@sxh62/dynamo 0.3.0 → 0.3.1

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 CHANGED
@@ -131,6 +131,25 @@ Taxonomy: `RepositoryError` (base, carries `operation`) → `RepositoryValidatio
131
131
  (schema/parse), `NotFoundError` (a failed `ConditionalCheckFailedException`), and
132
132
  `PaginationLimitExceededError` / `BatchProcessingError`.
133
133
 
134
+ ## Converting an app — the checklist (every item is a gate)
135
+
136
+ Each per-app conversion is done only when **all** of these hold:
137
+
138
+ - [ ] **Dep + table** — add `@sxh62/dynamo` (+ `dynamodb-toolbox`) and build `MainTable` with `defineTable`.
139
+ - [ ] **Entities** — declare every entity with `FAMILY_ENTITY_OPTIONS` (no `_et`, no timestamps), fields flattened beside `pk`/`sk`.
140
+ - [ ] **Repositories** — read/write/query through a toolbox `EntityRepository`; keep the raw `DocumentClient` only for streams/sweeps.
141
+ - [ ] **Delete the local `BaseRepository`** — and its tests; nothing extends it.
142
+ - [ ] **Conformance profile** — mount the shared `conformanceCases(profile)` suite for this app's table/entities.
143
+ - [ ] **Migrate + verify every environment (BLOCKING GATE)** — see the section below. The conversion is **not done** until any shape change is migrated **in dev, production, and every sample/other stage**, every environment is checked, and the environments checked **plus the result are recorded on the task**.
144
+ - [ ] **Gate green** — type-check, lint, tests, coverage at the project threshold (and a smoke run for apps with a build pipeline).
145
+
146
+ > The migration step is a **gate on the conversion task, not a follow-up backlog item.** A strict
147
+ > entity read fails on an un-migrated row, so deferring it leaves the app broken in whichever
148
+ > environment nobody checked — during the `@sxh62/dynamo` rollout that is exactly what happened
149
+ > (dnd-app's dev stage carried 30 un-migrated `{ data }` blob rows until a manual pass). When the
150
+ > per-app conversion task is written, make "migrate/verify every environment + record the result"
151
+ > an explicit acceptance criterion.
152
+
134
153
  ## Changing an entity's stored shape? Migrate — in every environment.
135
154
 
136
155
  When a shape changes (e.g. the old `{ pk, sk, data: {...} }` blob → flattened), write a
@@ -138,7 +157,7 @@ When a shape changes (e.g. the old `{ pk, sk, data: {...} }` blob → flattened)
138
157
  the target shape. See rpg_combat_tool's `scripts/migrate-flatten.ts` (+ `migrate.sh`): scan for a
139
158
  marker attribute, rewrite, do nothing if there's nothing to do.
140
159
 
141
- **This is a standard step of every conversion — not optional, and not just one environment.**
160
+ **This is a gate in the conversion checklist above — not optional, and not just one environment.**
142
161
  Before (or with) deploying the new code, check the stored items in **every environment** (dev,
143
162
  production, and any sample/other stages) and migrate each one that needs it: a strict entity read
144
163
  fails on an un-migrated row. A shape-preserving conversion (flat → flat, as in ronke) has nothing
@@ -1,27 +1,16 @@
1
1
  import type { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
2
2
  import { Table } from "dynamodb-toolbox";
3
3
  import type { GlobalIndex } from "dynamodb-toolbox";
4
- export interface DefineTableOptions {
4
+ export interface DefineTableOptions<TIndexes extends Record<string, GlobalIndex> | undefined = undefined> {
5
5
  /** Table name (or a resolver, e.g. an SST `Resource` lookup). */
6
6
  name: string | (() => string);
7
7
  /** Injected document client; omit to attach it later. */
8
8
  documentClient?: DynamoDBDocumentClient;
9
9
  /** Additional global secondary indexes beyond the standard GSI1 (e.g. GSI2). */
10
- indexes?: Record<string, GlobalIndex>;
10
+ indexes?: TIndexes;
11
11
  }
12
- /**
13
- * Create a dynamodb-toolbox `Table` using the family's single-table conventions:
14
- * primary key `pk`/`sk` (both string) and a `GSI1` global index over
15
- * `gsi1pk`/`gsi1sk`. Extra indexes can be supplied but the convention is stable.
16
- */
17
- export declare function defineTable(options: DefineTableOptions): Table<{
18
- name: "pk";
19
- type: "string";
20
- }, {
21
- name: "sk";
22
- type: "string";
23
- }, {
24
- GSI1: {
12
+ declare const STANDARD_INDEXES: {
13
+ readonly GSI1: {
25
14
  readonly type: "global";
26
15
  readonly partitionKey: {
27
16
  readonly name: "gsi1pk";
@@ -32,7 +21,29 @@ export declare function defineTable(options: DefineTableOptions): Table<{
32
21
  readonly type: "string";
33
22
  };
34
23
  };
35
- }, "_et">;
24
+ };
25
+ /**
26
+ * The table's index map as consumers see it: the family's standard GSI1 plus
27
+ * whatever the caller declared. The declaration has to survive into the type,
28
+ * not just the runtime object — dynamodb-toolbox derives the index names its
29
+ * `query` accepts from the table's index map, so an index that is merged at
30
+ * runtime but absent from the type cannot be queried at all.
31
+ */
32
+ type TableIndexes<TIndexes extends Record<string, GlobalIndex> | undefined> = {
33
+ GSI1: (typeof STANDARD_INDEXES)["GSI1"];
34
+ } & (TIndexes extends Record<string, GlobalIndex> ? TIndexes : unknown);
35
+ /**
36
+ * Create a dynamodb-toolbox `Table` using the family's single-table conventions:
37
+ * primary key `pk`/`sk` (both string) and a `GSI1` global index over
38
+ * `gsi1pk`/`gsi1sk`. Extra indexes can be supplied but the convention is stable.
39
+ */
40
+ export declare function defineTable<const TIndexes extends Record<string, GlobalIndex> | undefined = undefined>(options: DefineTableOptions<TIndexes>): Table<{
41
+ name: "pk";
42
+ type: "string";
43
+ }, {
44
+ name: "sk";
45
+ type: "string";
46
+ }, TableIndexes<TIndexes>, "_et">;
36
47
  /**
37
48
  * Family entity conventions. Items are discriminated by their `pk`/`sk` prefixes,
38
49
  * not by a stored `_et` entity attribute, so entities disable it. Spread this into
@@ -46,4 +57,5 @@ export declare const FAMILY_ENTITY_OPTIONS: {
46
57
  readonly entityAttribute: false;
47
58
  readonly timestamps: false;
48
59
  };
60
+ export {};
49
61
  //# sourceMappingURL=conventions.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"conventions.d.ts","sourceRoot":"","sources":["../src/conventions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IAC9B,yDAAyD;IACzD,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;CACvC;AAUD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB;;;;;;;;;;;;;;;;;;UAQtD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;CAAyD,CAAC"}
1
+ {"version":3,"file":"conventions.d.ts","sourceRoot":"","sources":["../src/conventions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,kBAAkB,CACjC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,SAAS,GAAG,SAAS;IAEpE,iEAAiE;IACjE,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IAC9B,yDAAyD;IACzD,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,gFAAgF;IAChF,OAAO,CAAC,EAAE,QAAQ,CAAC;CACpB;AAED,QAAA,MAAM,gBAAgB;;;;;;;;;;;;CAMZ,CAAC;AAEX;;;;;;GAMG;AACH,KAAK,YAAY,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,SAAS,IAAI;IAC5E,IAAI,EAAE,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;CACzC,GAAG,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,QAAQ,GAAG,OAAO,CAAC,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,SAAS,GAAG,SAAS,EAC1E,OAAO,EAAE,kBAAkB,CAAC,QAAQ,CAAC;;;;;;kCAQtC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB;;;CAAyD,CAAC"}
@@ -1 +1 @@
1
- {"version":3,"file":"conventions.js","sourceRoot":"","sources":["../src/conventions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAYzC,MAAM,gBAAgB,GAAG;IACvB,IAAI,EAAE;QACJ,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;QAChD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC5C;CACO,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,OAAO,IAAI,KAAK,CAAC;QACf,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3F,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,YAAY,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC5C,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;QACvC,OAAO,EAAE,EAAE,GAAG,gBAAgB,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE;KACrD,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAW,CAAC"}
1
+ {"version":3,"file":"conventions.js","sourceRoot":"","sources":["../src/conventions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAczC,MAAM,gBAAgB,GAAG;IACvB,IAAI,EAAE;QACJ,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;QAChD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC5C;CACO,CAAC;AAaX;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAEzB,OAAqC;IACrC,OAAO,IAAI,KAAK,CAAC;QACf,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3F,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,YAAY,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC5C,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE;QACvC,OAAO,EAAE,EAAE,GAAG,gBAAgB,EAAE,GAAG,OAAO,CAAC,OAAO,EAA4B;KAC/E,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAW,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sxh62/dynamo",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
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",