@romedb/node 0.2.14 → 0.2.16

package/client.d.ts

@@ -1,105 +1 @@
-import type { Value } from './values';
-export { Float64, Record, Vector, Value, PortableValue, encodeValue, decodeValue } from './values';
-export interface Statement { sql: string; params?: { [key: string]: Value }; }
-export interface RequestOptions { signal?: AbortSignal; timeoutMs?: number; }
-/** What a copy of the database leaves out. */
-export interface CopyOptions {
-  /**
-   * These tables keep their schema and indexes but no rows. Their rows are never read, so
-   * they cannot reach the file. Unknown names fail with RDB_VALIDATION. The copy also gets
-   * a new identity, because a receipt can hold row data.
-   */
-  emptyTables?: readonly string[];
-  /** Leave out the database ID, the sequence and the receipts: the copy is a new database. */
-  newIdentity?: boolean;
-}
-export interface FileExportOptions extends RequestOptions, CopyOptions {}
-export interface WorkLimits { rowsRead?: number; rowMutations?: number; vmSteps?: number; }
-export interface ReadOptions extends RequestOptions { afterSequence?: number; workLimits?: WorkLimits; }
-export interface WriteOptions extends ReadOptions { requestId?: string; ifSequence?: number; }
-export type PreparedWrite =
-  | { readonly version: 1; readonly url: string; readonly databaseId: string; readonly body: string }
-  | { readonly version: 2; readonly url: string; readonly databaseId: string; readonly queryVersion: 2 | 3; readonly body: string };
-export interface QueryResult { columns: string[]; rows: Value[][]; affected: bigint; }
-export interface BatchResult { requestId: string; sequence: number; results: QueryResult[]; readVersion?: 2; executionWork?: unknown; }
-export interface Capabilities { provenance: 'negotiated' | 'documented'; [key: string]: unknown; }
-export interface DatabaseInfo {
-  id: string; sequence: number; capabilities: Capabilities;
-  /** RomeDB release of the engine, such as "2.7.0". RomeDB 2.7.0 and later report it. */
-  engineVersion?: string;
-  [key: string]: unknown;
-}
-export interface ConnectOptions {
-  url: string; token: string; timeoutMs?: number; fetch?: typeof globalThis.fetch;
-  /** Cloud database URLs skip the details request at connect by default; the first write without afterSequence fetches it. Pass false to request it at connect. */
-  deferInfo?: boolean;
-  /** Cloud database URLs send a background warm request at connect by default. Pass false to skip it. */
-  warm?: boolean;
-}
-export interface WarmResult { state: 'ready' | 'starting' | 'skipped'; }
-/** A copy of the database at one sequence: a complete .romedb file that opens without a log beside it. */
-export interface DatabaseFile {
-  /** Every write up to and including this sequence is in the file, and none after it. */
-  sequence: number;
-  /** File size in bytes; the body fails unless exactly this many arrive. */
-  size: number;
-  /** Read it to the end or cancel it, so the copy's storage is freed. */
-  body: ReadableStream<Uint8Array>;
-}
-export type Outcome = 'not-sent' | 'read-failed' | 'unknown' | 'rolled-back';
-export class ClientError extends Error {
-  readonly code: string;
-  readonly outcome: Outcome;
-  readonly request?: PreparedWrite;
-  readonly status?: number;
-  readonly sequence?: number;
-  /** The server's Retry-After delay in milliseconds, on HTTP error replies that send one. */
-  readonly retryAfterMs?: number;
-  /** For RDB_TRANSPORT, RDB_PROTOCOL and RDB_CANCELLED without a reply: the fetch or parse error underneath. */
-  readonly cause?: unknown;
-  constructor(code: string, message: string, outcome: Outcome, details?: { request?: PreparedWrite; status?: number; sequence?: number; retryAfterMs?: number; cause?: unknown });
-}
-export interface Client {
-  readonly sequence: number;
-  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 class RemoteDatabase implements Client {
-  private constructor();
-  readonly url: string;
-  /** True for a Cloud database. A loopback organization URL (romedb serve --directory) is not Cloud once info() has run. */
-  readonly cloud: boolean;
-  /** True once a reply has given the database's current sequence. */
-  readonly sequenceKnown: boolean;
-  /** True when connect() skipped the details request (the default for Cloud URLs). */
-  readonly deferred: boolean;
-  /** Ask Cloud to start the database's container and open the database without running a query. */
-  warm(options?: RequestOptions): Promise<WarmResult>;
-  /**
-   * Download the database as a .romedb file (romedb serve and serve --directory; not Cloud yet).
-   * timeoutMs covers building the copy, until the file starts arriving; signal also stops the download.
-   */
-  exportFile(options?: FileExportOptions): Promise<DatabaseFile>;
-  readonly sequence: number;
-  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 connect(options: ConnectOptions): Promise<RemoteDatabase>;
-export function normalizeUrl(url: string): string;
-export function validatePrepared(request: unknown): { requestId: string; afterSequence: number; ifSequence?: number; statements: unknown[] };
-/** Node.js only. Elsewhere it rejects; store the PreparedWrite yourself. */
-export function saveRequest(path: string, request: PreparedWrite): Promise<void>;
-/** Node.js only. Elsewhere it rejects. */
-export function loadRequest(path: string): Promise<PreparedWrite>;
+export * from '@romedb/client';

package/client.mjs

@@ -1,502 +1 @@
-// 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, checkCopyOptions } = 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 DATABASE_FILE_TYPE = 'application/vnd.romedb.database';
-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('RDB_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('RDB_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('RDB_PROTOCOL', 'Invalid warm reply', 'read-failed');
-    return { state: reply.state };
-  }
-  async read(statements, options = {}) {
-    this.#assertOpen();
-    if (this.#capabilities.readVersion !== 2) throw new ClientError('RDB_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('RDB_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('RDB_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('RDB_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('RDB_UNSUPPORTED', 'Database does not support this write contract', 'not-sent', { request: prepared });
-    if (prepared.url !== this.#url || prepared.databaseId !== this.#id) throw new ClientError('RDB_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('RDB_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 exportFile(options = {}) {
-    this.#assertOpen();
-    if (this.#transport) throw new ClientError('RDB_UNSUPPORTED', 'Export embedded databases through EmbeddedDatabase.exportFile', 'not-sent');
-    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);
-    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('RDB_CANCELLED', 'Request cancelled before dispatch', 'not-sent');
-    if (this.#active.size >= 32) throw new ClientError('RDB_LIMIT', 'Client request limit reached', 'not-sent');
-    const controller = new AbortController();
-    const abort = () => controller.abort();
-    options.signal?.addEventListener('abort', abort, { once: true });
-    const timer = setTimeout(abort, duration);
-    this.#active.add(controller);
-    let open = true;
-    const finish = () => {
-      if (!open) return;
-      open = false;
-      clearTimeout(timer);
-      options.signal?.removeEventListener('abort', abort);
-      this.#active.delete(controller);
-    };
-    const credential = this.#token;
-    let status;
-    try {
-      const response = await this.#fetch(this.#url + '/file' + fileQuery(options), {
-        method: 'GET',
-        headers: { authorization: `Bearer ${credential}`, accept: `${DATABASE_FILE_TYPE}, application/json`, ...(this.#id === undefined ? {} : { 'x-romedb-database-id': this.#id }) },
-        redirect: 'manual', signal: controller.signal,
-      });
-      // The deadline covers building the copy; the caller's signal still stops the download.
-      clearTimeout(timer);
-      status = response.status;
-      if (response.type === 'opaqueredirect' || (status >= 300 && status < 400)) throw new ClientError('RDB_PROTOCOL', 'Database URL redirected; redirects are never followed with a credential', 'read-failed', { status });
-      if (!response.ok) {
-        const retryAfterMs = retryAfter(response.headers.get('retry-after'));
-        const reply = await boundedJson(response, MAX_RESPONSE).catch(() => undefined);
-        const code = plainObject(reply?.error) && typeof reply.error.code === 'string' && /^RDB_[A-Z0-9_]{1,80}$/.test(reply.error.code) ? reply.error.code : httpCode(status);
-        throw new ClientError(code, safeMessage(reply, credential), 'read-failed', { status, ...(retryAfterMs === undefined ? {} : { retryAfterMs }) });
-      }
-      const size = Number(/^\d{1,16}$/.exec(response.headers.get('content-length') ?? '')?.[0] ?? NaN);
-      const exported = Number(/^\d{1,16}$/.exec(response.headers.get('x-romedb-sequence') ?? '')?.[0] ?? NaN);
-      const identity = response.headers.get('x-romedb-database-id');
-      if ((response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase() !== DATABASE_FILE_TYPE || !Number.isSafeInteger(size) || !sequence(exported, true) || !response.body) {
-        throw new ClientError('RDB_PROTOCOL', 'Invalid database file response', 'read-failed', { status });
-      }
-      if (identity === null || (this.#id !== undefined && identity !== this.#id)) throw new ClientError('RDB_REQUEST_IDENTITY', 'Database file belongs to another database', 'read-failed', { status });
-      this.#id ??= identity;
-      this.#sequence = Math.max(this.#sequence, exported);
-      this.#sequenceKnown = true;
-      return { sequence: exported, size, body: countedBody(response.body, size, controller, finish) };
-    } catch (error) {
-      finish();
-      if (error instanceof ClientError) throw new ClientError(error.code, redactMessage(error.message, credential), error.outcome, { ...(error.status === undefined ? {} : { status: error.status }), ...(error.retryAfterMs === undefined ? {} : { retryAfterMs: error.retryAfterMs }) });
-      throw new ClientError(controller.signal.aborted ? 'RDB_CANCELLED' : status === undefined ? 'RDB_TRANSPORT' : 'RDB_PROTOCOL', 'Database file request failed', 'read-failed', { ...(status === undefined ? {} : { status }), cause: error });
-    }
-  }
-  async close() {
-    this.#closed = true;
-    for (const controller of this.#active) controller.abort();
-    this.#token = '';
-  }
-  #assertOpen() {
-    if (this.#closed) throw new ClientError('RDB_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('RDB_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('RDB_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('RDB_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('RDB_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' && /^RDB_[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 ? 'RDB_CANCELLED' : status === undefined ? 'RDB_TRANSPORT' : 'RDB_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('RDB_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' && /^RDB_[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(() => {}); }
-}
-
-// Passes the download through and fails it unless exactly `size` bytes arrive.
-function countedBody(body, size, controller, finish) {
-  const reader = body.getReader();
-  let received = 0;
-  const failure = (message, cause) => new ClientError(controller.signal.aborted ? 'RDB_CANCELLED' : 'RDB_TRANSPORT', message, 'read-failed', cause === undefined ? {} : { cause });
-  return new ReadableStream({
-    async pull(stream) {
-      let chunk;
-      try { chunk = await reader.read(); }
-      catch (error) { finish(); stream.error(failure('Database file download failed', error)); return; }
-      if (chunk.done) {
-        finish();
-        if (received === size) stream.close();
-        else stream.error(failure('Database file ended before its declared size'));
-        return;
-      }
-      received += chunk.value.byteLength;
-      if (received > size) {
-        finish(); controller.abort();
-        stream.error(new ClientError('RDB_PROTOCOL', 'Database file is larger than its declared size', 'read-failed'));
-        return;
-      }
-      stream.enqueue(chunk.value);
-    },
-    cancel(reason) { finish(); controller.abort(); return reader.cancel(reason).catch(() => {}); },
-  }, { highWaterMark: 0 });
-}
-
-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('RDB_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 fileQuery({ emptyTables, newIdentity }) {
-  const parts = [];
-  if (emptyTables?.length) parts.push(`empty=${emptyTables.map(encodeURIComponent).join(',')}`);
-  if (newIdentity) parts.push('identity=new');
-  return parts.length ? `?${parts.join('&')}` : '';
-}
-function httpCode(status) { return status === 401 ? 'RDB_AUTH' : status === 403 ? 'RDB_FORBIDDEN' : status === 409 ? 'RDB_CONFLICT' : status === 429 || status === 413 ? 'RDB_LIMIT' : 'RDB_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;
+export * from '@romedb/client';

package/embedded-client.cjs

@@ -8,7 +8,7 @@ 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, checkCopyOptions } = require('./values.cjs');
-const { createEmbeddedClient } = require('./client-internal.cjs');
+const { createEmbeddedClient } = require('@romedb/client/internal');
 const native = require('./native.cjs');
 const sessions = new Map();
 const construction = Symbol('EmbeddedDatabase');