@onreza/sqlx-js 0.3.0 → 0.5.0

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";
+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 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): QueryCallSite[];
-export declare function scanProject(root: 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"]);
+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 SQLX_MODULES = new Set(["@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,7 +125,7 @@ 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" };
         }
     }
@@ -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,8 +323,8 @@ 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))

package/dist/src/typed.d.ts

@@ -4,17 +4,27 @@ type ParamsOf<T> = T extends {
 type RowOf<T> = T extends {
     row: infer R;
 } ? R : never;
+type ExecuteResult = import("./runtime.js").ExecuteResult;
+type JsonInputValue = import("./runtime.js").JsonInputValue;
+type JsonParameter<T> = import("./runtime.js").JsonParameter<T>;
+type PgArrayParameter<T> = import("./runtime.js").PgArrayParameter<T>;
+type JsonFn = <T extends JsonInputValue>(value: T) => JsonParameter<T>;
+type ArrayFn = <T>(value: readonly (T | null)[]) => PgArrayParameter<T>;
 export type TypedFile<TFileQueries> = {
     <P extends keyof TFileQueries>(path: P, ...params: ParamsOf<TFileQueries[P]>): Promise<RowOf<TFileQueries[P]>[]>;
     one: <P extends keyof TFileQueries>(path: P, ...params: ParamsOf<TFileQueries[P]>) => Promise<RowOf<TFileQueries[P]>>;
     optional: <P extends keyof TFileQueries>(path: P, ...params: ParamsOf<TFileQueries[P]>) => Promise<RowOf<TFileQueries[P]> | null>;
+    execute: <P extends keyof TFileQueries>(path: P, ...params: ParamsOf<TFileQueries[P]>) => Promise<ExecuteResult>;
 };
 export type TypedSql<TQueries, TFileQueries> = {
     <Q extends keyof TQueries>(query: Q, ...params: ParamsOf<TQueries[Q]>): Promise<RowOf<TQueries[Q]>[]>;
     one: <Q extends keyof TQueries>(query: Q, ...params: ParamsOf<TQueries[Q]>) => Promise<RowOf<TQueries[Q]>>;
     optional: <Q extends keyof TQueries>(query: Q, ...params: ParamsOf<TQueries[Q]>) => Promise<RowOf<TQueries[Q]> | null>;
+    execute: <Q extends keyof TQueries>(query: Q, ...params: ParamsOf<TQueries[Q]>) => Promise<ExecuteResult>;
     file: TypedFile<TFileQueries>;
     id: (...parts: string[]) => string;
+    json: JsonFn;
+    array: ArrayFn;
 };
 export type Typed<TQueries, TFileQueries, TTransactionOptions> = TypedSql<TQueries, TFileQueries> & {
     transaction: {

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@onreza/sqlx-js",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Compile-time-checked raw SQL for TypeScript + PostgreSQL. Inspired by sqlx.",
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=18"
+    "node": ">=24",
+    "bun": ">=1.3"
   },
   "sideEffects": false,
   "main": "./dist/src/index.js",
@@ -49,13 +50,13 @@
     "migrations"
   ],
   "scripts": {
-    "prepare": "(test -f dist/bin/sqlx-js.js || bun run build) && ([ ! -d .git ] || lefthook install >/dev/null 2>&1 || true)",
-    "test": "bun test tests",
+    "prepare": "node scripts/prepare-package.mjs",
+    "test": "bun test tests --timeout 120000",
     "test:typecheck": "tsc --noEmit",
     "test:example": "bunx tsc -p example --noEmit",
     "sqlx:prepare": "bun bin/sqlx-js.ts prepare",
     "sqlx:migrate": "bun bin/sqlx-js.ts migrate",
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && bun scripts/fix-dist-imports.ts",
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && bun scripts/fix-dist-imports.ts",
     "prepack": "bun run build"
   },
   "peerDependencies": {