@nicia-ai/typegraph 0.39.0 → 0.41.0

package/dist/chunk-SVUKGWSN.cjs

@@ -1,102 +0,0 @@
-'use strict';
-
-var chunkDDCYVIVV_cjs = require('./chunk-DDCYVIVV.cjs');
-var chunkSAFZ6JTI_cjs = require('./chunk-SAFZ6JTI.cjs');
-
-// src/core/temporal.ts
-var RECORDED_MAX = "9999-12-31T23:59:59.999Z";
-function assertValidRecordedInstant(value, path) {
-  chunkDDCYVIVV_cjs.validateCanonicalIsoDate(value, path);
-  if (value >= RECORDED_MAX) {
-    throw new chunkSAFZ6JTI_cjs.ValidationError(
-      `${path} must be before the recorded-time open sentinel ${RECORDED_MAX}.`,
-      {
-        issues: [
-          {
-            path,
-            message: `Expected a timestamp before ${RECORDED_MAX}, got "${value}"`
-          }
-        ]
-      },
-      {
-        suggestion: "Use a real recorded-time commit instant, not the open-interval sentinel."
-      }
-    );
-  }
-}
-function asRecordedInstant(value) {
-  assertValidRecordedInstant(value, "asRecordedInstant");
-  return value;
-}
-function resolveReadCoordinate(mode, asOf, suggestion) {
-  if (mode !== "asOf" && asOf !== void 0) {
-    throw new chunkSAFZ6JTI_cjs.ValidationError(
-      `Temporal mode "${mode}" does not take an asOf timestamp.`,
-      {
-        issues: [
-          {
-            path: "asOf",
-            message: `asOf is only valid with mode "asOf", not "${mode}"`
-          }
-        ]
-      },
-      {
-        suggestion: 'Pin an instant with store.asOf(timestamp) or store.view({ mode: "asOf", asOf }); drop asOf for other modes.'
-      }
-    );
-  }
-  assertValidAsOf(
-    mode,
-    asOf,
-    suggestion === void 0 ? void 0 : { suggestion }
-  );
-  return { valid: asOf === void 0 ? { mode } : { mode, asOf } };
-}
-function withRecordedCoordinate(coordinate, recordedAsOf) {
-  assertValidRecordedInstant(recordedAsOf, "asOfRecorded");
-  return {
-    ...coordinate,
-    recorded: { asOf: recordedAsOf }
-  };
-}
-function assertValidAsOf(mode, asOf, options) {
-  if (mode === "asOf" && asOf === void 0) {
-    throw new chunkSAFZ6JTI_cjs.ValidationError(
-      'Temporal mode "asOf" requires a timestamp',
-      {
-        issues: [
-          { path: "asOf", message: "Timestamp is required for asOf mode" }
-        ]
-      },
-      {
-        suggestion: options?.suggestion ?? 'Provide an ISO-8601 timestamp for asOf mode, e.g. "2026-01-01T00:00:00.000Z".'
-      }
-    );
-  }
-  if (asOf !== void 0) {
-    chunkDDCYVIVV_cjs.validateCanonicalIsoDate(asOf, "asOf");
-  }
-}
-function describeCoordinate(coordinate) {
-  const { mode, asOf } = coordinate.valid;
-  const valid = asOf === void 0 ? `mode "${mode}"` : `mode "${mode}" asOf ${asOf}`;
-  return coordinate.recorded === void 0 ? valid : `${valid}, recorded asOf ${coordinate.recorded.asOf}`;
-}
-function coordinateContext(coordinate) {
-  const { mode, asOf } = coordinate.valid;
-  return {
-    temporalMode: mode,
-    ...asOf !== void 0 && { asOf },
-    ...coordinate.recorded === void 0 ? {} : { recordedAsOf: coordinate.recorded.asOf }
-  };
-}
-
-exports.RECORDED_MAX = RECORDED_MAX;
-exports.asRecordedInstant = asRecordedInstant;
-exports.assertValidRecordedInstant = assertValidRecordedInstant;
-exports.coordinateContext = coordinateContext;
-exports.describeCoordinate = describeCoordinate;
-exports.resolveReadCoordinate = resolveReadCoordinate;
-exports.withRecordedCoordinate = withRecordedCoordinate;
-//# sourceMappingURL=chunk-SVUKGWSN.cjs.map
-//# sourceMappingURL=chunk-SVUKGWSN.cjs.map

package/dist/chunk-SVUKGWSN.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/core/temporal.ts"],"names":["validateCanonicalIsoDate","ValidationError"],"mappings":"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","file":"chunk-SVUKGWSN.cjs","sourcesContent":["/**\n * Shared temporal coordinate + validation.\n */\nimport { ValidationError } from \"../errors\";\nimport { validateCanonicalIsoDate } from \"../utils/date\";\nimport { type TemporalMode } from \"./types\";\n\n/**\n * Open-ended recorded-time sentinel. Chosen so SQLite text ordering and\n * PostgreSQL `timestamptz` ordering both put every real commit instant before\n * the open interval end.\n */\nexport const RECORDED_MAX = \"9999-12-31T23:59:59.999Z\";\n\ndeclare const RECORDED_INSTANT_BRAND: unique symbol;\n\n/**\n * A canonical UTC ISO-8601 recorded-time instant (`YYYY-MM-DDTHH:mm:ss.sssZ`),\n * nominally branded so it can only originate from a recorded-time source —\n * {@link Store.recordedNow} or an explicit {@link asRecordedInstant} — never an\n * ad-hoc wall-clock string.\n *\n * The recorded commit clock is a logical, monotonic per-graph instant that can\n * run briefly ahead of wall time under bursty same-millisecond writes, so a raw\n * `new Date().toISOString()` may sort *before* the most recent commits and\n * silently omit them. The brand turns that footgun into a compile error:\n * `store.asOfRecorded` accepts only a `RecordedInstant`, so a bare wall-clock\n * string no longer type-checks — callers reach for `await store.recordedNow()`\n * (the monotonic high-water mark) or {@link asRecordedInstant} instead.\n */\nexport type RecordedInstant = string & {\n  readonly [RECORDED_INSTANT_BRAND]: \"RecordedInstant\";\n};\n\nexport function assertValidRecordedInstant(value: string, path: string): void {\n  validateCanonicalIsoDate(value, path);\n  if (value >= RECORDED_MAX) {\n    throw new ValidationError(\n      `${path} must be before the recorded-time open sentinel ${RECORDED_MAX}.`,\n      {\n        issues: [\n          {\n            path,\n            message: `Expected a timestamp before ${RECORDED_MAX}, got \"${value}\"`,\n          },\n        ],\n      },\n      {\n        suggestion:\n          \"Use a real recorded-time commit instant, not the open-interval sentinel.\",\n      },\n    );\n  }\n}\n\n/**\n * Brands a canonical UTC ISO-8601 string as a {@link RecordedInstant}.\n *\n * The escape hatch for an instant that round-trips through untyped storage:\n * captured from {@link Store.recordedNow}, persisted as a plain string, read\n * back, and replayed into `asOfRecorded`. Validates the canonical form eagerly —\n * the same check `asOfRecorded` applies — so a malformed value fails here, at the\n * brand site, rather than deeper in a read. Does *not* assert the instant is a\n * real captured commit; it only guarantees the value is well-formed enough to\n * compare correctly against the recorded relations.\n *\n * @throws {ValidationError} when `value` is not a canonical UTC ISO-8601 string.\n */\nexport function asRecordedInstant(value: string): RecordedInstant {\n  assertValidRecordedInstant(value, \"asRecordedInstant\");\n  return value as RecordedInstant;\n}\n\n/**\n * The single opaque temporal coordinate every pinned read is resolved\n * against. It carries the valid-time axis plus an optional recorded/system-time\n * axis, so every surface can inject one coordinate object instead of threading\n * each temporal dimension separately.\n */\nexport type ReadCoordinate = Readonly<{\n  /**\n   * The valid-time axis: a resolved temporal mode and (only for `\"asOf\"`) the\n   * instant it is pinned to.\n   */\n  valid: Readonly<{\n    mode: TemporalMode;\n    /** Defined only when `mode` is `\"asOf\"`. */\n    asOf?: string;\n  }>;\n  /** The recorded/system-time axis. Defined only for recorded-pinned views. */\n  recorded?: Readonly<{ asOf: RecordedInstant }>;\n}>;\n\n/**\n * Resolves and validates a `(mode, asOf)` pair into a {@link ReadCoordinate}.\n * Rejects an `asOf` paired with any non-`\"asOf\"` mode rather than silently\n * dropping it — pinning an instant is only meaningful in `\"asOf\"` mode, so a\n * `view({ mode: \"current\", asOf })` is a caller mistake, not a coordinate to\n * quietly discard. Then validates via {@link assertValidAsOf}.\n *\n * @param mode - The temporal mode to pin.\n * @param asOf - The supplied timestamp. Required for `\"asOf\"`; rejected for\n *   every other mode.\n * @param suggestion - Caller-specific remediation hint for the\n *   missing/invalid-timestamp case.\n */\nexport function resolveReadCoordinate(\n  mode: TemporalMode,\n  asOf: string | undefined,\n  suggestion?: string,\n): ReadCoordinate {\n  if (mode !== \"asOf\" && asOf !== undefined) {\n    throw new ValidationError(\n      `Temporal mode \"${mode}\" does not take an asOf timestamp.`,\n      {\n        issues: [\n          {\n            path: \"asOf\",\n            message: `asOf is only valid with mode \"asOf\", not \"${mode}\"`,\n          },\n        ],\n      },\n      {\n        suggestion:\n          'Pin an instant with store.asOf(timestamp) or store.view({ mode: \"asOf\", asOf }); drop asOf for other modes.',\n      },\n    );\n  }\n  assertValidAsOf(\n    mode,\n    asOf,\n    suggestion === undefined ? undefined : { suggestion },\n  );\n  return { valid: asOf === undefined ? { mode } : { mode, asOf } };\n}\n\n/**\n * Adds a recorded/system-time pin to an existing valid-time coordinate.\n * Direct `store.asOfRecorded(T)` passes the diagonal valid-time coordinate\n * (`mode: \"asOf\", asOf: T`); `store.asOf(vt).asOfRecorded(rt)` passes the\n * already-resolved valid coordinate and adds the recorded sibling.\n */\nexport function withRecordedCoordinate(\n  coordinate: ReadCoordinate,\n  recordedAsOf: RecordedInstant,\n): ReadCoordinate {\n  assertValidRecordedInstant(recordedAsOf, \"asOfRecorded\");\n  return {\n    ...coordinate,\n    recorded: { asOf: recordedAsOf },\n  };\n}\n\n/**\n * Validates the `asOf` coordinate of a temporal read: `\"asOf\"` mode\n * requires a timestamp, and any supplied timestamp must be a canonical\n * fixed-width UTC ISO-8601 string (`YYYY-MM-DDTHH:mm:ss.sssZ`). The latter\n * is load-bearing — temporal filters compare `asOf` against `valid_from` /\n * `valid_to` as text on SQLite, so a non-canonical value (date-only, an\n * offset, natural language, or variable-width / missing milliseconds like\n * `.1Z`) would sort and compare wrong rather than error. Reached only through\n * {@link resolveReadCoordinate}, which every temporal read entry point routes\n * through (direct reads, queries, subgraphs, algorithms, and StoreView), so\n * they all fail identically.\n *\n * @param mode - The resolved temporal mode.\n * @param asOf - The supplied timestamp (may be `undefined`).\n * @param options.suggestion - A caller-specific remediation hint for the\n *   missing-timestamp case.\n *\n * @throws {ValidationError} when `mode` is `\"asOf\"` and `asOf` is missing, or\n *   when any supplied `asOf` is not a canonical UTC ISO-8601 timestamp. The\n *   canonical check runs for *every* mode that consumes `asOf`, so a\n *   non-canonical value can never reach a text comparison.\n */\nfunction assertValidAsOf(\n  mode: TemporalMode,\n  asOf: string | undefined,\n  options?: Readonly<{ suggestion?: string }>,\n): void {\n  if (mode === \"asOf\" && asOf === undefined) {\n    throw new ValidationError(\n      'Temporal mode \"asOf\" requires a timestamp',\n      {\n        issues: [\n          { path: \"asOf\", message: \"Timestamp is required for asOf mode\" },\n        ],\n      },\n      {\n        suggestion:\n          options?.suggestion ??\n          'Provide an ISO-8601 timestamp for asOf mode, e.g. \"2026-01-01T00:00:00.000Z\".',\n      },\n    );\n  }\n  if (asOf !== undefined) {\n    validateCanonicalIsoDate(asOf, \"asOf\");\n  }\n}\n\n/**\n * A human-readable description of a coordinate for error messages, e.g.\n * `mode \"current\"` or `mode \"asOf\" asOf 2026-01-01T00:00:00.000Z`. Shared by\n * every refusal path (the `StoreView` read-only / current-only / search facades\n * and the sealed-query builder) so they describe a coordinate identically — and\n * a future axis (recorded time) is reflected everywhere from one place.\n */\nexport function describeCoordinate(coordinate: ReadCoordinate): string {\n  const { mode, asOf } = coordinate.valid;\n  const valid =\n    asOf === undefined ? `mode \"${mode}\"` : `mode \"${mode}\" asOf ${asOf}`;\n  return coordinate.recorded === undefined ?\n      valid\n    : `${valid}, recorded asOf ${coordinate.recorded.asOf}`;\n}\n\n/**\n * The structured error-context fields describing a coordinate, shared by the\n * same refusal paths as {@link describeCoordinate}.\n */\nexport function coordinateContext(\n  coordinate: ReadCoordinate,\n): Record<string, unknown> {\n  const { mode, asOf } = coordinate.valid;\n  return {\n    temporalMode: mode,\n    ...(asOf !== undefined && { asOf }),\n    ...(coordinate.recorded === undefined ?\n      {}\n    : { recordedAsOf: coordinate.recorded.asOf }),\n  };\n}\n"]}