@rapidmx/web-client 0.3.1 → 0.5.0

package/apps/shared/search/searchTier2.ts

@@ -0,0 +1,79 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Tier 2 (`specs/search.md` §6) - the local encrypted index's public entry point, mirroring
+ * `@rapidmx/react-shared`'s `searchTier3.ts#searchEncryptedCandidates()` in shape: given a parsed query
+ * and this session's unlocked keys, return already-scored, already-sourced results plus how much of the
+ * mailbox the local index actually covers right now.
+ *
+ * Returns `{ results: [], coverage: undefined }` - never throws, never rejects - both when `unlocked` is
+ * absent (nothing is indexed without a master key to derive the index key from, the same "silently
+ * contributes nothing" degradation `searchTier3.ts`'s own doc comment describes for its identical case)
+ * and when anything about the local index itself fails (Worker/WASM/OPFS unsupported or unavailable in
+ * this browser, a corrupted index mid-rebuild, a query timeout). This tier's own storage engine is
+ * strictly best-effort infrastructure Tier 1 doesn't depend on - a caller `Promise.all()`-ing this
+ * alongside Tier 1/Tier 3 (`apps/www/index.tsx`'s own search orchestration) must never see the *whole
+ * search* fail just because this one, most novel piece had a bad moment.
+ */
+import type { UnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import type { ParsedSearchQuery } from "@rapidmx/react-shared/search/queryGrammar.js";
+import type { SearchResult } from "@rapidmx/react-shared/search/searchApi.js";
+import { deriveLocalIndexKey } from "./localIndexKey.js";
+import { getLocalCoverage, initLocalIndex, searchLocal } from "./localIndexRpcClient.js";
+import type { Coverage } from "./localIndexWorker.js";
+
+export interface Tier2SearchOutcome {
+    results: SearchResult[];
+    /** `undefined` when `unlocked` was absent - there's no local index to report coverage for at all in
+     * that case, distinct from a real, empty (just-built) index. */
+    coverage?: Coverage;
+    /** `true` when at least one more match exists beyond `results` - §8's composite pagination cursor's
+     * own per-tier continuation signal. Always `false` alongside the `unlocked`-absent/error
+     * degradations below - there is nothing more to page through either way. */
+    hasMore: boolean;
+}
+
+/** Ensures this mailbox's local index connection is open before it's queried - idempotent
+ * (`localIndexWorker.ts`'s own `init()` no-ops for an already-open mailbox), so callers never need to
+ * coordinate with `LocalIndexLifecycle.tsx`'s own unlock-triggered `init()` call; whichever runs first
+ * wins, and the other is a cheap no-op. */
+async function ensureInitialized(mailboxUid: string, unlocked: UnlockedKeys): Promise<void> {
+    const indexKey = await deriveLocalIndexKey(unlocked.masterKey, mailboxUid);
+    await initLocalIndex({ mailboxUid, indexKey });
+}
+
+export async function searchLocalIndex(
+    mailboxUid: string,
+    parsed: ParsedSearchQuery,
+    unlocked: UnlockedKeys | undefined,
+    limit = 50,
+    offset = 0,
+): Promise<Tier2SearchOutcome> {
+    if (!unlocked) {
+        return { results: [], hasMore: false };
+    }
+    try {
+        await ensureInitialized(mailboxUid, unlocked);
+        const [page, coverage] = await Promise.all([searchLocal(mailboxUid, parsed, limit, offset), getLocalCoverage(mailboxUid)]);
+        const results: SearchResult[] = page.hits.map((hit) => ({
+            entityType: "message",
+            entityUid: hit.entityUid,
+            // Negated: bm25()'s own convention is "more negative is a better match" (SQLite), the
+            // opposite of every other score this codebase merges (Postgres ts_rank, OpenSearch _score,
+            // and normalizeServerScores() itself all treat "higher is better"). Negating here, once,
+            // keeps that convention uniform for the caller (apps/www/index.tsx's merge layer) - it never
+            // needs to know this tier's underlying scoring function works backwards from the others.
+            score: -hit.score,
+            snippet: hit.snippet,
+            source: "local",
+            metadataOnly: false,
+        }));
+        return { results, coverage, hasMore: page.hasMore };
+    } catch {
+        // See this function's own doc comment - a broken local index degrades to "nothing to contribute
+        // this time," never a rejected search.
+        return { results: [], hasMore: false };
+    }
+}

package/apps/shared/search/wa-sqlite-shims.d.ts

@@ -0,0 +1,44 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * `@journeyapps/wa-sqlite` ships real `.d.ts` files for its top-level module and most `src/examples/*`
+ * VFS implementations, but not for `src/FacadeVFS.js` (the base class for hand-written VFS
+ * implementations) or `src/examples/AccessHandlePoolVFS.js` (the OPFS SAH Pool VFS this codebase's
+ * `EncryptingVFS` wraps) - both used directly by `localIndexVFS.ts`. Declared here, minimally, covering
+ * only the members this codebase actually calls.
+ */
+declare module "@journeyapps/wa-sqlite/src/FacadeVFS.js" {
+    import * as VFS from "@journeyapps/wa-sqlite/src/VFS.js";
+
+    /** Convenience base class for a JavaScript VFS - see the real source's own doc comment. Subclasses
+     * override the `jXxx` methods (JS-friendly wrappers) rather than the raw `xXxx` C-callback methods. */
+    export class FacadeVFS extends VFS.Base {
+        constructor(name: string, module: unknown);
+        hasAsyncMethod(methodName: string): boolean;
+        getFilename(pFile: number): string;
+        jOpen(filename: string | null, pFile: number, flags: number, pOutFlags: DataView): number | Promise<number>;
+        jDelete(filename: string, syncDir: number): number | Promise<number>;
+        jAccess(filename: string, flags: number, pResOut: DataView): number | Promise<number>;
+        jFullPathname(filename: string, zOut: Uint8Array): number | Promise<number>;
+        jClose(pFile: number): number | Promise<number>;
+        jRead(pFile: number, pData: Uint8Array, iOffset: number): number | Promise<number>;
+        jWrite(pFile: number, pData: Uint8Array, iOffset: number): number | Promise<number>;
+        jTruncate(pFile: number, size: number): number | Promise<number>;
+        jSync(pFile: number, flags: number): number | Promise<number>;
+        jFileSize(pFile: number, pSize64: DataView): number | Promise<number>;
+        jSectorSize(pFile: number): number;
+        jDeviceCharacteristics(pFile: number): number;
+    }
+}
+
+declare module "@journeyapps/wa-sqlite/src/examples/AccessHandlePoolVFS.js" {
+    import { FacadeVFS } from "@journeyapps/wa-sqlite/src/FacadeVFS.js";
+
+    /** The OPFS "SAH Pool" VFS - synchronous, works with the plain (non-Asyncify) SQLite WASM build.
+     * `create()` is the intended entry point (constructs, then awaits internal readiness). */
+    export class AccessHandlePoolVFS extends FacadeVFS {
+        static create(name: string, module: unknown): Promise<AccessHandlePoolVFS>;
+    }
+}