@an5/adapters 0.2.5 → 0.2.9

package/dist/googlesheets/sqlExecutor.js

@@ -46,9 +46,9 @@ function matchRowSQL(row, whereText, values) {
         const m = part.match(/^(.+?)\s*(=|!=|<>|>|<|>=|<=|LIKE|CONTAINS)\s*(.+)$/i);
         if (!m)
             continue;
-        const field = m[1].trim().replace(/[[\]]/g, '');
-        const op = m[2].toUpperCase();
-        const valRef = m[3].trim();
+        const field = (m[1] ?? '').trim().replace(/[[\]]/g, '');
+        const op = (m[2] ?? '').toUpperCase();
+        const valRef = (m[3] ?? '').trim();
         const val = valRef.startsWith('?') ? values[parseInt(valRef.slice(1))] : valRef.replace(/^['"]|['"]$/g, '');
         const cell = row[field];
         switch (op) {
@@ -94,20 +94,26 @@ function extractColsAndVals(sql, params) {
     const vals = [];
     const colMatch = sql.match(/\(([^)]+)\)\s*VALUES/i);
     if (colMatch) {
-        const rawCols = colMatch[1].split(',').map(c => c.trim().replace(/[[\]]/g, ''));
+        const rawCols = (colMatch[1] ?? '').split(',').map(c => c.trim().replace(/[[\]]/g, ''));
         // Find actual values
-        const valMatch = sql.substring(colMatch.index + colMatch[0].length).match(/\(([^)]+)\)/);
+        const valMatch = sql.substring((colMatch.index ?? 0) + colMatch[0].length).match(/\(([^)]+)\)/);
         if (valMatch) {
-            const rawVals = valMatch[1].split(',').map(v => v.trim());
+            const rawVals = (valMatch[1] ?? '').split(',').map(v => v.trim());
             for (let i = 0; i < rawCols.length; i++) {
-                cols.push(rawCols[i]);
+                const col = rawCols[i];
+                if (col === undefined)
+                    continue;
+                cols.push(col);
                 const rv = rawVals[i];
-                if (rv.startsWith('@') && params && params[rv.slice(1)] !== undefined) {
+                if (rv !== undefined && rv.startsWith('@') && params && params[rv.slice(1)] !== undefined) {
                     vals.push(params[rv.slice(1)]);
                 }
-                else {
+                else if (rv !== undefined) {
                     vals.push(rv.replace(/^['"]|['"]$/g, ''));
                 }
+                else {
+                    vals.push(null);
+                }
             }
         }
     }
@@ -125,13 +131,13 @@ async function execSelect(adapter, query, params) {
             return obj;
         });
     }
-    const sheetName = m[2] || m[3] || m[4];
+    const sheetName = m[2] ?? m[3] ?? m[4] ?? '';
     const whereClause = m[5];
     const raw = await adapter.readRange((0, helpers_1.esc)(sheetName) + '!A:ZZ');
     if (raw.length < 1)
         return [];
     const headers = raw[0];
-    const fieldList = m[1].trim();
+    const fieldList = (m[1] ?? '*').trim();
     const selectAll = fieldList === '*';
     const rows = raw.slice(1).map(row => {
         const obj = {};
@@ -139,16 +145,15 @@ async function execSelect(adapter, query, params) {
         return obj;
     });
     if (!whereClause)
-        return selectAll ? rows : rows.map(r => pickFields(r, fieldList, headers));
-    const { text, values } = substParams(query, params);
+        return selectAll ? rows : rows.map(r => pickFields(r, fieldList));
     // Extract just the WHERE part
     const whereParts = query.match(/WHERE\s+(.+)$/i);
-    const whereText = whereParts ? whereParts[1] : '';
+    const whereText = whereParts?.[1] ?? '';
     const { text: whereSubst, values: whereVals } = substParams(whereText, params);
     const result = rows.filter(r => matchRowSQL(r, whereSubst, whereVals));
-    return selectAll ? result : result.map(r => pickFields(r, fieldList, headers));
+    return selectAll ? result : result.map(r => pickFields(r, fieldList));
 }
-function pickFields(row, fieldList, headers) {
+function pickFields(row, fieldList) {
     const fields = fieldList.split(',').map(f => f.trim().replace(/[[\]]/g, ''));
     const obj = {};
     fields.forEach(f => { obj[f] = row[f]; });
@@ -158,7 +163,7 @@ async function execInsert(adapter, query, params) {
     const m = query.match(/INSERT\s+INTO\s+(?:'([^']+)'|"([^"]+)"|(\S+))\s*(.*)/i);
     if (!m)
         throw new Error('Invalid INSERT syntax');
-    const sheetName = m[1] || m[2] || m[3];
+    const sheetName = m[1] ?? m[2] ?? m[3] ?? '';
     const { cols, vals } = extractColsAndVals(query, params);
     if (cols.length === 0)
         throw new Error('Cannot extract columns from INSERT');
@@ -198,8 +203,8 @@ async function execUpdate(adapter, query, params) {
     const m = query.match(/UPDATE\s+(?:'([^']+)'|"([^"]+)"|(\S+))\s+SET\s+(.+?)(?:\s+WHERE\s+(.+))?$/i);
     if (!m)
         throw new Error('Invalid UPDATE syntax');
-    const sheetName = m[1] || m[2] || m[3];
-    const setClause = m[4];
+    const sheetName = m[1] ?? m[2] ?? m[3] ?? '';
+    const setClause = m[4] ?? '';
     const whereClause = m[5];
     // Parse SET clause
     const setPairs = setClause.split(',').map(p => p.trim());
@@ -209,8 +214,8 @@ async function execUpdate(adapter, query, params) {
         const sm = pair.match(/^(\w+)\s*=\s*(.+)$/i);
         if (!sm)
             continue;
-        setFields.push(sm[1].replace(/[[\]]/g, ''));
-        const rv = sm[2].trim();
+        setFields.push((sm[1] ?? '').replace(/[[\]]/g, ''));
+        const rv = (sm[2] ?? '').trim();
         if (rv.startsWith('@') && params && params[rv.slice(1)] !== undefined) {
             setVals.push(params[rv.slice(1)]);
         }
@@ -230,7 +235,7 @@ async function execUpdate(adapter, query, params) {
     let count = 0;
     for (let i = 0; i < rows.length; i++) {
         const row = {};
-        headers.forEach((h, j) => { row[h] = rows[i][j] ?? null; });
+        headers.forEach((h, j) => { row[h] = rows[i]?.[j] ?? null; });
         row.__row = i + 2;
         if (whereClause && !matchRowSQL(row, whereSubst, whereVals))
             continue;
@@ -253,7 +258,7 @@ async function execDelete(adapter, query, params) {
     const m = query.match(/DELETE\s+FROM\s+(?:'([^']+)'|"([^"]+)"|(\S+))\s*(?:WHERE\s+(.+))?$/i);
     if (!m)
         throw new Error('Invalid DELETE syntax');
-    const sheetName = m[1] || m[2] || m[3];
+    const sheetName = m[1] ?? m[2] ?? m[3] ?? '';
     const whereClause = m[4];
     const meta = await adapter.getSheetMeta(sheetName);
     if (!meta)
@@ -282,7 +287,7 @@ async function execDelete(adapter, query, params) {
     const toDelete = [];
     for (let i = 1; i < raw.length; i++) {
         const row = {};
-        headers.forEach((h, j) => { row[h] = raw[i][j] ?? null; });
+        headers.forEach((h, j) => { row[h] = raw[i]?.[j] ?? null; });
         if (matchRowSQL(row, whereSubst, whereVals)) {
             toDelete.push(i + 1);
         }

package/dist/googlesheets/tableClient.js

@@ -54,7 +54,10 @@ class SheetsTableClient {
         for (let i = 1; i < values.length; i++) {
             const row = { __row: i + 1 };
             for (let j = 0; j < headers.length; j++) {
-                row[headers[j]] = (0, helpers_1.coerceCell)(values[i][j], this.fields[headers[j]]);
+                const h = headers[j];
+                if (h === undefined)
+                    continue;
+                row[h] = (0, helpers_1.coerceCell)(values[i]?.[j], this.fields[h]);
             }
             rows.push(row);
         }
@@ -222,6 +225,8 @@ class SheetsTableClient {
         if (matching.length === 0)
             throw new Error('No record found matching where clause');
         const target = matching[0];
+        if (target === undefined)
+            throw new Error('No record found matching where clause');
         const updated = { ...target, ...args.data, __row: target.__row };
         await this.adapter.writeRange(`${this.escSheetName}!A${target.__row}`, [
             this.rowToValues(updated, headers),
@@ -256,6 +261,8 @@ class SheetsTableClient {
         if (matching.length === 0)
             throw new Error('No record found matching where clause');
         const target = matching[0];
+        if (target === undefined)
+            throw new Error('No record found matching where clause');
         const meta = await this.adapter.getSheetMeta(this.sheetName);
         if (!meta)
             throw new Error(`Sheet "${this.sheetName}" not found`);
@@ -395,14 +402,16 @@ class SheetsTableClient {
                 continue;
             let dot = 0, m1 = 0, m2 = 0;
             for (let i = 0; i < args.vector.length; i++) {
-                dot += args.vector[i] * vec[i];
-                m1 += args.vector[i] ** 2;
-                m2 += vec[i] ** 2;
+                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]) ** 2, 0));
+                    : Math.sqrt(args.vector.reduce((s, v, i) => s + (v - (vec[i] ?? 0)) ** 2, 0));
             scored.push({ row, dist });
         }
         scored.sort((a, b) => a.dist - b.dist);

package/dist/index.d.ts

@@ -1,5 +1,9 @@
-export { An5Adapter, AdapterTableClient, createAn5Adapter, setAdapterMetadata, } from './an5Adapter';
+export { An5Adapter, AdapterTableClient, createAn5Adapter, createAdapterProxy, executorFromAdapter, setAdapterMetadata, } from './an5Adapter';
+export { parseWhere, buildOrderBy, quote } from './base/sql';
+export { NBaseVectorClient, NBaseError, createNBaseVectorClient, createNBaseClient, parseNBaseConnectionString, buildVectorId, parseVectorId, } from './nbase';
+export type { NBaseAdapterConfig, NBaseClientConfig, NBaseVector, NBaseSearchOptions, NBaseSearchResult, NBaseStats, } from './nbase';
 export type { An5AdapterConfig, AdapterMetadata, Dialect, } from './an5Adapter';
+export type { TypedAn5Adapter, AdapterAPI } from './typed';
 export { getLlmConfig, setLlmConfig, getEmbeddingConfig, setEmbeddingConfig, resetAdapter, } from './config';
 export type { LlmConfigData, EmbeddingConfigData, } from './config';
 export { An5SheetsAdapter, SheetsTableClient, createAn5SheetsAdapter, parseSheetsConnectionString, } from './googlesheets';

package/dist/index.js

@@ -1,11 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseSheetsConnectionString = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = exports.resetAdapter = exports.setEmbeddingConfig = exports.getEmbeddingConfig = exports.setLlmConfig = exports.getLlmConfig = exports.setAdapterMetadata = exports.createAn5Adapter = exports.AdapterTableClient = exports.An5Adapter = void 0;
+exports.parseSheetsConnectionString = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = exports.resetAdapter = exports.setEmbeddingConfig = exports.getEmbeddingConfig = exports.setLlmConfig = exports.getLlmConfig = exports.parseVectorId = exports.buildVectorId = exports.parseNBaseConnectionString = exports.createNBaseClient = exports.createNBaseVectorClient = exports.NBaseError = exports.NBaseVectorClient = exports.quote = exports.buildOrderBy = exports.parseWhere = exports.setAdapterMetadata = exports.executorFromAdapter = exports.createAdapterProxy = exports.createAn5Adapter = exports.AdapterTableClient = exports.An5Adapter = void 0;
 var an5Adapter_1 = require("./an5Adapter");
 Object.defineProperty(exports, "An5Adapter", { enumerable: true, get: function () { return an5Adapter_1.An5Adapter; } });
 Object.defineProperty(exports, "AdapterTableClient", { enumerable: true, get: function () { return an5Adapter_1.AdapterTableClient; } });
 Object.defineProperty(exports, "createAn5Adapter", { enumerable: true, get: function () { return an5Adapter_1.createAn5Adapter; } });
+Object.defineProperty(exports, "createAdapterProxy", { enumerable: true, get: function () { return an5Adapter_1.createAdapterProxy; } });
+Object.defineProperty(exports, "executorFromAdapter", { enumerable: true, get: function () { return an5Adapter_1.executorFromAdapter; } });
 Object.defineProperty(exports, "setAdapterMetadata", { enumerable: true, get: function () { return an5Adapter_1.setAdapterMetadata; } });
+var sql_1 = require("./base/sql");
+Object.defineProperty(exports, "parseWhere", { enumerable: true, get: function () { return sql_1.parseWhere; } });
+Object.defineProperty(exports, "buildOrderBy", { enumerable: true, get: function () { return sql_1.buildOrderBy; } });
+Object.defineProperty(exports, "quote", { enumerable: true, get: function () { return sql_1.quote; } });
+var nbase_1 = require("./nbase");
+Object.defineProperty(exports, "NBaseVectorClient", { enumerable: true, get: function () { return nbase_1.NBaseVectorClient; } });
+Object.defineProperty(exports, "NBaseError", { enumerable: true, get: function () { return nbase_1.NBaseError; } });
+Object.defineProperty(exports, "createNBaseVectorClient", { enumerable: true, get: function () { return nbase_1.createNBaseVectorClient; } });
+Object.defineProperty(exports, "createNBaseClient", { enumerable: true, get: function () { return nbase_1.createNBaseClient; } });
+Object.defineProperty(exports, "parseNBaseConnectionString", { enumerable: true, get: function () { return nbase_1.parseNBaseConnectionString; } });
+Object.defineProperty(exports, "buildVectorId", { enumerable: true, get: function () { return nbase_1.buildVectorId; } });
+Object.defineProperty(exports, "parseVectorId", { enumerable: true, get: function () { return nbase_1.parseVectorId; } });
 var config_1 = require("./config");
 Object.defineProperty(exports, "getLlmConfig", { enumerable: true, get: function () { return config_1.getLlmConfig; } });
 Object.defineProperty(exports, "setLlmConfig", { enumerable: true, get: function () { return config_1.setLlmConfig; } });

package/dist/mssql/engine.js

@@ -12,7 +12,7 @@ function parseMssqlConnectionString(url) {
     // Strip scheme prefix
     cleanUrl = cleanUrl.replace(/^(?:sqlserver|mssql):\/\//i, '');
     const parts = cleanUrl.split(';');
-    const firstPart = parts[0].trim();
+    const firstPart = (parts[0] ?? '').trim();
     // host:port or host,port (SQL Server native style)
     let server = firstPart;
     let port = 1433;
@@ -35,7 +35,10 @@ function parseMssqlConnectionString(url) {
         connectionTimeout: 15000,
     };
     for (let i = 1; i < parts.length; i++) {
-        const part = parts[i].trim();
+        const rawPart = parts[i];
+        if (rawPart === undefined)
+            continue;
+        const part = rawPart.trim();
         if (!part)
             continue;
         const eqIdx = part.indexOf('=');
@@ -52,7 +55,8 @@ function parseMssqlConnectionString(url) {
         else if (key === 'server' || key === 'data source') {
             // SERVER=host,port style (key-value form)
             const [s, p] = value.split(',');
-            config.server = s.trim();
+            if (s !== undefined)
+                config.server = s.trim();
             if (p)
                 config.port = parseInt(p.trim(), 10) || 1433;
         }
@@ -70,7 +74,7 @@ class MssqlEngine {
     constructor(adapterConfig) {
         this.dialect = 'mssql';
         this.pool = null;
-        this.config = parseMssqlConnectionString(adapterConfig.connectionString);
+        this.config = parseMssqlConnectionString(adapterConfig.connectionString ?? '');
         if (adapterConfig.poolMax)
             this.config.pool = { ...this.config.pool, max: adapterConfig.poolMax };
         if (adapterConfig.requestTimeout)

package/dist/mysql/engine.js

@@ -14,7 +14,7 @@ class MysqlEngine {
         if (!Mysql2)
             throw new Error('mysql2 package is required for MySQL support. Run: npm install mysql2');
         this.pool = Mysql2.createPool({
-            uri: adapterConfig.connectionString,
+            uri: adapterConfig.connectionString ?? '',
             connectionLimit: adapterConfig.poolMax ?? 10,
             connectTimeout: adapterConfig.connectionTimeout ?? 15000,
         });

package/dist/nbase/client.d.ts

@@ -0,0 +1,92 @@
+/**
+ * NBase — Neural Vector Database client.
+ *
+ * NBase is a vector database with HNSW/LSH/KNN indexing exposed over a REST
+ * API. an5 uses it to move similarity search out of the database process: the
+ * vectors live in NBase, the rows stay in the relational table, and the search
+ * results are hydrated from the table by the id kept in vector metadata.
+ *
+ * The client only uses the global `fetch`, so it works in Node 18+ and in the
+ * browser without pulling in a dependency.
+ */
+export interface NBaseVector {
+    id: string | number;
+    vector: number[];
+    metadata?: Record<string, unknown>;
+}
+export interface NBaseSearchOptions {
+    /** Number of neighbours to return. */
+    k?: number;
+    /** Distance metric; NBase accepts `cosine` and `euclidean`. */
+    distanceMetric?: 'cosine' | 'euclidean';
+    /** `hnsw` uses the graph index, anything else uses the clustered path. */
+    method?: 'hnsw' | 'clustered';
+    efSearch?: number;
+    filters?: Record<string, unknown> | Array<Record<string, unknown>>;
+    includeMetadata?: boolean;
+    includeVectors?: boolean;
+    skipCache?: boolean;
+    searchTimeoutMs?: number;
+    rerank?: boolean;
+    rerankingMethod?: string;
+    rerankLambda?: number;
+    partitionIds?: string[];
+}
+export interface NBaseSearchResult {
+    id: string | number;
+    /** Distance from the query vector. Lower is more similar. */
+    dist: number;
+    metadata?: Record<string, unknown>;
+    vector?: number[];
+    dimension?: number;
+}
+export interface NBaseClientConfig {
+    /** Base URL, e.g. `http://localhost:1307`. */
+    url: string;
+    /** Optional bearer token, for deployments behind an auth proxy. */
+    token?: string;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Injectable for tests and for runtimes without a global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface NBaseStats {
+    vectorCount?: number;
+    metadataCount?: number;
+    memoryUsage?: number;
+    [key: string]: unknown;
+}
+export declare class NBaseError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: unknown;
+    constructor(message: string, status?: number | undefined, body?: unknown);
+}
+export declare class NBaseVectorClient {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(config: NBaseClientConfig);
+    private request;
+    /** Liveness probe. NBase mounts its status routes at the server root. */
+    health(): Promise<{
+        status: string;
+        version?: string;
+    }>;
+    /** Vector count, memory use and other database statistics. */
+    stats(): Promise<NBaseStats>;
+    /** Adds or replaces vectors. NBase accepts a single vector or a bulk array. */
+    addVectors(vectors: NBaseVector[]): Promise<{
+        count: number;
+        ids?: Array<string | number>;
+    }>;
+    /** Nearest-neighbour search. Results are ordered by ascending `dist`. */
+    search(vector: number[], options?: NBaseSearchOptions): Promise<NBaseSearchResult[]>;
+    /** Reads a single vector. Returns undefined when the id is unknown. */
+    get(id: string | number): Promise<NBaseSearchResult | undefined>;
+    exists(id: string | number): Promise<boolean>;
+    delete(id: string | number): Promise<boolean>;
+    updateMetadata(id: string | number, metadata: Record<string, unknown>): Promise<boolean>;
+}
+/** Creates an NBase vector client. */
+export declare function createNBaseVectorClient(config: NBaseClientConfig): NBaseVectorClient;

package/dist/nbase/client.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * NBase — Neural Vector Database client.
+ *
+ * NBase is a vector database with HNSW/LSH/KNN indexing exposed over a REST
+ * API. an5 uses it to move similarity search out of the database process: the
+ * vectors live in NBase, the rows stay in the relational table, and the search
+ * results are hydrated from the table by the id kept in vector metadata.
+ *
+ * The client only uses the global `fetch`, so it works in Node 18+ and in the
+ * browser without pulling in a dependency.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NBaseVectorClient = exports.NBaseError = void 0;
+exports.createNBaseVectorClient = createNBaseVectorClient;
+const DEFAULT_TIMEOUT_MS = 30000;
+class NBaseError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'NBaseError';
+    }
+}
+exports.NBaseError = NBaseError;
+class NBaseVectorClient {
+    constructor(config) {
+        this.config = config;
+        this.baseUrl = String(config.url).replace(/\/+$/, '');
+        const impl = config.fetchImpl ?? globalThis.fetch;
+        if (!impl) {
+            throw new NBaseError('No fetch implementation available. Node 18+ or a fetch polyfill is required.');
+        }
+        this.fetchImpl = impl;
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async request(path, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                ...init,
+                signal: controller.signal,
+                headers: {
+                    'content-type': 'application/json',
+                    ...(this.config.token ? { authorization: `Bearer ${this.config.token}` } : {}),
+                    ...init?.headers,
+                },
+            });
+            const text = await response.text();
+            let body;
+            try {
+                body = text ? JSON.parse(text) : undefined;
+            }
+            catch {
+                body = text;
+            }
+            if (!response.ok) {
+                const message = (body && typeof body === 'object' && 'error' in body
+                    ? String(body.error)
+                    : undefined) ?? `HTTP ${response.status}`;
+                throw new NBaseError(`NBase request ${path} failed: ${message}`, response.status, body);
+            }
+            return body;
+        }
+        catch (err) {
+            if (err instanceof NBaseError)
+                throw err;
+            if (err?.name === 'AbortError') {
+                throw new NBaseError(`NBase request ${path} timed out after ${this.timeoutMs}ms`);
+            }
+            throw new NBaseError(`Could not reach NBase at ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Liveness probe. NBase mounts its status routes at the server root. */
+    async health() {
+        return this.request('/health');
+    }
+    /** Vector count, memory use and other database statistics. */
+    async stats() {
+        return this.request('/stats');
+    }
+    /** Adds or replaces vectors. NBase accepts a single vector or a bulk array. */
+    async addVectors(vectors) {
+        if (vectors.length === 0)
+            return { count: 0 };
+        const result = await this.request('/api/vectors', { method: 'POST', body: JSON.stringify({ vectors: vectors.length === 1 ? vectors[0] : vectors }) });
+        return { count: result.count ?? vectors.length, ...(result.addedIds ? { ids: result.addedIds } : {}) };
+    }
+    /** Nearest-neighbour search. Results are ordered by ascending `dist`. */
+    async search(vector, options = {}) {
+        const body = await this.request('/api/search', {
+            method: 'POST',
+            body: JSON.stringify({
+                query: vector,
+                k: options.k ?? 10,
+                ...(options.distanceMetric ? { distanceMetric: options.distanceMetric } : {}),
+                ...(options.method ? { method: options.method } : {}),
+                ...(options.efSearch !== undefined ? { efSearch: options.efSearch } : {}),
+                ...(options.filters ? { filters: options.filters } : {}),
+                ...(options.includeMetadata !== undefined ? { includeMetadata: options.includeMetadata } : {}),
+                ...(options.includeVectors !== undefined ? { includeVectors: options.includeVectors } : {}),
+                ...(options.skipCache !== undefined ? { skipCache: options.skipCache } : {}),
+                ...(options.searchTimeoutMs !== undefined ? { searchTimeoutMs: options.searchTimeoutMs } : {}),
+                ...(options.rerank !== undefined ? { rerank: options.rerank } : {}),
+                ...(options.rerankingMethod ? { rerankingMethod: options.rerankingMethod } : {}),
+                ...(options.rerankLambda !== undefined ? { rerankLambda: options.rerankLambda } : {}),
+                ...(options.partitionIds ? { partitionIds: options.partitionIds } : {}),
+            }),
+        });
+        return body.results ?? [];
+    }
+    /** Reads a single vector. Returns undefined when the id is unknown. */
+    async get(id) {
+        try {
+            return await this.request(`/api/vectors/${encodeURIComponent(String(id))}`);
+        }
+        catch (err) {
+            if (err instanceof NBaseError && err.status === 404)
+                return undefined;
+            throw err;
+        }
+    }
+    async exists(id) {
+        const result = await this.request(`/api/vectors/${encodeURIComponent(String(id))}/exists`);
+        return result.exists === true;
+    }
+    async delete(id) {
+        await this.request(`/api/vectors/${encodeURIComponent(String(id))}`, { method: 'DELETE' });
+        return true;
+    }
+    async updateMetadata(id, metadata) {
+        await this.request(`/api/vectors/${encodeURIComponent(String(id))}/metadata`, {
+            method: 'PATCH',
+            body: JSON.stringify(metadata),
+        });
+        return true;
+    }
+}
+exports.NBaseVectorClient = NBaseVectorClient;
+/** Creates an NBase vector client. */
+function createNBaseVectorClient(config) {
+    return new NBaseVectorClient(config);
+}

package/dist/nbase/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * NBase connection-string and adapter configuration.
+ *
+ * NBase is configured through the connection string alone:
+ *
+ *    createAn5Adapter({ connectionString: 'nbase://localhost:1307' })
+ *
+ * Accepted forms are `nbase://host:port`, `nbase:host:port` and an explicit
+ * scheme, with optional `?token=…&timeoutMs=…&method=…` options. An adapter
+ * created this way is vector-only: it has no relational database, so a search
+ * returns the NBase hits instead of table rows.
+ */
+import { NBaseVectorClient, NBaseError, createNBaseVectorClient, type NBaseClientConfig, type NBaseVector, type NBaseSearchOptions, type NBaseSearchResult, type NBaseStats } from './client';
+export interface NBaseAdapterConfig extends NBaseClientConfig {
+    url: string;
+    /**
+     * Metadata key that holds the relational row id. `an5Id` by default, which
+     * is what `indexTableVectors` writes.
+     */
+    idField?: string;
+    /** Metadata key holding the model name, used to keep collections apart. */
+    modelField?: string;
+    /** Force the search method instead of letting NBase choose. */
+    method?: 'hnsw' | 'clustered';
+}
+/** True when the whole connection string points at NBase. */
+export declare function isNBaseConnectionString(connectionString: string): boolean;
+/**
+ * Parses an NBase connection string.
+ *
+ * Accepts `nbase:http://host:port`, `nbase://host:port` and
+ * `nbase:host:port`, with optional `?token=…&timeoutMs=…` options.
+ */
+export declare function parseNBaseConnectionString(connectionString: string): NBaseAdapterConfig;
+/** Builds the vector id used to link a NBase vector back to a relational row. */
+export declare function buildVectorId(model: string, id: string | number): string;
+/** Splits a vector id produced by {@link buildVectorId}. */
+export declare function parseVectorId(vectorId: string | number): {
+    model: string;
+    id: string;
+};
+export declare function createNBaseClient(config: NBaseAdapterConfig | string): {
+    client: NBaseVectorClient;
+    options: NBaseAdapterConfig;
+};
+export { NBaseVectorClient, NBaseError, createNBaseVectorClient };
+export type { NBaseClientConfig, NBaseVector, NBaseSearchOptions, NBaseSearchResult, NBaseStats };

package/dist/nbase/index.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNBaseVectorClient = exports.NBaseError = exports.NBaseVectorClient = void 0;
+exports.isNBaseConnectionString = isNBaseConnectionString;
+exports.parseNBaseConnectionString = parseNBaseConnectionString;
+exports.buildVectorId = buildVectorId;
+exports.parseVectorId = parseVectorId;
+exports.createNBaseClient = createNBaseClient;
+/**
+ * NBase connection-string and adapter configuration.
+ *
+ * NBase is configured through the connection string alone:
+ *
+ *    createAn5Adapter({ connectionString: 'nbase://localhost:1307' })
+ *
+ * Accepted forms are `nbase://host:port`, `nbase:host:port` and an explicit
+ * scheme, with optional `?token=…&timeoutMs=…&method=…` options. An adapter
+ * created this way is vector-only: it has no relational database, so a search
+ * returns the NBase hits instead of table rows.
+ */
+const client_1 = require("./client");
+Object.defineProperty(exports, "NBaseVectorClient", { enumerable: true, get: function () { return client_1.NBaseVectorClient; } });
+Object.defineProperty(exports, "NBaseError", { enumerable: true, get: function () { return client_1.NBaseError; } });
+Object.defineProperty(exports, "createNBaseVectorClient", { enumerable: true, get: function () { return client_1.createNBaseVectorClient; } });
+/** Matches `nbase:`, `nbase://` and `nbase=http(s)://` at the start of a value. */
+const NBASE_PREFIX = /^nbase:(?:\/\/)?/i;
+/** True when the whole connection string points at NBase. */
+function isNBaseConnectionString(connectionString) {
+    return NBASE_PREFIX.test(connectionString.trim());
+}
+/** Builds options from a URL and an optional query string. */
+function buildOptions(url, query) {
+    const params = new URLSearchParams(query ?? '');
+    const trimmed = url.trim().replace(/\/+$/, '');
+    // `nbase://host:port` is shorthand for the same host over HTTP; an explicit
+    // scheme is used as-is so https deployments work.
+    const withScheme = !trimmed
+        ? 'http://localhost:1307'
+        : /^[a-z]+:\/\//i.test(trimmed)
+            ? trimmed
+            : `http://${trimmed}`;
+    return {
+        url: withScheme,
+        ...(params.get('token') ? { token: params.get('token') } : {}),
+        ...(params.get('timeoutMs') ? { timeoutMs: Number(params.get('timeoutMs')) } : {}),
+        ...(params.get('idField') ? { idField: params.get('idField') } : {}),
+        ...(params.get('modelField') ? { modelField: params.get('modelField') } : {}),
+        ...(params.get('method') ? { method: params.get('method') } : {}),
+    };
+}
+/**
+ * Parses an NBase connection string.
+ *
+ * Accepts `nbase:http://host:port`, `nbase://host:port` and
+ * `nbase:host:port`, with optional `?token=…&timeoutMs=…` options.
+ */
+function parseNBaseConnectionString(connectionString) {
+    const raw = connectionString.trim();
+    if (!isNBaseConnectionString(raw)) {
+        throw new Error(`Not an NBase connection string: ${raw}`);
+    }
+    const [url, query] = raw.replace(NBASE_PREFIX, '').split('?');
+    return buildOptions(url ?? '', query);
+}
+/** Builds the vector id used to link a NBase vector back to a relational row. */
+function buildVectorId(model, id) {
+    return `${model}:${id}`;
+}
+/** Splits a vector id produced by {@link buildVectorId}. */
+function parseVectorId(vectorId) {
+    const raw = String(vectorId);
+    const separator = raw.indexOf(':');
+    if (separator === -1)
+        return { model: '', id: raw };
+    return { model: raw.slice(0, separator), id: raw.slice(separator + 1) };
+}
+function createNBaseClient(config) {
+    const options = typeof config === 'string' ? parseNBaseConnectionString(config) : config;
+    return { client: (0, client_1.createNBaseVectorClient)(options), options };
+}

package/dist/postgres/engine.js

@@ -14,7 +14,7 @@ class PostgresEngine {
         if (!PgPool)
             throw new Error('pg package is required for PostgreSQL support. Run: npm install pg');
         this.pool = new PgPool({
-            connectionString: adapterConfig.connectionString,
+            connectionString: adapterConfig.connectionString ?? '',
             max: adapterConfig.poolMax ?? 10,
         });
     }