@possumtech/sqlrite 0.2.3 → 1.0.2

package/.github/ISSUE_TEMPLATE/build.md

@@ -0,0 +1,9 @@
+---
+name: build
+about: Build
+title: 'build: '
+labels: ['build']
+type: 'Task'
+---
+## Build
+What build task is being modified and why?

package/.github/ISSUE_TEMPLATE/chore.md

@@ -0,0 +1,9 @@
+---
+name: chore
+about: General
+title: 'chore: '
+labels: ['chore']
+type: 'Task'
+---
+## Chore
+What work is being done?

package/.github/ISSUE_TEMPLATE/ci.md

@@ -0,0 +1,9 @@
+---
+name: ci
+about: Continuous integration
+title: 'ci: '
+labels: ['ci']
+type: 'Task'
+---
+## Continuous integration
+What continuous integration task is being modified and why?

package/.github/ISSUE_TEMPLATE/docs.md

@@ -0,0 +1,9 @@
+---
+name: docs
+about: Documentation
+title: 'docs: '
+labels: ['docs']
+type: 'Task'
+---
+## Documentation
+What documentation is being modified?

package/.github/ISSUE_TEMPLATE/feat.md

@@ -0,0 +1,12 @@
+---
+name: feat
+about: New functionality for the project
+title: 'feat: '
+labels: ['feat']
+type: 'Feature'
+---
+## Problem
+Describe the need.
+
+## Solution
+Describe the change.

package/.github/ISSUE_TEMPLATE/fix.md

@@ -0,0 +1,12 @@
+---
+name: fix
+about: Fix a problem or error
+title: 'fix: '
+labels: ['fix']
+type: 'Bug'
+---
+## Behavior
+What is happening?
+
+## Expected
+What should happen?

package/.github/ISSUE_TEMPLATE/perf.md

@@ -0,0 +1,9 @@
+---
+name: perf
+about: Improvements to speed or resource usage
+title: 'perf: '
+labels: ['perf']
+type: 'Feature'
+---
+## Improvement
+What is being optimized?

package/.github/ISSUE_TEMPLATE/refactor.md

@@ -0,0 +1,9 @@
+---
+name: refactor
+about: Refactor
+title: 'refactor: '
+labels: ['refactor']
+type: 'Task'
+---
+## Refactor
+What's the purpose, scope, and nature of the refactor?

package/.github/ISSUE_TEMPLATE/revert.md

@@ -0,0 +1,9 @@
+---
+name: revert
+about: Revert
+title: 'revert: '
+labels: ['revert']
+type: 'Task'
+---
+## Revert
+What prior work is being reverted and why?

package/.github/ISSUE_TEMPLATE/style.md

@@ -0,0 +1,9 @@
+---
+name: style
+about: Style
+title: 'style: '
+labels: ['style']
+type: 'Task'
+---
+## Style
+What stylistic element is being modified and why?

package/.github/ISSUE_TEMPLATE/test.md

@@ -0,0 +1,9 @@
+---
+name: test
+about: Test
+title: 'test: '
+labels: ['test']
+type: 'Task'
+---
+## Testing
+What's being tested and how?

package/README.md

@@ -1,187 +1,149 @@
-# sqlrite
+# 🪨 SqlRite
 
-SQL Done Right
+[![npm version](https://img.shields.io/npm/v/@possumtech/sqlrite?color=brightgreen)](https://www.npmjs.com/package/@possumtech/sqlrite)
+[![license](https://img.shields.io/github/license/possumtech/sqlrite)](LICENSE)
+[![node version](https://img.shields.io/badge/node-%3E%3D25.0.0-blue)](https://nodejs.org)
 
-## About sqlrite
+**SQL Done Right.** A high-performance, opinionated, and LLM-ready wrapper for Node.js native SQLite.
 
-The sqlrite package is a modern node module that delivers an opinionated
-alternative to ORMs. It is a thin wrapper around the
-[native sqlite module](https://nodejs.org/api/sqlite.html), which
-enables one to separate SQL code from Javascript code.
+---
 
-## Opinions
+## 📖 About
 
-1. **SQL Supremacy**: Your application is data, and SQL is the best interface.
+SqlRite is a thin, zero-dependency wrapper around the [native Node.js `sqlite` module](https://nodejs.org/api/sqlite.html). It enforces a clean separation of concerns by treating SQL as a first-class citizen, enabling a development workflow that is faster, more secure, and optimized for modern AI coding assistants.
 
-2. **Standards**: Node is the standard for server-side web apps, and it now
-contains a native sqlite module. Sqlite is the standard for SQL.
+### Why SqlRite?
 
-3. **Simplicity**: It takes as much time to master an ORM as it would take to
-just master SQL, and with worse performance. For all but the most distributed,
-concurrent, and custom use cases, sqlite is the simple, correct choice.
+1.  **⚡ Zero-Config Prepared Statements**: Define SQL in `.sql` files; call them as native JS methods.
+2.  **🧵 True Non-Blocking I/O**: The default async model offloads all DB operations to a dedicated Worker Thread.
+3.  **📦 LLM-Ready Architecture**: By isolating SQL from JS boilerplate, you provide AI agents with a clean, high-signal "Source of Truth" for your data layer.
+4.  **🧩 Locality of Behavior**: Keep your SQL files right next to the JS logic that uses them.
+5.  **🚀 Modern Standards**: Built for Node 25+, ESM-native, and uses the latest `node:sqlite` primitives.
+6.  **🛡️ Production-Ready Defaults**: Automatically enables WAL mode, Foreign Key enforcement, and DML Strictness.
 
-4. **Security**: Inline SQL is insecure, unmaintainable, and error-prone.
+---
 
-5. **Speed**: By enforcing the use of prepared statements, sqlrite ensures that
-your queries are compiled and cached by the sqlite engine.
+## 🛠 Installation
 
-6. **Separation**: SQL code should be in separate SQL files rather than
-scattered throughout your JS codebase.
-
-7. **Size**: By relying on the native sqlite module, and nothing else, sqlrite
-won't bloat your project with unnecessary dependencies. This thing is *tiny*.
-
-## Usage
-
-**SQL**
-
-Add a `sql` folder to your project and include as many `.sql` files as you
-wish, with whatever folder structure you like. Sqlrite will automatically load
-them all.
-
-| Syntax              | Name                   | Description            |
-|---------------------|------------------------|------------------------|
-| `-- INIT: txName`   | Executed Transaction   | Executed transaction   |
-| `-- EXEC: txName`   | Executable Transaction | Executable transaction |
-| `-- PREP: stmtName` | Prepared Statements    | Prepared statement     |
-
-There are three types of "chunk" one can add to a `.sql` file:
-
-1. **INIT**: A transaction that is executed when the module is instantiated.
-This is where you should create your tables, for example.
-
-2. **EXEC**: A transaction that can be executed at any time. For example,
-	 dropping a table. This is where you should put your transactions that are
-	 not prepared statements, like maintaining your database.
-
-3. **PREP**: A prepared statement that can be executed at any time. This is
-where you should put your queries. After declaring a prepared statement, you can
-then run it with either the `.all({})`, `.get({})` or `.run({})` methods, as per
-the native sqlite API.
-
-| Method     | Description                                           |
-|------------|-------------------------------------------------------|
-| `.all({})` | Returns all rows that match the query.                |
-| `.get({})` | Returns the first row that matches the query.         |
-| `.run({})` | Executes the query and returns the (optional) result. |
-
-### Synchronous/Asynchronous
-
-The native sqlite module currently only supports synchronous operations. This
-can pose a performance issue in some common cases. Sqlrite addresses this by
-allowing one to run one's queries asynchronously by appending `.async`:
-
-For example, instead of:
-
-**Synchronous**
-
-```js
-console.log(sql.getPositions.all());
+```bash
+npm install @possumtech/sqlrite
 ```
 
-**Asynchronous**
+---
 
-```js
-sql.async.getPositions.all().then((positions) => console.log(positions));
-```
+## 🚀 Quick Start
 
+### 1. Define your SQL (`src/users.sql`)
 
-**Example SQL File**
+SqlRite uses simple metadata headers to turn SQL chunks into JS methods. We recommend using `STRICT` tables for maximum type safety.
 
 ```sql
--- INIT: createEmployeeTable
-BEGIN TRANSACTION;
-
-CREATE TABLE IF NOT EXISTS employees (
-	id INTEGER PRIMARY KEY AUTOINCREMENT,
-	name TEXT NOT NULL,
-	position TEXT NOT NULL,
-	salary REAL NOT NULL
-);
+-- INIT: createUsers
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  meta TEXT
+) STRICT;
+
+-- PREP: addUser
+INSERT INTO users (name, meta) VALUES ($name, $meta);
+
+-- PREP: getUserByName
+SELECT * FROM users WHERE name = $name;
+```
 
-END TRANSACTION;
+### 2. Use it in Javascript
 
--- EXEC: deleteTable
-BEGIN TRANSACTION;
+#### Asynchronous (Default - Recommended)
+Uses Worker Threads to keep your main event loop free.
 
-DROP TABLE IF EXISTS employees;
+```javascript
+import SqlRite from "@possumtech/sqlrite";
 
-END TRANSACTION;
+const sql = new SqlRite({ 
+  path: "data.db", 
+  dir: "src" 
+});
 
--- PREP: addEmployee
-INSERT INTO employees (name, position, salary)
-	VALUES ($name, $position, $salary);
+// PREP chunks expose .all(), .get(), and .run()
+// Objects/Arrays are automatically stringified for you!
+await sql.addUser.run({ 
+  name: "Alice", 
+  meta: { theme: "dark", preferences: [1, 2, 3] } 
+});
 
--- PREP: getPositions
-SELECT name, position FROM employees;
+const user = await sql.getUserByName.get({ name: "Alice" });
+console.log(JSON.parse(user.meta).theme); // Manual parse required for output
 
--- PREP: getHighestPaidEmployee
-SELECT name FROM employees ORDER BY salary DESC LIMIT 1;
+await sql.close();
 ```
 
-**Example Node File**
+#### Synchronous
+Ideal for CLI tools, migrations, or scripts.
 
-```js
-import SqlRite from "@possumtech/sqlrite";
+```javascript
+import { SqlRiteSync } from "@possumtech/sqlrite";
 
-const sql = new SqlRite();
+const sql = new SqlRiteSync({ dir: ["src", "migrations"] });
+const users = sql.getUserByName.all({ name: "Alice" });
+sql.close();
+```
 
-sql.addEmployee.run({ name: "John", position: "CEO", salary: 99999 });
-sql.addEmployee.run({ name: "Jane", position: "COO", salary: 49998 });
-sql.addEmployee.run({ name: "Jack", position: "CFO", salary: 49997 });
-sql.addEmployee.run({ name: "Jill", position: "CIO", salary: 49996 });
+---
 
-const employee = sql.getHighestPaidEmployee.get();
+## 🤖 LLM-Ready Architecture
 
-assert(employee?.name === "John", "The highest paid employee should be John");
+In the era of AI-assisted engineering, **Context is King**. 
 
-sql.async.getPositions.all().then((positions) => console.log(positions));
+SqlRite's "SQL-First" approach is specifically designed to maximize the effectiveness of LLMs (like Gemini, Claude, and GPT):
 
-console.log(`The highest paid employee is ${employee.name}.`);
+*   **High Signal-to-Noise**: When you feed a `.sql` file to an LLM, it sees 100% schema and logic, 0% Javascript boilerplate. This prevents "context contamination" and hallucination.
+*   **Schema Awareness**: Agents can instantly "understand" your entire database contract by reading the isolated SQL files, making them significantly better at generating correct queries.
+*   **Clean Diffs**: AI-generated refactors of your data layer stay within `.sql` files, keeping your JS history clean and your logic easier to audit.
 
-sql.deleteTable();
-```
+---
 
-## Installation
+## 💎 Features & Syntax
 
-1. Navigate to your project directory and run the following command:
+### Modern Defaults
 
-```bash
-npm install @possumtech/sqlrite
-```
+SqlRite automatically executes these PRAGMAs on every connection to ensure high performance and data integrity:
 
-2. Then create a `sql` directory in your project directory. This is where you
-will put your SQL files.
+*   **WAL Mode**: `PRAGMA journal_mode = WAL` enables concurrent readers and writers.
+*   **Foreign Keys**: `PRAGMA foreign_keys = ON` enforces relational constraints.
+*   **DML Strict Mode**: `PRAGMA dml_strict = ON` catches common SQL errors (like using double quotes for strings).
 
-```bash
-mkdir sql
-cd sql
-touch exampleFile.sql
-```
+### Metadata Headers
 
-## Configuration
+| Syntax | Name | Behavior |
+| :--- | :--- | :--- |
+| `-- INIT: name` | **Initializer** | Runs once automatically when `SqlRite` is instantiated. |
+| `-- EXEC: name` | **Transaction** | Exposes a method `sql.name()` for one-off SQL execution. |
+| `-- PREP: name` | **Statement** | Compiles a Prepared Statement; exposes `.all()`, `.get()`, and `.run()`. |
 
-```js
-import SqlRite from "@possumtech/sqlrite";
+### Locality & Multi-Directory Support
 
-const sql = new SqlRite({
-	// SQLite database file path.
-	path: ":memory:",
+You don't have to put all your SQL in one folder. SqlRite encourages placing SQL files exactly where they are needed:
 
-	// Path to your SQL directory.
-	dir: "sql",
+```javascript
+const sql = new SqlRite({
+  dir: ["src/auth", "src/billing", "src/shared/sql"]
 });
 ```
 
-You will almost certainly wish to replace the `path` with a path to your
-database file. Otherwise, the database will be created in memory and lost when
-the process ends.
+Files are sorted **numerically by filename prefix** across all directories (e.g., `001-setup.sql` will always run before `002-seed.sql`), ensuring deterministic migrations.
 
-```js
-const sql = new SqlRite({ path: "path/to/your/database.sqlite3" });
-```
+---
+
+## ⚙️ Configuration
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `path` | `string` | `":memory:"` | Path to the SQLite database file. |
+| `dir` | `string\|string[]` | `"sql"` | Directory or directories to scan for `.sql` files. |
+
+---
 
-Additional arguments will be passed to the options object of the native sqlite
-module.
+## 📄 License
 
-To close the database connection, call the `.close()` method:
+MIT © [@wikitopian](https://github.com/wikitopian)

package/SqlRite.d.ts

@@ -0,0 +1,34 @@
+export interface SqlRiteOptions {
+	path?: string;
+	dir?: string | string[];
+}
+
+export interface SqlRitePreparedStatements {
+	all: (params?: Record<string, any>) => Promise<any[]>;
+	get: (params?: Record<string, any>) => Promise<any>;
+	run: (params?: Record<string, any>) => Promise<any>;
+}
+
+export interface SqlRiteSyncPreparedStatements {
+	all: (params?: Record<string, any>) => any[];
+	get: (params?: Record<string, any>) => any;
+	run: (params?: Record<string, any>) => any;
+}
+
+export class SqlRiteSync {
+	constructor(options?: SqlRiteOptions);
+	close(): void;
+	[key: string]:
+		| ((params?: Record<string, any>) => void)
+		| SqlRiteSyncPreparedStatements
+		| any;
+}
+
+export default class SqlRite {
+	constructor(options?: SqlRiteOptions);
+	close(): Promise<void>;
+	[key: string]:
+		| ((params?: Record<string, any>) => Promise<void>)
+		| SqlRitePreparedStatements
+		| any;
+}

package/SqlRite.js

@@ -1,77 +1,107 @@
-import fs from "node:fs";
-import { DatabaseSync } from "node:sqlite";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+import SqlRiteSync from "./SqlRiteSync.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export { SqlRiteSync };
 
 export default class SqlRite {
+	#worker = null;
+	#id = 0;
+	#promises = new Map();
+	#readyPromise = Promise.resolve();
+	#protected = new Set(["exec", "close", "constructor"]);
+
 	constructor(options = {}) {
 		const defaults = {
 			path: ":memory:",
 			dir: "sql",
 		};
-
 		const merged = { ...defaults, ...options };
 
-		const db = new DatabaseSync(merged.path, merged);
-
-		this.close = () => db.close();
-
-		// allow multiple directories
-		if (!Array.isArray(merged.dir)) merged.dir = [merged.dir];
-		const files = merged.dir.flatMap((d) => this.getFiles(d));
-
-		const code = files.map((f) => fs.readFileSync(f, "utf8")).join("");
-
-		this.async = {};
-
-		const chunks =
-			/-- (?<chunk>(?<type>INIT|EXEC|PREP): (?<name>\w+)\n(?<sql>.*?))($|(?=-- (INIT|EXEC|PREP):))/gs;
-
-		const initChunks = [];
-		const execChunks = [];
-		const prepChunks = [];
-
-		for (const chunk of code.matchAll(chunks)) {
-			const { type } = chunk.groups;
-
-			if (type === "INIT") initChunks.push(chunk.groups);
-			if (type === "EXEC") execChunks.push(chunk.groups);
-			if (type === "PREP") prepChunks.push(chunk.groups);
-		}
-
-		initChunks.forEach((init) => {
-			db.exec(init.sql);
+		this.#worker = new Worker(path.join(__dirname, "SqlWorker.js"), {
+			workerData: { options: merged },
 		});
 
-		execChunks.forEach((exec) => {
-			this[exec.name] = () => db.exec(exec.sql);
-			this.async[exec.name] = async () => db.exec(exec.sql);
+		this.#readyPromise = new Promise((resolve) => {
+			this.#worker.on("message", (msg) => {
+				if (msg.type === "READY") {
+					this.#setupMethods(msg.names);
+					resolve();
+				} else if (msg.id !== undefined) {
+					const promise = this.#promises.get(msg.id);
+					if (promise) {
+						this.#promises.delete(msg.id);
+						if (msg.error) promise.reject(new Error(msg.error));
+						else promise.resolve(msg.result);
+					}
+				}
+			});
 		});
 
-		prepChunks.forEach((prep) => {
-			this[prep.name] = db.prepare(prep.sql);
-
-			this.async[prep.name] = {};
-
-			this.async[prep.name].all = async (params = {}) =>
-				this[prep.name].all(params);
-
-			this.async[prep.name].get = async (params = {}) =>
-				this[prep.name].get(params);
-
-			this.async[prep.name].run = async (params = {}) =>
-				this[prep.name].run(params);
+		// Fallback for methods not yet defined or dynamic ones
+		return new Proxy(this, {
+			get: (target, prop, _receiver) => {
+				if (prop in target) {
+					const val = target[prop];
+					if (typeof val === "function") return val.bind(target);
+					return val;
+				}
+				if (typeof prop === "symbol" || prop === "then") {
+					return target[prop];
+				}
+				// Return a proxy that can handle .all(), .get(), .run() or direct calls
+				return new Proxy(() => {}, {
+					apply: (_t, _thisArg, args) => {
+						return target.#callWorker("EXEC", prop, null, args[0]);
+					},
+					get: (_t, method) => {
+						if (["all", "get", "run"].includes(method)) {
+							return (params) =>
+								target.#callWorker(
+									`PREP_${method.toUpperCase()}`,
+									prop,
+									null,
+									params,
+								);
+						}
+					},
+				});
+			},
 		});
 	}
 
-	getFiles(dir) {
-		const files = [];
+	#setupMethods(names) {
+		for (const name of names.EXEC) {
+			if (this.#protected.has(name)) continue;
+			this[name] = (params) => this.#callWorker("EXEC", name, null, params);
+		}
+		for (const name of names.PREP) {
+			if (this.#protected.has(name)) continue;
+			this[name] = {
+				all: (params) => this.#callWorker("PREP_ALL", name, null, params),
+				get: (params) => this.#callWorker("PREP_GET", name, null, params),
+				run: (params) => this.#callWorker("PREP_RUN", name, null, params),
+			};
+		}
+	}
 
-		for (const item of fs.readdirSync(dir)) {
-			const path = `${dir}/${item}`;
+	async #callWorker(type, name, sql, params) {
+		await this.#readyPromise;
+		return new Promise((resolve, reject) => {
+			const id = this.#id++;
+			this.#promises.set(id, { resolve, reject });
+			this.#worker.postMessage({ id, type, name, sql, params });
+		});
+	}
 
-			if (fs.lstatSync(path).isDirectory()) files.push(...this.getFiles(path));
-			else if (item.endsWith(".sql")) files.push(path);
-		}
+	async exec(sql) {
+		return this.#callWorker("EXEC", null, sql, null);
+	}
 
-		return files.sort();
+	async close() {
+		return this.#callWorker("CLOSE");
 	}
 }

package/SqlRiteCore.js

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export default class SqlRiteCore {
+	static #CHUNK_REGEX = /^-- (INIT|EXEC|PREP): (\w+)/;
+
+	static getFiles(dir) {
+		const files = [];
+		const items = fs.readdirSync(dir, { withFileTypes: true });
+
+		for (const item of items) {
+			const fullPath = path.join(dir, item.name);
+			if (item.isDirectory()) {
+				files.push(...SqlRiteCore.getFiles(fullPath));
+			} else if (item.name.endsWith(".sql")) {
+				files.push(fullPath);
+			}
+		}
+
+		return SqlRiteCore.#sortFiles(files);
+	}
+
+	static #sortFiles(files) {
+		return [...files].sort((a, b) => {
+			const aBase = path.basename(a);
+			const bBase = path.basename(b);
+			const aMatch = aBase.match(/^(\d+)/);
+			const bMatch = bBase.match(/^(\d+)/);
+
+			if (aMatch && bMatch) {
+				const aNum = Number.parseInt(aMatch[1], 10);
+				const bNum = Number.parseInt(bMatch[1], 10);
+				if (aNum !== bNum) return aNum - bNum;
+			} else if (aMatch) {
+				return -1;
+			} else if (bMatch) {
+				return 1;
+			}
+
+			return a.localeCompare(b);
+		});
+	}
+
+	static parseSql(files) {
+		const chunks = { INIT: [], EXEC: [], PREP: [] };
+
+		for (const file of files) {
+			const content = fs.readFileSync(file, "utf8");
+			SqlRiteCore.#processContent(content, chunks);
+		}
+
+		return SqlRiteCore.#trimChunks(chunks);
+	}
+
+	static #processContent(content, chunks) {
+		const lines = content.split(/\r?\n/);
+		let currentChunk = null;
+
+		for (const line of lines) {
+			const match = line.match(SqlRiteCore.#CHUNK_REGEX);
+			if (match) {
+				const [_, type, name] = match;
+				currentChunk = { type, name, sql: "" };
+				chunks[type].push(currentChunk);
+			} else if (currentChunk) {
+				currentChunk.sql += `${line}\n`;
+			}
+		}
+	}
+
+	static #trimChunks(chunks) {
+		for (const [type, list] of Object.entries(chunks)) {
+			chunks[type] = list
+				.map((c) => ({
+					...c,
+					sql: c.sql.trim(),
+				}))
+				.filter((c) => c.sql.length > 0);
+		}
+		return chunks;
+	}
+
+	static jsonify(params) {
+		if (!params) return {};
+		const result = { ...params };
+
+		for (const [key, value] of Object.entries(result)) {
+			if (
+				Array.isArray(value) ||
+				(value !== null &&
+					typeof value === "object" &&
+					value.constructor?.name === "Object")
+			) {
+				result[key] = JSON.stringify(value);
+			}
+		}
+		return result;
+	}
+}

package/SqlRiteSync.js

@@ -0,0 +1,56 @@
+import { DatabaseSync } from "node:sqlite";
+import SqlRiteCore from "./SqlRiteCore.js";
+
+export default class SqlRiteSync {
+	#db = null;
+	#stmts = new Map();
+	#protected = new Set(["exec", "close", "constructor"]);
+
+	constructor(options = {}) {
+		const defaults = {
+			path: ":memory:",
+			dir: "sql",
+		};
+		const merged = { ...defaults, ...options };
+		this.#db = new DatabaseSync(merged.path, merged);
+
+		// Performance and Safety Defaults
+		this.#db.exec("PRAGMA journal_mode = WAL;");
+		this.#db.exec("PRAGMA synchronous = NORMAL;");
+		this.#db.exec("PRAGMA foreign_keys = ON;");
+		this.#db.exec("PRAGMA dml_strict = ON;");
+
+		const dirs = Array.isArray(merged.dir) ? merged.dir : [merged.dir];
+		const files = dirs.flatMap((d) => SqlRiteCore.getFiles(d));
+		const chunks = SqlRiteCore.parseSql(files);
+
+		for (const init of chunks.INIT) {
+			this.#db.exec(init.sql);
+		}
+
+		for (const exec of chunks.EXEC) {
+			if (this.#protected.has(exec.name)) continue;
+			this[exec.name] = () => this.#db.exec(exec.sql);
+		}
+
+		for (const prep of chunks.PREP) {
+			if (this.#protected.has(prep.name)) continue;
+			const stmt = this.#db.prepare(prep.sql);
+			this.#stmts.set(prep.name, stmt);
+
+			this[prep.name] = {
+				all: (params = {}) => stmt.all(SqlRiteCore.jsonify(params)),
+				get: (params = {}) => stmt.get(SqlRiteCore.jsonify(params)),
+				run: (params = {}) => stmt.run(SqlRiteCore.jsonify(params)),
+			};
+		}
+	}
+
+	exec(sql) {
+		this.#db.exec(sql);
+	}
+
+	close() {
+		this.#db.close();
+	}
+}

package/SqlWorker.js

@@ -0,0 +1,68 @@
+import { DatabaseSync } from "node:sqlite";
+import { parentPort, workerData } from "node:worker_threads";
+import SqlRiteCore from "./SqlRiteCore.js";
+
+const { options } = workerData;
+const db = new DatabaseSync(options.path, options);
+
+// Performance and Safety Defaults
+db.exec("PRAGMA journal_mode = WAL;");
+db.exec("PRAGMA synchronous = NORMAL;");
+db.exec("PRAGMA foreign_keys = ON;");
+db.exec("PRAGMA dml_strict = ON;");
+
+const stmts = new Map();
+
+// Initialize
+const dirs = Array.isArray(options.dir) ? options.dir : [options.dir];
+const files = dirs.flatMap((d) => SqlRiteCore.getFiles(d));
+const chunks = SqlRiteCore.parseSql(files);
+
+for (const init of chunks.INIT) {
+	db.exec(init.sql);
+}
+
+for (const prep of chunks.PREP) {
+	const stmt = db.prepare(prep.sql);
+	stmts.set(prep.name, stmt);
+}
+
+parentPort.on("message", (msg) => {
+	const { id, type, name, sql, params } = msg;
+
+	try {
+		let result;
+		if (type === "EXEC") {
+			const chunk = chunks.EXEC.find((e) => e.name === name);
+			if (chunk) {
+				db.exec(chunk.sql);
+			} else if (sql) {
+				db.exec(sql);
+			}
+			result = null;
+		} else if (type === "PREP_ALL") {
+			result = stmts.get(name).all(SqlRiteCore.jsonify(params));
+		} else if (type === "PREP_GET") {
+			result = stmts.get(name).get(SqlRiteCore.jsonify(params));
+		} else if (type === "PREP_RUN") {
+			result = stmts.get(name).run(SqlRiteCore.jsonify(params));
+		} else if (type === "CLOSE") {
+			db.close();
+			parentPort.postMessage({ id, result: null });
+			process.exit(0);
+		}
+
+		parentPort.postMessage({ id, result });
+	} catch (error) {
+		parentPort.postMessage({ id, error: error.message });
+	}
+});
+
+// Signal ready
+parentPort.postMessage({
+	type: "READY",
+	names: {
+		EXEC: chunks.EXEC.map((e) => e.name),
+		PREP: chunks.PREP.map((p) => p.name),
+	},
+});

package/biome.json

@@ -0,0 +1,16 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.6/schema.json",
+	"linter": {
+		"rules": {
+			"complexity": {
+				"noStaticOnlyClass": "off"
+			},
+			"correctness": {
+				"noConstructorReturn": "off"
+			},
+			"suspicious": {
+				"noExplicitAny": "off"
+			}
+		}
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@possumtech/sqlrite",
-	"version": "0.2.3",
+	"version": "1.0.2",
 	"description": "SQL Done Right",
 	"keywords": [
 		"node",
@@ -21,8 +21,17 @@
 	"author": "@wikitopian",
 	"type": "module",
 	"main": "SqlRite.js",
+	"engines": {
+		"node": ">=25.0.0",
+		"npm": ">=11.1.0"
+	},
 	"scripts": {
-		"syntax": "npx @biomejs/biome check",
-		"test": "node --test"
+		"lint": "biome check .",
+		"test": "node --experimental-test-coverage --test test/test.js",
+		"debug": "node --experimental-test-coverage --inspect-brk --test",
+		"check": "npm run lint && npm test"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.6"
 	}
 }

package/test/test.js

@@ -1,21 +1,147 @@
 import assert from "node:assert";
-import SqlRite from "../SqlRite.js";
+import fs from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import SqlRite, { SqlRiteSync } from "../SqlRite.js";
+import SqlRiteCore from "../SqlRiteCore.js";
 
-const sql = new SqlRite();
+// Setup test environment
+if (!fs.existsSync("sql")) fs.mkdirSync("sql");
+fs.writeFileSync(
+	"sql/001-init.sql",
+	"-- INIT: createEmployees\nCREATE TABLE IF NOT EXISTS employees (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, position TEXT NOT NULL, salary REAL NOT NULL);",
+);
+fs.writeFileSync(
+	"sql/002-data.sql",
+	"-- PREP: addEmployee\nINSERT INTO employees (name, position, salary) VALUES ($name, $position, $salary);\n-- PREP: getPositions\nSELECT name, position FROM employees;\n-- PREP: getHighestPaidEmployee\nSELECT * FROM employees ORDER BY salary DESC LIMIT 1;\n-- EXEC: deleteTable\nDROP TABLE IF EXISTS sync_test;",
+);
 
-sql.addEmployee.run({ name: "John", position: "CEO", salary: 99999 });
-sql.addEmployee.run({ name: "Jane", position: "COO", salary: 49998 });
-sql.addEmployee.run({ name: "Jack", position: "CFO", salary: 49997 });
-sql.addEmployee.run({ name: "Jill", position: "CIO", salary: 49996 });
+test("SqlRiteCore", (t) => {
+	t.test("getFiles() should sort numerically", () => {
+		const files = SqlRiteCore.getFiles("sql");
+		const basenames = files.map((f) => path.basename(f));
+		assert.ok(
+			basenames.indexOf("001-init.sql") < basenames.indexOf("002-data.sql"),
+			"001 should come before 002",
+		);
+	});
 
-const employee = sql.getHighestPaidEmployee.get();
+	t.test("getFiles() handles subdirectories", () => {
+		if (!fs.existsSync("sql/sub")) fs.mkdirSync("sql/sub");
+		fs.writeFileSync("sql/sub/999-last.sql", "-- INIT: subInit\nSELECT 1;");
+		const files = SqlRiteCore.getFiles("sql");
+		assert.ok(
+			files.some((f) => f.includes("999-last.sql")),
+			"Should find file in subdirectory",
+		);
+	});
 
-assert(employee?.name === "John", "The highest paid employee should be John");
+	t.test("parseSql() filters empty and trims", () => {
+		fs.writeFileSync("sql/empty.sql", "-- PREP: empty\n  \n  ");
+		const chunks = SqlRiteCore.parseSql(["sql/empty.sql"]);
+		assert.strictEqual(chunks.PREP.length, 0, "Should filter empty chunks");
+	});
 
-sql.async.getPositions.all().then((positions) => console.log(positions));
+	t.test("jsonify() handles objects and arrays", () => {
+		const input = { arr: [1, 2], obj: { a: 1 }, str: "val", nil: null };
+		const output = SqlRiteCore.jsonify(input);
+		assert.strictEqual(output.arr, "[1,2]");
+		assert.strictEqual(output.obj, '{"a":1}');
+		assert.strictEqual(output.str, "val");
+		assert.strictEqual(output.nil, null);
+		assert.deepStrictEqual(
+			SqlRiteCore.jsonify(null),
+			{},
+			"Should return empty object for null params",
+		);
+	});
+});
 
-console.log(`The highest paid employee is ${employee.name}.`);
+test("SqlRiteSync", (t) => {
+	const sql = new SqlRiteSync({ dir: "sql" });
 
-sql.deleteTable();
+	t.test("initialization and INIT chunks", () => {
+		// Employees table should exist from 001-init.sql
+		const res = sql.getPositions.all();
+		assert.ok(Array.isArray(res));
+	});
 
-sql.close();
+	t.test("exec()", () => {
+		sql.exec("CREATE TABLE sync_test (id INTEGER)");
+		sql.exec("INSERT INTO sync_test VALUES (1)");
+		// No error means success
+	});
+
+	t.test("PREP methods (all, get, run)", () => {
+		sql.addEmployee.run({
+			name: "Sync User",
+			position: "Dev",
+			salary: 50000,
+		});
+		const res = sql.getPositions.all();
+		assert.ok(res.some((e) => e.name === "Sync User"));
+	});
+
+	t.test("EXEC methods", () => {
+		sql.deleteTable();
+		// No error means success
+	});
+
+	t.test("close()", () => {
+		sql.close();
+	});
+});
+
+test("SqlRite (Async)", async (t) => {
+	const sql = new SqlRite({ dir: "sql" });
+
+	await t.test("READY signal and methods setup", async () => {
+		// Wait for ready via any method call or just a small timeout if needed
+		// but since every method awaits the readyPromise, we can just call one
+		assert.ok(typeof sql.addEmployee.run === "function");
+	});
+
+	await t.test("PREP methods", async () => {
+		await sql.addEmployee.run({
+			name: "Async User",
+			position: "Lead",
+			salary: 90000,
+		});
+		const res = await sql.getPositions.all();
+		assert.ok(res.some((e) => e.name === "Async User"));
+	});
+
+	await t.test("Proxy fallback", async () => {
+		const res = await sql.getHighestPaidEmployee.get();
+		assert.strictEqual(res.name, "Async User");
+	});
+
+	await t.test("Raw SQL execution", async () => {
+		await sql.exec("CREATE TABLE async_test (id INTEGER)");
+		// Success if no throw
+	});
+
+	await t.test("Error handling", async () => {
+		try {
+			await sql.nonExistentMethod.all();
+			assert.fail("Should have thrown");
+		} catch (err) {
+			// Proxy fallback returns a function that calls #callWorker
+			// Since the name isn't found in EXEC or PREP, the worker will throw
+			assert.ok(err.message.includes("Cannot read properties of undefined"));
+		}
+	});
+
+	await t.test("close()", async () => {
+		await sql.close();
+	});
+});
+
+test("Multi-directory support", () => {
+	if (!fs.existsSync("sql2")) fs.mkdirSync("sql2");
+	fs.writeFileSync("sql2/extra.sql", "-- PREP: extra\nSELECT 1 as val;");
+	const sql = new SqlRiteSync({ dir: ["sql", "sql2"] });
+	const res = sql.extra.get();
+	assert.strictEqual(res.val, 1);
+	sql.close();
+});

package/sql/test.sql

@@ -1,28 +0,0 @@
--- INIT: createEmployeeTable
-BEGIN TRANSACTION;
-
-CREATE TABLE IF NOT EXISTS employees (
-	id INTEGER PRIMARY KEY AUTOINCREMENT,
-	name TEXT NOT NULL,
-	position TEXT NOT NULL,
-	salary REAL NOT NULL
-);
-
-END TRANSACTION;
-
--- EXEC: deleteTable
-BEGIN TRANSACTION;
-
-DROP TABLE IF EXISTS employees;
-
-END TRANSACTION;
-
--- PREP: addEmployee
-INSERT INTO employees (name, position, salary)
-	VALUES ($name, $position, $salary);
-
--- PREP: getPositions
-SELECT name, position FROM employees;
-
--- PREP: getHighestPaidEmployee
-SELECT name FROM employees ORDER BY salary DESC LIMIT 1;