@romedb/node 0.2.12 → 0.2.14

package/embedded-client.cjs

@@ -7,7 +7,7 @@ const path = require('node:path');
 const { pathToFileURL } = require('node:url');
 const common = require('./client.cjs');
 const { connect, RemoteDatabase, ClientError, Float64, Record, Vector, encodeValue, decodeValue, normalizeUrl, validatePrepared, saveRequest, loadRequest } = common;
-const { plainObject } = require('./values.cjs');
+const { plainObject, checkCopyOptions } = require('./values.cjs');
 const { createEmbeddedClient } = require('./client-internal.cjs');
 const native = require('./native.cjs');
 const sessions = new Map();
@@ -21,12 +21,12 @@ async function openEmbedded(options) {
   opening.then(database => { if (abandoned) void database.close().catch(() => {}); }, () => {});
   let timer;
   const deadline = new Promise((resolve, reject) => {
-    timer = setTimeout(() => { abandoned = true; reject(new common.ClientError('FDB_CANCELLED', 'Embedded connection deadline expired; startup cleanup will finish when native work returns', 'not-sent')); }, duration);
+    timer = setTimeout(() => { abandoned = true; reject(new common.ClientError('RDB_CANCELLED', 'Embedded connection deadline expired; startup cleanup will finish when native work returns', 'not-sent')); }, duration);
   });
   try { return await Promise.race([opening, deadline]); }
   catch (error) {
     if (error instanceof common.ClientError || error instanceof TypeError || error instanceof RangeError) throw error;
-    const code = error.code === 'EEXIST' ? 'FDB_ALREADY_EXISTS' : ['EACCES', 'EPERM'].includes(error.code) ? 'FDB_FORBIDDEN' : error.code === 'ENOENT' ? 'FDB_NOT_FOUND' : 'FDB_STORAGE';
+    const code = error.code === 'EEXIST' ? 'RDB_ALREADY_EXISTS' : ['EACCES', 'EPERM'].includes(error.code) ? 'RDB_FORBIDDEN' : error.code === 'ENOENT' ? 'RDB_NOT_FOUND' : 'RDB_STORAGE';
     throw new common.ClientError(code, 'Embedded filesystem operation failed', 'not-sent');
   } finally { clearTimeout(timer); }
 }
@@ -41,7 +41,7 @@ async function openEmbeddedFile(options) {
     if (sessions.size >= maxOpen) throw openLimit();
     const parsed = path.parse(file);
     for (const sidecar of [file + '-wal', file + '-shm', file + '-log', file + '-journal', path.join(parsed.dir, parsed.name + '.db-log')]) {
-      try { await fs.lstat(sidecar); throw new common.ClientError('FDB_CONFLICT', 'Database sidecar exists; recover it before creating a file', 'not-sent'); }
+      try { await fs.lstat(sidecar); throw new common.ClientError('RDB_CONFLICT', 'Database sidecar exists; recover it before creating a file', 'not-sent'); }
       catch (error) { if (error.code !== 'ENOENT') throw error; }
     }
     const handle = await fs.open(file, 'wx', 0o600);
@@ -52,10 +52,10 @@ async function openEmbeddedFile(options) {
   let metadata;
   try { metadata = await fs.lstat(file); }
   catch (error) {
-    if (error.code === 'ENOENT') throw new common.ClientError('FDB_NOT_FOUND', 'Open an existing database or explicitly create one', 'not-sent');
+    if (error.code === 'ENOENT') throw new common.ClientError('RDB_NOT_FOUND', 'Open an existing database or explicitly create one', 'not-sent');
     throw error;
   }
-  if (!metadata.isFile() || metadata.nlink !== 1) throw new common.ClientError('FDB_VALIDATION', 'Use a regular database file with one link', 'not-sent');
+  if (!metadata.isFile() || metadata.nlink !== 1) throw new common.ClientError('RDB_VALIDATION', 'Use a regular database file with one link', 'not-sent');
   const canonical = await fs.realpath(file);
   let session = sessions.get(canonical);
   if (session?.closing) { await session.closed; return openEmbeddedFile({ ...options, create: false }); }
@@ -72,8 +72,40 @@ async function openEmbeddedFile(options) {
   } catch (error) { await releaseSession(session, canonical); throw error; }
 }
 
+function checkExportOptions(options) {
+  if (!plainObject(options) || Object.keys(options).some(key => !['signal', 'timeoutMs', 'emptyTables', 'newIdentity'].includes(key))) throw new TypeError('export options take signal, timeoutMs, emptyTables and newIdentity');
+  checkCopyOptions(options);
+  if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError('signal must be an AbortSignal');
+  if (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1 || options.timeoutMs > 4294967295)) throw new RangeError('timeoutMs must be 1..4294967295');
+}
+
+// The file has no name any more; the handle keeps it until the stream ends or is cancelled.
+function fileStream(handle, size, signal) {
+  let offset = 0;
+  const fail = async (controller, error) => {
+    await handle.close().catch(() => {});
+    controller.error(error);
+  };
+  return new ReadableStream({
+    async pull(controller) {
+      if (signal?.aborted) return fail(controller, new common.ClientError('RDB_CANCELLED', 'Embedded export download cancelled', 'read-failed'));
+      try {
+        if (offset === size) { await handle.close(); controller.close(); return; }
+        const chunk = new Uint8Array(Math.min(262144, size - offset));
+        const { bytesRead } = await handle.read(chunk, 0, chunk.byteLength, offset);
+        if (bytesRead === 0) throw new Error('exported file ended early');
+        offset += bytesRead;
+        controller.enqueue(bytesRead === chunk.byteLength ? chunk : chunk.slice(0, bytesRead));
+      } catch (error) {
+        await fail(controller, new common.ClientError('RDB_STORAGE', 'Exported database file could not be read', 'read-failed', { cause: error }));
+      }
+    },
+    cancel() { return handle.close().catch(() => {}); },
+  }, { highWaterMark: 0 });
+}
+
 function openLimit() {
-  return new common.ClientError('FDB_LIMIT', `Embedded database limit reached: ${sessions.size} files are open; close one or raise maxOpen`, 'not-sent');
+  return new common.ClientError('RDB_LIMIT', `Embedded database limit reached: ${sessions.size} files are open; close one or raise maxOpen`, 'not-sent');
 }
 
 class EmbeddedDatabase {
@@ -93,6 +125,32 @@ class EmbeddedDatabase {
   submit(request, options) { return this.#client.submit(request, options); }
   recover(request, options) { return this.#client.recover(request, options); }
   writeAtomic(statements, options) { return this.#client.writeAtomic(statements, options); }
+  exportFile(destination, options) {
+    if (this.#closing) return Promise.reject(new common.ClientError('RDB_CLOSED', 'Database client is closed', 'not-sent'));
+    return typeof destination === 'string' ? this.#exportTo(destination, options ?? {}) : this.#exportStream(destination ?? {});
+  }
+  async #exportTo(destination, options) {
+    checkExportOptions(options);
+    if (!destination || destination.length > 4096 || destination.includes('\0')) throw new TypeError('exportFile requires a bounded destination path');
+    const { sequence, bytes } = await this.#session.request('export', JSON.stringify({ destination: path.resolve(destination), emptyTables: options.emptyTables, newIdentity: options.newIdentity }), options.signal, options.timeoutMs);
+    return { sequence, bytes };
+  }
+  async #exportStream(options) {
+    checkExportOptions(options);
+    let folder;
+    try {
+      folder = await fs.mkdtemp(path.join(path.dirname(this.#path), '.romedb-download-'));
+      const file = path.join(folder, 'export.romedb');
+      const { sequence, bytes } = await this.#exportTo(file, options);
+      const handle = await fs.open(file, 'r');
+      await fs.rm(folder, { recursive: true });
+      return { sequence, size: bytes, body: fileStream(handle, bytes, options.signal) };
+    } catch (error) {
+      if (folder !== undefined) await fs.rm(folder, { recursive: true, force: true }).catch(() => {});
+      if (error instanceof common.ClientError || error instanceof TypeError || error instanceof RangeError) throw error;
+      throw new common.ClientError(['EACCES', 'EPERM'].includes(error.code) ? 'RDB_FORBIDDEN' : error.code === 'ENOENT' ? 'RDB_NOT_FOUND' : 'RDB_STORAGE', 'Embedded export file operation failed', 'read-failed', { cause: error });
+    }
+  }
   close() {
     this.#closing ??= (async () => { await this.#client.close(); await releaseSession(this.#session, this.#path); })();
     return this.#closing;
@@ -126,11 +184,11 @@ class Session {
       else pending.resolve(message.result);
     });
     this.#worker.on('error', () => {
-      this.#failure ??= new common.ClientError('FDB_TRANSPORT', 'Embedded worker failed; reconcile pending writes', 'unknown');
+      this.#failure ??= new common.ClientError('RDB_TRANSPORT', 'Embedded worker failed; reconcile pending writes', 'unknown');
       rejectReady(this.#failure);
     });
     this.#worker.on('exit', code => {
-      this.#failure ??= new common.ClientError('FDB_CLOSED', code === 0 ? 'Embedded worker closed' : 'Embedded worker exited unexpectedly', 'unknown');
+      this.#failure ??= new common.ClientError('RDB_CLOSED', code === 0 ? 'Embedded worker closed' : 'Embedded worker exited unexpectedly', 'unknown');
       rejectReady(this.#failure);
       for (const pending of this.#pending.values()) {
         pending.listener?.[Symbol.dispose]();
@@ -143,23 +201,24 @@ class Session {
   }
   request(operation, body, signal, duration) {
     if (this.#failure) return Promise.reject(this.#failure);
-    if (this.closing && operation !== 'close') return Promise.reject(new common.ClientError('FDB_CLOSED', 'Embedded session is closing', 'not-sent'));
-    if (signal?.aborted) return Promise.reject(new common.ClientError('FDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent'));
+    if (this.closing && operation !== 'close') return Promise.reject(new common.ClientError('RDB_CLOSED', 'Embedded session is closing', 'not-sent'));
+    if (signal?.aborted) return Promise.reject(new common.ClientError('RDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent'));
     const bytes = body === undefined ? 0 : Buffer.byteLength(body);
-    if (operation !== 'close' && (this.#pending.size >= 32 || this.#bytes + bytes > 2097152)) return Promise.reject(new common.ClientError('FDB_LIMIT', 'Embedded request queue limit reached', 'not-sent'));
+    if (operation !== 'close' && (this.#pending.size >= 32 || this.#bytes + bytes > 2097152)) return Promise.reject(new common.ClientError('RDB_LIMIT', 'Embedded request queue limit reached', 'not-sent'));
     const token = native.createCancellationToken(duration === undefined ? undefined : String(duration));
     return new Promise((resolve, reject) => {
       const id = ++this.#next;
       const listener = signal === undefined ? undefined : addAbortListener(signal, () => {
         native.cancelOperation(token);
-        reject(new common.ClientError('FDB_CANCELLED', operation === 'write' ? 'Write was not confirmed; recover the saved request' : 'Embedded request cancelled', operation === 'write' ? 'unknown' : 'read-failed'));
+        // An export settles when the worker reports it, so a late cancellation cannot hide a finished file.
+        if (operation !== 'export') reject(new common.ClientError('RDB_CANCELLED', operation === 'write' ? 'Write was not confirmed; recover the saved request' : 'Embedded request cancelled', operation === 'write' ? 'unknown' : 'read-failed'));
       });
       this.#pending.set(id, { resolve, reject, token, listener, bytes }); this.#bytes += bytes;
       try { this.#worker.postMessage({ id, operation, body, cancellationKey: token }); }
       catch {
         this.#pending.delete(id); this.#bytes -= bytes;
         listener?.[Symbol.dispose](); native.releaseCancellationToken(token);
-        reject(new common.ClientError('FDB_TRANSPORT', 'Embedded request could not be dispatched', 'not-sent'));
+        reject(new common.ClientError('RDB_TRANSPORT', 'Embedded request could not be dispatched', 'not-sent'));
       }
     });
   }

package/embedded-client.d.ts

@@ -1,5 +1,8 @@
 export * from './client';
-import type { Client, DatabaseInfo, Statement, RequestOptions, ReadOptions, WriteOptions, BatchResult, PreparedWrite } from './client';
+import type { Client, DatabaseInfo, Statement, RequestOptions, ReadOptions, WriteOptions, BatchResult, PreparedWrite, DatabaseFile, FileExportOptions } from './client';
+/** timeoutMs has no default for exports: without it, an export runs until it finishes or signal aborts it. */
+export interface ExportOptions extends FileExportOptions {}
+export interface ExportedFile { sequence: number; bytes: number; }
 export interface EmbeddedOptions { path: string; create?: boolean; timeoutMs?: number; maxOpen?: number; }
 export class EmbeddedDatabase implements Client {
   private constructor();
@@ -14,6 +17,13 @@ export class EmbeddedDatabase implements Client {
   submit(request: PreparedWrite, options?: RequestOptions): Promise<BatchResult>;
   recover(request: PreparedWrite, options?: RequestOptions): Promise<BatchResult>;
   writeAtomic(statements: Statement[], options?: WriteOptions): Promise<BatchResult>;
+  /**
+   * Copy the database into a new private file while reads and writes continue. The destination
+   * and its log files must not exist. Writes up to and including `sequence` are in the file.
+   */
+  exportFile(destination: string, options?: ExportOptions): Promise<ExportedFile>;
+  /** Copy the database and stream it; nothing is left on disk once the body ends or is cancelled. */
+  exportFile(options?: ExportOptions): Promise<DatabaseFile>;
   close(): Promise<void>;
 }
 export function openEmbedded(options: EmbeddedOptions): Promise<EmbeddedDatabase>;

package/embedded-worker.cjs

@@ -1,20 +1,21 @@
 'use strict';
 const { parentPort, workerData } = require('node:worker_threads');
 const { createHash } = require('node:crypto');
-const { NativeDatabase } = require('./native.cjs');
+const { NativeDatabase, cancelOperation } = require('./native.cjs');
 const { validatePrepared } = require('./client.cjs');
 let database;
 let sequence = 0;
 let fenced = false;
 const receipts = new Map();
+const copies = new Map();
 try {
   database = new NativeDatabase(workerData.path, '10000', '67108864', workerData.create ? 'create-mvcc' : 'mvcc');
   const foreignKeys = JSON.parse(database.execute('PRAGMA foreign_keys=ON', '{}'));
   if (foreignKeys.execution.error) throw new Error(foreignKeys.execution.error.message);
   parentPort.postMessage({ ready: true });
 } catch (error) {
-  const coded = /^(FDB_[A-Z0-9_]+): (.*)$/s.exec(error.message);
-  parentPort.postMessage({ readyError: { code: /file is locked/i.test(error.message) ? 'FDB_BUSY' : coded?.[1] ?? (error.code?.startsWith('FDB_') ? error.code : 'FDB_STORAGE'), message: coded?.[2] ?? error.message } });
+  const coded = /^(RDB_[A-Z0-9_]+): (.*)$/s.exec(error.message);
+  parentPort.postMessage({ readyError: { code: /file is locked/i.test(error.message) ? 'RDB_BUSY' : coded?.[1] ?? (error.code?.startsWith('RDB_') ? error.code : 'RDB_STORAGE'), message: coded?.[2] ?? error.message } });
   database?.close();
   parentPort.close();
 }
@@ -22,18 +23,36 @@ try {
 if (database) parentPort.on('message', ({ id, operation, body, cancellationKey }) => {
   try {
     if (operation === 'close') {
-      if (!fenced) try { database.execute('PRAGMA wal_checkpoint(TRUNCATE)', '{}'); } catch {}
-      database.close();
-      parentPort.postMessage({ id });
-      parentPort.close();
+      for (const key of copies.keys()) cancelOperation(key);
+      void Promise.allSettled(copies.values()).then(() => {
+        if (!fenced) try { database.execute('PRAGMA wal_checkpoint(TRUNCATE)', '{}'); } catch {}
+        database.close();
+        parentPort.postMessage({ id });
+        parentPort.close();
+      });
+      return;
+    }
+    if (fenced) fail('RDB_STORAGE', 'Embedded outcome is uncertain; close and reconcile the database', 'unknown');
+    if (operation === 'export') {
+      // Writes run on this thread, so none commits between the start of the copy's snapshot and reading the sequence.
+      const copy = JSON.parse(body);
+      const pending = database.startFileExport(copy.destination, cancellationKey, copy.emptyTables, copy.newIdentity);
+      const snapshot = sequence;
+      const finished = pending.finish().then(
+        bytes => parentPort.postMessage({ id, result: { sequence: snapshot, bytes: Number(bytes) } }),
+        error => {
+          const coded = /^(RDB_[A-Z0-9_]+): (.*)$/s.exec(error.message);
+          parentPort.postMessage({ id, error: { code: coded?.[1] ?? 'RDB_STORAGE', message: (coded?.[2] ?? error.message).slice(0, 2048), outcome: 'read-failed' } });
+        },
+      ).finally(() => copies.delete(cancellationKey));
+      copies.set(cancellationKey, finished);
       return;
     }
-    if (fenced) fail('FDB_STORAGE', 'Embedded outcome is uncertain; close and reconcile the database', 'unknown');
     if (operation === 'info') {
       const mode = JSON.parse(database.execute('PRAGMA journal_mode', '{}'));
-      if (mode.execution.error) fail('FDB_STORAGE', 'Cannot inspect embedded journal mode', 'read-failed');
+      if (mode.execution.error) fail('RDB_STORAGE', 'Cannot inspect embedded journal mode', 'read-failed');
       const engine = JSON.parse(database.execute('SELECT romedb_version()', '{}'));
-      if (engine.execution.error) fail('FDB_STORAGE', 'Cannot read the embedded engine version', 'read-failed');
+      if (engine.execution.error) fail('RDB_STORAGE', 'Cannot read the embedded engine version', 'read-failed');
       parentPort.postMessage({ id, result: {
         id: workerData.databaseId, sequence, adapterVersion: 1,
         engineVersion: engine.execution.result.rows[0][0].value,
@@ -43,12 +62,12 @@ if (database) parentPort.on('message', ({ id, operation, body, cancellationKey }
       } });
       return;
     }
-    if (!['read', 'write'].includes(operation)) fail('FDB_UNSUPPORTED', 'Unknown embedded operation', 'not-sent');
+    if (!['read', 'write'].includes(operation)) fail('RDB_UNSUPPORTED', 'Unknown embedded operation', 'not-sent');
     const reading = operation === 'read';
     const request = JSON.parse(body);
     let writeBody = body;
     if (reading) {
-      if (request.readVersion !== 2 || request.ifSequence !== undefined) fail('FDB_VALIDATION', 'Invalid fresh read envelope', 'read-failed');
+      if (request.readVersion !== 2 || request.ifSequence !== undefined) fail('RDB_VALIDATION', 'Invalid fresh read envelope', 'read-failed');
       const { readVersion, ...rest } = request;
       writeBody = JSON.stringify(rest);
     }
@@ -56,22 +75,22 @@ if (database) parentPort.on('message', ({ id, operation, body, cancellationKey }
     const hash = createHash('sha256').update(body).digest('hex');
     if (!reading && receipts.has(request.requestId)) {
       const receipt = receipts.get(request.requestId);
-      if (receipt.hash !== hash) fail('FDB_REQUEST_IDENTITY', 'Request ID was reused with another body', 'unknown');
+      if (receipt.hash !== hash) fail('RDB_REQUEST_IDENTITY', 'Request ID was reused with another body', 'unknown');
       parentPort.postMessage({ id, result: receipt.result });
       return;
     }
-    if (request.afterSequence > sequence || (!reading && sequence - request.afterSequence >= 64)) fail('FDB_CONFLICT', 'Request position is ahead or its replay window expired; reconcile the request', reading ? 'read-failed' : 'unknown');
-    if (sequence >= Number.MAX_SAFE_INTEGER - 1 && !reading) fail('FDB_LIMIT', 'Adapter sequence is exhausted', 'not-sent');
+    if (request.afterSequence > sequence || (!reading && sequence - request.afterSequence >= 64)) fail('RDB_CONFLICT', 'Request position is ahead or its replay window expired; reconcile the request', reading ? 'read-failed' : 'unknown');
+    if (sequence >= Number.MAX_SAFE_INTEGER - 1 && !reading) fail('RDB_LIMIT', 'Adapter sequence is exhausted', 'not-sent');
     let result;
     if (!reading && request.ifSequence !== undefined && request.ifSequence !== sequence) {
-      result = { error: { code: 'FDB_CONFLICT', message: 'Sequence changed; refresh before saving' } };
+      result = { error: { code: 'RDB_CONFLICT', message: 'Sequence changed; refresh before saving' } };
     } else {
       const report = JSON.parse(database.executeAtomicRequest(JSON.stringify({ readOnly: reading, statements: request.statements, ...(request.workLimits === undefined ? {} : { workLimits: request.workLimits }) }), cancellationKey));
       if (report.execution.error) {
         const error = report.execution.error;
-        if (['FDB_STORAGE', 'FDB_ROLLBACK'].includes(error.code) || report.transaction.after !== 'autocommit') {
+        if (['RDB_STORAGE', 'RDB_ROLLBACK'].includes(error.code) || report.transaction.after !== 'autocommit') {
           fenced = true;
-          fail('FDB_STORAGE', 'Atomic request outcome is uncertain; close and reconcile the database', 'unknown');
+          fail('RDB_STORAGE', 'Atomic request outcome is uncertain; close and reconcile the database', 'unknown');
         }
         if (reading) fail(error.code, error.message, 'read-failed');
         result = { error };
@@ -85,7 +104,8 @@ if (database) parentPort.on('message', ({ id, operation, body, cancellationKey }
     }
     parentPort.postMessage({ id, result });
   } catch (error) {
-    parentPort.postMessage({ id, error: { code: error.code ?? 'FDB_VALIDATION', message: String(error.message).slice(0, 2048), outcome: error.outcome ?? (operation === 'read' ? 'read-failed' : 'unknown') } });
+    const coded = operation === 'export' ? /^(RDB_[A-Z0-9_]+): (.*)$/s.exec(error.message) : null;
+    parentPort.postMessage({ id, error: { code: coded?.[1] ?? error.code ?? 'RDB_VALIDATION', message: String(coded?.[2] ?? error.message).slice(0, 2048), outcome: error.outcome ?? (operation === 'read' || operation === 'export' ? 'read-failed' : 'unknown') } });
   }
 });
 

package/index.cjs

@@ -1,4 +1,5 @@
 'use strict';
+const { checkCopyOptions } = require('./values.cjs');
 const { NativeDatabase, interruptConnection, createCancellationToken, cancelOperation, releaseCancellationToken, vectorFromComponents, vectorFromSparseEntries } = require('./native.cjs');
 class Record {
   constructor(table, key) {
@@ -6,6 +7,8 @@ class Record {
     this.table = table; this.key = key;
     Object.freeze(this);
   }
+  toString() { return `${this.table}:${this.key}`; }
+  equals(other) { return other instanceof Record && other.table === this.table && other.key === this.key; }
 }
 class Vector {
   static float32(values) { return constructVector('float32', values); }
@@ -186,7 +189,7 @@ function decodeProfile(raw) {
     metrics: Object.fromEntries(Object.entries(metrics).map(([key, value]) => [key, BigInt(value)])) };
 }
 function isRomeDBError(value) {
-  if (!(value instanceof Error) || typeof value.code !== 'string' || !/^FDB_[A-Z][A-Z0-9_]*$/.test(value.code)) return false;
+  if (!(value instanceof Error) || typeof value.code !== 'string' || !/^RDB_[A-Z][A-Z0-9_]*$/.test(value.code)) return false;
   const transaction = value.transaction;
   if (!(transaction === undefined || (transaction !== null && typeof transaction === 'object' &&
     (transaction.before === 'autocommit' || transaction.before === 'active') &&
@@ -196,19 +199,19 @@ function isRomeDBError(value) {
     typeof migration.version === 'bigint' && migration.version > 0n &&
     typeof migration.offset === 'bigint' && migration.offset >= 0n &&
     migration.cause !== null && typeof migration.cause === 'object' &&
-    typeof migration.cause.code === 'string' && /^FDB_[A-Z][A-Z0-9_]*$/.test(migration.cause.code) &&
+    typeof migration.cause.code === 'string' && /^RDB_[A-Z][A-Z0-9_]*$/.test(migration.cause.code) &&
     typeof migration.cause.message === 'string');
 }
 exports.isRomeDBError = isRomeDBError;
 function cardinalityError(count, transaction) {
   const error = new RangeError(`expected exactly one row, got ${count}`);
-  error.code = 'FDB_CARDINALITY';
+  error.code = 'RDB_CARDINALITY';
   error.transaction = transaction;
   return error;
 }
 function closedError(message = 'database is closed') {
   const error = new Error(message);
-  error.code = 'FDB_CLOSED';
+  error.code = 'RDB_CLOSED';
   return error;
 }
 class Database {
@@ -313,7 +316,7 @@ class AsyncDatabase {
   #fail(error, shutdown = false) {
     if (!this.#failure) {
       this.#failure = new Error(`database worker failure: ${error.message}`, { cause: error });
-      this.#failure.code = 'FDB_WORKER';
+      this.#failure.code = 'RDB_WORKER';
     }
     this.#readyReject(this.#failure);
     for (const pending of this.#pending.values()) { pending.cleanup(); pending.reject(this.#failure); }
@@ -331,7 +334,7 @@ class AsyncDatabase {
     if (this.#closing && !closing) return Promise.reject(closedError('database is closing or closed'));
     const bytes = args.reduce((size, arg) => size + Buffer.byteLength(arg), 0);
     if (!closing && (this.#pending.size >= 256 || this.#bytes + bytes > 128 * 1024 * 1024)) {
-      const error = new RangeError('database worker queue limit exceeded'); error.code = 'FDB_LIMIT';
+      const error = new RangeError('database worker queue limit exceeded'); error.code = 'RDB_LIMIT';
       return Promise.reject(error);
     }
     const id = ++this.#next;
@@ -412,6 +415,19 @@ class AsyncDatabase {
     return { alreadyApplied: report.execution.result.alreadyApplied,
       applied: report.execution.result.applied.map(BigInt), transaction: report.transaction };
   }
+  async exportFile(destination, options = {}) {
+    if (typeof destination !== 'string' || !destination || destination.length > 4096 || destination.includes('\0')) throw new TypeError('exportFile requires a bounded destination path');
+    checkCopyOptions(options);
+    const copy = JSON.stringify({ emptyTables: options.emptyTables, newIdentity: options.newIdentity });
+    try { return await this.#request('exportFile', [require('node:path').resolve(destination), copy], false, options.signal, options.timeoutMs); }
+    catch (error) {
+      const coded = /^(RDB_[A-Z0-9_]+): (.*)$/s.exec(error.message);
+      if (!coded) throw error;
+      const failure = new Error(coded[2]);
+      failure.code = coded[1];
+      throw failure;
+    }
+  }
   async all(sql, parameters, options) { return (await this.execute(sql, parameters, options)).rows; }
   async first(sql, parameters, options) { return (await this.all(sql, parameters, options))[0]; }
   async exactlyOne(sql, parameters, options) {
@@ -442,7 +458,7 @@ function collectionClient(db, name, asynchronous) {
     const check = info => {
       if (info.rows[0]?.[0]?.model !== 'document') throw new TypeError('collection methods require a document collection');
     };
-    const missing = error => { if (error.code !== 'FDB_NOT_FOUND') throw error; };
+    const missing = error => { if (error.code !== 'RDB_NOT_FOUND') throw error; };
     if (asynchronous) return (async () => {
       try { check(await db.execute(`INFO FOR TABLE ${table}`, {}, options)); } catch (error) { missing(error); }
       return project(await db.execute(sql, params, options));

package/index.d.ts

@@ -66,6 +66,13 @@ export class Database {
 }
 
 export interface ExecuteOptions { signal?: AbortSignal; timeoutMs?: number; }
+export interface FileExport { bytes: number; }
+export interface FileExportOptions extends ExecuteOptions {
+  /** These tables keep their schema and indexes but no rows, and the copy gets a new identity. */
+  emptyTables?: readonly string[];
+  /** Leave out the database ID, the sequence and the receipts: the copy is a new database. */
+  newIdentity?: boolean;
+}
 export class AsyncDatabase {
   collection<T extends object = Document>(name: string): AsyncCollection<T>;
   private constructor();
@@ -75,6 +82,8 @@ export class AsyncDatabase {
   migrate(migrations: Migration[], options?: ExecuteOptions): Promise<MigrationReport>;
   exportDocuments(table: string, format?: TransferFormat, options?: ExecuteOptions): Promise<string>;
   importDocuments(table: string, input: string, format?: TransferFormat, options?: ExecuteOptions): Promise<ImportReport>;
+  /** Copy an MVCC database into a new private file while queries continue; the destination and its log files must not exist. */
+  exportFile(destination: string, options?: FileExportOptions): Promise<FileExport>;
   execute(sql: string, parameters?: Parameters, options?: ExecuteOptions): Promise<QueryResult>;
   profileSelect(sql: string, parameters?: Parameters, options?: ExecuteOptions): Promise<ProfiledQuery>;
   /** Checks write results atomically; does not bound engine or logical materialization memory. */

package/native.cjs

@@ -3,7 +3,7 @@ const minimumNodeMajor = 22;
 const nodeMajor = Number.parseInt(process.versions.node.split('.')[0], 10);
 if (nodeMajor < minimumNodeMajor) {
   const error = new Error(`RomeDB requires Node.js ${minimumNodeMajor} or newer; this process is running Node ${process.versions.node}.`);
-  error.code = 'FDB_RUNTIME_VERSION';
+  error.code = 'RDB_RUNTIME_VERSION';
   throw error;
 }
 try {
@@ -15,6 +15,6 @@ try {
     'See the package README for supported build and installation instructions.',
     { cause },
   );
-  error.code = 'FDB_NATIVE_LOAD';
+  error.code = 'RDB_NATIVE_LOAD';
   throw error;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@romedb/node",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "RomeDB for Node.js: the embedded database (Linux x64 native addon) and a Web-API client for romedb serve and RomeDB Cloud",
   "main": "index.cjs",
   "types": "index.d.ts",
@@ -32,6 +32,15 @@
     "typescript": "5.8.3"
   },
   "license": "MIT",
+  "homepage": "https://github.com/romedb/romedb/tree/main/romedb/bindings/node#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/romedb/romedb.git",
+    "directory": "romedb/bindings/node"
+  },
+  "bugs": {
+    "url": "https://github.com/romedb/romedb/issues"
+  },
   "files": [
     "index.cjs",
     "client.cjs",
@@ -58,14 +67,5 @@
   "scripts": {
     "test": "node build-esm.cjs --check && node --test --test-concurrency=2 test.cjs client.test.cjs client-web.test.mjs client-native.test.cjs embedded-client.test.cjs",
     "typecheck": "tsc --noEmit --strict --target ES2022 --module Node16 types.test.ts client.types.test.ts embedded-client.types.test.ts values.types.test.ts"
-  },
-  "homepage": "https://github.com/romedb/romedb/tree/main/romedb/bindings/node#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/romedb/romedb.git",
-    "directory": "romedb/bindings/node"
-  },
-  "bugs": {
-    "url": "https://github.com/romedb/romedb/issues"
   }
-}
+}

package/romedb.node

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/romedb.node
-size: 41228032 bytes
-sha256: d77c5d1e9f732191c5670a75fa184e6b7fccd37fdcca863ddc76a5efcbd5ed2d
+size: 41464424 bytes
+sha256: d98971746cedc29b00b8333f763433c47db42f65306b933966e636e0221aac3c

package/values.cjs

@@ -18,6 +18,8 @@ class Record {
     this.key = key;
     Object.freeze(this);
   }
+  toString() { return `${this.table}:${this.key}`; }
+  equals(other) { return other instanceof Record && other.table === this.table && other.key === this.key; }
 }
 
 class Vector {
@@ -204,8 +206,16 @@ function checkDepth(depth) {
   if (depth > 64) throw new RangeError('value nesting exceeds 64');
 }
 
+function checkCopyOptions(options) {
+  const { emptyTables, newIdentity } = options;
+  if (emptyTables !== undefined && (!Array.isArray(emptyTables) || emptyTables.length > 256 || emptyTables.some(name => typeof name !== 'string' || !name || name.length > 255 || /[,\0]/.test(name)))) {
+    throw new TypeError('emptyTables takes up to 256 table names without commas');
+  }
+  if (newIdentity !== undefined && typeof newIdentity !== 'boolean') throw new TypeError('newIdentity must be a boolean');
+}
+
 function plainObject(value) {
   return value !== null && typeof value === 'object' && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
 }
 
-module.exports = { Float64, Record, Vector, encodeValue, decodeValue, plainObject, text };
+module.exports = { Float64, Record, Vector, encodeValue, decodeValue, plainObject, text, checkCopyOptions };

package/values.d.ts

@@ -1,5 +1,5 @@
 export class Float64 { constructor(value: number); readonly value: number; }
-export class Record { constructor(table: string, key: string | bigint); readonly table: string; readonly key: string | bigint; }
+export class Record { constructor(table: string, key: string | bigint); readonly table: string; readonly key: string | bigint; /** `table:key`. */ toString(): string; /** The same table and key, including the key's type. */ equals(other: unknown): boolean; }
 export class Vector {
   constructor(bytes: Uint8Array);
   /** A copy of the encoded bytes. */

package/values.mjs

@@ -22,6 +22,8 @@ class Record {
     this.key = key;
     Object.freeze(this);
   }
+  toString() { return `${this.table}:${this.key}`; }
+  equals(other) { return other instanceof Record && other.table === this.table && other.key === this.key; }
 }
 
 class Vector {
@@ -208,13 +210,21 @@ function checkDepth(depth) {
   if (depth > 64) throw new RangeError('value nesting exceeds 64');
 }
 
+function checkCopyOptions(options) {
+  const { emptyTables, newIdentity } = options;
+  if (emptyTables !== undefined && (!Array.isArray(emptyTables) || emptyTables.length > 256 || emptyTables.some(name => typeof name !== 'string' || !name || name.length > 255 || /[,\0]/.test(name)))) {
+    throw new TypeError('emptyTables takes up to 256 table names without commas');
+  }
+  if (newIdentity !== undefined && typeof newIdentity !== 'boolean') throw new TypeError('newIdentity must be a boolean');
+}
+
 function plainObject(value) {
   return value !== null && typeof value === 'object' && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
 }
 
-module.exports = { Float64, Record, Vector, encodeValue, decodeValue, plainObject, text };
+module.exports = { Float64, Record, Vector, encodeValue, decodeValue, plainObject, text, checkCopyOptions };
 })(commonjs, commonjs.exports, specifier => {
   throw new TypeError(`Cannot load ${specifier}`);
 });
 
-export const { Float64, Record, Vector, encodeValue, decodeValue, plainObject, text } = commonjs.exports;
+export const { Float64, Record, Vector, encodeValue, decodeValue, plainObject, text, checkCopyOptions } = commonjs.exports;

package/worker.cjs

@@ -1,17 +1,35 @@
 'use strict';
 const { parentPort, workerData } = require('node:worker_threads');
-const { NativeDatabase } = require('./native.cjs');
+const { NativeDatabase, createCancellationToken, cancelOperation, releaseCancellationToken } = require('./native.cjs');
 const db = new NativeDatabase(workerData.path, ...(workerData.limits ?? []));
-const methods = new Set(['execute', 'executeAtomicRequest', 'writeWithResultLimits', 'profileSelect', 'profileSelectWithLimits', 'checkCollectionIntegrity', 'executeBatch', 'migrate', 'exportDocuments', 'importDocuments', 'close']);
+const methods = new Set(['execute', 'executeAtomicRequest', 'writeWithResultLimits', 'profileSelect', 'profileSelectWithLimits', 'checkCollectionIntegrity', 'executeBatch', 'migrate', 'exportDocuments', 'importDocuments', 'exportFile', 'close']);
+const copies = new Map();
 parentPort.on('message', ({ id, method, args, cancellationKey }) => {
   try {
     if (!methods.has(method)) throw new Error('unknown database worker operation');
+    if (method === 'exportFile') {
+      const key = cancellationKey ?? createCancellationToken();
+      const finished = Promise.resolve()
+        .then(() => { const copy = JSON.parse(args[1]); return db.startFileExport(args[0], key, copy.emptyTables, copy.newIdentity).finish(); })
+        .then(bytes => parentPort.postMessage({ id, result: { bytes: Number(bytes) } }), error => parentPort.postMessage({ id, error: { message: error.message } }))
+        .finally(() => { copies.delete(key); if (cancellationKey === undefined) releaseCancellationToken(key); });
+      copies.set(key, finished);
+      return;
+    }
+    if (method === 'close') {
+      for (const key of copies.keys()) cancelOperation(key);
+      void Promise.allSettled(copies.values()).then(() => {
+        db.close();
+        parentPort.postMessage({ id, result: undefined });
+        parentPort.close();
+      });
+      return;
+    }
     const result = method === 'execute' && cancellationKey !== undefined
       ? db.executeCancellable(...args, cancellationKey)
       : (method === 'executeAtomicRequest' || method === 'writeWithResultLimits' || method === 'profileSelect' || method === 'profileSelectWithLimits' || method === 'checkCollectionIntegrity' || method === 'executeBatch' || method === 'importDocuments' || method === 'exportDocuments' || method === 'migrate') && cancellationKey !== undefined
         ? db[method](...args, cancellationKey) : db[method](...args);
     parentPort.postMessage({ id, result });
-    if (method === 'close') parentPort.close();
   } catch (error) {
     parentPort.postMessage({ id, error: { message: error.message } });
   }