@sxh62/dynamo 0.1.1 → 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.
Files changed (50) hide show
  1. package/README.md +187 -0
  2. package/dist/conformance.d.ts +26 -0
  3. package/dist/conformance.d.ts.map +1 -0
  4. package/dist/conformance.js +74 -0
  5. package/dist/conformance.js.map +1 -0
  6. package/dist/conventions.d.ts +49 -0
  7. package/dist/conventions.d.ts.map +1 -0
  8. package/dist/conventions.js +33 -0
  9. package/dist/conventions.js.map +1 -0
  10. package/dist/errors.d.ts +13 -2
  11. package/dist/errors.d.ts.map +1 -1
  12. package/dist/errors.js +34 -4
  13. package/dist/errors.js.map +1 -1
  14. package/dist/index.d.ts +3 -6
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +3 -6
  17. package/dist/index.js.map +1 -1
  18. package/dist/pagination.d.ts +16 -0
  19. package/dist/pagination.d.ts.map +1 -0
  20. package/dist/pagination.js +23 -0
  21. package/dist/pagination.js.map +1 -0
  22. package/package.json +9 -4
  23. package/dist/base-repository.d.ts +0 -36
  24. package/dist/base-repository.d.ts.map +0 -1
  25. package/dist/base-repository.js +0 -141
  26. package/dist/base-repository.js.map +0 -1
  27. package/dist/batch-processor.d.ts +0 -27
  28. package/dist/batch-processor.d.ts.map +0 -1
  29. package/dist/batch-processor.js +0 -73
  30. package/dist/batch-processor.js.map +0 -1
  31. package/dist/client.d.ts +0 -15
  32. package/dist/client.d.ts.map +0 -1
  33. package/dist/client.js +0 -14
  34. package/dist/client.js.map +0 -1
  35. package/dist/config.d.ts +0 -30
  36. package/dist/config.d.ts.map +0 -1
  37. package/dist/config.js +0 -21
  38. package/dist/config.js.map +0 -1
  39. package/dist/query-engine.d.ts +0 -31
  40. package/dist/query-engine.d.ts.map +0 -1
  41. package/dist/query-engine.js +0 -122
  42. package/dist/query-engine.js.map +0 -1
  43. package/dist/update-builder.d.ts +0 -14
  44. package/dist/update-builder.d.ts.map +0 -1
  45. package/dist/update-builder.js +0 -27
  46. package/dist/update-builder.js.map +0 -1
  47. package/dist/validation.d.ts +0 -7
  48. package/dist/validation.d.ts.map +0 -1
  49. package/dist/validation.js +0 -37
  50. package/dist/validation.js.map +0 -1
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"}
@@ -0,0 +1,49 @@
1
+ import type { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
2
+ import { Table } from "dynamodb-toolbox";
3
+ import type { GlobalIndex } from "dynamodb-toolbox";
4
+ export interface DefineTableOptions {
5
+ /** Table name (or a resolver, e.g. an SST `Resource` lookup). */
6
+ name: string | (() => string);
7
+ /** Injected document client; omit to attach it later. */
8
+ documentClient?: DynamoDBDocumentClient;
9
+ /** Additional global secondary indexes beyond the standard GSI1 (e.g. GSI2). */
10
+ indexes?: Record<string, GlobalIndex>;
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: {
25
+ readonly type: "global";
26
+ readonly partitionKey: {
27
+ readonly name: "gsi1pk";
28
+ readonly type: "string";
29
+ };
30
+ readonly sortKey: {
31
+ readonly name: "gsi1sk";
32
+ readonly type: "string";
33
+ };
34
+ };
35
+ }, "_et">;
36
+ /**
37
+ * Family entity conventions. Items are discriminated by their `pk`/`sk` prefixes,
38
+ * not by a stored `_et` entity attribute, so entities disable it. Spread this into
39
+ * entity construction to keep dynamodb-toolbox's full type inference:
40
+ *
41
+ * ```ts
42
+ * new Entity({ name: "Encounter", table, schema, ...FAMILY_ENTITY_OPTIONS })
43
+ * ```
44
+ */
45
+ export declare const FAMILY_ENTITY_OPTIONS: {
46
+ readonly entityAttribute: false;
47
+ readonly timestamps: false;
48
+ };
49
+ //# sourceMappingURL=conventions.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,33 @@
1
+ import { Table } from "dynamodb-toolbox";
2
+ const STANDARD_INDEXES = {
3
+ GSI1: {
4
+ type: "global",
5
+ partitionKey: { name: "gsi1pk", type: "string" },
6
+ sortKey: { name: "gsi1sk", type: "string" },
7
+ },
8
+ };
9
+ /**
10
+ * Create a dynamodb-toolbox `Table` using the family's single-table conventions:
11
+ * primary key `pk`/`sk` (both string) and a `GSI1` global index over
12
+ * `gsi1pk`/`gsi1sk`. Extra indexes can be supplied but the convention is stable.
13
+ */
14
+ export function defineTable(options) {
15
+ return new Table({
16
+ ...(options.documentClient !== undefined ? { documentClient: options.documentClient } : {}),
17
+ name: options.name,
18
+ partitionKey: { name: "pk", type: "string" },
19
+ sortKey: { name: "sk", type: "string" },
20
+ indexes: { ...STANDARD_INDEXES, ...options.indexes },
21
+ });
22
+ }
23
+ /**
24
+ * Family entity conventions. Items are discriminated by their `pk`/`sk` prefixes,
25
+ * not by a stored `_et` entity attribute, so entities disable it. Spread this into
26
+ * entity construction to keep dynamodb-toolbox's full type inference:
27
+ *
28
+ * ```ts
29
+ * new Entity({ name: "Encounter", table, schema, ...FAMILY_ENTITY_OPTIONS })
30
+ * ```
31
+ */
32
+ export const FAMILY_ENTITY_OPTIONS = { entityAttribute: false, timestamps: false };
33
+ //# sourceMappingURL=conventions.js.map
@@ -0,0 +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"}
package/dist/errors.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
- * Typed error hierarchy for the persistence library (behaviour B-OPS-4).
3
- * Every failure is a `RepositoryError` subclass carrying the operation context.
2
+ * Typed error hierarchy for the family's repository layer, preserved from
3
+ * `@sxh62/dynamo` so consumers' HTTP layers keep working across the migration.
4
4
  */
5
5
  export interface RepositoryErrorOptions {
6
6
  cause?: unknown;
@@ -30,4 +30,15 @@ export declare class BatchProcessingError extends RepositoryError {
30
30
  readonly unprocessed: unknown[];
31
31
  constructor(operation: string, unprocessed: unknown[]);
32
32
  }
33
+ /**
34
+ * Map a raw dynamodb-toolbox / DynamoDB error onto the family taxonomy.
35
+ *
36
+ * - an existing `RepositoryError` passes through unchanged;
37
+ * - `ConditionalCheckFailedException` means a write condition was not met (item
38
+ * absent) → `NotFoundError`;
39
+ * - a `DynamoDBToolboxError` is a schema/parse/format/option problem →
40
+ * `RepositoryValidationError`;
41
+ * - anything else is wrapped as `RepositoryError`, preserving the cause.
42
+ */
43
+ export declare function mapToolboxError(error: unknown, operation: string): RepositoryError;
33
44
  //# sourceMappingURL=errors.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB;CAKjF;AAED,MAAM,WAAW,sBAAuB,SAAQ,sBAAsB;IACpE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,yBAA0B,SAAQ,eAAe;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B;CAMrF;AAED,qBAAa,aAAc,SAAQ,eAAe;CAAG;AAErD,qBAAa,4BAA6B,SAAQ,eAAe;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAIhD;AAED,qBAAa,oBAAqB,SAAQ,eAAe;IACvD,QAAQ,CAAC,WAAW,EAAE,OAAO,EAAE,CAAC;gBAEpB,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE;CAItD"}
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB;CAKjF;AAED,MAAM,WAAW,sBAAuB,SAAQ,sBAAsB;IACpE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,yBAA0B,SAAQ,eAAe;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B;CAMrF;AAED,qBAAa,aAAc,SAAQ,eAAe;CAAG;AAErD,qBAAa,4BAA6B,SAAQ,eAAe;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAIhD;AAED,qBAAa,oBAAqB,SAAQ,eAAe;IACvD,QAAQ,CAAC,WAAW,EAAE,OAAO,EAAE,CAAC;gBAEpB,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE;CAItD;AAYD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAclF"}
package/dist/errors.js CHANGED
@@ -1,7 +1,4 @@
1
- /**
2
- * Typed error hierarchy for the persistence library (behaviour B-OPS-4).
3
- * Every failure is a `RepositoryError` subclass carrying the operation context.
4
- */
1
+ import { DynamoDBToolboxError } from "dynamodb-toolbox/errors";
5
2
  export class RepositoryError extends Error {
6
3
  operation;
7
4
  constructor(message, operation, options) {
@@ -37,4 +34,37 @@ export class BatchProcessingError extends RepositoryError {
37
34
  this.unprocessed = unprocessed;
38
35
  }
39
36
  }
37
+ const CONDITIONAL_CHECK_FAILED = "ConditionalCheckFailedException";
38
+ function errorName(error) {
39
+ if (typeof error !== "object" || error === null || !("name" in error)) {
40
+ return undefined;
41
+ }
42
+ const name = error.name;
43
+ return typeof name === "string" ? name : undefined;
44
+ }
45
+ /**
46
+ * Map a raw dynamodb-toolbox / DynamoDB error onto the family taxonomy.
47
+ *
48
+ * - an existing `RepositoryError` passes through unchanged;
49
+ * - `ConditionalCheckFailedException` means a write condition was not met (item
50
+ * absent) → `NotFoundError`;
51
+ * - a `DynamoDBToolboxError` is a schema/parse/format/option problem →
52
+ * `RepositoryValidationError`;
53
+ * - anything else is wrapped as `RepositoryError`, preserving the cause.
54
+ */
55
+ export function mapToolboxError(error, operation) {
56
+ if (error instanceof RepositoryError) {
57
+ return error;
58
+ }
59
+ if (errorName(error) === CONDITIONAL_CHECK_FAILED) {
60
+ return new NotFoundError(`Condition not met for ${operation} (item absent)`, operation, {
61
+ cause: error,
62
+ });
63
+ }
64
+ if (DynamoDBToolboxError.match(error)) {
65
+ return new RepositoryValidationError(error.message, operation, { cause: error });
66
+ }
67
+ const message = error instanceof Error ? error.message : String(error);
68
+ return new RepositoryError(message, operation, { cause: error });
69
+ }
40
70
  //# sourceMappingURL=errors.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,SAAS,CAAS;IAE3B,YAAY,OAAe,EAAE,SAAiB,EAAE,OAAgC;QAC9E,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAQD,MAAM,OAAO,yBAA0B,SAAQ,eAAe;IACnD,EAAE,CAAqB;IACvB,EAAE,CAAqB;IACvB,MAAM,CAAqB;IAEpC,YAAY,OAAe,EAAE,SAAiB,EAAE,UAAkC,EAAE;QAClF,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,eAAe;CAAG;AAErD,MAAM,OAAO,4BAA6B,SAAQ,eAAe;IACtD,QAAQ,CAAS;IAE1B,YAAY,SAAiB,EAAE,QAAgB;QAC7C,KAAK,CAAC,uBAAuB,MAAM,CAAC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC;QAC3E,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,eAAe;IAC9C,WAAW,CAAY;IAEhC,YAAY,SAAiB,EAAE,WAAsB;QACnD,KAAK,CAAC,4BAA4B,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,sBAAsB,EAAE,SAAS,CAAC,CAAC;QAC/F,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF"}
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
package/dist/index.d.ts CHANGED
@@ -1,8 +1,5 @@
1
- export * from "./base-repository.js";
2
- export * from "./batch-processor.js";
3
- export * from "./client.js";
4
- export * from "./config.js";
1
+ export * from "./conformance.js";
2
+ export * from "./conventions.js";
5
3
  export * from "./errors.js";
6
- export * from "./query-engine.js";
7
- export * from "./update-builder.js";
4
+ export * from "./pagination.js";
8
5
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,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,8 +1,5 @@
1
- export * from "./base-repository.js";
2
- export * from "./batch-processor.js";
3
- export * from "./client.js";
4
- export * from "./config.js";
1
+ export * from "./conformance.js";
2
+ export * from "./conventions.js";
5
3
  export * from "./errors.js";
6
- export * from "./query-engine.js";
7
- export * from "./update-builder.js";
4
+ export * from "./pagination.js";
8
5
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,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"}
@@ -0,0 +1,16 @@
1
+ export interface PaginateOptions {
2
+ /** Upper bound on pages fetched. Use `Infinity` to paginate to completion. */
3
+ maxPages: number;
4
+ /** Operation name recorded on a thrown `PaginationLimitExceededError`. */
5
+ operation: string;
6
+ }
7
+ /**
8
+ * Run an auto-paginating toolbox query/scan and **throw** `PaginationLimitExceededError`
9
+ * when `maxPages` is reached with pages still remaining.
10
+ *
11
+ * dynamodb-toolbox's own `maxPages` option silently stops at the cap, returning a
12
+ * truncated result set with a dangling `LastEvaluatedKey`; this wrapper turns that
13
+ * silent truncation into a loud, typed failure.
14
+ */
15
+ export declare function paginate<RESPONSE>(run: (maxPages: number) => Promise<RESPONSE>, options: PaginateOptions): Promise<RESPONSE>;
16
+ //# sourceMappingURL=pagination.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;CACnB;AASD;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EACrC,GAAG,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,EAC5C,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,QAAQ,CAAC,CAMnB"}
@@ -0,0 +1,23 @@
1
+ import { PaginationLimitExceededError } from "./errors.js";
2
+ function morePagesRemain(response) {
3
+ if (typeof response !== "object" || response === null) {
4
+ return false;
5
+ }
6
+ return response.LastEvaluatedKey !== undefined;
7
+ }
8
+ /**
9
+ * Run an auto-paginating toolbox query/scan and **throw** `PaginationLimitExceededError`
10
+ * when `maxPages` is reached with pages still remaining.
11
+ *
12
+ * dynamodb-toolbox's own `maxPages` option silently stops at the cap, returning a
13
+ * truncated result set with a dangling `LastEvaluatedKey`; this wrapper turns that
14
+ * silent truncation into a loud, typed failure.
15
+ */
16
+ export async function paginate(run, options) {
17
+ const response = await run(options.maxPages);
18
+ if (morePagesRemain(response)) {
19
+ throw new PaginationLimitExceededError(options.operation, options.maxPages);
20
+ }
21
+ return response;
22
+ }
23
+ //# sourceMappingURL=pagination.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAS3D,SAAS,eAAe,CAAC,QAAiB;IACxC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAQ,QAA2C,CAAC,gBAAgB,KAAK,SAAS,CAAC;AACrF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,GAA4C,EAC5C,OAAwB;IAExB,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,4BAA4B,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "@sxh62/dynamo",
3
- "version": "0.1.1",
3
+ "version": "0.3.0",
4
+ "description": "Family conventions and shared extensions over dynamodb-toolbox for the sxh DynamoDB apps.",
4
5
  "type": "module",
5
6
  "main": "./dist/index.js",
6
7
  "types": "./dist/index.d.ts",
@@ -10,7 +11,7 @@
10
11
  "repository": {
11
12
  "type": "git",
12
13
  "url": "git+https://github.com/sxh/dynamo_persistence.git",
13
- "directory": "server"
14
+ "directory": "toolbox"
14
15
  },
15
16
  "publishConfig": {
16
17
  "access": "public"
@@ -23,17 +24,21 @@
23
24
  "test": "vitest run",
24
25
  "coverage": "vitest run --coverage",
25
26
  "build": "tsc -p tsconfig.build.json",
26
- "prepack": "npm run build",
27
- "integration": "vitest run --config vitest.integration.config.ts"
27
+ "prepack": "npm run build"
28
28
  },
29
29
  "peerDependencies": {
30
30
  "@aws-sdk/client-dynamodb": "^3.700.0",
31
31
  "@aws-sdk/lib-dynamodb": "^3.700.0",
32
+ "@aws-sdk/util-dynamodb": "^3.700.0",
32
33
  "zod": "^3.24.0"
33
34
  },
35
+ "dependencies": {
36
+ "dynamodb-toolbox": "^2.11.0"
37
+ },
34
38
  "devDependencies": {
35
39
  "@aws-sdk/client-dynamodb": "^3.700.0",
36
40
  "@aws-sdk/lib-dynamodb": "^3.700.0",
41
+ "@aws-sdk/util-dynamodb": "^3.700.0",
37
42
  "@eslint/js": "^9.17.0",
38
43
  "@types/node": "^22.10.0",
39
44
  "@vitest/coverage-v8": "5.0.3",
@@ -1,36 +0,0 @@
1
- import { type TransactWriteCommandInput } from "@aws-sdk/lib-dynamodb";
2
- import type { ZodType } from "zod";
3
- import { type WriteRequests } from "./batch-processor.js";
4
- import { type Logger, type RepositoryConfig } from "./config.js";
5
- import { type QueryParams, type ScanParams } from "./query-engine.js";
6
- /**
7
- * Shared DynamoDB access primitives over an injected document client (DESIGN §5.3).
8
- * All collaborators (client, table name, limits) are injected — no `sst`/`Resource` coupling.
9
- */
10
- export declare abstract class BaseRepository {
11
- protected readonly tableName: string;
12
- protected readonly logger: Logger;
13
- private readonly docClient;
14
- private readonly maxPages;
15
- private readonly batchSize;
16
- private readonly maxBatchRetries;
17
- private readonly concurrencyLimit;
18
- private queryEngineInstance?;
19
- protected constructor(config: RepositoryConfig);
20
- private get queryEngine();
21
- protected putItem<T>(item: T, schema?: ZodType<T>): Promise<T>;
22
- protected getItem<T>(pk: string, sk: string, schema?: ZodType<T>): Promise<T | null>;
23
- protected deleteItem(pk: string, sk: string): Promise<void>;
24
- protected updateItem<T>(pk: string, sk: string, attributes: Partial<T>, schema?: ZodType<T>): Promise<T>;
25
- protected query<T>(params: QueryParams, schema?: ZodType<T>): Promise<{
26
- items: T[];
27
- nextToken?: string;
28
- }>;
29
- protected queryAll<T>(params: QueryParams, schema?: ZodType<T>): Promise<T[]>;
30
- protected scanAll<T>(params: ScanParams, schema?: ZodType<T>): Promise<T[]>;
31
- protected queryIterator<T>(params: QueryParams, schema?: ZodType<T>): AsyncGenerator<T[]>;
32
- protected transactWrite(items: TransactWriteCommandInput["TransactItems"], operationName: string): Promise<void>;
33
- protected batchWrite(requests: WriteRequests): Promise<void>;
34
- private wrap;
35
- }
36
- //# sourceMappingURL=base-repository.d.ts.map