Merge branch 'main' into fix-cleanup-1

.github/workflows/pr-check.yml

@@ -13,22 +13,27 @@ jobs:
       PORT: 8000
     strategy:
       matrix:
-        node-version: [20.x]
+        node-version: [20.x, 19.x, 18.x]
     steps:
       - uses: actions/checkout@v4
       - name: Setup DynamoDB local
         run: docker run -d -p 8000:8000 amazon/dynamodb-local:latest
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
       - name: Install packages
-        run: npm install
+        run: pnpm install
       - name: Run build command
-        run: npm run build --if-present
+        run: pnpm build
       - name: Run ESLint
-        run: npm run lint --if-present
+        run: pnpm lint
       - name: Run test suite
-        run: npm run test run
+        run: pnpm test run
       - name: Run 100% coverage check
-        run: npm run coverage
+        run: pnpm coverage

README.md

@@ -30,8 +30,130 @@ const accountSchema = z.object({
   id: z.string().uuid(),
   email: z.string(),
   status: z.enum(["verified", "unverified"]),
-  address: z.array(z.string()),
 });
 ```
 
-You can add it to your
+You've also started defining your `dynamodb-onetable` Table schema:
+
+```ts
+import { OneSchema, OneTableError } from "dynamodb-onetable";
+
+const SCHEMA = {
+  format: "onetable:1.1.0",
+  version: "0.0.1",
+  indexes: { primary: { hash: "pk", sort: "sk" } },
+  params: { isoDates: false, timestamps: true, null: true },
+  // 👈 We need models here
+} satisfies OneSchema;
+```
+
+Adding a `Account` model is easy. First, create a `zod` schema and then pass it into `createModelSchema`.
+
+```ts
+import { createModelSchema } from "zod-to-dynamodb-onetable-schema";
+
+const accountRecordSchema = accountSchema.extend({
+  pk: z.literal("${_type}#${id}"),
+  sk: z.literal("${_type}#"),
+});
+
+const SCHEMA = {
+  // other fields collapsed
+  models: { Account: createModelSchema(accountRecordSchema, {}) },
+} satisfies OneSchema;
+```
+
+Your schema is complete, now let's use the model:
+
+```ts
+import { Table } from "dynamodb-onetable";
+
+const table = new Table({
+  // other fields collapsed,
+  schema: SCHEMA,
+});
+
+const accountModel = table.getModel("Account");
+
+const newAccount: z.infer<typeof accountSchema> = {
+  id: uuidv4(),
+  email: "[email protected]",
+  status: "unverified",
+};
+
+await accountModel.create(newAccount);
+const storedAccount = await accountModel.get(newAccount);
+expect(newAccount).toEqual(storedAccount);
+```
+
+Notice we didn't need to specify the `pk` or `pk`? That's because `Table` handles it for us when we use `z.literal()` with OneTable's [value template syntax](https://doc.onetable.io/api/table/schemas/attributes/#value-templates). The typing is smart enough to identify that these values can be automatically extracted from your entity data and aren't needed.
+
+<details>
+<summary><b>Expand for an example that explicitly sets the indexes</b></summary>
+
+```ts
+import { Table, OneSchema, OneTableError } from "dynamodb-onetable";
+import { createModelSchema } from "zod-to-dynamodb-onetable-schema";
+import { z } from "zod";
+
+const accountRecordSchema = z.object({
+  pk: z.string(),
+  sk: z.string(),
+  id: z.string().uuid(),
+  email: z.string(),
+  status: z.enum(["verified", "unverified"]),
+});
+
+const SCHEMA = {
+  // other fields collapsed
+  models: { Account: createModelSchema(accountRecordSchema, {}) },
+} satisfies OneSchema;
+
+const accountModel = table.getModel("Account");
+
+const newAccount: z.infer<typeof accountRecordSchema> = {
+  pk: "Account#1",
+  sk: "Account",
+  id: 1,
+  email: "[email protected]",
+  status: "unverified",
+};
+
+await accountModel.create(newAccount);
+const storedAccount = await accountModel.get(newAccount);
+expect(newAccount).toMatchObject(storedAccount);
+```
+
+</details>
+
+## Contributing
+
+I appreciate any contributions, issues or discussions. My aim is to make contributing quick and easy.
+
+Please note that PR quality checks enforce a 100% code coverage rate and will test your code against a local version of DynamoDB. Passing these requirements are essential to getting a merge/release. For new code, at least some tests should interface with an instance of `Table` that interacts with a local DynamoDB instance. An example of this test type is at `tests/createModelSchema.spec.ts`.
+
+Here's a quick start to getting this repo running on your own machine (assumes you already have `gh`, `node` and `docker` installed):
+
+1. Clone the repo to your own machine
+
+```sh
+gh repo clone jharlow/zod-to-dynamodb-onetable-schema
+```
+
+2. Start an instance of `dynamodb-local` on your machine
+
+```sh
+docker run -d -p 8000:8000 amazon/dynamodb-local
+```
+
+3. Install dependencies
+
+```sh
+npm install
+```
+
+4. You can now execute the test suite and develop 🙌
+
+```sh
+npm test
+```

package.json

@@ -1,11 +1,28 @@
 {
   "name": "zod-to-dynamodb-onetable-schema",
   "version": "0.0.0",
-  "description": "Build your `dynamodb-onetable` schema using your existing `zod` schemas",
+  "description": "Auto-generate `dynamodb-onetable` model schemas using `zod`, with best-in-class autocomplete",
+  "keywords": [
+    "dynamo",
+    "dynamodb",
+    "dynamodb-onetable",
+    "zod"
+  ],
+  "author": "John Harlow <[email protected]>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jharlow/zod-to-dynamodb-onetable-schema.git"
+  },
+  "bugs": {
+    "url": "httckaps://github.com/jharlow/zod-to-dynamodb-onetable-schema/issues"
+  },
+  "homepage": "https://github.com/jharlow/zod-to-dynamodb-onetable-schema",
   "main": "index.ts",
   "files": [
     "dist/**/*"
   ],
+  "type": "module",
   "exports": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
@@ -16,10 +33,8 @@
     "test": "vitest",
     "coverage": "vitest run --coverage"
   },
-  "author": "John Harlow",
-  "license": "MIT",
   "devDependencies": {
-    "@aws-sdk/client-dynamodb": "^3.666.0",
+    "@aws-sdk/client-dynamodb": "^3.668.0",
     "@eslint/js": "^9.12.0",
     "@types/aws-lambda": "^8.10.145",
     "@types/eslint__js": "^8.42.3",