@nicia-ai/typegraph 0.44.0 → 0.46.0

package/dist/chunk-YNULOIR5.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/query/dialect/vector/libsql-strategy.ts"],"names":["assertFiniteEmbedding","sql","vectorPhysicalName","quoteIdentifier","VECTOR_CONTRIBUTION_PREFIX","vectorScoreExpression","conditions","vectorMinScoreCondition","pageClause","vectorPageClause"],"mappings":"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","file":"chunk-YNULOIR5.cjs","sourcesContent":["/**\n * libSQL native vector strategy.\n *\n * libSQL ships vector search in core — no extension to load — so this\n * strategy is wired unconditionally by `createLibsqlBackend`. It backs each\n * `(nodeKind, fieldPath)` with its own `F32_BLOB(N)` table (the spike proved\n * the dimension MUST live in the column type for `libsql_vector_idx` to\n * build), brute-forces with `vector_distance_cos` / `vector_distance_l2`, and\n * accelerates with DiskANN (`libsql_vector_idx` + `vector_top_k`) when the\n * slot declares an approximate index.\n *\n * Metric support is `cosine` + `l2` (no `inner_product`), matching sqlite-vec\n * and advertised as data on `capabilities`. The generic `\"hnsw\"` index intent\n * (the portable \"give me an ANN index\" signal that `embedding()` defaults to)\n * is realized here as libSQL's DiskANN index; `\"ivfflat\"` is not supported and\n * a slot declaring it is materialized brute-force-only.\n *\n * The `pgvectorStrategy` and `sqliteVecStrategy` siblings follow the same\n * `VectorStrategy` contract for their engines.\n */\nimport { type StrategyTableContribution } from \"../../../backend/table-contribution\";\nimport {\n  type DeleteEmbeddingParams,\n  type UpsertEmbeddingBatchParams,\n  type UpsertEmbeddingParams,\n  type VectorCapabilities,\n  type VectorMetric,\n  type VectorSearchParams,\n} from \"../../../backend/types\";\nimport { sql, type SqlFragment } from \"../../sql-fragment\";\nimport {\n  assertFiniteEmbedding,\n  quoteIdentifier,\n  VECTOR_CONTRIBUTION_PREFIX,\n  vectorMinScoreCondition,\n  vectorPhysicalName,\n  vectorScoreExpression,\n  type VectorSlot,\n  type VectorStrategy,\n} from \"../vector-strategy\";\nimport { vectorPageClause } from \"./pagination\";\n\n/** Physical-name prefixes for the per-field table and its DiskANN index. */\nconst TABLE_PREFIX = \"tg_vec\";\nconst INDEX_PREFIX = \"tg_vecidx\";\n\n/**\n * libSQL `F32_BLOB` caps at 65,536 dimensions (per Turso docs / spike §2).\n */\nconst LIBSQL_MAX_DIMENSIONS = 65_536;\n\nconst LIBSQL_CAPABILITIES: VectorCapabilities = {\n  supported: true,\n  metrics: [\"cosine\", \"l2\"],\n  // \"hnsw\" = portable ANN intent, realized as DiskANN. \"none\" = brute-force.\n  indexTypes: [\"hnsw\", \"none\"],\n  maxDimensions: LIBSQL_MAX_DIMENSIONS,\n  // `vector_top_k` is a table function: no filter pushdown, no way to re-enter\n  // the index. A filtered DiskANN search over-fetches by\n  // CANDIDATE_FILTER_OVERFETCH and filters afterwards, so it under-fills once\n  // more than the headroom is filtered out. Unlike sqlite-vec (pushdown) and\n  // pgvector >= 0.8 (iterative scan), libSQL has no recovery at all.\n  filteredApproximateSearch: {\n    mode: \"post-filter\",\n    guaranteesFullPage: false,\n  },\n};\n\n/** Whether a slot's declared index type maps to a real libSQL ANN index. */\nfunction usesAnnIndex(slot: VectorSlot): boolean {\n  return slot.indexType === \"hnsw\";\n}\n\n/** libSQL metric token accepted by `libsql_vector_idx(col, 'metric=…')`. */\nfunction libsqlMetricToken(metric: VectorMetric): string {\n  switch (metric) {\n    case \"cosine\": {\n      return \"cosine\";\n    }\n    case \"l2\": {\n      return \"l2\";\n    }\n    case \"inner_product\": {\n      throw new Error(\n        \"libSQL vector search does not support inner_product. Use 'cosine' or 'l2'.\",\n      );\n    }\n    default: {\n      const _exhaustive: never = metric;\n      throw new Error(`Unsupported vector metric: ${String(_exhaustive)}`);\n    }\n  }\n}\n\n/**\n * Formats an embedding as the text argument to `vector32(...)`. The value is\n * bound as a parameter (not interpolated) — `vector32` parses it into the\n * F32 blob. Finiteness is validated first so a NaN names its index.\n */\nfunction vector32Literal(\n  embedding: readonly number[],\n  name: string,\n): SqlFragment {\n  assertFiniteEmbedding(embedding, name);\n  return sql`vector32(${`[${embedding.join(\",\")}]`})`;\n}\n\nfunction distanceExpression(\n  embeddingColumn: SqlFragment,\n  queryEmbedding: readonly number[],\n  metric: VectorMetric,\n): SqlFragment {\n  const query = vector32Literal(queryEmbedding, \"queryEmbedding\");\n  switch (metric) {\n    case \"cosine\": {\n      return sql`vector_distance_cos(${embeddingColumn}, ${query})`;\n    }\n    case \"l2\": {\n      return sql`vector_distance_l2(${embeddingColumn}, ${query})`;\n    }\n    case \"inner_product\": {\n      throw new Error(\n        \"libSQL vector search does not support inner_product. Use 'cosine' or 'l2'.\",\n      );\n    }\n    default: {\n      const _exhaustive: never = metric;\n      throw new Error(`Unsupported vector metric: ${String(_exhaustive)}`);\n    }\n  }\n}\n\nfunction tableName(\n  graphId: string,\n  nodeKind: string,\n  fieldPath: string,\n): string {\n  return vectorPhysicalName(TABLE_PREFIX, graphId, nodeKind, fieldPath);\n}\n\nexport const libsqlVectorStrategy: VectorStrategy = {\n  name: \"libsql-native\",\n  capabilities: LIBSQL_CAPABILITIES,\n\n  tableName,\n\n  ownedTables(slot): readonly StrategyTableContribution[] {\n    const table = tableName(slot.graphId, slot.nodeKind, slot.fieldPath);\n    const name = quoteIdentifier(table);\n\n    // No standalone graph_id index: the PRIMARY KEY (graph_id, node_id) already\n    // covers `WHERE graph_id = ?` via its leading column, so a separate index\n    // would be pure write amplification.\n    const createDdl = [\n      `CREATE TABLE IF NOT EXISTS ${name} (\n  \"graph_id\" TEXT NOT NULL,\n  \"node_id\" TEXT NOT NULL,\n  \"embedding\" F32_BLOB(${slot.dimensions}) NOT NULL,\n  \"created_at\" TEXT NOT NULL,\n  \"updated_at\" TEXT NOT NULL,\n  PRIMARY KEY (\"graph_id\", \"node_id\")\n);`,\n    ];\n\n    if (usesAnnIndex(slot)) {\n      // The DiskANN index DDL is deterministic raw SQL; fold it into the\n      // contribution so materialization creates table + index together.\n      createDdl.push(libsqlVectorIndexDdl(table, slot));\n    }\n\n    return [\n      {\n        logicalName: `${VECTOR_CONTRIBUTION_PREFIX}:${slot.nodeKind}.${slot.fieldPath}`,\n        owner: \"libsql-native\",\n        tableName: table,\n        createDdl,\n        runtimeEnsure: true,\n      },\n    ];\n  },\n\n  buildUpsert(\n    slot,\n    params: UpsertEmbeddingParams,\n    timestamp,\n  ): readonly SqlFragment[] {\n    const table = sql.identifier(\n      tableName(slot.graphId, slot.nodeKind, slot.fieldPath),\n    );\n    const value = vector32Literal(params.embedding, \"embedding\");\n    return [\n      sql`\n        INSERT INTO ${table} (\"graph_id\", \"node_id\", \"embedding\", \"created_at\", \"updated_at\")\n        VALUES (${params.graphId}, ${params.nodeId}, ${value}, ${timestamp}, ${timestamp})\n        ON CONFLICT (\"graph_id\", \"node_id\")\n        DO UPDATE SET \"embedding\" = ${value}, \"updated_at\" = ${timestamp}\n      `,\n    ];\n  },\n\n  buildUpsertBatch(\n    slot,\n    params: UpsertEmbeddingBatchParams,\n    timestamp,\n  ): readonly SqlFragment[] {\n    const table = sql.identifier(\n      tableName(slot.graphId, slot.nodeKind, slot.fieldPath),\n    );\n    const valueRows = sql.join(\n      params.rows.map(\n        (row) =>\n          sql`(${params.graphId}, ${row.nodeId}, ${vector32Literal(row.embedding, \"embedding\")}, ${timestamp}, ${timestamp})`,\n      ),\n      sql`, `,\n    );\n    // `excluded.\"embedding\"` reuses the row's already-converted F32_BLOB\n    // value, so the multi-row form needs no per-row conversion in the\n    // update arm (unlike buildUpsert's single bound value).\n    return [\n      sql`\n        INSERT INTO ${table} (\"graph_id\", \"node_id\", \"embedding\", \"created_at\", \"updated_at\")\n        VALUES ${valueRows}\n        ON CONFLICT (\"graph_id\", \"node_id\")\n        DO UPDATE SET \"embedding\" = excluded.\"embedding\", \"updated_at\" = excluded.\"updated_at\"\n      `,\n    ];\n  },\n\n  buildDelete(slot, params: DeleteEmbeddingParams): readonly SqlFragment[] {\n    const table = sql.identifier(\n      tableName(slot.graphId, slot.nodeKind, slot.fieldPath),\n    );\n    return [\n      sql`\n        DELETE FROM ${table}\n        WHERE \"graph_id\" = ${params.graphId} AND \"node_id\" = ${params.nodeId}\n      `,\n    ];\n  },\n\n  buildSearch(\n    slot,\n    params: VectorSearchParams,\n    candidates?: SqlFragment,\n  ): SqlFragment {\n    const table = tableName(slot.graphId, slot.nodeKind, slot.fieldPath);\n    const quoted = sql.identifier(table);\n    const embeddingColumn = sql`${quoted}.\"embedding\"`;\n    const distance = distanceExpression(\n      embeddingColumn,\n      params.queryEmbedding,\n      params.metric,\n    );\n    const score = vectorScoreExpression(distance, params.metric);\n\n    if (usesAnnIndex(slot)) {\n      // DiskANN: vector_top_k returns rowids from the per-field table; join\n      // back, then scope by graph and compute the real distance/score.\n      // `vector_top_k` is table-global, so single-graph deployments are exact;\n      // multi-graph recall is bounded by the over-fetched k (documented).\n      const indexName = libsqlIndexName(slot);\n      const query = vector32Literal(params.queryEmbedding, \"queryEmbedding\");\n      const conditions: SqlFragment[] = [\n        sql`${quoted}.\"graph_id\" = ${params.graphId}`,\n      ];\n      if (params.minScore !== undefined) {\n        conditions.push(\n          vectorMinScoreCondition(distance, params.metric, params.minScore),\n        );\n      }\n      // `vector_top_k` is a table function with no filter pushdown, so a\n      // candidate filter can only be applied AFTER the ANN retrieval.\n      // Over-fetch the DiskANN k to leave headroom for filtered-out rows;\n      // recall is bounded by the over-fetch, and the page under-fills once\n      // more than the headroom is filtered out. Declared, not merely noted:\n      // `capabilities.filteredApproximateSearch.mode === \"post-filter\"`.\n      if (candidates !== undefined) {\n        conditions.push(sql`${quoted}.\"node_id\" IN (${candidates})`);\n      }\n      // `pageK` covers the requested page (`limit + offset`); the\n      // candidate-filter over-fetch multiplies on top of it.\n      const pageK = params.limit + (params.offset ?? 0);\n      const annK =\n        candidates === undefined ? pageK : pageK * CANDIDATE_FILTER_OVERFETCH;\n      const pageClause = vectorPageClause(params.limit, params.offset);\n      return sql`\n        SELECT ${quoted}.\"node_id\" AS node_id, ${score} AS score\n        FROM vector_top_k(${indexName}, ${query}, ${annK})\n        JOIN ${quoted} ON ${quoted}.rowid = id\n        WHERE ${sql.join(conditions, sql` AND `)}\n        ORDER BY ${distance} ASC\n        ${pageClause}\n      `;\n    }\n\n    // Brute-force scan.\n    const conditions: SqlFragment[] = [\n      sql`${quoted}.\"graph_id\" = ${params.graphId}`,\n    ];\n    if (candidates !== undefined) {\n      conditions.push(sql`${quoted}.\"node_id\" IN (${candidates})`);\n    }\n    if (params.minScore !== undefined) {\n      conditions.push(\n        vectorMinScoreCondition(distance, params.metric, params.minScore),\n      );\n    }\n    const pageClause = vectorPageClause(params.limit, params.offset);\n    return sql`\n      SELECT ${quoted}.\"node_id\" AS node_id, ${score} AS score\n      FROM ${quoted}\n      WHERE ${sql.join(conditions, sql` AND `)}\n      ORDER BY ${distance} ASC\n      ${pageClause}\n    `;\n  },\n\n  distanceExpression(embeddingColumn, queryEmbedding, metric) {\n    return distanceExpression(embeddingColumn, queryEmbedding, metric);\n  },\n\n  buildCreateIndex(slot): SqlFragment | undefined {\n    if (!usesAnnIndex(slot)) return undefined;\n    return sql.raw(\n      libsqlVectorIndexDdl(\n        tableName(slot.graphId, slot.nodeKind, slot.fieldPath),\n        slot,\n      ),\n    );\n  },\n\n  buildDropIndex(slot): SqlFragment | undefined {\n    if (!usesAnnIndex(slot)) return undefined;\n    const indexName = libsqlIndexName(slot);\n    return sql.raw(`DROP INDEX IF EXISTS ${quoteIdentifier(indexName)}`);\n  },\n\n  buildDropStorage(slot): readonly string[] {\n    const table = quoteIdentifier(\n      tableName(slot.graphId, slot.nodeKind, slot.fieldPath),\n    );\n    const statements: string[] = [];\n    // Drop the DiskANN index first so libSQL reclaims its shadow tables,\n    // then the table itself.\n    if (usesAnnIndex(slot)) {\n      statements.push(\n        `DROP INDEX IF EXISTS ${quoteIdentifier(libsqlIndexName(slot))}`,\n      );\n    }\n    statements.push(`DROP TABLE IF EXISTS ${table}`);\n    return statements;\n  },\n};\n\n/**\n * DiskANN over-fetch multiplier applied when a candidate filter is present:\n * `vector_top_k` cannot pre-filter, so fetch `4k` neighbors and filter after.\n * Mirrors the hybrid facade's 4x over-fetch. Recall for the filtered search\n * is bounded by this headroom — if more than `3k` of the top `4k` neighbors\n * are filtered out, fewer than `k` rows return. That is the observable\n * meaning of `capabilities.filteredApproximateSearch.guaranteesFullPage`.\n */\nconst CANDIDATE_FILTER_OVERFETCH = 4;\n\nfunction libsqlIndexName(slot: VectorSlot): string {\n  return vectorPhysicalName(\n    INDEX_PREFIX,\n    slot.graphId,\n    slot.nodeKind,\n    slot.fieldPath,\n  );\n}\n\nfunction libsqlVectorIndexDdl(table: string, slot: VectorSlot): string {\n  const indexName = quoteIdentifier(libsqlIndexName(slot));\n  const metric = libsqlMetricToken(slot.metric);\n  return `CREATE INDEX IF NOT EXISTS ${indexName} ON ${quoteIdentifier(table)}(libsql_vector_idx(\"embedding\", 'metric=${metric}'));`;\n}\n"]}

package/dist/chunk-ZDH3DX3C.cjs

@@ -1,30 +0,0 @@
-'use strict';
-
-// src/utils/array.ts
-function chunk(items, size) {
-  if (!Number.isSafeInteger(size) || size < 1) {
-    throw new RangeError(`chunk size must be a positive integer, got: ${size}`);
-  }
-  if (items.length === 0) return [];
-  if (items.length <= size) return [items];
-  const chunks = [];
-  for (let start = 0; start < items.length; start += size) {
-    chunks.push(items.slice(start, start + size));
-  }
-  return chunks;
-}
-function groupBy(items, keyFor) {
-  const groups = /* @__PURE__ */ new Map();
-  for (const item of items) {
-    const key = keyFor(item);
-    const group = groups.get(key) ?? [];
-    group.push(item);
-    groups.set(key, group);
-  }
-  return groups;
-}
-
-exports.chunk = chunk;
-exports.groupBy = groupBy;
-//# sourceMappingURL=chunk-ZDH3DX3C.cjs.map
-//# sourceMappingURL=chunk-ZDH3DX3C.cjs.map

package/dist/chunk-ZDH3DX3C.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/utils/array.ts"],"names":[],"mappings":";;;AAQO,SAAS,KAAA,CACd,OACA,IAAA,EAC2B;AAK3B,EAAA,IAAI,CAAC,MAAA,CAAO,aAAA,CAAc,IAAI,CAAA,IAAK,OAAO,CAAA,EAAG;AAC3C,IAAA,MAAM,IAAI,UAAA,CAAW,CAAA,4CAAA,EAA+C,IAAI,CAAA,CAAE,CAAA;AAAA,EAC5E;AACA,EAAA,IAAI,KAAA,CAAM,MAAA,KAAW,CAAA,EAAG,OAAO,EAAC;AAChC,EAAA,IAAI,KAAA,CAAM,MAAA,IAAU,IAAA,EAAM,OAAO,CAAC,KAAK,CAAA;AACvC,EAAA,MAAM,SAAgB,EAAC;AACvB,EAAA,KAAA,IAAS,QAAQ,CAAA,EAAG,KAAA,GAAQ,KAAA,CAAM,MAAA,EAAQ,SAAS,IAAA,EAAM;AACvD,IAAA,MAAA,CAAO,KAAK,KAAA,CAAM,KAAA,CAAM,KAAA,EAAO,KAAA,GAAQ,IAAI,CAAC,CAAA;AAAA,EAC9C;AACA,EAAA,OAAO,MAAA;AACT;AAMO,SAAS,OAAA,CACd,OACA,MAAA,EACa;AACb,EAAA,MAAM,MAAA,uBAAa,GAAA,EAAY;AAC/B,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,MAAM,GAAA,GAAM,OAAO,IAAI,CAAA;AACvB,IAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,GAAA,CAAI,GAAG,KAAK,EAAC;AAClC,IAAA,KAAA,CAAM,KAAK,IAAI,CAAA;AACf,IAAA,MAAA,CAAO,GAAA,CAAI,KAAK,KAAK,CAAA;AAAA,EACvB;AACA,EAAA,OAAO,MAAA;AACT","file":"chunk-ZDH3DX3C.cjs","sourcesContent":["/**\n * Splits `items` into consecutive chunks of at most `size` elements.\n *\n * An empty input yields no chunks (`[]`), and an input that already fits in a\n * single chunk is returned without copying. Callers rely on the empty-input\n * behavior to skip work entirely rather than issue a statement with an empty\n * `IN ()` list.\n */\nexport function chunk<T>(\n  items: readonly T[],\n  size: number,\n): readonly (readonly T[])[] {\n  // A non-positive, non-finite, or fractional size would make the slice loop\n  // fail to advance correctly; fail loud rather than spin or emit empty chunks.\n  // All current callers derive size from a positive integer bind-parameter\n  // budget, so this only guards against a future regression.\n  if (!Number.isSafeInteger(size) || size < 1) {\n    throw new RangeError(`chunk size must be a positive integer, got: ${size}`);\n  }\n  if (items.length === 0) return [];\n  if (items.length <= size) return [items];\n  const chunks: T[][] = [];\n  for (let start = 0; start < items.length; start += size) {\n    chunks.push(items.slice(start, start + size));\n  }\n  return chunks;\n}\n\n/**\n * Groups items by a caller-supplied key while preserving input order within\n * each group.\n */\nexport function groupBy<T, K>(\n  items: Iterable<T>,\n  keyFor: (item: T) => K,\n): Map<K, T[]> {\n  const groups = new Map<K, T[]>();\n  for (const item of items) {\n    const key = keyFor(item);\n    const group = groups.get(key) ?? [];\n    group.push(item);\n    groups.set(key, group);\n  }\n  return groups;\n}\n"]}

package/dist/chunk-ZTAJL4DT.cjs

@@ -1,85 +0,0 @@
-'use strict';
-
-var chunkC4F7VJ5D_cjs = require('./chunk-C4F7VJ5D.cjs');
-
-// src/utils/date.ts
-var CANONICAL_ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
-var ZONELESS_DATETIME_PATTERN = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?$/;
-var OFFSET_DATETIME_PATTERN = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)(Z|[+-]\d{2}(?::?\d{2})?)$/i;
-var DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
-function normalizedOffset(offset) {
-  if (offset.toUpperCase() === "Z") return "Z";
-  if (/^[+-]\d{2}$/.test(offset)) return `${offset}:00`;
-  if (/^[+-]\d{4}$/.test(offset)) {
-    return `${offset.slice(0, 3)}:${offset.slice(3)}`;
-  }
-  return offset;
-}
-function databaseTimestampMilliseconds(value) {
-  if (ZONELESS_DATETIME_PATTERN.test(value)) {
-    return Date.parse(`${value.replace(" ", "T")}Z`);
-  }
-  const offsetMatch = OFFSET_DATETIME_PATTERN.exec(value);
-  if (offsetMatch !== null) {
-    const date = offsetMatch[1];
-    const time = offsetMatch[2];
-    const offset = offsetMatch[3];
-    if (date === void 0 || time === void 0 || offset === void 0) {
-      return Number.NaN;
-    }
-    return Date.parse(`${date}T${time}${normalizedOffset(offset)}`);
-  }
-  if (DATE_ONLY_PATTERN.test(value)) {
-    return Date.parse(`${value}T00:00:00.000Z`);
-  }
-  return Number.NaN;
-}
-function canonicalizeDatabaseTimestamp(value) {
-  if (value instanceof Date) {
-    if (Number.isNaN(value.getTime())) return void 0;
-    return value.toISOString();
-  }
-  if (typeof value !== "string") return void 0;
-  const milliseconds = databaseTimestampMilliseconds(value);
-  if (Number.isNaN(milliseconds)) return void 0;
-  return new Date(milliseconds).toISOString();
-}
-function isCanonicalIsoDate(value) {
-  if (!CANONICAL_ISO_DATE_PATTERN.test(value)) return false;
-  const date = new Date(value);
-  return !Number.isNaN(date.getTime()) && date.toISOString() === value;
-}
-function validateCanonicalIsoDate(value, fieldName) {
-  if (!isCanonicalIsoDate(value)) {
-    throw new chunkC4F7VJ5D_cjs.ValidationError(
-      `Invalid canonical ISO 8601 datetime for "${fieldName}": "${value}". Expected fixed-width UTC: YYYY-MM-DDTHH:mm:ss.sssZ`,
-      {
-        issues: [
-          {
-            path: fieldName,
-            message: `Expected canonical UTC ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ), got: "${value}"`
-          }
-        ]
-      },
-      {
-        suggestion: `Use a fixed-width UTC datetime like "2024-01-15T10:30:00.000Z" (e.g. new Date(value).toISOString()).`
-      }
-    );
-  }
-  return value;
-}
-function validateOptionalCanonicalIsoDate(value, fieldName) {
-  if (value === void 0) return void 0;
-  return validateCanonicalIsoDate(value, fieldName);
-}
-function nowIso() {
-  return (/* @__PURE__ */ new Date()).toISOString();
-}
-
-exports.canonicalizeDatabaseTimestamp = canonicalizeDatabaseTimestamp;
-exports.isCanonicalIsoDate = isCanonicalIsoDate;
-exports.nowIso = nowIso;
-exports.validateCanonicalIsoDate = validateCanonicalIsoDate;
-exports.validateOptionalCanonicalIsoDate = validateOptionalCanonicalIsoDate;
-//# sourceMappingURL=chunk-ZTAJL4DT.cjs.map
-//# sourceMappingURL=chunk-ZTAJL4DT.cjs.map

package/dist/chunk-ZTAJL4DT.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/utils/date.ts"],"names":["ValidationError"],"mappings":"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","file":"chunk-ZTAJL4DT.cjs","sourcesContent":["/**\n * Date encoding utilities for consistent storage.\n *\n * Contract: All dates are stored as ISO 8601 strings in UTC.\n * - Always includes milliseconds\n * - Always UTC (Z suffix)\n * - Sorts correctly as strings\n */\n\nimport { ValidationError } from \"../errors\";\n\n/**\n * ISO 8601 datetime pattern.\n * Matches formats like:\n * - 2024-01-15T10:30:00.000Z\n * - 2024-01-15T10:30:00Z\n * - 2024-01-15T10:30:00.123Z\n */\nconst ISO_DATE_PATTERN = /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$/;\n\n/**\n * Checks if a string is a valid ISO 8601 datetime.\n *\n * @param value - String to validate\n * @returns True if valid ISO 8601 datetime\n */\nexport function isValidIsoDate(value: string): boolean {\n  if (!ISO_DATE_PATTERN.test(value)) {\n    return false;\n  }\n  // Also check that Date parsing produces a valid date\n  const date = new Date(value);\n  return !Number.isNaN(date.getTime());\n}\n\n/**\n * Validates that a string is a valid ISO 8601 datetime.\n * Throws ValidationError if invalid.\n *\n * @param value - String to validate\n * @param fieldName - Name of field for error message\n * @returns The validated string\n * @throws ValidationError if not a valid ISO datetime\n */\nexport function validateIsoDate(value: string, fieldName: string): string {\n  if (!isValidIsoDate(value)) {\n    throw new ValidationError(\n      `Invalid ISO 8601 datetime for \"${fieldName}\": \"${value}\". ` +\n        `Expected format: YYYY-MM-DDTHH:mm:ss.sssZ`,\n      {\n        issues: [\n          {\n            path: fieldName,\n            message: `Invalid ISO 8601 datetime format. Expected: YYYY-MM-DDTHH:mm:ss.sssZ, got: \"${value}\"`,\n          },\n        ],\n      },\n      {\n        suggestion: `Use a valid ISO 8601 UTC datetime like \"2024-01-15T10:30:00.000Z\"`,\n      },\n    );\n  }\n  return value;\n}\n\n/**\n * Strict canonical ISO 8601 pattern: fixed-width UTC with exactly\n * millisecond precision (`YYYY-MM-DDTHH:mm:ss.sssZ`). Unlike\n * {@link ISO_DATE_PATTERN}, which tolerates a missing or variable-width\n * fractional part, this is the only shape whose lexicographic text order\n * matches chronological order — avoiding cases like `\"...:00.1Z\"` (= `.100`)\n * sorting *after* `\"...:00.101Z\"`.\n */\nconst CANONICAL_ISO_DATE_PATTERN =\n  /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$/;\n\nconst ZONELESS_DATETIME_PATTERN =\n  /^\\d{4}-\\d{2}-\\d{2}[ T]\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?$/;\nconst OFFSET_DATETIME_PATTERN =\n  /^(\\d{4}-\\d{2}-\\d{2})[ T](\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?)(Z|[+-]\\d{2}(?::?\\d{2})?)$/i;\nconst DATE_ONLY_PATTERN = /^\\d{4}-\\d{2}-\\d{2}$/;\n\nfunction normalizedOffset(offset: string): string {\n  if (offset.toUpperCase() === \"Z\") return \"Z\";\n  if (/^[+-]\\d{2}$/.test(offset)) return `${offset}:00`;\n  if (/^[+-]\\d{4}$/.test(offset)) {\n    return `${offset.slice(0, 3)}:${offset.slice(3)}`;\n  }\n  return offset;\n}\n\nfunction databaseTimestampMilliseconds(value: string): number {\n  if (ZONELESS_DATETIME_PATTERN.test(value)) {\n    return Date.parse(`${value.replace(\" \", \"T\")}Z`);\n  }\n  const offsetMatch = OFFSET_DATETIME_PATTERN.exec(value);\n  if (offsetMatch !== null) {\n    const date = offsetMatch[1];\n    const time = offsetMatch[2];\n    const offset = offsetMatch[3];\n    if (date === undefined || time === undefined || offset === undefined) {\n      return Number.NaN;\n    }\n    return Date.parse(`${date}T${time}${normalizedOffset(offset)}`);\n  }\n  if (DATE_ONLY_PATTERN.test(value)) {\n    return Date.parse(`${value}T00:00:00.000Z`);\n  }\n  return Number.NaN;\n}\n\n/**\n * Canonicalizes a database-driver timestamp without interpreting a zoneless\n * string in the host timezone. PostgreSQL drivers can return values such as\n * `2026-06-25 12:00:00`; TypeGraph treats that shape as UTC so the same stored\n * clock value cannot move across hosts or daylight-saving boundaries.\n *\n * Returns `undefined` for an unsupported or unrepresentable value so callers\n * can raise an error specific to their storage boundary.\n */\nexport function canonicalizeDatabaseTimestamp(\n  value: unknown,\n): string | undefined {\n  if (value instanceof Date) {\n    if (Number.isNaN(value.getTime())) return undefined;\n    return value.toISOString();\n  }\n  if (typeof value !== \"string\") return undefined;\n  const milliseconds = databaseTimestampMilliseconds(value);\n  if (Number.isNaN(milliseconds)) return undefined;\n  return new Date(milliseconds).toISOString();\n}\n\n/**\n * Checks if a string is a canonical UTC ISO 8601 datetime with fixed\n * millisecond width (`YYYY-MM-DDTHH:mm:ss.sssZ`).\n */\nexport function isCanonicalIsoDate(value: string): boolean {\n  if (!CANONICAL_ISO_DATE_PATTERN.test(value)) return false;\n  const date = new Date(value);\n  return !Number.isNaN(date.getTime()) && date.toISOString() === value;\n}\n\n/**\n * Validates that a string is a canonical UTC ISO 8601 datetime with fixed\n * millisecond width. Stricter than {@link validateIsoDate} (which also\n * accepts missing or 1–2 digit milliseconds): required wherever the value\n * is compared **as text** against stored timestamps and must sort\n * chronologically — e.g. a temporal `asOf` coordinate, where a\n * variable-width value would mis-order and silently include or exclude the\n * wrong rows. Produce one with `new Date(value).toISOString()`.\n *\n * @param value - String to validate\n * @param fieldName - Name of field for error message\n * @returns The validated string\n * @throws ValidationError if not a canonical UTC ISO datetime\n */\nexport function validateCanonicalIsoDate(\n  value: string,\n  fieldName: string,\n): string {\n  if (!isCanonicalIsoDate(value)) {\n    throw new ValidationError(\n      `Invalid canonical ISO 8601 datetime for \"${fieldName}\": \"${value}\". ` +\n        `Expected fixed-width UTC: YYYY-MM-DDTHH:mm:ss.sssZ`,\n      {\n        issues: [\n          {\n            path: fieldName,\n            message: `Expected canonical UTC ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ), got: \"${value}\"`,\n          },\n        ],\n      },\n      {\n        suggestion: `Use a fixed-width UTC datetime like \"2024-01-15T10:30:00.000Z\" (e.g. new Date(value).toISOString()).`,\n      },\n    );\n  }\n  return value;\n}\n\n/**\n * Validates an optional canonical ISO date string. Returns `undefined` for an\n * absent value; otherwise enforces canonical fixed-width UTC ISO 8601 via\n * {@link validateCanonicalIsoDate}. Used for stored validity-window inputs\n * (`validFrom` / `validTo`) so every timestamp the temporal filters compare as\n * text is canonical and sorts chronologically — the same contract the `asOf`\n * read coordinate already enforces.\n */\nexport function validateOptionalCanonicalIsoDate(\n  value: string | undefined,\n  fieldName: string,\n): string | undefined {\n  if (value === undefined) return undefined;\n  return validateCanonicalIsoDate(value, fieldName);\n}\n\n/**\n * Encodes a Date to an ISO 8601 string for storage.\n */\nexport function encodeDate(date: Date): string {\n  return date.toISOString();\n}\n\n/**\n * Decodes an ISO 8601 string to a Date.\n * Validates the string format first.\n *\n * @throws ValidationError if not a valid ISO datetime\n */\nexport function decodeDate(isoString: string): Date {\n  validateIsoDate(isoString, \"date\");\n  return new Date(isoString);\n}\n\n/**\n * Returns the current timestamp as an ISO string.\n */\nexport function nowIso(): string {\n  return new Date().toISOString();\n}\n"]}

package/dist/define-graph-DVF-oN1i.d.cts

@@ -1,173 +0,0 @@
-import { N as NodeRegistration, E as EdgeRegistration, O as OntologyRelation, D as DeleteBehavior, T as TemporalMode, I as IndexDeclaration, G as GraphExtension, b as NodeType, c as AnyEdgeType, d as GraphDefaults } from './types-Cjvkj0jA.cjs';
-
-/** Brand key for GraphDef */
-declare const GRAPH_DEF_BRAND: "__graphDef";
-/**
- * An edge entry in the graph definition.
- * Can be:
- * - EdgeType directly (constrained or unconstrained)
- * - EdgeRegistration object (always works, can override/narrow defaults)
- */
-type EdgeEntry = EdgeRegistration | AnyEdgeType;
-/**
- * Normalized edge map type - all entries become EdgeRegistration.
- * For bare EdgeTypes, constrained endpoints are extracted from the type;
- * unconstrained edges fall back to all node types in the graph.
- */
-type NormalizedEdges<TNodes extends Record<string, NodeRegistration>, TEdges extends Record<string, EdgeEntry>> = {
-    [K in keyof TEdges]: TEdges[K] extends EdgeRegistration ? TEdges[K] : TEdges[K] extends AnyEdgeType ? EdgeRegistration<TEdges[K], TEdges[K]["from"] extends readonly (infer N extends NodeType)[] ? N : TNodes[keyof TNodes]["type"], TEdges[K]["to"] extends readonly (infer N extends NodeType)[] ? N : TNodes[keyof TNodes]["type"]> : never;
-};
-/**
- * Configuration for defineGraph.
- */
-type GraphDefConfig<TNodes extends Record<string, NodeRegistration>, TEdges extends Record<string, EdgeEntry>, TOntology extends readonly OntologyRelation[]> = Readonly<{
-    /** Unique identifier for this graph */
-    id: string;
-    /** Node registrations */
-    nodes: TNodes;
-    /** Edge registrations or EdgeTypes with built-in domain/range */
-    edges: TEdges;
-    /** Ontology relations */
-    ontology?: TOntology;
-    /** Graph-wide defaults */
-    defaults?: GraphDefaults;
-    /**
-     * Index declarations attached to this graph.
-     *
-     * Accepts the outputs of `defineNodeIndex` / `defineEdgeIndex` (which
-     * already return `IndexDeclaration` values) or pre-built declarations
-     * reconstructed from a stored schema or graph extension.
-     *
-     * Validated at definition time: every index must reference a `kind`
-     * that exists in `nodes` / `edges`, and index `name`s must be unique
-     * within the graph.
-     *
-     * Index DDL is **not** generated by `defineGraph`. Indexes flow into
-     * `SerializedSchema.indexes` so they can later be materialized via
-     * `store.materializeIndexes()` — lifting the storage concern out of
-     * the schema-version commit path.
-     */
-    indexes?: readonly IndexDeclaration[];
-}>;
-/**
- * A graph definition.
- *
- * This is a compile-time artifact that describes the structure of a graph.
- * Use `createStore()` to create a runtime store from this definition.
- */
-type GraphDef<TNodes extends Record<string, NodeRegistration> = Record<string, NodeRegistration>, TEdges extends Record<string, EdgeRegistration> = Record<string, EdgeRegistration>, TOntology extends readonly OntologyRelation[] = readonly OntologyRelation[]> = Readonly<{
-    [GRAPH_DEF_BRAND]: true;
-    id: string;
-    nodes: TNodes;
-    edges: TEdges;
-    ontology: TOntology;
-    defaults: Readonly<{
-        onNodeDelete: DeleteBehavior;
-        temporalMode: TemporalMode;
-    }>;
-    /**
-     * Index declarations attached to this graph. Preserves whatever the
-     * caller passed to `defineGraph` (including an explicit empty array)
-     * for introspection purposes.
-     *
-     * The serialized canonical form is order-canonicalized (sorted by
-     * `name`) and treats `undefined` and `[]` as the same "no slice" form
-     * — an empty array does not bump the schema hash, since indexes are
-     * an unordered set keyed by name and `[]` carries no semantic meaning
-     * that an absent slice doesn't.
-     */
-    indexes: readonly IndexDeclaration[] | undefined;
-    /**
-     * Graph extension this graph was merged with, if any. Set by
-     * `mergeGraphExtension`; never set by `defineGraph` directly.
-     * Exists solely so re-serialization is stable — the rest of the
-     * system reads the merged kinds through `nodes` / `edges` /
-     * `ontology` and never inspects this field. Absent on graphs that
-     * have never been extended; legacy graphs hash byte-identically.
-     */
-    extension: GraphExtension | undefined;
-    /**
-     * Soft-deprecated kind names attached to this graph. Set by the
-     * loader from the persisted schema and by `store.deprecateKinds(...)`
-     * / `store.undeprecateKinds(...)`. A purely informational signal
-     * surfaced for introspection — does not gate reads, writes, or
-     * queries. Defaults to the empty set on freshly-defined graphs.
-     */
-    deprecatedKinds: ReadonlySet<string>;
-}>;
-/**
- * Extract node kind names from a GraphDef.
- */
-type NodeKinds<G extends GraphDef> = keyof G["nodes"] & string;
-/**
- * Extract edge kind names from a GraphDef.
- */
-type EdgeKinds<G extends GraphDef> = keyof G["edges"] & string;
-/**
- * Get a NodeType from a GraphDef by kind name.
- */
-type GetNodeType<G extends GraphDef, K extends NodeKinds<G>> = G["nodes"][K]["type"];
-/**
- * Get an EdgeType from a GraphDef by kind name.
- */
-type GetEdgeType<G extends GraphDef, K extends EdgeKinds<G>> = G["edges"][K]["type"];
-/**
- * Get all NodeTypes from a GraphDef.
- */
-type AllNodeTypes<G extends GraphDef> = {
-    [K in NodeKinds<G>]: G["nodes"][K]["type"];
-}[NodeKinds<G>];
-/**
- * Get all EdgeTypes from a GraphDef.
- */
-type AllEdgeTypes<G extends GraphDef> = {
-    [K in EdgeKinds<G>]: G["edges"][K]["type"];
-}[EdgeKinds<G>];
-/**
- * Creates a graph definition.
- *
- * @example
- * ```typescript
- * const graph = defineGraph({
- *   id: "my_graph",
- *   nodes: {
- *     Person: { type: Person },
- *     Company: { type: Company },
- *   },
- *   edges: {
- *     // Traditional EdgeRegistration syntax
- *     worksAt: {
- *       type: worksAt,
- *       from: [Person],
- *       to: [Company],
- *       cardinality: "many",
- *     },
- *     // Or use EdgeType directly if it has from/to defined
- *     knows,  // EdgeType with built-in domain/range
- *   },
- *   ontology: [
- *     subClassOf(Company, Organization),
- *     disjointWith(Person, Organization),
- *   ],
- *   defaults: {
- *     onNodeDelete: "restrict",
- *     temporalMode: "current",
- *   },
- * });
- * ```
- */
-declare function defineGraph<const TNodes extends Record<string, NodeRegistration<NodeType>>, const TEdges extends Record<string, EdgeEntry>, const TOntology extends readonly OntologyRelation[]>(config: GraphDefConfig<TNodes, TEdges, TOntology>): GraphDef<TNodes, NormalizedEdges<TNodes, TEdges>, TOntology>;
-/**
- * Checks if a value is a GraphDef.
- */
-declare function isGraphDef(value: unknown): value is GraphDef;
-/**
- * Gets all node kind names from a GraphDef.
- */
-declare function getNodeKinds<G extends GraphDef>(graph: G): readonly (keyof G["nodes"] & string)[];
-/**
- * Gets all edge kind names from a GraphDef.
- */
-declare function getEdgeKinds<G extends GraphDef>(graph: G): readonly (keyof G["edges"] & string)[];
-
-export { type AllEdgeTypes as A, type EdgeKinds as E, type GraphDef as G, type NodeKinds as N, type AllNodeTypes as a, type GetEdgeType as b, type GetNodeType as c, defineGraph as d, getNodeKinds as e, getEdgeKinds as g, isGraphDef as i };

package/dist/define-graph-SvYXOl78.d.ts

@@ -1,173 +0,0 @@
-import { N as NodeRegistration, E as EdgeRegistration, O as OntologyRelation, D as DeleteBehavior, T as TemporalMode, I as IndexDeclaration, G as GraphExtension, b as NodeType, c as AnyEdgeType, d as GraphDefaults } from './types-Cjvkj0jA.js';
-
-/** Brand key for GraphDef */
-declare const GRAPH_DEF_BRAND: "__graphDef";
-/**
- * An edge entry in the graph definition.
- * Can be:
- * - EdgeType directly (constrained or unconstrained)
- * - EdgeRegistration object (always works, can override/narrow defaults)
- */
-type EdgeEntry = EdgeRegistration | AnyEdgeType;
-/**
- * Normalized edge map type - all entries become EdgeRegistration.
- * For bare EdgeTypes, constrained endpoints are extracted from the type;
- * unconstrained edges fall back to all node types in the graph.
- */
-type NormalizedEdges<TNodes extends Record<string, NodeRegistration>, TEdges extends Record<string, EdgeEntry>> = {
-    [K in keyof TEdges]: TEdges[K] extends EdgeRegistration ? TEdges[K] : TEdges[K] extends AnyEdgeType ? EdgeRegistration<TEdges[K], TEdges[K]["from"] extends readonly (infer N extends NodeType)[] ? N : TNodes[keyof TNodes]["type"], TEdges[K]["to"] extends readonly (infer N extends NodeType)[] ? N : TNodes[keyof TNodes]["type"]> : never;
-};
-/**
- * Configuration for defineGraph.
- */
-type GraphDefConfig<TNodes extends Record<string, NodeRegistration>, TEdges extends Record<string, EdgeEntry>, TOntology extends readonly OntologyRelation[]> = Readonly<{
-    /** Unique identifier for this graph */
-    id: string;
-    /** Node registrations */
-    nodes: TNodes;
-    /** Edge registrations or EdgeTypes with built-in domain/range */
-    edges: TEdges;
-    /** Ontology relations */
-    ontology?: TOntology;
-    /** Graph-wide defaults */
-    defaults?: GraphDefaults;
-    /**
-     * Index declarations attached to this graph.
-     *
-     * Accepts the outputs of `defineNodeIndex` / `defineEdgeIndex` (which
-     * already return `IndexDeclaration` values) or pre-built declarations
-     * reconstructed from a stored schema or graph extension.
-     *
-     * Validated at definition time: every index must reference a `kind`
-     * that exists in `nodes` / `edges`, and index `name`s must be unique
-     * within the graph.
-     *
-     * Index DDL is **not** generated by `defineGraph`. Indexes flow into
-     * `SerializedSchema.indexes` so they can later be materialized via
-     * `store.materializeIndexes()` — lifting the storage concern out of
-     * the schema-version commit path.
-     */
-    indexes?: readonly IndexDeclaration[];
-}>;
-/**
- * A graph definition.
- *
- * This is a compile-time artifact that describes the structure of a graph.
- * Use `createStore()` to create a runtime store from this definition.
- */
-type GraphDef<TNodes extends Record<string, NodeRegistration> = Record<string, NodeRegistration>, TEdges extends Record<string, EdgeRegistration> = Record<string, EdgeRegistration>, TOntology extends readonly OntologyRelation[] = readonly OntologyRelation[]> = Readonly<{
-    [GRAPH_DEF_BRAND]: true;
-    id: string;
-    nodes: TNodes;
-    edges: TEdges;
-    ontology: TOntology;
-    defaults: Readonly<{
-        onNodeDelete: DeleteBehavior;
-        temporalMode: TemporalMode;
-    }>;
-    /**
-     * Index declarations attached to this graph. Preserves whatever the
-     * caller passed to `defineGraph` (including an explicit empty array)
-     * for introspection purposes.
-     *
-     * The serialized canonical form is order-canonicalized (sorted by
-     * `name`) and treats `undefined` and `[]` as the same "no slice" form
-     * — an empty array does not bump the schema hash, since indexes are
-     * an unordered set keyed by name and `[]` carries no semantic meaning
-     * that an absent slice doesn't.
-     */
-    indexes: readonly IndexDeclaration[] | undefined;
-    /**
-     * Graph extension this graph was merged with, if any. Set by
-     * `mergeGraphExtension`; never set by `defineGraph` directly.
-     * Exists solely so re-serialization is stable — the rest of the
-     * system reads the merged kinds through `nodes` / `edges` /
-     * `ontology` and never inspects this field. Absent on graphs that
-     * have never been extended; legacy graphs hash byte-identically.
-     */
-    extension: GraphExtension | undefined;
-    /**
-     * Soft-deprecated kind names attached to this graph. Set by the
-     * loader from the persisted schema and by `store.deprecateKinds(...)`
-     * / `store.undeprecateKinds(...)`. A purely informational signal
-     * surfaced for introspection — does not gate reads, writes, or
-     * queries. Defaults to the empty set on freshly-defined graphs.
-     */
-    deprecatedKinds: ReadonlySet<string>;
-}>;
-/**
- * Extract node kind names from a GraphDef.
- */
-type NodeKinds<G extends GraphDef> = keyof G["nodes"] & string;
-/**
- * Extract edge kind names from a GraphDef.
- */
-type EdgeKinds<G extends GraphDef> = keyof G["edges"] & string;
-/**
- * Get a NodeType from a GraphDef by kind name.
- */
-type GetNodeType<G extends GraphDef, K extends NodeKinds<G>> = G["nodes"][K]["type"];
-/**
- * Get an EdgeType from a GraphDef by kind name.
- */
-type GetEdgeType<G extends GraphDef, K extends EdgeKinds<G>> = G["edges"][K]["type"];
-/**
- * Get all NodeTypes from a GraphDef.
- */
-type AllNodeTypes<G extends GraphDef> = {
-    [K in NodeKinds<G>]: G["nodes"][K]["type"];
-}[NodeKinds<G>];
-/**
- * Get all EdgeTypes from a GraphDef.
- */
-type AllEdgeTypes<G extends GraphDef> = {
-    [K in EdgeKinds<G>]: G["edges"][K]["type"];
-}[EdgeKinds<G>];
-/**
- * Creates a graph definition.
- *
- * @example
- * ```typescript
- * const graph = defineGraph({
- *   id: "my_graph",
- *   nodes: {
- *     Person: { type: Person },
- *     Company: { type: Company },
- *   },
- *   edges: {
- *     // Traditional EdgeRegistration syntax
- *     worksAt: {
- *       type: worksAt,
- *       from: [Person],
- *       to: [Company],
- *       cardinality: "many",
- *     },
- *     // Or use EdgeType directly if it has from/to defined
- *     knows,  // EdgeType with built-in domain/range
- *   },
- *   ontology: [
- *     subClassOf(Company, Organization),
- *     disjointWith(Person, Organization),
- *   ],
- *   defaults: {
- *     onNodeDelete: "restrict",
- *     temporalMode: "current",
- *   },
- * });
- * ```
- */
-declare function defineGraph<const TNodes extends Record<string, NodeRegistration<NodeType>>, const TEdges extends Record<string, EdgeEntry>, const TOntology extends readonly OntologyRelation[]>(config: GraphDefConfig<TNodes, TEdges, TOntology>): GraphDef<TNodes, NormalizedEdges<TNodes, TEdges>, TOntology>;
-/**
- * Checks if a value is a GraphDef.
- */
-declare function isGraphDef(value: unknown): value is GraphDef;
-/**
- * Gets all node kind names from a GraphDef.
- */
-declare function getNodeKinds<G extends GraphDef>(graph: G): readonly (keyof G["nodes"] & string)[];
-/**
- * Gets all edge kind names from a GraphDef.
- */
-declare function getEdgeKinds<G extends GraphDef>(graph: G): readonly (keyof G["edges"] & string)[];
-
-export { type AllEdgeTypes as A, type EdgeKinds as E, type GraphDef as G, type NodeKinds as N, type AllNodeTypes as a, type GetEdgeType as b, type GetNodeType as c, defineGraph as d, getNodeKinds as e, getEdgeKinds as g, isGraphDef as i };