@holo-js/db-sqlite 0.5.5 → 0.6.0

package/dist/.holo-build-fingerprint

@@ -1 +1 @@
-de3d444a601bf4e70ddaa25987415b7c9c92124e47e5e6061825d5196b939399
+d2303f7566e65ea6e4b4bf463954b7c43ff37a93d0f3feebe4be02a3b57ec093

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { DriverAdapter, DriverQueryResult, DriverExecutionResult, DatabaseOperationOptions, DatabaseDriverFactory } from '@holo-js/db';
+import { DriverAdapter, holoRuntimeInternals, DriverQueryResult, DriverExecutionResult, DatabaseOperationOptions, DatabaseDriverFactory } from '@holo-js/db';
 export { DriverAdapter, DriverExecutionResult, DriverQueryResult } from '@holo-js/db';
 
 type SQLiteTransactionMode = 'deferred' | 'immediate' | 'exclusive';
@@ -14,11 +14,17 @@ interface SQLiteStatementLike {
         changes?: number;
         lastInsertRowid?: unknown;
     };
+    safeIntegers?(enabled: boolean): unknown;
 }
 interface SQLiteDatabaseLike {
     prepare(sql: string): SQLiteStatementLike;
     exec(sql: string): unknown;
     close(): unknown;
+    function?(name: string, options: {
+        deterministic: boolean;
+        safeIntegers?: boolean;
+        varargs?: boolean;
+    }, implementation: (...args: unknown[]) => unknown): unknown;
 }
 interface SQLiteAdapterOptions {
     filename?: string;
@@ -27,15 +33,21 @@ interface SQLiteAdapterOptions {
 }
 declare class SQLiteAdapter implements DriverAdapter {
     private database?;
+    private hasRegisteredFunctions;
+    private canCallFunctions;
     private connected;
     private readonly transactionKey;
-    private readonly transactionScope;
     private readonly filename;
     private readonly createDatabaseInstance;
     constructor(options?: SQLiteAdapterOptions);
     initialize(): Promise<void>;
+    databaseExists(): Promise<boolean>;
+    ensureDatabaseExists(): Promise<void>;
+    isDatabaseMissingError(error: unknown): boolean;
     disconnect(): Promise<void>;
     isConnected(): boolean;
+    get [holoRuntimeInternals.driverConnectionKey](): SQLiteAdapter;
+    get [holoRuntimeInternals.transactionScopeKey](): string | SQLiteAdapter;
     runWithTransactionScope<T>(callback: () => Promise<T>): Promise<T>;
     beforeMigrationTransaction(): Promise<SQLiteMigrationTransactionState>;
     validateMigrationTransaction(): Promise<void>;
@@ -49,7 +61,9 @@ declare class SQLiteAdapter implements DriverAdapter {
     createSavepoint(name: string): Promise<void>;
     rollbackToSavepoint(name: string): Promise<void>;
     releaseSavepoint(name: string): Promise<void>;
+    private prepareExact;
     private getDatabase;
+    private openDatabase;
     private normalizeSavepointName;
     private resolveBeginStatement;
 }

package/dist/index.mjs

@@ -1,30 +1,67 @@
 // src/index.ts
 import { AsyncLocalStorage } from "async_hooks";
-import { resolve } from "path";
+import { existsSync } from "fs";
+import { appendFile, mkdir } from "fs/promises";
+import { dirname, resolve } from "path";
 import Database from "better-sqlite3";
 import {
-  DatabaseError
+  CapabilityError,
+  DatabaseError,
+  holoRuntimeInternals
 } from "@holo-js/db";
 var TransactionError = class extends Error {
 };
+var MISSING_DATABASE_ERROR_CODE = "SQLITE_DATABASE_MISSING";
+function isInMemoryDatabase(filename) {
+  return filename === ":memory:" || filename === "";
+}
+function resolveSQLiteFilename(filename) {
+  if (!filename.startsWith("file:")) return filename;
+  const location = filename.slice("file:".length).replace(/#.*$/s, "");
+  const queryStart = location.indexOf("?");
+  if (queryStart !== -1) {
+    throw new Error(`SQLite URL "${filename}" has query parameters, which Holo doesn't support. Remove "${location.slice(queryStart)}" from the URL.`);
+  }
+  if (!location.startsWith("//")) return decodeURIComponent(location);
+  const pathStart = location.indexOf("/", 2);
+  const authority = pathStart === -1 ? location.slice(2) : location.slice(2, pathStart);
+  if (authority !== "" && authority !== "localhost") {
+    throw new Error(`SQLite URL "${filename}" names the host "${authority}". Use "file:" with a local path.`);
+  }
+  return decodeURIComponent(pathStart === -1 ? "" : location.slice(pathStart));
+}
 var transactionTails = /* @__PURE__ */ new Map();
+var heldTransactionScopes = new AsyncLocalStorage();
 function normalizeBinding(value) {
-  return typeof value === "boolean" ? Number(value) : value;
+  if (typeof value === "boolean") {
+    return BigInt(value);
+  }
+  if (typeof value === "number" && Number.isSafeInteger(value)) {
+    return BigInt(value);
+  }
+  return value instanceof Date ? holoRuntimeInternals.formatSQLiteDateTime(value) : value;
+}
+function exactInteger(value) {
+  return value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : value.toString();
+}
+function exactIntegerRow(row) {
+  return Object.fromEntries(Object.entries(row).map(([key, value]) => [key, typeof value === "bigint" ? exactInteger(value) : value]));
 }
 var SQLiteAdapter = class {
   database;
+  hasRegisteredFunctions = false;
+  canCallFunctions = false;
   connected;
   transactionKey;
-  transactionScope = new AsyncLocalStorage();
   filename;
   createDatabaseInstance;
   constructor(options = {}) {
     this.database = options.database;
     this.connected = !!options.database;
-    this.filename = options.filename ?? ":memory:";
-    this.transactionKey = options.database || this.filename === ":memory:" ? this : resolve(this.filename);
+    this.filename = resolveSQLiteFilename(options.filename ?? ":memory:");
+    this.transactionKey = options.database || isInMemoryDatabase(this.filename) ? this : resolve(this.filename);
     this.createDatabaseInstance = options.createDatabase ?? ((filename) => {
-      const database = new Database(filename);
+      const database = new Database(filename, { fileMustExist: !isInMemoryDatabase(filename) });
       try {
         database.exec("PRAGMA journal_mode = WAL");
         return database;
@@ -35,30 +72,35 @@ var SQLiteAdapter = class {
     });
   }
   async initialize() {
-    if (this.connected) {
-      return;
-    }
-    try {
-      this.database = this.createDatabaseInstance(this.filename);
-    } catch (error) {
-      const message = error instanceof Error && error.message ? error.message : "Unknown SQLite driver error.";
-      throw new Error(`Unable to open SQLite database "${this.filename}": ${message}`, { cause: error });
-    }
     this.connected = true;
   }
+  async databaseExists() {
+    return !!this.database || isInMemoryDatabase(this.filename) || existsSync(this.filename);
+  }
+  async ensureDatabaseExists() {
+    await mkdir(dirname(resolve(this.filename)), { recursive: true });
+    await appendFile(this.filename, "");
+  }
+  isDatabaseMissingError(error) {
+    return error instanceof DatabaseError && error.code === MISSING_DATABASE_ERROR_CODE;
+  }
   async disconnect() {
-    if (!this.connected || !this.database) {
-      return;
-    }
-    this.database.close();
+    this.database?.close();
     this.database = void 0;
     this.connected = false;
   }
   isConnected() {
     return this.connected;
   }
+  get [holoRuntimeInternals.driverConnectionKey]() {
+    return this;
+  }
+  get [holoRuntimeInternals.transactionScopeKey]() {
+    return this.transactionKey;
+  }
   async runWithTransactionScope(callback) {
-    if (this.transactionScope.getStore()) {
+    const held = heldTransactionScopes.getStore();
+    if (held?.get(this.transactionKey)?.active) {
       return callback();
     }
     const previous = transactionTails.get(this.transactionKey) ?? Promise.resolve();
@@ -68,9 +110,11 @@ var SQLiteAdapter = class {
     }));
     transactionTails.set(this.transactionKey, current);
     await previous;
+    const scope = { active: true };
     try {
-      return await this.transactionScope.run(true, callback);
+      return await heldTransactionScopes.run(new Map(held).set(this.transactionKey, scope), callback);
     } finally {
+      scope.active = false;
       release();
       if (transactionTails.get(this.transactionKey) === current) transactionTails.delete(this.transactionKey);
     }
@@ -98,8 +142,7 @@ var SQLiteAdapter = class {
     }
   }
   async query(sql, bindings = []) {
-    const statement = this.getDatabase().prepare(sql);
-    const rows = statement.all(...bindings.map(normalizeBinding));
+    const rows = this.prepareExact(sql).all(...bindings.map(normalizeBinding)).map((row) => exactIntegerRow(row));
     return {
       rows,
       rowCount: rows.length
@@ -110,11 +153,10 @@ var SQLiteAdapter = class {
   }
   async execute(sql, bindings = []) {
     return this.runWithTransactionScope(async () => {
-      const statement = this.getDatabase().prepare(sql);
-      const result = statement.run(...bindings.map(normalizeBinding));
+      const result = this.prepareExact(sql).run(...bindings.map(normalizeBinding));
       return {
         affectedRows: result.changes,
-        lastInsertId: typeof result.lastInsertRowid === "bigint" ? Number(result.lastInsertRowid) : result.lastInsertRowid
+        lastInsertId: typeof result.lastInsertRowid === "bigint" ? exactInteger(result.lastInsertRowid) : result.lastInsertRowid
       };
     });
   }
@@ -136,13 +178,48 @@ var SQLiteAdapter = class {
   async releaseSavepoint(name) {
     this.getDatabase().exec(`RELEASE SAVEPOINT ${this.normalizeSavepointName(name)}`);
   }
+  prepareExact(sql) {
+    const database = this.getDatabase();
+    const wallClockFunction = holoRuntimeInternals.SQLITE_WALL_CLOCK_FUNCTION;
+    if (!this.canCallFunctions && sql.includes(`${wallClockFunction}(`)) {
+      throw new CapabilityError(`This query compares dates in app.timezone through the ${wallClockFunction}() SQL function, which the injected SQLite database can't register because it has no function() method. Pass a better-sqlite3 Database, or set app.timezone to UTC.`);
+    }
+    const decimalTextFunction = holoRuntimeInternals.SQLITE_DECIMAL_TEXT_FUNCTION;
+    if (!this.canCallFunctions && sql.includes(`${decimalTextFunction}(`)) {
+      throw new CapabilityError(`This query compares decimal keys with text keys through the ${decimalTextFunction}() SQL function, which the injected SQLite database can't register because it has no function() method. Pass a better-sqlite3 Database.`);
+    }
+    const statement = database.prepare(sql);
+    statement.safeIntegers?.(true);
+    return statement;
+  }
   getDatabase() {
-    if (!this.connected || !this.database) {
-      this.database = this.createDatabaseInstance(this.filename);
-      this.connected = true;
+    if (!this.database) {
+      this.database = this.openDatabase();
+      this.hasRegisteredFunctions = false;
+    }
+    if (!this.hasRegisteredFunctions) {
+      this.canCallFunctions = typeof this.database.function === "function";
+      this.database.function?.(holoRuntimeInternals.SQLITE_WALL_CLOCK_FUNCTION, { deterministic: true }, holoRuntimeInternals.formatSQLiteWallClock);
+      this.database.function?.(holoRuntimeInternals.SQLITE_DECIMAL_TEXT_FUNCTION, { deterministic: true, safeIntegers: true, varargs: true }, (value, places) => holoRuntimeInternals.readSQLiteDecimal(value, places == null ? void 0 : Number(places)));
+      this.hasRegisteredFunctions = true;
     }
+    this.connected = true;
     return this.database;
   }
+  openDatabase() {
+    if (!isInMemoryDatabase(this.filename) && !existsSync(this.filename)) {
+      throw new DatabaseError(
+        `Database file at path "${this.filename}" does not exist. Run "holo migrate" to create it.`,
+        MISSING_DATABASE_ERROR_CODE
+      );
+    }
+    try {
+      return this.createDatabaseInstance(this.filename);
+    } catch (error) {
+      const message = error instanceof Error && error.message ? error.message : "Unknown SQLite driver error.";
+      throw new Error(`Unable to open SQLite database "${this.filename}": ${message}`, { cause: error });
+    }
+  }
   normalizeSavepointName(name) {
     if (!/^[A-Z_]\w*$/i.test(name)) {
       throw new TransactionError(`Invalid savepoint name "${name}".`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holo-js/db-sqlite",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "Holo-JS Framework - SQLite database adapter",
   "type": "module",
   "license": "MIT",
@@ -32,13 +32,13 @@
     "node": "^22.18.0 || ^24.0.0 || ^26.0.0"
   },
   "peerDependencies": {
-    "@holo-js/db": "^0.5.5"
+    "@holo-js/db": "^0.6.0"
   },
   "dependencies": {
     "better-sqlite3": "^13.0.3"
   },
   "devDependencies": {
-    "@holo-js/db": "^0.5.5",
+    "@holo-js/db": "^0.6.0",
     "@types/better-sqlite3": "^9.6.0",
     "tsup": "^9.0.0",
     "typescript": "^6.0.3",