@docstack/react 0.1.0 → 0.1.2

package/README.md

@@ -1,187 +1,230 @@
+[![npm](https://img.shields.io/npm/v/@docstack/react)](https://www.npmjs.com/package/@docstack/react)
+[![Docs](https://img.shields.io/badge/docs-onyx--og.github.io-blue)](https://onyx-og.github.io/docstack/)
+[![License](https://img.shields.io/badge/license-CC--BY--SA--4.0-lightgrey)](https://github.com/onyx-og/docstack/blob/main/LICENSE.md)
+
 # @docstack/react
 
-React bindings for **DocStack Client**, enabling seamless integration of the intelligent, offline-first database engine into React applications.
+**React bindings for [DocStack](https://github.com/onyx-og/docstack) — an offline-first embedded database with schemas, SQL, access scopes and encryption.**
+
+A provider that owns the database lifecycle, and hooks that are **live by default**. Every hook subscribes to the local database, so when a document changes — because the user edited it, because a background job wrote it, or because it arrived over sync — the components reading it re-render. There is no fetching layer, no cache to invalidate, and no staleness to reason about.
 
-This package provides a context provider and hooks to initialize the database, subscribe to data changes, and perform write operations.
+---
 
 ## 📦 Installation
 
 ```bash
-npm install @docstack/react @docstack/client
+npm install @docstack/react @docstack/client pouchdb-browser pouchdb-find
 ```
 
-## 🚀 Usage
+React 19 is a peer dependency. `pouchdb-browser` and `pouchdb-find` are peers of `@docstack/client`.
 
-### 1. Setup the Provider
+## 🚀 Why hooks instead of a data layer
 
-Wrap your application root with `<StackProvider>`. This component initializes the DocStack engine and applies any schema patches provided in the configuration.
+In a typical React app, "data" means a server, a client cache, and the machinery between them — query keys, invalidation, refetch intervals, optimistic updates and rollback.
 
-```tsx
-import { StackProvider } from "@docstack/react";
+DocStack removes the server from that path. The database is in the browser, so:
+
+* **A query is a subscription.** `useClassDocs`, `useQuerySQL`, `useFind` and the domain hooks all re-run when the data they read changes. Nothing to invalidate.
+* **Writes are immediate and already true.** `classObj.add(...)` returns after the document has landed locally. There is no optimistic state to reconcile, because the write is not a request.
+* **`useQuerySQL` watches the right things.** It derives which classes to subscribe to from the query's own AST, so a `JOIN` across three classes re-runs when any of the three changes — and bursts coalesce into one re-run (150 ms by default).
+* **Offline is not a state you handle.** Components render from local storage. Sync status is something you *display* (`useSyncStatus`), not something a read has to survive.
 
-const DB_NAME = 'my-app-db';
+## ⚡ Quick start
 
-// Define schema patches (versioned changes to your data model)
-const PATCHES = [
-  {
-    "~class": "patch",
-    version: "1.0.0",
+### 1. Mount the provider
+
+`StackProvider` builds the DocStack instance, opens each configured database, and applies the schema patches it is given. It reconciles when `config` changes: a stack added to the array is opened, one removed is closed.
+
+```tsx
+import { StackProvider } from '@docstack/react';
+
+const PATCHES = [{
+    '~class': 'patch',
+    _id: 'my-app-0.1.0',
+    version: '0.1.0',
+    target: 'my-app',
+    changelog: 'Add the Todo class.',
     active: true,
-    docs: [
-      {
-        _id: "Todo",
-        "~class": "class",
-        name: "Todo",
+    docs: [{
+        '~class': 'class',
+        _id: 'Todo',
+        name: 'Todo',
         schema: {
-          title: { name: "title", type: "string", config: { mandatory: true } },
-          completed: { name: "completed", type: "boolean", config: { defaultValue: false } }
-        }
-      }
-    ]
-  }
-];
-
-function App() {
-  return (
-    <StackProvider config={[{ name: DB_NAME, patches: PATCHES }]}>
-      <MyComponent />
+            title: { name: 'title', type: 'string', config: { mandatory: true } },
+            completed: { name: 'completed', type: 'boolean', config: { defaultValue: false } },
+        },
+    }],
+}];
+
+const App = () => (
+    <StackProvider config={[{ name: 'my-app', patches: PATCHES }]}>
+        <TodoList />
     </StackProvider>
-  );
-}
+);
 ```
 
-### 2. Read Data (Reactive)
+Each entry accepts everything `ClientStack` accepts — `patches`, `documentKey`, `transactions`, `logLevel`, `plugins`, `credentials`.
 
-Use the `useClassDocs` hook to fetch documents for a specific class. This hook automatically subscribes to changes, so your component re-renders whenever the underlying data changes.
+### 2. Read — and stay live
 
 ```tsx
-import { useClassDocs } from "@docstack/react";
-
-function TodoList() {
-  // Fetch all documents of class 'Todo' from 'my-app-db'
-  const { docs: todos, loading } = useClassDocs('my-app-db', 'Todo');
-
-  if (loading) return <p>Loading...</p>;
-
-  return (
-    <ul>
-      {todos.map(todo => (
-        <li key={todo._id}>
-          {todo.title} {todo.completed ? '✅' : '⭕'}
-        </li>
-      ))}
-    </ul>
-  );
-}
+import { useClassDocs } from '@docstack/react';
+
+const TodoList = () => {
+    const { docs, loading } = useClassDocs('my-app', 'Todo');
+
+    if (loading) return <p>Loading…</p>;
+
+    return (
+        <ul>
+            {docs.map(todo => (
+                <li key={todo._id}>{todo.title} {todo.completed ? '✅' : '⭕'}</li>
+            ))}
+        </ul>
+    );
+};
 ```
 
-### 3. Write Data
+Pass a Mango selector as the third argument to narrow it: `useClassDocs('my-app', 'Todo', { completed: { $eq: false } })`.
 
-Use the `useDocStack` hook to access the underlying DocStack client instance for creating, updating, or deleting data.
+### 3. Write
 
 ```tsx
 import { useState } from 'react';
-import { useClass } from "@docstack/react";
-
-function AddTodo() {
-  const { classObj: todoClass } = useClass('my-app-db', 'Todo');
-  const [title, setTitle] = useState("");
-
-  const handleAdd = async () => {
-    if (!todoClass || !title) return;
-    
-    // Add the new document
-    await todoClass.add({ title, completed: false });
-    
-    setTitle("");
-  };
-
-  return (
-    <div>
-      <input value={title} onChange={e => setTitle(e.target.value)} />
-      <button onClick={handleAdd}>Add Task</button>
-    </div>
-  );
-}
+import { useClass } from '@docstack/react';
+
+const AddTodo = () => {
+    const { classObj: todoClass } = useClass('my-app', 'Todo');
+    const [title, setTitle] = useState('');
+
+    const handleAdd = async () => {
+        if (!todoClass || !title) return;
+        await todoClass.add({ title, completed: false });
+        setTitle('');   // the list above updates itself
+    };
+
+    return (
+        <>
+            <input value={title} onChange={e => setTitle(e.target.value)} />
+            <button onClick={handleAdd}>Add</button>
+        </>
+    );
+};
 ```
 
-## 📚 API Reference
+### 4. SQL, live
 
-### `<StackProvider />`
+```tsx
+import { useQuerySQL } from '@docstack/react';
+
+const Overdue = ({ today }: { today: string }) => {
+    const { result, loading, error } = useQuerySQL(
+        'my-app',
+        `SELECT t.title, p.name AS project
+         FROM Todo AS t
+         JOIN Project AS p ON p._id = t.projectId
+         WHERE t.completed = false AND t.dueDate < ?
+         ORDER BY t.dueDate`,
+        [today],
+    );
+
+    if (loading) return <p>Loading…</p>;
+    if (error) return <p>Query failed</p>;
+
+    return <ul>{result.rows.map(r => <li key={r.title}>{r.title} — {r.project}</li>)}</ul>;
+};
+```
 
-The context provider that manages the lifecycle of the DocStack client.
+**Params are an array**, and the query is live. For a deliberate one-shot read, say so at the call site: `useQuerySQL(stack, sql, [today], { live: false })`.
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `config` | `Array<{ name: string, patches: any[] }>` | Configuration for initializing stacks, including database names and schema patches. |
+### 5. Show sync state honestly
 
-### `useClassDocs(dbName: string, className: string)`
+```tsx
+import { useSyncStatus } from '@docstack/react';
+
+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>;
+};
+```
+
+`lastConvergedAt` is the value to render as "last synced" — it marks a cycle that finished with nothing left to send. `lastActiveAt` only says documents moved, which is not the same promise.
+
+The subscription is on the stacks rather than on the replication handles, so it survives a `handle.restart()` (a refreshed credential, say) and works whether it mounts before or after `sync()` was called.
+
+## 📚 API reference
 
-A hook that subscribes to a specific class in the database.
+### `<StackProvider />`
 
-- **Arguments**:
-  - `dbName`: The name of the database stack.
-  - `className`: The name of the class to query.
-- **Returns**:
-  - `docs`: An array of documents belonging to the class.
-  - `loading`: A boolean indicating if the initial data load is in progress.
+| Prop | Type | Description |
+|---|---|---|
+| `config` | `StackConfig[]` | Stacks to open. A string is the database name; an object accepts every `ClientStack` option (`name`, `patches`, `documentKey`, `transactions`, `logLevel`, `plugins`, `credentials`). Reconciled on change. |
+| `credentials` | `ClientCredentials \| ClientCredentials[]` | One credential for every stack, or one per config entry. Merged into the configs it applies to. |
+| `destroyRemovedStacks` | `boolean` | 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. |
 
-### `useClass(dbName: string, className: string)`
+The context publishes `null` until the instance is ready. That window is startup, not a missing provider — every hook handles it, and `useDocStack()` returning `null` is the signal to render a splash rather than an error.
 
-A hook that retrieves the class definition for writing data.
+### Hooks
 
-- **Arguments**:
-  - `dbName`: The name of the database stack.
-  - `className`: The name of the class.
-- **Returns**:
-  - `classObj`: The class instance used for operations like `add` or `updateCard`.
-  - `loading`: Boolean indicating if the class is loading.
+| Hook | Signature | Returns |
+|---|---|---|
+| `useDocStack` | `()` | The `DocStack` instance, or `null` during startup |
+| `useClassDocs` | `(stack, className, query?)` | `{ docs, loading, error }` — live documents of a class, optionally filtered by a Mango selector |
+| `useClass` | `(stack, className)` | `{ classObj, loading, error }` — the `Class` instance, for `add` / `updateCard` / `addTrigger` |
+| `useClassList` | `(stack, selector)` | `{ classList, loading, error }` — the classes defined in the database |
+| `useClassCreate` | `(stack)` | `(className, description?) => Promise<Class>` |
+| `useQuerySQL` | `(stack, sql, params?, options?)` | `{ result, loading, error, refetch }` — `result.rows` and `result.ast`. Live unless `{ live: false }`; `{ coalesceMs }` defaults to 150 |
+| `useFind` | `(stack, { selector, fields? }, sort?, limit?)` | `{ docs, loading, error }` — Mango query; `limit` defaults to 50 |
+| `useSyncStatus` | `(stackName?)` | `Record<string, SyncStatus>` — one stack, or every open stack |
+| `useDomain` | `(stack, domainName)` | `{ domain, loading, error }` |
+| `useDomainList` | `(stack, selector)` | `{ domainList, loading, error }` |
+| `useDomainRelations` | `(stack, domainName, query?)` | `{ docs, loading, error }` — live relation documents |
+| `useDomainCreate` | `(stack)` | `(name, cardinality, sourceClass, targetClass, description?) => Promise<Domain>` |
 
-### `useDocStack()`
+The package also re-exports DocStack's document-modelling types (`Patch`, `ClassModel`, `AttributeModel`, `Document`, `SyncStatus`, `StackConfig`, …) — sourced from `@docstack/client` so a consumer using both never ends up holding two structurally identical but distinct copies of `Patch`.
 
-A hook that returns the initialized DocStack client instance.
+## 🧩 Patterns
 
-- **Returns**: The `DocStack` instance (or `null` if not yet initialized). Use this to access `getStack()`, run queries, or execute jobs.
+**Gate on readiness, not on loading.** `useDocStack()` is `null` until the provider finishes opening its databases:
 
-### `useQuerySQL(dbName: string, sql: string, ...params: any[])`
+```tsx
+const Root = () => {
+    const docstack = useDocStack();
+    if (!docstack) return <Splash />;
+    return <App />;
+};
+```
 
-A hook to execute SQL queries against the local database.
+**A database per workspace.** `config` is an array, so multiple databases are the normal case, not a workaround. Give each workspace its own stack and pass the active one's name down:
+
+```tsx
+<StackProvider config={workspaces.map(w => ({ name: w.stackName, patches: WORKSPACE_PATCHES }))}>
+    <Workspace stackName={active.stackName} />
+</StackProvider>
+```
 
-- **Arguments**:
-  - `dbName`: The name of the database stack.
-  - `sql`: The SQL query string.
-  - `params`: Variable arguments for query parameters.
-- **Returns**:
-  - `result`: An object containing `rows` (the query results).
-  - `loading`: Boolean indicating execution status.
+Every hook takes the stack name as its first argument, so switching workspaces is a prop change — not a remount, and not a second `DocStack` instance racing the first.
 
-### `useFind(dbName: string, query: { selector: object, fields?: string[] })`
+**Snapshots where you mean them.** A report that should not shift under the reader wants `{ live: false }`. Say it at the call site so the next reader knows it was a decision.
 
-A hook to find documents using a MongoDB-style selector.
+**Reach for the client when hooks aren't the right shape.** `useDocStack()` gives you the full instance — `getStack(name)` for transactions, exports, job execution or `sync()`.
 
-- **Arguments**:
-  - `dbName`: The name of the database stack.
-  - `query`: An object with a `selector` property (Mango query syntax).
-- **Returns**:
-  - `docs`: An array of matching documents.
-  - `loading`: Boolean indicating if the search is in progress.
+## 🔍 How it compares
 
-### `useClassList(dbName: string, selector: object)`
+If you have used `useLiveQuery` in [Dexie](https://dexie.org/) or the reactive queries in [RxDB](https://rxdb.info/), the reactivity model here will feel familiar: a query that re-runs when its data changes, backed by local storage.
 
-A hook to retrieve a list of available classes (schemas) in the database.
+What differs is what sits underneath the hook. A `useQuerySQL` call resolves against an engine that already applies schema validation, access scopes and field-level decryption, and the SQL it runs supports joins, aggregation and subqueries rather than a selector API. And because DocStack replicates to any PouchDB-compatible remote — including a folder in the end user's own Google Drive — `useSyncStatus` can describe a sync you never had to run a server for.
 
-- **Arguments**:
-  - `dbName`: The name of the database stack.
-  - `selector`: A filter object to select specific classes.
-- **Returns**:
-  - `classList`: An array of `Class` instances.
-  - `loading`: Boolean indicating if the list is loading.
+## 📖 Documentation
 
-### `useClassCreate(dbName: string)`
+* [Full documentation](https://onyx-og.github.io/docstack/)
+* [@docstack/client](https://github.com/onyx-og/docstack/blob/main/packages/client/README.md) — the engine these hooks wrap
+* [Architecture decisions](https://github.com/onyx-og/docstack/tree/main/specs/adr) — including [ADR-0025](https://github.com/onyx-og/docstack/blob/main/specs/adr/0025-live-usequerysql.md) on live `useQuerySQL` and [ADR-0035](https://github.com/onyx-og/docstack/blob/main/specs/adr/0035-react-usefind-never-applies-an-empty-result.md) on `useFind` result ordering
+* [Contributing](https://github.com/onyx-og/docstack/blob/main/CONTRIBUTING.md)
 
-A hook that returns a function to create new classes dynamically.
+## License
 
-- **Arguments**:
-  - `dbName`: The name of the database stack.
-- **Returns**:
-  - A function `(className: string, description?: string) => Promise<Class>` to create a new class.
+[CC-BY-SA-4.0](https://github.com/onyx-og/docstack/blob/main/LICENSE.md) · © Onyx AC, LLC

package/lib/hooks/index.js

@@ -137,6 +137,9 @@ export const useFind = (stack, query, sort, limit = 50) => {
     const [docs, setDocs] = useState([]);
     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(() => {
         var _a;
         // Check if the docStack instance is available
@@ -155,22 +158,27 @@ export const useFind = (stack, query, sort, limit = 50) => {
         }
         setLoading(true);
         const runQuery = () => __awaiter(void 0, void 0, void 0, function* () {
+            const id = ++runId.current;
             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);
-                    }
+                    const found = yield 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);
                 }
             }
             catch (err) {
-                setError(err);
+                if (id === runId.current)
+                    setError(err);
             }
             finally {
-                setLoading(false);
+                if (id === runId.current)
+                    setLoading(false);
             }
         });
         runQuery();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docstack/react",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "One does not simply stack documents.",
   "main": "lib/index.js",
   "module": "lib/index.js",
@@ -23,7 +23,8 @@
     "components",
     "database",
     "documents",
-    "nosql", "sql",
+    "nosql",
+    "sql",
     "storage",
     "state-management"
   ],
@@ -38,7 +39,7 @@
     "react-dom": "^19.2.3"
   },
   "dependencies": {
-    "@docstack/client": "^0.1.5",
+    "@docstack/client": "^0.3.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3"
   },

package/src/hooks/index.ts

@@ -184,6 +184,10 @@ 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) {
@@ -203,21 +207,22 @@ export const useFind = (stack: string, query: {
         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);
             }
         };