@stratasync/react 0.2.0

package/dist/hooks/use-query.js

@@ -0,0 +1,302 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useSyncClientInstance, useSyncReady } from "./use-sync-client.js";
+const captureSnapshots = (items) => items.map((item) => {
+    const record = item;
+    return { id: record.id, updatedAt: record.updatedAt };
+});
+/**
+ * Compares new query result items against previously-captured snapshots.
+ * Returns true if every item matches its snapshot by id + updatedAt.
+ *
+ * Unlike a direct reference comparison, this detects in-place mutations
+ * because the snapshot stores *copied* values from the time data was last
+ * committed to React state.
+ */
+const isQueryResultEqual = (snapshots, next) => {
+    if (snapshots.length !== next.length) {
+        return false;
+    }
+    for (let i = 0; i < snapshots.length; i += 1) {
+        const s = snapshots[i];
+        const n = next[i];
+        if (s?.id !== n.id) {
+            return false;
+        }
+        if (s?.updatedAt !== n.updatedAt) {
+            return false;
+        }
+    }
+    return true;
+};
+/**
+ * Default empty state for a query that hasn't loaded data yet.
+ */
+const emptyQueryState = (isLoading) => ({
+    data: [],
+    hasMore: false,
+    isLoading,
+    totalCount: undefined,
+});
+/**
+ * Cast UseQueryOptions<T> to QueryOptions compatible with the identity map's
+ * `T & Record<string, unknown>` shape.
+ */
+const buildSyncQueryOptions = (opts) => ({
+    includeArchived: opts.includeArchived,
+    limit: opts.limit,
+    offset: opts.offset,
+    orderBy: opts.orderBy,
+    where: opts.where,
+});
+/**
+ * Synchronously query from a raw Map (avoids flash of empty state)
+ */
+const querySyncFromMap = (map, options = {}) => {
+    let results = [...map.values()];
+    if (options.where) {
+        results = results.filter(options.where);
+    }
+    if (!options.includeArchived) {
+        results = results.filter((item) => !item.archivedAt);
+    }
+    const totalCount = results.length;
+    if (options.orderBy) {
+        results = results.toSorted(options.orderBy);
+    }
+    if (options.offset && options.offset > 0) {
+        results = results.slice(options.offset);
+    }
+    let hasMore = false;
+    if (options.limit && options.limit > 0) {
+        hasMore = results.length > options.limit;
+        results = results.slice(0, options.limit);
+    }
+    return { data: results, hasMore, totalCount };
+};
+/**
+ * Hook to query models with filtering, sorting, and pagination
+ *
+ * @param modelName - Name of the model to query
+ * @param options - Query options including filters, sorting, and pagination
+ * @returns UseQueryResult with data array, loading state, and metadata
+ *
+ * @example
+ * ```tsx
+ * function TaskList({ projectId }: { projectId: string }) {
+ *   const { data: tasks, isLoading, hasMore } = useQuery<Task>('Task', {
+ *     where: (task) => task.projectId === projectId,
+ *     orderBy: (a, b) => a.createdAt - b.createdAt,
+ *     limit: 20,
+ *   });
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <ul>
+ *       {tasks.map((task) => (
+ *         <li key={task.id}>{task.title}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export const useQuery = (modelName, options = {}) => {
+    const client = useSyncClientInstance();
+    const isReady = useSyncReady();
+    // Compute initial state from identity map (only runs on mount via lazy useState)
+    const computeState = () => {
+        if (options.skip) {
+            return emptyQueryState(false);
+        }
+        if (!isReady) {
+            return emptyQueryState(true);
+        }
+        const map = client.getIdentityMap(modelName);
+        if (map.size === 0) {
+            return emptyQueryState(true);
+        }
+        const result = querySyncFromMap(map, buildSyncQueryOptions(options));
+        return {
+            data: result.data,
+            hasMore: result.hasMore,
+            isLoading: false,
+            totalCount: result.totalCount,
+        };
+    };
+    // Lazy initializers — only run on mount, preventing MobX tracking on re-renders
+    const initialRef = useRef(null);
+    if (initialRef.current === null) {
+        initialRef.current = computeState();
+    }
+    const initial = initialRef.current;
+    const [data, setData] = useState(initial.data);
+    const [isLoading, setIsLoading] = useState(initial.isLoading);
+    const [error, setError] = useState(null);
+    const [totalCount, setTotalCount] = useState(initial.totalCount);
+    const [hasMore, setHasMore] = useState(initial.hasMore);
+    // Use ref to track options to avoid infinite loops
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    // Track current data for structural equality checks (avoids unnecessary re-renders)
+    const dataRef = useRef(initial.data);
+    // Snapshot of id+updatedAt per item — detects in-place identity-map mutations
+    const snapshotsRef = useRef(captureSnapshots(initial.data));
+    // Track if we have data to avoid setting loading state when refreshing cached data
+    const hasDataRef = useRef(initial.data.length > 0);
+    // Ref mirrors for metadata state — only call setters when values actually change
+    const totalCountRef = useRef(initial.totalCount);
+    const hasMoreRef = useRef(initial.hasMore);
+    const isLoadingRef = useRef(initial.isLoading);
+    const errorRef = useRef(null);
+    // Microtask debounce flag — coalesces rapid modelChange events into one refresh
+    const pendingRefreshRef = useRef(false);
+    const requestVersionRef = useRef(0);
+    /**
+     * Apply a query result to React state. Only calls setters when values
+     * actually changed, preventing unnecessary re-renders.
+     */
+    const applyResult = useCallback((resultData, resultTotalCount, resultHasMore, applyOptions = {}) => {
+        if (applyOptions.forceDataUpdate ||
+            !isQueryResultEqual(snapshotsRef.current, resultData)) {
+            snapshotsRef.current = captureSnapshots(resultData);
+            dataRef.current = resultData;
+            setData(resultData);
+        }
+        if (resultTotalCount !== totalCountRef.current) {
+            totalCountRef.current = resultTotalCount;
+            setTotalCount(resultTotalCount);
+        }
+        if (resultHasMore !== hasMoreRef.current) {
+            hasMoreRef.current = resultHasMore;
+            setHasMore(resultHasMore);
+        }
+        hasDataRef.current = resultData.length > 0;
+        if (isLoadingRef.current !== false) {
+            isLoadingRef.current = false;
+            setIsLoading(false);
+        }
+        if (errorRef.current !== null) {
+            errorRef.current = null;
+            setError(null);
+        }
+    }, []);
+    /** Clear data and stop loading (used when query is skipped). */
+    const clearSkipped = useCallback(() => {
+        if (dataRef.current.length > 0) {
+            dataRef.current = [];
+            snapshotsRef.current = [];
+            setData([]);
+        }
+        if (isLoadingRef.current !== false) {
+            isLoadingRef.current = false;
+            setIsLoading(false);
+        }
+    }, []);
+    const executeQuery = useCallback(async () => {
+        if (optionsRef.current.skip) {
+            requestVersionRef.current += 1;
+            clearSkipped();
+            return;
+        }
+        requestVersionRef.current += 1;
+        const requestVersion = requestVersionRef.current;
+        // Only show loading if we don't already have cached data
+        // This prevents the flash of empty state when refreshing
+        if (!hasDataRef.current) {
+            isLoadingRef.current = true;
+            setIsLoading(true);
+        }
+        if (errorRef.current !== null) {
+            errorRef.current = null;
+            setError(null);
+        }
+        try {
+            const queryOptions = {
+                includeArchived: optionsRef.current.includeArchived,
+                limit: optionsRef.current.limit,
+                offset: optionsRef.current.offset,
+                orderBy: optionsRef.current.orderBy,
+                where: optionsRef.current.where,
+            };
+            const result = await client.query(modelName, queryOptions);
+            if (requestVersion !== requestVersionRef.current) {
+                return;
+            }
+            applyResult(result.data, result.totalCount, result.hasMore);
+        }
+        catch (queryError) {
+            if (requestVersion !== requestVersionRef.current) {
+                return;
+            }
+            const newError = queryError instanceof Error
+                ? queryError
+                : new Error(String(queryError));
+            errorRef.current = newError;
+            setError(newError);
+            // Preserve stale data on refresh errors to avoid UI flash.
+            hasDataRef.current = dataRef.current.length > 0;
+            if (isLoadingRef.current !== false) {
+                isLoadingRef.current = false;
+                setIsLoading(false);
+            }
+        }
+    }, [client, modelName, applyResult, clearSkipped]);
+    // Synchronous refresh — reads identity map and updates React state immediately
+    const refreshSync = useCallback(() => {
+        if (optionsRef.current.skip) {
+            clearSkipped();
+            return;
+        }
+        const map = client.getIdentityMap(modelName);
+        const result = querySyncFromMap(map, buildSyncQueryOptions(optionsRef.current));
+        applyResult(result.data, result.totalCount, result.hasMore);
+    }, [client, modelName, applyResult, clearSkipped]);
+    useEffect(() => {
+        if (isReady && !options.skip) {
+            executeQuery();
+        }
+        else if (options.skip) {
+            requestVersionRef.current += 1;
+            clearSkipped();
+        }
+    }, [isReady, options.skip, executeQuery, clearSkipped]);
+    useEffect(() => () => {
+        requestVersionRef.current += 1;
+    }, []);
+    useEffect(() => {
+        if (!isReady || options.skip) {
+            return;
+        }
+        const unsubscribe = client.onEvent((event) => {
+            // Coalesce rapid modelChange events (e.g. a delta packet with many
+            // actions for the same model type) into a single refreshSync call.
+            if (event.type === "modelChange" &&
+                event.modelName === modelName &&
+                !pendingRefreshRef.current) {
+                pendingRefreshRef.current = true;
+                queueMicrotask(() => {
+                    pendingRefreshRef.current = false;
+                    refreshSync();
+                });
+            }
+        });
+        return () => {
+            unsubscribe();
+            pendingRefreshRef.current = false;
+        };
+    }, [client, modelName, isReady, options.skip, refreshSync]);
+    return {
+        data,
+        error,
+        hasMore,
+        isLoading,
+        refresh: executeQuery,
+        totalCount,
+    };
+};
+/**
+ * Hook to query all models of a type
+ */
+export const useQueryAll = (modelName, options = {}) => useQuery(modelName, options);
+//# sourceMappingURL=use-query.js.map

package/dist/hooks/use-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-query.js","sourceRoot":"","sources":["../../src/hooks/use-query.ts"],"names":[],"mappings":"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"}

package/dist/hooks/use-sync-client.d.ts

@@ -0,0 +1,25 @@
+import type { SyncContextValue, SyncStatusContextValue } from "../types.js";
+export declare const useSyncStatusValue: () => SyncStatusContextValue;
+export declare const useSyncBacklogValue: () => number;
+/**
+ * Hook to access the sync client from context
+ * @throws Error if used outside of SyncProvider
+ */
+export declare const useSyncClient: () => SyncContextValue;
+/**
+ * Hook to access just the sync client instance
+ */
+export declare const useSyncClientInstance: () => SyncContextValue["client"];
+/**
+ * Hook to check if the sync client is ready
+ */
+export declare const useSyncReady: () => boolean;
+/**
+ * Hook to get the current sync state
+ */
+export declare const useSyncState: () => SyncContextValue["state"];
+/**
+ * Hook to get the latest sync error.
+ */
+export declare const useSyncError: () => Error | null;
+//# sourceMappingURL=use-sync-client.d.ts.map

package/dist/hooks/use-sync-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-sync-client.d.ts","sourceRoot":"","sources":["../../src/hooks/use-sync-client.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAY5E,eAAO,MAAM,kBAAkB,QAAO,sBAMrC,CAAC;AAEF,eAAO,MAAM,mBAAmB,QAAO,MAItC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAO,gBAMhC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,QAAO,gBAAgB,CAAC,QAAQ,CACzC,CAAC;AAE1B;;GAEG;AACH,eAAO,MAAM,YAAY,QAAO,OAAuC,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,YAAY,QAAO,gBAAgB,CAAC,OAAO,CAC5B,CAAC;AAE7B;;GAEG;AACH,eAAO,MAAM,YAAY,QAAO,KAAK,GAAG,IAAkC,CAAC"}

package/dist/hooks/use-sync-client.js

@@ -0,0 +1,49 @@
+import { useContext } from "react";
+import { SyncBacklogContext, SyncClientContext, SyncStatusContext, } from "../context.js";
+const SYNC_PROVIDER_ERROR = "useSyncClient must be used within a SyncProvider";
+const useRequiredSyncClient = () => {
+    const client = useContext(SyncClientContext);
+    if (!client) {
+        throw new Error(SYNC_PROVIDER_ERROR);
+    }
+    return client;
+};
+export const useSyncStatusValue = () => {
+    const status = useContext(SyncStatusContext);
+    if (!status) {
+        throw new Error(SYNC_PROVIDER_ERROR);
+    }
+    return status;
+};
+export const useSyncBacklogValue = () => {
+    // Ensure hooks still throw a clear provider error when used outside context.
+    useRequiredSyncClient();
+    return useContext(SyncBacklogContext);
+};
+/**
+ * Hook to access the sync client from context
+ * @throws Error if used outside of SyncProvider
+ */
+export const useSyncClient = () => {
+    const client = useRequiredSyncClient();
+    const status = useSyncStatusValue();
+    const backlog = useSyncBacklogValue();
+    return { backlog, client, ...status };
+};
+/**
+ * Hook to access just the sync client instance
+ */
+export const useSyncClientInstance = () => useRequiredSyncClient();
+/**
+ * Hook to check if the sync client is ready
+ */
+export const useSyncReady = () => useSyncStatusValue().isReady;
+/**
+ * Hook to get the current sync state
+ */
+export const useSyncState = () => useSyncStatusValue().state;
+/**
+ * Hook to get the latest sync error.
+ */
+export const useSyncError = () => useSyncStatusValue().error;
+//# sourceMappingURL=use-sync-client.js.map

package/dist/hooks/use-sync-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-sync-client.js","sourceRoot":"","sources":["../../src/hooks/use-sync-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAEnC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAGvB,MAAM,mBAAmB,GAAG,kDAAkD,CAAC;AAE/E,MAAM,qBAAqB,GAAG,GAA+B,EAAE;IAC7D,MAAM,MAAM,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAA2B,EAAE;IAC7D,MAAM,MAAM,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAW,EAAE;IAC9C,6EAA6E;IAC7E,qBAAqB,EAAE,CAAC;IACxB,OAAO,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACxC,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAqB,EAAE;IAClD,MAAM,MAAM,GAAG,qBAAqB,EAAE,CAAC;IACvC,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAC;IACpC,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;IAEtC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;AACxC,CAAC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAA+B,EAAE,CACpE,qBAAqB,EAAE,CAAC;AAE1B;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAY,EAAE,CAAC,kBAAkB,EAAE,CAAC,OAAO,CAAC;AAExE;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAA8B,EAAE,CAC1D,kBAAkB,EAAE,CAAC,KAAK,CAAC;AAE7B;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAiB,EAAE,CAAC,kBAAkB,EAAE,CAAC,KAAK,CAAC"}

package/dist/hooks/use-yjs-document.d.ts

@@ -0,0 +1,108 @@
+/**
+ * React hook for Yjs collaborative document editing.
+ */
+import type { Doc as YDoc } from "yjs";
+/**
+ * Document key identifying a collaborative field.
+ */
+export interface DocumentKey {
+    entityType: string;
+    entityId: string;
+    fieldName: string;
+}
+/**
+ * Connection state for Yjs document.
+ */
+export type YjsConnectionState = "disconnected" | "connecting" | "syncing" | "connected";
+/**
+ * Session participant information.
+ */
+interface SessionParticipant {
+    userId: string;
+    isEditing: boolean;
+}
+/**
+ * Session state for a collaborative document.
+ */
+export interface YjsSessionState {
+    active: boolean;
+    participants: SessionParticipant[];
+}
+/**
+ * Options for useYjsDocument hook.
+ */
+export interface UseYjsDocumentOptions {
+    /** Initial content if document is empty */
+    initialContent?: string;
+    /** Whether to automatically connect when component mounts */
+    autoConnect?: boolean;
+    /** Whether to start in editing mode */
+    editing?: boolean;
+    /** Skip connecting (useful for conditional loading) */
+    skip?: boolean;
+}
+/**
+ * Result of useYjsDocument hook.
+ */
+export interface UseYjsDocumentResult {
+    /** The Yjs document instance */
+    doc: YDoc | null;
+    /** Current connection state */
+    connectionState: YjsConnectionState;
+    /** Whether the document is connected for collaboration */
+    isConnected: boolean;
+    /** Whether there's an active collaborative session */
+    isSessionActive: boolean;
+    /** Current session participants */
+    participants: SessionParticipant[];
+    /** Current content of the document */
+    content: string;
+    /** Connect to the document */
+    connect: () => void;
+    /** Disconnect from the document */
+    disconnect: () => void;
+    /** Signal editing focus */
+    focus: () => void;
+    /** Signal editing blur */
+    blur: () => void;
+    /** Any error that occurred */
+    error: Error | null;
+}
+/**
+ * Hook to manage a Yjs collaborative document.
+ *
+ * @param docKey - Document key identifying the field
+ * @param options - Hook options
+ * @returns UseYjsDocumentResult with document, connection state, and controls
+ *
+ * @example
+ * ```tsx
+ * function TaskDescriptionEditor({ taskId }: { taskId: string }) {
+ *   const {
+ *     doc,
+ *     isSessionActive,
+ *     participants,
+ *   } = useYjsDocument(
+ *     { entityType: 'Task', entityId: taskId, fieldName: 'description' },
+ *     { autoConnect: true, initialContent: task.description }
+ *   );
+ *
+ *   // doc becomes available after the first render (even offline).
+ *   // Initial content is seeded into the local Y.Doc during connect(),
+ *   // so the editor shows content immediately without waiting for the server.
+ *   return (
+ *     <div>
+ *       {isSessionActive && (
+ *         <div>
+ *           Collaborating with: {participants.map(p => p.userId).join(', ')}
+ *         </div>
+ *       )}
+ *       {doc && <TiptapEditor doc={doc} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare const useYjsDocument: (docKey: DocumentKey, options?: UseYjsDocumentOptions) => UseYjsDocumentResult;
+export {};
+//# sourceMappingURL=use-yjs-document.d.ts.map

package/dist/hooks/use-yjs-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-yjs-document.d.ts","sourceRoot":"","sources":["../../src/hooks/use-yjs-document.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,GAAG,IAAI,IAAI,EAAE,MAAM,KAAK,CAAC;AAIvC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,cAAc,GACd,YAAY,GACZ,SAAS,GACT,WAAW,CAAC;AAEhB;;GAEG;AACH,UAAU,kBAAkB;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,uCAAuC;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,gCAAgC;IAChC,GAAG,EAAE,IAAI,GAAG,IAAI,CAAC;IACjB,+BAA+B;IAC/B,eAAe,EAAE,kBAAkB,CAAC;IACpC,0DAA0D;IAC1D,WAAW,EAAE,OAAO,CAAC;IACrB,sDAAsD;IACtD,eAAe,EAAE,OAAO,CAAC;IACzB,mCAAmC;IACnC,YAAY,EAAE,kBAAkB,EAAE,CAAC;IACnC,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,mCAAmC;IACnC,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,cAAc,GACzB,QAAQ,WAAW,EACnB,UAAS,qBAA0B,KAClC,oBAuMF,CAAC"}