effect-dynamodb 0.1.0

package/dist/EventStore.d.ts

@@ -0,0 +1,208 @@
+/**
+ * EventStore — Typed, Effect-native event sourcing on DynamoDB.
+ *
+ * Provides:
+ * - `Decider` type for command-event-state modeling
+ * - `makeStream` factory for creating event streams bound to a Table
+ * - Core operations: `append`, `read`, `readFrom`, `currentVersion`
+ * - `commandHandler` combinator for read-decide-append cycle
+ * - `fold` / `foldFrom` helpers for state reconstruction
+ *
+ * Built on the existing library primitives (DynamoSchema, KeyComposer, Query,
+ * DynamoClient, Marshaller).
+ */
+import { Effect, Schema } from "effect";
+import { DynamoClient, type DynamoClientError } from "./DynamoClient.js";
+import { TransactionCancelled, ValidationError, VersionConflict } from "./Errors.js";
+import * as Query from "./Query.js";
+import type { Table, TableConfig } from "./Table.js";
+/**
+ * A Decider encodes the command-event-state triad for an aggregate.
+ *
+ * - `decide` — given a command and current state, produce events (or fail with E)
+ * - `evolve` — pure left fold: apply one event to a state
+ * - `initialState` — starting state for a new aggregate
+ */
+export interface Decider<State, Command, Event, E = never> {
+    readonly decide: (command: Command, state: State) => Effect.Effect<ReadonlyArray<Event>, E>;
+    readonly evolve: (state: State, event: Event) => State;
+    readonly initialState: State;
+}
+/**
+ * A persisted event read from a stream, enriched with stream metadata.
+ */
+export interface StreamEvent<A> {
+    readonly streamId: string;
+    readonly version: number;
+    readonly eventType: string;
+    readonly data: A;
+    readonly metadata: Record<string, unknown> | undefined;
+    readonly timestamp: string;
+}
+/** Result of appending events to a stream. */
+export interface AppendResult<A> {
+    readonly version: number;
+    readonly events: ReadonlyArray<A>;
+}
+/** Result of a command handler execution. */
+export interface CommandHandlerResult<State, Event> extends AppendResult<Event> {
+    readonly state: State;
+}
+type StreamIdInput<T extends ReadonlyArray<string>> = {
+    readonly [K in T[number]]: string;
+};
+declare const EventStreamTypeId: unique symbol;
+export type EventStreamTypeId = typeof EventStreamTypeId;
+/**
+ * An EventStream is the repository for a named event stream.
+ *
+ * Created via {@link makeStream}. Operations are called directly on the stream:
+ * `MatchEvents.append(...)`, `MatchEvents.read(...)`, `MatchEvents.query.events(...)`.
+ */
+export interface EventStream<TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata> {
+    readonly [EventStreamTypeId]: EventStreamTypeId;
+    readonly streamName: string;
+    readonly eventSchema: Schema.Top;
+    readonly append: (streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: {
+        readonly metadata?: TMetadata;
+    } | undefined) => Effect.Effect<AppendResult<TEvent>, VersionConflict | DynamoClientError | ValidationError | TransactionCancelled, DynamoClient | TableConfig>;
+    readonly read: (streamId: StreamIdInput<TStreamIdFields>) => Effect.Effect<ReadonlyArray<StreamEvent<TEvent>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    readonly readFrom: (streamId: StreamIdInput<TStreamIdFields>, afterVersion: number) => Effect.Effect<ReadonlyArray<StreamEvent<TEvent>>, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    readonly currentVersion: (streamId: StreamIdInput<TStreamIdFields>) => Effect.Effect<number, DynamoClientError | ValidationError, DynamoClient | TableConfig>;
+    readonly query: {
+        readonly events: (streamId: StreamIdInput<TStreamIdFields>) => Query.Query<StreamEvent<TEvent>>;
+    };
+}
+/**
+ * Create an EventStream bound to a Table.
+ *
+ * @example
+ * ```typescript
+ * class MatchStarted extends Schema.Class<MatchStarted>("MatchStarted")({
+ *   venue: Schema.String,
+ * }) {}
+ *
+ * class InningsCompleted extends Schema.Class<InningsCompleted>("InningsCompleted")({
+ *   innings: Schema.Number,
+ *   runs: Schema.Number,
+ * }) {}
+ *
+ * const MatchEvents = EventStore.makeStream({
+ *   table: EventsTable,
+ *   streamName: "Match",
+ *   events: [MatchStarted, InningsCompleted],
+ *   streamId: { composite: ["matchId"] },
+ * })
+ * ```
+ */
+export declare const makeStream: <const TEvents extends ReadonlyArray<Schema.Top>, TTable extends Table, const TStreamName extends string, const TStreamId extends {
+    readonly composite: ReadonlyArray<string>;
+}, TMetadata extends Schema.Top | undefined = undefined>(config: {
+    readonly table: TTable;
+    readonly streamName: TStreamName;
+    readonly events: TEvents;
+    readonly streamId: TStreamId;
+    readonly metadata?: TMetadata;
+}) => EventStream<Schema.Schema.Type<TEvents[number]>, TStreamId["composite"], TMetadata extends Schema.Top ? Schema.Schema.Type<TMetadata> : undefined>;
+/**
+ * An EventStream whose operations have `DynamoClient` and `TableConfig` already
+ * resolved, so all methods return `Effect<A, E, never>`.
+ *
+ * Created via {@link bind}. Use in service layers to avoid leaking infrastructure
+ * requirements through service method signatures.
+ *
+ * @example
+ * ```typescript
+ * export class MatchEventService extends Context.Service<MatchEventService>()("MatchEventService", {
+ *   make: Effect.gen(function* () {
+ *     const stream = yield* EventStore.bind(MatchEvents)
+ *     return {
+ *       append: (matchId, events, version) => stream.append({ matchId }, events, version),
+ *       read: (matchId) => stream.read({ matchId }),
+ *     }
+ *   }),
+ * }) {}
+ * ```
+ */
+export interface BoundEventStream<TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata> {
+    readonly [EventStreamTypeId]: EventStreamTypeId;
+    readonly streamName: string;
+    readonly eventSchema: Schema.Top;
+    readonly append: (streamId: StreamIdInput<TStreamIdFields>, events: ReadonlyArray<TEvent>, expectedVersion: number, options?: {
+        readonly metadata?: TMetadata;
+    } | undefined) => Effect.Effect<AppendResult<TEvent>, VersionConflict | DynamoClientError | ValidationError | TransactionCancelled, never>;
+    readonly read: (streamId: StreamIdInput<TStreamIdFields>) => Effect.Effect<ReadonlyArray<StreamEvent<TEvent>>, DynamoClientError | ValidationError, never>;
+    readonly readFrom: (streamId: StreamIdInput<TStreamIdFields>, afterVersion: number) => Effect.Effect<ReadonlyArray<StreamEvent<TEvent>>, DynamoClientError | ValidationError, never>;
+    readonly currentVersion: (streamId: StreamIdInput<TStreamIdFields>) => Effect.Effect<number, DynamoClientError | ValidationError, never>;
+    readonly query: {
+        readonly events: (streamId: StreamIdInput<TStreamIdFields>) => Query.Query<StreamEvent<TEvent>>;
+    };
+    /** Escape hatch: provide DynamoClient | TableConfig to an arbitrary effect. */
+    readonly provide: <A, E>(effect: Effect.Effect<A, E, DynamoClient | TableConfig>) => Effect.Effect<A, E, never>;
+}
+/**
+ * Bind an EventStream to resolved `DynamoClient` and `TableConfig` services.
+ * Returns a {@link BoundEventStream} where all operations have `R = never`.
+ *
+ * Use inside `Context.Service` make effects to prevent service methods
+ * from leaking infrastructure requirements.
+ *
+ * @example
+ * ```typescript
+ * const stream = yield* EventStore.bind(MatchEvents)
+ * const events = yield* stream.read({ matchId: "m-1" })    // R = never
+ * yield* stream.append({ matchId: "m-1" }, [event], 0)     // R = never
+ * ```
+ */
+export declare const bind: <TEvent, TStreamIdFields extends ReadonlyArray<string>, TMetadata>(stream: EventStream<TEvent, TStreamIdFields, TMetadata>) => Effect.Effect<BoundEventStream<TEvent, TStreamIdFields, TMetadata>, never, DynamoClient | TableConfig>;
+type CommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata> = (streamId: StreamIdInput<TStreamIdFields>, command: Command, options?: {
+    readonly metadata?: TMetadata;
+} | undefined) => Effect.Effect<CommandHandlerResult<State, TEvent>, E | VersionConflict | DynamoClientError | ValidationError | TransactionCancelled, DynamoClient | TableConfig>;
+type BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata> = (streamId: StreamIdInput<TStreamIdFields>, command: Command, options?: {
+    readonly metadata?: TMetadata;
+} | undefined) => Effect.Effect<CommandHandlerResult<State, TEvent>, E | VersionConflict | DynamoClientError | ValidationError | TransactionCancelled, never>;
+/**
+ * Create a command handler that reads, decides, and appends atomically.
+ *
+ * Supports both data-first and data-last (pipeable) usage, and works with
+ * both `EventStream` (R = DynamoClient | TableConfig) and `BoundEventStream` (R = never).
+ *
+ * ```typescript
+ * // Data-first with EventStream
+ * const handle = EventStore.commandHandler(decider, stream)
+ *
+ * // Data-first with BoundEventStream
+ * const handle = EventStore.commandHandler(decider, boundStream)
+ *
+ * // Data-last (pipe)
+ * const handle = stream.pipe(EventStore.commandHandler(decider))
+ * ```
+ */
+export declare const commandHandler: {
+    <State, Command, TEvent, E>(decider: Decider<State, Command, TEvent, E>): {
+        <TStreamIdFields extends ReadonlyArray<string>, TMetadata>(stream: BoundEventStream<TEvent, TStreamIdFields, TMetadata>): BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata>;
+        <TStreamIdFields extends ReadonlyArray<string>, TMetadata>(stream: EventStream<TEvent, TStreamIdFields, TMetadata>): CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata>;
+    };
+    <State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata>(decider: Decider<State, Command, TEvent, E>, stream: BoundEventStream<TEvent, TStreamIdFields, TMetadata>): BoundCommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata>;
+    <State, Command, TEvent, E, TStreamIdFields extends ReadonlyArray<string>, TMetadata>(decider: Decider<State, Command, TEvent, E>, stream: EventStream<TEvent, TStreamIdFields, TMetadata>): CommandHandler<State, Command, TEvent, E, TStreamIdFields, TMetadata>;
+};
+/**
+ * Reconstruct state from events by folding through a decider's `evolve` function.
+ *
+ * Pure synchronous — no DynamoDB access.
+ */
+export declare const fold: {
+    <A>(events: ReadonlyArray<StreamEvent<A>>): <S, C, E>(decider: Decider<S, C, A, E>) => S;
+    <S, C, A, E>(decider: Decider<S, C, A, E>, events: ReadonlyArray<StreamEvent<A>>): S;
+};
+/**
+ * Fold from a starting state (e.g., snapshot + delta events).
+ *
+ * Pure synchronous — no DynamoDB access.
+ */
+export declare const foldFrom: {
+    <A>(startState: unknown, events: ReadonlyArray<StreamEvent<A>>): <S, C, E>(decider: Decider<S, C, A, E>) => S;
+    <S, C, A, E>(decider: Decider<S, C, A, E>, startState: S, events: ReadonlyArray<StreamEvent<A>>): S;
+};
+export {};
+//# sourceMappingURL=EventStore.d.ts.map

package/dist/EventStore.d.ts.map

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

package/dist/EventStore.js

@@ -0,0 +1,333 @@
+/**
+ * EventStore — Typed, Effect-native event sourcing on DynamoDB.
+ *
+ * Provides:
+ * - `Decider` type for command-event-state modeling
+ * - `makeStream` factory for creating event streams bound to a Table
+ * - Core operations: `append`, `read`, `readFrom`, `currentVersion`
+ * - `commandHandler` combinator for read-decide-append cycle
+ * - `fold` / `foldFrom` helpers for state reconstruction
+ *
+ * Built on the existing library primitives (DynamoSchema, KeyComposer, Query,
+ * DynamoClient, Marshaller).
+ */
+import { Effect, Function, Schema } from "effect";
+import { DynamoClient } from "./DynamoClient.js";
+import * as DynamoSchema from "./DynamoSchema.js";
+import { isAwsTransactionCancelled, TransactionCancelled, ValidationError, VersionConflict, } from "./Errors.js";
+import * as KeyComposer from "./KeyComposer.js";
+import { toAttributeMap } from "./Marshaller.js";
+import * as Query from "./Query.js";
+// ---------------------------------------------------------------------------
+// EventStreamTypeId
+// ---------------------------------------------------------------------------
+const EventStreamTypeId = Symbol.for("effect-dynamodb/EventStream");
+// ---------------------------------------------------------------------------
+// makeStream factory
+// ---------------------------------------------------------------------------
+/**
+ * Create an EventStream bound to a Table.
+ *
+ * @example
+ * ```typescript
+ * class MatchStarted extends Schema.Class<MatchStarted>("MatchStarted")({
+ *   venue: Schema.String,
+ * }) {}
+ *
+ * class InningsCompleted extends Schema.Class<InningsCompleted>("InningsCompleted")({
+ *   innings: Schema.Number,
+ *   runs: Schema.Number,
+ * }) {}
+ *
+ * const MatchEvents = EventStore.makeStream({
+ *   table: EventsTable,
+ *   streamName: "Match",
+ *   events: [MatchStarted, InningsCompleted],
+ *   streamId: { composite: ["matchId"] },
+ * })
+ * ```
+ */
+export const makeStream = (config) => {
+    const schema = config.table.schema;
+    const entityType = `${config.streamName.toLowerCase()}.event`;
+    const compositeFields = config.streamId.composite;
+    // Build union schema from event schemas for decoding
+    const eventUnion = config.events.length === 1
+        ? config.events[0]
+        : Schema.Union(config.events);
+    // Metadata schema (optional)
+    const metadataSchema = config.metadata;
+    // ---------------------------------------------------------------------------
+    // Key helpers
+    // ---------------------------------------------------------------------------
+    const composeStreamPk = (streamId) => {
+        const composites = KeyComposer.extractComposites(compositeFields, streamId);
+        return DynamoSchema.composeKey(schema, config.streamName.toLowerCase(), composites);
+    };
+    const composeEventSk = (version) => DynamoSchema.composeEventVersionKey(schema, entityType, version);
+    // ---------------------------------------------------------------------------
+    // Decode a raw DynamoDB item → StreamEvent<TEvent>
+    // ---------------------------------------------------------------------------
+    const decodeStreamEvent = (raw) => Effect.gen(function* () {
+        const decoder = Schema.decodeUnknownEffect(eventUnion);
+        const data = yield* decoder(raw.data).pipe(Effect.mapError((cause) => new ValidationError({
+            entityType,
+            operation: "EventStore.decode",
+            cause,
+        })));
+        return {
+            streamId: raw.streamId,
+            version: raw.version,
+            eventType: raw.eventType,
+            data,
+            metadata: raw.metadata,
+            timestamp: raw.timestamp,
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // append
+    // ---------------------------------------------------------------------------
+    const append = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
+        if (events.length === 0) {
+            return { version: expectedVersion, events: [] };
+        }
+        const client = yield* DynamoClient;
+        const { name: tableName } = yield* config.table.Tag;
+        const pk = composeStreamPk(streamId);
+        const now = new Date().toISOString();
+        // Resolve stream ID string for storage (join composites)
+        const streamIdStr = compositeFields
+            .map((f) => streamId[f])
+            .join("#");
+        // Validate and encode metadata if schema provided
+        let encodedMetadata;
+        if (options?.metadata !== undefined && metadataSchema) {
+            const validated = yield* Schema.decodeUnknownEffect(metadataSchema)(options.metadata).pipe(Effect.mapError((cause) => new ValidationError({
+                entityType,
+                operation: "EventStore.append.metadata",
+                cause,
+            })));
+            encodedMetadata = validated;
+        }
+        else if (options?.metadata !== undefined) {
+            encodedMetadata = options.metadata;
+        }
+        // Build transact items — one Put per event, each with attribute_not_exists(pk)
+        const transactItems = events.map((event, i) => {
+            const version = expectedVersion + i + 1;
+            // In Effect v4, Schema.Class instances don't have _tag as an own property.
+            // The identifier is on the constructor (class) itself.
+            const evtType = event._tag ??
+                event.constructor.identifier ??
+                event.constructor.name;
+            const eventData = { _tag: evtType, ...event };
+            const item = {
+                pk,
+                sk: composeEventSk(version),
+                __edd_e__: entityType,
+                streamId: streamIdStr,
+                version,
+                eventType: evtType,
+                data: eventData,
+                timestamp: now,
+            };
+            if (encodedMetadata !== undefined) {
+                item.metadata = encodedMetadata;
+            }
+            return {
+                Put: {
+                    TableName: tableName,
+                    Item: toAttributeMap(item),
+                    ConditionExpression: "attribute_not_exists(pk)",
+                },
+            };
+        });
+        yield* client.transactWriteItems({ TransactItems: transactItems }).pipe(Effect.mapError((error) => {
+            if (isAwsTransactionCancelled(error.cause)) {
+                const reasons = (error.cause.CancellationReasons ?? []).map((r) => ({
+                    code: r?.Code,
+                    message: r?.Message,
+                }));
+                const hasConflict = reasons.some((r) => r.code === "ConditionalCheckFailed");
+                if (hasConflict) {
+                    return new VersionConflict({
+                        streamName: config.streamName,
+                        streamId: streamIdStr,
+                        expectedVersion,
+                    });
+                }
+                return new TransactionCancelled({
+                    operation: "TransactWriteItems",
+                    reasons,
+                    cause: error.cause,
+                });
+            }
+            return error;
+        }));
+        return {
+            version: expectedVersion + events.length,
+            events,
+        };
+    });
+    // ---------------------------------------------------------------------------
+    // read
+    // ---------------------------------------------------------------------------
+    const read = (streamId) => Effect.gen(function* () {
+        const query = buildEventsQuery(streamId);
+        return yield* Query.collect(query);
+    });
+    // ---------------------------------------------------------------------------
+    // readFrom
+    // ---------------------------------------------------------------------------
+    const readFrom = (streamId, afterVersion) => Effect.gen(function* () {
+        const query = buildEventsQuery(streamId).pipe(Query.where({ gt: composeEventSk(afterVersion) }));
+        return yield* Query.collect(query);
+    });
+    // ---------------------------------------------------------------------------
+    // currentVersion
+    // ---------------------------------------------------------------------------
+    const currentVersion = (streamId) => Effect.gen(function* () {
+        const query = buildEventsQuery(streamId).pipe(Query.reverse, Query.limit(1));
+        const results = yield* Query.collect(query);
+        if (results.length === 0)
+            return 0;
+        return results[0].version;
+    });
+    // ---------------------------------------------------------------------------
+    // query.events helper
+    // ---------------------------------------------------------------------------
+    const buildEventsQuery = (streamId) => {
+        const pk = composeStreamPk(streamId);
+        return Query.make({
+            tableName: "",
+            indexName: undefined,
+            pkField: "pk",
+            pkValue: pk,
+            skField: "sk",
+            entityTypes: [entityType],
+            decoder: (raw) => decodeStreamEvent(raw),
+            resolveTableName: config.table.Tag.useSync((tc) => tc.name),
+        });
+    };
+    const queryNamespace = {
+        events: (streamId) => buildEventsQuery(streamId),
+    };
+    // ---------------------------------------------------------------------------
+    // Return EventStream
+    // ---------------------------------------------------------------------------
+    // Cast rationale: makeStream builds the stream object from closures that capture
+    // the generic config. The Table.Tag service has a dynamically-created tag whose R
+    // type parameter is opaque, causing Effect.gen to infer `unknown` for R. The cast
+    // is safe because all operations correctly require DynamoClient | TableConfig at
+    // runtime — the user must provide these layers.
+    return {
+        [EventStreamTypeId]: EventStreamTypeId,
+        streamName: config.streamName,
+        eventSchema: eventUnion,
+        append,
+        read,
+        readFrom,
+        currentVersion,
+        query: queryNamespace,
+    };
+};
+// ---------------------------------------------------------------------------
+// EventStore.bind — resolve services, return BoundEventStream with R = never
+// ---------------------------------------------------------------------------
+/**
+ * Bind an EventStream to resolved `DynamoClient` and `TableConfig` services.
+ * Returns a {@link BoundEventStream} where all operations have `R = never`.
+ *
+ * Use inside `Context.Service` make effects to prevent service methods
+ * from leaking infrastructure requirements.
+ *
+ * @example
+ * ```typescript
+ * const stream = yield* EventStore.bind(MatchEvents)
+ * const events = yield* stream.read({ matchId: "m-1" })    // R = never
+ * yield* stream.append({ matchId: "m-1" }, [event], 0)     // R = never
+ * ```
+ */
+export const bind = (stream) => Effect.gen(function* () {
+    const ctx = yield* Effect.context();
+    const provide = (effect) => Effect.provide(effect, ctx);
+    return {
+        [EventStreamTypeId]: EventStreamTypeId,
+        streamName: stream.streamName,
+        eventSchema: stream.eventSchema,
+        append: (streamId, events, expectedVersion, options) => provide(stream.append(streamId, events, expectedVersion, options)),
+        read: (streamId) => provide(stream.read(streamId)),
+        readFrom: (streamId, afterVersion) => provide(stream.readFrom(streamId, afterVersion)),
+        currentVersion: (streamId) => provide(stream.currentVersion(streamId)),
+        query: stream.query,
+        provide,
+    };
+});
+/**
+ * Create a command handler that reads, decides, and appends atomically.
+ *
+ * Supports both data-first and data-last (pipeable) usage, and works with
+ * both `EventStream` (R = DynamoClient | TableConfig) and `BoundEventStream` (R = never).
+ *
+ * ```typescript
+ * // Data-first with EventStream
+ * const handle = EventStore.commandHandler(decider, stream)
+ *
+ * // Data-first with BoundEventStream
+ * const handle = EventStore.commandHandler(decider, boundStream)
+ *
+ * // Data-last (pipe)
+ * const handle = stream.pipe(EventStore.commandHandler(decider))
+ * ```
+ */
+export const commandHandler = Function.dual(2, (decider, stream) => (streamId, command, options) => Effect.gen(function* () {
+    // 1. Read all events
+    const events = yield* stream.read(streamId);
+    // 2. Fold to current state
+    const curVersion = events.length > 0 ? events[events.length - 1].version : 0;
+    let state = decider.initialState;
+    for (const event of events) {
+        state = decider.evolve(state, event.data);
+    }
+    // 3. Decide
+    const newEvents = yield* decider.decide(command, state);
+    // 4. No-op command — return current state
+    if (newEvents.length === 0) {
+        return { state, version: curVersion, events: [] };
+    }
+    // 5. Append with optimistic concurrency
+    const result = yield* stream.append(streamId, newEvents, curVersion, options);
+    // 6. Evolve state through new events
+    for (const event of newEvents) {
+        state = decider.evolve(state, event);
+    }
+    return { state, version: result.version, events: newEvents };
+}));
+// ---------------------------------------------------------------------------
+// fold helpers
+// ---------------------------------------------------------------------------
+/**
+ * Reconstruct state from events by folding through a decider's `evolve` function.
+ *
+ * Pure synchronous — no DynamoDB access.
+ */
+export const fold = Function.dual(2, (decider, events) => {
+    let state = decider.initialState;
+    for (const event of events) {
+        state = decider.evolve(state, event.data);
+    }
+    return state;
+});
+/**
+ * Fold from a starting state (e.g., snapshot + delta events).
+ *
+ * Pure synchronous — no DynamoDB access.
+ */
+export const foldFrom = Function.dual(3, (decider, startState, events) => {
+    let state = startState;
+    for (const event of events) {
+        state = decider.evolve(state, event.data);
+    }
+    return state;
+});
+//# sourceMappingURL=EventStore.js.map

package/dist/EventStore.js.map

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

package/dist/Expression.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Expression — Type-safe builders for DynamoDB expressions.
+ *
+ * Produces expression strings with attribute name/value placeholders,
+ * matching the shape used by DynamoDB query/put/update/delete operations.
+ *
+ * Three builder types:
+ * - condition: For conditional puts/deletes (ConditionExpression)
+ * - filter: For query result filtering (FilterExpression)
+ * - update: For update operations (UpdateExpression)
+ */
+import type { AttributeValue } from "@aws-sdk/client-dynamodb";
+export interface ExpressionResult {
+    readonly expression: string;
+    readonly names: Record<string, string>;
+    readonly values: Record<string, AttributeValue>;
+}
+export interface ConditionInput {
+    readonly eq?: Record<string, unknown> | undefined;
+    readonly ne?: Record<string, unknown> | undefined;
+    readonly lt?: Record<string, unknown> | undefined;
+    readonly le?: Record<string, unknown> | undefined;
+    readonly gt?: Record<string, unknown> | undefined;
+    readonly ge?: Record<string, unknown> | undefined;
+    readonly between?: Record<string, readonly [unknown, unknown]> | undefined;
+    readonly beginsWith?: Record<string, string> | undefined;
+    readonly attributeExists?: string | ReadonlyArray<string> | undefined;
+    readonly attributeNotExists?: string | ReadonlyArray<string> | undefined;
+}
+/**
+ * Build a ConditionExpression for conditional puts/deletes.
+ * All clauses are ANDed together.
+ */
+export declare const condition: (input: ConditionInput) => ExpressionResult;
+/**
+ * Build a FilterExpression for query result filtering.
+ * Same syntax as condition expressions.
+ */
+export declare const filter: (input: ConditionInput) => ExpressionResult;
+export interface UpdateInput {
+    readonly set?: Record<string, unknown> | undefined;
+    readonly remove?: ReadonlyArray<string> | undefined;
+    readonly add?: Record<string, number> | undefined;
+    readonly delete?: Record<string, unknown> | undefined;
+}
+/**
+ * Build an UpdateExpression with SET, REMOVE, ADD, DELETE clauses.
+ */
+export declare const update: (input: UpdateInput) => ExpressionResult;
+//# sourceMappingURL=Expression.d.ts.map

package/dist/Expression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Expression.d.ts","sourceRoot":"","sources":["../src/Expression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AAK9D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CAChD;AAID,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAA;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;IACxD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IACrE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;CACzE;AAsGD;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,cAAc,KAAG,gBAAyC,CAAA;AAE3F;;;GAGG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,cAAc,KAAG,gBAAyC,CAAA;AAIxF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IACnD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;CACtD;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,WAAW,KAAG,gBA8D3C,CAAA"}