chore: updates and tidy ups (#79)

This PR updates the README and includes a few other tidy-ups and
upgrades

---------

Co-authored-by: Benjamin Williams <[email protected]>
Co-authored-by: Dafydd Llŷr Pearson <[email protected]>

.eslintrc

@@ -7,6 +7,7 @@
     "plugin:@typescript-eslint/recommended"
   ],
   "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
     "@typescript-eslint/ban-ts-comment": "off",
     "@typescript-eslint/no-unused-vars": [
       "warn",

README.md

@@ -1,31 +1,70 @@
 # PlanX Core
 
-This package is a declarative boundary between the data access layer (GraphQL/Hasura/Postgres) and the PlanX domain.
+This package is a declarative wrapper for the core data structures and operations of [PlanX](https://github.com/theopensystemslab/planx-new).
 
-## Running locally
+It also includes data processing functions for the various export formats of PlanX application data.
+
+## Structure
+
+The package is structured by functional responsibility. Here is a summary of what each directory contains:
+
+    ./src
+    ├── requests  # a data access client exposing declarative interfaces for common database operations
+    ├── models    # a set of functions and classes that encapsulate the functionality of domain objects
+    ├── exports   # data processing functions to convert application data into third-party data formats
+    ├── templates # data processing functions to convert application data into various document formats
+    └── types     # a set of Typescript types for the exported functions and structures of this package
+
+## Conventions
+
+Requests:
+
+- `CoreDomainClient` sets up individual resource clients which each expose a declarative interface for operations on that resource.
+- Functions or methods that begin with an underscore (e.g `$admin.session._destroy`) are intended as development/test utilities and do not represent actions that should be a part of application code.
+- Instances of `CoreDomainClient` should be named `$<ROLE>` to indicate the permission set it has been granted, e.g. `$api` or `$public`
+
+Models:
+
+- Rich data structures which have implicit rules around how data should be read or manipulated are best represented as classes which encapsulate behaviours in methods.
+- Simple data structures which have few or no rules around how data should be read or manipulated are best represented as simple objects/arrays with a clear type definition.
+
+Exports / Templates:
+
+- Prefer stream processing where possible.
+
+Types:
+
+- Following the [robustness principle](https://en.wikipedia.org/wiki/Robustness_principle), types should generally be represented as an `interface` for inputs and as a `type` for outputs with a known structure.
+
+## Local Development
 
 - Install [pnpm](https://pnpm.io) globally if you don't have it already `npm i pnpm -g`
 - Install dependencies `pnpm i`
 
 Other useful package scripts:
 
-  * `pnpm test`: run the test suite
-  * `pnpm check`: check and fix type and linting errors
-  * `pnpm build`: build the package
+- `pnpm build`: generate package exports and examples
+
+- `pnpm check`: scan for type and style errors
+- `pnpm lint`: scan for style errors
+- `pnpm lint:fix`: fix style errors
+
+- `pnpm test`: run unit tests
+- `pnpm test:coverage`: run unit tests with coverage report
 
-## Debugging
+### Debugging
 
 Setting the environment variable `DEBUG` to any truthy value turns on the console output for debugging (useful for setup and teardown issues).
 
 ## Publishing
 
-This node package is published via Github and can be referenced in a `package.json`, like so:
+This node package is published via Github and can be referenced in a `pnpm` style `package.json` file, like so:
 
     "dependencies": {
-      "@opensystemslab/planx-core": "git://github.com/theopensystemslab/planx-core.git#commit-ish",
+      "@opensystemslab/planx-core": "github:theopensystemslab/planx-core#commit-ish",
       ...
     }
 
 ## License
 
-This repository is licensed under the [Open Government License v3](http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
+This repository is licensed under the [The Mozilla Public License (MPL) Version 2](https://github.com/theopensystemslab/planx-core/blob/main/LICENSE).

jest.config.ts

@@ -9,7 +9,8 @@ export default {
       },
     ],
   },
-  testPathIgnorePatterns: ["dist/*"],
+  testPathIgnorePatterns: ["dist/*", "tests/*"],
+  setupFilesAfterEnv: ["./jest.setup.js"],
   collectCoverage: true,
   coverageReporters: ["html", "lcov", "text-summary"],
   coverageDirectory: "./coverage",

jest.setup.js

@@ -0,0 +1,2 @@
+process.env.HASURA_GRAPHQL_ADMIN_SECRET = "👻";
+process.env.HASURA_GRAPHQL_URL = "👻";

package.json

@@ -13,7 +13,6 @@
   ],
   "module": "./dist/index.js",
   "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "lint-staged": {
     "src/**/*.{js,ts}": "eslint --fix",
     "src/**/*": "prettier -w"
@@ -30,6 +29,7 @@
       "require": "./types/index.js"
     }
   },
+  "types": "./dist/index.d.ts",
   "scripts": {
     "build": "rimraf ./types ./dist && tsc --project ./tsconfig.types.json && tsc && pnpm copy-json-schema",
     "examples": "rimraf ./examples && ts-node ./src/templates/generateExamples.ts",
@@ -91,13 +91,14 @@
     "@types/lodash.set": "^4.3.7",
     "@types/lodash.startcase": "^4.4.7",
     "@types/node": "^18.16.19",
-    "@types/react": "^18.2.15",
     "@types/react-dom": "^18.2.13",
     "@types/uuid": "^9.0.5",
-    "@typescript-eslint/eslint-plugin": "^5.62.0",
-    "@typescript-eslint/parser": "^5.62.0",
     "esbuild": "^0.19.4",
+    "@types/react": "^18.2.17",
+    "@typescript-eslint/eslint-plugin": "^6.2.0",
+    "@typescript-eslint/parser": "^6.2.0",
     "esbuild-jest": "^0.5.0",
+    "eslint": "^8.46.0",
     "eslint-plugin-simple-import-sort": "^10.0.0",
     "husky": "^8.0.3",
     "jest": "^29.7.0",