@objectstack/service-datasource 10.2.0 → 11.0.0

package/dist/sqlite-driver-fallback-BPFQYLX7.js

@@ -0,0 +1,11 @@
+import {
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
+  resolveSqliteDriver
+} from "./chunk-JRBGOCRJ.js";
+export {
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
+  resolveSqliteDriver
+};
+//# sourceMappingURL=sqlite-driver-fallback-BPFQYLX7.js.map

package/dist/sqlite-driver-fallback-BPFQYLX7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/sqlite-driver-fallback-JX4XOICD.cjs

@@ -0,0 +1,11 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+var _chunk76HQ74MXcjs = require('./chunk-76HQ74MX.cjs');
+
+
+
+
+exports.NATIVE_SQLITE_MEMORY_FALLBACK_WARNING = _chunk76HQ74MXcjs.NATIVE_SQLITE_MEMORY_FALLBACK_WARNING; exports.NATIVE_SQLITE_WASM_FALLBACK_WARNING = _chunk76HQ74MXcjs.NATIVE_SQLITE_WASM_FALLBACK_WARNING; exports.resolveSqliteDriver = _chunk76HQ74MXcjs.resolveSqliteDriver;
+//# sourceMappingURL=sqlite-driver-fallback-JX4XOICD.cjs.map

package/dist/sqlite-driver-fallback-JX4XOICD.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/framework/framework/packages/services/service-datasource/dist/sqlite-driver-fallback-JX4XOICD.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACF,wDAA6B;AAC7B;AACE;AACA;AACA;AACF,kRAAC","file":"/home/runner/work/framework/framework/packages/services/service-datasource/dist/sqlite-driver-fallback-JX4XOICD.cjs"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/service-datasource",
-  "version": "10.2.0",
+  "version": "11.0.0",
   "license": "Apache-2.0",
   "description": "The datasource service (ADR-0015): external-table federation (introspect/draft/import/validate) + runtime UI datasource lifecycle (list/test/create/update/remove + REST routes). Open-source mechanism; the tier line falls on which ICryptoProvider / driver factory a host injects.",
   "type": "module",
@@ -19,18 +19,19 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "10.2.0",
-    "@objectstack/spec": "10.2.0"
+    "@objectstack/core": "11.0.0",
+    "@objectstack/spec": "11.0.0"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
-    "@objectstack/driver-memory": "10.2.0",
-    "@objectstack/driver-sql": "10.2.0",
-    "@objectstack/plugin-hono-server": "10.2.0",
-    "@objectstack/driver-mongodb": "10.2.0"
+    "@objectstack/driver-memory": "11.0.0",
+    "@objectstack/driver-sql": "11.0.0",
+    "@objectstack/driver-sqlite-wasm": "11.0.0",
+    "@objectstack/plugin-hono-server": "11.0.0",
+    "@objectstack/driver-mongodb": "11.0.0"
   },
   "keywords": [
     "objectstack",

package/src/default-datasource-driver-factory.ts

@@ -113,7 +113,19 @@ function buildMongoUrl(spec: DatasourceConnectionSpec): string {
  * lazily so a host that never builds (e.g.) a mongo connection doesn't pay for
  * the mongo SDK.
  */
-export function createDefaultDatasourceDriverFactory(): IDatasourceDriverFactory {
+export interface DefaultDatasourceDriverFactoryOptions {
+  /**
+   * Enables the dev-only native-`better-sqlite3` → wasm → in-memory step-down
+   * for sqlite construction (#2229). When omitted, defaults per call to
+   * `process.env.NODE_ENV === 'development'`. In production a native load
+   * failure is NOT silently swapped for a different engine (fail-closed).
+   */
+  dev?: boolean;
+}
+
+export function createDefaultDatasourceDriverFactory(
+  options: DefaultDatasourceDriverFactoryOptions = {},
+): IDatasourceDriverFactory {
   return {
     supports(driverId: string): boolean {
       return resolveKind(driverId) !== undefined;
@@ -140,14 +152,19 @@ export function createDefaultDatasourceDriverFactory(): IDatasourceDriverFactory
       }
 
       if (kind === 'sqlite') {
-        const { SqlDriver } = await import('@objectstack/driver-sql');
-        const driver = new SqlDriver({
-          client: 'better-sqlite3',
-          connection: buildSqlConnection(spec, 'better-sqlite3') as any,
-          useNullAsDefault: true,
-          ...(schemaMode ? { schemaMode: schemaMode as any } : {}),
-        } as any);
-        return toHandle(driver, () => sqlServerVersion(driver, 'sqlite'));
+        // better-sqlite3 loads its native addon lazily (first query), so an ABI
+        // mismatch is invisible at construction and crashes later. resolveSqliteDriver
+        // probes up-front and, IN DEV ONLY, steps down to wasm SQLite (real SQL +
+        // on-disk persistence) then in-memory; in production it returns the native
+        // driver unprobed so a failure surfaces loudly (fail-closed). (#2229)
+        const conn = buildSqlConnection(spec, 'better-sqlite3') as { filename?: string };
+        const { resolveSqliteDriver } = await import('./sqlite-driver-fallback.js');
+        const resolved = await resolveSqliteDriver({
+          filename: conn.filename ?? ':memory:',
+          dev: options.dev,
+          ...(schemaMode ? { schemaMode } : {}),
+        });
+        return toHandle(resolved.driver, () => sqlServerVersion(resolved.driver, 'sqlite'));
       }
 
       if (kind === 'mongodb') {

package/src/index.ts

@@ -76,6 +76,17 @@ export type {
 
 // Host glue: dev driver factory + fail-closed secret binder.
 export { createDefaultDatasourceDriverFactory } from './default-datasource-driver-factory.js';
+// Shared native-better-sqlite3 → wasm → in-memory step-down (#2229).
+export {
+  resolveSqliteDriver,
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+} from './sqlite-driver-fallback.js';
+export type {
+  ResolveSqliteDriverOptions,
+  ResolvedSqliteDriver,
+  SqliteFallbackEngine,
+} from './sqlite-driver-fallback.js';
 export {
   createDatasourceSecretBinder,
   toCredentialsRef,

package/src/sqlite-driver-fallback.test.ts

@@ -0,0 +1,184 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, beforeEach, afterAll, vi } from 'vitest';
+import {
+  resolveSqliteDriver,
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+} from './sqlite-driver-fallback.js';
+
+// Shared, mutable test state read by the mocked driver constructors. `vi.hoisted`
+// makes it available inside the hoisted `vi.mock` factories below.
+const state = vi.hoisted(() => ({
+  /** Make the native better-sqlite3 driver throw a NODE_MODULE_VERSION-style error. */
+  nativeFails: false,
+  /** Make the wasm SQLite driver fail to connect (forces the in-memory last resort). */
+  wasmFails: false,
+  nativeConfigs: [] as any[],
+  wasmConfigs: [] as any[],
+  memoryCount: 0,
+}));
+
+const ABI_ERROR_MESSAGE =
+  "The module '/x/better_sqlite3.node' was compiled against a different Node.js version " +
+  'using NODE_MODULE_VERSION 141. This version of Node.js requires NODE_MODULE_VERSION 127. ' +
+  'Please try re-compiling or re-installing the module.';
+
+vi.mock('@objectstack/driver-sql', () => {
+  class SqlDriver {
+    public readonly name = 'com.objectstack.driver.sql';
+    constructor(public readonly config: any) {
+      state.nativeConfigs.push(config);
+    }
+    async connect(): Promise<void> {
+      // Mirrors the real driver: connect() runs mkdir + a PRAGMA whose error it
+      // swallows — so it is NOT where the ABI failure surfaces.
+    }
+    async execute(_sql: string): Promise<unknown> {
+      // better-sqlite3 loads its native addon lazily at the first query, so the
+      // ABI mismatch surfaces here (the SELECT 1 probe), not at construction.
+      if (state.nativeFails) throw new Error(ABI_ERROR_MESSAGE);
+      return [{ ok: 1 }];
+    }
+    async disconnect(): Promise<void> {}
+  }
+  return { SqlDriver };
+});
+
+vi.mock('@objectstack/driver-sqlite-wasm', () => {
+  class SqliteWasmDriver {
+    public readonly name = 'com.objectstack.driver.sqlite-wasm';
+    constructor(public readonly config: any) {
+      state.wasmConfigs.push(config);
+    }
+    async connect(): Promise<void> {
+      if (state.wasmFails) throw new Error('wasm sqlite failed to initialise');
+    }
+    async execute(): Promise<unknown> {
+      return [];
+    }
+    async disconnect(): Promise<void> {}
+  }
+  return { SqliteWasmDriver };
+});
+
+vi.mock('@objectstack/driver-memory', () => {
+  class InMemoryDriver {
+    public readonly name = 'com.objectstack.driver.memory';
+    constructor() {
+      state.memoryCount += 1;
+    }
+  }
+  return { InMemoryDriver };
+});
+
+describe('resolveSqliteDriver — native better-sqlite3 → wasm → in-memory step-down (#2229)', () => {
+  beforeEach(() => {
+    state.nativeFails = false;
+    state.wasmFails = false;
+    state.nativeConfigs = [];
+    state.wasmConfigs = [];
+    state.memoryCount = 0;
+  });
+
+  it('uses native better-sqlite3 on the happy path (no fallback, no warning)', async () => {
+    const warn = vi.fn();
+    const resolved = await resolveSqliteDriver({ filename: ':memory:', dev: true, warn });
+
+    expect(resolved.engine).toBe('better-sqlite3');
+    expect(resolved.label).toBe('SqlDriver(sqlite)');
+    expect(resolved.driver.name).toBe('com.objectstack.driver.sql');
+    expect(warn).not.toHaveBeenCalled();
+    expect(state.wasmConfigs).toHaveLength(0);
+    expect(state.memoryCount).toBe(0);
+  });
+
+  it('falls back to wasm SQLite when the native addon fails to load, emitting the warning', async () => {
+    state.nativeFails = true;
+    const warn = vi.fn();
+
+    const resolved = await resolveSqliteDriver({
+      filename: '/tmp/proj/.objectstack/data/dev.db',
+      dev: true,
+      warn,
+    });
+
+    expect(resolved.engine).toBe('sqlite-wasm');
+    expect(resolved.label).toBe('SqliteWasmDriver');
+    expect(resolved.driver.name).toBe('com.objectstack.driver.sqlite-wasm');
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith(NATIVE_SQLITE_WASM_FALLBACK_WARNING);
+    // The persistent file path is preserved (real on-disk persistence via wasm).
+    expect(state.wasmConfigs[0].filename).toBe('/tmp/proj/.objectstack/data/dev.db');
+    expect(state.wasmConfigs[0].persist).toBe('on-write');
+    expect(state.memoryCount).toBe(0);
+  });
+
+  it('uses on-disconnect persistence for an ephemeral :memory: wasm fallback', async () => {
+    state.nativeFails = true;
+    const resolved = await resolveSqliteDriver({ filename: ':memory:', dev: true, warn: vi.fn() });
+
+    expect(resolved.engine).toBe('sqlite-wasm');
+    expect(state.wasmConfigs[0].filename).toBe(':memory:');
+    expect(state.wasmConfigs[0].persist).toBe('on-disconnect');
+  });
+
+  it('drops to InMemoryDriver as a dev-only last resort when neither native nor wasm load', async () => {
+    state.nativeFails = true;
+    state.wasmFails = true;
+    const warn = vi.fn();
+
+    const resolved = await resolveSqliteDriver({ filename: ':memory:', dev: true, warn });
+
+    expect(resolved.engine).toBe('memory');
+    expect(resolved.label).toBe('InMemoryDriver');
+    expect(state.memoryCount).toBe(1);
+    expect(warn).toHaveBeenCalledWith(NATIVE_SQLITE_MEMORY_FALLBACK_WARNING);
+  });
+
+  it('forwards autoMigrate / schemaMode to the native driver', async () => {
+    await resolveSqliteDriver({ filename: ':memory:', dev: true, autoMigrate: 'safe', schemaMode: 'managed' });
+    expect(state.nativeConfigs[0]).toMatchObject({
+      client: 'better-sqlite3',
+      useNullAsDefault: true,
+      autoMigrate: 'safe',
+      schemaMode: 'managed',
+    });
+  });
+
+  it('production (dev=false) is fail-closed — returns native unprobed, never degrades', async () => {
+    state.nativeFails = true;
+    const warn = vi.fn();
+
+    const resolved = await resolveSqliteDriver({ filename: '/tmp/prod.db', dev: false, warn });
+
+    // The native driver is handed back as-is so the ABI failure surfaces loudly
+    // at first use — we must NOT swap in wasm/mingo behind the operator's back.
+    expect(resolved.engine).toBe('better-sqlite3');
+    expect(resolved.label).toBe('SqlDriver(sqlite)');
+    expect(warn).not.toHaveBeenCalled();
+    expect(state.wasmConfigs).toHaveLength(0);
+    expect(state.memoryCount).toBe(0);
+  });
+
+  describe('dev gate defaults to NODE_ENV when not passed explicitly', () => {
+    const originalNodeEnv = process.env.NODE_ENV;
+    afterAll(() => {
+      process.env.NODE_ENV = originalNodeEnv;
+    });
+
+    it('falls back to wasm when dev is omitted and NODE_ENV=development', async () => {
+      state.nativeFails = true;
+      process.env.NODE_ENV = 'development';
+      const resolved = await resolveSqliteDriver({ filename: ':memory:', warn: vi.fn() });
+      expect(resolved.engine).toBe('sqlite-wasm');
+    });
+
+    it('is fail-closed when dev is omitted and NODE_ENV=production', async () => {
+      state.nativeFails = true;
+      process.env.NODE_ENV = 'production';
+      const resolved = await resolveSqliteDriver({ filename: ':memory:', warn: vi.fn() });
+      expect(resolved.engine).toBe('better-sqlite3');
+    });
+  });
+});

package/src/sqlite-driver-fallback.ts

@@ -0,0 +1,195 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Shared native-`better-sqlite3` → wasm SQLite → in-memory step-down for any
+ * sqlite-via-`better-sqlite3` construction (issue #2229).
+ *
+ * ## Why a probe is necessary
+ *
+ * `better-sqlite3` loads its native `.node` addon LAZILY — not at
+ * `require('better-sqlite3')`, and not even at knex construction, but at the
+ * first pool-connection acquire (`new Database(file)`), i.e. the first query.
+ * So an ABI mismatch (a cached prebuilt binary built for a different Node
+ * version — `NODE_MODULE_VERSION` mismatch) is invisible at boot and only
+ * surfaces much later as a runtime `Find operation failed` on the first read.
+ *
+ * This helper makes the failure observable up-front by actively probing: it
+ * opens a connection and runs a cheap `SELECT 1`, which forces the native addon
+ * to load. (`connect()` alone is NOT a reliable probe: for SQLite it only runs
+ * `mkdir` + a `PRAGMA` whose error is swallowed internally — so we additionally
+ * issue a raw `SELECT 1`, which propagates the load error.) On failure it steps
+ * down:
+ *
+ *   1. native `better-sqlite3`  — fast, real SQL
+ *   2. wasm SQLite              — pure-JS, real SQL + on-disk persistence, slower   [dev only]
+ *   3. in-memory (mingo)        — neither real SQL nor persistent                   [dev only, last resort]
+ *
+ * ## Dev vs production
+ *
+ * The wasm + in-memory step-down is GATED to dev. In production a native load
+ * failure is NOT silently swapped for a different engine: the error is re-thrown
+ * so it surfaces loudly (fail-closed) instead of an operator unknowingly running
+ * on wasm/mingo. This mirrors the existing `serve.ts` default-dev fallback and
+ * hoists it into one place shared by every sqlite construction site.
+ */
+
+/** Which engine the resolver ultimately produced. */
+export type SqliteFallbackEngine = 'better-sqlite3' | 'sqlite-wasm' | 'memory';
+
+export interface ResolveSqliteDriverOptions {
+  /**
+   * SQLite filename — `:memory:` for an ephemeral database, or an absolute /
+   * relative path for a persistent file. Preserved across the wasm fallback so
+   * a persistent `file:` database keeps its on-disk persistence through wasm.
+   * Pass the raw filename (callers strip any `file:` / `sqlite:` scheme first).
+   */
+  filename: string;
+  /**
+   * Gates the wasm + in-memory step-down. When `true` (dev) a native ABI/load
+   * failure steps down the chain with a warning. When `false` (production) the
+   * native driver is returned unprobed so a failure surfaces loudly at first use
+   * (fail-closed) — we never silently degrade behind the operator's back.
+   * Defaults to `process.env.NODE_ENV === 'development'`.
+   */
+  dev?: boolean;
+  /** Forwarded to the native SqlDriver (dev loosen-only self-heal, #2186). */
+  autoMigrate?: 'off' | 'safe';
+  /** Forwarded to the SQL drivers (external schema mode, ADR-0015). */
+  schemaMode?: string;
+  /**
+   * Warning sink for the step-down messages. Defaults to `console.warn`.
+   * `serve.ts` passes a `chalk.yellow` wrapper so the banner stays consistent.
+   */
+  warn?: (message: string) => void;
+}
+
+export interface ResolvedSqliteDriver {
+  /** The concrete engine driver to register (e.g. via `DriverPlugin`). */
+  driver: any;
+  /** Which engine actually resolved. */
+  engine: SqliteFallbackEngine;
+  /** Banner label, matching `serve.ts`'s existing strings. */
+  label: string;
+}
+
+/**
+ * Warning emitted when native `better-sqlite3` is unavailable but wasm SQLite
+ * loads. Kept byte-for-byte identical to the original `serve.ts` text so the
+ * dev experience is the same regardless of which construction site triggers it.
+ */
+export const NATIVE_SQLITE_WASM_FALLBACK_WARNING =
+  '  ⚠ native better-sqlite3 unavailable (ABI mismatch or not built) — dev using wasm SQLite (real SQL, slower).\n' +
+  '    Rebuild better-sqlite3 for native speed, or set OS_DATABASE_DRIVER=sqlite-wasm to silence this.';
+
+/** Warning emitted when neither native nor wasm SQLite loads (dev last resort). */
+export const NATIVE_SQLITE_MEMORY_FALLBACK_WARNING =
+  '  ⚠ neither native nor wasm SQLite available — dev falling back to InMemoryDriver (mingo, not real SQL).\n' +
+  '    Rebuild better-sqlite3, or set OS_DATABASE_URL / OS_DATABASE_DRIVER for SQL fidelity.';
+
+/** `:memory:` and other `:`-prefixed pseudo-filenames are never persisted. */
+function isEphemeralFilename(filename: string): boolean {
+  return filename === ':memory:' || filename.startsWith(':');
+}
+
+/**
+ * Probe a `better-sqlite3` SQLite construction and, in dev, step down to wasm
+ * SQLite (then in-memory) when the native addon cannot load.
+ *
+ * @see {@link ResolveSqliteDriverOptions}
+ */
+export async function resolveSqliteDriver(
+  opts: ResolveSqliteDriverOptions,
+): Promise<ResolvedSqliteDriver> {
+  const { filename } = opts;
+  const dev = opts.dev ?? process.env.NODE_ENV === 'development';
+  const warn =
+    opts.warn ??
+    ((message: string) => {
+      try {
+        // eslint-disable-next-line no-console
+        console.warn(message);
+      } catch {
+        /* ignore */
+      }
+    });
+
+  const { SqlDriver } = await import('@objectstack/driver-sql');
+
+  const buildNative = () =>
+    new SqlDriver({
+      client: 'better-sqlite3',
+      connection: { filename },
+      useNullAsDefault: true,
+      ...(opts.autoMigrate ? { autoMigrate: opts.autoMigrate } : {}),
+      ...(opts.schemaMode ? { schemaMode: opts.schemaMode } : {}),
+    } as any);
+
+  // Production: never silently swap engines. Construct the native driver and
+  // hand it back UNPROBED — exactly the historical behavior. A native load
+  // failure surfaces loudly at first use (fail-closed).
+  if (!dev) {
+    return { driver: buildNative(), engine: 'better-sqlite3', label: 'SqlDriver(sqlite)' };
+  }
+
+  // ── Dev: probe-by-connect, step down on native ABI/load failure. ──────────
+
+  // 1. Native better-sqlite3.
+  let nativeDriver: any;
+  let nativeOk = false;
+  try {
+    nativeDriver = buildNative();
+    // connect() runs mkdir (so a SELECT on a file DB whose dir is missing does
+    // not false-positive as an ABI failure) + a PRAGMA whose error it swallows;
+    // the raw SELECT 1 below is what reliably forces the native addon to load
+    // and PROPAGATES an ABI mismatch.
+    await nativeDriver.connect();
+    await nativeDriver.execute('SELECT 1');
+    nativeOk = true;
+  } catch {
+    nativeOk = false;
+    if (typeof nativeDriver?.disconnect === 'function') {
+      try {
+        await nativeDriver.disconnect();
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  if (nativeOk) {
+    return { driver: nativeDriver, engine: 'better-sqlite3', label: 'SqlDriver(sqlite)' };
+  }
+
+  // 2. wasm SQLite — real SQL semantics + on-disk persistence, no native build.
+  let wasmDriver: any;
+  let wasmOk = false;
+  try {
+    const { SqliteWasmDriver } = await import('@objectstack/driver-sqlite-wasm');
+    wasmDriver = new SqliteWasmDriver({
+      filename,
+      // Match the existing construction sites: ephemeral DBs flush on
+      // disconnect; a persistent file flushes on every write so AI-authored
+      // data survives an unclean dev-server kill.
+      persist: isEphemeralFilename(filename) ? 'on-disconnect' : 'on-write',
+    } as any);
+    await wasmDriver.connect();
+    wasmOk = true;
+  } catch {
+    wasmOk = false;
+    if (typeof wasmDriver?.disconnect === 'function') {
+      try {
+        await wasmDriver.disconnect();
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  if (wasmOk) {
+    warn(NATIVE_SQLITE_WASM_FALLBACK_WARNING);
+    return { driver: wasmDriver, engine: 'sqlite-wasm', label: 'SqliteWasmDriver' };
+  }
+
+  // 3. In-memory (mingo) — dev-only last resort. Not real SQL, not persistent.
+  const { InMemoryDriver } = await import('@objectstack/driver-memory');
+  warn(NATIVE_SQLITE_MEMORY_FALLBACK_WARNING);
+  return { driver: new InMemoryDriver(), engine: 'memory', label: 'InMemoryDriver' };
+}