@dreamlake/dreamdb 0.3.0 → 0.4.0

package/browser/dreamdb_bg.wasm.d.ts

@@ -0,0 +1,56 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const __wbg_s3backend_free: (a: number, b: number) => void;
+export const __wbg_space_free: (a: number, b: number) => void;
+export const __wbg_writer_free: (a: number, b: number) => void;
+export const addressRoundTrip: (a: number, b: number) => [number, number, number, number];
+export const addressVariant: (a: number, b: number) => [number, number, number, number];
+export const bytesToBase32: (a: number, b: number) => [number, number];
+export const decodeCbor: (a: number, b: number) => [number, number, number];
+export const encodeCbor: (a: any) => [number, number, number, number];
+export const modalityParse: (a: number, b: number) => [number, number, number];
+export const multihashBase32: (a: number, b: number) => [number, number];
+export const multihashHex: (a: number, b: number) => [number, number];
+export const rangeHeader: (a: bigint, b: bigint) => [number, number, number, number];
+export const s3backend_get: (a: number, b: number, c: number, d: any) => any;
+export const s3backend_list: (a: number, b: number, c: number) => any;
+export const s3backend_new: (a: number, b: number) => number;
+export const space_connectorBase: (a: number) => [number, number];
+export const space_fromUri: (a: number, b: number, c: any) => any;
+export const space_history: (a: number, b: number) => any;
+export const space_manifestHash: (a: number) => [number, number];
+export const space_queryHybrid: (a: number, b: number, c: number, d: any) => any;
+export const space_queryScalar: (a: number, b: number, c: number, d: number, e: number, f: any) => any;
+export const space_queryText: (a: number, b: number, c: number, d: number, e: number, f: number) => any;
+export const space_queryVector: (a: number, b: number, c: number, d: number, e: number, f: any) => any;
+export const space_readScalarColumn: (a: number, b: any, c: any) => any;
+export const space_resolveObjectIndex: (a: number, b: any) => any;
+export const space_timelineId: (a: number) => [number, number, number, number];
+export const space_trackFor: (a: number, b: number, c: number) => any;
+export const space_tracks: (a: number) => any;
+export const spatialKeyRoundTrip: (a: number, b: number) => [number, number, number, number];
+export const timeAnchorFromHex: (a: number, b: number) => [bigint, number, number];
+export const timeAnchorHex: (a: bigint) => [number, number];
+export const timeBucket: (a: bigint, b: number, c: number) => [bigint, number, number];
+export const version: () => [number, number];
+export const writer_appendMany: (a: number, b: any) => any;
+export const writer_commit: (a: number) => any;
+export const writer_deleteRecords: (a: number, b: number, c: number, d: number, e: number) => any;
+export const writer_manifestHash: (a: number) => [number, number, number, number];
+export const writer_open: (a: number, b: number, c: any) => any;
+export const writer_refName: (a: number) => [number, number];
+export const writer_snapshot: (a: number, b: number, c: number) => any;
+export const zeroSpatialKey: () => [number, number];
+export const __wasm_init: () => void;
+export const wasm_bindgen_f7c54996eb9137d9___convert__closures_____invoke___wasm_bindgen_f7c54996eb9137d9___JsValue__core_7d5f0a2ba6a62c33___result__Result_____wasm_bindgen_f7c54996eb9137d9___JsError___true_: (a: number, b: number, c: any) => [number, number];
+export const wasm_bindgen_f7c54996eb9137d9___convert__closures_____invoke___js_sys_ac40961855821e8e___Function_fn_wasm_bindgen_f7c54996eb9137d9___JsValue_____wasm_bindgen_f7c54996eb9137d9___sys__Undefined___js_sys_ac40961855821e8e___Function_fn_wasm_bindgen_f7c54996eb9137d9___JsValue_____wasm_bindgen_f7c54996eb9137d9___sys__Undefined_______true_: (a: number, b: number, c: any, d: any) => void;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_exn_store: (a: number) => void;
+export const __externref_table_alloc: () => number;
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __wbindgen_destroy_closure: (a: number, b: number) => void;
+export const __externref_table_dealloc: (a: number) => void;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __wbindgen_start: () => void;

package/browser-extras.mjs

@@ -0,0 +1,193 @@
+// Browser-side additions to the wasm bindings.
+//
+// These live in JS rather than Rust on purpose: they are pure IO plus a
+// user-supplied callback, and the crate itself says so (`connector.rs` keeps
+// URL minting on the JS side). Nothing here touches the protocol, so nothing
+// here can drift from it.
+//
+// Loaded only by the `browser` and `web` entry points. Node does not want a
+// presigned-URL backend — on a server you hand the SDK real credentials via an
+// S3 client, and minting a URL for yourself just adds a round trip.
+
+/** Zero spatial-key path segment for non-spatial (fragment) object addresses. */
+export const ZERO_SPATIAL_KEY = '0000000000000000'
+
+/**
+ * Stand-in for the authoring surface, which the browser build does not carry.
+ *
+ * The type declarations describe `Authoring` on both ends so that a codebase
+ * shared between server and client type-checks once. Rather than let the
+ * browser fail with `undefined is not a constructor`, every entry point is a
+ * function that says what is missing and where to run it.
+ */
+class AuthoringUnavailable {
+  static #nope(what) {
+    throw new Error(
+      `Authoring.${what} is not available in the browser build of ` +
+        `@dreamlake/dreamdb. Dataset creation, layers, merge and compaction ` +
+        `pull in the index builders (IVF/IMI/LSH/Vamana + codebook training), ` +
+        `which cost ~123 KB gzipped and need training data that does not ` +
+        `belong in a tab. Run it under Node — the "node" export condition ` +
+        `resolves to the full build — or use the CLI.`,
+    )
+  }
+  static async create() { AuthoringUnavailable.#nope('create') }
+  static async open() { AuthoringUnavailable.#nope('open') }
+}
+
+export { AuthoringUnavailable as Authoring }
+
+/**
+ * A Backend (contract v2) that gets bytes over plain `fetch` and writes through
+ * short-lived presigned URLs minted by *your* server.
+ *
+ * Credentials never reach the browser. That was the explicit constraint, and it
+ * is also the only version of browser writes that is safe to ship: a bucket
+ * key in client JS is a bucket key in everyone's DevTools.
+ *
+ * ## What you must provide
+ *
+ * ```js
+ * new PresignedBackend({
+ *   readBase: 'https://bucket.s3.amazonaws.com',   // public/CDN read path
+ *   mintPut: async (paths, opts) => {
+ *     // paths: string[]  → return { [path]: { url, headers? } }
+ *     // opts.ifMatch:    caller wants a conditional PUT (ref updates only)
+ *     const r = await fetch('/api/dreamdb/sign', {
+ *       method: 'POST',
+ *       headers: { 'content-type': 'application/json' },
+ *       body: JSON.stringify({ paths, ifMatch: opts?.ifMatch }),
+ *     })
+ *     if (!r.ok) throw new Error(`sign failed: ${r.status}`)
+ *     return (await r.json()).urls
+ *   },
+ * })
+ * ```
+ *
+ * `mintPut` takes an **array** of paths. One commit writes buckets, tracks, a
+ * manifest and a ref; signing them one at a time turns a commit into N server
+ * round trips. The backend batches where it can, and signs alone only when a
+ * write needs its own conditional header.
+ *
+ * ## Two things that will bite you if the bucket is misconfigured
+ *
+ * 1. **`ExposeHeaders: ["ETag"]` in the bucket's CORS rule is mandatory.**
+ *    Without it the browser can see the response but not its ETag header, so
+ *    the SDK has no prior version to compare against, falls back to a
+ *    create-only PUT, and the *second* commit to any ref fails while the first
+ *    succeeded. That asymmetry is what makes it hard to spot.
+ * 2. **Whether `If-Match` survives presigning is provider-specific.** SigV4
+ *    signs whatever headers you tell it to, so a presigned conditional PUT is
+ *    constructible — but it is not something the docs promise, and GCS uses
+ *    `x-goog-if-generation-match` instead. Hence `refStrategy` below.
+ */
+export class PresignedBackend {
+  /**
+   * @param {object} o
+   * @param {string} o.readBase                 Base URL for reads.
+   * @param {(paths: string[], opts?: {ifMatch?: string}) => Promise<Record<string, {url: string, headers?: Record<string,string>}>>} o.mintPut
+   * @param {(path: string, opts: {ifMatch?: string, ifNoneMatchStar?: boolean}, bytes: Uint8Array) => Promise<{status: string, etag?: string}>} [o.commitRef]
+   *        Server-side ref commit. Used when `refStrategy` is `'proxy'`.
+   * @param {'proxy'|'presign'} [o.refStrategy='proxy']
+   *        How the 33-byte ref object is written. `'proxy'` posts it to your
+   *        server, which performs the conditional PUT with real credentials —
+   *        works identically on S3, R2, MinIO and GCS. `'presign'` signs a
+   *        conditional PUT and sends it from the browser; fewer moving parts,
+   *        but it depends on provider behaviour this SDK cannot promise.
+   * @param {(path: string) => string} [o.readUrl] Override read URL building.
+   */
+  constructor({ readBase, mintPut, commitRef, refStrategy = 'proxy', readUrl }) {
+    if (!readBase) throw new Error('PresignedBackend: readBase is required')
+    if (typeof mintPut !== 'function') {
+      throw new Error('PresignedBackend: mintPut(paths, opts) is required')
+    }
+    if (refStrategy === 'proxy' && typeof commitRef !== 'function') {
+      throw new Error(
+        "PresignedBackend: refStrategy 'proxy' (the default) needs commitRef(). " +
+          "Pass refStrategy: 'presign' to sign conditional ref PUTs instead — " +
+          'but read the note on provider support first.',
+      )
+    }
+    this.readBase = readBase.replace(/\/+$/, '')
+    this.mintPut = mintPut
+    this.commitRef = commitRef
+    this.refStrategy = refStrategy
+    this._readUrl = readUrl
+  }
+
+  #url(path) {
+    return this._readUrl ? this._readUrl(path) : `${this.readBase}/${path}`
+  }
+
+  /** v2 get: returns `{bytes, etag}`. Range is inclusive of `end`. */
+  async get(path, range) {
+    const headers = {}
+    if (range) headers.range = `bytes=${range.start}-${range.end}`
+    const r = await fetch(this.#url(path), { headers })
+    if (!r.ok) throw new Error(`GET ${path}: ${r.status} ${r.statusText}`)
+    return {
+      bytes: new Uint8Array(await r.arrayBuffer()),
+      etag: normalizeEtag(r.headers.get('etag')),
+    }
+  }
+
+  async head(path) {
+    const r = await fetch(this.#url(path), { method: 'HEAD' })
+    if (r.status === 404) return { exists: false }
+    if (!r.ok) throw new Error(`HEAD ${path}: ${r.status}`)
+    const len = r.headers.get('content-length')
+    return {
+      exists: true,
+      etag: normalizeEtag(r.headers.get('etag')),
+      size: len == null ? undefined : Number(len),
+    }
+  }
+
+  async put(path, bytes, opts = {}) {
+    // Ref updates are the only conditional writes, and they are the ones whose
+    // semantics differ per provider — so they get their own path.
+    const isRef = path.startsWith('refs/')
+    if (isRef && this.refStrategy === 'proxy') {
+      return await this.commitRef(path, opts, bytes)
+    }
+
+    const minted = await this.mintPut([path], opts.ifMatch ? { ifMatch: opts.ifMatch } : undefined)
+    const spec = minted?.[path]
+    if (!spec?.url) throw new Error(`mintPut returned no URL for ${path}`)
+
+    const headers = { ...(spec.headers || {}) }
+    if (opts.ifMatch) headers['if-match'] = opts.ifMatch
+    else if (opts.ifNoneMatchStar) headers['if-none-match'] = '*'
+
+    const r = await fetch(spec.url, { method: 'PUT', body: bytes, headers })
+
+    // 412 is genuinely ambiguous and the SDK cannot disambiguate it from the
+    // status alone: for `If-None-Match: *` on a content-addressed object it
+    // means "already there", which is success; for `If-Match` on a ref it means
+    // someone else moved it, which is a conflict the caller must resolve.
+    if (r.status === 412 || r.status === 409) {
+      return opts.ifNoneMatchStar
+        ? { status: 'exists' }
+        : { status: 'casFailed', etag: normalizeEtag(r.headers.get('etag')) }
+    }
+    if (!r.ok) throw new Error(`PUT ${path}: ${r.status} ${r.statusText}`)
+    return { status: 'created', etag: normalizeEtag(r.headers.get('etag')) }
+  }
+
+  // No `delete`. It would need a signed DELETE URL, and the sign endpoint only
+  // ever signs PUT — handing out object deletion to a browser is not something
+  // this write channel should make easy. Nothing in the browser write surface
+  // needs it either: `deleteRecords` writes tombstones (new objects), and
+  // dropping a ref is an `Authoring` operation, which is Node-only.
+}
+
+/**
+ * S3 quotes ETags and sometimes suffixes them (`W/"…"`, `"…-3"` for multipart).
+ * The conditional-write comparison is byte-exact, so a stray quote turns every
+ * CAS into a mismatch — which reads as "someone else is writing" forever.
+ */
+function normalizeEtag(v) {
+  if (!v) return undefined
+  const t = v.trim().replace(/^W\//, '').replace(/^"|"$/g, '')
+  return t || undefined
+}

package/browser.mjs

@@ -0,0 +1,4 @@
+// Bundler entry (Vite, webpack, Next, Rollup). The wasm is imported as a
+// module and instantiated by the bundler; there is nothing to await.
+export * from './browser/dreamdb.js'
+export { ZERO_SPATIAL_KEY, PresignedBackend, Authoring } from './browser-extras.mjs'