@romedb/node 0.0.0-stage → 0.2.12

package/client.mjs

@@ -0,0 +1,410 @@
+// Generated by build-esm.cjs from client.cjs. Edit client.cjs, then run `node build-esm.cjs`.
+import * as module0 from './values.mjs';
+
+const commonjs = { exports: {} };
+(function (module, exports, require) {
+'use strict';
+// Web APIs only: this file also runs in Workers and browsers through client.mjs.
+const { Float64, Record, Vector, encodeValue, decodeValue, plainObject, text } = require('./values.cjs');
+
+const MAX_REQUEST = 65_536;
+const MAX_CLOUD_REQUEST = 1_048_576;
+const CLOUD_QUERY_VERSION = 3;
+const MAX_RESPONSE = 524_288;
+const MAX_SEQUENCE = Number.MAX_SAFE_INTEGER - 1;
+const construction = Symbol('RemoteDatabase');
+const warmAtConnect = Symbol('warmAtConnect');
+const WARM_STATES = new Set(['ready', 'starting', 'skipped']);
+const encoder = new TextEncoder();
+
+class ClientError extends Error {
+  constructor(code, message, outcome, details = {}) {
+    const { cause, ...fields } = details;
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'ClientError';
+    this.code = code;
+    this.outcome = outcome;
+    Object.assign(this, fields);
+  }
+}
+
+async function connect(options) {
+  const db = new RemoteDatabase(options, construction);
+  db[warmAtConnect]();
+  if (db.deferred) return db;
+  try { await db.info(); return db; }
+  catch (error) { await db.close(); throw error; }
+}
+
+class RemoteDatabase {
+  #url; #token; #fetch; #timeout; #sequence = 0; #id; #capabilities; #transport;
+  #closed = false; #active = new Set(); #inflightBytes = 0; #sequenceKnown = false; #deferred = false; #cloud = false; #warm = false; #loopbackOrganization = false;
+  constructor(options, key, transport) {
+    if (key !== construction) throw new TypeError('use connect()');
+    if (!plainObject(options)) throw new TypeError('connection options require an object');
+    this.#url = transport ? normalizeFileUrl(options.url) : normalizeUrl(options.url);
+    this.#transport = transport;
+    if (typeof options.token !== 'string' || !/^[\x21-\x7e]{1,4096}$/.test(options.token)) throw new TypeError('token requires a bounded bearer credential');
+    this.#token = options.token;
+    const fetch = options.fetch ?? globalThis.fetch;
+    if (typeof fetch !== 'function') throw new TypeError('fetch must be a function');
+    // Workers refuse fetch called on another object, so the default keeps globalThis.
+    this.#fetch = options.fetch ?? fetch.bind(globalThis);
+    this.#timeout = timeout(options.timeoutMs ?? 20_000);
+    if (options.deferInfo !== undefined && typeof options.deferInfo !== 'boolean') throw new TypeError('deferInfo requires a boolean');
+    if (options.warm !== undefined && typeof options.warm !== 'boolean') throw new TypeError('warm requires a boolean');
+    const cloudId = transport ? undefined : /\/databases\/([0-9a-f-]{36})$/.exec(this.#url)?.[1];
+    // A loopback organization URL is a local service directory or Cloud in development;
+    // the details reply tells which, so these connections always read details first.
+    this.#loopbackOrganization = cloudId !== undefined && loopbackHost(new URL(this.#url).hostname);
+    this.#cloud = cloudId !== undefined && !this.#loopbackOrganization;
+    if (cloudId === undefined && options.deferInfo === true) throw new TypeError('deferInfo applies only to Cloud database URLs');
+    if (cloudId === undefined && options.warm === true) throw new TypeError('warm applies only to Cloud database URLs');
+    // Cloud database URLs carry the database id and have documented capabilities,
+    // so the details request waits until a write needs a current sequence.
+    if (this.#cloud && options.deferInfo !== false) {
+      this.#id = cloudId; this.#capabilities = capabilities(this.#url, {}, false); this.#deferred = true;
+    }
+    this.#warm = this.#cloud && options.warm !== false;
+  }
+  [warmAtConnect]() {
+    if (this.#warm) this.warm().catch(() => {});
+  }
+  get deferred() { return this.#deferred; }
+  get url() { return this.#url; }
+  get cloud() { return this.#cloud; }
+  get sequence() { return this.#sequence; }
+  get sequenceKnown() { return this.#sequenceKnown; }
+  get databaseId() { return this.#id; }
+  async info(options = {}) {
+    const info = await this.#request('', undefined, options, false);
+    if (!plainObject(info) || typeof info.id !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/.test(info.id) || !sequence(info.sequence, true) || (this.#id !== undefined && this.#id !== info.id)) {
+      throw new ClientError('FDB_PROTOCOL', 'Invalid database details or changed database identity', 'read-failed');
+    }
+    if (this.#loopbackOrganization) this.#cloud = info.serviceVersion === undefined;
+    const supported = capabilities(this.#url, info, !this.#cloud);
+    this.#id = info.id;
+    this.#sequence = Math.max(this.#sequence, info.sequence);
+    this.#sequenceKnown = true;
+    this.#capabilities = supported;
+    return { ...info, capabilities: supported };
+  }
+  async warm(options = {}) {
+    this.#assertOpen();
+    if (!this.#cloud) throw new ClientError('FDB_UNSUPPORTED', 'warm applies only to Cloud database URLs', 'not-sent');
+    const reply = await this.#request('/warm', '{}', options, false);
+    if (!plainObject(reply) || !WARM_STATES.has(reply.state)) throw new ClientError('FDB_PROTOCOL', 'Invalid warm reply', 'read-failed');
+    return { state: reply.state };
+  }
+  async read(statements, options = {}) {
+    this.#assertOpen();
+    if (this.#capabilities.readVersion !== 2) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support fresh reads', 'not-sent');
+    if (options.ifSequence !== undefined) throw new TypeError('fresh reads do not accept ifSequence');
+    const afterSequence = options.afterSequence ?? this.#sequence;
+    checkSequence(afterSequence);
+    const workLimits = encodeWorkLimits(options.workLimits);
+    const queryVersion = this.#queryVersion();
+    const body = JSON.stringify({ readVersion: 2, requestId: crypto.randomUUID(), afterSequence, statements: encodeStatements(statements, queryVersion), ...(workLimits === undefined ? {} : { workLimits }) });
+    checkBodySize(body, queryVersion);
+    const request = JSON.parse(body);
+    const reply = await this.#request('/read', body, options, false, undefined, queryVersion);
+    const result = confirmReply(reply, request, true);
+    this.#sequence = Math.max(this.#sequence, result.sequence);
+    this.#sequenceKnown = true;
+    return result;
+  }
+  prepareWrite(statements, options = {}) {
+    this.#assertOpen();
+    if (!this.#sequenceKnown && this.#deferred && options.afterSequence === undefined) throw new ClientError('FDB_SEQUENCE_UNKNOWN', 'Read, call info() or pass afterSequence before preparing a write on a deferred connection', 'not-sent');
+    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support atomic writes with recovery', 'not-sent');
+    const afterSequence = options.afterSequence ?? this.#sequence;
+    checkSequence(afterSequence);
+    if (options.ifSequence !== undefined) {
+      if (this.#capabilities.exactSequenceCondition !== true) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support exact sequence conditions', 'not-sent');
+      checkSequence(options.ifSequence);
+      if (options.ifSequence < afterSequence) throw new RangeError('ifSequence must be at least afterSequence');
+    }
+    const requestId = options.requestId ?? crypto.randomUUID();
+    if (typeof requestId !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/.test(requestId)) throw new TypeError('requestId requires 1..80 letters, digits, underscores or hyphens');
+    const workLimits = encodeWorkLimits(options.workLimits);
+    const queryVersion = this.#queryVersion();
+    const body = JSON.stringify({ requestId, afterSequence, ...(options.ifSequence === undefined ? {} : { ifSequence: options.ifSequence }), statements: encodeStatements(statements, queryVersion), ...(workLimits === undefined ? {} : { workLimits }) });
+    checkBodySize(body, queryVersion);
+    return Object.freeze({ version: 2, url: this.#url, databaseId: this.#id, queryVersion, body });
+  }
+  async submit(prepared, options = {}) {
+    this.#assertOpen();
+    const request = validatePrepared(prepared);
+    if (this.#capabilities.atomicWrites !== true || this.#capabilities.replayWindow !== 64 || (request.ifSequence !== undefined && this.#capabilities.exactSequenceCondition !== true)) throw new ClientError('FDB_UNSUPPORTED', 'Database does not support this write contract', 'not-sent', { request: prepared });
+    if (prepared.url !== this.#url || prepared.databaseId !== this.#id) throw new ClientError('FDB_REQUEST_IDENTITY', 'Saved request belongs to another database', 'not-sent');
+    try {
+      const reply = await this.#request('/query', prepared.body, options, true, prepared, preparedQueryVersion(prepared));
+      const result = confirmReply(reply, request, false, prepared);
+      this.#sequence = Math.max(this.#sequence, result.sequence);
+      this.#sequenceKnown = true;
+      return result;
+    } catch (error) {
+      if (error instanceof ClientError) {
+        if (error.outcome === 'rolled-back') this.#sequence = Math.max(this.#sequence, error.sequence);
+        throw error;
+      }
+      throw new ClientError('FDB_PROTOCOL', 'Write response could not be confirmed; recover the saved request', 'unknown', { request: prepared });
+    }
+  }
+  async recover(prepared, options = {}) {
+    try { return await this.submit(prepared, options); }
+    catch (error) {
+      if (error instanceof ClientError && error.outcome === 'not-sent') throw new ClientError(error.code, 'Recovery did not confirm the earlier write; keep the saved request', 'unknown', { request: prepared });
+      throw error;
+    }
+  }
+  async writeAtomic(statements, options = {}) {
+    if (!this.#sequenceKnown && this.#deferred && options.afterSequence === undefined) await this.info(options);
+    return this.submit(this.prepareWrite(statements, options), options);
+  }
+  async close() {
+    this.#closed = true;
+    for (const controller of this.#active) controller.abort();
+    this.#token = '';
+  }
+  #assertOpen() {
+    if (this.#closed) throw new ClientError('FDB_CLOSED', 'Database client is closed', 'not-sent');
+  }
+  #queryVersion() { return this.#cloud ? CLOUD_QUERY_VERSION : 2; }
+  async #request(path, body, options, writing, prepared, queryVersion = 2) {
+    this.#assertOpen();
+    const duration = timeout(options.timeoutMs ?? this.#timeout);
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError('signal must be an AbortSignal');
+    if (options.signal?.aborted) throw new ClientError('FDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent', prepared ? { request: prepared } : {});
+    const bodyBytes = body === undefined ? 0 : byteLength(body);
+    if (this.#active.size >= 32 || this.#inflightBytes + bodyBytes > 2_097_152) throw new ClientError('FDB_LIMIT', 'Client request limit reached', 'not-sent', prepared ? { request: prepared } : {});
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(abort, duration);
+    this.#active.add(controller);
+    this.#inflightBytes += bodyBytes;
+    const credential = this.#token;
+    const fetch = this.#fetch;
+    let status;
+    try {
+      if (this.#transport) return await this.#transport(path, body, controller.signal, duration);
+      const send = () => fetch(this.#url + path, {
+        method: body === undefined ? 'GET' : 'POST',
+        headers: { authorization: `Bearer ${credential}`, accept: 'application/json', ...(body === undefined ? {} : { 'content-type': 'application/json' }), ...(this.#id === undefined ? {} : { 'x-romedb-database-id': prepared?.databaseId ?? this.#id }),
+          ...(queryVersion === CLOUD_QUERY_VERSION && (path === '/query' || path === '/read') ? { 'x-romedb-query-version': String(queryVersion) } : {}) },
+        ...(body === undefined ? {} : { body }),
+        // Workers have no redirect: 'error'; a redirect is refused below, never followed with the credential.
+        redirect: 'manual', signal: controller.signal,
+      });
+      let response = await send();
+      if (await queueRefused(response)) {
+        await pause(queueRetryDelay(response), controller.signal);
+        response = await send();
+      }
+      status = response.status;
+      if (response.type === 'opaqueredirect' || (status >= 300 && status < 400)) {
+        await response.body?.cancel().catch(() => {});
+        throw new ClientError('FDB_PROTOCOL', 'Database URL redirected; redirects are never followed with a credential', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
+      }
+      const retryAfterMs = retryAfter(response.headers.get('retry-after'));
+      const replyVersion = response.headers.get('x-romedb-query-version');
+      if ((path === '/query' || path === '/read') && replyVersion !== null && replyVersion !== '2' && replyVersion !== String(queryVersion)) {
+        await response.body?.cancel();
+        throw new ClientError('FDB_PROTOCOL', 'Unsupported database query response version', writing ? 'unknown' : 'read-failed', { status, ...(prepared ? { request: prepared } : {}) });
+      }
+      const reply = await boundedJson(response, MAX_RESPONSE);
+      if (plainObject(reply?.error) && typeof reply.error.message === 'string') reply.error.message = redactMessage(reply.error.message, credential);
+      if (!response.ok && !(writing && reply?.requestId && reply?.sequence !== undefined)) {
+        const code = plainObject(reply?.error) && typeof reply.error.code === 'string' && /^FDB_[A-Z0-9_]{1,80}$/.test(reply.error.code) ? reply.error.code : httpCode(status);
+        throw new ClientError(code, safeMessage(reply, credential), writing ? 'unknown' : 'read-failed', { status, ...(retryAfterMs === undefined ? {} : { retryAfterMs }), ...(prepared ? { request: prepared } : {}) });
+      }
+      return reply;
+    } catch (error) {
+      if (error instanceof ClientError) {
+        const outcome = writing
+          ? this.#transport && error.outcome === 'not-sent' ? 'not-sent' : 'unknown'
+          : error.outcome === 'not-sent' ? 'not-sent' : 'read-failed';
+        const message = this.#transport ? error.message.slice(0, 2048) : redactMessage(error.message, credential);
+        throw new ClientError(error.code, message, outcome, {
+          ...(error.status === undefined ? {} : { status: error.status }),
+          ...(error.retryAfterMs === undefined ? {} : { retryAfterMs: error.retryAfterMs }),
+          ...(prepared ? { request: prepared } : {}),
+        });
+      }
+      const code = controller.signal.aborted ? 'FDB_CANCELLED' : status === undefined ? 'FDB_TRANSPORT' : 'FDB_PROTOCOL';
+      throw new ClientError(code, writing ? 'Write was not confirmed; recover the saved request' : 'Database request failed', writing ? 'unknown' : 'read-failed', { ...(status === undefined ? {} : { status }), ...(prepared ? { request: prepared } : {}), cause: error });
+    } finally {
+      clearTimeout(timer);
+      options.signal?.removeEventListener('abort', abort);
+      this.#active.delete(controller);
+      this.#inflightBytes -= bodyBytes;
+    }
+  }
+}
+
+require('./client-internal.cjs').createEmbeddedClient = async (options, transport) => {
+  const database = new RemoteDatabase({ ...options, token: 'embedded' }, construction, transport);
+  try { await database.info(); return database; }
+  catch (error) { await database.close(); throw error; }
+};
+
+function normalizeFileUrl(input) {
+  if (typeof input !== 'string' || input.length > 4096) throw new TypeError('file URL requires a bounded local path');
+  const url = new URL(input);
+  if (url.protocol !== 'file:' || url.hostname || url.search || url.hash || url.pathname === '/' || /%2f|%5c|%00/i.test(url.pathname)) throw new TypeError('use a local file URL without a query or fragment');
+  return url.href;
+}
+
+function normalizeUrl(input) {
+  if (typeof input !== 'string' || input.length > 4096) throw new TypeError('url requires a bounded database URL');
+  // romedb:// is an alias for https://; the same checks apply after the rewrite.
+  const url = new URL(input.startsWith('romedb://') ? 'https://' + input.slice('romedb://'.length) : input);
+  const loopback = loopbackHost(url.hostname);
+  if (url.username || url.password || url.search || url.hash || (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))) throw new TypeError('use HTTPS or loopback HTTP without URL credentials, query or fragment');
+  let path = url.pathname.replace(/\/$/, '').replace(/\/(?:query|read)$/, '');
+  if (loopback && !path) path = '/v1/database';
+  const uuid = '[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}';
+  if (!(loopback && path === '/v1/database') && !new RegExp(`^/v1/organizations/${uuid}/databases/${uuid}$`).test(path)) throw new TypeError('use a local service URL or stable organization-scoped Cloud database URL');
+  return url.origin + path;
+}
+
+function encodeStatements(statements, queryVersion = 2) {
+  if (!Array.isArray(statements) || statements.length < 1 || statements.length > 32) throw new RangeError('request requires 1..32 statements');
+  return statements.map(statement => {
+    if (!plainObject(statement) || Object.keys(statement).some(key => !['sql', 'params'].includes(key)) || typeof statement.sql !== 'string' || !statement.sql.trim()) throw new TypeError('statement requires SQL and optional params');
+    if (statement.params === undefined) return { sql: text(statement.sql) };
+    if (!plainObject(statement.params)) throw new TypeError('params require an object');
+    return { sql: text(statement.sql), params: Object.fromEntries(Object.entries(statement.params).map(([key, value]) => [text(key), encodeValue(value, 0, queryVersion === CLOUD_QUERY_VERSION)])) };
+  });
+}
+
+function validatePrepared(prepared) {
+  const fields = prepared?.version === 1 ? 'body,databaseId,url,version' : 'body,databaseId,queryVersion,url,version';
+  if (!plainObject(prepared) || Object.keys(prepared).sort().join(',') !== fields || ![1, 2].includes(prepared.version) ||
+      (prepared.version === 2 && ![2, CLOUD_QUERY_VERSION].includes(prepared.queryVersion)) || typeof prepared.databaseId !== 'string' || !prepared.databaseId ||
+      (prepared.url?.startsWith('file:') ? normalizeFileUrl(prepared.url) : normalizeUrl(prepared.url)) !== prepared.url || typeof prepared.body !== 'string') throw new TypeError('invalid saved request');
+  checkBodySize(prepared.body, preparedQueryVersion(prepared));
+  const body = JSON.parse(prepared.body);
+  if (!plainObject(body) || Object.keys(body).some(key => !['requestId', 'afterSequence', 'ifSequence', 'statements', 'workLimits'].includes(key)) || typeof body.requestId !== 'string' || !/^[A-Za-z0-9_-]{1,80}$/.test(body.requestId)) throw new TypeError('invalid saved request identity');
+  encodeWorkLimits(body.workLimits);
+  checkSequence(body.afterSequence);
+  if (body.ifSequence !== undefined) {
+    checkSequence(body.ifSequence);
+    if (body.ifSequence < body.afterSequence) throw new RangeError('invalid saved sequence condition');
+  }
+  if (!Array.isArray(body.statements) || body.statements.length < 1 || body.statements.length > 32) throw new TypeError('invalid saved statements');
+  for (const statement of body.statements) {
+    if (!plainObject(statement) || Object.keys(statement).some(key => !['sql', 'params'].includes(key)) || typeof statement.sql !== 'string' || !statement.sql.trim() || (statement.params !== undefined && !plainObject(statement.params))) throw new TypeError('invalid saved statement');
+    for (const value of Object.values(statement.params ?? {})) decodeValue(value);
+  }
+  return body;
+}
+
+function confirmReply(reply, request, reading, prepared) {
+  const invalid = () => new ClientError('FDB_PROTOCOL', reading ? 'Read response identity or results differ' : 'Write response could not be confirmed; recover the saved request', reading ? 'read-failed' : 'unknown', prepared ? { request: prepared } : {});
+  if (!plainObject(reply) || reply.requestId !== request.requestId || !sequence(reply.sequence, true) || (reading ? reply.readVersion !== 2 || reply.sequence < request.afterSequence : reply.readVersion !== undefined || reply.sequence <= request.afterSequence || reply.sequence - request.afterSequence > 64)) throw invalid();
+  if (plainObject(reply.error) && typeof reply.error.code === 'string' && /^FDB_[A-Z0-9_]+$/.test(reply.error.code) && typeof reply.error.message === 'string' && reply.results === undefined) throw new ClientError(reply.error.code, reply.error.message.slice(0, 2048), reading ? 'read-failed' : 'rolled-back', { sequence: reply.sequence, request: prepared });
+  if (!Array.isArray(reply.results) || reply.results.length !== request.statements.length || reply.error !== undefined || byteLength(JSON.stringify(reply.results)) > 262_144) throw invalid();
+  try {
+    const results = reply.results.map(result => {
+      if (!plainObject(result) || !Array.isArray(result.columns) || result.columns.some(name => typeof name !== 'string') || !Array.isArray(result.rows) || result.rows.length > 1000 || typeof result.affected !== 'string' || !/^(?:0|[1-9][0-9]{0,19})$/.test(result.affected) || BigInt(result.affected) > (1n << 64n) - 1n) throw invalid();
+      return { columns: result.columns, rows: result.rows.map(row => {
+        if (!Array.isArray(row) || row.length !== result.columns.length) throw invalid();
+        return row.map(value => decodeValue(value));
+      }), affected: BigInt(result.affected) };
+    });
+    return { requestId: reply.requestId, sequence: reply.sequence, results, ...(reading ? { readVersion: 2 } : {}), ...(reply.executionWork === undefined ? {} : { executionWork: reply.executionWork }) };
+  } catch { throw invalid(); }
+}
+
+async function boundedJson(response, limit) {
+  if (!/^application\/json(?:\s*;|$)/i.test(response.headers.get('content-type') ?? '')) throw new TypeError('response requires JSON');
+  if (!response.body) throw new TypeError('response body is missing');
+  const reader = response.body.getReader();
+  const chunks = [];
+  let length = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      length += value.byteLength;
+      if (length > limit) throw new RangeError('response exceeds client byte limit');
+      chunks.push(value);
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+  } finally { await reader.cancel().catch(() => {}); }
+}
+
+function loopbackHost(hostname) { return ['127.0.0.1', 'localhost', '[::1]'].includes(hostname); }
+
+function capabilities(url, info, local) {
+  if (local) {
+    if ((url.startsWith('file:') ? info.adapterVersion : info.serviceVersion) !== 1 || !plainObject(info.capabilities) || !plainObject(info.limits) || info.capabilities.readVersion !== 2 || typeof info.capabilities.atomicWrites !== 'boolean' || typeof info.capabilities.exactSequenceCondition !== 'boolean' || (info.capabilities.atomicWrites && info.capabilities.replayWindow !== 64)) throw new ClientError('FDB_PROTOCOL', 'Unsupported database client contract', 'read-failed');
+    return { ...info.capabilities, provenance: 'negotiated' };
+  }
+  return { provenance: 'documented', readVersion: 2, atomicWrites: true, replayWindow: 64, exactSequenceCondition: true, negotiatedLimits: false };
+}
+
+function sequence(value, reply = false) { return Number.isSafeInteger(value) && value >= 0 && value <= (reply ? MAX_SEQUENCE + 1 : MAX_SEQUENCE); }
+function encodeWorkLimits(value) {
+  if (value === undefined) return undefined;
+  const ceilings = { rowsRead: 1_000_000, rowMutations: 100_000, vmSteps: 10_000_000 };
+  if (!plainObject(value)) throw new TypeError('workLimits require an object');
+  for (const [name, limit] of Object.entries(value)) {
+    if (!Object.hasOwn(ceilings, name) || !Number.isSafeInteger(limit) || limit < 0 || limit > ceilings[name]) throw new RangeError('workLimits require nonnegative integers within the service ceilings');
+  }
+  return Object.fromEntries(Object.keys(ceilings).filter(key => Object.hasOwn(value, key)).map(key => [key, value[key]]));
+}
+function checkSequence(value) { if (!sequence(value)) throw new RangeError('sequence requires a nonnegative safe integer below Number.MAX_SAFE_INTEGER'); }
+function timeout(value) { if (!Number.isInteger(value) || value < 1 || value > 120_000) throw new RangeError('timeoutMs must be 1..120000'); return value; }
+function byteLength(text) { return encoder.encode(text).byteLength; }
+function checkBodySize(body, queryVersion = 2) {
+  if (byteLength(body) > (queryVersion === CLOUD_QUERY_VERSION ? MAX_CLOUD_REQUEST : MAX_REQUEST))
+    throw new RangeError(queryVersion === CLOUD_QUERY_VERSION ? 'request exceeds 1 MiB' : 'request exceeds 64 KiB');
+}
+function preparedQueryVersion(prepared) { return prepared.version === 1 ? 2 : prepared.queryVersion; }
+// Cloud refuses a queued request with 503 query_queue_* before dispatching it,
+// so nothing ran and one retry is safe for reads and writes alike.
+async function queueRefused(response) {
+  if (response.status !== 503) return false;
+  try { return /^query_queue_[a-z_]{1,40}$/.test((await response.clone().json())?.code ?? ''); } catch { return false; }
+}
+function queueRetryDelay(response) {
+  const header = response.headers.get('retry-after');
+  return header === null ? 0 : Math.min(retryAfter(header) ?? 1000, 2000);
+}
+// Retry-After holds delay seconds or an HTTP date.
+function retryAfter(value) {
+  if (value === null) return undefined;
+  if (/^\s*\d{1,9}(?:\.\d+)?\s*$/.test(value)) return Math.round(Number(value) * 1000);
+  const date = /GMT\s*$/.test(value) ? Date.parse(value) : NaN;
+  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+function pause(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) { reject(signal.reason); return; }
+    const timer = setTimeout(() => { signal.removeEventListener('abort', stop); resolve(); }, ms);
+    const stop = () => { clearTimeout(timer); reject(signal.reason); };
+    signal.addEventListener('abort', stop, { once: true });
+  });
+}
+function httpCode(status) { return status === 401 ? 'FDB_AUTH' : status === 403 ? 'FDB_FORBIDDEN' : status === 409 ? 'FDB_CONFLICT' : status === 429 || status === 413 ? 'FDB_LIMIT' : 'FDB_REMOTE'; }
+function redactMessage(message, token) { return (token ? message.replaceAll(token, '[redacted]') : message).slice(0, 2048); }
+function safeMessage(reply, token) { return redactMessage(typeof reply?.error === 'string' ? reply.error : typeof reply?.error?.message === 'string' ? reply.error.message : 'Database request was rejected', token); }
+
+async function saveRequest(path, request) { return require('./request-journal.cjs').saveRequest(path, request, validatePrepared); }
+async function loadRequest(path) { return require('./request-journal.cjs').loadRequest(path, validatePrepared); }
+
+module.exports = { connect, RemoteDatabase, ClientError, Float64, Record, Vector, encodeValue, decodeValue, normalizeUrl, validatePrepared, saveRequest, loadRequest };
+})(commonjs, commonjs.exports, specifier => {
+  if (specifier === './values.cjs') return module0;
+  if (specifier === './client-internal.cjs') return {};
+  if (specifier === './request-journal.cjs') throw new TypeError("saveRequest and loadRequest need Node.js file access; store the PreparedWrite yourself");
+  throw new TypeError(`Cannot load ${specifier}`);
+});
+
+export const { connect, RemoteDatabase, ClientError, Float64, Record, Vector, encodeValue, decodeValue, normalizeUrl, validatePrepared, saveRequest, loadRequest } = commonjs.exports;

package/embedded-client.cjs

@@ -0,0 +1,180 @@
+'use strict';
+const { Worker } = require('node:worker_threads');
+const { addAbortListener } = require('node:events');
+const { randomUUID } = require('node:crypto');
+const fs = require('node:fs/promises');
+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 { createEmbeddedClient } = require('./client-internal.cjs');
+const native = require('./native.cjs');
+const sessions = new Map();
+const construction = Symbol('EmbeddedDatabase');
+
+async function openEmbedded(options) {
+  const duration = options?.timeoutMs ?? 20000;
+  if (!Number.isInteger(duration) || duration < 1 || duration > 120000) throw new RangeError('timeoutMs must be 1..120000');
+  let abandoned = false;
+  const opening = openEmbeddedFile(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);
+  });
+  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';
+    throw new common.ClientError(code, 'Embedded filesystem operation failed', 'not-sent');
+  } finally { clearTimeout(timer); }
+}
+
+async function openEmbeddedFile(options) {
+  if (!plainObject(options) || Object.keys(options).some(key => !['path', 'create', 'timeoutMs', 'maxOpen'].includes(key)) || typeof options.path !== 'string' || !options.path || options.path.length > 4096 || options.path.includes('\0') || (options.create !== undefined && typeof options.create !== 'boolean')) throw new TypeError('embedded options require a bounded path, optional create, timeoutMs and maxOpen');
+  if (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1 || options.timeoutMs > 120000)) throw new RangeError('timeoutMs must be 1..120000');
+  const maxOpen = options.maxOpen ?? 16;
+  if (!Number.isInteger(maxOpen) || maxOpen < 1 || maxOpen > 1024) throw new RangeError('maxOpen must be 1..1024');
+  const file = path.resolve(options.path);
+  if (options.create) {
+    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'); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    const handle = await fs.open(file, 'wx', 0o600);
+    try { await handle.sync(); } finally { await handle.close(); }
+    const parent = await fs.open(path.dirname(file), 'r');
+    try { await parent.sync(); } finally { await parent.close(); }
+  }
+  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');
+    throw error;
+  }
+  if (!metadata.isFile() || metadata.nlink !== 1) throw new common.ClientError('FDB_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 }); }
+  if (!session) {
+    if (sessions.size >= maxOpen) throw openLimit();
+    session = new Session(canonical, options.create === true);
+    sessions.set(canonical, session);
+  }
+  session.references++;
+  try {
+    await session.ready;
+    const client = await createEmbeddedClient({ url: session.url, timeoutMs: options.timeoutMs }, (route, body, signal, duration) => session.request(route === '' ? 'info' : route === '/read' ? 'read' : 'write', body, signal, duration));
+    return new EmbeddedDatabase(client, session, canonical, construction);
+  } catch (error) { await releaseSession(session, canonical); throw error; }
+}
+
+function openLimit() {
+  return new common.ClientError('FDB_LIMIT', `Embedded database limit reached: ${sessions.size} files are open; close one or raise maxOpen`, 'not-sent');
+}
+
+class EmbeddedDatabase {
+  #client; #session; #path; #closing;
+  constructor(client, session, file, key) {
+    if (key !== construction) throw new TypeError('use openEmbedded()');
+    this.#client = client; this.#session = session; this.#path = file;
+  }
+  get url() { return this.#client.url; }
+  get sequence() { return this.#client.sequence; }
+  get sequenceKnown() { return this.#client.sequenceKnown; }
+  get databaseId() { return this.#client.databaseId; }
+  get path() { return this.#path; }
+  info(options) { return this.#client.info(options); }
+  read(statements, options) { return this.#client.read(statements, options); }
+  prepareWrite(statements, options) { return this.#client.prepareWrite(statements, options); }
+  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); }
+  close() {
+    this.#closing ??= (async () => { await this.#client.close(); await releaseSession(this.#session, this.#path); })();
+    return this.#closing;
+  }
+}
+
+class Session {
+  #worker; #pending = new Map(); #bytes = 0; #next = 0; #failure;
+  references = 0; closing = false; ready; closed;
+  constructor(file, create) {
+    this.url = pathToFileURL(file).href;
+    this.#worker = new Worker(require.resolve('./embedded-worker.cjs'), { workerData: { path: file, url: this.url, databaseId: randomUUID(), create } });
+    let resolveReady, rejectReady, resolveExit;
+    this.ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+    this.closed = new Promise(resolve => { resolveExit = resolve; });
+    this.ready.catch(() => {});
+    this.#worker.on('message', message => {
+      if (message.ready) return resolveReady();
+      if (message.readyError) {
+        this.#failure = new common.ClientError(message.readyError.code, message.readyError.message, 'not-sent');
+        rejectReady(this.#failure);
+        return;
+      }
+      const pending = this.#pending.get(message.id);
+      if (!pending) return;
+      this.#pending.delete(message.id);
+      this.#bytes -= pending.bytes;
+      pending.listener?.[Symbol.dispose]();
+      native.releaseCancellationToken(pending.token);
+      if (message.error) pending.reject(new common.ClientError(message.error.code, message.error.message, message.error.outcome));
+      else pending.resolve(message.result);
+    });
+    this.#worker.on('error', () => {
+      this.#failure ??= new common.ClientError('FDB_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');
+      rejectReady(this.#failure);
+      for (const pending of this.#pending.values()) {
+        pending.listener?.[Symbol.dispose]();
+        native.releaseCancellationToken(pending.token);
+        pending.reject(this.#failure);
+      }
+      this.#pending.clear(); this.#bytes = 0;
+      resolveExit();
+    });
+  }
+  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'));
+    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'));
+    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'));
+      });
+      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'));
+      }
+    });
+  }
+  async close() {
+    this.closing = true;
+    try { if (!this.#failure) await this.request('close'); }
+    finally { await this.closed; }
+  }
+}
+
+async function releaseSession(session, file) {
+  if (--session.references === 0) {
+    try { await session.close(); }
+    finally { if (sessions.get(file) === session) sessions.delete(file); }
+  }
+}
+
+module.exports = { openEmbedded, EmbeddedDatabase, connect, RemoteDatabase, ClientError, Float64, Record, Vector, encodeValue, decodeValue, normalizeUrl, validatePrepared, saveRequest, loadRequest };

package/embedded-client.d.ts

@@ -0,0 +1,19 @@
+export * from './client';
+import type { Client, DatabaseInfo, Statement, RequestOptions, ReadOptions, WriteOptions, BatchResult, PreparedWrite } from './client';
+export interface EmbeddedOptions { path: string; create?: boolean; timeoutMs?: number; maxOpen?: number; }
+export class EmbeddedDatabase implements Client {
+  private constructor();
+  readonly path: string;
+  readonly url: string;
+  readonly sequence: number;
+  readonly sequenceKnown: boolean;
+  readonly databaseId: string;
+  info(options?: RequestOptions): Promise<DatabaseInfo>;
+  read(statements: Statement[], options?: ReadOptions): Promise<BatchResult>;
+  prepareWrite(statements: Statement[], options?: WriteOptions): PreparedWrite;
+  submit(request: PreparedWrite, options?: RequestOptions): Promise<BatchResult>;
+  recover(request: PreparedWrite, options?: RequestOptions): Promise<BatchResult>;
+  writeAtomic(statements: Statement[], options?: WriteOptions): Promise<BatchResult>;
+  close(): Promise<void>;
+}
+export function openEmbedded(options: EmbeddedOptions): Promise<EmbeddedDatabase>;