graphddb 0.8.1 → 0.9.1

package/dist/{chunk-T44OB5GU.js → chunk-HLFNCKFV.js}

@@ -17,7 +17,7 @@ import {
   normalizeTopLevelSelect,
   parseChange,
   validateInlineSnapshotSelect
-} from "./chunk-HNY2EJPV.js";
+} from "./chunk-7OCXY4R6.js";
 import {
   EXPR_VERSION,
   MARKER_ROW_ENTITY,
@@ -26,7 +26,7 @@ import {
   isScpExprConditionInput,
   isTransactionDefinition,
   isTransactionRef
-} from "./chunk-L4QRCHRQ.js";
+} from "./chunk-WOFRHRXY.js";
 import {
   BATCH_GET_MAX_KEYS,
   CONDITION_OPERATOR_KEYS,
@@ -61,7 +61,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-L2NEDS7U.js";
+} from "./chunk-GWWRXIHF.js";
 import {
   TableMapping,
   createColumnMap,
@@ -2520,7 +2520,12 @@ function renderWrite(op, key, params, contextLabel) {
     return { ...base, item: renderRecord(op.item, key, params, `${contextLabel} item`) };
   }
   if (op.operation === "update") {
-    return { ...base, changes: renderRecord(op.changes, key, params, `${contextLabel} changes`) };
+    const add = op.add !== void 0 && Object.keys(op.add).length > 0 ? renderRecord(op.add, key, params, `${contextLabel} add`) : void 0;
+    return {
+      ...base,
+      changes: renderRecord(op.changes, key, params, `${contextLabel} changes`),
+      ...add !== void 0 ? { add } : {}
+    };
   }
   return base;
 }
@@ -2534,11 +2539,34 @@ async function executeSingleWrite(w, retry) {
     return;
   }
   if (w.operation === "update") {
+    if (w.add !== void 0) {
+      const primaryOptions = { ...options ?? {}, add: w.add };
+      if (w.condition === void 0) {
+        await executeUpdate(w.modelClass, w.key, w.changes ?? {}, primaryOptions);
+        return;
+      }
+      try {
+        await executeUpdate(w.modelClass, w.key, w.changes ?? {}, primaryOptions);
+      } catch (e) {
+        if (!isConditionalCheckFailure(e)) throw e;
+        const fallbackOptions = {
+          add: w.add,
+          ...retry !== void 0 ? { retry } : {}
+        };
+        await executeUpdate(w.modelClass, w.key, {}, fallbackOptions);
+      }
+      return;
+    }
     await executeUpdate(w.modelClass, w.key, w.changes ?? {}, options);
     return;
   }
   await executeDelete(w.modelClass, w.key, options);
 }
+function isConditionalCheckFailure(e) {
+  if (e === null || typeof e !== "object") return false;
+  const name = e.name;
+  return name === "ConditionalCheckFailedException" || name === "ConditionalCheckFailed";
+}
 function renderConditionCheck(check, key, params, contextLabel) {
   const modelClass = check.entity.modelClass;
   const referencedKey = {};
@@ -4428,8 +4456,17 @@ function isConcreteLiteral(value) {
   const t = typeof value;
   return value === null || value instanceof Date || t === "string" || t === "number" || t === "boolean";
 }
-function makeFragment(intent, entity, input, use, condition) {
+function makeFragment(intent, entity, input, use, condition, add) {
   const checked = assertFaithfulInput(input ?? {}, intent, entity.name);
+  let checkedAdd;
+  if (add !== void 0 && Object.keys(add).length > 0) {
+    if (intent !== "update") {
+      throw new Error(
+        `mutation: the '${intent}' fragment on '${entity.name}' declares \`add\`, but an atomic \`ADD\` (issue #301) is only valid on an \`update\` fragment.`
+      );
+    }
+    checkedAdd = assertFaithfulInput(add, intent, entity.name);
+  }
   if (use !== void 0 && !isEntityWritesDefinition(use)) {
     throw new Error(
       `mutation: the '${intent}' fragment on '${entity.name}' was given a \`use:\` that is not an \`entityWrites(...)\` save contract. \`use:\` takes the WHOLE \`writes\` set (an \`entityWrites(...)\` value), never a single lifecycle (e.g. \`Model.writes.create\`) \u2014 the fragment's intent already selects the lifecycle.`
@@ -4441,6 +4478,7 @@ function makeFragment(intent, entity, input, use, condition) {
     intent,
     entity,
     input: checked,
+    ...checkedAdd !== void 0 ? { add: checkedAdd } : {},
     ...use !== void 0 ? { use } : {},
     ...checkedCondition !== void 0 ? { condition: checkedCondition } : {}
   };
@@ -4536,7 +4574,8 @@ function mutation(nameOrBody, maybeBody) {
     const { intent, entity } = resolveDescriptorTarget(descriptor, alias);
     const merged = mergeBindings(descriptor, intent, alias);
     const resolved = resolveAliasRefs(merged, aliasToIndex, alias);
-    return makeFragment(intent, entity, resolved, descriptor.use, descriptor.condition);
+    const add = descriptor.add !== void 0 ? resolveAliasRefs(descriptor.add, aliasToIndex, alias) : void 0;
+    return makeFragment(intent, entity, resolved, descriptor.use, descriptor.condition, add);
   });
   return { [COMMAND_PLAN_BRAND]: true, name, fragments };
 }
@@ -4680,8 +4719,16 @@ function buildCommandContract(methods) {
   const resolved = {};
   for (const [name, body] of Object.entries(methods)) {
     if (isPublicWriteDescriptor(body)) {
-      const { plan: plan2, select, condition, mode, description } = writeDescriptorToPlan(name, body);
-      resolved[name] = finalizeDescriptorCommand(name, plan2, select, condition, mode, description);
+      const { plan: plan2, select, condition, mode, batchWriteEligible, description } = writeDescriptorToPlan(name, body);
+      resolved[name] = finalizeDescriptorCommand(
+        name,
+        plan2,
+        select,
+        condition,
+        mode,
+        description,
+        batchWriteEligible
+      );
       continue;
     }
     if (isPublicCompositeDescriptor(body)) {
@@ -4771,7 +4818,7 @@ function buildPlannedCommandMethod(name, planned) {
     ...returnSelection !== void 0 ? { returnSelection } : {}
   };
 }
-function finalizeDescriptorCommand(name, plan2, select, condition, mode, description) {
+function finalizeDescriptorCommand(name, plan2, select, condition, declaredMode, description, batchWriteEligible = false) {
   const planned = {
     [PLANNED_COMMAND_BRAND]: true,
     plan: plan2,
@@ -4779,6 +4826,13 @@ function finalizeDescriptorCommand(name, plan2, select, condition, mode, descrip
     select
   };
   const built = buildPlannedCommandMethod(name, planned);
+  const promoted = built.ops !== void 0 && built.ops.length > 1 || built.conditionChecks !== void 0 || built.edgeWrites !== void 0 || built.derivedUpdates !== void 0 || built.uniqueGuards !== void 0 || built.outboxEvents !== void 0 || built.idempotencyGuard !== void 0 || built.maintainWrites !== void 0 || built.maintainOutbox !== void 0;
+  if (declaredMode === "batchWrite" && (!batchWriteEligible || promoted)) {
+    throw new Error(
+      `publishCommand: method '${name}' declares mode: 'batchWrite', but DynamoDB's BatchWriteItem carries no ConditionExpression, no Update and no composed derived effects \u2014 only an UNCONDITIONAL put/delete qualifies (an \`upsert\` or a condition-free \`remove\` with no derived effects). This method is ${!batchWriteEligible ? "conditional / not an unconditional put/delete" : "promoted to an atomic TransactWriteItems by its derived effects"}. Use mode: 'transaction' (atomic TransactWriteItems, condition-capable, \u226425) \u2014 or the transaction forEach form for atomic per-item values.`
+    );
+  }
+  const mode = declaredMode ?? (batchWriteEligible && !promoted ? "batchWrite" : "transaction");
   const builtOp = built.op;
   const op = condition !== void 0 ? { ...builtOp, condition } : builtOp;
   return {
@@ -4992,6 +5046,35 @@ function writeDescriptorToPlan(name, d) {
   const model = resolveDescriptorModel(d[intent], name);
   const keyFieldNames = Object.keys(d.key);
   const inputFieldNames = d.input !== void 0 ? Object.keys(d.input) : [];
+  const addFieldNames = d.add !== void 0 ? Object.keys(d.add) : [];
+  if (addFieldNames.length > 0) {
+    if (intent !== "update") {
+      throw new Error(
+        `publishCommand: method '${name}' declares \`add\` on a '${intent}' descriptor, but an atomic \`ADD\` (issue #301) is only valid on an \`update\` (a standalone UpdateItem). A create / upsert / remove cannot carry \`add\`.`
+      );
+    }
+    if (d.add === null || typeof d.add !== "object") {
+      throw new Error(`publishCommand: method '${name}' has a non-object \`add\`.`);
+    }
+    for (const field of addFieldNames) {
+      const v = d.add[field];
+      if (!isParam(v) || v.kind !== "number") {
+        throw new Error(
+          `publishCommand: method '${name}' binds \`add.${field}\` to a non-\`param.number()\` value. An atomic \`ADD\` delta (issue #301) is a caller \`param.number()\` \u2014 a compile-time constant or a non-numeric param is not a valid atomic increment.`
+        );
+      }
+      if (keyFieldNames.includes(field)) {
+        throw new Error(
+          `publishCommand: method '${name}' binds field '${field}' in both \`key\` and \`add\`. A primary-key field cannot be atomically incremented \u2014 it belongs in \`key\` only.`
+        );
+      }
+      if (inputFieldNames.includes(field)) {
+        throw new Error(
+          `publishCommand: method '${name}' binds field '${field}' in both \`input\` (SET) and \`add\` (ADD). A field is either overwritten (\`input\`) or atomically incremented (\`add\`), never both.`
+        );
+      }
+    }
+  }
   const plan2 = mutation(name, ($) => {
     const keyRefs = (fields) => {
       const out = {};
@@ -5009,13 +5092,17 @@ function writeDescriptorToPlan(name, d) {
     const descriptor = {
       [intent]: (() => model),
       key: keyRefs(keyFieldNames),
-      ...inputFieldNames.length > 0 ? { input: inputRefs(d.input) } : {}
+      ...inputFieldNames.length > 0 ? { input: inputRefs(d.input) } : {},
+      // #301: `add` deltas are always `param.number()` (validated above), so each binds
+      // to a same-named `$.field` placeholder — the runtime resolves the caller delta.
+      ...addFieldNames.length > 0 ? { add: keyRefs(addFieldNames) } : {}
     };
     return { [name]: descriptor };
   });
   const select = d.result !== void 0 && d.result.select !== void 0 ? d.result.select : void 0;
   const condition = d.condition !== void 0 ? descriptorConditionRecord(d.condition, name) : void 0;
-  return { plan: plan2, select, condition, mode: d.mode ?? "transaction", description: d.description };
+  const batchWriteEligible = (intent === "upsert" || intent === "remove") && d.condition === void 0;
+  return { plan: plan2, select, condition, mode: d.mode, batchWriteEligible, description: d.description };
 }
 
 // src/spec/mutation-command.ts
@@ -5782,6 +5869,12 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenan
       if (keyFieldSet.has(field)) continue;
       changes[field] = renderInputLeaf(leaf, false, index, field, resolveEntityRef);
     }
+    const add = {};
+    if (fragment.add !== void 0) {
+      for (const [field, leaf] of Object.entries(fragment.add)) {
+        add[field] = renderInputLeaf(leaf, false, index, field, resolveEntityRef);
+      }
+    }
     op = {
       __isContractMethodOp: true,
       entity: fragment.entity,
@@ -5789,6 +5882,7 @@ function compileFragment(fragment, index = 0, resolveEntityRef = null, maintenan
       keys: wholeKeysSentinel(),
       keyFields,
       ...fragment.intent === "update" ? { changes } : {},
+      ...fragment.intent === "update" && Object.keys(add).length > 0 ? { add } : {},
       // #242: a conditioned update / remove — the write is a CAS-style gate (the
       // row must satisfy the condition or the write is rejected, not silently
       // committed). Absent → an unconditional update / remove (unchanged).