@an5/adapters 0.2.5 → 0.2.9

package/dist/an5Adapter.js

@@ -1,19 +1,208 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAdapter = exports.AdapterTableClient = exports.An5AdapterTx = exports.An5Adapter = exports.setAdapterMetadata = void 0;
+exports.createAdapter = exports.AdapterTableClient = exports.An5AdapterTx = exports.ViewClient = exports.An5Adapter = exports.createAdapterProxy = exports.setAdapterMetadata = void 0;
 exports.createAn5Adapter = createAn5Adapter;
+exports.createBrowserSqliteAdapter = createBrowserSqliteAdapter;
+exports.executorFromAdapter = executorFromAdapter;
 const uuid_1 = require("./base/uuid");
 const googlesheets_1 = require("./googlesheets");
 const parseConnectionString_1 = require("./googlesheets/parseConnectionString");
+/**
+ * File extensions that mean SQLite when a connection string has no scheme.
+ *
+ * `.sqlite3` is here as well as in `@an5/orm`'s `detectProvider`, because the ORM
+ * validates field types and writes the DDL from the provider this file picks: if the
+ * two lists differed, a `.sqlite3` file would be pushed as SQL Server DDL.
+ */
+const SQLITE_FILE_SUFFIXES = ['.sqlite', '.sqlite3', '.db'];
+const nbase_1 = require("./nbase");
 const sql_1 = require("./base/sql");
 const metadata_1 = require("./base/metadata");
 var metadata_2 = require("./base/metadata");
 Object.defineProperty(exports, "setAdapterMetadata", { enumerable: true, get: function () { return metadata_2.setAdapterMetadata; } });
+Object.defineProperty(exports, "createAdapterProxy", { enumerable: true, get: function () { return metadata_2.createAdapterProxy; } });
 function isSheetsConfig(config) {
     return config.spreadsheetId !== undefined;
 }
+function sanitizeParamName(name) {
+    const cleaned = String(name).replace(/[^A-Za-z0-9_]/g, '_');
+    return /^[A-Za-z]/.test(cleaned) ? cleaned : `p_${cleaned}`;
+}
+function appendUpdateSet(sets, params, col, val, dialect) {
+    const quoted = (0, sql_1.quote)(col, dialect);
+    const safeCol = sanitizeParamName(col);
+    if (val && typeof val === 'object' && !(val instanceof Date)) {
+        if (val.increment !== undefined) {
+            sets.push(`${quoted} = ${quoted} + @s_${safeCol}_inc`);
+            params[`s_${safeCol}_inc`] = val.increment;
+            return;
+        }
+        if (val.decrement !== undefined) {
+            sets.push(`${quoted} = ${quoted} - @s_${safeCol}_dec`);
+            params[`s_${safeCol}_dec`] = val.decrement;
+            return;
+        }
+        if (val.multiply !== undefined) {
+            sets.push(`${quoted} = ${quoted} * @s_${safeCol}_mul`);
+            params[`s_${safeCol}_mul`] = val.multiply;
+            return;
+        }
+        if (val.divide !== undefined) {
+            sets.push(`${quoted} = ${quoted} / @s_${safeCol}_div`);
+            params[`s_${safeCol}_div`] = val.divide;
+            return;
+        }
+        if (val.set !== undefined) {
+            sets.push(`${quoted} = @s_${safeCol}_set`);
+            params[`s_${safeCol}_set`] = val.set;
+            return;
+        }
+    }
+    sets.push(`${quoted} = @s_${safeCol}`);
+    params[`s_${safeCol}`] = val;
+}
+function selectedAggregateFields(fields) {
+    if (!fields || typeof fields !== 'object')
+        return [];
+    return Object.keys(fields).filter(key => fields[key]);
+}
+function normalizeByFields(by) {
+    if (typeof by === 'string')
+        return [by];
+    return Array.isArray(by) ? by.filter(field => typeof field === 'string' && field.length > 0) : [];
+}
+function toNonNegativeInt(value, fallback = 0) {
+    const n = Number.parseInt(String(value), 10);
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
+function projectFields(row, select) {
+    if (!row || !select || typeof select !== 'object')
+        return row;
+    const projected = {};
+    for (const [key, val] of Object.entries(select)) {
+        if (val) {
+            projected[key] = row[key];
+        }
+    }
+    if (row._count) {
+        projected._count = row._count;
+    }
+    return projected;
+}
+async function resolveIncludes(modelName, rows, include, adapter) {
+    if (!rows || rows.length === 0 || !include || typeof include !== 'object')
+        return;
+    const modelRelations = (0, metadata_1.getRelationsForModel)(modelName);
+    for (const [key, value] of Object.entries(include)) {
+        if (!value)
+            continue;
+        if (key === '_count') {
+            for (const row of rows) {
+                if (!row._count)
+                    row._count = {};
+            }
+            for (const [relKey, relation] of Object.entries(modelRelations)) {
+                if (relation.relationType === 'many') {
+                    const uniqueKeys = Array.from(new Set(rows.map(r => r[relation.localKey]).filter(k => k !== undefined && k !== null)));
+                    if (uniqueKeys.length > 0) {
+                        const relClient = adapter.table(relation.modelName);
+                        const relatedRows = await relClient.findMany({
+                            where: { [relation.foreignKey]: { in: uniqueKeys } },
+                        });
+                        const countMap = new Map();
+                        relatedRows.forEach((r) => {
+                            const k = r[relation.foreignKey];
+                            countMap.set(k, (countMap.get(k) || 0) + 1);
+                        });
+                        rows.forEach(r => {
+                            const k = r[relation.localKey];
+                            r._count[relKey] = countMap.get(k) || 0;
+                        });
+                    }
+                    else {
+                        rows.forEach(r => { r._count[relKey] = 0; });
+                    }
+                }
+            }
+            continue;
+        }
+        const relation = modelRelations[key];
+        if (!relation)
+            continue;
+        const isMany = relation.relationType === 'many';
+        const localKey = relation.localKey;
+        const foreignKey = relation.foreignKey;
+        const joinKey = isMany ? localKey : foreignKey;
+        const matchKey = isMany ? foreignKey : localKey;
+        const uniqueKeys = Array.from(new Set(rows.map(r => r[joinKey]).filter(k => k !== undefined && k !== null)));
+        if (uniqueKeys.length === 0) {
+            rows.forEach(r => { r[key] = isMany ? [] : null; });
+            continue;
+        }
+        const subArgs = typeof value === 'object' ? { ...value } : {};
+        const nestedInclude = subArgs.include;
+        const nestedSelect = subArgs.select;
+        const subWhere = {
+            [matchKey]: { in: uniqueKeys },
+            ...(subArgs.where || {}),
+        };
+        const relClient = adapter.table(relation.modelName);
+        const relatedRows = await relClient.findMany({
+            where: subWhere,
+            orderBy: subArgs.orderBy,
+            take: subArgs.take,
+            skip: subArgs.skip,
+        });
+        if (nestedInclude) {
+            await resolveIncludes(relation.modelName, relatedRows, nestedInclude, adapter);
+        }
+        const outputRows = nestedSelect && typeof nestedSelect === 'object'
+            ? relatedRows.map((r) => projectFields(r, nestedSelect))
+            : relatedRows;
+        const groupMap = new Map();
+        relatedRows.forEach((r, idx) => {
+            const k = r[isMany ? foreignKey : localKey];
+            if (!groupMap.has(k))
+                groupMap.set(k, []);
+            groupMap.get(k).push(outputRows[idx]);
+        });
+        rows.forEach(r => {
+            const k = r[isMany ? localKey : foreignKey];
+            const matches = groupMap.get(k) || [];
+            if (isMany) {
+                r[key] = matches;
+            }
+            else {
+                r[key] = matches[0] || null;
+            }
+        });
+    }
+}
 // ─── An5Adapter ────────────────────────────────────────────────────────────────────
 class An5Adapter {
+    /**
+     * Returns the NBase client for this adapter, if the project configured one.
+     * The connection string may also point straight at NBase, which keeps
+     * `DATABASE_URL=nbase://host:port` working on its own.
+     */
+    nbaseClient() {
+        if (this._nbase && this._nbaseConfig)
+            return { client: this._nbase, config: this._nbaseConfig };
+        if (!this._nbaseConfig)
+            return null;
+        const config = this._nbaseConfig;
+        const client = (0, nbase_1.createNBaseVectorClient)(config);
+        this._nbase = client;
+        this._nbaseConfig = config;
+        return { client, config };
+    }
+    /**
+     * True when the adapter only knows about NBase, so there is no relational
+     * database to read rows from.
+     */
+    get nbaseOnly() {
+        return this._nbaseOnly === true;
+    }
     get dialect() {
         if (this.sheetsAdapter)
             return 'googlesheets';
@@ -32,49 +221,89 @@ class An5Adapter {
         this._engineType = null;
         this._engineConfig = null;
         this.sheetsAdapter = null;
+        this._nbase = null;
+        this._nbaseConfig = null;
+        this._nbaseOnly = false;
+        this._listeners = {};
+        this._middlewares = [];
         if (isSheetsConfig(adapterConfig)) {
             this.sheetsAdapter = new googlesheets_1.An5SheetsAdapter(adapterConfig);
-            return;
+            return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
+        }
+        // Keep the config even when the caller supplies its own engine: the NBase
+        // settings and anything else on the config are read from it later.
+        this._engineConfig = adapterConfig;
+        // `nbase://host:port` as the connection string configures the vector store
+        // on its own: there is no relational database, so the adapter is
+        // vector-only. The same string passed as `nbase` keeps the database from
+        // `connectionString` as the source of rows.
+        const rawConnectionString = String(this._engineConfig.connectionString ?? '').trim();
+        if ((0, nbase_1.isNBaseConnectionString)(rawConnectionString)) {
+            this._nbaseConfig = (0, nbase_1.parseNBaseConnectionString)(rawConnectionString);
+            this._nbaseOnly = true;
+            return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
         }
-        const cs = adapterConfig.connectionString.trim();
-        if (cs.startsWith('googlesheets://')) {
+        const attached = this._engineConfig.nbase;
+        if (attached && (0, nbase_1.isNBaseConnectionString)(attached)) {
+            this._nbaseConfig = (0, nbase_1.parseNBaseConnectionString)(attached);
+        }
+        if (adapterConfig.engine) {
+            this._engine = adapterConfig.engine;
+            this._engineType = this._engine?.dialect || 'sqlite';
+            return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
+        }
+        if (adapterConfig.db || adapterConfig.driver) {
+            const { SqliteBrowserEngine } = require('./sqlite/browserEngine.js');
+            this._engine = new SqliteBrowserEngine(adapterConfig);
+            this._engineType = 'sqlite';
+            return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
+        }
+        // Lower-cased for the dialect test only; the connection string itself keeps its
+        // case for the driver. A URI scheme is case-insensitive, and `@an5/orm` reads the
+        // provider the same way to validate field types and write DDL — if the two
+        // disagreed, a schema would be checked against one database and run on another.
+        const cs = (adapterConfig.connectionString || '').trim();
+        const forDialect = cs.toLowerCase();
+        if (forDialect.startsWith('googlesheets://')) {
             this.sheetsAdapter = new googlesheets_1.An5SheetsAdapter((0, parseConnectionString_1.parseSheetsConnectionString)(cs));
-            return;
+            return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
         }
         this._engineConfig = adapterConfig;
-        if (cs.startsWith('postgres://') || cs.startsWith('postgresql://')) {
+        if (forDialect.startsWith('postgres://') || forDialect.startsWith('postgresql://')) {
             this._engineType = 'postgres';
         }
-        else if (cs.startsWith('mysql://') || cs.startsWith('mariadb://')) {
+        else if (forDialect.startsWith('mysql://') || forDialect.startsWith('mariadb://')) {
             this._engineType = 'mysql';
         }
-        else if (cs.startsWith('sqlite://') || cs.endsWith('.sqlite') || cs.endsWith('.db')) {
+        else if (forDialect.startsWith('sqlite://')
+            || SQLITE_FILE_SUFFIXES.some((suffix) => forDialect.endsWith(suffix))) {
             this._engineType = 'sqlite';
         }
         else {
             this._engineType = 'mssql';
         }
+        return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
     }
     async requireEngine() {
         if (!this._engine && this._engineType) {
             switch (this._engineType) {
                 case 'postgres': {
-                    const { PostgresEngine } = require('./postgres.js');
+                    const { PostgresEngine } = require('./postgres/index.js');
                     this._engine = new PostgresEngine(this._engineConfig);
                     break;
                 }
                 case 'mysql': {
-                    const { MysqlEngine } = require('./mysql.js');
+                    const { MysqlEngine } = require('./mysql/index.js');
                     this._engine = new MysqlEngine(this._engineConfig);
                     break;
                 }
                 case 'sqlite': {
-                    const { SqliteEngine } = require('./sqlite.js');
+                    const { SqliteEngine } = require('./sqlite/index.js');
                     this._engine = new SqliteEngine(this._engineConfig);
                     break;
                 }
                 case 'mssql': {
-                    const { MssqlEngine } = require('./mssql.js');
+                    const { MssqlEngine } = require('./mssql/index.js');
                     this._engine = new MssqlEngine(this._engineConfig);
                     break;
                 }
@@ -139,8 +368,36 @@ class An5Adapter {
     async $connect() {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.$connect();
+        if (this._nbaseOnly) {
+            // NBase is stateless over HTTP, so there is nothing to open. Report the
+            // endpoint so a misconfiguration is obvious.
+            const config = this.nbaseClient()?.config;
+            if (config)
+                await this.nbaseClient().client.health();
+            return;
+        }
         await (await this.requireEngine()).connect();
     }
+    /**
+     * Health check for the configured NBase instance, or the database when the
+     * adapter has none.
+     */
+    async $nbaseHealth() {
+        const nbase = this.nbaseClient();
+        if (!nbase)
+            return { connected: false, error: 'No NBase instance configured.' };
+        try {
+            const health = await nbase.client.health();
+            return { connected: health.status === 'ok', endpoint: nbase.config.url };
+        }
+        catch (err) {
+            return {
+                connected: false,
+                endpoint: nbase.config.url,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
     async $disconnect() {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.$disconnect();
@@ -164,11 +421,107 @@ class An5Adapter {
             throw err;
         }
     }
+    async $begin() {
+        if (this.sheetsAdapter) {
+            throw new Error('Interactive transactions are not supported by the Google Sheets adapter');
+        }
+        const engine = await this.requireEngine();
+        return new An5AdapterTx(await engine.beginTransaction(), this.dialect);
+    }
     table(modelName) {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.table(modelName);
         return new AdapterTableClient(this, modelName);
     }
+    $on(event, callback) {
+        if (!this._listeners[event])
+            this._listeners[event] = [];
+        this._listeners[event].push(callback);
+        return this;
+    }
+    $off(event, callback) {
+        if (!this._listeners[event])
+            return this;
+        this._listeners[event] = this._listeners[event].filter(cb => cb !== callback);
+        return this;
+    }
+    $emit(event, ...args) {
+        if (this._listeners[event]) {
+            for (const cb of this._listeners[event]) {
+                try {
+                    cb(...args);
+                }
+                catch { }
+            }
+        }
+    }
+    $use(middleware) {
+        this._middlewares.push(middleware);
+        return this;
+    }
+    view(viewName) {
+        return new ViewClient(this, viewName);
+    }
+    async $queryProc(procName, params) {
+        if (this.sheetsAdapter)
+            throw new Error('Stored procedures are not supported by the Google Sheets adapter');
+        const paramObj = {};
+        let sql = '';
+        if (Array.isArray(params)) {
+            const placeholders = params.map((v, i) => {
+                paramObj[`p_${i}`] = v;
+                return `@p_${i}`;
+            });
+            sql = this.dialect === 'postgres' || this.dialect === 'mysql'
+                ? `CALL ${procName}(${placeholders.join(', ')})`
+                : `EXEC ${procName} ${placeholders.join(', ')}`;
+        }
+        else if (params && typeof params === 'object') {
+            const pairs = Object.entries(params).map(([k, v]) => {
+                paramObj[`p_${k}`] = v;
+                return `@${k} = @p_${k}`;
+            });
+            sql = this.dialect === 'postgres' || this.dialect === 'mysql'
+                ? `CALL ${procName}(${Object.keys(params).map(k => `@p_${k}`).join(', ')})`
+                : `EXEC ${procName} ${pairs.join(', ')}`;
+        }
+        else {
+            sql = this.dialect === 'postgres' || this.dialect === 'mysql'
+                ? `CALL ${procName}()`
+                : `EXEC ${procName}`;
+        }
+        return this.exec(sql, paramObj);
+    }
+    async $executeProc(procName, params) {
+        if (this.sheetsAdapter)
+            throw new Error('Stored procedures are not supported by the Google Sheets adapter');
+        const paramObj = {};
+        let sql = '';
+        if (Array.isArray(params)) {
+            const placeholders = params.map((v, i) => {
+                paramObj[`p_${i}`] = v;
+                return `@p_${i}`;
+            });
+            sql = this.dialect === 'postgres' || this.dialect === 'mysql'
+                ? `CALL ${procName}(${placeholders.join(', ')})`
+                : `EXEC ${procName} ${placeholders.join(', ')}`;
+        }
+        else if (params && typeof params === 'object') {
+            const pairs = Object.entries(params).map(([k, v]) => {
+                paramObj[`p_${k}`] = v;
+                return `@${k} = @p_${k}`;
+            });
+            sql = this.dialect === 'postgres' || this.dialect === 'mysql'
+                ? `CALL ${procName}(${Object.keys(params).map(k => `@p_${k}`).join(', ')})`
+                : `EXEC ${procName} ${pairs.join(', ')}`;
+        }
+        else {
+            sql = this.dialect === 'postgres' || this.dialect === 'mysql'
+                ? `CALL ${procName}()`
+                : `EXEC ${procName}`;
+        }
+        return this._executeRaw(sql, paramObj);
+    }
     async readRange(range) {
         return this.requireSheetsAdapter().readRange(range);
     }
@@ -186,21 +539,92 @@ class An5Adapter {
     }
 }
 exports.An5Adapter = An5Adapter;
+// ─── View Client (Read-Only) ────────────────────────────────────────────────────────
+class ViewClient {
+    constructor(adapter, viewName) {
+        this.adapter = adapter;
+        this.viewName = viewName;
+        this.tableClient = new AdapterTableClient(adapter, viewName);
+    }
+    get dialect() { return this.tableClient.dialect; }
+    get tableName() { return this.tableClient.tableName; }
+    async findMany(args) {
+        return this.tableClient.findMany(args);
+    }
+    async findFirst(args) {
+        return this.tableClient.findFirst(args);
+    }
+    async findUnique(args) {
+        return this.tableClient.findUnique(args);
+    }
+    async count(args) {
+        return this.tableClient.count(args);
+    }
+    async aggregate(args) {
+        return this.tableClient.aggregate(args);
+    }
+    async groupBy(args) {
+        return this.tableClient.groupBy(args);
+    }
+    async vectorSearch(args) {
+        return this.tableClient.vectorSearch(args);
+    }
+    async create() {
+        throw new Error(`View '${this.viewName}' is read-only. Mutation operations (create) are not allowed.`);
+    }
+    async createMany() {
+        throw new Error(`View '${this.viewName}' is read-only. Mutation operations (createMany) are not allowed.`);
+    }
+    async update() {
+        throw new Error(`View '${this.viewName}' is read-only. Mutation operations (update) are not allowed.`);
+    }
+    async updateMany() {
+        throw new Error(`View '${this.viewName}' is read-only. Mutation operations (updateMany) are not allowed.`);
+    }
+    async delete() {
+        throw new Error(`View '${this.viewName}' is read-only. Mutation operations (delete) are not allowed.`);
+    }
+    async deleteMany() {
+        throw new Error(`View '${this.viewName}' is read-only. Mutation operations (deleteMany) are not allowed.`);
+    }
+    async upsert() {
+        throw new Error(`View '${this.viewName}' is read-only. Mutation operations (upsert) are not allowed.`);
+    }
+}
+exports.ViewClient = ViewClient;
 // ─── Transaction-scoped adapter ────────────────────────────────────────────────────
 class An5AdapterTx {
     constructor(handle, dialect) {
         this.handle = handle;
         this.dialect = dialect;
+        this.closed = false;
+        return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
     }
     async exec(query, params) {
+        this.ensureOpen();
         return this.handle.exec(query, params);
     }
     async _executeRaw(query, params) {
+        this.ensureOpen();
         return this.handle.executeRaw(query, params);
     }
+    async $commit() {
+        this.ensureOpen();
+        this.closed = true;
+        await this.handle.commit();
+    }
+    async $rollback() {
+        this.ensureOpen();
+        this.closed = true;
+        await this.handle.rollback();
+    }
     table(modelName) {
         return new AdapterTableClient(this, modelName);
     }
+    ensureOpen() {
+        if (this.closed)
+            throw new Error('Transaction is already closed');
+    }
 }
 exports.An5AdapterTx = An5AdapterTx;
 // ─── Table Client ──────────────────────────────────────────────────────────────────
@@ -235,6 +659,14 @@ class AdapterTableClient {
     get nolock() {
         return this.dialect === 'mssql' ? ' WITH (NOLOCK)' : '';
     }
+    /** Build the shared context used by parseWhere to resolve relations and self references. */
+    whereContext() {
+        return {
+            relationMap: (0, metadata_1.getRelationMap)(),
+            modelToTable: (0, metadata_1.getModelToTable)(),
+            selfRef: this.tableName,
+        };
+    }
     async doExec(query, params) {
         return this.adapter.exec(query, params);
     }
@@ -243,49 +675,92 @@ class AdapterTableClient {
     }
     async findMany(args) {
         const params = {};
-        const whereSql = (0, sql_1.parseWhere)(this.modelName, args?.where, params, this.dialect);
+        const whereCtx = this.whereContext();
+        const whereSql = (0, sql_1.parseWhere)(this.modelName, args?.where, params, this.dialect, '', whereCtx);
         const orderSql = (0, sql_1.buildOrderBy)(args?.orderBy, this.dialect);
         const take = args?.take;
-        const skip = args?.skip ?? 0;
+        const skip = args?.skip;
+        const hasSkip = skip !== undefined && skip !== null;
+        let cols = "*";
+        if (args?.select && typeof args.select === "object") {
+            const relationKeys = (0, metadata_1.getRelationsForModel)(this.modelName);
+            const hasRelationSelect = Object.keys(args.select).some(k => k === '_count' || relationKeys[k]);
+            const fields = (0, metadata_1.getFieldsForModel)(this.modelName);
+            const selectedKeys = Object.keys(args.select).filter(k => args.select[k] === true && (Object.keys(fields).length === 0 || fields[k]));
+            if (selectedKeys.length > 0 && !hasRelationSelect) {
+                cols = selectedKeys.map(k => (0, sql_1.quote)(k, this.dialect)).join(", ");
+            }
+        }
         let query;
-        if (take !== undefined) {
+        if (take !== undefined && !hasSkip) {
             if (this.dialect === 'postgres' || this.dialect === 'mysql' || this.dialect === 'sqlite') {
-                query = `SELECT * FROM ${this.tableName}`;
+                query = `SELECT ${cols} FROM ${this.tableName}`;
                 if (whereSql)
                     query += ` WHERE ${whereSql}`;
                 if (orderSql)
                     query += ` ${orderSql}`;
-                query += ` LIMIT ${take} OFFSET ${skip}`;
+                query += ` LIMIT ${take}`;
+            }
+            else {
+                query = `SELECT TOP (${take}) ${cols} FROM ${this.tableName}${this.nolock}`;
+                if (whereSql)
+                    query += ` WHERE ${whereSql}`;
+                if (orderSql)
+                    query += ` ${orderSql}`;
+            }
+        }
+        else if (hasSkip) {
+            if (this.dialect === 'postgres' || this.dialect === 'mysql' || this.dialect === 'sqlite') {
+                query = `SELECT ${cols} FROM ${this.tableName}`;
+                if (whereSql)
+                    query += ` WHERE ${whereSql}`;
+                if (orderSql)
+                    query += ` ${orderSql}`;
+                query += ` LIMIT ${take ?? 'ALL'} OFFSET ${skip}`;
             }
             else {
                 // mssql requires ORDER BY before OFFSET/FETCH
-                query = `SELECT * FROM ${this.tableName}${this.nolock}`;
+                query = `SELECT ${cols} FROM ${this.tableName}${this.nolock}`;
                 if (whereSql)
                     query += ` WHERE ${whereSql}`;
                 query += ` ${orderSql || 'ORDER BY (SELECT NULL)'}`;
-                query += ` OFFSET ${skip} ROWS FETCH NEXT ${take} ROWS ONLY`;
+                query += ` OFFSET ${skip} ROWS`;
+                if (take !== undefined) {
+                    query += ` FETCH NEXT ${take} ROWS ONLY`;
+                }
             }
         }
         else {
-            query = `SELECT * FROM ${this.tableName}${this.nolock}`;
+            query = `SELECT ${cols} FROM ${this.tableName}${this.nolock}`;
             if (whereSql)
                 query += ` WHERE ${whereSql}`;
             if (orderSql)
                 query += ` ${orderSql}`;
         }
-        return this.doExec(query, params);
+        const rows = await this.doExec(query, params);
+        if (args?.include) {
+            await resolveIncludes(this.modelName, rows, args.include, this.adapter);
+        }
+        if (args?.select && typeof args.select === 'object') {
+            const relationKeys = (0, metadata_1.getRelationsForModel)(this.modelName);
+            const hasRelationSelect = Object.keys(args.select).some(k => k === '_count' || relationKeys[k]);
+            if (hasRelationSelect) {
+                await resolveIncludes(this.modelName, rows, args.select, this.adapter);
+            }
+            return rows.map((r) => projectFields(r, args.select));
+        }
+        return rows;
     }
     async findFirst(args) {
         const rows = await this.findMany({ ...args, take: 1 });
         return rows[0] ?? null;
     }
     async findUnique(args) {
-        return this.findFirst({ where: args.where });
+        return this.findFirst({ where: args.where, select: args.select, include: args.include });
     }
     async count(args) {
         const params = {};
-        const whereSql = (0, sql_1.parseWhere)(this.modelName, args?.where, params, this.dialect);
-        // Add NOLOCK for mssql count too
+        const whereSql = (0, sql_1.parseWhere)(this.modelName, args?.where, params, this.dialect, '', this.whereContext());
         let query = `SELECT COUNT(*) AS cnt FROM ${this.tableName}${this.nolock}`;
         if (whereSql)
             query += ` WHERE ${whereSql}`;
@@ -293,11 +768,20 @@ class AdapterTableClient {
         return Number(rows[0]?.cnt ?? rows[0]?.CNT ?? 0);
     }
     async create(args) {
+        const modelRelations = (0, metadata_1.getRelationsForModel)(this.modelName);
+        const rawData = { ...args.data };
+        const relationWrites = {};
+        for (const key of Object.keys(rawData)) {
+            if (modelRelations[key] && typeof rawData[key] === 'object' && rawData[key] !== null && !(rawData[key] instanceof Date)) {
+                relationWrites[key] = rawData[key];
+                delete rawData[key];
+            }
+        }
         const fields = (0, metadata_1.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 data = { ...args.data };
+        const data = { ...rawData };
         if (idFieldName) {
             const fieldDef = fields[idFieldName];
             const rawType = typeof fieldDef === 'string' ? fieldDef : (fieldDef?.ts || fieldDef?.sql || fieldDef?.type || '');
@@ -316,12 +800,41 @@ class AdapterTableClient {
         }
         const query = `INSERT INTO ${this.tableName} (${cols.map(c => (0, sql_1.quote)(c, this.dialect)).join(', ')}) VALUES (${vals.join(', ')})`;
         await this.doExec(query, params);
-        return (await this.findFirst({ where: idFieldName ? { [idFieldName]: data[idFieldName] } : data }));
+        const createdRecord = (await this.findFirst({ where: idFieldName ? { [idFieldName]: data[idFieldName] } : data }));
+        // Handle nested relation writes
+        for (const [relKey, relWrite] of Object.entries(relationWrites)) {
+            const relation = modelRelations[relKey];
+            if (!relation)
+                continue;
+            const childClient = this.adapter.table(relation.modelName);
+            if (relWrite.create) {
+                const createItems = Array.isArray(relWrite.create) ? relWrite.create : [relWrite.create];
+                for (const item of createItems) {
+                    await childClient.create({
+                        data: {
+                            ...item,
+                            [relation.foreignKey]: createdRecord[relation.localKey],
+                        },
+                    });
+                }
+            }
+        }
+        if (args.include) {
+            await resolveIncludes(this.modelName, [createdRecord], args.include, this.adapter);
+        }
+        if (args.select) {
+            await resolveIncludes(this.modelName, [createdRecord], args.select, this.adapter);
+            return projectFields(createdRecord, args.select);
+        }
+        return createdRecord;
     }
     async createMany(args) {
         if (args.data.length === 0)
             return { count: 0 };
-        const firstCols = Object.keys(args.data[0]).filter(k => args.data[0][k] !== undefined);
+        const firstRow = args.data[0];
+        if (firstRow === undefined)
+            return { count: 0 };
+        const firstCols = Object.keys(firstRow).filter(k => firstRow[k] !== undefined);
         // Bulk INSERT for the common case (same columns, no skipDuplicates)
         if (firstCols.length > 0 && !args.skipDuplicates) {
             const params = {};
@@ -359,29 +872,80 @@ class AdapterTableClient {
         return { count };
     }
     async update(args) {
-        const params = {};
-        const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect, 'w_');
-        const setCols = Object.keys(args.data).filter(k => args.data[k] !== undefined);
-        const sets = [];
-        for (const col of setCols) {
-            const p = `s_${col}`;
-            params[p] = args.data[col];
-            sets.push(`${(0, sql_1.quote)(col, this.dialect)} = @${p}`);
+        const modelRelations = (0, metadata_1.getRelationsForModel)(this.modelName);
+        const rawData = { ...args.data };
+        const relationWrites = {};
+        for (const key of Object.keys(rawData)) {
+            if (modelRelations[key] && typeof rawData[key] === 'object' && rawData[key] !== null && !(rawData[key] instanceof Date)) {
+                relationWrites[key] = rawData[key];
+                delete rawData[key];
+            }
         }
-        const query = `UPDATE ${this.tableName} SET ${sets.join(', ')}${whereSql ? ` WHERE ${whereSql}` : ''}`;
-        await this.doExecuteRaw(query, params);
-        return (await this.findFirst({ where: args.where }));
+        const setCols = Object.keys(rawData).filter(k => rawData[k] !== undefined);
+        if (setCols.length > 0) {
+            const params = {};
+            const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect, 'w_', this.whereContext());
+            const sets = [];
+            for (const col of setCols) {
+                appendUpdateSet(sets, params, col, rawData[col], this.dialect);
+            }
+            if (sets.length > 0) {
+                const query = `UPDATE ${this.tableName} SET ${sets.join(', ')}${whereSql ? ` WHERE ${whereSql}` : ''}`;
+                await this.doExecuteRaw(query, params);
+            }
+        }
+        const updatedRecord = (await this.findFirst({ where: args.where }));
+        // Handle nested writes
+        for (const [relKey, relWrite] of Object.entries(relationWrites)) {
+            const relation = modelRelations[relKey];
+            if (!relation)
+                continue;
+            const childClient = this.adapter.table(relation.modelName);
+            if (relWrite.create) {
+                const createItems = Array.isArray(relWrite.create) ? relWrite.create : [relWrite.create];
+                for (const item of createItems) {
+                    await childClient.create({
+                        data: {
+                            ...item,
+                            [relation.foreignKey]: updatedRecord[relation.localKey],
+                        },
+                    });
+                }
+            }
+            if (relWrite.update) {
+                const updateObj = relWrite.update;
+                await childClient.update({
+                    where: updateObj.where,
+                    data: updateObj.data,
+                });
+            }
+            if (relWrite.disconnect) {
+                const disc = relWrite.disconnect;
+                await childClient.updateMany({
+                    where: disc,
+                    data: { [relation.foreignKey]: null },
+                });
+            }
+        }
+        if (args.include) {
+            await resolveIncludes(this.modelName, [updatedRecord], args.include, this.adapter);
+        }
+        if (args.select) {
+            await resolveIncludes(this.modelName, [updatedRecord], args.select, this.adapter);
+            return projectFields(updatedRecord, args.select);
+        }
+        return updatedRecord;
     }
     async updateMany(args) {
         const params = {};
-        const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect, 'w_');
+        const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect, 'w_', this.whereContext());
         const setCols = Object.keys(args.data).filter(k => args.data[k] !== undefined);
         const sets = [];
         for (const col of setCols) {
-            const p = `s_${col}`;
-            params[p] = args.data[col];
-            sets.push(`${(0, sql_1.quote)(col, this.dialect)} = @${p}`);
+            appendUpdateSet(sets, params, col, args.data[col], this.dialect);
         }
+        if (sets.length === 0)
+            return { count: 0 };
         const query = `UPDATE ${this.tableName} SET ${sets.join(', ')}${whereSql ? ` WHERE ${whereSql}` : ''}`;
         const count = await this.doExecuteRaw(query, params);
         return { count };
@@ -389,13 +953,13 @@ class AdapterTableClient {
     async delete(args) {
         const existing = await this.findFirst({ where: args.where });
         const params = {};
-        const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect);
+        const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect, '', this.whereContext());
         await this.doExecuteRaw(`DELETE FROM ${this.tableName} WHERE ${whereSql}`, params);
         return existing;
     }
     async deleteMany(args) {
         const params = {};
-        const whereSql = (0, sql_1.parseWhere)(this.modelName, args?.where, params, this.dialect);
+        const whereSql = (0, sql_1.parseWhere)(this.modelName, args?.where, params, this.dialect, '', this.whereContext());
         const query = `DELETE FROM ${this.tableName}${whereSql ? ` WHERE ${whereSql}` : ''}`;
         const count = await this.doExecuteRaw(query, params);
         return { count };
@@ -408,37 +972,345 @@ class AdapterTableClient {
     }
     async aggregate(args) {
         const params = {};
-        const whereSql = (0, sql_1.parseWhere)(this.modelName, args?.where, params, this.dialect);
+        const whereSql = (0, sql_1.parseWhere)(this.modelName, args?.where, params, this.dialect, '', this.whereContext());
         const aggs = [];
-        if (args._count)
-            aggs.push('COUNT(*) AS _count');
+        if (args._count) {
+            aggs.push('COUNT(*) AS cnt_all');
+            if (typeof args._count === 'object') {
+                for (const f of selectedAggregateFields(args._count)) {
+                    if (f !== '_all')
+                        aggs.push(`COUNT(${(0, sql_1.quote)(f, this.dialect)}) AS cnt_${sanitizeParamName(f)}`);
+                }
+            }
+        }
         if (args._sum)
-            for (const f of Object.keys(args._sum))
-                aggs.push(`SUM(${(0, sql_1.quote)(f, this.dialect)}) AS _sum_${f}`);
+            for (const f of selectedAggregateFields(args._sum))
+                aggs.push(`SUM(${(0, sql_1.quote)(f, this.dialect)}) AS sum_${sanitizeParamName(f)}`);
         if (args._avg)
-            for (const f of Object.keys(args._avg))
-                aggs.push(`AVG(${(0, sql_1.quote)(f, this.dialect)}) AS _avg_${f}`);
+            for (const f of selectedAggregateFields(args._avg))
+                aggs.push(`AVG(${(0, sql_1.quote)(f, this.dialect)}) AS avg_${sanitizeParamName(f)}`);
         if (args._min)
-            for (const f of Object.keys(args._min))
-                aggs.push(`MIN(${(0, sql_1.quote)(f, this.dialect)}) AS _min_${f}`);
+            for (const f of selectedAggregateFields(args._min))
+                aggs.push(`MIN(${(0, sql_1.quote)(f, this.dialect)}) AS min_${sanitizeParamName(f)}`);
         if (args._max)
-            for (const f of Object.keys(args._max))
-                aggs.push(`MAX(${(0, sql_1.quote)(f, this.dialect)}) AS _max_${f}`);
-        const query = `SELECT ${aggs.join(', ')} FROM ${this.tableName}${whereSql ? ` WHERE ${whereSql}` : ''}`;
+            for (const f of selectedAggregateFields(args._max))
+                aggs.push(`MAX(${(0, sql_1.quote)(f, this.dialect)}) AS max_${sanitizeParamName(f)}`);
+        if (aggs.length === 0)
+            throw new Error('Aggregate requires at least one aggregator field');
+        const query = `SELECT ${aggs.join(', ')} FROM ${this.tableName}${this.nolock}${whereSql ? ` WHERE ${whereSql}` : ''}`;
         const rows = await this.doExec(query, params);
-        return rows[0] ?? {};
+        const row = rows[0] || {};
+        const result = {};
+        if (args._count) {
+            const allCount = Number(row.cnt_all ?? row._count ?? 0);
+            result._count = { _all: allCount };
+            if (typeof args._count === 'object') {
+                for (const f of selectedAggregateFields(args._count)) {
+                    if (f === '_all')
+                        continue;
+                    const k = `cnt_${sanitizeParamName(f)}`;
+                    result._count[f] = row[k] !== undefined ? Number(row[k]) : allCount;
+                }
+            }
+        }
+        if (args._sum) {
+            result._sum = {};
+            for (const f of selectedAggregateFields(args._sum)) {
+                const k = `sum_${sanitizeParamName(f)}`;
+                result._sum[f] = row[k] !== null && row[k] !== undefined ? Number(row[k]) : null;
+            }
+        }
+        if (args._avg) {
+            result._avg = {};
+            for (const f of selectedAggregateFields(args._avg)) {
+                const k = `avg_${sanitizeParamName(f)}`;
+                result._avg[f] = row[k] !== null && row[k] !== undefined ? Number(row[k]) : null;
+            }
+        }
+        if (args._min) {
+            result._min = {};
+            for (const f of selectedAggregateFields(args._min)) {
+                const k = `min_${sanitizeParamName(f)}`;
+                result._min[f] = row[k] ?? null;
+            }
+        }
+        if (args._max) {
+            result._max = {};
+            for (const f of selectedAggregateFields(args._max)) {
+                const k = `max_${sanitizeParamName(f)}`;
+                result._max[f] = row[k] ?? null;
+            }
+        }
+        return result;
     }
     async groupBy(args) {
         const params = {};
         const whereSql = (0, sql_1.parseWhere)(this.modelName, args?.where, params, this.dialect);
-        const byCols = (args.by || []).map((b) => (0, sql_1.quote)(b, this.dialect)).join(', ');
-        const query = `SELECT ${byCols}, COUNT(*) AS _count FROM ${this.tableName}${whereSql ? ` WHERE ${whereSql}` : ''} GROUP BY ${byCols}`;
+        const byFields = normalizeByFields(args?.by);
+        if (byFields.length === 0)
+            throw new Error("groupBy requires 'by' fields");
+        const byCols = byFields.map((b) => (0, sql_1.quote)(b, this.dialect)).join(', ');
+        const aggs = ['COUNT(*) AS _count'];
+        if (args?._sum)
+            for (const f of selectedAggregateFields(args._sum))
+                aggs.push(`SUM(${(0, sql_1.quote)(f, this.dialect)}) AS _sum_${f}`);
+        if (args?._avg)
+            for (const f of selectedAggregateFields(args._avg))
+                aggs.push(`AVG(${(0, sql_1.quote)(f, this.dialect)}) AS _avg_${f}`);
+        if (args?._min)
+            for (const f of selectedAggregateFields(args._min))
+                aggs.push(`MIN(${(0, sql_1.quote)(f, this.dialect)}) AS _min_${f}`);
+        if (args?._max)
+            for (const f of selectedAggregateFields(args._max))
+                aggs.push(`MAX(${(0, sql_1.quote)(f, this.dialect)}) AS _max_${f}`);
+        let query = `SELECT ${byCols}, ${aggs.join(', ')} FROM ${this.tableName}${whereSql ? ` WHERE ${whereSql}` : ''} GROUP BY ${byCols}`;
+        const orderSql = (0, sql_1.buildOrderBy)(args?.orderBy, this.dialect);
+        const hasSkip = args?.skip !== undefined && args?.skip !== null;
+        const hasTake = args?.take !== undefined && args?.take !== null;
+        if (orderSql)
+            query += ` ${orderSql}`;
+        else if (hasSkip || hasTake)
+            query += ` ORDER BY ${byCols}`;
+        if (hasSkip || hasTake) {
+            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}`;
+            }
+            else {
+                query += ` OFFSET ${skip} ROWS`;
+                if (hasTake)
+                    query += ` FETCH NEXT ${take} ROWS ONLY`;
+            }
+        }
         return this.doExec(query, params);
     }
+    /**
+     * Runs similarity search in NBase and hydrates the matching rows from the
+     * relational table, keeping the `{ ...row, distance }` shape the other
+     * engines return.
+     */
+    async searchViaNBase(nbase, args, metric, take) {
+        const { client, config } = nbase;
+        const idField = config.idField ?? 'an5Id';
+        const modelField = config.modelField ?? 'an5Model';
+        const results = await client.search(args.vector, {
+            k: take,
+            // NBase implements cosine and euclidean; a dot-product request falls back
+            // to cosine, which still orders the results sensibly.
+            distanceMetric: metric === 'euclidean' ? 'euclidean' : 'cosine',
+            includeMetadata: true,
+            ...(config.method ? { method: config.method } : {}),
+        });
+        // Map each hit back to its row id. Ids are written as `Model:id`, and the
+        // metadata key is honoured for projects that index vectors themselves.
+        const ids = [];
+        const distances = new Map();
+        for (const hit of results) {
+            const fromMetadata = hit.metadata?.[idField];
+            const rawId = fromMetadata !== undefined && fromMetadata !== null
+                ? String(fromMetadata)
+                : (0, nbase_1.parseVectorId)(hit.id).id;
+            if (!rawId)
+                continue;
+            const model = hit.metadata?.[modelField] ?? (0, nbase_1.parseVectorId)(hit.id).model;
+            ids.push(model === this.modelName ? rawId : `${model}:${rawId}`);
+            distances.set(ids[ids.length - 1], hit.dist);
+        }
+        if (ids.length === 0)
+            return [];
+        const pk = this.primaryKeyColumn();
+        const inList = ids.map((_, i) => `@nbase_id_${i}`).join(', ');
+        const idParams = {};
+        ids.forEach((id, i) => { idParams[`nbase_id_${i}`] = id; });
+        idParams.take = take;
+        const selectColumns = this.modelFields().map((f) => (0, sql_1.quote)(f, this.dialect)).join(', ');
+        const columns = selectColumns ? `${selectColumns}, ${(0, sql_1.quote)(pk, this.dialect)} AS __an5_nbase_key` : `${(0, sql_1.quote)(pk, this.dialect)} AS __an5_nbase_key`;
+        const query = `SELECT ${columns} FROM ${this.tableName} WHERE ${(0, sql_1.quote)(pk, this.dialect)} IN (${inList})`;
+        const rows = await this.adapter.exec(query, idParams);
+        const byKey = new Map();
+        for (const row of rows ?? []) {
+            byKey.set(String(row.__an5_nbase_key), row);
+        }
+        const hydrated = [];
+        for (const id of ids) {
+            const row = byKey.get(id);
+            if (!row)
+                continue;
+            const { __an5_nbase_key, ...rest } = row;
+            hydrated.push({ ...rest, distance: distances.get(id) ?? 0 });
+            if (hydrated.length >= take)
+                break;
+        }
+        return hydrated;
+    }
+    /**
+     * Vector search for an adapter configured with only an NBase connection
+     * string. The hit id and metadata are the result, since there is no
+     * relational row to hydrate.
+     */
+    async searchViaNBaseOnly(nbase, args, metric, take) {
+        const { client, config } = nbase;
+        const idField = config.idField ?? 'an5Id';
+        const results = await client.search(args.vector, {
+            k: take,
+            distanceMetric: metric === 'euclidean' ? 'euclidean' : 'cosine',
+            includeMetadata: true,
+            ...(config.method ? { method: config.method } : {}),
+        });
+        return results.map((hit) => {
+            const metadata = { ...(hit.metadata ?? {}) };
+            if (metadata[idField] === undefined) {
+                const parsed = (0, nbase_1.parseVectorId)(hit.id);
+                if (parsed.id)
+                    metadata[idField] = parsed.id;
+                if (parsed.model)
+                    metadata[config.modelField ?? 'an5Model'] = parsed.model;
+            }
+            return { id: hit.id, ...metadata, distance: hit.dist };
+        });
+    }
+    /** The primary key column registered for this model, falling back to `id`. */
+    primaryKeyColumn() {
+        const fields = this.modelFields();
+        const marked = fields.find((f) => f === 'id');
+        return marked ?? fields[0] ?? 'id';
+    }
+    /** Scalar column names known for this model from the generated metadata. */
+    modelFields() {
+        const fields = (0, metadata_1.getFieldsForModel)(this.modelName);
+        if (fields && typeof fields === 'object' && !Array.isArray(fields)) {
+            return Object.keys(fields);
+        }
+        return [];
+    }
+    /**
+     * Pushes a table's embedding column into NBase so it can be searched there.
+     *
+     * Each vector keeps the row id in its metadata, which is what lets
+     * `vectorSearch` return real rows instead of bare vector ids.
+     */
+    async indexVectorsInNBase(args = {}) {
+        const nbase = this.adapter.nbaseClient?.() ?? null;
+        if (!nbase) {
+            throw new Error('No NBase instance configured. Use a nbase:// connection string, e.g. createAn5Adapter({ connectionString: "nbase://localhost:1307" }).');
+        }
+        if (this.adapter.nbaseOnly) {
+            throw new Error('indexVectorsInNBase reads the vectors from a table, but this adapter was created with an nbase:// connection string and has no database. ' +
+                'Create the adapter with your database connection string to index, or add the vectors with the NBase client directly.');
+        }
+        const vectorField = args.vectorField || 'embedding';
+        const batchSize = args.batchSize ?? 200;
+        const pk = this.primaryKeyColumn();
+        const rows = await this.findMany({ ...(args.where ? { where: args.where } : {}), ...(args.take ? { take: args.take } : {}) });
+        let indexed = 0;
+        for (let i = 0; i < rows.length; i += batchSize) {
+            const batch = rows.slice(i, i + batchSize);
+            const vectors = batch
+                .map((row) => {
+                const raw = row[vectorField];
+                if (raw === undefined || raw === null)
+                    return null;
+                let vector;
+                try {
+                    vector = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                }
+                catch {
+                    return null;
+                }
+                if (!Array.isArray(vector) || vector.length === 0)
+                    return null;
+                return {
+                    id: (0, nbase_1.buildVectorId)(this.modelName, String(row[pk])),
+                    vector,
+                    metadata: {
+                        [nbase.config.idField ?? 'an5Id']: String(row[pk]),
+                        [nbase.config.modelField ?? 'an5Model']: this.modelName,
+                    },
+                };
+            })
+                .filter((v) => v !== null);
+            if (vectors.length === 0)
+                continue;
+            const result = await nbase.client.addVectors(vectors);
+            indexed += result.count;
+        }
+        return { indexed };
+    }
     async vectorSearch(args) {
-        const rows = await this.findMany({ where: args.where });
         const vectorField = args.vectorField || 'embedding';
-        const metric = args.distanceMetric || 'cosine';
+        const METRICS = ['cosine', 'euclidean', 'dot'];
+        const ELEMENT_TYPES = ['float32', 'float16', 'uint8'];
+        const metric = METRICS.includes(args.distanceMetric) ? args.distanceMetric : 'cosine';
+        const elementType = ELEMENT_TYPES.includes(args.vectorElementType) ? args.vectorElementType : 'float32';
+        const take = args.take ?? 10;
+        const dim = Array.isArray(args.vector) ? args.vector.length : 0;
+        const vectorJson = JSON.stringify(args.vector);
+        const col = (0, sql_1.quote)(vectorField, this.dialect);
+        const params = { query_vector: vectorJson };
+        // 0. NBase, when the project configured one: the vectors live in the vector
+        //    database, so the search never loads the table into memory.
+        const nbase = this.adapter.nbaseClient?.() ?? null;
+        if (nbase) {
+            try {
+                // With an NBase-only connection string there is no table to read rows
+                // from, so the hits are returned as the vector metadata itself.
+                if (this.adapter.nbaseOnly) {
+                    return (await this.searchViaNBaseOnly(nbase, args, metric, take));
+                }
+                return await this.searchViaNBase(nbase, args, metric, take);
+            }
+            catch (err) {
+                if (!(err instanceof nbase_1.NBaseError))
+                    throw err;
+                // A NBase outage must not take vector search down with it; fall through
+                // to the database instead of failing the query.
+                console.warn(`[an5] NBase vector search unavailable (${err.message}); falling back to ${this.dialect}.`);
+            }
+        }
+        // 1. Try native dialect execution
+        if (this.dialect === 'postgres') {
+            const op = metric === 'cosine' ? '<=>' : metric === 'dot' ? '<#>' : '<->';
+            const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect, '', this.whereContext());
+            const query = `SELECT *, (${col} ${op} @query_vector::vector) AS distance FROM ${this.tableName}${whereSql ? ` WHERE ${whereSql}` : ''} ORDER BY distance ASC LIMIT ${take}`;
+            try {
+                return await this.doExec(query, params);
+            }
+            catch (err) {
+                const msg = String(err?.message || '').toLowerCase();
+                if (!msg.includes('vector') && !msg.includes('operator does not exist'))
+                    throw err;
+            }
+        }
+        else if (this.dialect === 'mssql') {
+            const distFn = metric === 'cosine' ? 'cosine' : metric === 'euclidean' ? 'euclidean' : 'dot';
+            const whereSql = (0, sql_1.parseWhere)(this.modelName, args.where, params, this.dialect, '', this.whereContext());
+            const query = `SELECT TOP (${take}) *, VECTOR_DISTANCE('${distFn}', ${col}, CAST(@query_vector AS VECTOR(${dim}, ${elementType}))) AS distance FROM ${this.tableName}${this.nolock}${whereSql ? ` WHERE ${whereSql}` : ''} ORDER BY distance ASC`;
+            try {
+                return await this.doExec(query, params);
+            }
+            catch (err) {
+                const msg = String(err?.message || '').toLowerCase();
+                const isUnsupported = msg.includes('vector_distance') ||
+                    msg.includes('syntax near') ||
+                    msg.includes('not a recognized built-in function') ||
+                    msg.includes('not a defined system type') ||
+                    msg.includes('type "vector"') ||
+                    msg.includes('pgvector') ||
+                    msg.includes('operator does not exist') ||
+                    msg.includes('limit of 1998') ||
+                    err?.number === 195 ||
+                    err?.number === 102 ||
+                    err?.number === 319 ||
+                    err?.originalError?.number === 319;
+                if (!isUnsupported)
+                    throw err;
+            }
+        }
+        // 2. Fallback: in-memory similarity computation when native vector support is unavailable
+        const rows = await this.findMany({ where: args.where });
         const scored = [];
         for (const row of rows) {
             const raw = row[vectorField];
@@ -455,30 +1327,88 @@ class AdapterTableClient {
                 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);
-        return scored.slice(0, args.take ?? 10).map(s => ({ ...s.row, distance: s.dist }));
+        return scored.slice(0, take).map(s => ({ ...s.row, distance: s.dist }));
     }
 }
 exports.AdapterTableClient = AdapterTableClient;
-// ─── Factory ──────────────────────────────────────────────────────────────────────
 function createAn5Adapter(config) {
     if (isSheetsConfig(config))
         return new googlesheets_1.An5SheetsAdapter(config);
-    if (config.connectionString.trim().startsWith('googlesheets://')) {
+    if (config.connectionString && config.connectionString.trim().startsWith('googlesheets://')) {
         return new googlesheets_1.An5SheetsAdapter((0, parseConnectionString_1.parseSheetsConnectionString)(config.connectionString));
     }
     return new An5Adapter(config);
 }
 exports.createAdapter = createAn5Adapter;
+function createBrowserSqliteAdapter(config) {
+    const { SqliteBrowserEngine } = require('./sqlite/browserEngine.js');
+    return new An5Adapter({ engine: new SqliteBrowserEngine(config) });
+}
+function normalizeAffectedCount(result) {
+    if (typeof result === 'number')
+        return result;
+    if (!result)
+        return 0;
+    if (Array.isArray(result.rowsAffected))
+        return Number(result.rowsAffected[0] ?? 0);
+    if (typeof result.rowsAffected === 'number')
+        return result.rowsAffected;
+    if (typeof result.count === 'number')
+        return result.count;
+    return 0;
+}
+function executorFromAdapter(adapterLike) {
+    if (!adapterLike)
+        return adapterLike;
+    if (typeof adapterLike === 'function' && adapterLike.executeRaw) {
+        return adapterLike;
+    }
+    return Object.assign(async (queryText, params) => {
+        return typeof adapterLike === 'function'
+            ? adapterLike(queryText, params)
+            : adapterLike.exec(queryText, params);
+    }, {
+        executeRaw: async (queryText, params) => {
+            if (typeof adapterLike._executeRaw === 'function') {
+                return adapterLike._executeRaw(queryText, params);
+            }
+            if (typeof adapterLike.executeRaw === 'function') {
+                return adapterLike.executeRaw(queryText, params);
+            }
+            const res = typeof adapterLike === 'function'
+                ? await adapterLike(queryText, params)
+                : await adapterLike.exec(queryText, params);
+            return normalizeAffectedCount(res);
+        },
+        transaction: adapterLike.$transaction
+            ? async (fn, options) => {
+                return adapterLike.$transaction(async (tx) => fn(executorFromAdapter(tx)), options);
+            }
+            : undefined,
+        beginTransaction: adapterLike.$begin
+            ? async () => {
+                const tx = await adapterLike.$begin();
+                return {
+                    executor: executorFromAdapter(tx),
+                    commit: () => tx.$commit(),
+                    rollback: () => tx.$rollback(),
+                };
+            }
+            : undefined,
+    });
+}