@dreamlake/dreamdb 0.2.1 → 0.3.1

package/dreamdb.d.ts

@@ -41,6 +41,63 @@ export class Space {
      * `{ 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 }]`
@@ -85,6 +142,22 @@ export class Space {
     readonly manifestHash: 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;
+
 /**
  * Encode arbitrary bytes as lowercase RFC-4648 base32 (no padding).
  *

package/dreamdb.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./dreamdb_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    S3Backend, Space, bytesToBase32, decodeCbor, version, zeroSpatialKey
+    S3Backend, Space, __wasm_init, bytesToBase32, decodeCbor, version, zeroSpatialKey
 } from "./dreamdb_bg.js";

package/dreamdb_bg.js

@@ -129,6 +129,93 @@ export class Space {
             wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * 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.)
+     * @param {Float32Array} vector
+     * @param {any} opts
+     * @returns {Promise<Array<any>>}
+     */
+    queryHybrid(vector, opts) {
+        const ptr0 = passArrayF32ToWasm0(vector, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.space_queryHybrid(this.__wbg_ptr, ptr0, len0, opts);
+        return ret;
+    }
+    /**
+     * 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.
+     * @param {string} field
+     * @param {string} op
+     * @param {any} value
+     * @returns {Promise<Array<any>>}
+     */
+    queryScalar(field, op, value) {
+        const ptr0 = passStringToWasm0(field, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(op, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.space_queryScalar(this.__wbg_ptr, ptr0, len0, ptr1, len1, value);
+        return ret;
+    }
+    /**
+     * 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`.
+     * @param {string} field
+     * @param {string} query
+     * @param {number} top_k
+     * @returns {Promise<Array<any>>}
+     */
+    queryText(field, query, top_k) {
+        const ptr0 = passStringToWasm0(field, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.space_queryText(this.__wbg_ptr, ptr0, len0, ptr1, len1, top_k);
+        return ret;
+    }
     /**
      * Top-K cosine vector search over an embedding `field`. `opts` may be a
      * number (topK) or `{ topK?, probeCount? }`. Returns `[{ anchor, score }]`
@@ -216,6 +303,24 @@ export class Space {
 }
 if (Symbol.dispose) Space.prototype[Symbol.dispose] = Space.prototype.free;
 
+/**
+ * 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() {
+    wasm.__wasm_init();
+}
+
 /**
  * Encode arbitrary bytes as lowercase RFC-4648 base32 (no padding).
  *
@@ -293,6 +398,11 @@ export function __wbg_Error_bce6d499ff0a4aff(arg0, arg1) {
     const ret = Error(getStringFromWasm0(arg0, arg1));
     return ret;
 }
+export function __wbg___wbindgen_boolean_get_2304fb8c853028c8(arg0) {
+    const v = arg0;
+    const ret = typeof(v) === 'boolean' ? v : undefined;
+    return isLikeNone(ret) ? 0xFFFFFF : ret ? 1 : 0;
+}
 export function __wbg___wbindgen_debug_string_edece8177ad01481(arg0, arg1) {
     const ret = debugString(arg1);
     const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
@@ -340,6 +450,9 @@ export function __wbg_call_dfde26266607c996() { return handleError(function (arg
     const ret = arg0.call(arg1, arg2);
     return ret;
 }, arguments); }
+export function __wbg_error_f085d7e62279b703(arg0) {
+    console.error(arg0);
+}
 export function __wbg_get_dcf82ab8aad1a593() { return handleError(function (arg0, arg1) {
     const ret = Reflect.get(arg0, arg1);
     return ret;
@@ -348,6 +461,10 @@ export function __wbg_get_unchecked_1dfe6d05ad91d9b7(arg0, arg1) {
     const ret = arg0[arg1 >>> 0];
     return ret;
 }
+export function __wbg_headers_4cfb0c75793d7a8d(arg0) {
+    const ret = arg0.headers;
+    return ret;
+}
 export function __wbg_instanceof_Promise_09012cfa9708520a(arg0) {
     let result;
     try {
@@ -458,6 +575,9 @@ export function __wbg_set_a0e911be3da02782() { return handleError(function (arg0
     const ret = Reflect.set(arg0, arg1, arg2);
     return ret;
 }, arguments); }
+export function __wbg_set_d57e5106f0271787() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
+    arg0.set(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4));
+}, arguments); }
 export function __wbg_set_facb7a5914e0fa39(arg0, arg1, arg2) {
     const ret = arg0.set(arg1, arg2);
     return ret;
@@ -495,7 +615,7 @@ export function __wbg_then_bd927500e8905df2(arg0, arg1, arg2) {
     return ret;
 }
 export function __wbindgen_cast_0000000000000001(arg0, arg1) {
-    // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 275, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+    // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 392, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
     const ret = makeMutClosure(arg0, arg1, wasm_bindgen_f7c54996eb9137d9___convert__closures_____invoke___wasm_bindgen_f7c54996eb9137d9___JsValue__core_7d5f0a2ba6a62c33___result__Result_____wasm_bindgen_f7c54996eb9137d9___JsError___true_);
     return ret;
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@dreamlake/dreamdb",
   "type": "module",
   "description": "WebAssembly binding of dreamdb-dataset — the browser DreamDB SDK (@dreamlake/dreamdb)",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "license": "MIT OR Apache-2.0",
   "files": [
     "dreamdb_bg.wasm",