@docstack/react 0.0.7 → 0.1.0

package/src/hooks/domain.ts

@@ -1,7 +1,6 @@
 import { useContext, useCallback, useEffect, useRef, useState } from "react";
 import { DocStackContext } from "../components/StackProvider/index.js";
-import { Class } from "@docstack/client";
-import {Document,  Domain,  DomainModel,  RelationDocument,  SelectAST, UnionAST} from "@docstack/shared";
+import { Class, Domain, Document, DomainModel, RelationDocument, SelectAST, UnionAST } from "@docstack/client";
 
 /**
  * Hook to create a new Domain in a specific stack.
@@ -38,7 +37,9 @@ export const useDomainCreate = (stack: string) => {
                 if (!docStack) {
                     // Handle the case where the provider is not yet initialized or missing
                     // You could throw an error or return an empty state.
-                    console.error('useDomainCreate must be used within a DocStackProvider.');
+                    // Null until the provider's `ready` event; that is startup,
+                    // not a missing provider. See ADR-0022.
+                    console.warn('useDomainCreate - stack not ready yet; the call was ignored.');
                     // setLoading(false);
                     return Promise.resolve(null);
                 }
@@ -98,7 +99,10 @@ export const useDomainList = (stack: string, selector: {[key: string]: any}) =>
     useEffect(() => {
         // Only run if the docStack is available and a className is provided
         if (!docStack) {
-            setLoading(false);
+            // Null until the provider's `ready` event: startup, not a missing
+            // provider. Reporting "loaded" here is indistinguishable from a genuinely
+            // empty result. See ADR-0022.
+            setLoading(true);
             return;
         }
 
@@ -132,20 +136,30 @@ export const useDomainList = (stack: string, selector: {[key: string]: any}) =>
             return;
         }
 
+        let cancelled = false;
+        let attached: EventListener | null = null;
+
         const runQueryAndListen = async () => {
             setLoading(true);
             try {
                 const stackInstance = docStack!.getStack(stack)!;
                 const initialDomainModelList = await originClass.getCards(selector) as DomainModel[];
                 const initDomainList = await Promise.all(initialDomainModelList.map(async (dm) => await Domain.buildFromModel(stackInstance, dm)));
-                
+
+                if (cancelled) {
+                    // Torn down mid-query; these were built anyway and each holds a live
+                    // subscription until it is closed.
+                    for (const domain of initDomainList) domain.close();
+                    return;
+                }
                 domainListRef.current = initDomainList;
                 setDomainList(domainListRef.current);
             } catch (err: any) {
-                setError(err);
+                if (!cancelled) setError(err);
             } finally {
-                setLoading(false);
+                if (!cancelled) setLoading(false);
             }
+            if (cancelled) return;
 
             const changeListener = (change: CustomEvent) => {
                 const doc = change.detail.doc;
@@ -176,14 +190,22 @@ export const useDomainList = (stack: string, selector: {[key: string]: any}) =>
                 setDomainList([...domainListRef.current])
             };
 
-            originClass.addEventListener('doc', changeListener as EventListener);
-
-            return () => {
-                originClass.removeEventListener('doc', changeListener as EventListener);
-            };
+            attached = changeListener as EventListener;
+            originClass.addEventListener('doc', attached);
         };
 
         runQueryAndListen();
+
+        // The cleanup used to be returned from `runQueryAndListen`, where React never saw
+        // it: the listener stayed attached and the built domains stayed subscribed.
+        return () => {
+            cancelled = true;
+            if (attached) originClass.removeEventListener('doc', attached);
+            // Guarded: the change handler above pushes the raw document for a domain it
+            // has not seen before, so the list is not uniformly Domain instances.
+            for (const domain of domainListRef.current) domain?.close?.();
+            domainListRef.current = [];
+        };
     }, [originClass, JSON.stringify(selector)]); // Dependency on classObj and query
 
     return { domainList, loading, error };
@@ -219,8 +241,14 @@ export const useDomain = (stack: string, domainName: string) => {
         if (!docStack) {
             // Handle the case where the provider is not yet initialized or missing
             // You could throw an error or return an empty state.
-            console.error('useDomain must be used within a DocStackProvider.');
-            setLoading(false);
+            // The provider publishes `null` into the context until its `ready`
+            // event fires, so this is the normal startup window, not a missing
+            // provider. Reporting it as one sends the reader hunting for a bug
+            // that is not there - and `setLoading(false)` was worse than the
+            // message: it tells a consumer "loaded, and empty" during startup,
+            // which is indistinguishable from a genuinely empty result. See
+            // ADR-0022.
+            setLoading(true);
             return;
         }
 
@@ -299,7 +327,16 @@ export const useDomainRelations = (stack: string, domainName: string, query = {}
 
     useEffect(() => {
         // Only run if the docStack is available and a className is provided
-        if (!docStack || !domainName) {
+        if (!docStack) {
+            // Null until the provider's `ready` event: startup, not a missing
+            // provider. Reporting "loaded" here is indistinguishable from a genuinely
+            // empty result. See ADR-0022.
+            setLoading(true);
+            return;
+        }
+        if (!domainName) {
+            // A genuinely absent domainName is "nothing to load", which is a settled state -
+            // unlike the pre-ready window above.
             setLoading(false);
             return;
         }
@@ -334,17 +371,22 @@ export const useDomainRelations = (stack: string, domainName: string, query = {}
             return;
         }
 
+        let cancelled = false;
+        let attached: EventListener | null = null;
+
         const runQueryAndListen = async () => {
             setLoading(true);
             try {
                 const initialDocs = await domain.getRelations(query);
+                if (cancelled) return;
                 docsRef.current = initialDocs;
                 setDocs(docsRef.current);
             } catch (err: any) {
-                setError(err);
+                if (!cancelled) setError(err);
             } finally {
-                setLoading(false);
+                if (!cancelled) setLoading(false);
             }
+            if (cancelled) return;
 
             const changeListener = (change: CustomEvent) => {
                 const doc = change.detail.doc;
@@ -378,14 +420,18 @@ export const useDomainRelations = (stack: string, domainName: string, query = {}
                 setDocs([...docsRef.current])
             };
 
-            domain.addEventListener('doc', changeListener as EventListener);
-
-            return () => {
-                domain.removeEventListener('doc', changeListener as EventListener);
-            };
+            attached = changeListener as EventListener;
+            domain.addEventListener('doc', attached);
         };
 
         runQueryAndListen();
+
+        // The cleanup used to be returned from `runQueryAndListen`, so React never
+        // received it and each query change left another listener on the domain.
+        return () => {
+            cancelled = true;
+            if (attached) domain.removeEventListener('doc', attached);
+        };
     }, [domain, JSON.stringify(query)]); // Dependency on classObj and query
 
     return { docs, loading, error };

package/src/hooks/index.ts

@@ -1,15 +1,21 @@
 // src/hooks/useFind.js
-import { useContext, useEffect, useRef, useState } from 'react';
+import { useCallback, useContext, useEffect, useRef, useState } from 'react';
 import { DocStackContext } from '../components/StackProvider/index.js';
-import { Document, SelectAST, UnionAST } from '@docstack/shared';
+import { Document, SelectAST, UnionAST, collectQueryClasses } from '@docstack/client';
 
 /**
  * Hook to execute a SQL query against a specific stack.
  * 
+ * Live by default: the query re-runs when a document changes in a class it actually
+ * reads, derived from the `ast` the query itself returns. It used to run once and never
+ * again, which was invisible beside `useClassDocs` in the same import - one list
+ * refreshing next to one that did not. See ADR-0025.
+ *
  * @param stack - The name of the stack to query.
  * @param sql - The SQL query string.
- * @param params - Optional parameters for the SQL query.
- * @returns Object containing the query result (rows and AST), loading state, and error.
+ * @param params - Values for the query's `?` placeholders.
+ * @param options - See {@link QuerySQLOptions}; `{ live: false }` for a snapshot.
+ * @returns The query result (rows and AST), loading state, error, and `refetch`.
  * 
  * @example
  * ```tsx
@@ -26,60 +32,117 @@ import { Document, SelectAST, UnionAST } from '@docstack/shared';
  * };
  * ```
  */
-export const useQuerySQL = (stack: string, sql: string, ...params: any[]) => {
+export type QuerySQLOptions = {
+    /**
+     * Re-run when a document changes in a class this query reads. Defaults to `true`.
+     *
+     * Pass `false` for a deliberate snapshot - and say so at the call site, which the
+     * previous behaviour never did.
+     */
+    live?: boolean;
+    /** Coalesce a burst of changes into one re-run, in milliseconds. Defaults to 150. */
+    coalesceMs?: number;
+};
+
+export const useQuerySQL = (
+    stack: string,
+    sql: string,
+    params: any[] = [],
+    options: QuerySQLOptions = {},
+) => {
+    const { live = true, coalesceMs = 150 } = options;
     const docStack = useContext(DocStackContext);
     const [result, setResult] = useState<{ rows: any[]; ast: (SelectAST | UnionAST)[] | null; }>({ rows: [], ast: [] });
     const [loading, setLoading] = useState(true);
-    const [error, setError] = useState(null);
-    // [TODO] Solve bounce of component because of StrictMode or other reasons
-    const queryRef = useRef(false);
+    const [error, setError] = useState<any>(null);
+
+    // Which classes to watch. Held in state because it falls out of the first result and
+    // drives the subscription effect below.
+    const [watched, setWatched] = useState<string[] | null | undefined>(undefined);
+
+    // Stable identities, so the effects key on the query rather than on the render count.
+    // The old `queryRef` latch was standing in for this: `params` arrived as a rest
+    // parameter, a fresh array every render, so the effect re-ran every render and the
+    // latch was the only thing preventing a query storm - at the cost of never re-running
+    // at all, including when `sql` changed. See ADR-0025.
+    const paramsKey = JSON.stringify(params);
+    const paramsRef = useRef(params);
+    paramsRef.current = params;
 
-    useEffect( () => {
+    // Guards against a slow earlier run overwriting a fast later one.
+    const runId = useRef(0);
+
+    const runQuery = useCallback(async () => {
+        const stackInstance = docStack?.getStack(stack);
+        if (!stackInstance) return;
+
+        const id = ++runId.current;
+        try {
+            const queryResult = await stackInstance.query(sql, ...paramsRef.current);
+            if (id !== runId.current) return;
+            setResult(queryResult);
+            setWatched(collectQueryClasses(queryResult.ast));
+            setError(null);
+        } catch (err: any) {
+            if (id === runId.current) setError(err);
+        } finally {
+            if (id === runId.current) setLoading(false);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [docStack, stack, sql, paramsKey]);
+
+    useEffect(() => {
         if (!docStack) {
-            // Handle the case where the provider is not yet initialized or missing
-            // You could throw an error or return an empty state.
-            console.error('useClassList must be used within a DocStackProvider.');
-            setLoading(false);
+            // Null until the provider's `ready` event: startup, not a missing provider.
+            // See ADR-0022.
+            setLoading(true);
             return;
         }
+        setLoading(true);
+        runQuery();
+    }, [docStack, runQuery]);
 
-        const runQuery = async () => {
-            try {
-                const stackInstance = docStack.getStack(stack);
-                if (stackInstance) {
-                    // Run the initial query
-                    console.log("Preparing to run query", {sql, params})
-                    // debugger
-                    const queryResult = await stackInstance.query(sql, ...params);
-                    setResult(queryResult);
+    const watchedKey = JSON.stringify(watched ?? null);
 
-                } else {
-                    console.log("Could not find corresponding stack", {stack})
-                }
-            } catch (err: any) {
-                console.log("Got error while running query", {error: err})
-                setError(err);
-            } finally {
-                setLoading(false);
-            }
+    useEffect(() => {
+        const stackInstance = docStack?.getStack(stack);
+        // `undefined` is "no result yet"; `null` is "the AST could not be accounted for".
+        if (!live || !stackInstance || watched === undefined) return;
+
+        let cancelled = false;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        let subscriptions: any[] = [];
+        const target = new EventTarget();
+
+        const onDoc = () => {
+            clearTimeout(timer);
+            timer = setTimeout(runQuery, coalesceMs);
         };
+        target.addEventListener("doc", onDoc);
 
-        if (!queryRef.current) {
-            queryRef.current = true;
-            setLoading(true);
-            runQuery();
-        } else {
-            console.log("Already performing query");
-        }
-        
+        // Fail open. Watching every class is wasteful; watching none is silently wrong,
+        // and silence is the failure this hook exists to end. Subscriptions share one
+        // database listener, so the wasteful branch costs little. See ADR-0025.
+        const resolveClasses = async (): Promise<string[]> => {
+            if (watched === null) return stackInstance.getClassNames();
+            return watched;
+        };
 
-        return () => {
-            //
-        }
+        void resolveClasses().then(classes => {
+            if (cancelled) return;
+            subscriptions = classes.map(name => stackInstance.subscribeClassDocs(name, target));
+        });
 
-    }, [docStack, stack, params]);
+        return () => {
+            cancelled = true;
+            clearTimeout(timer);
+            target.removeEventListener("doc", onDoc);
+            for (const subscription of subscriptions) stackInstance.releaseListener(subscription);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [docStack, stack, live, coalesceMs, watchedKey, runQuery]);
 
-    return { loading, result, error };
+    return { loading, result, error, refetch: runQuery };
 }
 
 /**
@@ -126,8 +189,14 @@ export const useFind = (stack: string, query: {
         if (!docStack) {
             // Handle the case where the provider is not yet initialized or missing
             // You could throw an error or return an empty state.
-            console.error('useFind must be used within a DocStackProvider.');
-            setLoading(false);
+            // The provider publishes `null` into the context until its `ready`
+            // event fires, so this is the normal startup window, not a missing
+            // provider. Reporting it as one sends the reader hunting for a bug
+            // that is not there - and `setLoading(false)` was worse than the
+            // message: it tells a consumer "loaded, and empty" during startup,
+            // which is indistinguishable from a genuinely empty result. See
+            // ADR-0022.
+            setLoading(true);
             return;
         }
 
@@ -154,25 +223,35 @@ export const useFind = (stack: string, query: {
 
         runQuery();
 
-        // Set up the listener for changes
-        const changeListener = (change: any) => {
-            // Logic to handle the change and update the docs state
-            // This part is crucial for real-time updates.
-            // You'll need to re-run the query or intelligently update the docs array
-            // based on the change object (add, update, delete).
-            // A simple way is to re-run the query.
-            // runQuery();
+        // A selector names its class directly, so there is no AST to consult - but it has
+        // to be subscribed the same way. This used to listen for `docStack`'s `change`,
+        // which is dispatched from the replication path and carries a `direction`: a
+        // document written locally never produces one, so an implementation built on it
+        // would appear to work while syncing and do nothing on the machine where the user
+        // is typing. See ADR-0025.
+        const className = (query.selector as { [key: string]: any })?.["~class"];
+        const stackInstance = docStack.getStack(stack);
+
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        let subscription: any;
+        const target = new EventTarget();
+        const onDoc = () => {
+            clearTimeout(timer);
+            timer = setTimeout(runQuery, 150);
         };
 
-        // [TODO] Implement events
-        docStack.addEventListener('change', changeListener);
+        if (stackInstance && typeof className === "string" && className) {
+            target.addEventListener("doc", onDoc);
+            subscription = stackInstance.subscribeClassDocs(className, target);
+        }
 
-        // Cleanup function: remove the listener when the component unmounts
         return () => {
-            docStack.removeEventListener('change', changeListener);
+            clearTimeout(timer);
+            target.removeEventListener("doc", onDoc);
+            if (stackInstance && subscription) stackInstance.releaseListener(subscription);
         };
 
-    }, [docStack, JSON.stringify(query)]); // Re-run if docStack or query changes
+    }, [docStack, stack, JSON.stringify(query)]); // Re-run if docStack or query changes
 
     return { docs, loading, error };
 };

package/src/hooks/sync.ts

@@ -0,0 +1,84 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useDocStack } from '../components/StackProvider/index.js';
+import type { SyncStatus } from '@docstack/client';
+
+/**
+ * Subscribes to replication state for one stack, or for all of them.
+ *
+ * Reads the state DocStack's sync layer keeps rather than tracking replication in the
+ * component: `lastConvergedAt` is the honest "last synced" value - the moment a cycle
+ * finished with nothing left to send - while `lastActiveAt` only says documents moved.
+ *
+ * The subscription is on the stacks, not on the replication handles, so it survives a
+ * {@link StackSyncHandle.restart} (a refreshed credential, say) and works whether it
+ * mounts before or after `sync()` was called.
+ *
+ * @param stackName - Narrow to a single stack. Omit for every open stack.
+ * @returns A map of stack name to {@link SyncStatus}; empty for stacks that have never
+ * synced.
+ *
+ * @example
+ * ```tsx
+ * const SyncBadge = ({ stack }: { stack: string }) => {
+ *     const status = useSyncStatus(stack)[stack];
+ *     if (!status) return <span>Not syncing</span>;
+ *     if (status.state === 'error') return <span>Offline - retrying</span>;
+ *     return <span>Synced {status.lastConvergedAt ? timeAgo(status.lastConvergedAt) : 'never'}</span>;
+ * };
+ * ```
+ */
+export const useSyncStatus = (stackName?: string): Record<string, SyncStatus> => {
+    const docStack = useDocStack();
+    const [statuses, setStatuses] = useState<Record<string, SyncStatus>>({});
+
+    const collect = useCallback((): Record<string, SyncStatus> => {
+        if (!docStack) return {};
+        const stacks = stackName
+            ? [docStack.getStack(stackName)].filter(Boolean)
+            : docStack.getStacks();
+
+        const next: Record<string, SyncStatus> = {};
+        for (const stack of stacks) {
+            const status = stack!.getSyncStatus();
+            if (status) next[stack!.name] = status;
+        }
+        return next;
+    }, [docStack, stackName]);
+
+    useEffect(() => {
+        if (!docStack) return;
+
+        let subscribed: { target: EventTarget; }[] = [];
+
+        const onStatus = () => setStatuses(collect());
+
+        const subscribe = () => {
+            for (const { target } of subscribed) {
+                target.removeEventListener('sync-status', onStatus);
+            }
+            const stacks = stackName
+                ? [docStack.getStack(stackName)].filter(Boolean)
+                : docStack.getStacks();
+            subscribed = stacks.map(stack => ({ target: stack as unknown as EventTarget }));
+            for (const { target } of subscribed) {
+                target.addEventListener('sync-status', onStatus);
+            }
+            onStatus();
+        };
+
+        // The set of stacks is not fixed: one joined at runtime has to be picked up.
+        docStack.addEventListener('stack-added', subscribe);
+        docStack.addEventListener('stack-removed', subscribe);
+        subscribe();
+
+        return () => {
+            docStack.removeEventListener('stack-added', subscribe);
+            docStack.removeEventListener('stack-removed', subscribe);
+            for (const { target } of subscribed) {
+                target.removeEventListener('sync-status', onStatus);
+            }
+        };
+    }, [docStack, stackName, collect]);
+
+    return statuses;
+};

package/src/index.ts

@@ -2,9 +2,43 @@ import StackProvider, {DocStackContext, useDocStack} from "./components/StackPro
 import { useFind, useQuerySQL } from "./hooks/index.js";
 import { useClass, useClassList, useClassDocs, useClassCreate } from "./hooks/class.js";
 import { useDomainList, useDomain, useDomainRelations, useDomainCreate } from "./hooks/domain.js";
+import { useSyncStatus } from "./hooks/sync.js";
 
 export { StackProvider, DocStackContext, useDocStack };
-export { useFind, useQuerySQL };
+export { useFind, useQuerySQL, useSyncStatus };
 
 export { useClassList, useClass, useClassDocs, useClassCreate };
-export { useDomainList, useDomain, useDomainRelations, useDomainCreate };
+export { useDomainList, useDomain, useDomainRelations, useDomainCreate };
+
+/**
+ * Document-modelling types, re-exported from `@docstack/client`.
+ *
+ * Sourced from the client rather than `@docstack/shared` on purpose: the two packages
+ * would otherwise resolve their own copies of `@docstack/shared`, and a consumer using
+ * both could end up holding two structurally-identical-but-distinct `Patch` types.
+ * One source means one copy.
+ */
+export type {
+    AttributeType,
+    AttributeTypeConfig,
+    AttributeModel,
+    ClassModel,
+    DomainModel,
+    TriggerModel,
+    Document,
+    RelationDocument,
+    Patch,
+    SelectAST,
+    UnionAST,
+    ClientCredentials,
+    DocstackReady,
+    StackConfig,
+    StackOptions,
+    SyncDirection,
+    SyncState,
+    SyncStatus,
+    StackSyncOptions,
+    DocStackSyncOptions,
+    RemoteResolver,
+    InternalDocFilterOptions,
+} from "@docstack/client";

package/lib/index.js.LICENSE.txt

@@ -1,9 +0,0 @@
-/**
- * @license React
- * react-jsx-runtime.production.js
- *
- * Copyright (c) Meta Platforms, Inc. and affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */