@sxh62/dynamo 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,187 @@
1
+ # @sxh62/dynamo — family conventions over dynamodb-toolbox
2
+
3
+ Shared single-table conventions and small extensions for the sxh DynamoDB apps, layered on
4
+ [`dynamodb-toolbox`](https://github.com/dynamodb-toolbox/dynamodb-toolbox).
5
+
6
+ This package is **not a facade over toolbox**. Use toolbox directly (`Table`, `Entity`,
7
+ `EntityRepository`, schema builders) and reach for `@sxh62/dynamo` for the handful of
8
+ conventions and extensions below — so every app is wired the same way.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ npm install @sxh62/dynamo dynamodb-toolbox
14
+ ```
15
+
16
+ Peers: `@aws-sdk/client-dynamodb`, `@aws-sdk/lib-dynamodb`, `@aws-sdk/util-dynamodb`, `zod`.
17
+
18
+ ## The conventions
19
+
20
+ ### 1. One table per app — `defineTable`
21
+
22
+ Every app has a single `MainTable`: primary key `pk`/`sk` (both string) plus a `GSI1` global
23
+ index over `gsi1pk`/`gsi1sk`. Build it with `defineTable` so the layout is identical everywhere.
24
+
25
+ ```ts
26
+ import { defineTable } from "@sxh62/dynamo";
27
+ import { Resource } from "sst";
28
+
29
+ export const mainTable = defineTable({
30
+ // Deferred so the SST resource binding resolves at runtime, not at module load.
31
+ name: () => Resource.MainTable.name,
32
+ documentClient: getDocClient(),
33
+ });
34
+ ```
35
+
36
+ `defineTable` returns the toolbox `Table` (with its narrowed key types preserved). Extra global
37
+ indexes (e.g. `GSI2`) can be supplied via `indexes`.
38
+
39
+ ### 2. Entities: no `_et`, no timestamps — `FAMILY_ENTITY_OPTIONS`
40
+
41
+ Items are discriminated by their `pk`/`sk` **prefixes**. The family stores **no** `_et` entity
42
+ attribute and **no** `_ct`/`_md` timestamps, so every entity must disable both. Spread the
43
+ shared constant:
44
+
45
+ ```ts
46
+ import { Entity, item, string } from "dynamodb-toolbox";
47
+ import { FAMILY_ENTITY_OPTIONS } from "@sxh62/dynamo";
48
+
49
+ export const EncounterEntity = new Entity({
50
+ name: "Encounter",
51
+ table: mainTable,
52
+ schema: item({
53
+ pk: string().key(),
54
+ sk: string().key(),
55
+ encounterId: string(),
56
+ name: string(),
57
+ combatants: list(
58
+ map({ combatantId: string(), name: string(), kind: string(), system: string(), data: any() }),
59
+ ),
60
+ }),
61
+ ...FAMILY_ENTITY_OPTIONS, // { entityAttribute: false, timestamps: false }
62
+ });
63
+ ```
64
+
65
+ > **Why a constant, not a `defineEntity()` helper?** Wrapping `new Entity(...)` collapses
66
+ > toolbox's generic type inference (it demands `computeKey` and widens attribute types). An
67
+ > options constant keeps full inference while still enforcing the convention.
68
+
69
+ ### 3. Store entity fields flattened
70
+
71
+ Entity fields live **beside** `pk`/`sk` at the top level — not under a `data` blob:
72
+
73
+ ```
74
+ { pk: "USER#1", sk: "ENCOUNTER#enc-1", encounterId: "enc-1", name: "Goblin Ambush", ... }
75
+ ```
76
+
77
+ Nested objects use `map(...)`; arrays of objects use `list(map(...))` — **not** `item(...)`
78
+ (using `item` there silently stores `null` elements). Top-level `item(...)` is for the entity
79
+ schema itself.
80
+
81
+ ### 4. Query with `{ partition, range }`
82
+
83
+ toolbox's query input is a partition value plus an optional range — not `pk`/`sk`:
84
+
85
+ ```ts
86
+ entity.query({ partition: keys.user(ownerId), range: { beginsWith: "ENCOUNTER#" } });
87
+ ```
88
+
89
+ ### 5. Toolbox for entity CRUD; raw DocumentClient for stream/maintenance
90
+
91
+ - **Entity read/write/query** → toolbox `EntityRepository` (`entity.build(EntityRepository)`).
92
+ - **Append-only streams or partition-wide maintenance** (audit logs, "delete everything for a
93
+ user") → the raw `DocumentClient` (Query + chunked `BatchWrite`). These are deliberately
94
+ **not** entity-bound: they must tolerate rows of any shape, and `deletePartition` would throw
95
+ on an item that matches no registered entity.
96
+
97
+ ### 6. Auto-pagination must throw at the cap — `paginate`
98
+
99
+ toolbox's `maxPages` **silently stops** at the cap, returning a truncated result with a dangling
100
+ `LastEvaluatedKey`. Wrap the query so an overflow fails loudly instead:
101
+
102
+ ```ts
103
+ import { paginate } from "@sxh62/dynamo";
104
+
105
+ const { Items } = await paginate(
106
+ (maxPages) => encounters.query({ partition, range }, { maxPages }),
107
+ { maxPages: 50, operation: "encounters.list" },
108
+ );
109
+ ```
110
+
111
+ `paginate` throws `PaginationLimitExceededError` when pages remain. Use `maxPages: Infinity` to
112
+ paginate to completion.
113
+
114
+ ### 7. Typed errors — `mapToolboxError`
115
+
116
+ Translate toolbox / DynamoDB errors onto the family taxonomy at the repository boundary:
117
+
118
+ ```ts
119
+ import { mapToolboxError } from "@sxh62/dynamo";
120
+
121
+ async save(encounter: Encounter): Promise<void> {
122
+ try {
123
+ await encounters.put({ ... });
124
+ } catch (error) {
125
+ throw mapToolboxError(error, "encounters.save");
126
+ }
127
+ }
128
+ ```
129
+
130
+ Taxonomy: `RepositoryError` (base, carries `operation`) → `RepositoryValidationError`
131
+ (schema/parse), `NotFoundError` (a failed `ConditionalCheckFailedException`), and
132
+ `PaginationLimitExceededError` / `BatchProcessingError`.
133
+
134
+ ## Changing an entity's stored shape? Migrate — in every environment.
135
+
136
+ When a shape changes (e.g. the old `{ pk, sk, data: {...} }` blob → flattened), write a
137
+ **one-time, idempotent** migration that rewrites the affected rows and skips anything already in
138
+ the target shape. See rpg_combat_tool's `scripts/migrate-flatten.ts` (+ `migrate.sh`): scan for a
139
+ marker attribute, rewrite, do nothing if there's nothing to do.
140
+
141
+ **This is a standard step of every conversion — not optional, and not just one environment.**
142
+ Before (or with) deploying the new code, check the stored items in **every environment** (dev,
143
+ production, and any sample/other stages) and migrate each one that needs it: a strict entity read
144
+ fails on an un-migrated row. A shape-preserving conversion (flat → flat, as in ronke) has nothing
145
+ to migrate — but you still check every environment to confirm that.
146
+
147
+ ## Prove it: the per-app conformance suite
148
+
149
+ Each app should run the shared suite against a small **profile** — its table and entities — so
150
+ every app proves it follows these conventions the same way, instead of hand-writing its own
151
+ check. `conformanceCases(profile)` returns named cases whose `check()` throws with an actionable
152
+ message when a convention is violated; it is framework-agnostic, so run it from any test runner:
153
+
154
+ ```ts
155
+ import { conformanceCases } from "@sxh62/dynamo";
156
+ import { it } from "vitest";
157
+
158
+ import { mainTable } from "./table";
159
+ import { ALL_ENTITIES } from "./entities";
160
+
161
+ for (const c of conformanceCases({
162
+ table: mainTable,
163
+ entities: ALL_ENTITIES,
164
+ extraIndexes: ["GSI2"],
165
+ })) {
166
+ it(c.name, c.check);
167
+ }
168
+ ```
169
+
170
+ The profile:
171
+
172
+ ```ts
173
+ interface ConformanceProfile {
174
+ table: Table; // built with defineTable
175
+ entities: Entity[]; // built with FAMILY_ENTITY_OPTIONS
176
+ extraIndexes?: string[]; // any global indexes beyond GSI1 (e.g. ["GSI2"])
177
+ }
178
+ ```
179
+
180
+ It asserts: the primary key is `pk`/`sk` (both string); `GSI1` is a global index over
181
+ `gsi1pk`/`gsi1sk`; every declared extra index exists; every entity is bound to the table; and
182
+ every entity disables both the `_et` attribute and timestamps (i.e. spreads
183
+ `FAMILY_ENTITY_OPTIONS`).
184
+
185
+ ## The "raw vs toolbox" rule, in one line
186
+
187
+ **toolbox for entities; the DocumentClient for streams and sweeps.**
@@ -0,0 +1,26 @@
1
+ import type { Entity, Table } from "dynamodb-toolbox";
2
+ /** The facts an app declares so the family-conformance suite can check it. */
3
+ export interface ConformanceProfile {
4
+ /** The app's single family table (built with `defineTable`). */
5
+ table: Table;
6
+ /** The app's entities (each built with `FAMILY_ENTITY_OPTIONS`). */
7
+ entities: Entity[];
8
+ /** Names of extra global indexes beyond the mandatory `GSI1` (e.g. `["GSI2"]`). */
9
+ extraIndexes?: string[];
10
+ }
11
+ /** A single named conformance check. `check` throws when the convention is violated. */
12
+ export interface ConformanceCase {
13
+ name: string;
14
+ check: () => void;
15
+ }
16
+ /**
17
+ * Build the family-conformance cases for an app profile. Each case's `check`
18
+ * throws with an actionable message when the app drifts from the `@sxh62/dynamo`
19
+ * conventions, so any test framework can run it:
20
+ *
21
+ * ```ts
22
+ * for (const c of conformanceCases({ table, entities })) it(c.name, c.check);
23
+ * ```
24
+ */
25
+ export declare function conformanceCases(profile: ConformanceProfile): ConformanceCase[];
26
+ //# sourceMappingURL=conformance.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEtD,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,KAAK,EAAE,KAAK,CAAC;IACb,oEAAoE;IACpE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AA0BD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,eAAe,EAAE,CAmE/E"}
@@ -0,0 +1,74 @@
1
+ function assert(condition, message) {
2
+ if (!condition) {
3
+ throw new Error(`Conformance failure: ${message}`);
4
+ }
5
+ }
6
+ function isStringKey(key, name) {
7
+ return key?.name === name && key.type === "string";
8
+ }
9
+ function isFamilyGsi1(index) {
10
+ return isStringKey(index?.partitionKey, "gsi1pk") && isStringKey(index?.sortKey, "gsi1sk");
11
+ }
12
+ /**
13
+ * Build the family-conformance cases for an app profile. Each case's `check`
14
+ * throws with an actionable message when the app drifts from the `@sxh62/dynamo`
15
+ * conventions, so any test framework can run it:
16
+ *
17
+ * ```ts
18
+ * for (const c of conformanceCases({ table, entities })) it(c.name, c.check);
19
+ * ```
20
+ */
21
+ export function conformanceCases(profile) {
22
+ const { table, entities } = profile;
23
+ const extraIndexes = profile.extraIndexes ?? [];
24
+ const indexes = table.indexes;
25
+ const cases = [
26
+ {
27
+ name: "declares at least one entity",
28
+ check: () => {
29
+ assert(entities.length > 0, "a profile must declare at least one entity");
30
+ },
31
+ },
32
+ {
33
+ name: "uses the family primary key pk/sk (both string)",
34
+ check: () => {
35
+ assert(isStringKey(table.partitionKey, "pk"), "partition key must be `pk` (string)");
36
+ assert(isStringKey(table.sortKey, "sk"), "sort key must be `sk` (string)");
37
+ },
38
+ },
39
+ {
40
+ name: "declares the family GSI1 (gsi1pk/gsi1sk)",
41
+ check: () => {
42
+ assert(isFamilyGsi1(indexes.GSI1), "GSI1 must be a global index over gsi1pk/gsi1sk");
43
+ },
44
+ },
45
+ {
46
+ name: "binds every entity to the family table",
47
+ check: () => {
48
+ assert(entities.every((entity) => entity.table === table), "every entity must be built on the profile table");
49
+ },
50
+ },
51
+ {
52
+ name: "disables the stored _et entity attribute on every entity",
53
+ check: () => {
54
+ assert(entities.every((entity) => entity.entityAttribute === false), "spread FAMILY_ENTITY_OPTIONS so no `_et` attribute is stored");
55
+ },
56
+ },
57
+ {
58
+ name: "disables timestamps on every entity",
59
+ check: () => {
60
+ assert(entities.every((entity) => entity.timestamps === false), "spread FAMILY_ENTITY_OPTIONS so no `_ct`/`_md` timestamps are stored");
61
+ },
62
+ },
63
+ ];
64
+ if (extraIndexes.length > 0) {
65
+ cases.push({
66
+ name: "declares the app's extra global indexes",
67
+ check: () => {
68
+ assert(extraIndexes.every((name) => indexes[name] !== undefined), `missing extra index(es): ${extraIndexes.join(", ")}`);
69
+ },
70
+ });
71
+ }
72
+ return cases;
73
+ }
74
+ //# sourceMappingURL=conformance.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"conformance.js","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AA4BA,SAAS,MAAM,CAAC,SAAkB,EAAE,OAAe;IACjD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,wBAAwB,OAAO,EAAE,CAAC,CAAC;IACrD,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,GAA0B,EAAE,IAAY;IAC3D,OAAO,GAAG,EAAE,IAAI,KAAK,IAAI,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC;AACrD,CAAC;AAED,SAAS,YAAY,CAAC,KAA8B;IAClD,OAAO,WAAW,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,CAAC,IAAI,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AAC7F,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA2B;IAC1D,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IACpC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IAChD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAkD,CAAC;IAEzE,MAAM,KAAK,GAAsB;QAC/B;YACE,IAAI,EAAE,8BAA8B;YACpC,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,4CAA4C,CAAC,CAAC;YAC5E,CAAC;SACF;QACD;YACE,IAAI,EAAE,iDAAiD;YACvD,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,CAAC,EAAE,qCAAqC,CAAC,CAAC;gBACrF,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,gCAAgC,CAAC,CAAC;YAC7E,CAAC;SACF;QACD;YACE,IAAI,EAAE,0CAA0C;YAChD,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,gDAAgD,CAAC,CAAC;YACvF,CAAC;SACF;QACD;YACE,IAAI,EAAE,wCAAwC;YAC9C,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,CACJ,QAAQ,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,KAAK,KAAK,CAAC,EAClD,iDAAiD,CAClD,CAAC;YACJ,CAAC;SACF;QACD;YACE,IAAI,EAAE,0DAA0D;YAChE,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,CACJ,QAAQ,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,eAAe,KAAK,KAAK,CAAC,EAC5D,8DAA8D,CAC/D,CAAC;YACJ,CAAC;SACF;QACD;YACE,IAAI,EAAE,qCAAqC;YAC3C,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,CACJ,QAAQ,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,KAAK,KAAK,CAAC,EACvD,sEAAsE,CACvE,CAAC;YACJ,CAAC;SACF;KACF,CAAC;IAEF,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,yCAAyC;YAC/C,KAAK,EAAE,GAAG,EAAE;gBACV,MAAM,CACJ,YAAY,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,EACzD,4BAA4B,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACtD,CAAC;YACJ,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ export * from "./conformance.js";
1
2
  export * from "./conventions.js";
2
3
  export * from "./errors.js";
3
4
  export * from "./pagination.js";
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}
package/dist/index.js CHANGED
@@ -1,3 +1,4 @@
1
+ export * from "./conformance.js";
1
2
  export * from "./conventions.js";
2
3
  export * from "./errors.js";
3
4
  export * from "./pagination.js";
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sxh62/dynamo",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Family conventions and shared extensions over dynamodb-toolbox for the sxh DynamoDB apps.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",