graphddb 0.3.0 → 0.4.0

package/dist/{chunk-QQNP43JL.js → chunk-GWFZVNAV.js}

@@ -1,7 +1,13 @@
 import {
   ChangeCaptureRegistry,
+  ClientManager,
+  MetadataRegistry,
+  buildConditionExpression,
+  buildDeleteInput,
+  buildMaintenanceGraph,
+  buildPutInput,
   resolveModelClass
-} from "./chunk-6AIAHP3A.js";
+} from "./chunk-72VZYOSG.js";
 
 // src/cdc/prng.ts
 var SeededRandom = class {
@@ -455,7 +461,346 @@ function createCdcEmulator(opts = {}) {
   return new CdcEmulator(opts);
 }
 
+// src/relation/maintenance-projection.ts
+var PATH_FIELD_RE = /^\$\.(?:entity|input)\.([A-Za-z_$][\w$]*)$/;
+function pathField(path) {
+  const m = PATH_FIELD_RE.exec(path);
+  if (m !== null) return m[1];
+  return path;
+}
+function applyTransform(op, args, value) {
+  if (op === "identity") return value;
+  if (op === "preview") {
+    const n = args[0];
+    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+      throw new Error(
+        `maintenance projection: a 'preview' projection has a non-positive-integer length bound (${JSON.stringify(n)}).`
+      );
+    }
+    if (value === null || value === void 0) return value;
+    return String(value).slice(0, n);
+  }
+  throw new Error(`maintenance projection: unknown projection transform op '${op}'.`);
+}
+function projectFrom(project, source) {
+  const out = {};
+  for (const [attr, transform] of Object.entries(project)) {
+    const field = pathField(transform.path);
+    out[attr] = applyTransform(transform.op, transform.args, source[field]);
+  }
+  return out;
+}
+function compareDesc(a, b) {
+  if (a === b) return 0;
+  if (a === void 0 || a === null) return 1;
+  if (b === void 0 || b === null) return -1;
+  return a > b ? -1 : 1;
+}
+function orderAndTrimCollection(items, collection) {
+  let next = [...items];
+  const orderBy = collection.orderBy;
+  if (orderBy !== void 0) {
+    const orderField = pathField(orderBy);
+    const dir = collection.orderDir ?? "DESC";
+    next.sort(
+      (a, b) => dir === "ASC" ? compareDesc(b[orderField], a[orderField]) : compareDesc(a[orderField], b[orderField])
+    );
+    if (collection.maxItems !== void 0 && next.length > collection.maxItems) {
+      next = next.slice(0, collection.maxItems);
+    }
+  } else if (collection.maxItems !== void 0 && next.length > collection.maxItems) {
+    next = next.slice(next.length - collection.maxItems);
+  }
+  return next;
+}
+function collectionIdentityAttr(effect) {
+  return Object.keys(effect.project)[0];
+}
+
+// src/cdc/maintenance-drain.ts
+var MAINT_OUTBOX_PK_PREFIX = "OUTBOX#MAINT#";
+var OWNER_ATTR = "__maintOwner__";
+var RELATION_ATTR = "__maintRelation__";
+var TRIGGER_ATTR = "__maintTrigger__";
+function ownerKey(ownerClass, effect, source) {
+  const keyInput = {};
+  for (const [ownerField, srcPath] of Object.entries(effect.keys)) {
+    keyInput[ownerField] = source[pathField(srcPath)];
+  }
+  const { TableName, Key } = buildDeleteInput(
+    ownerClass,
+    keyInput
+  );
+  return { TableName, Key };
+}
+var MaintenanceDrain = class {
+  graph;
+  /** Owner entity name → its model class (for the owner-row key derivation). */
+  ownerByName = /* @__PURE__ */ new Map();
+  /** Per-event-id de-dup within a single handler invocation (at-least-once). */
+  appliedSeq = /* @__PURE__ */ new Set();
+  /** Count of owner-row writes applied (test/diagnostic). */
+  applied = 0;
+  constructor(opts = {}) {
+    const classes = (opts.models ?? []).map((m) => {
+      try {
+        return resolveModelClass(m);
+      } catch {
+        return m;
+      }
+    });
+    const explicitViews = opts.views;
+    const allClasses = [
+      ...classes,
+      ...(explicitViews ?? []).map((v) => v.viewClass)
+    ];
+    const scoped = allClasses.length > 0 ? new Map(allClasses.map((c) => [c, MetadataRegistry.get(c)])) : void 0;
+    this.graph = buildMaintenanceGraph(scoped, explicitViews);
+    for (const item of this.graph.items) {
+      this.ownerByName.set(item.ownerEntity, item.ownerClass);
+    }
+  }
+  /** The CDC {@link ChangeHandler} to subscribe to an emulator / Streams source. */
+  handler = async (batch) => {
+    const failures = [];
+    for (const event of batch.records) {
+      if (!event.keys.pk.startsWith(MAINT_OUTBOX_PK_PREFIX)) continue;
+      if (event.eventName === "REMOVE") continue;
+      const image = event.newImage;
+      if (image === void 0) continue;
+      try {
+        await this.applyOne(event, image);
+      } catch (e) {
+        failures.push(event.sequenceNumber);
+        if (process.env.GRAPHDDB_DRAIN_DEBUG) {
+          console.error("DRAIN ERROR", event.keys.pk, e);
+        }
+      }
+    }
+    return failures.length > 0 ? { batchItemFailures: failures } : {};
+  };
+  /** Resolve one maintenance-outbox event to its effect and apply the owner-row write. */
+  async applyOne(event, image) {
+    const eventId = `${event.shardId}#${event.sequenceNumber}`;
+    if (this.appliedSeq.has(eventId)) return;
+    const ownerEntity = String(image[OWNER_ATTR] ?? "");
+    const relationProperty = String(image[RELATION_ATTR] ?? "");
+    const trigger = String(image[TRIGGER_ATTR] ?? "");
+    const item = this.resolve(trigger, ownerEntity, relationProperty);
+    if (item === void 0) {
+      this.appliedSeq.add(eventId);
+      return;
+    }
+    const effect = item.effect;
+    const ownerClass = item.ownerClass;
+    const { TableName, Key } = ownerKey(ownerClass, effect, image);
+    const executor = ClientManager.getExecutor();
+    if (effect.kind === "counter") {
+      if (effect.value.op === "count") {
+        await executor.update({
+          TableName,
+          Key,
+          UpdateExpression: "ADD #a0 :a0",
+          ExpressionAttributeNames: { "#a0": effect.attribute },
+          ExpressionAttributeValues: { ":a0": effect.delta ?? 0 }
+        });
+      } else {
+        await this.applyMax(TableName, Key, effect.attribute, effect.value.field, image);
+      }
+    } else if (effect.kind === "membership") {
+      await this.applyMembership(TableName, Key, item, effect, image);
+    } else if (effect.kind === "snapshot") {
+      const projection = projectFrom(effect.project, image);
+      await this.applySnapshot(TableName, Key, projection);
+    } else {
+      await this.applyCollection(TableName, Key, item, image);
+    }
+    this.appliedSeq.add(eventId);
+    this.applied += 1;
+  }
+  /** Resolve a maintenance-outbox event back to the declared {@link MaintainItem}. */
+  resolve(trigger, ownerEntity, relationProperty) {
+    for (const item of this.graph.effectsFor(trigger)) {
+      const itemOwnerName = item.ownerClass.name;
+      if ((itemOwnerName === ownerEntity || item.ownerEntity === ownerEntity) && item.relationProperty === relationProperty) {
+        return item;
+      }
+    }
+    return void 0;
+  }
+  /** A `snapshot` SET of each projected attribute onto the owner row (idempotent). */
+  async applySnapshot(TableName, Key, projection) {
+    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 ClientManager.getExecutor().update({
+      TableName,
+      Key,
+      UpdateExpression: `SET ${sets.join(", ")}`,
+      ExpressionAttributeNames: names,
+      ExpressionAttributeValues: values
+    });
+  }
+  /**
+   * A sparse-view **membership** write (#133): evaluate the membership predicate against
+   * the source image; PUT the view row (its projection + key fields) when the predicate
+   * holds, DELETE it when it flips false. A source `removed` event always deletes (the
+   * source no longer exists, so its view row must disappear regardless of the predicate).
+   *
+   * Both ops are idempotent under at-least-once redelivery: a repeated PUT writes the same
+   * row, a repeated DELETE is a no-op. The view row is keyed by the source identity
+   * (`effect.keys`), so the PUT/DELETE always targets the SAME physical row the predicate
+   * gates.
+   */
+  async applyMembership(TableName, Key, item, effect, image) {
+    void TableName;
+    const ownerClass = item.ownerClass;
+    const isRemoved = item.trigger.endsWith(".removed");
+    const holds = !isRemoved && evaluateMembership(effect.predicate, image);
+    if (holds) {
+      const keyInput2 = {};
+      for (const [ownerField, srcPath] of Object.entries(effect.keys)) {
+        keyInput2[ownerField] = image[pathField(srcPath)];
+      }
+      const projection = projectFrom(effect.project, image);
+      const putItem = { ...keyInput2, ...projection };
+      const putInput = buildPutInput(ownerClass, putItem);
+      await ClientManager.getExecutor().put(putInput);
+      return;
+    }
+    const keyInput = {};
+    for (const [ownerField, srcPath] of Object.entries(effect.keys)) {
+      keyInput[ownerField] = image[pathField(srcPath)];
+    }
+    const deleteInput = buildDeleteInput(ownerClass, keyInput);
+    await ClientManager.getExecutor().delete(deleteInput);
+  }
+  /**
+   * A running `max`: read the owner row, and `SET` the attribute to the source value
+   * only when it is greater (or absent). Implemented as a conditional update so a
+   * redelivered / out-of-order older value never regresses the stored max — idempotent
+   * and commutative under at-least-once delivery.
+   */
+  async applyMax(TableName, Key, attribute, sourceField, image) {
+    const candidate = image[sourceField];
+    if (candidate === void 0 || candidate === null) return;
+    const cond = buildConditionExpression({ attributeNotExists: attribute });
+    try {
+      await ClientManager.getExecutor().update({
+        TableName,
+        Key,
+        UpdateExpression: "SET #a0 = :v",
+        ConditionExpression: `attribute_not_exists(#a0) OR #a0 < :v`,
+        ExpressionAttributeNames: { "#a0": attribute },
+        ExpressionAttributeValues: { ":v": candidate }
+      });
+    } catch (e) {
+      void cond;
+      if (isConditionFailure(e)) return;
+      throw e;
+    }
+  }
+  /**
+   * A bounded `collection`: read the current list, apply the event (append for a
+   * `created`/`updated` source, splice for a `removed`), de-duplicate by the projected
+   * identity key, order by `orderBy` (in `orderDir`, default DESC), trim to `maxItems`, and write the whole
+   * list back. The read-modify-write is exactly what a single synchronous
+   * `UpdateExpression` cannot do — the reason a bounded/ordered collection is a stream
+   * maintainer (Phase 1 sync was append-only).
+   */
+  async applyCollection(TableName, Key, item, image) {
+    const effect = item.effect;
+    if (effect.kind !== "collection") return;
+    const field = effect.collection.field;
+    const executor = ClientManager.getExecutor();
+    const res = await executor.execute({
+      type: "GetItem",
+      tableName: TableName,
+      keyCondition: Key,
+      consistentRead: true
+    });
+    const current = res.items[0];
+    const existing = Array.isArray(current?.[field]) ? [...current[field]] : [];
+    const projected = projectFrom(effect.project, image);
+    const idAttr = collectionIdentityAttr(effect);
+    const idOf = (row) => idAttr ? row[idAttr] : void 0;
+    const isRemoved = item.trigger.endsWith(".removed");
+    let next;
+    if (isRemoved) {
+      next = existing.filter((row) => idOf(row) !== idOf(projected));
+    } else {
+      next = existing.filter((row) => idOf(row) !== idOf(projected));
+      next.push(projected);
+    }
+    next = orderAndTrimCollection(next, effect.collection);
+    await executor.update({
+      TableName,
+      Key,
+      UpdateExpression: "SET #c = :list",
+      ExpressionAttributeNames: { "#c": field },
+      ExpressionAttributeValues: { ":list": next }
+    });
+  }
+  /** Owner-row writes applied so far (test/diagnostic). */
+  appliedCount() {
+    return this.applied;
+  }
+  /** Clear the per-delivery de-dup set + counters (test reset). */
+  reset() {
+    this.appliedSeq = /* @__PURE__ */ new Set();
+    this.applied = 0;
+  }
+};
+function evaluateMembership(predicate, image) {
+  const field = pathField(predicate.path);
+  const present = Object.prototype.hasOwnProperty.call(image, field);
+  const value = image[field];
+  switch (predicate.op) {
+    case "exists":
+      return present && value !== null && value !== void 0;
+    case "notExists":
+      return !present || value === null || value === void 0;
+    case "truthy":
+      return Boolean(value);
+    case "falsy":
+      return !value;
+    case "eq":
+      return value === predicate.value;
+    case "ne":
+      return value !== predicate.value;
+    default:
+      return false;
+  }
+}
+function isConditionFailure(e) {
+  const name = e?.name ?? "";
+  const msg = e instanceof Error ? e.message : String(e);
+  return name === "ConditionalCheckFailedException" || /ConditionalCheckFailed|condition/i.test(msg);
+}
+function createMaintenanceDrain(opts = {}) {
+  return new MaintenanceDrain(opts);
+}
+function createMaintenanceDrainHandler(opts = {}) {
+  return createMaintenanceDrain(opts).handler;
+}
+
 export {
   CdcEmulator,
-  createCdcEmulator
+  createCdcEmulator,
+  pathField,
+  projectFrom,
+  compareDesc,
+  orderAndTrimCollection,
+  MAINT_OUTBOX_PK_PREFIX,
+  MaintenanceDrain,
+  createMaintenanceDrain,
+  createMaintenanceDrainHandler
 };