@an5/adapters 0.2.11 → 0.2.14

package/dist/sqlite/browserEngine.d.ts

@@ -1,4 +1,5 @@
 import type { Dialect, QueryEngine, TransactionHandle } from '../base/types';
+import { SqliteVectorSupport } from './vector';
 export interface SqliteDriver {
     exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]> | T[];
     executeRaw?(query: string, params?: Record<string, any>): Promise<number> | number;
@@ -9,9 +10,21 @@ export interface SqliteBrowserConfig {
     driver?: SqliteDriver;
     exec?: <T = any>(query: string, params?: Record<string, any>) => Promise<T[]> | T[];
     executeRaw?: (query: string, params?: Record<string, any>) => Promise<number> | number;
+    /** Path to the sqlite-vec extension, for WASM builds that allow loading one. */
+    sqliteVec?: string;
+    /** Pin the vector search strategy instead of probing for one. */
+    vectorStrategy?: 'auto' | 'sqlite-vec' | 'udf' | 'sql' | 'memory';
+    /** Register a scalar function with the driver, when its API allows it. */
+    registerFunction?: (name: string, fn: (...args: any[]) => any) => void;
 }
 export declare class SqliteBrowserEngine implements QueryEngine {
     dialect: Dialect;
+    /**
+     * A WASM build cannot register a JS callback as an SQL function, so this only
+     * reaches the `sql` strategy (json_each in plain SQL) and the in-memory one.
+     * A custom `registerFunction` hook unlocks `udf` as well.
+     */
+    readonly vectorSupport: SqliteVectorSupport;
     private db;
     private driver;
     private customExec;

package/dist/sqlite/browserEngine.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SqliteBrowserEngine = void 0;
 exports.createBrowserSqliteAdapter = createBrowserSqliteAdapter;
+const vector_1 = require("./vector");
 // ─── Browser SQLite Engine ──────────────────────────────────────────────────────────
 class SqliteBrowserEngine {
     constructor(config) {
@@ -10,6 +11,18 @@ class SqliteBrowserEngine {
         this.driver = null;
         this.customExec = null;
         this.customExecuteRaw = null;
+        this.vectorSupport = new vector_1.SqliteVectorSupport({
+            native: () => this.db,
+            registerFunction: (name, fn) => {
+                const register = config?.registerFunction;
+                if (typeof register === 'function')
+                    return register(name, fn);
+                const db = this.db;
+                if (db && typeof db.create_function === 'function')
+                    return db.create_function(name, fn);
+                throw new Error('this SQLite build cannot register functions');
+            },
+        }, { sqliteVec: config?.sqliteVec, vectorStrategy: config?.vectorStrategy });
         if (!config)
             return;
         if (config.exec && typeof config.exec === 'function') {

package/dist/sqlite/engine.d.ts

@@ -1,9 +1,14 @@
 import type { An5AdapterConfig, Dialect, QueryEngine, TransactionHandle } from '../base/types';
+import { SqliteVectorSupport } from './vector';
 export declare class SqliteEngine implements QueryEngine {
     dialect: Dialect;
+    /** Registers `an5_vec_*` and loads sqlite-vec for in-database vector search. */
+    readonly vectorSupport: SqliteVectorSupport;
     private db;
     private readonly filePath;
     constructor(adapterConfig: An5AdapterConfig);
+    /** The better-sqlite3 handle, needed for extension loading. */
+    native(): any;
     private getDb;
     exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]>;
     executeRaw(query: string, params?: Record<string, any>): Promise<number>;

package/dist/sqlite/engine.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SqliteEngine = void 0;
+const vector_1 = require("./vector");
 // ─── SQLite Engine ─────────────────────────────────────────────────────────────────
 let BetterSqlite3 = null;
 try {
@@ -17,6 +18,14 @@ class SqliteEngine {
             .replace(/^sqlite:\/\/\//i, '/')
             .replace(/^sqlite:\/\//i, '')
             .replace(/^sqlite:/i, '');
+        this.vectorSupport = new vector_1.SqliteVectorSupport({
+            native: () => this.getDb(),
+            registerFunction: (name, fn) => this.getDb().function(name, { deterministic: true }, fn),
+        }, { sqliteVec: adapterConfig.sqliteVec, vectorStrategy: adapterConfig.vectorStrategy });
+    }
+    /** The better-sqlite3 handle, needed for extension loading. */
+    native() {
+        return this.getDb();
     }
     getDb() {
         if (!this.db)
@@ -42,6 +51,7 @@ class SqliteEngine {
             this.db.close();
             this.db = null;
         }
+        this.vectorSupport.reset();
     }
     async beginTransaction() {
         const db = this.getDb();

package/dist/sqlite/index.d.ts

@@ -1,2 +1,3 @@
 export * from './engine';
 export * from './browserEngine';
+export * from './vector';

package/dist/sqlite/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./engine"), exports);
 __exportStar(require("./browserEngine"), exports);
+__exportStar(require("./vector"), exports);

package/dist/sqlite/vector.d.ts

@@ -0,0 +1,155 @@
+export type VectorMetric = 'cosine' | 'euclidean' | 'dot';
+export type SqliteVectorStrategy = 'sqlite-vec' | 'udf' | 'sql' | 'memory';
+export type VectorStrategyPreference = 'auto' | SqliteVectorStrategy;
+/** Scalar functions shipped by the sqlite-vec extension. */
+export declare const SQLITE_VEC_FUNCTIONS: Record<VectorMetric, string>;
+/** Scalar functions the adapter registers itself when the driver allows it. */
+export declare const AN5_VECTOR_FUNCTIONS: Record<VectorMetric, string>;
+/** Read a numeric array out of the shapes a driver can hand back. */
+export declare function parseVector(value: unknown): number[] | null;
+/**
+ * Decode a stored vector: a float32 BLOB, a legacy JSON text column, or an
+ * array the caller already decoded.
+ */
+export declare function decodeVector(value: unknown): number[] | null;
+/** Encode a vector as the little-endian float32 BLOB `VECTOR(n)` columns store. */
+export declare function encodeVector(values: readonly number[]): Uint8Array;
+/** True when the value still needs encoding on its way into a `VECTOR(n)` column. */
+export declare function needsVectorEncoding(value: unknown): boolean;
+/** True when a generated metadata entry describes a `VECTOR(n)` column. */
+export declare function isVectorField(def: unknown): boolean;
+/**
+ * Distance between two equal-length vectors, lower is closer. Mirrors the
+ * functions registered on the drivers so a search ranks the same way whichever
+ * strategy ran.
+ */
+export declare function vectorDistance(a: readonly number[], b: readonly number[], metric: unknown): number | null;
+export interface SqliteVectorQuery {
+    sql: string;
+    params: Record<string, any>;
+}
+interface BuildArgs {
+    strategy: SqliteVectorStrategy;
+    metric: VectorMetric;
+    /** Already quoted, e.g. `[documents]`. */
+    table: string;
+    /** Already quoted column reference. */
+    column: string;
+    /** The query embedding. */
+    vector: number[];
+    take: number;
+    /** A WHERE tail built by the caller, or empty. */
+    tail?: string;
+    /** Pre-bound WHERE parameters shared with the caller. */
+    params: Record<string, any>;
+}
+/**
+ * Ranking SQL for one strategy. `sqlite-vec` and `udf` bind the query vector as
+ * a float32 BLOB; `sql` binds it as JSON text because `json_each` reads text.
+ */
+export declare function buildSqliteVectorQuery(args: BuildArgs): SqliteVectorQuery;
+export interface SqliteVectorCapabilities {
+    /** AN5's C extension is loaded; keep its functions instead of driver callbacks. */
+    native?: boolean;
+    /** `vec_version()` answered, so the sqlite-vec extension is loaded. */
+    vec: boolean;
+    /** The adapter's own distance functions are registered with the driver. */
+    udf: boolean;
+    /** `json_each()` is available, which the pure-SQL strategy needs. */
+    json1: boolean;
+}
+export interface SqliteVectorOptions {
+    /** Path to the sqlite-vec extension binary to load before probing. */
+    sqliteVec?: string | undefined;
+    /** Pin a strategy instead of probing for the fastest one available. */
+    vectorStrategy?: VectorStrategyPreference | undefined;
+}
+/**
+ * A driver hook the engine can supply to register the distance functions and
+ * load the sqlite-vec extension. Every field is optional: a driver that offers
+ * nothing simply reports no capabilities and the search falls back.
+ */
+/**
+ * Registers a scalar function with the driver. Implementations that take a
+ * determinism flag (better-sqlite3) supply it themselves.
+ */
+export type SqliteVectorFunctionRegistrar = (name: string, fn: (...args: any[]) => any) => void;
+export interface SqliteVectorHooks {
+    /** Raw driver handle, used for `loadExtension`. */
+    native?: () => any;
+    /** Register `name` with the driver's scalar-function API. */
+    registerFunction?: SqliteVectorFunctionRegistrar;
+}
+/**
+ * Resolve the ordered list of strategies to try for this connection.
+ *
+ * `declaredType` is the column's DDL type: the JSON strategy only reaches rows
+ * stored as text, so a `BLOB` column drops it from the order.
+ */
+export declare function planSqliteVectorStrategies(caps: SqliteVectorCapabilities, declaredType: string | null, preference?: VectorStrategyPreference): SqliteVectorStrategy[];
+/**
+ * Register `an5_vec_*` on a driver and load sqlite-vec when a path is configured.
+ * Safe to call repeatedly; each driver hook is used at most once.
+ */
+export declare class SqliteVectorSupport {
+    private readonly hooks;
+    private readonly options;
+    private caps;
+    /**
+     * Declared column types and the "any binary row" probe, keyed by column.
+     *
+     * Both cost a query, and neither changes while a schema is in use. A stale
+     * answer is still safe: the probe only decides which strategy to try first, and
+     * a strategy that fails falls through to the next one rather than reporting a
+     * wrong result.
+     */
+    private readonly columnTypes;
+    private readonly binaryRows;
+    constructor(hooks: SqliteVectorHooks, options?: SqliteVectorOptions);
+    capabilities(): Promise<SqliteVectorCapabilities>;
+    /** Confirms JSON1 and a usable sqlite-vec/UDF before a query is built for them. */
+    probe(exec: (sql: string, params?: Record<string, any>) => Promise<any[]>): Promise<SqliteVectorCapabilities>;
+    /** The column's declared DDL type, remembered per column. */
+    columnType(exec: (sql: string, params?: Record<string, any>) => Promise<any[]>, table: string, column: string): Promise<string | null>;
+    /**
+     * Whether any row stores raw bytes, which `json_each` cannot read.
+     *
+     * Checked only for the `sql` strategy, where a legacy JSON column that has
+     * since taken new float32 rows would otherwise rank just the old ones.
+     */
+    hasBinaryRows(exec: (sql: string, params?: Record<string, any>) => Promise<any[]>, table: string, column: string, tail: string, params: Record<string, any>): Promise<boolean>;
+    reset(): void;
+}
+/** Reads a vector column's declared DDL type, or null when it cannot be found. */
+export declare function readSqliteColumnType(exec: (sql: string, params?: Record<string, any>) => Promise<any[]>, table: string, column: string): Promise<string | null>;
+export interface SqliteVectorSearchArgs {
+    exec: (sql: string, params?: Record<string, any>) => Promise<any[]>;
+    /** Absent when the engine cannot register functions or load extensions. */
+    vectorSupport?: SqliteVectorSupport | null;
+    /** Quoted table reference, e.g. `[documents]`. */
+    table: string;
+    /** Unquoted table name, for `pragma_table_info`. */
+    rawTable: string;
+    /** Quoted column reference. */
+    column: string;
+    /** Unquoted column name. */
+    rawColumn: string;
+    vector: number[];
+    metric: VectorMetric;
+    take: number;
+    /** A WHERE tail (leading space included) or empty. */
+    tail?: string | undefined;
+    /** Parameter object shared with the caller's WHERE clause. */
+    params: Record<string, any>;
+    preference?: VectorStrategyPreference | undefined;
+}
+/**
+ * Rank a SQLite table by distance inside the database, trying each available
+ * strategy in order. Returns null when the connection offers none, so the
+ * caller can fall back to scoring in memory.
+ */
+export declare function runSqliteVectorSearch(args: SqliteVectorSearchArgs): Promise<{
+    rows: Record<string, any>[];
+    strategy: SqliteVectorStrategy;
+} | null>;
+export {};