@photon-grove/evt 0.0.0-stage → 0.1.0

package/dist/envelope.d.ts

@@ -0,0 +1,15 @@
+import { type SerializedEvent } from './event.js';
+/** Encodes the envelope for an event, byte for byte as the Go publisher wrote it. */
+export declare function encodeEnvelope(event: SerializedEvent, source: string): string;
+/**
+ * Decodes the event from an envelope body: an SNS message, or an SQS body delivered raw. An event
+ * with no entity ID or event ID is refused.
+ */
+export declare function decodeEnvelope(body: string): SerializedEvent;
+/**
+ * The message attributes the publisher set, all strings: `entityType` and `eventType`, then
+ * `commandId` and `traceparent` when they aren't empty, and `correlationId`, the command ID or
+ * else the traceparent.
+ */
+export declare function messageAttributes(event: SerializedEvent): Record<string, string>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,KAAK,eAAe,EAA6B,MAAM,YAAY,CAAA;AAO3E,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAY7E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAW5D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBhF"}

package/dist/envelope.js

@@ -0,0 +1,59 @@
+// The stream envelope: the EventBridge-style message around each committed event, which consumers
+// in every language unwrap. Go decodes it with projectors.StreamRecordFromEnvelope.
+import { eventFromJson, encodeEvent } from './event.js';
+import { DOCUMENT, invalid, objectOrNull } from './fields.js';
+import { RawJson, parseJson, stringifyJson } from './json.js';
+// Go's zero time.Time, which the publisher left in the time field.
+const ZERO_TIME = '0001-01-01T00:00:00Z';
+/** Encodes the envelope for an event, byte for byte as the Go publisher wrote it. */
+export function encodeEnvelope(event, source) {
+    return stringifyJson({
+        version: '',
+        id: event.id,
+        'detail-type': event.type,
+        source,
+        account: '',
+        time: ZERO_TIME,
+        region: '',
+        resources: null,
+        detail: new RawJson(encodeEvent(event)),
+    });
+}
+/**
+ * Decodes the event from an envelope body: an SNS message, or an SQS body delivered raw. An event
+ * with no entity ID or event ID is refused.
+ */
+export function decodeEnvelope(body) {
+    const envelope = objectOrNull(parseJson(body, DOCUMENT), 'envelope') ?? new Map();
+    const event = eventFromJson(objectOrNull(envelope.get('detail'), 'envelope.detail'));
+    if (event.entityId === '') {
+        throw invalid('event envelope has no entity id');
+    }
+    if (event.id === '') {
+        throw invalid('event envelope has no event id');
+    }
+    return event;
+}
+/**
+ * The message attributes the publisher set, all strings: `entityType` and `eventType`, then
+ * `commandId` and `traceparent` when they aren't empty, and `correlationId`, the command ID or
+ * else the traceparent.
+ */
+export function messageAttributes(event) {
+    const attributes = {
+        entityType: event.entityType,
+        eventType: event.type,
+    };
+    const commandId = event.metadata.commandId;
+    if (commandId !== null && commandId !== '') {
+        attributes['commandId'] = commandId;
+        attributes['correlationId'] = commandId;
+    }
+    const traceparent = event.metadata.trace?.get('traceparent');
+    if (traceparent !== undefined && traceparent !== '') {
+        attributes['traceparent'] = traceparent;
+        attributes['correlationId'] ??= traceparent;
+    }
+    return attributes;
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,oFAAoF;AAEpF,OAAO,EAAuB,aAAa,EAAE,WAAW,EAAC,MAAM,YAAY,CAAA;AAC3E,OAAO,EAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAC,MAAM,aAAa,CAAA;AAC3D,OAAO,EAAC,OAAO,EAAE,SAAS,EAAE,aAAa,EAAC,MAAM,WAAW,CAAA;AAE3D,mEAAmE;AACnE,MAAM,SAAS,GAAG,sBAAsB,CAAA;AAExC,qFAAqF;AACrF,MAAM,UAAU,cAAc,CAAC,KAAsB,EAAE,MAAc;IACnE,OAAO,aAAa,CAAC;QACnB,OAAO,EAAE,EAAE;QACX,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,aAAa,EAAE,KAAK,CAAC,IAAI;QACzB,MAAM;QACN,OAAO,EAAE,EAAE;QACX,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE;QACV,SAAS,EAAE,IAAI;QACf,MAAM,EAAE,IAAI,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;KACxC,CAAC,CAAA;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,QAAQ,GAAG,YAAY,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,UAAU,CAAC,IAAI,IAAI,GAAG,EAAE,CAAA;IACjF,MAAM,KAAK,GAAG,aAAa,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAA;IACpF,IAAI,KAAK,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC1B,MAAM,OAAO,CAAC,iCAAiC,CAAC,CAAA;IAClD,CAAC;IACD,IAAI,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACpB,MAAM,OAAO,CAAC,gCAAgC,CAAC,CAAA;IACjD,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAsB;IACtD,MAAM,UAAU,GAA2B;QACzC,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,SAAS,EAAE,KAAK,CAAC,IAAI;KACtB,CAAA;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAA;IAC1C,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QAC3C,UAAU,CAAC,WAAW,CAAC,GAAG,SAAS,CAAA;QACnC,UAAU,CAAC,eAAe,CAAC,GAAG,SAAS,CAAA;IACzC,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,aAAa,CAAC,CAAA;IAC5D,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,KAAK,EAAE,EAAE,CAAC;QACpD,UAAU,CAAC,aAAa,CAAC,GAAG,WAAW,CAAA;QACvC,UAAU,CAAC,eAAe,CAAC,KAAK,WAAW,CAAA;IAC7C,CAAC;IAED,OAAO,UAAU,CAAA;AACnB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,111 @@
+/**
+ * What went wrong:
+ *
+ * - `invalidJson`: text that isn't JSON.
+ * - `invalidRecord`: a stored record (an event, a snapshot, an item) with the wrong shape.
+ * - `invalidArgument`: a value evt can't write, such as a float that isn't finite or an object
+ *   whose key order the engine has already changed, or a read with a bad argument, such as
+ *   `latest(0)`.
+ * - `invalidCommit`: a commit built wrong, such as one with another entity's event. Nothing was
+ *   written.
+ * - `conflict`: optimistic concurrency failed. Another writer committed since the stream was
+ *   read. Reload and run the command again.
+ * - `sequenceGap`: a commit or a load skips a sequence. A conflict.
+ * - `streamHeadDrift`: a stream's head disagrees with its events or snapshot. Never retried.
+ * - `commitTooLarge`: the commit is over the transaction budget. Nothing was written.
+ * - `compactionUncovered`: no snapshot covers the events compaction was asked to delete.
+ * - `reservedEntityId`: a write to an entity ID in a namespace only the engine writes.
+ * - `replay`: a stored event failed to upcast or decode while an aggregate loaded.
+ * - `snapshot`: a stored snapshot failed to decode while an aggregate loaded.
+ */
+export type EvtErrorCode = 'invalidJson' | 'invalidRecord' | 'invalidArgument' | 'invalidCommit' | 'conflict' | 'sequenceGap' | 'streamHeadDrift' | 'commitTooLarge' | 'compactionUncovered' | 'reservedEntityId' | 'replay' | 'snapshot';
+export declare class EvtError extends Error {
+    readonly name: string;
+    readonly code: EvtErrorCode;
+    constructor(code: EvtErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Optimistic concurrency failed on a written stream: its sequence or snapshot moved. */
+export declare class ConflictError extends EvtError {
+    readonly name = "ConflictError";
+    readonly code = "conflict";
+    readonly entityId: string;
+    constructor(entityId: string, detail: string);
+}
+/** A commit's first event skips past the stream's head, or a load found a hole. A conflict. */
+export declare class SequenceGapError extends EvtError {
+    readonly name = "SequenceGapError";
+    readonly code = "sequenceGap";
+    readonly entityId: string;
+    /** The last sequence before the gap. */
+    readonly after: bigint;
+    /** The sequence found next, which isn't `after + 1`. */
+    readonly found: bigint;
+    constructor(entityId: string, after: bigint, found: bigint);
+}
+/**
+ * A stream's head disagrees with its events or snapshot (ADR 0007): a writer appended without
+ * raising the head, events were deleted, a snapshot is ahead of the head, or a stream has data and
+ * no head. It isn't retryable: running the command again fails the same way. Repair is offline.
+ */
+export declare class StreamHeadDriftError extends EvtError {
+    readonly name = "StreamHeadDriftError";
+    readonly code = "streamHeadDrift";
+    readonly entityId: string;
+    /** The stored head, or null when the stream has no head. */
+    readonly stored: bigint | null;
+    /** The head its events and snapshot imply: the higher of the two. */
+    readonly derived: bigint;
+    constructor(entityId: string, stored: bigint | null, derived: bigint);
+}
+/** The commit is over the transaction budget: too many actions, bytes, or bytes in one item. */
+export declare class CommitTooLargeError extends EvtError {
+    readonly name = "CommitTooLargeError";
+    readonly code = "commitTooLarge";
+    readonly actions: number;
+    readonly bytes: number;
+    readonly largestItem: number;
+    constructor(actions: number, bytes: number, largestItem: number);
+}
+/** Compaction was refused because no snapshot covers the events it would delete. */
+export declare class CompactionUncoveredError extends EvtError {
+    readonly name = "CompactionUncoveredError";
+    readonly code = "compactionUncovered";
+    readonly entityId: string;
+    readonly through: bigint;
+    /** The event sequence the stored snapshot covers, or null with no snapshot. */
+    readonly covered: bigint | null;
+    constructor(entityId: string, through: bigint, covered: bigint | null);
+}
+/** A write to an entity ID in a reserved namespace (`SYSTEM#`, `command-outcome#`). */
+export declare class ReservedEntityIdError extends EvtError {
+    readonly name = "ReservedEntityIdError";
+    readonly code = "reservedEntityId";
+    readonly entityId: string;
+    constructor(entityId: string);
+}
+/** A load failed closed on a stored event: an upcaster threw, or the payload didn't decode. */
+export declare class ReplayError extends EvtError {
+    readonly name = "ReplayError";
+    readonly code = "replay";
+    readonly eventType: string;
+    /** The stored version, or the version an earlier upcaster produced. */
+    readonly version: number;
+    readonly phase: 'upcast' | 'decode';
+    constructor(eventType: string, version: number, phase: 'upcast' | 'decode', detail: string, cause?: unknown);
+}
+/** A load found a stored snapshot whose payload the aggregate's state codec doesn't decode. */
+export declare class SnapshotError extends EvtError {
+    readonly name = "SnapshotError";
+    readonly code = "snapshot";
+    readonly entityId: string;
+    constructor(entityId: string, cause: unknown);
+}
+/** Whether an error is an optimistic-concurrency conflict: a `conflict` or a `sequenceGap`. */
+export declare function isConflict(error: unknown): boolean;
+/** Whether reloading and running the command again may succeed. So far, only after a conflict. */
+export declare function isRetryable(error: unknown): boolean;
+/** An error's message, or the value itself as text. */
+export declare function messageOf(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -0,0 +1,139 @@
+// Every failure evt throws is an EvtError with a code, as the Rust crate returns its Error enum.
+// Domain outcomes (a rejected command, a duplicate) are values, never errors. A failure with
+// details has its own subclass, so `instanceof` narrows to its fields.
+export class EvtError extends Error {
+    name = 'EvtError';
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/** Optimistic concurrency failed on a written stream: its sequence or snapshot moved. */
+export class ConflictError extends EvtError {
+    name = 'ConflictError';
+    code = 'conflict';
+    entityId;
+    constructor(entityId, detail) {
+        super('conflict', `conflict on entity ${entityId}: ${detail}`);
+        this.entityId = entityId;
+    }
+}
+/** A commit's first event skips past the stream's head, or a load found a hole. A conflict. */
+export class SequenceGapError extends EvtError {
+    name = 'SequenceGapError';
+    code = 'sequenceGap';
+    entityId;
+    /** The last sequence before the gap. */
+    after;
+    /** The sequence found next, which isn't `after + 1`. */
+    found;
+    constructor(entityId, after, found) {
+        super('sequenceGap', `conflict on entity ${entityId}: the stream skips from sequence ${after} to ${found}: it ` +
+            'was compacted during the load, or events expired');
+        this.entityId = entityId;
+        this.after = after;
+        this.found = found;
+    }
+}
+/**
+ * A stream's head disagrees with its events or snapshot (ADR 0007): a writer appended without
+ * raising the head, events were deleted, a snapshot is ahead of the head, or a stream has data and
+ * no head. It isn't retryable: running the command again fails the same way. Repair is offline.
+ */
+export class StreamHeadDriftError extends EvtError {
+    name = 'StreamHeadDriftError';
+    code = 'streamHeadDrift';
+    entityId;
+    /** The stored head, or null when the stream has no head. */
+    stored;
+    /** The head its events and snapshot imply: the higher of the two. */
+    derived;
+    constructor(entityId, stored, derived) {
+        super('streamHeadDrift', `stream head drift on entity ${entityId}: stored head ${stored ?? 'absent'}, ` +
+            `derived head ${derived}`);
+        this.entityId = entityId;
+        this.stored = stored;
+        this.derived = derived;
+    }
+}
+/** The commit is over the transaction budget: too many actions, bytes, or bytes in one item. */
+export class CommitTooLargeError extends EvtError {
+    name = 'CommitTooLargeError';
+    code = 'commitTooLarge';
+    actions;
+    bytes;
+    largestItem;
+    constructor(actions, bytes, largestItem) {
+        super('commitTooLarge', `commit exceeds transaction budget: ${actions} actions, ${bytes} bytes, ` +
+            `largest item ${largestItem}`);
+        this.actions = actions;
+        this.bytes = bytes;
+        this.largestItem = largestItem;
+    }
+}
+/** Compaction was refused because no snapshot covers the events it would delete. */
+export class CompactionUncoveredError extends EvtError {
+    name = 'CompactionUncoveredError';
+    code = 'compactionUncovered';
+    entityId;
+    through;
+    /** The event sequence the stored snapshot covers, or null with no snapshot. */
+    covered;
+    constructor(entityId, through, covered) {
+        super('compactionUncovered', 'compaction refused: no durable snapshot covers the requested range ' +
+            `(entity ${entityId}, through ${through}, snapshot covers ${covered ?? 'nothing'})`);
+        this.entityId = entityId;
+        this.through = through;
+        this.covered = covered;
+    }
+}
+/** A write to an entity ID in a reserved namespace (`SYSTEM#`, `command-outcome#`). */
+export class ReservedEntityIdError extends EvtError {
+    name = 'ReservedEntityIdError';
+    code = 'reservedEntityId';
+    entityId;
+    constructor(entityId) {
+        super('reservedEntityId', `entity ID ${entityId} is in a reserved namespace (SYSTEM#, command-outcome#)`);
+        this.entityId = entityId;
+    }
+}
+/** A load failed closed on a stored event: an upcaster threw, or the payload didn't decode. */
+export class ReplayError extends EvtError {
+    name = 'ReplayError';
+    code = 'replay';
+    eventType;
+    /** The stored version, or the version an earlier upcaster produced. */
+    version;
+    phase;
+    constructor(eventType, version, phase, detail, cause) {
+        const doing = phase === 'upcast' ? 'upcasting' : 'decoding';
+        super('replay', `replay failed while ${doing} ${eventType} v${version}: ${detail}`, { cause });
+        this.eventType = eventType;
+        this.version = version;
+        this.phase = phase;
+    }
+}
+/** A load found a stored snapshot whose payload the aggregate's state codec doesn't decode. */
+export class SnapshotError extends EvtError {
+    name = 'SnapshotError';
+    code = 'snapshot';
+    entityId;
+    constructor(entityId, cause) {
+        super('snapshot', `decoding snapshot for entity ${entityId}: ${messageOf(cause)}`, { cause });
+        this.entityId = entityId;
+    }
+}
+/** Whether an error is an optimistic-concurrency conflict: a `conflict` or a `sequenceGap`. */
+export function isConflict(error) {
+    return error instanceof EvtError && (error.code === 'conflict' || error.code === 'sequenceGap');
+}
+/** Whether reloading and running the command again may succeed. So far, only after a conflict. */
+export function isRetryable(error) {
+    return isConflict(error);
+}
+/** An error's message, or the value itself as text. */
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/event.d.ts

@@ -0,0 +1,47 @@
+import { type JsonObject } from './fields.js';
+import { type Metadata } from './metadata.js';
+/** An event as it is stored. Its JSON is the `detail` of a stream envelope. */
+export interface SerializedEvent {
+    /** `{entityId}:{sequence}`. */
+    id: string;
+    /** The 1-based position of the event in its stream. */
+    sequence: bigint;
+    /** The event kind, such as `account:opened`. */
+    type: string;
+    /** The payload's schema version. */
+    version: number;
+    /** The stream the event belongs to. */
+    entityId: string;
+    /** The aggregate type of the entity. */
+    entityType: string;
+    /**
+     * The payload bytes, stored verbatim. Null only when decoded from a JSON `null`, which is
+     * written back as `null`, as Go does.
+     */
+    payload: Uint8Array | null;
+    metadata: Metadata;
+}
+/** A snapshot of aggregate state. A stream keeps at most one, its latest. */
+export interface SerializedSnapshot {
+    entityType: string;
+    entityId: string;
+    /** 1 for an entity's first snapshot, then one more for each. */
+    sequence: bigint;
+    /** The last event sequence folded into the snapshot. */
+    eventSequence: bigint;
+    /** The state's bytes, stored verbatim. Null only when decoded from a JSON `null`. */
+    payload: Uint8Array | null;
+}
+/** The event ID for a sequence of a stream: `{entityId}:{sequence}`. */
+export declare function eventId(entityId: string, sequence: bigint): string;
+/** Encodes an event as the JSON Go writes for it. */
+export declare function encodeEvent(event: SerializedEvent): string;
+/** Decodes an event's JSON leniently, as Go does. */
+export declare function decodeEvent(json: string): SerializedEvent;
+/** Encodes a snapshot as the JSON Go writes for it. Its entity ID key is `entityID`. */
+export declare function encodeSnapshot(snapshot: SerializedSnapshot): string;
+/** Decodes a snapshot's JSON leniently, as Go does. */
+export declare function decodeSnapshot(json: string): SerializedSnapshot;
+export declare function eventJson(event: SerializedEvent): object;
+export declare function eventFromJson(value: JsonObject | null): SerializedEvent;
+//# sourceMappingURL=event.d.ts.map

package/dist/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAGA,OAAO,EASL,KAAK,UAAU,EAChB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAC,KAAK,QAAQ,EAAiC,MAAM,eAAe,CAAA;AAE3E,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAA;IAChB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAA;IACf,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,OAAO,EAAE,UAAU,GAAG,IAAI,CAAA;IAC1B,QAAQ,EAAE,QAAQ,CAAA;CACnB;AAED,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAA;IAChB,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAA;IACrB,qFAAqF;IACrF,OAAO,EAAE,UAAU,GAAG,IAAI,CAAA;CAC3B;AAED,wEAAwE;AACxE,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAE1D;AAED,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAEzD;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CAQnE;AAED,uDAAuD;AACvD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAU/D;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAWxD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,eAAe,CAavE"}

package/dist/event.js

@@ -0,0 +1,64 @@
+// Serialized events and snapshots: the stored form every repository reads and writes, and their
+// JSON encodings, which match Go's evt.SerializedEvent and evt.SerializedSnapshot.
+import { DOCUMENT, bytesField, int64Argument, int64Field, objectOrNull, safeIntegerArgument, safeIntegerField, stringField, } from './fields.js';
+import { parseJson, stringifyJson } from './json.js';
+import { metadataFromJson, metadataJson } from './metadata.js';
+/** The event ID for a sequence of a stream: `{entityId}:{sequence}`. */
+export function eventId(entityId, sequence) {
+    return `${entityId}:${sequence}`;
+}
+/** Encodes an event as the JSON Go writes for it. */
+export function encodeEvent(event) {
+    return stringifyJson(eventJson(event));
+}
+/** Decodes an event's JSON leniently, as Go does. */
+export function decodeEvent(json) {
+    return eventFromJson(objectOrNull(parseJson(json, DOCUMENT), 'event'));
+}
+/** Encodes a snapshot as the JSON Go writes for it. Its entity ID key is `entityID`. */
+export function encodeSnapshot(snapshot) {
+    return stringifyJson({
+        entityType: snapshot.entityType,
+        entityID: snapshot.entityId,
+        sequence: int64Argument(snapshot.sequence, 'snapshot.sequence'),
+        eventSequence: int64Argument(snapshot.eventSequence, 'snapshot.eventSequence'),
+        payload: snapshot.payload,
+    });
+}
+/** Decodes a snapshot's JSON leniently, as Go does. */
+export function decodeSnapshot(json) {
+    const object = objectOrNull(parseJson(json, DOCUMENT), 'snapshot') ?? new Map();
+    return {
+        entityType: stringField(object, 'entityType', 'snapshot'),
+        entityId: stringField(object, 'entityID', 'snapshot'),
+        sequence: int64Field(object, 'sequence', 'snapshot'),
+        eventSequence: int64Field(object, 'eventSequence', 'snapshot'),
+        payload: bytesField(object, 'payload', 'snapshot'),
+    };
+}
+export function eventJson(event) {
+    return {
+        id: event.id,
+        sequence: int64Argument(event.sequence, 'event.sequence'),
+        type: event.type,
+        version: safeIntegerArgument(event.version, 'event.version'),
+        entityId: event.entityId,
+        entityType: event.entityType,
+        payload: event.payload,
+        metadata: metadataJson(event.metadata),
+    };
+}
+export function eventFromJson(value) {
+    const object = value ?? new Map();
+    return {
+        id: stringField(object, 'id', 'event'),
+        sequence: int64Field(object, 'sequence', 'event'),
+        type: stringField(object, 'type', 'event'),
+        version: safeIntegerField(object, 'version', 'event'),
+        entityId: stringField(object, 'entityId', 'event'),
+        entityType: stringField(object, 'entityType', 'event'),
+        payload: bytesField(object, 'payload', 'event'),
+        metadata: metadataFromJson(object.get('metadata')),
+    };
+}
+//# sourceMappingURL=event.js.map

package/dist/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"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"}

package/dist/fields.d.ts

@@ -0,0 +1,31 @@
+import { EvtError } from './errors.js';
+import { type JsonValue, type ParseOptions } from './json.js';
+export type JsonObject = Map<string, JsonValue>;
+/** How evt parses its own documents: a repeated key is refused. */
+export declare const DOCUMENT: ParseOptions;
+export declare function invalid(message: string): EvtError;
+/** An object, or null for JSON null. */
+export declare function objectOrNull(value: JsonValue | undefined, what: string): JsonObject | null;
+/** A string field, `""` when missing or null. */
+export declare function stringField(object: JsonObject, name: string, what: string): string;
+/** A string field that may be null (a Go `*string`). */
+export declare function nullableString(object: JsonObject, name: string, what: string): string | null;
+/** An int64 field, `0n` when missing or null. `1.0`, `1e3` and `"1"` are refused, as in Go. */
+export declare function int64Field(object: JsonObject, name: string, what: string): bigint;
+/** A small integer field, `0` when missing or null, refused if it isn't a safe integer. */
+export declare function safeIntegerField(object: JsonObject, name: string, what: string): number;
+/** Reads a JSON number as an int64. */
+export declare function int64(value: JsonValue, what: string): bigint;
+/** Refuses an integer outside int64. */
+export declare function checkInt64(value: bigint, what: string): bigint;
+/** Refuses to write an integer that no reader would read back as an int64. */
+export declare function int64Argument(value: bigint, what: string): bigint;
+/** Refuses to write a small integer that isn't a safe integer, such as 1.5 or NaN. */
+export declare function safeIntegerArgument(value: number, what: string): number;
+/** A base64 field (a Go `[]byte`), null when missing or null. */
+export declare function bytesField(object: JsonObject, name: string, what: string): Uint8Array | null;
+/**
+ * A Go `map[string]string`: null for a missing or null map, and `""` for a null value.
+ */
+export declare function stringMap(value: JsonValue | undefined, what: string): Map<string, string> | null;
+//# sourceMappingURL=fields.d.ts.map

package/dist/fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAKA,OAAO,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAA;AACpC,OAAO,EAAa,KAAK,SAAS,EAAE,KAAK,YAAY,EAAC,MAAM,WAAW,CAAA;AAEvE,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;AAM/C,mEAAmE;AACnE,eAAO,MAAM,QAAQ,EAAE,YAAwC,CAAA;AAE/D,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAEjD;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAS1F;AAED,iDAAiD;AACjD,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAElF;AAED,wDAAwD;AACxD,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU5F;AAED,+FAA+F;AAC/F,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOjF;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvF;AAED,uCAAuC;AACvC,wBAAgB,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM5D;AAED,wCAAwC;AACxC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMjE;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAMvE;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAI5F;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAgBhG"}

package/dist/fields.js

@@ -0,0 +1,105 @@
+// Lenient decoding of engine documents by Go's rules: a missing field or null is the zero value,
+// unknown fields are ignored, and a value of the wrong JSON type is an error. Field names match
+// exactly, as in Rust (Go also matches them case-insensitively).
+import { base64Decode } from './base64.js';
+import { EvtError } from './errors.js';
+import { JsonNumber } from './json.js';
+const INT64_MIN = -(2n ** 63n);
+const INT64_MAX = 2n ** 63n - 1n;
+/** How evt parses its own documents: a repeated key is refused. */
+export const DOCUMENT = { duplicateKeys: 'refuse' };
+export function invalid(message) {
+    return new EvtError('invalidRecord', message);
+}
+/** An object, or null for JSON null. */
+export function objectOrNull(value, what) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (!(value instanceof Map)) {
+        throw invalid(`${what} is not an object`);
+    }
+    return value;
+}
+/** A string field, `""` when missing or null. */
+export function stringField(object, name, what) {
+    return nullableString(object, name, what) ?? '';
+}
+/** A string field that may be null (a Go `*string`). */
+export function nullableString(object, name, what) {
+    const value = object.get(name);
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== 'string') {
+        throw invalid(`${what}.${name} is not a string`);
+    }
+    return value;
+}
+/** An int64 field, `0n` when missing or null. `1.0`, `1e3` and `"1"` are refused, as in Go. */
+export function int64Field(object, name, what) {
+    const value = object.get(name);
+    if (value === undefined || value === null) {
+        return 0n;
+    }
+    return int64(value, `${what}.${name}`);
+}
+/** A small integer field, `0` when missing or null, refused if it isn't a safe integer. */
+export function safeIntegerField(object, name, what) {
+    const value = int64Field(object, name, what);
+    if (value < BigInt(Number.MIN_SAFE_INTEGER) || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw invalid(`${what}.${name} is ${value}, past the integers this field holds`);
+    }
+    return Number(value);
+}
+/** Reads a JSON number as an int64. */
+export function int64(value, what) {
+    if (!(value instanceof JsonNumber) || !value.isInteger) {
+        throw invalid(`${what} is not an integer`);
+    }
+    return checkInt64(BigInt(value.text), what);
+}
+/** Refuses an integer outside int64. */
+export function checkInt64(value, what) {
+    if (value < INT64_MIN || value > INT64_MAX) {
+        throw invalid(`${what} is ${value}, outside int64`);
+    }
+    return value;
+}
+/** Refuses to write an integer that no reader would read back as an int64. */
+export function int64Argument(value, what) {
+    if (value < INT64_MIN || value > INT64_MAX) {
+        throw new EvtError('invalidArgument', `${what} is ${value}, outside int64`);
+    }
+    return value;
+}
+/** Refuses to write a small integer that isn't a safe integer, such as 1.5 or NaN. */
+export function safeIntegerArgument(value, what) {
+    if (!Number.isSafeInteger(value)) {
+        throw new EvtError('invalidArgument', `${what} is ${value}, not a safe integer`);
+    }
+    return value;
+}
+/** A base64 field (a Go `[]byte`), null when missing or null. */
+export function bytesField(object, name, what) {
+    const text = nullableString(object, name, what);
+    return text === null ? null : base64Decode(text);
+}
+/**
+ * A Go `map[string]string`: null for a missing or null map, and `""` for a null value.
+ */
+export function stringMap(value, what) {
+    const object = objectOrNull(value, what);
+    if (object === null) {
+        return null;
+    }
+    const map = new Map();
+    for (const [key, entry] of object) {
+        if (entry !== null && typeof entry !== 'string') {
+            throw invalid(`${what}.${key} is not a string`);
+        }
+        map.set(key, entry ?? '');
+    }
+    return map;
+}
+//# sourceMappingURL=fields.js.map

package/dist/fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fields.js","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { type Aggregate, type AggregateDefinition, type Decision, type EventDefinition, type EventDefinitions, type EventOf, type Rejection, type Upcaster, defineAggregate, defineEvents, jsonUpcaster, } from './aggregate.js';
+export { base64Decode, base64Encode } from './base64.js';
+export { type Codec, type JsonOptions, type StandardResult, type StandardSchemaV1, json, } from './codec.js';
+export { encodeEnvelope, decodeEnvelope, messageAttributes } from './envelope.js';
+export { CommitTooLargeError, CompactionUncoveredError, ConflictError, EvtError, type EvtErrorCode, ReplayError, ReservedEntityIdError, SequenceGapError, SnapshotError, StreamHeadDriftError, isConflict, isRetryable, } from './errors.js';
+export { type SerializedEvent, type SerializedSnapshot, decodeEvent, decodeSnapshot, encodeEvent, encodeSnapshot, eventId, } from './event.js';
+export { JsonNumber, type JsonValue, parseJson, stringifyJson } from './json.js';
+export { type Metadata, type Origin, decodeMetadata, effectiveCausationId, emptyMetadata, encodeMetadata, } from './metadata.js';
+export type { CallOptions, Commit, NewSnapshot, Repository } from './repository.js';
+export { DEFAULT_RETRY_POLICY, type RetryPolicy, retryDelay, } from './retry.js';
+export { MAX_COMMIT_ITEM_BYTES, snapshotCommitSize, snapshotEventsDue } from './snapshots.js';
+export { compareUtf8, utf8Length } from './utf8.js';
+export { DEFAULT_SNAPSHOT_INTERVAL, type ExecuteOptions, type ExecuteResult, type Loaded, type RetryOptions, Store, type StoreOptions, } from './store.js';
+//# sourceMappingURL=index.d.ts.map