@reddb-io/browser 0.0.0-stage → 0.1.0-alpha.1

package/src/index.js

@@ -0,0 +1,150 @@
+/** Shared Rust/WASM runtime and experimental artifact storage. */
+import { BrowserError, RUNTIME_ABI_VERSION, VALUE_ENCODING } from './protocol.js'
+export { BrowserError } from './protocol.js'
+
+function createClient(suppliedWorker) {
+  if (!globalThis.Worker) throw new BrowserError('RUNTIME_UNSUPPORTED', 'RedDB requires module Workers and WebAssembly')
+  if (suppliedWorker !== undefined && !(suppliedWorker instanceof Worker)) {
+    throw new BrowserError('INVALID_ARGUMENT', 'worker must be a dedicated Worker instance')
+  }
+  const worker = suppliedWorker ?? new Worker(new URL('./worker.js', import.meta.url), { type: 'module' })
+  const pending = new Map()
+  let sequence = 0
+  let closed = false
+  let terminated = false
+
+  function shutdown(error = new BrowserError('CLOSED', 'This runtime handle is closed')) {
+    closed = true
+    for (const request of pending.values()) request.reject(error)
+    pending.clear()
+    if (!terminated) worker.terminate()
+    terminated = true
+  }
+
+  worker.onmessage = ({ data }) => {
+    if (terminated) return
+    if (data?.abiVersion !== RUNTIME_ABI_VERSION) {
+      shutdown(new BrowserError('VERSION_MISMATCH', 'Worker runtime ABI does not match this SDK'))
+      return
+    }
+    if (!Number.isSafeInteger(data.id) || data.id < 1) {
+      shutdown(new BrowserError('WORKER_FAILED', 'Invalid runtime response identifier'))
+      return
+    }
+    const request = pending.get(data.id)
+    if (!request) return
+    pending.delete(data.id)
+    if (data.error) request.reject(new BrowserError(data.error.code, data.error.message))
+    else request.resolve(data.result)
+  }
+  worker.onerror = (event) => shutdown(new BrowserError('WORKER_FAILED', event.message || 'RedDB worker failed'))
+  worker.onmessageerror = () => shutdown(new BrowserError('WORKER_FAILED', 'Unable to decode a worker response'))
+
+  function call(method, params = {}) {
+    if (closed) return Promise.reject(new BrowserError('CLOSED', 'This runtime handle is closed'))
+    const id = ++sequence
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject })
+      try { worker.postMessage({ abiVersion: RUNTIME_ABI_VERSION, id, method, params }) }
+      catch (error) { pending.delete(id); reject(error) }
+    })
+  }
+
+  const ready = call('initialize').then(info => {
+    if (info?.abiVersion !== RUNTIME_ABI_VERSION || info.valueEncoding !== VALUE_ENCODING
+      || info.capabilities?.queryValidation !== true || info.capabilities?.scalarQueries !== true) {
+      throw new BrowserError('VERSION_MISMATCH', 'WASM runtime capabilities do not match this SDK')
+    }
+    return info
+  }).catch(error => { shutdown(error); throw error })
+  ready.catch(() => {}) // A bridge can be closed before its first invocation.
+  let closing
+  return {
+    ready, call, shutdown,
+    closeFile() {
+      if (!closing) {
+        closing = closed ? Promise.resolve() : call('close').finally(() => shutdown())
+        closed = true
+      }
+      return closing
+    },
+  }
+}
+
+function runtimeMethods(client) {
+  const query = (method, sql) => typeof sql === 'string'
+    ? client.call(method, { sql })
+    : Promise.reject(new BrowserError('INVALID_ARGUMENT', 'Expected an RQL string'))
+  return {
+    info: () => client.call('info'),
+    validateQuery: sql => query('validateQuery', sql),
+    executeScalar: sql => query('executeScalar', sql),
+  }
+}
+
+/** Storage-independent Rust/WASM operations; does not open an OPFS file. */
+export async function createRuntime({ worker } = {}) {
+  const client = createClient(worker)
+  await client.ready
+  return { ...runtimeMethods(client), close() { client.shutdown(); return Promise.resolve() } }
+}
+
+/** JSON-safe boundary for Dart, .NET and other JS-interop hosts. */
+export function createInteropRuntime({ worker } = {}) {
+  let client
+  let ready
+  let closed = false
+  try {
+    client = createClient(worker)
+    ready = client.ready.then(() => runtimeMethods(client))
+  } catch (error) { ready = Promise.reject(error) }
+  ready.catch(() => {})
+  return {
+    async invoke(method, params = {}) {
+      try {
+        if (closed) throw new BrowserError('CLOSED', 'This runtime handle is closed')
+        const runtime = await ready
+        if (!params || typeof params !== 'object' || Array.isArray(params)) {
+          throw new BrowserError('INVALID_ARGUMENT', 'Expected an argument object')
+        }
+        let result
+        switch (method) {
+          case 'info': result = await runtime.info(); break
+          case 'validateQuery': result = await runtime.validateQuery(params.sql); break
+          case 'executeScalar': result = await runtime.executeScalar(params.sql); break
+          default: throw new BrowserError('INVALID_ARGUMENT', 'Unknown runtime operation')
+        }
+        return { ok: true, result: result ?? null }
+      } catch (error) {
+        return { ok: false, error: {
+          code: typeof error.code === 'string' ? error.code : 'RUNTIME_ERROR',
+          message: error.message || String(error),
+        } }
+      }
+    },
+    close() { closed = true; client?.shutdown() },
+  }
+}
+
+/** Open an exclusively owned, canonical .rdb artifact in an OPFS worker. */
+export async function openArtifact({ name, worker } = {}) {
+  if (typeof name !== 'string' || !/^[a-zA-Z0-9_-][a-zA-Z0-9_.-]{0,79}$/.test(name)) {
+    throw new BrowserError('INVALID_NAME', 'Artifact names must contain 1–80 letters, digits, dots, underscores or hyphens')
+  }
+  if (!globalThis.isSecureContext || !globalThis.Worker || !globalThis.navigator?.storage?.getDirectory || !globalThis.navigator?.locks) {
+    throw new BrowserError('STORAGE_UNSUPPORTED', 'RedDB Browser requires HTTPS, module Workers, OPFS and Web Locks')
+  }
+  const client = createClient(worker)
+  try { await client.ready; await client.call('open', { name }) }
+  catch (error) { client.shutdown(error); throw error }
+  const { call } = client
+  return {
+    ...runtimeMethods(client),
+    generation: () => call('generation'),
+    readWal: () => call('readWal'),
+    readSnapshot: () => call('readSnapshot'),
+    append: (payloads) => call('append', { payloads }),
+    checkpoint: (snapshot, minWalBytes = 0) => call('checkpoint', { snapshot, minWalBytes }),
+    close: client.closeFile,
+  }
+}

package/src/protocol.js

@@ -0,0 +1,10 @@
+export const RUNTIME_ABI_VERSION = 1
+export const VALUE_ENCODING = 'reddb-json-v1'
+
+export class BrowserError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = 'BrowserError'
+    this.code = code
+  }
+}

package/src/wasm/reddb_wasm.d.ts

@@ -0,0 +1,89 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Canonical `.rdb` artifact I/O. The worker owns and closes the underlying
+ * exclusive access handle; freeing this wrapper never unlocks it early.
+ */
+export class BrowserArtifact {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    append(payloads: Array<any>): void;
+    checkpoint(snapshot: Uint8Array, min_wal_bytes: number): void;
+    static create(handle: any, name: string, created_at_unix_ms: number): BrowserArtifact;
+    /**
+     * String-valued counters preserve all u64 bits across JavaScript.
+     */
+    generation(): string;
+    static open(handle: any, name: string): BrowserArtifact;
+    readSnapshot(): Uint8Array | undefined;
+    readWal(): Array<any>;
+}
+
+/**
+ * Experimental storage-free execution, using the native scalar evaluator.
+ */
+export function executeScalar(sql: string): any;
+
+/**
+ * Contract shared by the JS worker and foreign-language browser adapters.
+ */
+export function runtimeInfo(): any;
+
+export function validateQuery(sql: string): void;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_browserartifact_free: (a: number, b: number) => void;
+    readonly browserartifact_append: (a: number, b: any) => [number, number];
+    readonly browserartifact_checkpoint: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly browserartifact_create: (a: any, b: number, c: number, d: number) => [number, number, number];
+    readonly browserartifact_generation: (a: number) => [number, number, number, number];
+    readonly browserartifact_open: (a: any, b: number, c: number) => [number, number, number];
+    readonly browserartifact_readSnapshot: (a: number) => [number, number, number, number];
+    readonly browserartifact_readWal: (a: number) => [number, number, number];
+    readonly executeScalar: (a: number, b: number) => [number, number, number];
+    readonly runtimeInfo: () => [number, number, number];
+    readonly validateQuery: (a: number, b: number) => [number, number];
+    readonly rust_zstd_wasm_shim_calloc: (a: number, b: number) => number;
+    readonly rust_zstd_wasm_shim_free: (a: number) => void;
+    readonly rust_zstd_wasm_shim_malloc: (a: number) => number;
+    readonly rust_zstd_wasm_shim_memcmp: (a: number, b: number, c: number) => number;
+    readonly rust_zstd_wasm_shim_memcpy: (a: number, b: number, c: number) => number;
+    readonly rust_zstd_wasm_shim_memmove: (a: number, b: number, c: number) => number;
+    readonly rust_zstd_wasm_shim_memset: (a: number, b: number, c: number) => number;
+    readonly rust_zstd_wasm_shim_qsort: (a: number, b: number, c: number, d: number) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;