graphddb 0.3.1 → 0.4.1

package/dist/index.js

@@ -79,23 +79,19 @@ import {
   validateDepth,
   when,
   wholeKeysSentinel
-} from "./chunk-VST3WOK3.js";
+} from "./chunk-G5RWWBAL.js";
 import {
   CdcEmulator,
-  InMemoryProjectionSink,
   MAINT_OUTBOX_PK_PREFIX,
   MaintenanceDrain,
-  ProjectionSinkDrain,
   compareDesc,
   createCdcEmulator,
   createMaintenanceDrain,
   createMaintenanceDrainHandler,
-  createProjectionSinkDrain,
-  createProjectionSinkHandler,
   orderAndTrimCollection,
   pathField,
   projectFrom
-} from "./chunk-PNIZS37E.js";
+} from "./chunk-BROCT574.js";
 import {
   BATCH_GET_MAX_KEYS,
   BATCH_WRITE_MAX_ITEMS,
@@ -111,7 +107,6 @@ import {
   RetryingExecutor,
   TableMapping,
   TransactionContext,
-  ViewRegistry,
   attachModelClass,
   buildConditionExpression,
   buildDeleteInput,
@@ -121,14 +116,10 @@ import {
   buildUpdateInput,
   collapseSameKeyItems,
   collectRawConditionParams,
+  collectViewDefinitions,
   commitTransaction,
   cond,
   createDefaultLinter,
-  defineProjection,
-  defineProjections,
-  defineVersioned,
-  defineView,
-  defineViews,
   entityWrites,
   execItemKeySignature,
   executeDelete,
@@ -145,11 +136,9 @@ import {
   isLifecycleContract,
   isMaintainTrigger,
   isParam,
-  isProjectionDefinition,
   isRawCondition,
   isRetryableError,
   isRetryableTransactionCancellation,
-  isViewDefinition,
   k,
   key,
   lifecyclePhaseForIntent,
@@ -164,9 +153,8 @@ import {
   resolveKey,
   resolveModelClass,
   segmentFieldNames,
-  serializeFieldValue,
-  whenMember
-} from "./chunk-YIXXTGZ6.js";
+  serializeFieldValue
+} from "./chunk-CPTV3H2U.js";
 
 // src/metadata/prefix.ts
 function derivePrefix(customPrefix, className) {
@@ -217,6 +205,7 @@ var pendingFields = [];
 var pendingEmbedded = [];
 var pendingRelations = [];
 var pendingAggregates = [];
+var pendingMaintainedFrom = [];
 function collectField(field2) {
   pendingFields.push(field2);
 }
@@ -229,6 +218,9 @@ function collectRelation(relation) {
 function collectAggregate(aggregate2) {
   pendingAggregates.push(aggregate2);
 }
+function collectMaintainedFrom(decl) {
+  pendingMaintainedFrom.push(decl);
+}
 function drainFields() {
   const result = pendingFields;
   pendingFields = [];
@@ -249,6 +241,11 @@ function drainAggregates() {
   pendingAggregates = [];
   return result;
 }
+function drainMaintainedFrom() {
+  const result = pendingMaintainedFrom;
+  pendingMaintainedFrom = [];
+  return result;
+}
 
 // src/decorators/model.ts
 function model(options) {
@@ -257,7 +254,19 @@ function model(options) {
     const embeddedFields = drainEmbedded();
     const relations = drainRelations();
     const aggregates = drainAggregates();
+    const maintainedFrom2 = drainMaintainedFrom();
     const prefix = derivePrefix(options.prefix, context.name);
+    const kind = options.kind ?? "entity";
+    if (kind === "entity" && maintainedFrom2.length > 0) {
+      throw new Error(
+        `@model on '${String(context.name)}': ${maintainedFrom2.length} \`@maintainedFrom\` declaration(s) are present but \`kind\` is 'entity' (the default). A maintained view must declare \`@model({ kind: 'materializedView' | 'sparseView' })\` \u2014 a plain entity does not carry view maintainers.`
+      );
+    }
+    if (kind !== "entity" && maintainedFrom2.length === 0) {
+      throw new Error(
+        `@model on '${String(context.name)}': \`kind: '${kind}'\` declares a maintained view but no \`@maintainedFrom(...)\` source is stacked. A view with no source is maintained by nothing \u2014 add at least one \`@maintainedFrom\` decorator.`
+      );
+    }
     MetadataRegistry.register(target, {
       tableName: options.table,
       prefix,
@@ -266,7 +275,10 @@ function model(options) {
       gsiDefinitions: [],
       relations,
       aggregates,
-      embeddedFields
+      embeddedFields,
+      kind,
+      ...options.description !== void 0 ? { description: options.description } : {},
+      maintainedFrom: maintainedFrom2
     });
   };
 }
@@ -336,7 +348,95 @@ function embedded(modelFactory) {
   };
 }
 
+// src/decorators/maintained-symbolic.ts
+var SOURCE_REF = /* @__PURE__ */ Symbol("graphddb:maintainedSourceRef");
+var SELF_REF = /* @__PURE__ */ Symbol("graphddb:maintainedSelfRef");
+function isSourceRef(value) {
+  return typeof value === "object" && value !== null && value[SOURCE_REF] === true;
+}
+function isSelfRef(value) {
+  return typeof value === "object" && value !== null && value[SELF_REF] === true;
+}
+function createSourceProxy() {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        let ref = cache.get(prop);
+        if (!ref) {
+          ref = { [SOURCE_REF]: true, field: prop, path: `$.entity.${prop}` };
+          cache.set(prop, ref);
+        }
+        return ref;
+      }
+    }
+  );
+}
+function createSelfProxy() {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        let ref = cache.get(prop);
+        if (!ref) {
+          ref = { [SELF_REF]: true, field: prop };
+          cache.set(prop, ref);
+        }
+        return ref;
+      }
+    }
+  );
+}
+
 // src/decorators/relation.ts
+function lowerVersionedProjectionValue(propertyName, attr, value) {
+  if (isSourceRef(value)) return identity(value.path);
+  if (value && typeof value === "object" && value.kind === "transform") {
+    return value;
+  }
+  throw new Error(
+    `@hasOne/@hasMany versioned relation '${propertyName}': projection target '${attr}' must be a \`source.<field>\` reference or a transform (e.g. \`preview(source.body, 120)\`), got ${JSON.stringify(value)}.`
+  );
+}
+function lowerVersionedOptions(propertyName, opts) {
+  if (!opts || typeof opts !== "object" || opts.pattern !== "versionedLatest" && opts.pattern !== "versionedHistory") {
+    throw new Error(
+      `@hasOne/@hasMany versioned relation '${propertyName}': the (self, source) => options callback must return \`{ pattern: 'versionedLatest' | 'versionedHistory', on, project }\`.`
+    );
+  }
+  if (!Array.isArray(opts.on) || opts.on.length === 0) {
+    throw new Error(
+      `@hasOne/@hasMany versioned relation '${propertyName}': \`on\` must be a non-empty array of lifecycle events (e.g. \`['created', 'updated']\`).`
+    );
+  }
+  const projectEntries = Object.entries(opts.project ?? {});
+  if (projectEntries.length === 0) {
+    throw new Error(
+      `@hasOne/@hasMany versioned relation '${propertyName}': \`project\` is empty \u2014 a versioned row with no captured attributes projects nothing.`
+    );
+  }
+  const project = {};
+  for (const [attr, value] of projectEntries) {
+    project[attr] = lowerVersionedProjectionValue(propertyName, attr, value);
+  }
+  return {
+    pattern: opts.pattern,
+    versioned: {
+      mode: opts.pattern === "versionedLatest" ? "latest" : "history",
+      on: [...opts.on],
+      project,
+      ...opts.consistency !== void 0 ? { consistency: opts.consistency } : {},
+      ...opts.updateMode !== void 0 ? { updateMode: opts.updateMode } : {}
+    }
+  };
+}
+function isVersionedCallback(arg) {
+  return typeof arg === "function";
+}
 var RESERVED_RELATION_PROPERTY_NAMES = /* @__PURE__ */ new Set([
   "items"
 ]);
@@ -347,15 +447,34 @@ function assertRelationPropertyNameAllowed(propertyName) {
     );
   }
 }
-function hasMany(targetFactory, keyBinding, options) {
+function hasMany(targetFactory, keyBindingOrCallback, options) {
   return function(_value, context) {
     const propertyName = String(context.name);
     assertRelationPropertyNameAllowed(propertyName);
+    if (isVersionedCallback(keyBindingOrCallback)) {
+      const opts = keyBindingOrCallback(
+        createSelfProxy(),
+        createSourceProxy()
+      );
+      if (opts.pattern !== "versionedHistory") {
+        throw new Error(
+          `@hasMany versioned relation '${propertyName}': a \`@hasMany\` maintains an append-only HISTORY, so its pattern must be 'versionedHistory' (got '${opts.pattern}'). Use \`@hasOne\` for 'versionedLatest' (the single overwritten pointer).`
+        );
+      }
+      collectRelation({
+        type: "hasMany",
+        propertyName,
+        targetFactory,
+        keyBinding: {},
+        options: lowerVersionedOptions(propertyName, opts)
+      });
+      return;
+    }
     collectRelation({
       type: "hasMany",
       propertyName,
       targetFactory,
-      keyBinding,
+      keyBinding: keyBindingOrCallback,
       options
     });
   };
@@ -373,15 +492,34 @@ function belongsTo(targetFactory, keyBinding, options) {
     });
   };
 }
-function hasOne(targetFactory, keyBinding) {
+function hasOne(targetFactory, keyBindingOrCallback) {
   return function(_value, context) {
     const propertyName = String(context.name);
     assertRelationPropertyNameAllowed(propertyName);
+    if (isVersionedCallback(keyBindingOrCallback)) {
+      const opts = keyBindingOrCallback(
+        createSelfProxy(),
+        createSourceProxy()
+      );
+      if (opts.pattern !== "versionedLatest") {
+        throw new Error(
+          `@hasOne versioned relation '${propertyName}': a \`@hasOne\` maintains a single LATEST pointer (overwritten per revision), so its pattern must be 'versionedLatest' (got '${opts.pattern}'). Use \`@hasMany\` for 'versionedHistory' (append-only per-version rows).`
+        );
+      }
+      collectRelation({
+        type: "hasOne",
+        propertyName,
+        targetFactory,
+        keyBinding: {},
+        options: lowerVersionedOptions(propertyName, opts)
+      });
+      return;
+    }
     collectRelation({
       type: "hasOne",
       propertyName,
       targetFactory,
-      keyBinding
+      keyBinding: keyBindingOrCallback
     });
   };
 }
@@ -409,6 +547,118 @@ function max(field2) {
   return { op: "max", field: field2 };
 }
 
+// src/decorators/maintained.ts
+function whenMember(operand, op, value) {
+  const raw = isSourceRef(operand) ? operand.path : operand;
+  const path = raw.startsWith("$.input.") || raw.startsWith("$.entity.") ? raw : `$.entity.${raw}`;
+  const needsValue = op === "eq" || op === "ne";
+  if (needsValue && value === void 0) {
+    throw new Error(
+      `whenMember(source.\u2026, '${op}', \u2026): the '${op}' op requires a comparand value (e.g. \`whenMember(source.status, '${op}', 'active')\`).`
+    );
+  }
+  return needsValue ? { path, op, value } : { path, op };
+}
+function lowerProjectionValue(modelName, attr, value) {
+  if (isSourceRef(value)) return identity(value.path);
+  if (value && typeof value === "object" && value.kind === "transform") {
+    return value;
+  }
+  throw new Error(
+    `@maintainedFrom on '${modelName}': projection target '${attr}' must be a \`source.<field>\` reference or a transform (e.g. \`preview(source.body, 120)\`), got ${JSON.stringify(value)}. A maintained projection captures only symbolic source references \u2014 a literal / computed value is not allowed.`
+  );
+}
+function lowerKeyBind(modelName, keyBind) {
+  const out = {};
+  const entries = Object.entries(keyBind);
+  if (entries.length === 0) {
+    throw new Error(
+      `@maintainedFrom on '${modelName}': \`keyBind\` is empty. The view-row key binding (view-key field \u2192 \`source.<field>\`) is required to resolve which view row a source event maintains.`
+    );
+  }
+  for (const [viewKeyField, ref] of entries) {
+    if (!isSourceRef(ref)) {
+      throw new Error(
+        `@maintainedFrom on '${modelName}': \`keyBind.${viewKeyField}\` must be a \`source.<field>\` reference (e.g. \`{ ${viewKeyField}: source.${viewKeyField} }\`), got ${JSON.stringify(ref)}.`
+      );
+    }
+    out[viewKeyField] = ref.path;
+  }
+  return out;
+}
+function maintainedFrom(source, callback) {
+  return function(target, context) {
+    const modelName = String(context.name ?? target.name ?? "(anonymous)");
+    const selfProxy = createSelfProxy();
+    const sourceProxy = createSourceProxy();
+    const opts = callback(selfProxy, sourceProxy);
+    if (!opts || typeof opts !== "object") {
+      throw new Error(
+        `@maintainedFrom on '${modelName}': the (self, source) => options callback must return an options object.`
+      );
+    }
+    if (!Array.isArray(opts.on) || opts.on.length === 0) {
+      throw new Error(
+        `@maintainedFrom on '${modelName}': \`on\` must be a non-empty array of lifecycle events (e.g. \`['created', 'removed']\`).`
+      );
+    }
+    for (const ev of opts.on) {
+      if (ev !== "created" && ev !== "updated" && ev !== "removed") {
+        throw new Error(
+          `@maintainedFrom on '${modelName}': \`on\` event ${JSON.stringify(ev)} is not one of 'created' / 'updated' / 'removed'.`
+        );
+      }
+    }
+    const keyBind = lowerKeyBind(modelName, opts.keyBind);
+    const projectEntries = Object.entries(opts.project ?? {});
+    if (projectEntries.length === 0) {
+      throw new Error(
+        `@maintainedFrom on '${modelName}': \`project\` is empty. A maintained view with no captured attributes projects nothing \u2014 declare a \`project\` map (e.g. \`{ title: source.title, textPreview: preview(source.body, 120) }\`).`
+      );
+    }
+    const project = {};
+    for (const [attr, value] of projectEntries) {
+      project[attr] = lowerProjectionValue(modelName, attr, value);
+    }
+    if (opts.collection && opts.when) {
+      throw new Error(
+        `@maintainedFrom on '${modelName}': a declaration carries both \`collection\` and \`when\`. They are mutually exclusive \u2014 a collection slice holds a maintained list; a membership (\`when\`) row appears/disappears as a whole.`
+      );
+    }
+    let collection;
+    if (opts.collection) {
+      const c = opts.collection;
+      if (!isSelfRef(c.field)) {
+        throw new Error(
+          `@maintainedFrom on '${modelName}': \`collection.field\` must be a \`self.<field>\` reference (the view attribute holding the list, e.g. \`self.latestPosts\`), got ${JSON.stringify(c.field)}.`
+        );
+      }
+      if (c.orderBy !== void 0 && !isSourceRef(c.orderBy)) {
+        throw new Error(
+          `@maintainedFrom on '${modelName}': \`collection.orderBy\` must be a \`source.<field>\` reference, got ${JSON.stringify(c.orderBy)}.`
+        );
+      }
+      collection = {
+        field: c.field.field,
+        ...c.maxItems !== void 0 ? { maxItems: c.maxItems } : {},
+        ...c.order !== void 0 ? { order: c.order } : {},
+        ...c.orderBy !== void 0 ? { orderBy: c.orderBy.path } : {}
+      };
+    }
+    const metadata = {
+      sourceFactory: source,
+      on: [...opts.on],
+      keyBind,
+      project,
+      ...collection ? { collection } : {},
+      ...opts.when ? { when: opts.when } : {},
+      ...opts.consistency !== void 0 ? { consistency: opts.consistency } : {},
+      ...opts.updateMode !== void 0 ? { updateMode: opts.updateMode } : {}
+    };
+    collectMaintainedFrom(metadata);
+  };
+}
+
 // src/operations/declarative-transaction.ts
 var PLACEHOLDER_RE = /\{[^{}]+\}/g;
 function resolveTemplate(template, params, element) {
@@ -989,10 +1239,13 @@ 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 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, views);
+    this.graph = buildMaintenanceGraph(scoped, explicitViews);
   }
   /**
    * Re-derive the materialized value for one owner row × maintainer from the source
@@ -1344,7 +1597,15 @@ function collectParams(structure, out = {}) {
   return out;
 }
 function descriptorFromParam(name, value, existing) {
-  const descriptor = value.literals === void 0 ? { kind: value.kind, required: true } : { kind: value.kind, literals: value.literals, required: true };
+  const descriptor = {
+    kind: value.kind,
+    ...value.literals !== void 0 ? { literals: value.literals } : {},
+    // Pure-documentation description (issue #154); carried through verbatim. Does
+    // not participate in the conflicting-kind check below (it is not part of the
+    // execution-relevant descriptor identity).
+    ...value.description !== void 0 ? { description: value.description } : {},
+    required: true
+  };
   if (existing !== void 0 && existing.kind !== descriptor.kind) {
     throw new Error(
       `Parameter '${name}' is declared with conflicting types ('${existing.kind}' and '${descriptor.kind}'). A parameter name must have a single type across a definition.`
@@ -1441,7 +1702,7 @@ function collectConditionTreeParams(obj, out) {
     }
   }
 }
-function makeDefinition(model2, operation, key2, select, changes, condition) {
+function makeDefinition(model2, operation, key2, select, changes, condition, description) {
   const params = collectParams(key2);
   if (changes !== void 0) collectParams(changes, params);
   collectConditionParams(condition, params);
@@ -1453,25 +1714,30 @@ function makeDefinition(model2, operation, key2, select, changes, condition) {
     select,
     changes,
     ...condition !== void 0 ? { condition } : {},
+    ...description !== void 0 ? { description } : {},
     params
   };
 }
-function defineQuery(model2, key2, select) {
+function defineQuery(model2, key2, select, options) {
   return makeDefinition(
     model2,
     "query",
     key2,
     select,
-    void 0
+    void 0,
+    void 0,
+    options?.description
   );
 }
-function defineList(model2, key2, select) {
+function defineList(model2, key2, select, options) {
   return makeDefinition(
     model2,
     "list",
     key2,
     select,
-    void 0
+    void 0,
+    void 0,
+    options?.description
   );
 }
 function definePut(model2, item, options) {
@@ -1481,7 +1747,8 @@ function definePut(model2, item, options) {
     item,
     void 0,
     void 0,
-    options?.condition
+    options?.condition,
+    options?.description
   );
 }
 function defineUpdate(model2, key2, changes, options) {
@@ -1491,7 +1758,8 @@ function defineUpdate(model2, key2, changes, options) {
     key2,
     void 0,
     changes,
-    options?.condition
+    options?.condition,
+    options?.description
   );
 }
 function defineDelete(model2, key2, options) {
@@ -1501,7 +1769,8 @@ function defineDelete(model2, key2, options) {
     key2,
     void 0,
     void 0,
-    options?.condition
+    options?.condition,
+    options?.description
   );
 }
 function defineQueries(definitions) {
@@ -1546,7 +1815,6 @@ export {
   DynamoExecutor,
   EDGE_WRITES_MARKER,
   ENTITY_WRITES_MARKER,
-  InMemoryProjectionSink,
   LIFECYCLE_CONTRACT_MARKER,
   Linter,
   MAINT_OUTBOX_PK_PREFIX,
@@ -1555,12 +1823,10 @@ export {
   MaintenanceRebuilder,
   MetadataRegistry,
   OLD_VALUE_NAMESPACE,
-  ProjectionSinkDrain,
   RetryingExecutor,
   SPEC_VERSION,
   TableMapping,
   TransactionContext,
-  ViewRegistry,
   aggregate,
   assertBundleSerializable,
   assertContractBoundaries,
@@ -1588,6 +1854,7 @@ export {
   buildUpdateInput,
   collectContractBoundaryViolations,
   collectContractN1Violations,
+  collectViewDefinitions,
   compileFilterExpression,
   compileFragment,
   compileMutationPlan,
@@ -1600,8 +1867,6 @@ export {
   createMaintenanceDrain,
   createMaintenanceDrainHandler,
   createMaintenanceRebuilder,
-  createProjectionSinkDrain,
-  createProjectionSinkHandler,
   datetime,
   decodeCursor,
   decodePerKeyCursor,
@@ -1609,17 +1874,12 @@ export {
   defineDelete,
   defineList,
   definePlan,
-  defineProjection,
-  defineProjections,
   definePut,
   defineQueries,
   defineQuery,
   defineTransaction,
   defineTransactions,
   defineUpdate,
-  defineVersioned,
-  defineView,
-  defineViews,
   deriveEdgeWriteItems,
   deriveEdgeWriteItemsFor,
   deriveModelEdgeWriteItems,
@@ -1675,19 +1935,18 @@ export {
   isMutationInputRef,
   isParam,
   isPlannedCommandMethod,
-  isProjectionDefinition,
   isQueryModelContract,
   isRetryableError,
   isRetryableTransactionCancellation,
   isSelectBuilder,
   isTransactionRef,
-  isViewDefinition,
   k,
   key,
   lifecyclePhaseForIntent,
   list,
   literal,
   maintainTrigger,
+  maintainedFrom,
   map,
   max,
   mintContractKeyFieldRef,

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-DuJ08bgc.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-BWOrWcbd.js';
 import '@aws-sdk/client-dynamodb';
 
 /**

package/dist/testing/index.js

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