@docstack/react 0.0.9 → 0.1.1

package/src/hooks/class.ts

@@ -1,7 +1,7 @@
 import { useContext, useCallback, useEffect, useRef, useState } from "react";
 import { DocStackContext } from "../components/StackProvider/index.js";
 import { Class } from "@docstack/client";
-import {ClassModel, Document} from "@docstack/shared";
+import {ClassModel, Document} from "@docstack/client";
 
 /**
  * Hook to create a new Class in a specific stack.
@@ -34,7 +34,9 @@ export const useClassCreate = (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('useClassCreate 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('useClassCreate - stack not ready yet; the call was ignored.');
                     // setLoading(false);
                     return Promise.resolve(null);
                 }
@@ -94,7 +96,10 @@ export const useClassList = (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;
         }
 
@@ -128,6 +133,9 @@ export const useClassList = (stack: string, selector: {[key: string]: any}) => {
             return;
         }
 
+        let cancelled = false;
+        let attached: EventListener | null = null;
+
         const runQueryAndListen = async () => {
             setLoading(true);
             try {
@@ -138,13 +146,20 @@ export const useClassList = (stack: string, selector: {[key: string]: any}) => {
                     const classInstance = await Class.buildFromModel(stackInstance!, cls);
                     initialClassList.push(classInstance);
                 }
+                if (cancelled) {
+                    // The effect was torn down mid-query; these were built anyway, and
+                    // each one holds a live subscription until it is closed.
+                    for (const classInstance of initialClassList) classInstance.close();
+                    return;
+                }
                 classListRef.current = initialClassList;
                 setClassList(classListRef.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;
@@ -177,14 +192,23 @@ export const useClassList = (stack: string, selector: {[key: string]: any}) => {
                 setClassList([...classListRef.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 classes stayed subscribed for
+        // every render that changed the selector.
+        return () => {
+            cancelled = true;
+            if (attached) originClass.removeEventListener('doc', attached);
+            // Guarded: the change handler above pushes the raw document for a class it
+            // has not seen before, so the list is not uniformly Class instances.
+            for (const classInstance of classListRef.current) classInstance?.close?.();
+            classListRef.current = [];
+        };
     }, [originClass, JSON.stringify(selector)]); // Dependency on classObj and query
 
     return { classList, loading, error };
@@ -220,8 +244,14 @@ export const useClass = (stack: string, className: 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('useClass 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;
         }
 
@@ -298,7 +328,16 @@ export const useClassDocs = (stack: string, className: string, query = {}) => {
 
     useEffect(() => {
         // Only run if the docStack is available and a className is provided
-        if (!docStack || !className) {
+        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 (!className) {
+            // A genuinely absent className is "nothing to load", which is a settled state -
+            // unlike the pre-ready window above.
             setLoading(false);
             return;
         }
@@ -333,18 +372,23 @@ export const useClassDocs = (stack: string, className: string, query = {}) => {
             return;
         }
 
+        let cancelled = false;
+        let attached: EventListener | null = null;
+
         const runQueryAndListen = async () => {
             setLoading(true);
             try {
-                debugger;
+                // debugger;
                 const initialDocs = await classObj.getCards(query) as Document[];
+                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;
@@ -380,14 +424,18 @@ export const useClassDocs = (stack: string, className: string, query = {}) => {
                 setDocs([...docsRef.current])
             };
 
-            classObj.addEventListener('doc', changeListener as EventListener);
-
-            return () => {
-                classObj.removeEventListener('doc', changeListener as EventListener);
-            };
+            attached = changeListener as EventListener;
+            classObj.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 class.
+        return () => {
+            cancelled = true;
+            if (attached) classObj.removeEventListener('doc', attached);
+        };
     }, [classObj, JSON.stringify(query)]); // Dependency on classObj and query
 
     return { docs, loading, error };

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);
-
-                } 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);
-            }
+    const watchedKey = JSON.stringify(watched ?? null);
+
+    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 };
 }
 
 /**
@@ -121,58 +184,79 @@ export const useFind = (stack: string, query: {
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
 
+    // Guards against a slow earlier run overwriting a fast later one - the same
+    // discipline as useQuerySQL's runId above.
+    const runId = useRef(0);
+
     useEffect(() => {
         // Check if the docStack instance is available
         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;
         }
 
         setLoading(true);
 
         const runQuery = async () => {
+            const id = ++runId.current;
             try {
                 const stackInstance = docStack.getStack(stack);
                 if (stackInstance) {
-                    // Run the initial query
-                    const initialDocs = await stackInstance.findDocuments(query.selector, query.fields);
-                    if (initialDocs.docs.length) {
-                        let docs = initialDocs.docs as Document[]; // [TODO] Check types
-                        setDocs(docs);
-                    }
+                    const found = await stackInstance.findDocuments(query.selector, query.fields);
+                    // An empty result is a result. This setter used to be guarded on
+                    // `.docs.length`, so a live list could gain rows but never lose its
+                    // last one - a deleted document stayed on screen until a remount.
+                    // The hazard that guard was standing in for is *staleness*, and the
+                    // counter above owns that. See ADR-0035.
+                    if (id === runId.current) setDocs(found.docs as Document[]);
                 }
-                
             } catch (err: any) {
-                setError(err);
+                if (id === runId.current) setError(err);
             } finally {
-                setLoading(false);
+                if (id === runId.current) setLoading(false);
             }
         };
 
         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 };
 };