@vibeorm/extensions 2.0.0-alpha.1 → 2.0.0-alpha.10

package/README.md

@@ -85,6 +85,74 @@ Two gates worth knowing before you pick a dialect:
 - `engine: "bm25"` is refused on `pglite` (it does not bundle `pg_search`) and on non-postgres dialects. `"auto"` never selects it, because ParadeDB availability is not knowable at generate time.
 - The `fts5` engine requires the searched model to have a single `Int` or `BigInt` `@id`. That is the only primary key that aliases and pins the SQLite rowid the external-content table keys on; anything else is refused at generate time.
 
+### Type-ahead (prefix) matching
+
+All engines match complete words by default — a user still typing gets nothing for `"piz"`. For search-as-you-type boxes pass `prefix: true`:
+
+```ts
+const hits = await db.post.search({ query: "piz", prefix: true, take: 8 });
+```
+
+The query is split into unicode letter/number tokens (punctuation separates and never matches) and every token matches as a prefix. Per engine: tsvector builds `to_tsquery('lang', 'piz:*')` (still one bound parameter — `websearch_to_tsquery` has no prefix syntax), fts5 uses `"piz"*` in the MATCH string, mysql switches to `+piz*` in BOOLEAN MODE. A query with no tokens resolves to `[]` without touching the database. Three caveats:
+
+- tsvector prefixes run against **stemmed** lexemes, so a stemming `language` ("english", "norwegian") can miss mid-stem prefixes. Declare `language: "simple"` on models meant for type-ahead.
+- `engine: "bm25"` refuses `prefix` (`VIBE_UNSUPPORTED_CAPABILITY`) — ParadeDB prefix behavior is decided by the index tokenizer, which this extension does not configure.
+- mysql InnoDB ignores tokens shorter than `innodb_ft_min_token_size` (default 3), so one- and two-letter prefixes match nothing there.
+
+### Filtering hits: `where` composes with the core filter language
+
+`search({ where })` compiles through the same filter compiler as every core query — scalar
+filters, relation filters and `dbNow()` comparisons all AND into the match. The menu
+composition (type-ahead over items that are orderable *right now*):
+
+```prisma
+model MenuItem {
+  id            Int       @id @default(autoincrement())
+  name          String
+  description   String
+  availableFrom DateTime?
+  availableTo   DateTime?
+  category      Category? @relation(fields: [categoryId], references: [id])
+  categoryId    Int?
+
+  @@search([name, description], weights: [2, 1], language: "simple")
+}
+```
+
+```ts
+import { dbNow } from "@vibeorm/runtime";
+
+const hits = await db.menuItem.search({
+  query: "piz",              // mid-keystroke
+  prefix: true,
+  take: 8,
+  where: {
+    category: { is: { active: true } },
+    availableFrom: { lte: dbNow() },   // the DATABASE's clock, not the process's
+    availableTo: { gte: dbNow() },
+  },
+});
+```
+
+For typo tolerance ("piza") declare `@@trgm([name])` too and fall back to
+`findMany({ where: { name: { similarTo: query } } })` when a prefix search returns nothing
+(postgres/pglite only).
+
+### Hydrating hits with relations
+
+`search()` returns bare rows — it has no `include`/`select` of relations. The intended pattern is the `select: "id"` projection plus a re-read through your own typed query, which carries relations, `omit`, computed fields and everything else the core API does:
+
+```ts
+const hits = await db.post.search({ query: "piz", prefix: true, select: "id", take: 8 });
+const rows = await db.post.findMany({
+  where: { id: { in: hits.map((hit) => hit.row.id) } },
+  include: { author: { select: { id: true, name: true } } },
+});
+// findMany does not preserve rank — re-order by score:
+const byId = new Map(rows.map((row) => [row.id, row]));
+const ranked = hits.flatMap((hit) => byId.get(hit.row.id) ?? []);
+```
+
 `createSearchDelegate(config)` is the runtime glue the generator emits into the client. You do not call it by hand.
 
 ## Vector

package/dist/index.js

@@ -74,7 +74,7 @@ async function pgExtensionCheck(params) {
 }
 
 // packages/extensions/src/search/index.ts
-var VERSION = "2.0.0-alpha.0";
+var VERSION = "2.0.0-alpha.1";
 var SCORE_ALIAS = "_vibe_score";
 var HIGHLIGHT_ALIAS = "_vibe_highlight";
 var WEIGHT_LETTERS = ["A", "B", "C", "D"];
@@ -101,6 +101,10 @@ function resolveSearchEngine(params) {
     hint: `this dialect supports "${native}"${dialect === "postgres" ? ' and "bm25"' : ""}`
   });
 }
+function declRank(declaration) {
+  const value = declaration["rank"];
+  return value === "ts_rank" || value === "ts_rank_cd" ? value : undefined;
+}
 function readDeclaration(params) {
   const fields = declStringArray(params.declaration, "fields");
   if (fields === undefined || fields.length === 0)
@@ -109,7 +113,10 @@ function readDeclaration(params) {
     fields,
     weights: declNumberArray(params.declaration, "weights"),
     base: declString(params.declaration, "name") ?? `${tableNameOf({ model: params.model })}_search`,
-    language: declString(params.declaration, "language")
+    language: declString(params.declaration, "language"),
+    columnName: declString(params.declaration, "columnName"),
+    indexName: declString(params.declaration, "indexName"),
+    rank: declRank(params.declaration)
   };
 }
 function weightLetters(params) {
@@ -119,6 +126,41 @@ function weightLetters(params) {
   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 resolveArtifactNames(params) {
+  const { decl, engine, dialect } = params;
+  if (engine === "fts5" && (decl.columnName !== undefined || decl.indexName !== undefined)) {
+    throw unsupportedCapability({
+      dialect,
+      feature: "@@search columnName/indexName overrides on the fts5 engine",
+      hint: "fts5 emits a shadow table + triggers \u2014 there is no column or index to rename; use name: to change the table base"
+    });
+  }
+  if (decl.columnName !== undefined && engine !== "tsvector") {
+    throw unsupportedCapability({
+      dialect,
+      feature: `@@search columnName on the ${engine} engine`,
+      hint: "only the tsvector engine materializes a generated column \u2014 drop columnName or target tsvector"
+    });
+  }
+  return {
+    tsvColumn: decl.columnName ?? `${decl.base}_tsv`,
+    indexName: decl.indexName ?? `${decl.base}_idx`
+  };
+}
+function resolveRank(params) {
+  const { decl, options, engine, dialect } = params;
+  if (decl.rank !== undefined && engine !== "tsvector") {
+    throw unsupportedCapability({
+      dialect,
+      feature: `@@search rank on the ${engine} engine`,
+      hint: "rank chooses between the postgres ranking functions ts_rank and ts_rank_cd \u2014 a tsvector-only concept"
+    });
+  }
+  if (engine !== "tsvector")
+    return;
+  const fallback = options["rank"];
+  return decl.rank ?? (fallback === "ts_rank" || fallback === "ts_rank_cd" ? fallback : undefined);
+}
 function tsvectorExpression(params) {
   const { dialect, model, decl, language } = params;
   const quote = (name) => dialect.quoteIdent({ name });
@@ -152,9 +194,10 @@ function searchArtifacts(ctx) {
       continue;
     const table = tableNameOf({ model });
     const columns = decl.fields.map((field) => columnNameOf({ model, field }));
+    resolveRank({ decl, options: ctx.options, engine, dialect: ctx.dialect });
     if (engine === "tsvector") {
       const language = decl.language ?? ctx.options["language"] ?? "english";
-      const tsvColumn = `${decl.base}_tsv`;
+      const { tsvColumn, indexName } = resolveArtifactNames({ decl, engine, dialect: ctx.dialect });
       const expression = tsvectorExpression({ dialect, model, decl, language });
       artifacts.push({
         id: `search:${modelName}:column`,
@@ -165,11 +208,11 @@ function searchArtifacts(ctx) {
         drop: [`ALTER TABLE ${quote(table)} DROP COLUMN IF EXISTS ${quote(tsvColumn)};`]
       }, {
         id: `search:${modelName}:index`,
-        owns: { kind: "index", table, name: `${decl.base}_idx` },
+        owns: { kind: "index", table, name: indexName },
         create: [
-          `CREATE INDEX IF NOT EXISTS ${quote(`${decl.base}_idx`)} ON ${quote(table)} USING gin (${quote(tsvColumn)});`
+          `CREATE INDEX IF NOT EXISTS ${quote(indexName)} ON ${quote(table)} USING gin (${quote(tsvColumn)});`
         ],
-        drop: [`DROP INDEX IF EXISTS ${quote(`${decl.base}_idx`)};`]
+        drop: [`DROP INDEX IF EXISTS ${quote(indexName)};`]
       });
       continue;
     }
@@ -183,17 +226,19 @@ function searchArtifacts(ctx) {
         });
       }
       const pkColumn = columnNameOf({ model, field: pkField });
+      const bm25Names = resolveArtifactNames({ decl, engine, dialect: ctx.dialect });
       artifacts.push({
         id: `search:${modelName}:index`,
-        owns: { kind: "index", table, name: `${decl.base}_idx` },
+        owns: { kind: "index", table, name: bm25Names.indexName },
         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}');`
+          `CREATE INDEX IF NOT EXISTS ${quote(bm25Names.indexName)} 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`)};`]
+        drop: [`DROP INDEX IF EXISTS ${quote(bm25Names.indexName)};`]
       });
       continue;
     }
     if (engine === "fts5") {
+      resolveArtifactNames({ decl, engine, dialect: ctx.dialect });
       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");
@@ -242,13 +287,14 @@ END;`
       });
       continue;
     }
+    const fulltextNames = resolveArtifactNames({ decl, engine, dialect: ctx.dialect });
     artifacts.push({
       id: `search:${modelName}:index`,
-      owns: { kind: "index", table, name: `${decl.base}_idx` },
+      owns: { kind: "index", table, name: fulltextNames.indexName },
       create: [
-        `CREATE FULLTEXT INDEX ${quote(`${decl.base}_idx`)} ON ${quote(table)} (${columns.map((column) => quote(column)).join(", ")});`
+        `CREATE FULLTEXT INDEX ${quote(fulltextNames.indexName)} ON ${quote(table)} (${columns.map((column) => quote(column)).join(", ")});`
       ],
-      drop: [`DROP INDEX ${quote(`${decl.base}_idx`)} ON ${quote(table)};`]
+      drop: [`DROP INDEX ${quote(fulltextNames.indexName)} ON ${quote(table)};`]
     });
   }
   return artifacts;
@@ -294,9 +340,33 @@ function createSearchDelegate(config) {
           meta: { table: config.table }
         });
       }
+      const prefix = args.prefix === true;
+      if (prefix && config.engine === "bm25") {
+        throw unsupportedCapability({
+          dialect: "postgres",
+          feature: 'search prefix mode on the "bm25" engine',
+          hint: "ParadeDB prefix behavior is decided by the index tokenizer (ngram/edge-ngram) \u2014 configure the index instead, or use the tsvector engine"
+        });
+      }
+      let matchText = args.query;
+      if (prefix) {
+        const tokens = args.query.match(/[\p{L}\p{N}]+/gu) ?? [];
+        if (tokens.length === 0)
+          return [];
+        matchText = config.engine === "tsvector" ? tokens.map((token) => `${token}:*`).join(" & ") : config.engine === "fts5" ? tokens.map((token) => `"${token}"*`).join(" ") : tokens.map((token) => `+${token}*`).join(" ");
+      }
       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 idOnly = args.select === "id";
+      if (idOnly && config.pkColumn === undefined) {
+        throw new VibeError2({
+          code: "VIBE_VALIDATION",
+          message: `select: "id" needs a single-column primary key baked into the client \u2014 ${config.table} has none, or the client predates the projection (run vibeorm generate)`,
+          meta: { table: config.table }
+        });
+      }
+      const projection = idOnly ? `${t}.${quote(config.pkColumn ?? "")}` : `${t}.*`;
       const collector = new ParamCollector(dialect);
       const userWhere = (qualify) => {
         if (args.where === undefined)
@@ -309,9 +379,10 @@ function createSearchDelegate(config) {
       let engineHasHighlights = true;
       if (config.engine === "tsvector") {
         const language = config.language ?? "english";
+        const ranker = config.rank ?? "ts_rank_cd";
         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)}`;
+        const tsquery = () => prefix ? `to_tsquery('${language}', ${collector.add(matchText)})` : `websearch_to_tsquery('${language}', ${collector.add(matchText)})`;
+        text = `SELECT ${projection}, ${ranker}(${tsv}, ${tsquery()}) AS ${quote(SCORE_ALIAS)}`;
         if (hlColumn !== null) {
           text += `, ts_headline('${language}', ${t}.${quote(hlColumn)}, ${tsquery()}) AS ${quote(HIGHLIGHT_ALIAS)}`;
         }
@@ -320,19 +391,19 @@ function createSearchDelegate(config) {
         if (where !== null)
           text += ` AND (${where})`;
         if (args.minScore !== undefined) {
-          text += ` AND ts_rank_cd(${tsv}, ${tsquery()}) >= ${collector.add(args.minScore)}`;
+          text += ` AND ${ranker}(${tsv}, ${tsquery()}) >= ${collector.add(args.minScore)}`;
         }
         text += ` ORDER BY ${quote(SCORE_ALIAS)} DESC`;
-        strip = [config.tsvColumn ?? ""];
+        strip = idOnly ? [] : [config.tsvColumn ?? ""];
       } else if (config.engine === "fts5") {
         const fts = quote(config.ftsTable ?? "");
-        text = `SELECT ${t}.*, -bm25(${fts}) AS ${quote(SCORE_ALIAS)}`;
+        text = `SELECT ${projection}, -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)}`;
+        text += ` WHERE ${fts} MATCH ${collector.add(matchText)}`;
         const where = userWhere("t");
         if (where !== null)
           text += ` AND (${where})`;
@@ -342,8 +413,9 @@ function createSearchDelegate(config) {
         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}`;
+        const mode = prefix ? "IN BOOLEAN MODE" : "IN NATURAL LANGUAGE MODE";
+        const match = () => `MATCH (${config.fields.map((field) => `${t}.${quote(field.column)}`).join(", ")}) AGAINST (${collector.add(matchText)} ${mode})`;
+        text = `SELECT ${projection}, ${match()} AS ${quote(SCORE_ALIAS)} FROM ${quote(config.table)} AS ${t}`;
         text += ` WHERE ${match()}`;
         const where = userWhere("t");
         if (where !== null)
@@ -354,7 +426,7 @@ function createSearchDelegate(config) {
         text += ` ORDER BY ${quote(SCORE_ALIAS)} DESC`;
       } else {
         const pk = `${t}.${quote(config.pkColumn ?? "")}`;
-        text = `SELECT ${t}.*, paradedb.score(${pk}) AS ${quote(SCORE_ALIAS)}`;
+        text = `SELECT ${projection}, paradedb.score(${pk}) AS ${quote(SCORE_ALIAS)}`;
         if (hlColumn !== null) {
           text += `, paradedb.snippet(${t}.${quote(hlColumn)}) AS ${quote(HIGHLIGHT_ALIAS)}`;
         }
@@ -415,6 +487,16 @@ function search(options = {}) {
             if (language !== undefined && (typeof language !== "string" || !isSafeSqlName({ name: language }))) {
               return { error: `language must be a plain text-search config name` };
             }
+            for (const key of ["columnName", "indexName"]) {
+              const value = args.named[key];
+              if (value !== undefined && (typeof value !== "string" || !isSafeSqlName({ name: value }))) {
+                return { error: `${key} must be a plain identifier` };
+              }
+            }
+            const rank = args.named["rank"];
+            if (rank !== undefined && rank !== "ts_rank" && rank !== "ts_rank_cd") {
+              return { error: `rank must be "ts_rank" or "ts_rank_cd"` };
+            }
             return { declaration: { fields, ...args.named } };
           }
         }
@@ -438,6 +520,8 @@ function search(options = {}) {
           });
         }
         const pkField = primaryKeyFieldOf({ model });
+        const rank = resolveRank({ decl, options: extOptions, engine, dialect });
+        const names = resolveArtifactNames({ decl, engine, dialect });
         const config = {
           engine,
           table: tableNameOf({ model }),
@@ -445,26 +529,42 @@ function search(options = {}) {
             name: field,
             column: columnNameOf({ model, field })
           })),
-          ...engine === "tsvector" ? { tsvColumn: `${decl.base}_tsv`, language } : {},
+          ...engine === "tsvector" ? { tsvColumn: names.tsvColumn, language, ...rank === undefined ? {} : { rank } } : {},
           ...engine === "fts5" ? { ftsTable: `${decl.base}_fts` } : {},
-          ...engine === "bm25" && pkField !== null ? { pkColumn: columnNameOf({ model, field: pkField }) } : {}
+          ...pkField !== null ? { pkColumn: columnNameOf({ model, field: pkField }) } : {}
         };
         const fieldUnion = decl.fields.map((field) => JSON.stringify(field)).join(" | ");
+        const argLines = [
+          `  readonly query: string;`,
+          `  readonly where?: ${typeNames.whereInput};`,
+          `  readonly take?: number;`,
+          `  readonly skip?: number;`,
+          `  readonly minScore?: number;`,
+          `  readonly highlight?: { readonly field: ${fieldUnion} };`,
+          `  readonly prefix?: boolean;`
+        ];
+        const dts = pkField === null ? [
+          `readonly search: (args: {`,
+          ...argLines,
+          `}) => Promise<SearchHit<${typeNames.payload}>[]>;`
+        ] : [
+          `readonly search: {`,
+          `  (args: {`,
+          ...argLines.map((line) => `  ${line}`),
+          `    readonly select: "id";`,
+          `  }): Promise<SearchHit<Pick<${typeNames.payload}, ${JSON.stringify(pkField)}>>[]>;`,
+          `  (args: {`,
+          ...argLines.map((line) => `  ${line}`),
+          `    readonly select?: "row";`,
+          `  }): Promise<SearchHit<${typeNames.payload}>[]>;`,
+          `};`
+        ];
         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}>[]>;`
-          ]
+          dts
         };
       }
     },
@@ -571,7 +671,8 @@ function vectorArtifacts(ctx) {
         });
       }
       const column = columnNameOf({ model, field });
-      const indexName = `${table}_${column}_${kindRaw}_idx`;
+      const nameOverride = indexFields.length === 1 ? declString(declaration, "indexName") : undefined;
+      const indexName = nameOverride ?? `${table}_${column}_${kindRaw}_idx`;
       const withOptions = [];
       const m = declaration["m"];
       const efConstruction = declaration["efConstruction"];
@@ -719,6 +820,17 @@ function vector(options = {}) {
                 return { error: `${key} must be a number` };
               }
             }
+            const indexName = args.named["indexName"];
+            if (indexName !== undefined) {
+              if (typeof indexName !== "string" || !isSafeSqlName({ name: indexName })) {
+                return { error: `indexName must be a plain identifier` };
+              }
+              if (fields.length !== 1) {
+                return {
+                  error: `indexName needs exactly one indexed field \u2014 split @@vector declarations to name each index`
+                };
+              }
+            }
             return { declaration: { fields, ...args.named } };
           }
         }
@@ -963,4 +1075,4 @@ export {
   createSearchDelegate
 };
 
-//# debugId=B1B4930A9A8DBD3964756E2164756E21
+//# debugId=92CFAFA74775D03064756E2164756E21