graphddb 0.3.0 → 0.3.1

package/dist/index.js

@@ -2,8 +2,6 @@ import {
   BatchGetResult,
   DDBModel,
   EDGE_WRITES_MARKER,
-  ENTITY_WRITES_MARKER,
-  LIFECYCLE_CONTRACT_MARKER,
   MARKER_ROW_ENTITY,
   OLD_VALUE_NAMESPACE,
   RELATION_TRAVERSAL_CONCURRENCY,
@@ -16,7 +14,6 @@ import {
   buildBridgeBundle,
   buildContexts,
   buildContracts,
-  buildMaintenanceGraph,
   buildManifest,
   buildOperations,
   buildProjection,
@@ -42,7 +39,6 @@ import {
   detectRelationFields,
   edgeWrites,
   encodeCursor,
-  entityWrites,
   evaluateFilter,
   execute,
   executeBatchGet,
@@ -54,10 +50,8 @@ import {
   executeQuery,
   from,
   getEdgeWrites,
-  getEntityWrites,
   getImplicitKeyFields,
   hydrate,
-  identity,
   isCommandModelContract,
   isCommandPlan,
   isContractComposeNode,
@@ -66,23 +60,17 @@ import {
   isContractKeyRef,
   isContractParamRef,
   isEdgeWritesDefinition,
-  isEntityWritesDefinition,
-  isLifecycleContract,
-  isMaintainTrigger,
   isMutationFragment,
   isMutationInputRef,
   isPlannedCommandMethod,
   isQueryModelContract,
   isSelectBuilder,
   isTransactionRef,
-  lifecyclePhaseForIntent,
-  maintainTrigger,
   mapWithConcurrency,
   mintContractKeyFieldRef,
   mintContractParamRef,
   mutation,
   plan,
-  preview,
   publicCommandModel,
   publicQueryModel,
   query,
@@ -91,11 +79,23 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-QEOFIXTN.js";
+} from "./chunk-VST3WOK3.js";
 import {
   CdcEmulator,
-  createCdcEmulator
-} from "./chunk-QQNP43JL.js";
+  InMemoryProjectionSink,
+  MAINT_OUTBOX_PK_PREFIX,
+  MaintenanceDrain,
+  ProjectionSinkDrain,
+  compareDesc,
+  createCdcEmulator,
+  createMaintenanceDrain,
+  createMaintenanceDrainHandler,
+  createProjectionSinkDrain,
+  createProjectionSinkHandler,
+  orderAndTrimCollection,
+  pathField,
+  projectFrom
+} from "./chunk-PNIZS37E.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -103,15 +103,19 @@ import {
   DEFAULT_MAX_ATTEMPTS,
   DEFAULT_RETRY_POLICY,
   DynamoExecutor,
+  ENTITY_WRITES_MARKER,
+  LIFECYCLE_CONTRACT_MARKER,
   Linter,
   MAX_TRANSACT_ITEMS,
   MetadataRegistry,
   RetryingExecutor,
   TableMapping,
   TransactionContext,
+  ViewRegistry,
   attachModelClass,
   buildConditionExpression,
   buildDeleteInput,
+  buildMaintenanceGraph,
   buildPutInput,
   buildUpdateExpression,
   buildUpdateInput,
@@ -120,31 +124,49 @@ import {
   commitTransaction,
   cond,
   createDefaultLinter,
+  defineProjection,
+  defineProjections,
+  defineVersioned,
+  defineView,
+  defineViews,
+  entityWrites,
   execItemKeySignature,
   executeDelete,
   executePut,
   executeTransaction,
   executeUpdate,
+  getEntityWrites,
   gsi,
   gsiAmbiguityRule,
+  identity,
   isColumn,
+  isEntityWritesDefinition,
   isKeySegment,
+  isLifecycleContract,
+  isMaintainTrigger,
   isParam,
+  isProjectionDefinition,
   isRawCondition,
   isRetryableError,
   isRetryableTransactionCancellation,
+  isViewDefinition,
   k,
   key,
+  lifecyclePhaseForIntent,
+  maintainTrigger,
   missingGsiRule,
   noScanRule,
   param,
+  preview,
   relationDepthRule,
   requireLimitRule,
   resolveConditionTree,
   resolveKey,
   resolveModelClass,
-  serializeFieldValue
-} from "./chunk-6AIAHP3A.js";
+  segmentFieldNames,
+  serializeFieldValue,
+  whenMember
+} from "./chunk-YIXXTGZ6.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -955,6 +977,360 @@ var queryBoundaryRule = {
   }
 };
 
+// src/relation/maintenance-rebuild.ts
+function toClass(m) {
+  try {
+    return resolveModelClass(m);
+  } catch {
+    return m;
+  }
+}
+var MaintenanceRebuilder = class {
+  graph;
+  constructor(opts = {}) {
+    const classes = (opts.models ?? []).map(toClass);
+    const views = opts.views ?? [];
+    const allClasses = [...classes, ...views.map((v) => v.viewClass)];
+    const scoped = allClasses.length > 0 ? new Map(allClasses.map((c) => [c, MetadataRegistry.get(c)])) : void 0;
+    this.graph = buildMaintenanceGraph(scoped, views);
+  }
+  /**
+   * Re-derive the materialized value for one owner row × maintainer from the source
+   * rows and report whether it differs from what the owner row currently stores. Does
+   * NOT write anything (a read-only drift probe).
+   *
+   * @param owner The owner model class declaring the maintainer.
+   * @param relationProperty The relation / `@aggregate` property the value lives under.
+   * @param ownerKeyInput The owner row's key input (e.g. `{ threadId: 't1' }`).
+   */
+  async detectDrift(owner, relationProperty, ownerKeyInput) {
+    const { item, ownerMeta, ownerKey } = this.resolve(owner, relationProperty);
+    const expected = await this.recompute(item, ownerMeta, ownerKeyInput);
+    const ownerRow = await this.readOwnerRow(ownerMeta, ownerKey(ownerKeyInput));
+    const actual = this.actualValue(item.effect, ownerRow);
+    const ownerAbsentAndEmpty = ownerRow === void 0 && isEmptyMaintained(item.effect, expected);
+    return {
+      relationProperty,
+      ownerEntity: item.ownerEntity,
+      ownerKey: ownerKey(ownerKeyInput),
+      kind: item.effect.kind,
+      drifted: !ownerAbsentAndEmpty && !deepEqual(normalize(expected), normalize(actual)),
+      expected,
+      actual
+    };
+  }
+  /**
+   * Re-derive the materialized value for one owner row × maintainer from the source
+   * rows and WRITE the absolute re-derived value onto the owner row when it drifts (or
+   * always, when `force`). Returns the drift verdict plus whether a repair write ran.
+   *
+   * @param options.force Write even when no drift is detected (default: write only on drift).
+   */
+  async rebuild(owner, relationProperty, ownerKeyInput, options = {}) {
+    const report = await this.detectDrift(owner, relationProperty, ownerKeyInput);
+    if (!report.drifted && options.force !== true) {
+      return { ...report, repaired: false };
+    }
+    const { item, ownerMeta } = this.resolve(owner, relationProperty);
+    await this.writeValue(item.effect, ownerMeta, report.ownerKey, report.expected);
+    return { ...report, repaired: true };
+  }
+  /** Resolve an owner model + property to its {@link MaintainItem} + owner-key builder. */
+  resolve(owner, relationProperty) {
+    const ownerClass = toClass(owner);
+    const ownerMeta = MetadataRegistry.get(ownerClass);
+    const item = this.graph.items.find(
+      (i) => i.relationProperty === relationProperty && (i.ownerClass === ownerClass || i.ownerClass.name === ownerClass.name)
+    );
+    if (item === void 0) {
+      throw new Error(
+        `Maintenance rebuild: no maintainer found for property '${relationProperty}' on '${ownerClass.name}'. The rebuilder repairs declared \`maintainedOn\` maintainers (snapshot / collection / counter); '${relationProperty}' declares none, or its model is not in this rebuilder's scope.`
+      );
+    }
+    const ownerKey = (input) => {
+      const { Key } = buildDeleteInput(
+        ownerClass,
+        input
+      );
+      return Key;
+    };
+    return { item, ownerMeta, ownerKey };
+  }
+  /**
+   * Scan every source row bound to this owner row and re-derive the maintained value:
+   *
+   *  - **collection** — project each source row, order + trim by the SAME read-side
+   *    rules (`orderBy` / `orderDir` / `maxItems`) the drain uses, return the list;
+   *  - **snapshot** — project the single bound source row (or `undefined` when none);
+   *  - **counter `count`** — the COUNT of source rows (absolute, not an ADD);
+   *  - **counter `max`** — the maximum source value of the tracked field.
+   */
+  async recompute(item, _ownerMeta, ownerKeyInput) {
+    const effect = item.effect;
+    if (effect.kind === "membership") {
+      throw new Error(
+        `Maintenance rebuild: sparse-view membership maintainer '${item.relationProperty}' on '${item.ownerEntity}' is not yet supported by the rebuild planner (#133 follow-up). A membership row appears/disappears per source row by predicate; rebuild it by re-running the source events through the drain.`
+      );
+    }
+    const sources = await this.scanSourceRows(item, ownerKeyInput);
+    if (effect.kind === "collection") {
+      return this.recomputeCollection(effect, sources);
+    }
+    if (effect.kind === "snapshot") {
+      return this.recomputeSnapshot(effect, sources);
+    }
+    return this.recomputeCounter(effect, sources);
+  }
+  /**
+   * The source rows bound to one owner row. The maintenance key binding is
+   * `{ ownerField: '$.entity.<sourceField>' }` (the destination owner-key field ← the
+   * source row's field). INVERTED for a rebuild: the owner row supplies the value, and
+   * the source partition is queried for rows whose `<sourceField>` matches — exactly the
+   * set the live `hasMany` / `@aggregate` read aggregates. Queries the source via the
+   * same {@link plan} the read planner uses (a partition Query), paginating fully.
+   */
+  async scanSourceRows(item, ownerKeyInput) {
+    const sourceMeta = MetadataRegistry.get(item.sourceClass);
+    const queryKey = {};
+    for (const [ownerField, srcPath] of Object.entries(item.effect.keys)) {
+      const sourceField = pathField(srcPath);
+      queryKey[sourceField] = ownerKeyInput[ownerField];
+    }
+    const executor = ClientManager.getExecutor();
+    const rows = [];
+    let after;
+    do {
+      const execPlan = plan(sourceMeta, {
+        key: queryKey,
+        // Select all declared source fields so every projection / value source path
+        // and the sort-key leaf is present on the scanned row.
+        select: selectAll(sourceMeta),
+        consistentRead: false,
+        ...after ? { after } : {}
+      });
+      const op = execPlan.operations[0];
+      const res = await executor.execute(op);
+      for (const it of res.items) rows.push(it);
+      after = res.lastEvaluatedKey;
+    } while (after !== void 0);
+    return rows;
+  }
+  /** Re-derive a bounded collection: project, then order + trim by the read-side rules. */
+  recomputeCollection(effect, sources) {
+    if (effect.collection.orderBy === void 0 && effect.collection.maxItems !== void 0) {
+      throw new Error(
+        `Maintenance rebuild: relation '${effect.collection.field}' maintains an UNORDERED bounded collection (\`maxItems: ${effect.collection.maxItems}\` with no \`read.order\`). Its trimmed contents depend on stream ARRIVAL order, which the source rows do not record, so the value cannot be faithfully rebuilt from source \u2014 a rebuild would keep a different subset than the drain converged to. Declare a \`read.order\` on the relation so the maintained collection orders by the source's sort-key field (then the rebuild and the drain agree), or rebuild it unbounded.`
+      );
+    }
+    const projected = sources.map((row) => projectFrom(effect.project, row));
+    return orderAndTrimCollection(projected, effect.collection);
+  }
+  /**
+   * Re-derive a single-row snapshot. A snapshot mirrors ONE source row (a `belongsTo` /
+   * `hasOne`, normally 1:1). In the unusual case where MORE THAN ONE source row binds, the
+   * live single-value read takes the FIRST row in the source's natural query order
+   * (`ScanIndexForward`, default ASC = the smallest sort-key leaf), so re-derive the same
+   * row — {@link pickFirst} — for a verdict consistent with the live read. Returns
+   * `undefined` when no source row is bound (the snapshot should be absent).
+   */
+  recomputeSnapshot(effect, sources) {
+    if (sources.length === 0) return void 0;
+    const chosen = sources.length === 1 ? sources[0] : pickFirst(sources, this.sourceMetaOf(effect));
+    return projectFrom(effect.project, chosen);
+  }
+  /** The source entity metadata a maintain effect projects from (its relation target). */
+  sourceMetaOf(effect) {
+    const item = this.graph.items.find((i) => i.effect === effect);
+    return item ? MetadataRegistry.get(item.sourceClass) : void 0;
+  }
+  /** Re-derive a counter: the absolute COUNT of source rows, or the MAX of the tracked field. */
+  recomputeCounter(effect, sources) {
+    if (effect.value.op === "count") {
+      return sources.length;
+    }
+    const field2 = effect.value.field;
+    let best;
+    for (const row of sources) {
+      const v = row[field2];
+      if (v === void 0 || v === null) continue;
+      if (best === void 0 || compareDesc(v, best) < 0) best = v;
+    }
+    return best;
+  }
+  /** Read the owner row (consistent) for the drift comparison / actual value. */
+  async readOwnerRow(ownerMeta, ownerKey) {
+    const res = await ClientManager.getExecutor().execute({
+      type: "GetItem",
+      tableName: TableMapping.resolve(ownerMeta.tableName),
+      keyCondition: ownerKey,
+      consistentRead: true
+    });
+    return res.items[0];
+  }
+  /** The value currently stored on the owner row for this maintainer. */
+  actualValue(effect, ownerRow) {
+    if (ownerRow === void 0) return void 0;
+    if (effect.kind === "collection") {
+      return ownerRow[effect.collection.field];
+    }
+    if (effect.kind === "counter") {
+      return ownerRow[effect.attribute];
+    }
+    const out = {};
+    let anyPresent = false;
+    for (const attr of Object.keys(effect.project)) {
+      if (Object.prototype.hasOwnProperty.call(ownerRow, attr)) {
+        out[attr] = ownerRow[attr];
+        anyPresent = true;
+      }
+    }
+    return anyPresent ? out : void 0;
+  }
+  /** Write the re-derived ABSOLUTE value onto the owner row (the repair). */
+  async writeValue(effect, ownerMeta, ownerKey, expected) {
+    const TableName = TableMapping.resolve(ownerMeta.tableName);
+    const executor = ClientManager.getExecutor();
+    if (effect.kind === "collection") {
+      await executor.update({
+        TableName,
+        Key: ownerKey,
+        UpdateExpression: "SET #c = :list",
+        ExpressionAttributeNames: { "#c": effect.collection.field },
+        ExpressionAttributeValues: { ":list": expected ?? [] }
+      });
+      return;
+    }
+    if (effect.kind === "counter") {
+      if (expected === void 0 || expected === null) {
+        if (effect.value.op === "count") {
+          await executor.update({
+            TableName,
+            Key: ownerKey,
+            UpdateExpression: "SET #a = :v",
+            ExpressionAttributeNames: { "#a": effect.attribute },
+            ExpressionAttributeValues: { ":v": 0 }
+          });
+        } else {
+          await executor.update({
+            TableName,
+            Key: ownerKey,
+            UpdateExpression: "REMOVE #a",
+            ExpressionAttributeNames: { "#a": effect.attribute }
+          });
+        }
+        return;
+      }
+      await executor.update({
+        TableName,
+        Key: ownerKey,
+        UpdateExpression: "SET #a = :v",
+        ExpressionAttributeNames: { "#a": effect.attribute },
+        ExpressionAttributeValues: { ":v": expected }
+      });
+      return;
+    }
+    if (expected === void 0) {
+      const names2 = {};
+      const removes = [];
+      let i2 = 0;
+      for (const attr of Object.keys(effect.project)) {
+        names2[`#m${i2}`] = attr;
+        removes.push(`#m${i2}`);
+        i2 += 1;
+      }
+      if (removes.length === 0) return;
+      await executor.update({
+        TableName,
+        Key: ownerKey,
+        UpdateExpression: `REMOVE ${removes.join(", ")}`,
+        ExpressionAttributeNames: names2
+      });
+      return;
+    }
+    const projection = expected;
+    const names = {};
+    const values = {};
+    const sets = [];
+    let i = 0;
+    for (const [attr, value] of Object.entries(projection)) {
+      names[`#m${i}`] = attr;
+      values[`:m${i}`] = value;
+      sets.push(`#m${i} = :m${i}`);
+      i += 1;
+    }
+    if (sets.length === 0) return;
+    await executor.update({
+      TableName,
+      Key: ownerKey,
+      UpdateExpression: `SET ${sets.join(", ")}`,
+      ExpressionAttributeNames: names,
+      ExpressionAttributeValues: values
+    });
+  }
+};
+function selectAll(meta) {
+  const select = {};
+  for (const f of meta.fields) select[f.propertyName] = true;
+  return select;
+}
+function pickFirst(sources, sourceMeta) {
+  const skFields = sourceMeta?.primaryKey ? segmentFieldNames(sourceMeta.primaryKey.segmented.skSegments) : [];
+  const orderField = skFields[skFields.length - 1];
+  if (orderField === void 0) return sources[0];
+  return [...sources].sort((a, b) => compareDesc(b[orderField], a[orderField]))[0];
+}
+function normalize(value) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value === "number") return value;
+  if (typeof value === "string" && /^-?\d+$/.test(value)) {
+    const n = Number(value);
+    if (Number.isSafeInteger(n)) return n;
+  }
+  if (Array.isArray(value)) return value.map(normalize);
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k2, v] of Object.entries(value)) {
+      const nv = normalize(v);
+      if (nv === void 0) continue;
+      out[k2] = nv;
+    }
+    return out;
+  }
+  return value;
+}
+function isEmptyMaintained(effect, expected) {
+  if (effect.kind === "collection") {
+    return Array.isArray(expected) && expected.length === 0;
+  }
+  if (effect.kind === "counter") {
+    return effect.value.op === "count" ? expected === 0 : expected === void 0 || expected === null;
+  }
+  return expected === void 0;
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === void 0 || b === void 0 || a === null || b === null) return a === b;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    if (ka.length !== kb.length) return false;
+    return ka.every(
+      (k2) => deepEqual(
+        a[k2],
+        b[k2]
+      )
+    );
+  }
+  return false;
+}
+function createMaintenanceRebuilder(opts = {}) {
+  return new MaintenanceRebuilder(opts);
+}
+
 // src/define/define.ts
 function collectParams(structure, out = {}) {
   if (structure === null || typeof structure !== "object") return out;
@@ -1170,15 +1546,21 @@ export {
   DynamoExecutor,
   EDGE_WRITES_MARKER,
   ENTITY_WRITES_MARKER,
+  InMemoryProjectionSink,
   LIFECYCLE_CONTRACT_MARKER,
   Linter,
+  MAINT_OUTBOX_PK_PREFIX,
   MAX_TRANSACT_ITEMS,
+  MaintenanceDrain,
+  MaintenanceRebuilder,
   MetadataRegistry,
   OLD_VALUE_NAMESPACE,
+  ProjectionSinkDrain,
   RetryingExecutor,
   SPEC_VERSION,
   TableMapping,
   TransactionContext,
+  ViewRegistry,
   aggregate,
   assertBundleSerializable,
   assertContractBoundaries,
@@ -1215,6 +1597,11 @@ export {
   count,
   createCdcEmulator,
   createDefaultLinter,
+  createMaintenanceDrain,
+  createMaintenanceDrainHandler,
+  createMaintenanceRebuilder,
+  createProjectionSinkDrain,
+  createProjectionSinkHandler,
   datetime,
   decodeCursor,
   decodePerKeyCursor,
@@ -1222,12 +1609,17 @@ export {
   defineDelete,
   defineList,
   definePlan,
+  defineProjection,
+  defineProjections,
   definePut,
   defineQueries,
   defineQuery,
   defineTransaction,
   defineTransactions,
   defineUpdate,
+  defineVersioned,
+  defineView,
+  defineViews,
   deriveEdgeWriteItems,
   deriveEdgeWriteItemsFor,
   deriveModelEdgeWriteItems,
@@ -1283,11 +1675,13 @@ export {
   isMutationInputRef,
   isParam,
   isPlannedCommandMethod,
+  isProjectionDefinition,
   isQueryModelContract,
   isRetryableError,
   isRetryableTransactionCancellation,
   isSelectBuilder,
   isTransactionRef,
+  isViewDefinition,
   k,
   key,
   lifecyclePhaseForIntent,
@@ -1323,5 +1717,6 @@ export {
   validateDepth,
   validateGsiAmbiguity,
   when,
+  whenMember,
   wholeKeysSentinel
 };

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { E as Executor, D as DynamoDBOperation, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, f as DDBModel, C as ChangeEvent } from '../types-xJRn5qkv.js';
+import { E as Executor, D as DynamoDBOperation, R as ReadExecOptions, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, e as BatchExecOptions, T as TransactWriteExecItem, M as ModelStatic, f as DDBModel, C as ChangeEvent } from '../types-DuJ08bgc.js';
 import '@aws-sdk/client-dynamodb';
 
 /**

package/dist/testing/index.js

@@ -1,12 +1,12 @@
 import {
   createCdcEmulator
-} from "../chunk-QQNP43JL.js";
+} from "../chunk-PNIZS37E.js";
 import {
   ClientManager,
   MetadataRegistry,
   TableMapping,
   resolveModelClass
-} from "../chunk-6AIAHP3A.js";
+} from "../chunk-YIXXTGZ6.js";
 
 // src/memory/memory-store.ts
 function deepClone(value) {