@rudderjs/database 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleiman Shahbari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/db.d.ts

@@ -0,0 +1,78 @@
+import type { QueryListener, Row } from '@rudderjs/contracts';
+import { Expression } from './expression.js';
+/**
+ * A scoped facade over one NAMED connection — what `DB.connection('reporting')`
+ * returns. Same raw-SQL surface as `DB`, resolved against that connection's
+ * adapter (opened lazily on first use). One divergence from the root facade:
+ * `listen()` is async here, because attaching the listener may first open the
+ * connection.
+ */
+export interface DBConnection {
+    select(sql: string, bindings?: readonly unknown[]): Promise<Row[]>;
+    insert(sql: string, bindings?: readonly unknown[]): Promise<number>;
+    update(sql: string, bindings?: readonly unknown[]): Promise<number>;
+    delete(sql: string, bindings?: readonly unknown[]): Promise<number>;
+    statement(sql: string, bindings?: readonly unknown[]): Promise<number>;
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    listen(listener: QueryListener): Promise<void>;
+}
+/**
+ * The DB facade. Raw-SQL escape hatch over the active ORM adapter, mirroring
+ * Laravel's `DB` facade. All methods take positional `bindings` (`?` / `$n`
+ * placeholders) — values are never string-interpolated into `sql`.
+ */
+export declare const DB: {
+    /** Run a raw `SELECT` and resolve to the matched rows. */
+    readonly select: (sql: string, bindings?: readonly unknown[]) => Promise<Row[]>;
+    /** Run a raw `INSERT`. Resolves to the number of rows affected. */
+    readonly insert: (sql: string, bindings?: readonly unknown[]) => Promise<number>;
+    /** Run a raw `UPDATE`. Resolves to the number of rows affected. */
+    readonly update: (sql: string, bindings?: readonly unknown[]) => Promise<number>;
+    /** Run a raw `DELETE`. Resolves to the number of rows affected. */
+    readonly delete: (sql: string, bindings?: readonly unknown[]) => Promise<number>;
+    /** Run an arbitrary raw statement (DDL, etc.). Resolves to rows affected. */
+    readonly statement: (sql: string, bindings?: readonly unknown[]) => Promise<number>;
+    /**
+     * Run `fn` inside a database transaction, mirroring Laravel's `DB::transaction`.
+     * Every `Model.*` and `DB.*` call issued inside `fn` runs on the *same* open
+     * transaction — the runner (pushed in by `@rudderjs/orm`) threads the
+     * transaction-scoped adapter through `AsyncLocalStorage`, so no connection is
+     * passed around. Commits when `fn` resolves; rolls back and re-throws if it
+     * rejects. Nested `DB.transaction()` / `Model.transaction()` calls map to
+     * savepoints where the driver supports them.
+     *
+     * @throws if no transaction runner is registered (no database provider loaded),
+     *   or if the active adapter doesn't implement `transaction()`.
+     */
+    readonly transaction: <T>(fn: () => Promise<T>) => Promise<T>;
+    /**
+     * Register a query listener, mirroring Laravel's `DB::listen`. The listener
+     * fires once per executed query with `{ sql, bindings, duration }` (duration
+     * in ms) — use it for app-level query logging or slow-query alerting.
+     * Delegates to the active adapter's `onQuery()` hook; listener errors are
+     * swallowed by the adapter and never break the query.
+     *
+     * Synchronous, unlike the exec methods — registration happens immediately
+     * against the adapter resolved at call time.
+     *
+     * @throws if no adapter is registered, or the active adapter doesn't
+     *   implement query listening (`onQuery`).
+     */
+    readonly listen: (listener: QueryListener) => void;
+    /** Wrap a literal SQL fragment so the query layer splices it verbatim. */
+    readonly raw: (value: string | number) => Expression;
+    /**
+     * A facade scoped to a NAMED connection from `config/database.ts`'s
+     * `connections` map, mirroring Laravel's `DB::connection('name')`. The
+     * connection opens lazily on the first executed call (cheap to call this
+     * method itself — it resolves nothing). Inside a `transaction(fn,
+     * { connection: name })` callback, calls on the matching scoped facade join
+     * that open transaction.
+     *
+     * @example
+     * const rows = await DB.connection('reporting').select('select * from stats')
+     * await DB.connection('reporting').transaction(async () => { ... })
+     */
+    readonly connection: (name: string) => DBConnection;
+};
+//# sourceMappingURL=db.d.ts.map

package/dist/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAc,aAAa,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAA;AAOzE,OAAO,EAAE,UAAU,EAAO,MAAM,iBAAiB,CAAA;AAoCjD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;IAClE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACtE,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAChD,MAAM,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/C;AAED;;;;GAIG;AAIH,eAAO,MAAM,EAAE;IACb,0DAA0D;2BACxC,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,GAAG,EAAE,CAAC;IAI5E,mEAAmE;2BACjD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAI7E,mEAAmE;2BACjD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAI7E,mEAAmE;2BACjD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAI7E,6EAA6E;8BACxD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAIhF;;;;;;;;;;;OAWG;2BACe,CAAC,MAAM,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC;IAItD;;;;;;;;;;;;OAYG;gCACc,aAAa,KAAG,IAAI;IAIrC,0EAA0E;0BAC/D,MAAM,GAAG,MAAM,KAAG,UAAU;IAIvC;;;;;;;;;;;OAWG;gCACc,MAAM,KAAG,YAAY;CA0B9B,CAAA"}

package/dist/db.js

@@ -0,0 +1,142 @@
+// ─── DB facade ─────────────────────────────────────────────
+//
+// Laravel-style raw-SQL entry point: `DB.select / insert / update / delete /
+// statement / raw / listen`. It resolves the active ORM adapter (via the
+// registry bridge) and maps onto the adapter's raw-exec seam:
+//   - reads  (select)                       → adapter.selectRaw  → Row[]
+//   - writes (insert/update/delete/statement) → adapter.affectingStatement → number
+//   - query listening (listen)              → adapter.onQuery
+//
+// One adapter instance is shared with the Models — no second connection. If the
+// active adapter doesn't implement the seam (older/partial adapters), each method
+// throws a clear error naming that adapter.
+import { resolveAdapter, resolveTransactionRunner, resolveConnectionResolver, resolveNamedTransactionRunner, } from './registry-bridge.js';
+import { raw } from './expression.js';
+function adapterName(adapter) {
+    return adapter.constructor?.name ?? 'the active adapter';
+}
+function requireSelectRaw(adapter) {
+    if (typeof adapter.selectRaw !== 'function') {
+        throw new Error(`[RudderJS DB] ${adapterName(adapter)} does not implement selectRaw() — ` +
+            'this adapter cannot run raw DB.select() queries.');
+    }
+    return adapter.selectRaw.bind(adapter);
+}
+function requireAffecting(adapter) {
+    if (typeof adapter.affectingStatement !== 'function') {
+        throw new Error(`[RudderJS DB] ${adapterName(adapter)} does not implement affectingStatement() — ` +
+            'this adapter cannot run raw DB.insert()/update()/delete()/statement() calls.');
+    }
+    return adapter.affectingStatement.bind(adapter);
+}
+function requireOnQuery(adapter) {
+    if (typeof adapter.onQuery !== 'function') {
+        throw new Error(`[RudderJS DB] ${adapterName(adapter)} does not implement onQuery() — ` +
+            'this adapter does not support query listening, so DB.listen() has nothing to hook into.');
+    }
+    return adapter.onQuery.bind(adapter);
+}
+/**
+ * The DB facade. Raw-SQL escape hatch over the active ORM adapter, mirroring
+ * Laravel's `DB` facade. All methods take positional `bindings` (`?` / `$n`
+ * placeholders) — values are never string-interpolated into `sql`.
+ */
+// `async` (not bare `return`) so a missing-adapter / missing-seam guard throws
+// as a rejected promise rather than synchronously — the facade always presents a
+// Promise-returning contract, so callers can `.catch()` / `await assert.rejects`.
+export const DB = {
+    /** Run a raw `SELECT` and resolve to the matched rows. */
+    async select(sql, bindings = []) {
+        return requireSelectRaw(resolveAdapter())(sql, bindings);
+    },
+    /** Run a raw `INSERT`. Resolves to the number of rows affected. */
+    async insert(sql, bindings = []) {
+        return requireAffecting(resolveAdapter())(sql, bindings);
+    },
+    /** Run a raw `UPDATE`. Resolves to the number of rows affected. */
+    async update(sql, bindings = []) {
+        return requireAffecting(resolveAdapter())(sql, bindings);
+    },
+    /** Run a raw `DELETE`. Resolves to the number of rows affected. */
+    async delete(sql, bindings = []) {
+        return requireAffecting(resolveAdapter())(sql, bindings);
+    },
+    /** Run an arbitrary raw statement (DDL, etc.). Resolves to rows affected. */
+    async statement(sql, bindings = []) {
+        return requireAffecting(resolveAdapter())(sql, bindings);
+    },
+    /**
+     * Run `fn` inside a database transaction, mirroring Laravel's `DB::transaction`.
+     * Every `Model.*` and `DB.*` call issued inside `fn` runs on the *same* open
+     * transaction — the runner (pushed in by `@rudderjs/orm`) threads the
+     * transaction-scoped adapter through `AsyncLocalStorage`, so no connection is
+     * passed around. Commits when `fn` resolves; rolls back and re-throws if it
+     * rejects. Nested `DB.transaction()` / `Model.transaction()` calls map to
+     * savepoints where the driver supports them.
+     *
+     * @throws if no transaction runner is registered (no database provider loaded),
+     *   or if the active adapter doesn't implement `transaction()`.
+     */
+    async transaction(fn) {
+        return resolveTransactionRunner()(fn);
+    },
+    /**
+     * Register a query listener, mirroring Laravel's `DB::listen`. The listener
+     * fires once per executed query with `{ sql, bindings, duration }` (duration
+     * in ms) — use it for app-level query logging or slow-query alerting.
+     * Delegates to the active adapter's `onQuery()` hook; listener errors are
+     * swallowed by the adapter and never break the query.
+     *
+     * Synchronous, unlike the exec methods — registration happens immediately
+     * against the adapter resolved at call time.
+     *
+     * @throws if no adapter is registered, or the active adapter doesn't
+     *   implement query listening (`onQuery`).
+     */
+    listen(listener) {
+        requireOnQuery(resolveAdapter())(listener);
+    },
+    /** Wrap a literal SQL fragment so the query layer splices it verbatim. */
+    raw(value) {
+        return raw(value);
+    },
+    /**
+     * A facade scoped to a NAMED connection from `config/database.ts`'s
+     * `connections` map, mirroring Laravel's `DB::connection('name')`. The
+     * connection opens lazily on the first executed call (cheap to call this
+     * method itself — it resolves nothing). Inside a `transaction(fn,
+     * { connection: name })` callback, calls on the matching scoped facade join
+     * that open transaction.
+     *
+     * @example
+     * const rows = await DB.connection('reporting').select('select * from stats')
+     * await DB.connection('reporting').transaction(async () => { ... })
+     */
+    connection(name) {
+        const adapterFor = async () => resolveConnectionResolver()(name);
+        return {
+            async select(sql, bindings = []) {
+                return requireSelectRaw(await adapterFor())(sql, bindings);
+            },
+            async insert(sql, bindings = []) {
+                return requireAffecting(await adapterFor())(sql, bindings);
+            },
+            async update(sql, bindings = []) {
+                return requireAffecting(await adapterFor())(sql, bindings);
+            },
+            async delete(sql, bindings = []) {
+                return requireAffecting(await adapterFor())(sql, bindings);
+            },
+            async statement(sql, bindings = []) {
+                return requireAffecting(await adapterFor())(sql, bindings);
+            },
+            async transaction(fn) {
+                return resolveNamedTransactionRunner()(name, fn);
+            },
+            async listen(listener) {
+                requireOnQuery(await adapterFor())(listener);
+            },
+        };
+    },
+};
+//# sourceMappingURL=db.js.map

package/dist/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"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"}

package/dist/execution.d.ts

@@ -0,0 +1,2 @@
+export type { Row, Executor, Transaction, Connection } from '@rudderjs/contracts';
+//# sourceMappingURL=execution.d.ts.map

package/dist/execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"AAYA,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/execution.js

@@ -0,0 +1,13 @@
+// ─── DB execution contracts (re-export) ────────────────────
+//
+// The canonical execution types — `Row`, `Executor`, `Transaction`,
+// `Connection` — are owned by `@rudderjs/contracts` (the zero-dependency
+// foundation, beside `OrmAdapter`). `@rudderjs/database` is their conceptual
+// home — the DB *facade* — so we re-export them here as the public surface.
+//
+// Keeping the definitions in contracts avoids a build cycle: `@rudderjs/database`
+// depends on `@rudderjs/contracts` (for `OrmAdapter`), so contracts cannot depend
+// back on database. Every adapter already imports from contracts, so there's a
+// single import point and no flag-day when the data layer is later extracted.
+export {};
+//# sourceMappingURL=execution.js.map

package/dist/execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,oEAAoE;AACpE,yEAAyE;AACzE,6EAA6E;AAC7E,4EAA4E;AAC5E,EAAE;AACF,kFAAkF;AAClF,kFAAkF;AAClF,+EAA+E;AAC/E,8EAA8E"}

package/dist/expression.d.ts

@@ -0,0 +1,2 @@
+export { Expression, raw } from '@rudderjs/contracts';
+//# sourceMappingURL=expression.d.ts.map

package/dist/expression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.d.ts","sourceRoot":"","sources":["../src/expression.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/expression.js

@@ -0,0 +1,6 @@
+// Raw SQL expression wrapper — moved to @rudderjs/contracts so the query
+// builder's raw methods stay client-safe (@rudderjs/database is node-only).
+// Re-exported here to keep `DB.raw()` and `import { raw } from
+// '@rudderjs/database'` working.
+export { Expression, raw } from '@rudderjs/contracts';
+//# sourceMappingURL=expression.js.map

package/dist/expression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.js","sourceRoot":"","sources":["../src/expression.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,4EAA4E;AAC5E,+DAA+D;AAC/D,iCAAiC;AACjC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { DB } from './db.js';
+export type { DBConnection } from './db.js';
+export { Expression, raw } from './expression.js';
+export { registerAdapterResolver, resolveAdapter, registerTransactionRunner, resolveTransactionRunner, registerConnectionResolver, resolveConnectionResolver, registerNamedTransactionRunner, resolveNamedTransactionRunner, __resetAdapterResolver, } from './registry-bridge.js';
+export type { TransactionRunner, ConnectionResolver, NamedTransactionRunner } from './registry-bridge.js';
+export type { Row, Executor, Transaction, Connection } from './execution.js';
+export type { QueryEvent, QueryListener } from '@rudderjs/contracts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AAC5B,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,yBAAyB,EACzB,8BAA8B,EAC9B,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AACzG,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC5E,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// @rudderjs/database — the SQL data-layer foundation.
+//
+// PR1 establishes the package boundary + the public `DB` facade contract. The
+// query-builder breadth, connection manager, and native-engine internals land in
+// later PRs (see docs/plans/2026-06-01-database-package-extraction-PR1.md).
+export { DB } from './db.js';
+export { Expression, raw } from './expression.js';
+export { registerAdapterResolver, resolveAdapter, registerTransactionRunner, resolveTransactionRunner, registerConnectionResolver, resolveConnectionResolver, registerNamedTransactionRunner, resolveNamedTransactionRunner, __resetAdapterResolver, } from './registry-bridge.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,8EAA8E;AAC9E,iFAAiF;AACjF,4EAA4E;AAE5E,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AAE5B,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,yBAAyB,EACzB,8BAA8B,EAC9B,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,sBAAsB,CAAA"}

package/dist/registry-bridge.d.ts

@@ -0,0 +1,69 @@
+import type { OrmAdapter } from '@rudderjs/contracts';
+/**
+ * Runs `fn` inside a database transaction, returning its result. Pushed in by
+ * `@rudderjs/orm` (its `transaction()` free function) so `DB.transaction()` reuses
+ * the ORM's `AsyncLocalStorage` transaction scoping — every `Model.*` AND `DB.*`
+ * call inside `fn` joins the *same* open transaction (one connection, not two).
+ * `@rudderjs/database` can't import `@rudderjs/orm`, so the runner is injected the
+ * same way the adapter resolver is.
+ */
+export type TransactionRunner = <T>(fn: () => Promise<T>) => Promise<T>;
+/**
+ * Resolves the adapter for a NAMED connection (`DB.connection('reporting')`),
+ * opening it lazily on first use. Pushed in by `@rudderjs/orm`'s `db-bridge`
+ * (it closes over the ConnectionManager + the transaction-scope lookup, so a
+ * `DB.connection(name).select()` inside a `transaction(fn, { connection:
+ * name })` callback joins that open transaction). Async because the first
+ * access may open the connection (driver import + connect).
+ */
+export type ConnectionResolver = (name: string) => Promise<OrmAdapter>;
+/** Runs `fn` inside a transaction on a NAMED connection — the named
+ *  counterpart of {@link TransactionRunner}, same injection rationale. */
+export type NamedTransactionRunner = <T>(name: string, fn: () => Promise<T>) => Promise<T>;
+/**
+ * Register the function that resolves the active ORM adapter. Called once by
+ * `@rudderjs/orm`'s `db-bridge` module (imported for side effect from each
+ * adapter provider). Idempotent — the last registration wins, which matches a
+ * dev HMR re-boot re-installing the same accessor.
+ */
+export declare function registerAdapterResolver(fn: () => OrmAdapter): void;
+/**
+ * Resolve the active ORM adapter. Throws a clear error when no resolver has been
+ * registered — i.e. `@rudderjs/orm` (and a database provider) wasn't loaded, so
+ * there is no adapter for the DB facade to run against.
+ */
+export declare function resolveAdapter(): OrmAdapter;
+/**
+ * Register the function that runs work inside a transaction. Called by
+ * `@rudderjs/orm`'s `db-bridge` module alongside {@link registerAdapterResolver},
+ * passing the ORM's `transaction()` free function (which owns the ALS scoping).
+ * Idempotent — last registration wins (a dev HMR re-boot re-installs the same fn).
+ */
+export declare function registerTransactionRunner(fn: TransactionRunner): void;
+/**
+ * Resolve the active transaction runner. Throws a clear error when none has been
+ * registered — i.e. `@rudderjs/orm` (and a database provider) wasn't loaded.
+ */
+export declare function resolveTransactionRunner(): TransactionRunner;
+/**
+ * Register the function that resolves a named connection's adapter. Called by
+ * `@rudderjs/orm`'s `db-bridge` module alongside {@link registerAdapterResolver}.
+ * Idempotent — last registration wins (dev HMR re-boot re-installs it).
+ */
+export declare function registerConnectionResolver(fn: ConnectionResolver): void;
+/**
+ * Resolve the named-connection resolver. Throws a clear error when none has
+ * been registered — i.e. `@rudderjs/orm` (and a database provider) wasn't
+ * loaded, or the installed `@rudderjs/orm` predates named-connection support.
+ */
+export declare function resolveConnectionResolver(): ConnectionResolver;
+/**
+ * Register the function that runs work inside a transaction on a named
+ * connection. Called by `@rudderjs/orm`'s `db-bridge` module. Idempotent —
+ * last registration wins.
+ */
+export declare function registerNamedTransactionRunner(fn: NamedTransactionRunner): void;
+/** Resolve the named transaction runner. Throws a clear error when none has
+ *  been registered. */
+export declare function resolveNamedTransactionRunner(): NamedTransactionRunner;
+//# sourceMappingURL=registry-bridge.d.ts.map

package/dist/registry-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-bridge.d.ts","sourceRoot":"","sources":["../src/registry-bridge.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAEvE;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;AAEtE;0EAC0E;AAC1E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAO1F;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,UAAU,GAAG,IAAI,CAElE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAS3C;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,iBAAiB,GAAG,IAAI,CAErE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,iBAAiB,CAS5D;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,EAAE,kBAAkB,GAAG,IAAI,CAEvE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,kBAAkB,CAU9D;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,sBAAsB,GAAG,IAAI,CAE/E;AAED;uBACuB;AACvB,wBAAgB,6BAA6B,IAAI,sBAAsB,CAStE"}

package/dist/registry-bridge.js

@@ -0,0 +1,107 @@
+// ─── Adapter-resolver bridge (orm → database) ──────────────
+//
+// `@rudderjs/database` must NOT import `@rudderjs/orm` (the dependency direction
+// is orm → database). But the DB facade needs the *same* active adapter the
+// Models use — opening a second connection would violate the one-connection
+// rule. So `@rudderjs/orm` PUSHES its `ModelRegistry.getAdapter` accessor into
+// this module via {@link registerAdapterResolver}; the facade pulls it via
+// {@link resolveAdapter}.
+//
+// Resolving through the accessor (not a cached adapter) means `DB.*` inside a
+// `Model.transaction()` callback transparently joins the open transaction —
+// `ModelRegistry.getAdapter()` already returns the transaction-scoped adapter.
+let resolver = null;
+let txRunner = null;
+let connectionResolver = null;
+let namedTxRunner = null;
+/**
+ * Register the function that resolves the active ORM adapter. Called once by
+ * `@rudderjs/orm`'s `db-bridge` module (imported for side effect from each
+ * adapter provider). Idempotent — the last registration wins, which matches a
+ * dev HMR re-boot re-installing the same accessor.
+ */
+export function registerAdapterResolver(fn) {
+    resolver = fn;
+}
+/**
+ * Resolve the active ORM adapter. Throws a clear error when no resolver has been
+ * registered — i.e. `@rudderjs/orm` (and a database provider) wasn't loaded, so
+ * there is no adapter for the DB facade to run against.
+ */
+export function resolveAdapter() {
+    if (!resolver) {
+        throw new Error('[RudderJS DB] No ORM adapter is available. The DB facade resolves the ' +
+            'active adapter from @rudderjs/orm — make sure a database provider is ' +
+            'registered (and @rudderjs/orm installed) before calling DB.*');
+    }
+    return resolver();
+}
+/**
+ * Register the function that runs work inside a transaction. Called by
+ * `@rudderjs/orm`'s `db-bridge` module alongside {@link registerAdapterResolver},
+ * passing the ORM's `transaction()` free function (which owns the ALS scoping).
+ * Idempotent — last registration wins (a dev HMR re-boot re-installs the same fn).
+ */
+export function registerTransactionRunner(fn) {
+    txRunner = fn;
+}
+/**
+ * Resolve the active transaction runner. Throws a clear error when none has been
+ * registered — i.e. `@rudderjs/orm` (and a database provider) wasn't loaded.
+ */
+export function resolveTransactionRunner() {
+    if (!txRunner) {
+        throw new Error('[RudderJS DB] No transaction runner is available. DB.transaction() runs ' +
+            'through @rudderjs/orm — make sure a database provider is registered (and ' +
+            '@rudderjs/orm installed) before calling DB.transaction().');
+    }
+    return txRunner;
+}
+/**
+ * Register the function that resolves a named connection's adapter. Called by
+ * `@rudderjs/orm`'s `db-bridge` module alongside {@link registerAdapterResolver}.
+ * Idempotent — last registration wins (dev HMR re-boot re-installs it).
+ */
+export function registerConnectionResolver(fn) {
+    connectionResolver = fn;
+}
+/**
+ * Resolve the named-connection resolver. Throws a clear error when none has
+ * been registered — i.e. `@rudderjs/orm` (and a database provider) wasn't
+ * loaded, or the installed `@rudderjs/orm` predates named-connection support.
+ */
+export function resolveConnectionResolver() {
+    if (!connectionResolver) {
+        throw new Error('[RudderJS DB] No connection resolver is available. DB.connection(name) ' +
+            'resolves named connections through @rudderjs/orm — make sure a database ' +
+            'provider is registered (and @rudderjs/orm installed) before calling ' +
+            'DB.connection().');
+    }
+    return connectionResolver;
+}
+/**
+ * Register the function that runs work inside a transaction on a named
+ * connection. Called by `@rudderjs/orm`'s `db-bridge` module. Idempotent —
+ * last registration wins.
+ */
+export function registerNamedTransactionRunner(fn) {
+    namedTxRunner = fn;
+}
+/** Resolve the named transaction runner. Throws a clear error when none has
+ *  been registered. */
+export function resolveNamedTransactionRunner() {
+    if (!namedTxRunner) {
+        throw new Error('[RudderJS DB] No named transaction runner is available. ' +
+            'DB.connection(name).transaction() runs through @rudderjs/orm — make sure ' +
+            'a database provider is registered (and @rudderjs/orm installed) first.');
+    }
+    return namedTxRunner;
+}
+/** @internal — test-only reset of the registered resolvers + transaction runners. */
+export function __resetAdapterResolver() {
+    resolver = null;
+    txRunner = null;
+    connectionResolver = null;
+    namedTxRunner = null;
+}
+//# sourceMappingURL=registry-bridge.js.map

package/dist/registry-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-bridge.js","sourceRoot":"","sources":["../src/registry-bridge.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,iFAAiF;AACjF,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,2EAA2E;AAC3E,0BAA0B;AAC1B,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,+EAA+E;AA4B/E,IAAI,QAAQ,GAA8B,IAAI,CAAA;AAC9C,IAAI,QAAQ,GAA6B,IAAI,CAAA;AAC7C,IAAI,kBAAkB,GAA8B,IAAI,CAAA;AACxD,IAAI,aAAa,GAAkC,IAAI,CAAA;AAEvD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,EAAoB;IAC1D,QAAQ,GAAG,EAAE,CAAA;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,wEAAwE;YACtE,uEAAuE;YACvE,8DAA8D,CACjE,CAAA;IACH,CAAC;IACD,OAAO,QAAQ,EAAE,CAAA;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,EAAqB;IAC7D,QAAQ,GAAG,EAAE,CAAA;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB;IACtC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,0EAA0E;YACxE,2EAA2E;YAC3E,2DAA2D,CAC9D,CAAA;IACH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,EAAsB;IAC/D,kBAAkB,GAAG,EAAE,CAAA;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB;IACvC,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,yEAAyE;YACvE,0EAA0E;YAC1E,sEAAsE;YACtE,kBAAkB,CACrB,CAAA;IACH,CAAC;IACD,OAAO,kBAAkB,CAAA;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,8BAA8B,CAAC,EAA0B;IACvE,aAAa,GAAG,EAAE,CAAA;AACpB,CAAC;AAED;uBACuB;AACvB,MAAM,UAAU,6BAA6B;IAC3C,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,0DAA0D;YACxD,2EAA2E;YAC3E,wEAAwE,CAC3E,CAAA;IACH,CAAC;IACD,OAAO,aAAa,CAAA;AACtB,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,sBAAsB;IACpC,QAAQ,GAAG,IAAI,CAAA;IACf,QAAQ,GAAG,IAAI,CAAA;IACf,kBAAkB,GAAG,IAAI,CAAA;IACzB,aAAa,GAAG,IAAI,CAAA;AACtB,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@rudderjs/database",
+  "version": "1.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rudderjs/rudder",
+    "directory": "packages/database"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "boost"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@rudderjs/contracts": "^1.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "tsx": "^4.0.0"
+  },
+  "author": "Suleiman Shahbari",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "clean": "rm -rf dist",
+    "test": "tsc -p tsconfig.test.json && node --test \"dist-test/**/*.test.js\""
+  }
+}