SnowLuma v2.4.2 source snapshot

packages/sqlite/package.json

@@ -0,0 +1,36 @@
+{
+  "license": "SEE LICENSE IN LICENSE",
+  "name": "@snowluma/sqlite",
+  "version": "2.4.2",
+  "private": true,
+  "type": "module",
+  "description": "SnowLuma asynchronous SQLite facade, native loader and release assets.",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./vite": {
+      "types": "./src/vite.ts",
+      "default": "./src/vite.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@appthreat/sqlite3": "9.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "4.1.12"
+  },
+  "engines": {
+    "node": "^24.22.1 || >=26.12.1"
+  }
+}

packages/sqlite/src/driver.ts

@@ -0,0 +1,118 @@
+import path from 'node:path';
+import {
+    loadNative,
+    type BindValue,
+    type NativeDatabase,
+    type NativeStatement,
+    type Row,
+} from './native';
+
+export type { BindValue } from './native';
+
+/** Promises adapt native completion callbacks; SQLite work stays on native workers. */
+export async function openDatabase(filename: string, readOnly: boolean): Promise<Database> {
+    if (process.permission && filename !== ':memory:') {
+        const file = path.resolve(filename);
+        const checks: ['fs.read' | 'fs.write', string][] = [['fs.read', file]];
+
+        if (!readOnly) {
+            checks.push(['fs.write', file], ['fs.write', path.dirname(file)]);
+        }
+
+        for (const [scope, resource] of checks) {
+            if (!process.permission.has(scope, resource)) {
+                throw new Error(`SQLite permission denied: ${scope} ${resource}`);
+            }
+        }
+    }
+
+    const binding = loadNative();
+    const mode =
+        (readOnly ? binding.OPEN_READONLY : binding.OPEN_READWRITE | binding.OPEN_CREATE) |
+        binding.OPEN_FULLMUTEX;
+    return new Promise((resolve, reject) => {
+        new binding.Database(filename, mode, function (error) {
+            if (error) {
+                reject(error);
+            } else {
+                resolve(new Database(this));
+            }
+        });
+    });
+}
+
+export class Database {
+    constructor(private readonly native: NativeDatabase) {}
+
+    exec(sql: string): Promise<void> {
+        return new Promise((resolve, reject) =>
+            this.native.exec(sql, (error) => (error ? reject(error) : resolve())),
+        );
+    }
+
+    prepare(sql: string): Promise<Statement> {
+        const binding = loadNative();
+        return new Promise((resolve, reject) => {
+            new binding.Statement(this.native, sql, function (error) {
+                if (error) {
+                    reject(error);
+                } else {
+                    resolve(new Statement(this));
+                }
+            });
+        });
+    }
+
+    close(): Promise<void> {
+        return new Promise((resolve, reject) =>
+            this.native.close((error) => (error ? reject(error) : resolve())),
+        );
+    }
+}
+
+export class Statement {
+    constructor(private readonly native: NativeStatement) {}
+
+    run(parameters: BindValue[]): Promise<{ changes: number; lastIDBigInt: bigint }> {
+        return new Promise((resolve, reject) =>
+            this.native.run(parameters, (error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+
+                const { changes, lastIDBigInt } = this.native;
+
+                if (changes === undefined || lastIDBigInt === undefined) {
+                    reject(new Error('SQLite native run completed without its result metadata'));
+                } else {
+                    resolve({ changes, lastIDBigInt });
+                }
+            }),
+        );
+    }
+
+    get(parameters: BindValue[]): Promise<Row | undefined> {
+        return new Promise((resolve, reject) =>
+            this.native.get(parameters, (error, row) => (error ? reject(error) : resolve(row))),
+        );
+    }
+
+    all(parameters: BindValue[]): Promise<Row[]> {
+        return new Promise((resolve, reject) =>
+            this.native.all(parameters, (error, rows) => (error ? reject(error) : resolve(rows))),
+        );
+    }
+
+    reset(): Promise<void> {
+        return new Promise((resolve, reject) =>
+            this.native.reset((error) => (error ? reject(error) : resolve())),
+        );
+    }
+
+    finalize(): Promise<void> {
+        return new Promise((resolve, reject) =>
+            this.native.finalize((error) => (error ? reject(error) : resolve())),
+        );
+    }
+}

packages/sqlite/src/index.ts

@@ -0,0 +1,199 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { openDatabase, type Database, type Statement, type BindValue } from './driver';
+
+export type SqliteValue = BindValue;
+export type SqliteRow = Record<string, unknown>;
+const MAX_PENDING_OPERATIONS = 2048;
+const context = new AsyncLocalStorage<{ database: SqliteDatabase; active: boolean }>();
+
+/** Owns one native asynchronous connection. Serialize whole store operations,
+ * not only statements, so unrelated calls cannot enter another call's transaction.
+ */
+export class SqliteDatabase {
+    readonly initialization: Promise<void>;
+    private database: Database | null = null;
+    private tail: Promise<unknown>;
+    private readonly statements = new Map<string, Statement>();
+    private pending = 0;
+    private shutdown: { task: Promise<void> | null } | null = null;
+
+    constructor(
+        filename: string,
+        options: { readOnly?: boolean; busyTimeout?: number; beforeOpen?: Promise<void> } = {},
+    ) {
+        this.initialization = (async () => {
+            await options.beforeOpen;
+
+            if (!options.readOnly && filename !== ':memory:') {
+                await mkdir(path.dirname(filename), { recursive: true });
+            }
+
+            const database = await openDatabase(filename, options.readOnly ?? false);
+            this.database = database;
+
+            try {
+                await database.exec(`PRAGMA busy_timeout = ${options.busyTimeout ?? 1000}`);
+                await database.exec('PRAGMA foreign_keys = ON');
+
+                if (!options.readOnly) {
+                    await database.exec('PRAGMA journal_mode = WAL');
+                    await database.exec('PRAGMA synchronous = NORMAL');
+                }
+            } catch (error) {
+                try {
+                    await database.close();
+                    this.database = null;
+                } catch (closeError) {
+                    throw new AggregateError(
+                        [error, closeError],
+                        'SQLite initialization and cleanup failed',
+                        { cause: error },
+                    );
+                }
+
+                throw error;
+            }
+        })();
+        this.tail = this.initialization.catch(() => undefined);
+    }
+
+    serial<T>(operation: () => T | Promise<T>): Promise<T> {
+        const current = context.getStore();
+
+        if (current?.database === this && current.active) {
+            return Promise.resolve().then(operation);
+        }
+
+        if (this.shutdown) {
+            return Promise.reject(new Error('SQLite database is closing'));
+        }
+
+        if (this.pending >= MAX_PENDING_OPERATIONS) {
+            return Promise.reject(new Error('SQLite operation queue is full'));
+        }
+
+        this.pending++;
+        const work = this.tail.then(async () => {
+            await this.initialization;
+            const scope = { database: this, active: true };
+
+            try {
+                return await context.run(scope, operation);
+            } finally {
+                scope.active = false;
+            }
+        });
+        this.tail = work
+            .then(
+                () => undefined,
+                () => undefined,
+            )
+            .finally(() => {
+                this.pending--;
+            });
+        return work;
+    }
+
+    prepare(sql: string): SqliteStatement {
+        return new SqliteStatement(this, sql);
+    }
+
+    exec(sql: string): Promise<void> {
+        return this.serial(() => this.database!.exec(sql));
+    }
+
+    /** Preparation and statement execution both happen in the driver's native workers. */
+    execute<T>(sql: string, operation: (statement: Statement) => Promise<T>): Promise<T> {
+        return this.serial(async () => {
+            let statement = this.statements.get(sql);
+
+            if (!statement) {
+                statement = await this.database!.prepare(sql);
+                this.statements.set(sql, statement);
+            }
+
+            try {
+                return await operation(statement);
+            } finally {
+                // get() may stop on SQLITE_ROW. Release its read snapshot before the
+                // next operation or another connection's commit causes BUSY_SNAPSHOT.
+                await statement.reset();
+            }
+        });
+    }
+
+    close(): Promise<void> {
+        const current = context.getStore();
+
+        if (current?.database === this && current.active) {
+            return Promise.reject(new Error('Cannot close SQLite from a serialized operation'));
+        }
+
+        // Shutdown remains terminal for callers even if native cleanup needs a retry.
+        const shutdown = (this.shutdown ??= { task: null });
+
+        if (shutdown.task) {
+            return shutdown.task;
+        }
+
+        shutdown.task = (async () => {
+            // The queue includes initialization and every accepted operation.
+            await this.tail;
+
+            if (!this.database) {
+                return;
+            }
+
+            const results = await Promise.allSettled(
+                [...this.statements.values()].map((statement) => statement.finalize()),
+            );
+            this.statements.clear();
+            const errors = results.flatMap((result) =>
+                result.status === 'rejected' ? [result.reason] : [],
+            );
+
+            try {
+                await this.database.close();
+                this.database = null;
+            } catch (error) {
+                errors.push(error);
+            }
+
+            if (errors.length) {
+                throw new AggregateError(errors, 'SQLite close failed');
+            }
+        })();
+        void shutdown.task.catch(() => {
+            shutdown.task = null;
+        });
+        return shutdown.task;
+    }
+}
+
+/** A lazy SQL descriptor: creating it does not touch SQLite or block JavaScript. */
+export class SqliteStatement {
+    constructor(
+        private readonly database: SqliteDatabase,
+        readonly sourceSQL: string,
+    ) {}
+
+    run(...values: SqliteValue[]): Promise<{ changes: number; lastInsertRowid: number | bigint }> {
+        const parameters = structuredClone(values);
+        return this.database.execute(this.sourceSQL, async (statement) => {
+            const result = await statement.run(parameters);
+            return { changes: result.changes, lastInsertRowid: result.lastIDBigInt };
+        });
+    }
+
+    get(...values: SqliteValue[]): Promise<SqliteRow | undefined> {
+        const parameters = structuredClone(values);
+        return this.database.execute(this.sourceSQL, (statement) => statement.get(parameters));
+    }
+
+    all(...values: SqliteValue[]): Promise<SqliteRow[]> {
+        const parameters = structuredClone(values);
+        return this.database.execute(this.sourceSQL, (statement) => statement.all(parameters));
+    }
+}

packages/sqlite/src/layout.ts

@@ -0,0 +1,52 @@
+// Upgrade these together with package.json, then rerun the native and bundle tests.
+export const DRIVER_VERSION = '9.1.0';
+export const NATIVE_INTERFACE_VERSION = 1;
+export const REQUIRED_NAPI_VERSION = 10;
+export const RELEASE_PREBUILDS = './native/sqlite/prebuilds/';
+
+export function prebuildFiles(target: string): string[] {
+    if (!/^(win32|linux|darwin)-(x64|arm64)$/.test(target)) {
+        throw new Error(`Unsupported SQLite target: ${target}`);
+    }
+
+    return (
+        target.startsWith('linux-')
+            ? ['@appthreat+sqlite3.glibc.node', '@appthreat+sqlite3.musl.node']
+            : ['@appthreat+sqlite3.node']
+    ).map((file) => `${target}/${file}`);
+}
+
+export function runtimePrebuild(platform: string, arch: string, libc?: 'glibc' | 'musl'): string {
+    const target = `${platform}-${arch}`;
+    const files = prebuildFiles(target);
+
+    if (platform !== 'linux') {
+        return files[0];
+    }
+
+    if (!libc) {
+        throw new Error('SQLite requires an explicit Linux libc selection');
+    }
+
+    return `${target}/@appthreat+sqlite3.${libc}.node`;
+}
+
+export function assertRuntime(node: string, napi: string | undefined): void {
+    if (!(Number.parseInt(node, 10) >= 24) || !(Number(napi) >= REQUIRED_NAPI_VERSION)) {
+        throw new Error(
+            `SQLite requires Node >=24 and Node-API >=${REQUIRED_NAPI_VERSION}; got Node ${node}, Node-API ${napi ?? 'unavailable'}`,
+        );
+    }
+}
+
+export function runtimeLibc(report: object): 'glibc' | 'musl' {
+    if (!('header' in report) || !report.header || typeof report.header !== 'object') {
+        throw new Error('Cannot determine SQLite libc: Node diagnostic report has no header');
+    }
+
+    return 'glibcVersionRuntime' in report.header &&
+        typeof report.header.glibcVersionRuntime === 'string' &&
+        report.header.glibcVersionRuntime.length > 0
+        ? 'glibc'
+        : 'musl';
+}

packages/sqlite/src/native.ts

@@ -0,0 +1,128 @@
+import { EventEmitter } from 'node:events';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+    assertRuntime,
+    NATIVE_INTERFACE_VERSION,
+    RELEASE_PREBUILDS,
+    runtimeLibc,
+    runtimePrebuild,
+} from './layout';
+
+// Only the callback ABI used by SnowLuma is exposed. No upstream JavaScript,
+// convenience methods, synchronous SQL methods or node-gyp resolver are loaded.
+export type BindValue =
+    | string
+    | number
+    | bigint
+    | boolean
+    | null
+    | undefined
+    | Uint8Array
+    | ArrayBuffer
+    | DataView
+    | Date
+    | RegExp;
+export type Row = Record<string, unknown>;
+type Done = (error: Error | null) => void;
+
+export interface NativeDatabase {
+    exec(sql: string, callback: Done): void;
+    close(callback: Done): void;
+}
+
+export interface NativeStatement {
+    run(parameters: BindValue[], callback: Done): void;
+    get(
+        parameters: BindValue[],
+        callback: (error: Error | null, row: Row | undefined) => void,
+    ): void;
+    all(parameters: BindValue[], callback: (error: Error | null, rows: Row[]) => void): void;
+    reset(callback: Done): void;
+    finalize(callback: Done): void;
+    readonly changes: number | undefined;
+    readonly lastIDBigInt: bigint | undefined;
+}
+
+interface NativeBinding {
+    NATIVE_INTERFACE_VERSION: number;
+    OPEN_READONLY: number;
+    OPEN_READWRITE: number;
+    OPEN_CREATE: number;
+    OPEN_FULLMUTEX: number;
+    Database: new (
+        filename: string,
+        mode: number,
+        callback: (this: NativeDatabase, error: Error | null) => void,
+    ) => NativeDatabase;
+    Statement: new (
+        database: NativeDatabase,
+        sql: string,
+        callback: (this: NativeStatement, error: Error | null) => void,
+    ) => NativeStatement;
+}
+
+function assertBinding(value: unknown): asserts value is NativeBinding {
+    if (
+        !value ||
+        typeof value !== 'object' ||
+        !('NATIVE_INTERFACE_VERSION' in value) ||
+        value.NATIVE_INTERFACE_VERSION !== NATIVE_INTERFACE_VERSION ||
+        !('Database' in value) ||
+        typeof value.Database !== 'function' ||
+        !('Statement' in value) ||
+        typeof value.Statement !== 'function' ||
+        !('OPEN_READONLY' in value) ||
+        value.OPEN_READONLY !== 1 ||
+        !('OPEN_READWRITE' in value) ||
+        value.OPEN_READWRITE !== 2 ||
+        !('OPEN_CREATE' in value) ||
+        value.OPEN_CREATE !== 4 ||
+        !('OPEN_FULLMUTEX' in value) ||
+        value.OPEN_FULLMUTEX !== 0x10000
+    ) {
+        throw new Error(
+            `SQLite native interface mismatch; expected interface ${NATIVE_INTERFACE_VERSION}`,
+        );
+    }
+}
+
+declare const __SNOWLUMA_SQLITE_RELEASE__: boolean;
+let binding: NativeBinding | undefined;
+
+export function loadNative(): NativeBinding {
+    if (binding) {
+        return binding;
+    }
+
+    assertRuntime(process.versions.node, process.versions.napi);
+    const libc = process.platform === 'linux' ? runtimeLibc(process.report.getReport()) : undefined;
+    const file = runtimePrebuild(process.platform, process.arch, libc);
+    // Vite makes the release branch constant. A missing release binary must fail,
+    // never fall back to another install, the working directory or a local build.
+    const root =
+        typeof __SNOWLUMA_SQLITE_RELEASE__ !== 'undefined' && __SNOWLUMA_SQLITE_RELEASE__
+            ? fileURLToPath(new URL(RELEASE_PREBUILDS, import.meta.url))
+            : path.join(
+                  path.dirname(
+                      createRequire(import.meta.url).resolve('@appthreat/sqlite3/package.json'),
+                  ),
+                  'prebuilds',
+              );
+    const filename = path.join(root, file);
+
+    try {
+        const module: { exports: unknown } = { exports: {} };
+        process.dlopen(module, filename);
+        assertBinding(module.exports);
+        // The native constructors emit open/close/error events even when callbacks
+        // are supplied, and expect EventEmitter methods on their prototypes.
+        Object.assign(module.exports.Database.prototype, EventEmitter.prototype);
+        Object.assign(module.exports.Statement.prototype, EventEmitter.prototype);
+        binding = module.exports;
+        return binding;
+    } catch (cause) {
+        throw new Error(`Failed to load SQLite native addon: ${filename}`, { cause });
+    }
+}

packages/sqlite/src/vite.ts

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import type { Plugin } from 'vite';
+import { DRIVER_VERSION, NATIVE_INTERFACE_VERSION, prebuildFiles } from './layout.ts';
+
+/** Upstream is a locked prebuild source, never a runtime JS or installer dependency. */
+export function sqliteBuildPlugin(target: string): Plugin {
+    const require = createRequire(import.meta.url);
+    const driverRoot = path.dirname(require.resolve('@appthreat/sqlite3/package.json'));
+    const metadata: unknown = JSON.parse(
+        fs.readFileSync(path.join(driverRoot, 'package.json'), 'utf8'),
+    );
+
+    if (
+        !metadata ||
+        typeof metadata !== 'object' ||
+        !('version' in metadata) ||
+        metadata.version !== DRIVER_VERSION
+    ) {
+        throw new Error(
+            `SQLite prebuild version mismatch; expected @appthreat/sqlite3 ${DRIVER_VERSION}`,
+        );
+    }
+
+    const files = prebuildFiles(target).map((file) => `prebuilds/${file}`);
+    const assets = [
+        ...files.map((file) => ({ file, source: path.join(driverRoot, file) })),
+        { file: 'LICENSE.sqlite3', source: path.join(driverRoot, 'LICENSE') },
+    ];
+
+    for (const asset of assets) {
+        if (!fs.statSync(asset.source, { throwIfNoEntry: false })?.isFile()) {
+            throw new Error(`Missing SQLite release input for ${target}: ${asset.source}`);
+        }
+    }
+
+    return {
+        name: 'snowluma-sqlite-prebuilds',
+        config: () => ({ define: { __SNOWLUMA_SQLITE_RELEASE__: 'true' } }),
+        generateBundle() {
+            for (const asset of assets) {
+                this.emitFile({
+                    type: 'asset',
+                    fileName: `native/sqlite/${asset.file}`,
+                    source: fs.readFileSync(asset.source),
+                });
+            }
+
+            this.emitFile({
+                type: 'asset',
+                fileName: 'native/sqlite/manifest.json',
+                source:
+                    JSON.stringify(
+                        {
+                            package: '@appthreat/sqlite3',
+                            version: DRIVER_VERSION,
+                            nativeInterface: NATIVE_INTERFACE_VERSION,
+                            target,
+                            files,
+                        },
+                        null,
+                        2,
+                    ) + '\n',
+            });
+        },
+    };
+}

packages/sqlite/tests/build.test.ts

@@ -0,0 +1,125 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { isBuiltin } from 'node:module';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { expect, it } from 'vitest';
+import { build } from 'vite';
+import { sqliteBuildPlugin } from '../src/vite';
+import { prebuildFiles } from '../src/layout';
+
+it('runs bundled SQLite from a release directory with no installed dependencies', async () => {
+    const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'sqlite-release-'));
+
+    try {
+        const target = `${process.platform}-${process.arch}`;
+        await build({
+            configFile: false,
+            logLevel: 'silent',
+            plugins: [sqliteBuildPlugin(target)],
+            build: {
+                target: 'node24',
+                outDir: directory,
+                emptyOutDir: false,
+                minify: false,
+                lib: {
+                    entry: fileURLToPath(new URL('../src/index.ts', import.meta.url)),
+                    formats: ['es'],
+                    fileName: () => 'database.mjs',
+                },
+                rollupOptions: {
+                    external: isBuiltin,
+                },
+            },
+        });
+        const probe = path.join(directory, 'probe.mjs');
+        await fs.writeFile(
+            probe,
+            `
+      import { SqliteDatabase } from './database.mjs';
+      const db = new SqliteDatabase(':memory:');
+      await db.exec('CREATE TABLE records (value TEXT)');
+      await db.prepare('INSERT INTO records VALUES (?)').run('packaged');
+      const row = await db.prepare('SELECT value FROM records').get();
+      await db.close();
+      if (row.value !== 'packaged') throw new Error('packaged SQLite round trip failed');
+      console.log('packaged SQLite ok');
+    `,
+        );
+        const { stdout } = await promisify(execFile)(process.execPath, [probe], {
+            cwd: os.tmpdir(),
+        });
+        expect(stdout.trim()).toBe('packaged SQLite ok');
+        const manifest = JSON.parse(
+            await fs.readFile(path.join(directory, 'native/sqlite/manifest.json'), 'utf8'),
+        );
+        expect(manifest).toMatchObject({
+            package: '@appthreat/sqlite3',
+            version: '9.1.0',
+            nativeInterface: 1,
+            target,
+        });
+        const bundle = await fs.readFile(path.join(directory, 'database.mjs'), 'utf8');
+        expect(bundle).not.toContain('node-gyp-build');
+        expect(bundle).not.toContain("resolve('@appthreat/sqlite3/package.json')");
+
+        // Even with dependencies available in the caller's cwd, a broken release
+        // cannot silently load a development binary or a different local build.
+        for (const file of prebuildFiles(target)) {
+            await fs.unlink(path.join(directory, 'native/sqlite/prebuilds', file));
+        }
+
+        await expect(
+            promisify(execFile)(process.execPath, [probe], { cwd: process.cwd() }),
+        ).rejects.toMatchObject({
+            stderr: expect.stringContaining('Failed to load SQLite native addon:'),
+        });
+    } finally {
+        await fs.rm(directory, { recursive: true, force: true });
+    }
+}, 30_000);
+
+it.each(['win32-x64', 'win32-arm64', 'linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64'])(
+    'packages %s using the same installed prebuild dependency',
+    async (target) => {
+        const result = await build({
+            configFile: false,
+            logLevel: 'silent',
+            plugins: [sqliteBuildPlugin(target)],
+            build: {
+                target: 'node24',
+                write: false,
+                minify: false,
+                lib: {
+                    entry: fileURLToPath(new URL('../src/index.ts', import.meta.url)),
+                    formats: ['es'],
+                },
+                rollupOptions: { external: isBuiltin },
+            },
+        });
+        const bundle = Array.isArray(result) ? result[0] : result;
+
+        if (!('output' in bundle)) {
+            throw new Error('Expected one release bundle');
+        }
+
+        const names = bundle.output.map((file) => file.fileName);
+        expect(names.filter((name) => name.endsWith('.node')).sort()).toEqual(
+            prebuildFiles(target)
+                .map((file) => `native/sqlite/prebuilds/${file}`)
+                .sort(),
+        );
+        expect(names).toContain('native/sqlite/LICENSE.sqlite3');
+        expect(names).toContain('native/sqlite/manifest.json');
+
+        for (const chunk of bundle.output) {
+            if (chunk.type === 'chunk') {
+                expect(
+                    Object.keys(chunk.modules).some((file) => file.includes('/node_modules/')),
+                ).toBe(false);
+            }
+        }
+    },
+);

packages/sqlite/tests/layout.test.ts

@@ -0,0 +1,24 @@
+import { expect, it } from 'vitest';
+import { assertRuntime, prebuildFiles, runtimeLibc, runtimePrebuild } from '../src/layout';
+
+it('selects only the exact platform, architecture and libc binary', () => {
+    expect(runtimePrebuild('win32', 'arm64')).toBe('win32-arm64/@appthreat+sqlite3.node');
+    expect(runtimePrebuild('darwin', 'x64')).toBe('darwin-x64/@appthreat+sqlite3.node');
+    expect(
+        runtimePrebuild('linux', 'arm64', runtimeLibc({ header: { glibcVersionRuntime: '2.39' } })),
+    ).toBe('linux-arm64/@appthreat+sqlite3.glibc.node');
+    expect(runtimePrebuild('linux', 'x64', runtimeLibc({ header: {} }))).toBe(
+        'linux-x64/@appthreat+sqlite3.musl.node',
+    );
+    expect(() => runtimePrebuild('linux', 'x64')).toThrow('libc');
+    expect(() => prebuildFiles('linux-ia32')).toThrow('Unsupported SQLite target');
+    expect(() => runtimeLibc({})).toThrow('diagnostic report');
+});
+
+it('rejects incompatible runtimes before attempting to load a Node-API 10 binary', () => {
+    expect(() => assertRuntime('24.0.0', '10')).not.toThrow();
+    expect(() => assertRuntime('26.0.0', '11')).not.toThrow();
+    expect(() => assertRuntime('22.0.0', '10')).toThrow('Node >=24');
+    expect(() => assertRuntime('24.0.0', '9')).toThrow('Node-API >=10');
+    expect(() => assertRuntime('24.0.0', undefined)).toThrow('Node-API >=10');
+});

packages/sqlite/tests/sqlite.test.ts

@@ -0,0 +1,240 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { setImmediate as nextTurn, setTimeout as delay } from 'node:timers/promises';
+import { afterEach, expect, it, vi } from 'vitest';
+import { SqliteDatabase } from '../src/index';
+import { Database, Statement } from '../src/driver';
+
+const directories: string[] = [];
+afterEach(async () => {
+    for (const directory of directories.splice(0)) {
+        await rm(directory, { recursive: true, force: true });
+    }
+});
+
+async function filename(): Promise<string> {
+    const directory = await mkdtemp(path.join(os.tmpdir(), 'sqlite-async-'));
+    directories.push(directory);
+    return path.join(directory, 'test.db');
+}
+
+it('keeps the event loop responsive while SQLite waits for a write lock', async () => {
+    const file = await filename();
+    const db = new SqliteDatabase(file, { busyTimeout: 0 });
+    await db.exec('CREATE TABLE records (value INTEGER)');
+    const locker = new SqliteDatabase(file);
+    await locker.exec('BEGIN IMMEDIATE');
+
+    try {
+        const insert = db.prepare('INSERT INTO records VALUES (?)');
+        // Both connections must use the same SQLite library for in-process locks.
+        // Prove contention before checking whether waiting leaves timers responsive.
+        await expect(insert.run(7)).rejects.toMatchObject({ code: 'SQLITE_BUSY' });
+        await db.exec('PRAGMA busy_timeout = 1000');
+        let timerRan = false;
+        const release = delay(25).then(() => {
+            timerRan = true;
+            return locker.exec('ROLLBACK');
+        });
+
+        try {
+            await Promise.all([
+                insert.run(7).then(() => {
+                    expect(timerRan).toBe(true);
+                }),
+                release,
+            ]);
+            expect(await db.prepare('SELECT value FROM records').get()).toEqual({ value: 7 });
+        } finally {
+            await release;
+        }
+    } finally {
+        await locker.close();
+        await db.close();
+    }
+});
+
+it('releases a cached get cursor before a second connection commits', async () => {
+    const file = await filename();
+    const first = new SqliteDatabase(file);
+    await first.exec('CREATE TABLE records (value INTEGER); INSERT INTO records VALUES (1)');
+    const second = new SqliteDatabase(file);
+
+    try {
+        const get = first.prepare('SELECT value FROM records ORDER BY value DESC');
+        expect(await get.get()).toEqual({ value: 1 });
+        await second.prepare('INSERT INTO records VALUES (?)').run(2);
+        await first.prepare('INSERT INTO records VALUES (?)').run(3);
+        expect(await get.get()).toEqual({ value: 3 });
+    } finally {
+        await first.close();
+        await second.close();
+    }
+});
+
+it('keeps concurrent operations outside a transaction and drains accepted writes before close', async () => {
+    const db = new SqliteDatabase(await filename());
+    await db.exec('CREATE TABLE records (value INTEGER)');
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => {
+        release = resolve;
+    });
+    let entered!: () => void;
+    const started = new Promise<void>((resolve) => {
+        entered = resolve;
+    });
+    const transaction = db.serial(async () => {
+        await db.exec('BEGIN IMMEDIATE');
+        await db.prepare('INSERT INTO records VALUES (?)').run(1);
+        entered();
+        await gate;
+        await db.exec('ROLLBACK');
+    });
+    await started;
+    const write = db.prepare('INSERT INTO records VALUES (?)').run(2);
+    const read = db.prepare('SELECT value FROM records').all();
+    const closing = db.close();
+    await expect(db.exec('SELECT 1')).rejects.toThrow('closing');
+    release();
+    await transaction;
+    await write;
+    expect(await read).toEqual([{ value: 2 }]);
+    await closing;
+});
+
+it('preserves native errors, exact insert IDs and blob parameters through the callback facade', async () => {
+    const db = new SqliteDatabase(await filename());
+
+    try {
+        await db.exec('CREATE TABLE records (id INTEGER PRIMARY KEY, payload BLOB)');
+        const insert = db.prepare('INSERT INTO records VALUES (?, ?)');
+        const id = 9_007_199_254_740_993n;
+        const bytes = new Uint8Array([0, 127, 255]);
+        const pending = insert.run(id, bytes);
+        bytes.fill(42);
+        expect(await pending).toEqual({ changes: 1, lastInsertRowid: id });
+        expect(await db.prepare('SELECT payload FROM records WHERE id = ?').get(id)).toEqual({
+            payload: Buffer.from([0, 127, 255]),
+        });
+        await expect(insert.run(id, null)).rejects.toMatchObject({
+            code: 'SQLITE_CONSTRAINT_PRIMARYKEY',
+        });
+        await expect(db.prepare('SELECT FROM invalid').get()).rejects.toMatchObject({
+            code: 'SQLITE_ERROR',
+        });
+        // Failed operations must release the connection queue and leave it usable.
+        expect(await db.prepare('SELECT count(*) AS count FROM records').get()).toEqual({
+            count: 1,
+        });
+    } finally {
+        await db.close();
+    }
+});
+
+it('rejects failed opens and safely closes a partially initialized connection', async () => {
+    const db = new SqliteDatabase(await filename(), { readOnly: true });
+    await expect(db.initialization).rejects.toMatchObject({ code: 'SQLITE_CANTOPEN' });
+    await expect(db.prepare('SELECT 1').get()).rejects.toMatchObject({ code: 'SQLITE_CANTOPEN' });
+    await db.close();
+});
+
+it.each(['ready', 'failed'] as const)(
+    'opens only after the previous owner is %s',
+    async (outcome) => {
+        const driver = await import('../src/driver');
+        const open = vi.spyOn(driver, 'openDatabase');
+        let resolve!: () => void;
+        let reject!: (error: Error) => void;
+        const beforeOpen = new Promise<void>((yes, no) => {
+            resolve = yes;
+            reject = no;
+        });
+        const db = new SqliteDatabase(':memory:', { beforeOpen });
+
+        try {
+            await nextTurn();
+            expect(open).not.toHaveBeenCalled();
+
+            if (outcome === 'ready') {
+                resolve();
+                await db.initialization;
+                expect(open).toHaveBeenCalledOnce();
+                expect(await db.prepare('SELECT 1 AS value').get()).toEqual({ value: 1 });
+            } else {
+                const failure = new Error('previous owner could not close');
+                reject(failure);
+                await expect(db.initialization).rejects.toBe(failure);
+                await expect(db.exec('SELECT 1')).rejects.toBe(failure);
+                expect(open).not.toHaveBeenCalled();
+            }
+        } finally {
+            resolve();
+            await db.close();
+            open.mockRestore();
+        }
+    },
+);
+
+it('keeps writes rejected after a failed close while allowing cleanup to retry', async () => {
+    const db = new SqliteDatabase(':memory:');
+    await db.initialization;
+    const close = vi
+        .spyOn(Database.prototype, 'close')
+        .mockRejectedValueOnce(new Error('close failed'));
+
+    try {
+        await expect(db.close()).rejects.toThrow('SQLite close failed');
+        await expect(db.exec('CREATE TABLE late_write (value INTEGER)')).rejects.toThrow('closing');
+        const retry = db.close();
+        expect(db.close()).toBe(retry);
+        await retry;
+        expect(close).toHaveBeenCalledTimes(2);
+        await expect(db.serial(() => 1)).rejects.toThrow('closing');
+    } finally {
+        close.mockRestore();
+        await db.close();
+    }
+});
+
+it('does not accept work when connection close succeeds but statement cleanup reports an error', async () => {
+    const db = new SqliteDatabase(':memory:');
+    await db.prepare('SELECT 1').get();
+    const original = Statement.prototype.finalize;
+    const finalize = vi
+        .spyOn(Statement.prototype, 'finalize')
+        .mockImplementationOnce(async function (this: Statement) {
+            await original.call(this);
+            throw new Error('statement cleanup failed');
+        });
+
+    try {
+        await expect(db.close()).rejects.toThrow('SQLite close failed');
+        await expect(db.serial(() => 1)).rejects.toThrow('closing');
+        await db.close();
+    } finally {
+        finalize.mockRestore();
+        await db.close();
+    }
+});
+
+it('rejects close from inside its own serialized operation instead of waiting on itself', async () => {
+    const db = new SqliteDatabase(':memory:');
+
+    try {
+        await db.serial(async () => {
+            await expect(
+                Promise.race([
+                    db.close(),
+                    nextTurn().then(() => {
+                        throw new Error('close is waiting on its own operation');
+                    }),
+                ]),
+            ).rejects.toThrow('Cannot close SQLite from a serialized operation');
+            await db.exec('CREATE TABLE records (value INTEGER)');
+        });
+        await db.prepare('INSERT INTO records VALUES (?)').run(1);
+    } finally {
+        await db.close();
+    }
+});

packages/sqlite/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "types": ["node"], "noEmit": true, "allowImportingTsExtensions": true },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}

packages/sqlite/vitest.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: { include: ['tests/**/*.test.ts'], environment: 'node' },
+});