@xnetjs/data-bridge 0.0.2 → 0.0.3

package/dist/worker/data-worker.d.ts

@@ -1,2 +1,162 @@
+import { D as DataWorkerAPI, a as WorkerConfig, S as SerializedQueryOptions, Q as QueryDelta, W as WorkerQuerySnapshot, b as WorkerAcquiredDoc, v as WorkerSubscription, B as BoundedQueryWorkingSet } from '../query-descriptor-D0k2gUQ0.js';
+import { B as BridgeTransactionResult, S as SyncStatus } from '../types-BRvuTwEn.js';
+import { NodeStore, NodeStorageAdapter, NodeState, NodeBatchWriteInput, NodeBatchWriteResult, TransactionOperation, NodeChangeEvent } from '@xnetjs/data';
+import 'y-protocols/awareness';
+import 'yjs';
 
-export {  }
+/**
+ * DataWorker host - the worker-resident data layer (exploration 0164)
+ *
+ * This class runs NodeStore, query subscriptions, and invalidation off the
+ * main thread. It is exposed via Comlink by `data-worker.ts`; tests
+ * instantiate it directly.
+ *
+ * Key responsibilities:
+ * - Initialize and manage NodeStore inside the worker
+ * - Handle query subscriptions and push per-query deltas to the main thread
+ * - Execute CRUD operations and atomic transactions
+ * - Manage Y.Doc pool for collaborative editing
+ * - Handle signing/verification (all crypto happens here)
+ *
+ * Invalidation mirrors MainThreadBridge's 0163 machinery:
+ * - Bounded working sets keep limited+ordered queries incremental
+ * - Batch change events hydrate touched nodes once instead of re-querying
+ * - Re-queries graft previous node references back in for unchanged rows
+ */
+
+interface ActiveWorkerSubscription extends WorkerSubscription {
+    onDelta: (delta: QueryDelta) => void;
+    /** Overfetched prefix buffer for bounded (limit + orderBy) descriptors */
+    workingSet: BoundedQueryWorkingSet | null;
+}
+declare class DataWorker implements DataWorkerAPI {
+    protected store: NodeStore | null;
+    protected storage: NodeStorageAdapter | null;
+    private subscriptions;
+    private status;
+    private statusHandlers;
+    private changeFeedHandlers;
+    private storeUnsubscribe;
+    private storeBatchUnsubscribe;
+    private pendingStoreChanges;
+    private storeChangeFlushQueued;
+    private docPool;
+    private nextClientId;
+    initialize(config: WorkerConfig): Promise<void>;
+    /**
+     * Create the worker's storage adapter.
+     *
+     * With a forwarded `storagePort`, persistence goes through the existing
+     * SQLite worker via PortSQLiteAdapter (worker-to-worker, no main-thread
+     * hop). Without one, storage is in-memory.
+     */
+    protected createStorageAdapter(config: WorkerConfig): Promise<NodeStorageAdapter>;
+    subscribe(queryId: string, schemaId: string, options: SerializedQueryOptions, onDelta: (delta: QueryDelta) => void): Promise<WorkerQuerySnapshot>;
+    unsubscribe(queryId: string): Promise<void>;
+    reloadQuery(queryId: string): Promise<WorkerQuerySnapshot>;
+    /**
+     * Encode a snapshot for the wire. Binary payloads ride a freshly
+     * allocated buffer, so it is transferred (zero-copy) instead of cloned.
+     */
+    private toWireSnapshot;
+    create(schemaId: string, data: Record<string, unknown>, id?: string): Promise<NodeState>;
+    update(nodeId: string, changes: Record<string, unknown>): Promise<NodeState>;
+    delete(nodeId: string): Promise<void>;
+    restore(nodeId: string): Promise<NodeState>;
+    bulkWrite(input: NodeBatchWriteInput): Promise<NodeBatchWriteResult>;
+    transaction(operations: TransactionOperation[]): Promise<BridgeTransactionResult>;
+    get(nodeId: string): Promise<NodeState | null>;
+    acquireDoc(nodeId: string, onUpdate: (update: Uint8Array, origin: string) => void): Promise<WorkerAcquiredDoc>;
+    private acquireDocEntry;
+    private createDocEntry;
+    private handleDocUpdate;
+    private persistDocState;
+    private forwardRemoteDocUpdate;
+    private sendDocUpdate;
+    releaseDoc(nodeId: string): void;
+    applyLocalUpdate(nodeId: string, update: Uint8Array): void;
+    getStatus(): SyncStatus;
+    onStatusChange(handler: (status: SyncStatus) => void): void;
+    /**
+     * Subscribe to the worker's raw store change feed (devtools and other
+     * instrumentation). Events are structured-clone-safe NodeChangeEvents.
+     * The bridge registers a single forwarder and fans out locally, so the
+     * worker keeps at most one handler per bridge.
+     */
+    subscribeToChanges(handler: (event: NodeChangeEvent) => void): void;
+    private emitChangeFeedEvent;
+    destroy(): Promise<void>;
+    private detachStoreListeners;
+    private closeStorage;
+    /**
+     * Execute a subscription's query against storage. Bounded descriptors
+     * overfetch a small buffer so later node changes can be applied in
+     * memory, and re-queries graft previous node references back in wherever
+     * the snapshots are equivalent (so reference-based delta math and
+     * downstream identity caches keep working).
+     */
+    private loadQueryState;
+    private reloadSubscription;
+    private enqueueStoreChange;
+    private flushStoreChanges;
+    private isBulkStoreChangeSet;
+    private subscriptionsForSchema;
+    private handleStoreChangeSet;
+    /**
+     * Batch notifications carry node ids only. Small batches hydrate the
+     * touched nodes once and flow through the same delta path as regular
+     * change events; only genuinely bulk batches re-query each subscription.
+     */
+    private handleStoreBatchChange;
+    private reloadSubscriptionsForSchemas;
+    private applyStoreBatchChangeDeltas;
+    /**
+     * Apply a list of node changes to one subscription, falling back to a
+     * storage re-query only when a delta is ambiguous. Emits at most one
+     * wire delta per change.
+     */
+    protected applyChangesToSubscription(sub: ActiveWorkerSubscription, changes: ReadonlyArray<{
+        nodeId: string;
+        nextNode: NodeState | null;
+    }>, options?: {
+        onAmbiguous?: 'reload' | 'skip';
+    }): Promise<void>;
+    /**
+     * Apply one change to a subscription and emit its wire delta.
+     * Returns false when the change was ambiguous (the subscription was
+     * reloaded — or skipped — wholesale, so remaining changes are moot).
+     */
+    private applyChangeAndEmit;
+    private emitSubscriptionDelta;
+    /**
+     * Find the freshest cached snapshot of a node across all subscriptions.
+     */
+    private findCachedNode;
+    /**
+     * Synchronously apply an optimistic node mutation to every affected
+     * subscription before persistence, so the main thread sees the edit one
+     * postMessage later (~next microtask) instead of after storage commits.
+     * Ambiguous deltas are skipped, not reloaded — storage still holds the
+     * OLD state, and the durable change event that follows reconciles.
+     * Returns a revert function that re-queries authoritative state (used
+     * when persistence fails).
+     */
+    private applyOptimisticNodeChange;
+    private applyChangeToSubscriptionState;
+    private applyBoundedChange;
+    private applyUnboundedChange;
+    private setStatus;
+    /**
+     * Evict unused Y.Docs from the pool to manage memory.
+     * Only evicts docs with refCount=0 that haven't been accessed recently.
+     */
+    private evictOldDocs;
+    /**
+     * Find eviction candidates — docs with no refs and old enough — ordered
+     * oldest-accessed first.
+     */
+    private collectDocEvictionCandidates;
+    private evictDoc;
+}
+
+export { DataWorker };