@xnetjs/data-bridge 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,1011 @@
+import * as _xnetjs_data from '@xnetjs/data';
+import { PropertyBuilder, DefinedSchema, InferCreateProps, NodeState, NodeChangeEvent, ListNodesOptions, NodeStore, SchemaIRI } from '@xnetjs/data';
+import { Awareness } from 'y-protocols/awareness';
+import { Doc } from 'yjs';
+
+/**
+ * Sort direction for ordering results
+ */
+type SortDirection = 'asc' | 'desc';
+/**
+ * System fields that can be used for ordering
+ */
+type SystemOrderField = 'createdAt' | 'updatedAt';
+/**
+ * Options for querying nodes via the DataBridge.
+ * Maps to the filter options used by useQuery.
+ */
+interface QueryOptions<P extends Record<string, PropertyBuilder> = Record<string, PropertyBuilder>> {
+    /** Filter by single node ID (makes this a single-node query) */
+    nodeId?: string;
+    /** Filter conditions (property: value) */
+    where?: Partial<InferCreateProps<P>>;
+    /** Include soft-deleted nodes */
+    includeDeleted?: boolean;
+    /** Sort by property or system field */
+    orderBy?: {
+        [K in keyof InferCreateProps<P> | SystemOrderField]?: SortDirection;
+    };
+    /** Limit results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * A subscription to a query result.
+ * Compatible with React's useSyncExternalStore pattern.
+ *
+ * @typeParam P - Property builder type (unused at runtime, for type inference)
+ */
+interface QuerySubscription<P extends Record<string, PropertyBuilder> = Record<string, PropertyBuilder>> {
+    /** Get current snapshot (synchronous - reads from cache). Returns null if loading. */
+    getSnapshot(): NodeState[] | null;
+    /** Subscribe to updates (React will call this) */
+    subscribe(callback: () => void): () => void;
+}
+/**
+ * Result of a create operation
+ */
+interface CreateResult {
+    node: NodeState;
+}
+/**
+ * Result of an update operation
+ */
+interface UpdateResult {
+    node: NodeState;
+}
+/**
+ * Result of acquiring a Y.Doc for editing.
+ * The doc is kept in sync with the data thread via the bridge.
+ */
+interface AcquiredDoc {
+    /** The Y.Doc instance (on main thread for TipTap binding) */
+    doc: Doc;
+    /** Awareness instance for presence/cursors */
+    awareness: Awareness;
+}
+/**
+ * Sync connection status
+ */
+type SyncStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
+/**
+ * Configuration for initializing a DataBridge
+ */
+interface DataBridgeConfig {
+    /** Database name for storage */
+    dbName?: string;
+    /** Author's DID for signing changes */
+    authorDID: string;
+    /** Ed25519 signing key */
+    signingKey: Uint8Array;
+    /** Signaling server URL for sync */
+    signalingUrl?: string;
+}
+/**
+ * The DataBridge interface abstracts data access across different platforms.
+ *
+ * Implementations:
+ * - MainThreadBridge: Direct NodeStore access (Phase 0, fallback)
+ * - WorkerBridge: Web Worker via Comlink (Phase 1)
+ * - IPCBridge: Electron utility process (Phase 2)
+ * - NativeBridge: React Native Turbo Module (Phase 5)
+ *
+ * All implementations provide the same API, allowing React hooks to work
+ * identically across all platforms.
+ */
+interface DataBridge {
+    /**
+     * Create a subscription to a query result.
+     * Returns an object compatible with useSyncExternalStore.
+     *
+     * The subscription loads data asynchronously and updates the cache.
+     * getSnapshot() returns null while loading, then the result array.
+     */
+    query<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, options?: QueryOptions<P>): QuerySubscription<P>;
+    /**
+     * Create a new node.
+     */
+    create<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, data: InferCreateProps<P>, id?: string): Promise<NodeState>;
+    /**
+     * Update an existing node.
+     */
+    update(nodeId: string, changes: Record<string, unknown>): Promise<NodeState>;
+    /**
+     * Soft-delete a node.
+     */
+    delete(nodeId: string): Promise<void>;
+    /**
+     * Restore a soft-deleted node.
+     */
+    restore(nodeId: string): Promise<NodeState>;
+    /**
+     * Acquire a Y.Doc for editing. Returns the doc with current state.
+     * The doc receives updates from the data thread via the bridge.
+     *
+     * Note: Phase 0 (MainThreadBridge) does not implement this method.
+     * It will be implemented in Phase 3 when Y.Doc split architecture is added.
+     */
+    acquireDoc?(nodeId: string): Promise<AcquiredDoc>;
+    /**
+     * Release a Y.Doc when no longer editing.
+     * The data thread continues syncing in the background.
+     *
+     * Note: Phase 0 (MainThreadBridge) does not implement this method.
+     */
+    releaseDoc?(nodeId: string): void;
+    /**
+     * Initialize the bridge with configuration.
+     * For MainThreadBridge, this is a no-op (already initialized with NodeStore).
+     */
+    initialize?(config: DataBridgeConfig): Promise<void>;
+    /**
+     * Clean up resources.
+     */
+    destroy(): void;
+    /**
+     * Current sync status.
+     */
+    readonly status: SyncStatus;
+    /**
+     * Subscribe to status changes.
+     */
+    on(event: 'status', handler: (status: SyncStatus) => void): () => void;
+    /**
+     * Get the underlying NodeStore directly.
+     * Only available in MainThreadBridge for backward compatibility.
+     * Will be removed in later phases.
+     */
+    readonly nodeStore?: _xnetjs_data.NodeStore;
+    /**
+     * Subscribe to store changes directly.
+     * Only available in MainThreadBridge for backward compatibility.
+     */
+    subscribeToChanges?(listener: (event: NodeChangeEvent) => void): () => void;
+    /**
+     * Get a single node by ID directly.
+     * Only available in MainThreadBridge for backward compatibility.
+     */
+    get?(nodeId: string): Promise<NodeState | null>;
+    /**
+     * List nodes with options directly.
+     * Only available in MainThreadBridge for backward compatibility.
+     */
+    list?(options?: ListNodesOptions): Promise<NodeState[]>;
+}
+
+/**
+ * Types for worker-main thread communication
+ *
+ * These types define the contract between the DataWorker running in a
+ * Web Worker and the WorkerBridge on the main thread.
+ */
+
+/**
+ * Result from acquiring a Y.Doc in the worker.
+ * The state is sent as a Uint8Array for efficient transfer.
+ */
+interface WorkerAcquiredDoc {
+    /** The node ID this doc belongs to */
+    nodeId: string;
+    /** Encoded Y.Doc state (Y.encodeStateAsUpdate) */
+    state: Uint8Array;
+    /** Client ID for this connection */
+    clientId: number;
+}
+/**
+ * Document update message from worker to main thread
+ */
+interface DocUpdateMessage {
+    type: 'doc-update';
+    nodeId: string;
+    /** Yjs update (Uint8Array) */
+    update: Uint8Array;
+    /** Origin of the update (e.g., 'remote', 'local') */
+    origin: string;
+}
+/**
+ * Configuration passed to the worker on initialization
+ */
+interface WorkerConfig {
+    /** Database name for IndexedDB */
+    dbName: string;
+    /** Author's DID for signing changes */
+    authorDID: string;
+    /** Ed25519 signing key (serialized as array for transfer) */
+    signingKey: number[];
+}
+/**
+ * Serialized query options (sent to worker)
+ */
+interface SerializedQueryOptions {
+    nodeId?: string;
+    where?: Record<string, unknown>;
+    includeDeleted?: boolean;
+    orderBy?: Record<string, 'asc' | 'desc'>;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Delta update types for incremental cache updates
+ */
+type QueryDelta$1 = {
+    type: 'add';
+    node: NodeState;
+    index: number;
+} | {
+    type: 'remove';
+    nodeId: string;
+} | {
+    type: 'update';
+    nodeId: string;
+    node: NodeState;
+};
+/**
+ * The API exposed by the DataWorker via Comlink.
+ * This is what WorkerBridge calls on the main thread.
+ */
+interface DataWorkerAPI {
+    /**
+     * Initialize the worker with configuration.
+     * Must be called before any other method.
+     */
+    initialize(config: WorkerConfig): Promise<void>;
+    /**
+     * Subscribe to a query. Returns initial results.
+     * Delta updates are sent via the callback.
+     */
+    subscribe(queryId: string, schemaId: string, options: SerializedQueryOptions, onDelta: (delta: QueryDelta$1) => void): Promise<NodeState[]>;
+    /**
+     * Unsubscribe from a query.
+     */
+    unsubscribe(queryId: string): Promise<void>;
+    /**
+     * Create a new node.
+     */
+    create(schemaId: string, data: Record<string, unknown>, id?: string): Promise<NodeState>;
+    /**
+     * Update an existing node.
+     */
+    update(nodeId: string, changes: Record<string, unknown>): Promise<NodeState>;
+    /**
+     * Delete a node (soft delete).
+     */
+    delete(nodeId: string): Promise<void>;
+    /**
+     * Restore a deleted node.
+     */
+    restore(nodeId: string): Promise<NodeState>;
+    /**
+     * Get a single node by ID.
+     */
+    get(nodeId: string): Promise<NodeState | null>;
+    /**
+     * Acquire a Y.Doc for editing.
+     * Returns the current state which should be applied to the main-thread mirror doc.
+     *
+     * @param nodeId - The node ID to acquire
+     * @param onUpdate - Callback for receiving updates from the worker (remote changes)
+     * @returns The initial doc state and client ID
+     */
+    acquireDoc(nodeId: string, onUpdate: (update: Uint8Array, origin: string) => void): Promise<WorkerAcquiredDoc>;
+    /**
+     * Release a Y.Doc when no longer editing.
+     * The doc stays in the pool for background sync.
+     */
+    releaseDoc(nodeId: string): void;
+    /**
+     * Apply a local update from the main-thread mirror doc to the worker's source-of-truth doc.
+     * The worker will broadcast this to the network.
+     *
+     * @param nodeId - The node ID
+     * @param update - The Yjs update (from Y.encodeStateAsUpdate or update event)
+     */
+    applyLocalUpdate(nodeId: string, update: Uint8Array): void;
+    /**
+     * Get current sync status.
+     */
+    getStatus(): SyncStatus;
+    /**
+     * Subscribe to status changes.
+     */
+    onStatusChange(handler: (status: SyncStatus) => void): void;
+    /**
+     * Clean up and close the worker.
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * MainThreadBridge - Direct NodeStore access implementation
+ *
+ * Phase 0 implementation that wraps NodeStore directly.
+ * Provides the DataBridge interface while keeping current behavior.
+ *
+ * This is the fallback implementation used when:
+ * - Web Workers are not available
+ * - During Phase 0 transition period
+ * - For testing/development
+ */
+
+/**
+ * Minimal SyncManager interface for Y.Doc acquisition.
+ * This avoids a direct dependency on @xnetjs/react's full SyncManager type.
+ */
+interface SyncManagerLike {
+    acquire(nodeId: string): Promise<Doc>;
+    release(nodeId: string): void;
+    getAwareness(nodeId: string): Awareness | null;
+}
+/**
+ * DataBridge implementation that accesses NodeStore directly on the main thread.
+ *
+ * This is the Phase 0 implementation that maintains current behavior while
+ * providing the DataBridge abstraction. Later phases will move operations
+ * off the main thread via Web Workers or IPC.
+ */
+declare class MainThreadBridge implements DataBridge {
+    private store;
+    private cache;
+    private statusListeners;
+    private storeUnsubscribe;
+    private _syncManager;
+    constructor(store: NodeStore);
+    /**
+     * Set the SyncManager for Y.Doc acquisition.
+     * This is called by XNetProvider after the SyncManager is created.
+     */
+    setSyncManager(syncManager: SyncManagerLike | null): void;
+    query<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, options?: QueryOptions<P>): QuerySubscription<P>;
+    /**
+     * Load query data from the store and update cache.
+     */
+    private loadQuery;
+    /**
+     * Handle store changes and invalidate affected caches.
+     */
+    private handleStoreChange;
+    create<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, data: InferCreateProps<P>, id?: string): Promise<NodeState>;
+    update(nodeId: string, changes: Record<string, unknown>): Promise<NodeState>;
+    delete(nodeId: string): Promise<void>;
+    restore(nodeId: string): Promise<NodeState>;
+    /**
+     * Acquire a Y.Doc for editing.
+     * Delegates to SyncManager if available, otherwise throws.
+     *
+     * @throws Error if SyncManager is not set
+     */
+    acquireDoc(nodeId: string): Promise<AcquiredDoc>;
+    /**
+     * Release a Y.Doc when no longer editing.
+     */
+    releaseDoc(nodeId: string): void;
+    destroy(): void;
+    get status(): SyncStatus;
+    on(event: 'status', handler: (status: SyncStatus) => void): () => void;
+    get nodeStore(): NodeStore;
+    subscribeToChanges(listener: (event: NodeChangeEvent) => void): () => void;
+    get(nodeId: string): Promise<NodeState | null>;
+    list(options?: ListNodesOptions): Promise<NodeState[]>;
+}
+/**
+ * Create a MainThreadBridge from a NodeStore.
+ */
+declare function createMainThreadBridge(store: NodeStore): MainThreadBridge;
+
+/**
+ * WorkerBridge - Main thread bridge to DataWorker
+ *
+ * This bridge runs on the main thread and communicates with the DataWorker
+ * running in a Web Worker via Comlink. It provides the same DataBridge
+ * interface as MainThreadBridge but offloads all heavy operations.
+ *
+ * Key features:
+ * - Type-safe RPC via Comlink
+ * - Query caching with delta updates
+ * - useSyncExternalStore-compatible subscriptions
+ */
+
+/**
+ * DataBridge implementation that communicates with a Web Worker.
+ *
+ * All heavy operations (storage, queries, crypto) run in the worker,
+ * keeping the main thread free for UI rendering.
+ */
+declare class WorkerBridge implements DataBridge {
+    private worker;
+    private remote;
+    private cache;
+    private subscriptions;
+    private queryCounter;
+    private statusListeners;
+    private _status;
+    private initialized;
+    private mirrorDocs;
+    constructor(workerUrl: string | URL);
+    /**
+     * Initialize the bridge and underlying worker.
+     */
+    initialize(config: DataBridgeConfig): Promise<void>;
+    query<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, options?: QueryOptions<P>): QuerySubscription<P>;
+    private startWorkerSubscription;
+    private applyDelta;
+    private serializeOptions;
+    create<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, data: InferCreateProps<P>, id?: string): Promise<NodeState>;
+    update(nodeId: string, changes: Record<string, unknown>): Promise<NodeState>;
+    delete(nodeId: string): Promise<void>;
+    restore(nodeId: string): Promise<NodeState>;
+    /**
+     * Acquire a Y.Doc for editing.
+     *
+     * Implements the split Y.Doc pattern:
+     * 1. Worker maintains "source of truth" Y.Doc (handles persistence & network sync)
+     * 2. Main thread gets a mirror Y.Doc for TipTap binding
+     * 3. Updates flow bidirectionally:
+     *    - Local edits → worker (for persistence & broadcast)
+     *    - Remote edits → main thread (for rendering)
+     */
+    acquireDoc(nodeId: string): Promise<AcquiredDoc>;
+    /**
+     * Release a Y.Doc when no longer editing.
+     * The worker continues syncing in the background.
+     */
+    releaseDoc(nodeId: string): void;
+    destroy(): void;
+    get status(): SyncStatus;
+    on(event: 'status', handler: (status: SyncStatus) => void): () => void;
+}
+/**
+ * Create a WorkerBridge from a worker URL.
+ *
+ * @param workerUrl - URL to the data worker script
+ * @returns A new WorkerBridge instance (must call initialize() before use)
+ */
+declare function createWorkerBridge(workerUrl: string | URL): WorkerBridge;
+
+/**
+ * NativeBridge - DataBridge implementation for React Native/Expo
+ *
+ * Phase 5 implementation that provides the DataBridge interface for React Native.
+ *
+ * Architecture:
+ * - Uses expo-sqlite for storage (runs on native thread)
+ * - Uses NodeStore on JS thread (can be moved to JSI in future)
+ * - Provides same API as MainThreadBridge/WorkerBridge
+ *
+ * Future enhancements:
+ * - Turbo Module for heavy operations (crypto, queries)
+ * - JSI bindings for direct native access
+ * - Native WebSocket for sync
+ */
+
+/**
+ * Interface for native storage adapters (expo-sqlite, etc.)
+ * This allows the NativeBridge to work with different storage backends.
+ */
+interface NativeStorageAdapter {
+    /** Open the database */
+    open(): Promise<void>;
+    /** Close the database */
+    close(): Promise<void>;
+    /** Get a document by ID */
+    getDocument(id: string): Promise<{
+        content: Uint8Array;
+    } | null>;
+    /** Set a document */
+    setDocument(id: string, content: Uint8Array): Promise<void>;
+    /** Delete a document */
+    deleteDocument(id: string): Promise<void>;
+    /** List all document IDs */
+    listDocuments(): Promise<string[]>;
+}
+interface NativeBridgeConfig {
+    /** The NodeStore instance to use */
+    store: NodeStore;
+    /** Optional native storage adapter for Y.Doc persistence */
+    storageAdapter?: NativeStorageAdapter;
+    /** Signaling server URL for sync (optional, default: no sync) */
+    signalingUrl?: string;
+}
+/**
+ * DataBridge implementation for React Native/Expo.
+ *
+ * This implementation runs on the JS thread but is designed to work with
+ * React Native's architecture. Storage operations use expo-sqlite which
+ * runs on a native thread.
+ *
+ * For now, this is similar to MainThreadBridge but structured for RN.
+ * Future versions will add Turbo Module integration for off-thread operations.
+ */
+declare class NativeBridge implements DataBridge {
+    private store;
+    private cache;
+    private statusListeners;
+    private storeUnsubscribe;
+    private storageAdapter?;
+    private _status;
+    private destroyed;
+    constructor(config: NativeBridgeConfig);
+    query<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, options?: QueryOptions<P>): QuerySubscription<P>;
+    /**
+     * Load query data from the store and update cache.
+     */
+    private loadQuery;
+    /**
+     * Handle store changes and invalidate affected caches.
+     */
+    private handleStoreChange;
+    create<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, data: InferCreateProps<P>, id?: string): Promise<NodeState>;
+    update(nodeId: string, changes: Record<string, unknown>): Promise<NodeState>;
+    delete(nodeId: string): Promise<void>;
+    restore(nodeId: string): Promise<NodeState>;
+    /**
+     * Acquire a Y.Doc for editing.
+     *
+     * Note: Y.Doc management in React Native is limited compared to web.
+     * For now, this throws an error. Future versions will support Y.Doc
+     * via native WebSocket sync or JSI bindings.
+     */
+    acquireDoc(_nodeId: string): Promise<AcquiredDoc>;
+    /**
+     * Release a Y.Doc when no longer editing.
+     */
+    releaseDoc(_nodeId: string): void;
+    /**
+     * Initialize the bridge.
+     * Opens storage adapter if provided.
+     */
+    initialize(_config: DataBridgeConfig): Promise<void>;
+    destroy(): void;
+    get status(): SyncStatus;
+    on(event: 'status', handler: (status: SyncStatus) => void): () => void;
+    private setStatus;
+    get nodeStore(): NodeStore;
+    subscribeToChanges(listener: (event: NodeChangeEvent) => void): () => void;
+    get(nodeId: string): Promise<NodeState | null>;
+    list(options?: ListNodesOptions): Promise<NodeState[]>;
+}
+/**
+ * Create a NativeBridge from a NodeStore.
+ */
+declare function createNativeBridge(config: NativeBridgeConfig): NativeBridge;
+/**
+ * Check if we're running in a React Native environment.
+ */
+declare function isReactNative(): boolean;
+/**
+ * Check if we're running in Expo.
+ */
+declare function isExpo(): boolean;
+
+/**
+ * Factory functions for creating DataBridge instances
+ *
+ * Provides platform-aware bridge creation with automatic detection
+ * of Web Worker support and appropriate fallbacks.
+ */
+
+interface CreateBridgeOptions {
+    /**
+     * NodeStore instance (required for MainThreadBridge fallback)
+     */
+    nodeStore: NodeStore;
+    /**
+     * Configuration for the bridge
+     */
+    config: DataBridgeConfig;
+    /**
+     * URL to the data worker script.
+     * If not provided, MainThreadBridge will be used.
+     *
+     * In Vite, use import.meta.url to get the worker URL:
+     * ```ts
+     * // Option 1: Use the package's built worker
+     * const workerUrl = new URL('@xnetjs/data-bridge/worker', import.meta.url)
+     *
+     * // Option 2: Use Vite's ?worker&url import (bundles into your build)
+     * import workerUrl from '@xnetjs/data-bridge/dist/worker/data-worker.js?worker&url'
+     * ```
+     *
+     * Note: Vite handles Web Worker bundling automatically. No additional
+     * configuration is needed - just pass the URL to WorkerBridge.
+     */
+    workerUrl?: URL | string;
+    /**
+     * Force a specific bridge type.
+     * - 'worker': Force WorkerBridge (fails if workers not supported)
+     * - 'main-thread': Force MainThreadBridge
+     * - 'auto': Auto-detect (default)
+     */
+    mode?: 'worker' | 'main-thread' | 'auto';
+}
+/**
+ * Check if Web Workers are supported in the current environment.
+ */
+declare function isWorkerSupported(): boolean;
+/**
+ * Check if we're in a Node.js environment (e.g., SSR, tests).
+ */
+declare function isNodeEnvironment(): boolean;
+/**
+ * Create a DataBridge with automatic platform detection.
+ *
+ * @example
+ * ```ts
+ * // In a web app with Vite
+ * const bridge = await createDataBridge({
+ *   nodeStore,
+ *   config: { authorDID, signingKey },
+ *   workerUrl: new URL('@xnetjs/data-bridge/worker', import.meta.url)
+ * })
+ *
+ * // In tests or when workers aren't needed
+ * const bridge = await createDataBridge({
+ *   nodeStore,
+ *   config: { authorDID, signingKey },
+ *   mode: 'main-thread'
+ * })
+ * ```
+ */
+declare function createDataBridge(options: CreateBridgeOptions): Promise<DataBridge>;
+/**
+ * Create a MainThreadBridge directly.
+ * Use this when you don't need off-main-thread support.
+ */
+declare function createMainThreadBridgeSync(nodeStore: NodeStore): MainThreadBridge;
+/**
+ * Create a WorkerBridge directly.
+ * The bridge must be initialized before use.
+ *
+ * @example
+ * ```ts
+ * const bridge = createWorkerBridgeSync(workerUrl)
+ * await bridge.initialize(config)
+ * ```
+ */
+declare function createWorkerBridgeSync(workerUrl: URL | string): WorkerBridge;
+
+/**
+ * QueryCache - In-memory cache for query results with LRU eviction
+ *
+ * Provides:
+ * - Fast synchronous access to query results (for useSyncExternalStore)
+ * - Subscriber notification on cache updates
+ * - Query deduplication via stable query IDs
+ * - LRU eviction for memory management
+ * - Weak references for inactive subscriptions (automatic cleanup)
+ */
+
+interface QueryCacheOptions {
+    /** Maximum number of queries to cache (default: 100) */
+    maxSize?: number;
+    /** Enable weak reference cleanup interval (default: true in browser, false in tests) */
+    enableWeakRefCleanup?: boolean;
+}
+/**
+ * In-memory cache for query results with subscriber notification and LRU eviction.
+ */
+declare class QueryCache {
+    private cache;
+    private maxSize;
+    private cleanupInterval;
+    constructor(options?: QueryCacheOptions);
+    /**
+     * Start the interval that cleans up dead weak references.
+     */
+    private startWeakRefCleanup;
+    /**
+     * Stop the weak reference cleanup interval.
+     */
+    stopCleanup(): void;
+    /**
+     * Clean up dead weak references from all cache entries.
+     * Returns the number of dead references removed.
+     */
+    cleanupDeadWeakRefs(): number;
+    /**
+     * Compute a stable query ID from schema and options.
+     * Same query params should produce the same ID for deduplication.
+     */
+    computeQueryId<P extends Record<string, PropertyBuilder>>(schemaId: string, options?: QueryOptions<P>): string;
+    /**
+     * Get cached data for a query (synchronous for useSyncExternalStore).
+     * Updates lastAccessed for LRU tracking.
+     */
+    get(queryId: string): NodeState[] | null;
+    /**
+     * Check if a query is in the cache.
+     */
+    has(queryId: string): boolean;
+    /**
+     * Set cached data for a query and notify subscribers.
+     * Triggers LRU eviction if cache exceeds maxSize.
+     */
+    set(queryId: string, data: NodeState[], schemaId: SchemaIRI, options: QueryOptions): void;
+    /**
+     * Initialize a cache entry (called when starting a subscription).
+     */
+    initEntry(queryId: string, schemaId: SchemaIRI, options: QueryOptions): void;
+    /**
+     * Subscribe to cache updates for a query.
+     * Uses strong references - callback will not be garbage collected until unsubscribed.
+     */
+    subscribe(queryId: string, callback: () => void): () => void;
+    /**
+     * 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: string, callback: () => void): () => void;
+    /**
+     * Notify all subscribers of a query that data has changed.
+     * Handles both strong and weak subscribers, cleaning up dead weak refs.
+     */
+    notifySubscribers(queryId: string): void;
+    /**
+     * Get the number of active subscribers for a query.
+     * Includes both strong and live weak subscribers.
+     */
+    getSubscriberCount(queryId: string): number;
+    /**
+     * Get the number of weak subscribers (including potentially dead ones).
+     * Useful for debugging.
+     */
+    getWeakSubscriberCount(queryId: string): number;
+    /**
+     * Remove a query from the cache.
+     */
+    delete(queryId: string): void;
+    /**
+     * Get all query IDs that match a schema.
+     */
+    getQueriesForSchema(schemaId: SchemaIRI): string[];
+    /**
+     * Get the schema IRI for a cached query.
+     */
+    getSchemaId(queryId: string): SchemaIRI | undefined;
+    /**
+     * Get the options for a cached query.
+     */
+    getOptions(queryId: string): QueryOptions | undefined;
+    /**
+     * Clear the entire cache and stop cleanup interval.
+     */
+    clear(): void;
+    /**
+     * Destroy the cache, stopping all cleanup intervals.
+     */
+    destroy(): void;
+    /**
+     * Get the number of cached queries.
+     */
+    get size(): number;
+    /**
+     * Get the maximum cache size.
+     */
+    get maxCacheSize(): number;
+    /**
+     * Check if an entry has any active subscribers (strong or live weak).
+     */
+    private hasActiveSubscribers;
+    /**
+     * Evict least-recently-used entries if cache exceeds maxSize.
+     * Only evicts entries with no active subscribers and older than MIN_AGE_FOR_EVICTION.
+     */
+    private evictIfNeeded;
+    /**
+     * Manually trigger eviction (for testing or explicit cleanup).
+     */
+    evict(): number;
+    /**
+     * Filter nodes based on query options.
+     */
+    filterNodes<P extends Record<string, PropertyBuilder>>(nodes: NodeState[], options?: QueryOptions<P>): NodeState[];
+    /**
+     * Sort nodes based on query options.
+     */
+    sortNodes<P extends Record<string, PropertyBuilder>>(nodes: NodeState[], options?: QueryOptions<P>): NodeState[];
+    /**
+     * Apply pagination to nodes.
+     */
+    paginateNodes(nodes: NodeState[], options?: QueryOptions): NodeState[];
+}
+
+/**
+ * Debounce utilities for DataBridge
+ *
+ * These utilities help reduce message frequency between main thread and worker,
+ * particularly useful for high-frequency Y.Doc updates during rapid typing.
+ */
+interface DebounceOptions {
+    /** Time in ms to wait before executing */
+    wait: number;
+    /** Maximum time in ms to wait before forcing execution */
+    maxWait?: number;
+    /** If true, execute on leading edge instead of trailing */
+    leading?: boolean;
+}
+interface DebouncedFunction<T extends (...args: unknown[]) => void> {
+    (...args: Parameters<T>): void;
+    /** Cancel any pending execution */
+    cancel(): void;
+    /** Execute immediately if there's a pending call */
+    flush(): void;
+    /** Check if there's a pending execution */
+    pending(): boolean;
+}
+/**
+ * Creates a debounced function that delays invoking func until after `wait`
+ * milliseconds have elapsed since the last time the debounced function was invoked.
+ *
+ * Optionally supports a maxWait to ensure execution even during continuous calls.
+ */
+declare function debounce<T extends (...args: unknown[]) => void>(func: T, options: DebounceOptions): DebouncedFunction<T>;
+/**
+ * Accumulates Y.Doc updates and batches them into a single merged update.
+ * This is more efficient than debouncing individual updates because Yjs
+ * can merge multiple updates into one.
+ */
+interface UpdateBatcher {
+    /** Add an update to the batch */
+    add(update: Uint8Array): void;
+    /** Cancel pending batch */
+    cancel(): void;
+    /** Flush pending updates immediately */
+    flush(): void;
+    /** Check if there are pending updates */
+    pending(): boolean;
+}
+interface UpdateBatcherOptions {
+    /** Time in ms to wait before flushing the batch */
+    wait: number;
+    /** Maximum time in ms before forcing a flush */
+    maxWait: number;
+    /** Callback to receive the batched update */
+    onFlush: (mergedUpdate: Uint8Array) => void;
+}
+/**
+ * Creates an update batcher that accumulates Y.Doc updates and merges them.
+ *
+ * Uses Yjs mergeUpdates to combine multiple updates into one, reducing
+ * message count and improving network efficiency.
+ */
+declare function createUpdateBatcher(options: UpdateBatcherOptions): UpdateBatcher;
+/**
+ * Delta types for query result changes
+ */
+type QueryDelta = {
+    type: 'add';
+    node: unknown;
+    index: number;
+} | {
+    type: 'remove';
+    nodeId: string;
+} | {
+    type: 'update';
+    nodeId: string;
+    node: unknown;
+};
+/**
+ * Options for creating a delta batcher
+ */
+interface DeltaBatcherOptions {
+    /** Time in ms to wait before flushing deltas */
+    wait: number;
+    /** Maximum time in ms before forcing a flush */
+    maxWait: number;
+    /** Callback to receive batched deltas */
+    onFlush: (deltas: QueryDelta[]) => void;
+}
+/**
+ * Batcher for query deltas that coalesces rapid changes.
+ *
+ * Merging rules:
+ * - Multiple updates to same node → keep only latest update
+ * - Add then remove same node → both cancel out (no delta)
+ * - Remove then add same node → becomes update
+ * - Add then update same node → keep add with updated data
+ */
+interface DeltaBatcher {
+    /** Add a delta to the batch */
+    add(delta: QueryDelta): void;
+    /** Cancel pending batch */
+    cancel(): void;
+    /** Flush pending deltas immediately */
+    flush(): void;
+    /** Check if there are pending deltas */
+    pending(): boolean;
+}
+/**
+ * Creates a delta batcher that coalesces rapid query result changes.
+ */
+declare function createDeltaBatcher(options: DeltaBatcherOptions): DeltaBatcher;
+
+/**
+ * Binary Serialization for NodeState
+ *
+ * Provides efficient binary encoding for NodeState objects when transferring
+ * between main thread and worker via postMessage. This is more efficient than
+ * JSON for large datasets with typed arrays.
+ *
+ * Format:
+ * - Uses TextEncoder/TextDecoder for strings
+ * - Preserves Uint8Array as-is (transferable)
+ * - Compacts property timestamps
+ *
+ * Note: This is an optimization for large transfers. For small payloads,
+ * structured clone (default postMessage behavior) may be faster.
+ */
+
+/**
+ * Binary encoder for NodeState arrays.
+ *
+ * Encodes an array of NodeState objects to a single Uint8Array.
+ * The result can be transferred via postMessage as a Transferable.
+ */
+declare class NodeStateEncoder {
+    private chunks;
+    private textEncoder;
+    /**
+     * Encode an array of NodeState objects.
+     */
+    encode(states: NodeState[]): Uint8Array;
+    private writeNodeState;
+    private writeProperties;
+    private writeTimestamps;
+    private writeTimestamp;
+    private writeValue;
+    private writeByte;
+    private writeUint32;
+    private writeFloat64;
+    private writeString;
+    private writeUint8Array;
+    private finish;
+}
+/**
+ * Binary decoder for NodeState arrays.
+ */
+declare class NodeStateDecoder {
+    private data;
+    private view;
+    private offset;
+    private textDecoder;
+    constructor(data: Uint8Array);
+    /**
+     * Decode a Uint8Array back to an array of NodeState objects.
+     */
+    decode(): NodeState[];
+    private readNodeState;
+    private readProperties;
+    private readTimestamps;
+    private readTimestamp;
+    private readValue;
+    private readByte;
+    private readUint32;
+    private readFloat64;
+    private readString;
+    private readUint8Array;
+}
+/**
+ * Encode an array of NodeState to binary.
+ */
+declare function encodeNodeStates(states: NodeState[]): Uint8Array;
+/**
+ * Decode binary back to NodeState array.
+ */
+declare function decodeNodeStates(data: Uint8Array): NodeState[];
+/**
+ * Check if binary encoding would be beneficial for this payload size.
+ * For small payloads, structured clone may be faster.
+ */
+declare function shouldUseBinaryEncoding(states: NodeState[]): boolean;
+
+export { type AcquiredDoc, type CreateBridgeOptions, type CreateResult, type DataBridge, type DataBridgeConfig, type DataWorkerAPI, type DebounceOptions, type DebouncedFunction, type DeltaBatcher, type DeltaBatcherOptions, type QueryDelta as DeltaQueryDelta, type DocUpdateMessage, MainThreadBridge, NativeBridge, type NativeBridgeConfig, type NativeStorageAdapter, NodeStateDecoder, NodeStateEncoder, QueryCache, type QueryDelta$1 as QueryDelta, type QueryOptions, type QuerySubscription, type SerializedQueryOptions, type SortDirection, type SyncManagerLike, type SyncStatus, type SystemOrderField, type UpdateBatcher, type UpdateBatcherOptions, type UpdateResult, type WorkerAcquiredDoc, WorkerBridge, type WorkerConfig, createDataBridge, createDeltaBatcher, createMainThreadBridge, createMainThreadBridgeSync, createNativeBridge, createUpdateBatcher, createWorkerBridge, createWorkerBridgeSync, debounce, decodeNodeStates, encodeNodeStates, isExpo, isNodeEnvironment, isReactNative, isWorkerSupported, shouldUseBinaryEncoding };