@objectstack/service-datasource 10.2.0 → 11.0.0

package/dist/index.d.cts

@@ -523,7 +523,100 @@ declare class DatasourceAdminServicePlugin implements Plugin {
  * lazily so a host that never builds (e.g.) a mongo connection doesn't pay for
  * the mongo SDK.
  */
-declare function createDefaultDatasourceDriverFactory(): IDatasourceDriverFactory;
+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;
+}
+declare function createDefaultDatasourceDriverFactory(options?: DefaultDatasourceDriverFactoryOptions): IDatasourceDriverFactory;
+
+/**
+ * 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. */
+type SqliteFallbackEngine = 'better-sqlite3' | 'sqlite-wasm' | 'memory';
+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;
+}
+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.
+ */
+declare const NATIVE_SQLITE_WASM_FALLBACK_WARNING: string;
+/** Warning emitted when neither native nor wasm SQLite loads (dev last resort). */
+declare const NATIVE_SQLITE_MEMORY_FALLBACK_WARNING: string;
+/**
+ * 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}
+ */
+declare function resolveSqliteDriver(opts: ResolveSqliteDriverOptions): Promise<ResolvedSqliteDriver>;
 
 /**
  * Default datasource SecretBinder — persists a runtime datasource's cleartext
@@ -611,4 +704,4 @@ declare function createDatasourceSecretBinder(deps: DatasourceSecretBinderDeps):
  */
 declare function registerDatasourceAdminRoutes(server: IHttpServer, ctx: PluginContext, basePath?: string): void;
 
-export { type ConnectResult, type ConnectStatus, type ConnectableDatasource, type ConnectionEngineLike, type ConnectionSecretResolver, DatasourceAdminService, type DatasourceAdminServiceConfig, DatasourceAdminServicePlugin, type DatasourceAdminServicePluginOptions, type DatasourceBoundObject, DatasourceConnectContext, DatasourceConnectPolicy, DatasourceConnectionService, type DatasourceConnectionServiceConfig, DatasourceDraft, type DatasourceLike, type DatasourceSecretBinder, type DatasourceSecretBinderDeps, DatasourceSummary, ExternalDatasourceService, type ExternalDatasourceServiceConfig, ExternalDatasourceServicePlugin, type ExternalDatasourceServicePluginOptions, IDatasourceAdminService, IDatasourceDriverFactory, type Logger$1 as Logger, type ObjectLike, type ProbeInput, type SecretBinder, SecretInput, type SecretStoreEngineLike, type StoredDatasource, TestConnectionResult, createDatasourceSecretBinder, createDefaultDatasourceDriverFactory, isDatasourceAddressed, parseCredentialsRef, registerDatasourceAdminRoutes, toCredentialsRef };
+export { type ConnectResult, type ConnectStatus, type ConnectableDatasource, type ConnectionEngineLike, type ConnectionSecretResolver, DatasourceAdminService, type DatasourceAdminServiceConfig, DatasourceAdminServicePlugin, type DatasourceAdminServicePluginOptions, type DatasourceBoundObject, DatasourceConnectContext, DatasourceConnectPolicy, DatasourceConnectionService, type DatasourceConnectionServiceConfig, DatasourceDraft, type DatasourceLike, type DatasourceSecretBinder, type DatasourceSecretBinderDeps, DatasourceSummary, ExternalDatasourceService, type ExternalDatasourceServiceConfig, ExternalDatasourceServicePlugin, type ExternalDatasourceServicePluginOptions, IDatasourceAdminService, IDatasourceDriverFactory, type Logger$1 as Logger, NATIVE_SQLITE_MEMORY_FALLBACK_WARNING, NATIVE_SQLITE_WASM_FALLBACK_WARNING, type ObjectLike, type ProbeInput, type ResolveSqliteDriverOptions, type ResolvedSqliteDriver, type SecretBinder, SecretInput, type SecretStoreEngineLike, type SqliteFallbackEngine, type StoredDatasource, TestConnectionResult, createDatasourceSecretBinder, createDefaultDatasourceDriverFactory, isDatasourceAddressed, parseCredentialsRef, registerDatasourceAdminRoutes, resolveSqliteDriver, toCredentialsRef };

package/dist/index.d.ts

@@ -523,7 +523,100 @@ declare class DatasourceAdminServicePlugin implements Plugin {
  * lazily so a host that never builds (e.g.) a mongo connection doesn't pay for
  * the mongo SDK.
  */
-declare function createDefaultDatasourceDriverFactory(): IDatasourceDriverFactory;
+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;
+}
+declare function createDefaultDatasourceDriverFactory(options?: DefaultDatasourceDriverFactoryOptions): IDatasourceDriverFactory;
+
+/**
+ * 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. */
+type SqliteFallbackEngine = 'better-sqlite3' | 'sqlite-wasm' | 'memory';
+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;
+}
+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.
+ */
+declare const NATIVE_SQLITE_WASM_FALLBACK_WARNING: string;
+/** Warning emitted when neither native nor wasm SQLite loads (dev last resort). */
+declare const NATIVE_SQLITE_MEMORY_FALLBACK_WARNING: string;
+/**
+ * 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}
+ */
+declare function resolveSqliteDriver(opts: ResolveSqliteDriverOptions): Promise<ResolvedSqliteDriver>;
 
 /**
  * Default datasource SecretBinder — persists a runtime datasource's cleartext
@@ -611,4 +704,4 @@ declare function createDatasourceSecretBinder(deps: DatasourceSecretBinderDeps):
  */
 declare function registerDatasourceAdminRoutes(server: IHttpServer, ctx: PluginContext, basePath?: string): void;
 
-export { type ConnectResult, type ConnectStatus, type ConnectableDatasource, type ConnectionEngineLike, type ConnectionSecretResolver, DatasourceAdminService, type DatasourceAdminServiceConfig, DatasourceAdminServicePlugin, type DatasourceAdminServicePluginOptions, type DatasourceBoundObject, DatasourceConnectContext, DatasourceConnectPolicy, DatasourceConnectionService, type DatasourceConnectionServiceConfig, DatasourceDraft, type DatasourceLike, type DatasourceSecretBinder, type DatasourceSecretBinderDeps, DatasourceSummary, ExternalDatasourceService, type ExternalDatasourceServiceConfig, ExternalDatasourceServicePlugin, type ExternalDatasourceServicePluginOptions, IDatasourceAdminService, IDatasourceDriverFactory, type Logger$1 as Logger, type ObjectLike, type ProbeInput, type SecretBinder, SecretInput, type SecretStoreEngineLike, type StoredDatasource, TestConnectionResult, createDatasourceSecretBinder, createDefaultDatasourceDriverFactory, isDatasourceAddressed, parseCredentialsRef, registerDatasourceAdminRoutes, toCredentialsRef };
+export { type ConnectResult, type ConnectStatus, type ConnectableDatasource, type ConnectionEngineLike, type ConnectionSecretResolver, DatasourceAdminService, type DatasourceAdminServiceConfig, DatasourceAdminServicePlugin, type DatasourceAdminServicePluginOptions, type DatasourceBoundObject, DatasourceConnectContext, DatasourceConnectPolicy, DatasourceConnectionService, type DatasourceConnectionServiceConfig, DatasourceDraft, type DatasourceLike, type DatasourceSecretBinder, type DatasourceSecretBinderDeps, DatasourceSummary, ExternalDatasourceService, type ExternalDatasourceServiceConfig, ExternalDatasourceServicePlugin, type ExternalDatasourceServicePluginOptions, IDatasourceAdminService, IDatasourceDriverFactory, type Logger$1 as Logger, NATIVE_SQLITE_MEMORY_FALLBACK_WARNING, NATIVE_SQLITE_WASM_FALLBACK_WARNING, type ObjectLike, type ProbeInput, type ResolveSqliteDriverOptions, type ResolvedSqliteDriver, type SecretBinder, SecretInput, type SecretStoreEngineLike, type SqliteFallbackEngine, type StoredDatasource, TestConnectionResult, createDatasourceSecretBinder, createDefaultDatasourceDriverFactory, isDatasourceAddressed, parseCredentialsRef, registerDatasourceAdminRoutes, resolveSqliteDriver, toCredentialsRef };

package/dist/index.js

@@ -1,6 +1,11 @@
 import {
   allowAllConnectPolicy
 } from "./chunk-XLS4RP7B.js";
+import {
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
+  resolveSqliteDriver
+} from "./chunk-JRBGOCRJ.js";
 
 // src/external-datasource-service.ts
 import {
@@ -1114,7 +1119,7 @@ function buildMongoUrl(spec) {
   const auth = user ? `${encodeURIComponent(user)}:${encodeURIComponent(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 import("@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 import("./sqlite-driver-fallback-BPFQYLX7.js");
+        const resolved = await resolveSqliteDriver2({
+          filename: 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;
@@ -1450,12 +1455,15 @@ export {
   DatasourceConnectionService,
   ExternalDatasourceService,
   ExternalDatasourceServicePlugin,
+  NATIVE_SQLITE_MEMORY_FALLBACK_WARNING,
+  NATIVE_SQLITE_WASM_FALLBACK_WARNING,
   allowAllConnectPolicy,
   createDatasourceSecretBinder,
   createDefaultDatasourceDriverFactory,
   isDatasourceAddressed,
   parseCredentialsRef,
   registerDatasourceAdminRoutes,
+  resolveSqliteDriver,
   toCredentialsRef
 };
 //# sourceMappingURL=index.js.map