@vibeorm/extensions 2.0.0-alpha.1

package/dist/index.js

@@ -0,0 +1,966 @@
+// @bun
+// packages/extensions/src/search/index.ts
+import { VibeError as VibeError2, defineExtension, unsupportedCapability } from "@vibeorm/schema";
+import { ParamCollector, getSqlDialect, renderExpr } from "@vibeorm/sql";
+
+// packages/extensions/src/shared.ts
+import { VibeError } from "@vibeorm/schema";
+function tableNameOf(params) {
+  return params.model.dbName ?? params.model.name;
+}
+function columnNameOf(params) {
+  const found = params.model.fields.find((candidate) => candidate.name === params.field);
+  if (found === undefined) {
+    throw new VibeError({
+      code: "VIBE_INTERNAL",
+      message: `extension referenced unknown field "${params.field}" on model "${params.model.name}"`,
+      meta: { model: params.model.name, field: params.field }
+    });
+  }
+  return found.dbName ?? found.name;
+}
+function primaryKeyFieldOf(params) {
+  const { model } = params;
+  if (model.primaryKey !== undefined && model.primaryKey.fields.length === 1) {
+    return model.primaryKey.fields[0] ?? null;
+  }
+  const idField = model.fields.find((field) => field.isId);
+  return idField?.name ?? null;
+}
+function declString(decl, key) {
+  const value = decl[key];
+  return typeof value === "string" ? value : undefined;
+}
+function declStringArray(decl, key) {
+  const value = decl[key];
+  if (!Array.isArray(value))
+    return;
+  return value.every((entry) => typeof entry === "string") ? value : undefined;
+}
+function declNumberArray(decl, key) {
+  const value = decl[key];
+  if (!Array.isArray(value))
+    return;
+  return value.every((entry) => typeof entry === "number") ? value : undefined;
+}
+var SQL_LITERAL_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isSafeSqlName(params) {
+  return SQL_LITERAL_NAME.test(params.name);
+}
+async function pgExtensionCheck(params) {
+  const { execute, name } = params;
+  try {
+    const rows = await execute({
+      text: "SELECT name, default_version, installed_version FROM pg_available_extensions WHERE name = $1",
+      values: [name]
+    });
+    const row = rows[0];
+    if (row === undefined) {
+      return { name: `extension ${name}`, ok: false, note: "not available on this server" };
+    }
+    const installed = row["installed_version"];
+    return {
+      name: `extension ${name}`,
+      ok: true,
+      note: installed === null || installed === undefined ? "available, not installed" : `installed ${String(installed)}`
+    };
+  } catch (error) {
+    return {
+      name: `extension ${name}`,
+      ok: false,
+      note: `check failed: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+
+// packages/extensions/src/search/index.ts
+var VERSION = "2.0.0-alpha.0";
+var SCORE_ALIAS = "_vibe_score";
+var HIGHLIGHT_ALIAS = "_vibe_highlight";
+var WEIGHT_LETTERS = ["A", "B", "C", "D"];
+function resolveSearchEngine(params) {
+  const { dialect, provider, requested } = params;
+  const native = dialect === "postgres" ? "tsvector" : dialect === "sqlite" ? "fts5" : "fulltext";
+  if (requested === "auto")
+    return native;
+  if (requested === native)
+    return native;
+  if (requested === "bm25" && dialect === "postgres") {
+    if (provider === "pglite") {
+      throw unsupportedCapability({
+        dialect,
+        feature: 'the search engine "bm25" (ParadeDB pg_search)',
+        hint: 'pglite does not bundle pg_search \u2014 use engine "auto"/"tsvector"'
+      });
+    }
+    return "bm25";
+  }
+  throw unsupportedCapability({
+    dialect,
+    feature: `the search engine "${requested}"`,
+    hint: `this dialect supports "${native}"${dialect === "postgres" ? ' and "bm25"' : ""}`
+  });
+}
+function readDeclaration(params) {
+  const fields = declStringArray(params.declaration, "fields");
+  if (fields === undefined || fields.length === 0)
+    return null;
+  return {
+    fields,
+    weights: declNumberArray(params.declaration, "weights"),
+    base: declString(params.declaration, "name") ?? `${tableNameOf({ model: params.model })}_search`,
+    language: declString(params.declaration, "language")
+  };
+}
+function weightLetters(params) {
+  const { decl } = params;
+  if (decl.weights === undefined || decl.weights.length !== decl.fields.length)
+    return null;
+  const ranked = [...new Set(decl.weights)].sort((a, b) => b - a);
+  return decl.weights.map((weight) => WEIGHT_LETTERS[Math.min(ranked.indexOf(weight), WEIGHT_LETTERS.length - 1)]);
+}
+function tsvectorExpression(params) {
+  const { dialect, model, decl, language } = params;
+  const quote = (name) => dialect.quoteIdent({ name });
+  const letters = weightLetters({ decl });
+  const parts = decl.fields.map((field, index) => {
+    const vector = `to_tsvector('${language}', coalesce(${quote(columnNameOf({ model, field }))}, ''))`;
+    return letters === null ? vector : `setweight(${vector}, '${letters[index]}')`;
+  });
+  return letters === null && parts.length > 1 ? `to_tsvector('${language}', ${decl.fields.map((field) => `coalesce(${quote(columnNameOf({ model, field }))}, '')`).join(" || ' ' || ")})` : parts.join(" || ");
+}
+function searchArtifacts(ctx) {
+  const requested = ctx.options["engine"] ?? "auto";
+  const engine = resolveSearchEngine({ dialect: ctx.dialect, provider: ctx.provider, requested });
+  const dialect = getSqlDialect({ dialect: ctx.dialect });
+  const quote = (name) => dialect.quoteIdent({ name });
+  const artifacts = [];
+  if (engine === "bm25") {
+    artifacts.push({
+      id: "search:extension:pg_search",
+      owns: { kind: "postgresExtension", name: "pg_search" },
+      create: ["CREATE EXTENSION IF NOT EXISTS pg_search;"],
+      drop: ["DROP EXTENSION IF EXISTS pg_search;"]
+    });
+  }
+  for (const [modelName, declaration] of Object.entries(ctx.declarations)) {
+    const model = ctx.schema.models.find((candidate) => candidate.name === modelName);
+    if (model === undefined)
+      continue;
+    const decl = readDeclaration({ model, declaration });
+    if (decl === null)
+      continue;
+    const table = tableNameOf({ model });
+    const columns = decl.fields.map((field) => columnNameOf({ model, field }));
+    if (engine === "tsvector") {
+      const language = decl.language ?? ctx.options["language"] ?? "english";
+      const tsvColumn = `${decl.base}_tsv`;
+      const expression = tsvectorExpression({ dialect, model, decl, language });
+      artifacts.push({
+        id: `search:${modelName}:column`,
+        owns: { kind: "column", table, column: tsvColumn },
+        create: [
+          `ALTER TABLE ${quote(table)} ADD COLUMN IF NOT EXISTS ${quote(tsvColumn)} tsvector GENERATED ALWAYS AS (${expression}) STORED;`
+        ],
+        drop: [`ALTER TABLE ${quote(table)} DROP COLUMN IF EXISTS ${quote(tsvColumn)};`]
+      }, {
+        id: `search:${modelName}:index`,
+        owns: { kind: "index", table, name: `${decl.base}_idx` },
+        create: [
+          `CREATE INDEX IF NOT EXISTS ${quote(`${decl.base}_idx`)} ON ${quote(table)} USING gin (${quote(tsvColumn)});`
+        ],
+        drop: [`DROP INDEX IF EXISTS ${quote(`${decl.base}_idx`)};`]
+      });
+      continue;
+    }
+    if (engine === "bm25") {
+      const pkField = primaryKeyFieldOf({ model });
+      if (pkField === null) {
+        throw new VibeError2({
+          code: "VIBE_SCHEMA_INVALID",
+          message: `@@search with engine "bm25" needs a single-column primary key on "${modelName}" (key_field)`,
+          meta: { model: modelName }
+        });
+      }
+      const pkColumn = columnNameOf({ model, field: pkField });
+      artifacts.push({
+        id: `search:${modelName}:index`,
+        owns: { kind: "index", table, name: `${decl.base}_idx` },
+        create: [
+          `CREATE INDEX IF NOT EXISTS ${quote(`${decl.base}_idx`)} ON ${quote(table)} USING bm25 (${[pkColumn, ...columns].map((column) => quote(column)).join(", ")}) WITH (key_field='${pkColumn}');`
+        ],
+        drop: [`DROP INDEX IF EXISTS ${quote(`${decl.base}_idx`)};`]
+      });
+      continue;
+    }
+    if (engine === "fts5") {
+      const pkName = primaryKeyFieldOf({ model });
+      const pkField = pkName === null ? undefined : model.fields.find((field) => field.name === pkName);
+      const pkIsRowidAlias = pkField !== undefined && !pkField.isList && (pkField.type === "Int" || pkField.type === "BigInt");
+      if (!pkIsRowidAlias) {
+        throw unsupportedCapability({
+          dialect: "sqlite",
+          feature: `@@search (fts5) on "${modelName}", whose primary key is not a single INTEGER column`,
+          hint: "fts5 external-content tables key on the rowid; only an Int/BigInt @id aliases and PINS it \u2014 any other key's implicit rowid can be renumbered by VACUUM, silently mis-linking search hits. Give the searched model an Int/BigInt @id."
+        });
+      }
+      const fts = `${decl.base}_fts`;
+      const columnList = columns.map((column) => quote(column)).join(", ");
+      const newList = columns.map((column) => `new.${quote(column)}`).join(", ");
+      const oldList = columns.map((column) => `old.${quote(column)}`).join(", ");
+      artifacts.push({
+        id: `search:${modelName}:fts5-table`,
+        owns: {
+          kind: "table",
+          name: fts,
+          auxiliaryPrefixes: [`${fts}_`]
+        },
+        create: [
+          `CREATE VIRTUAL TABLE IF NOT EXISTS ${quote(fts)} USING fts5(${columnList}, content='${table}');`
+        ],
+        drop: [`DROP TABLE IF EXISTS ${quote(fts)};`]
+      }, {
+        id: `search:${modelName}:fts5-triggers`,
+        owns: { kind: "trigger", table, name: `${fts}_ai` },
+        create: [
+          `CREATE TRIGGER IF NOT EXISTS ${quote(`${fts}_ai`)} AFTER INSERT ON ${quote(table)} BEGIN
+  INSERT INTO ${quote(fts)}(rowid, ${columnList}) VALUES (new.rowid, ${newList});
+END;`,
+          `CREATE TRIGGER IF NOT EXISTS ${quote(`${fts}_ad`)} AFTER DELETE ON ${quote(table)} BEGIN
+  INSERT INTO ${quote(fts)}(${quote(fts)}, rowid, ${columnList}) VALUES ('delete', old.rowid, ${oldList});
+END;`,
+          `CREATE TRIGGER IF NOT EXISTS ${quote(`${fts}_au`)} AFTER UPDATE ON ${quote(table)} BEGIN
+  INSERT INTO ${quote(fts)}(${quote(fts)}, rowid, ${columnList}) VALUES ('delete', old.rowid, ${oldList});
+  INSERT INTO ${quote(fts)}(rowid, ${columnList}) VALUES (new.rowid, ${newList});
+END;`
+        ],
+        drop: [
+          `DROP TRIGGER IF EXISTS ${quote(`${fts}_ai`)};`,
+          `DROP TRIGGER IF EXISTS ${quote(`${fts}_ad`)};`,
+          `DROP TRIGGER IF EXISTS ${quote(`${fts}_au`)};`
+        ]
+      });
+      continue;
+    }
+    artifacts.push({
+      id: `search:${modelName}:index`,
+      owns: { kind: "index", table, name: `${decl.base}_idx` },
+      create: [
+        `CREATE FULLTEXT INDEX ${quote(`${decl.base}_idx`)} ON ${quote(table)} (${columns.map((column) => quote(column)).join(", ")});`
+      ],
+      drop: [`DROP INDEX ${quote(`${decl.base}_idx`)} ON ${quote(table)};`]
+    });
+  }
+  return artifacts;
+}
+function highlightColumn(params) {
+  const { config, args } = params;
+  if (args.highlight === undefined)
+    return null;
+  const field = config.fields.find((candidate) => candidate.name === args.highlight?.field);
+  if (field === undefined) {
+    throw new VibeError2({
+      code: "VIBE_VALIDATION",
+      message: `highlight.field "${args.highlight.field}" is not searched \u2014 declared: ${config.fields.map((candidate) => candidate.name).join(", ")}`,
+      meta: { field: args.highlight.field }
+    });
+  }
+  return field.column;
+}
+function shapeHits(params) {
+  const { rows, strip, highlightsRequested, engineHasHighlights } = params;
+  return rows.map((raw) => {
+    const row = { ...raw };
+    const score = Number(row[SCORE_ALIAS]);
+    const highlight = row[HIGHLIGHT_ALIAS];
+    delete row[SCORE_ALIAS];
+    delete row[HIGHLIGHT_ALIAS];
+    for (const name of strip)
+      delete row[name];
+    const highlights = engineHasHighlights && highlightsRequested && highlight !== null && highlight !== undefined ? [String(highlight)] : null;
+    return { row, score, highlights };
+  });
+}
+function createSearchDelegate(config) {
+  return (ctx) => {
+    const dialect = ctx.dialect;
+    const quote = (name) => dialect.quoteIdent({ name });
+    const t = quote("t");
+    return async (args) => {
+      if (typeof args.query !== "string" || args.query.trim().length === 0) {
+        throw new VibeError2({
+          code: "VIBE_VALIDATION",
+          message: "search requires a non-empty query string",
+          meta: { table: config.table }
+        });
+      }
+      const take = Math.max(1, Math.trunc(args.take ?? 10));
+      const skip = args.skip === undefined ? null : Math.max(0, Math.trunc(args.skip));
+      const hlColumn = highlightColumn({ config, args });
+      const collector = new ParamCollector(dialect);
+      const userWhere = (qualify) => {
+        if (args.where === undefined)
+          return null;
+        const expr = ctx.compileWhere({ where: args.where, qualify });
+        return expr === undefined ? null : renderExpr({ dialect, expr, collector });
+      };
+      let text;
+      let strip = [];
+      let engineHasHighlights = true;
+      if (config.engine === "tsvector") {
+        const language = config.language ?? "english";
+        const tsv = `${t}.${quote(config.tsvColumn ?? "")}`;
+        const tsquery = () => `websearch_to_tsquery('${language}', ${collector.add(args.query)})`;
+        text = `SELECT ${t}.*, ts_rank_cd(${tsv}, ${tsquery()}) AS ${quote(SCORE_ALIAS)}`;
+        if (hlColumn !== null) {
+          text += `, ts_headline('${language}', ${t}.${quote(hlColumn)}, ${tsquery()}) AS ${quote(HIGHLIGHT_ALIAS)}`;
+        }
+        text += ` FROM ${quote(config.table)} AS ${t} WHERE ${tsv} @@ ${tsquery()}`;
+        const where = userWhere("t");
+        if (where !== null)
+          text += ` AND (${where})`;
+        if (args.minScore !== undefined) {
+          text += ` AND ts_rank_cd(${tsv}, ${tsquery()}) >= ${collector.add(args.minScore)}`;
+        }
+        text += ` ORDER BY ${quote(SCORE_ALIAS)} DESC`;
+        strip = [config.tsvColumn ?? ""];
+      } else if (config.engine === "fts5") {
+        const fts = quote(config.ftsTable ?? "");
+        text = `SELECT ${t}.*, -bm25(${fts}) AS ${quote(SCORE_ALIAS)}`;
+        if (hlColumn !== null) {
+          const index = config.fields.findIndex((field) => field.column === hlColumn);
+          text += `, snippet(${fts}, ${index}, '<b>', '</b>', '\u2026', 16) AS ${quote(HIGHLIGHT_ALIAS)}`;
+        }
+        text += ` FROM ${fts} JOIN ${quote(config.table)} AS ${t} ON ${t}.rowid = ${fts}.rowid`;
+        text += ` WHERE ${fts} MATCH ${collector.add(args.query)}`;
+        const where = userWhere("t");
+        if (where !== null)
+          text += ` AND (${where})`;
+        if (args.minScore !== undefined) {
+          text += ` AND -bm25(${fts}) >= ${collector.add(args.minScore)}`;
+        }
+        text += ` ORDER BY ${quote(SCORE_ALIAS)} DESC`;
+      } else if (config.engine === "fulltext") {
+        engineHasHighlights = false;
+        const match = () => `MATCH (${config.fields.map((field) => `${t}.${quote(field.column)}`).join(", ")}) AGAINST (${collector.add(args.query)} IN NATURAL LANGUAGE MODE)`;
+        text = `SELECT ${t}.*, ${match()} AS ${quote(SCORE_ALIAS)} FROM ${quote(config.table)} AS ${t}`;
+        text += ` WHERE ${match()}`;
+        const where = userWhere("t");
+        if (where !== null)
+          text += ` AND (${where})`;
+        if (args.minScore !== undefined) {
+          text += ` AND ${match()} >= ${collector.add(args.minScore)}`;
+        }
+        text += ` ORDER BY ${quote(SCORE_ALIAS)} DESC`;
+      } else {
+        const pk = `${t}.${quote(config.pkColumn ?? "")}`;
+        text = `SELECT ${t}.*, paradedb.score(${pk}) AS ${quote(SCORE_ALIAS)}`;
+        if (hlColumn !== null) {
+          text += `, paradedb.snippet(${t}.${quote(hlColumn)}) AS ${quote(HIGHLIGHT_ALIAS)}`;
+        }
+        text += ` FROM ${quote(config.table)} AS ${t} WHERE (${config.fields.map((field) => `${t}.${quote(field.column)} @@@ ${collector.add(args.query)}`).join(" OR ")})`;
+        const where = userWhere("t");
+        if (where !== null)
+          text += ` AND (${where})`;
+        text += ` ORDER BY ${quote(SCORE_ALIAS)} DESC`;
+      }
+      text += ` LIMIT ${take}`;
+      if (skip !== null)
+        text += ` OFFSET ${skip}`;
+      const rows = await ctx.executeRows({ text, values: collector.values, method: "search" });
+      let hits = shapeHits({
+        rows,
+        strip,
+        highlightsRequested: args.highlight !== undefined,
+        engineHasHighlights
+      });
+      if (config.engine === "bm25" && args.minScore !== undefined) {
+        const min = args.minScore;
+        hits = hits.filter((hit) => hit.score >= min);
+      }
+      return hits;
+    };
+  };
+}
+function search(options = {}) {
+  return defineExtension({
+    name: "search",
+    version: VERSION,
+    options: { ...options },
+    requires: { postgresql: null, pglite: null, sqlite: null, mysql: null },
+    schema: {
+      modelAttributes: [
+        {
+          name: "search",
+          parse: ({ args, fieldNames }) => {
+            const fields = args.fields ?? [];
+            if (fields.length === 0) {
+              return { error: "@@search requires a field list, e.g. @@search([title, body])" };
+            }
+            const missing = fields.find((name2) => !fieldNames.includes(name2));
+            if (missing !== undefined) {
+              return { error: `@@search references unknown field "${missing}"` };
+            }
+            const name = args.named["name"];
+            if (name !== undefined && (typeof name !== "string" || !isSafeSqlName({ name }))) {
+              return { error: `name must be a plain identifier` };
+            }
+            const weights = args.named["weights"];
+            if (weights !== undefined) {
+              if (!Array.isArray(weights) || weights.length !== fields.length || weights.some((weight) => typeof weight !== "number")) {
+                return { error: `weights must be a number list matching the field list` };
+              }
+            }
+            const language = args.named["language"];
+            if (language !== undefined && (typeof language !== "string" || !isSafeSqlName({ name: language }))) {
+              return { error: `language must be a plain text-search config name` };
+            }
+            return { declaration: { fields, ...args.named } };
+          }
+        }
+      ],
+      indexKinds: ["bm25", "fts5", "fulltext", "gin"]
+    },
+    migrate: { artifacts: searchArtifacts },
+    client: {
+      model: ({ model, dialect, provider, options: extOptions, declaration, typeNames }) => {
+        const decl = readDeclaration({ model, declaration });
+        if (decl === null)
+          return null;
+        const requested = extOptions["engine"] ?? "auto";
+        const engine = resolveSearchEngine({ dialect, provider, requested });
+        const language = decl.language ?? extOptions["language"] ?? "english";
+        if (!isSafeSqlName({ name: language })) {
+          throw new VibeError2({
+            code: "VIBE_SCHEMA_INVALID",
+            message: `search language "${language}" is not a plain text-search config name`,
+            meta: { model: model.name, language }
+          });
+        }
+        const pkField = primaryKeyFieldOf({ model });
+        const config = {
+          engine,
+          table: tableNameOf({ model }),
+          fields: decl.fields.map((field) => ({
+            name: field,
+            column: columnNameOf({ model, field })
+          })),
+          ...engine === "tsvector" ? { tsvColumn: `${decl.base}_tsv`, language } : {},
+          ...engine === "fts5" ? { ftsTable: `${decl.base}_fts` } : {},
+          ...engine === "bm25" && pkField !== null ? { pkColumn: columnNameOf({ model, field: pkField }) } : {}
+        };
+        const fieldUnion = decl.fields.map((field) => JSON.stringify(field)).join(" | ");
+        return {
+          kind: "method",
+          runtimeGlue: `createSearchDelegate(${JSON.stringify(config)})`,
+          imports: [{ from: "@vibeorm/extensions/search", names: ["createSearchDelegate"] }],
+          dtsImports: [{ from: "@vibeorm/extensions/search", names: ["SearchHit"] }],
+          dts: [
+            `readonly search: (args: {`,
+            `  readonly query: string;`,
+            `  readonly where?: ${typeNames.whereInput};`,
+            `  readonly take?: number;`,
+            `  readonly skip?: number;`,
+            `  readonly minScore?: number;`,
+            `  readonly highlight?: { readonly field: ${fieldUnion} };`,
+            `}) => Promise<SearchHit<${typeNames.payload}>[]>;`
+          ]
+        };
+      }
+    },
+    doctor: async ({ execute, dialect, options: extOptions }) => {
+      if (dialect === "postgres") {
+        const requested = extOptions["engine"] ?? "auto";
+        if (requested === "bm25") {
+          return { checks: [await pgExtensionCheck({ execute, name: "pg_search" })] };
+        }
+        return { checks: [{ name: "tsvector", ok: true, note: "built in" }] };
+      }
+      if (dialect === "sqlite") {
+        try {
+          const rows = await execute({
+            text: "SELECT 1 AS ok FROM pragma_compile_options WHERE compile_options = 'ENABLE_FTS5'"
+          });
+          return {
+            checks: [
+              rows.length > 0 ? { name: "fts5", ok: true, note: "compiled in" } : { name: "fts5", ok: false, note: "sqlite built without FTS5" }
+            ]
+          };
+        } catch (error) {
+          return {
+            checks: [
+              {
+                name: "fts5",
+                ok: false,
+                note: `check failed: ${error instanceof Error ? error.message : String(error)}`
+              }
+            ]
+          };
+        }
+      }
+      return { checks: [{ name: "fulltext", ok: true, note: "built in (InnoDB FULLTEXT)" }] };
+    }
+  });
+}
+
+// packages/extensions/src/vector/index.ts
+import { VibeError as VibeError3, defineExtension as defineExtension2, unsupportedCapability as unsupportedCapability2 } from "@vibeorm/schema";
+import { ParamCollector as ParamCollector2, getSqlDialect as getSqlDialect2, renderExpr as renderExpr2 } from "@vibeorm/sql";
+var VERSION2 = "2.0.0-alpha.0";
+var METRIC_OPERATOR = {
+  cosine: "<=>",
+  l2: "<->",
+  ip: "<#>"
+};
+var METRIC_OPCLASS = {
+  cosine: "vector_cosine_ops",
+  l2: "vector_l2_ops",
+  ip: "vector_ip_ops"
+};
+var METRICS = ["cosine", "l2", "ip"];
+var INDEX_KINDS = ["hnsw", "ivfflat"];
+var DISTANCE_ALIAS = "_vibe_distance";
+function vectorColumnsOf(params) {
+  const columns = params.declaration["columns"];
+  if (columns === null || typeof columns !== "object" || Array.isArray(columns))
+    return {};
+  const out = {};
+  for (const [field, spec] of Object.entries(columns)) {
+    if (spec === null || typeof spec !== "object")
+      continue;
+    const dims = spec.dims;
+    if (typeof dims === "number")
+      out[field] = { dims };
+  }
+  return out;
+}
+function vectorArtifacts(ctx) {
+  if (ctx.dialect !== "postgres") {
+    throw unsupportedCapability2({
+      dialect: ctx.dialect,
+      feature: "the vector extension (pgvector)",
+      hint: "pgvector exists on postgres/pglite only (sqlite-vec/mysql are post-2.0)"
+    });
+  }
+  const dialect = getSqlDialect2({ dialect: ctx.dialect });
+  const quote = (name) => dialect.quoteIdent({ name });
+  const artifacts = [
+    {
+      id: "vector:extension",
+      owns: { kind: "postgresExtension", name: "vector" },
+      create: ["CREATE EXTENSION IF NOT EXISTS vector;"],
+      drop: ["DROP EXTENSION IF EXISTS vector;"]
+    }
+  ];
+  for (const [modelName, declaration] of Object.entries(ctx.declarations)) {
+    const model = ctx.schema.models.find((candidate) => candidate.name === modelName);
+    if (model === undefined)
+      continue;
+    const table = tableNameOf({ model });
+    const columns = vectorColumnsOf({ declaration });
+    const indexFields = declStringArray(declaration, "fields") ?? [];
+    const kindRaw = declString(declaration, "index") ?? "hnsw";
+    const metricRaw = declString(declaration, "metric") ?? "cosine";
+    const metric = METRICS.find((candidate) => candidate === metricRaw) ?? "cosine";
+    for (const field of indexFields) {
+      if (columns[field] === undefined) {
+        throw new VibeError3({
+          code: "VIBE_SCHEMA_INVALID",
+          message: `@@vector on "${modelName}" indexes "${field}", which is not a Vector(n) column`,
+          meta: { model: modelName, field }
+        });
+      }
+      const column = columnNameOf({ model, field });
+      const indexName = `${table}_${column}_${kindRaw}_idx`;
+      const withOptions = [];
+      const m = declaration["m"];
+      const efConstruction = declaration["efConstruction"];
+      const lists = declaration["lists"];
+      if (kindRaw === "hnsw") {
+        if (typeof m === "number")
+          withOptions.push(`m = ${m}`);
+        if (typeof efConstruction === "number")
+          withOptions.push(`ef_construction = ${efConstruction}`);
+      } else if (typeof lists === "number") {
+        withOptions.push(`lists = ${lists}`);
+      }
+      const withClause = withOptions.length === 0 ? "" : ` WITH (${withOptions.join(", ")})`;
+      artifacts.push({
+        id: `vector:${modelName}:${field}`,
+        owns: { kind: "index", table, name: indexName },
+        create: [
+          `CREATE INDEX IF NOT EXISTS ${quote(indexName)} ON ${quote(table)} USING ${kindRaw} (${quote(column)} ${METRIC_OPCLASS[metric]})${withClause};`
+        ],
+        drop: [`DROP INDEX IF EXISTS ${quote(indexName)};`]
+      });
+    }
+  }
+  return artifacts;
+}
+function resolveColumn(params) {
+  const { config, args } = params;
+  const spec = config.columns[args.by];
+  if (spec === undefined) {
+    throw new VibeError3({
+      code: "VIBE_VALIDATION",
+      message: `"${args.by}" is not a Vector(n) column \u2014 declared: ${Object.keys(config.columns).join(", ")}`,
+      meta: { by: args.by }
+    });
+  }
+  if (!Array.isArray(args.to) || args.to.some((entry) => typeof entry !== "number" || !Number.isFinite(entry))) {
+    throw new VibeError3({
+      code: "VIBE_VALIDATION",
+      message: `vector "to" must be an array of finite numbers`,
+      meta: { by: args.by }
+    });
+  }
+  if (args.to.length !== spec.dims) {
+    throw new VibeError3({
+      code: "VIBE_VALIDATION",
+      message: `vector "to" has ${args.to.length} dimensions, "${args.by}" expects ${spec.dims}`,
+      meta: { by: args.by, dims: spec.dims }
+    });
+  }
+  return { column: spec.column, literal: `[${args.to.join(",")}]` };
+}
+function createVectorNamespace(config) {
+  return (ctx) => {
+    const dialect = ctx.dialect;
+    const quote = (name) => dialect.quoteIdent({ name });
+    const t = quote("t");
+    return {
+      nearest: async (args) => {
+        const { column, literal } = resolveColumn({ config, args });
+        const metric = args.metric ?? config.metric;
+        const op = METRIC_OPERATOR[metric];
+        const col = `${t}.${quote(column)}`;
+        const collector = new ParamCollector2(dialect);
+        let text = `SELECT ${t}.*, (${col} ${op} ${collector.add(literal)}) AS ${quote(DISTANCE_ALIAS)}`;
+        text += ` FROM ${quote(config.table)} AS ${t}`;
+        text += ` WHERE ${col} IS NOT NULL`;
+        if (args.where !== undefined) {
+          const expr = ctx.compileWhere({ where: args.where, qualify: "t" });
+          if (expr !== undefined)
+            text += ` AND (${renderExpr2({ dialect, expr, collector })})`;
+        }
+        if (args.maxDistance !== undefined) {
+          text += ` AND (${col} ${op} ${collector.add(literal)}) < ${collector.add(args.maxDistance)}`;
+        }
+        text += ` ORDER BY ${col} ${op} ${collector.add(literal)} LIMIT ${Math.max(1, Math.trunc(args.take ?? 10))}`;
+        const rows = await ctx.executeRows({
+          text,
+          values: collector.values,
+          method: "vector.nearest"
+        });
+        return rows.map((row) => {
+          const { [DISTANCE_ALIAS]: distance, ...rest } = row;
+          return { row: rest, distance: Number(distance) };
+        });
+      },
+      set: async (args) => {
+        const { column, literal } = resolveColumn({ config, args });
+        const collector = new ParamCollector2(dialect);
+        let text = `UPDATE ${quote(config.table)} SET ${quote(column)} = ${collector.add(literal)}`;
+        const expr = ctx.compileWhere({ where: args.where });
+        if (expr !== undefined)
+          text += ` WHERE ${renderExpr2({ dialect, expr, collector })}`;
+        text += ` RETURNING 1 AS ${quote("_vibe_set")}`;
+        const rows = await ctx.executeRows({ text, values: collector.values, method: "vector.set" });
+        return rows.length;
+      }
+    };
+  };
+}
+function vector(options = {}) {
+  return defineExtension2({
+    name: "vector",
+    version: VERSION2,
+    options: { ...options },
+    requires: { postgresql: { extension: "vector" }, pglite: { extension: "vector" } },
+    schema: {
+      fieldTypes: [
+        {
+          name: "Vector",
+          lower: ({ field, args }) => {
+            const dims = Number(args[0]);
+            if (!Number.isInteger(dims) || dims <= 0) {
+              return { error: "Vector(n) requires a positive integer dimension, e.g. Vector(1536)" };
+            }
+            return {
+              nativeType: `vector(${dims})`,
+              declaration: { columns: { [field]: { dims } } }
+            };
+          }
+        }
+      ],
+      modelAttributes: [
+        {
+          name: "vector",
+          parse: ({ args, fieldNames }) => {
+            const fields = args.fields ?? [];
+            if (fields.length === 0) {
+              return { error: "@@vector requires a field list, e.g. @@vector([embedding])" };
+            }
+            const missing = fields.find((name) => !fieldNames.includes(name));
+            if (missing !== undefined) {
+              return { error: `@@vector references unknown field "${missing}"` };
+            }
+            const metric = args.named["metric"];
+            if (metric !== undefined && !METRICS.includes(metric)) {
+              return { error: `metric must be one of ${METRICS.join(", ")}` };
+            }
+            const kind = args.named["index"];
+            if (kind !== undefined && !INDEX_KINDS.includes(String(kind))) {
+              return { error: `index must be one of ${INDEX_KINDS.join(", ")}` };
+            }
+            for (const key of ["m", "efConstruction", "lists"]) {
+              const value = args.named[key];
+              if (value !== undefined && typeof value !== "number") {
+                return { error: `${key} must be a number` };
+              }
+            }
+            return { declaration: { fields, ...args.named } };
+          }
+        }
+      ],
+      indexKinds: ["hnsw", "ivfflat"]
+    },
+    migrate: { artifacts: vectorArtifacts },
+    client: {
+      model: ({ model, dialect, declaration, typeNames }) => {
+        const columns = vectorColumnsOf({ declaration });
+        const fieldNames = Object.keys(columns);
+        if (fieldNames.length === 0)
+          return null;
+        if (dialect !== "postgres") {
+          throw unsupportedCapability2({
+            dialect,
+            feature: `the vector extension (declared on model "${model.name}")`,
+            hint: "pgvector exists on postgres/pglite only"
+          });
+        }
+        const metricRaw = declString(declaration, "metric");
+        const metric = METRICS.find((candidate) => candidate === metricRaw) ?? "cosine";
+        const config = {
+          table: tableNameOf({ model }),
+          columns: Object.fromEntries(fieldNames.map((field) => [
+            field,
+            { column: columnNameOf({ model, field }), dims: columns[field].dims }
+          ])),
+          metric
+        };
+        const byUnion = fieldNames.map((name) => JSON.stringify(name)).join(" | ");
+        return {
+          kind: "namespace",
+          runtimeGlue: `createVectorNamespace(${JSON.stringify(config)})`,
+          imports: [{ from: "@vibeorm/extensions/vector", names: ["createVectorNamespace"] }],
+          dtsImports: [{ from: "@vibeorm/extensions/vector", names: ["VectorHit", "VectorMetric"] }],
+          dts: [
+            `readonly vector: {`,
+            `  readonly nearest: (args: {`,
+            `    readonly by: ${byUnion};`,
+            `    readonly to: readonly number[];`,
+            `    readonly metric?: VectorMetric;`,
+            `    readonly take?: number;`,
+            `    readonly where?: ${typeNames.whereInput};`,
+            `    readonly maxDistance?: number;`,
+            `  }) => Promise<VectorHit<${typeNames.payload}>[]>;`,
+            `  readonly set: (args: {`,
+            `    readonly where: ${typeNames.whereInput};`,
+            `    readonly by: ${byUnion};`,
+            `    readonly to: readonly number[];`,
+            `  }) => Promise<number>;`,
+            `};`
+          ]
+        };
+      }
+    },
+    doctor: async ({ execute, dialect }) => {
+      if (dialect !== "postgres") {
+        return { checks: [{ name: "vector dialect", ok: false, note: "postgres/pglite only" }] };
+      }
+      return { checks: [await pgExtensionCheck({ execute, name: "vector" })] };
+    }
+  });
+}
+
+// packages/extensions/src/trgm/index.ts
+import { defineExtension as defineExtension3, unsupportedCapability as unsupportedCapability3 } from "@vibeorm/schema";
+import { getSqlDialect as getSqlDialect3 } from "@vibeorm/sql";
+var DEFAULT_THRESHOLD = 0.3;
+var VERSION3 = "2.0.0-alpha.0";
+function trgmArtifacts(ctx) {
+  if (ctx.dialect !== "postgres") {
+    throw unsupportedCapability3({
+      dialect: ctx.dialect,
+      feature: "the trgm extension (pg_trgm)",
+      hint: "pg_trgm exists on postgres/pglite only"
+    });
+  }
+  const dialect = getSqlDialect3({ dialect: ctx.dialect });
+  const quote = (name) => dialect.quoteIdent({ name });
+  const artifacts = [
+    {
+      id: "trgm:extension",
+      owns: { kind: "postgresExtension", name: "pg_trgm" },
+      create: ["CREATE EXTENSION IF NOT EXISTS pg_trgm;"],
+      drop: ["DROP EXTENSION IF EXISTS pg_trgm;"]
+    }
+  ];
+  for (const [modelName, declaration] of Object.entries(ctx.declarations)) {
+    const model = ctx.schema.models.find((candidate) => candidate.name === modelName);
+    if (model === undefined)
+      continue;
+    const table = tableNameOf({ model });
+    for (const field of declStringArray(declaration, "fields") ?? []) {
+      const column = columnNameOf({ model, field });
+      const indexName = `${table}_${column}_trgm_idx`;
+      artifacts.push({
+        id: `trgm:${modelName}:${field}`,
+        owns: { kind: "index", table, name: indexName },
+        create: [
+          `CREATE INDEX IF NOT EXISTS ${quote(indexName)} ON ${quote(table)} USING gin (${quote(column)} gin_trgm_ops);`
+        ],
+        drop: [`DROP INDEX IF EXISTS ${quote(indexName)};`]
+      });
+    }
+  }
+  return artifacts;
+}
+function trgm(options = {}) {
+  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+  return defineExtension3({
+    name: "trgm",
+    version: VERSION3,
+    options: { ...options },
+    requires: { postgresql: { extension: "pg_trgm" }, pglite: { extension: "pg_trgm" } },
+    schema: {
+      modelAttributes: [
+        {
+          name: "trgm",
+          parse: ({ args, fieldNames }) => {
+            const fields = args.fields ?? [];
+            if (fields.length === 0) {
+              return { error: "@@trgm requires a field list, e.g. @@trgm([name])" };
+            }
+            const missing = fields.find((name) => !fieldNames.includes(name));
+            if (missing !== undefined) {
+              return { error: `@@trgm references unknown field "${missing}"` };
+            }
+            return { declaration: { fields } };
+          }
+        }
+      ],
+      indexKinds: ["gin_trgm"]
+    },
+    migrate: { artifacts: trgmArtifacts },
+    sql: {
+      whereOperators: [
+        {
+          name: "similarTo",
+          compile: ({ column, operand, dialect, options: extOptions }) => {
+            if (dialect !== "postgres") {
+              throw unsupportedCapability3({
+                dialect,
+                feature: 'the "similarTo" operator (pg_trgm)',
+                hint: "pg_trgm exists on postgres/pglite only"
+              });
+            }
+            const text = typeof operand === "string" ? operand : typeof operand === "object" && operand !== null && ("text" in operand) ? operand.text : undefined;
+            if (typeof text !== "string") {
+              return { error: "expects a string or { text, threshold? }" };
+            }
+            const perUse = typeof operand === "object" && operand !== null && "threshold" in operand ? operand.threshold : undefined;
+            const configured = extOptions["threshold"];
+            const sessionThreshold = typeof configured === "number" ? configured : DEFAULT_THRESHOLD;
+            const effective = typeof perUse === "number" ? perUse : sessionThreshold;
+            if (effective >= Math.max(sessionThreshold, DEFAULT_THRESHOLD)) {
+              return {
+                fragment: {
+                  parts: [
+                    "(",
+                    { ident: column },
+                    " % ",
+                    { param: text },
+                    " AND similarity(",
+                    { ident: column },
+                    ", ",
+                    { param: text },
+                    ") >= ",
+                    { param: effective },
+                    ")"
+                  ]
+                }
+              };
+            }
+            return {
+              fragment: {
+                parts: [
+                  "similarity(",
+                  { ident: column },
+                  ", ",
+                  { param: text },
+                  ") >= ",
+                  { param: effective }
+                ]
+              }
+            };
+          }
+        }
+      ]
+    },
+    runtime: {
+      onConnect: async ({ execute, dialect, options: extOptions }) => {
+        if (dialect !== "postgres" || typeof extOptions["threshold"] !== "number")
+          return;
+        await execute({
+          text: `SET pg_trgm.similarity_threshold = ${Number(threshold)}`
+        });
+      }
+    },
+    doctor: async ({ execute, dialect }) => {
+      if (dialect !== "postgres") {
+        return { checks: [{ name: "trgm dialect", ok: false, note: "postgres/pglite only" }] };
+      }
+      const checks = [await pgExtensionCheck({ execute, name: "pg_trgm" })];
+      const floor = Math.max(threshold, DEFAULT_THRESHOLD);
+      try {
+        const rows = await execute({
+          text: `SELECT current_setting('pg_trgm.similarity_threshold', true) AS "threshold"`
+        });
+        const raw = rows[0]?.["threshold"];
+        if (raw === undefined || raw === null || raw === "") {
+          checks.push({
+            name: "trgm similarity_threshold",
+            ok: true,
+            note: `not set in this session \u2014 the 0.3 default applies (\u2264 gate floor ${floor})`
+          });
+          return { checks };
+        }
+        const server = Number(raw);
+        checks.push(Number.isNaN(server) ? { name: "trgm similarity_threshold", ok: false, note: "could not read pg_trgm.similarity_threshold" } : server <= floor ? { name: "trgm similarity_threshold", ok: true, note: `server ${server} \u2264 gate floor ${floor}` } : {
+          name: "trgm similarity_threshold",
+          ok: false,
+          note: `server pg_trgm.similarity_threshold=${server} exceeds the %-gate floor ${floor} \u2014 indexed similarTo queries can drop rows; lower the GUC or raise the extension threshold`
+        });
+      } catch {
+        checks.push({
+          name: "trgm similarity_threshold",
+          ok: false,
+          note: "reading pg_trgm.similarity_threshold failed"
+        });
+      }
+      return { checks };
+    }
+  });
+}
+export {
+  vector,
+  trgm,
+  search,
+  resolveSearchEngine,
+  createVectorNamespace,
+  createSearchDelegate
+};
+
+//# debugId=B1B4930A9A8DBD3964756E2164756E21