@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 +20 -1
- package/dist/conventions.d.ts +28 -16
- package/dist/conventions.d.ts.map +1 -1
- package/dist/conventions.js.map +1 -1
- package/package.json +1 -1
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
|
|
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
|
package/dist/conventions.d.ts
CHANGED
|
@@ -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?:
|
|
10
|
+
indexes?: TIndexes;
|
|
11
11
|
}
|
|
12
|
-
|
|
13
|
-
|
|
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
|
-
}
|
|
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;
|
|
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"}
|
package/dist/conventions.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../src/conventions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,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"}
|