@dikolab/kbdb 0.1.1 → 0.1.3

package/src/shared/dir-resolver/index.ts

@@ -4,4 +4,8 @@ export {
 } from './functions/resolve-base-dir.function.ts';
 export { resolveWorkerScript } from './functions/resolve-worker-script.function.ts';
 export { resolveWasmDir } from './functions/resolve-wasm-dir.function.ts';
+export {
+   isRemoteUrl,
+   joinPath,
+} from './functions/join-path.function.ts';
 export type { BaseDir } from './typings/base-dir.interface.ts';

package/src/shared/version/constants/version.constant.ts

@@ -1,2 +1,2 @@
 /** Current package version, kept in sync with package.json. */
-export const VERSION = '0.1.0';
+export const VERSION = '0.1.3';

package/src/shared/worker-daemon/functions/load-wasm-modules.function.ts

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+
 import type { DaemonConfig } from '../typings/daemon-config.interface.ts';
 import type { WasmModules } from '../typings/wasm-modules.interface.ts';
 import { createHostImports } from './create-host-imports.function.ts';
@@ -7,23 +7,8 @@ import type {
    AllocatorRef,
    MemoryRef,
 } from './create-host-imports.function.ts';
+import { isRemoteUrl, joinPath } from '../../dir-resolver/index.ts';
 
-/**
- * Loads and instantiates the `kb-worker` WASM module.
- *
- * `kb-worker.wasm` statically links the `fs-database` and
- * `query-parser` crates, so only one module needs to be
- * instantiated.  The module exports its own linear memory;
- * host I/O imports read it through a deferred `MemoryRef`
- * that is wired up immediately after instantiation.
- *
- * @param config - daemon configuration, used to supply the context
- *   path to the host I/O imports
- * @param wasmDir - absolute path to the directory containing the
- *   compiled WASM subdirectories (`query-parser/`, `fs-database/`,
- *   `kb-worker/`)
- * @throws when the WASM file cannot be read or instantiated
- */
 export async function loadWasmModules(
    config: DaemonConfig,
    wasmDir: string,
@@ -38,8 +23,8 @@ export async function loadWasmModules(
       allocator,
    );
 
-   const wkPath = join(wasmDir, 'kb-worker', 'kbdb_worker_bg.wasm');
-   const wkBytes = readWasmFileOrThrow(wkPath, 'kb-worker');
+   const wkPath = joinPath(wasmDir, 'kb-worker', 'kbdb_worker_bg.wasm');
+   const wkBytes = await readWasmFile(wkPath, 'kb-worker');
 
    let wkModule: WebAssembly.Module;
    try {
@@ -71,8 +56,20 @@ export async function loadWasmModules(
    return { memory, kbWorker };
 }
 
-function readWasmFileOrThrow(path: string, label: string): ArrayBuffer {
+async function readWasmFile(
+   path: string,
+   label: string,
+): Promise<ArrayBuffer> {
    try {
+      if (isRemoteUrl(path)) {
+         const response = await fetch(path);
+         if (!response.ok) {
+            throw new Error(
+               `HTTP ${String(response.status)} ${response.statusText}`,
+            );
+         }
+         return await response.arrayBuffer();
+      }
       const buf = readFileSync(path);
       return buf.buffer.slice(
          buf.byteOffset,

package/src/wasm/fs-database/kbdb_fs_database.d.ts

@@ -0,0 +1,220 @@
+declare namespace wasm_bindgen {
+    /* tslint:disable */
+    /* eslint-disable */
+
+    /**
+     * Adds a section. `ptr`/`len` point to an encoded `AddSectionParams`.
+     *
+     * On success: writes encoded kbid string to return slot, returns 0.
+     * On error: writes error message to return slot, returns -1.
+     */
+    export function db_add_section(ptr: number, len: number): number;
+
+    /**
+     * Adds a section's terms to the inverted and positional indexes.
+     * `ptr`/`len` point to encoded
+     * (kbid_str, term_count, [(term_str, pos_count, [positions], heading_tf, body_tf, code_tf)]).
+     */
+    export function db_add_to_index(ptr: number, len: number): number;
+
+    /**
+     * Checks database integrity. Returns 0 on success.
+     * On success a summary string is placed in the return slot.
+     */
+    export function db_check_integrity(_ptr: number, _len: number): number;
+
+    /**
+     * Reads `catalog.toml` from the path at `ptr`/`len` and returns the version
+     * status without modifying state.
+     *
+     * On success, the return slot contains 8 bytes:
+     * - bytes 0-3: `catalog_version` as little-endian u32
+     * - bytes 4-7: `required_version` (DB_FORMAT_VERSION) as little-endian u32
+     *
+     * Return value:
+     * - 0: compatible (versions match)
+     * - 1: needs migration (catalog version < required)
+     * - 2: too new (catalog version > required)
+     * - -1: I/O or parse error (message in return slot)
+     *
+     * Note: this export accepts a path directly and does NOT require `db_init`
+     * to have been called first.
+     */
+    export function db_check_version(ptr: number, len: number): number;
+
+    /**
+     * Runs garbage collection. Returns 0 on success.
+     * On success a summary string is placed in the return slot.
+     */
+    export function db_gc(_ptr: number, _len: number): number;
+
+    /**
+     * Initialises the database context path.
+     *
+     * The JS host must call this before any other function.
+     * `ptr`/`len` point to a UTF-8 context path string in WASM memory.
+     */
+    export function db_init(ptr: number, len: number): number;
+
+    /**
+     * Initialises a new empty catalog at the current context path.
+     * Writes the default catalog to disk and returns 0 on success.
+     */
+    export function db_init_catalog(_ptr: number, _len: number): number;
+
+    /**
+     * Creates the full directory scaffold for a new database at `ptr`/`len` path.
+     *
+     * Creates directories, seeds `catalog.toml` (stamped with `DB_FORMAT_VERSION`),
+     * empty index files, `worker.toml`, and `.gitignore`.
+     *
+     * Returns 0 on success. Returns -1 with an error message in the return slot
+     * if the directory already exists or any I/O fails.
+     *
+     * Note: this export accepts a path directly and does NOT require `db_init`
+     * to have been called first.
+     */
+    export function db_init_directory(ptr: number, len: number): number;
+
+    /**
+     * Lists all document manifests. No input parameters (`ptr`/`len` are ignored).
+     *
+     * On success encodes a `u32 count` followed by each `DocumentManifest` into
+     * the return slot and returns 0. On error writes an error message and returns -1.
+     */
+    export function db_list_documents(_ptr: number, _len: number): number;
+
+    /**
+     * Lists all section records. No input parameters (`ptr`/`len` are ignored).
+     *
+     * On success encodes a `u32 count` followed by each `SectionRecord` into the
+     * return slot and returns 0. On error writes an error message and returns -1.
+     */
+    export function db_list_sections(_ptr: number, _len: number): number;
+
+    /**
+     * Executes a query plan against the loaded indexes.
+     * `ptr`/`len` point to an encoded `QueryPlan`.
+     * On success writes encoded `Vec<RawMatch>` to the return slot.
+     */
+    export function db_query(ptr: number, len: number): number;
+
+    /**
+     * Reads the catalog. Returns 0 on success.
+     * On success the serialised catalog TOML text is in the return slot.
+     */
+    export function db_read_catalog(_ptr: number, _len: number): number;
+
+    /**
+     * Reads corpus statistics from `<ctx>/corpus.bin`.
+     * On success places encoded `CorpusStats` bytes in the return slot.
+     */
+    export function db_read_corpus_stats(_ptr: number, _len: number): number;
+
+    /**
+     * Reads a document manifest. `ptr`/`len` point to a UTF-8 docid string.
+     */
+    export function db_read_document(ptr: number, len: number): number;
+
+    /**
+     * Reads a section by kbid. `ptr`/`len` point to a UTF-8 kbid string.
+     */
+    export function db_read_section(ptr: number, len: number): number;
+
+    /**
+     * Reads multiple sections. `ptr`/`len` point to encoded `Vec<KbId>` (count + kbids).
+     */
+    export function db_read_sections(ptr: number, len: number): number;
+
+    /**
+     * Rebuilds indexes from scratch.
+     *
+     * Clears the existing inverted and positional indexes, then drives the
+     * section-scan rebuild loop. Full per-field tokenization is handled by
+     * `kb-worker.wasm` orchestration; this function provides the read-pass
+     * scaffolding and the final index write.
+     */
+    export function db_rebuild_index(_ptr: number, _len: number): number;
+
+    /**
+     * Removes a document manifest. `ptr`/`len` point to a UTF-8 docid string.
+     */
+    export function db_remove_document(ptr: number, len: number): number;
+
+    /**
+     * Removes a section's entries from the indexes.
+     * `ptr`/`len` point to a UTF-8 kbid string.
+     */
+    export function db_remove_from_index(ptr: number, len: number): number;
+
+    /**
+     * Removes a section by kbid. `ptr`/`len` point to a UTF-8 kbid string.
+     */
+    export function db_remove_section(ptr: number, len: number): number;
+
+    /**
+     * Updates a section. `ptr`/`len` point to encoded (old_kbid_str, AddSectionParams).
+     */
+    export function db_update_section(ptr: number, len: number): number;
+
+    /**
+     * Writes/updates the catalog. `ptr`/`len` point to encoded catalog TOML text.
+     */
+    export function db_write_catalog(ptr: number, len: number): number;
+
+    /**
+     * Writes corpus statistics to `<ctx>/corpus.bin`.
+     * `ptr`/`len` point to 12 bytes of encoded `CorpusStats`.
+     */
+    export function db_write_corpus_stats(ptr: number, len: number): number;
+
+    /**
+     * Writes a document manifest. `ptr`/`len` point to an encoded `DocumentManifest`.
+     */
+    export function db_write_document(ptr: number, len: number): number;
+
+}
+declare type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+declare interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly set_return: (a: number, b: number) => void;
+    readonly kbdb_free: (a: number, b: number) => void;
+    readonly db_add_section: (a: number, b: number) => number;
+    readonly db_add_to_index: (a: number, b: number) => number;
+    readonly db_check_integrity: (a: number, b: number) => number;
+    readonly db_check_version: (a: number, b: number) => number;
+    readonly db_gc: (a: number, b: number) => number;
+    readonly db_init: (a: number, b: number) => number;
+    readonly db_init_catalog: (a: number, b: number) => number;
+    readonly db_init_directory: (a: number, b: number) => number;
+    readonly db_list_documents: (a: number, b: number) => number;
+    readonly db_list_sections: (a: number, b: number) => number;
+    readonly db_query: (a: number, b: number) => number;
+    readonly db_read_catalog: (a: number, b: number) => number;
+    readonly db_read_corpus_stats: (a: number, b: number) => number;
+    readonly db_read_document: (a: number, b: number) => number;
+    readonly db_read_section: (a: number, b: number) => number;
+    readonly db_read_sections: (a: number, b: number) => number;
+    readonly db_rebuild_index: (a: number, b: number) => number;
+    readonly db_remove_document: (a: number, b: number) => number;
+    readonly db_remove_from_index: (a: number, b: number) => number;
+    readonly db_remove_section: (a: number, b: number) => number;
+    readonly db_update_section: (a: number, b: number) => number;
+    readonly db_write_catalog: (a: number, b: number) => number;
+    readonly db_write_corpus_stats: (a: number, b: number) => number;
+    readonly db_write_document: (a: number, b: number) => number;
+    readonly kbdb_alloc: (a: number) => number;
+    readonly get_return_len: () => number;
+    readonly get_return_ptr: () => number;
+}
+
+/**
+ * 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>}
+ */
+declare function wasm_bindgen (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;