@docstack/react 0.0.7 → 0.1.0

package/lib/hooks/sync.d.ts

@@ -0,0 +1,27 @@
+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 declare const useSyncStatus: (stackName?: string) => Record<string, SyncStatus>;

package/lib/hooks/sync.js

@@ -0,0 +1,76 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useDocStack } from '../components/StackProvider/index.js';
+/**
+ * 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) => {
+    const docStack = useDocStack();
+    const [statuses, setStatuses] = useState({});
+    const collect = useCallback(() => {
+        if (!docStack)
+            return {};
+        const stacks = stackName
+            ? [docStack.getStack(stackName)].filter(Boolean)
+            : docStack.getStacks();
+        const next = {};
+        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 = [];
+        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 }));
+            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/lib/index.d.ts

@@ -2,7 +2,17 @@ import StackProvider, { DocStackContext, useDocStack } from "./components/StackP
 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 };
+/**
+ * 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

@@ -1,3 +1,9 @@
-/*! For license information please see index.js.LICENSE.txt */
-import{createContext as e,useCallback as n,useContext as t,useEffect as r,useRef as o,useState as c}from"react";import{Class as i,DocStack as s}from"@docstack/client";import{Domain as l}from"@docstack/shared";var d={698(e,n){var t=Symbol.for("react.transitional.element");Symbol.for("react.fragment"),n.jsx=function(e,n,r){var o=null;if(void 0!==r&&(o=""+r),void 0!==n.key&&(o=""+n.key),"key"in n)for(var c in r={},n)"key"!==c&&(r[c]=n[c]);else r=n;return n=r.ref,{$$typeof:t,type:e,key:o,ref:void 0!==n?n:null,props:r}}},848(e,n,t){e.exports=t(698)}},a={};function u(e){var n=a[e];if(void 0!==n)return n.exports;var t=a[e]={exports:{}};return d[e](t,t.exports,u),t.exports}u.d=(e,n)=>{for(var t in n)u.o(n,t)&&!u.o(e,t)&&Object.defineProperty(e,t,{enumerable:!0,get:n[t]})},u.o=(e,n)=>Object.prototype.hasOwnProperty.call(e,n);var f=u(848);const v=e(null),g=()=>t(v),y=e=>{const{config:t,children:i,credentials:l}=e,d=o(null),[a,u]=c(null),g=n(()=>{u(d.current)},[]);return r(()=>{if(null===d.current&&t.length){console.log("DocStack provider - init instance",{config:t});const e=t.map((e,n)=>{const t=Array.isArray(l)?l[n]:l;return"string"==typeof e?t?{connection:e,credentials:t}:e:t?Object.assign(Object.assign({},e),{credentials:t}):e}),n=new s(...e);d.current=n,d.current.addEventListener("ready",g)}return()=>{d.current}},[t,l,g]),(0,f.jsx)(v.Provider,{value:a,children:i})};var h=function(e,n,t,r){return new(t||(t=Promise))(function(o,c){function i(e){try{l(r.next(e))}catch(e){c(e)}}function s(e){try{l(r.throw(e))}catch(e){c(e)}}function l(e){var n;e.done?o(e.value):(n=e.value,n instanceof t?n:new t(function(e){e(n)})).then(i,s)}l((r=r.apply(e,n||[])).next())})};const m=(e,n,...i)=>{const s=t(v),[l,d]=c({rows:[],ast:[]}),[a,u]=c(!0),[f,g]=c(null),y=o(!1);return r(()=>s?(y.current?console.log("Already performing query"):(y.current=!0,u(!0),h(void 0,void 0,void 0,function*(){try{const t=s.getStack(e);if(t){console.log("Preparing to run query",{sql:n,params:i});const e=yield t.query(n,...i);d(e)}else console.log("Could not find corresponding stack",{stack:e})}catch(e){console.log("Got error while running query",{error:e}),g(e)}finally{u(!1)}})),()=>{}):(console.error("useClassList must be used within a DocStackProvider."),void u(!1)),[s,e,i]),{loading:a,result:l,error:f}},p=(e,n,o,i=50)=>{const s=t(v),[l,d]=c([]),[a,u]=c(!0),[f,g]=c(null);return r(()=>{if(!s)return console.error("useFind must be used within a DocStackProvider."),void u(!1);u(!0),h(void 0,void 0,void 0,function*(){try{const t=s.getStack(e);if(t){const e=yield t.findDocuments(n.selector,n.fields);if(e.docs.length){let n=e.docs;d(n)}}}catch(e){g(e)}finally{u(!1)}});const t=e=>{};return s.addEventListener("change",t),()=>{s.removeEventListener("change",t)}},[s,JSON.stringify(n)]),{docs:l,loading:a,error:f}};var k=function(e,n,t,r){return new(t||(t=Promise))(function(o,c){function i(e){try{l(r.next(e))}catch(e){c(e)}}function s(e){try{l(r.throw(e))}catch(e){c(e)}}function l(e){var n;e.done?o(e.value):(n=e.value,n instanceof t?n:new t(function(e){e(n)})).then(i,s)}l((r=r.apply(e,n||[])).next())})};const S=e=>{const r=t(v);return n((n,t)=>k(void 0,void 0,void 0,function*(){try{if(!r)return console.error("useClassCreate must be used within a DocStackProvider."),Promise.resolve(null);const o=r.getStack(e);if(o){const e=yield i.create(o,n,"class",t);return yield o.addClass(e),e}return null}catch(e){return console.error(e),null}}),[r,e])},w=(e,n)=>{const s=t(v),[l,d]=c(),[a,u]=c([]),f=o([]),[g,y]=c(!0),[h,m]=c(null);return r(()=>{if(s)return k(void 0,void 0,void 0,function*(){y(!0),m(null);try{const n=s.getStack(e);if(n){const e=yield n.getClass("class");e&&d(e)}}catch(e){m(e),y(!1)}}),()=>{};y(!1)},[s,e]),r(()=>{l&&k(void 0,void 0,void 0,function*(){y(!0);try{const t=yield l.getCards(n),r=[],o=s.getStack(e);for(const e of t){const n=yield i.buildFromModel(o,e);r.push(n)}f.current=r,u(f.current)}catch(e){m(e)}finally{y(!1)}const t=e=>{const n=e.detail.doc;if(console.log("useClassDocs - detail",{detail:e.detail}),n.active){const e=f.current.findIndex(e=>e.id==n._id);-1!=e?f.current=[...f.current.slice(0,e),n,...f.current.slice(e+1,f.current.length)]:f.current.push(n)}else{console.log("useClassDocs - a doc was deleted",{doc:n});const e=f.current.findIndex(e=>e.id==n._id);-1!=e&&(f.current=[...f.current.slice(0,e),...f.current.slice(e+1,f.current.length)])}u([...f.current])};return l.addEventListener("doc",t),()=>{l.removeEventListener("doc",t)}})},[l,JSON.stringify(n)]),{classList:a,loading:g,error:h}},C=(e,n)=>{const i=t(v),[s,l]=c(!1),[d,a]=c(),[u,f]=c(),g=o(!1);return r(()=>i?(g.current||(g.current=!0,l(!0),k(void 0,void 0,void 0,function*(){try{const t=i.getStack(e);if(t){const e=yield t.getClass(n);e&&f(e)}}catch(e){a(e)}finally{l(!1)}})),()=>{}):(console.error("useClass must be used within a DocStackProvider."),void l(!1)),[i,e,n]),{loading:s,error:d,classObj:u}},x=(e,n,i={})=>{const s=t(v),[l,d]=c(),[a,u]=c([]),f=o([]),[g,y]=c(!0),[h,m]=c(null);return r(()=>{if(s&&n)return k(void 0,void 0,void 0,function*(){y(!0),m(null);try{const t=s.getStack(e);if(t){const e=yield t.getClass(n);e&&d(e)}}catch(e){m(e),y(!1)}}),()=>{};y(!1)},[s,e,n]),r(()=>{l&&k(void 0,void 0,void 0,function*(){y(!0);try{const e=yield l.getCards(i);f.current=e,u(f.current)}catch(e){m(e)}finally{y(!1)}const e=e=>{const n=e.detail.doc;if(console.log("useClassDocs - detail",{detail:e.detail}),n.active){console.log("useClassDocs - a doc was changed or added",{doc:n});const e=f.current.findIndex(e=>e._id==n._id);-1!=e?(console.log("useClassDocs - a doc was changed",{doc:n}),f.current=[...f.current.slice(0,e),n,...f.current.slice(e+1,f.current.length)]):(console.log("useClassDocs - a doc was added",{doc:n}),f.current.push(n))}else{console.log("useClassDocs - a doc was deleted",{doc:n});const e=f.current.findIndex(e=>e._id==n._id);-1!=e&&(f.current=[...f.current.slice(0,e),...f.current.slice(e+1,f.current.length)])}u([...f.current])};return l.addEventListener("doc",e),()=>{l.removeEventListener("doc",e)}})},[l,JSON.stringify(i)]),{docs:a,loading:g,error:h}};var D=function(e,n,t,r){return new(t||(t=Promise))(function(o,c){function i(e){try{l(r.next(e))}catch(e){c(e)}}function s(e){try{l(r.throw(e))}catch(e){c(e)}}function l(e){var n;e.done?o(e.value):(n=e.value,n instanceof t?n:new t(function(e){e(n)})).then(i,s)}l((r=r.apply(e,n||[])).next())})};const b=e=>{const r=t(v);return n((n,t,o,c,i)=>D(void 0,void 0,void 0,function*(){try{if(!r)return console.error("useDomainCreate must be used within a DocStackProvider."),Promise.resolve(null);const s=r.getStack(e);return s?yield l.create(s,null,n,"domain",t,o,c,i):null}catch(e){return console.error(e),null}}),[r,e])},P=(e,n)=>{const i=t(v),[s,d]=c(),[a,u]=c([]),f=o([]),[g,y]=c(!0),[h,m]=c(null);return r(()=>{if(i)return D(void 0,void 0,void 0,function*(){y(!0),m(null);try{const n=i.getStack(e);if(n){const e=yield n.getClass("domain");e&&d(e)}}catch(e){m(e),y(!1)}}),()=>{};y(!1)},[i,e]),r(()=>{s&&D(void 0,void 0,void 0,function*(){y(!0);try{const t=i.getStack(e),r=yield s.getCards(n),o=yield Promise.all(r.map(e=>D(void 0,void 0,void 0,function*(){return yield l.buildFromModel(t,e)})));f.current=o,u(f.current)}catch(e){m(e)}finally{y(!1)}const t=e=>{const n=e.detail.doc;if(n.active){const e=f.current.findIndex(e=>e.id==n._id);-1!=e?f.current=[...f.current.slice(0,e),n,...f.current.slice(e+1,f.current.length)]:f.current.push(n)}else{const e=f.current.findIndex(e=>e.id==n._id);-1!=e&&(f.current=[...f.current.slice(0,e),...f.current.slice(e+1,f.current.length)])}u([...f.current])};return s.addEventListener("doc",t),()=>{s.removeEventListener("doc",t)}})},[s,JSON.stringify(n)]),{domainList:a,loading:g,error:h}},L=(e,n)=>{const i=t(v),[s,l]=c(!1),[d,a]=c(),[u,f]=c(),g=o(!1);return r(()=>i?(g.current||(g.current=!0,l(!0),D(void 0,void 0,void 0,function*(){try{const t=i.getStack(e);if(t){const e=yield t.getDomain(n);e&&f(e)}}catch(e){a(e)}finally{l(!1)}})),()=>{}):(console.error("useDomain must be used within a DocStackProvider."),void l(!1)),[i,e,n]),{loading:s,error:d,domain:u}},E=(e,n,i={})=>{const s=t(v),[l,d]=c(),[a,u]=c([]),f=o([]),[g,y]=c(!0),[h,m]=c(null);return r(()=>{if(s&&n)return D(void 0,void 0,void 0,function*(){y(!0),m(null);try{const t=s.getStack(e);if(t){const e=yield t.getDomain(n);e&&d(e)}}catch(e){m(e),y(!1)}}),()=>{};y(!1)},[s,e,n]),r(()=>{l&&D(void 0,void 0,void 0,function*(){y(!0);try{const e=yield l.getRelations(i);f.current=e,u(f.current)}catch(e){m(e)}finally{y(!1)}const e=e=>{const n=e.detail.doc;if(n.active){console.log("useDomainRelations - a doc was changed or added",{doc:n});const e=f.current.findIndex(e=>e._id==n._id);-1!=e?(console.log("useDomainRelations - a doc was changed",{doc:n}),f.current=[...f.current.slice(0,e),n,...f.current.slice(e+1,f.current.length)]):(console.log("useDomainRelations - a doc was added",{doc:n}),f.current.push(n))}else{const e=f.current.findIndex(e=>e._id==n._id);-1!=e&&(f.current=[...f.current.slice(0,e),...f.current.slice(e+1,f.current.length)])}u([...f.current])};return l.addEventListener("doc",e),()=>{l.removeEventListener("doc",e)}})},[l,JSON.stringify(i)]),{docs:a,loading:g,error:h}};export{v as DocStackContext,y as StackProvider,C as useClass,S as useClassCreate,x as useClassDocs,w as useClassList,g as useDocStack,L as useDomain,b as useDomainCreate,P as useDomainList,E as useDomainRelations,p as useFind,m as useQuerySQL};
-//# sourceMappingURL=index.js.map
+import StackProvider, { DocStackContext, useDocStack } from "./components/StackProvider/index.js";
+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, useSyncStatus };
+export { useClassList, useClass, useClassDocs, useClassCreate };
+export { useDomainList, useDomain, useDomainRelations, useDomainCreate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docstack/react",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "description": "One does not simply stack documents.",
   "main": "lib/index.js",
   "module": "lib/index.js",
@@ -10,7 +10,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "npm run build:prod",
+    "build": "npx tsc -build --force ./tsconfig.json",
     "build:dev": "webpack --node-env=development",
     "build:prod": "webpack --node-env=production"
   },
@@ -38,8 +38,7 @@
     "react-dom": "^19.2.3"
   },
   "dependencies": {
-    "@docstack/client": "^0.1.3",
-    "@docstack/shared": "^0.0.4",
+    "@docstack/client": "^0.1.5",
     "react": "^19.2.3",
     "react-dom": "^19.2.3"
   },

package/src/components/StackProvider/index.tsx

@@ -1,6 +1,6 @@
-import { ReactNode, createContext, useContext, useRef, useCallback, useEffect, useState } from 'react';
+import { ReactNode, createContext, useContext, useRef, useCallback, useEffect, useMemo, useReducer, useState } from 'react';
 import {DocStack} from '@docstack/client'; // Import your DocStack class
-import { ClientCredentials, StackConfig } from '@docstack/shared';
+import { ClientCredentials, StackConfig } from '@docstack/client';
 
 // You can give it a default value, e.g., null, which can be checked later.
 /**
@@ -11,16 +11,16 @@ export const DocStackContext = createContext<DocStack | null>(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>;
  * };
  * ```
@@ -29,9 +29,41 @@ 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: StackConfig): string => {
+    if (typeof config === 'string') return config;
+    return config.name || (config as { connection?: string }).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: StackConfig[],
+    credentials?: ClientCredentials | ClientCredentials[]
+): StackConfig[] => 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 ? { ...cfg, credentials: cred } : cfg;
+}) as StackConfig[];
+
 /**
  * Props for the {@link StackProvider} component.
- * 
+ *
  * @example
  * ```ts
  * const props: DocStackProviderProps = {
@@ -45,6 +77,11 @@ 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;
 }
@@ -52,52 +89,99 @@ export interface DocStackProviderProps {
 /**
  * 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>
+ *     );
+ * };
  * ```
  */
 const StackProvider = (props: DocStackProviderProps) => {
-    const { config, children, credentials } = props;
+    const { config, children, credentials, destroyRemovedStacks } = props;
     // Use a ref to store the DocStack instance
     const docStackRef = useRef<DocStack | null>(null);
     const [docStack, setDocStack] = useState<DocStack | null>(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: number) => 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<unknown>>(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 (docStackRef.current === null && config.length) {
-            console.log("DocStack provider - init instance", {config});
-            const mergedConfig = config.map((cfg, idx) => {
-                const cred = Array.isArray(credentials) ? credentials[idx] : credentials;
-                if (typeof cfg === "string") {
-                    return cred ? { connection: cfg, credentials: cred } : cfg;
-                }
-                return cred ? { ...cfg, credentials: cred } : cfg;
-            });
-            const instance = new DocStack(...mergedConfig as StackConfig[]);
+        if (!mergedConfig.length) return;
+
+        if (docStackRef.current === null) {
+            console.log("DocStack provider - init instance", { config: mergedConfig });
+            const instance = new DocStack(...mergedConfig);
             docStackRef.current = instance;
-            docStackRef.current.addEventListener("ready", setsDocStackWhenReady);
+            instance.addEventListener("ready", setsDocStackWhenReady);
+            instance.addEventListener("stack-added", signalStacksChanged);
+            instance.addEventListener("stack-removed", signalStacksChanged);
+            return;
         }
 
-        // Optional: Cleanup function to remove listeners
-        return () => {
-            if (docStackRef.current) {
-                // docStackRef.current.removeEventListener("ready", setsDocStackWhenReady);
-                // docStackRef.current.getStore().removeAllListeners();
+        const instance = docStackRef.current;
+        let cancelled = false;
+
+        const reconcile = async () => {
+            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 });
+                    await 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 });
+                    await instance.addStack(cfg);
+                }
             }
         };
-    }, [config, credentials, setsDocStackWhenReady]);
+
+        reconciling.current = reconciling.current.then(reconcile).catch(error => {
+            console.error("DocStack provider - failed to reconcile stacks", error);
+        });
+
+        return () => {
+            cancelled = true;
+        };
+    }, [mergedConfig, destroyRemovedStacks, setsDocStackWhenReady]);
 
     return (
         <DocStackContext.Provider value={docStack}>
@@ -106,4 +190,4 @@ const StackProvider = (props: DocStackProviderProps) => {
     );
 };
 
-export default StackProvider;
+export default StackProvider;

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 };