@objectstack/service-datasource 10.2.0 → 11.0.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/service-datasource@10.2.0 build /home/runner/work/framework/framework/packages/services/service-datasource
+> @objectstack/service-datasource@11.0.0 build /home/runner/work/framework/framework/packages/services/service-datasource
 > tsup
 
 CLI Building entry: src/index.ts, src/contracts/index.ts
@@ -10,23 +10,31 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.js               52.34 KB
-ESM dist/contracts/index.js     133.00 B
-ESM dist/chunk-XLS4RP7B.js      185.00 B
-ESM dist/index.js.map           129.15 KB
-ESM dist/contracts/index.js.map 71.00 B
-ESM dist/chunk-XLS4RP7B.js.map  3.10 KB
-ESM ⚡️ Build success in 934ms
-CJS dist/index.cjs               63.66 KB
-CJS dist/contracts/index.cjs     242.00 B
-CJS dist/chunk-BI2SYWLC.cjs      280.00 B
-CJS dist/index.cjs.map           110.35 KB
-CJS dist/contracts/index.cjs.map 304.00 B
-CJS dist/chunk-BI2SYWLC.cjs.map  3.38 KB
-CJS ⚡️ Build success in 1084ms
+ESM dist/index.js                               52.67 KB
+ESM dist/chunk-XLS4RP7B.js                      185.00 B
+ESM dist/sqlite-driver-fallback-BPFQYLX7.js     314.00 B
+ESM dist/chunk-JRBGOCRJ.js                      2.96 KB
+ESM dist/contracts/index.js                     133.00 B
+ESM dist/index.js.map                           130.13 KB
+ESM dist/chunk-XLS4RP7B.js.map                  3.10 KB
+ESM dist/sqlite-driver-fallback-BPFQYLX7.js.map 71.00 B
+ESM dist/chunk-JRBGOCRJ.js.map                  9.53 KB
+ESM dist/contracts/index.js.map                 71.00 B
+ESM ⚡️ Build success in 1082ms
+CJS dist/index.cjs                               64.11 KB
+CJS dist/contracts/index.cjs                     242.00 B
+CJS dist/chunk-BI2SYWLC.cjs                      280.00 B
+CJS dist/sqlite-driver-fallback-JX4XOICD.cjs     473.00 B
+CJS dist/chunk-76HQ74MX.cjs                      4.33 KB
+CJS dist/index.cjs.map                           111.29 KB
+CJS dist/contracts/index.cjs.map                 304.00 B
+CJS dist/chunk-BI2SYWLC.cjs.map                  3.38 KB
+CJS dist/sqlite-driver-fallback-JX4XOICD.cjs.map 356.00 B
+CJS dist/chunk-76HQ74MX.cjs.map                  10.74 KB
+CJS ⚡️ Build success in 1091ms
 DTS Build start
-DTS ⚡️ Build success in 18283ms
-DTS dist/index.d.ts            28.97 KB
+DTS ⚡️ Build success in 14612ms
+DTS dist/index.d.ts            33.63 KB
 DTS dist/contracts/index.d.ts  11.03 KB
-DTS dist/index.d.cts           28.97 KB
+DTS dist/index.d.cts           33.63 KB
 DTS dist/contracts/index.d.cts 11.03 KB

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @objectstack/service-external-datasource
 
+## 11.0.0
+
+### Patch Changes
+
+- Updated dependencies [ab5718a]
+- Updated dependencies [4845c12]
+- Updated dependencies [c1a754a]
+- Updated dependencies [6fbe91f]
+- Updated dependencies [715d667]
+- Updated dependencies [5eef4cf]
+- Updated dependencies [72759e1]
+- Updated dependencies [6c4fbd9]
+- Updated dependencies [ef3ed67]
+- Updated dependencies [cd51229]
+- Updated dependencies [7697a0e]
+- Updated dependencies [e7e04f1]
+- Updated dependencies [cfd5ac4]
+- Updated dependencies [2be5c1f]
+- Updated dependencies [ad143ce]
+- Updated dependencies [5c4a8c8]
+- Updated dependencies [3afaeed]
+- Updated dependencies [8801c02]
+- Updated dependencies [3d04e06]
+- Updated dependencies [4a84c98]
+- Updated dependencies [c715d25]
+- Updated dependencies [aa33b02]
+- Updated dependencies [d980f0d]
+- Updated dependencies [a658523]
+- Updated dependencies [82ff91c]
+- Updated dependencies [638f472]
+  - @objectstack/spec@11.0.0
+  - @objectstack/core@11.0.0
+
+## 10.3.0
+
+### Patch Changes
+
+- f2063f3: fix(cli): extend native better-sqlite3 → wasm SQLite auto-fallback to the persistent-file / `--artifact` dev path (#2229)
+
+  The native-`better-sqlite3` → wasm SQLite → in-memory step-down previously only
+  guarded the zero-config `:memory:` dev branch of `serve`. A normal
+  `objectstack dev` run never reaches it — `dev` injects a persistent `file:` DB
+  (so AI-authored data survives restarts) and `--artifact` boots resolve sqlite
+  through the datasource factory — both of which constructed
+  `better-sqlite3` directly with no probe and no fallback. An ABI mismatch (e.g.
+  a cached prebuilt binary built for a different Node version) was therefore not
+  caught at boot and surfaced later as a runtime `Find operation failed` on the
+  first query.
+
+  The probe-by-connect + step-down is now hoisted into a shared
+  `resolveSqliteDriver` helper (`@objectstack/service-datasource`) and applied to
+  both previously-unguarded sqlite construction sites: the explicit `sqlite` /
+  `file:` branch in `serve.ts` and the sqlite branch of the default datasource
+  driver factory. better-sqlite3 loads its native addon lazily (first query), so
+  the helper forces the load with a `SELECT 1` and, **in dev only**, steps down to
+  wasm SQLite (real SQL + on-disk persistence — the same `file:` keeps working)
+  then to the in-memory driver as a last resort, emitting the existing
+  `⚠ native better-sqlite3 unavailable …` warning. In production the native driver
+  is returned unprobed so a load failure surfaces loudly (fail-closed) rather than
+  silently degrading to a different engine.
+
+  - @objectstack/spec@10.3.0
+  - @objectstack/core@10.3.0
+
 ## 10.2.0
 
 ### Patch Changes

package/dist/chunk-76HQ74MX.cjs

@@ -0,0 +1,82 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/sqlite-driver-fallback.ts
+var NATIVE_SQLITE_WASM_FALLBACK_WARNING = "  \u26A0 native better-sqlite3 unavailable (ABI mismatch or not built) \u2014 dev using wasm SQLite (real SQL, slower).\n    Rebuild better-sqlite3 for native speed, or set OS_DATABASE_DRIVER=sqlite-wasm to silence this.";
+var NATIVE_SQLITE_MEMORY_FALLBACK_WARNING = "  \u26A0 neither native nor wasm SQLite available \u2014 dev falling back to InMemoryDriver (mingo, not real SQL).\n    Rebuild better-sqlite3, or set OS_DATABASE_URL / OS_DATABASE_DRIVER for SQL fidelity.";
+function isEphemeralFilename(filename) {
+  return filename === ":memory:" || filename.startsWith(":");
+}
+async function resolveSqliteDriver(opts) {
+  const { filename } = opts;
+  const dev = _nullishCoalesce(opts.dev, () => ( process.env.NODE_ENV === "development"));
+  const warn = _nullishCoalesce(opts.warn, () => ( ((message) => {
+    try {
+      console.warn(message);
+    } catch (e) {
+    }
+  })));
+  const { SqlDriver } = await Promise.resolve().then(() => _interopRequireWildcard(require("@objectstack/driver-sql")));
+  const buildNative = () => new SqlDriver({
+    client: "better-sqlite3",
+    connection: { filename },
+    useNullAsDefault: true,
+    ...opts.autoMigrate ? { autoMigrate: opts.autoMigrate } : {},
+    ...opts.schemaMode ? { schemaMode: opts.schemaMode } : {}
+  });
+  if (!dev) {
+    return { driver: buildNative(), engine: "better-sqlite3", label: "SqlDriver(sqlite)" };
+  }
+  let nativeDriver;
+  let nativeOk = false;
+  try {
+    nativeDriver = buildNative();
+    await nativeDriver.connect();
+    await nativeDriver.execute("SELECT 1");
+    nativeOk = true;
+  } catch (e2) {
+    nativeOk = false;
+    if (typeof _optionalChain([nativeDriver, 'optionalAccess', _ => _.disconnect]) === "function") {
+      try {
+        await nativeDriver.disconnect();
+      } catch (e3) {
+      }
+    }
+  }
+  if (nativeOk) {
+    return { driver: nativeDriver, engine: "better-sqlite3", label: "SqlDriver(sqlite)" };
+  }
+  let wasmDriver;
+  let wasmOk = false;
+  try {
+    const { SqliteWasmDriver } = await Promise.resolve().then(() => _interopRequireWildcard(require("@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"
+    });
+    await wasmDriver.connect();
+    wasmOk = true;
+  } catch (e4) {
+    wasmOk = false;
+    if (typeof _optionalChain([wasmDriver, 'optionalAccess', _2 => _2.disconnect]) === "function") {
+      try {
+        await wasmDriver.disconnect();
+      } catch (e5) {
+      }
+    }
+  }
+  if (wasmOk) {
+    warn(NATIVE_SQLITE_WASM_FALLBACK_WARNING);
+    return { driver: wasmDriver, engine: "sqlite-wasm", label: "SqliteWasmDriver" };
+  }
+  const { InMemoryDriver } = await Promise.resolve().then(() => _interopRequireWildcard(require("@objectstack/driver-memory")));
+  warn(NATIVE_SQLITE_MEMORY_FALLBACK_WARNING);
+  return { driver: new InMemoryDriver(), engine: "memory", label: "InMemoryDriver" };
+}
+
+
+
+
+
+exports.NATIVE_SQLITE_WASM_FALLBACK_WARNING = NATIVE_SQLITE_WASM_FALLBACK_WARNING; exports.NATIVE_SQLITE_MEMORY_FALLBACK_WARNING = NATIVE_SQLITE_MEMORY_FALLBACK_WARNING; exports.resolveSqliteDriver = resolveSqliteDriver;
+//# sourceMappingURL=chunk-76HQ74MX.cjs.map

package/dist/chunk-76HQ74MX.cjs.map

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

package/dist/chunk-JRBGOCRJ.js

@@ -0,0 +1,82 @@
+// src/sqlite-driver-fallback.ts
+var NATIVE_SQLITE_WASM_FALLBACK_WARNING = "  \u26A0 native better-sqlite3 unavailable (ABI mismatch or not built) \u2014 dev using wasm SQLite (real SQL, slower).\n    Rebuild better-sqlite3 for native speed, or set OS_DATABASE_DRIVER=sqlite-wasm to silence this.";
+var NATIVE_SQLITE_MEMORY_FALLBACK_WARNING = "  \u26A0 neither native nor wasm SQLite available \u2014 dev falling back to InMemoryDriver (mingo, not real SQL).\n    Rebuild better-sqlite3, or set OS_DATABASE_URL / OS_DATABASE_DRIVER for SQL fidelity.";
+function isEphemeralFilename(filename) {
+  return filename === ":memory:" || filename.startsWith(":");
+}
+async function resolveSqliteDriver(opts) {
+  const { filename } = opts;
+  const dev = opts.dev ?? process.env.NODE_ENV === "development";
+  const warn = opts.warn ?? ((message) => {
+    try {
+      console.warn(message);
+    } catch {
+    }
+  });
+  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 } : {}
+  });
+  if (!dev) {
+    return { driver: buildNative(), engine: "better-sqlite3", label: "SqlDriver(sqlite)" };
+  }
+  let nativeDriver;
+  let nativeOk = false;
+  try {
+    nativeDriver = buildNative();
+    await nativeDriver.connect();
+    await nativeDriver.execute("SELECT 1");
+    nativeOk = true;
+  } catch {
+    nativeOk = false;
+    if (typeof nativeDriver?.disconnect === "function") {
+      try {
+        await nativeDriver.disconnect();
+      } catch {
+      }
+    }
+  }
+  if (nativeOk) {
+    return { driver: nativeDriver, engine: "better-sqlite3", label: "SqlDriver(sqlite)" };
+  }
+  let wasmDriver;
+  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"
+    });
+    await wasmDriver.connect();
+    wasmOk = true;
+  } catch {
+    wasmOk = false;
+    if (typeof wasmDriver?.disconnect === "function") {
+      try {
+        await wasmDriver.disconnect();
+      } catch {
+      }
+    }
+  }
+  if (wasmOk) {
+    warn(NATIVE_SQLITE_WASM_FALLBACK_WARNING);
+    return { driver: wasmDriver, engine: "sqlite-wasm", label: "SqliteWasmDriver" };
+  }
+  const { InMemoryDriver } = await import("@objectstack/driver-memory");
+  warn(NATIVE_SQLITE_MEMORY_FALLBACK_WARNING);
+  return { driver: new InMemoryDriver(), engine: "memory", label: "InMemoryDriver" };
+}
+
+export {
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+  resolveSqliteDriver
+};
+//# sourceMappingURL=chunk-JRBGOCRJ.js.map

package/dist/chunk-JRBGOCRJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sqlite-driver-fallback.ts"],"sourcesContent":["// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.\n\n/**\n * Shared native-`better-sqlite3` → wasm SQLite → in-memory step-down for any\n * sqlite-via-`better-sqlite3` construction (issue #2229).\n *\n * ## Why a probe is necessary\n *\n * `better-sqlite3` loads its native `.node` addon LAZILY — not at\n * `require('better-sqlite3')`, and not even at knex construction, but at the\n * first pool-connection acquire (`new Database(file)`), i.e. the first query.\n * So an ABI mismatch (a cached prebuilt binary built for a different Node\n * version — `NODE_MODULE_VERSION` mismatch) is invisible at boot and only\n * surfaces much later as a runtime `Find operation failed` on the first read.\n *\n * This helper makes the failure observable up-front by actively probing: it\n * opens a connection and runs a cheap `SELECT 1`, which forces the native addon\n * to load. (`connect()` alone is NOT a reliable probe: for SQLite it only runs\n * `mkdir` + a `PRAGMA` whose error is swallowed internally — so we additionally\n * issue a raw `SELECT 1`, which propagates the load error.) On failure it steps\n * down:\n *\n *   1. native `better-sqlite3`  — fast, real SQL\n *   2. wasm SQLite              — pure-JS, real SQL + on-disk persistence, slower   [dev only]\n *   3. in-memory (mingo)        — neither real SQL nor persistent                   [dev only, last resort]\n *\n * ## Dev vs production\n *\n * The wasm + in-memory step-down is GATED to dev. In production a native load\n * failure is NOT silently swapped for a different engine: the error is re-thrown\n * so it surfaces loudly (fail-closed) instead of an operator unknowingly running\n * on wasm/mingo. This mirrors the existing `serve.ts` default-dev fallback and\n * hoists it into one place shared by every sqlite construction site.\n */\n\n/** Which engine the resolver ultimately produced. */\nexport type SqliteFallbackEngine = 'better-sqlite3' | 'sqlite-wasm' | 'memory';\n\nexport interface ResolveSqliteDriverOptions {\n  /**\n   * SQLite filename — `:memory:` for an ephemeral database, or an absolute /\n   * relative path for a persistent file. Preserved across the wasm fallback so\n   * a persistent `file:` database keeps its on-disk persistence through wasm.\n   * Pass the raw filename (callers strip any `file:` / `sqlite:` scheme first).\n   */\n  filename: string;\n  /**\n   * Gates the wasm + in-memory step-down. When `true` (dev) a native ABI/load\n   * failure steps down the chain with a warning. When `false` (production) the\n   * native driver is returned unprobed so a failure surfaces loudly at first use\n   * (fail-closed) — we never silently degrade behind the operator's back.\n   * Defaults to `process.env.NODE_ENV === 'development'`.\n   */\n  dev?: boolean;\n  /** Forwarded to the native SqlDriver (dev loosen-only self-heal, #2186). */\n  autoMigrate?: 'off' | 'safe';\n  /** Forwarded to the SQL drivers (external schema mode, ADR-0015). */\n  schemaMode?: string;\n  /**\n   * Warning sink for the step-down messages. Defaults to `console.warn`.\n   * `serve.ts` passes a `chalk.yellow` wrapper so the banner stays consistent.\n   */\n  warn?: (message: string) => void;\n}\n\nexport interface ResolvedSqliteDriver {\n  /** The concrete engine driver to register (e.g. via `DriverPlugin`). */\n  driver: any;\n  /** Which engine actually resolved. */\n  engine: SqliteFallbackEngine;\n  /** Banner label, matching `serve.ts`'s existing strings. */\n  label: string;\n}\n\n/**\n * Warning emitted when native `better-sqlite3` is unavailable but wasm SQLite\n * loads. Kept byte-for-byte identical to the original `serve.ts` text so the\n * dev experience is the same regardless of which construction site triggers it.\n */\nexport const NATIVE_SQLITE_WASM_FALLBACK_WARNING =\n  '  ⚠ native better-sqlite3 unavailable (ABI mismatch or not built) — dev using wasm SQLite (real SQL, slower).\\n' +\n  '    Rebuild better-sqlite3 for native speed, or set OS_DATABASE_DRIVER=sqlite-wasm to silence this.';\n\n/** Warning emitted when neither native nor wasm SQLite loads (dev last resort). */\nexport const NATIVE_SQLITE_MEMORY_FALLBACK_WARNING =\n  '  ⚠ neither native nor wasm SQLite available — dev falling back to InMemoryDriver (mingo, not real SQL).\\n' +\n  '    Rebuild better-sqlite3, or set OS_DATABASE_URL / OS_DATABASE_DRIVER for SQL fidelity.';\n\n/** `:memory:` and other `:`-prefixed pseudo-filenames are never persisted. */\nfunction isEphemeralFilename(filename: string): boolean {\n  return filename === ':memory:' || filename.startsWith(':');\n}\n\n/**\n * Probe a `better-sqlite3` SQLite construction and, in dev, step down to wasm\n * SQLite (then in-memory) when the native addon cannot load.\n *\n * @see {@link ResolveSqliteDriverOptions}\n */\nexport async function resolveSqliteDriver(\n  opts: ResolveSqliteDriverOptions,\n): Promise<ResolvedSqliteDriver> {\n  const { filename } = opts;\n  const dev = opts.dev ?? process.env.NODE_ENV === 'development';\n  const warn =\n    opts.warn ??\n    ((message: string) => {\n      try {\n        // eslint-disable-next-line no-console\n        console.warn(message);\n      } catch {\n        /* ignore */\n      }\n    });\n\n  const { SqlDriver } = await import('@objectstack/driver-sql');\n\n  const buildNative = () =>\n    new SqlDriver({\n      client: 'better-sqlite3',\n      connection: { filename },\n      useNullAsDefault: true,\n      ...(opts.autoMigrate ? { autoMigrate: opts.autoMigrate } : {}),\n      ...(opts.schemaMode ? { schemaMode: opts.schemaMode } : {}),\n    } as any);\n\n  // Production: never silently swap engines. Construct the native driver and\n  // hand it back UNPROBED — exactly the historical behavior. A native load\n  // failure surfaces loudly at first use (fail-closed).\n  if (!dev) {\n    return { driver: buildNative(), engine: 'better-sqlite3', label: 'SqlDriver(sqlite)' };\n  }\n\n  // ── Dev: probe-by-connect, step down on native ABI/load failure. ──────────\n\n  // 1. Native better-sqlite3.\n  let nativeDriver: any;\n  let nativeOk = false;\n  try {\n    nativeDriver = buildNative();\n    // connect() runs mkdir (so a SELECT on a file DB whose dir is missing does\n    // not false-positive as an ABI failure) + a PRAGMA whose error it swallows;\n    // the raw SELECT 1 below is what reliably forces the native addon to load\n    // and PROPAGATES an ABI mismatch.\n    await nativeDriver.connect();\n    await nativeDriver.execute('SELECT 1');\n    nativeOk = true;\n  } catch {\n    nativeOk = false;\n    if (typeof nativeDriver?.disconnect === 'function') {\n      try {\n        await nativeDriver.disconnect();\n      } catch {\n        /* ignore */\n      }\n    }\n  }\n  if (nativeOk) {\n    return { driver: nativeDriver, engine: 'better-sqlite3', label: 'SqlDriver(sqlite)' };\n  }\n\n  // 2. wasm SQLite — real SQL semantics + on-disk persistence, no native build.\n  let wasmDriver: any;\n  let wasmOk = false;\n  try {\n    const { SqliteWasmDriver } = await import('@objectstack/driver-sqlite-wasm');\n    wasmDriver = new SqliteWasmDriver({\n      filename,\n      // Match the existing construction sites: ephemeral DBs flush on\n      // disconnect; a persistent file flushes on every write so AI-authored\n      // data survives an unclean dev-server kill.\n      persist: isEphemeralFilename(filename) ? 'on-disconnect' : 'on-write',\n    } as any);\n    await wasmDriver.connect();\n    wasmOk = true;\n  } catch {\n    wasmOk = false;\n    if (typeof wasmDriver?.disconnect === 'function') {\n      try {\n        await wasmDriver.disconnect();\n      } catch {\n        /* ignore */\n      }\n    }\n  }\n  if (wasmOk) {\n    warn(NATIVE_SQLITE_WASM_FALLBACK_WARNING);\n    return { driver: wasmDriver, engine: 'sqlite-wasm', label: 'SqliteWasmDriver' };\n  }\n\n  // 3. In-memory (mingo) — dev-only last resort. Not real SQL, not persistent.\n  const { InMemoryDriver } = await import('@objectstack/driver-memory');\n  warn(NATIVE_SQLITE_MEMORY_FALLBACK_WARNING);\n  return { driver: new InMemoryDriver(), engine: 'memory', label: 'InMemoryDriver' };\n}\n"],"mappings":";AA+EO,IAAM,sCACX;AAIK,IAAM,wCACX;AAIF,SAAS,oBAAoB,UAA2B;AACtD,SAAO,aAAa,cAAc,SAAS,WAAW,GAAG;AAC3D;AAQA,eAAsB,oBACpB,MAC+B;AAC/B,QAAM,EAAE,SAAS,IAAI;AACrB,QAAM,MAAM,KAAK,OAAO,QAAQ,IAAI,aAAa;AACjD,QAAM,OACJ,KAAK,SACJ,CAAC,YAAoB;AACpB,QAAI;AAEF,cAAQ,KAAK,OAAO;AAAA,IACtB,QAAQ;AAAA,IAER;AAAA,EACF;AAEF,QAAM,EAAE,UAAU,IAAI,MAAM,OAAO,yBAAyB;AAE5D,QAAM,cAAc,MAClB,IAAI,UAAU;AAAA,IACZ,QAAQ;AAAA,IACR,YAAY,EAAE,SAAS;AAAA,IACvB,kBAAkB;AAAA,IAClB,GAAI,KAAK,cAAc,EAAE,aAAa,KAAK,YAAY,IAAI,CAAC;AAAA,IAC5D,GAAI,KAAK,aAAa,EAAE,YAAY,KAAK,WAAW,IAAI,CAAC;AAAA,EAC3D,CAAQ;AAKV,MAAI,CAAC,KAAK;AACR,WAAO,EAAE,QAAQ,YAAY,GAAG,QAAQ,kBAAkB,OAAO,oBAAoB;AAAA,EACvF;AAKA,MAAI;AACJ,MAAI,WAAW;AACf,MAAI;AACF,mBAAe,YAAY;AAK3B,UAAM,aAAa,QAAQ;AAC3B,UAAM,aAAa,QAAQ,UAAU;AACrC,eAAW;AAAA,EACb,QAAQ;AACN,eAAW;AACX,QAAI,OAAO,cAAc,eAAe,YAAY;AAClD,UAAI;AACF,cAAM,aAAa,WAAW;AAAA,MAChC,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AACA,MAAI,UAAU;AACZ,WAAO,EAAE,QAAQ,cAAc,QAAQ,kBAAkB,OAAO,oBAAoB;AAAA,EACtF;AAGA,MAAI;AACJ,MAAI,SAAS;AACb,MAAI;AACF,UAAM,EAAE,iBAAiB,IAAI,MAAM,OAAO,iCAAiC;AAC3E,iBAAa,IAAI,iBAAiB;AAAA,MAChC;AAAA;AAAA;AAAA;AAAA,MAIA,SAAS,oBAAoB,QAAQ,IAAI,kBAAkB;AAAA,IAC7D,CAAQ;AACR,UAAM,WAAW,QAAQ;AACzB,aAAS;AAAA,EACX,QAAQ;AACN,aAAS;AACT,QAAI,OAAO,YAAY,eAAe,YAAY;AAChD,UAAI;AACF,cAAM,WAAW,WAAW;AAAA,MAC9B,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AACA,MAAI,QAAQ;AACV,SAAK,mCAAmC;AACxC,WAAO,EAAE,QAAQ,YAAY,QAAQ,eAAe,OAAO,mBAAmB;AAAA,EAChF;AAGA,QAAM,EAAE,eAAe,IAAI,MAAM,OAAO,4BAA4B;AACpE,OAAK,qCAAqC;AAC1C,SAAO,EAAE,QAAQ,IAAI,eAAe,GAAG,QAAQ,UAAU,OAAO,iBAAiB;AACnF;","names":[]}

package/dist/index.cjs

@@ -2,6 +2,11 @@
 
 var _chunkBI2SYWLCcjs = require('./chunk-BI2SYWLC.cjs');
 
+
+
+
+var _chunk76HQ74MXcjs = require('./chunk-76HQ74MX.cjs');
+
 // src/external-datasource-service.ts
 
 
@@ -1114,7 +1119,7 @@ function buildMongoUrl(spec) {
   const auth = user ? `${encodeURIComponent(user)}:${encodeURIComponent(_nullishCoalesce(spec.secret, () => ( "")))}@` : "";
   return `mongodb://${auth}${host}:${port}/${db}`;
 }
-function createDefaultDatasourceDriverFactory() {
+function createDefaultDatasourceDriverFactory(options = {}) {
   return {
     supports(driverId) {
       return resolveKind(driverId) !== void 0;
@@ -1136,14 +1141,14 @@ function createDefaultDatasourceDriverFactory() {
         return toHandle(driver, () => sqlServerVersion(driver, "pg"));
       }
       if (kind === "sqlite") {
-        const { SqlDriver } = await Promise.resolve().then(() => _interopRequireWildcard(require("@objectstack/driver-sql")));
-        const driver = new SqlDriver({
-          client: "better-sqlite3",
-          connection: buildSqlConnection(spec, "better-sqlite3"),
-          useNullAsDefault: true,
+        const conn = buildSqlConnection(spec, "better-sqlite3");
+        const { resolveSqliteDriver: resolveSqliteDriver2 } = await Promise.resolve().then(() => _interopRequireWildcard(require("./sqlite-driver-fallback-JX4XOICD.cjs")));
+        const resolved = await resolveSqliteDriver2({
+          filename: _nullishCoalesce(conn.filename, () => ( ":memory:")),
+          dev: options.dev,
           ...schemaMode ? { schemaMode } : {}
         });
-        return toHandle(driver, () => sqlServerVersion(driver, "sqlite"));
+        return toHandle(resolved.driver, () => sqlServerVersion(resolved.driver, "sqlite"));
       }
       if (kind === "mongodb") {
         let MongoDBDriver;
@@ -1457,5 +1462,8 @@ function registerDatasourceAdminRoutes(server, ctx, basePath = "/api/v1") {
 
 
 
-exports.DatasourceAdminService = DatasourceAdminService; exports.DatasourceAdminServicePlugin = DatasourceAdminServicePlugin; exports.DatasourceConnectionService = DatasourceConnectionService; exports.ExternalDatasourceService = ExternalDatasourceService; exports.ExternalDatasourceServicePlugin = ExternalDatasourceServicePlugin; exports.allowAllConnectPolicy = _chunkBI2SYWLCcjs.allowAllConnectPolicy; exports.createDatasourceSecretBinder = createDatasourceSecretBinder; exports.createDefaultDatasourceDriverFactory = createDefaultDatasourceDriverFactory; exports.isDatasourceAddressed = isDatasourceAddressed; exports.parseCredentialsRef = parseCredentialsRef; exports.registerDatasourceAdminRoutes = registerDatasourceAdminRoutes; exports.toCredentialsRef = toCredentialsRef;
+
+
+
+exports.DatasourceAdminService = DatasourceAdminService; exports.DatasourceAdminServicePlugin = DatasourceAdminServicePlugin; exports.DatasourceConnectionService = DatasourceConnectionService; exports.ExternalDatasourceService = ExternalDatasourceService; exports.ExternalDatasourceServicePlugin = ExternalDatasourceServicePlugin; 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.allowAllConnectPolicy = _chunkBI2SYWLCcjs.allowAllConnectPolicy; exports.createDatasourceSecretBinder = createDatasourceSecretBinder; exports.createDefaultDatasourceDriverFactory = createDefaultDatasourceDriverFactory; exports.isDatasourceAddressed = isDatasourceAddressed; exports.parseCredentialsRef = parseCredentialsRef; exports.registerDatasourceAdminRoutes = registerDatasourceAdminRoutes; exports.resolveSqliteDriver = _chunk76HQ74MXcjs.resolveSqliteDriver; exports.toCredentialsRef = toCredentialsRef;
 //# sourceMappingURL=index.cjs.map