@an5/adapters 0.2.10 → 0.2.13

package/typescript/src/an5Adapter.ts

@@ -26,10 +26,20 @@ import {
   type NBaseAdapterConfig,
   type NBaseVectorClient,
 } from './nbase';
-import { buildOrderBy, parseWhere, quote } from './base/sql';
+import { bindParam, buildOrderBy, parseWhere, quote } from './base/sql';
+import {
+  decodeVector,
+  isVectorField,
+  needsVectorEncoding,
+  runSqliteVectorSearch,
+  vectorDistance,
+  type SqliteVectorSupport,
+  type VectorStrategyPreference,
+} from './sqlite/vector';
 import {
   createAdapterProxy,
   getFieldsForModel,
+  resolveIdField,
   getModelToTable,
   getRelationMap,
   getRelationsForModel,
@@ -51,39 +61,59 @@ function sanitizeParamName(name: string): string {
   return /^[A-Za-z]/.test(cleaned) ? cleaned : `p_${cleaned}`;
 }
 
+/** Match only unique/primary-key violations, never general constraint errors. */
+function isDuplicateKeyError(error: unknown, dialect: Dialect): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const e = error as any;
+  if (dialect === 'postgres') return e.code === '23505';
+  if (dialect === 'mysql') return e.code === 'ER_DUP_ENTRY' || e.errno === 1062;
+  if (dialect === 'sqlite') {
+    return e.code === 'SQLITE_CONSTRAINT_UNIQUE' || e.code === 'SQLITE_CONSTRAINT_PRIMARYKEY'
+      || e.errcode === 2067 || e.errcode === 1555;
+  }
+  if (dialect === 'mssql') {
+    const number = e.number ?? e.originalError?.info?.number;
+    return number === 2601 || number === 2627;
+  }
+  return false;
+}
+
 function appendUpdateSet(sets: string[], params: Record<string, any>, col: string, val: any, dialect: Dialect): void {
   const quoted = quote(col, dialect);
   const safeCol = sanitizeParamName(col);
-  if (val && typeof val === 'object' && !(val instanceof Date)) {
+  // `TypedArray.prototype.set` is the copy method, not the update operator, so a
+  // vector written as a float32 BLOB must not be read as `{ set: ... }`.
+  const isLiteral = Array.isArray(val) || ArrayBuffer.isView(val) || val instanceof ArrayBuffer;
+  if (val && typeof val === 'object' && !(val instanceof Date) && !isLiteral) {
     if (val.increment !== undefined) {
-      sets.push(`${quoted} = ${quoted} + @s_${safeCol}_inc`);
-      params[`s_${safeCol}_inc`] = val.increment;
+      const p = bindParam(params, `s_${safeCol}_inc`, val.increment);
+      sets.push(`${quoted} = ${quoted} + @${p}`);
       return;
     }
     if (val.decrement !== undefined) {
-      sets.push(`${quoted} = ${quoted} - @s_${safeCol}_dec`);
-      params[`s_${safeCol}_dec`] = val.decrement;
+      const p = bindParam(params, `s_${safeCol}_dec`, val.decrement);
+      sets.push(`${quoted} = ${quoted} - @${p}`);
       return;
     }
     if (val.multiply !== undefined) {
-      sets.push(`${quoted} = ${quoted} * @s_${safeCol}_mul`);
-      params[`s_${safeCol}_mul`] = val.multiply;
+      const p = bindParam(params, `s_${safeCol}_mul`, val.multiply);
+      sets.push(`${quoted} = ${quoted} * @${p}`);
       return;
     }
     if (val.divide !== undefined) {
-      sets.push(`${quoted} = ${quoted} / @s_${safeCol}_div`);
-      params[`s_${safeCol}_div`] = val.divide;
+      const p = bindParam(params, `s_${safeCol}_div`, val.divide);
+      sets.push(`${quoted} = ${quoted} / @${p}`);
       return;
     }
     if (val.set !== undefined) {
-      sets.push(`${quoted} = @s_${safeCol}_set`);
-      params[`s_${safeCol}_set`] = val.set;
+      const p = bindParam(params, `s_${safeCol}_set`, val.set);
+      sets.push(`${quoted} = @${p}`);
       return;
     }
   }
 
-  sets.push(`${quoted} = @s_${safeCol}`);
-  params[`s_${safeCol}`] = val;
+  const p = bindParam(params, `s_${safeCol}`, val);
+  sets.push(`${quoted} = @${p}`);
 }
 
 function selectedAggregateFields(fields: any): string[] {
@@ -368,6 +398,22 @@ export class An5Adapter {
     return (await this.requireEngine()).exec<T>(query, params);
   }
 
+  /**
+   * The SQLite engine's vector hooks, or null when this is not a SQLite adapter.
+   * `vectorSearch` needs them to load sqlite-vec and register the distance
+   * functions; a connection with no hooks still searches in memory.
+   */
+  async sqliteVectorSupport(): Promise<SqliteVectorSupport | null> {
+    if (this.sheetsAdapter) return null;
+    const engine = await this.requireEngine();
+    return engine.dialect === 'sqlite' ? (engine.vectorSupport ?? null) : null;
+  }
+
+  /** `vectorStrategy` from the config, so a project can pin one strategy. */
+  get vectorStrategy(): VectorStrategyPreference | undefined {
+    return this._engineConfig?.vectorStrategy;
+  }
+
   /** INTERNAL: used by AdapterTableClient for DML statements needing row count */
   async _executeRaw(query: string, params?: Record<string, any>): Promise<number> {
     return (await this.requireEngine()).executeRaw(query, params);
@@ -714,6 +760,14 @@ export class AdapterTableClient<T = any> {
   public get dialect(): Dialect { return this.adapter.dialect; }
 
   public get tableName(): string {
+    const t = this.mappedTableName;
+    if (t.startsWith('[') || t.startsWith('"') || t.startsWith('`')) return t;
+    if (t.includes('.')) return t.split('.').map(p => quote(p, this.dialect)).join('.');
+    return quote(t, this.dialect);
+  }
+
+  /** The table name this model maps to, before any quoting is applied. */
+  private get mappedTableName(): string {
     const name = this.modelName;
     let t = name;
     const modelToTable = getModelToTable();
@@ -726,9 +780,17 @@ export class AdapterTableClient<T = any> {
         if (modelToTable[lower]) t = modelToTable[lower];
       }
     }
-    if (t.startsWith('[') || t.startsWith('"') || t.startsWith('`')) return t;
-    if (t.includes('.')) return t.split('.').map(p => quote(p, this.dialect)).join('.');
-    return quote(t, this.dialect);
+    return t;
+  }
+
+  /**
+   * The bare table name, for helpers that take a string literal. `@@map` values
+   * may be pre-quoted or schema-qualified, neither of which `pragma_table_info`
+   * accepts, so the last segment is unwrapped here.
+   */
+  public get rawTableName(): string {
+    const last = this.mappedTableName.split('.').pop() ?? this.mappedTableName;
+    return last.replace(/^[\s]*[\[\]"`]+|[\[\]"`]+[\s]*$/g, '');
   }
 
   private get nolock(): string {
@@ -752,6 +814,53 @@ export class AdapterTableClient<T = any> {
     return this.adapter._executeRaw(query, params);
   }
 
+  /**
+   * Encode every `VECTOR(n)` value on its way into SQLite.
+   *
+   * The column holds a float32 BLOB, which is a third of the size of the JSON
+   * text it replaces and is what sqlite-vec reads. Values that already arrived
+   * as text or bytes are left alone, so rows written by an older version stay
+   * readable.
+   */
+  private encodeVectorFields(data: Record<string, any>): Record<string, any> {
+    if (this.dialect !== 'sqlite') return data;
+    const fields = getFieldsForModel(this.modelName);
+    const vectorFields = Object.keys(fields).filter((name) => isVectorField(fields[name]));
+    if (vectorFields.length === 0) return data;
+    const { encodeVector } = require('./sqlite/vector');
+    const out = { ...data };
+    for (const name of vectorFields) {
+      const value = out[name];
+      if (needsVectorEncoding(value)) {
+        const parsed = Array.from(value as ArrayLike<number>);
+        if (parsed.length > 0) out[name] = encodeVector(parsed);
+      }
+    }
+    return out;
+  }
+
+  /** Decode `VECTOR(n)` columns back into `number[]` after a read. */
+  private decodeVectorFields<T>(rows: T[]): T[] {
+    if (this.dialect !== 'sqlite' || !Array.isArray(rows) || rows.length === 0) return rows;
+    const fields = getFieldsForModel(this.modelName);
+    const vectorFields = Object.keys(fields).filter((name) => isVectorField(fields[name]));
+    if (vectorFields.length === 0) return rows;
+    return rows.map((row: any) => {
+      if (!row || typeof row !== 'object') return row;
+      let changed = false;
+      const out: any = { ...row };
+      for (const name of vectorFields) {
+        if (!(name in out)) continue;
+        const decoded = decodeVector(out[name]);
+        if (decoded) {
+          out[name] = decoded;
+          changed = true;
+        }
+      }
+      return changed ? out : row;
+    });
+  }
+
   async findMany(args?: { where?: any; orderBy?: any; skip?: number; take?: number; select?: any; include?: any }): Promise<T[]> {
     const params: Record<string, any> = {};
     const whereCtx = this.whereContext();
@@ -789,7 +898,8 @@ export class AdapterTableClient<T = any> {
         query = `SELECT ${cols} FROM ${this.tableName}`;
         if (whereSql) query += ` WHERE ${whereSql}`;
         if (orderSql) query += ` ${orderSql}`;
-        query += ` LIMIT ${take ?? 'ALL'} OFFSET ${skip}`;
+        const limit = take ?? (this.dialect === 'sqlite' ? '-1' : this.dialect === 'mysql' ? '18446744073709551615' : 'ALL');
+        query += ` LIMIT ${limit} OFFSET ${skip}`;
       } else {
         // mssql requires ORDER BY before OFFSET/FETCH
         query = `SELECT ${cols} FROM ${this.tableName}${this.nolock}`;
@@ -806,7 +916,7 @@ export class AdapterTableClient<T = any> {
       if (orderSql) query += ` ${orderSql}`;
     }
 
-    const rows = await this.doExec<T>(query, params);
+    const rows = this.decodeVectorFields(await this.doExec<T>(query, params));
 
     if (args?.include) {
       await resolveIncludes(this.modelName, rows, args.include, this.adapter);
@@ -854,11 +964,9 @@ export class AdapterTableClient<T = any> {
     }
 
     const fields = getFieldsForModel(this.modelName);
-    const idFieldName = Object.prototype.hasOwnProperty.call(fields, 'id')
-      ? 'id'
-      : Object.keys(fields).find((name) => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
+    const idFieldName = resolveIdField(fields);
 
-    const data: any = { ...rawData };
+    const data: any = this.encodeVectorFields(rawData);
     if (idFieldName) {
       const fieldDef: any = fields[idFieldName];
       const rawType = typeof fieldDef === 'string' ? fieldDef : (fieldDef?.ts || fieldDef?.sql || fieldDef?.type || '');
@@ -918,35 +1026,44 @@ export class AdapterTableClient<T = any> {
     if (firstRow === undefined) return { count: 0 };
     const firstCols = Object.keys(firstRow).filter(k => (firstRow as any)[k] !== undefined);
 
-    // Bulk INSERT for the common case (same columns, no skipDuplicates)
-    if (firstCols.length > 0 && !args.skipDuplicates) {
+    const sameColumns = args.data.every(row => {
+      const cols = Object.keys(row).filter(k => (row as any)[k] !== undefined);
+      return cols.length === firstCols.length && firstCols.every(col => cols.includes(col));
+    });
+
+    const fields = getFieldsForModel(this.modelName);
+    const idFieldName = resolveIdField(fields);
+    const idDef = idFieldName ? fields[idFieldName] : undefined;
+    const idType = typeof idDef === 'string' ? idDef : (idDef?.ts || idDef?.sql || idDef?.type || '');
+    const generatesId = ['string', 'uuid', 'uniqueidentifier', 'nvarchar', 'varchar', 'text'].includes(String(idType).toLowerCase());
+    const needsGeneratedId = idFieldName && generatesId && args.data.some(row => !(row as any)[idFieldName]);
+
+    // Rows needing generated IDs follow create's default handling.
+    if (firstCols.length > 0 && sameColumns && !needsGeneratedId && !args.skipDuplicates) {
       const params: Record<string, any> = {};
       const rowPlaceholders: string[] = [];
 
       for (let r = 0; r < args.data.length; r++) {
         const row = args.data[r] as any;
+        const encoded = this.encodeVectorFields(row);
         const vals = firstCols.map(col => {
           const p = `r${r}_${col}`;
-          params[p] = row[col] ?? null;
+          params[p] = encoded[col] ?? null;
           return `@${p}`;
         });
         rowPlaceholders.push(`(${vals.join(', ')})`);
       }
 
       const query = `INSERT INTO ${this.tableName} (${firstCols.map(c => quote(c, this.dialect)).join(', ')}) VALUES ${rowPlaceholders.join(', ')}`;
-      try {
-        await this.doExecuteRaw(query, params);
-        return { count: args.data.length };
-      } catch {
-        // fallback below if bulk fails (e.g. mixed column sets)
-      }
+      await this.doExecuteRaw(query, params);
+      return { count: args.data.length };
     }
 
     // Row-by-row fallback
     let count = 0;
     for (const row of args.data) {
       try { await this.create({ data: row }); count++; }
-      catch (e) { if (!args.skipDuplicates) throw e; }
+      catch (e) { if (!args.skipDuplicates || !isDuplicateKeyError(e, this.dialect)) throw e; }
     }
     return { count };
   }
@@ -963,13 +1080,14 @@ export class AdapterTableClient<T = any> {
       }
     }
 
+    const data = this.encodeVectorFields(rawData);
     const setCols = Object.keys(rawData).filter(k => rawData[k] !== undefined);
     if (setCols.length > 0) {
       const params: Record<string, any> = {};
       const whereSql = parseWhere(this.modelName, args.where, params, this.dialect, 'w_', this.whereContext());
       const sets: string[] = [];
       for (const col of setCols) {
-        appendUpdateSet(sets, params, col, rawData[col], this.dialect);
+        appendUpdateSet(sets, params, col, data[col], this.dialect);
       }
       if (sets.length > 0) {
         const query = `UPDATE ${this.tableName} SET ${sets.join(', ')}${whereSql ? ` WHERE ${whereSql}` : ''}`;
@@ -1025,11 +1143,12 @@ export class AdapterTableClient<T = any> {
   async updateMany(args: { where?: any; data: Partial<T> }): Promise<{ count: number }> {
     const params: Record<string, any> = {};
     const whereSql = parseWhere(this.modelName, args.where, params, this.dialect, 'w_', this.whereContext());
+    const data = this.encodeVectorFields(args.data as Record<string, any>);
     const setCols = Object.keys(args.data).filter(k => (args.data as any)[k] !== undefined);
     const sets: string[] = [];
 
     for (const col of setCols) {
-      appendUpdateSet(sets, params, col, (args.data as any)[col], this.dialect);
+      appendUpdateSet(sets, params, col, data[col], this.dialect);
     }
 
     if (sets.length === 0) return { count: 0 };
@@ -1132,7 +1251,7 @@ export class AdapterTableClient<T = any> {
 
   async groupBy(args: any): Promise<any[]> {
     const params: Record<string, any> = {};
-    const whereSql = parseWhere(this.modelName, args?.where, params, this.dialect);
+    const whereSql = parseWhere(this.modelName, args?.where, params, this.dialect, '', this.whereContext());
     const byFields = normalizeByFields(args?.by);
     if (byFields.length === 0) throw new Error("groupBy requires 'by' fields");
     const byCols = byFields.map((b: string) => quote(b, this.dialect)).join(', ');
@@ -1151,8 +1270,8 @@ export class AdapterTableClient<T = any> {
       const skip = toNonNegativeInt(args?.skip);
       const take = toNonNegativeInt(args?.take, 1);
       if (this.dialect === 'postgres' || this.dialect === 'mysql' || this.dialect === 'sqlite') {
-        if (hasTake) query += ` LIMIT ${take}`;
-        query += ` OFFSET ${skip}`;
+        const limit = hasTake ? take : (this.dialect === 'sqlite' ? '-1' : this.dialect === 'mysql' ? '18446744073709551615' : 'ALL');
+        query += ` LIMIT ${limit} OFFSET ${skip}`;
       } else {
         query += ` OFFSET ${skip} ROWS`;
         if (hasTake) query += ` FETCH NEXT ${take} ROWS ONLY`;
@@ -1385,6 +1504,28 @@ export class AdapterTableClient<T = any> {
         const msg = String(err?.message || '').toLowerCase();
         if (!msg.includes('vector') && !msg.includes('operator does not exist')) throw err;
       }
+    } else if (this.dialect === 'sqlite') {
+      // SQLite has no vector type, so the ranking runs through sqlite-vec, a
+      // driver function, or json_each — whichever this connection supports.
+      const whereSql = parseWhere(this.modelName, args.where, params, this.dialect, '', this.whereContext());
+      const support = await (this.adapter as any).sqliteVectorSupport?.() ?? null;
+      const ranked = await runSqliteVectorSearch({
+        exec: (sql, p) => this.doExec<any>(sql, p),
+        vectorSupport: support,
+        table: this.tableName,
+        rawTable: this.rawTableName,
+        column: col,
+        rawColumn: vectorField,
+        vector: args.vector,
+        metric,
+        take,
+        tail: whereSql ? ` WHERE ${whereSql}` : '',
+        params,
+        preference: (this.adapter as any).vectorStrategy,
+      });
+      if (ranked) return this.decodeVectorFields(ranked.rows) as (T & { distance: number })[];
+      // No in-database strategy: score the column in the client instead.
+      return this.scoreVectorsInMemory(args, metric, take, vectorField);
     } else if (this.dialect === 'mssql') {
       const distFn = metric === 'cosine' ? 'cosine' : metric === 'euclidean' ? 'euclidean' : 'dot';
       const whereSql = parseWhere(this.modelName, args.where, params, this.dialect, '', this.whereContext());
@@ -1411,30 +1552,31 @@ export class AdapterTableClient<T = any> {
     }
 
     // 2. Fallback: in-memory similarity computation when native vector support is unavailable
+    return this.scoreVectorsInMemory(args, metric, take, vectorField);
+  }
+
+  /**
+   * Rank the vector column in the client. This is the last resort for every
+   * provider, and the only option on SQLite connections that offer neither
+   * sqlite-vec, a driver function nor JSON1.
+   *
+   * The whole table is loaded, so it is only reasonable for a table small
+   * enough to fit in memory.
+   */
+  private async scoreVectorsInMemory(
+    args: { vector: number[]; where?: any },
+    metric: 'cosine' | 'euclidean' | 'dot',
+    take: number,
+    vectorField = 'embedding',
+  ): Promise<(T & { distance: number })[]> {
     const rows = await this.findMany({ where: args.where });
 
     const scored: { row: T; dist: number }[] = [];
     for (const row of rows) {
-      const raw = (row as any)[vectorField];
-      if (!raw) continue;
-      let vec: number[] = [];
-      try { vec = typeof raw === 'string' ? JSON.parse(raw) : raw; } catch { continue; }
-      if (!Array.isArray(vec) || vec.length !== args.vector.length) continue;
-
-      let dot = 0, m1 = 0, m2 = 0;
-      for (let i = 0; i < args.vector.length; i++) {
-        const av = args.vector[i] ?? 0;
-        const bv = vec[i] ?? 0;
-        dot += av * bv;
-        m1 += av ** 2;
-        m2 += bv ** 2;
-      }
-      const cosine = m1 && m2 ? dot / (Math.sqrt(m1) * Math.sqrt(m2)) : 0;
-      const dist = metric === 'cosine'
-        ? 1 - cosine
-        : metric === 'dot'
-          ? -dot
-          : Math.sqrt(args.vector.reduce((s, v, i) => s + (v - (vec[i] ?? 0)) ** 2, 0));
+      const vec = decodeVector((row as any)[vectorField]);
+      if (!vec) continue;
+      const dist = vectorDistance(args.vector, vec, metric);
+      if (dist === null) continue;
       scored.push({ row, dist });
     }
     scored.sort((a, b) => a.dist - b.dist);

package/typescript/src/base/metadata.ts

@@ -13,6 +13,14 @@ export interface ModelFieldMeta {
   [key: string]: any;
 }
 
+/** Prefer schema primary-key metadata; retain name inference for legacy clients. */
+export function resolveIdField(fields: Record<string, any>): string | undefined {
+  const primaryKey = Object.keys(fields).find(name => fields[name]?.isId === true);
+  if (primaryKey) return primaryKey;
+  if (Object.prototype.hasOwnProperty.call(fields, 'id')) return 'id';
+  return Object.keys(fields).find(name => name.endsWith('_id') || name.endsWith('Id') || name.toLowerCase() === 'id');
+}
+
 export interface AdapterMetadata {
   modelToTable?: Record<string, string>;
   modelFields?: Record<string, any>;

package/typescript/src/base/sql.ts

@@ -39,6 +39,15 @@ function sanitizeParamName(name: string): string {
   return /^[A-Za-z]/.test(cleaned) ? cleaned : `p_${cleaned}`;
 }
 
+/** Allocate parameters without overwriting values from sibling clauses. */
+export function bindParam(params: Record<string, any>, name: string, value: any): string {
+  let candidate = name;
+  let suffix = 1;
+  while (Object.prototype.hasOwnProperty.call(params, candidate)) candidate = `${name}_${suffix++}`;
+  params[candidate] = value;
+  return candidate;
+}
+
 function normalizeSortDirection(dir: unknown): 'ASC' | 'DESC' {
   return typeof dir === 'string' && dir.toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
 }
@@ -132,26 +141,24 @@ export function parseWhere(
         if (v.not !== undefined) {
           if (v.not === null) { conditions.push(`${col} IS NOT NULL`); }
           else if (v.not && typeof v.not === 'object' && !(v.not instanceof Date) && !Array.isArray(v.not)) {
-            const nestedParams: Record<string, any> = {};
-            const nestedSql = parseWhere(modelName, { [key]: v.not }, nestedParams, dialect, `${prefix}${key}_not_`, ctx);
-            Object.assign(params, nestedParams);
+            const nestedSql = parseWhere(modelName, { [key]: v.not }, params, dialect, `${prefix}${key}_not_`, ctx);
             if (nestedSql) conditions.push(`NOT (${nestedSql})`);
-          } else { const p = `${pname}_not`; params[p] = v.not; conditions.push(`${col} <> @${p}`); }
+          } else { const p = bindParam(params, `${pname}_not`, v.not); conditions.push(`${col} <> @${p}`); }
         }
         if (v.equals !== undefined) {
           if (v.equals === null) { conditions.push(`${col} IS NULL`); }
-          else { const p = `${pname}_eq`; params[p] = v.equals; conditions.push(`${col} = @${p}`); }
+          else { const p = bindParam(params, `${pname}_eq`, v.equals); conditions.push(`${col} = @${p}`); }
         }
-        if (v.contains !== undefined) { const p = `${pname}_co`; params[p] = `%${v.contains}%`; conditions.push(`${col} LIKE @${p}`); }
-        if (v.startsWith !== undefined) { const p = `${pname}_sw`; params[p] = `${v.startsWith}%`; conditions.push(`${col} LIKE @${p}`); }
-        if (v.endsWith !== undefined) { const p = `${pname}_ew`; params[p] = `%${v.endsWith}`; conditions.push(`${col} LIKE @${p}`); }
-        if (v.gte !== undefined) { const p = `${pname}_gte`; params[p] = v.gte; conditions.push(`${col} >= @${p}`); }
-        if (v.lte !== undefined) { const p = `${pname}_lte`; params[p] = v.lte; conditions.push(`${col} <= @${p}`); }
-        if (v.gt !== undefined) { const p = `${pname}_gt`; params[p] = v.gt; conditions.push(`${col} > @${p}`); }
-        if (v.lt !== undefined) { const p = `${pname}_lt`; params[p] = v.lt; conditions.push(`${col} < @${p}`); }
+        if (v.contains !== undefined) { const p = bindParam(params, `${pname}_co`, `%${v.contains}%`); conditions.push(`${col} LIKE @${p}`); }
+        if (v.startsWith !== undefined) { const p = bindParam(params, `${pname}_sw`, `${v.startsWith}%`); conditions.push(`${col} LIKE @${p}`); }
+        if (v.endsWith !== undefined) { const p = bindParam(params, `${pname}_ew`, `%${v.endsWith}`); conditions.push(`${col} LIKE @${p}`); }
+        if (v.gte !== undefined) { const p = bindParam(params, `${pname}_gte`, v.gte); conditions.push(`${col} >= @${p}`); }
+        if (v.lte !== undefined) { const p = bindParam(params, `${pname}_lte`, v.lte); conditions.push(`${col} <= @${p}`); }
+        if (v.gt !== undefined) { const p = bindParam(params, `${pname}_gt`, v.gt); conditions.push(`${col} > @${p}`); }
+        if (v.lt !== undefined) { const p = bindParam(params, `${pname}_lt`, v.lt); conditions.push(`${col} < @${p}`); }
         if (v.in !== undefined) {
           if (Array.isArray(v.in) && v.in.length > 0) {
-            const ps = v.in.map((x: any, i: number) => { const p = `${pname}_in${i}`; params[p] = x; return `@${p}`; });
+            const ps = v.in.map((x: any, i: number) => { const p = bindParam(params, `${pname}_in${i}`, x); return `@${p}`; });
             conditions.push(`${col} IN (${ps.join(', ')})`);
           } else {
             conditions.push('1=0');
@@ -159,15 +166,15 @@ export function parseWhere(
         }
         if (v.notIn !== undefined) {
           if (Array.isArray(v.notIn) && v.notIn.length > 0) {
-            const ps = v.notIn.map((x: any, i: number) => { const p = `${pname}_notin${i}`; params[p] = x; return `@${p}`; });
+            const ps = v.notIn.map((x: any, i: number) => { const p = bindParam(params, `${pname}_notin${i}`, x); return `@${p}`; });
             conditions.push(`${col} NOT IN (${ps.join(', ')})`);
           } else {
             conditions.push('1=1');
           }
         }
       } else {
-        params[pname] = value;
-        conditions.push(`${col} = @${pname}`);
+        const p = bindParam(params, pname, value);
+        conditions.push(`${col} = @${p}`);
       }
     }
   }

package/typescript/src/base/types.ts

@@ -1,3 +1,5 @@
+import type { SqliteVectorSupport, VectorStrategyPreference } from '../sqlite/vector';
+
 export type Dialect = 'mssql' | 'postgres' | 'mysql' | 'sqlite' | 'googlesheets';
 
 export interface An5AdapterConfig {
@@ -8,6 +10,17 @@ export interface An5AdapterConfig {
    * run in NBase while the rows stay in `connectionString`'s database.
    */
   nbase?: string;
+  /**
+   * Path to sqlite-vec or the AN5 native vector extension. On SQLite it is loaded before the
+   * vector capabilities are probed, so `vectorSearch` ranks inside the database
+   * instead of loading the table into memory. Other providers ignore it.
+   */
+  sqliteVec?: string;
+  /**
+   * Pin the SQLite vector search strategy. `auto` (the default) probes for
+   * sqlite-vec, a driver function and JSON1, and uses the first that works.
+   */
+  vectorStrategy?: VectorStrategyPreference;
   engine?: QueryEngine;
   db?: any;
   driver?: any;
@@ -30,4 +43,6 @@ export interface QueryEngine {
   connect(): Promise<void>;
   disconnect(): Promise<void>;
   beginTransaction(): Promise<TransactionHandle>;
+  /** SQLite only: extension loading and distance-function registration. */
+  vectorSupport?: SqliteVectorSupport;
 }

package/typescript/src/googlesheets/adapter.ts

@@ -1,4 +1,5 @@
 import { An5SheetsAdapterConfig, resolveConfig } from './config';
+import { sheetsTokenProvider } from './oauth';
 import type { sheets_v4 } from 'googleapis';
 import { execQuery } from './sqlExecutor';
 import { SheetsTableClient } from './tableClient';
@@ -8,12 +9,10 @@ import { createAdapterProxy } from '../base/metadata';
 
 // ─── Fetch-based API proxy for OAuth Access Token / API Key (browser-compatible) ──
 
-function createFetchApi(spreadsheetId: string, accessToken?: string, apiKey?: string) {
+function createFetchApi(spreadsheetId: string, accessToken?: string, apiKey?: string, oauth: An5SheetsAdapterConfig = { spreadsheetId }) {
   const base = `https://sheets.googleapis.com/v4/spreadsheets/${spreadsheetId}`;
   const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-  if (accessToken) {
-    headers['Authorization'] = `Bearer ${accessToken}`;
-  }
+  const tokenProvider = sheetsTokenProvider({ ...oauth, ...(accessToken ? { accessToken } : {}) });
 
   async function request<T>(method: string, path: string, body?: any): Promise<T> {
     let url = path.startsWith('http') ? path : `${base}${path}`;
@@ -21,9 +20,14 @@ function createFetchApi(spreadsheetId: string, accessToken?: string, apiKey?: st
       const sep = url.includes('?') ? '&' : '?';
       url += `${sep}key=${encodeURIComponent(apiKey)}`;
     }
-    const opts: RequestInit = { method, headers };
+    const token = await tokenProvider();
+    const opts: RequestInit = { method, headers: { ...headers, ...(token ? { Authorization: `Bearer ${token}` } : {}) } };
     if (body) opts.body = JSON.stringify(body);
-    const res = await fetch(url, opts);
+    let res = await fetch(url, opts);
+    if (res.status === 401 && oauth.refreshToken) {
+      const refreshed = await tokenProvider(true);
+      res = await fetch(url, { ...opts, headers: { ...headers, Authorization: `Bearer ${refreshed}` } });
+    }
     if (!res.ok) {
       const text = await res.text().catch(() => '');
       const err = new Error(`Google Sheets API error (${res.status}): ${text}`);
@@ -85,13 +89,17 @@ export class An5SheetsAdapter {
   private sheetsCache: Promise<SheetMeta[]> | null = null;
 
   constructor(config: An5SheetsAdapterConfig) {
+    const browser = typeof window !== 'undefined' || (typeof self !== 'undefined' && typeof process === 'undefined');
+    if (browser && (config.refreshToken || config.oauthClientSecret || config.privateKey || config.credentials)) {
+      throw new Error('Browser Google Sheets connections require a user access token. Keep desktop OAuth refresh tokens and service account keys outside the browser.');
+    }
     this.config = resolveConfig(config);
     // Dynamic model access (`db.user` / `db.User`), same as An5Adapter.
     return createAdapterProxy(this, (name) => this.table(name));
   }
 
   private get isFetchMode(): boolean {
-    return !!(this.config as any).accessToken || !!(this.config as any).apiKey;
+    return !!(this.config as any).accessToken || !!(this.config as any).refreshToken || !!(this.config as any).apiKey;
   }
 
   async getSheets(): Promise<any> {
@@ -100,7 +108,8 @@ export class An5SheetsAdapter {
         this.fetchApi = createFetchApi(
           this.config.spreadsheetId,
           (this.config as any).accessToken,
-          (this.config as any).apiKey
+          (this.config as any).apiKey,
+          this.config as An5SheetsAdapterConfig
         );
       }
       return this.fetchApi;

package/typescript/src/googlesheets/config.ts

@@ -10,6 +10,11 @@ export interface An5SheetsAdapterConfig {
    * When provided, the adapter uses raw fetch() instead of googleapis JWT, making it compatible
    * with browser environments. Mutually exclusive with clientEmail/privateKey/credentials. */
   accessToken?: string;
+  /** Offline desktop OAuth credentials. Keep these in secure storage, never source control. */
+  refreshToken?: string;
+  oauthClientId?: string;
+  oauthClientSecret?: string;
+  tokenExpiresAt?: number;
   /** Google API key for browser-based API access. */
   apiKey?: string;
 }
@@ -22,10 +27,14 @@ export function normalizeKey(key: string): string {
 }
 
 export function resolveConfig(config: An5SheetsAdapterConfig) {
-  if (config.accessToken || config.apiKey) {
+  if (config.accessToken || config.refreshToken || config.apiKey) {
     return {
       spreadsheetId: config.spreadsheetId,
       accessToken: config.accessToken,
+      refreshToken: config.refreshToken,
+      oauthClientId: config.oauthClientId,
+      oauthClientSecret: config.oauthClientSecret,
+      tokenExpiresAt: config.tokenExpiresAt,
       apiKey: config.apiKey,
       sheetMapping: config.sheetMapping,
     };