@nicia-ai/typegraph 0.49.0 → 0.51.0

package/dist/chunk-PC5NGH5A.js

@@ -0,0 +1,549 @@
+import { sql } from './chunk-7QFRK6PU.js';
+import { UnsupportedBackendCapabilityError, ConfigurationError } from './chunk-YDEJQWOL.js';
+import { requireDefined } from './chunk-DYATYRY4.js';
+
+// src/backend/table-contribution.ts
+var FULLTEXT_CONTRIBUTION_NAME = "fulltext";
+var BASE_CONTRIBUTION_OWNER = "base";
+
+// src/query/dialect/fulltext-strategy.ts
+var ALL_FULLTEXT_MODES = [
+  "websearch",
+  "phrase",
+  "plain",
+  "raw"
+];
+function buildFulltextCapabilities(strategy) {
+  return {
+    supported: true,
+    languages: strategy.languages,
+    phraseQueries: strategy.supportedModes.includes("phrase"),
+    prefixQueries: strategy.supportsPrefix,
+    highlighting: strategy.supportsSnippets
+  };
+}
+function buildFulltextGraphDelete(tableName, graphId) {
+  return sql`
+    DELETE FROM ${sql.identifier(tableName)}
+    WHERE "graph_id" = ${graphId}
+  `;
+}
+function buildForeignFulltextGraphProbe(tableName, graphId, limit) {
+  return sql`
+    SELECT DISTINCT "graph_id"
+    FROM ${sql.identifier(tableName)}
+    WHERE "graph_id" <> ${graphId}
+    LIMIT ${limit}
+  `;
+}
+function quoteIdentifier(name) {
+  return `"${name.replaceAll('"', '""')}"`;
+}
+function tsvectorColumn(tableName) {
+  return sql`${sql.identifier(tableName)}."tsv"`;
+}
+function dedupeFulltextBatchRows(rows) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const row of rows) seen.set(row.nodeId, row);
+  return [...seen.values()];
+}
+function buildPkScopedDelete(tableName, params) {
+  const table = sql.identifier(tableName);
+  return sql`
+    DELETE FROM ${table}
+    WHERE "graph_id" = ${params.graphId}
+      AND "node_kind" = ${params.nodeKind}
+      AND "node_id" = ${params.nodeId}
+  `;
+}
+function buildPkScopedBatchDelete(tableName, params) {
+  if (params.nodeIds.length === 0) return void 0;
+  const unique = [...new Set(params.nodeIds)];
+  const table = sql.identifier(tableName);
+  return sql`
+    DELETE FROM ${table}
+    WHERE "graph_id" = ${params.graphId}
+      AND "node_kind" = ${params.nodeKind}
+      AND "node_id" IN (${sql.join(
+    unique.map((id) => sql`${id}`),
+    sql`, `
+  )})
+  `;
+}
+function postgresTsquery(mode, query, language) {
+  const langExpr = language === void 0 ? sql`"language"` : sql`${language}::regconfig`;
+  switch (mode) {
+    case "websearch": {
+      return sql`websearch_to_tsquery(${langExpr}, ${query})`;
+    }
+    case "phrase": {
+      return sql`phraseto_tsquery(${langExpr}, ${query})`;
+    }
+    case "plain": {
+      return sql`plainto_tsquery(${langExpr}, ${query})`;
+    }
+    case "raw": {
+      return sql`to_tsquery(${langExpr}, ${query})`;
+    }
+    default: {
+      const _exhaustive = mode;
+      throw new Error(`Unsupported fulltext mode: ${String(_exhaustive)}`);
+    }
+  }
+}
+var tsvectorStrategy = {
+  name: "tsvector",
+  supportedModes: ALL_FULLTEXT_MODES,
+  supportsSnippets: true,
+  // `raw` mode exposes `foo:*` prefix-match syntax to callers.
+  supportsPrefix: true,
+  supportsLanguageOverride: true,
+  // Canonical Postgres stemmers; every stock install ships these plus a
+  // few others. Runtime `to_tsvector` accepts any installed regconfig
+  // name — this list is advisory for capability discovery.
+  languages: [
+    "simple",
+    "english",
+    "french",
+    "german",
+    "italian",
+    "portuguese",
+    "russian",
+    "spanish",
+    "swedish"
+  ],
+  matchCondition(tableName, query, mode, language) {
+    const q = postgresTsquery(mode, query, language);
+    return sql`${tsvectorColumn(tableName)} @@ ${q}`;
+  },
+  rankExpression(tableName, query, mode, language) {
+    const q = postgresTsquery(mode, query, language);
+    return sql`ts_rank_cd(${tsvectorColumn(tableName)}, ${q})`;
+  },
+  snippetExpression(_tableName, query, mode, language) {
+    const langExpr = language === void 0 ? sql`"language"` : sql`${language}::regconfig`;
+    const q = postgresTsquery(mode, query, language);
+    return sql`ts_headline(${langExpr}, "content", ${q}, 'StartSel=<mark>,StopSel=</mark>,MaxFragments=1,MinWords=5,MaxWords=30,ShortWord=3')`;
+  },
+  ownedTables(primaryTableName) {
+    const name = quoteIdentifier(primaryTableName);
+    const gin = quoteIdentifier(`${primaryTableName}_tsv_idx`);
+    const kind = quoteIdentifier(`${primaryTableName}_kind_idx`);
+    const createDdl = [
+      `CREATE TABLE IF NOT EXISTS ${name} (
+  "graph_id" TEXT NOT NULL,
+  "node_kind" TEXT NOT NULL,
+  "node_id" TEXT NOT NULL,
+  "content" TEXT NOT NULL,
+  "language" regconfig NOT NULL,
+  "tsv" tsvector NOT NULL
+    GENERATED ALWAYS AS (to_tsvector("language", "content")) STORED,
+  "updated_at" TIMESTAMPTZ NOT NULL,
+  PRIMARY KEY ("graph_id", "node_kind", "node_id")
+);`,
+      `CREATE INDEX IF NOT EXISTS ${gin} ON ${name} USING GIN ("tsv");`,
+      `CREATE INDEX IF NOT EXISTS ${kind} ON ${name} ("graph_id", "node_kind");`
+    ];
+    return [
+      {
+        logicalName: FULLTEXT_CONTRIBUTION_NAME,
+        owner: "tsvector",
+        tableName: primaryTableName,
+        createDdl,
+        // Both indexes belong to the table, so Postgres drops them with
+        // it; no separate DROP INDEX is needed or wanted (naming them
+        // would break the moment a future createDdl renames one).
+        dropDdl: [`DROP TABLE IF EXISTS ${name};`],
+        runtimeEnsure: true
+      }
+    ];
+  },
+  buildUpsert(tableName, params, timestamp) {
+    const table = sql.identifier(tableName);
+    return [
+      sql`
+        INSERT INTO ${table} ("graph_id", "node_kind", "node_id", "content", "language", "updated_at")
+        VALUES (
+          ${params.graphId}, ${params.nodeKind}, ${params.nodeId},
+          ${params.content}, ${params.language}::regconfig,
+          ${timestamp}
+        )
+        ON CONFLICT ("graph_id", "node_kind", "node_id")
+        DO UPDATE SET
+          "content" = EXCLUDED."content",
+          "language" = EXCLUDED."language",
+          "updated_at" = EXCLUDED."updated_at"
+      `
+    ];
+  },
+  buildBatchUpsert(tableName, params, timestamp) {
+    const rows = dedupeFulltextBatchRows(params.rows);
+    if (rows.length === 0) return [];
+    const table = sql.identifier(tableName);
+    const valueTuples = rows.map(
+      (row) => sql`
+        (
+              ${params.graphId}, ${params.nodeKind}, ${row.nodeId},
+              ${row.content}, ${row.language}::regconfig,
+              ${timestamp}
+            )
+      `
+    );
+    return [
+      sql`
+        INSERT INTO ${table} ("graph_id", "node_kind", "node_id", "content", "language", "updated_at")
+        VALUES ${sql.join(valueTuples, sql`, `)}
+        ON CONFLICT ("graph_id", "node_kind", "node_id")
+        DO UPDATE SET
+          "content" = EXCLUDED."content",
+          "language" = EXCLUDED."language",
+          "updated_at" = EXCLUDED."updated_at"
+      `
+    ];
+  },
+  buildDelete(tableName, params) {
+    return [buildPkScopedDelete(tableName, params)];
+  },
+  buildBatchDelete(tableName, params) {
+    const stmt = buildPkScopedBatchDelete(tableName, params);
+    return stmt === void 0 ? [] : [stmt];
+  }
+};
+function translateToFts5Query(query, mode) {
+  switch (mode) {
+    case "phrase": {
+      return `"${query.replaceAll('"', '""')}"`;
+    }
+    case "plain": {
+      return query.trim().split(/\s+/u).filter((token) => token.length > 0).map((token) => `"${token.replaceAll('"', '""')}"`).join(" ");
+    }
+    case "websearch": {
+      return translateWebsearchToFts5(query);
+    }
+    case "raw": {
+      return query;
+    }
+    default: {
+      const _exhaustive = mode;
+      throw new Error(`Unsupported fulltext mode: ${String(_exhaustive)}`);
+    }
+  }
+}
+function translateWebsearchToFts5(query) {
+  const tokens = [];
+  let index = 0;
+  function skipWhitespace() {
+    while (index < query.length && /\s/u.test(query[index] ?? "")) {
+      index += 1;
+    }
+  }
+  function readPhrase() {
+    index += 1;
+    let content = "";
+    while (index < query.length && query[index] !== '"') {
+      content += query[index] ?? "";
+      index += 1;
+    }
+    if (query[index] === '"') index += 1;
+    return `"${content.replaceAll('"', '""')}"`;
+  }
+  function readBareTerm() {
+    let term = "";
+    while (index < query.length && !/\s/u.test(query[index] ?? "")) {
+      term += query[index] ?? "";
+      index += 1;
+    }
+    return term;
+  }
+  while (index < query.length) {
+    skipWhitespace();
+    if (index >= query.length) break;
+    const ch = query[index];
+    if (ch === '"') {
+      tokens.push(readPhrase());
+      continue;
+    }
+    if (ch === "-") {
+      index += 1;
+      const term = query[index] === '"' ? readPhrase() : `"${readBareTerm().replaceAll('"', '""')}"`;
+      tokens.push(`NOT ${term}`);
+      continue;
+    }
+    if (ch === "+") {
+      index += 1;
+      continue;
+    }
+    const bare = readBareTerm();
+    if (bare.length === 0) continue;
+    if (bare.toUpperCase() === "OR") {
+      tokens.push("OR");
+      continue;
+    }
+    tokens.push(`"${bare.replaceAll('"', '""')}"`);
+  }
+  if (tokens.length > 0 && tokens[0]?.startsWith("NOT ")) {
+    tokens.shift();
+  }
+  return tokens.join(" ");
+}
+var fts5Strategy = {
+  name: "fts5",
+  supportedModes: ALL_FULLTEXT_MODES,
+  supportsSnippets: true,
+  // FTS5 supports `foo*` prefix matching natively.
+  supportsPrefix: true,
+  // FTS5 tokenizer is fixed at table-create time; per-row / per-query
+  // language metadata is stored but not consulted.
+  supportsLanguageOverride: false,
+  // The built-in tokenizer is `porter unicode61 remove_diacritics 2`; the
+  // `language` field on searchable() is recorded for future use but not
+  // applied at query time.
+  languages: ["porter", "unicode61", "trigram"],
+  matchCondition(tableName, query, mode, _language) {
+    const matchExpression = translateToFts5Query(query, mode);
+    return sql`${sql.identifier(tableName)} MATCH ${matchExpression}`;
+  },
+  rankExpression(tableName, _query, _mode, _language) {
+    return sql`-bm25(${sql.identifier(tableName)})`;
+  },
+  snippetExpression(tableName, _query, _mode, _language) {
+    return sql`snippet(${sql.identifier(tableName)}, -1, '<mark>', '</mark>', '…', 20)`;
+  },
+  ownedTables(primaryTableName) {
+    const name = quoteIdentifier(primaryTableName);
+    return [
+      {
+        logicalName: FULLTEXT_CONTRIBUTION_NAME,
+        owner: "fts5",
+        tableName: primaryTableName,
+        createDdl: [
+          `CREATE VIRTUAL TABLE IF NOT EXISTS ${name} USING fts5(
+  graph_id UNINDEXED,
+  node_kind UNINDEXED,
+  node_id UNINDEXED,
+  language UNINDEXED,
+  updated_at UNINDEXED,
+  content,
+  tokenize='porter unicode61 remove_diacritics 2'
+);`
+        ],
+        // `DROP TABLE` on an FTS5 virtual table also removes the shadow
+        // tables (`_data`, `_idx`, `_content`, …) the module created, so
+        // one statement is the whole teardown.
+        dropDdl: [`DROP TABLE IF EXISTS ${name};`],
+        runtimeEnsure: true
+      }
+    ];
+  },
+  buildUpsert(tableName, params, timestamp) {
+    const table = sql.identifier(tableName);
+    return [
+      sql`
+        DELETE FROM ${table}
+        WHERE "graph_id" = ${params.graphId}
+          AND "node_kind" = ${params.nodeKind}
+          AND "node_id" = ${params.nodeId}
+      `,
+      sql`
+        INSERT INTO ${table} (graph_id, node_kind, node_id, content, language, updated_at)
+        VALUES (${params.graphId}, ${params.nodeKind}, ${params.nodeId}, ${params.content}, ${params.language}, ${timestamp})
+      `
+    ];
+  },
+  buildBatchUpsert(tableName, params, timestamp) {
+    const rows = dedupeFulltextBatchRows(params.rows);
+    if (rows.length === 0) return [];
+    const table = sql.identifier(tableName);
+    const nodeIds = rows.map((row) => row.nodeId);
+    const deleteStmt = sql`
+      DELETE FROM ${table}
+      WHERE "graph_id" = ${params.graphId}
+        AND "node_kind" = ${params.nodeKind}
+        AND "node_id" IN (${sql.join(
+      nodeIds.map((id) => sql`${id}`),
+      sql`, `
+    )})
+    `;
+    const valueTuples = rows.map(
+      (row) => sql`
+        (
+              ${params.graphId}, ${params.nodeKind}, ${row.nodeId},
+              ${row.content}, ${row.language}, ${timestamp}
+            )
+      `
+    );
+    const insertStmt = sql`
+      INSERT INTO ${table} (graph_id, node_kind, node_id, content, language, updated_at)
+      VALUES ${sql.join(valueTuples, sql`, `)}
+    `;
+    return [deleteStmt, insertStmt];
+  },
+  buildDelete(tableName, params) {
+    return [buildPkScopedDelete(tableName, params)];
+  },
+  buildBatchDelete(tableName, params) {
+    const stmt = buildPkScopedBatchDelete(tableName, params);
+    return stmt === void 0 ? [] : [stmt];
+  }
+};
+
+// src/query/dialect/vector-strategy.ts
+var VECTOR_CONTRIBUTION_PREFIX = "vector";
+function buildVectorCapabilities(strategy) {
+  return strategy.capabilities;
+}
+function vectorScoreExpression(distanceExpression, metric) {
+  switch (metric) {
+    case "cosine": {
+      return sql`(1 - (${distanceExpression}))`;
+    }
+    case "l2":
+    case "inner_product": {
+      return distanceExpression;
+    }
+    default: {
+      const _exhaustive = metric;
+      throw new Error(`Unsupported vector metric: ${String(_exhaustive)}`);
+    }
+  }
+}
+function vectorMinScoreCondition(distanceExpression, metric, minScore) {
+  assertVectorMinScore(minScore, metric);
+  switch (metric) {
+    case "cosine": {
+      return sql`${distanceExpression} <= ${1 - minScore}`;
+    }
+    case "l2": {
+      return sql`${distanceExpression} <= ${minScore}`;
+    }
+    case "inner_product": {
+      return sql`${distanceExpression} <= ${-minScore}`;
+    }
+    default: {
+      const _exhaustive = metric;
+      throw new Error(`Unsupported vector metric: ${String(_exhaustive)}`);
+    }
+  }
+}
+function assertFiniteEmbedding(embedding, name) {
+  for (const [index, value] of embedding.entries()) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      throw new TypeError(
+        `${name}[${index}] must be a finite number, got: ${value}`
+      );
+    }
+  }
+}
+function assertVectorSearchLimit(limit) {
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw new RangeError(
+      `vectorSearch limit must be a positive integer, got: ${limit}`
+    );
+  }
+}
+function vectorSearchFrontierTuning(strategy) {
+  return strategy?.capabilities.searchFrontierTuning ?? {
+    tunable: false,
+    reason: "vector support is disabled on this backend"
+  };
+}
+function resolveEfSearchOverride(applicability) {
+  const { efSearch, indexType, tuning, transactions, dialect, engine } = applicability;
+  if (efSearch === void 0) return void 0;
+  if (!tuning.tunable) {
+    throw new UnsupportedBackendCapabilityError(
+      `${dialect} efSearch override`,
+      "vector.searchFrontierTuning",
+      { efSearch, engine, reason: tuning.reason },
+      `Omit efSearch: ${engine} has no per-search ANN frontier parameter (${tuning.reason}). Tune recall with the search limit, or use an exact search.`
+    );
+  }
+  if (indexType !== tuning.indexType) {
+    throw new ConfigurationError(
+      `${dialect} efSearch requires an ${tuning.indexType.toUpperCase()} vector index.`,
+      { efSearch, indexType },
+      {
+        suggestion: `Configure the embedding with index: { type: "${tuning.indexType}" }, or omit efSearch.`
+      }
+    );
+  }
+  if (tuning.requiresTransactionScope && !transactions) {
+    throw new UnsupportedBackendCapabilityError(
+      `${dialect} efSearch override`,
+      "transactions",
+      { efSearch, engine, parameter: tuning.parameter },
+      `Use a transactional ${dialect} driver: ${tuning.parameter} is scoped to the search's own transaction, and a session-wide setting would leak into concurrent searches.`
+    );
+  }
+  return tuning.parameter;
+}
+function assertApproximateMetricSupported(request) {
+  const {
+    approximate,
+    requestedMetric,
+    declaredMetric,
+    indexType,
+    nodeKind,
+    fieldPath
+  } = request;
+  if (approximate !== true) return;
+  if (indexType === "none") return;
+  if (requestedMetric === void 0 || requestedMetric === declaredMetric) {
+    return;
+  }
+  throw new ConfigurationError(
+    `Approximate retrieval for "${nodeKind}.${fieldPath}" cannot use metric "${requestedMetric}": its ${indexType.toUpperCase()} index is built for "${declaredMetric}", and an ANN structure only retrieves under the metric it was built for.`,
+    {
+      nodeKind,
+      fieldPath,
+      requestedMetric,
+      declaredMetric,
+      indexType
+    },
+    {
+      suggestion: `Omit metric (or pass "${declaredMetric}") to keep approximate retrieval, or drop approximate to scan exactly under "${requestedMetric}".`
+    }
+  );
+}
+function assertVectorMinScore(minScore, metric, label = "minScore") {
+  if (!Number.isFinite(minScore)) {
+    throw new RangeError(`${label} must be a finite number, got: ${minScore}`);
+  }
+  if (metric === "cosine" && Math.abs(minScore) > 1) {
+    throw new RangeError(
+      `${label} for the cosine metric must be between -1 and 1, got: ${minScore}`
+    );
+  }
+}
+var MAX_VECTOR_IDENTIFIER_LENGTH = 63;
+function sanitizeIdentifierPart(value) {
+  return value.toLowerCase().replaceAll(/[^a-z0-9_]/g, "_");
+}
+function shortHash(input) {
+  let h1 = 3735928559;
+  let h2 = 1103547991;
+  for (let index = 0; index < input.length; index++) {
+    const ch = requireDefined(input.codePointAt(index));
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
+  h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
+  const hi = (h2 >>> 0).toString(16).padStart(8, "0");
+  const lo = (h1 >>> 0).toString(16).padStart(8, "0");
+  return `${hi}${lo}`.slice(0, 8);
+}
+function vectorPhysicalName(prefix, graphId, nodeKind, fieldPath) {
+  const readable = `${prefix}_${sanitizeIdentifierPart(graphId)}_${sanitizeIdentifierPart(nodeKind)}_${sanitizeIdentifierPart(fieldPath)}`;
+  const hash = shortHash(JSON.stringify([graphId, nodeKind, fieldPath]));
+  const full = `${readable}_${hash}`;
+  if (full.length <= MAX_VECTOR_IDENTIFIER_LENGTH) return full;
+  return `${readable.slice(0, MAX_VECTOR_IDENTIFIER_LENGTH - 1 - hash.length)}_${hash}`;
+}
+function quoteIdentifier2(name) {
+  return `"${name.replaceAll('"', '""')}"`;
+}
+
+export { ALL_FULLTEXT_MODES, BASE_CONTRIBUTION_OWNER, FULLTEXT_CONTRIBUTION_NAME, VECTOR_CONTRIBUTION_PREFIX, assertApproximateMetricSupported, assertFiniteEmbedding, assertVectorMinScore, assertVectorSearchLimit, buildForeignFulltextGraphProbe, buildFulltextCapabilities, buildFulltextGraphDelete, buildVectorCapabilities, fts5Strategy, quoteIdentifier2 as quoteIdentifier, resolveEfSearchOverride, shortHash, tsvectorStrategy, vectorMinScoreCondition, vectorPhysicalName, vectorScoreExpression, vectorSearchFrontierTuning };
+//# sourceMappingURL=chunk-PC5NGH5A.js.map
+//# sourceMappingURL=chunk-PC5NGH5A.js.map