graphddb 0.2.0 → 0.2.2

package/dist/{chunk-347U24SB.js → chunk-3MI43FHU.js}

@@ -525,6 +525,51 @@ var TableMapping = class {
   }
 };
 
+// src/define/param.ts
+function makeParam(kind, literals) {
+  return literals === void 0 ? { kind } : { kind, literals };
+}
+var param = {
+  /** A placeholder for a `string` value. */
+  string() {
+    return makeParam("string");
+  },
+  /** A placeholder for a `number` value. */
+  number() {
+    return makeParam("number");
+  },
+  /**
+   * A placeholder constrained to one of the given literal values. The value
+   * type of the resulting {@link Param} is the **union of the literals**, so it
+   * is preserved precisely in the IR and the inferred definition types.
+   *
+   * @example
+   * ```ts
+   * param.literal('active', 'disabled'); // Param<'active' | 'disabled'>
+   * ```
+   */
+  literal(...values) {
+    return makeParam("literal", values);
+  },
+  /**
+   * A placeholder for an **array** parameter whose elements have the given field
+   * shape. Used by `defineTransaction`'s `tx.forEach(p.<arrayParam>, …)` to bind
+   * each element's fields to `{item.<field>}` templates.
+   *
+   * @example
+   * ```ts
+   * param.array({ userId: param.string(), role: param.string() });
+   * // Param<{ userId: string; role: string }[]>
+   * ```
+   */
+  array(element) {
+    return { kind: "array", element };
+  }
+};
+function isParam(value) {
+  return typeof value === "object" && value !== null && "kind" in value && (value.kind === "string" || value.kind === "number" || value.kind === "literal" || value.kind === "array");
+}
+
 // src/client/lib-dynamodb.ts
 var cached = null;
 async function loadLibDynamoDB() {
@@ -825,20 +870,20 @@ async function executeQuery(docClient, operation) {
   };
   for (let i = 0; i < keyEntries.length; i++) {
     const [attrName, value] = keyEntries[i];
-    const nameAlias = `#k${i}`;
-    const valueAlias = `:k${i}`;
-    exprAttrNames[nameAlias] = attrName;
-    exprAttrValues[valueAlias] = value;
-    conditionParts.push(`${nameAlias} = ${valueAlias}`);
+    const nameAlias2 = `#k${i}`;
+    const valueAlias2 = `:k${i}`;
+    exprAttrNames[nameAlias2] = attrName;
+    exprAttrValues[valueAlias2] = value;
+    conditionParts.push(`${nameAlias2} = ${valueAlias2}`);
   }
   if (operation.rangeCondition) {
     const rc = operation.rangeCondition;
     const idx = keyEntries.length;
-    const nameAlias = `#k${idx}`;
-    const valueAlias = `:k${idx}`;
-    exprAttrNames[nameAlias] = rc.key;
-    exprAttrValues[valueAlias] = rc.value;
-    conditionParts.push(`begins_with(${nameAlias}, ${valueAlias})`);
+    const nameAlias2 = `#k${idx}`;
+    const valueAlias2 = `:k${idx}`;
+    exprAttrNames[nameAlias2] = rc.key;
+    exprAttrValues[valueAlias2] = rc.value;
+    conditionParts.push(`begins_with(${nameAlias2}, ${valueAlias2})`);
   }
   const cmd = new QueryCommand({
     TableName: operation.tableName,
@@ -860,14 +905,290 @@ async function executeQuery(docClient, operation) {
   };
 }
 
+// src/select/cond.ts
+var RAW_COND = /* @__PURE__ */ Symbol.for("graphddb.rawCond");
+function isRawCondition(value) {
+  return typeof value === "object" && value !== null && value[RAW_COND] === true;
+}
+function cond(template, ...parts) {
+  return {
+    [RAW_COND]: true,
+    template,
+    parts
+  };
+}
+function compileRawCondition(raw, allocName, allocValue) {
+  let out = raw.template[0];
+  for (let i = 0; i < raw.parts.length; i++) {
+    const part = raw.parts[i];
+    if (isColumn(part)) {
+      out += allocName(part.name);
+    } else {
+      out += allocValue(part);
+    }
+    out += raw.template[i + 1];
+  }
+  return out;
+}
+function condParamName(index) {
+  return `cond_p${index}`;
+}
+function serializeRawCondition(raw, renderSlot) {
+  const names = {};
+  const values = {};
+  let valueCounter = 0;
+  let paramIndex = 0;
+  const nameAlias2 = (column) => {
+    const alias = `#cr_${column}`;
+    names[alias] = column;
+    return alias;
+  };
+  const valueAlias2 = (value) => {
+    const alias = `:cr${valueCounter++}`;
+    values[alias] = value;
+    return alias;
+  };
+  let out = raw.template[0];
+  for (let i = 0; i < raw.parts.length; i++) {
+    const part = raw.parts[i];
+    if (isColumn(part)) {
+      out += nameAlias2(part.name);
+    } else {
+      const custom = renderSlot?.(part, paramIndex);
+      if (custom !== void 0) {
+        if (isParam(part)) paramIndex++;
+        out += valueAlias2(custom);
+      } else if (isParam(part)) {
+        out += valueAlias2({ $param: condParamName(paramIndex++) });
+      } else if (part instanceof Date) {
+        out += valueAlias2(part.toISOString());
+      } else {
+        out += valueAlias2(part);
+      }
+    }
+    out += raw.template[i + 1];
+  }
+  return { expression: out, names, values };
+}
+function collectRawConditionParams(raw) {
+  const out = [];
+  let paramIndex = 0;
+  for (const part of raw.parts) {
+    if (isColumn(part)) continue;
+    if (isParam(part)) {
+      out.push({ name: condParamName(paramIndex++), param: part });
+    }
+  }
+  return out;
+}
+
 // src/expression/condition-expression.ts
+var OPERATOR_KEYS = /* @__PURE__ */ new Set([
+  "eq",
+  "ne",
+  "gt",
+  "ge",
+  "lt",
+  "le",
+  "between",
+  "in",
+  "beginsWith",
+  "contains",
+  "notContains",
+  "attributeExists",
+  "attributeType",
+  "size"
+]);
+function nameAlias(ctx, field) {
+  const alias = `#cond_${field}`;
+  ctx.names[alias] = field;
+  return alias;
+}
+function valueAlias(ctx, value) {
+  const alias = `:cond${ctx.valueCounter.n++}`;
+  ctx.values[alias] = value;
+  return alias;
+}
+function isOperatorObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date || value instanceof Uint8Array || value instanceof Set) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return false;
+  return keys.every((k2) => OPERATOR_KEYS.has(k2));
+}
+function joinAnd(clauses) {
+  if (clauses.length === 1) return clauses[0];
+  return clauses.map((c) => wrap(c)).join(" AND ");
+}
+function wrap(expr) {
+  if (isAlreadyWrapped(expr)) return expr;
+  if (expr.includes(" AND ") || expr.includes(" OR ")) return `(${expr})`;
+  return expr;
+}
+function isAlreadyWrapped(expr) {
+  if (!expr.startsWith("(") || !expr.endsWith(")")) return false;
+  let depth = 0;
+  for (let i = 0; i < expr.length; i++) {
+    if (expr[i] === "(") depth++;
+    else if (expr[i] === ")") {
+      depth--;
+      if (depth === 0 && i < expr.length - 1) return false;
+    }
+  }
+  return depth === 0;
+}
+function compileField(ctx, field, condition) {
+  const n = nameAlias(ctx, field);
+  if (!isOperatorObject(condition)) {
+    return `${n} = ${valueAlias(ctx, condition)}`;
+  }
+  const ops = condition;
+  const clauses = [];
+  for (const [op, value] of Object.entries(ops)) {
+    switch (op) {
+      case "eq":
+        clauses.push(`${n} = ${valueAlias(ctx, value)}`);
+        break;
+      case "ne":
+        clauses.push(`${n} <> ${valueAlias(ctx, value)}`);
+        break;
+      case "gt":
+        clauses.push(`${n} > ${valueAlias(ctx, value)}`);
+        break;
+      case "ge":
+        clauses.push(`${n} >= ${valueAlias(ctx, value)}`);
+        break;
+      case "lt":
+        clauses.push(`${n} < ${valueAlias(ctx, value)}`);
+        break;
+      case "le":
+        clauses.push(`${n} <= ${valueAlias(ctx, value)}`);
+        break;
+      case "between": {
+        const [lo, hi] = value;
+        clauses.push(
+          `${n} BETWEEN ${valueAlias(ctx, lo)} AND ${valueAlias(ctx, hi)}`
+        );
+        break;
+      }
+      case "in": {
+        const aliases = value.map((v) => valueAlias(ctx, v));
+        clauses.push(`${n} IN (${aliases.join(", ")})`);
+        break;
+      }
+      case "beginsWith":
+        clauses.push(`begins_with(${n}, ${valueAlias(ctx, value)})`);
+        break;
+      case "contains":
+        clauses.push(`contains(${n}, ${valueAlias(ctx, value)})`);
+        break;
+      case "notContains":
+        clauses.push(`NOT contains(${n}, ${valueAlias(ctx, value)})`);
+        break;
+      case "attributeExists":
+        clauses.push(
+          value === false ? `attribute_not_exists(${n})` : `attribute_exists(${n})`
+        );
+        break;
+      case "attributeType":
+        clauses.push(`attribute_type(${n}, ${valueAlias(ctx, value)})`);
+        break;
+      case "size":
+        clauses.push(`size(${n}) = ${valueAlias(ctx, value)}`);
+        break;
+      default:
+        throw new Error(`Unknown condition operator '${op}' on field '${field}'`);
+    }
+  }
+  return joinAnd(clauses);
+}
+function compileRaw(ctx, raw) {
+  return compileRawCondition(
+    raw,
+    (column) => nameAlias(ctx, column),
+    (value) => valueAlias(ctx, value)
+  );
+}
+function compileNode(ctx, node) {
+  if (isRawCondition(node)) {
+    return compileRaw(ctx, node);
+  }
+  const clauses = [];
+  for (const [key2, value] of Object.entries(node)) {
+    if (value === void 0) continue;
+    if (key2 === "and" || key2 === "or") {
+      const parts = value.map((sub) => compileNode(ctx, sub)).filter((s) => s.length > 0);
+      if (parts.length === 0) continue;
+      if (parts.length === 1) {
+        clauses.push(parts[0]);
+      } else {
+        const sep = key2 === "and" ? " AND " : " OR ";
+        clauses.push(`(${parts.map((p) => wrap(p)).join(sep)})`);
+      }
+      continue;
+    }
+    if (key2 === "not") {
+      const inner = compileNode(ctx, value);
+      if (inner.length > 0) clauses.push(`NOT ${wrap(inner)}`);
+      continue;
+    }
+    const clause = compileField(ctx, key2, value);
+    if (clause.length > 0) clauses.push(clause);
+  }
+  return joinAnd(clauses);
+}
+function resolveConditionTree(declarative, resolveParam) {
+  return resolveNode(declarative, resolveParam);
+}
+function isParamLeaf(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.$param === "string";
+}
+function resolveLeaf(value, resolveParam) {
+  if (isParamLeaf(value)) return resolveParam(value.$param);
+  return value;
+}
+function resolveNode(node, resolveParam) {
+  const obj = node;
+  const out = {};
+  for (const [key2, value] of Object.entries(obj)) {
+    if (key2 === "and" || key2 === "or") {
+      out[key2] = value.map((s) => resolveNode(s, resolveParam));
+    } else if (key2 === "not") {
+      out[key2] = resolveNode(value, resolveParam);
+    } else {
+      const ops = value;
+      const rendered = {};
+      for (const [op, opVal] of Object.entries(ops)) {
+        if (op === "between") {
+          const [lo, hi] = opVal;
+          rendered[op] = [
+            resolveLeaf(lo, resolveParam),
+            resolveLeaf(hi, resolveParam)
+          ];
+        } else if (op === "in") {
+          rendered[op] = opVal.map(
+            (v) => resolveLeaf(v, resolveParam)
+          );
+        } else if (op === "attributeExists") {
+          rendered[op] = opVal;
+        } else {
+          rendered[op] = resolveLeaf(opVal, resolveParam);
+        }
+      }
+      out[key2] = rendered;
+    }
+  }
+  return out;
+}
 function buildConditionExpression(condition) {
+  if (isRawCondition(condition)) {
+    const ctx2 = { names: {}, values: {}, valueCounter: { n: 0 } };
+    const expression2 = compileRaw(ctx2, condition);
+    return { expression: expression2, names: ctx2.names, values: ctx2.values };
+  }
   if (condition.notExists === true) {
-    return {
-      expression: "attribute_not_exists(PK)",
-      names: {},
-      values: {}
-    };
+    return { expression: "attribute_not_exists(PK)", names: {}, values: {} };
   }
   if (typeof condition.attributeExists === "string") {
     const field = condition.attributeExists;
@@ -887,22 +1208,9 @@ function buildConditionExpression(condition) {
       values: {}
     };
   }
-  const clauses = [];
-  const names = {};
-  const values = {};
-  let counter = 0;
-  for (const [fieldName, value] of Object.entries(condition)) {
-    const nameKey = `#cond_${fieldName}`;
-    const valueKey = `:cond${counter++}`;
-    names[nameKey] = fieldName;
-    values[valueKey] = value;
-    clauses.push(`${nameKey} = ${valueKey}`);
-  }
-  return {
-    expression: clauses.join(" AND "),
-    names,
-    values
-  };
+  const ctx = { names: {}, values: {}, valueCounter: { n: 0 } };
+  const expression = compileNode(ctx, condition);
+  return { expression, names: ctx.names, values: ctx.values };
 }
 
 // src/operations/serialize.ts
@@ -1037,6 +1345,29 @@ function resolveSegmentedKey(segmented, values, context = "key") {
   };
 }
 
+// src/operations/gsi-derive.ts
+function deriveGsiKey(gsi2, available, context) {
+  const gsiInput = {};
+  for (const fieldName of gsi2.inputFieldNames) {
+    gsiInput[fieldName] = available[fieldName];
+  }
+  const { pk, sk } = resolveSegmentedKey(gsi2.segmented, gsiInput, context);
+  return {
+    pkAttr: `${gsi2.indexName}PK`,
+    pk,
+    skAttr: `${gsi2.indexName}SK`,
+    sk: sk ?? ""
+  };
+}
+function affectedGsis(meta, changedFields) {
+  return meta.gsiDefinitions.filter(
+    (gsi2) => gsi2.inputFieldNames.some((f) => changedFields.has(f))
+  );
+}
+function missingGsiFields(gsi2, available) {
+  return gsi2.inputFieldNames.filter((f) => available[f] === void 0);
+}
+
 // src/capture/registry.ts
 var ChangeCaptureRegistryImpl = class {
   subscribers = /* @__PURE__ */ new Set();
@@ -1142,18 +1473,18 @@ function buildPutInput(modelClass, item, options) {
       dynamoItem[emb.propertyName] = value;
     }
   }
+  const available = {};
+  for (const fieldName of meta.fields.map((f) => f.propertyName)) {
+    available[fieldName] = serialized[fieldName] ?? item[fieldName];
+  }
   for (const gsi2 of meta.gsiDefinitions) {
-    const gsiInput = {};
-    for (const fieldName of gsi2.inputFieldNames) {
-      gsiInput[fieldName] = serialized[fieldName] ?? item[fieldName];
-    }
-    const { pk: gsiPk, sk: gsiSk } = resolveSegmentedKey(
-      gsi2.segmented,
-      gsiInput,
+    const { pkAttr, pk: gsiPk, skAttr, sk: gsiSk } = deriveGsiKey(
+      gsi2,
+      available,
       `${modelClass.name} GSI '${gsi2.indexName}'`
     );
-    dynamoItem[`${gsi2.indexName}PK`] = gsiPk;
-    dynamoItem[`${gsi2.indexName}SK`] = gsiSk ?? "";
+    dynamoItem[pkAttr] = gsiPk;
+    dynamoItem[skAttr] = gsiSk;
   }
   const putInput = {
     TableName: tableName,
@@ -1313,6 +1644,64 @@ function resolveUpdateKey(modelClass, primaryKey, entity, fieldMap) {
   );
   return { pk, sk: sk ?? "" };
 }
+function buildGsiRederiveSets(modelClass, meta, entity, serializedChanges, fieldMap, names, values, options) {
+  const changedFields = new Set(Object.keys(serializedChanges));
+  const affected = affectedGsis(meta, changedFields);
+  if (affected.length === 0) return [];
+  const available = {};
+  for (const [fieldName, raw] of Object.entries(entity)) {
+    if (raw === void 0) continue;
+    const fm = fieldMap.get(fieldName);
+    available[fieldName] = fm ? serializeFieldValue(raw, fm) : raw;
+  }
+  Object.assign(available, serializedChanges);
+  const clauses = [];
+  let i = 0;
+  for (const gsi2 of affected) {
+    const missing = missingGsiFields(gsi2, available);
+    if (missing.length > 0) {
+      if (options?.rederive === "read-modify-write") continue;
+      const changed = gsi2.inputFieldNames.filter((f) => changedFields.has(f));
+      throw new Error(
+        `Cannot update '${modelClass.name}': updating ${fmtFields(changed)} affects index '${gsi2.indexName}' (also depends on ${fmtFields(missing)}); provide ${missing.length > 1 ? "them" : "it"}, or use { rederive: 'read-modify-write' }.`
+      );
+    }
+    const { pkAttr, pk, skAttr, sk } = deriveGsiKey(
+      gsi2,
+      available,
+      `${modelClass.name} GSI '${gsi2.indexName}'`
+    );
+    const pkN = `#gsi${i}pk`;
+    const pkV = `:gsi${i}pk`;
+    names[pkN] = pkAttr;
+    values[pkV] = pk;
+    clauses.push(`${pkN} = ${pkV}`);
+    const skN = `#gsi${i}sk`;
+    const skV = `:gsi${i}sk`;
+    names[skN] = skAttr;
+    values[skV] = sk;
+    clauses.push(`${skN} = ${skV}`);
+    i++;
+  }
+  return clauses;
+}
+function fmtFields(fields) {
+  return fields.map((f) => `'${f}'`).join(", ");
+}
+function appendSetClauses(expression, clauses) {
+  if (clauses.length === 0) return expression;
+  const extra = clauses.join(", ");
+  if (/(^|\s)SET\s/.test(expression)) {
+    const removeIdx = expression.indexOf(" REMOVE ");
+    if (removeIdx === -1) {
+      return `${expression}, ${extra}`;
+    }
+    const setPart = expression.slice(0, removeIdx);
+    const rest = expression.slice(removeIdx);
+    return `${setPart}, ${extra}${rest}`;
+  }
+  return `SET ${extra} ${expression}`.trimEnd();
+}
 function buildUpdateInput(modelClass, entity, changes, options) {
   const meta = MetadataRegistry.get(modelClass);
   if (!meta.primaryKey) {
@@ -1353,6 +1742,16 @@ function buildUpdateInput(modelClass, entity, changes, options) {
   const updateResult = buildUpdateExpression(serializedChanges, embeddedFieldNames);
   const names = { ...updateResult.names };
   const values = { ...updateResult.values };
+  const gsiSetClauses = buildGsiRederiveSets(
+    modelClass,
+    meta,
+    entity,
+    serializedChanges,
+    fieldMap,
+    names,
+    values,
+    options
+  );
   let conditionExpression;
   if (options?.condition) {
     const condResult = buildConditionExpression(options.condition);
@@ -1366,7 +1765,7 @@ function buildUpdateInput(modelClass, entity, changes, options) {
       PK: pk,
       SK: sk
     },
-    UpdateExpression: updateResult.expression,
+    UpdateExpression: appendSetClauses(updateResult.expression, gsiSetClauses),
     ExpressionAttributeNames: names
   };
   if (Object.keys(values).length > 0) {
@@ -1387,8 +1786,72 @@ function serializeChanges(modelClass, changes) {
   }
   return out;
 }
+function needsReadForRederive(meta, entity, serializedChanges, fieldMap) {
+  const changedFields = new Set(Object.keys(serializedChanges));
+  const affected = affectedGsis(meta, changedFields);
+  if (affected.length === 0) return false;
+  const available = {};
+  for (const [fieldName, raw] of Object.entries(entity)) {
+    if (raw === void 0) continue;
+    const fm = fieldMap.get(fieldName);
+    available[fieldName] = fm ? serializeFieldValue(raw, fm) : raw;
+  }
+  Object.assign(available, serializedChanges);
+  return affected.some((gsi2) => missingGsiFields(gsi2, available).length > 0);
+}
+async function rederiveByReadModifyWrite(modelClass, entity, changes, options, pk, sk, tableName) {
+  const result = await ClientManager.getExecutor().execute({
+    type: "GetItem",
+    tableName,
+    keyCondition: { PK: pk, SK: sk },
+    consistentRead: true
+  });
+  const current = result.items[0];
+  if (!current) {
+    throw new Error(
+      `Cannot read-modify-write update '${modelClass.name}': no item exists at PK=${pk}, SK=${sk}. The row must exist to re-derive its GSI keys.`
+    );
+  }
+  const enriched = { ...current, ...entity };
+  const guarded = {
+    ...options,
+    rederive: void 0,
+    condition: options?.condition ?? { attributeExists: "PK" }
+  };
+  return buildUpdateInput(modelClass, enriched, changes, guarded);
+}
 async function executeUpdate(modelClass, entity, changes, options) {
-  const updateInput = buildUpdateInput(modelClass, entity, changes, options);
+  let updateInput;
+  if (options?.rederive === "read-modify-write") {
+    const meta = MetadataRegistry.get(modelClass);
+    const fieldMap = new Map(meta.fields.map((f) => [f.propertyName, f]));
+    const serializedChanges = {};
+    for (const [fieldName, value] of Object.entries(changes)) {
+      const fm = fieldMap.get(fieldName);
+      serializedChanges[fieldName] = fm && value !== void 0 ? serializeFieldValue(value, fm) : value;
+    }
+    if (meta.primaryKey && needsReadForRederive(meta, entity, serializedChanges, fieldMap)) {
+      const { pk, sk } = resolveUpdateKey(
+        modelClass,
+        meta.primaryKey,
+        entity,
+        fieldMap
+      );
+      updateInput = await rederiveByReadModifyWrite(
+        modelClass,
+        entity,
+        changes,
+        options,
+        pk,
+        sk,
+        TableMapping.resolve(meta.tableName)
+      );
+    } else {
+      updateInput = buildUpdateInput(modelClass, entity, changes, options);
+    }
+  } else {
+    updateInput = buildUpdateInput(modelClass, entity, changes, options);
+  }
   const wantsOld = ChangeCaptureRegistry.wantsOldImage(modelClass);
   const result = await ClientManager.getExecutor().update(
     updateInput,
@@ -1719,17 +2182,17 @@ var TransactionContext = class {
     this.assertWithinLimit();
     const modelClass = resolveModelClass(model);
     const { TableName, Key } = buildDeleteInput(modelClass, key2);
-    const cond = buildConditionExpression(options.condition);
+    const cond2 = buildConditionExpression(options.condition);
     const check = {
       TableName,
       Key,
-      ConditionExpression: cond.expression
+      ConditionExpression: cond2.expression
     };
-    if (Object.keys(cond.names).length > 0) {
-      check.ExpressionAttributeNames = cond.names;
+    if (Object.keys(cond2.names).length > 0) {
+      check.ExpressionAttributeNames = cond2.names;
     }
-    if (Object.keys(cond.values).length > 0) {
-      check.ExpressionAttributeValues = cond.values;
+    if (Object.keys(cond2.values).length > 0) {
+      check.ExpressionAttributeValues = cond2.values;
     }
     this.items.push({ ConditionCheck: check });
   }
@@ -1791,10 +2254,18 @@ export {
   pkTemplate,
   skTemplate,
   resolveSegmentedKey,
+  param,
+  isParam,
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
   DynamoExecutor,
   ClientManager,
+  isRawCondition,
+  cond,
+  compileRawCondition,
+  serializeRawCondition,
+  collectRawConditionParams,
+  resolveConditionTree,
   buildConditionExpression,
   serializeFieldValue,
   ChangeCaptureRegistry,