graphddb 0.2.0 → 0.2.1

package/README.md

@@ -37,6 +37,64 @@ A partition key is a graph entry point, a relation an explicit traversal path, a
 selection set. GraphDDB does not invent a query language — it executes well-designed access
 patterns directly and makes ambiguity visible through plans, limits, and relation resolution.
 
+## Install
+
+```bash
+npm install graphddb
+```
+
+The AWS SDK v3 is a peer dependency — install the clients you use:
+
+```bash
+npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
+```
+
+`tsx` is an optional peer dependency, needed only to run the code-generation CLI
+(`graphddb generate …`) directly against TypeScript definition files. Library
+consumers don't need it (so it never pulls esbuild into your runtime bundle):
+
+```bash
+npm install -D tsx
+```
+
+Requires Node.js ≥ 22.
+
+## Quick Start
+
+```ts
+import { DDBModel, model, string, key, k } from 'graphddb';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+@model({ table: 'AppTable', prefix: 'USER' })
+class UserModel extends DDBModel {
+  static readonly keys = key<{ userId: string }>((c) => ({
+    pk: k`USER#${c.userId}`,
+    sk: k`PROFILE`,
+  }));
+
+  @string userId!: string;
+  @string name!: string;
+}
+const User = UserModel.asModel();
+
+// Wire up the DynamoDB client once (configure retries/region on the client itself).
+DDBModel.setClient(new DynamoDBClient({}));
+
+// Read — only the selected fields appear in the result type.
+const user = await User.query({ userId: 'alice' }, { name: true });
+
+// Single-item write — raw base op, named after the DynamoDB API.
+await User.putItem({ userId: 'alice', name: 'Alice' });
+
+// Multi-item atomic write — the unified envelope (default `mode: 'transaction'`).
+await DDBModel.mutate({
+  user: { update: User, key: { userId: 'alice' }, input: { name: 'Alice B.' } },
+});
+```
+
+For cross-service contracts, the Python bridge, multi-fragment atomic mutations,
+and more, see the sections below and [`docs/spec.md`](./docs/spec.md).
+
 ## User Permissions Example
 
 The [user-permissions](./examples/user-permissions/) example models users, groups, memberships, and permissions in a single DynamoDB table.
@@ -272,6 +330,10 @@ are aliased (`ExpressionAttributeNames`) — there is no literal interpolation,
 the compiled expression is injection-free, and it is attached independently of
 the `KeyConditionExpression` / `ProjectionExpression`.
 
+The same `cond` fragment is also accepted as a write `condition` (on
+`putItem` / `updateItem` / `deleteItem`, transaction items, and public commands),
+not just as a read filter.
+
 > **RCU note:** A `FilterExpression` does **not** reduce read capacity —
 > DynamoDB reads matching keys first, then filters. `limit` is applied
 > **before** the filter, so a single page may return **fewer** than `limit`
@@ -339,7 +401,11 @@ const res = await DDBModel.mutate({
 - **`key`** is a single object or an **array of objects** (key-array bulk). A
   transaction compiles to `TransactWriteItems`; parallel mode compiles to
   `BatchWriteItem` (chunked, with `UnprocessedItems` retry).
-- **`condition`** is an equality subset that gates the write.
+- **`condition`** is a `WriteCondition` write gate — the same declarative
+  operator subset as read filters (`eq`/`ne`/comparisons/`between`/`in`/string
+  ops/`size`/`attributeType` + `and`/`or`/`not`), the legacy existence primitives
+  (`notExists` / `attributeExists` / `attributeNotExists`), or a raw `cond`
+  fragment.
 - **`result: { select, options? }`** reads the written item back; omit it and the
   route returns void.
 - **`mode: 'transaction'`** (DEFAULT) is one atomic `TransactWriteItems`:
@@ -515,7 +581,6 @@ Layer 5: Hydrator
 | Structured keys | Keys are built from `k` segment templates; partial keys compile to `begins_with` at a segment boundary. |
 | Typed consistentRead | `consistentRead` is only available for PK queries. GSI queries are rejected at compile time. |
 | Server-side filter | `filter` is a declarative DynamoDB `FilterExpression` (AppSync `ModelFilterInput`-compatible), typed against the full entity and able to reference unprojected attributes. It does not reduce RCU, and `limit` is applied before it. |
-| Post-load filtering | No built-in post-load predicate; use `result.items.filter(...)` on the typed projection. Efficient narrowing belongs in key design. |
 
 ## Architectural Boundaries
 
@@ -583,7 +648,7 @@ The query / relation / write API above is the core layer. GraphDDB also ships:
 - Entity metadata / decorators
 - DDBModel base class / connection management
 - Type system (SelectableOf, QueryResult, QueryKeyOf)
-- CRUD (put, update, delete, conditional writes)
+- CRUD (put, update, delete, conditional writes — `WriteCondition` shares the full declarative filter operator set plus the `cond` raw escape hatch)
 - Query / List (planner, executor, hydrator, cursor pagination)
 - Type-safe filtering: declarative server-side `filter` (FilterExpression / AppSync `ModelFilterInput`-compatible), plus `Model.col` column refs and the `cond` raw escape hatch
 - Structured segment keys (`k` tag): partial keys compile to `begins_with` at a segment boundary

package/dist/{chunk-F27INYI2.js → chunk-4B4MUPUJ.js}

@@ -13,6 +13,7 @@ import {
   buildUpdateInput,
   captureWrite,
   commitTransaction,
+  compileRawCondition,
   createColumnMap,
   execItemKeySignature,
   executeDelete,
@@ -20,14 +21,18 @@ import {
   executeTransaction,
   executeUpdate,
   isColumn,
+  isParam,
+  isRawCondition,
+  param,
   pkTemplate,
   resolveKey,
   resolveModelClass,
   resolveSegmentedKey,
   segmentFieldNames,
   serializeFieldValue,
+  serializeRawCondition,
   skTemplate
-} from "./chunk-347U24SB.js";
+} from "./chunk-PWV7JDMR.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -236,51 +241,6 @@ function getImplicitKeyFields(select, metadata) {
   return [...needed];
 }
 
-// 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/planner/projection.ts
 function buildProjection(select, additionalFields) {
   const paths = [];
@@ -321,32 +281,6 @@ function buildProjection(select, additionalFields) {
   };
 }
 
-// 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;
-}
-
 // src/expression/filter-expression.ts
 var LOGICAL_KEYS = /* @__PURE__ */ new Set(["and", "or", "not"]);
 var OPERATOR_KEYS = /* @__PURE__ */ new Set([
@@ -1916,6 +1850,12 @@ function renderRecord(structure, key, params, context) {
 }
 function renderCondition(condition, key, params, context) {
   if (condition === void 0) return void 0;
+  if (isRawCondition(condition)) {
+    const parts = condition.parts.map(
+      (part) => isColumn(part) ? part : renderLeaf(part, key, params, `${context} condition`)
+    );
+    return { ...condition, parts };
+  }
   if (typeof condition === "object" && condition !== null) {
     const obj = condition;
     if (obj.notExists === true) return { notExists: true };
@@ -2003,14 +1943,14 @@ function renderConditionCheck(check, key, params, contextLabel) {
     modelClass,
     referencedKey
   );
-  const cond2 = buildConditionExpression({ attributeExists: "PK" });
+  const cond = buildConditionExpression({ attributeExists: "PK" });
   const checkInput = {
     TableName,
     Key,
-    ConditionExpression: cond2.expression
+    ConditionExpression: cond.expression
   };
-  if (Object.keys(cond2.names).length > 0) checkInput.ExpressionAttributeNames = cond2.names;
-  if (Object.keys(cond2.values).length > 0) checkInput.ExpressionAttributeValues = cond2.values;
+  if (Object.keys(cond.names).length > 0) checkInput.ExpressionAttributeNames = cond.names;
+  if (Object.keys(cond.values).length > 0) checkInput.ExpressionAttributeValues = cond.values;
   return checkInput;
 }
 var RUNTIME_TOKEN_RE = /\{([^{}]+)\}/g;
@@ -2093,10 +2033,10 @@ function renderUniqueGuardItems(guard, key, params, contextLabel) {
     if (item.type === "Put") {
       const Item = renderTemplateRecord(item.item, key, params, `${contextLabel} guard Put`);
       const put = { TableName: TableMapping.resolve(item.tableName), Item };
-      const cond2 = buildConditionExpression({ attributeNotExists: "PK" });
-      put.ConditionExpression = cond2.expression;
-      if (Object.keys(cond2.names).length > 0) put.ExpressionAttributeNames = cond2.names;
-      if (Object.keys(cond2.values).length > 0) put.ExpressionAttributeValues = cond2.values;
+      const cond = buildConditionExpression({ attributeNotExists: "PK" });
+      put.ConditionExpression = cond.expression;
+      if (Object.keys(cond.names).length > 0) put.ExpressionAttributeNames = cond.names;
+      if (Object.keys(cond.values).length > 0) put.ExpressionAttributeValues = cond.values;
       return { Put: put };
     }
     const Key = renderTemplateRecord(item.keyCondition, key, params, `${contextLabel} guard Delete`);
@@ -2115,10 +2055,10 @@ function renderIdempotencyGuardItems(guard, key, params, contextLabel) {
   return guard.items.map((item) => {
     const Item = renderTemplateRecord(item.item, key, params, `${contextLabel} idempotency Put`);
     const put = { TableName: TableMapping.resolve(item.tableName), Item };
-    const cond2 = buildConditionExpression({ attributeNotExists: "PK" });
-    put.ConditionExpression = cond2.expression;
-    if (Object.keys(cond2.names).length > 0) put.ExpressionAttributeNames = cond2.names;
-    if (Object.keys(cond2.values).length > 0) put.ExpressionAttributeValues = cond2.values;
+    const cond = buildConditionExpression({ attributeNotExists: "PK" });
+    put.ConditionExpression = cond.expression;
+    if (Object.keys(cond.names).length > 0) put.ExpressionAttributeNames = cond.names;
+    if (Object.keys(cond.values).length > 0) put.ExpressionAttributeValues = cond.values;
     return { Put: put };
   });
 }
@@ -3891,17 +3831,24 @@ function describeKey(fragment) {
 }
 
 // src/spec/guard.ts
-function conditionInputToSpec(condition, context, renderLeaf2) {
+function conditionInputToSpec(condition, context, renderLeaf2, renderTreeLeaf, renderRawSlot) {
   if (condition === void 0 || condition === null) return void 0;
+  if (isRawCondition(condition)) {
+    const { expression, names, values } = serializeRawCondition(
+      condition,
+      renderRawSlot
+    );
+    return { kind: "raw", expression, names, values };
+  }
   if (typeof condition !== "object") {
     throw new Error(
-      `${context}: write condition must be an object (\`{ notExists: true }\`, \`{ attributeExists: '<field>' }\`, \`{ attributeNotExists: '<field>' }\`, or field equality).`
+      `${context}: write condition must be an object (\`{ notExists: true }\`, \`{ attributeExists: '<field>' }\`, \`{ attributeNotExists: '<field>' }\`, or a declarative field condition).`
     );
   }
   const obj = condition;
   if (obj.notExists === true) return { kind: "notExists" };
-  if ("attributeExists" in obj) {
-    if (typeof obj.attributeExists !== "string" || obj.attributeExists.length === 0) {
+  if ("attributeExists" in obj && typeof obj.attributeExists === "string") {
+    if (obj.attributeExists.length === 0) {
       throw new Error(
         `${context}: \`attributeExists\` must name a non-empty attribute field.`
       );
@@ -3916,12 +3863,122 @@ function conditionInputToSpec(condition, context, renderLeaf2) {
     }
     return { kind: "attributeNotExists", field: obj.attributeNotExists };
   }
+  if (usesOperatorTree(obj)) {
+    const leaf = renderTreeLeaf ?? ((value, name) => defaultTreeLeaf(value, name, context));
+    return { kind: "expr", declarative: buildTree(obj, context, leaf) };
+  }
   const fields = {};
   for (const key of Object.keys(obj).sort()) {
     fields[key] = renderLeaf2(key, obj[key]);
   }
   return { kind: "equals", fields };
 }
+function assertNotNestedRaw(sub, context) {
+  if (isRawCondition(sub)) {
+    throw new Error(
+      `${context}: a raw \`cond\` write condition may be used as a whole condition, but not nested inside an \`and\` / \`or\` / \`not\` group of a serializable (public-contract / Python-bridge) command. Move the \`cond\` to the top level, or express the group declaratively.`
+    );
+  }
+}
+var LOGICAL_KEYS2 = /* @__PURE__ */ new Set(["and", "or", "not"]);
+var OPERATOR_KEYS2 = /* @__PURE__ */ new Set([
+  "eq",
+  "ne",
+  "gt",
+  "ge",
+  "lt",
+  "le",
+  "between",
+  "in",
+  "beginsWith",
+  "contains",
+  "notContains",
+  "attributeExists",
+  "attributeType",
+  "size"
+]);
+function isOperatorObject2(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) || value instanceof Date) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return false;
+  return keys.every((k) => OPERATOR_KEYS2.has(k));
+}
+function usesOperatorTree(obj) {
+  for (const [key, value] of Object.entries(obj)) {
+    if (LOGICAL_KEYS2.has(key)) return true;
+    if (isOperatorObject2(value)) return true;
+  }
+  return false;
+}
+function defaultTreeLeaf(value, name, context) {
+  void name;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  throw new Error(
+    `${context}: condition operand must be a concrete literal or a param; got ${typeof value}.`
+  );
+}
+function conditionParamName(field, op, index) {
+  if (op === "between") return `${field}_${index === 0 ? "lo" : "hi"}`;
+  if (op === "in") return `${field}_${index ?? 0}`;
+  if (op === "size") return `${field}_size`;
+  return field;
+}
+function buildTree(obj, context, renderTreeLeaf) {
+  const out = {};
+  for (const key of Object.keys(obj).sort()) {
+    const value = obj[key];
+    if (value === void 0) continue;
+    if (key === "and" || key === "or") {
+      out[key] = value.map((sub) => {
+        assertNotNestedRaw(sub, context);
+        return buildTree(sub, context, renderTreeLeaf);
+      });
+      continue;
+    }
+    if (key === "not") {
+      assertNotNestedRaw(value, context);
+      out[key] = buildTree(
+        value,
+        context,
+        renderTreeLeaf
+      );
+      continue;
+    }
+    if (!isOperatorObject2(value)) {
+      out[key] = { eq: renderTreeLeaf(value, conditionParamName(key, "eq")) };
+      continue;
+    }
+    const ops = value;
+    const rendered = {};
+    for (const op of Object.keys(ops).sort()) {
+      const opVal = ops[op];
+      if (op === "between") {
+        const [lo, hi] = opVal;
+        rendered[op] = [
+          renderTreeLeaf(lo, conditionParamName(key, op, 0)),
+          renderTreeLeaf(hi, conditionParamName(key, op, 1))
+        ];
+      } else if (op === "in") {
+        rendered[op] = opVal.map(
+          (v, i) => renderTreeLeaf(v, conditionParamName(key, op, i))
+        );
+      } else if (op === "attributeExists") {
+        rendered[op] = opVal;
+      } else if (op === "attributeType") {
+        rendered[op] = String(opVal);
+      } else {
+        rendered[op] = renderTreeLeaf(opVal, conditionParamName(key, op));
+      }
+    }
+    out[key] = rendered;
+  }
+  return out;
+}
 function assertSupportedCondition(commandName, condition) {
   if (condition.kind === "notExists") return;
   if (condition.kind === "attributeExists" || condition.kind === "attributeNotExists") {
@@ -3948,8 +4005,25 @@ function assertSupportedCondition(commandName, condition) {
     }
     return;
   }
+  if (condition.kind === "raw") {
+    if (typeof condition.expression !== "string" || condition.expression.length === 0) {
+      throw new Error(
+        `Command '${commandName}' has an empty raw \`cond\` write condition.`
+      );
+    }
+    return;
+  }
+  if (condition.kind === "expr") {
+    const tree = condition.declarative;
+    if (!tree || Object.keys(tree).length === 0) {
+      throw new Error(
+        `Command '${commandName}' has an empty declarative write condition.`
+      );
+    }
+    return;
+  }
   throw new Error(
-    `Command '${commandName}' has an unsupported write condition. The Python bridge supports '{ notExists }' or field equality only.`
+    `Command '${commandName}' has an unsupported write condition.`
   );
 }
 function assertJsonSerializable(value, path = "$") {
@@ -4498,6 +4572,17 @@ function leafTemplate(value, context) {
     `defineTransaction: ${context} must be a field reference (from \`p\` or a forEach element) or a concrete literal; got ${typeof value}.`
   );
 }
+function conditionTreeLeaf(value, name, context) {
+  void name;
+  if (isTransactionRef(value)) return { $param: tokenName(value.token) };
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  throw new Error(
+    `defineTransaction: ${context} condition operand must be a field reference (from \`p\` or a forEach element) or a concrete literal; got ${typeof value}.`
+  );
+}
 function templateRecord2(structure, context) {
   const out = {};
   for (const field of Object.keys(structure).sort()) {
@@ -4541,7 +4626,12 @@ function conditionSpec(condition, commandName) {
   const spec = conditionInputToSpec(
     condition,
     commandName,
-    (field, value) => leafTemplate(value, `condition field '${field}'`)
+    (field, value) => leafTemplate(value, `condition field '${field}'`),
+    (value, name) => conditionTreeLeaf(value, name, commandName),
+    // A raw `cond` value slot in a transaction is a field reference
+    // (`p.*` / forEach element) → a `{ $param }` marker carrying its token name;
+    // a concrete literal falls through to the default renderer (issue #114-B).
+    (part) => isTransactionRef(part) ? { $param: tokenName(part.token) } : void 0
   );
   if (spec) assertSupportedCondition(commandName, spec);
   return spec;
@@ -5092,9 +5182,32 @@ function extractCondition(def) {
   return conditionInputToSpec(
     def.condition,
     `Command on '${def.entity.name}'`,
-    (field, value) => templateLeaf(field, value)
+    (field, value) => templateLeaf(field, value),
+    (value, name) => conditionTreeLeaf2(value, name),
+    // A raw `cond` value slot (issue #114-B): a contract param / key ref carries
+    // its own name; a plain `param.*` falls through to the positional default.
+    (part) => {
+      if (isContractParamRef(part)) return { $param: tokenName2(part.token) };
+      if (isContractKeyFieldRef(part)) return { $param: part.field };
+      return void 0;
+    }
+  );
+}
+function conditionTreeLeaf2(value, name) {
+  if (isContractParamRef(value)) return { $param: tokenName2(value.token) };
+  if (isContractKeyFieldRef(value)) return { $param: value.field };
+  if (isParam(value)) return { $param: name };
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  throw new Error(
+    `A declarative write-condition operand must be a concrete literal or a param reference; got ${typeof value}.`
   );
 }
+function tokenName2(token) {
+  return token.startsWith("{") && token.endsWith("}") ? token.slice(1, -1) : token;
+}
 function buildQuerySpec(def) {
   const operations = buildReadOperations(def);
   const executionPlan = deriveExecutionPlan(operations.map((op) => op.resultPath));
@@ -5252,6 +5365,7 @@ function convertLeaf(leaf, bindField, place, context) {
   );
 }
 function convertCondition(condition, place, context) {
+  if (isRawCondition(condition)) return condition;
   if (typeof condition === "object" && condition !== null) {
     const obj = condition;
     if (obj.notExists === true) return { notExists: true };
@@ -5414,8 +5528,32 @@ function toElementRecord(record, keyParams) {
   return out;
 }
 function toElementCondition(condition, keyParams) {
-  if (condition.kind !== "equals") return condition;
-  return { kind: "equals", fields: toElementRecord(condition.fields, keyParams) };
+  if (condition.kind === "equals") {
+    return { kind: "equals", fields: toElementRecord(condition.fields, keyParams) };
+  }
+  if (condition.kind === "expr") {
+    return { kind: "expr", declarative: toElementTree(condition.declarative, keyParams) };
+  }
+  if (condition.kind === "raw") {
+    return {
+      kind: "raw",
+      expression: condition.expression,
+      names: condition.names,
+      values: toElementTree(condition.values, keyParams)
+    };
+  }
+  return condition;
+}
+function toElementTree(node, keyParams) {
+  if (Array.isArray(node)) return node.map((n) => toElementTree(n, keyParams));
+  if (node === null || typeof node !== "object") return node;
+  const obj = node;
+  if (typeof obj.$param === "string" && !obj.$param.startsWith("item.")) {
+    return keyParams.has(obj.$param) ? { $param: `item.${obj.$param}` } : obj;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) out[k] = toElementTree(v, keyParams);
+  return out;
 }
 function synthesizeBatchTransaction(commandSpec, op) {
   const keyParams = new Set(keyParamNames(op));
@@ -5948,10 +6086,7 @@ export {
   normalizeSelectSpec,
   detectRelationFields,
   getImplicitKeyFields,
-  param,
-  isParam,
   buildProjection,
-  cond,
   compileFilterExpression,
   evaluateFilter,
   plan,
@@ -6013,6 +6148,7 @@ export {
   publicQueryModel,
   publicCommandModel,
   isPlannedCommandMethod,
+  conditionParamName,
   assertSupportedCondition,
   assertJsonSerializable,
   assertBundleSerializable,