dbgate-sqlite-dumper 0.1.0

package/README.md

@@ -0,0 +1,230 @@
+# dbgate-sqlite-dumper
+
+Standalone, client-agnostic SQLite dump and restore library for Node.js.
+
+Produces the same plain-SQL dump the `sqlite3` shell's `.dump` command writes, and
+restores it back — entirely through a database handle. **No `sqlite3` shell, no
+external process is ever invoked.** Framework-independent: it does not depend on
+DbGate internals and works outside DbGate.
+
+- Node.js >= 20, ESM and CJS builds, full TypeScript types
+- `better-sqlite3` is an **optional** peer dependency, reachable only through the
+  separate `dbgate-sqlite-dumper/better-sqlite3` entry point — the core never
+  imports a driver
+- Streaming both ways: a multi-gigabyte database dumps, and a multi-gigabyte `.sql`
+  file restores, in constant memory
+
+## Two-way native compatibility
+
+Both directions are **proven by automated tests against the real `sqlite3` shell**,
+not assumed:
+
+- **Dumps produced by this library restore with the native shell.**
+  ```sh
+  sqlite3 copy.db < dump.sql
+  ```
+- **Dumps produced by the native `.dump` restore with this library.**
+  ```ts
+  await restoreSqlDump({ connection, source: createReadStream('native-dump.sql') });
+  ```
+
+There is no custom format, no archive wrapper, and no metadata sidecar. A `.sql` file
+this package writes is **byte-identical** to `sqlite3 database.db .dump` — and to its
+`--data-only`, `--preserve-rowids`, `--newlines` and `--nosys` variants — with one
+exception that is a property of SQLite itself: the digits past the 17th in a `REAL`
+literal come from SQLite's own `printf("%!.20g")`, which changed between releases, so a
+driver bundling a different SQLite than the shell may spell the same double differently
+(`0.100000000000000005` vs `0.1000000000000000056`). Both parse to the identical value;
+the tests compare such lines as doubles and every other byte exactly. See
+[docs/native-compatibility.md](docs/native-compatibility.md).
+
+Every path in the matrix ends by reading back the restored database and deep-comparing
+its schema _and_ every table's rows — text compared as bytes — against the source.
+
+| Path                                       | Tested |
+| ------------------------------------------ | ------ |
+| this library → native `sqlite3` restore    | ✅     |
+| native `.dump` → this library's restore    | ✅     |
+| this library → this library                | ✅     |
+| native `.dump` → native restore (baseline) | ✅     |
+
+## Install
+
+```sh
+npm install dbgate-sqlite-dumper
+# optional, for the bundled better-sqlite3 adapter:
+npm install better-sqlite3
+```
+
+## Quick start
+
+### Dump
+
+```ts
+import { createWriteStream } from 'node:fs';
+import { dumpSqlite } from 'dbgate-sqlite-dumper';
+import { connectBetterSqlite3 } from 'dbgate-sqlite-dumper/better-sqlite3';
+
+const { connection, close } = await connectBetterSqlite3('shop.db', { readonly: true });
+
+try {
+  const result = await dumpSqlite(
+    connection,
+    { mode: 'full' },
+    createWriteStream('shop.sql'),
+    event => console.log(event.phase, event.objectName ?? '', event.bytesWritten ?? ''),
+  );
+
+  console.log(`${result.rowsExported} rows in ${result.statementsWritten} statements`);
+  for (const warning of result.warnings) {
+    console.warn(`[${warning.severity}] ${warning.code}: ${warning.message}`);
+  }
+} finally {
+  await close();
+}
+```
+
+The result is restorable by `sqlite3 shop_copy.db < shop.sql`.
+
+### Restore
+
+```ts
+import { createReadStream } from 'node:fs';
+import { restoreSqlDump } from 'dbgate-sqlite-dumper';
+import { connectBetterSqlite3 } from 'dbgate-sqlite-dumper/better-sqlite3';
+
+const { connection, close } = await connectBetterSqlite3('shop_copy.db');
+
+const result = await restoreSqlDump({
+  connection,
+  source: createReadStream('shop.sql'),
+  progress: event => console.log(event.phase, event.currentObject, event.rowsRestored),
+});
+
+console.log(`${result.statementsExecuted} statements, ${result.rowsRestored} rows`);
+for (const error of result.errors) {
+  console.error(
+    `statement ${error.statementIndex} (line ${error.location.startLine}): ${error.message}`,
+  );
+  console.error(`  ${error.sqlPreview}`); // truncated, key-redacted
+  console.error(`  code=${error.sqliteError?.code}`);
+}
+await close();
+```
+
+`source` accepts a `string`, a `Buffer`, a `Readable`, or any `AsyncIterable` of text or
+`Buffer` chunks. Input is parsed incrementally, so restoring a multi-gigabyte dump does not
+read it into memory.
+
+### Using a database you already have open
+
+```ts
+import Database from 'better-sqlite3';
+import { fromBetterSqlite3 } from 'dbgate-sqlite-dumper/better-sqlite3';
+
+const connection = fromBetterSqlite3(new Database('shop.db'));
+```
+
+A database you supply is **borrowed and never closed**. See
+[docs/better-sqlite3-adapter.md](docs/better-sqlite3-adapter.md); any other driver works by
+implementing the small `SqliteConnection` interface.
+
+## Public API
+
+| Function                                                               | Purpose                                                            |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `dumpSqlite(connection, options, output, onProgress?, signal?)`        | Full pipeline: snapshot → introspect → plan → render → stream rows |
+| `restoreSqlDump({ connection, source, options?, progress?, signal? })` | Streaming parser → statements → database                           |
+| `introspectSqlite(connection, options?, signal?)`                      | Normalized `SqliteDatabase` + version/capabilities/diagnostics     |
+| `inspectDumpArchive(database, options?)`                               | Pure planning → ordered, verified `ArchiveEntry[]`                 |
+| `renderPlainSql(request)`                                              | Pure model → plain SQL text (never touches the database)           |
+| `exportTableDataAsInserts(request)`                                    | Stream one table's rows as `INSERT` statements                     |
+| `preflightRestore(request)`                                            | Target version, modules, conflicts, and what the dump needs        |
+| `isSqliteDump(sample)`                                                 | Recognizes native _and_ this package's dumps                       |
+| `parseSqlStatements(sql)` / `streamSqlStatements(source)`              | The shell-compatible statement splitter, usable on its own         |
+| `isCompleteStatement(sql)`                                             | A port of `sqlite3_complete()`                                     |
+| `beginSqliteDumpSession(connection, options?)`                         | The read snapshot, on its own                                      |
+| `checkTargetCompatibility(database, target)`                           | Which features a target cannot accept                              |
+| `fromBetterSqlite3(database)`                                          | Adapter (from `dbgate-sqlite-dumper/better-sqlite3`)               |
+| `connectBetterSqlite3(filename, options?)`                             | Convenience opener (from `dbgate-sqlite-dumper/better-sqlite3`)    |
+
+Each stage is independently usable: `inspectDumpArchive` and `renderPlainSql` are pure
+functions of the model and need no connection at all.
+
+## Why a real parser, not `split(';')`
+
+Splitting a SQLite script on semicolons breaks on the _first_ trigger in any dump:
+
+```sql
+CREATE TRIGGER audit_books AFTER INSERT ON books BEGIN
+  INSERT INTO audit VALUES ('book ' || new.title || '; END');
+  UPDATE authors SET books = books + 1 WHERE id = new.author_id;
+END;
+```
+
+This package splits a script exactly where the `sqlite3` shell does, by porting the two
+pieces of SQLite that decide it: `sqlite3_complete()` — the state machine that keeps a
+trigger body's inner statements together — and the shell's own line rules:
+
+- **`GO` and `/` lines end a statement**, as in the shell (SQL Server and Oracle habits).
+- **Dot-commands are the shell's, not SQL.** Presentational ones (`.mode`, `.headers`,
+  `.print`) are skipped with a warning; ones that change the database (`.read`,
+  `.import`, `.open`) are refused with a precise error rather than silently ignored.
+- **A `\r` before a newline is dropped**, even inside a string literal — the shell's line
+  reader does that, so a CRLF file restores identically.
+- **Bytes that are not valid UTF-8 survive.** The native `.dump` writes such text raw; a
+  JavaScript driver cannot pass it through a string, so the literal is rewritten to the
+  exact-byte `CAST(X'...' AS TEXT)`.
+
+Boundary correctness is not assumed: the parser's output is asserted identical at **every**
+chunk size and **every** single split point, and a suite of hand-written scripts is run
+through both the shell and this package, which must leave identical databases.
+
+## Documentation
+
+| Document                                                         | Contents                                                         |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------- |
+| [docs/native-compatibility.md](docs/native-compatibility.md)     | The two-way promise, what is reproduced and why, native quirks   |
+| [docs/dump-api.md](docs/dump-api.md)                             | `dumpSqlite` options, modes, consistency, progress, batching     |
+| [docs/restore-api.md](docs/restore-api.md)                       | `restoreSqlDump`, the parser, session cleanup, errors, preflight |
+| [docs/better-sqlite3-adapter.md](docs/better-sqlite3-adapter.md) | Ownership, defensive mode, the `SqliteConnection` contract       |
+| [docs/supported-objects.md](docs/supported-objects.md)           | Object matrix: dumped / restored / round-trip tested             |
+| [docs/supported-data-types.md](docs/supported-data-types.md)     | Per-storage-class fidelity and how each value is written         |
+| [docs/known-limitations.md](docs/known-limitations.md)           | What this package does not do, and why                           |
+| [docs/round-trip-testing.md](docs/round-trip-testing.md)         | Running the interop suite; the fixture                           |
+| [docs/architecture.md](docs/architecture.md)                     | Layer-by-layer design and the reasoning behind it                |
+
+## Fidelity highlights
+
+- **64-bit integers are exact.** Every value is rendered to text by SQLite itself, so
+  `9223372036854775807` never passes through a JavaScript number.
+- **`REAL` digits are SQLite's own**, from the same `printf` the shell uses.
+- **Virtual tables come back byte-identical**, FTS5 indexes and R-trees included: like the
+  native `.dump`, the schema row is written directly and the shadow tables' contents are
+  copied, instead of rebuilding the index.
+- **Text is bytes.** Invalid UTF-8 and embedded `NUL`s survive a round trip; the native
+  shell silently truncates text at the first `NUL`, this package does not.
+- **Connections are left as they were found.** A native dump turns `foreign_keys` off and
+  never turns it back on; a restore that stops early leaves a transaction open. Both are
+  put back before the handle is returned.
+- **Consistent under concurrent writes.** A dump reads every table inside one snapshot.
+
+## Development
+
+```sh
+npm install
+npm run typecheck
+npm run lint
+npm test                   # unit tests; better-sqlite3 in-process, nothing else needed
+
+npm run test:integration   # needs the sqlite3 shell on PATH (apt install sqlite3)
+npm run test:package       # builds, then smoke-tests dist/ as ESM and CJS
+```
+
+Integration tests skip themselves with a clear message when the `sqlite3` shell is not
+installed; set `SQLITE_TEST_REQUIRED=1` (as CI does) to make that a hard error.
+`SQLITE3_BIN` selects a specific shell binary.
+
+## License
+
+GPL-3.0-only. See [LICENSE](LICENSE).

package/dist/better-sqlite3.cjs

@@ -0,0 +1,178 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/better-sqlite3.ts
+var better_sqlite3_exports = {};
+__export(better_sqlite3_exports, {
+  connectBetterSqlite3: () => connectBetterSqlite3,
+  fromBetterSqlite3: () => fromBetterSqlite3
+});
+module.exports = __toCommonJS(better_sqlite3_exports);
+
+// src/utils/errors.ts
+var SqliteDumperError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "SqliteDumperError";
+    this.code = code;
+  }
+};
+var OperationCancelledError = class extends SqliteDumperError {
+  constructor(message = "The operation was cancelled") {
+    super("operation-cancelled", message);
+    this.name = "OperationCancelledError";
+  }
+};
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw new OperationCancelledError();
+  }
+}
+
+// src/better-sqlite3.ts
+function toDriverParameters(parameters) {
+  return (parameters ?? []).map(
+    (value) => value instanceof Uint8Array && !Buffer.isBuffer(value) ? Buffer.from(value.buffer, value.byteOffset, value.byteLength) : value
+  );
+}
+function prepare(database, sql) {
+  const statement = database.prepare(sql);
+  statement.safeIntegers(true);
+  return statement;
+}
+function isMultipleStatementsError(error) {
+  return error instanceof RangeError && /more than one statement/i.test(error.message);
+}
+function fromBetterSqlite3(database) {
+  const connection = {
+    async query(query, signal) {
+      throwIfAborted(signal);
+      const statement = prepare(database, query.sql);
+      const parameters = toDriverParameters(query.parameters);
+      if (statement.reader) {
+        const rows = statement.all(...parameters);
+        return { rows, columns: statement.columns().map((column) => column.name) };
+      }
+      statement.run(...parameters);
+      return { rows: [] };
+    },
+    stream(query, options) {
+      const signal = options?.signal;
+      return {
+        async *[Symbol.asyncIterator]() {
+          throwIfAborted(signal);
+          const statement = prepare(database, query.sql);
+          if (!statement.reader) {
+            statement.run(...toDriverParameters(query.parameters));
+            return;
+          }
+          const iterator = statement.iterate(
+            ...toDriverParameters(query.parameters)
+          );
+          try {
+            for (const row of iterator) {
+              if (signal?.aborted) {
+                throw new OperationCancelledError();
+              }
+              yield row;
+            }
+          } finally {
+            iterator.return?.();
+          }
+        }
+      };
+    },
+    async execute(sql, signal) {
+      throwIfAborted(signal);
+      let statement;
+      try {
+        statement = prepare(database, sql);
+      } catch (error) {
+        if (!isMultipleStatementsError(error)) {
+          throw error;
+        }
+        const before = totalChanges(database);
+        database.exec(sql);
+        return { changes: totalChanges(database) - before };
+      }
+      if (statement.reader) {
+        for (const _row of statement.iterate()) {
+        }
+        return { changes: 0 };
+      }
+      const info = statement.run();
+      return { changes: Number(info.changes) };
+    },
+    describeError(error) {
+      if (!(error instanceof Error)) {
+        return void 0;
+      }
+      const code = error.code;
+      return {
+        ...typeof code === "string" ? { code } : {},
+        message: error.message
+      };
+    },
+    isInTransaction() {
+      return database.inTransaction;
+    },
+    async setDefensive(enabled) {
+      database.unsafeMode(!enabled);
+    },
+    async cancel() {
+    }
+  };
+  return connection;
+}
+function totalChanges(database) {
+  return Number(database.prepare("SELECT total_changes()").pluck().get());
+}
+async function connectBetterSqlite3(filename, options) {
+  const module2 = await import("better-sqlite3");
+  const DatabaseConstructor = module2.default ?? module2;
+  const database = new DatabaseConstructor(filename, options);
+  let closed = false;
+  return {
+    connection: fromBetterSqlite3(database),
+    database,
+    close: async () => {
+      if (!closed) {
+        closed = true;
+        database.close();
+      }
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  connectBetterSqlite3,
+  fromBetterSqlite3
+});
+//# sourceMappingURL=better-sqlite3.cjs.map

package/dist/better-sqlite3.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/better-sqlite3.ts","../src/utils/errors.ts"],"sourcesContent":["/**\r\n * Optional adapter for the `better-sqlite3` package.\r\n *\r\n * Wraps a caller-owned `better-sqlite3` `Database` as a\r\n * {@link SqliteConnection}. This module is never imported by the core\r\n * package; `better-sqlite3` is an optional peer dependency and is only\r\n * resolved when a consumer imports `dbgate-sqlite-dumper/better-sqlite3`\r\n * themselves.\r\n *\r\n * `better-sqlite3` is the driver DbGate's own SQLite plugin uses, which is\r\n * why it is the bundled adapter. Any other driver works through the same\r\n * {@link SqliteConnection} interface.\r\n */\r\nimport type BetterSqlite3 from 'better-sqlite3';\r\nimport type {\r\n  SqliteConnection,\r\n  SqliteErrorInfo,\r\n  SqliteExecResult,\r\n  SqliteParameterValue,\r\n  SqliteQuery,\r\n  SqliteQueryResult,\r\n  SqliteRow,\r\n  SqliteStreamOptions,\r\n} from './connection/types.js';\r\nimport { OperationCancelledError, throwIfAborted } from './utils/errors.js';\r\n\r\ntype Database = BetterSqlite3.Database;\r\ntype Statement = BetterSqlite3.Statement<unknown[], unknown>;\r\n\r\nfunction toDriverParameters(parameters: readonly SqliteParameterValue[] | undefined): unknown[] {\r\n  return (parameters ?? []).map(value =>\r\n    value instanceof Uint8Array && !Buffer.isBuffer(value)\r\n      ? Buffer.from(value.buffer, value.byteOffset, value.byteLength)\r\n      : value,\r\n  );\r\n}\r\n\r\n/**\r\n * Prepares a statement with 64-bit integers returned as `bigint`, so no\r\n * catalog value is ever rounded. (Row data does not depend on this: the core\r\n * reads it through SQL that renders numbers as text — see `valueQuery.ts`.)\r\n */\r\nfunction prepare(database: Database, sql: string): Statement {\r\n  const statement = database.prepare(sql) as Statement;\r\n  statement.safeIntegers(true);\r\n  return statement;\r\n}\r\n\r\nfunction isMultipleStatementsError(error: unknown): boolean {\r\n  return error instanceof RangeError && /more than one statement/i.test(error.message);\r\n}\r\n\r\n/**\r\n * Wraps an open `better-sqlite3` database. The database is **borrowed**:\r\n * this package never closes it.\r\n *\r\n * `better-sqlite3` is synchronous, which shapes three behaviours:\r\n *\r\n * - `stream()` steps the statement one row at a time with `iterate()`,\r\n *   yielding between rows, so a table of any size streams in constant\r\n *   memory. While a stream is open the database cannot run another\r\n *   statement — this package never asks it to.\r\n * - `cancel()` cannot interrupt a statement mid-step. Cancellation takes\r\n *   effect between rows and between statements, which for a dump or a\r\n *   restore (each statement is short) is prompt.\r\n * - `setDefensive()` is implemented with `unsafeMode()`, which is how\r\n *   `better-sqlite3` exposes `SQLITE_DBCONFIG_DEFENSIVE`. (Unsafe mode also\r\n *   relaxes the driver's own guard against writing while iterating; this\r\n *   package never does that.)\r\n */\r\nexport function fromBetterSqlite3(database: Database): SqliteConnection {\r\n  const connection: SqliteConnection = {\r\n    async query<Row extends SqliteRow = SqliteRow>(\r\n      query: SqliteQuery,\r\n      signal?: AbortSignal,\r\n    ): Promise<SqliteQueryResult<Row>> {\r\n      throwIfAborted(signal);\r\n      const statement = prepare(database, query.sql);\r\n      const parameters = toDriverParameters(query.parameters);\r\n      if (statement.reader) {\r\n        const rows = statement.all(...parameters) as Row[];\r\n        return { rows, columns: statement.columns().map(column => column.name) };\r\n      }\r\n      statement.run(...parameters);\r\n      return { rows: [] };\r\n    },\r\n\r\n    stream<Row extends SqliteRow = SqliteRow>(\r\n      query: SqliteQuery,\r\n      options?: SqliteStreamOptions,\r\n    ): AsyncIterable<Row> {\r\n      const signal = options?.signal;\r\n      return {\r\n        async *[Symbol.asyncIterator](): AsyncGenerator<Row> {\r\n          throwIfAborted(signal);\r\n          const statement = prepare(database, query.sql);\r\n          if (!statement.reader) {\r\n            statement.run(...toDriverParameters(query.parameters));\r\n            return;\r\n          }\r\n          const iterator = statement.iterate(\r\n            ...toDriverParameters(query.parameters),\r\n          ) as IterableIterator<Row>;\r\n          try {\r\n            for (const row of iterator) {\r\n              if (signal?.aborted) {\r\n                throw new OperationCancelledError();\r\n              }\r\n              yield row;\r\n            }\r\n          } finally {\r\n            // Finalizes the statement even when the consumer stops early,\r\n            // which is what frees the database for the next statement.\r\n            iterator.return?.();\r\n          }\r\n        },\r\n      };\r\n    },\r\n\r\n    async execute(sql: string, signal?: AbortSignal): Promise<SqliteExecResult> {\r\n      throwIfAborted(signal);\r\n      let statement: Statement;\r\n      try {\r\n        statement = prepare(database, sql);\r\n      } catch (error) {\r\n        if (!isMultipleStatementsError(error)) {\r\n          throw error;\r\n        }\r\n        // Text the shell would run as several statements at once. Rare in a\r\n        // restore (the parser splits statements), but valid input.\r\n        const before = totalChanges(database);\r\n        database.exec(sql);\r\n        return { changes: totalChanges(database) - before };\r\n      }\r\n      if (statement.reader) {\r\n        // A script's own SELECT or PRAGMA query: step it to completion, as\r\n        // the shell would, without keeping the rows.\r\n        for (const _row of statement.iterate()) {\r\n          // discard\r\n        }\r\n        return { changes: 0 };\r\n      }\r\n      const info = statement.run();\r\n      return { changes: Number(info.changes) };\r\n    },\r\n\r\n    describeError(error: unknown): SqliteErrorInfo | undefined {\r\n      if (!(error instanceof Error)) {\r\n        return undefined;\r\n      }\r\n      const code = (error as { code?: unknown }).code;\r\n      return {\r\n        ...(typeof code === 'string' ? { code } : {}),\r\n        message: error.message,\r\n      };\r\n    },\r\n\r\n    isInTransaction(): boolean {\r\n      return database.inTransaction;\r\n    },\r\n\r\n    async setDefensive(enabled: boolean): Promise<void> {\r\n      database.unsafeMode(!enabled);\r\n    },\r\n\r\n    async cancel(): Promise<void> {\r\n      // better-sqlite3 runs each statement synchronously to completion;\r\n      // there is nothing in flight to interrupt.\r\n    },\r\n  };\r\n  return connection;\r\n}\r\n\r\nfunction totalChanges(database: Database): number {\r\n  return Number(database.prepare('SELECT total_changes()').pluck().get());\r\n}\r\n\r\nexport interface ConnectedBetterSqlite3 {\r\n  readonly connection: SqliteConnection;\r\n  /** The underlying `better-sqlite3` database, for anything the adapter does not cover. */\r\n  readonly database: Database;\r\n  /** Closes the database. Idempotent. */\r\n  close(): Promise<void>;\r\n}\r\n\r\n/**\r\n * Opens a database file with `better-sqlite3` and wraps it. Unlike\r\n * {@link fromBetterSqlite3}, the returned `close()` owns the handle.\r\n *\r\n * `better-sqlite3` is loaded lazily, so importing this module does not\r\n * require the optional peer dependency to be installed until this function\r\n * is actually called.\r\n */\r\nexport async function connectBetterSqlite3(\r\n  filename: string,\r\n  options?: BetterSqlite3.Options,\r\n): Promise<ConnectedBetterSqlite3> {\r\n  const module = await import('better-sqlite3');\r\n  const DatabaseConstructor = (module.default ?? module) as unknown as new (\r\n    filename: string,\r\n    options?: BetterSqlite3.Options,\r\n  ) => Database;\r\n  const database = new DatabaseConstructor(filename, options);\r\n  let closed = false;\r\n  return {\r\n    connection: fromBetterSqlite3(database),\r\n    database,\r\n    close: async () => {\r\n      if (!closed) {\r\n        closed = true;\r\n        database.close();\r\n      }\r\n    },\r\n  };\r\n}\r\n","/** Base class for every error this package throws intentionally. */\r\nexport class SqliteDumperError extends Error {\r\n  readonly code: string;\r\n\r\n  constructor(code: string, message: string, options?: { cause?: unknown }) {\r\n    super(message, options);\r\n    this.name = 'SqliteDumperError';\r\n    this.code = code;\r\n  }\r\n}\r\n\r\n/** Thrown when an operation stops because its `AbortSignal` was triggered. */\r\nexport class OperationCancelledError extends SqliteDumperError {\r\n  constructor(message = 'The operation was cancelled') {\r\n    super('operation-cancelled', message);\r\n    this.name = 'OperationCancelledError';\r\n  }\r\n}\r\n\r\nexport function throwIfAborted(signal: AbortSignal | undefined): void {\r\n  if (signal?.aborted) {\r\n    throw new OperationCancelledError();\r\n  }\r\n}\r\n\r\n/**\r\n * True for both cancellation shapes this package can observe: its own\r\n * {@link OperationCancelledError} and the `DOMException` an `AbortSignal`\r\n * (or a Node stream aborted through one) raises.\r\n */\r\nexport function isAbortError(error: unknown): boolean {\r\n  return (\r\n    (error instanceof DOMException && error.name === 'AbortError') ||\r\n    (error instanceof Error && error.name === 'OperationCancelledError')\r\n  );\r\n}\r\n"],"mappings":"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","names":["module"]}

package/dist/better-sqlite3.d.cts

@@ -0,0 +1,55 @@
+import BetterSqlite3 from 'better-sqlite3';
+import { S as SqliteConnection } from './types-CTyJTzB6.cjs';
+
+/**
+ * Optional adapter for the `better-sqlite3` package.
+ *
+ * Wraps a caller-owned `better-sqlite3` `Database` as a
+ * {@link SqliteConnection}. This module is never imported by the core
+ * package; `better-sqlite3` is an optional peer dependency and is only
+ * resolved when a consumer imports `dbgate-sqlite-dumper/better-sqlite3`
+ * themselves.
+ *
+ * `better-sqlite3` is the driver DbGate's own SQLite plugin uses, which is
+ * why it is the bundled adapter. Any other driver works through the same
+ * {@link SqliteConnection} interface.
+ */
+
+type Database = BetterSqlite3.Database;
+/**
+ * Wraps an open `better-sqlite3` database. The database is **borrowed**:
+ * this package never closes it.
+ *
+ * `better-sqlite3` is synchronous, which shapes three behaviours:
+ *
+ * - `stream()` steps the statement one row at a time with `iterate()`,
+ *   yielding between rows, so a table of any size streams in constant
+ *   memory. While a stream is open the database cannot run another
+ *   statement — this package never asks it to.
+ * - `cancel()` cannot interrupt a statement mid-step. Cancellation takes
+ *   effect between rows and between statements, which for a dump or a
+ *   restore (each statement is short) is prompt.
+ * - `setDefensive()` is implemented with `unsafeMode()`, which is how
+ *   `better-sqlite3` exposes `SQLITE_DBCONFIG_DEFENSIVE`. (Unsafe mode also
+ *   relaxes the driver's own guard against writing while iterating; this
+ *   package never does that.)
+ */
+declare function fromBetterSqlite3(database: Database): SqliteConnection;
+interface ConnectedBetterSqlite3 {
+    readonly connection: SqliteConnection;
+    /** The underlying `better-sqlite3` database, for anything the adapter does not cover. */
+    readonly database: Database;
+    /** Closes the database. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Opens a database file with `better-sqlite3` and wraps it. Unlike
+ * {@link fromBetterSqlite3}, the returned `close()` owns the handle.
+ *
+ * `better-sqlite3` is loaded lazily, so importing this module does not
+ * require the optional peer dependency to be installed until this function
+ * is actually called.
+ */
+declare function connectBetterSqlite3(filename: string, options?: BetterSqlite3.Options): Promise<ConnectedBetterSqlite3>;
+
+export { type ConnectedBetterSqlite3, connectBetterSqlite3, fromBetterSqlite3 };

package/dist/better-sqlite3.d.ts

@@ -0,0 +1,55 @@
+import BetterSqlite3 from 'better-sqlite3';
+import { S as SqliteConnection } from './types-CTyJTzB6.js';
+
+/**
+ * Optional adapter for the `better-sqlite3` package.
+ *
+ * Wraps a caller-owned `better-sqlite3` `Database` as a
+ * {@link SqliteConnection}. This module is never imported by the core
+ * package; `better-sqlite3` is an optional peer dependency and is only
+ * resolved when a consumer imports `dbgate-sqlite-dumper/better-sqlite3`
+ * themselves.
+ *
+ * `better-sqlite3` is the driver DbGate's own SQLite plugin uses, which is
+ * why it is the bundled adapter. Any other driver works through the same
+ * {@link SqliteConnection} interface.
+ */
+
+type Database = BetterSqlite3.Database;
+/**
+ * Wraps an open `better-sqlite3` database. The database is **borrowed**:
+ * this package never closes it.
+ *
+ * `better-sqlite3` is synchronous, which shapes three behaviours:
+ *
+ * - `stream()` steps the statement one row at a time with `iterate()`,
+ *   yielding between rows, so a table of any size streams in constant
+ *   memory. While a stream is open the database cannot run another
+ *   statement — this package never asks it to.
+ * - `cancel()` cannot interrupt a statement mid-step. Cancellation takes
+ *   effect between rows and between statements, which for a dump or a
+ *   restore (each statement is short) is prompt.
+ * - `setDefensive()` is implemented with `unsafeMode()`, which is how
+ *   `better-sqlite3` exposes `SQLITE_DBCONFIG_DEFENSIVE`. (Unsafe mode also
+ *   relaxes the driver's own guard against writing while iterating; this
+ *   package never does that.)
+ */
+declare function fromBetterSqlite3(database: Database): SqliteConnection;
+interface ConnectedBetterSqlite3 {
+    readonly connection: SqliteConnection;
+    /** The underlying `better-sqlite3` database, for anything the adapter does not cover. */
+    readonly database: Database;
+    /** Closes the database. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Opens a database file with `better-sqlite3` and wraps it. Unlike
+ * {@link fromBetterSqlite3}, the returned `close()` owns the handle.
+ *
+ * `better-sqlite3` is loaded lazily, so importing this module does not
+ * require the optional peer dependency to be installed until this function
+ * is actually called.
+ */
+declare function connectBetterSqlite3(filename: string, options?: BetterSqlite3.Options): Promise<ConnectedBetterSqlite3>;
+
+export { type ConnectedBetterSqlite3, connectBetterSqlite3, fromBetterSqlite3 };