@photon-grove/evt 0.0.0 → 0.1.1

package/dist/dynamodb/item.js

@@ -0,0 +1,264 @@
+// The DynamoDB item layout of the event log. It's pure: it shapes items the way the AWS SDK's
+// low-level client takes them, and imports nothing from the SDK.
+//
+// | Attribute    | Type | Event item     | Snapshot item (sk 0) | Head item (sk -1) |
+// | ------------ | ---- | -------------- | -------------------- | ----------------- |
+// | `pk`         | S    | entity ID      | entity ID            | entity ID         |
+// | `sk`         | N    | event sequence | `0`                  | `-1`              |
+// | `type`       | S    | event type     |                      |                   |
+// | `version`    | N    | event version  |                      |                   |
+// | `entityType` | S    | entity type    | entity type          |                   |
+// | `payload`    | S    | payload JSON   | state JSON           |                   |
+// | `metadata`   | S    | metadata JSON  |                      |                   |
+// | `seq`        | N    |                | snapshot sequence    |                   |
+// | `eventSeq`   | N    |                | last event folded in |                   |
+// | `head`       | N    |                |                      | highest sequence  |
+// | `ttl`        | N    | optional       | optional             | optional          |
+import { eventId } from '../event.js';
+import { EvtError } from '../errors.js';
+import { DOCUMENT, checkInt64, int64Argument, invalid, safeIntegerArgument, } from '../fields.js';
+import { parseJson } from '../json.js';
+import { encodeMetadata, metadataFromJson } from '../metadata.js';
+import { utf8Decode, utf8Encode, utf8Length } from '../utf8.js';
+/** The sort key of a stream's inline snapshot. */
+export const SNAPSHOT_SORT_KEY = 0n;
+/** The sort key of a stream's head item. */
+export const HEAD_SORT_KEY = -1n;
+/** The sort key of a single-item view row. */
+export const DEFAULT_VIEW_SORT_KEY = 'VIEW';
+/** Encodes an event as an event-log item. `ttl` (Unix seconds) is written only when positive. */
+export function eventItem(event, ttl) {
+    return withTtl({
+        pk: { S: event.entityId },
+        sk: { N: int64Argument(event.sequence, 'event.sequence').toString() },
+        type: { S: event.type },
+        version: { N: safeIntegerArgument(event.version, 'event.version').toString() },
+        entityType: { S: event.entityType },
+        payload: { S: payloadText(event.payload, 'event payload') },
+        metadata: { S: encodeMetadata(event.metadata) },
+    }, ttl);
+}
+/** Encodes a stream's inline snapshot item. `ttl` is written only when positive. */
+export function snapshotItem(snapshot, ttl) {
+    return withTtl({
+        pk: { S: snapshot.entityId },
+        sk: { N: SNAPSHOT_SORT_KEY.toString() },
+        seq: { N: int64Argument(snapshot.sequence, 'snapshot.sequence').toString() },
+        eventSeq: { N: int64Argument(snapshot.eventSequence, 'snapshot.eventSequence').toString() },
+        entityType: { S: snapshot.entityType },
+        payload: { S: payloadText(snapshot.payload, 'snapshot payload') },
+    }, ttl);
+}
+/** Encodes a stream's head item. `ttl` is written only when positive. */
+export function headItem(entityId, head, ttl) {
+    const item = {
+        pk: { S: entityId },
+        sk: { N: HEAD_SORT_KEY.toString() },
+        head: { N: int64Argument(head, 'head').toString() },
+    };
+    return withTtl(item, ttl);
+}
+/** Encodes a single-item view row: `pk = {entityType}#{entityId}`, `sk = "VIEW"`. */
+export function viewItem(entityType, entityId, payload) {
+    return {
+        pk: { S: `${entityType}#${entityId}` },
+        sk: { S: DEFAULT_VIEW_SORT_KEY },
+        entityID: { S: entityId },
+        entityType: { S: entityType },
+        payload: { S: payloadText(payload, 'view payload') },
+    };
+}
+/**
+ * Decodes an event-log item. Missing attributes other than the key are empty, and `metadata` must
+ * be present and not blank. A JSON `null` metadata is the zero value, as in Go.
+ */
+export function eventFromItem(item) {
+    const entityId = requiredString(item, 'pk');
+    const sequence = requiredNumber(item, 'sk');
+    const id = eventId(entityId, sequence);
+    const metadata = optionalString(item, 'metadata') ?? '';
+    if (metadata.trim() === '') {
+        throw invalid(`event ${id} has empty metadata`);
+    }
+    let decoded;
+    try {
+        decoded = metadataFromJson(parseJson(metadata, DOCUMENT));
+    }
+    catch (error) {
+        throw new EvtError('invalidRecord', `event ${id} metadata: ${message(error)}`, { cause: error });
+    }
+    return {
+        id,
+        sequence,
+        type: optionalString(item, 'type') ?? '',
+        version: safeInteger(optionalNumber(item, 'version') ?? 0n, 'version'),
+        entityId,
+        entityType: optionalString(item, 'entityType') ?? '',
+        payload: utf8Encode(optionalString(item, 'payload') ?? ''),
+        metadata: decoded,
+    };
+}
+/** Decodes a stream's inline snapshot item. */
+export function snapshotFromItem(item) {
+    return {
+        entityType: optionalString(item, 'entityType') ?? '',
+        entityId: requiredString(item, 'pk'),
+        sequence: optionalNumber(item, 'seq') ?? 0n,
+        eventSequence: optionalNumber(item, 'eventSeq') ?? 0n,
+        payload: utf8Encode(optionalString(item, 'payload') ?? ''),
+    };
+}
+/** Decodes a head item into its head and its `ttl`, if it has one. */
+export function headFromItem(item) {
+    return { head: requiredNumber(item, 'head'), ttl: ttlFromItem(item) };
+}
+/** An item's `ttl` in Unix seconds, or undefined when it has none. */
+export function ttlFromItem(item) {
+    const ttl = optionalNumber(item, 'ttl');
+    return ttl === undefined ? undefined : safeInteger(ttl, 'ttl');
+}
+/** Whether an item is a stream's inline snapshot (`sk = 0`). */
+export function isSnapshotItem(item) {
+    return sortKey(item) === SNAPSHOT_SORT_KEY;
+}
+/** An item's numeric sort key, if it has one. */
+export function sortKey(item) {
+    const sk = item['sk'];
+    if (sk === undefined || !('N' in sk)) {
+        return undefined;
+    }
+    return parseNumber(sk.N);
+}
+/**
+ * The `ttl` of an item written at `nowMs` (Unix milliseconds) under a retention of `retentionMs`:
+ * their sum in whole Unix seconds, rounded down after adding, as Go's `Time.Add(...).Unix()` is.
+ * Undefined, so no `ttl` is written, for a zero retention. A retention with a fraction of a
+ * millisecond is refused, because Go would count it.
+ */
+export function expiry(nowMs, retentionMs) {
+    if (!Number.isSafeInteger(nowMs) || !Number.isSafeInteger(retentionMs) || retentionMs < 0) {
+        throw new EvtError('invalidArgument', 'the clock and the retention must be whole, non-negative milliseconds: ' +
+            `${nowMs}, ${retentionMs}`);
+    }
+    if (retentionMs === 0) {
+        return undefined;
+    }
+    return Math.floor((nowMs + retentionMs) / 1000);
+}
+/**
+ * The size DynamoDB counts for an item: each attribute's name plus its value, in UTF-8 bytes. The
+ * commit budget measures every action with it.
+ */
+export function itemSize(item) {
+    let size = 0;
+    for (const [name, value] of Object.entries(item)) {
+        size += utf8Length(name) + valueSize(value);
+    }
+    return size;
+}
+function valueSize(value) {
+    if ('S' in value) {
+        return utf8Length(value.S);
+    }
+    if ('N' in value) {
+        return utf8Length(value.N);
+    }
+    if ('B' in value) {
+        return value.B.length;
+    }
+    if ('BOOL' in value || 'NULL' in value) {
+        return 1;
+    }
+    if ('M' in value) {
+        return 3 + itemSize(value.M) + Object.keys(value.M).length;
+    }
+    if ('L' in value) {
+        return value.L.reduce((size, entry) => size + 1 + valueSize(entry), 3);
+    }
+    if ('SS' in value) {
+        return value.SS.reduce((size, entry) => size + utf8Length(entry), 0);
+    }
+    if ('NS' in value) {
+        return value.NS.reduce((size, entry) => size + utf8Length(entry), 0);
+    }
+    return value.BS.reduce((size, entry) => size + entry.length, 0);
+}
+function withTtl(item, ttl) {
+    if (ttl !== undefined && safeIntegerArgument(ttl, 'ttl') > 0) {
+        item['ttl'] = { N: ttl.toString() };
+    }
+    return item;
+}
+// A payload is stored as a DynamoDB string, so it must be UTF-8. A null payload is stored empty.
+function payloadText(payload, what) {
+    if (payload === null) {
+        return '';
+    }
+    try {
+        return utf8Decode(payload, what);
+    }
+    catch (error) {
+        const reason = `${what} is not valid UTF-8 and cannot be stored as a string`;
+        throw new EvtError('invalidArgument', reason, { cause: error });
+    }
+}
+function requiredString(item, name) {
+    const value = optionalString(item, name);
+    if (value === undefined) {
+        throw invalid(`item has no ${name} attribute`);
+    }
+    return value;
+}
+function requiredNumber(item, name) {
+    const value = optionalNumber(item, name);
+    if (value === undefined) {
+        throw invalid(`item has no ${name} attribute`);
+    }
+    return value;
+}
+function optionalString(item, name) {
+    const value = item[name];
+    if (value === undefined || 'NULL' in value) {
+        return undefined;
+    }
+    if (!('S' in value)) {
+        throw invalid(`attribute ${name} is not a string`);
+    }
+    return value.S;
+}
+function optionalNumber(item, name) {
+    const value = item[name];
+    if (value === undefined || 'NULL' in value) {
+        return undefined;
+    }
+    if (!('N' in value)) {
+        throw invalid(`attribute ${name} is not a number`);
+    }
+    const number = parseNumber(value.N);
+    if (number === undefined) {
+        throw invalid(`attribute ${name} is not an integer: ${value.N}`);
+    }
+    return number;
+}
+// An int64 in decimal, as strconv.ParseInt reads it: an optional sign, then digits.
+function parseNumber(text) {
+    if (!/^[+-]?\d+$/.test(text)) {
+        return undefined;
+    }
+    try {
+        return checkInt64(BigInt(text), 'number');
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeInteger(value, name) {
+    if (value < BigInt(Number.MIN_SAFE_INTEGER) || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw invalid(`attribute ${name} is ${value}, past the integers it holds`);
+    }
+    return Number(value);
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=item.js.map

package/dist/dynamodb/item.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item.js","sourceRoot":"","sources":["../../src/dynamodb/item.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,iEAAiE;AACjE,EAAE;AACF,sFAAsF;AACtF,sFAAsF;AACtF,sFAAsF;AACtF,sFAAsF;AACtF,sFAAsF;AACtF,sFAAsF;AACtF,sFAAsF;AACtF,sFAAsF;AACtF,sFAAsF;AACtF,sFAAsF;AACtF,sFAAsF;AACtF,sFAAsF;AACtF,sFAAsF;AAEtF,OAAO,EAAgD,OAAO,EAAC,MAAM,aAAa,CAAA;AAClF,OAAO,EAAC,QAAQ,EAAC,MAAM,cAAc,CAAA;AACrC,OAAO,EACL,QAAQ,EACR,UAAU,EACV,aAAa,EACb,OAAO,EACP,mBAAmB,GACpB,MAAM,cAAc,CAAA;AACrB,OAAO,EAAC,SAAS,EAAC,MAAM,YAAY,CAAA;AACpC,OAAO,EAAC,cAAc,EAAE,gBAAgB,EAAC,MAAM,gBAAgB,CAAA;AAC/D,OAAO,EAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAC,MAAM,YAAY,CAAA;AAkB7D,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAA;AAEnC,4CAA4C;AAC5C,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,EAAE,CAAA;AAEhC,8CAA8C;AAC9C,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAA;AAE3C,iGAAiG;AACjG,MAAM,UAAU,SAAS,CAAC,KAAsB,EAAE,GAAY;IAC5D,OAAO,OAAO,CACZ;QACE,EAAE,EAAE,EAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,EAAC;QACvB,EAAE,EAAE,EAAC,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,QAAQ,EAAE,EAAC;QACnE,IAAI,EAAE,EAAC,CAAC,EAAE,KAAK,CAAC,IAAI,EAAC;QACrB,OAAO,EAAE,EAAC,CAAC,EAAE,mBAAmB,CAAC,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,QAAQ,EAAE,EAAC;QAC5E,UAAU,EAAE,EAAC,CAAC,EAAE,KAAK,CAAC,UAAU,EAAC;QACjC,OAAO,EAAE,EAAC,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,EAAC;QACzD,QAAQ,EAAE,EAAC,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAC;KAC9C,EACD,GAAG,CACJ,CAAA;AACH,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,YAAY,CAAC,QAA4B,EAAE,GAAY;IACrE,OAAO,OAAO,CACZ;QACE,EAAE,EAAE,EAAC,CAAC,EAAE,QAAQ,CAAC,QAAQ,EAAC;QAC1B,EAAE,EAAE,EAAC,CAAC,EAAE,iBAAiB,CAAC,QAAQ,EAAE,EAAC;QACrC,GAAG,EAAE,EAAC,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC,QAAQ,EAAE,EAAC;QAC1E,QAAQ,EAAE,EAAC,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,aAAa,EAAE,wBAAwB,CAAC,CAAC,QAAQ,EAAE,EAAC;QACzF,UAAU,EAAE,EAAC,CAAC,EAAE,QAAQ,CAAC,UAAU,EAAC;QACpC,OAAO,EAAE,EAAC,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,EAAC;KAChE,EACD,GAAG,CACJ,CAAA;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,QAAQ,CAAC,QAAgB,EAAE,IAAY,EAAE,GAAY;IACnE,MAAM,IAAI,GAAS;QACjB,EAAE,EAAE,EAAC,CAAC,EAAE,QAAQ,EAAC;QACjB,EAAE,EAAE,EAAC,CAAC,EAAE,aAAa,CAAC,QAAQ,EAAE,EAAC;QACjC,IAAI,EAAE,EAAC,CAAC,EAAE,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAC;KAClD,CAAA;IAED,OAAO,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;AAC3B,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,QAAQ,CAAC,UAAkB,EAAE,QAAgB,EAAE,OAAmB;IAChF,OAAO;QACL,EAAE,EAAE,EAAC,CAAC,EAAE,GAAG,UAAU,IAAI,QAAQ,EAAE,EAAC;QACpC,EAAE,EAAE,EAAC,CAAC,EAAE,qBAAqB,EAAC;QAC9B,QAAQ,EAAE,EAAC,CAAC,EAAE,QAAQ,EAAC;QACvB,UAAU,EAAE,EAAC,CAAC,EAAE,UAAU,EAAC;QAC3B,OAAO,EAAE,EAAC,CAAC,EAAE,WAAW,CAAC,OAAO,EAAE,cAAc,CAAC,EAAC;KACnD,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAU;IACtC,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAC3C,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IAC3C,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;IACtC,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAA;IACvD,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3B,MAAM,OAAO,CAAC,SAAS,EAAE,qBAAqB,CAAC,CAAA;IACjD,CAAC;IAED,IAAI,OAAO,CAAA;IACX,IAAI,CAAC;QACH,OAAO,GAAG,gBAAgB,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAA;IAC3D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,QAAQ,CAAC,eAAe,EAAE,SAAS,EAAE,cAAc,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,EAAC,KAAK,EAAE,KAAK,EAAC,CAAC,CAAA;IAChG,CAAC;IAED,OAAO;QACL,EAAE;QACF,QAAQ;QACR,IAAI,EAAE,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE;QACxC,OAAO,EAAE,WAAW,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC;QACtE,QAAQ;QACR,UAAU,EAAE,cAAc,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE;QACpD,OAAO,EAAE,UAAU,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;QAC1D,QAAQ,EAAE,OAAO;KAClB,CAAA;AACH,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,gBAAgB,CAAC,IAAU;IACzC,OAAO;QACL,UAAU,EAAE,cAAc,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE;QACpD,QAAQ,EAAE,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC;QACpC,QAAQ,EAAE,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;QAC3C,aAAa,EAAE,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE;QACrD,OAAO,EAAE,UAAU,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;KAC3D,CAAA;AACH,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,OAAO,EAAC,IAAI,EAAE,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,WAAW,CAAC,IAAI,CAAC,EAAC,CAAA;AACrE,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,WAAW,CAAC,IAAU;IACpC,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IAEvC,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;AAChE,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,IAAU;IACvC,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,iBAAiB,CAAA;AAC5C,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,OAAO,CAAC,IAAU;IAChC,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;IACrB,IAAI,EAAE,KAAK,SAAS,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;QACrC,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,WAAmB;IACvD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QAC1F,MAAM,IAAI,QAAQ,CAChB,iBAAiB,EACjB,wEAAwE;YACtE,GAAG,KAAK,KAAK,WAAW,EAAE,CAC7B,CAAA;IACH,CAAC;IACD,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,IAAI,CAAC,CAAA;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAU;IACjC,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,IAAI,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;IAC7C,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,SAAS,CAAC,KAAqB;IACtC,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;QACjB,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAC5B,CAAC;IACD,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;QACjB,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAC5B,CAAC;IACD,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;QACjB,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAA;IACvB,CAAC;IACD,IAAI,MAAM,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QACvC,OAAO,CAAC,CAAA;IACV,CAAC;IACD,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;IAC5D,CAAC;IACD,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;QACjB,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;IACxE,CAAC;IACD,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;QAClB,OAAO,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;IACtE,CAAC;IACD,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;QAClB,OAAO,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;IACtE,CAAC;IAED,OAAO,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;AACjE,CAAC;AAED,SAAS,OAAO,CAAC,IAAU,EAAE,GAAuB;IAClD,IAAI,GAAG,KAAK,SAAS,IAAI,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7D,IAAI,CAAC,KAAK,CAAC,GAAG,EAAC,CAAC,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAC,CAAA;IACnC,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,iGAAiG;AACjG,SAAS,WAAW,CAAC,OAA0B,EAAE,IAAY;IAC3D,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,EAAE,CAAA;IACX,CAAC;IAED,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,GAAG,IAAI,sDAAsD,CAAA;QAC5E,MAAM,IAAI,QAAQ,CAAC,iBAAiB,EAAE,MAAM,EAAE,EAAC,KAAK,EAAE,KAAK,EAAC,CAAC,CAAA;IAC/D,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,IAAU,EAAE,IAAY;IAC9C,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACxC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,OAAO,CAAC,eAAe,IAAI,YAAY,CAAC,CAAA;IAChD,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED,SAAS,cAAc,CAAC,IAAU,EAAE,IAAY;IAC9C,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACxC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,OAAO,CAAC,eAAe,IAAI,YAAY,CAAC,CAAA;IAChD,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED,SAAS,cAAc,CAAC,IAAU,EAAE,IAAY;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;IACxB,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QAC3C,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,OAAO,CAAC,aAAa,IAAI,kBAAkB,CAAC,CAAA;IACpD,CAAC;IAED,OAAO,KAAK,CAAC,CAAC,CAAA;AAChB,CAAC;AAED,SAAS,cAAc,CAAC,IAAU,EAAE,IAAY;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;IACxB,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;QAC3C,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,OAAO,CAAC,aAAa,IAAI,kBAAkB,CAAC,CAAA;IACpD,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,OAAO,CAAC,aAAa,IAAI,uBAAuB,KAAK,CAAC,CAAC,EAAE,CAAC,CAAA;IAClE,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED,oFAAoF;AACpF,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAA;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,KAAa,EAAE,IAAY;IAC9C,IAAI,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,IAAI,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACvF,MAAM,OAAO,CAAC,aAAa,IAAI,OAAO,KAAK,8BAA8B,CAAC,CAAA;IAC5E,CAAC;IAED,OAAO,MAAM,CAAC,KAAK,CAAC,CAAA;AACtB,CAAC;AAED,SAAS,OAAO,CAAC,KAAc;IAC7B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC/D,CAAC"}

package/dist/dynamodb/marker.d.ts

@@ -0,0 +1,11 @@
+import { type FeatureManifest } from '../features.js';
+import { type Item } from './item.js';
+/** The partition key of the feature-marker row. */
+export declare const FEATURES_PK = "SYSTEM#FEATURES";
+/** The partition key of the rebuild-lock row, which every commit checks is absent. */
+export declare const REBUILD_LOCK_PK = "SYSTEM#REBUILD";
+/** Encodes a feature manifest as its marker item. Empty entity-type sets are left out. */
+export declare function markerItem(manifest: FeatureManifest): Item;
+/** Decodes a marker item. An absent text attribute is an empty map or set. */
+export declare function manifestFromItem(item: Item): FeatureManifest;
+//# sourceMappingURL=marker.d.ts.map

package/dist/dynamodb/marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../src/dynamodb/marker.ts"],"names":[],"mappings":"AAWA,OAAO,EAAC,KAAK,eAAe,EAAiC,MAAM,gBAAgB,CAAA;AACnF,OAAO,EAAC,KAAK,IAAI,EAAoB,MAAM,WAAW,CAAA;AAEtD,mDAAmD;AACnD,eAAO,MAAM,WAAW,oBAAoB,CAAA;AAE5C,sFAAsF;AACtF,eAAO,MAAM,eAAe,mBAAmB,CAAA;AAE/C,0FAA0F;AAC1F,wBAAgB,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAgB1D;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,eAAe,CAW5D"}

package/dist/dynamodb/marker.js

@@ -0,0 +1,56 @@
+// The DynamoDB item of the feature-marker row. The control rows live in the reserved SYSTEM#
+// namespace at sort key 0.
+//
+// | Attribute          | Type | Feature-marker item (`pk = SYSTEM#FEATURES`, `sk = 0`)       |
+// | ------------------ | ---- | ------------------------------------------------------------ |
+// | `version`          | N    | bumped on every change to the manifest                       |
+// | `features`         | S    | JSON object, feature name → stored-format version, sorted    |
+// | `historyDependent` | S    | JSON array of entity types, sorted. Absent when empty        |
+// | `retention`        | S    | JSON array of entity types, sorted. Absent when empty        |
+import { checkInt64, invalid } from '../fields.js';
+import { decodeManifest, encodeManifest } from '../features.js';
+import { SNAPSHOT_SORT_KEY } from './item.js';
+/** The partition key of the feature-marker row. */
+export const FEATURES_PK = 'SYSTEM#FEATURES';
+/** The partition key of the rebuild-lock row, which every commit checks is absent. */
+export const REBUILD_LOCK_PK = 'SYSTEM#REBUILD';
+/** Encodes a feature manifest as its marker item. Empty entity-type sets are left out. */
+export function markerItem(manifest) {
+    const texts = encodeManifest(manifest);
+    const item = {
+        pk: { S: FEATURES_PK },
+        sk: { N: SNAPSHOT_SORT_KEY.toString() },
+        version: { N: manifest.version.toString() },
+        features: { S: texts.features },
+    };
+    if (manifest.historyDependent.length > 0) {
+        item['historyDependent'] = { S: texts.historyDependent };
+    }
+    if (manifest.retention.length > 0) {
+        item['retention'] = { S: texts.retention };
+    }
+    return item;
+}
+/** Decodes a marker item. An absent text attribute is an empty map or set. */
+export function manifestFromItem(item) {
+    const version = item['version'];
+    if (version === undefined || !('N' in version) || !/^\d+$/.test(version.N)) {
+        throw invalid('the feature marker has no version');
+    }
+    return decodeManifest(checkInt64(BigInt(version.N), 'the feature marker version'), {
+        features: text(item, 'features'),
+        historyDependent: text(item, 'historyDependent'),
+        retention: text(item, 'retention'),
+    });
+}
+function text(item, name) {
+    const value = item[name];
+    if (value === undefined) {
+        return '';
+    }
+    if (!('S' in value)) {
+        throw invalid(`the feature marker's ${name} attribute is not a string`);
+    }
+    return value.S;
+}
+//# sourceMappingURL=marker.js.map

package/dist/dynamodb/marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.js","sourceRoot":"","sources":["../../src/dynamodb/marker.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,2BAA2B;AAC3B,EAAE;AACF,+FAA+F;AAC/F,+FAA+F;AAC/F,+FAA+F;AAC/F,+FAA+F;AAC/F,+FAA+F;AAC/F,+FAA+F;AAE/F,OAAO,EAAC,UAAU,EAAE,OAAO,EAAC,MAAM,cAAc,CAAA;AAChD,OAAO,EAAuB,cAAc,EAAE,cAAc,EAAC,MAAM,gBAAgB,CAAA;AACnF,OAAO,EAAY,iBAAiB,EAAC,MAAM,WAAW,CAAA;AAEtD,mDAAmD;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,iBAAiB,CAAA;AAE5C,sFAAsF;AACtF,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,CAAA;AAE/C,0FAA0F;AAC1F,MAAM,UAAU,UAAU,CAAC,QAAyB;IAClD,MAAM,KAAK,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAA;IACtC,MAAM,IAAI,GAAS;QACjB,EAAE,EAAE,EAAC,CAAC,EAAE,WAAW,EAAC;QACpB,EAAE,EAAE,EAAC,CAAC,EAAE,iBAAiB,CAAC,QAAQ,EAAE,EAAC;QACrC,OAAO,EAAE,EAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAC;QACzC,QAAQ,EAAE,EAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,EAAC;KAC9B,CAAA;IACD,IAAI,QAAQ,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,kBAAkB,CAAC,GAAG,EAAC,CAAC,EAAE,KAAK,CAAC,gBAAgB,EAAC,CAAA;IACxD,CAAC;IACD,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,IAAI,CAAC,WAAW,CAAC,GAAG,EAAC,CAAC,EAAE,KAAK,CAAC,SAAS,EAAC,CAAA;IAC1C,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,gBAAgB,CAAC,IAAU;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAA;IAC/B,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,MAAM,OAAO,CAAC,mCAAmC,CAAC,CAAA;IACpD,CAAC;IAED,OAAO,cAAc,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,4BAA4B,CAAC,EAAE;QACjF,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC;QAChC,gBAAgB,EAAE,IAAI,CAAC,IAAI,EAAE,kBAAkB,CAAC;QAChD,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC;KACnC,CAAC,CAAA;AACJ,CAAC;AAED,SAAS,IAAI,CAAC,IAAU,EAAE,IAAY;IACpC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;IACxB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,CAAA;IACX,CAAC;IACD,IAAI,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,OAAO,CAAC,wBAAwB,IAAI,4BAA4B,CAAC,CAAA;IACzE,CAAC;IAED,OAAO,KAAK,CAAC,CAAC,CAAA;AAChB,CAAC"}

package/dist/dynamodb/repository.d.ts

@@ -0,0 +1,61 @@
+import type { SerializedEvent, SerializedSnapshot } from '../event.js';
+import { type CallOptions, type Commit, type Repository, type StoreInitializer } from '../repository.js';
+import type { DynamoClient } from './client.js';
+/** How a {@link DynamoRepository} reads and initializes its store. */
+export interface DynamoRepositoryOptions {
+    /**
+     * Whether a write to a store that doesn't declare stream-heads initializes it, scanning the
+     * table to make sure it holds no data, instead of refusing with a
+     * {@link StoreNotInitializedError}. Off by default, so writers never need `dynamodb:Scan`:
+     * initialize a fresh store once, at deploy time, with {@link DynamoRepository.initialize}.
+     */
+    lazyInitialization?: boolean;
+    /**
+     * Whether event and snapshot reads are strongly consistent. On by default. Head reads, the
+     * failure-path probe, compaction and the feature marker always read consistently.
+     */
+    consistentRead?: boolean;
+    /**
+     * How long the items of each entity type live, in whole milliseconds, keyed by entity type.
+     * Every event, snapshot and head item of a type with a positive retention carries a DynamoDB
+     * `ttl`, the write time plus the retention in Unix seconds, for the table's TTL to delete. A
+     * type that isn't listed, or has 0, is kept forever. TTL deletes items in no order, so retain
+     * only short-lived streams that nothing replays. Declare the retained types in the store's
+     * feature manifest too, from Go or Rust, so that their writers refuse read fences on them.
+     */
+    retention?: Readonly<Record<string, number>> | ReadonlyMap<string, number>;
+    /**
+     * The clock that stamps `ttl`s and decides which have passed, in Unix milliseconds as
+     * `Date.now` gives them, never seconds. `Date.now` by default.
+     */
+    clock?: () => number;
+}
+/**
+ * A {@link Repository} on a DynamoDB event-log table, through the AWS SDK's low-level `DynamoDB`
+ * client or anything shaped like it ({@link DynamoClient}).
+ *
+ * The repository validates the store's feature manifest at its first write and caches the version
+ * it validated. Every commit and snapshot write checks that version, so when another writer
+ * declares a feature, the next write fails, validates the manifest again, and either refuses an
+ * unsupported feature or fails once with a retryable {@link FeatureManifestChangedError}.
+ */
+export declare class DynamoRepository implements Repository, StoreInitializer {
+    #private;
+    constructor(client: DynamoClient, eventsTable: string, options?: DynamoRepositoryOptions);
+    /** The events table this repository writes. */
+    get eventsTable(): string;
+    /**
+     * Declares stream-heads on a store that holds no data, and resolves `true` when this call
+     * declared it. It scans the table with strongly consistent reads, so run it once, at deploy
+     * time, with a role that may Scan. Concurrent initializations let exactly one declare.
+     */
+    initialize(options?: CallOptions): Promise<boolean>;
+    commit(commit: Commit, options?: CallOptions): Promise<void>;
+    events(entityId: string, options?: CallOptions): Promise<SerializedEvent[]>;
+    eventsAfter(entityId: string, after: bigint, options?: CallOptions): Promise<SerializedEvent[]>;
+    latest(entityId: string, n: number, options?: CallOptions): Promise<SerializedEvent[]>;
+    snapshot(entityId: string, options?: CallOptions): Promise<SerializedSnapshot | null>;
+    putSnapshot(snapshot: SerializedSnapshot, options?: CallOptions): Promise<boolean>;
+    compactBelow(entityId: string, through: bigint, options?: CallOptions): Promise<number>;
+}
+//# sourceMappingURL=repository.d.ts.map

package/dist/dynamodb/repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/dynamodb/repository.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAC,eAAe,EAAE,kBAAkB,EAAC,MAAM,aAAa,CAAA;AASpE,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,gBAAgB,EAMtB,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAC,YAAY,EAAqC,MAAM,aAAa,CAAA;AAoBjF,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1E;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;CACrB;AAoBD;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,YAAW,UAAU,EAAE,gBAAgB;;IAgBnE,YAAY,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B,EAO3F;IAED,+CAA+C;IAC/C,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;OAIG;IACG,UAAU,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAyBxD;IAEK,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBjE;IAEK,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAEhF;IAEK,WAAW,CACf,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,eAAe,EAAE,CAAC,CAa5B;IAEK,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAmB3F;IAEK,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAI1F;IAEK,WAAW,CAAC,QAAQ,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAgEvF;IAEK,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CA+C5F;CAyjBF"}