@xnetjs/data-bridge 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Smothers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @xnetjs/data-bridge
+
+DataBridge abstractions for moving xNet data operations off the main thread.
+
+## Installation
+
+```bash
+pnpm add @xnetjs/data-bridge
+```
+
+## What It Provides
+
+- `MainThreadBridge` for direct NodeStore-backed access
+- `WorkerBridge` for Web Worker execution via Comlink
+- `createDataBridge()` factory with automatic bridge selection
+- Shared bridge types (`DataBridge`, `QueryOptions`, `DataBridgeConfig`)
+- Utilities for query caching, debouncing, and binary state transfer
+
+## Usage
+
+```ts
+import { createDataBridge } from '@xnetjs/data-bridge'
+
+const bridge = await createDataBridge({
+  nodeStore,
+  config: {
+    authorDID,
+    signingKey,
+    dbName: 'xnet'
+  },
+  workerUrl: new URL('@xnetjs/data-bridge/worker', import.meta.url),
+  mode: 'auto'
+})
+
+const subscription = bridge.query(TaskSchema, {
+  where: { status: 'todo' },
+  orderBy: { createdAt: 'desc' }
+})
+```
+
+## Exports
+
+- Types: `DataBridge`, `QueryOptions`, `DataBridgeConfig`, `AcquiredDoc`, `SyncStatus`
+- Implementations: `MainThreadBridge`, `WorkerBridge`, `NativeBridge`
+- Factories: `createDataBridge`, `createMainThreadBridgeSync`, `createWorkerBridgeSync`
+- Worker helpers: `isWorkerSupported`, `isNodeEnvironment`
+
+## Testing
+
+```bash
+pnpm --filter @xnetjs/data-bridge test
+```

package/dist/chunk-X6F5CPJI.js

@@ -0,0 +1,386 @@
+// src/query-cache.ts
+var DEFAULT_MAX_SIZE = 100;
+var MIN_AGE_FOR_EVICTION = 3e4;
+var WEAK_REF_CLEANUP_INTERVAL = 6e4;
+var QueryCache = class {
+  cache = /* @__PURE__ */ new Map();
+  maxSize;
+  cleanupInterval = null;
+  constructor(options) {
+    this.maxSize = options?.maxSize ?? DEFAULT_MAX_SIZE;
+    const enableCleanup = options?.enableWeakRefCleanup ?? typeof window !== "undefined";
+    if (enableCleanup) {
+      this.startWeakRefCleanup();
+    }
+  }
+  /**
+   * Start the interval that cleans up dead weak references.
+   */
+  startWeakRefCleanup() {
+    if (this.cleanupInterval) return;
+    this.cleanupInterval = setInterval(() => {
+      this.cleanupDeadWeakRefs();
+    }, WEAK_REF_CLEANUP_INTERVAL);
+    if (typeof this.cleanupInterval === "object" && "unref" in this.cleanupInterval) {
+      this.cleanupInterval.unref();
+    }
+  }
+  /**
+   * Stop the weak reference cleanup interval.
+   */
+  stopCleanup() {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+  }
+  /**
+   * Clean up dead weak references from all cache entries.
+   * Returns the number of dead references removed.
+   */
+  cleanupDeadWeakRefs() {
+    let removed = 0;
+    for (const entry of this.cache.values()) {
+      for (const [identity, ref] of entry.weakSubscribers) {
+        if (ref.deref() === void 0) {
+          entry.weakSubscribers.delete(identity);
+          removed++;
+        }
+      }
+    }
+    return removed;
+  }
+  /**
+   * Compute a stable query ID from schema and options.
+   * Same query params should produce the same ID for deduplication.
+   */
+  computeQueryId(schemaId, options) {
+    const parts = [schemaId];
+    if (options?.nodeId) {
+      parts.push(`id:${options.nodeId}`);
+    }
+    if (options?.where) {
+      const sortedWhere = Object.keys(options.where).sort().map((k) => `${k}:${JSON.stringify(options.where[k])}`).join(",");
+      parts.push(`where:{${sortedWhere}}`);
+    }
+    if (options?.includeDeleted) {
+      parts.push("deleted:true");
+    }
+    if (options?.orderBy) {
+      const sortedOrder = Object.entries(options.orderBy).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}:${v}`).join(",");
+      parts.push(`order:{${sortedOrder}}`);
+    }
+    if (options?.limit !== void 0) {
+      parts.push(`limit:${options.limit}`);
+    }
+    if (options?.offset !== void 0) {
+      parts.push(`offset:${options.offset}`);
+    }
+    return parts.join("|");
+  }
+  /**
+   * Get cached data for a query (synchronous for useSyncExternalStore).
+   * Updates lastAccessed for LRU tracking.
+   */
+  get(queryId) {
+    const entry = this.cache.get(queryId);
+    if (entry) {
+      entry.lastAccessed = Date.now();
+    }
+    return entry?.data ?? null;
+  }
+  /**
+   * Check if a query is in the cache.
+   */
+  has(queryId) {
+    return this.cache.has(queryId);
+  }
+  /**
+   * Set cached data for a query and notify subscribers.
+   * Triggers LRU eviction if cache exceeds maxSize.
+   */
+  set(queryId, data, schemaId, options) {
+    const entry = this.cache.get(queryId);
+    const now = Date.now();
+    if (entry) {
+      entry.data = data;
+      entry.lastUpdated = now;
+      entry.lastAccessed = now;
+      this.notifySubscribers(queryId);
+    } else {
+      this.evictIfNeeded();
+      this.cache.set(queryId, {
+        data,
+        subscribers: /* @__PURE__ */ new Set(),
+        weakSubscribers: /* @__PURE__ */ new Map(),
+        schemaId,
+        options,
+        lastUpdated: now,
+        lastAccessed: now
+      });
+    }
+  }
+  /**
+   * Initialize a cache entry (called when starting a subscription).
+   */
+  initEntry(queryId, schemaId, options) {
+    if (!this.cache.has(queryId)) {
+      const now = Date.now();
+      this.cache.set(queryId, {
+        data: null,
+        subscribers: /* @__PURE__ */ new Set(),
+        weakSubscribers: /* @__PURE__ */ new Map(),
+        schemaId,
+        options,
+        lastUpdated: 0,
+        lastAccessed: now
+      });
+    }
+  }
+  /**
+   * Subscribe to cache updates for a query.
+   * Uses strong references - callback will not be garbage collected until unsubscribed.
+   */
+  subscribe(queryId, callback) {
+    const entry = this.cache.get(queryId);
+    if (entry) {
+      entry.subscribers.add(callback);
+    }
+    return () => {
+      const e = this.cache.get(queryId);
+      if (e) {
+        e.subscribers.delete(callback);
+      }
+    };
+  }
+  /**
+   * Subscribe with a weak reference.
+   * The callback can be garbage collected if the owning component is unmounted
+   * and no other references to the callback exist.
+   *
+   * This is useful for long-lived subscriptions where you want automatic cleanup
+   * without explicit unsubscribe calls. However, for React components, prefer
+   * the regular subscribe() with proper cleanup in useEffect.
+   *
+   * @param queryId - The query to subscribe to
+   * @param callback - The callback to invoke on updates
+   * @returns Unsubscribe function
+   */
+  subscribeWeak(queryId, callback) {
+    const entry = this.cache.get(queryId);
+    if (entry) {
+      entry.weakSubscribers.set(callback, new WeakRef(callback));
+    }
+    return () => {
+      const e = this.cache.get(queryId);
+      if (e) {
+        e.weakSubscribers.delete(callback);
+      }
+    };
+  }
+  /**
+   * Notify all subscribers of a query that data has changed.
+   * Handles both strong and weak subscribers, cleaning up dead weak refs.
+   */
+  notifySubscribers(queryId) {
+    const entry = this.cache.get(queryId);
+    if (!entry) return;
+    for (const callback of entry.subscribers) {
+      callback();
+    }
+    for (const [identity, ref] of entry.weakSubscribers) {
+      const callback = ref.deref();
+      if (callback) {
+        callback();
+      } else {
+        entry.weakSubscribers.delete(identity);
+      }
+    }
+  }
+  /**
+   * Get the number of active subscribers for a query.
+   * Includes both strong and live weak subscribers.
+   */
+  getSubscriberCount(queryId) {
+    const entry = this.cache.get(queryId);
+    if (!entry) return 0;
+    let count = entry.subscribers.size;
+    for (const ref of entry.weakSubscribers.values()) {
+      if (ref.deref() !== void 0) {
+        count++;
+      }
+    }
+    return count;
+  }
+  /**
+   * Get the number of weak subscribers (including potentially dead ones).
+   * Useful for debugging.
+   */
+  getWeakSubscriberCount(queryId) {
+    return this.cache.get(queryId)?.weakSubscribers.size ?? 0;
+  }
+  /**
+   * Remove a query from the cache.
+   */
+  delete(queryId) {
+    this.cache.delete(queryId);
+  }
+  /**
+   * Get all query IDs that match a schema.
+   */
+  getQueriesForSchema(schemaId) {
+    const matches = [];
+    for (const [queryId, entry] of this.cache) {
+      if (entry.schemaId === schemaId) {
+        matches.push(queryId);
+      }
+    }
+    return matches;
+  }
+  /**
+   * Get the schema IRI for a cached query.
+   */
+  getSchemaId(queryId) {
+    return this.cache.get(queryId)?.schemaId;
+  }
+  /**
+   * Get the options for a cached query.
+   */
+  getOptions(queryId) {
+    return this.cache.get(queryId)?.options;
+  }
+  /**
+   * Clear the entire cache and stop cleanup interval.
+   */
+  clear() {
+    this.stopCleanup();
+    this.cache.clear();
+  }
+  /**
+   * Destroy the cache, stopping all cleanup intervals.
+   */
+  destroy() {
+    this.stopCleanup();
+    this.cache.clear();
+  }
+  /**
+   * Get the number of cached queries.
+   */
+  get size() {
+    return this.cache.size;
+  }
+  /**
+   * Get the maximum cache size.
+   */
+  get maxCacheSize() {
+    return this.maxSize;
+  }
+  // ─── LRU Eviction ──────────────────────────────────────────────────────────
+  /**
+   * Check if an entry has any active subscribers (strong or live weak).
+   */
+  hasActiveSubscribers(entry) {
+    if (entry.subscribers.size > 0) return true;
+    for (const ref of entry.weakSubscribers.values()) {
+      if (ref.deref() !== void 0) return true;
+    }
+    return false;
+  }
+  /**
+   * Evict least-recently-used entries if cache exceeds maxSize.
+   * Only evicts entries with no active subscribers and older than MIN_AGE_FOR_EVICTION.
+   */
+  evictIfNeeded() {
+    if (this.cache.size < this.maxSize) return;
+    const now = Date.now();
+    const candidates = [];
+    for (const [queryId, entry] of this.cache) {
+      if (!this.hasActiveSubscribers(entry) && now - entry.lastAccessed > MIN_AGE_FOR_EVICTION) {
+        candidates.push({ queryId, lastAccessed: entry.lastAccessed });
+      }
+    }
+    if (candidates.length === 0) return;
+    candidates.sort((a, b) => a.lastAccessed - b.lastAccessed);
+    const targetSize = Math.floor(this.maxSize * 0.8);
+    const toEvict = this.cache.size - targetSize;
+    for (let i = 0; i < Math.min(toEvict, candidates.length); i++) {
+      this.cache.delete(candidates[i].queryId);
+    }
+  }
+  /**
+   * Manually trigger eviction (for testing or explicit cleanup).
+   */
+  evict() {
+    const sizeBefore = this.cache.size;
+    this.evictIfNeeded();
+    return sizeBefore - this.cache.size;
+  }
+  // ─── Helpers for filtering and sorting ─────────────────────────────────────
+  /**
+   * Filter nodes based on query options.
+   */
+  filterNodes(nodes, options) {
+    if (!options) return nodes;
+    let result = nodes;
+    if (options.where) {
+      result = result.filter((node) => {
+        for (const [key, value] of Object.entries(options.where)) {
+          if (node.properties[key] !== value) {
+            return false;
+          }
+        }
+        return true;
+      });
+    }
+    if (!options.includeDeleted) {
+      result = result.filter((node) => !node.deleted);
+    }
+    return result;
+  }
+  /**
+   * Sort nodes based on query options.
+   */
+  sortNodes(nodes, options) {
+    if (!options?.orderBy) return nodes;
+    const entries = Object.entries(options.orderBy);
+    if (entries.length === 0) return nodes;
+    return [...nodes].sort((a, b) => {
+      for (const [key, direction] of entries) {
+        const keyStr = key;
+        let aVal;
+        let bVal;
+        if (keyStr === "createdAt" || keyStr === "updatedAt") {
+          aVal = a[keyStr];
+          bVal = b[keyStr];
+        } else {
+          aVal = a.properties[keyStr];
+          bVal = b.properties[keyStr];
+        }
+        if (aVal === bVal) continue;
+        if (aVal == null) return direction === "asc" ? 1 : -1;
+        if (bVal == null) return direction === "asc" ? -1 : 1;
+        const comparison = aVal < bVal ? -1 : 1;
+        return direction === "asc" ? comparison : -comparison;
+      }
+      return 0;
+    });
+  }
+  /**
+   * Apply pagination to nodes.
+   */
+  paginateNodes(nodes, options) {
+    if (!options) return nodes;
+    let result = nodes;
+    if (options.offset !== void 0 && options.offset > 0) {
+      result = result.slice(options.offset);
+    }
+    if (options.limit !== void 0 && options.limit > 0) {
+      result = result.slice(0, options.limit);
+    }
+    return result;
+  }
+};
+
+export {
+  QueryCache
+};