sqlstack 3.0.0 → 3.2.0

package/dist/esm/decorators/query.js

@@ -1,5 +1,5 @@
 import { getClassLabels, getMethodLabels, setMethodLabels } from '../core/metadata.js';
-import { SqlStackError, ExactlyOneRowError, NoRowsError, RowsExistError, DatabaseError } from '../core/errors.js';
+import { SqlStackError, ExactlyOneRowError, NoRowsError, RowsExistError, DatabaseError, ExpectedRowsError } from '../core/errors.js';
 import { isValidationDisabled, validateOutput } from '../core/validator.js';
 import { resolveExecution } from '../runtime.js';
 import { createSqliteBinder, createMysqlBinder, createPostgresBinder } from '../binders/sqlBinder.js';
@@ -8,6 +8,7 @@ import { registerDecoratedMethod, recordQueryMethodOnClass } from '../core/resol
 import { defaultSourceScanResolver } from '../core/sourceScanResolver.js';
 import { getActiveTransaction } from '../transactions.js';
 import { SqlFragment } from '../sql.js';
+import { runStorage } from '../run.js';
 export function Query(arg) {
     return function (_target, prop, desc) {
         const options = typeof arg === 'string' ? undefined : arg;
@@ -44,281 +45,269 @@ export function Query(arg) {
         desc.value = async function (...callArgs) {
             const labels = getMethodLabels(this, prop);
             const classLabels = getClassLabels(this);
-            // 0) Check if the method body returns a SqlFragment (template literal path)
-            let fragmentResult;
-            try {
-                fragmentResult = await original.apply(this, callArgs);
-            }
-            catch {
-                // Method body threw (e.g. placeholder `throw new Error('replaced')`) — fall through to file/inline SQL
-                fragmentResult = undefined;
-            }
-            if (fragmentResult instanceof SqlFragment) {
-                const { sql: boundSql, params } = fragmentResult.toSQL();
+            // The full file/inline pipeline (resolve source, bind, execute,
+            // shape/transform/validate). Invoked either by run() from inside the
+            // method body, or directly as the legacy fallback when the body throws.
+            const pipeline = async () => {
+                // 1) prepare args with defaults
+                const rawInput = callArgs.length === 1 ? callArgs[0] : callArgs; // object or positional array
+                // 2) choose database and dialect via the active environment
                 const dbName = labels.db ?? options?.db ?? classLabels?.db;
-                const { entry } = await resolveExecution(dbName);
+                const { entry, resolver: activeResolver } = await resolveExecution(dbName);
                 const db = entry.db;
-                let out;
-                try {
-                    const tx = getActiveTransaction(entry);
-                    out = tx ? await tx.query(boundSql, params) : await db.query(boundSql, params);
-                }
-                catch (dbError) {
-                    throw new DatabaseError(dbError?.message || String(dbError), boundSql, dbError instanceof Error ? dbError : undefined);
-                }
-                if (Array.isArray(out)) {
-                    const shaped = applyShape(out, labels.shape);
-                    const transformed = labels.transform ? labels.transform(shaped) : shaped;
-                    if (labels.validateSchema && !isValidationDisabled()) {
-                        if (Array.isArray(transformed)) {
-                            for (const row of transformed)
-                                validateOutput(labels.validateSchema, row);
-                        }
-                        else if (transformed !== null && transformed !== undefined) {
-                            validateOutput(labels.validateSchema, transformed);
-                        }
-                    }
-                    return transformed;
-                }
-                return out;
-            }
-            // 1) prepare args with defaults
-            const rawInput = callArgs.length === 1 ? callArgs[0] : callArgs; // object or positional array
-            // 2) choose database and dialect via the active environment
-            const dbName = labels.db ?? options?.db ?? classLabels?.db;
-            const { entry, resolver: activeResolver } = await resolveExecution(dbName);
-            const db = entry.db;
-            const dialect = options?.dialect ?? db.dialect ?? 'sqlite';
-            // 3) load SQL source (inline, environment resolver, v1 fs fallback,
-            //    or the zero-config source scan — bare @Query() with nothing installed)
-            const sql = labels?.source?.kind === 'inline'
-                ? labels.source.sql
-                : activeResolver
-                    ? activeResolver.resolve({
-                        className: this?.constructor?.name ?? '<anonymous>',
-                        methodName: String(prop),
-                        dialect,
-                        rootDir: labels?.source?.kind === 'fs' ? labels.source.rootDir : undefined,
-                    })
-                    : labels?.source?.kind === 'fs'
-                        ? resolveSqlFromFs(labels.source.rootDir, String(prop), dialect).sql
-                        : defaultSourceScanResolver()?.resolve({
+                const dialect = options?.dialect ?? db.dialect ?? 'sqlite';
+                // 3) load SQL source (inline, environment resolver, v1 fs fallback,
+                //    or the zero-config source scan — bare @Query() with nothing installed)
+                const sql = labels?.source?.kind === 'inline'
+                    ? labels.source.sql
+                    : activeResolver
+                        ? activeResolver.resolve({
                             className: this?.constructor?.name ?? '<anonymous>',
                             methodName: String(prop),
                             dialect,
-                        });
-            if (!sql) {
-                throw new SqlStackError(`No SQL source provided for method ${String(prop)}. Use @Query() with a file/folder path or inline sql.`);
-            }
-            // 4) bind placeholders
-            // Decide argument mode: positional if SQL contains :argN
-            let workingSql = sql;
-            const hasPositional = /:arg[1-9][0-9]*/.test(workingSql);
-            // Prepare args for binder
-            let args;
-            if (hasPositional) {
-                args = callArgs;
-            }
-            else {
-                const namedBase = callArgs.length > 0 ? callArgs[0] : undefined;
-                args = applyDefaults(labels.defaults, namedBase ?? {});
-            }
-            // Compute paging and inject :offset/:limit (named mode) or rewrite to positional
-            const pageCfg = labels.page;
-            if (pageCfg) {
-                const { size, zeroBase } = pageCfg;
-                const base = zeroBase ? 0 : 1;
-                // Extract page number from input (object) or a trailing options object in positional mode
-                const pageFromObject = (val) => {
-                    if (val && typeof val === 'object' && !Array.isArray(val) && typeof val.page !== 'undefined') {
-                        const p = val.page;
-                        if (typeof p === 'number' && isFinite(p))
-                            return p;
-                    }
-                    return undefined;
-                };
-                let pageNum;
+                            rootDir: labels?.source?.kind === 'fs' ? labels.source.rootDir : undefined,
+                        })
+                        : labels?.source?.kind === 'fs'
+                            ? resolveSqlFromFs(labels.source.rootDir, String(prop), dialect).sql
+                            : defaultSourceScanResolver()?.resolve({
+                                className: this?.constructor?.name ?? '<anonymous>',
+                                methodName: String(prop),
+                                dialect,
+                            });
+                if (!sql) {
+                    throw new SqlStackError(`No SQL source provided for method ${String(prop)}. Use @Query() with a file/folder path or inline sql.`);
+                }
+                // 4) bind placeholders
+                // Decide argument mode: positional if SQL contains :argN
+                let workingSql = sql;
+                const hasPositional = /:arg[1-9][0-9]*/.test(workingSql);
+                // Prepare args for binder
+                let args;
                 if (hasPositional) {
-                    // Variadic-style: only the LAST argument may carry `{ page }`
-                    if (callArgs.length > 0) {
-                        const last = callArgs[callArgs.length - 1];
-                        pageNum = pageFromObject(last);
-                    }
+                    args = callArgs;
                 }
                 else {
-                    // Prefer last-arg options if provided; otherwise read from named object
-                    if (callArgs.length > 1) {
-                        const last = callArgs[callArgs.length - 1];
-                        pageNum = pageFromObject(last);
+                    const namedBase = callArgs.length > 0 ? callArgs[0] : undefined;
+                    args = applyDefaults(labels.defaults, namedBase ?? {});
+                }
+                // Compute paging and inject :offset/:limit (named mode) or rewrite to positional
+                const pageCfg = labels.page;
+                if (pageCfg) {
+                    const { size, zeroBase } = pageCfg;
+                    const base = zeroBase ? 0 : 1;
+                    // Extract page number from input (object) or a trailing options object in positional mode
+                    const pageFromObject = (val) => {
+                        if (val && typeof val === 'object' && !Array.isArray(val) && typeof val.page !== 'undefined') {
+                            const p = val.page;
+                            if (typeof p === 'number' && isFinite(p))
+                                return p;
+                        }
+                        return undefined;
+                    };
+                    let pageNum;
+                    if (hasPositional) {
+                        // Variadic-style: only the LAST argument may carry `{ page }`
+                        if (callArgs.length > 0) {
+                            const last = callArgs[callArgs.length - 1];
+                            pageNum = pageFromObject(last);
+                        }
                     }
-                    if (pageNum === undefined) {
-                        pageNum = pageFromObject(args);
+                    else {
+                        // Prefer last-arg options if provided; otherwise read from named object
+                        if (callArgs.length > 1) {
+                            const last = callArgs[callArgs.length - 1];
+                            pageNum = pageFromObject(last);
+                        }
+                        if (pageNum === undefined) {
+                            pageNum = pageFromObject(args);
+                        }
                     }
-                }
-                const effectivePage = typeof pageNum === 'number' ? pageNum : base;
-                const offset = (effectivePage - base) * size;
-                const limit = size;
-                if (hasPositional) {
-                    // Replace occurrences of :offset and :limit with new :argN tokens appended to args
-                    const baseIndex = callArgs.length; // start numbering after user args
-                    let nextIndex = baseIndex + 1;
-                    const additions = [];
-                    const rewrite = (sqlText) => {
-                        const out = [];
-                        let i = 0;
-                        let inSQ = false, inDQ = false, inLC = false, inBC = false;
-                        const len = sqlText.length;
-                        while (i < len) {
-                            const ch = sqlText[i];
-                            const next = i + 1 < len ? sqlText[i + 1] : '';
-                            if (inLC) {
-                                out.push(ch);
-                                if (ch === '\n')
-                                    inLC = false;
-                                i++;
-                                continue;
-                            }
-                            if (inBC) {
-                                out.push(ch);
-                                if (ch === '*' && next === '/') {
-                                    out.push(next);
+                    const effectivePage = typeof pageNum === 'number' ? pageNum : base;
+                    const offset = (effectivePage - base) * size;
+                    const limit = size;
+                    if (hasPositional) {
+                        // Replace occurrences of :offset and :limit with new :argN tokens appended to args
+                        const baseIndex = callArgs.length; // start numbering after user args
+                        let nextIndex = baseIndex + 1;
+                        const additions = [];
+                        const rewrite = (sqlText) => {
+                            const out = [];
+                            let i = 0;
+                            let inSQ = false, inDQ = false, inLC = false, inBC = false;
+                            const len = sqlText.length;
+                            while (i < len) {
+                                const ch = sqlText[i];
+                                const next = i + 1 < len ? sqlText[i + 1] : '';
+                                if (inLC) {
+                                    out.push(ch);
+                                    if (ch === '\n')
+                                        inLC = false;
                                     i++;
-                                    inBC = false;
+                                    continue;
                                 }
-                                i++;
-                                continue;
-                            }
-                            if (inSQ) {
-                                out.push(ch);
-                                if (ch === "'" && next === "'") {
-                                    out.push(next);
+                                if (inBC) {
+                                    out.push(ch);
+                                    if (ch === '*' && next === '/') {
+                                        out.push(next);
+                                        i++;
+                                        inBC = false;
+                                    }
+                                    i++;
+                                    continue;
+                                }
+                                if (inSQ) {
+                                    out.push(ch);
+                                    if (ch === "'" && next === "'") {
+                                        out.push(next);
+                                        i += 2;
+                                        continue;
+                                    }
+                                    if (ch === "'")
+                                        inSQ = false;
+                                    i++;
+                                    continue;
+                                }
+                                if (inDQ) {
+                                    out.push(ch);
+                                    if (ch === '"' && next === '"') {
+                                        out.push(next);
+                                        i += 2;
+                                        continue;
+                                    }
+                                    if (ch === '"')
+                                        inDQ = false;
+                                    i++;
+                                    continue;
+                                }
+                                if (ch === '-' && next === '-') {
+                                    out.push(ch, next);
                                     i += 2;
+                                    inLC = true;
                                     continue;
                                 }
-                                if (ch === "'")
-                                    inSQ = false;
-                                i++;
-                                continue;
-                            }
-                            if (inDQ) {
-                                out.push(ch);
-                                if (ch === '"' && next === '"') {
-                                    out.push(next);
+                                if (ch === '/' && next === '*') {
+                                    out.push(ch, next);
                                     i += 2;
+                                    inBC = true;
                                     continue;
                                 }
-                                if (ch === '"')
-                                    inDQ = false;
-                                i++;
-                                continue;
-                            }
-                            if (ch === '-' && next === '-') {
-                                out.push(ch, next);
-                                i += 2;
-                                inLC = true;
-                                continue;
-                            }
-                            if (ch === '/' && next === '*') {
-                                out.push(ch, next);
-                                i += 2;
-                                inBC = true;
-                                continue;
-                            }
-                            if (ch === '"') {
-                                out.push(ch);
-                                inDQ = true;
-                                i++;
-                                continue;
-                            }
-                            if (ch === "'") {
-                                out.push(ch);
-                                inSQ = true;
-                                i++;
-                                continue;
-                            }
-                            if (ch === ':' && next === ':') {
-                                out.push('::');
-                                i += 2;
-                                continue;
-                            }
-                            if (ch === ':') {
-                                // parse token
-                                let j = i + 1;
-                                const start = j;
-                                while (j < len) {
-                                    const c = sqlText[j];
-                                    if ((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c === '_')
-                                        j++;
-                                    else
-                                        break;
+                                if (ch === '"') {
+                                    out.push(ch);
+                                    inDQ = true;
+                                    i++;
+                                    continue;
                                 }
-                                const name = sqlText.slice(start, j);
-                                if (name === 'offset') {
-                                    const token = `:arg${nextIndex++}`;
-                                    out.push(token);
-                                    additions.push(offset);
-                                    i = j;
+                                if (ch === "'") {
+                                    out.push(ch);
+                                    inSQ = true;
+                                    i++;
                                     continue;
                                 }
-                                if (name === 'limit') {
-                                    const token = `:arg${nextIndex++}`;
-                                    out.push(token);
-                                    additions.push(limit);
-                                    i = j;
+                                if (ch === ':' && next === ':') {
+                                    out.push('::');
+                                    i += 2;
                                     continue;
                                 }
-                                // otherwise leave untouched
-                                out.push(':');
+                                if (ch === ':') {
+                                    // parse token
+                                    let j = i + 1;
+                                    const start = j;
+                                    while (j < len) {
+                                        const c = sqlText[j];
+                                        if ((c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') || c === '_')
+                                            j++;
+                                        else
+                                            break;
+                                    }
+                                    const name = sqlText.slice(start, j);
+                                    if (name === 'offset') {
+                                        const token = `:arg${nextIndex++}`;
+                                        out.push(token);
+                                        additions.push(offset);
+                                        i = j;
+                                        continue;
+                                    }
+                                    if (name === 'limit') {
+                                        const token = `:arg${nextIndex++}`;
+                                        out.push(token);
+                                        additions.push(limit);
+                                        i = j;
+                                        continue;
+                                    }
+                                    // otherwise leave untouched
+                                    out.push(':');
+                                    i++;
+                                    continue;
+                                }
+                                out.push(ch);
                                 i++;
-                                continue;
                             }
-                            out.push(ch);
-                            i++;
+                            return out.join('');
+                        };
+                        const rewritten = rewrite(workingSql);
+                        if (rewritten !== workingSql) {
+                            workingSql = rewritten;
+                            // append values so :argK map correctly
+                            args.push(...additions);
                         }
-                        return out.join('');
-                    };
-                    const rewritten = rewrite(workingSql);
-                    if (rewritten !== workingSql) {
-                        workingSql = rewritten;
-                        // append values so :argK map correctly
-                        args.push(...additions);
+                    }
+                    else {
+                        // Named-mode: attach computed values (override any provided)
+                        args = { ...args, offset, limit };
                     }
                 }
-                else {
-                    // Named-mode: attach computed values (override any provided)
-                    args = { ...args, offset, limit };
+                const binder = dialect === 'postgres' ? createPostgresBinder() : dialect === 'mysql' ? createMysqlBinder() : createSqliteBinder();
+                const { sql: boundSql, params } = binder.bind(workingSql, args);
+                // 5) execute query via registry DB
+                let out;
+                try {
+                    const tx = getActiveTransaction(entry);
+                    out = tx ? await tx.query(boundSql, params) : await db.query(boundSql, params);
                 }
-            }
-            const binder = dialect === 'postgres' ? createPostgresBinder() : dialect === 'mysql' ? createMysqlBinder() : createSqliteBinder();
-            const { sql: boundSql, params } = binder.bind(workingSql, args);
-            // 5) execute query via registry DB
-            let out;
+                catch (dbError) {
+                    // Attach SQL query (with placeholders) to error for debugging
+                    throw new DatabaseError(dbError?.message || String(dbError), boundSql, dbError instanceof Error ? dbError : undefined);
+                }
+                // 6) If rows were returned (SELECT/CTE/RETURNING), shape + transform + validate;
+                //    otherwise return the write result as-is (or fail if a shape was requested)
+                return finishResult(out, labels, this, prop);
+            };
+            // 0) Invoke the method body inside a run() context. Three outcomes:
+            //    - body calls run(): the pipeline executed inside the body; return
+            //      the body's result verbatim (it may have caught/transformed it).
+            //    - body returns a SqlFragment (template literal path): execute it.
+            //    - body throws without calling run() (legacy placeholder throw):
+            //      fall through to the pipeline.
+            const runCtx = { ran: false, execute: pipeline };
+            let fragmentResult;
             try {
-                const tx = getActiveTransaction(entry);
-                out = tx ? await tx.query(boundSql, params) : await db.query(boundSql, params);
+                fragmentResult = await runStorage.run(runCtx, () => original.apply(this, callArgs));
             }
-            catch (dbError) {
-                // Attach SQL query (with placeholders) to error for debugging
-                throw new DatabaseError(dbError?.message || String(dbError), boundSql, dbError instanceof Error ? dbError : undefined);
+            catch (bodyError) {
+                // A body that invoked run() is real logic — its errors propagate.
+                if (runCtx.ran)
+                    throw bodyError;
+                // Method body threw (e.g. placeholder `throw new Error('replaced')`) — fall through to file/inline SQL
+                fragmentResult = undefined;
             }
-            // 6) If rows were returned (SELECT/CTE), shape + transform + validate
-            if (Array.isArray(out)) {
-                const shaped = applyShape(out, labels.shape);
-                const transformed = labels.transform ? labels.transform(shaped) : shaped;
-                // 7) validate result via JSON Schema, if provided
-                if (labels.validateSchema && !isValidationDisabled()) {
-                    if (Array.isArray(transformed)) {
-                        for (const row of transformed)
-                            validateOutput(labels.validateSchema, row);
-                    }
-                    else if (transformed !== null && transformed !== undefined) {
-                        validateOutput(labels.validateSchema, transformed);
-                    }
+            if (runCtx.ran)
+                return fragmentResult;
+            if (fragmentResult instanceof SqlFragment) {
+                const { sql: boundSql, params } = fragmentResult.toSQL();
+                const dbName = labels.db ?? options?.db ?? classLabels?.db;
+                const { entry } = await resolveExecution(dbName);
+                const db = entry.db;
+                let out;
+                try {
+                    const tx = getActiveTransaction(entry);
+                    out = tx ? await tx.query(boundSql, params) : await db.query(boundSql, params);
+                }
+                catch (dbError) {
+                    throw new DatabaseError(dbError?.message || String(dbError), boundSql, dbError instanceof Error ? dbError : undefined);
                 }
-                return transformed;
+                return finishResult(out, labels, this, prop);
             }
-            // Non-SELECT: return the write result as-is
-            return out;
+            return pipeline();
         };
         return desc;
     };
@@ -330,6 +319,31 @@ function applyDefaults(defaults, input) {
         return input; // defaults only apply to named-object args
     return { ...defaults, ...(input || {}) };
 }
+// Shared tail of both execution paths. Rows (any statement that produced a
+// result set) are shaped, transformed, and validated. A write result is
+// returned verbatim — unless a result-shape decorator was requested, in which
+// case the statement cannot satisfy it and we fail at the call site instead of
+// silently handing back a truthy `{ rowsAffected }` object.
+function finishResult(out, labels, self, prop) {
+    if (!Array.isArray(out)) {
+        if (labels.shape) {
+            throw new ExpectedRowsError(`${self?.constructor?.name ?? '<anonymous>'}.${String(prop)}`, labels.shape);
+        }
+        return out;
+    }
+    const shaped = applyShape(out, labels.shape);
+    const transformed = labels.transform ? labels.transform(shaped) : shaped;
+    if (labels.validateSchema && !isValidationDisabled()) {
+        if (Array.isArray(transformed)) {
+            for (const row of transformed)
+                validateOutput(labels.validateSchema, row);
+        }
+        else if (transformed !== null && transformed !== undefined) {
+            validateOutput(labels.validateSchema, transformed);
+        }
+    }
+    return transformed;
+}
 function applyShape(rows, shape) {
     switch (shape) {
         case 'single':