@docstack/react 0.0.7 → 0.1.0

package/lib/hooks/domain.js

@@ -0,0 +1,423 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { useContext, useCallback, useEffect, useRef, useState } from "react";
+import { DocStackContext } from "../components/StackProvider/index.js";
+import { Domain } from "@docstack/client";
+/**
+ * Hook to create a new Domain in a specific stack.
+ *
+ * @param stack - The name of the stack to create the domain in.
+ * @returns A callback function to create the domain.
+ *
+ * @example
+ * ```tsx
+ * const CreateDomain = () => {
+ *     const createDomain = useDomainCreate('my-stack');
+ *     // Assume sourceClass and targetClass are available Class instances
+ *
+ *     const handleCreate = async () => {
+ *         const newDomain = await createDomain(
+ *             'UserProjects',
+ *             '1:N',
+ *             userClass,
+ *             projectClass,
+ *             'User has many projects'
+ *         );
+ *     };
+ *
+ *     return <button onClick={handleCreate}>Create Domain</button>;
+ * };
+ * ```
+ */
+export const useDomainCreate = (stack) => {
+    const docStack = useContext(DocStackContext);
+    return useCallback((domainName, cardinality, sourceClass, targetClass, domainDesc) => __awaiter(void 0, void 0, void 0, function* () {
+        try {
+            if (!docStack) {
+                // Handle the case where the provider is not yet initialized or missing
+                // You could throw an error or return an empty state.
+                // 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);
+            }
+            // Run the initial query
+            const stackInstance = docStack.getStack(stack);
+            if (stackInstance) {
+                const domain = yield Domain.create(stackInstance, null, domainName, "domain", cardinality, sourceClass, targetClass, domainDesc);
+                return domain;
+            }
+            return null;
+        }
+        catch (err) {
+            // setError(err);
+            console.error(err);
+            return null;
+        }
+    }), [docStack, stack]);
+};
+/**
+ * Hook to retrieve a list of domains from a stack based on a selector.
+ * Maintains a real-time list of domains matching the selector.
+ *
+ * @param stack - The name of the stack to query.
+ * @param selector - Mango selector to filter domains.
+ * @returns Object containing the list of domains, loading state, and error.
+ *
+ * @example
+ * ```tsx
+ * const DomainList = () => {
+ *     const { domainList, loading } = useDomainList('my-stack', {
+ *         relation: { $eq: '1:N' }
+ *     });
+ *
+ *     if (loading) return <div>Loading...</div>;
+ *
+ *     return (
+ *         <ul>
+ *             {domainList.map(d => <li key={d.id}>{d.name} ({d.relation})</li>)}
+ *         </ul>
+ *     );
+ * };
+ * ```
+ */
+export const useDomainList = (stack, selector) => {
+    const docStack = useContext(DocStackContext);
+    const [originClass, setOriginClass] = useState();
+    const [domainList, setDomainList] = useState([]);
+    const domainListRef = useRef([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        // Only run if the docStack is available and a className is provided
+        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;
+        }
+        const fetchClass = () => __awaiter(void 0, void 0, void 0, function* () {
+            setLoading(true);
+            setError(null);
+            try {
+                const stackInstance = docStack.getStack(stack);
+                if (stackInstance) {
+                    const retrievedClass = yield stackInstance.getClass('domain');
+                    if (retrievedClass) {
+                        setOriginClass(retrievedClass);
+                    }
+                }
+            }
+            catch (err) {
+                setError(err);
+                setLoading(false);
+            }
+        });
+        fetchClass();
+        return () => {
+            // clean what?
+        };
+    }, [docStack, stack]); // Dependency on docStack and stack
+    useEffect(() => {
+        if (!originClass) {
+            return;
+        }
+        let cancelled = false;
+        let attached = null;
+        const runQueryAndListen = () => __awaiter(void 0, void 0, void 0, function* () {
+            setLoading(true);
+            try {
+                const stackInstance = docStack.getStack(stack);
+                const initialDomainModelList = yield originClass.getCards(selector);
+                const initDomainList = yield Promise.all(initialDomainModelList.map((dm) => __awaiter(void 0, void 0, void 0, function* () { return yield 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) {
+                if (!cancelled)
+                    setError(err);
+            }
+            finally {
+                if (!cancelled)
+                    setLoading(false);
+            }
+            if (cancelled)
+                return;
+            const changeListener = (change) => {
+                const doc = change.detail.doc;
+                if (!doc.active) {
+                    // A doc was deleted
+                    const docIndex = domainListRef.current.findIndex((d) => d.id == doc._id);
+                    if (docIndex != -1) {
+                        domainListRef.current = [
+                            ...domainListRef.current.slice(0, docIndex),
+                            ...domainListRef.current.slice(docIndex + 1, domainListRef.current.length)
+                        ];
+                    }
+                }
+                else {
+                    // A doc was changed or added
+                    const docIndex = domainListRef.current.findIndex((d) => d.id == doc._id);
+                    if (docIndex != -1) {
+                        // A doc was changed
+                        domainListRef.current = [
+                            ...domainListRef.current.slice(0, docIndex),
+                            doc,
+                            ...domainListRef.current.slice(docIndex + 1, domainListRef.current.length)
+                        ];
+                    }
+                    else {
+                        // A doc was added
+                        domainListRef.current.push(doc);
+                    }
+                }
+                setDomainList([...domainListRef.current]);
+            };
+            attached = changeListener;
+            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 () => {
+            var _a;
+            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)
+                (_a = domain === null || domain === void 0 ? void 0 : domain.close) === null || _a === void 0 ? void 0 : _a.call(domain);
+            domainListRef.current = [];
+        };
+    }, [originClass, JSON.stringify(selector)]); // Dependency on classObj and query
+    return { domainList, loading, error };
+};
+/**
+ * Hook to retrieve a single Domain instance by name.
+ *
+ * @param stack - The name of the stack.
+ * @param domainName - The name of the domain to retrieve.
+ * @returns Object containing the Domain instance, loading state, and error.
+ *
+ * @example
+ * ```tsx
+ * const DomainDetails = () => {
+ *     const { domain, loading } = useDomain('my-stack', 'UserProjects');
+ *
+ *     if (loading) return <div>Loading...</div>;
+ *     if (!domain) return <div>Domain not found</div>;
+ *
+ *     return <div>Relation Type: {domain.relation}</div>;
+ * };
+ * ```
+ */
+export const useDomain = (stack, domainName) => {
+    const docStack = useContext(DocStackContext);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState();
+    const [domain, setDomain] = useState();
+    const reqRef = useRef(false);
+    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.
+            // 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;
+        }
+        const fetchClass = () => __awaiter(void 0, void 0, void 0, function* () {
+            try {
+                const stackInstance = docStack.getStack(stack);
+                if (stackInstance) {
+                    const res = yield stackInstance.getDomain(domainName);
+                    // TODO: manage class model (schema!) updates
+                    if (res) {
+                        setDomain(res);
+                    }
+                }
+            }
+            catch (e) {
+                setError(e);
+            }
+            finally {
+                setLoading(false);
+            }
+        });
+        if (!reqRef.current) {
+            reqRef.current = true;
+            setLoading(true);
+            fetchClass();
+        }
+        return () => {
+            // reqRef.current = false;
+        };
+    }, [docStack, stack, domainName]);
+    return { loading, error, domain };
+};
+/**
+ * Hook to retrieve relation documents for a specific domain.
+ * Maintains a real-time list of relations matching the query.
+ *
+ * @param stack - The name of the stack.
+ * @param domainName - The domain name to fetch relations for.
+ * @param query - Optional Mango selector to filter relations.
+ * @returns Object containing the list of relation documents, loading state, and error.
+ *
+ * @example
+ * ```tsx
+ * const ProjectTasks = () => {
+ *     const { docs, loading } = useDomainRelations('my-stack', 'ProjectTasks', {
+ *         sourceId: { $eq: 'Project-123' }
+ *     });
+ *
+ *     if (loading) return <div>Loading...</div>;
+ *
+ *     return (
+ *         <ul>
+ *             {docs.map(rel => (
+ *                 <li key={rel._id}>Linked Task: {rel.targetId}</li>
+ *             ))}
+ *         </ul>
+ *     );
+ * };
+ * ```
+ */
+export const useDomainRelations = (stack, domainName, query = {}) => {
+    const docStack = useContext(DocStackContext);
+    const [domain, setDomain] = useState();
+    const [docs, setDocs] = useState([]);
+    const docsRef = useRef([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        // Only run if the docStack is available and a className is provided
+        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;
+        }
+        const fetchClass = () => __awaiter(void 0, void 0, void 0, function* () {
+            setLoading(true);
+            setError(null);
+            try {
+                const stackInstance = docStack.getStack(stack);
+                if (stackInstance) {
+                    const retrievedDomain = yield stackInstance.getDomain(domainName);
+                    if (retrievedDomain) {
+                        setDomain(retrievedDomain);
+                    }
+                }
+            }
+            catch (err) {
+                setError(err);
+                setLoading(false);
+            }
+        });
+        fetchClass();
+        return () => {
+            // clean what?
+        };
+    }, [docStack, stack, domainName]); // Dependency on docStack and className
+    useEffect(() => {
+        if (!domain) {
+            return;
+        }
+        let cancelled = false;
+        let attached = null;
+        const runQueryAndListen = () => __awaiter(void 0, void 0, void 0, function* () {
+            setLoading(true);
+            try {
+                const initialDocs = yield domain.getRelations(query);
+                if (cancelled)
+                    return;
+                docsRef.current = initialDocs;
+                setDocs(docsRef.current);
+            }
+            catch (err) {
+                if (!cancelled)
+                    setError(err);
+            }
+            finally {
+                if (!cancelled)
+                    setLoading(false);
+            }
+            if (cancelled)
+                return;
+            const changeListener = (change) => {
+                const doc = change.detail.doc;
+                if (!doc.active) {
+                    // A doc was deleted
+                    const docIndex = docsRef.current.findIndex((d) => d._id == doc._id);
+                    if (docIndex != -1) {
+                        docsRef.current = [
+                            ...docsRef.current.slice(0, docIndex),
+                            ...docsRef.current.slice(docIndex + 1, docsRef.current.length)
+                        ];
+                    }
+                }
+                else {
+                    // A doc was changed or added
+                    console.log("useDomainRelations - a doc was changed or added", { doc });
+                    const docIndex = docsRef.current.findIndex((d) => d._id == doc._id);
+                    if (docIndex != -1) {
+                        // A doc was changed
+                        console.log("useDomainRelations - a doc was changed", { doc });
+                        docsRef.current = [
+                            ...docsRef.current.slice(0, docIndex),
+                            doc,
+                            ...docsRef.current.slice(docIndex + 1, docsRef.current.length)
+                        ];
+                    }
+                    else {
+                        // A doc was added
+                        console.log("useDomainRelations - a doc was added", { doc });
+                        docsRef.current.push(doc);
+                    }
+                }
+                setDocs([...docsRef.current]);
+            };
+            attached = changeListener;
+            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/lib/hooks/index.d.ts

@@ -1,11 +1,17 @@
-import { Document, SelectAST, UnionAST } from '@docstack/shared';
+import { Document, SelectAST, UnionAST } 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
@@ -22,13 +28,25 @@ import { Document, SelectAST, UnionAST } from '@docstack/shared';
  * };
  * ```
  */
-export declare 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 declare const useQuerySQL: (stack: string, sql: string, params?: any[], options?: QuerySQLOptions) => {
     loading: boolean;
     result: {
         rows: any[];
         ast: (SelectAST | UnionAST)[] | null;
     };
-    error: null;
+    error: any;
+    refetch: () => Promise<void>;
 };
 /**
  * Hook to find documents in a stack using a Mango selector.

package/lib/hooks/index.js

@@ -0,0 +1,206 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+// src/hooks/useFind.js
+import { useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { DocStackContext } from '../components/StackProvider/index.js';
+import { collectQueryClasses } from '@docstack/client';
+export const useQuerySQL = (stack, sql, params = [], options = {}) => {
+    const { live = true, coalesceMs = 150 } = options;
+    const docStack = useContext(DocStackContext);
+    const [result, setResult] = useState({ rows: [], ast: [] });
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(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(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;
+    // Guards against a slow earlier run overwriting a fast later one.
+    const runId = useRef(0);
+    const runQuery = useCallback(() => __awaiter(void 0, void 0, void 0, function* () {
+        const stackInstance = docStack === null || docStack === void 0 ? void 0 : docStack.getStack(stack);
+        if (!stackInstance)
+            return;
+        const id = ++runId.current;
+        try {
+            const queryResult = yield stackInstance.query(sql, ...paramsRef.current);
+            if (id !== runId.current)
+                return;
+            setResult(queryResult);
+            setWatched(collectQueryClasses(queryResult.ast));
+            setError(null);
+        }
+        catch (err) {
+            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) {
+            // Null until the provider's `ready` event: startup, not a missing provider.
+            // See ADR-0022.
+            setLoading(true);
+            return;
+        }
+        setLoading(true);
+        runQuery();
+    }, [docStack, runQuery]);
+    const watchedKey = JSON.stringify(watched !== null && watched !== void 0 ? watched : null);
+    useEffect(() => {
+        const stackInstance = docStack === null || docStack === void 0 ? void 0 : 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;
+        let subscriptions = [];
+        const target = new EventTarget();
+        const onDoc = () => {
+            clearTimeout(timer);
+            timer = setTimeout(runQuery, coalesceMs);
+        };
+        target.addEventListener("doc", onDoc);
+        // 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 = () => __awaiter(void 0, void 0, void 0, function* () {
+            if (watched === null)
+                return stackInstance.getClassNames();
+            return watched;
+        });
+        void resolveClasses().then(classes => {
+            if (cancelled)
+                return;
+            subscriptions = classes.map(name => stackInstance.subscribeClassDocs(name, target));
+        });
+        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, refetch: runQuery };
+};
+/**
+ * Hook to find documents in a stack using a Mango selector.
+ *
+ * @param stack - The name of the stack to query.
+ * @param query - Object containing the selector and optional fields projection.
+ * @param sort - Optional sort criteria.
+ * @param limit - Maximum number of documents to return (default: 50).
+ * @returns Object containing the list of documents, loading state, and error.
+ *
+ * @example
+ * ```tsx
+ * const ActiveTasks = () => {
+ *     const { docs, loading } = useFind('my-stack', {
+ *         selector: {
+ *             "~class": "Task",
+ *             active: true
+ *         },
+ *         fields: ['_id', 'title']
+ *     });
+ *
+ *     if (loading) return <div>Loading...</div>;
+ *
+ *     return (
+ *         <ul>
+ *             {docs.map(doc => <li key={doc._id}>{doc.title}</li>)}
+ *         </ul>
+ *     );
+ * };
+ * ```
+ */
+export const useFind = (stack, query, sort, limit = 50) => {
+    const docStack = useContext(DocStackContext);
+    const [docs, setDocs] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        var _a;
+        // 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.
+            // 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 = () => __awaiter(void 0, void 0, void 0, function* () {
+            try {
+                const stackInstance = docStack.getStack(stack);
+                if (stackInstance) {
+                    // Run the initial query
+                    const initialDocs = yield stackInstance.findDocuments(query.selector, query.fields);
+                    if (initialDocs.docs.length) {
+                        let docs = initialDocs.docs; // [TODO] Check types
+                        setDocs(docs);
+                    }
+                }
+            }
+            catch (err) {
+                setError(err);
+            }
+            finally {
+                setLoading(false);
+            }
+        });
+        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 = (_a = query.selector) === null || _a === void 0 ? void 0 : _a["~class"];
+        const stackInstance = docStack.getStack(stack);
+        let timer;
+        let subscription;
+        const target = new EventTarget();
+        const onDoc = () => {
+            clearTimeout(timer);
+            timer = setTimeout(runQuery, 150);
+        };
+        if (stackInstance && typeof className === "string" && className) {
+            target.addEventListener("doc", onDoc);
+            subscription = stackInstance.subscribeClassDocs(className, target);
+        }
+        return () => {
+            clearTimeout(timer);
+            target.removeEventListener("doc", onDoc);
+            if (stackInstance && subscription)
+                stackInstance.releaseListener(subscription);
+        };
+    }, [docStack, stack, JSON.stringify(query)]); // Re-run if docStack or query changes
+    return { docs, loading, error };
+};
+export const useClassCreate = () => {
+};