graphddb 0.4.3 → 0.5.1

package/dist/{chunk-G5RWWBAL.js → chunk-FI63YKK5.js}

@@ -11,8 +11,11 @@ import {
   buildConditionExpression,
   buildDeleteInput,
   buildMaintenanceGraph,
+  buildProject,
   buildPutInput,
   buildReadRuntime,
+  buildRelation,
+  buildSubscribeHandler,
   buildUpdateInput,
   buildWriteRuntime,
   captureWrite,
@@ -27,13 +30,18 @@ import {
   executeTransaction,
   executeUpdate,
   getEntityWrites,
+  hydrate,
   isColumn,
   isEntityWritesDefinition,
   isLifecycleContract,
   isParam,
   isRawCondition,
+  isSelectBuilder,
   lifecyclePhaseForIntent,
+  normalizeSelectSpec,
+  normalizeTopLevelSelect,
   param,
+  parseChange,
   pkTemplate,
   resolveKey,
   resolveModelClass,
@@ -42,7 +50,7 @@ import {
   serializeFieldValue,
   serializeRawCondition,
   skTemplate
-} from "./chunk-CPTV3H2U.js";
+} from "./chunk-B3GWIWT6.js";
 
 // src/spec/types.ts
 var SPEC_VERSION = "1.0";
@@ -129,7 +137,11 @@ function buildEntity(metadata) {
     key: buildKey(metadata.primaryKey),
     gsis: buildGsis(metadata),
     relations: buildRelations(metadata),
-    ...metadata.description !== void 0 ? { description: metadata.description } : {}
+    ...metadata.description !== void 0 ? { description: metadata.description } : {},
+    // TTL (issue #172, Epic #167 — C4): a physical-schema fact carried on the
+    // manifest so the CFn emitter can render `TimeToLiveSpecification`. Absent
+    // when no `@ttl` field is declared (byte-identical to the pre-#172 manifest).
+    ...metadata.ttlAttribute !== void 0 ? { ttlAttribute: metadata.ttlAttribute } : {}
   };
 }
 function buildManifest(registry = MetadataRegistry) {
@@ -140,12 +152,28 @@ function buildManifest(registry = MetadataRegistry) {
   }
   const entities = {};
   const tables = {};
+  const ttlByPhysicalTable = /* @__PURE__ */ new Map();
   for (const name of [...entitiesByName.keys()].sort()) {
     const metadata = entitiesByName.get(name);
     entities[name] = buildEntity(metadata);
+    const physicalName = TableMapping.resolve(metadata.tableName);
     tables[metadata.tableName] = {
-      physicalName: TableMapping.resolve(metadata.tableName)
+      physicalName
     };
+    if (metadata.ttlAttribute !== void 0) {
+      const existing = ttlByPhysicalTable.get(physicalName);
+      if (existing && existing.attr !== metadata.ttlAttribute) {
+        throw new Error(
+          `Manifest build: physical table '${physicalName}' has more than one TTL attribute \u2014 entity '${existing.entity}' declares \`@ttl\` on '${existing.attr}' and entity '${name}' on '${metadata.ttlAttribute}'. DynamoDB allows exactly one TTL attribute per table; align the \`@ttl\` attribute across all entities sharing this table (or drop one).`
+        );
+      }
+      if (!existing) {
+        ttlByPhysicalTable.set(physicalName, {
+          entity: name,
+          attr: metadata.ttlAttribute
+        });
+      }
+    }
   }
   return {
     version: SPEC_VERSION,
@@ -154,79 +182,6 @@ function buildManifest(registry = MetadataRegistry) {
   };
 }
 
-// src/types/select-builder.ts
-var SELECT_BUILDER = /* @__PURE__ */ Symbol.for("graphddb.selectBuilder");
-var SELECT_SPEC = /* @__PURE__ */ Symbol.for("graphddb.selectSpec");
-
-// src/select/builder.ts
-var BuilderImpl = class _BuilderImpl {
-  [SELECT_BUILDER] = true;
-  /** The resolved spec, exposed (non-method) so normalizers can read it. */
-  [SELECT_SPEC];
-  constructor(spec) {
-    this[SELECT_SPEC] = spec;
-  }
-  clone(patch) {
-    return new _BuilderImpl({ ...this[SELECT_SPEC], ...patch });
-  }
-  filter(filter) {
-    return this.clone({ filter });
-  }
-  limit(limit) {
-    return this.clone({ limit });
-  }
-  after(cursor) {
-    return this.clone({ after: cursor });
-  }
-  order(order) {
-    return this.clone({ order });
-  }
-};
-function isSelectBuilder(value) {
-  return typeof value === "object" && value !== null && value[SELECT_BUILDER] === true;
-}
-function fromBuilder(value) {
-  const spec = value[SELECT_SPEC];
-  return {
-    select: spec.select,
-    filter: spec.filter,
-    limit: spec.limit,
-    after: spec.after,
-    order: spec.order
-  };
-}
-function normalizeSelectSpec(value) {
-  if (isSelectBuilder(value)) {
-    return fromBuilder(value);
-  }
-  const obj = value;
-  return {
-    select: obj.select,
-    filter: obj.filter,
-    limit: obj.limit,
-    after: obj.after,
-    order: obj.order
-  };
-}
-function normalizeTopLevelSelect(value) {
-  if (isSelectBuilder(value)) {
-    return fromBuilder(value);
-  }
-  return { select: value ?? {} };
-}
-function buildProject(select) {
-  return new BuilderImpl({
-    [SELECT_BUILDER]: true,
-    select
-  });
-}
-function buildRelation(select) {
-  return new BuilderImpl({
-    [SELECT_BUILDER]: true,
-    select
-  });
-}
-
 // src/relation/detect.ts
 function isRelationSpec(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -706,80 +661,6 @@ async function execute(operation, options) {
   return ClientManager.getExecutor().execute(operation, options);
 }
 
-// src/hydrator/hydrator.ts
-function hydrate(rawItems, select, metadata, updatable = false) {
-  return rawItems.map((item) => hydrateItem(item, select, metadata, updatable));
-}
-function hydrateItem(raw, select, metadata, updatable = false) {
-  const fieldMap = new Map(
-    metadata.fields.map((f) => [f.propertyName, f])
-  );
-  const embeddedMap = new Map(
-    metadata.embeddedFields.map((e) => [e.propertyName, e])
-  );
-  const result = {};
-  for (const [fieldName, selectValue] of Object.entries(select)) {
-    if (selectValue === true) {
-      const value = raw[fieldName];
-      if (value !== void 0) {
-        const fieldMeta = fieldMap.get(fieldName);
-        result[fieldName] = deserializeValue(value, fieldMeta);
-      }
-    } else if (typeof selectValue === "object" && selectValue !== null) {
-      if ("select" in selectValue || isSelectBuilder(selectValue)) {
-        continue;
-      }
-      const rawEmb = raw[fieldName];
-      if (rawEmb && typeof rawEmb === "object") {
-        result[fieldName] = hydrateEmbedded(
-          rawEmb,
-          selectValue,
-          metadata,
-          fieldName
-        );
-      }
-    }
-  }
-  if (updatable) {
-    attachHiddenKey(result, raw);
-  }
-  return result;
-}
-function hydrateEmbedded(raw, select, _metadata, _fieldName) {
-  const result = {};
-  for (const [key, selectValue] of Object.entries(select)) {
-    if (selectValue === true) {
-      if (raw[key] !== void 0) {
-        result[key] = raw[key];
-      }
-    } else if (typeof selectValue === "object" && selectValue !== null && !("select" in selectValue)) {
-      const nested = raw[key];
-      if (nested && typeof nested === "object") {
-        result[key] = hydrateEmbedded(
-          nested,
-          selectValue,
-          _metadata,
-          key
-        );
-      }
-    }
-  }
-  return result;
-}
-function deserializeValue(value, fieldMeta) {
-  if (!fieldMeta) return value;
-  if (fieldMeta.options?.deserialize) {
-    return fieldMeta.options.deserialize(value);
-  }
-  if (fieldMeta.options?.format === "datetime" && typeof value === "string") {
-    return new Date(value);
-  }
-  if (fieldMeta.options?.format === "date" && typeof value === "string") {
-    return /* @__PURE__ */ new Date(value + "T00:00:00.000Z");
-  }
-  return value;
-}
-
 // src/pagination/cursor.ts
 function encodeCursor(lastEvaluatedKey) {
   const json = JSON.stringify(lastEvaluatedKey);
@@ -3096,6 +2977,58 @@ var DDBModel = class {
   static mutate(envelope, options) {
     return executeWriteEnvelope(envelope, options);
   }
+  /**
+   * Parse a single CDC {@link ChangeEvent} into the `[oldRecord, newRecord]` tuple
+   * for THIS model (issue #153 — the pure `(event) => [old, new]` typed mapper).
+   * It reuses the read path's `hydrate` on `oldImage` / `newImage` (ISO 8601 →
+   * `Date` for `@datetime`, embedded reconstruction) and returns typed instances of
+   * this model — **all fields**, no projection (narrowing does not reduce cost; the
+   * image is already on the stream).
+   *
+   * Routing + parse in one call: an event for a DIFFERENT model returns
+   * `[null, null]` (a valid event for this model always has ≥1 non-null side, so
+   * `[null, null]` is an unambiguous "not for this class" signal — no separate
+   * `owns()` guard). The present side per event kind mirrors DynamoDB Streams:
+   * INSERT → `[null, new]`, MODIFY → `[old, new]`, REMOVE → `[old, null]`.
+   *
+   * Only callable on a `@cdcProjected` model — the generated {@link CdcModelRegistry}
+   * types this at the `subscribe` surface, and at runtime a non-`@cdcProjected` model
+   * throws (loudly, never silently returning `[null, null]`, which would masquerade
+   * as a routing miss). Delivery / sink writes / dedup are the consumer's, outside
+   * this boundary (see `docs/cdc-projection.md`).
+   */
+  static fromChange(event) {
+    const modelClass = this;
+    const metadata = MetadataRegistry.get(modelClass);
+    if (!metadata.cdcProjected) {
+      throw new Error(
+        `${modelClass.name}.fromChange: model '${modelClass.name}' is not @cdcProjected, so its change events cannot be parsed. Add @cdcProjected() to the model.`
+      );
+    }
+    return parseChange(event, metadata, modelClass.name, modelClass);
+  }
+  /**
+   * Build a batch CDC {@link ChangeHandler} from an envelope-style handler map keyed
+   * by model name (issue #153 — the GraphQL query/mutation/**subscription** trio's
+   * third sibling). Unlike `query` / `mutate`, `subscribe` DOES NOT subscribe and
+   * does not hit DynamoDB: it *returns* a `(batch) => Promise<BatchResult>` the
+   * consumer mounts on their own stream source (the CDC emulator locally, DynamoDB
+   * Streams → Lambda in production) — delivery lives outside the boundary.
+   *
+   * The returned handler loops the batch, routes each event to its owning model by
+   * `event.model` / `keys.pk`, typed-parses via that model's `fromChange`, calls the
+   * matching handler, and — if a handler throws — records the event's
+   * `sequenceNumber` into `batchItemFailures` (the `ReportBatchItemFailures`
+   * redelivery protocol) and continues. It NEVER writes a sink and NEVER dedups
+   * (both are consumer concerns). Handler keys are constrained to the generated
+   * {@link CdcModelRegistry} (`@cdcProjected` models only); a key that is not a
+   * registered `@cdcProjected` model throws at build time.
+   */
+  static subscribe(handlers) {
+    return buildSubscribeHandler(
+      handlers
+    );
+  }
   /**
    * Multi-key, multi-model batch read. Each {@link BatchGetRequest} contributes its
    * keys to a chunked `BatchGetItem` per physical table; results are re-grouped by
@@ -7002,8 +6935,6 @@ export {
   SPEC_VERSION,
   MARKER_ROW_ENTITY,
   buildManifest,
-  isSelectBuilder,
-  normalizeSelectSpec,
   detectRelationFields,
   getImplicitKeyFields,
   buildProjection,
@@ -7011,7 +6942,6 @@ export {
   evaluateFilter,
   plan,
   execute,
-  hydrate,
   encodeCursor,
   decodeCursor,
   executeListInternal,