@onreza/sqlx-js 0.4.0 → 0.6.0

package/dist/src/postgres-runtime.js

@@ -1,28 +1,45 @@
 import postgres from "postgres";
-import { createSqlRuntime, encodeParam, encodePgArrayLiteral, parsePgArrayLiteral } from "./runtime.js";
+import { resolve } from "node:path";
+import { createSqlRuntime, encodePgArrayLiteral, isPrimitiveArrayElement, parameterKind, parsePgArrayLiteral, } from "./runtime.js";
 import { arrayElementOid, builtinArrayOids } from "./pg/oids.js";
 const HOOKS = Symbol.for("sqlx-js.hooks");
+function resolvedFileRoot(value) {
+    return resolve(value ?? process.env.SQLX_JS_FILE_ROOT ?? process.cwd());
+}
 class PostgresRuntimeClient {
     client;
     onQuery;
-    constructor(client, onQuery) {
+    prepare;
+    fileRoot;
+    constructor(client, onQuery, prepare = true, fileRoot = resolvedFileRoot()) {
         this.client = client;
         this.onQuery = onQuery;
+        this.prepare = prepare;
+        this.fileRoot = fileRoot;
     }
     async query(query, params) {
-        return await this.client.unsafe(query, params, { prepare: true });
+        return await this.client.unsafe(query, params, { prepare: this.prepare });
     }
     transformParam(param) {
-        const elementOid = postgresNativeArrayElementOid(param);
-        if (elementOid !== undefined)
-            return this.client.array(param, elementOid);
-        return encodeParam(param);
+        const kind = parameterKind(param);
+        if (kind === "json")
+            return this.client.json(param.value);
+        if (kind === "array") {
+            const value = [...param.value];
+            if (value.every(isPrimitiveArrayElement))
+                return encodePgArrayLiteral(value);
+            if (value.every((item) => item === null || parameterKind(item) === "json")) {
+                return this.client.array(value, 3807);
+            }
+            return this.client.array(value);
+        }
+        return param;
     }
     async transaction(fn) {
         if (!("begin" in this.client))
             throw new Error("sqlx-js.transaction: nested transactions are not supported");
         return await this.client.begin(async (tx) => {
-            return await fn(new PostgresRuntimeClient(tx, this.onQuery));
+            return await fn(new PostgresRuntimeClient(tx, this.onQuery, this.prepare, this.fileRoot));
         });
     }
     async close() {
@@ -74,6 +91,7 @@ const STRING_ARRAY_ELEMENT_OIDS = new Set([
     4451,
     4536,
 ]);
+const JSON_ELEMENT_OIDS = new Set([114, 3802]);
 function parseSimpleArrayElement(oid) {
     switch (oid) {
         case 16:
@@ -90,28 +108,21 @@ function parseSimpleArrayElement(oid) {
             return STRING_ARRAY_ELEMENT_OIDS.has(oid) ? (value) => value : undefined;
     }
 }
-function postgresNativeArrayElementOid(value) {
-    if (!Array.isArray(value) || value.length === 0)
-        return undefined;
-    let oid;
-    for (const item of value) {
-        if (item === null)
-            continue;
-        const itemOid = item instanceof Uint8Array ? 17 : undefined;
-        if (itemOid === undefined)
-            return undefined;
-        if (oid !== undefined && oid !== itemOid)
-            return undefined;
-        oid = itemOid;
-    }
-    return oid;
-}
 function postgresTypes() {
     const types = { bigint: postgres.BigInt };
     for (const oid of builtinArrayOids()) {
         const elementOid = arrayElementOid(oid);
         if (elementOid === undefined)
             continue;
+        if (JSON_ELEMENT_OIDS.has(elementOid)) {
+            types[`array_${oid}`] = {
+                to: oid,
+                from: [oid],
+                serialize: (value) => Array.isArray(value) ? encodePgArrayLiteral(value) : String(value),
+                parse: (value) => parsePgArrayLiteral(value, JSON.parse),
+            };
+            continue;
+        }
         const parseElement = parseSimpleArrayElement(elementOid);
         if (!parseElement)
             continue;
@@ -124,10 +135,30 @@ function postgresTypes() {
     }
     return types;
 }
+function typeOids(value) {
+    if (value === null || value === undefined)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+function installJsonArrayCodecs(client) {
+    const options = client.options;
+    options.parsers ??= {};
+    options.serializers ??= {};
+    const configured = Object.values(options.types ?? {});
+    for (const oid of [199, 3807]) {
+        const hasParser = configured.some((type) => typeOids(type.from).includes(oid));
+        const hasSerializer = configured.some((type) => type.to === oid);
+        if (!hasParser)
+            options.parsers[oid] = (value) => parsePgArrayLiteral(value, JSON.parse);
+        if (!hasSerializer) {
+            options.serializers[oid] = (value) => Array.isArray(value) ? encodePgArrayLiteral(value) : String(value);
+        }
+    }
+}
 export function createClient(url = process.env.DATABASE_URL, options = {}) {
     if (!url)
         throw new Error("sqlx-js: DATABASE_URL is not set");
-    const { onQuery, statementTimeoutMs, ...pgOptions } = options;
+    const { onQuery, statementTimeoutMs, fileRoot, ...pgOptions } = options;
     const connection = statementTimeoutMs !== undefined
         ? { ...(pgOptions.connection ?? {}), statement_timeout: statementTimeoutMs }
         : pgOptions.connection;
@@ -136,12 +167,17 @@ export function createClient(url = process.env.DATABASE_URL, options = {}) {
         ...(connection ? { connection } : {}),
         types: { ...postgresTypes(), ...(pgOptions.types ?? {}) },
     });
-    if (onQuery)
-        client[HOOKS] = { onQuery };
+    client[HOOKS] = {
+        onQuery,
+        prepare: pgOptions.prepare ?? true,
+        fileRoot: resolvedFileRoot(fileRoot),
+    };
     return client;
 }
 function createDefaultClient() {
-    return new PostgresRuntimeClient(createClient());
+    const client = createClient();
+    const attached = client[HOOKS];
+    return new PostgresRuntimeClient(client, attached.onQuery, attached.prepare, attached.fileRoot);
 }
 function getRuntimeClient() {
     defaultClient ??= createDefaultClient();
@@ -151,8 +187,9 @@ export function getClient() {
     return getRuntimeClient().client;
 }
 export function setClient(client, options) {
+    installJsonArrayCodecs(client);
     const attached = client[HOOKS];
-    defaultClient = new PostgresRuntimeClient(client, options?.onQuery ?? attached?.onQuery);
+    defaultClient = new PostgresRuntimeClient(client, options?.onQuery ?? attached?.onQuery, options?.prepare ?? attached?.prepare ?? client.options?.prepare ?? true, resolvedFileRoot(options?.fileRoot ?? attached?.fileRoot));
 }
 export async function close() {
     if (defaultClient) {

package/dist/src/runtime.d.ts

@@ -7,19 +7,47 @@ export type OnQueryEvent = {
     error?: unknown;
 };
 export type OnQueryHook = (event: OnQueryEvent) => void;
+export type RuntimeQueryResult = unknown[] & {
+    count?: number | null;
+    command?: string | null;
+};
 export type RuntimeClient = {
-    query: (query: string, params: unknown[]) => Promise<unknown[]>;
+    query: (query: string, params: unknown[]) => Promise<RuntimeQueryResult>;
     transformParam?: (param: unknown) => unknown;
     transaction: <R>(fn: (client: RuntimeClient) => Promise<R>) => Promise<R>;
     close: () => Promise<void>;
     onQuery?: OnQueryHook;
+    fileRoot?: string;
 };
 type AnyFn = (...args: unknown[]) => Promise<unknown[]>;
 type AnyOneFn = (...args: unknown[]) => Promise<unknown>;
 type AnyOptionalFn = (...args: unknown[]) => Promise<unknown | null>;
+type AnyExecuteFn = (...args: unknown[]) => Promise<ExecuteResult>;
 type IdentifierFn = (...parts: string[]) => string;
+declare const PARAMETER_KIND: unique symbol;
+export type JsonParameter<T = JsonInputValue> = {
+    readonly [PARAMETER_KIND]: "json";
+    readonly value: T;
+};
+export type PgArrayParameter<T = unknown> = {
+    readonly [PARAMETER_KIND]: "array";
+    readonly value: readonly (T | null)[];
+};
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonInputValue = JsonPrimitive | JsonInputObject | JsonInputArray;
+export type JsonInputObject = {
+    readonly [key: string]: JsonInputValue | undefined;
+};
+export type JsonInputArray = readonly JsonInputValue[];
+export type ExecuteResult = {
+    rowCount: number;
+    command: string;
+};
+export declare function json<T extends JsonInputValue>(value: T): JsonParameter<T>;
+export declare function array<T>(value: readonly (T | null)[]): PgArrayParameter<T>;
+export declare function parameterKind(value: unknown): "json" | "array" | undefined;
 declare function renameRows(rows: unknown[]): unknown[];
-declare function isPrimitiveArrayElement(v: unknown): boolean;
+export declare function isPrimitiveArrayElement(v: unknown): boolean;
 export declare function encodePgArrayLiteral(arr: unknown[]): string;
 type PgArrayValue<T> = T | null | PgArrayValue<T>[];
 export declare function parsePgArrayLiteral<T = string>(input: string, parseElement?: (value: string) => T): PgArrayValue<T>[];
@@ -40,21 +68,26 @@ export declare const _internal: {
     loadSqlFile: typeof loadSqlFile;
     buildSetTransaction: typeof buildSetTransaction;
     clearIdentifierCache: typeof clearIdentifierCache;
+    parameterKind: typeof parameterKind;
     toPgError: typeof toPgError;
 };
-declare function loadSqlFile(path: string): string;
+declare function loadSqlFile(path: string, fileRoot?: string): string;
 export declare function clearSqlFileCache(): void;
 declare function clearIdentifierCache(): void;
 export declare function id(...parts: string[]): string;
 type FileCallable = AnyFn & {
     one: AnyOneFn;
     optional: AnyOptionalFn;
+    execute: AnyExecuteFn;
 };
 type SqlCallable = AnyFn & {
     file: FileCallable;
     one: AnyOneFn;
     optional: AnyOptionalFn;
+    execute: AnyExecuteFn;
     id: IdentifierFn;
+    json: typeof json;
+    array: typeof array;
 };
 export type TransactionOptions = {
     isolation?: "read uncommitted" | "read committed" | "repeatable read" | "serializable";

package/dist/src/runtime.js

@@ -1,7 +1,19 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
 import { PgClient, parseDatabaseUrl, PgError } from "./pg/wire.js";
-import { applyPending, acquireMigrateLock, releaseMigrateLock, DEFAULT_MIGRATE_LOCK_KEY } from "./commands/migrate.js";
+import { applyPending, acquireMigrateLock, releaseMigrateLock, DEFAULT_MIGRATE_LOCK_KEY } from "./migration-core.js";
+const PARAMETER_KIND = Symbol("sqlx-js.parameter");
+export function json(value) {
+    return { [PARAMETER_KIND]: "json", value };
+}
+export function array(value) {
+    return { [PARAMETER_KIND]: "array", value };
+}
+export function parameterKind(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    return value[PARAMETER_KIND];
+}
 const SUFFIX = /[!?]$/;
 function renameRows(rows) {
     if (rows.length === 0)
@@ -28,9 +40,11 @@ function renameRows(rows) {
     }
     return out;
 }
-function isPrimitiveArrayElement(v) {
+export function isPrimitiveArrayElement(v) {
     if (v === null || v === undefined)
         return true;
+    if (v instanceof Date || v instanceof Uint8Array)
+        return true;
     const t = typeof v;
     return t === "string" || t === "number" || t === "bigint" || t === "boolean";
 }
@@ -44,6 +58,18 @@ export function encodePgArrayLiteral(arr) {
             parts.push("NULL");
             continue;
         }
+        if (parameterKind(v) === "json") {
+            parts.push(quoteArrayElement(JSON.stringify(v.value)));
+            continue;
+        }
+        if (v instanceof Date) {
+            parts.push(quoteArrayElement(v.toISOString()));
+            continue;
+        }
+        if (v instanceof Uint8Array) {
+            parts.push(quoteArrayElement(`\\x${Buffer.from(v).toString("hex")}`));
+            continue;
+        }
         if (typeof v === "bigint") {
             parts.push(v.toString());
             continue;
@@ -126,13 +152,12 @@ export function parsePgArrayLiteral(input, parseElement = (value) => value) {
     return parsed;
 }
 export function encodeParam(p) {
-    if (!Array.isArray(p))
-        return p;
-    if (p.length === 0)
-        return p;
-    if (!p.every(isPrimitiveArrayElement))
-        return p;
-    return encodePgArrayLiteral(p);
+    const kind = parameterKind(p);
+    if (kind === "json")
+        return JSON.stringify(p.value);
+    if (kind === "array")
+        return encodePgArrayLiteral([...p.value]);
+    return p;
 }
 export class NoRowsError extends Error {
     constructor(message = "expected exactly 1 row, got 0") {
@@ -213,16 +238,17 @@ export const _internal = {
     loadSqlFile,
     buildSetTransaction,
     clearIdentifierCache,
+    parameterKind,
     toPgError,
 };
-async function runQuery(client, query, params) {
+async function runRawQuery(client, query, params) {
     const encoded = params.length === 0
         ? params
         : params.map((p) => client.transformParam ? client.transformParam(p) : encodeParam(p));
     const onQuery = client.onQuery;
     if (!onQuery) {
         try {
-            return renameRows(await client.query(query, encoded));
+            return await client.query(query, encoded);
         }
         catch (e) {
             throw toPgError(e) ?? e;
@@ -230,9 +256,14 @@ async function runQuery(client, query, params) {
     }
     const start = performance.now();
     try {
-        const rows = await client.query(query, encoded);
-        onQuery({ query, params, durationMs: performance.now() - start, rowCount: rows.length });
-        return renameRows(rows);
+        const result = await client.query(query, encoded);
+        onQuery({
+            query,
+            params,
+            durationMs: performance.now() - start,
+            rowCount: result.count ?? result.length,
+        });
+        return result;
     }
     catch (e) {
         const error = toPgError(e) ?? e;
@@ -240,6 +271,16 @@ async function runQuery(client, query, params) {
         throw error;
     }
 }
+async function runQuery(client, query, params) {
+    return renameRows(await runRawQuery(client, query, params));
+}
+async function runExecute(client, query, params) {
+    const result = await runRawQuery(client, query, params);
+    return {
+        rowCount: result.count ?? result.length,
+        command: result.command ?? "",
+    };
+}
 async function runOne(client, query, params) {
     const rows = await runQuery(client, query, params);
     if (rows.length === 1)
@@ -257,8 +298,16 @@ async function runOptional(client, query, params) {
     throw new TooManyRowsError(rows.length, "0 or 1");
 }
 const sqlFileCache = new Map();
-function loadSqlFile(path) {
-    const full = resolve(process.cwd(), path);
+function loadSqlFile(path, fileRoot = process.env.SQLX_JS_FILE_ROOT ?? process.cwd()) {
+    const root = resolve(fileRoot);
+    if (isAbsolute(path)) {
+        throw new Error(`sqlx-js.sql.file: path must be relative to fileRoot: ${path}`);
+    }
+    const full = resolve(root, path);
+    const rel = relative(root, full);
+    if (rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(rel)) {
+        throw new Error(`sqlx-js.sql.file: path escapes fileRoot: ${path}`);
+    }
     try {
         const st = statSync(full);
         const cached = sqlFileCache.get(full);
@@ -393,13 +442,16 @@ function makeBoundCallable(client) {
         return runQuery(client, query, params);
     });
     const file = (async (path, ...params) => {
-        return runQuery(client, loadSqlFile(path), params);
+        return runQuery(client, loadSqlFile(path, client.fileRoot), params);
     });
     file.one = (async (path, ...params) => {
-        return runOne(client, loadSqlFile(path), params);
+        return runOne(client, loadSqlFile(path, client.fileRoot), params);
     });
     file.optional = (async (path, ...params) => {
-        return runOptional(client, loadSqlFile(path), params);
+        return runOptional(client, loadSqlFile(path, client.fileRoot), params);
+    });
+    file.execute = (async (path, ...params) => {
+        return runExecute(client, loadSqlFile(path, client.fileRoot), params);
     });
     fn.file = file;
     fn.one = (async (query, ...params) => {
@@ -408,7 +460,12 @@ function makeBoundCallable(client) {
     fn.optional = (async (query, ...params) => {
         return runOptional(client, query, params);
     });
+    fn.execute = (async (query, ...params) => {
+        return runExecute(client, query, params);
+    });
     fn.id = id;
+    fn.json = json;
+    fn.array = array;
     return fn;
 }
 function buildSetTransaction(opts) {
@@ -428,13 +485,20 @@ export function createSqlRuntime(getClient) {
         return runQuery(getClient(), query, params);
     });
     const rootFile = (async (path, ...params) => {
-        return runQuery(getClient(), loadSqlFile(path), params);
+        const client = getClient();
+        return runQuery(client, loadSqlFile(path, client.fileRoot), params);
     });
     rootFile.one = (async (path, ...params) => {
-        return runOne(getClient(), loadSqlFile(path), params);
+        const client = getClient();
+        return runOne(client, loadSqlFile(path, client.fileRoot), params);
     });
     rootFile.optional = (async (path, ...params) => {
-        return runOptional(getClient(), loadSqlFile(path), params);
+        const client = getClient();
+        return runOptional(client, loadSqlFile(path, client.fileRoot), params);
+    });
+    rootFile.execute = (async (path, ...params) => {
+        const client = getClient();
+        return runExecute(client, loadSqlFile(path, client.fileRoot), params);
     });
     root.file = rootFile;
     root.one = (async (query, ...params) => {
@@ -443,7 +507,12 @@ export function createSqlRuntime(getClient) {
     root.optional = (async (query, ...params) => {
         return runOptional(getClient(), query, params);
     });
+    root.execute = (async (query, ...params) => {
+        return runExecute(getClient(), query, params);
+    });
     root.id = id;
+    root.json = json;
+    root.array = array;
     root.transaction = (async (fnOrOpts, maybeFn) => {
         const c = getClient();
         let opts = {};

package/dist/src/scan/scanner.d.ts

@@ -1,3 +1,4 @@
+import type { ScanConfig } from "../config.js";
 export type QueryCallSite = {
     file: string;
     line: number;
@@ -7,6 +8,12 @@ export type QueryCallSite = {
     kind: "inline" | "file";
     sqlFilePath?: string;
 };
-export declare function findSourceFiles(root: string): string[];
-export declare function scanFile(absPath: string, root: string): QueryCallSite[];
-export declare function scanProject(root: string): QueryCallSite[];
+export declare class ScanError extends Error {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+    constructor(file: string, line: number, column: number, message: string);
+}
+export declare function findSourceFiles(root: string, scan?: ScanConfig): string[];
+export declare function scanFile(absPath: string, root: string, modules?: readonly string[]): QueryCallSite[];
+export declare function scanProject(root: string, scan?: ScanConfig): QueryCallSite[];

package/dist/src/scan/scanner.js

@@ -1,25 +1,67 @@
 import ts from "typescript";
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
-const EXCLUDE_DIRS = new Set(["node_modules", ".git", ".sqlx-js", "dist", "build", ".next"]);
-const SQLX_MODULES = new Set(["@onreza/sqlx-js"]);
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+export class ScanError extends Error {
+    file;
+    line;
+    column;
+    constructor(file, line, column, message) {
+        super(`sqlx-js: ${file}:${line}:${column} — ${message}`);
+        this.file = file;
+        this.line = line;
+        this.column = column;
+        this.name = "ScanError";
+    }
+}
+const DEFAULT_EXCLUDES = [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/.sqlx-js/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+];
+const DEFAULT_SQLX_MODULES = ["@onreza/sqlx-js"];
 const EXT = /\.(ts|tsx|mts|cts)$/;
-function walk(dir, out) {
-    for (const name of readdirSync(dir)) {
-        if (EXCLUDE_DIRS.has(name))
-            continue;
-        const full = join(dir, name);
-        const st = statSync(full);
-        if (st.isDirectory())
-            walk(full, out);
-        else if (EXT.test(name))
-            out.push(full);
+const TS_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts"];
+function formatConfigError(error) {
+    return ts.flattenDiagnosticMessageText(error.messageText, "\n");
+}
+function collectTsconfigFiles(configPath, out, visited) {
+    const resolved = resolve(configPath);
+    if (visited.has(resolved))
+        return;
+    visited.add(resolved);
+    const read = ts.readConfigFile(resolved, ts.sys.readFile);
+    if (read.error)
+        throw new Error(`sqlx-js scan: ${resolved}: ${formatConfigError(read.error)}`);
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, resolve(resolved, ".."), undefined, resolved);
+    if (parsed.errors.length > 0) {
+        throw new Error(`sqlx-js scan: ${resolved}: ${parsed.errors.map(formatConfigError).join("; ")}`);
+    }
+    for (const file of parsed.fileNames) {
+        if (EXT.test(file))
+            out.add(resolve(file));
+    }
+    for (const reference of parsed.projectReferences ?? []) {
+        collectTsconfigFiles(ts.resolveProjectReferencePath(reference), out, visited);
     }
 }
-export function findSourceFiles(root) {
-    const out = [];
-    walk(root, out);
-    return out;
+export function findSourceFiles(root, scan = {}) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(scan.exclude ?? [])];
+    if (scan.include !== undefined) {
+        if (scan.include.length === 0)
+            return [];
+        return ts.sys.readDirectory(root, TS_EXTENSIONS, excludes, scan.include).map((file) => resolve(file)).sort();
+    }
+    const configPath = join(root, "tsconfig.json");
+    if (!ts.sys.fileExists(configPath)) {
+        return ts.sys.readDirectory(root, TS_EXTENSIONS, excludes, ["**/*"]).map((file) => resolve(file)).sort();
+    }
+    const configured = new Set();
+    collectTsconfigFiles(configPath, configured, new Set());
+    const allowed = new Set(ts.sys.readDirectory(root, TS_EXTENSIONS, excludes, ["**/*"]).map((file) => resolve(file)));
+    return [...configured].filter((file) => allowed.has(file)).sort();
 }
 function classifyCallee(callee, scope) {
     if (ts.isIdentifier(callee)) {
@@ -45,7 +87,7 @@ function classifyCallee(callee, scope) {
             return { kind: "transaction" };
         if (methodName === "file")
             return { kind: "file" };
-        if (methodName === "one" || methodName === "optional")
+        if (methodName === "one" || methodName === "optional" || methodName === "execute")
             return { kind: "inline" };
         return null;
     }
@@ -57,7 +99,7 @@ function classifyCallee(callee, scope) {
         if (ts.isIdentifier(mid.expression) && scope.namespaces.has(mid.expression.text)) {
             if (mid.name.text !== "sql")
                 return null;
-            if (methodName === "one" || methodName === "optional")
+            if (methodName === "one" || methodName === "optional" || methodName === "execute")
                 return { kind: "inline" };
             if (methodName === "file")
                 return { kind: "file" };
@@ -72,7 +114,7 @@ function classifyCallee(callee, scope) {
                 return null;
             if (mid.name.text !== "file")
                 return null;
-            if (methodName === "one" || methodName === "optional")
+            if (methodName === "one" || methodName === "optional" || methodName === "execute")
                 return { kind: "file" };
             return null;
         }
@@ -83,13 +125,13 @@ function classifyCallee(callee, scope) {
             scope.namespaces.has(mid.expression.expression.text) &&
             mid.expression.name.text === "sql" &&
             mid.name.text === "file" &&
-            (methodName === "one" || methodName === "optional")) {
+            (methodName === "one" || methodName === "optional" || methodName === "execute")) {
             return { kind: "file" };
         }
     }
     return null;
 }
-export function scanFile(absPath, root) {
+export function scanFile(absPath, root, modules = DEFAULT_SQLX_MODULES) {
     const text = readFileSync(absPath, "utf8");
     const source = ts.createSourceFile(absPath, text, ts.ScriptTarget.ESNext, false, ts.ScriptKind.TSX);
     const importedAliases = new Set();
@@ -100,7 +142,7 @@ export function scanFile(absPath, root) {
         const mod = stmt.moduleSpecifier;
         if (!ts.isStringLiteral(mod))
             continue;
-        if (!SQLX_MODULES.has(mod.text))
+        if (!modules.includes(mod.text))
             continue;
         const ic = stmt.importClause;
         if (!ic)
@@ -130,7 +172,7 @@ export function scanFile(absPath, root) {
     const recordInline = (first, args) => {
         if (!ts.isStringLiteralLike(first)) {
             const pos = here(first);
-            throw new Error(`sqlx-js: ${fileRel}:${pos.line}:${pos.column} — sql() requires a string literal as first argument`);
+            throw new ScanError(fileRel, pos.line, pos.column, "sql() requires a string literal as first argument");
         }
         const pos = here(first);
         out.push({
@@ -146,13 +188,22 @@ export function scanFile(absPath, root) {
     const recordFile = (first, args, callee) => {
         if (!ts.isStringLiteralLike(first)) {
             const pos = first ? here(first) : here(callee);
-            throw new Error(`sqlx-js: ${fileRel}:${pos.line}:${pos.column} — sql.file() requires a string literal path`);
+            throw new ScanError(fileRel, pos.line, pos.column, "sql.file() requires a string literal path");
         }
         const sqlPath = first.text;
-        const abs = resolve(dirname(absPath), sqlPath);
+        if (isAbsolute(sqlPath)) {
+            const pos = here(first);
+            throw new ScanError(fileRel, pos.line, pos.column, `sql.file path must be relative to --root: ${sqlPath}`);
+        }
+        const abs = resolve(root, sqlPath);
+        const rel = relative(root, abs);
+        if (rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(rel)) {
+            const pos = here(first);
+            throw new ScanError(fileRel, pos.line, pos.column, `sql.file path escapes --root: ${sqlPath}`);
+        }
         if (!existsSync(abs)) {
             const pos = here(first);
-            throw new Error(`sqlx-js: ${fileRel}:${pos.line}:${pos.column} — sql.file path not found: ${sqlPath}`);
+            throw new ScanError(fileRel, pos.line, pos.column, `sql.file path not found: ${sqlPath}`);
         }
         const query = readFileSync(abs, "utf8");
         const pos = here(first);
@@ -163,7 +214,7 @@ export function scanFile(absPath, root) {
             query,
             paramCount: args.length - 1,
             kind: "file",
-            sqlFilePath: relative(root, abs),
+            sqlFilePath: sqlPath,
         });
         return true;
     };
@@ -272,11 +323,11 @@ export function scanFile(absPath, root) {
     visit(source, { sqlAliases: importedAliases, namespaces: importedNamespaces });
     return out;
 }
-export function scanProject(root) {
-    const files = findSourceFiles(root);
+export function scanProject(root, scan = {}) {
+    const files = findSourceFiles(root, scan);
     const out = [];
     for (const f of files) {
-        for (const site of scanFile(f, root))
+        for (const site of scanFile(f, root, scan.modules ?? DEFAULT_SQLX_MODULES))
             out.push(site);
     }
     return out;

package/dist/src/type-inspection.d.ts

@@ -0,0 +1 @@
+export declare function containsUnknownType(type: string): boolean;