sqlstack 3.3.0 → 3.5.0

package/dist/cjs/index.js

@@ -14,12 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SourceScanResolver = exports.MANIFEST_DIALECT_EXT = exports.ManifestResolver = exports.FsResolver = exports.sqliteFamily = exports.FamilyRuntime = exports.resolveExecution = exports.activeSqlStack = exports.SqlStack = exports.SqlStackDB = exports.run = exports.SqlFragment = exports.sql = void 0;
+exports.SourceScanResolver = exports.getActiveResolver = exports.MANIFEST_DIALECT_EXT = exports.ManifestResolver = exports.FsResolver = exports.sqliteFamily = exports.FamilyRuntime = exports.resolveExecution = exports.activeSqlStack = exports.SqlStack = exports.SqlStackDB = exports.run = exports.SqlFragment = exports.sql = void 0;
 // SQL Template Strings
 var sql_1 = require("./sql");
 Object.defineProperty(exports, "sql", { enumerable: true, get: function () { return sql_1.sql; } });
 Object.defineProperty(exports, "SqlFragment", { enumerable: true, get: function () { return sql_1.SqlFragment; } });
-// Query body execution — `return run<T>()` inside a @Query method body
+// Query execution — `return run()` inside a @Query method body, or
+// `run(db, sql`...`)` anywhere with a database chosen at call time
 var run_1 = require("./run");
 Object.defineProperty(exports, "run", { enumerable: true, get: function () { return run_1.run; } });
 // Decorators
@@ -56,6 +57,7 @@ var resolver_1 = require("./core/resolver");
 Object.defineProperty(exports, "FsResolver", { enumerable: true, get: function () { return resolver_1.FsResolver; } });
 Object.defineProperty(exports, "ManifestResolver", { enumerable: true, get: function () { return resolver_1.ManifestResolver; } });
 Object.defineProperty(exports, "MANIFEST_DIALECT_EXT", { enumerable: true, get: function () { return resolver_1.MANIFEST_DIALECT_EXT; } });
+Object.defineProperty(exports, "getActiveResolver", { enumerable: true, get: function () { return resolver_1.getActiveResolver; } });
 var sourceScanResolver_1 = require("./core/sourceScanResolver");
 Object.defineProperty(exports, "SourceScanResolver", { enumerable: true, get: function () { return sourceScanResolver_1.SourceScanResolver; } });
 // Legacy exports (kept for backward compatibility)

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uBAAuB;AACvB,6BAAyC;AAAhC,0FAAA,GAAG,OAAA;AAAE,kGAAA,WAAW,OAAA;AAEzB,uEAAuE;AACvE,6BAA4B;AAAnB,0FAAA,GAAG,OAAA;AAEZ,aAAa;AACb,2DAAyC;AACzC,qDAAmC;AACnC,wDAAsC;AACtC,2DAAyC;AACzC,8DAA4C;AAC5C,yDAAuC;AACvC,oDAAkC;AAElC,eAAe;AACf,iDAA+B;AAE/B,WAAW;AACX,6CAA2B;AAE3B,wBAAwB;AACxB,gDAA8B;AAC9B,mDAAiC;AAEjC,aAAa;AACb,8CAA4B;AAI5B,uCAAkD;AAAzC,sGAAA,UAAU,OAAA;AAEnB,gFAAgF;AAChF,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AAEjB,qCAA6D;AAApD,yGAAA,cAAc,OAAA;AAAE,2GAAA,gBAAgB,OAAA;AAEzC,sCAAsC;AACtC,mCAAyC;AAAhC,uGAAA,aAAa,OAAA;AAQtB,wDAAuD;AAA9C,4GAAA,YAAY,OAAA;AAKrB,4CAAqF;AAA5E,sGAAA,UAAU,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AAC3D,gEAA+D;AAAtD,wHAAA,kBAAkB,OAAA;AAE3B,mDAAmD;AACnD,sDAAoC","sourcesContent":["// SQL Template Strings\nexport { sql, SqlFragment } from './sql';\n\n// Query body execution — `return run<T>()` inside a @Query method body\nexport { run } from './run';\n\n// Decorators\nexport * from './decorators/queryBinder';\nexport * from './decorators/query';\nexport * from './decorators/defaults';\nexport * from './decorators/resultShape';\nexport * from './decorators/validateResult';\nexport * from './decorators/transform';\nexport * from './decorators/page';\n\n// Transactions\nexport * from './transactions';\n\n// Adapters\nexport * from './adapters';\n\n// Errors and Validation\nexport * from './core/errors';\nexport * from './core/validator';\n\n// DTO Helper\nexport * from './utils/dto';\n\n// Database Registry and Types\nexport type { Dialect, WriteResult, PostgresWriteResult, QueryResult, Database } from './registry';\nexport { SqlStackDB, IStackDB } from './registry';\n\n// Environment-owned runtime (v3): per-root SqlStack + active-context resolution\nexport { SqlStack } from './stack';\nexport type { DatabaseEntry, DatabaseRegistration, SqlStackConfig } from './stack';\nexport { activeSqlStack, resolveExecution } from './runtime';\n\n// Dynamic database families (spec 17)\nexport { FamilyRuntime } from './family';\nexport type {\n  DatabaseFamilyProvider,\n  FamilyConfig,\n  FamilyMemberEntry,\n  DatabaseLease,\n  DatabaseInspection,\n} from './family';\nexport { sqliteFamily } from './families/sqliteFamily';\nexport type { SqliteFamilyOptions } from './families/sqliteFamily';\n\n// SQL Resolvers (v2): pluggable SQL source resolution\nexport type { SqlResolver, SqlManifest, SqlResolutionRequest, ManifestResolverOptions } from './core/resolver';\nexport { FsResolver, ManifestResolver, MANIFEST_DIALECT_EXT } from './core/resolver';\nexport { SourceScanResolver } from './core/sourceScanResolver';\n\n// Legacy exports (kept for backward compatibility)\nexport * from './binders/sqlBinder';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uBAAuB;AACvB,6BAAyC;AAAhC,0FAAA,GAAG,OAAA;AAAE,kGAAA,WAAW,OAAA;AAEzB,mEAAmE;AACnE,mEAAmE;AACnE,6BAA4B;AAAnB,0FAAA,GAAG,OAAA;AAGZ,aAAa;AACb,2DAAyC;AACzC,qDAAmC;AACnC,wDAAsC;AACtC,2DAAyC;AACzC,8DAA4C;AAC5C,yDAAuC;AACvC,oDAAkC;AAElC,eAAe;AACf,iDAA+B;AAE/B,WAAW;AACX,6CAA2B;AAE3B,wBAAwB;AACxB,gDAA8B;AAC9B,mDAAiC;AAEjC,aAAa;AACb,8CAA4B;AAI5B,uCAAkD;AAAzC,sGAAA,UAAU,OAAA;AAEnB,gFAAgF;AAChF,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AAEjB,qCAA6D;AAApD,yGAAA,cAAc,OAAA;AAAE,2GAAA,gBAAgB,OAAA;AAEzC,sCAAsC;AACtC,mCAAyC;AAAhC,uGAAA,aAAa,OAAA;AAQtB,wDAAuD;AAA9C,4GAAA,YAAY,OAAA;AAKrB,4CAAwG;AAA/F,sGAAA,UAAU,OAAA;AAAE,4GAAA,gBAAgB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AAAE,6GAAA,iBAAiB,OAAA;AAC9E,gEAA+D;AAAtD,wHAAA,kBAAkB,OAAA;AAE3B,mDAAmD;AACnD,sDAAoC","sourcesContent":["// SQL Template Strings\nexport { sql, SqlFragment } from './sql';\n\n// Query execution — `return run()` inside a @Query method body, or\n// `run(db, sql`...`)` anywhere with a database chosen at call time\nexport { run } from './run';\nexport type { RunDatabase, RejectCompiledSql } from './run';\n\n// Decorators\nexport * from './decorators/queryBinder';\nexport * from './decorators/query';\nexport * from './decorators/defaults';\nexport * from './decorators/resultShape';\nexport * from './decorators/validateResult';\nexport * from './decorators/transform';\nexport * from './decorators/page';\n\n// Transactions\nexport * from './transactions';\n\n// Adapters\nexport * from './adapters';\n\n// Errors and Validation\nexport * from './core/errors';\nexport * from './core/validator';\n\n// DTO Helper\nexport * from './utils/dto';\n\n// Database Registry and Types\nexport type { Dialect, WriteResult, PostgresWriteResult, QueryResult, Database } from './registry';\nexport { SqlStackDB, IStackDB } from './registry';\n\n// Environment-owned runtime (v3): per-root SqlStack + active-context resolution\nexport { SqlStack } from './stack';\nexport type { DatabaseEntry, DatabaseRegistration, SqlStackConfig } from './stack';\nexport { activeSqlStack, resolveExecution } from './runtime';\n\n// Dynamic database families (spec 17)\nexport { FamilyRuntime } from './family';\nexport type {\n  DatabaseFamilyProvider,\n  FamilyConfig,\n  FamilyMemberEntry,\n  DatabaseLease,\n  DatabaseInspection,\n} from './family';\nexport { sqliteFamily } from './families/sqliteFamily';\nexport type { SqliteFamilyOptions } from './families/sqliteFamily';\n\n// SQL Resolvers (v2): pluggable SQL source resolution\nexport type { SqlResolver, SqlManifest, SqlResolutionRequest, ManifestResolverOptions } from './core/resolver';\nexport { FsResolver, ManifestResolver, MANIFEST_DIALECT_EXT, getActiveResolver } from './core/resolver';\nexport { SourceScanResolver } from './core/sourceScanResolver';\n\n// Legacy exports (kept for backward compatibility)\nexport * from './binders/sqlBinder';\n"]}

package/dist/cjs/run.d.ts

@@ -1,29 +1,163 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { SqlStackError } from './core/errors';
+import type { Dialect } from './registry';
+import { SqlFragment } from './sql';
+import type { SqlResolver } from './core/resolver';
+import type { ActiveTransaction } from './transactions';
+/**
+ * Anything run(db, ...) can execute against: sqlstack's own `Database`
+ * (from createSqliteDb/createPgDb/createMysqlDb), or any application handle
+ * exposing `query(sql, params)`. `dialect` selects placeholder style and
+ * defaults to `'sqlite'` when absent. run never opens databases by path.
+ */
+export interface RunDatabase {
+    readonly dialect?: Dialect;
+    query(sql: string, params: unknown[]): Promise<unknown>;
+}
+/**
+ * Type-level guard for the params form of run: rejects the
+ * `{ sql, params }` object returned by `fragment.toSQL()`. Pass the sql``
+ * fragment itself instead, so run owns dialect binding and error handling.
+ */
+export type RejectCompiledSql<P> = P extends {
+    readonly sql: string;
+    readonly params: readonly unknown[];
+} ? never : unknown;
+/**
+ * What a run(...) call made inside a @Query body asks of the wrapper's
+ * pipeline. `default` is the zero-argument run().
+ */
+export type RunInvocation = {
+    readonly kind: 'default';
+} | {
+    readonly kind: 'fragment';
+    readonly db?: RunDatabase | string;
+    readonly fragment: SqlFragment;
+} | {
+    readonly kind: 'params';
+    readonly db: RunDatabase | string;
+    readonly params: object;
+};
 /**
  * Per-invocation context established by the @Query wrapper before the method
  * body executes. `execute` performs the full query pipeline (resolve SQL,
  * bind, execute, shape/transform/validate); `ran` records that the body
  * invoked run(), so the wrapper returns the body's result verbatim instead
- * of falling through to the legacy pipeline.
+ * of falling through to the legacy pipeline. `invocations` marks a wrapper
+ * that understands the argument-taking run forms (an older duplicated copy
+ * of the decorator would silently ignore them).
  */
 export type RunContext = {
-    execute: () => Promise<unknown>;
+    execute: (invocation?: RunInvocation) => Promise<unknown>;
     ran: boolean;
+    invocations?: true;
 };
 export declare const runStorage: AsyncLocalStorage<RunContext>;
 /**
  * Execute the current @Query method's SQL and return the finished result.
- * Call it as the body of a @Query-decorated method in place of the legacy
- * placeholder throw:
+ * Call it as the body of a @Query-decorated method:
  *
  *   @Query()
  *   async getUsers(active: boolean): Promise<User[]> {
- *     return run<User[]>();
+ *     return run();
  *   }
  *
  * Takes no arguments — the method's own arguments, database, SQL source,
  * transaction, shaping, transform, and validation all come from the
- * decorator context. The generic is a typing convenience only.
+ * decorator context. T is inferred from the method's declared return type.
+ *
+ * @throws {DatabaseError} When the driver rejects the statement (original
+ * error in `.cause`).
+ * @throws {SqlStackError} When called outside a @Query method, or for
+ * shape/validation failures (ExactlyOneRowError, NoRowsError, ValidationError, ...).
  */
 export declare function run<T = any>(): Promise<T>;
+/**
+ * Inside a @Query method: execute this inline sql`` fragment instead of the
+ * method's SQL file. The database comes from the method/class/registry
+ * context (`@Query({ db })`, `@QueryBinder({ db })`, the default), the
+ * active transaction on it is joined, and the method's shape/transform/
+ * validation decorators apply. The method's arguments are not auto-bound —
+ * the fragment's `${}` values are the parameters.
+ *
+ *   @Single @Query()
+ *   async byEmail(email: string): Promise<User | null> {
+ *     return run(sql`SELECT * FROM users WHERE email = ${email}`);
+ *   }
+ *
+ * @throws {DatabaseError} When the fragment cannot be compiled (macro input
+ * errors), the database cannot be resolved, or the driver rejects the
+ * statement. The original error is in `.cause`.
+ * @throws {SqlStackError} When called outside a @Query method (use
+ * `run(db, query)` there), or for shape/validation failures.
+ */
+export declare function run<T = unknown>(query: SqlFragment): Promise<T>;
+/**
+ * Execute an sql`` fragment against an explicit database: a handle
+ * (anything with `query(sql, params)`) or the name of a database registered
+ * with the active SqlStack / legacy registry. Usable anywhere.
+ *
+ * Binds for the database's dialect (`$1..` for Postgres, `?` otherwise;
+ * default sqlite). Joins an active transaction opened on the same database
+ * (same registered handle, or same name). Outside a @Query method the raw
+ * result is returned (rows array, or `{ rowsAffected }` for writes); inside
+ * one, the method's shape/transform/validation decorators apply.
+ *
+ *   const rows = await run<Row[]>(accountsDb, sql`SELECT * FROM t WHERE id = ${id}`);
+ *
+ * @throws {DatabaseError} When the fragment cannot be compiled, a named
+ * database cannot be resolved, or the driver rejects the statement. The
+ * original error is in `.cause`, and its string `code` is copied to `.code`.
+ * @throws {SqlStackError} For invalid arguments, or shape/validation failures.
+ */
+export declare function run<T = unknown>(db: RunDatabase | string, query: SqlFragment): Promise<T>;
+/**
+ * Inside a @Query method: run the method's own SQL (its .sql file or inline
+ * `@Query({ sql })`) against `db`, binding `params` (an object for `:named`
+ * placeholders, an array for `:arg1..`). The method's raw arguments are NOT
+ * auto-bound in this form — `params` is the whole binding input. @Defaults,
+ * @Page, shaping, transform, and validation still apply.
+ *
+ *   @Single @Query()
+ *   async byEmail(db: Database, p: { email: string }): Promise<User | null> {
+ *     return run(db, p);
+ *   }
+ *
+ * @throws {DatabaseError} When binding fails, a named database cannot be
+ * resolved, or the driver rejects the statement. The original error is in
+ * `.cause`.
+ * @throws {SqlStackError} When called outside a @Query method, when passed
+ * `.toSQL()` output, or for shape/validation failures.
+ */
+export declare function run<T = unknown, P extends object = object>(db: RunDatabase | string, params: P & RejectCompiledSql<P>): Promise<T>;
+/** @internal A database chosen for one run, plus the transaction it joins. */
+export type RunTarget = {
+    readonly db: RunDatabase;
+    readonly tx: ActiveTransaction | undefined;
+    /** SQL resolver of the environment, when the target was resolved by name. */
+    readonly resolver: SqlResolver | undefined;
+    readonly byName: boolean;
+};
+/**
+ * @internal Resolve run's database argument. A name goes through the active
+ * SqlStack (or legacy registry) and joins that entry's transaction. A handle
+ * is used as-is — no registry lookup, so it works without any SqlStack — and
+ * joins an active transaction only if one is open on that same handle.
+ */
+export declare function resolveRunTarget(db: RunDatabase | string): Promise<RunTarget>;
+/** @internal Run one bound statement on the target (inside its transaction, if any). */
+export declare function executeOnTarget(target: RunTarget, boundSql: string, params: unknown[]): Promise<unknown>;
+/**
+ * @internal Normalize a failure from run's argument-taking forms: errors that
+ * are already SqlStackError (DatabaseError, shape/validation errors) pass
+ * through; anything else becomes DatabaseError with the original in `.cause`.
+ */
+export declare function toRunError(err: unknown, sqlText: string): SqlStackError;
+/** @internal Raw template text of a fragment, for error messages. */
+export declare function fragmentText(fragment: SqlFragment): string;
+/** @internal Compile a fragment for the dialect, wrapping macro errors. */
+export declare function compileForRun(fragment: SqlFragment, dialect: Dialect): {
+    sql: string;
+    params: unknown[];
+};
 //# sourceMappingURL=run.d.ts.map

package/dist/cjs/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAUF,eAAO,MAAM,UAAU,EAA0B,iBAAiB,CAAC,UAAU,CAAC,CAAC;AAE/E;;;;;;;;;;;;;GAaG;AACH,wBAAsB,GAAG,CAAC,CAAC,GAAG,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,CAS/C"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"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"}

package/dist/cjs/run.js

@@ -2,8 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runStorage = void 0;
 exports.run = run;
+exports.resolveRunTarget = resolveRunTarget;
+exports.executeOnTarget = executeOnTarget;
+exports.toRunError = toRunError;
+exports.fragmentText = fragmentText;
+exports.compileForRun = compileForRun;
 const node_async_hooks_1 = require("node:async_hooks");
 const errors_1 = require("./core/errors");
+const sql_1 = require("./sql");
+const runtime_1 = require("./runtime");
+const transactions_1 = require("./transactions");
 // Anchored on globalThis via Symbol.for so duplicated module instances
 // (npm link, dual ESM/CJS loads) share one channel between the decorator
 // and the run() the application imports.
@@ -13,26 +21,128 @@ if (!anchor[RUN_CHANNEL]) {
     anchor[RUN_CHANNEL] = new node_async_hooks_1.AsyncLocalStorage();
 }
 exports.runStorage = anchor[RUN_CHANNEL];
-/**
- * Execute the current @Query method's SQL and return the finished result.
- * Call it as the body of a @Query-decorated method in place of the legacy
- * placeholder throw:
- *
- *   @Query()
- *   async getUsers(active: boolean): Promise<User[]> {
- *     return run<User[]>();
- *   }
- *
- * Takes no arguments — the method's own arguments, database, SQL source,
- * transaction, shaping, transform, and validation all come from the
- * decorator context. The generic is a typing convenience only.
- */
-async function run() {
+async function run(...args) {
+    const invocation = parseRunArgs(args);
     const ctx = exports.runStorage.getStore();
     if (!ctx) {
-        throw new errors_1.SqlStackError('run() called outside a @Query method. It may only be invoked from the body of a @Query-decorated method.');
+        if (invocation.kind === 'fragment' && invocation.db !== undefined) {
+            return executeFragment(invocation.db, invocation.fragment);
+        }
+        if (invocation.kind === 'default') {
+            throw new errors_1.SqlStackError('run() called outside a @Query method. It may only be invoked from the body of a @Query-decorated method.');
+        }
+        if (invocation.kind === 'fragment') {
+            throw new errors_1.SqlStackError('run(query) called outside a @Query method has no database. Pass one explicitly: run(db, query).');
+        }
+        throw new errors_1.SqlStackError('run(db, params) called outside a @Query method has no SQL source. ' +
+            'Pass an sql`` fragment instead: run(db, sql`...`).');
+    }
+    if (invocation.kind !== 'default' && !ctx.invocations) {
+        throw new errors_1.SqlStackError('run(...) with arguments reached a @Query wrapper from an older sqlstack copy that cannot honour them. ' +
+            'Make sure a single sqlstack version is installed.');
     }
     ctx.ran = true;
-    return ctx.execute();
+    return invocation.kind === 'default' ? ctx.execute() : ctx.execute(invocation);
+}
+function parseRunArgs(args) {
+    if (args.length === 0)
+        return { kind: 'default' };
+    if (args.length === 1) {
+        const [query] = args;
+        if ((0, sql_1.isSqlFragment)(query))
+            return { kind: 'fragment', fragment: query };
+        throw new errors_1.SqlStackError(typeof query === 'string'
+            ? 'run(query) does not accept SQL strings. Build the statement with the sql`` tag: run(sql`...`).'
+            : 'run(query) requires an sql`` fragment.');
+    }
+    if (args.length === 2) {
+        const [db, second] = args;
+        assertRunDatabase(db);
+        if ((0, sql_1.isSqlFragment)(second))
+            return { kind: 'fragment', db, fragment: second };
+        if (typeof second === 'string') {
+            throw new errors_1.SqlStackError('run(db, query) does not accept SQL strings. Build the statement with the sql`` tag: run(db, sql`...`).');
+        }
+        if (isCompiledSql(second)) {
+            throw new errors_1.SqlStackError('run(db, ...) received the { sql, params } output of .toSQL(). Pass the sql`` fragment itself so run can ' +
+                'bind it for the target dialect: run(db, sql`...`).');
+        }
+        if (typeof second === 'object' && second !== null)
+            return { kind: 'params', db, params: second };
+        throw new errors_1.SqlStackError('run(db, x) requires an sql`` fragment or a params object/array as its second argument.');
+    }
+    throw new errors_1.SqlStackError(`run() accepts at most 2 arguments, got ${args.length}.`);
+}
+function assertRunDatabase(db) {
+    if (typeof db === 'string' && db.length > 0)
+        return;
+    if (typeof db === 'object' && db !== null && typeof db.query === 'function')
+        return;
+    throw new errors_1.SqlStackError('run(db, ...) requires a database handle with query(sql, params) or a registered database name as its first argument.');
+}
+function isCompiledSql(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    const rec = value;
+    return keys.length === 2 && typeof rec.sql === 'string' && Array.isArray(rec.params);
+}
+/**
+ * @internal Resolve run's database argument. A name goes through the active
+ * SqlStack (or legacy registry) and joins that entry's transaction. A handle
+ * is used as-is — no registry lookup, so it works without any SqlStack — and
+ * joins an active transaction only if one is open on that same handle.
+ */
+async function resolveRunTarget(db) {
+    if (typeof db === 'string') {
+        const { entry, resolver } = await (0, runtime_1.resolveExecution)(db);
+        return { db: entry.db, tx: (0, transactions_1.getActiveTransaction)(entry), resolver, byName: true };
+    }
+    return { db, tx: (0, transactions_1.getActiveTransactionForDatabase)(db), resolver: undefined, byName: false };
+}
+/** @internal Run one bound statement on the target (inside its transaction, if any). */
+async function executeOnTarget(target, boundSql, params) {
+    try {
+        return target.tx ? await target.tx.query(boundSql, params) : await target.db.query(boundSql, params);
+    }
+    catch (dbError) {
+        throw toDatabaseError(dbError, boundSql);
+    }
+}
+/**
+ * @internal Normalize a failure from run's argument-taking forms: errors that
+ * are already SqlStackError (DatabaseError, shape/validation errors) pass
+ * through; anything else becomes DatabaseError with the original in `.cause`.
+ */
+function toRunError(err, sqlText) {
+    return err instanceof errors_1.SqlStackError ? err : toDatabaseError(err, sqlText);
+}
+function toDatabaseError(err, sqlText) {
+    const message = err?.message;
+    return new errors_1.DatabaseError(typeof message === 'string' && message ? message : String(err), sqlText, err instanceof Error ? err : undefined);
+}
+/** @internal Raw template text of a fragment, for error messages. */
+function fragmentText(fragment) {
+    return fragment.strings.join('?');
+}
+/** @internal Compile a fragment for the dialect, wrapping macro errors. */
+function compileForRun(fragment, dialect) {
+    try {
+        return (0, sql_1.compileFragment)(fragment, dialect);
+    }
+    catch (err) {
+        throw toRunError(err, fragmentText(fragment));
+    }
+}
+async function executeFragment(db, fragment) {
+    let target;
+    try {
+        target = await resolveRunTarget(db);
+    }
+    catch (err) {
+        throw toRunError(err, fragmentText(fragment));
+    }
+    const { sql: boundSql, params } = compileForRun(fragment, target.db.dialect ?? 'sqlite');
+    return executeOnTarget(target, boundSql, params);
 }
 //# sourceMappingURL=run.js.map

package/dist/cjs/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":";;;AAuCA,kBASC;AAhDD,uDAAqD;AACrD,0CAA8C;AAc9C,uEAAuE;AACvE,yEAAyE;AACzE,yCAAyC;AACzC,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAC5D,MAAM,MAAM,GAAG,UAA0C,CAAC;AAC1D,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;IACzB,MAAM,CAAC,WAAW,CAAC,GAAG,IAAI,oCAAiB,EAAc,CAAC;AAC5D,CAAC;AACY,QAAA,UAAU,GAAG,MAAM,CAAC,WAAW,CAAkC,CAAC;AAE/E;;;;;;;;;;;;;GAaG;AACI,KAAK,UAAU,GAAG;IACvB,MAAM,GAAG,GAAG,kBAAU,CAAC,QAAQ,EAAE,CAAC;IAClC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,sBAAa,CACrB,0GAA0G,CAC3G,CAAC;IACJ,CAAC;IACD,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC;IACf,OAAO,GAAG,CAAC,OAAO,EAAgB,CAAC;AACrC,CAAC","sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport { SqlStackError } from './core/errors';\n\n/**\n * Per-invocation context established by the @Query wrapper before the method\n * body executes. `execute` performs the full query pipeline (resolve SQL,\n * bind, execute, shape/transform/validate); `ran` records that the body\n * invoked run(), so the wrapper returns the body's result verbatim instead\n * of falling through to the legacy pipeline.\n */\nexport type RunContext = {\n  execute: () => Promise<unknown>;\n  ran: boolean;\n};\n\n// Anchored on globalThis via Symbol.for so duplicated module instances\n// (npm link, dual ESM/CJS loads) share one channel between the decorator\n// and the run() the application imports.\nconst RUN_CHANNEL = Symbol.for('noego.sqlstack.runContext');\nconst anchor = globalThis as Record<PropertyKey, unknown>;\nif (!anchor[RUN_CHANNEL]) {\n  anchor[RUN_CHANNEL] = new AsyncLocalStorage<RunContext>();\n}\nexport const runStorage = anchor[RUN_CHANNEL] as AsyncLocalStorage<RunContext>;\n\n/**\n * Execute the current @Query method's SQL and return the finished result.\n * Call it as the body of a @Query-decorated method in place of the legacy\n * placeholder throw:\n *\n *   @Query()\n *   async getUsers(active: boolean): Promise<User[]> {\n *     return run<User[]>();\n *   }\n *\n * Takes no arguments — the method's own arguments, database, SQL source,\n * transaction, shaping, transform, and validation all come from the\n * decorator context. The generic is a typing convenience only.\n */\nexport async function run<T = any>(): Promise<T> {\n  const ctx = runStorage.getStore();\n  if (!ctx) {\n    throw new SqlStackError(\n      'run() called outside a @Query method. It may only be invoked from the body of a @Query-decorated method.'\n    );\n  }\n  ctx.ran = true;\n  return ctx.execute() as Promise<T>;\n}\n"]}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"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","sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport { SqlStackError, DatabaseError } from './core/errors';\nimport type { Dialect } from './registry';\nimport { SqlFragment, isSqlFragment, compileFragment } from './sql';\nimport { resolveExecution } from './runtime';\nimport type { SqlResolver } from './core/resolver';\nimport { getActiveTransaction, getActiveTransactionForDatabase } from './transactions';\nimport type { ActiveTransaction } from './transactions';\n\n/**\n * Anything run(db, ...) can execute against: sqlstack's own `Database`\n * (from createSqliteDb/createPgDb/createMysqlDb), or any application handle\n * exposing `query(sql, params)`. `dialect` selects placeholder style and\n * defaults to `'sqlite'` when absent. run never opens databases by path.\n */\nexport interface RunDatabase {\n  readonly dialect?: Dialect;\n  query(sql: string, params: unknown[]): Promise<unknown>;\n}\n\n/**\n * Type-level guard for the params form of run: rejects the\n * `{ sql, params }` object returned by `fragment.toSQL()`. Pass the sql``\n * fragment itself instead, so run owns dialect binding and error handling.\n */\nexport type RejectCompiledSql<P> = P extends { readonly sql: string; readonly params: readonly unknown[] }\n  ? never\n  : unknown;\n\n/**\n * What a run(...) call made inside a @Query body asks of the wrapper's\n * pipeline. `default` is the zero-argument run().\n */\nexport type RunInvocation =\n  | { readonly kind: 'default' }\n  | { readonly kind: 'fragment'; readonly db?: RunDatabase | string; readonly fragment: SqlFragment }\n  | { readonly kind: 'params'; readonly db: RunDatabase | string; readonly params: object };\n\n/**\n * Per-invocation context established by the @Query wrapper before the method\n * body executes. `execute` performs the full query pipeline (resolve SQL,\n * bind, execute, shape/transform/validate); `ran` records that the body\n * invoked run(), so the wrapper returns the body's result verbatim instead\n * of falling through to the legacy pipeline. `invocations` marks a wrapper\n * that understands the argument-taking run forms (an older duplicated copy\n * of the decorator would silently ignore them).\n */\nexport type RunContext = {\n  execute: (invocation?: RunInvocation) => Promise<unknown>;\n  ran: boolean;\n  invocations?: true;\n};\n\n// Anchored on globalThis via Symbol.for so duplicated module instances\n// (npm link, dual ESM/CJS loads) share one channel between the decorator\n// and the run() the application imports.\nconst RUN_CHANNEL = Symbol.for('noego.sqlstack.runContext');\nconst anchor = globalThis as Record<PropertyKey, unknown>;\nif (!anchor[RUN_CHANNEL]) {\n  anchor[RUN_CHANNEL] = new AsyncLocalStorage<RunContext>();\n}\nexport const runStorage = anchor[RUN_CHANNEL] as AsyncLocalStorage<RunContext>;\n\n/**\n * Execute the current @Query method's SQL and return the finished result.\n * Call it as the body of a @Query-decorated method:\n *\n *   @Query()\n *   async getUsers(active: boolean): Promise<User[]> {\n *     return run();\n *   }\n *\n * Takes no arguments — the method's own arguments, database, SQL source,\n * transaction, shaping, transform, and validation all come from the\n * decorator context. T is inferred from the method's declared return type.\n *\n * @throws {DatabaseError} When the driver rejects the statement (original\n * error in `.cause`).\n * @throws {SqlStackError} When called outside a @Query method, or for\n * shape/validation failures (ExactlyOneRowError, NoRowsError, ValidationError, ...).\n */\nexport function run<T = any>(): Promise<T>;\n/**\n * Inside a @Query method: execute this inline sql`` fragment instead of the\n * method's SQL file. The database comes from the method/class/registry\n * context (`@Query({ db })`, `@QueryBinder({ db })`, the default), the\n * active transaction on it is joined, and the method's shape/transform/\n * validation decorators apply. The method's arguments are not auto-bound —\n * the fragment's `${}` values are the parameters.\n *\n *   @Single @Query()\n *   async byEmail(email: string): Promise<User | null> {\n *     return run(sql`SELECT * FROM users WHERE email = ${email}`);\n *   }\n *\n * @throws {DatabaseError} When the fragment cannot be compiled (macro input\n * errors), the database cannot be resolved, or the driver rejects the\n * statement. The original error is in `.cause`.\n * @throws {SqlStackError} When called outside a @Query method (use\n * `run(db, query)` there), or for shape/validation failures.\n */\nexport function run<T = unknown>(query: SqlFragment): Promise<T>;\n/**\n * Execute an sql`` fragment against an explicit database: a handle\n * (anything with `query(sql, params)`) or the name of a database registered\n * with the active SqlStack / legacy registry. Usable anywhere.\n *\n * Binds for the database's dialect (`$1..` for Postgres, `?` otherwise;\n * default sqlite). Joins an active transaction opened on the same database\n * (same registered handle, or same name). Outside a @Query method the raw\n * result is returned (rows array, or `{ rowsAffected }` for writes); inside\n * one, the method's shape/transform/validation decorators apply.\n *\n *   const rows = await run<Row[]>(accountsDb, sql`SELECT * FROM t WHERE id = ${id}`);\n *\n * @throws {DatabaseError} When the fragment cannot be compiled, a named\n * database cannot be resolved, or the driver rejects the statement. The\n * original error is in `.cause`, and its string `code` is copied to `.code`.\n * @throws {SqlStackError} For invalid arguments, or shape/validation failures.\n */\nexport function run<T = unknown>(db: RunDatabase | string, query: SqlFragment): Promise<T>;\n/**\n * Inside a @Query method: run the method's own SQL (its .sql file or inline\n * `@Query({ sql })`) against `db`, binding `params` (an object for `:named`\n * placeholders, an array for `:arg1..`). The method's raw arguments are NOT\n * auto-bound in this form — `params` is the whole binding input. @Defaults,\n * @Page, shaping, transform, and validation still apply.\n *\n *   @Single @Query()\n *   async byEmail(db: Database, p: { email: string }): Promise<User | null> {\n *     return run(db, p);\n *   }\n *\n * @throws {DatabaseError} When binding fails, a named database cannot be\n * resolved, or the driver rejects the statement. The original error is in\n * `.cause`.\n * @throws {SqlStackError} When called outside a @Query method, when passed\n * `.toSQL()` output, or for shape/validation failures.\n */\nexport function run<T = unknown, P extends object = object>(\n  db: RunDatabase | string,\n  params: P & RejectCompiledSql<P>\n): Promise<T>;\nexport async function run(...args: unknown[]): Promise<unknown> {\n  const invocation = parseRunArgs(args);\n  const ctx = runStorage.getStore();\n\n  if (!ctx) {\n    if (invocation.kind === 'fragment' && invocation.db !== undefined) {\n      return executeFragment(invocation.db, invocation.fragment);\n    }\n    if (invocation.kind === 'default') {\n      throw new SqlStackError(\n        'run() called outside a @Query method. It may only be invoked from the body of a @Query-decorated method.'\n      );\n    }\n    if (invocation.kind === 'fragment') {\n      throw new SqlStackError(\n        'run(query) called outside a @Query method has no database. Pass one explicitly: run(db, query).'\n      );\n    }\n    throw new SqlStackError(\n      'run(db, params) called outside a @Query method has no SQL source. ' +\n        'Pass an sql`` fragment instead: run(db, sql`...`).'\n    );\n  }\n\n  if (invocation.kind !== 'default' && !ctx.invocations) {\n    throw new SqlStackError(\n      'run(...) with arguments reached a @Query wrapper from an older sqlstack copy that cannot honour them. ' +\n        'Make sure a single sqlstack version is installed.'\n    );\n  }\n\n  ctx.ran = true;\n  return invocation.kind === 'default' ? ctx.execute() : ctx.execute(invocation);\n}\n\nfunction parseRunArgs(args: unknown[]): RunInvocation {\n  if (args.length === 0) return { kind: 'default' };\n\n  if (args.length === 1) {\n    const [query] = args;\n    if (isSqlFragment(query)) return { kind: 'fragment', fragment: query };\n    throw new SqlStackError(\n      typeof query === 'string'\n        ? 'run(query) does not accept SQL strings. Build the statement with the sql`` tag: run(sql`...`).'\n        : 'run(query) requires an sql`` fragment.'\n    );\n  }\n\n  if (args.length === 2) {\n    const [db, second] = args;\n    assertRunDatabase(db);\n    if (isSqlFragment(second)) return { kind: 'fragment', db, fragment: second };\n    if (typeof second === 'string') {\n      throw new SqlStackError(\n        'run(db, query) does not accept SQL strings. Build the statement with the sql`` tag: run(db, sql`...`).'\n      );\n    }\n    if (isCompiledSql(second)) {\n      throw new SqlStackError(\n        'run(db, ...) received the { sql, params } output of .toSQL(). Pass the sql`` fragment itself so run can ' +\n          'bind it for the target dialect: run(db, sql`...`).'\n      );\n    }\n    if (typeof second === 'object' && second !== null) return { kind: 'params', db, params: second };\n    throw new SqlStackError('run(db, x) requires an sql`` fragment or a params object/array as its second argument.');\n  }\n\n  throw new SqlStackError(`run() accepts at most 2 arguments, got ${args.length}.`);\n}\n\nfunction assertRunDatabase(db: unknown): asserts db is RunDatabase | string {\n  if (typeof db === 'string' && db.length > 0) return;\n  if (typeof db === 'object' && db !== null && typeof (db as { query?: unknown }).query === 'function') return;\n  throw new SqlStackError(\n    'run(db, ...) requires a database handle with query(sql, params) or a registered database name as its first argument.'\n  );\n}\n\nfunction isCompiledSql(value: unknown): boolean {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;\n  const keys = Object.keys(value);\n  const rec = value as { sql?: unknown; params?: unknown };\n  return keys.length === 2 && typeof rec.sql === 'string' && Array.isArray(rec.params);\n}\n\n// ---------------------------------------------------------------------------\n// Shared execution helpers (also used by the @Query wrapper)\n// ---------------------------------------------------------------------------\n\n/** @internal A database chosen for one run, plus the transaction it joins. */\nexport type RunTarget = {\n  readonly db: RunDatabase;\n  readonly tx: ActiveTransaction | undefined;\n  /** SQL resolver of the environment, when the target was resolved by name. */\n  readonly resolver: SqlResolver | undefined;\n  readonly byName: boolean;\n};\n\n/**\n * @internal Resolve run's database argument. A name goes through the active\n * SqlStack (or legacy registry) and joins that entry's transaction. A handle\n * is used as-is — no registry lookup, so it works without any SqlStack — and\n * joins an active transaction only if one is open on that same handle.\n */\nexport async function resolveRunTarget(db: RunDatabase | string): Promise<RunTarget> {\n  if (typeof db === 'string') {\n    const { entry, resolver } = await resolveExecution(db);\n    return { db: entry.db, tx: getActiveTransaction(entry), resolver, byName: true };\n  }\n  return { db, tx: getActiveTransactionForDatabase(db), resolver: undefined, byName: false };\n}\n\n/** @internal Run one bound statement on the target (inside its transaction, if any). */\nexport async function executeOnTarget(target: RunTarget, boundSql: string, params: unknown[]): Promise<unknown> {\n  try {\n    return target.tx ? await target.tx.query(boundSql, params) : await target.db.query(boundSql, params);\n  } catch (dbError) {\n    throw toDatabaseError(dbError, boundSql);\n  }\n}\n\n/**\n * @internal Normalize a failure from run's argument-taking forms: errors that\n * are already SqlStackError (DatabaseError, shape/validation errors) pass\n * through; anything else becomes DatabaseError with the original in `.cause`.\n */\nexport function toRunError(err: unknown, sqlText: string): SqlStackError {\n  return err instanceof SqlStackError ? err : toDatabaseError(err, sqlText);\n}\n\nfunction toDatabaseError(err: unknown, sqlText: string): DatabaseError {\n  const message = (err as { message?: unknown } | undefined)?.message;\n  return new DatabaseError(\n    typeof message === 'string' && message ? message : String(err),\n    sqlText,\n    err instanceof Error ? err : undefined\n  );\n}\n\n/** @internal Raw template text of a fragment, for error messages. */\nexport function fragmentText(fragment: SqlFragment): string {\n  return fragment.strings.join('?');\n}\n\n/** @internal Compile a fragment for the dialect, wrapping macro errors. */\nexport function compileForRun(fragment: SqlFragment, dialect: Dialect): { sql: string; params: unknown[] } {\n  try {\n    return compileFragment(fragment, dialect);\n  } catch (err) {\n    throw toRunError(err, fragmentText(fragment));\n  }\n}\n\nasync function executeFragment(db: RunDatabase | string, fragment: SqlFragment): Promise<unknown> {\n  let target: RunTarget;\n  try {\n    target = await resolveRunTarget(db);\n  } catch (err) {\n    throw toRunError(err, fragmentText(fragment));\n  }\n  const { sql: boundSql, params } = compileForRun(fragment, target.db.dialect ?? 'sqlite');\n  return executeOnTarget(target, boundSql, params);\n}\n"]}

package/dist/cjs/runtime.d.ts

@@ -20,6 +20,14 @@ export type ResolvedExecution = {
  * Resolve the concrete database entry (and SQL resolver) for one execution.
  */
 export declare function resolveExecution(dbName?: string): Promise<ResolvedExecution>;
+/**
+ * @internal The SQL source resolver for one execution WITHOUT resolving a
+ * database — used when the caller supplied a database handle directly
+ * (`run(db, params)`). Same environment rules as resolveExecution: the
+ * active root's SqlStack resolver when an IoC environment is active (and an
+ * error when that environment has no SqlStack), else the legacy global one.
+ */
+export declare function resolveSqlResolver(): Promise<SqlResolver | undefined>;
 /** @internal Resolve a legacy global-registry database as a DatabaseEntry. */
 export declare function legacyEntry(dbName?: string): DatabaseEntry;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/cjs/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAyCnD,6DAA6D;AAC7D,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAkBD;;;;;;GAMG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAyBpE;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,gEAAgE;IAChE,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAUlF;AAgBD,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAQ1D"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAyCnD,6DAA6D;AAC7D,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAkBD;;;;;;GAMG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAyBpE;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,gEAAgE;IAChE,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAUlF;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAG3E;AAgBD,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAQ1D"}

package/dist/cjs/runtime.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.__resetIocDetection = __resetIocDetection;
 exports.activeSqlStack = activeSqlStack;
 exports.resolveExecution = resolveExecution;
+exports.resolveSqlResolver = resolveSqlResolver;
 exports.legacyEntry = legacyEntry;
 const stack_1 = require("./stack");
 const registry_1 = require("./registry");
@@ -111,6 +112,17 @@ async function resolveExecution(dbName) {
         viaStack: false,
     };
 }
+/**
+ * @internal The SQL source resolver for one execution WITHOUT resolving a
+ * database — used when the caller supplied a database handle directly
+ * (`run(db, params)`). Same environment rules as resolveExecution: the
+ * active root's SqlStack resolver when an IoC environment is active (and an
+ * error when that environment has no SqlStack), else the legacy global one.
+ */
+async function resolveSqlResolver() {
+    const stack = await activeSqlStack();
+    return stack ? stack.resolver() : (0, resolver_1.getActiveResolver)();
+}
 // ---------------------------------------------------------------------------
 // Legacy (deprecated) global-registry support
 // ---------------------------------------------------------------------------

package/dist/cjs/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"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","sourcesContent":["import { SqlStack, DatabaseEntry } from './stack';\nimport { SqlStackDB } from './registry';\nimport type { Database } from './registry';\nimport type { SqlResolver } from './core/resolver';\nimport { getActiveResolver } from './core/resolver';\nimport { SqlStackError } from './core/errors';\n\n/**\n * Active-environment resolution for @Query and transactions (spec 16 §17,\n * repo spec 19 §7/§9).\n *\n * Canonical path: the active IoC execution context (owned by @noego/ioc)\n * supplies the current scope; the scope resolves its root's SqlStack\n * Singleton. When an IoC environment is active, the process-global legacy\n * registry is NEVER consulted — legacy state cannot override an active root.\n *\n * Legacy path: with no active IoC environment, execution falls back to the\n * deprecated process-global SqlStackDB registry so existing consumers keep\n * working during migration.\n */\n\ntype IocModule = {\n  ExecutionContext: { current(): any };\n  DependencyNotFoundError?: new (...args: any[]) => Error;\n};\n\ntype ActiveScope = {\n  get(label: any): unknown;\n  isRegistered?(label: any): boolean;\n};\n\n// @noego/ioc is an optional peer: sqlstack remains usable standalone. The\n// import is dynamic so the CJS and ESM builds both work and so a missing\n// peer only disables the IoC path instead of breaking module load.\nlet iocModulePromise: Promise<IocModule | undefined> | undefined;\n\nfunction loadIoc(): Promise<IocModule | undefined> {\n  iocModulePromise ??= import('@noego/ioc').then(\n    (m: any) => (m?.ExecutionContext ? (m as IocModule) : undefined),\n    () => undefined\n  );\n  return iocModulePromise;\n}\n\n/** @internal Test-only: force re-detection of @noego/ioc. */\nexport function __resetIocDetection(): void {\n  iocModulePromise = undefined;\n}\n\nfunction missingActiveSqlStackError(): SqlStackError {\n  return new SqlStackError(\n    'An IoC execution environment is active, but no SqlStack is registered in it. ' +\n      'Register a SqlStack at root composition (see registerSqlStack in \"sqlstack/ioc\").'\n  );\n}\n\nfunction isDirectMissingSqlStackError(ioc: IocModule, err: unknown): boolean {\n  const DependencyNotFoundError = ioc.DependencyNotFoundError;\n  return (\n    typeof DependencyNotFoundError === 'function' &&\n    err instanceof DependencyNotFoundError &&\n    err.message === 'Dependency not found: SqlStack'\n  );\n}\n\n/**\n * The SqlStack for the active IoC execution context, or undefined when no\n * IoC environment is active (or @noego/ioc is not installed).\n *\n * Throws when an environment IS active but has no SqlStack registered —\n * silently falling back to global state under an active root is forbidden.\n */\nexport async function activeSqlStack(): Promise<SqlStack | undefined> {\n  const ioc = await loadIoc();\n  if (!ioc) return undefined;\n  const scope = ioc.ExecutionContext.current() as ActiveScope | undefined;\n  if (!scope) return undefined;\n\n  // Newer IoC peers expose exact-token registration knowledge. Consulting it\n  // before resolution distinguishes an absent SqlStack from errors raised by a\n  // registered SqlStack provider (including DependencyNotFoundError).\n  const registrationKnown = typeof scope.isRegistered === 'function';\n  if (registrationKnown && !scope.isRegistered!(SqlStack)) {\n    throw missingActiveSqlStackError();\n  }\n\n  try {\n    return (await scope.get(SqlStack)) as SqlStack;\n  } catch (err) {\n    // Older optional peers cannot answer isRegistered(). Their direct missing\n    // error is recognized by exported error identity plus the exact SqlStack\n    // label; nested provider errors retain their original identity.\n    if (!registrationKnown && isDirectMissingSqlStackError(ioc, err)) {\n      throw missingActiveSqlStackError();\n    }\n    throw err;\n  }\n}\n\nexport type ResolvedExecution = {\n  entry: DatabaseEntry;\n  resolver: SqlResolver | undefined;\n  /** True when resolved through an active IoC root's SqlStack. */\n  viaStack: boolean;\n};\n\n/**\n * Resolve the concrete database entry (and SQL resolver) for one execution.\n */\nexport async function resolveExecution(dbName?: string): Promise<ResolvedExecution> {\n  const stack = await activeSqlStack();\n  if (stack) {\n    return { entry: await stack.resolveEntry(dbName), resolver: stack.resolver(), viaStack: true };\n  }\n  return {\n    entry: legacyEntry(dbName),\n    resolver: getActiveResolver(),\n    viaStack: false,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Legacy (deprecated) global-registry support\n// ---------------------------------------------------------------------------\n\n// Stable DatabaseEntry identities for the legacy global registry, so the\n// entry-keyed transaction store works identically on both paths. Keyed by\n// name AND database object so re-registration under a name yields a fresh\n// identity (matching the fresh underlying connection).\nconst legacyEntries = new Map<string, { db: Database; entry: DatabaseEntry }>();\n\n// One shared legacy pseudo-stack so legacy entries carry a stack identity for\n// diagnostics. It is intentionally NOT usable as a real stack.\nlet legacyStack: SqlStack | undefined;\n\n/** @internal Resolve a legacy global-registry database as a DatabaseEntry. */\nexport function legacyEntry(dbName?: string): DatabaseEntry {\n  const { name, db } = SqlStackDB.getEntry(dbName);\n  const cached = legacyEntries.get(name);\n  if (cached && cached.db === db) return cached.entry;\n  legacyStack ??= new SqlStack();\n  const entry: DatabaseEntry = { name, db, owned: false, stack: legacyStack };\n  legacyEntries.set(name, { db, entry });\n  return entry;\n}\n"]}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"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","sourcesContent":["import { SqlStack, DatabaseEntry } from './stack';\nimport { SqlStackDB } from './registry';\nimport type { Database } from './registry';\nimport type { SqlResolver } from './core/resolver';\nimport { getActiveResolver } from './core/resolver';\nimport { SqlStackError } from './core/errors';\n\n/**\n * Active-environment resolution for @Query and transactions (spec 16 §17,\n * repo spec 19 §7/§9).\n *\n * Canonical path: the active IoC execution context (owned by @noego/ioc)\n * supplies the current scope; the scope resolves its root's SqlStack\n * Singleton. When an IoC environment is active, the process-global legacy\n * registry is NEVER consulted — legacy state cannot override an active root.\n *\n * Legacy path: with no active IoC environment, execution falls back to the\n * deprecated process-global SqlStackDB registry so existing consumers keep\n * working during migration.\n */\n\ntype IocModule = {\n  ExecutionContext: { current(): any };\n  DependencyNotFoundError?: new (...args: any[]) => Error;\n};\n\ntype ActiveScope = {\n  get(label: any): unknown;\n  isRegistered?(label: any): boolean;\n};\n\n// @noego/ioc is an optional peer: sqlstack remains usable standalone. The\n// import is dynamic so the CJS and ESM builds both work and so a missing\n// peer only disables the IoC path instead of breaking module load.\nlet iocModulePromise: Promise<IocModule | undefined> | undefined;\n\nfunction loadIoc(): Promise<IocModule | undefined> {\n  iocModulePromise ??= import('@noego/ioc').then(\n    (m: any) => (m?.ExecutionContext ? (m as IocModule) : undefined),\n    () => undefined\n  );\n  return iocModulePromise;\n}\n\n/** @internal Test-only: force re-detection of @noego/ioc. */\nexport function __resetIocDetection(): void {\n  iocModulePromise = undefined;\n}\n\nfunction missingActiveSqlStackError(): SqlStackError {\n  return new SqlStackError(\n    'An IoC execution environment is active, but no SqlStack is registered in it. ' +\n      'Register a SqlStack at root composition (see registerSqlStack in \"sqlstack/ioc\").'\n  );\n}\n\nfunction isDirectMissingSqlStackError(ioc: IocModule, err: unknown): boolean {\n  const DependencyNotFoundError = ioc.DependencyNotFoundError;\n  return (\n    typeof DependencyNotFoundError === 'function' &&\n    err instanceof DependencyNotFoundError &&\n    err.message === 'Dependency not found: SqlStack'\n  );\n}\n\n/**\n * The SqlStack for the active IoC execution context, or undefined when no\n * IoC environment is active (or @noego/ioc is not installed).\n *\n * Throws when an environment IS active but has no SqlStack registered —\n * silently falling back to global state under an active root is forbidden.\n */\nexport async function activeSqlStack(): Promise<SqlStack | undefined> {\n  const ioc = await loadIoc();\n  if (!ioc) return undefined;\n  const scope = ioc.ExecutionContext.current() as ActiveScope | undefined;\n  if (!scope) return undefined;\n\n  // Newer IoC peers expose exact-token registration knowledge. Consulting it\n  // before resolution distinguishes an absent SqlStack from errors raised by a\n  // registered SqlStack provider (including DependencyNotFoundError).\n  const registrationKnown = typeof scope.isRegistered === 'function';\n  if (registrationKnown && !scope.isRegistered!(SqlStack)) {\n    throw missingActiveSqlStackError();\n  }\n\n  try {\n    return (await scope.get(SqlStack)) as SqlStack;\n  } catch (err) {\n    // Older optional peers cannot answer isRegistered(). Their direct missing\n    // error is recognized by exported error identity plus the exact SqlStack\n    // label; nested provider errors retain their original identity.\n    if (!registrationKnown && isDirectMissingSqlStackError(ioc, err)) {\n      throw missingActiveSqlStackError();\n    }\n    throw err;\n  }\n}\n\nexport type ResolvedExecution = {\n  entry: DatabaseEntry;\n  resolver: SqlResolver | undefined;\n  /** True when resolved through an active IoC root's SqlStack. */\n  viaStack: boolean;\n};\n\n/**\n * Resolve the concrete database entry (and SQL resolver) for one execution.\n */\nexport async function resolveExecution(dbName?: string): Promise<ResolvedExecution> {\n  const stack = await activeSqlStack();\n  if (stack) {\n    return { entry: await stack.resolveEntry(dbName), resolver: stack.resolver(), viaStack: true };\n  }\n  return {\n    entry: legacyEntry(dbName),\n    resolver: getActiveResolver(),\n    viaStack: false,\n  };\n}\n\n/**\n * @internal The SQL source resolver for one execution WITHOUT resolving a\n * database — used when the caller supplied a database handle directly\n * (`run(db, params)`). Same environment rules as resolveExecution: the\n * active root's SqlStack resolver when an IoC environment is active (and an\n * error when that environment has no SqlStack), else the legacy global one.\n */\nexport async function resolveSqlResolver(): Promise<SqlResolver | undefined> {\n  const stack = await activeSqlStack();\n  return stack ? stack.resolver() : getActiveResolver();\n}\n\n// ---------------------------------------------------------------------------\n// Legacy (deprecated) global-registry support\n// ---------------------------------------------------------------------------\n\n// Stable DatabaseEntry identities for the legacy global registry, so the\n// entry-keyed transaction store works identically on both paths. Keyed by\n// name AND database object so re-registration under a name yields a fresh\n// identity (matching the fresh underlying connection).\nconst legacyEntries = new Map<string, { db: Database; entry: DatabaseEntry }>();\n\n// One shared legacy pseudo-stack so legacy entries carry a stack identity for\n// diagnostics. It is intentionally NOT usable as a real stack.\nlet legacyStack: SqlStack | undefined;\n\n/** @internal Resolve a legacy global-registry database as a DatabaseEntry. */\nexport function legacyEntry(dbName?: string): DatabaseEntry {\n  const { name, db } = SqlStackDB.getEntry(dbName);\n  const cached = legacyEntries.get(name);\n  if (cached && cached.db === db) return cached.entry;\n  legacyStack ??= new SqlStack();\n  const entry: DatabaseEntry = { name, db, owned: false, stack: legacyStack };\n  legacyEntries.set(name, { db, entry });\n  return entry;\n}\n"]}

package/dist/cjs/sql.d.ts

@@ -1,11 +1,30 @@
+import type { Dialect } from './registry';
 export declare class SqlFragment {
     readonly strings: readonly string[];
     readonly values: readonly unknown[];
     constructor(strings: readonly string[], values: readonly unknown[]);
+    /**
+     * Compile to SQL with `?` placeholders and the matching parameter list.
+     *
+     * @throws {Error} When a binder macro (`:insert`, `:update`, `:filter`,
+     * `:batch_insert`) receives invalid input. `run(...)` wraps this in
+     * DatabaseError with the original error in `.cause`.
+     */
     toSQL(): {
         sql: string;
         params: unknown[];
     };
 }
+/** @internal True for a SqlFragment from this or any other sqlstack copy. */
+export declare function isSqlFragment(value: unknown): value is SqlFragment;
+/**
+ * @internal Compile a fragment for a dialect: `$1, $2, ...` for Postgres,
+ * `?` for SQLite and MySQL. Throws plain Error on invalid macro input
+ * (callers in run() wrap it).
+ */
+export declare function compileFragment(fragment: SqlFragment, dialect: Dialect): {
+    sql: string;
+    params: unknown[];
+};
 export declare function sql(strings: TemplateStringsArray, ...values: unknown[]): SqlFragment;
 //# sourceMappingURL=sql.d.ts.map

package/dist/cjs/sql.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/sql.ts"],"names":[],"mappings":"AAaA,qBAAa,WAAW;aAEJ,OAAO,EAAE,SAAS,MAAM,EAAE;aAC1B,MAAM,EAAE,SAAS,OAAO,EAAE;gBAD1B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,MAAM,EAAE,SAAS,OAAO,EAAE;IAG5C,KAAK,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,EAAE,CAAA;KAAE;CA8B5C;AAwDD,wBAAgB,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,CAEpF"}
+{"version":3,"file":"sql.d.ts","sourceRoot":"","sources":["../../src/sql.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAwB1C,qBAAa,WAAW;aAEJ,OAAO,EAAE,SAAS,MAAM,EAAE;aAC1B,MAAM,EAAE,SAAS,OAAO,EAAE;gBAD1B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,MAAM,EAAE,SAAS,OAAO,EAAE;IAG5C;;;;;;OAMG;IACH,KAAK,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,EAAE,CAAA;KAAE;CAG5C;AAID,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAOlE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAI3G;AA0FD,wBAAgB,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,CAEpF"}