@xnetjs/data-bridge 0.0.2 → 0.0.3

package/dist/native-bridge.d.ts

@@ -0,0 +1,126 @@
+import { D as DataBridge, Q as QueryOptions, a as QuerySubscription, b as QueryDescriptor, B as BridgeTransactionResult, A as AcquiredDoc, c as DataBridgeConfig, S as SyncStatus } from './types-BRvuTwEn.js';
+import { NodeStore, PropertyBuilder, DefinedSchema, InferCreateProps, NodeState, NodeBatchWriteInput, NodeBatchWriteResult, TransactionOperation, NodeChangeEvent, ListNodesOptions } from '@xnetjs/data';
+import 'y-protocols/awareness';
+import 'yjs';
+
+/**
+ * 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 storeBatchUnsubscribe;
+    private storageAdapter?;
+    private _status;
+    private destroyed;
+    constructor(config: NativeBridgeConfig);
+    query<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, options?: QueryOptions<P>): QuerySubscription<P>;
+    reloadQuery(descriptor: QueryDescriptor): Promise<void>;
+    /**
+     * Load query data from the store and update cache.
+     */
+    private loadQuery;
+    /**
+     * Handle store changes and invalidate affected caches.
+     */
+    private handleStoreChange;
+    private handleStoreBatchChange;
+    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>;
+    bulkWrite(input: NodeBatchWriteInput): Promise<NodeBatchWriteResult>;
+    transaction(operations: TransactionOperation[]): Promise<BridgeTransactionResult>;
+    /**
+     * 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;
+
+export { NativeBridge, type NativeBridgeConfig, type NativeStorageAdapter, createNativeBridge, isExpo, isReactNative };

package/dist/native-bridge.js

@@ -0,0 +1,13 @@
+import {
+  NativeBridge,
+  createNativeBridge,
+  isExpo,
+  isReactNative
+} from "./chunk-25WNZV7W.js";
+import "./chunk-5GTIP33X.js";
+export {
+  NativeBridge,
+  createNativeBridge,
+  isExpo,
+  isReactNative
+};

package/dist/query-descriptor-D0k2gUQ0.d.ts

@@ -0,0 +1,298 @@
+import { r as QueryPageOptions, b as QueryDescriptor, B as BridgeTransactionResult, S as SyncStatus, Q as QueryOptions } from './types-BRvuTwEn.js';
+import { NodeState, NodeBatchWriteInput, NodeBatchWriteResult, TransactionOperation, NodeChangeEvent, SchemaIRI, PropertyBuilder, NodeQueryCursor } from '@xnetjs/data';
+
+/**
+ * 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[];
+    /**
+     * Optional transferred MessagePort connected to the SQLite worker
+     * (created via `WebSQLiteProxy.createMessagePort()`). When present the
+     * data worker persists through a `PortSQLiteAdapter` instead of
+     * in-memory storage.
+     */
+    storagePort?: MessagePort;
+}
+/**
+ * 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;
+    page?: QueryPageOptions;
+    spatial?: QueryDescriptor['spatial'];
+    search?: string | QueryDescriptor['search'];
+    materializedView?: string | QueryDescriptor['materializedView'];
+    mode?: QueryDescriptor['mode'];
+    source?: QueryDescriptor['source'];
+}
+/**
+ * Wire format for query snapshots (initial loads and reloads).
+ *
+ * Large result sets are encoded with `binary-state.ts` so the backing
+ * ArrayBuffer can be transferred (zero-copy) instead of structured-cloned;
+ * small ones stay as plain structured-clone payloads, which is faster for
+ * few nodes.
+ */
+type WorkerQuerySnapshot = {
+    encoding: 'json';
+    nodes: NodeState[];
+} | {
+    encoding: 'binary';
+    data: Uint8Array;
+};
+/**
+ * Delta update types for incremental cache updates
+ */
+type QueryDelta = {
+    type: 'add';
+    node: NodeState;
+    index: number;
+} | {
+    type: 'remove';
+    nodeId: string;
+} | {
+    type: 'update';
+    nodeId: string;
+    node: NodeState;
+} | {
+    type: 'reload';
+    data: NodeState[];
+};
+/**
+ * Internal subscription tracking in the worker
+ */
+interface WorkerSubscription {
+    schemaId: SchemaIRI;
+    descriptor: QueryDescriptor;
+    options: SerializedQueryOptions;
+    lastResult: 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 the initial snapshot (binary-encoded
+     * and transferred above the size threshold). Delta updates are sent via
+     * the callback.
+     */
+    subscribe(queryId: string, schemaId: string, options: SerializedQueryOptions, onDelta: (delta: QueryDelta) => void): Promise<WorkerQuerySnapshot>;
+    /**
+     * Unsubscribe from a query.
+     */
+    unsubscribe(queryId: string): Promise<void>;
+    /**
+     * Force a targeted reload for an existing subscription.
+     */
+    reloadQuery(queryId: string): Promise<WorkerQuerySnapshot>;
+    /**
+     * 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>;
+    /**
+     * Execute a storage-owned batch write in the worker.
+     */
+    bulkWrite(input: NodeBatchWriteInput): Promise<NodeBatchWriteResult>;
+    /**
+     * Execute an atomic multi-operation transaction in the worker.
+     * Returns a structured-clone-safe result (no signed change list).
+     */
+    transaction(operations: TransactionOperation[]): Promise<BridgeTransactionResult>;
+    /**
+     * 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;
+    /**
+     * Subscribe to the worker's raw store change feed (devtools and other
+     * instrumentation). The bridge registers one forwarder and fans out to
+     * local listeners.
+     */
+    subscribeToChanges(handler: (event: NodeChangeEvent) => void): void;
+    /**
+     * Clean up and close the worker.
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Shared query descriptor helpers for @xnetjs/data-bridge
+ */
+
+type QueryResultDelta = {
+    kind: 'noop';
+} | {
+    kind: 'reload';
+} | {
+    kind: 'set';
+    data: NodeState[];
+};
+/**
+ * Extra rows fetched beyond a bounded query's visible window. The buffer
+ * lets node changes be applied in memory: removals are absorbed by spare
+ * rows instead of forcing a storage re-query, and inserts can be ranked
+ * against known rows.
+ */
+declare const BOUNDED_QUERY_OVERFETCH = 25;
+interface BoundedQueryWorkingSet {
+    /** Descriptor-ordered rows, at least covering the visible window. */
+    nodes: NodeState[];
+    /**
+     * True when the working-set fetch returned fewer rows than requested,
+     * meaning the buffer holds every matching node: deltas can never
+     * underflow into unknown rows and reloads are never required.
+     */
+    complete: boolean;
+}
+type BoundedQueryResultDelta = {
+    kind: 'noop';
+} | {
+    kind: 'reload';
+} | {
+    kind: 'set';
+    data: NodeState[];
+    workingSet: BoundedQueryWorkingSet;
+};
+declare function createQueryDescriptor<P extends Record<string, PropertyBuilder>>(schemaId: SchemaIRI, options?: QueryOptions<P>): QueryDescriptor;
+declare function queryDescriptorToOptions<P extends Record<string, PropertyBuilder> = Record<string, PropertyBuilder>>(descriptor: QueryDescriptor): QueryOptions<P>;
+declare function serializeQueryDescriptor(descriptor: QueryDescriptor): string;
+declare function encodeQueryCursor(descriptor: QueryDescriptor, node: NodeState): string;
+declare function decodeQueryCursor(cursor: string): NodeQueryCursor | null;
+declare function matchesQueryDescriptor(descriptor: QueryDescriptor, node: NodeState | null | undefined): boolean;
+declare function filterQueryNodes(nodes: NodeState[], descriptor: QueryDescriptor): NodeState[];
+declare function sortQueryNodes(nodes: NodeState[], descriptor: QueryDescriptor): NodeState[];
+declare function applyQueryDescriptor(nodes: NodeState[], descriptor: QueryDescriptor): NodeState[];
+declare function queryDescriptorNeedsBoundedReload(descriptor: QueryDescriptor): boolean;
+/**
+ * Whether a bounded (limited) descriptor can be maintained incrementally
+ * with an overfetch working set instead of re-executing on every change.
+ *
+ * Requirements:
+ * - `limit` without `offset`/`after`: window shifts under offset/cursor
+ *   pages can't be resolved from a prefix buffer, so they keep reload
+ *   semantics.
+ * - An explicit `orderBy`: the working set is a prefix of the descriptor
+ *   order, and rows beyond the buffer are known to sort after it. Without
+ *   `orderBy` the storage row order is not derivable in JS.
+ * - No materialized view: those windows are refreshed in storage.
+ */
+declare function queryDescriptorSupportsBoundedDelta(descriptor: QueryDescriptor): boolean;
+/**
+ * Descriptor used to fetch a bounded query's working set: the visible
+ * window plus {@link BOUNDED_QUERY_OVERFETCH} spare rows.
+ */
+declare function createBoundedWorkingSetDescriptor(descriptor: QueryDescriptor): QueryDescriptor;
+declare function createBoundedWorkingSet(descriptor: QueryDescriptor, nodes: NodeState[]): BoundedQueryWorkingSet;
+/**
+ * Apply a single node change to a bounded query's working set without
+ * re-executing the query.
+ *
+ * Correctness rests on one invariant: the working set was fetched as a
+ * prefix of the descriptor order, so every row NOT in the buffer sorts
+ * after the row that was last in the buffer at fetch time. Changes that
+ * would force a decision about those unknown rows (buffer underflow below
+ * `limit`, or ranking a row that sorts past every known row while the
+ * window is short) return `reload`.
+ */
+declare function applyNodeChangeToBoundedQueryResult(input: {
+    descriptor: QueryDescriptor;
+    workingSet: BoundedQueryWorkingSet;
+    nodeId: string;
+    nextNode: NodeState | null;
+}): BoundedQueryResultDelta;
+declare function applyNodeChangeToQueryResult(input: {
+    descriptor: QueryDescriptor;
+    currentData: NodeState[];
+    nodeId: string;
+    nextNode: NodeState | null;
+}): QueryResultDelta;
+
+export { type BoundedQueryWorkingSet as B, type DataWorkerAPI as D, type QueryDelta as Q, type SerializedQueryOptions as S, type WorkerQuerySnapshot as W, type WorkerConfig as a, type WorkerAcquiredDoc as b, type DocUpdateMessage as c, createQueryDescriptor as d, encodeQueryCursor as e, decodeQueryCursor as f, filterQueryNodes as g, sortQueryNodes as h, applyQueryDescriptor as i, queryDescriptorNeedsBoundedReload as j, applyNodeChangeToQueryResult as k, applyNodeChangeToBoundedQueryResult as l, matchesQueryDescriptor as m, queryDescriptorSupportsBoundedDelta as n, createBoundedWorkingSet as o, createBoundedWorkingSetDescriptor as p, queryDescriptorToOptions as q, BOUNDED_QUERY_OVERFETCH as r, serializeQueryDescriptor as s, type QueryResultDelta as t, type BoundedQueryResultDelta as u, type WorkerSubscription as v };