@fougere/adapter-sql 0.13.0-alpha.0 → 0.13.1-alpha.0

package/dist/driver/Driver.d.ts

@@ -1,16 +1,22 @@
 import { type Dialect as KyselyDialect } from 'kysely';
 import type { Engine } from '../fields/Engine.js';
 /**
- * What opens an engine from a url: the packages the APP installs, and the Kysely dialect built
- * over them. SQLite is not here — its driver is this package's own.
+ * The packages each engine opens with. The APP installs them, never this package, so a
+ * project that opens no SQL installs no driver — and nothing native.
  *
  * Documented: [sources](https://fougere.dev/docs/infra/sources).
  */
-export interface Driver {
-    packages: string[];
-    dialect(url: string, modules: any[]): KyselyDialect;
-}
+export declare const PACKAGES: Record<Engine, string[]>;
+/** The Kysely dialect an engine builds from a url, over its packages. SQLite opens a path. */
+export type Driver = (url: string, modules: any[]) => KyselyDialect;
 export declare const DRIVERS: Record<Exclude<Engine, 'sqlite'>, Driver>;
+/**
+ * The packages of `engine`, resolved from the app — loaded at the moment it opens, not before.
+ * What is not installed and what is installed but will not load are two refusals, and each
+ * names what to do.
+ */
+export declare function modulesOf(engine: Engine, from?: string): any[];
+export declare function messageOf(error: unknown): string;
 /** The dialect `url` names, over the driver the app installed beside it. */
 export declare function dialectFor(engine: Exclude<Engine, 'sqlite'>, url: string, from?: string): KyselyDialect;
 /** `mssql://user:password@host:1433/database` — tedious takes an object and reads no url. */

package/dist/driver/Driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Driver.d.ts","sourceRoot":"","sources":["../../src/driver/Driver.ts"],"names":[],"mappings":"AAEA,OAAO,EAA+C,KAAK,OAAO,IAAI,aAAa,EAAE,MAAM,QAAQ,CAAC;AACpG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,aAAa,CAAC;CACrD;AAED,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAgB7D,CAAC;AAEF,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,SAAgB,GAAG,aAAa,CAe9G;AAED,6FAA6F;AAC7F,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM;;;;;YAM1B,QAAQ;YAAuC,QAAQ;;;;;;;;EAIrE"}
+{"version":3,"file":"Driver.d.ts","sourceRoot":"","sources":["../../src/driver/Driver.ts"],"names":[],"mappings":"AAEA,OAAO,EAA+C,KAAK,OAAO,IAAI,aAAa,EAAE,MAAM,QAAQ,CAAC;AACpG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAK7C,CAAC;AAEF,8FAA8F;AAC9F,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,aAAa,CAAC;AAEpE,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAO7D,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,SAAgB,GAAG,GAAG,EAAE,CAqBrE;AAgBD,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,SAAgB,GAAG,aAAa,CAE9G;AAED,6FAA6F;AAC7F,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM;;;;;YAM1B,QAAQ;YAAuC,QAAQ;;;;;;;;EAIrE"}

package/dist/driver/Driver.js

@@ -1,37 +1,66 @@
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { MssqlDialect, MysqlDialect, PostgresDialect } from 'kysely';
+/**
+ * The packages each engine opens with. The APP installs them, never this package, so a
+ * project that opens no SQL installs no driver — and nothing native.
+ *
+ * Documented: [sources](https://fougere.dev/docs/infra/sources).
+ */
+export const PACKAGES = {
+    sqlite: ['better-sqlite3'],
+    pg: ['pg'],
+    mysql: ['mysql2'],
+    mssql: ['tedious', 'tarn'],
+};
 export const DRIVERS = {
-    pg: {
-        packages: ['pg'],
-        dialect: (url, [pg]) => new PostgresDialect({ pool: new pg.Pool({ connectionString: url }) }),
-    },
-    mysql: {
-        packages: ['mysql2'],
-        dialect: (url, [mysql]) => new MysqlDialect({ pool: mysql.createPool(url) }),
-    },
-    mssql: {
-        packages: ['tedious', 'tarn'],
-        dialect: (url, [tedious, tarn]) => new MssqlDialect({
-            tarn: { ...tarn, options: { min: 0, max: 10 } },
-            tedious: { ...tedious, connectionFactory: () => new tedious.Connection(tediousConfig(url)) },
-        }),
-    },
+    pg: (url, [pg]) => new PostgresDialect({ pool: new pg.Pool({ connectionString: url }) }),
+    mysql: (url, [mysql]) => new MysqlDialect({ pool: mysql.createPool(url) }),
+    mssql: (url, [tedious, tarn]) => new MssqlDialect({
+        tarn: { ...tarn, options: { min: 0, max: 10 } },
+        tedious: { ...tedious, connectionFactory: () => new tedious.Connection(tediousConfig(url)) },
+    }),
 };
-/** The dialect `url` names, over the driver the app installed beside it. */
-export function dialectFor(engine, url, from = process.cwd()) {
-    const driver = DRIVERS[engine];
+/**
+ * The packages of `engine`, resolved from the app — loaded at the moment it opens, not before.
+ * What is not installed and what is installed but will not load are two refusals, and each
+ * names what to do.
+ */
+export function modulesOf(engine, from = process.cwd()) {
     const require = createRequire(join(from, 'package.json'));
-    const modules = driver.packages.map((name) => {
+    const packages = PACKAGES[engine];
+    const missing = packages.filter((name) => !resolves(require, name));
+    if (missing.length) {
+        throw new Error(`The ${engine} engine opens through ${quoted(packages)}, and ${quoted(missing)} is not installed beside the app (${from}).\n`
+            + `Install it there: pnpm add ${missing.join(' ')}`);
+    }
+    return packages.map((name) => {
         try {
             return require(name);
         }
-        catch {
-            throw new Error(`dialect '${engine}' needs its driver, and '${name}' does not resolve from ${from} — `
-                + `install it beside the app: pnpm add ${driver.packages.join(' ')}`);
+        catch (error) {
+            throw new Error(`The ${engine} engine opens through '${name}', which is installed beside the app (${from}) but does not load: ${messageOf(error)}`, { cause: error });
         }
     });
-    return driver.dialect(url, modules);
+}
+function resolves(require, name) {
+    try {
+        require.resolve(name);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function quoted(names) {
+    return names.map((name) => `'${name}'`).join(' and ');
+}
+export function messageOf(error) {
+    return error instanceof Error ? error.message.split('\n')[0] : String(error);
+}
+/** The dialect `url` names, over the driver the app installed beside it. */
+export function dialectFor(engine, url, from = process.cwd()) {
+    return DRIVERS[engine](url, modulesOf(engine, from));
 }
 /** `mssql://user:password@host:1433/database` — tedious takes an object and reads no url. */
 export function tediousConfig(url) {

package/dist/driver/Driver.js.map

@@ -1 +1 @@
-{"version":3,"file":"Driver.js","sourceRoot":"","sources":["../../src/driver/Driver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Driver.js","sourceRoot":"","sources":["../../src/driver/Driver.ts"],"names":[],"mappings":"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"}

package/dist/sqlite/SqliteSource.d.ts

@@ -1,9 +1,9 @@
-import Database from 'better-sqlite3';
+import type BetterSqlite from 'better-sqlite3';
 import { type SqlSource } from '../source/SqlSource.js';
 import type { SqliteSourceOptions } from './SqliteSourceOptions.js';
 export interface SqliteSource extends SqlSource {
     /** The raw handle, for pragmas and synchronous exec. */
-    sqlite: Database.Database;
+    sqlite: BetterSqlite.Database;
 }
 export declare function createSqliteSource(opts?: SqliteSourceOptions): SqliteSource;
 //# sourceMappingURL=SqliteSource.d.ts.map

package/dist/sqlite/SqliteSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SqliteSource.d.ts","sourceRoot":"","sources":["../../src/sqlite/SqliteSource.ts"],"names":[],"mappings":"AAGA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAItC,OAAO,EAA4C,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAMlG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,wDAAwD;IACxD,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC;CAC3B;AAED,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,mBAAwB,GAAG,YAAY,CA6B/E"}
+{"version":3,"file":"SqliteSource.d.ts","sourceRoot":"","sources":["../../src/sqlite/SqliteSource.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,YAAY,MAAM,gBAAgB,CAAC;AAI/C,OAAO,EAA4C,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAMlG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,wDAAwD;IACxD,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC;CAC/B;AAED,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,mBAAwB,GAAG,YAAY,CA6B/E"}

package/dist/sqlite/SqliteSource.js

@@ -1,12 +1,11 @@
 import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { Kysely, SqliteDialect } from 'kysely';
-import Database from 'better-sqlite3';
 import { createStorageFactory } from '../crud/SqlStorage.js';
 import { logQueries } from '../query/QuerySink.js';
 import { drift, driftReport } from '../drift.js';
 import { createKyselySource, sqlEnforces, sqlSink } from '../source/SqlSource.js';
-import { DRIVERS, dialectFor } from '../driver/Driver.js';
+import { DRIVERS, dialectFor, messageOf, modulesOf } from '../driver/Driver.js';
 import { ENGINES } from '../fields/Engine.js';
 import { desiredTables, migrate } from '../diff/Change.js';
 import { toTableName } from '../table/TableDef.js';
@@ -16,7 +15,7 @@ export function createSqliteSource(opts = {}) {
     // A file-backed DB needs its directory — SQLite won't create it.
     if (path !== ':memory:')
         mkdirSync(dirname(path), { recursive: true });
-    const sqlite = new Database(path);
+    const sqlite = open(path);
     sqlite.pragma('journal_mode = WAL');
     sqlite.pragma('foreign_keys = ON');
     const db = new Kysely({ dialect: new SqliteDialect({ database: sqlite }), log: logQueries(opts.name ?? path) });
@@ -40,6 +39,27 @@ export function createSqliteSource(opts = {}) {
         transacted: (fn) => db.transaction().execute((trx) => fn(createStorageFactory(trx, opts.storageFactoryOptions, 'sqlite'))),
     };
 }
+function open(path) {
+    const [Database] = modulesOf('sqlite');
+    try {
+        return new Database(path);
+    }
+    catch (error) {
+        throw new Error(unopened(error, path), { cause: error });
+    }
+}
+function unopened(error, path) {
+    const code = error.code;
+    const rebuild = 'Build it from its sources: cd node_modules/better-sqlite3 && npx node-gyp rebuild';
+    if (code === 'MODULE_NOT_FOUND' && messageOf(error).includes('better_sqlite3.node')) {
+        return `'better-sqlite3' ships no native binary for ${process.platform}-${process.arch} — its prebuilt ones cover `
+            + `linux, macOS and Windows on x64 and arm64. ${rebuild}`;
+    }
+    if (code === 'ERR_DLOPEN_FAILED') {
+        return `The native binary of 'better-sqlite3' does not load under Node ${process.version}: ${messageOf(error)}. ${rebuild}`;
+    }
+    return `SQLite could not open '${path}': ${messageOf(error)}`;
+}
 /** `source. */
 Sources.register('sql', (conf) => {
     const dialect = conf.dialect;

package/dist/sqlite/SqliteSource.js.map

@@ -1 +1 @@
-{"version":3,"file":"SqliteSource.js","sourceRoot":"","sources":["../../src/sqlite/SqliteSource.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SqliteSource.js","sourceRoot":"","sources":["../../src/sqlite/SqliteSource.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fougere/adapter-sql",
-  "version": "0.13.0-alpha.0",
+  "version": "0.13.1-alpha.0",
   "description": "Entity → SQL tables through Kysely (SQLite, PostgreSQL, MySQL, SQL Server).",
   "keywords": [
     "fougere",
@@ -37,16 +37,16 @@
     "src"
   ],
   "dependencies": {
-    "@fougere/core": "0.13.0-alpha.0",
-    "@fougere/schema": "0.13.0-alpha.0",
-    "better-sqlite3": "^13.0.3",
+    "@fougere/core": "0.13.1-alpha.0",
+    "@fougere/schema": "0.13.1-alpha.0",
     "dequal": "^2.0.3"
   },
   "peerDependencies": {
     "kysely": ">=0.28.17"
   },
   "devDependencies": {
-    "@fougere/core": "0.13.0-alpha.0",
+    "@fougere/core": "0.13.1-alpha.0",
+    "better-sqlite3": "^13.0.3",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.0.0",
     "kysely": "^0.28.17"

package/src/driver/Driver.ts

@@ -4,50 +4,79 @@ import { MssqlDialect, MysqlDialect, PostgresDialect, type Dialect as KyselyDial
 import type { Engine } from '../fields/Engine.js';
 
 /**
- * What opens an engine from a url: the packages the APP installs, and the Kysely dialect built
- * over them. SQLite is not here — its driver is this package's own.
+ * The packages each engine opens with. The APP installs them, never this package, so a
+ * project that opens no SQL installs no driver — and nothing native.
  *
  * Documented: [sources](https://fougere.dev/docs/infra/sources).
  */
-export interface Driver {
-  packages: string[];
-  dialect(url: string, modules: any[]): KyselyDialect;
-}
+export const PACKAGES: Record<Engine, string[]> = {
+  sqlite: ['better-sqlite3'],
+  pg: ['pg'],
+  mysql: ['mysql2'],
+  mssql: ['tedious', 'tarn'],
+};
+
+/** The Kysely dialect an engine builds from a url, over its packages. SQLite opens a path. */
+export type Driver = (url: string, modules: any[]) => KyselyDialect;
 
 export const DRIVERS: Record<Exclude<Engine, 'sqlite'>, Driver> = {
-  pg: {
-    packages: ['pg'],
-    dialect: (url, [pg]) => new PostgresDialect({ pool: new pg.Pool({ connectionString: url }) }),
-  },
-  mysql: {
-    packages: ['mysql2'],
-    dialect: (url, [mysql]) => new MysqlDialect({ pool: mysql.createPool(url) }),
-  },
-  mssql: {
-    packages: ['tedious', 'tarn'],
-    dialect: (url, [tedious, tarn]) => new MssqlDialect({
-      tarn: { ...tarn, options: { min: 0, max: 10 } },
-      tedious: { ...tedious, connectionFactory: () => new tedious.Connection(tediousConfig(url)) },
-    }),
-  },
+  pg: (url, [pg]) => new PostgresDialect({ pool: new pg.Pool({ connectionString: url }) }),
+  mysql: (url, [mysql]) => new MysqlDialect({ pool: mysql.createPool(url) }),
+  mssql: (url, [tedious, tarn]) => new MssqlDialect({
+    tarn: { ...tarn, options: { min: 0, max: 10 } },
+    tedious: { ...tedious, connectionFactory: () => new tedious.Connection(tediousConfig(url)) },
+  }),
 };
 
-/** The dialect `url` names, over the driver the app installed beside it. */
-export function dialectFor(engine: Exclude<Engine, 'sqlite'>, url: string, from = process.cwd()): KyselyDialect {
-  const driver = DRIVERS[engine];
+/**
+ * The packages of `engine`, resolved from the app — loaded at the moment it opens, not before.
+ * What is not installed and what is installed but will not load are two refusals, and each
+ * names what to do.
+ */
+export function modulesOf(engine: Engine, from = process.cwd()): any[] {
   const require = createRequire(join(from, 'package.json'));
-  const modules = driver.packages.map((name) => {
+  const packages = PACKAGES[engine];
+  const missing = packages.filter((name) => !resolves(require, name));
+  if (missing.length) {
+    throw new Error(
+      `The ${engine} engine opens through ${quoted(packages)}, and ${quoted(missing)} is not installed beside the app (${from}).\n`
+      + `Install it there: pnpm add ${missing.join(' ')}`,
+    );
+  }
+
+  return packages.map((name) => {
     try {
       return require(name);
-    } catch {
+    } catch (error) {
       throw new Error(
-        `dialect '${engine}' needs its driver, and '${name}' does not resolve from ${from} — `
-        + `install it beside the app: pnpm add ${driver.packages.join(' ')}`,
+        `The ${engine} engine opens through '${name}', which is installed beside the app (${from}) but does not load: ${messageOf(error)}`,
+        { cause: error },
       );
     }
   });
+}
 
-  return driver.dialect(url, modules);
+function resolves(require: NodeJS.Require, name: string): boolean {
+  try {
+    require.resolve(name);
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function quoted(names: string[]): string {
+  return names.map((name) => `'${name}'`).join(' and ');
+}
+
+export function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message.split('\n')[0] : String(error);
+}
+
+/** The dialect `url` names, over the driver the app installed beside it. */
+export function dialectFor(engine: Exclude<Engine, 'sqlite'>, url: string, from = process.cwd()): KyselyDialect {
+  return DRIVERS[engine](url, modulesOf(engine, from));
 }
 
 /** `mssql://user:password@host:1433/database` — tedious takes an object and reads no url. */

package/src/sqlite/SqliteSource.ts

@@ -1,12 +1,12 @@
 import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { Kysely, SqliteDialect } from 'kysely';
-import Database from 'better-sqlite3';
+import type BetterSqlite from 'better-sqlite3';
 import { createStorageFactory } from '../crud/SqlStorage.js';
 import { logQueries } from '../query/QuerySink.js';
 import { drift, driftReport } from '../drift.js';
 import { createKyselySource, sqlEnforces, sqlSink, type SqlSource } from '../source/SqlSource.js';
-import { DRIVERS, dialectFor } from '../driver/Driver.js';
+import { DRIVERS, dialectFor, messageOf, modulesOf } from '../driver/Driver.js';
 import { ENGINES } from '../fields/Engine.js';
 import { desiredTables, migrate } from '../diff/Change.js';
 import { toTableName } from '../table/TableDef.js';
@@ -15,14 +15,14 @@ import type { SqliteSourceOptions } from './SqliteSourceOptions.js';
 
 export interface SqliteSource extends SqlSource {
   /** The raw handle, for pragmas and synchronous exec. */
-  sqlite: Database.Database;
+  sqlite: BetterSqlite.Database;
 }
 
 export function createSqliteSource(opts: SqliteSourceOptions = {}): SqliteSource {
   const path = opts.path ?? 'fougere.db';
   // A file-backed DB needs its directory — SQLite won't create it.
   if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
-  const sqlite = new Database(path);
+  const sqlite = open(path);
   sqlite.pragma('journal_mode = WAL');
   sqlite.pragma('foreign_keys = ON');
   const db = new Kysely<any>({ dialect: new SqliteDialect({ database: sqlite }), log: logQueries(opts.name ?? path) });
@@ -49,6 +49,29 @@ export function createSqliteSource(opts: SqliteSourceOptions = {}): SqliteSource
   };
 }
 
+function open(path: string): BetterSqlite.Database {
+  const [Database] = modulesOf('sqlite') as [typeof BetterSqlite];
+  try {
+    return new Database(path);
+  } catch (error) {
+    throw new Error(unopened(error, path), { cause: error });
+  }
+}
+
+function unopened(error: unknown, path: string): string {
+  const code = (error as { code?: string }).code;
+  const rebuild = 'Build it from its sources: cd node_modules/better-sqlite3 && npx node-gyp rebuild';
+  if (code === 'MODULE_NOT_FOUND' && messageOf(error).includes('better_sqlite3.node')) {
+    return `'better-sqlite3' ships no native binary for ${process.platform}-${process.arch} — its prebuilt ones cover `
+      + `linux, macOS and Windows on x64 and arm64. ${rebuild}`;
+  }
+  if (code === 'ERR_DLOPEN_FAILED') {
+    return `The native binary of 'better-sqlite3' does not load under Node ${process.version}: ${messageOf(error)}. ${rebuild}`;
+  }
+
+  return `SQLite could not open '${path}': ${messageOf(error)}`;
+}
+
 /** `source. */
 Sources.register('sql', (conf: SourceConfig): Source => {
   const dialect = conf.dialect as string | undefined;