@romedb/client 0.0.0-stage → 0.2.14

package/client.mjs

@@ -0,0 +1,502 @@
+// 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;

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@romedb/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.14",
+  "description": "RomeDB client for Node.js, Cloudflare Workers and browsers. Connects by URL to romedb serve or RomeDB Cloud, with no native addon.",
+  "main": "client.cjs",
+  "types": "client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./client.d.ts",
+      "node": "./client.cjs",
+      "default": "./client.mjs"
+    },
+    "./values": {
+      "types": "./values.d.ts",
+      "node": "./values.cjs",
+      "default": "./values.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "client.cjs",
+    "client.mjs",
+    "client.d.ts",
+    "client-internal.cjs",
+    "values.cjs",
+    "values.mjs",
+    "values.d.ts",
+    "request-journal.cjs",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "keywords": [
+    "romedb",
+    "romeql",
+    "database",
+    "client",
+    "cloudflare-workers"
+  ],
+  "homepage": "https://github.com/romedb/romedb/tree/main/romedb/bindings/client#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/romedb/romedb.git",
+    "directory": "romedb/bindings/client"
+  },
+  "bugs": {
+    "url": "https://github.com/romedb/romedb/issues"
+  }
 }

package/request-journal.cjs

@@ -0,0 +1,47 @@
+'use strict';
+const fs = require('node:fs/promises');
+const { constants } = require('node:fs');
+const path = require('node:path');
+const { Buffer } = require('node:buffer');
+
+const MAX_JOURNAL = 2_359_296;
+
+async function saveRequest(file, request, validate) {
+  validate(request);
+  const text = JSON.stringify(request);
+  if (Buffer.byteLength(text) > MAX_JOURNAL) throw new RangeError('request journal exceeds byte limit');
+  const handle = await fs.open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+  try {
+    await handle.writeFile(text, 'utf8');
+    await handle.sync();
+  } catch (error) {
+    await handle.close();
+    await fs.unlink(file);
+    throw error;
+  }
+  await handle.close();
+  const directory = await fs.open(path.dirname(path.resolve(file)), constants.O_RDONLY | (constants.O_DIRECTORY ?? 0));
+  try { await directory.sync(); }
+  finally { await directory.close(); }
+}
+
+async function loadRequest(file, validate) {
+  const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o077) !== 0 || (typeof process.getuid === 'function' && stat.uid !== process.getuid()) || stat.size > MAX_JOURNAL) throw new Error('request journal requires a private bounded regular file');
+    const bytes = Buffer.alloc(MAX_JOURNAL + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const result = await handle.read(bytes, length, bytes.length - length, null);
+      if (!result.bytesRead) break;
+      length += result.bytesRead;
+    }
+    if (length > MAX_JOURNAL) throw new RangeError('request journal exceeds byte limit');
+    const request = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length)));
+    validate(request);
+    return Object.freeze(request);
+  } finally { await handle.close(); }
+}
+
+module.exports = { saveRequest, loadRequest };