@sxh62/dynamo 0.2.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 +206 -0
- package/dist/conformance.d.ts +26 -0
- package/dist/conformance.d.ts.map +1 -0
- package/dist/conformance.js +74 -0
- package/dist/conformance.js.map +1 -0
- package/dist/conventions.d.ts +28 -16
- package/dist/conventions.d.ts.map +1 -1
- package/dist/conventions.js.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,206 @@
|
|
|
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
|
+
## 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
|
+
|
|
153
|
+
## Changing an entity's stored shape? Migrate — in every environment.
|
|
154
|
+
|
|
155
|
+
When a shape changes (e.g. the old `{ pk, sk, data: {...} }` blob → flattened), write a
|
|
156
|
+
**one-time, idempotent** migration that rewrites the affected rows and skips anything already in
|
|
157
|
+
the target shape. See rpg_combat_tool's `scripts/migrate-flatten.ts` (+ `migrate.sh`): scan for a
|
|
158
|
+
marker attribute, rewrite, do nothing if there's nothing to do.
|
|
159
|
+
|
|
160
|
+
**This is a gate in the conversion checklist above — not optional, and not just one environment.**
|
|
161
|
+
Before (or with) deploying the new code, check the stored items in **every environment** (dev,
|
|
162
|
+
production, and any sample/other stages) and migrate each one that needs it: a strict entity read
|
|
163
|
+
fails on an un-migrated row. A shape-preserving conversion (flat → flat, as in ronke) has nothing
|
|
164
|
+
to migrate — but you still check every environment to confirm that.
|
|
165
|
+
|
|
166
|
+
## Prove it: the per-app conformance suite
|
|
167
|
+
|
|
168
|
+
Each app should run the shared suite against a small **profile** — its table and entities — so
|
|
169
|
+
every app proves it follows these conventions the same way, instead of hand-writing its own
|
|
170
|
+
check. `conformanceCases(profile)` returns named cases whose `check()` throws with an actionable
|
|
171
|
+
message when a convention is violated; it is framework-agnostic, so run it from any test runner:
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
import { conformanceCases } from "@sxh62/dynamo";
|
|
175
|
+
import { it } from "vitest";
|
|
176
|
+
|
|
177
|
+
import { mainTable } from "./table";
|
|
178
|
+
import { ALL_ENTITIES } from "./entities";
|
|
179
|
+
|
|
180
|
+
for (const c of conformanceCases({
|
|
181
|
+
table: mainTable,
|
|
182
|
+
entities: ALL_ENTITIES,
|
|
183
|
+
extraIndexes: ["GSI2"],
|
|
184
|
+
})) {
|
|
185
|
+
it(c.name, c.check);
|
|
186
|
+
}
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
The profile:
|
|
190
|
+
|
|
191
|
+
```ts
|
|
192
|
+
interface ConformanceProfile {
|
|
193
|
+
table: Table; // built with defineTable
|
|
194
|
+
entities: Entity[]; // built with FAMILY_ENTITY_OPTIONS
|
|
195
|
+
extraIndexes?: string[]; // any global indexes beyond GSI1 (e.g. ["GSI2"])
|
|
196
|
+
}
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
It asserts: the primary key is `pk`/`sk` (both string); `GSI1` is a global index over
|
|
200
|
+
`gsi1pk`/`gsi1sk`; every declared extra index exists; every entity is bound to the table; and
|
|
201
|
+
every entity disables both the `_et` attribute and timestamps (i.e. spreads
|
|
202
|
+
`FAMILY_ENTITY_OPTIONS`).
|
|
203
|
+
|
|
204
|
+
## The "raw vs toolbox" rule, in one line
|
|
205
|
+
|
|
206
|
+
**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":"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"}
|
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"}
|
package/dist/index.d.ts
CHANGED
package/dist/index.d.ts.map
CHANGED
|
@@ -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
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"}
|