@vibeorm/extensions 2.1.1 → 2.2.0

package/README.md

@@ -37,7 +37,9 @@ Each extension declares its schema attributes, the DDL artifacts `db push` / `mi
 
 ## Search
 
-Declare the searched fields with `@@search`. Optional named arguments: `name` (artifact base name, a plain identifier), `weights` (one number per field), `language` (a text-search config name, tsvector engine only).
+Declare the searched fields with `@@search`. Optional named arguments: `name` (artifact base name, a plain identifier), `weights` (one finite number per field, **tsvector only**), `language` (a text-search config name, tsvector engine only).
+
+Weights express ordinal priority, not numeric multipliers: distinct values descending map to PostgreSQL's A, B, C, D classes, with further classes capped at D. Equal weights share a class. FTS5, MySQL FULLTEXT and ParadeDB BM25 refuse declared weights with `VIBE_UNSUPPORTED_CAPABILITY`; omit `weights` on those engines.
 
 ```prisma
 model Post {
@@ -67,6 +69,8 @@ const hits = await db.post.search({
 // hits: SearchHit<Post>[] — { row, score, highlights }
 ```
 
+`take` must be a positive safe integer and `skip` a non-negative safe integer. Negative, fractional and non-finite pagination refuses with `VIBE_VALIDATION` rather than being clamped. `minScore` and vector `maxDistance` must be finite numbers; a negative inner-product distance is valid. Trigram thresholds must be finite numbers in [0, 1]. Vector index tuning requires integers: `m` 2..100, `efConstruction` 4..1000, `lists` 1..32768. The database may impose additional constraints between options.
+
 `highlights` is `readonly string[] | null`; it is `null` when no highlight was requested and on engines without highlighting.
 
 ### Engines per dialect
@@ -85,6 +89,10 @@ 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.
 
+### FTS5 installation on populated tables
+
+The installation statements create the external-content table, install its synchronization triggers, then run FTS5's `rebuild` command to index historical rows. Apply the full installation in one transaction. This scans the host table and takes SQLite's write lock; allow for that cost in a migration window. It is installation work, not an application-startup hook. Existing installations are not automatically repaired by upgrading the package; review and run an explicit rebuild migration if historical rows were omitted.
+
 ### 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`:

package/dist/index.js

@@ -1,10 +1,20 @@
 // @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 finiteNumber(params) {
+  const { value, name, integer, min } = params;
+  if (typeof value !== "number" || !Number.isFinite(value) || integer === true && !Number.isSafeInteger(value) || min !== undefined && value < min) {
+    throw new VibeError({
+      code: "VIBE_VALIDATION",
+      message: `${name} must be a finite ${integer === true ? "safe integer" : "number"}${min === undefined ? "" : ` >= ${min}`}`,
+      meta: { argument: name }
+    });
+  }
+  return value;
+}
 function tableNameOf(params) {
   return params.model.dbName ?? params.model.name;
 }
@@ -74,6 +84,7 @@ async function pgExtensionCheck(params) {
 }
 
 // packages/extensions/src/search/index.ts
+import { ParamCollector, getSqlDialect, renderExpr } from "@vibeorm/sql";
 var VERSION = "2.0.0-alpha.1";
 var SCORE_ALIAS = "_vibe_score";
 var HIGHLIGHT_ALIAS = "_vibe_highlight";
@@ -109,6 +120,9 @@ function readDeclaration(params) {
   const fields = declStringArray(params.declaration, "fields");
   if (fields === undefined || fields.length === 0)
     return null;
+  if (params.declaration["weights"] !== undefined && (!Array.isArray(params.declaration["weights"]) || params.declaration["weights"].length !== fields.length || params.declaration["weights"].some((weight) => typeof weight !== "number" || !Number.isFinite(weight)))) {
+    throw new VibeError2({ code: "VIBE_SCHEMA_INVALID", message: "weights must be a finite number list matching the field list", meta: { model: params.model.name } });
+  }
   return {
     fields,
     weights: declNumberArray(params.declaration, "weights"),
@@ -149,6 +163,13 @@ function resolveArtifactNames(params) {
 }
 function resolveRank(params) {
   const { decl, options, engine, dialect } = params;
+  if (decl.weights !== undefined && engine !== "tsvector") {
+    throw unsupportedCapability({
+      dialect,
+      feature: `@@search weights on the ${engine} engine`,
+      hint: "weights are supported only by tsvector; omit weights for this engine"
+    });
+  }
   if (decl.rank !== undefined && engine !== "tsvector") {
     throw unsupportedCapability({
       dialect,
@@ -277,7 +298,8 @@ 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;`
+END;`,
+          `INSERT INTO ${quote(fts)}(${quote(fts)}) VALUES ('rebuild');`
         ],
         drop: [
           `DROP TRIGGER IF EXISTS ${quote(`${fts}_ai`)};`,
@@ -340,6 +362,10 @@ function createSearchDelegate(config) {
           meta: { table: config.table }
         });
       }
+      const take = finiteNumber({ value: args.take === undefined ? 10 : args.take, name: "take", integer: true, min: 1 });
+      const skip = args.skip === undefined ? null : finiteNumber({ value: args.skip, name: "skip", integer: true, min: 0 });
+      if (args.minScore !== undefined)
+        finiteNumber({ value: args.minScore, name: "minScore" });
       const prefix = args.prefix === true;
       if (prefix && config.engine === "bm25") {
         throw unsupportedCapability({
@@ -355,8 +381,6 @@ function createSearchDelegate(config) {
           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) {
@@ -479,7 +503,7 @@ function search(options = {}) {
             }
             const weights = args.named["weights"];
             if (weights !== undefined) {
-              if (!Array.isArray(weights) || weights.length !== fields.length || weights.some((weight) => typeof weight !== "number")) {
+              if (!Array.isArray(weights) || weights.length !== fields.length || weights.some((weight) => typeof weight !== "number" || !Number.isFinite(weight))) {
                 return { error: `weights must be a number list matching the field list` };
               }
             }
@@ -621,6 +645,20 @@ var METRIC_OPCLASS = {
 var METRICS = ["cosine", "l2", "ip"];
 var INDEX_KINDS = ["hnsw", "ivfflat"];
 var DISTANCE_ALIAS = "_vibe_distance";
+var INDEX_BOUNDS = {
+  m: [2, 100],
+  efConstruction: [4, 1000],
+  lists: [1, 32768]
+};
+function indexOptionError(params) {
+  for (const [key, [min, max]] of Object.entries(INDEX_BOUNDS)) {
+    const value = params.declaration[key];
+    if (value !== undefined && (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max)) {
+      return `${key} must be an integer between ${min} and ${max}`;
+    }
+  }
+  return;
+}
 function vectorColumnsOf(params) {
   const columns = params.declaration["columns"];
   if (columns === null || typeof columns !== "object" || Array.isArray(columns))
@@ -657,6 +695,10 @@ function vectorArtifacts(ctx) {
     const model = ctx.schema.models.find((candidate) => candidate.name === modelName);
     if (model === undefined)
       continue;
+    const invalidOption = indexOptionError({ declaration });
+    if (invalidOption !== undefined) {
+      throw new VibeError3({ code: "VIBE_SCHEMA_INVALID", message: invalidOption, meta: { model: modelName } });
+    }
     const table = tableNameOf({ model });
     const columns = vectorColumnsOf({ declaration });
     const indexFields = declStringArray(declaration, "fields") ?? [];
@@ -732,6 +774,9 @@ function createVectorNamespace(config) {
     const t = quote("t");
     return {
       nearest: async (args) => {
+        const take = finiteNumber({ value: args.take === undefined ? 10 : args.take, name: "take", integer: true, min: 1 });
+        if (args.maxDistance !== undefined)
+          finiteNumber({ value: args.maxDistance, name: "maxDistance" });
         const { column, literal } = resolveColumn({ config, args });
         const metric = args.metric ?? config.metric;
         const op = METRIC_OPERATOR[metric];
@@ -748,7 +793,7 @@ function createVectorNamespace(config) {
         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))}`;
+        text += ` ORDER BY ${col} ${op} ${collector.add(literal)} LIMIT ${take}`;
         const rows = await ctx.executeRows({
           text,
           values: collector.values,
@@ -815,12 +860,9 @@ function vector(options = {}) {
             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` };
-              }
-            }
+            const invalidOption = indexOptionError({ declaration: args.named });
+            if (invalidOption !== undefined)
+              return { error: invalidOption };
             const indexName = args.named["indexName"];
             if (indexName !== undefined) {
               if (typeof indexName !== "string" || !isSafeSqlName({ name: indexName })) {
@@ -899,10 +941,13 @@ function vector(options = {}) {
 }
 
 // packages/extensions/src/trgm/index.ts
-import { defineExtension as defineExtension3, unsupportedCapability as unsupportedCapability3 } from "@vibeorm/schema";
+import { VibeError as VibeError4, 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 validThreshold(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
 function trgmArtifacts(ctx) {
   if (ctx.dialect !== "postgres") {
     throw unsupportedCapability3({
@@ -942,7 +987,10 @@ function trgmArtifacts(ctx) {
   return artifacts;
 }
 function trgm(options = {}) {
-  const threshold = options.threshold ?? DEFAULT_THRESHOLD;
+  const threshold = options.threshold === undefined ? DEFAULT_THRESHOLD : options.threshold;
+  if (!validThreshold(threshold)) {
+    throw new VibeError4({ code: "VIBE_VALIDATION", message: "trgm threshold must be a finite number between 0 and 1", meta: { argument: "threshold" } });
+  }
   return defineExtension3({
     name: "trgm",
     version: VERSION3,
@@ -986,6 +1034,9 @@ function trgm(options = {}) {
             }
             const perUse = typeof operand === "object" && operand !== null && "threshold" in operand ? operand.threshold : undefined;
             const configured = extOptions["threshold"];
+            if (configured !== undefined && !validThreshold(configured) || perUse !== undefined && !validThreshold(perUse)) {
+              return { error: "threshold must be a finite number between 0 and 1" };
+            }
             const sessionThreshold = typeof configured === "number" ? configured : DEFAULT_THRESHOLD;
             const effective = typeof perUse === "number" ? perUse : sessionThreshold;
             if (effective >= Math.max(sessionThreshold, DEFAULT_THRESHOLD)) {
@@ -1077,4 +1128,4 @@ export {
   createSearchDelegate
 };
 
-//# debugId=26711481A38DB0B264756E2164756E21
+//# debugId=02443E6D9865955B64756E2164756E21