sqlstack 3.5.0 → 3.6.0-dev.0

package/dist/cjs/core/resources.d.ts

@@ -0,0 +1,36 @@
+import type { Dialect } from '../registry';
+/**
+ * Packaged SQL resources: a path-keyed map `{ '<path>/<method>.sql': '<sql>' }`
+ * installed by a bundled/packaged runtime (Electron asar, Cloudflare Worker,
+ * @noego/app node runner) via `SqlStack.useResources(map)`.
+ *
+ * Keys are file paths — absolute, or relative to the project root (the shape
+ * `import.meta.glob('/server/**\/*.sql', { eager: true, query: '?raw' })`
+ * produces). Lookups match by path suffix: the decorator's guessed directory
+ * plus `<method>.sql` must END WITH a key. That makes the same map valid
+ * whether modules load from `/repo/server/...`, `app.asar/out/server/...`
+ * or a Worker's `modules/<project>/server/...` tree, as long as the module
+ * tree is not flattened.
+ */
+export type SqlResources = Record<string, string>;
+/** Forward slashes, no `file://`, no leading `./`, exactly one leading `/`. */
+export declare function normalizeResourcePath(p: string): string;
+/** Install (or clear with undefined) the process-wide packaged SQL resources. */
+export declare function setResources(map: SqlResources | undefined): void;
+export declare function getResources(): SqlResources | undefined;
+/**
+ * Resolve one absolute (or module-tree) candidate path against the installed
+ * resources. Order: exact key; the longest key that is a path suffix of the
+ * candidate; the unique key sharing the candidate's `<folder>/<file>` tail.
+ */
+export declare function lookupResource(candidatePath: string): string | undefined;
+/**
+ * Resolve a decorated method's SQL from the installed resources: the
+ * dialect-specific `<dir>/<method>.<ext>.sql` first, then `<dir>/<method>.sql`.
+ * Returns the tried candidate paths so a miss can be reported precisely.
+ */
+export declare function resolveSqlFromResources(dir: string, methodName: string, dialect: Dialect): {
+    sql: string | undefined;
+    tried: string[];
+};
+//# sourceMappingURL=resources.d.ts.map

package/dist/cjs/core/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../../src/core/resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAwBlD,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMvD;AAOD,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,CAchE;AAED,wBAAgB,YAAY,IAAI,YAAY,GAAG,SAAS,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoBxE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,GACf;IAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAQ9C"}

package/dist/cjs/core/resources.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeResourcePath = normalizeResourcePath;
+exports.setResources = setResources;
+exports.getResources = getResources;
+exports.lookupResource = lookupResource;
+exports.resolveSqlFromResources = resolveSqlFromResources;
+const g = globalThis;
+if (!g.__SQLSTACK_RESOURCES_STATE__) {
+    g.__SQLSTACK_RESOURCES_STATE__ = {
+        resources: undefined,
+        byKey: new Map(),
+        byTail: new Map(),
+        lookups: new Map(),
+    };
+}
+const state = g.__SQLSTACK_RESOURCES_STATE__;
+const DIALECT_EXT = { postgres: 'pg', mysql: 'mysql', sqlite: 'sqlite' };
+/** Forward slashes, no `file://`, no leading `./`, exactly one leading `/`. */
+function normalizeResourcePath(p) {
+    let s = p.replace(/\\/g, '/');
+    if (s.startsWith('file://'))
+        s = s.slice('file://'.length);
+    s = s.replace(/^(\.\/)+/, '');
+    s = s.replace(/^\/+/, '');
+    return '/' + s;
+}
+function tailOf(normalized) {
+    const parts = normalized.split('/');
+    return '/' + parts.slice(-2).join('/');
+}
+/** Install (or clear with undefined) the process-wide packaged SQL resources. */
+function setResources(map) {
+    state.byKey = new Map();
+    state.byTail = new Map();
+    state.lookups = new Map();
+    state.resources = map;
+    if (!map)
+        return;
+    for (const [rawKey, sql] of Object.entries(map)) {
+        const key = normalizeResourcePath(rawKey);
+        state.byKey.set(key, sql);
+        const tail = tailOf(key);
+        const list = state.byTail.get(tail);
+        if (list)
+            list.push(key);
+        else
+            state.byTail.set(tail, [key]);
+    }
+}
+function getResources() {
+    return state.resources;
+}
+/**
+ * Resolve one absolute (or module-tree) candidate path against the installed
+ * resources. Order: exact key; the longest key that is a path suffix of the
+ * candidate; the unique key sharing the candidate's `<folder>/<file>` tail.
+ */
+function lookupResource(candidatePath) {
+    if (!state.resources)
+        return undefined;
+    const candidate = normalizeResourcePath(candidatePath);
+    if (state.lookups.has(candidate))
+        return state.lookups.get(candidate);
+    let found = state.byKey.get(candidate);
+    if (found === undefined) {
+        let bestLen = -1;
+        for (const [key, sql] of state.byKey) {
+            if (key.length > bestLen && candidate.endsWith(key)) {
+                found = sql;
+                bestLen = key.length;
+            }
+        }
+    }
+    if (found === undefined) {
+        const hits = state.byTail.get(tailOf(candidate));
+        if (hits && hits.length === 1)
+            found = state.byKey.get(hits[0]);
+    }
+    state.lookups.set(candidate, found);
+    return found;
+}
+/**
+ * Resolve a decorated method's SQL from the installed resources: the
+ * dialect-specific `<dir>/<method>.<ext>.sql` first, then `<dir>/<method>.sql`.
+ * Returns the tried candidate paths so a miss can be reported precisely.
+ */
+function resolveSqlFromResources(dir, methodName, dialect) {
+    const base = normalizeResourcePath(dir).replace(/\/+$/, '');
+    const tried = [`${base}/${methodName}.${DIALECT_EXT[dialect]}.sql`, `${base}/${methodName}.sql`];
+    for (const candidate of tried) {
+        const sql = lookupResource(candidate);
+        if (sql !== undefined)
+            return { sql, tried };
+    }
+    return { sql: undefined, tried };
+}
+//# sourceMappingURL=resources.js.map

package/dist/cjs/core/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../../../src/core/resources.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Dialect } from '../registry';\n\n/**\n * Packaged SQL resources: a path-keyed map `{ '<path>/<method>.sql': '<sql>' }`\n * installed by a bundled/packaged runtime (Electron asar, Cloudflare Worker,\n * @noego/app node runner) via `SqlStack.useResources(map)`.\n *\n * Keys are file paths — absolute, or relative to the project root (the shape\n * `import.meta.glob('/server/**\\/*.sql', { eager: true, query: '?raw' })`\n * produces). Lookups match by path suffix: the decorator's guessed directory\n * plus `<method>.sql` must END WITH a key. That makes the same map valid\n * whether modules load from `/repo/server/...`, `app.asar/out/server/...`\n * or a Worker's `modules/<project>/server/...` tree, as long as the module\n * tree is not flattened.\n */\nexport type SqlResources = Record<string, string>;\n\ntype ResourcesState = {\n  resources: SqlResources | undefined;\n  /** normalized key → sql */\n  byKey: Map<string, string>;\n  /** `<folder>/<file>` tail → normalized keys sharing that tail */\n  byTail: Map<string, string[]>;\n  lookups: Map<string, string | undefined>;\n};\n\nconst g = globalThis as any;\nif (!g.__SQLSTACK_RESOURCES_STATE__) {\n  g.__SQLSTACK_RESOURCES_STATE__ = {\n    resources: undefined,\n    byKey: new Map(),\n    byTail: new Map(),\n    lookups: new Map(),\n  } as ResourcesState;\n}\nconst state: ResourcesState = g.__SQLSTACK_RESOURCES_STATE__;\n\nconst DIALECT_EXT: Record<Dialect, string> = { postgres: 'pg', mysql: 'mysql', sqlite: 'sqlite' };\n\n/** Forward slashes, no `file://`, no leading `./`, exactly one leading `/`. */\nexport function normalizeResourcePath(p: string): string {\n  let s = p.replace(/\\\\/g, '/');\n  if (s.startsWith('file://')) s = s.slice('file://'.length);\n  s = s.replace(/^(\\.\\/)+/, '');\n  s = s.replace(/^\\/+/, '');\n  return '/' + s;\n}\n\nfunction tailOf(normalized: string): string {\n  const parts = normalized.split('/');\n  return '/' + parts.slice(-2).join('/');\n}\n\n/** Install (or clear with undefined) the process-wide packaged SQL resources. */\nexport function setResources(map: SqlResources | undefined): void {\n  state.byKey = new Map();\n  state.byTail = new Map();\n  state.lookups = new Map();\n  state.resources = map;\n  if (!map) return;\n  for (const [rawKey, sql] of Object.entries(map)) {\n    const key = normalizeResourcePath(rawKey);\n    state.byKey.set(key, sql);\n    const tail = tailOf(key);\n    const list = state.byTail.get(tail);\n    if (list) list.push(key);\n    else state.byTail.set(tail, [key]);\n  }\n}\n\nexport function getResources(): SqlResources | undefined {\n  return state.resources;\n}\n\n/**\n * Resolve one absolute (or module-tree) candidate path against the installed\n * resources. Order: exact key; the longest key that is a path suffix of the\n * candidate; the unique key sharing the candidate's `<folder>/<file>` tail.\n */\nexport function lookupResource(candidatePath: string): string | undefined {\n  if (!state.resources) return undefined;\n  const candidate = normalizeResourcePath(candidatePath);\n  if (state.lookups.has(candidate)) return state.lookups.get(candidate);\n  let found: string | undefined = state.byKey.get(candidate);\n  if (found === undefined) {\n    let bestLen = -1;\n    for (const [key, sql] of state.byKey) {\n      if (key.length > bestLen && candidate.endsWith(key)) {\n        found = sql;\n        bestLen = key.length;\n      }\n    }\n  }\n  if (found === undefined) {\n    const hits = state.byTail.get(tailOf(candidate));\n    if (hits && hits.length === 1) found = state.byKey.get(hits[0]);\n  }\n  state.lookups.set(candidate, found);\n  return found;\n}\n\n/**\n * Resolve a decorated method's SQL from the installed resources: the\n * dialect-specific `<dir>/<method>.<ext>.sql` first, then `<dir>/<method>.sql`.\n * Returns the tried candidate paths so a miss can be reported precisely.\n */\nexport function resolveSqlFromResources(\n  dir: string,\n  methodName: string,\n  dialect: Dialect\n): { sql: string | undefined; tried: string[] } {\n  const base = normalizeResourcePath(dir).replace(/\\/+$/, '');\n  const tried = [`${base}/${methodName}.${DIALECT_EXT[dialect]}.sql`, `${base}/${methodName}.sql`];\n  for (const candidate of tried) {\n    const sql = lookupResource(candidate);\n    if (sql !== undefined) return { sql, tried };\n  }\n  return { sql: undefined, tried };\n}\n"]}

package/dist/cjs/core/sourceScanResolver.d.ts

@@ -1,14 +1,14 @@
 import type { SqlResolver, SqlResolutionRequest } from './resolver';
 /**
- * Zero-config Node resolution for bare @Query(): lazily scans the project
- * tree (process.cwd(), or an explicit rootDir) for @Query classes and their
- * sibling .sql files, then answers Contract A lookups from the in-memory
- * manifest. The scan runs once, on the first bare-@Query execution.
+ * Opt-in Node resolution that scans a project tree (process.cwd(), or an
+ * explicit rootDir) for @Query classes and their sibling .sql files, then
+ * answers Contract A lookups from the in-memory manifest. The scan runs once
+ * per instance, on first resolve.
  *
- * This is the DEFAULT resolver — installed resolvers (per-root SqlStackConfig
- * or the deprecated global) always take precedence, and bundled runtimes
- * (Cloudflare Workers) never reach it because their entrypoints install a
- * ManifestResolver.
+ * This is NOT a default. Bare @Query() resolves its own module directory
+ * (stack guess at decoration time) against `SqlStack.useResources(...)` or
+ * the filesystem; nothing walks the tree unless this resolver is installed
+ * explicitly via `SqlStack.useResolver` / `SqlStackConfig.resolver`.
  */
 export declare class SourceScanResolver implements SqlResolver {
     #private;
@@ -16,10 +16,4 @@ export declare class SourceScanResolver implements SqlResolver {
     constructor(rootDir?: string | undefined);
     resolve(request: SqlResolutionRequest): string | undefined;
 }
-/**
- * @internal Process-wide default used by the @Query call path when no
- * resolver is installed and the decorator captured no filesystem root.
- * Node-only: returns undefined where the filesystem is unavailable.
- */
-export declare function defaultSourceScanResolver(): SourceScanResolver | undefined;
 //# sourceMappingURL=sourceScanResolver.d.ts.map

package/dist/cjs/core/sourceScanResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sourceScanResolver.d.ts","sourceRoot":"","sources":["../../../src/core/sourceScanResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAIpE;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,YAAW,WAAW;;IAGxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAR,OAAO,CAAC,EAAE,MAAM,YAAA;IAE7C,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS;CAO3D;AAID;;;;GAIG;AACH,wBAAgB,yBAAyB,IAAI,kBAAkB,GAAG,SAAS,CAG1E"}
+{"version":3,"file":"sourceScanResolver.d.ts","sourceRoot":"","sources":["../../../src/core/sourceScanResolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAIpE;;;;;;;;;;GAUG;AACH,qBAAa,kBAAmB,YAAW,WAAW;;IAGxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAR,OAAO,CAAC,EAAE,MAAM,YAAA;IAE7C,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS;CAO3D"}

package/dist/cjs/core/sourceScanResolver.js

@@ -13,19 +13,18 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
 var _SourceScanResolver_inner;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SourceScanResolver = void 0;
-exports.defaultSourceScanResolver = defaultSourceScanResolver;
 const resolver_1 = require("./resolver");
 const generateManifest_1 = require("../codegen/generateManifest");
 /**
- * Zero-config Node resolution for bare @Query(): lazily scans the project
- * tree (process.cwd(), or an explicit rootDir) for @Query classes and their
- * sibling .sql files, then answers Contract A lookups from the in-memory
- * manifest. The scan runs once, on the first bare-@Query execution.
+ * Opt-in Node resolution that scans a project tree (process.cwd(), or an
+ * explicit rootDir) for @Query classes and their sibling .sql files, then
+ * answers Contract A lookups from the in-memory manifest. The scan runs once
+ * per instance, on first resolve.
  *
- * This is the DEFAULT resolver — installed resolvers (per-root SqlStackConfig
- * or the deprecated global) always take precedence, and bundled runtimes
- * (Cloudflare Workers) never reach it because their entrypoints install a
- * ManifestResolver.
+ * This is NOT a default. Bare @Query() resolves its own module directory
+ * (stack guess at decoration time) against `SqlStack.useResources(...)` or
+ * the filesystem; nothing walks the tree unless this resolver is installed
+ * explicitly via `SqlStack.useResolver` / `SqlStackConfig.resolver`.
  */
 class SourceScanResolver {
     constructor(rootDir) {
@@ -42,15 +41,4 @@ class SourceScanResolver {
 }
 exports.SourceScanResolver = SourceScanResolver;
 _SourceScanResolver_inner = new WeakMap();
-let defaultInstance;
-/**
- * @internal Process-wide default used by the @Query call path when no
- * resolver is installed and the decorator captured no filesystem root.
- * Node-only: returns undefined where the filesystem is unavailable.
- */
-function defaultSourceScanResolver() {
-    if (typeof process === 'undefined' || typeof process.cwd !== 'function')
-        return undefined;
-    return (defaultInstance ?? (defaultInstance = new SourceScanResolver()));
-}
 //# sourceMappingURL=sourceScanResolver.js.map

package/dist/cjs/core/sourceScanResolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"sourceScanResolver.js","sourceRoot":"","sources":["../../../src/core/sourceScanResolver.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAoCA,8DAGC;AAtCD,yCAA8C;AAC9C,kEAAkE;AAElE;;;;;;;;;;GAUG;AACH,MAAa,kBAAkB;IAG7B,YAA6B,OAAgB;QAAhB,YAAO,GAAP,OAAO,CAAS;QAF7C,4CAAqC;IAEW,CAAC;IAEjD,OAAO,CAAC,OAA6B;QACnC,IAAI,CAAC,uBAAA,IAAI,iCAAO,EAAE,CAAC;YACjB,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAA,sCAAmB,EAAC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;YACxE,uBAAA,IAAI,6BAAU,IAAI,2BAAgB,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,MAAA,CAAC;QAClE,CAAC;QACD,OAAO,uBAAA,IAAI,iCAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;CACF;AAZD,gDAYC;;AAED,IAAI,eAA+C,CAAC;AAEpD;;;;GAIG;AACH,SAAgB,yBAAyB;IACvC,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,OAAO,CAAC,GAAG,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IAC1F,OAAO,CAAC,eAAe,KAAf,eAAe,GAAK,IAAI,kBAAkB,EAAE,EAAC,CAAC;AACxD,CAAC","sourcesContent":["import type { SqlResolver, SqlResolutionRequest } from './resolver';\nimport { ManifestResolver } from './resolver';\nimport { scanSqlManifestSync } from '../codegen/generateManifest';\n\n/**\n * Zero-config Node resolution for bare @Query(): lazily scans the project\n * tree (process.cwd(), or an explicit rootDir) for @Query classes and their\n * sibling .sql files, then answers Contract A lookups from the in-memory\n * manifest. The scan runs once, on the first bare-@Query execution.\n *\n * This is the DEFAULT resolver — installed resolvers (per-root SqlStackConfig\n * or the deprecated global) always take precedence, and bundled runtimes\n * (Cloudflare Workers) never reach it because their entrypoints install a\n * ManifestResolver.\n */\nexport class SourceScanResolver implements SqlResolver {\n  #inner: ManifestResolver | undefined;\n\n  constructor(private readonly rootDir?: string) {}\n\n  resolve(request: SqlResolutionRequest): string | undefined {\n    if (!this.#inner) {\n      const { manifest } = scanSqlManifestSync(this.rootDir ?? process.cwd());\n      this.#inner = new ManifestResolver(manifest, { assert: false });\n    }\n    return this.#inner.resolve(request);\n  }\n}\n\nlet defaultInstance: SourceScanResolver | undefined;\n\n/**\n * @internal Process-wide default used by the @Query call path when no\n * resolver is installed and the decorator captured no filesystem root.\n * Node-only: returns undefined where the filesystem is unavailable.\n */\nexport function defaultSourceScanResolver(): SourceScanResolver | undefined {\n  if (typeof process === 'undefined' || typeof process.cwd !== 'function') return undefined;\n  return (defaultInstance ??= new SourceScanResolver());\n}\n"]}
+{"version":3,"file":"sourceScanResolver.js","sourceRoot":"","sources":["../../../src/core/sourceScanResolver.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AACA,yCAA8C;AAC9C,kEAAkE;AAElE;;;;;;;;;;GAUG;AACH,MAAa,kBAAkB;IAG7B,YAA6B,OAAgB;QAAhB,YAAO,GAAP,OAAO,CAAS;QAF7C,4CAAqC;IAEW,CAAC;IAEjD,OAAO,CAAC,OAA6B;QACnC,IAAI,CAAC,uBAAA,IAAI,iCAAO,EAAE,CAAC;YACjB,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAA,sCAAmB,EAAC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;YACxE,uBAAA,IAAI,6BAAU,IAAI,2BAAgB,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,MAAA,CAAC;QAClE,CAAC;QACD,OAAO,uBAAA,IAAI,iCAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;CACF;AAZD,gDAYC","sourcesContent":["import type { SqlResolver, SqlResolutionRequest } from './resolver';\nimport { ManifestResolver } from './resolver';\nimport { scanSqlManifestSync } from '../codegen/generateManifest';\n\n/**\n * Opt-in Node resolution that scans a project tree (process.cwd(), or an\n * explicit rootDir) for @Query classes and their sibling .sql files, then\n * answers Contract A lookups from the in-memory manifest. The scan runs once\n * per instance, on first resolve.\n *\n * This is NOT a default. Bare @Query() resolves its own module directory\n * (stack guess at decoration time) against `SqlStack.useResources(...)` or\n * the filesystem; nothing walks the tree unless this resolver is installed\n * explicitly via `SqlStack.useResolver` / `SqlStackConfig.resolver`.\n */\nexport class SourceScanResolver implements SqlResolver {\n  #inner: ManifestResolver | undefined;\n\n  constructor(private readonly rootDir?: string) {}\n\n  resolve(request: SqlResolutionRequest): string | undefined {\n    if (!this.#inner) {\n      const { manifest } = scanSqlManifestSync(this.rootDir ?? process.cwd());\n      this.#inner = new ManifestResolver(manifest, { assert: false });\n    }\n    return this.#inner.resolve(request);\n  }\n}\n"]}

package/dist/cjs/decorators/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/decorators/query.ts"],"names":[],"mappings":"AAsBA,KAAK,YAAY,GAAG;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,YAAY,IAC9B,SAAS,GAAG,EAAE,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,kBAAkB,wBAqW/E"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/decorators/query.ts"],"names":[],"mappings":"AAyBA,KAAK,YAAY,GAAG;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,YAAY,IAC9B,SAAS,GAAG,EAAE,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,kBAAkB,wBA6Y/E"}

package/dist/cjs/decorators/query.js

@@ -8,7 +8,7 @@ const runtime_1 = require("../runtime");
 const sqlBinder_1 = require("../binders/sqlBinder");
 const fileResolution_1 = require("../core/fileResolution");
 const resolver_1 = require("../core/resolver");
-const sourceScanResolver_1 = require("../core/sourceScanResolver");
+const resources_1 = require("../core/resources");
 const transactions_1 = require("../transactions");
 const sql_1 = require("../sql");
 const run_1 = require("../run");
@@ -39,14 +39,20 @@ function Query(arg) {
             (0, metadata_1.setMethodLabels)(_target, prop, { source: { kind: 'inline', sql: options.sql } });
         }
         else {
-            // FS-based resolution: only an EXPLICIT path argument pins a directory.
-            // Bare @Query() resolves through the active resolver (or the default
-            // SourceScanResolver) — no stack-based directory guessing, which breaks
-            // under bundlers and test transforms.
+            // An EXPLICIT path argument pins a filesystem directory. Bare @Query()
+            // records the directory of the decorating module (first non-sqlstack
+            // stack frame at decoration time); at call time that directory is
+            // resolved against the packaged resources map when one is installed
+            // (SqlStack.useResources), else read from the filesystem. No tree scan.
             const { rootDir } = (0, fileResolution_1.coerceRootPath)(rootArg);
             if (rootDir) {
                 (0, metadata_1.setMethodLabels)(_target, prop, { source: { kind: 'fs', rootDir } });
             }
+            else {
+                const dir = (0, fileResolution_1.guessDecoratorDir)();
+                if (dir)
+                    (0, metadata_1.setMethodLabels)(_target, prop, { source: { kind: 'guess', dir } });
+            }
         }
         // Record for resolver coverage checks: immutable class metadata (the
         // canonical, environment-local source) plus the deprecated global list
@@ -83,26 +89,25 @@ function Query(arg) {
                 }
                 const db = target.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)
+                // 3) load SQL source: inline; else an installed resolver (the
+                //    instance's, else the process-global one — a build-time manifest
+                //    registered by a host runner applies even when the SqlStack itself
+                //    came from an IoC root); else the decorator's directory (explicit
+                //    path or guessed module dir) against the packaged resources /
+                //    filesystem.
+                const className = this?.constructor?.name ?? '<anonymous>';
+                const resolver = activeResolver ?? (0, resolver_1.getActiveResolver)();
                 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'
-                            ? (0, fileResolution_1.resolveSqlFromFs)(labels.source.rootDir, String(prop), dialect).sql
-                            : (0, sourceScanResolver_1.defaultSourceScanResolver)()?.resolve({
-                                className: this?.constructor?.name ?? '<anonymous>',
-                                methodName: String(prop),
-                                dialect,
-                            });
+                    : (resolver?.resolve({
+                        className,
+                        methodName: String(prop),
+                        dialect,
+                        rootDir: labels?.source?.kind === 'fs' ? labels.source.rootDir : undefined,
+                    }) ?? resolveSourceSql(labels?.source, className, String(prop), dialect));
                 if (!sql) {
-                    throw new errors_1.SqlStackError(`No SQL source provided for method ${String(prop)}. Use @Query() with a file/folder path or inline sql.`);
+                    throw new errors_1.SqlStackError(`No SQL source for ${className}.${String(prop)}: the decorating module's directory could not be ` +
+                        'determined from the stack. Use @Query() with a file/folder path or inline sql.');
                 }
                 onSql(sql);
                 // 4) bind placeholders
@@ -314,11 +319,43 @@ function Query(arg) {
                 const resolved = await (0, runtime_1.resolveExecution)(dbName);
                 return {
                     db: resolved.entry.db,
-                    tx: (0, transactions_1.getActiveTransaction)(resolved.entry),
+                    tx: (0, transactions_1.getTransactionTarget)(resolved.entry),
                     resolver: resolved.resolver,
                     byName: true,
                 };
             };
+            // The method's own leading database argument: a handle (object with
+            // query()) or a registered database name. It selects run()'s target
+            // and is never bound as a value.
+            const leadingDb = async () => {
+                if (callArgs.length === 0)
+                    return undefined;
+                const first = callArgs[0];
+                if ((0, run_1.isRunDatabaseHandle)(first))
+                    return first;
+                if (typeof first === 'string' && first.length > 0 && (await (0, runtime_1.isRegisteredDatabaseName)(first)))
+                    return first;
+                return undefined;
+            };
+            // A database chosen by run's argument or the method's leading argument.
+            const explicitTarget = async (db) => {
+                const target = await (0, run_1.resolveRunTarget)(db);
+                // Inline SQL needs no resolver; only look one up for file-based SQL.
+                const resolver = target.byName
+                    ? target.resolver
+                    : labels?.source?.kind === 'inline'
+                        ? undefined
+                        : await (0, runtime_1.resolveSqlResolver)();
+                return { target, resolver };
+            };
+            // run() (and the legacy fallback): the method's arguments minus a
+            // leading database, on that database or the decorator context.
+            const executeDefault = async (onSql) => {
+                const lead = await leadingDb();
+                if (lead === undefined)
+                    return executeMethodSql(callArgs, undefined, onSql);
+                return executeMethodSql(callArgs.slice(1), await explicitTarget(lead), onSql);
+            };
             // run's argument-taking forms: return the adapter's raw result.
             const executeInvocation = async (invocation, onSql) => {
                 if (invocation.kind === 'fragment') {
@@ -330,17 +367,19 @@ function Query(arg) {
                     onSql(boundSql);
                     return (0, run_1.executeOnTarget)(target, boundSql, params);
                 }
-                // run(db, params): the method's own SQL against db, bound from params
-                // only (an object for :named, an array for :argN).
-                const target = await (0, run_1.resolveRunTarget)(invocation.db);
-                // Inline SQL needs no resolver; only look one up for file-based SQL.
-                const resolver = target.byName
-                    ? target.resolver
-                    : labels?.source?.kind === 'inline'
-                        ? undefined
-                        : await (0, runtime_1.resolveSqlResolver)();
+                if (invocation.kind === 'db') {
+                    // run(db): the method's own SQL against db, bound from the method's
+                    // arguments minus a leading database argument.
+                    const lead = await leadingDb();
+                    const bindArgs = lead === undefined ? callArgs : callArgs.slice(1);
+                    return executeMethodSql(bindArgs, await explicitTarget(invocation.db), onSql);
+                }
+                // run(db, params) / run(params): the method's own SQL bound from params
+                // only (an object for :named, an array for :argN), against run's db,
+                // else the method's leading database, else the decorator context.
                 const bindArgs = Array.isArray(invocation.params) ? [...invocation.params] : [invocation.params];
-                return executeMethodSql(bindArgs, { target, resolver }, onSql);
+                const db = invocation.db ?? (await leadingDb());
+                return executeMethodSql(bindArgs, db !== undefined ? await explicitTarget(db) : undefined, onSql);
             };
             // The full pipeline: execute, then — if rows were returned
             // (SELECT/CTE/RETURNING) — shape + transform + validate; a write result
@@ -352,7 +391,7 @@ function Query(arg) {
             // DatabaseError with the original error in `.cause`.
             const pipeline = async (invocation) => {
                 if (invocation === undefined || invocation.kind === 'default') {
-                    const out = await executeMethodSql(callArgs, undefined, () => { });
+                    const out = await executeDefault(() => { });
                     return finishResult(out, labels, this, prop);
                 }
                 let sqlText = invocation.kind === 'fragment' ? (0, run_1.fragmentText)(invocation.fragment) : '';
@@ -396,7 +435,7 @@ function Query(arg) {
                 const db = entry.db;
                 let out;
                 try {
-                    const tx = (0, transactions_1.getActiveTransaction)(entry);
+                    const tx = (0, transactions_1.getTransactionTarget)(entry);
                     out = tx ? await tx.query(boundSql, params) : await db.query(boundSql, params);
                 }
                 catch (dbError) {
@@ -409,6 +448,28 @@ function Query(arg) {
         return desc;
     };
 }
+// Directory-based SQL for a decorated method. An explicit @Query('<path>')
+// is always the filesystem. A bare @Query() uses the packaged resources map
+// when one is installed (bundled/packaged runtimes), else the filesystem next
+// to the decorating module (tests, plain Node). Misses name every key tried.
+function resolveSourceSql(source, className, methodName, dialect) {
+    if (!source || source.kind === 'inline')
+        return undefined;
+    if (source.kind === 'fs')
+        return (0, fileResolution_1.resolveSqlFromFs)(source.rootDir, methodName, dialect).sql;
+    const packaged = (0, resources_1.getResources)();
+    const fromResources = packaged ? (0, resources_1.resolveSqlFromResources)(source.dir, methodName, dialect) : undefined;
+    if (fromResources?.sql !== undefined)
+        return fromResources.sql;
+    try {
+        return (0, fileResolution_1.resolveSqlFromFs)(source.dir, methodName, dialect).sql;
+    }
+    catch (fsError) {
+        const triedResources = fromResources ? `\npackaged resources tried:\n${fromResources.tried.join('\n')}` : '';
+        throw new errors_1.SqlStackError(`sqlstack: no SQL for ${className}.${methodName}.${triedResources}\n` +
+            `${fsError?.message ?? String(fsError)}`);
+    }
+}
 // Deprecated (removal in the next major version): a @Query body that RETURNS
 // an sql`` fragment. It only type-checks when the method's declared return
 // type is bent to admit SqlFragment (an `as any`-style hole). One warning per