@freqhole/reliquary 0.0.0

package/dist/utils/log.js

@@ -0,0 +1,100 @@
+// lightweight logger with level + tag filtering.
+// level order: trace < debug < info < warn < error
+//
+// configuration precedence (highest wins):
+//   1. localStorage overrides (browser devtools, no rebuild needed):
+//        localStorage.logLevel = "trace";
+//        localStorage.logFilter = "automerge.repo,idb.docindex";
+//        location.reload();
+//   2. configureLogging({ level, filter }) - call this once at app startup.
+//      this is the hook a consuming app uses to wire up its own build-time env
+//      vars (e.g. `configureLogging({ level: import.meta.env.VITE_LOG_LEVEL })`
+//      in a vite app) without this package hard-depending on any bundler's env
+//      injection.
+//   3. default: "warn", no tag filter.
+//
+// trace is off by default even when a lower level is configured - enable it
+// explicitly when needed. it's useful for detailed call-by-call tracing of
+// services without adding noise to normal debug output.
+//
+// tags use dotted namespaces, e.g. "p2p.transfer", "audio.player", "idb.service".
+// filter prefix matching: "p2p" matches "p2p", "p2p.transfer", "p2p.knock", etc.
+//
+// usage:
+//   import { log } from "@freqhole/reliquary/utils";
+//   log.warn("share.panel", "could not build share link:", err);
+//   log.debug("playlist.sync", "syncPlaylists #", syncId, "entries:", entries.length);
+//   log.trace("automerge.repo", "findPlaylistDoc call #", n, docId);
+const LEVEL_NUM = {
+    trace: -1,
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+const DEFAULT_LEVEL = "warn";
+let configuredLevel;
+let configuredFilter;
+/**
+ * set the default log level and/or tag filter. intended to be called once at
+ * app startup; localStorage overrides (if present) still take priority so
+ * logging can be adjusted at runtime without a rebuild.
+ */
+export function configureLogging(config) {
+    if (config.level !== undefined)
+        configuredLevel = config.level;
+    if (config.filter !== undefined)
+        configuredFilter = config.filter;
+}
+/** clear any configureLogging() overrides, restoring the built-in default. */
+export function resetLoggingConfig() {
+    configuredLevel = undefined;
+    configuredFilter = undefined;
+}
+function readLocalStorage(key) {
+    return typeof localStorage !== "undefined" && typeof localStorage.getItem === "function"
+        ? localStorage.getItem(key)
+        : null;
+}
+function resolveLevel() {
+    const override = readLocalStorage("logLevel");
+    const raw = override ?? configuredLevel ?? DEFAULT_LEVEL;
+    return LEVEL_NUM[raw] ?? LEVEL_NUM.warn;
+}
+function resolveFilter() {
+    const override = readLocalStorage("logFilter");
+    if (override !== null) {
+        return override
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    }
+    return configuredFilter ?? [];
+}
+function allowed(tag) {
+    const filter = resolveFilter();
+    if (filter.length === 0)
+        return true;
+    return filter.some((prefix) => tag === prefix || tag.startsWith(prefix + "."));
+}
+function emit(level, tag, msg, ...args) {
+    if (LEVEL_NUM[level] < resolveLevel())
+        return;
+    if (!allowed(tag))
+        return;
+    const prefix = `[${tag}]`;
+    if (level === "error")
+        console.error(prefix, msg, ...args);
+    else if (level === "warn")
+        console.warn(prefix, msg, ...args);
+    // eslint-disable-next-line no-console -- this IS the logger implementation
+    else
+        console.log(prefix, msg, ...args);
+}
+export const log = {
+    trace: (tag, msg, ...args) => emit("trace", tag, msg, ...args),
+    debug: (tag, msg, ...args) => emit("debug", tag, msg, ...args),
+    info: (tag, msg, ...args) => emit("info", tag, msg, ...args),
+    warn: (tag, msg, ...args) => emit("warn", tag, msg, ...args),
+    error: (tag, msg, ...args) => emit("error", tag, msg, ...args),
+};

package/dist/utils/log.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=log.test.d.ts.map

package/dist/utils/log.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.test.d.ts","sourceRoot":"","sources":["../../src/utils/log.test.ts"],"names":[],"mappings":""}

package/dist/utils/log.test.js

@@ -0,0 +1,113 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureLogging, log, resetLoggingConfig } from "./log.js";
+// minimal in-memory localStorage stand-in so these tests don't depend on a DOM
+// environment; log.ts only touches localStorage.getItem.
+class FakeLocalStorage {
+    store = new Map();
+    getItem(key) {
+        return this.store.get(key) ?? null;
+    }
+    setItem(key, value) {
+        this.store.set(key, value);
+    }
+    removeItem(key) {
+        this.store.delete(key);
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+describe("log", () => {
+    let consoleLog;
+    let consoleWarn;
+    let consoleError;
+    beforeEach(() => {
+        consoleLog = vi.spyOn(console, "log").mockImplementation(() => { });
+        consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        consoleError = vi.spyOn(console, "error").mockImplementation(() => { });
+    });
+    afterEach(() => {
+        resetLoggingConfig();
+        vi.unstubAllGlobals();
+        consoleLog.mockRestore();
+        consoleWarn.mockRestore();
+        consoleError.mockRestore();
+    });
+    it("defaults to the warn level: debug/info/trace are suppressed, warn/error are not", () => {
+        log.trace("app", "trace msg");
+        log.debug("app", "debug msg");
+        log.info("app", "info msg");
+        log.warn("app", "warn msg");
+        log.error("app", "error msg");
+        expect(consoleLog).not.toHaveBeenCalled();
+        expect(consoleWarn).toHaveBeenCalledTimes(1);
+        expect(consoleError).toHaveBeenCalledTimes(1);
+    });
+    it("configureLogging lowers the level so debug/info start emitting", () => {
+        configureLogging({ level: "debug" });
+        log.trace("app", "trace msg");
+        log.debug("app", "debug msg");
+        log.info("app", "info msg");
+        expect(consoleLog).toHaveBeenCalledTimes(2); // debug + info, both route through console.log
+    });
+    it("trace stays off even when the configured level is debug", () => {
+        configureLogging({ level: "debug" });
+        log.trace("app", "trace msg");
+        expect(consoleLog).not.toHaveBeenCalled();
+    });
+    it("trace only emits when explicitly configured", () => {
+        configureLogging({ level: "trace" });
+        log.trace("app", "trace msg");
+        expect(consoleLog).toHaveBeenCalledTimes(1);
+    });
+    it("resetLoggingConfig restores the default level", () => {
+        configureLogging({ level: "trace" });
+        resetLoggingConfig();
+        log.debug("app", "debug msg");
+        expect(consoleLog).not.toHaveBeenCalled();
+    });
+    it("configureLogging's filter allows only matching tag prefixes", () => {
+        configureLogging({ level: "debug", filter: ["p2p"] });
+        log.debug("p2p.transfer", "in filter");
+        log.debug("audio.player", "not in filter");
+        expect(consoleLog).toHaveBeenCalledTimes(1);
+        expect(consoleLog).toHaveBeenCalledWith("[p2p.transfer]", "in filter");
+    });
+    it("an empty filter (or none configured) allows every tag", () => {
+        configureLogging({ level: "debug" });
+        log.debug("anything.goes", "msg");
+        expect(consoleLog).toHaveBeenCalledTimes(1);
+    });
+    it("prefixes emitted messages with [tag]", () => {
+        log.error("share.panel", "could not build link", { reason: "boom" });
+        expect(consoleError).toHaveBeenCalledWith("[share.panel]", "could not build link", {
+            reason: "boom",
+        });
+    });
+    describe("localStorage overrides", () => {
+        beforeEach(() => {
+            vi.stubGlobal("localStorage", new FakeLocalStorage());
+        });
+        it("localStorage.logLevel overrides configureLogging's level", () => {
+            configureLogging({ level: "warn" });
+            localStorage.setItem("logLevel", "debug");
+            log.debug("app", "debug msg");
+            expect(consoleLog).toHaveBeenCalledTimes(1);
+        });
+        it("localStorage.logFilter overrides configureLogging's filter", () => {
+            configureLogging({ level: "debug", filter: ["p2p"] });
+            localStorage.setItem("logFilter", "audio");
+            log.debug("audio.player", "now allowed");
+            log.debug("p2p.transfer", "no longer allowed");
+            expect(consoleLog).toHaveBeenCalledTimes(1);
+            expect(consoleLog).toHaveBeenCalledWith("[audio.player]", "now allowed");
+        });
+        it("an empty localStorage.logFilter value means no filter (allow every tag)", () => {
+            configureLogging({ level: "debug", filter: ["p2p"] });
+            localStorage.setItem("logFilter", "");
+            log.debug("p2p.transfer", "allowed");
+            log.debug("audio.player", "also allowed, since an explicit empty override clears the filter");
+            expect(consoleLog).toHaveBeenCalledTimes(2);
+        });
+    });
+});

package/dist/worker/blob-worker-client.d.ts

@@ -0,0 +1,118 @@
+import * as Comlink from "comlink";
+import type { BlobWorkerApi } from "./blob-worker.js";
+/**
+ * get (and lazily spawn) the comlink-wrapped blob worker proxy.
+ *
+ * returns null if Worker isn't available, or if the worker doesn't signal
+ * readiness within `WORKER_READY_TIMEOUT_MS` - callers should branch and use
+ * a main-thread fallback (every exported helper below already does this).
+ *
+ * waits for an explicit "ready" postMessage from the worker before handing
+ * out the Comlink proxy. this avoids a real race: the worker's module top
+ * level may await a wasm module's instantiation before calling
+ * `Comlink.expose()` (which registers the "message" listener). an RPC call
+ * sent before that listener exists fires with no listener attached and is
+ * silently dropped forever - the caller's promise then never resolves.
+ * waiting for the ready signal (sent immediately after `Comlink.expose()`
+ * in blob-worker.ts) guarantees the listener is registered before any real
+ * RPC call goes out.
+ */
+export declare function getBlobWorker(): Promise<Comlink.Remote<BlobWorkerApi> | null>;
+/**
+ * tear down the worker. mainly useful for tests; production code can leave
+ * the worker alive for the page lifetime.
+ */
+export declare function shutdownBlobWorker(): void;
+/**
+ * hash bytes with blake3, preferring the worker. accepts a Uint8Array.
+ * note: this DOES copy across the worker boundary (Uint8Array isn't
+ * transferable directly without giving up the underlying ArrayBuffer);
+ * for upload pipelines, prefer `processBlobBytes` which transfers the
+ * underlying buffer.
+ */
+export declare function hashBlake3(data: Uint8Array): Promise<string>;
+/**
+ * sha256 hash of an ArrayBuffer.
+ */
+export declare function hashSha256(data: ArrayBuffer): Promise<string>;
+/**
+ * base64-encode an ArrayBuffer.
+ *
+ * NOTE: the buffer is structured-cloned (copied) across the worker
+ * boundary so callers can safely reuse it afterwards. if you have a
+ * dedicated buffer that won't be touched again, you can transfer
+ * ownership manually for a small perf win.
+ */
+export declare function base64Encode(buffer: ArrayBuffer): Promise<string>;
+/**
+ * one-shot upload pipeline: hash + write to OPFS in the worker, return
+ * metadata. transfers the buffer.
+ */
+export declare function processBlobBytes(buffer: ArrayBuffer, filename: string, mime: string): Promise<{
+    blob_id: string;
+    sha256: string;
+    blake3: string;
+    size: number;
+    mime: string;
+    filename: string;
+}>;
+/**
+ * write a blob to OPFS via the worker (uses `FileSystemSyncAccessHandle`
+ * for max throughput).
+ *
+ * NOTE: the buffer is structured-cloned (copied) across the worker
+ * boundary so callers can safely reuse it afterwards - important for
+ * code paths that read or return the buffer after kicking off an OPFS
+ * write (e.g. a snatch/download cache-back-fill). for the upload pipeline
+ * use `processBlobBytes` instead, which transfers.
+ */
+export declare function writeBlobToOpfs(blobId: string, buffer: ArrayBuffer): Promise<void>;
+/**
+ * stream a File into OPFS via the worker's chunked upload session:
+ * incremental blake3 + incremental sync-access-handle writes, so neither
+ * thread ever holds the whole payload. each chunk buffer is transferred
+ * (zero-copy) across the worker boundary.
+ *
+ * `onProgress` reports bytes pushed / file size (0..1) per chunk.
+ * `signal` cancels between chunks: the worker session is aborted (temp
+ * file cleaned up) and a DOMException AbortError is thrown.
+ *
+ * returns { blake3, size } - the file lands in OPFS under its blake3
+ * content address. throws when streaming isn't available (no worker, no
+ * OPFS sync handles, no midden module bundled); callers should fall back
+ * to the one-shot processBlobBytes path.
+ */
+export declare function streamFileToOpfs(file: File, options?: {
+    onProgress?: (fraction: number) => void;
+    signal?: AbortSignal;
+}): Promise<{
+    blake3: string;
+    size: number;
+}>;
+export interface ResizeImageOptions {
+    maxWidth?: number;
+    maxHeight?: number;
+    quality?: number;
+    cropSquare?: boolean;
+    mime?: string;
+}
+/**
+ * resize an image Blob to a (default WebP) data URL.
+ * prefers the blob worker (keeps the decode/encode work off the main
+ * thread); falls back to a main-thread `OffscreenCanvas` path if the
+ * worker isn't available. returns null on failure (non-image input,
+ * decode failure, etc.).
+ */
+export declare function resizeImageToWebpDataUrl(blob: Blob, options?: ResizeImageOptions): Promise<string | null>;
+/**
+ * generate a thumbnail data URL (default 200x200 WebP @ q=0.75) for an
+ * image Blob. delegates to the worker.
+ */
+export declare function generateThumbnailDataUrl(blob: Blob, maxSize?: number): Promise<string | null>;
+/**
+ * decode a base64 string into a Uint8Array via the worker. for large
+ * payloads (megabyte-scale snatch responses) this avoids blocking the
+ * main thread on a tight `String.charCodeAt` loop.
+ */
+export declare function base64Decode(b64: string): Promise<Uint8Array>;
+//# sourceMappingURL=blob-worker-client.d.ts.map

package/dist/worker/blob-worker-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-worker-client.d.ts","sourceRoot":"","sources":["../../src/worker/blob-worker-client.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AACnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAsBtD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,CAuDnF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAOzC;AAiCD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAIlE;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAInE;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAIvE;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IACT,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAeD;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAQxF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAC1E,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAkC3C;AAID,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,SAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOhG;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAQnE"}