effect-dynamodb 1.32.0 → 1.34.0

package/dist/Entity.js

@@ -18,6 +18,7 @@ import { normalizeGsiConfig } from "@effect-dynamodb/schema/KeyComposer.js";
 import { deriveSourceText } from "@effect-dynamodb/schema/VectorIndex.js";
 import { Cause, Context, Crypto, Data, DateTime, Effect, Equal, Option, Schema, Stream, } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
+import { attributeValueEquals } from "./internal/AttributeValueEquals.js";
 import { isBoundOp, makeBoundAppend, makeBoundDelete, makeBoundGet, makeBoundPut, makeBoundUpdate, } from "./internal/BoundCrud.js";
 import { BoundQueryImpl, entityNaming, } from "./internal/BoundQuery.js";
 import { compileExpr, createConditionOps, emptyPartProblem, isExpr, nonEmptyCondition, parseShorthand, parseSimpleShorthand, toExpr, } from "./internal/Expr.js";
@@ -26,6 +27,7 @@ import { BASE_DELAY_MS, MAX_RETRIES } from "./internal/Hydrate.js";
 import { decodeImage, imageEntityType, ownRowsRawRow, packAttributeValueSync, packedExprRefusal, packedProjectionRefusal, packItemSync, unpackRow, withRegistry, } from "./internal/Packed.js";
 import { compilePath, createPathBuilder } from "./internal/PathBuilder.js";
 import { freshIncarnationToken, generateTimestampPrimitive, INCARNATION_TOKEN, isProjectionTombstone, overTombstone, UNSENTINELED_DEFAULTS, } from "./internal/TransactableOps.js";
+import { planWrite } from "./internal/TransactPlan.js";
 import { batchEntries, diagnosedValidationError, diagnoseFailure, keyAttributesOf, targetsFor, transactItemTarget, } from "./internal/WriteDiagnosis.js";
 import { decodeSparseFields, encodeSparseFields, fromAttributeMap, toAttributeMap, toAttributeValue, } from "./Marshaller.js";
 import * as Query from "./Query.js";
@@ -138,46 +140,6 @@ class MissingForCreate extends Data.TaggedError("MissingForCreate") {
 }
 /** @internal Re-exported for tests: what DynamoDB counts against an expression's 300 operators. */
 export { countOperators };
-const bytesKey = (bytes) => Array.from(bytes).join(",");
-/** Structural equality of two marshalled values (sets compare as sets). */
-const attributeValueEquals = (a, b) => {
-    if (a === undefined || b === undefined)
-        return a === b;
-    const [kind] = Object.keys(a);
-    if (kind === undefined || Object.keys(b)[0] !== kind)
-        return false;
-    const x = a[kind];
-    const y = b[kind];
-    switch (kind) {
-        case "L": {
-            const xs = x;
-            const ys = y;
-            return xs.length === ys.length && xs.every((v, i) => attributeValueEquals(v, ys[i]));
-        }
-        case "M": {
-            const xm = x;
-            const ym = y;
-            const keys = Object.keys(xm);
-            return (keys.length === Object.keys(ym).length &&
-                keys.every((k) => attributeValueEquals(xm[k], ym[k])));
-        }
-        case "SS":
-        case "NS": {
-            const xs = new Set(x);
-            const ys = y;
-            return xs.size === new Set(ys).size && ys.every((v) => xs.has(v));
-        }
-        case "B":
-            return bytesKey(x) === bytesKey(y);
-        case "BS": {
-            const xs = new Set(x.map(bytesKey));
-            const ys = y.map(bytesKey);
-            return xs.size === new Set(ys).size && ys.every((v) => xs.has(v));
-        }
-        default:
-            return x === y;
-    }
-};
 /**
  * The top-level attributes an UpdateExpression writes (SET / REMOVE / ADD /
  * DELETE targets), resolved through its attribute names.
@@ -3900,22 +3862,29 @@ const makeImpl = (config, precomputedData) => {
         // stored bytes (they depend on the codec and threshold it was written
         // under): an unread write reads it and compares the unpacked JSON
         // (#147). The write still requires the item (`attribute_exists`), and
-        // no library write changes an immutable value in between.
+        // no library write changes an immutable value in between. A missing
+        // item takes the path the write's rejection would have taken — create
+        // it, or fail — without sending a write that needs the item: an op that
+        // read its row missing writes nothing that requires it, which is what
+        // `transactWrite`'s planner relies on.
         if (plainWrite && immutables.some((asserted) => asserted.packed)) {
             const stored = yield* client.getItem({
                 TableName: tableName,
                 Key: marshalledKey,
                 ConsistentRead: true,
             });
-            if (stored.Item !== undefined) {
-                const packedChange = yield* packedImmutableMismatch(immutables, stored.Item);
-                if (packedChange !== undefined) {
-                    return yield* new ValidationError({
-                        entityType,
-                        operation: "update",
-                        cause: packedChange,
-                    });
-                }
+            if (stored.Item === undefined) {
+                return yield* createsOnMissing
+                    ? new MissingForCreate({ input: uState.updates })
+                    : missingItem();
+            }
+            const packedChange = yield* packedImmutableMismatch(immutables, stored.Item);
+            if (packedChange !== undefined) {
+                return yield* new ValidationError({
+                    entityType,
+                    operation: "update",
+                    cause: packedChange,
+                });
             }
         }
         // Build UpdateExpression
@@ -4293,9 +4262,12 @@ const makeImpl = (config, precomputedData) => {
         // Sparse-map .clearMap — Get-then-Update helper. Reads the current
         // item with a consistent read to discover which `<prefix>#*` attrs
         // exist, then folds the resulting REMOVEs into this same UpdateItem.
-        // The version CAS (when configured) provides atomicity; non-versioned
-        // entities are best-effort (a concurrent writer can add a new bucket
-        // between the read and the update — that bucket survives).
+        // On a versioned entity the update is conditioned on the version that
+        // read found (`casRead`), so a writer adding a bucket in between makes
+        // it fail rather than survive the clear; a stale `expectedVersion` is
+        // refused before anything is sent. Non-versioned entities are
+        // best-effort (a concurrent writer can add a new bucket between the read
+        // and the update — that bucket survives).
         if (uState.sparseClearFields && uState.sparseClearFields.length > 0) {
             for (const field of uState.sparseClearFields) {
                 if (!hasSparseFields || !(field in sparseFields)) {
@@ -4313,6 +4285,20 @@ const makeImpl = (config, precomputedData) => {
                 ConsistentRead: true,
             });
             if (clearGetResult.Item) {
+                if (systemFields.version && casRead === undefined && retainSnapshot === undefined) {
+                    yield* checkVersion(clearGetResult.Item, "update");
+                    const clearedRaw = fromAttributeMap(clearGetResult.Item);
+                    const version = clearedRaw[systemFields.version] ?? 0;
+                    if (evExpected !== undefined && version !== evExpected) {
+                        return yield* new OptimisticLockError({
+                            entityType,
+                            key: encodedKey,
+                            expectedVersion: evExpected,
+                            actualVersion: version,
+                        });
+                    }
+                    casRead = { raw: clearGetResult.Item, version };
+                }
                 const clearItemKeys = Object.keys(clearGetResult.Item);
                 for (const field of uState.sparseClearFields) {
                     const sparse = sparseFields[field];
@@ -4556,6 +4542,220 @@ const makeImpl = (config, precomputedData) => {
         return yield* updateResult(requested.returnValues ?? "allNew", undefined, item, new Set(Object.keys(item)), mode, key);
     })));
     const update = (key) => new EntityUpdateImpl((mode, requested) => updateOrCreate(key, mode, requested), emptyUpdateState, self, key);
+    /**
+     * Run one of this entity's write ops with its write recorded instead of
+     * sent (`planWrite`), and say how to read a cancellation of what it would
+     * have written. The op is the standalone op itself, so the plan carries
+     * every read it makes, every item it writes and every guard it puts on them
+     * — see `internal/TransactPlan.ts`.
+     *
+     * The verdict follows a guarded put's (`_planPut`): a cancelled sentinel
+     * reservation is the `UniqueConstraintViolation` the standalone op reports;
+     * a cancelled main item is the caller's condition when there is one
+     * (`TransactionCancelled`); anything else is a lost race — the row changed
+     * between the read and the transaction — and `transactWrite` plans it again
+     * from a fresh read.
+     *
+     * `payload` is what the caller asked to write. With the op's own read of
+     * the row, it lets a reservation say which values it reserves.
+     */
+    const planned = (operation, key, 
+    /** The op itself — a factory, because a missing row means running it again. */
+    op, request) => Effect.gen(function* () {
+        const encodedKey = yield* encodeKey(key, `${operation}.decodeKey`);
+        const primaryKey = composePrimaryKey(encodedKey);
+        const ownKey = toAttributeMap(primaryKey);
+        const recorded = yield* planWrite(operation, op(), ownKey);
+        let { items, ownRow } = recorded;
+        // An op that wrote without reading its row relies on its write's own
+        // condition to find the row missing — a standalone `update` then
+        // creates it (or fails `ItemNotFound`), `patch` fails
+        // `ConditionalCheckFailed`. A transaction cannot follow that fallback,
+        // so the row is read here, and a missing row is answered to the op as
+        // its write would have been answered: it takes the same path.
+        if (!recorded.readOwnRow && items.length > 0) {
+            const client = yield* DynamoClient;
+            const { name: tableName } = yield* tableTag;
+            const read = yield* client.getItem({
+                TableName: tableName,
+                Key: ownKey,
+                ConsistentRead: true,
+            });
+            if (read.Item === undefined) {
+                ;
+                ({ items, ownRow } = yield* planWrite(operation, op(), ownKey, { rowMissing: true }));
+            }
+            else {
+                ownRow = read.Item;
+                // A pinned version the row no longer has is refused before sending,
+                // as the read-first paths do — not retried as if it were a race.
+                if (request.expectedVersion !== undefined && systemFields.version) {
+                    const stored = fromAttributeMap(read.Item)[systemFields.version];
+                    const actual = typeof stored === "number" ? stored : 0;
+                    if (actual !== request.expectedVersion) {
+                        return yield* new OptimisticLockError({
+                            entityType,
+                            key: encodedKey,
+                            expectedVersion: request.expectedVersion,
+                            actualVersion: actual,
+                        });
+                    }
+                }
+            }
+        }
+        const pkField = config.indexes.primary.pk.field;
+        const skField = config.indexes.primary.sk.field;
+        const isOwn = (row) => {
+            if (row === undefined)
+                return false;
+            const plain = fromAttributeMap(row);
+            return plain[pkField] === primaryKey[pkField] && plain[skField] === primaryKey[skField];
+        };
+        // What the row looks like after the write, in domain names: the main
+        // Put's item when the op writes the whole row, else the row it read
+        // overlaid with the payload.
+        const mainPut = items.find((i) => i.Put !== undefined && isOwn(i.Put.Item))?.Put?.Item;
+        const read = ownRow === undefined ? {} : toDomainView(fromAttributeMap(ownRow));
+        const after = mainPut !== undefined
+            ? toDomainView(fromAttributeMap(mainPut))
+            : { ...read, ...request.payload };
+        if (mainPut === undefined) {
+            for (const [field, delta] of Object.entries(request.deltas ?? {})) {
+                const base = read[field];
+                after[field] = (typeof base === "number" ? base : 0) + delta;
+            }
+        }
+        const sentinelPrefix = `${entityType}._unique.`;
+        const versionPrefix = DynamoSchema.composeVersionKeyPrefix(schema, entityType);
+        const roles = items.map((item) => {
+            if (isOwn(item.Put?.Item) || isOwn(item.Update?.Key) || isOwn(item.Delete?.Key)) {
+                return { _tag: "main" };
+            }
+            // A retain snapshot: in the row's partition, at a version key.
+            const putRow = item.Put?.Item === undefined ? undefined : fromAttributeMap(item.Put.Item);
+            const putSk = putRow?.[skField];
+            if (putRow !== undefined &&
+                putRow[pkField] === primaryKey[pkField] &&
+                typeof putSk === "string" &&
+                putSk.startsWith(versionPrefix)) {
+                return { _tag: "snapshot", version: storedVersionOf(item.Put?.Item) ?? 0 };
+            }
+            const tag = item.Put?.Item?.__edd_e__?.S;
+            if (item.Put === undefined ||
+                item.Put.ConditionExpression === undefined ||
+                tag === undefined ||
+                !tag.startsWith(sentinelPrefix)) {
+                return { _tag: "side" };
+            }
+            const constraintName = tag.slice(sentinelPrefix.length);
+            const constraintDef = config.unique?.[constraintName];
+            const reserved = constraintDef === undefined
+                ? undefined
+                : composeUniqueSentinel(schema, entityType, constraintName, constraintDef, after);
+            const putKey = fromAttributeMap(item.Put.Item ?? {});
+            // Only values that recompose THIS sentinel are reported — never a guess.
+            const fields = reserved !== undefined &&
+                reserved.key.pk === putKey[pkField] &&
+                reserved.key.sk === putKey[skField]
+                ? reserved.fieldsRecord
+                : {};
+            return {
+                _tag: "reserve",
+                error: new UniqueConstraintViolation({ entityType, constraint: constraintName, fields }),
+            };
+        });
+        // How a rejected main item reads, as a guarded put's does: compare the
+        // stored item the cancellation returns (`ALL_OLD`) with the row the
+        // plan was built from. Versioned: its version and incarnation.
+        // Otherwise: every attribute the main item's condition names — the
+        // op's own guard inputs are all among them, so if none changed the
+        // guard held, and only the caller's condition can have rejected it.
+        const mainItem = items[roles.findIndex((role) => role._tag === "main")];
+        const guarded = mainItem?.Update ?? mainItem?.Put ?? mainItem?.Delete;
+        const conditionAttrs = [
+            ...new Set((guarded?.ConditionExpression?.match(/#[A-Za-z0-9_]+/g) ?? []).flatMap((token) => {
+                const attr = guarded?.ExpressionAttributeNames?.[token];
+                return attr === undefined ? [] : [attr];
+            })),
+        ];
+        const readVersion = storedVersionOf(ownRow);
+        const changedFrom = (stored) => conditionAttrs.filter((attr) => !attributeValueEquals(stored[attr], ownRow?.[attr]));
+        const raced = (stored) => systemFields.version
+            ? storedVersionOf(stored) !== readVersion ||
+                (incarnationAttr !== undefined &&
+                    !attributeValueEquals(stored[incarnationAttr], ownRow?.[incarnationAttr]))
+            : changedFrom(stored).length > 0;
+        /** A lost race: the error once retries run out, as a guarded put reports it. */
+        const lostRace = (stored) => ({
+            _tag: "Retry",
+            stored,
+            error: systemFields.version
+                ? new OptimisticLockError({
+                    entityType,
+                    key: encodedKey,
+                    expectedVersion: readVersion ?? 0,
+                    actualVersion: storedVersionOf(stored) ?? -1,
+                })
+                : new ConcurrentModification({
+                    entityType,
+                    key: encodedKey,
+                    attributes: stored === undefined ? [] : changedFrom(stored).map(domainNameOf),
+                    current: Option.none(),
+                }),
+        });
+        return {
+            items,
+            // A taken unique value fails; a snapshot the row's own history
+            // already holds fails (`historyConflict`, as standalone — re-reading
+            // will not change it); the caller's own condition rejecting an
+            // unchanged row is a condition. Everything else is a race, retried —
+            // and every attempt plans again from fresh reads, so a row now
+            // missing takes the op's missing-row path and a pinned version the
+            // row no longer has fails `OptimisticLockError`, as standalone.
+            verdict: (reasons) => {
+                let main;
+                let sideFailed = false;
+                for (const [i, role] of roles.entries()) {
+                    const reason = reasons[i];
+                    if (reason?.Code !== "ConditionalCheckFailed")
+                        continue;
+                    switch (role._tag) {
+                        case "reserve":
+                            return { _tag: "Fail", error: role.error };
+                        case "snapshot":
+                            return ownRow === undefined
+                                ? lostRace(undefined)
+                                : { _tag: "Fail", error: historyConflict(role.version, operation) };
+                        case "main":
+                            main =
+                                reason.Item === undefined
+                                    ? "absent"
+                                    : reason.Item;
+                            break;
+                        case "side":
+                            sideFailed = true;
+                    }
+                }
+                if (main === undefined)
+                    return sideFailed ? lostRace(undefined) : undefined;
+                if (main === "absent")
+                    return lostRace(undefined);
+                if (raced(main) || !request.callerCondition)
+                    return lostRace(main);
+                return { _tag: "Condition" };
+            },
+        };
+    });
+    /** Compile an update for `Transaction.transactWrite` — see `_planUpdate`. */
+    const planUpdate = (key, uState) => planned("transactWrite.update", key, () => updateOrCreate(key, "native", uState), {
+        payload: (uState.updates ?? {}),
+        deltas: {
+            ...uState.add,
+            ...Object.fromEntries(Object.entries(uState.subtract ?? {}).map(([field, by]) => [field, -by])),
+        },
+        callerCondition: uState.condition !== undefined,
+        expectedVersion: uState.expectedVersion,
+    });
     // ---------------------------------------------------------------------------
     // delete operation
     // ---------------------------------------------------------------------------
@@ -4923,6 +5123,8 @@ const makeImpl = (config, precomputedData) => {
     // ---------------------------------------------------------------------------
     // deleteIfExists operation — delete + attribute_exists condition
     // ---------------------------------------------------------------------------
+    /** Compile a delete for `Transaction.transactWrite` — see `_planDelete`. */
+    const planDelete = (key, opts) => planned("transactWrite.delete", key, () => del(key)._builder({ ...opts, returnValues: undefined }), { payload: {}, callerCondition: opts.condition !== undefined });
     const deleteIfExists = (key) => {
         const op = del(key);
         return new EntityDeleteImpl(op._builder, op._entity, op._key, op._condition, op._returnValues, true);
@@ -6533,6 +6735,11 @@ const makeImpl = (config, precomputedData) => {
         _unsentineledDefaults: unsentineledDefaults,
         _planPut: planPut,
         _multiItemWriteFeatures: multiItemWriteFeatures(),
+        _planUpdate: (key, state) => planUpdate(key, state).pipe(
+        // Planning stops at the write, so only what an update raises BEFORE
+        // writing can surface; anything else is a defect (`isPlanUpdateError`).
+        Effect.catch((e) => (isPlanUpdateError(e) ? Effect.fail(e) : Effect.die(e)))),
+        _planDelete: (key, opts) => planDelete(key, opts).pipe(Effect.catch((e) => (isPlanDeleteError(e) ? Effect.fail(e) : Effect.die(e)))),
         _liveRows: liveRows,
         _attachPrototype: attachPrototype,
         _overTombstone: (tableName, item) => Effect.gen(function* () {
@@ -6867,6 +7074,28 @@ export const bind = (entity) => Effect.gen(function* () {
         scanFetch: (...combinators) => provide(Query.execute(applyQuery(entity.scan(), combinators))),
     };
 });
+const tagged = (tags) => (e) => typeof e === "object" && e !== null && "_tag" in e && tags.has(String(e._tag));
+const clientErrorTags = [
+    "DynamoError",
+    "ThrottlingError",
+    "DynamoValidationError",
+    "InternalServerError",
+    "ResourceNotFoundError",
+];
+const planDeleteErrorTags = [
+    ...clientErrorTags,
+    "ValidationError",
+    "ConditionalCheckFailed",
+    "ItemNotFound",
+    "TransactionOverflow",
+];
+const isPlanDeleteError = tagged(new Set(planDeleteErrorTags));
+const isPlanUpdateError = tagged(new Set([
+    ...planDeleteErrorTags,
+    "OptimisticLockError",
+    "RefNotFound",
+    "UniqueConstraintViolation",
+]));
 const isEntityOp = (op) => EntityOpTypeId in op;
 const isEntityDelete = (op) => EntityDeleteTypeId in op;
 /**
@@ -6919,13 +7148,15 @@ export const extractTransactable = (op) => {
             };
         }
         if (target._opType === "update") {
-            // Every multi-item path (transactions, `Batch.write`, `EventStore`
-            // additional items) refuses an update, so no guard is carried here.
+            // `Transaction.transactWrite` plans an update from its whole state
+            // (`_planUpdate`), which applies `patch`'s guard itself; every other
+            // multi-item path refuses an update.
             return {
                 opType: "update",
                 entity: target._entity,
                 key: target._key,
                 condition: target._updateState?.condition,
+                updateState: target._updateState,
             };
         }
     }
@@ -6939,6 +7170,11 @@ export const extractTransactable = (op) => {
             condition: withGuard(target._mustExist
                 ? { attributeExists: [target._entity.indexes.primary.pk.field] }
                 : undefined, target._condition),
+            deleteRequest: {
+                condition: target._condition,
+                mustExist: target._mustExist === true,
+                returnValues: target._returnValues,
+            },
         };
     }
     return undefined;