@docstack/react 0.0.7 → 0.1.0

package/lib/components/StackProvider/index.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode } from 'react';
 import { DocStack } from '@docstack/client';
-import { ClientCredentials, StackConfig } from '@docstack/shared';
+import { ClientCredentials, StackConfig } from '@docstack/client';
 /**
  * Context object for the DocStack instance.
  * It provides the current DocStack instance or null if not initialized.
@@ -39,23 +39,40 @@ export interface DocStackProviderProps {
     config: StackConfig[];
     /** Credentials for the stack(s). Can be a single object or an array matching the config. */
     credentials?: ClientCredentials | ClientCredentials[];
+    /**
+     * Delete the underlying database when a stack drops out of `config`. Defaults to
+     * `false`: a workspace that disappears from the configuration is closed, not erased.
+     */
+    destroyRemovedStacks?: boolean;
     /** Child components. */
     children?: ReactNode;
 }
 /**
  * A provider component that initializes the DocStack client and makes it available
  * to child components via the {@link useDocStack} hook.
- * It handles the asynchronous initialization of the stack(s).
+ *
+ * The `config` prop is reconciled rather than read once: a stack that appears in it is
+ * opened, a stack that disappears is closed, and the stacks either side of the change
+ * are left running. An application whose set of databases grows at runtime - one per
+ * workspace, say - therefore does not have to reload to pick up a new one, which
+ * matters once each stack also carries a live replication that a reload would drop.
  *
  * @example
  * ```tsx
  * import { StackProvider } from '@docstack/react';
  *
- * const App = () => (
- *     <StackProvider config={[{ name: 'my-db' }]}>
- *         <MyApp />
- *     </StackProvider>
- * );
+ * const App = () => {
+ *     const workspaces = useWorkspaces();
+ *     const config = useMemo(
+ *         () => [{ name: 'app' }, ...workspaces.map(w => ({ name: `ws-${w.slug}` }))],
+ *         [workspaces]
+ *     );
+ *     return (
+ *         <StackProvider config={config}>
+ *             <MyApp />
+ *         </StackProvider>
+ *     );
+ * };
  * ```
  */
 declare const StackProvider: (props: DocStackProviderProps) => import("react/jsx-runtime").JSX.Element;

package/lib/components/StackProvider/index.js

@@ -0,0 +1,155 @@
+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 { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useRef, useCallback, useEffect, useMemo, useReducer, useState } from 'react';
+import { DocStack } from '@docstack/client'; // Import your DocStack class
+// You can give it a default value, e.g., null, which can be checked later.
+/**
+ * Context object for the DocStack instance.
+ * It provides the current DocStack instance or null if not initialized.
+ */
+export const DocStackContext = createContext(null);
+/**
+ * Hook to access the DocStack instance.
+ *
+ * @returns The current {@link DocStack} instance or null if not yet initialized.
+ *
+ * @example
+ * ```tsx
+ * const MyComponent = () => {
+ *     const docStack = useDocStack();
+ *
+ *     if (!docStack) return <div>Loading...</div>;
+ *
+ *     return <div>Connected to {docStack.getStacks().length} stacks</div>;
+ * };
+ * ```
+ */
+export const useDocStack = () => {
+    return useContext(DocStackContext);
+};
+/**
+ * The name a configuration entry will end up carrying as a stack.
+ *
+ * Mirrors `DocStack.resolveStackConfig`: a string configuration *is* the name, an
+ * object's `name` wins, and a connection-only entry is identified by its connection.
+ *
+ * @param config - One stack configuration.
+ * @returns The identifier to reconcile on.
+ */
+const stackKey = (config) => {
+    if (typeof config === 'string')
+        return config;
+    return config.name || config.connection || '';
+};
+/**
+ * Merges the `credentials` prop into the configurations it applies to.
+ *
+ * @param config - The configurations as given.
+ * @param credentials - One credential for every stack, or one per configuration entry.
+ * @returns Configurations with credentials folded in.
+ */
+const mergeCredentials = (config, credentials) => config.map((cfg, idx) => {
+    const cred = Array.isArray(credentials) ? credentials[idx] : credentials;
+    if (typeof cfg === 'string') {
+        return cred ? { connection: `db-${cfg}`, name: cfg, credentials: cred } : cfg;
+    }
+    return cred ? Object.assign(Object.assign({}, cfg), { credentials: cred }) : cfg;
+});
+/**
+ * A provider component that initializes the DocStack client and makes it available
+ * to child components via the {@link useDocStack} hook.
+ *
+ * The `config` prop is reconciled rather than read once: a stack that appears in it is
+ * opened, a stack that disappears is closed, and the stacks either side of the change
+ * are left running. An application whose set of databases grows at runtime - one per
+ * workspace, say - therefore does not have to reload to pick up a new one, which
+ * matters once each stack also carries a live replication that a reload would drop.
+ *
+ * @example
+ * ```tsx
+ * import { StackProvider } from '@docstack/react';
+ *
+ * const App = () => {
+ *     const workspaces = useWorkspaces();
+ *     const config = useMemo(
+ *         () => [{ name: 'app' }, ...workspaces.map(w => ({ name: `ws-${w.slug}` }))],
+ *         [workspaces]
+ *     );
+ *     return (
+ *         <StackProvider config={config}>
+ *             <MyApp />
+ *         </StackProvider>
+ *     );
+ * };
+ * ```
+ */
+const StackProvider = (props) => {
+    const { config, children, credentials, destroyRemovedStacks } = props;
+    // Use a ref to store the DocStack instance
+    const docStackRef = useRef(null);
+    const [docStack, setDocStack] = useState(null);
+    // The DocStack instance is stable across reconciliations, so adding or removing a
+    // stack changes nothing React can see by itself.
+    const [, signalStacksChanged] = useReducer((count) => count + 1, 0);
+    // Reconciliations are serialized: opening a database is asynchronous and two
+    // overlapping passes would race to add the same stack twice.
+    const reconciling = useRef(Promise.resolve());
+    const mergedConfig = useMemo(() => mergeCredentials(config, credentials), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(config), JSON.stringify(credentials)]);
+    const setsDocStackWhenReady = useCallback(() => {
+        setDocStack(docStackRef.current);
+    }, []);
+    useEffect(() => {
+        if (!mergedConfig.length)
+            return;
+        if (docStackRef.current === null) {
+            console.log("DocStack provider - init instance", { config: mergedConfig });
+            const instance = new DocStack(...mergedConfig);
+            docStackRef.current = instance;
+            instance.addEventListener("ready", setsDocStackWhenReady);
+            instance.addEventListener("stack-added", signalStacksChanged);
+            instance.addEventListener("stack-removed", signalStacksChanged);
+            return;
+        }
+        const instance = docStackRef.current;
+        let cancelled = false;
+        const reconcile = () => __awaiter(void 0, void 0, void 0, function* () {
+            if (cancelled)
+                return;
+            const wanted = new Map(mergedConfig.map(cfg => [stackKey(cfg), cfg]));
+            for (const stack of [...instance.getStacks()]) {
+                if (cancelled)
+                    return;
+                if (!wanted.has(stack.name)) {
+                    console.log("DocStack provider - closing stack dropped from config", { name: stack.name });
+                    yield instance.removeStack(stack.name, { destroy: destroyRemovedStacks });
+                }
+            }
+            for (const [name, cfg] of wanted) {
+                if (cancelled)
+                    return;
+                if (!instance.getStack(name)) {
+                    console.log("DocStack provider - opening stack added to config", { name });
+                    yield instance.addStack(cfg);
+                }
+            }
+        });
+        reconciling.current = reconciling.current.then(reconcile).catch(error => {
+            console.error("DocStack provider - failed to reconcile stacks", error);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [mergedConfig, destroyRemovedStacks, setsDocStackWhenReady]);
+    return (_jsx(DocStackContext.Provider, { value: docStack, children: children }));
+};
+export default StackProvider;

package/lib/components/index.js

@@ -0,0 +1 @@
+"use strict";

package/lib/hooks/class.d.ts

@@ -1,5 +1,5 @@
 import { Class } from "@docstack/client";
-import { Document } from "@docstack/shared";
+import { Document } from "@docstack/client";
 /**
  * Hook to create a new Class in a specific stack.
  *

package/lib/hooks/class.js

@@ -0,0 +1,428 @@
+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 { Class } from "@docstack/client";
+/**
+ * Hook to create a new Class in a specific stack.
+ *
+ * @param stack - The name of the stack to create the class in.
+ * @returns A callback function to create the class.
+ *
+ * @example
+ * ```tsx
+ * const MyComponent = () => {
+ *     const createClass = useClassCreate('my-stack');
+ *
+ *     const handleCreate = async () => {
+ *         const newClass = await createClass('NewClass', 'Description of new class');
+ *         if (newClass) {
+ *             console.log('Class created:', newClass.name);
+ *         }
+ *     };
+ *
+ *     return <button onClick={handleCreate}>Create Class</button>;
+ * };
+ * ```
+ */
+export const useClassCreate = (stack) => {
+    const docStack = useContext(DocStackContext);
+    return useCallback((className, classDesc) => __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('useClassCreate - 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 classObj_ = yield Class.create(stackInstance, className, "class", classDesc);
+                yield stackInstance.addClass(classObj_);
+                return classObj_;
+            }
+            return null;
+        }
+        catch (err) {
+            // setError(err);
+            console.error(err);
+            return null;
+        }
+    }), [docStack, stack]);
+};
+/**
+ * Hook to retrieve a list of classes from a stack based on a selector.
+ * Maintains a real-time list of classes matching the selector.
+ *
+ * @param stack - The name of the stack to query.
+ * @param selector - Mango selector to filter classes.
+ * @returns Object containing the list of classes, loading state, and error.
+ *
+ * @example
+ * ```tsx
+ * const ClassList = () => {
+ *     const { classList, loading } = useClassList('my-stack', {
+ *         name: { $regex: '^User' }
+ *     });
+ *
+ *     if (loading) return <div>Loading...</div>;
+ *
+ *     return (
+ *         <ul>
+ *             {classList.map(cls => <li key={cls.id}>{cls.name}</li>)}
+ *         </ul>
+ *     );
+ * };
+ * ```
+ */
+export const useClassList = (stack, selector) => {
+    const docStack = useContext(DocStackContext);
+    const [originClass, setOriginClass] = useState();
+    const [classList, setClassList] = useState([]);
+    const classListRef = 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('class');
+                    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 initialClassModelList = yield originClass.getCards(selector);
+                const initialClassList = [];
+                const stackInstance = docStack.getStack(stack);
+                for (const cls of initialClassModelList) {
+                    const classInstance = yield 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) {
+                if (!cancelled)
+                    setError(err);
+            }
+            finally {
+                if (!cancelled)
+                    setLoading(false);
+            }
+            if (cancelled)
+                return;
+            const changeListener = (change) => {
+                const doc = change.detail.doc;
+                console.log("useClassDocs - detail", { detail: change.detail });
+                if (!doc.active) {
+                    // A doc was deleted
+                    console.log("useClassDocs - a doc was deleted", { doc });
+                    const docIndex = classListRef.current.findIndex((d) => d.id == doc._id);
+                    if (docIndex != -1) {
+                        classListRef.current = [
+                            ...classListRef.current.slice(0, docIndex),
+                            ...classListRef.current.slice(docIndex + 1, classListRef.current.length)
+                        ];
+                    }
+                }
+                else {
+                    // A doc was changed or added
+                    const docIndex = classListRef.current.findIndex((d) => d.id == doc._id);
+                    if (docIndex != -1) {
+                        // A doc was changed
+                        classListRef.current = [
+                            ...classListRef.current.slice(0, docIndex),
+                            doc,
+                            ...classListRef.current.slice(docIndex + 1, classListRef.current.length)
+                        ];
+                    }
+                    else {
+                        // A doc was added
+                        classListRef.current.push(doc);
+                    }
+                }
+                setClassList([...classListRef.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 classes stayed subscribed for
+        // every render that changed the selector.
+        return () => {
+            var _a;
+            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)
+                (_a = classInstance === null || classInstance === void 0 ? void 0 : classInstance.close) === null || _a === void 0 ? void 0 : _a.call(classInstance);
+            classListRef.current = [];
+        };
+    }, [originClass, JSON.stringify(selector)]); // Dependency on classObj and query
+    return { classList, loading, error };
+};
+/**
+ * Hook to retrieve a single Class instance by name.
+ *
+ * @param stack - The name of the stack.
+ * @param className - The name of the class to retrieve.
+ * @returns Object containing the Class instance, loading state, and error.
+ *
+ * @example
+ * ```tsx
+ * const ClassDetails = () => {
+ *     const { classObj, loading } = useClass('my-stack', 'User');
+ *
+ *     if (loading) return <div>Loading...</div>;
+ *     if (!classObj) return <div>Class not found</div>;
+ *
+ *     return <div>Class Description: {classObj.description}</div>;
+ * };
+ * ```
+ */
+export const useClass = (stack, className) => {
+    const docStack = useContext(DocStackContext);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState();
+    const [classObj, setClass] = 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.getClass(className);
+                    // TODO: manage class model (schema!) updates
+                    if (res) {
+                        setClass(res);
+                    }
+                }
+            }
+            catch (e) {
+                setError(e);
+            }
+            finally {
+                setLoading(false);
+            }
+        });
+        if (!reqRef.current) {
+            reqRef.current = true;
+            setLoading(true);
+            fetchClass();
+        }
+        return () => {
+            // reqRef.current = false;
+        };
+    }, [docStack, stack, className]);
+    return { loading, error, classObj };
+};
+/**
+ * Hook to retrieve documents (cards) of a specific class.
+ * Maintains a real-time list of documents matching the query.
+ *
+ * @param stack - The name of the stack.
+ * @param className - The class name to fetch documents for.
+ * @param query - Optional Mango selector to filter documents.
+ * @returns Object containing the list of documents, loading state, and error.
+ *
+ * @example
+ * ```tsx
+ * const UserList = () => {
+ *     const { docs, loading } = useClassDocs('my-stack', 'User', {
+ *         age: { $gt: 18 }
+ *     });
+ *
+ *     if (loading) return <div>Loading...</div>;
+ *
+ *     return (
+ *         <ul>
+ *             {docs.map(doc => <li key={doc._id}>{doc.name}</li>)}
+ *         </ul>
+ *     );
+ * };
+ * ```
+ */
+export const useClassDocs = (stack, className, query = {}) => {
+    const docStack = useContext(DocStackContext);
+    const [classObj, setClass] = 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 (!className) {
+            // A genuinely absent className 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 retrievedClass = yield stackInstance.getClass(className);
+                    if (retrievedClass) {
+                        setClass(retrievedClass);
+                    }
+                }
+            }
+            catch (err) {
+                setError(err);
+                setLoading(false);
+            }
+        });
+        fetchClass();
+        return () => {
+            // clean what?
+        };
+    }, [docStack, stack, className]); // Dependency on docStack and className
+    useEffect(() => {
+        if (!classObj) {
+            return;
+        }
+        let cancelled = false;
+        let attached = null;
+        const runQueryAndListen = () => __awaiter(void 0, void 0, void 0, function* () {
+            setLoading(true);
+            try {
+                // debugger;
+                const initialDocs = yield classObj.getCards(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;
+                console.log("useClassDocs - detail", { detail: change.detail });
+                if (!doc.active) {
+                    // A doc was deleted
+                    console.log("useClassDocs - a doc was deleted", { doc });
+                    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("useClassDocs - 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("useClassDocs - 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("useClassDocs - a doc was added", { doc });
+                        docsRef.current.push(doc);
+                    }
+                }
+                setDocs([...docsRef.current]);
+            };
+            attached = changeListener;
+            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/lib/hooks/domain.d.ts

@@ -1,5 +1,4 @@
-import { Class } from "@docstack/client";
-import { Domain, RelationDocument } from "@docstack/shared";
+import { Class, Domain, RelationDocument } from "@docstack/client";
 /**
  * Hook to create a new Domain in a specific stack.
  *