@photon-grove/evt 0.1.1 → 0.2.0

package/dist/transaction.d.ts

@@ -0,0 +1,113 @@
+import type { Aggregate, EventDefinitions, EventOf } from './aggregate.js';
+import type { SerializedEvent } from './event.js';
+import { type Metadata } from './metadata.js';
+import { type CallOptions, type TransactionalRepository } from './repository.js';
+import type { ExecuteOptions, Loaded } from './store.js';
+declare const eventTypes: unique symbol;
+/** What a transaction needs from its store. */
+export interface TransactionContext {
+    readonly repository: TransactionalRepository;
+    load<S, C, D extends EventDefinitions>(aggregate: Aggregate<S, C, D>, entityId: string, options?: CallOptions): Promise<Loaded<S>>;
+    snapshotInterval(aggregate: {
+        readonly snapshotInterval?: number | undefined;
+    }): number;
+    /** The command's metadata with what the store fills in, and the commit ID stamped. */
+    metadata(partial?: Partial<Metadata>): Metadata;
+}
+/** A fence the caller stamps on a stream the transaction doesn't read. */
+export interface CallerFence {
+    readonly entityId: string;
+    /** The stream's entity type, which a fence on a retained type is refused for. */
+    readonly entityType: string;
+    /** The head the caller observed: 0 for a stream with no events. */
+    readonly head: bigint;
+}
+/**
+ * What a transaction's commit did:
+ *
+ * - `committed`: every stream's events (possibly none) are stored, and every fence held. `events`
+ *   are the stored events in the order the commit wrote them: by entity ID bytes, then sequence.
+ * - `duplicate`: an event a read stream folded in since its latest snapshot already carries the
+ *   command ID, so nothing was written.
+ */
+export type TransactionResult = {
+    kind: 'committed';
+    events: SerializedEvent[];
+} | {
+    kind: 'duplicate';
+    commandId: string;
+};
+interface Stream {
+    readonly aggregate: Aggregate<any, any, any>;
+    readonly order: number;
+    readonly loaded: Loaded<unknown>;
+    state: unknown;
+    events: SerializedEvent[];
+}
+/**
+ * A stream read into a {@link Transaction}, typed by its aggregate. Pass it to
+ * {@link Transaction.append} to stage events for it; a read never appended to is fenced at the
+ * head it was read at.
+ */
+export declare class StreamRead<S, D extends EventDefinitions> {
+    #private;
+    readonly [eventTypes]?: D;
+    /** @internal Built by {@link Transaction.read}. */
+    constructor(stream: Stream);
+    get entityId(): string;
+    /** The state, with the events appended through this handle. */
+    get state(): S;
+    /** The sequence of the last event, with the events appended through this handle. */
+    get sequence(): bigint;
+    /** The stream as it was read. */
+    get loaded(): Loaded<S>;
+}
+/**
+ * One atomic commit across several streams. {@link read} loads streams of any aggregate types,
+ * {@link append} stages the events decided for them, {@link fence} adds a fence the caller stamped
+ * on a stream it didn't read, and {@link commit} writes everything in one repository transaction,
+ * or nothing. A stream read but never appended to adds a fence the engine filled at the head it
+ * was read at, so the commit fails with a retryable `FenceConflictError` once another writer
+ * moves it. Begin one with {@link Store.transaction}.
+ *
+ * Every staging call checks its input before it changes anything, so one that throws leaves the
+ * transaction as it was. A transaction commits once: after {@link commit}, whatever it returned
+ * or threw, every call throws `invalidCommit`. Begin a new transaction to try again.
+ */
+export declare class Transaction {
+    #private;
+    /** @internal Begun by {@link Store.transaction}. */
+    constructor(context: TransactionContext);
+    /**
+     * Loads a stream into the read set, as {@link Store.load} does, and returns its typed handle.
+     * Reading a stream the transaction already read, or is reading, throws `invalidCommit`.
+     */
+    read<S, C, D extends EventDefinitions>(aggregate: Aggregate<S, C, D>, entityId: string, options?: CallOptions): Promise<StreamRead<S, D>>;
+    /**
+     * Stages events for a stream this transaction read. They're applied to the handle's state, and
+     * appending again continues the sequence. The commit stamps their metadata, and runs the
+     * aggregate's projectors over every event appended to the stream, with its final state. A
+     * handle from another transaction throws `invalidCommit`.
+     */
+    append<S, D extends EventDefinitions>(read: StreamRead<S, D>, events: readonly EventOf<D>[]): this;
+    /**
+     * Adds a fence the caller stamped, for a stream the transaction doesn't read: the commit fails
+     * with a `FenceConflictError` once another writer moves the stream past `head`, which isn't
+     * retryable, since only the caller knows what it read. A fence on a stream the transaction reads,
+     * before or after the read, is dropped at commit: the read's own fence, or its write, holds the
+     * stream instead. A fence in a reserved namespace, at a head outside [0, 2^63 - 1), or on a
+     * stream already fenced throws, with nothing added.
+     */
+    fence(fence: CallerFence): this;
+    /**
+     * Stamps one commit ID and the command's metadata on every appended event, and commits every
+     * stream with events, a fence on every stream read without any, and the caller's fences, in one
+     * atomic repository transaction. On failure nothing is written. A command ID that an event a
+     * read stream folded in since its latest snapshot already carries is a `duplicate`, and nothing
+     * is written. Projector operations follow the streams in the order they were read. A commit
+     * while a read is still loading throws `invalidCommit`, and leaves the transaction open.
+     */
+    commit(options?: ExecuteOptions): Promise<TransactionResult>;
+}
+export {};
+//# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

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

package/dist/transaction.js

@@ -0,0 +1,207 @@
+// The Store's multi-stream transaction (ADR 0004 C1, C2): a read set of any aggregate types, the
+// events decided for some of them, and one atomic commit that fences every stream it read but
+// didn't write.
+import { EvtError } from './errors.js';
+import { emptyMetadata } from './metadata.js';
+import { checkNotReserved, } from './repository.js';
+import { commitSnapshot, copyMetadata, projectCommit, serializeEvents } from './staging.js';
+import { compareUtf8 } from './utf8.js';
+const MAX_INT64 = 2n ** 63n - 1n;
+/**
+ * A stream read into a {@link Transaction}, typed by its aggregate. Pass it to
+ * {@link Transaction.append} to stage events for it; a read never appended to is fenced at the
+ * head it was read at.
+ */
+export class StreamRead {
+    #stream;
+    /** @internal Built by {@link Transaction.read}. */
+    constructor(stream) {
+        this.#stream = stream;
+    }
+    get entityId() {
+        return this.#stream.loaded.entityId;
+    }
+    /** The state, with the events appended through this handle. */
+    get state() {
+        return this.#stream.state;
+    }
+    /** The sequence of the last event, with the events appended through this handle. */
+    get sequence() {
+        return this.#stream.loaded.sequence + BigInt(this.#stream.events.length);
+    }
+    /** The stream as it was read. */
+    get loaded() {
+        return this.#stream.loaded;
+    }
+}
+/**
+ * One atomic commit across several streams. {@link read} loads streams of any aggregate types,
+ * {@link append} stages the events decided for them, {@link fence} adds a fence the caller stamped
+ * on a stream it didn't read, and {@link commit} writes everything in one repository transaction,
+ * or nothing. A stream read but never appended to adds a fence the engine filled at the head it
+ * was read at, so the commit fails with a retryable `FenceConflictError` once another writer
+ * moves it. Begin one with {@link Store.transaction}.
+ *
+ * Every staging call checks its input before it changes anything, so one that throws leaves the
+ * transaction as it was. A transaction commits once: after {@link commit}, whatever it returned
+ * or threw, every call throws `invalidCommit`. Begin a new transaction to try again.
+ */
+export class Transaction {
+    #context;
+    #streams = new Map();
+    // Every stream read or being read, by ID, with the position of its read call.
+    #ids = new Map();
+    #fences = new Map();
+    #reads = 0;
+    #pending = 0;
+    #done = false;
+    /** @internal Begun by {@link Store.transaction}. */
+    constructor(context) {
+        this.#context = context;
+    }
+    /**
+     * Loads a stream into the read set, as {@link Store.load} does, and returns its typed handle.
+     * Reading a stream the transaction already read, or is reading, throws `invalidCommit`.
+     */
+    async read(aggregate, entityId, options = {}) {
+        this.#checkOpen();
+        if (this.#ids.has(entityId)) {
+            throw invalidCommit(`duplicate read of ${entityId}`);
+        }
+        // The ID is held while the load runs, so a concurrent read of the same stream is refused too,
+        // and the read keeps the place it was called in, whenever its load finishes.
+        const order = this.#reads++;
+        this.#ids.set(entityId, order);
+        this.#pending++;
+        let loaded;
+        try {
+            loaded = await this.#context.load(aggregate, entityId, options);
+        }
+        catch (error) {
+            this.#ids.delete(entityId);
+            throw error;
+        }
+        finally {
+            this.#pending--;
+        }
+        const stream = {
+            aggregate,
+            order,
+            loaded,
+            state: loaded.state,
+            events: [],
+        };
+        const read = new StreamRead(stream);
+        this.#streams.set(read, stream);
+        return read;
+    }
+    /**
+     * Stages events for a stream this transaction read. They're applied to the handle's state, and
+     * appending again continues the sequence. The commit stamps their metadata, and runs the
+     * aggregate's projectors over every event appended to the stream, with its final state. A
+     * handle from another transaction throws `invalidCommit`.
+     */
+    append(read, events) {
+        this.#checkOpen();
+        const stream = this.#streams.get(read);
+        if (stream === undefined) {
+            throw invalidCommit(`stream ${read.entityId} was not read by this transaction`);
+        }
+        // Serialized now, so an event the aggregate can't encode fails here, with nothing staged.
+        const after = stream.loaded.sequence + BigInt(stream.events.length);
+        const staged = serializeEvents(stream.aggregate, stream.loaded.entityId, after, stream.state, events, emptyMetadata());
+        stream.events.push(...staged.events);
+        stream.state = staged.state;
+        return this;
+    }
+    /**
+     * Adds a fence the caller stamped, for a stream the transaction doesn't read: the commit fails
+     * with a `FenceConflictError` once another writer moves the stream past `head`, which isn't
+     * retryable, since only the caller knows what it read. A fence on a stream the transaction reads,
+     * before or after the read, is dropped at commit: the read's own fence, or its write, holds the
+     * stream instead. A fence in a reserved namespace, at a head outside [0, 2^63 - 1), or on a
+     * stream already fenced throws, with nothing added.
+     */
+    fence(fence) {
+        this.#checkOpen();
+        checkNotReserved(fence.entityId);
+        if (fence.head < 0n || fence.head >= MAX_INT64 || this.#fences.has(fence.entityId)) {
+            throw invalidCommit(`invalid or duplicate fence ${fence.entityId}`);
+        }
+        this.#fences.set(fence.entityId, { ...fence });
+        return this;
+    }
+    /**
+     * Stamps one commit ID and the command's metadata on every appended event, and commits every
+     * stream with events, a fence on every stream read without any, and the caller's fences, in one
+     * atomic repository transaction. On failure nothing is written. A command ID that an event a
+     * read stream folded in since its latest snapshot already carries is a `duplicate`, and nothing
+     * is written. Projector operations follow the streams in the order they were read. A commit
+     * while a read is still loading throws `invalidCommit`, and leaves the transaction open.
+     */
+    async commit(options = {}) {
+        this.#checkOpen();
+        if (this.#pending > 0) {
+            throw invalidCommit('a read is still loading; await it before the commit');
+        }
+        this.#done = true;
+        const metadata = this.#context.metadata(options.metadata);
+        const commandId = metadata.commandId;
+        const streams = [...this.#streams.values()];
+        streams.sort((a, b) => a.order - b.order);
+        if (commandId !== null &&
+            commandId !== '' &&
+            streams.some((stream) => stream.loaded.seenCommandIds.has(commandId))) {
+            return { kind: 'duplicate', commandId };
+        }
+        const commits = [];
+        const fences = [];
+        for (const stream of streams) {
+            const { aggregate, loaded } = stream;
+            if (stream.events.length === 0) {
+                fences.push({
+                    entityId: loaded.entityId,
+                    entityType: aggregate.type,
+                    head: loaded.sequence,
+                    provenance: 'engine',
+                });
+                continue;
+            }
+            for (const event of stream.events) {
+                event.metadata = copyMetadata(metadata);
+            }
+            const interval = this.#context.snapshotInterval(aggregate);
+            const appended = stream.events.length;
+            const snapshot = commitSnapshot(aggregate, loaded.entityId, interval, loaded, appended, stream.state);
+            commits.push({
+                entityId: loaded.entityId,
+                events: stream.events,
+                snapshot,
+                projections: projectCommit(aggregate, loaded.entityId, stream.state, stream.events, snapshot),
+            });
+        }
+        // A caller's fence on a stream the transaction read is superseded by the read's own.
+        for (const fence of this.#fences.values()) {
+            if (!this.#ids.has(fence.entityId)) {
+                fences.push({ ...fence, provenance: 'caller' });
+            }
+        }
+        await this.#context.repository.commitTransaction({ streams: commits, fences }, options);
+        // Sorted apart from what the repository was given, which stays in read order.
+        const written = [...commits];
+        written.sort((a, b) => compareUtf8(a.entityId, b.entityId));
+        return {
+            kind: 'committed',
+            events: written.flatMap((commit) => commit.events),
+        };
+    }
+    #checkOpen() {
+        if (this.#done) {
+            throw invalidCommit('the transaction has committed; begin a new one');
+        }
+    }
+}
+function invalidCommit(message) {
+    return new EvtError('invalidCommit', `invalid commit: ${message}`);
+}
+//# sourceMappingURL=transaction.js.map

package/dist/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,8FAA8F;AAC9F,gBAAgB;AAGhB,OAAO,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAA;AAEpC,OAAO,EAAgB,aAAa,EAAC,MAAM,eAAe,CAAA;AAC1D,OAAO,EAKL,gBAAgB,GACjB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAC,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAC,MAAM,cAAc,CAAA;AAEzF,OAAO,EAAC,WAAW,EAAC,MAAM,WAAW,CAAA;AAErC,MAAM,SAAS,GAAG,EAAE,IAAI,GAAG,GAAG,EAAE,CAAA;AAkDhC;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACZ,OAAO,CAAQ;IAIxB,mDAAmD;IACnD,YAAY,MAAc;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAA;IACrC,CAAC;IAED,+DAA+D;IAC/D,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,KAAU,CAAA;IAChC,CAAC;IAED,oFAAoF;IACpF,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC1E,CAAC;IAED,iCAAiC;IACjC,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC,MAAmB,CAAA;IACzC,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,WAAW;IACb,QAAQ,CAAoB;IAC5B,QAAQ,GAAG,IAAI,GAAG,EAAiD,CAAA;IAC5E,8EAA8E;IACrE,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAA;IAChC,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAA;IACjD,MAAM,GAAG,CAAC,CAAA;IACV,QAAQ,GAAG,CAAC,CAAA;IACZ,KAAK,GAAG,KAAK,CAAA;IAEb,oDAAoD;IACpD,YAAY,OAA2B;QACrC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;IACzB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CACR,SAA6B,EAC7B,QAAgB,EAChB,OAAO,GAAgB,EAAE;QAEzB,IAAI,CAAC,UAAU,EAAE,CAAA;QACjB,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,MAAM,aAAa,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAA;QACtD,CAAC;QAED,8FAA8F;QAC9F,6EAA6E;QAC7E,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAA;QAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;QAC9B,IAAI,CAAC,QAAQ,EAAE,CAAA;QACf,IAAI,MAAiB,CAAA;QACrB,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;QACjE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;YAC1B,MAAM,KAAK,CAAA;QACb,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,EAAE,CAAA;QACjB,CAAC;QAED,MAAM,MAAM,GAAW;YACrB,SAAS;YACT,KAAK;YACL,MAAM;YACN,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,EAAE;SACX,CAAA;QACD,MAAM,IAAI,GAAG,IAAI,UAAU,CAAO,MAAM,CAAC,CAAA;QACzC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAA6C,EAAE,MAAM,CAAC,CAAA;QAExE,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;OAKG;IACH,MAAM,CACJ,IAAsB,EACtB,MAA6B;QAE7B,IAAI,CAAC,UAAU,EAAE,CAAA;QACjB,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAA6C,CAAC,CAAA;QAC/E,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,aAAa,CAAC,UAAU,IAAI,CAAC,QAAQ,mCAAmC,CAAC,CAAA;QACjF,CAAC;QAED,0FAA0F;QAC1F,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACnE,MAAM,MAAM,GAAG,eAAe,CAC5B,MAAM,CAAC,SAAS,EAChB,MAAM,CAAC,MAAM,CAAC,QAAQ,EACtB,KAAK,EACL,MAAM,CAAC,KAAK,EACZ,MAAM,EACN,aAAa,EAAE,CAChB,CAAA;QACD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAA;QACpC,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAA;QAE3B,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,KAAkB;QACtB,IAAI,CAAC,UAAU,EAAE,CAAA;QACjB,gBAAgB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QAChC,IAAI,KAAK,CAAC,IAAI,GAAG,EAAE,IAAI,KAAK,CAAC,IAAI,IAAI,SAAS,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YACnF,MAAM,aAAa,CAAC,8BAA8B,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAA;QACrE,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAC,GAAG,KAAK,EAAC,CAAC,CAAA;QAE5C,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,CAAC,OAAO,GAAmB,EAAE;QACvC,IAAI,CAAC,UAAU,EAAE,CAAA;QACjB,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,aAAa,CAAC,qDAAqD,CAAC,CAAA;QAC5E,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QAEjB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;QACzD,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAA;QACpC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;QAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAA;QACzC,IACE,SAAS,KAAK,IAAI;YAClB,SAAS,KAAK,EAAE;YAChB,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EACrE,CAAC;YACD,OAAO,EAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAC,CAAA;QACvC,CAAC;QAED,MAAM,OAAO,GAAa,EAAE,CAAA;QAC5B,MAAM,MAAM,GAAgB,EAAE,CAAA;QAC9B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,EAAC,SAAS,EAAE,MAAM,EAAC,GAAG,MAAM,CAAA;YAClC,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC/B,MAAM,CAAC,IAAI,CAAC;oBACV,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,UAAU,EAAE,SAAS,CAAC,IAAI;oBAC1B,IAAI,EAAE,MAAM,CAAC,QAAQ;oBACrB,UAAU,EAAE,QAAQ;iBACrB,CAAC,CAAA;gBACF,SAAQ;YACV,CAAC;YAED,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClC,KAAK,CAAC,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAA;YACzC,CAAC;YACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAA;YAC1D,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAA;YACrC,MAAM,QAAQ,GAAG,cAAc,CAC7B,SAAS,EACT,MAAM,CAAC,QAAQ,EACf,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,MAAM,CAAC,KAAK,CACb,CAAA;YACD,OAAO,CAAC,IAAI,CAAC;gBACX,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,QAAQ;gBACR,WAAW,EAAE,aAAa,CACxB,SAAS,EACT,MAAM,CAAC,QAAQ,EACf,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,MAAM,EACb,QAAQ,CACT;aACF,CAAC,CAAA;QACJ,CAAC;QAED,qFAAqF;QACrF,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACnC,MAAM,CAAC,IAAI,CAAC,EAAC,GAAG,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAC,CAAC,CAAA;YAC/C,CAAC;QACH,CAAC;QAED,MAAM,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAC,EAAE,OAAO,CAAC,CAAA;QAErF,8EAA8E;QAC9E,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAA;QAC5B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;QAE3D,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;SACnD,CAAA;IACH,CAAC;IAED,UAAU;QACR,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,aAAa,CAAC,gDAAgD,CAAC,CAAA;QACvE,CAAC;IACH,CAAC;CACF;AAED,SAAS,aAAa,CAAC,OAAe;IACpC,OAAO,IAAI,QAAQ,CAAC,eAAe,EAAE,mBAAmB,OAAO,EAAE,CAAC,CAAA;AACpE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photon-grove/evt",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Event sourcing for TypeScript, wire-compatible with the Go and Rust evt implementations.",
   "keywords": [
     "event-sourcing",
@@ -38,6 +38,10 @@
       "types": "./dist/memory/index.d.ts",
       "default": "./dist/memory/index.js"
     },
+    "./postgres": {
+      "types": "./dist/postgres/index.d.ts",
+      "default": "./dist/postgres/index.js"
+    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"

package/src/aggregate.ts

@@ -5,6 +5,7 @@ import type {Codec} from './codec.js'
 import {EvtError, ReplayError, messageOf} from './errors.js'
 import type {SerializedEvent} from './event.js'
 import {type JsonValue, parseJson, stringifyJson} from './json.js'
+import type {ProjectorGroup} from './repository.js'
 import {utf8Decode, utf8Encode} from './utf8.js'
 
 /**
@@ -103,6 +104,33 @@ export interface AggregateDefinition<S, C, D extends EventDefinitions> {
    * snapshots.
    */
   readonly snapshotInterval?: number | undefined
+  /**
+   * The projectors whose operations every commit of this type writes in the same transaction as
+   * its events, in this order, such as the DynamoDB backend's `viewProjector`.
+   */
+  readonly projectors?: readonly Projector<S>[] | undefined
+}
+
+/** What a projector sees of a commit: its entity, the state after its events, and the events. */
+export interface Projection<S> {
+  readonly entityType: string
+  readonly entityId: string
+  /** The state after the commit's events. */
+  readonly state: S
+  /** The state as the aggregate's state codec encodes it, as a snapshot stores it. */
+  readonly encodedState: Uint8Array
+  /** Copies of the commit's events, as they are stored. */
+  readonly events: readonly Readonly<SerializedEvent>[]
+}
+
+/**
+ * Builds the operations a commit writes beside its events, in the same transaction, such as a
+ * view of the entity's state. Its group names the backend that writes it. `project` returns null
+ * when the commit needs none. It runs only for a commit with events, again on every retry, and it
+ * must not fail or change the state.
+ */
+export interface Projector<S> {
+  project(projection: Projection<S>): ProjectorGroup | null
 }
 
 /** A checked aggregate type. */

package/src/dynamodb/head.ts

@@ -72,6 +72,21 @@ export function headUpdate(
   }
 }
 
+/** The condition of a fence on a stream with no head: it still has none. */
+export const FENCE_ABSENT_CONDITION = 'attribute_not_exists(head)'
+
+/** The condition of a fence on a stream with a head: it still equals the one observed. */
+export const FENCE_CONDITION = 'head = :head'
+
+/** The `ConditionCheck` a transaction fences a stream it read at `head` with. */
+export function headFence(entityId: string, head: bigint): HeadAction {
+  const check = {entityId, updateExpression: null, names: []}
+
+  return head === 0n
+    ? {...check, conditionExpression: FENCE_ABSENT_CONDITION, values: []}
+    : {...check, conditionExpression: FENCE_CONDITION, values: [[':head', head]]}
+}
+
 /**
  * An action's size in the commit budget, by the rule for any update, delete or condition check:
  * its key attributes plus its expression strings, name placeholders (the placeholder and the

package/src/dynamodb/index.ts

@@ -37,9 +37,11 @@ export {
 } from './client.js'
 export {FEATURES_PK, REBUILD_LOCK_PK, manifestFromItem, markerItem} from './marker.js'
 export {DynamoRepository, type DynamoRepositoryOptions} from './repository.js'
+export {DYNAMODB_BACKEND, transactItemSize, viewProjector} from './views.js'
 export {
   type CommitTtl,
   type SnapshotTtl,
   commitTransaction,
   snapshotTransaction,
+  transactionItems,
 } from './requests.js'