@dreamlake/dreamdb 0.3.0 → 0.4.0

package/web/dreamdb.d.ts

@@ -0,0 +1,407 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * A `fetch`-backed backend rooted at a base URL.
+ */
+export class S3Backend {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Fetch `path` (relative to the base URL) and resolve to its bytes.
+     * `opts.noCache` is accepted for API compatibility (currently a no-op:
+     * content is hash-addressed; refs are read fresh each page load anyway).
+     */
+    get(path: string, _opts: any): Promise<Uint8Array>;
+    /**
+     * List object paths under `prefix`. Stub (returns empty); the current
+     * consumer read paths don't require listing.
+     */
+    list(_prefix: string): Promise<Array<any>>;
+    /**
+     * Construct rooted at `base_url` (trailing slash trimmed).
+     */
+    constructor(base_url: string);
+}
+
+export class Space {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Open a Space from a `.../refs/<name>` or `.../manifests/<hash>` URI,
+     * resolving the ref (if any) and loading the manifest. If `backend` is
+     * provided it handles IO (relative paths); otherwise a direct-fetch
+     * connector rooted at the parsed base URL is used (the `dreamdb-demo`
+     * no-backend path).
+     */
+    static fromUri(uri: string, backend: any): Promise<Space>;
+    /**
+     * Walk the manifest DAG from HEAD, up to `max_depth` entries. Each entry:
+     * `{ manifestHash, ts, writer, tracks: [{modality, address}] }`.
+     */
+    history(max_depth?: number | null): Promise<Array<any>>;
+    /**
+     * Hybrid search fusing a lexical (BM25) sub-query and a dense (vector)
+     * sub-query per spec/0015 §5/§6. Returns the fused `[{ anchor, score }]`
+     * list sorted by fused score descending — the same scored shape as
+     * `queryVector`.
+     *
+     * `vector` is the dense sub-query embedding (a `Float32Array`). `opts` is a
+     * plain JS object:
+     * ```js
+     * {
+     *   textField, textQuery,        // BM25 sub-query (required)
+     *   vectorField,                 // dense field the `vector` targets (required)
+     *   topK = 10,                   // fused results to return
+     *   fusion = 'rrf',              // 'rrf' | 'linear' | 'max' | 'pareto'
+     *   rrfK = 60,                   // RRF rank constant (fusion='rrf')
+     *   textWeight = 1, vectorWeight = 1, // Linear weights (fusion='linear')
+     *   textK = topK, vectorK = topK,     // per-sub-query candidate depths
+     *   textRequired = false, vectorRequired = false, // §5.3 boolean-AND gates
+     * }
+     * ```
+     *
+     * Delegates to the real (tested) `dreamdb-dataset::Dataset::query_hybrid`.
+     * (v0 does not expose the optional scalar pre/post-filter; it runs with no
+     * scalar gate.)
+     */
+    queryHybrid(vector: Float32Array, opts: any): Promise<Array<any>>;
+    /**
+     * Scalar-index lookup: every anchor whose `field` satisfies `op value`
+     * (spec/0011). Returns a `BigUint64Array`-style `Array` of anchors,
+     * tombstone-suppressed, sorted ascending and deduped.
+     *
+     * This is the expansion half of a compact lexical index. A BM25 index
+     * built over a scalar field's DISTINCT values returns one representative
+     * anchor per matched value; resolving that value back to *every* record
+     * carrying it is a scalar-index lookup, not a text-index concern. Keeping
+     * the split this way is what lets the text index stay small enough to
+     * load in a browser — indexing one document per record instead produced a
+     * 406 MB object for ~1,700 distinct strings.
+     *
+     * `op` is one of `==`, `!=`, `<`, `<=`, `>`, `>=`. `value` may be a
+     * string, number, or boolean; strings match both `String` and
+     * `Categorical` scalar fields.
+     */
+    queryScalar(field: string, op: string, value: any): Promise<Array<any>>;
+    /**
+     * Lexical BM25 text search over a text `field` (spec/0015 §3.6).
+     *
+     * Tokenizes `query` with the built-in `dreamdb.utf8-words` tokenizer
+     * (lowercase + split on non-alphanumeric — pure Rust, compiled into the
+     * wasm; no external model needed even though the field's embeddings were
+     * produced elsewhere), scores docs with BM25, and suppresses tombstoned
+     * anchors. Returns `[{ anchor, score }]` sorted by score descending — the
+     * same scored shape as `queryVector`.
+     *
+     * Delegates to the real (tested) `dreamdb-dataset::Dataset::query_text`.
+     */
+    queryText(field: string, query: string, top_k: number): Promise<Array<any>>;
+    /**
+     * Top-K cosine vector search over an embedding `field`. `opts` may be a
+     * number (topK) or `{ topK?, probeCount? }`. Returns `[{ anchor, score }]`
+     * sorted by score descending — the shape dreamdb-ts's `queryVector` yields.
+     *
+     * Delegates to the real (tested) `dreamdb-dataset` query path: ADC cull +
+     * two-pass rerank + HotShard merge + tombstone suppression.
+     */
+    queryVector(field: string, query: Float32Array, opts: any): Promise<Array<any>>;
+    /**
+     * Read a scalar track as a `Map<anchorString, value>`. Single-anchor
+     * entries resolve from the track index; multi-anchor entries fetch (and
+     * de-dupe) their bucket and roaring-decode the anchor set.
+     */
+    readScalarColumn(track: any, _opts: any): Promise<Map<any, any>>;
+    /**
+     * Fetch a track object and return its `object_index` (array of CBOR
+     * entries). Inline indexes only — paged indexes are not resolved (matching
+     * dreamdb-ts, which also doesn't support them on this path).
+     */
+    resolveObjectIndex(track: any): Promise<Array<any>>;
+    /**
+     * Base32 hash of the manifest's first timeline.
+     */
+    timelineId(): string;
+    /**
+     * Find a track by its resolved `key` or by `modality`.
+     */
+    trackFor(key_or_modality: string): any;
+    /**
+     * List resolved tracks from this manifest.
+     */
+    tracks(): Array<any>;
+    /**
+     * The base URL objects are fetched relative to (consumers build their own
+     * object URLs from this — e.g. `dreamdb-demo`'s track readers).
+     */
+    readonly connectorBase: string;
+    /**
+     * The manifest's base32 multihash.
+     */
+    readonly manifestHash: string;
+}
+
+/**
+ * A write handle onto a ref.
+ */
+export class Writer {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Append records and commit in one call.
+     *
+     * `samples` is an array of `{ anchor?: bigint|number, <field>: value }`.
+     * See `marshal::samples_from_js` for the accepted field shapes.
+     *
+     * Committing here rather than exposing a separate staged mode is
+     * deliberate for the browser surface: a staged write that is never
+     * committed leaves uploaded objects unreferenced, and a tab can close at
+     * any moment. `appendStaged` exists on the Node surface where the process
+     * lifetime is under the caller's control.
+     */
+    appendMany(samples: Array<any>): Promise<number>;
+    /**
+     * Flush staged entries and publish a new manifest.
+     *
+     * Fails with a CAS conflict if the ref moved underneath this writer. That
+     * is not retried automatically: an automatic retry would hide a logical
+     * conflict, and the caller is the only one who knows whether re-applying
+     * its records on top of the new head is correct.
+     */
+    commit(): Promise<string>;
+    /**
+     * Tombstone records by anchor. Returns the new manifest hash.
+     */
+    deleteRecords(anchors: BigUint64Array, reason?: string | null): Promise<string>;
+    /**
+     * Open a ref for writing.
+     *
+     * `uri` is the same `.../refs/<name>` form `Space.fromUri` takes; a
+     * `.../manifests/<hash>` URI is rejected rather than silently opening
+     * something unwritable, because a manifest hash names an immutable
+     * snapshot — there is nothing for a commit to advance.
+     *
+     * `backend` must implement `put` (Backend contract v2). Passing a
+     * read-only backend fails at the first write with a clear message rather
+     * than here, since the connector cannot know what the JS object omits
+     * until it calls it.
+     */
+    static open(uri: string, backend: any): Promise<Writer>;
+    /**
+     * Tag the current manifest with an immutable label (`refs/<ref>@<label>`).
+     */
+    snapshot(label: string): Promise<string>;
+    /**
+     * Current manifest hash, base32.
+     */
+    readonly manifestHash: string;
+    /**
+     * The ref this writer advances.
+     */
+    readonly refName: string;
+}
+
+/**
+ * Install a panic hook that logs the panic message AND its `file:line:col`
+ * to the console before the wasm trap surfaces to JS.
+ *
+ * Without this, every Rust panic reaches JavaScript as a bare
+ * `RuntimeError: unreachable` with nothing but wasm frame offsets — and it is
+ * indistinguishable from an allocation failure, since Rust's alloc-error
+ * handler also aborts. That ambiguity cost real debugging time: a browser
+ * `unreachable` from exhausting wasm32's 32-bit address space on an oversized
+ * index was initially read as an integer-overflow panic.
+ *
+ * Zero new deps — uses the already-enabled `web-sys` `console` feature.
+ * Runs once at module init.
+ */
+export function __wasm_init(): void;
+
+/**
+ * Parse an object path and re-format it. Byte-identity of the result is the
+ * actual assertion: a parser that silently drops a component still "parses".
+ */
+export function addressRoundTrip(path: string): string;
+
+/**
+ * The address variant name (`Genesis`, `Manifest`, `Ref`, …) for a path.
+ *
+ * Derived from the Debug representation rather than a hand-written match.
+ * `DreamDbAddress` has seventeen variants and gains one whenever the protocol
+ * does; a match arm per variant would be a second list to keep in sync, and
+ * the vectors only ever assert the name.
+ */
+export function addressVariant(path: string): string;
+
+/**
+ * Encode arbitrary bytes as lowercase RFC-4648 base32 (no padding).
+ *
+ * Byte-identical to `dreamdb-ts`'s `bytesToBase32` (alphabet
+ * `abcdefghijklmnopqrstuvwxyz234567`) and to `dreamdb_core`'s multihash
+ * `to_base32`, which is how object addresses are spelled on disk.
+ */
+export function bytesToBase32(bytes: Uint8Array): string;
+
+/**
+ * Decode a single CBOR value from `bytes` into its JS representation.
+ */
+export function decodeCbor(bytes: Uint8Array): any;
+
+/**
+ * Canonically encode a JS value as CBOR, returning the bytes.
+ *
+ * Canonical here means what spec/0002 §3.1 means: map keys sorted by their
+ * encoded bytes, shortest-form integers, no indefinite lengths. Two writers
+ * that disagree on this produce different content hashes for the same logical
+ * object, and every address derived from them diverges.
+ */
+export function encodeCbor(value: any): Uint8Array;
+
+/**
+ * Parse a modality tag into `{class, encoding, trackKind, objectKind, params,
+ * flags}`, or throw if it is invalid.
+ *
+ * `params` is a plain object of the `key=value` segments and `flags` an array
+ * of the bare ones (`bucketed`, `graph`). They are separate because the
+ * grammar treats them differently and merging them would make a flag
+ * indistinguishable from a parameter whose value happened to be empty.
+ */
+export function modalityParse(tag: string): any;
+
+/**
+ * BLAKE3-256 multihash of `bytes`, base32 (the form used in object paths).
+ */
+export function multihashBase32(bytes: Uint8Array): string;
+
+/**
+ * BLAKE3-256 multihash of `bytes` as lowercase hex (33 bytes: tag + digest).
+ */
+export function multihashHex(bytes: Uint8Array): string;
+
+/**
+ * DreamDB's half-open `[start, end)` → an HTTP `Range` header value.
+ *
+ * The off-by-one here is worth a vector of its own: HTTP ranges are
+ * *inclusive* of the end byte. Getting it wrong reads one byte too few from
+ * every object, which corrupts decode in ways that look like anything but an
+ * off-by-one.
+ */
+export function rangeHeader(start: bigint, end: bigint): string;
+
+/**
+ * Round-trip a spatial key through its base-2 form, per spec/0002 §6.
+ *
+ * Returns the re-encoded string, so a caller can assert byte-identity rather
+ * than merely "it parsed".
+ */
+export function spatialKeyRoundTrip(bits: string): string;
+
+/**
+ * The 16-char hex address form → TimeAnchor. Throws on a malformed input
+ * (wrong length, uppercase) rather than coercing it.
+ */
+export function timeAnchorFromHex(s: string): bigint;
+
+/**
+ * TimeAnchor → the 16-char hex used in addresses.
+ */
+export function timeAnchorHex(value: bigint): string;
+
+/**
+ * Which time bucket an anchor falls in, given a duration like `"1s"`/`"60s"`.
+ */
+export function timeBucket(t_start: bigint, duration: string): bigint;
+
+/**
+ * Package version — useful for consumers to confirm which build is loaded.
+ */
+export function version(): string;
+
+/**
+ * The all-zero spatial-key path segment used for non-spatial (fragment) object
+ * addresses. Matches `dreamdb-ts`'s `ZERO_SPATIAL_KEY` constant exactly.
+ */
+export function zeroSpatialKey(): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_s3backend_free: (a: number, b: number) => void;
+    readonly __wbg_space_free: (a: number, b: number) => void;
+    readonly __wbg_writer_free: (a: number, b: number) => void;
+    readonly addressRoundTrip: (a: number, b: number) => [number, number, number, number];
+    readonly addressVariant: (a: number, b: number) => [number, number, number, number];
+    readonly bytesToBase32: (a: number, b: number) => [number, number];
+    readonly decodeCbor: (a: number, b: number) => [number, number, number];
+    readonly encodeCbor: (a: any) => [number, number, number, number];
+    readonly modalityParse: (a: number, b: number) => [number, number, number];
+    readonly multihashBase32: (a: number, b: number) => [number, number];
+    readonly multihashHex: (a: number, b: number) => [number, number];
+    readonly rangeHeader: (a: bigint, b: bigint) => [number, number, number, number];
+    readonly s3backend_get: (a: number, b: number, c: number, d: any) => any;
+    readonly s3backend_list: (a: number, b: number, c: number) => any;
+    readonly s3backend_new: (a: number, b: number) => number;
+    readonly space_connectorBase: (a: number) => [number, number];
+    readonly space_fromUri: (a: number, b: number, c: any) => any;
+    readonly space_history: (a: number, b: number) => any;
+    readonly space_manifestHash: (a: number) => [number, number];
+    readonly space_queryHybrid: (a: number, b: number, c: number, d: any) => any;
+    readonly space_queryScalar: (a: number, b: number, c: number, d: number, e: number, f: any) => any;
+    readonly space_queryText: (a: number, b: number, c: number, d: number, e: number, f: number) => any;
+    readonly space_queryVector: (a: number, b: number, c: number, d: number, e: number, f: any) => any;
+    readonly space_readScalarColumn: (a: number, b: any, c: any) => any;
+    readonly space_resolveObjectIndex: (a: number, b: any) => any;
+    readonly space_timelineId: (a: number) => [number, number, number, number];
+    readonly space_trackFor: (a: number, b: number, c: number) => any;
+    readonly space_tracks: (a: number) => any;
+    readonly spatialKeyRoundTrip: (a: number, b: number) => [number, number, number, number];
+    readonly timeAnchorFromHex: (a: number, b: number) => [bigint, number, number];
+    readonly timeAnchorHex: (a: bigint) => [number, number];
+    readonly timeBucket: (a: bigint, b: number, c: number) => [bigint, number, number];
+    readonly version: () => [number, number];
+    readonly writer_appendMany: (a: number, b: any) => any;
+    readonly writer_commit: (a: number) => any;
+    readonly writer_deleteRecords: (a: number, b: number, c: number, d: number, e: number) => any;
+    readonly writer_manifestHash: (a: number) => [number, number, number, number];
+    readonly writer_open: (a: number, b: number, c: any) => any;
+    readonly writer_refName: (a: number) => [number, number];
+    readonly writer_snapshot: (a: number, b: number, c: number) => any;
+    readonly zeroSpatialKey: () => [number, number];
+    readonly __wasm_init: () => void;
+    readonly 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];
+    readonly 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;
+    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 __wbindgen_destroy_closure: (a: number, b: number) => void;
+    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>;