@firtoz/collection-sync 4.0.0 → 6.0.0

package/dist/partial-sync-client-bridge.d.ts

@@ -0,0 +1,157 @@
+import { SyncMessage } from '@firtoz/db-helpers';
+import { SyncClientMessage, SyncRangeSort, SyncRange, RangeFingerprint, SyncServerMessage } from './sync-protocol.js';
+import { PartialSyncRowShape } from './partial-sync-row-key.js';
+import { PartialSyncViewTransition } from './partial-sync-interest.js';
+import 'zod';
+
+type PartialSyncViewTransitionEvent<TItem extends PartialSyncRowShape> = {
+    type: PartialSyncViewTransition;
+    change: SyncMessage<TItem>;
+};
+type PartialSyncRangePatchAppliedEvent<TItem extends PartialSyncRowShape> = {
+    change: SyncMessage<TItem>;
+    viewTransition?: PartialSyncViewTransition;
+};
+type CollectionWithReceiveSync<TItem> = {
+    utils: {
+        receiveSync: (messages: SyncMessage<TItem>[]) => Promise<void>;
+    };
+    /**
+     * When set, server `queryRangeChunk` rows can become `update` messages when the collection
+     * already holds that id — including durable hydration (IndexedDB / SQLite reload) where rows
+     * exist before {@link PartialSyncClientBridge.seedHydratedLocalRows} runs or if it is skipped.
+     * Without this, the bridge may emit `insert` and hit duplicate-key errors from `receiveSync`.
+     */
+    get?: (key: string | number) => TItem | undefined;
+};
+type SendFn = (msg: SyncClientMessage) => void;
+type PartialSyncState = {
+    status: "offline";
+} | {
+    status: "connecting";
+} | {
+    status: "connected";
+} | {
+    status: "fetching";
+    requestId: string;
+    chunksReceived: number;
+} | {
+    status: "partial";
+    cachedCount: number;
+    totalCount: number;
+    cacheUtilization: number;
+} | {
+    status: "realtime";
+    cachedCount: number;
+    totalCount: number;
+    cacheUtilization: number;
+} | {
+    status: "evicting";
+    cachedCount: number;
+    evictingCount: number;
+} | {
+    status: "disconnected";
+    cachedCount: number;
+} | {
+    status: "error";
+    message: string;
+};
+type PartialSyncRangeResult<TItem> = {
+    rows: TItem[];
+    totalCount: number;
+    lastCursor: unknown | null;
+    hasMore: boolean;
+    /** Server applied a small delta; caller may need to refetch the window without fingerprint. */
+    invalidateWindow?: boolean;
+    /** Server confirmed fingerprint; no new rows on the wire. */
+    upToDate?: boolean;
+};
+type PartialSyncReconcileResult<TItem extends PartialSyncRowShape> = {
+    added: TItem[];
+    updated: TItem[];
+    staleIds: Array<string | number>;
+    movedHints: Array<{
+        id: string | number;
+        hint: Record<string, unknown>;
+    }>;
+    totalCount: number;
+};
+interface PartialSyncClientBridgeOptions<TItem extends PartialSyncRowShape> {
+    /** Defaults to a random UUID when omitted (must match {@link SyncClientBridge} when using mutations). */
+    clientId?: string;
+    /** Must match the server's partial-sync {@link PartialSyncServerBridgeOptions.collectionId}. */
+    collectionId?: string;
+    collection: CollectionWithReceiveSync<TItem>;
+    send: SendFn;
+    onStateChange?: (state: PartialSyncState) => void;
+    beforeApplyRows?: (rows: TItem[]) => Promise<void>;
+    /** Fired when a `rangePatch` carries `viewTransition` (row crossed client interest). */
+    onViewTransition?: (event: PartialSyncViewTransitionEvent<TItem>) => void;
+    /** Fired after any `rangePatch` is applied (including view transitions). */
+    onRangePatchApplied?: (event: PartialSyncRangePatchAppliedEvent<TItem>) => void;
+}
+declare class PartialSyncClientBridge<TItem extends PartialSyncRowShape> {
+    #private;
+    private readonly options;
+    readonly clientId: string;
+    readonly collectionId: string;
+    constructor(options: PartialSyncClientBridgeOptions<TItem>);
+    get state(): PartialSyncState;
+    get cachedCount(): number;
+    setConnecting(): void;
+    setConnected(connected: boolean): void;
+    setOffline(): void;
+    setSend(send: SendFn): void;
+    setError(message: string): void;
+    setCacheUtilization(utilization: number): void;
+    setEvicting(evictingCount: number): void;
+    clearEvictingState(): void;
+    /**
+     * Drop in-flight `queryRange` / `queryByOffset` / `rangeQuery` requests (e.g. user seek / sort reset).
+     * {@link requestRange}, {@link requestByOffset}, and {@link requestRangeQuery} call this first so
+     * overlapping viewport debounces cannot double-apply the same rows.
+     */
+    abortRangeRequests(): void;
+    /**
+     * Clear tracked row ids (e.g. after a local `truncate()` on the collection). Local truncate
+     * does not flow through `receiveSync`, so the bridge must be reset to match.
+     */
+    clearServerConfirmedKeys(): void;
+    /** Keys from the latest completed `rangeQuery` / chunk response. */
+    get serverConfirmedKeys(): ReadonlySet<string | number>;
+    /** Bumps when {@link serverConfirmedKeys} changes; pass into predicate hooks as a dependency. */
+    get serverConfirmedKeysRevision(): number;
+    /** Subscribe to {@link serverConfirmedKeysRevision} changes (for `useSyncExternalStore`). */
+    subscribeConfirmedKeysRevision(listener: () => void): () => void;
+    clearTrackedRowIds(): void;
+    requestRange(sort: SyncRangeSort, limit: number, afterCursor: unknown | null): Promise<PartialSyncRangeResult<TItem>>;
+    requestByOffset(sort: SyncRangeSort, limit: number, offset: number): Promise<PartialSyncRangeResult<TItem>>;
+    requestRangeQuery(range: SyncRange, fingerprint?: RangeFingerprint): Promise<PartialSyncRangeResult<TItem>>;
+    /**
+     * Reconcile the client's cached window against the server using a row manifest (id + version ms).
+     * Pass `manifest` to override rows; otherwise uses {@link PartialSyncClientBridge.serverConfirmedKeys} and {@link PartialSyncClientBridgeOptions.collection} `get`.
+     */
+    requestRangeReconcile(range: SyncRange, manifest?: Array<{
+        id: string | number;
+        version: number;
+    }>): Promise<PartialSyncReconcileResult<TItem>>;
+    handleServerMessage(message: SyncServerMessage<TItem>): Promise<void>;
+    /**
+     * Merge rows already present in the local collection (e.g. IndexedDB eager `initialLoad`) into
+     * `#cachedIds` so {@link cachedCount} and React-driven `bridgeState` match durable storage after reload.
+     * Safe to call multiple times; ids are a set. Does not call `receiveSync`.
+     */
+    seedHydratedLocalRows(rows: readonly TItem[]): void;
+    /**
+     * Updates `#cachedIds` after {@link SyncClientBridge} has already applied the same messages via `receiveSync`
+     * (e.g. `syncBatch`) so we do not double-apply.
+     */
+    syncTrackedIdsFromMessages(changes: SyncMessage<TItem>[]): void;
+    /**
+     * Apply pending plain `rangePatch` updates coalesced by row id. Idempotent when the map is empty.
+     * Invoked automatically by `connectPartialSync` after each inbound pump drain.
+     */
+    flushPendingCoalescedInboundUpdates(): Promise<void>;
+}
+
+export { PartialSyncClientBridge, type PartialSyncClientBridgeOptions, type PartialSyncRangePatchAppliedEvent, type PartialSyncRangeResult, type PartialSyncReconcileResult, type PartialSyncState, type PartialSyncViewTransitionEvent };

package/dist/partial-sync-client-bridge.js

@@ -0,0 +1,6 @@
+export { PartialSyncClientBridge } from './chunk-P3JOTUAB.js';
+import './chunk-BJJEAKXL.js';
+import './chunk-UJ24XW52.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=partial-sync-client-bridge.js.map
+//# sourceMappingURL=partial-sync-client-bridge.js.map

package/dist/partial-sync-client-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"partial-sync-client-bridge.js"}

package/dist/partial-sync-interest.d.ts

@@ -0,0 +1,48 @@
+import { SyncMessage } from '@firtoz/db-helpers';
+import { RangeCondition } from './sync-protocol.js';
+import { PartialSyncRowShape } from './partial-sync-row-key.js';
+import 'zod';
+
+/** Metadata on `rangePatch` when an update crosses client interest boundaries. */
+type PartialSyncViewTransition = "enterView" | "exitView";
+type PartialSyncPatchResult<TItem extends PartialSyncRowShape> = {
+    change: SyncMessage<TItem>;
+    viewTransition?: PartialSyncViewTransition;
+};
+/** Tracked 1D sort interval delivered to a client (index / cursor queries). */
+type DeliveredRange = {
+    sortColumn: string;
+    sortDirection: "asc" | "desc";
+    fromValue: unknown;
+    toValue: unknown;
+};
+declare function compareInterestValues(left: unknown, right: unknown): number;
+declare function sortValueWithinDeliveredRange(value: unknown, range: DeliveredRange): boolean;
+declare function rowMatchesDeliveredSortRanges<TItem>(ranges: DeliveredRange[], row: TItem, getSortValue: (row: TItem, column: string) => unknown): boolean;
+declare function rowMatchesPredicateGroups<TItem>(predicateGroups: RangeCondition[][], row: TItem, getColumnValue: (row: TItem, column: string) => unknown): boolean;
+declare function rowMatchesClientInterest<TItem>(sortRanges: DeliveredRange[], predicateGroups: RangeCondition[][], row: TItem, getSortValue: (row: TItem, column: string) => unknown, getColumnValue: (row: TItem, column: string) => unknown): boolean;
+type ClassifyPartialSyncRangePatchOptions = {
+    /**
+     * When set, `delete` is only forwarded if the key was previously delivered to this client
+     * (viewport-scoped deletes). When omitted, `delete` is always forwarded (legacy behavior).
+     */
+    deliveredRowIds?: ReadonlySet<string> | undefined;
+};
+/**
+ * Maps a server-side change to a `rangePatch` payload, or `null` if this client should not
+ * receive a patch. View enter/exit keeps the real `update` on the wire so clients can cache
+ * rows and filter locally instead of fake delete/insert.
+ */
+declare function classifyPartialSyncRangePatch<TItem extends PartialSyncRowShape>(sortRanges: DeliveredRange[], predicateGroups: RangeCondition[][], change: SyncMessage<TItem>, getSortValue: (row: TItem, column: string) => unknown, getColumnValue: (row: TItem, column: string) => unknown, options?: ClassifyPartialSyncRangePatchOptions): PartialSyncPatchResult<TItem> | null;
+/**
+ * Filters sync messages to those relevant to a single predicate range (viewport). Used for
+ * `rangeDelta` so clients never receive changelog rows outside their requested conditions.
+ *
+ * - `insert` / `update` / `truncate`: uses {@link classifyPartialSyncRangePatch} with only this
+ *   predicate group (no sort ranges).
+ * - `delete`: passed through unchanged — callers should filter deletes in the store when the
+ *   deleted row snapshot is available (e.g. changelog payload).
+ */
+declare function filterSyncMessagesForPredicateRange<TItem extends PartialSyncRowShape>(conditions: RangeCondition[], changes: SyncMessage<TItem>[], getSortValue: (row: TItem, column: string) => unknown, getColumnValue: (row: TItem, column: string) => unknown): SyncMessage<TItem>[];
+
+export { type ClassifyPartialSyncRangePatchOptions, type DeliveredRange, type PartialSyncPatchResult, type PartialSyncViewTransition, classifyPartialSyncRangePatch, compareInterestValues, filterSyncMessagesForPredicateRange, rowMatchesClientInterest, rowMatchesDeliveredSortRanges, rowMatchesPredicateGroups, sortValueWithinDeliveredRange };

package/dist/partial-sync-interest.js

@@ -0,0 +1,6 @@
+export { classifyPartialSyncRangePatch, compareInterestValues, filterSyncMessagesForPredicateRange, rowMatchesClientInterest, rowMatchesDeliveredSortRanges, rowMatchesPredicateGroups, sortValueWithinDeliveredRange } from './chunk-6EHROJFY.js';
+import './chunk-3EHHMLSV.js';
+import './chunk-UJ24XW52.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=partial-sync-interest.js.map
+//# sourceMappingURL=partial-sync-interest.js.map

package/dist/partial-sync-interest.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"partial-sync-interest.js"}

package/dist/partial-sync-mutation-handler.d.ts

@@ -0,0 +1,31 @@
+import { SyncMessage } from '@firtoz/db-helpers';
+import { PartialSyncServerBridge } from './partial-sync-server-bridge.js';
+import { PartialSyncRowShape } from './partial-sync-row-key.js';
+import { SyncServerMessage, SyncClientMessage } from './sync-protocol.js';
+import './partial-sync-interest.js';
+import 'zod';
+
+interface PartialSyncMutationHandlerStore<TItem extends PartialSyncRowShape> {
+    applySyncMessages: (messages: SyncMessage<TItem>[]) => Promise<void>;
+    getRow: (key: string | number) => Promise<TItem | undefined>;
+}
+interface PartialSyncMutationHandlerOptions<TItem extends PartialSyncRowShape> {
+    store: PartialSyncMutationHandlerStore<TItem>;
+    partialBridge: Pick<PartialSyncServerBridge<TItem>, "pushServerChanges">;
+    sendToClient: (clientId: string, message: SyncServerMessage<TItem>) => void;
+    collectionId?: string;
+}
+/**
+ * Partial-sync durable object mutation path: `mutateBatch` → `ack` / `reject` + interest-scoped
+ * `rangePatch` via {@link PartialSyncServerBridge.pushServerChanges}. No `serverVersion`, changelog,
+ * or `syncBatch` broadcast.
+ */
+declare class PartialSyncMutationHandler<TItem extends PartialSyncRowShape> {
+    #private;
+    private readonly options;
+    constructor(options: PartialSyncMutationHandlerOptions<TItem>);
+    get collectionId(): string;
+    handleClientMessage(message: SyncClientMessage): Promise<void>;
+}
+
+export { PartialSyncMutationHandler, type PartialSyncMutationHandlerOptions, type PartialSyncMutationHandlerStore };

package/dist/partial-sync-mutation-handler.js

@@ -0,0 +1,6 @@
+export { PartialSyncMutationHandler } from './chunk-5VMFQT5Z.js';
+import './chunk-BJJEAKXL.js';
+import './chunk-UJ24XW52.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=partial-sync-mutation-handler.js.map
+//# sourceMappingURL=partial-sync-mutation-handler.js.map

package/dist/partial-sync-mutation-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"partial-sync-mutation-handler.js"}

package/dist/partial-sync-predicate-match.d.ts

@@ -0,0 +1,8 @@
+import { RangeCondition } from './sync-protocol.js';
+import '@firtoz/db-helpers';
+import 'zod';
+
+declare function defaultPredicateColumnValue<TItem>(row: TItem, column: string): unknown;
+declare function matchesPredicate<TItem>(row: TItem, conditions: RangeCondition[], getColumnValue: (row: TItem, column: string) => unknown): boolean;
+
+export { defaultPredicateColumnValue, matchesPredicate };

package/dist/partial-sync-predicate-match.js

@@ -0,0 +1,4 @@
+export { defaultPredicateColumnValue, matchesPredicate } from './chunk-3EHHMLSV.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=partial-sync-predicate-match.js.map
+//# sourceMappingURL=partial-sync-predicate-match.js.map

package/dist/partial-sync-predicate-match.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"partial-sync-predicate-match.js"}

package/dist/partial-sync-row-key.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Row `id` values accepted by partial-sync (plain keys and ORM outputs such as drizzle-sqlite-wasm
+ * insert-schema types that are string-like but not assignable to `string | number` in TypeScript).
+ */
+type PartialSyncRowId = string | number | {
+    toString(): string;
+};
+/**
+ * Minimal object shape keyed by a partial-sync row id. Use when only identity matters (e.g. cache
+ * keys). Prefer {@link PartialSyncRowShape} for sync / partial-sync bridges and hooks.
+ */
+type PartialSyncRowRef = {
+    id: PartialSyncRowId;
+};
+/**
+ * Version watermark for sync / partial-sync (fingerprints, reconciliation). The **`updatedAt` key
+ * must exist** on the object; `null` or `undefined` mean “no ms watermark” at runtime (treated as
+ * `0` where a number is needed). Rows or ORM types **without** this property are not suitable for
+ * sync / partial-sync APIs—use {@link PartialSyncRowRef} only when you only need identity (e.g.
+ * cache keys). (`undefined` is included in the union so Drizzle `InferSelectModel` / optional
+ * columns remain assignable.)
+ */
+type PartialSyncRowVersion = {
+    updatedAt: number | Date | null | undefined;
+};
+/**
+ * Row shape required across {@link PartialSyncClientBridge}, {@link SyncClientBridge}, and React
+ * partial-sync hooks: stable id plus a mandatory {@link PartialSyncRowVersion} key (see there).
+ */
+type PartialSyncRowShape = PartialSyncRowRef & PartialSyncRowVersion;
+/** Max `updatedAt` as epoch ms; `null` / `undefined` → 0. */
+declare function partialSyncRowVersionWatermarkMs(row: PartialSyncRowVersion): number;
+/**
+ * Like {@link partialSyncRowVersionWatermarkMs} for decoded protocol payloads that are not yet
+ * narrowed to {@link PartialSyncRowVersion} (e.g. mutate-batch `value` fields). Missing
+ * `updatedAt` → 0.
+ */
+declare function partialSyncRowVersionWatermarkMsUnknown(row: unknown): number;
+declare function partialSyncRowKey(id: PartialSyncRowId): string | number;
+
+export { type PartialSyncRowId, type PartialSyncRowRef, type PartialSyncRowShape, type PartialSyncRowVersion, partialSyncRowKey, partialSyncRowVersionWatermarkMs, partialSyncRowVersionWatermarkMsUnknown };

package/dist/partial-sync-row-key.js

@@ -0,0 +1,4 @@
+export { partialSyncRowKey, partialSyncRowVersionWatermarkMs, partialSyncRowVersionWatermarkMsUnknown } from './chunk-UJ24XW52.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=partial-sync-row-key.js.map
+//# sourceMappingURL=partial-sync-row-key.js.map

package/dist/partial-sync-row-key.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"partial-sync-row-key.js"}

package/dist/partial-sync-server-bridge.d.ts

@@ -0,0 +1,102 @@
+import { SyncMessage } from '@firtoz/db-helpers';
+import { DeliveredRange, PartialSyncPatchResult } from './partial-sync-interest.js';
+import { SyncRangeSort, RangeCondition, SyncRange, SyncServerMessage, SyncClientMessage } from './sync-protocol.js';
+import { PartialSyncRowShape } from './partial-sync-row-key.js';
+import 'zod';
+
+type ClientQueryState<TItem extends PartialSyncRowShape = {
+    id: string;
+    updatedAt: null;
+}> = {
+    clientId: string;
+    deliveredRanges: DeliveredRange[];
+    /** Each entry is one predicate query's `conditions` (AND); OR across entries. */
+    predicateGroups: RangeCondition[][];
+    /** Row ids delivered to this client in the current interest session (for scoped deletes). */
+    deliveredRowIds: Set<string>;
+    pendingPatches: PartialSyncPatchResult<TItem>[];
+    streaming: boolean;
+};
+interface PartialSyncServerBridgeStore<TItem extends PartialSyncRowShape> {
+    queryRange: (options: {
+        sort: SyncRangeSort;
+        limit: number;
+        afterCursor: unknown | null;
+        chunkSize: number;
+    }) => AsyncIterable<TItem[]>;
+    queryByOffset: (options: {
+        sort: SyncRangeSort;
+        limit: number;
+        offset: number;
+        chunkSize: number;
+    }) => AsyncIterable<TItem[]>;
+    getTotalCount: () => Promise<number>;
+    getSortValue: (row: TItem, column: string) => unknown;
+    /** Predicate-based range (optional). */
+    queryByPredicate?: (options: {
+        conditions: RangeCondition[];
+        sort?: SyncRangeSort;
+        limit?: number;
+        chunkSize: number;
+    }) => AsyncIterable<TItem[]>;
+    getPredicateCount?: (conditions: RangeCondition[]) => Promise<number>;
+    /**
+     * Changes since `sinceVersion` within `range`. `null` if changelog cannot answer
+     * (caller should full-fetch).
+     */
+    changesSince?: (options: {
+        range: SyncRange;
+        sinceVersion: number;
+        chunkSize: number;
+    }) => Promise<{
+        changes: SyncMessage<TItem>[];
+        totalCount: number;
+    } | null>;
+    /** Authoritative row lookup (e.g. for {@link PartialSyncServerBridgeOptions.resolveMovedHint}). */
+    getRow?: (key: string | number) => Promise<TItem | undefined>;
+}
+type PartialSyncPushServerChangesOptions = {
+    /**
+     * Do not emit `rangePatch` to this client (e.g. the mutation author already applied the change
+     * locally and receives `ack` with the same payload).
+     */
+    excludeClientId?: string;
+};
+interface PartialSyncServerBridgeOptions<TItem extends PartialSyncRowShape> {
+    store: PartialSyncServerBridgeStore<TItem>;
+    sendToClient: (clientId: string, message: SyncServerMessage<TItem>) => void;
+    queryChunkSize?: number;
+    /** Multiplex key for sync messages. Default {@link DEFAULT_SYNC_COLLECTION_ID}. */
+    collectionId?: string;
+    /**
+     * Narrow client-requested predicate conditions (e.g. fog of war). Applied before querying and
+     * before interest tracking for predicate `rangeQuery`.
+     */
+    resolveClientVisibility?: (clientId: string, requestedConditions: RangeCondition[]) => RangeCondition[] | Promise<RangeCondition[]>;
+    /**
+     * Optional hint for rows that left the client's range during `rangeReconcile`.
+     * Return `null` to enforce fog of war (default when omitted).
+     */
+    resolveMovedHint?: (row: TItem, range: SyncRange) => Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
+}
+declare class PartialSyncServerBridge<TItem extends PartialSyncRowShape> {
+    #private;
+    private readonly options;
+    constructor(options: PartialSyncServerBridgeOptions<TItem>);
+    get collectionId(): string;
+    handleClientMessage(message: SyncClientMessage): Promise<void>;
+    pushServerChanges(changes: SyncMessage<TItem>[], options?: PartialSyncPushServerChangesOptions): Promise<void>;
+    /**
+     * Drop partial-sync interest for a disconnected client (prevents unbounded `#clientStates`
+     * growth and stale subscriptions).
+     */
+    removeClient(clientId: string): void;
+    /**
+     * Replace predicate interest for a client (server-authoritative visibility). Clears sort-range
+     * tracking; the next `rangeQuery` should re-establish delivered ranges from fresh chunks.
+     */
+    setClientVisibility(clientId: string, conditions: RangeCondition[]): void;
+    getClientState(clientId: string): ClientQueryState<TItem> | undefined;
+}
+
+export { type ClientQueryState, DeliveredRange, type PartialSyncPushServerChangesOptions, PartialSyncServerBridge, type PartialSyncServerBridgeOptions, type PartialSyncServerBridgeStore };

package/dist/partial-sync-server-bridge.js

@@ -0,0 +1,8 @@
+export { PartialSyncServerBridge } from './chunk-RDDS7JQW.js';
+import './chunk-BJJEAKXL.js';
+import './chunk-6EHROJFY.js';
+import './chunk-3EHHMLSV.js';
+import './chunk-UJ24XW52.js';
+import './chunk-HMLY7DHA.js';
+//# sourceMappingURL=partial-sync-server-bridge.js.map
+//# sourceMappingURL=partial-sync-server-bridge.js.map

package/dist/partial-sync-server-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"partial-sync-server-bridge.js"}

package/dist/react/constants.d.ts

@@ -0,0 +1,12 @@
+declare const DEFAULT_PAGE_LIMIT = 50;
+declare const DEFAULT_SEEK_ROW_GAP = 80;
+declare const DEFAULT_SEEK_COOLDOWN_MS = 200;
+/** Default quiet period before coalesced predicate `rangeQuery` after viewport motion. */
+declare const DEFAULT_VIEWPORT_RANGE_QUIET_MS = 72;
+/**
+ * Default max time between predicate `rangeQuery` calls while the viewport keeps changing
+ * (still issues a fetch even during continuous motion).
+ */
+declare const DEFAULT_VIEWPORT_RANGE_MAX_WAIT_MS = 200;
+
+export { DEFAULT_PAGE_LIMIT, DEFAULT_SEEK_COOLDOWN_MS, DEFAULT_SEEK_ROW_GAP, DEFAULT_VIEWPORT_RANGE_MAX_WAIT_MS, DEFAULT_VIEWPORT_RANGE_QUIET_MS };

package/dist/react/constants.js

@@ -0,0 +1,4 @@
+export { DEFAULT_PAGE_LIMIT, DEFAULT_SEEK_COOLDOWN_MS, DEFAULT_SEEK_ROW_GAP, DEFAULT_VIEWPORT_RANGE_MAX_WAIT_MS, DEFAULT_VIEWPORT_RANGE_QUIET_MS } from '../chunk-M5MJHS6A.js';
+import '../chunk-HMLY7DHA.js';
+//# sourceMappingURL=constants.js.map
+//# sourceMappingURL=constants.js.map

package/dist/react/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"constants.js"}

package/dist/react/index.d.ts

@@ -0,0 +1,19 @@
+export { DEFAULT_PAGE_LIMIT, DEFAULT_SEEK_COOLDOWN_MS, DEFAULT_SEEK_ROW_GAP, DEFAULT_VIEWPORT_RANGE_MAX_WAIT_MS, DEFAULT_VIEWPORT_RANGE_QUIET_MS } from './constants.js';
+export { CacheDisplayMode, PartialSyncCollection, PartialSyncItem, PartialSyncLiveCollection, PartialSyncRowSlot, PartialSyncRowSlotView, UsePartialSyncCollectionOptions, UsePartialSyncCollectionResult, UsePartialSyncViewportOptions, UsePartialSyncViewportResult, UsePartialSyncWindowOptions, UsePartialSyncWindowResult, UsePredicateFilteredRowsOptions, ViewportInfo } from './types.js';
+export { CreatePartialSyncAdapterConfig, NumericAxisSpec, PartialSyncViewportAdapter, PartialSyncViewportItem, PredicateSortSpec, betweenConditionsForNumericAxes, createPartialSyncAdapter } from './partial-sync-adapter.js';
+export { assertSyncUtils, computeFingerprintForIndexWindow, defaultPartialSyncVersionMs, getPartialSyncRowByMapId, tryIdsForIndexWindow } from './partial-sync-utils.js';
+export { usePartialSyncWindow } from './usePartialSyncWindow.js';
+export { usePartialSyncCollection } from './usePartialSyncCollection.js';
+export { usePartialSyncViewport } from './usePartialSyncViewport.js';
+export { usePredicateFilteredRows } from './usePredicateFilteredRows.js';
+export { PartialSyncRowRef, PartialSyncRowShape, PartialSyncRowVersion } from '../partial-sync-row-key.js';
+export { defaultPredicateColumnValue, matchesPredicate } from '../partial-sync-predicate-match.js';
+import '@tanstack/db';
+import '../cache-manager.js';
+import '../partial-sync-client-bridge.js';
+import '@firtoz/db-helpers';
+import '../sync-protocol.js';
+import 'zod';
+import '../partial-sync-interest.js';
+import '../connect-partial-sync.js';
+import '../sync-client-bridge.js';

package/dist/react/index.js

@@ -0,0 +1,17 @@
+export { usePartialSyncCollection } from '../chunk-I6RJWBGF.js';
+export { usePartialSyncViewport } from '../chunk-BGJH6PH2.js';
+export { usePartialSyncWindow } from '../chunk-O3KBDCEI.js';
+export { usePredicateFilteredRows } from '../chunk-YD5LVGWX.js';
+import '../chunk-43KYAIKY.js';
+export { DEFAULT_PAGE_LIMIT, DEFAULT_SEEK_COOLDOWN_MS, DEFAULT_SEEK_ROW_GAP, DEFAULT_VIEWPORT_RANGE_MAX_WAIT_MS, DEFAULT_VIEWPORT_RANGE_QUIET_MS } from '../chunk-M5MJHS6A.js';
+export { betweenConditionsForNumericAxes, createPartialSyncAdapter } from '../chunk-6X3434GJ.js';
+export { assertSyncUtils, computeFingerprintForIndexWindow, defaultPartialSyncVersionMs, getPartialSyncRowByMapId, tryIdsForIndexWindow } from '../chunk-4BEXLBCH.js';
+import '../chunk-5V6BSQAB.js';
+import '../chunk-XC4QNFSQ.js';
+import '../chunk-P3JOTUAB.js';
+import '../chunk-BJJEAKXL.js';
+export { defaultPredicateColumnValue, matchesPredicate } from '../chunk-3EHHMLSV.js';
+import '../chunk-UJ24XW52.js';
+import '../chunk-HMLY7DHA.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/react/partial-sync-adapter.d.ts

@@ -0,0 +1,40 @@
+import { PartialSyncRowShape } from '../partial-sync-row-key.js';
+import { RangeCondition, SyncRangeSort } from '../sync-protocol.js';
+import '@firtoz/db-helpers';
+import 'zod';
+
+/** Row shape compatible with partial-sync viewport hooks (matches {@link PartialSyncItem}). */
+type PartialSyncViewportItem = PartialSyncRowShape;
+type PredicateSortSpec<TSortColumn extends string> = {
+    column: TSortColumn;
+    direction: SyncRangeSort["direction"];
+};
+/**
+ * Bundles predicate ↔ viewport mapping, optional prefetch expansion, and sort accessors for
+ * {@link usePartialSyncViewport} + {@link usePredicateFilteredRows}.
+ */
+type PartialSyncViewportAdapter<TItem extends PartialSyncViewportItem, TViewport, TSortColumn extends keyof TItem & string> = {
+    toConditions: (viewport: TViewport) => RangeCondition[];
+    expandViewport: (viewport: TViewport, pad: number) => TViewport;
+    sort: PredicateSortSpec<TSortColumn>;
+    getSortValue: (row: TItem, column: TSortColumn) => unknown;
+};
+type CreatePartialSyncAdapterConfig<TItem extends PartialSyncViewportItem, TViewport, TSortColumn extends keyof TItem & string> = {
+    toConditions: (viewport: TViewport) => RangeCondition[];
+    /** Widen viewport before server `rangeQuery`. Default: identity (no prefetch). */
+    expandViewport?: (viewport: TViewport, pad: number) => TViewport;
+    sort: PredicateSortSpec<TSortColumn>;
+    getSortValue: (row: TItem, column: TSortColumn) => unknown;
+};
+declare function createPartialSyncAdapter<TItem extends PartialSyncViewportItem, TViewport, TSortColumn extends keyof TItem & string>(config: CreatePartialSyncAdapterConfig<TItem, TViewport, TSortColumn>): PartialSyncViewportAdapter<TItem, TViewport, TSortColumn>;
+type NumericAxisSpec<TViewport> = {
+    readonly column: string;
+    readonly min: (viewport: TViewport) => number;
+    readonly max: (viewport: TViewport) => number;
+};
+/**
+ * Builds `between` {@link RangeCondition}s from numeric axis accessors (N-D box / interval per column).
+ */
+declare function betweenConditionsForNumericAxes<TViewport>(viewport: TViewport, axes: readonly NumericAxisSpec<TViewport>[]): RangeCondition[];
+
+export { type CreatePartialSyncAdapterConfig, type NumericAxisSpec, type PartialSyncViewportAdapter, type PartialSyncViewportItem, type PredicateSortSpec, betweenConditionsForNumericAxes, createPartialSyncAdapter };

package/dist/react/partial-sync-adapter.js

@@ -0,0 +1,4 @@
+export { betweenConditionsForNumericAxes, createPartialSyncAdapter } from '../chunk-6X3434GJ.js';
+import '../chunk-HMLY7DHA.js';
+//# sourceMappingURL=partial-sync-adapter.js.map
+//# sourceMappingURL=partial-sync-adapter.js.map

package/dist/react/partial-sync-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"partial-sync-adapter.js"}

package/dist/react/partial-sync-utils.d.ts

@@ -0,0 +1,42 @@
+import { CollectionUtils } from '@firtoz/db-helpers';
+import { UtilsRecord } from '@tanstack/db';
+import { RangeFingerprint } from '../sync-protocol.js';
+import { PartialSyncItem, PartialSyncCollection } from './types.js';
+export { defaultPredicateColumnValue, matchesPredicate } from '../partial-sync-predicate-match.js';
+import 'zod';
+import '../cache-manager.js';
+import '../partial-sync-row-key.js';
+import '../partial-sync-client-bridge.js';
+import '../partial-sync-interest.js';
+import './partial-sync-adapter.js';
+import '../connect-partial-sync.js';
+import '../sync-client-bridge.js';
+
+/** Merge every row currently in the collection into the bridge cache (id set only). Idempotent. */
+declare function primePartialSyncBridgeCachedIdsFromCollection<TItem extends PartialSyncItem>(bridge: {
+    seedHydratedLocalRows: (rows: readonly TItem[]) => void;
+}, collection: Pick<PartialSyncCollection<TItem>, "entries">): void;
+/**
+ * TanStack `Collection` types `utils` as {@link UtilsRecord}. This narrows to sync helpers when
+ * present (e.g. after `memoryCollectionOptions` / Drizzle sync config).
+ */
+declare function assertSyncUtils<TItem>(utils: UtilsRecord): CollectionUtils<TItem>;
+/** Default fingerprint version: max `updatedAt` as epoch ms. */
+declare function defaultPartialSyncVersionMs<TItem extends PartialSyncItem>(row: TItem): number;
+/**
+ * Resolve a row for an id stored in the partial-sync index map. Uses {@link PartialSyncCollection.get}
+ * first; if that misses (e.g. key type / boxed string mismatch vs TanStack’s internal map), scans
+ * {@link PartialSyncCollection.entries} by `String(key)`.
+ */
+declare function getPartialSyncRowByMapId<TItem extends PartialSyncItem>(collection: PartialSyncCollection<TItem>, id: string | number): TItem | undefined;
+/**
+ * Returns consecutive row ids for `[offset, offset + want)` if all present in the map; else null.
+ */
+declare function tryIdsForIndexWindow<TKey extends string | number>(map: Map<number, TKey>, offset: number, want: number, totalCount: number): TKey[] | null;
+/**
+ * Fingerprint for reconciliation when every index in `[offset, offset + want)` is mapped and rows
+ * exist in the collection.
+ */
+declare function computeFingerprintForIndexWindow<TItem extends PartialSyncItem>(collection: PartialSyncCollection<TItem>, map: Map<number, string | number>, offset: number, want: number, getVersionMs?: (row: TItem) => number): RangeFingerprint | undefined;
+
+export { assertSyncUtils, computeFingerprintForIndexWindow, defaultPartialSyncVersionMs, getPartialSyncRowByMapId, primePartialSyncBridgeCachedIdsFromCollection, tryIdsForIndexWindow };

package/dist/react/partial-sync-utils.js

@@ -0,0 +1,5 @@
+export { assertSyncUtils, computeFingerprintForIndexWindow, defaultPartialSyncVersionMs, getPartialSyncRowByMapId, primePartialSyncBridgeCachedIdsFromCollection, tryIdsForIndexWindow } from '../chunk-4BEXLBCH.js';
+export { defaultPredicateColumnValue, matchesPredicate } from '../chunk-3EHHMLSV.js';
+import '../chunk-HMLY7DHA.js';
+//# sourceMappingURL=partial-sync-utils.js.map
+//# sourceMappingURL=partial-sync-utils.js.map

package/dist/react/partial-sync-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"partial-sync-utils.js"}