effect-dynamodb 1.31.0 → 1.32.0

package/dist/EventStore.js

@@ -11,7 +11,11 @@
  * - `commandHandler` combinator for the load-decide-fold-append cycle
  *   (snapshot-aware single-request loads, consistent loads, an optional
  *   `VersionConflict` retry policy, caller-supplied `expectedVersion`,
- *   decision-derived `additionalItems`, inline snapshots)
+ *   decision-derived `additionalItems`, inline snapshots, a caller's own
+ *   state record as the load via `loadState`)
+ * - Head proofs (`append({ headProof })`, #164): an additional item or the
+ *   inline snapshot proves the stream head in place of the version-contiguity
+ *   `ConditionCheck`
  * - Stream indexes (`makeStream({ indexes })`): sub-streams ordered by a key
  *   derived from each event, on an LSI or GSI, each projecting all of the
  *   event, all but its metadata, or only its keys — `readIndex`,
@@ -48,7 +52,7 @@ import { itemBytes, transactItemBytes } from "./internal/ItemSize.js";
 import { isMultiProjection, } from "./internal/MultiProjection.js";
 import { codecRequirements, currentRegistry, decodeImage, imageEntityType, runtimeCodecCheck, unregisteredCodecError, withRegistry, } from "./internal/Packed.js";
 import { createPathBuilder } from "./internal/PathBuilder.js";
-import { buildTransactWriteItems, GUARDED_TRANSACTION_ATTEMPTS, judgeCancellation, transactItemTarget, } from "./internal/TransactWriteOps.js";
+import { buildTransactWriteItems, GUARDED_TRANSACTION_ATTEMPTS, judgeCancellation, opConditionFailed, transactItemTarget, } from "./internal/TransactWriteOps.js";
 import { diagnosedValidationError, diagnoseFailure, mergeKeyAttributes, withCause, } from "./internal/WriteDiagnosis.js";
 import { fromAttributeMap, toAttributeMap } from "./Marshaller.js";
 import * as Query from "./Query.js";
@@ -410,6 +414,38 @@ const unverifiedSnapshotRefusal = (streamName, settings, operation) => settings
         `snapshot mode "inline" without "every" — the only mode that writes the snapshot in every ` +
         `append, so it is normally at the head. This stream's snapshot is mode "${settings.mode}"` +
         `${settings.every === undefined ? "" : ` with every: ${settings.every}`}.`;
+/**
+ * @internal `[EDD-9085]`: a snapshot head proof (`headProof: "snapshot"`) is
+ * accepted only by a stream whose snapshot is written in every append
+ * (`mode: "inline"` without `every`) — any other snapshot lags the head by
+ * design, and would fail the proof's condition. Returns the refusal message,
+ * or `undefined` when the stream accepts it.
+ */
+const snapshotProofRefusal = (streamName, settings, operation) => settings !== undefined && settings.mode === "inline" && settings.every === undefined
+    ? undefined
+    : `[EDD-9085] EventStream "${streamName}": ${operation} with headProof: "snapshot" requires ` +
+        `snapshot mode "inline" without "every" — the only mode that writes the snapshot in every ` +
+        `append, so it can prove the head. ` +
+        (settings === undefined
+            ? "This stream has no snapshot config."
+            : `This stream's snapshot is mode "${settings.mode}"` +
+                `${settings.every === undefined ? "" : ` with every: ${settings.every}`}.`);
+/**
+ * @internal Why a `headProof` is malformed — not `"snapshot"` nor
+ * `{ additionalItem: n }` with `n` a non-negative integer — or `undefined`
+ * when it is well-formed.
+ */
+const headProofShapeProblem = (headProof) => {
+    if (headProof === "snapshot")
+        return undefined;
+    const n = typeof headProof === "object" && headProof !== null
+        ? headProof.additionalItem
+        : undefined;
+    return typeof n === "number" && Number.isInteger(n) && n >= 0
+        ? undefined
+        : `headProof must be "snapshot" or { additionalItem: n } with n a non-negative integer; ` +
+            `received ${JSON.stringify(headProof) ?? String(headProof)}. Nothing was written.`;
+};
 /**
  * @internal Why an `eventTimestamps` value cannot be written for `count`
  * events — not an array, the wrong length, or an entry that is neither a
@@ -946,6 +982,20 @@ export const makeStream = (config) => {
                     }));
                 }
             }
+            // The head proof (#164) stands in for the contiguity check, so its
+            // own condition failing shares their verdict — ahead of the other
+            // additional items.
+            const proofFailed = tx.headProof === "snapshot"
+                ? failedAt(tx.snapshotIndex)
+                : tx.headProof !== undefined &&
+                    opConditionFailed(tx.additional, rawReasons, tx.headProof.additionalItem, tx.guardCount + tx.eventCount);
+            if (proofFailed) {
+                return Effect.fail(new VersionConflict({
+                    streamName: config.streamName,
+                    streamId: streamIdStr,
+                    expectedVersion: tx.expectedVersion,
+                }));
+            }
             // The additional items, attributed back to the caller OPS that
             // produced them (several items can belong to one op). Only an op's
             // own condition is `AdditionalItemConditionFailed`: a guarded put
@@ -1153,6 +1203,33 @@ export const makeStream = (config) => {
         if (snapshotState !== undefined && snapshot === undefined) {
             return yield* snapshotUnavailable("append({ snapshot })");
         }
+        // The head proof (#164), checked ahead of the no-op fast path, as the
+        // per-event options are. An index into `additionalItems` is checked by
+        // `append`, which has them (`measureAppend` does not take them).
+        const headProof = options?.headProof;
+        if (headProof !== undefined) {
+            const problem = headProofShapeProblem(headProof);
+            if (problem !== undefined) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "EventStore.append.headProof",
+                    cause: problem,
+                });
+            }
+            if (headProof === "snapshot") {
+                const refusal = snapshotProofRefusal(config.streamName, snapshotSettings, 'append({ headProof: "snapshot" })');
+                if (refusal !== undefined)
+                    return yield* Effect.die(new Error(refusal));
+                if (snapshotState === undefined) {
+                    return yield* new ValidationError({
+                        entityType: snapshotEntityType,
+                        operation: "EventStore.append.headProof",
+                        cause: 'headProof: "snapshot" requires the inline snapshot it names: pass `snapshot` ' +
+                            "with the state as of this append. Nothing was written.",
+                    });
+                }
+            }
+        }
         // Nothing at all to write — preserve the historical no-op fast path.
         // With additional items or a dedup sentinel the transaction still runs:
         // a caller who asked for a side write means it, and silently dropping it
@@ -1180,7 +1257,8 @@ export const makeStream = (config) => {
         // (#144): an append is never split — splitting would break its
         // atomicity — so one over the limit is rejected whole by DynamoDB and
         // reported as `AppendTooLarge`, with the expanded item count.
-        const needsContiguityCheck = expectedVersion > 0 && events.length > 0;
+        // A head proof (#164) proves the same thing, so it replaces the check.
+        const needsContiguityCheck = expectedVersion > 0 && events.length > 0 && headProof === undefined;
         const tableConfig = yield* config.table.Tag;
         const tableName = tableConfig.name;
         // A custom TTL attribute is only known at runtime. An index key attribute
@@ -1347,16 +1425,31 @@ export const makeStream = (config) => {
                 },
             };
         }
-        // The inline snapshot (#138): unconditional — see AppendOptions.snapshot.
-        // Packed per `snapshot.storedAs` (#147), so the transaction-size and
-        // item-size diagnosis count its stored bytes.
+        // The inline snapshot (#138): unconditional — see AppendOptions.snapshot
+        // — unless it is the head proof (#164), when it is conditioned on being
+        // at `expectedVersion`. Packed per `snapshot.storedAs` (#147), so the
+        // transaction-size and item-size diagnosis count its stored bytes.
         let snapshotPut;
         if (snapshotState !== undefined) {
+            const item = yield* buildSnapshotItem(streamId, snapshotState, expectedVersion + events.length, now, "EventStore.append.snapshot", eventPartitions);
             snapshotPut = {
-                Put: {
-                    TableName: tableName,
-                    Item: yield* buildSnapshotItem(streamId, snapshotState, expectedVersion + events.length, now, "EventStore.append.snapshot", eventPartitions),
-                },
+                Put: headProof !== "snapshot"
+                    ? { TableName: tableName, Item: item }
+                    : expectedVersion === 0
+                        ? {
+                            TableName: tableName,
+                            Item: item,
+                            ConditionExpression: "attribute_not_exists(pk)",
+                        }
+                        : {
+                            TableName: tableName,
+                            Item: item,
+                            ConditionExpression: "#asOfVersion = :expectedVersion",
+                            ExpressionAttributeNames: { "#asOfVersion": "asOfVersion" },
+                            ExpressionAttributeValues: toAttributeMap({
+                                ":expectedVersion": expectedVersion,
+                            }),
+                        },
             };
         }
         /**
@@ -1393,6 +1486,22 @@ export const makeStream = (config) => {
     const append = (streamId, events, expectedVersion, options) => Effect.gen(function* () {
         const additionalOps = options?.additionalItems ?? [];
         const idempotency = options?.idempotency;
+        const headProof = options?.headProof;
+        // The additional item a head proof names (#164) must exist — checked
+        // before anything is read, and ahead of the no-op fast path. Its shape
+        // is checked first, by `buildAppend`'s own rule.
+        const proofOp = typeof headProof === "object" && headProofShapeProblem(headProof) === undefined
+            ? headProof.additionalItem
+            : undefined;
+        if (proofOp !== undefined && proofOp >= additionalOps.length) {
+            return yield* new ValidationError({
+                entityType,
+                operation: "EventStore.append.headProof",
+                cause: `headProof names additionalItems[${proofOp}], but the append has ` +
+                    `${additionalOps.length} additional item${additionalOps.length === 1 ? "" : "s"}. ` +
+                    "Nothing was written.",
+            });
+        }
         const parts = yield* buildAppend(streamId, events, expectedVersion, options);
         if (parts === undefined)
             return { version: expectedVersion, events: [] };
@@ -1449,6 +1558,7 @@ export const makeStream = (config) => {
                 sentinelIndex,
                 snapshotIndex,
                 expectedVersion,
+                headProof,
             };
         };
         // A guarded put among the additional items reads its item; a race with
@@ -1458,6 +1568,17 @@ export const makeStream = (config) => {
             // Caller-owned items, compiled through the same builder
             // `Transaction.transactWrite` uses, so the two APIs cannot drift.
             const additional = yield* buildTransactWriteItems(additionalOps, "EventStore.append.additionalItems");
+            // An item without a condition of its own proves nothing about the
+            // head: accepting it would drop the gap protection silently.
+            if (proofOp !== undefined && !additional.conditioned.has(proofOp)) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "EventStore.append.headProof",
+                    cause: `headProof names additionalItems[${proofOp}], which carries no condition of its ` +
+                        "own: the proof must be conditioned on the stream being at expectedVersion " +
+                        "(`.condition()`, `create()` or `Transaction.check`). Nothing was written.",
+                });
+            }
             const tx = layout(additional);
             // DynamoDB's rules — one operation per item (an additional item
             // repeating an event, the contiguity check, the idempotency sentinel
@@ -2264,6 +2385,34 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
     }
     // Ignored on a stream without a snapshot config: there is no snapshot to trust.
     const unverifiedLoads = options?.verifySnapshot === false && snapshotSettings !== undefined;
+    // The head proof and a caller's load (#164), refused up front (EDD-9085)
+    // when they cannot work together or on this stream.
+    const loadState = options?.loadState;
+    const headProof = options?.headProof;
+    const refuse = (problem) => {
+        throw new Error(`[EDD-9085] EventStream "${stream.streamName}": commandHandler ${problem}`);
+    };
+    if (loadState !== undefined && typeof loadState !== "function") {
+        refuse("loadState must be a function of the stream id.");
+    }
+    if (headProof !== undefined) {
+        const problem = headProofShapeProblem(headProof);
+        if (problem !== undefined)
+            refuse(problem.replace(" Nothing was written.", ""));
+        if (headProof === "snapshot") {
+            const refusal = snapshotProofRefusal(stream.streamName, snapshotSettings, "commandHandler");
+            if (refusal !== undefined)
+                throw new Error(refusal);
+        }
+    }
+    if (loadState !== undefined && options?.verifySnapshot === false) {
+        refuse("with loadState and verifySnapshot: false — loadState replaces the stream load, so " +
+            "there is no snapshot load to leave unverified.");
+    }
+    if (loadState !== undefined && headProof === "snapshot") {
+        refuse('with loadState and headProof: "snapshot" — the handler never reads the snapshot, so ' +
+            "it cannot know the snapshot is at the head.");
+    }
     const retryPolicy = options?.retry;
     const schedule = retryPolicy === undefined
         ? undefined
@@ -2282,6 +2431,43 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
         //    replays from the beginning.
         const load = (verify) => Effect.gen(function* () {
             let state = decider.initialState;
+            // The caller's own record (#164), trusted as the head: the append's
+            // check (or the head proof) catches one that is not.
+            if (loadState !== undefined) {
+                const result = yield* loadState(streamId);
+                const refused = (cause) => new ValidationError({
+                    entityType: stream.streamName,
+                    operation: "EventStore.commandHandler.loadState",
+                    cause,
+                });
+                if (!Option.isOption(result)) {
+                    return yield* refused("loadState must return an Option of { state, version }: None for a new stream. " +
+                        "Nothing was written.");
+                }
+                if (Option.isNone(result)) {
+                    const fresh = {
+                        state,
+                        version: 0,
+                        snapshotAsOfVersion: undefined,
+                        verified: true,
+                        eventsAfterSnapshot: 0,
+                    };
+                    return fresh;
+                }
+                const record = result.value;
+                if (!Number.isInteger(record.version) || record.version < 0) {
+                    return yield* refused(`loadState returned version ${String(record.version)}: it must be a non-negative ` +
+                        "integer, the stream version the state is as of. Nothing was written.");
+                }
+                const loaded = {
+                    state: record.state,
+                    version: record.version,
+                    snapshotAsOfVersion: undefined,
+                    verified: true,
+                    eventsAfterSnapshot: 0,
+                };
+                return loaded;
+            }
             if (snapshotSettings !== undefined) {
                 const latest = (yield* stream.readLatest(streamId, verify ? readOptions : unverifiedReadOptions));
                 let snapshotAsOfVersion = 0;
@@ -2400,14 +2586,31 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
             }
             // Inline snapshots (#138) ride in the append transaction: on every
             // append, or once `every` events have accumulated since the snapshot.
+            // A `loadState` load never saw the snapshot (#164), so its cadence is
+            // an append that crosses a multiple of `every`.
             const mode = snapshotSettings?.mode ?? "after-append";
             const every = snapshotSettings?.every;
             const newVersion = baseVersion + newEvents.length;
+            const snapshotDue = (version) => every !== undefined &&
+                (loaded.snapshotAsOfVersion === undefined
+                    ? Math.floor(version / every) > Math.floor(baseVersion / every)
+                    : version - loaded.snapshotAsOfVersion >= every);
             if (snapshotSettings !== undefined &&
                 mode === "inline" &&
-                (every === undefined || newVersion - loaded.snapshotAsOfVersion >= every)) {
+                (every === undefined || snapshotDue(newVersion))) {
                 appendOptions.snapshot = next;
             }
+            // The head proof (#164). The caller's record proves it on every
+            // append; the inline snapshot only when this load found it at the
+            // head — a lagging one would fail the condition, so the check stays.
+            if (typeof headProof === "object") {
+                appendOptions.headProof = headProof;
+            }
+            else if (headProof === "snapshot" &&
+                appendOptions.snapshot !== undefined &&
+                loaded.snapshotAsOfVersion === baseVersion) {
+                appendOptions.headProof = "snapshot";
+            }
             const appended = stream.append(streamId, newEvents, baseVersion, appendOptions);
             const outcome = yield* returnAppendConflict
                 ? appended.pipe(Effect.catchIf((error) => error instanceof VersionConflict, (conflict) => Effect.succeed(conflict)))
@@ -2419,9 +2622,7 @@ const makeCommandHandlerImpl = (decider, stream, options) => {
             //    Best-effort: the events are already durable, so a snapshot-write
             //    failure must not report the command as failed. The next threshold
             //    crossing retries it.
-            if (mode === "after-append" &&
-                every !== undefined &&
-                result.version - loaded.snapshotAsOfVersion >= every) {
+            if (mode === "after-append" && snapshotDue(result.version)) {
                 yield* stream
                     .writeSnapshot(streamId, next, result.version)
                     .pipe(Effect.catchCause((cause) => Effect.logWarning(`EventStore: snapshot write failed for stream "${stream.streamName}" at version ${result.version}`, cause)));