@nicia-ai/typegraph 0.45.0 → 0.46.1

package/dist/chunk-WDGA7IYB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constraints/index.ts"],"names":[],"mappings":"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","file":"chunk-WDGA7IYB.js","sourcesContent":["/**\n * Constraint validation module.\n *\n * Provides validation functions for enforcing graph constraints:\n * - Uniqueness constraints on node properties\n * - Cardinality constraints on edges\n * - Endpoint type constraints on edges\n * - Disjointness constraints between node kinds\n */\n\n/**\n * Separator used between field values in composite unique keys.\n * Uses ASCII Record Separator (0x1E) — valid UTF-8 and safe for PostgreSQL\n * TEXT columns (unlike \\0 which PostgreSQL rejects).\n */\nconst UNIQUE_KEY_SEPARATOR = \"\\u001E\";\n\n/** Marker for undefined/null field values in unique keys. */\nconst UNIQUE_KEY_NULL_MARKER = \"\\u001F\"; // ASCII Unit Separator\nimport {\n  type Cardinality,\n  type Collation,\n  type EdgeRegistration,\n  type NullCheckOp,\n  type UniqueConstraint,\n  type UniquenessScope,\n} from \"../core/types\";\nimport {\n  CardinalityError,\n  ConfigurationError,\n  DisjointError,\n  EndpointError,\n  UniquenessError,\n} from \"../errors\";\nimport { type KindRegistry } from \"../registry/kind-registry\";\nimport { hasOwnKey, readOwnProperty } from \"../utils/object\";\nimport { isPresent } from \"../utils/presence\";\n\n// ============================================================\n// Uniqueness Validation\n// ============================================================\n\n/**\n * Computes the unique key for a node's uniqueness constraint.\n *\n * The key is built by concatenating the specified field values,\n * optionally normalized for case-insensitive comparison.\n *\n * Field values are read by declared OWN key ({@link readOwnProperty}): a\n * constraint may name a field that a props bag does not carry (an absent\n * optional field), and a plain `props[field]` read would answer such a field\n * with the inherited `Object.prototype` member when the field is named after\n * one. A constraint over a field named `toString` then keyed on the inherited\n * function — `\"\"` under `binary` (the function stringified and dropped by\n * `JSON.stringify`) and a `TypeError` under `caseInsensitive` — instead of the\n * null marker every other absent value gets.\n */\nexport function computeUniqueKey(\n  props: Record<string, unknown>,\n  fields: readonly string[],\n  collation: Collation,\n): string {\n  const values = fields.map((field) => {\n    const value = readOwnProperty(props, field);\n    if (value === undefined || value === null) {\n      return UNIQUE_KEY_NULL_MARKER;\n    }\n    // Convert to string, handling primitives safely\n    const stringValue =\n      typeof value === \"string\" ? value\n      : typeof value === \"number\" || typeof value === \"boolean\" ?\n        value.toString()\n      : JSON.stringify(value);\n    return collation === \"caseInsensitive\" ?\n        stringValue.toLowerCase()\n      : stringValue;\n  });\n  return values.join(UNIQUE_KEY_SEPARATOR);\n}\n\n/**\n * Checks if a uniqueness constraint's where predicate passes.\n *\n * A `where` callback that does not return a predicate is REFUSED here, not\n * treated as \"the constraint always applies\". The same malformed clause is a\n * hard `ConfigurationError` at definition time ({@link assertWhereFieldDeclared})\n * and at persistence time (`serializeWherePredicate`); a third reading that\n * silently widened a partial constraint to a total one would let the three\n * sites disagree about the same clause — the divergence\n * {@link captureWherePredicate} exists to prevent.\n *\n * The arm SHOULD be unreachable: `defineGraph` refuses a non-predicate callback\n * before any write can evaluate it, `validateGraphExtension` refuses the\n * document form, and a constraint reconstructed from a persisted schema carries\n * a callback this module built itself. It is reachable only by handing the\n * store a constraint object that never passed a definition gate — for which\n * failing loudly is the correct answer, since the alternative is enforcing\n * uniqueness over rows the author meant to exclude.\n */\nexport function checkWherePredicate(\n  constraint: UniqueConstraint,\n  props: Record<string, unknown>,\n): boolean {\n  if (!constraint.where) {\n    return true; // No where clause, always applies\n  }\n\n  const predicate = captureWherePredicate(constraint.where);\n  if (predicate === undefined) {\n    throw new ConfigurationError(\n      `Unique constraint \"${constraint.name}\" has a \\`where\\` callback that does not return a predicate.`,\n      { constraintName: constraint.name, fields: [...constraint.fields] },\n      {\n        suggestion: `Return a field predicate, e.g. \\`where: (fields) => fields.${constraint.fields[0] ?? \"someField\"}.isNotNull()\\`. A constraint built outside \\`defineGraph\\` bypasses the definition-time check that normally reports this.`,\n      },\n    );\n  }\n\n  return evaluatePredicate(predicate, props);\n}\n\ntype UniquePredicate = Readonly<{\n  __type: \"unique_predicate\";\n  field: string;\n  op: NullCheckOp;\n}>;\n\n/**\n * The `where` callback as every caller of {@link captureWherePredicate} sees it:\n * a per-field builder in, whatever the author returned out.\n *\n * Deliberately looser than `UniqueConstraint[\"where\"]`, whose builder type is\n * generic in the kind's schema — the capture is the same operation whether the\n * callback came from a typed `defineGraph` registration, a compiled\n * graph-extension document, or an untyped JavaScript caller.\n */\ntype UniqueWhereCallback = (\n  builder: Readonly<\n    Record<\n      string,\n      Readonly<{\n        isNull: () => UniquePredicate;\n        isNotNull: () => UniquePredicate;\n      }>\n    >\n  >,\n) => unknown;\n\n/**\n * Runs a `where` callback against the shared builder and returns the predicate\n * it named, or `undefined` when the callback returned something that is not a\n * predicate.\n *\n * The single owner of \"what does this `where` clause say\": constraint\n * EVALUATION ({@link checkWherePredicate}), definition-time VALIDATION\n * ({@link assertWhereFieldDeclared}), and persistence-time CAPTURE\n * (`serializeWherePredicate` in src/schema/serializer.ts) all read the clause\n * through this one function, so a persisted `where`, a validated `where`, and\n * an evaluated `where` cannot disagree about which field the author named.\n */\nexport function captureWherePredicate(\n  where: UniqueWhereCallback,\n): UniquePredicate | undefined {\n  const predicate = where(buildPredicateContext());\n  if (\n    typeof predicate !== \"object\" ||\n    predicate === null ||\n    !(\"__type\" in predicate)\n  ) {\n    return undefined;\n  }\n\n  const candidate = predicate as {\n    __type: unknown;\n    field: unknown;\n    op: unknown;\n  };\n  if (\n    candidate.__type !== \"unique_predicate\" ||\n    typeof candidate.field !== \"string\" ||\n    (candidate.op !== \"isNull\" && candidate.op !== \"isNotNull\")\n  ) {\n    return undefined;\n  }\n\n  return {\n    __type: \"unique_predicate\",\n    field: candidate.field,\n    op: candidate.op,\n  };\n}\n\n/**\n * Refuses a uniqueness constraint whose `where` clause names a field the kind\n * does not declare.\n *\n * The runtime half of the builder's guard. {@link buildPredicateContext} is\n * total by design — it must answer for a DECLARED-but-absent field, which is\n * the whole point of a partial constraint — so a typo'd name cannot be caught\n * there, and the type system catches it only for typed callers\n * (`UniqueConstraintPredicateBuilder` declares exactly the schema's fields and\n * has no index signature). An untyped caller naming an undeclared field\n * otherwise gets a predicate that quietly never applies.\n *\n * Called once per constraint at graph-definition time — the single point every\n * constraint passes through before any write can evaluate it — rather than at\n * each of the write paths' `checkWherePredicate` call sites, so the refusal\n * covers every path uniformly and costs nothing per write. Mirrors\n * `validateGraphExtension`'s `UNKNOWN_UNIQUE_WHERE_FIELD` refusal, which\n * already holds the same invariant for kinds declared as JSON documents.\n */\nexport function assertWhereFieldDeclared(\n  kind: string,\n  constraint: UniqueConstraint,\n  shape: Readonly<Record<string, unknown>>,\n): void {\n  if (!constraint.where) return;\n\n  const predicate = captureWherePredicate(constraint.where);\n  if (predicate === undefined) {\n    throw new ConfigurationError(\n      `Unique constraint \"${constraint.name}\" on node kind \"${kind}\" has a \\`where\\` callback that does not return a predicate.`,\n      { kind, constraintName: constraint.name },\n      {\n        suggestion: `Return a field predicate, e.g. \\`where: (fields) => fields.${Object.keys(shape)[0] ?? \"someField\"}.isNotNull()\\`.`,\n      },\n    );\n  }\n\n  if (!hasOwnKey(shape, predicate.field)) {\n    throw new ConfigurationError(\n      `Unique constraint \"${constraint.name}\" on node kind \"${kind}\" has a \\`where\\` clause on field \"${predicate.field}\", which is not declared in the kind's schema.`,\n      {\n        kind,\n        constraintName: constraint.name,\n        field: predicate.field,\n        declaredFields: Object.keys(shape),\n      },\n      {\n        suggestion: `Name a declared field (${Object.keys(shape).join(\", \")}) or add \"${predicate.field}\" to the schema.`,\n      },\n    );\n  }\n}\n\ntype PredicateContext = Readonly<\n  Record<\n    string,\n    Readonly<{\n      isNull: () => UniquePredicate;\n      isNotNull: () => UniquePredicate;\n    }>\n  >\n>;\n\n/**\n * Builds the context a constraint's `where` callback names fields on.\n *\n * EVERY field name gets a member, because the builder type declares every\n * schema field as required (`-?` in `UniqueConstraintPredicateBuilder`) —\n * precisely so a partial constraint can ask whether an OPTIONAL field is\n * present. Populating the context from the props bag's own keys instead left a\n * declared-but-absent field with no member, and the callback's access then hit\n * whatever the context's prototype offered: `Object.prototype.toString` for a\n * field named `toString` (so naming it threw \"isNull is not a function\"), and\n * `undefined` for an ordinary field (so the everyday partial constraint over\n * `externalId` threw — \"Cannot read properties of undefined\", or \"Expected a\n * defined value\" through `requireDefined` — for every node written without it).\n *\n * Answering every name is safe because a name comes from the predicate author\n * (the code), never from data, and the field's VALUE is still read from the\n * props bag by own key when the predicate is evaluated — so an absent field\n * evaluates as null, which is what a partial constraint means by absent. Every\n * reader of a `where` clause goes through {@link captureWherePredicate}, which\n * builds this one context, so a persisted `where`, a validated `where`, and an\n * evaluated `where` cannot see different builders.\n *\n * The guard against a TYPO'D field name is NOT this Proxy — it must stay total\n * or a declared-but-absent field loses its member. It is\n * {@link assertWhereFieldDeclared}, which every constraint passes at\n * graph-definition time: an undeclared name is refused there with a typed\n * `ConfigurationError`, so no `where` clause naming one ever reaches\n * evaluation, from a typed or an untyped caller.\n */\nfunction buildPredicateContext(): PredicateContext {\n  return new Proxy<PredicateContext>(\n    {},\n    {\n      get(_target, property) {\n        if (typeof property === \"symbol\") return;\n        return {\n          isNull: () => ({\n            __type: \"unique_predicate\" as const,\n            field: property,\n            op: \"isNull\" as const,\n          }),\n          isNotNull: () => ({\n            __type: \"unique_predicate\" as const,\n            field: property,\n            op: \"isNotNull\" as const,\n          }),\n        };\n      },\n    },\n  );\n}\n\n/**\n * Evaluates a uniqueness predicate.\n *\n * Takes a CAPTURED predicate, not an `unknown`: the \"is this really a\n * predicate?\" question belongs to {@link captureWherePredicate}, which is its\n * single owner. The defensive `return true` arms this function used to carry\n * were a second, quieter answer to that question — and they answered it the\n * opposite way, widening a partial constraint into a total one where the owner\n * refuses.\n */\nfunction evaluatePredicate(\n  pred: UniquePredicate,\n  props: Record<string, unknown>,\n): boolean {\n  // Own-key read: `pred.field` is a schema field name, and a props bag that\n  // does not carry it must read as absent rather than as the inherited\n  // `Object.prototype` member a field named after one would otherwise find\n  // (which reads as present, inverting both `isNull` and `isNotNull`).\n  const value = readOwnProperty(props, pred.field);\n  if (pred.op === \"isNull\") {\n    return value === null || value === undefined;\n  }\n  return isPresent(value);\n}\n\n/**\n * Gets all kinds that should be checked for a uniqueness constraint.\n *\n * For \"kindWithSubClasses\" scope, includes the entire subclass hierarchy:\n * - The kind itself\n * - All ancestors (parent classes)\n * - All descendants of those ancestors (sibling classes)\n *\n * For \"kind\" scope, only the specific kind.\n */\nexport function getKindsForUniquenessCheck(\n  baseKind: string,\n  scope: UniquenessScope,\n  registry: KindRegistry,\n): readonly string[] {\n  if (scope === \"kind\") {\n    return [baseKind];\n  }\n\n  // Get the entire connected subclass hierarchy by finding the root ancestor\n  const root = findRootAncestor(baseKind, registry);\n\n  // Return the root and all its descendants (which includes baseKind and siblings)\n  return registry.expandSubClasses(root);\n}\n\n/**\n * Finds the topmost ancestor of a kind, or the kind itself if it has no ancestors.\n */\nfunction findRootAncestor(kind: string, registry: KindRegistry): string {\n  const ancestors = registry.getAncestors(kind);\n\n  if (ancestors.size === 0) {\n    return kind;\n  }\n\n  // Find an ancestor with no ancestors (the root)\n  for (const ancestor of ancestors) {\n    if (registry.getAncestors(ancestor).size === 0) {\n      return ancestor;\n    }\n  }\n\n  // If all ancestors have ancestors, recurse up\n  const firstAncestor = [...ancestors][0];\n  return firstAncestor ? findRootAncestor(firstAncestor, registry) : kind;\n}\n\n/**\n * Creates a uniqueness error.\n */\nexport function createUniquenessError(\n  constraintName: string,\n  kind: string,\n  existingId: string,\n  newId: string,\n  fields: readonly string[],\n): UniquenessError {\n  return new UniquenessError({\n    constraintName,\n    kind,\n    existingId,\n    newId,\n    fields: [...fields],\n  });\n}\n\n// ============================================================\n// Cardinality Validation\n// ============================================================\n\n/**\n * Checks if adding an edge would violate cardinality constraints.\n *\n * @param edgeKind - The edge kind being added\n * @param fromKind - The source node kind\n * @param fromId - The source node ID\n * @param cardinality - The cardinality constraint\n * @param existingEdgeCount - Number of existing edges of this kind from this source\n * @param hasActiveEdge - Whether there's an active (valid_to IS NULL) edge\n * @returns Error if violation, undefined if valid\n */\nexport function checkCardinality(\n  edgeKind: string,\n  fromKind: string,\n  fromId: string,\n  cardinality: Cardinality,\n  existingEdgeCount: number,\n  hasActiveEdge: boolean,\n): CardinalityError | undefined {\n  switch (cardinality) {\n    case \"many\": {\n      // No constraint\n      return undefined;\n    }\n    case \"one\": {\n      // At most one edge of this kind from any source node\n      if (existingEdgeCount > 0) {\n        return new CardinalityError({\n          edgeKind,\n          fromKind,\n          fromId,\n          cardinality: \"one\",\n          existingCount: existingEdgeCount,\n        });\n      }\n      return undefined;\n    }\n    case \"unique\": {\n      // unique is checked separately per (source, target) pair\n      return undefined;\n    }\n    case \"oneActive\": {\n      // At most one edge with valid_to IS NULL from any source\n      if (hasActiveEdge) {\n        return new CardinalityError({\n          edgeKind,\n          fromKind,\n          fromId,\n          cardinality: \"oneActive\",\n          existingCount: 1,\n        });\n      }\n      return undefined;\n    }\n  }\n}\n\n/**\n * Checks unique edge constraint (at most one edge between any source-target pair).\n */\nexport function checkUniqueEdge(\n  edgeKind: string,\n  fromKind: string,\n  fromId: string,\n  _toKind: string,\n  _toId: string,\n  existingCount: number,\n): CardinalityError | undefined {\n  if (existingCount > 0) {\n    return new CardinalityError({\n      edgeKind,\n      fromKind,\n      fromId,\n      cardinality: \"unique\",\n      existingCount,\n    });\n  }\n  return undefined;\n}\n\n// ============================================================\n// Endpoint Validation\n// ============================================================\n\n/**\n * Validates that an edge's endpoints are valid node kinds.\n */\nexport function validateEdgeEndpoints(\n  edgeKind: string,\n  fromKind: string,\n  toKind: string,\n  registration: EdgeRegistration,\n  registry: KindRegistry,\n): EndpointError | undefined {\n  // Check from kinds\n  const validFromKinds = registration.from.map((node) => node.kind);\n  if (!registry.isAssignableToAny(fromKind, validFromKinds)) {\n    return new EndpointError({\n      edgeKind,\n      endpoint: \"from\",\n      actualKind: fromKind,\n      expectedKinds: validFromKinds,\n    });\n  }\n\n  // Check to kinds\n  const validToKinds = registration.to.map((node) => node.kind);\n  if (!registry.isAssignableToAny(toKind, validToKinds)) {\n    return new EndpointError({\n      edgeKind,\n      endpoint: \"to\",\n      actualKind: toKind,\n      expectedKinds: validToKinds,\n    });\n  }\n\n  return undefined;\n}\n\n// ============================================================\n// Disjointness Validation\n// ============================================================\n\n/**\n * Checks if creating a node would violate disjointness constraints.\n *\n * @param nodeId - The node ID being created\n * @param nodeKind - The kind of the new node\n * @param existingKinds - Kinds of existing nodes with the same ID\n * @param registry - The kind registry for disjointness checks\n * @returns Error if disjoint violation, undefined if valid\n */\nexport function checkDisjointness(\n  nodeId: string,\n  nodeKind: string,\n  existingKinds: readonly string[],\n  registry: KindRegistry,\n): DisjointError | undefined {\n  for (const existingKind of existingKinds) {\n    if (registry.areDisjoint(nodeKind, existingKind)) {\n      return new DisjointError({\n        nodeId,\n        attemptedKind: nodeKind,\n        conflictingKind: existingKind,\n      });\n    }\n  }\n  return undefined;\n}\n\n/**\n * Gets all disjoint kinds for a given kind.\n */\nexport function getDisjointKinds(\n  kind: string,\n  registry: KindRegistry,\n): readonly string[] {\n  return registry.getDisjointKinds(kind);\n}\n"]}