@hvakr/firestate 0.1.2 → 0.1.4

package/README.md

@@ -21,6 +21,7 @@ Firestate provides a declarative, schema-first approach that eliminates boilerpl
 
 - **Zod schemas as the source of truth**: each document/collection is declared with a [Zod](https://zod.dev) schema; firestate infers the TypeScript type via `z.infer` and validates writes at runtime
 - **Real-time sync**: Automatic Firestore listeners with proper lifecycle management
+- **Shared subscriptions**: Every hook reading the same resource shares one listener and one state, ref-counted across mounts — a write through any handle is instantly visible everywhere
 - **Optimistic updates**: Changes reflect immediately, sync in background
 - **Conflict resolution**: Automatic rebasing when concurrent changes occur
 - **Undo/redo**: Built-in command pattern with action grouping
@@ -31,24 +32,25 @@ Firestate provides a declarative, schema-first approach that eliminates boilerpl
 
 Firestate exposes two layers. Pick one based on what you're building:
 
-- **`createFirestate` + `doc` / `col`** (recommended for app code) — declare every Firestore thing in a single registry object; the library generates one typed React hook per entry. Each entry takes a `path` template and a Zod `schema`. In return you get:
+- **`createFirestate` + `doc` / `col`** (recommended for app code) — declare a Firestore resource (a document or collection) with a `path` template and a Zod `schema`, and the library generates one typed React hook per entry. In return you get:
   - the data type (`TaskList`) inferred from the schema via `z.infer`
   - the param keys (`{ listId }`) inferred from the path template and enforced at call sites
   - runtime validation on `set` / `add` writes — bad data throws at the call site instead of after a Firestore round trip
 
   Partial `update(diff)` calls are intentionally NOT validated: diffs commonly include Firestore sentinels like `serverTimestamp()` that a strict schema would reject.
 
+  Treat `createFirestate` as a **per-resource hook factory**, not an app-wide registry: give each document/collection its own module (`firestore/taskList.ts`, `firestore/tasks.ts`, …) with one `createFirestate` call, and export the hooks flat. See [Organizing by resource](#organizing-by-resource).
+
   ```ts
+  // firestore/taskList.ts
   import { z } from 'zod'
-  import { createFirestate, doc, col } from '@hvakr/firestate'
+  import { createFirestate, doc } from '@hvakr/firestate'
 
   const TaskListSchema = z.object({ name: z.string(), createdAt: z.number() })
-  const TaskSchema     = z.object({ title: z.string(), completed: z.boolean() })
 
-  export const { useTaskList, useTasks } = createFirestate({
-    taskList: doc({ path: 'taskLists/{listId}',       schema: TaskListSchema }),
-    tasks:    col({ path: 'taskLists/{listId}/tasks', schema: TaskSchema }),
-  })
+  const taskList = doc({ path: 'taskLists/{listId}', schema: TaskListSchema })
+
+  export const { useTaskList } = createFirestate({ taskList })
 
   // useTaskList({ listId })           — { listId: string } statically required
   // useTaskList()                     — type error: missing listId
@@ -63,9 +65,39 @@ Firestate exposes two layers. Pick one based on what you're building:
 
 Both layers share the same store, undo manager, and sync semantics — the registry is a thin layer on top of the lower-level primitives.
 
+### Organizing by resource
+
+`createFirestate` is best used **once per resource**, not once for your whole app. Put each document or collection in its own module — its schema, its base hook, and its [named slice-hooks](#named-slice-hooks-select) together — and call `createFirestate` there:
+
+```ts
+// firestore/tasks.ts
+import { z } from 'zod'
+import { createFirestate, col } from '@hvakr/firestate'
+
+const TaskSchema = z.object({ title: z.string(), completed: z.boolean(), createdAt: z.number() })
+const tasks = col({ path: 'taskLists/{listId}/tasks', schema: TaskSchema })
+
+export const { useTasks, useTaskById } = createFirestate({
+  tasks,                                                  // → useTasks (full handle)
+  taskById: tasks.select((s, p: { id: string }) => s.data[p.id]),
+})
+
+// firestore/taskList.ts is a sibling module with its own createFirestate call.
+// Components import directly from the resource: `import { useTaskById } from './firestore/tasks'`.
+```
+
+Why per-resource rather than one central call:
+
+- **It scales.** A central registry becomes a chokepoint every feature edits; resource modules keep a resource's schema, hooks, and slices colocated and let you code-split.
+- **Sharing still works app-wide.** Subscriptions are keyed by *definition identity*, and a resource module's definition lives at module scope (one stable object), so every component using `useTasks`/`useTaskById` shares one `onSnapshot` listener and one optimistic state — no matter how many modules.
+- **The store stays global.** All resource modules mount under one `FirestateProvider`, so undo/redo and sync tracking span every resource regardless of how you split the files.
+
+**The one rule:** keep a resource's base hook *and* all its `.select` slices in the **same** `createFirestate` call. Each call builds its own definitions, so splitting one resource across two calls would fork it into two listeners. Separate *resources* in separate calls is exactly what you want; separating *one* resource is the mistake.
+
 ## Table of Contents
 
 - [Choosing an API](#choosing-an-api)
+- [Organizing by resource](#organizing-by-resource)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Examples](#examples)
@@ -188,22 +220,33 @@ function App() {
 
 ```tsx
 // ProjectEditor.tsx
-import { useDocument, useCollection, useUndoManager } from '@hvakr/firestate'
+import {
+    useDocument,
+    useCollection,
+    useDocumentSyncStatus,
+    useUndoManager,
+} from '@hvakr/firestate'
 import { projectDoc, spacesCollection } from './schemas'
 
 function ProjectEditor({ projectId }: { projectId: string }) {
     const params = { projectId }
 
-    // Subscribe to project document
+    // Subscribe to project document. The default handle is sync-agnostic — it
+    // carries `data`/`isLoaded`/`error`, not `isSynced`, so it does NOT
+    // re-render when a save settles.
     const project = useDocument({ definition: projectDoc, params })
 
     // Subscribe to spaces collection (lazy)
     const spaces = useCollection({ definition: spacesCollection, params })
 
+    // Opt into save state only where you render it — shares the project's one
+    // listener, so it doesn't add a subscription.
+    const { isSaving } = useDocumentSyncStatus({ definition: projectDoc, params })
+
     // Access undo/redo
     const { undo, redo, canUndo, canRedo } = useUndoManager()
 
-    if (project.isLoading) return <Spinner />
+    if (!project.isLoaded) return <Spinner />
     if (!project.data) return <NotFound />
 
     return (
@@ -221,7 +264,7 @@ function ProjectEditor({ projectId }: { projectId: string }) {
             {/* Lazy-load spaces */}
             {!spaces.isActive ? (
                 <button onClick={spaces.load}>Load Spaces</button>
-            ) : spaces.isLoading ? (
+            ) : !spaces.isLoaded ? (
                 <Spinner />
             ) : (
                 <ul>
@@ -234,7 +277,7 @@ function ProjectEditor({ projectId }: { projectId: string }) {
             )}
 
             {/* Sync indicator */}
-            {!project.isSynced && <span>Saving...</span>}
+            {isSaving && <span>Saving...</span>}
         </div>
     )
 }
@@ -394,9 +437,11 @@ function App() {
 
 ### Pending edits on unmount
 
-Writes are debounced by `autosave` (default 1000 ms). If a component unmounts
-while there are unflushed local edits, those edits are dropped silently — the
-subscription is gone and the autosave timer is cleared. To handle this:
+Writes are debounced by `autosave` (default 1000 ms). The subscription is
+shared and ref-counted, so its state and autosave timer survive as long as any
+hook is still reading the resource. Only when the **last** reader unmounts with
+unflushed local edits are those edits dropped silently — the shared subscription
+is torn down and its autosave timer cleared. To handle this:
 
 - **Block navigation** with `useUnsavedChangesBlocker` (shown above) so users
   can't navigate away while writes are pending.
@@ -417,14 +462,15 @@ awaiting writes is not feasible.
 Creates typed React hooks from a registry object. Each key becomes a hook named
 `use{CapitalizedKey}`.
 
+Call it **once per resource** — a document or collection with its base hook and
+its [slice-hooks](#named-slice-hooks-select) — in that resource's own module. See
+[Organizing by resource](#organizing-by-resource) for why, and the one sharing
+rule that comes with it.
+
 ```typescript
+// firestore/spaces.ts
 import { z } from 'zod'
-import { createFirestate, doc, col } from '@hvakr/firestate'
-
-const ProjectSchema = z.object({
-    name: z.string(),
-    createdAt: z.number(),
-})
+import { createFirestate, col } from '@hvakr/firestate'
 
 const SpaceSchema = z.object({
     name: z.string(),
@@ -432,23 +478,18 @@ const SpaceSchema = z.object({
     floor: z.number(),
 })
 
-export const { useProject, useSpaces } = createFirestate({
-    project: doc({
-        path: 'projects/{projectId}',
-        schema: ProjectSchema,
-    }),
-    spaces: col({
-        path: 'projects/{projectId}/spaces',
-        schema: SpaceSchema,
-        lazy: true,
-    }),
+const spaces = col({
+    path: 'projects/{projectId}/spaces',
+    schema: SpaceSchema,
+    lazy: true,
 })
+
+export const { useSpaces } = createFirestate({ spaces })
 ```
 
 Generated hooks require the params implied by the path template:
 
 ```tsx
-const project = useProject({ projectId })
 const spaces = useSpaces({ projectId })
 ```
 
@@ -490,6 +531,60 @@ col({
 Path placeholders must look like `{name}`. Empty param values throw at runtime
 when a path is resolved.
 
+#### Named slice-hooks (`.select`)
+
+A bare entry generates a full-handle hook. Call `.select(...)` on an entry to
+derive a **named slice-hook** that shares the entry's schema and path — so the
+schema is declared once and reused — and re-renders only when its slice changes.
+Each derived hook is a flat sibling in the API, named by its registry key:
+
+Define each `.select` slice in the **same** `createFirestate` call as its base
+entry — one resource per module (see [Organizing by resource](#organizing-by-resource)):
+
+```typescript
+// firestore/tasks.ts
+const tasks = col({ path: 'projects/{projectId}/tasks', schema: TaskSchema })
+
+export const { useTasks, useTaskIds, useTaskById } = createFirestate({
+    tasks, // → useTasks (full handle)
+    taskIds: tasks.select((s) => Object.keys(s.data), { isEqual: shallow }),
+    // Parameterized: the selector declares its own params; the generated
+    // hook then requires them alongside the path params, in one bag.
+    taskById: tasks.select((s, p: { id: string }) => s.data[p.id]),
+})
+
+// firestore/project.ts — a separate resource, its own call:
+// export const { useProject, useProjectTitle } = createFirestate({
+//     project,
+//     projectTitle: project.select((s) => s.data?.name),
+// })
+```
+
+The selector receives the same full observable state as the inline `selector`
+option (see [Selecting a slice](#selecting-a-slice-selector--isequal)) and, for a
+parameterized slice, the merged params bag. At the call site you pass that one
+bag and (optionally) the runtime options — the selector and `isEqual` are baked
+into the hook, never passed per call:
+
+```tsx
+const ids = useTaskIds({ projectId }) //                data: string[]
+const one = useTaskById({ projectId, id }) //           data: Task | undefined  (merged bag)
+const disabled = useTaskById({ projectId, id }, { enabled: false })
+```
+
+A slice-hook returns a selected handle: `data` is the slice, plus the full
+writer surface and `ref` — so `one.update({ ... })` still writes the whole task,
+and a document slice-hook's `set` still replaces the whole document. Status
+fields are not on it unless the slice reads them.
+
+A base hook and all its slice-hooks share **one** subscription (one
+`onSnapshot` listener, one optimistic state), so a write through any of them is
+instantly visible to the rest — which is why they must live in one
+`createFirestate` call. The inline `selector` option on the base hook still works
+for one-off slices; reach for `.select` when a slice is named, reused, or
+parameterized. (A derived entry is a leaf — there is no `.select(...).select(...)`
+chaining.)
+
 ### Definition Helpers
 
 #### `defineDocument(definition)`
@@ -538,8 +633,7 @@ const {
     update,         // Update with partial diff
     set,            // Replace entire document
     delete: del,    // Delete the document
-    isLoading,      // Whether initial data is loading
-    isSynced,       // Whether all changes are synced
+    isLoaded,       // Whether the initial snapshot has arrived (ready to render)
     sync,           // Force sync immediately
     error,          // Error from listener, if any
     ref,            // Firestore DocumentReference
@@ -550,6 +644,12 @@ const {
     undoable: true,      // Optional: enable undo (default: true)
     enabled: true,       // Optional: set false until required params exist
 })
+
+// The default handle is SYNC-AGNOSTIC: no `isSynced`, so a save settling does
+// not re-render it. For save state, use the per-entry sync-status hook (with the
+// registry API) or fold `isSynced` into a `selector`. `isLoading` likewise moved
+// to the loading-status hook; the data handle keeps `isLoaded` for the common
+// "spinner until ready" gate.
 ```
 
 #### `useCollection(options)`
@@ -562,9 +662,8 @@ const {
     update,         // Update one or more documents
     add,            // Add a new document (explicit or auto-generated id)
     remove,         // Remove a document
-    isLoading,      // Whether initial data is loading
-    isSynced,       // Whether all changes are synced
-    isActive,       // Whether subscription is active
+    isLoaded,       // Active AND past the initial load (isActive && !isLoading)
+    isActive,       // Whether subscription is active (for lazy collections)
     load,           // Activate a lazy subscription
     sync,           // Force sync immediately
     error,          // Error from listener, if any
@@ -602,6 +701,139 @@ const id = add({ name: 'New Space', area: 500, floor: 1 })
 remove('oldSpaceId')
 ```
 
+#### Selecting a slice (`selector` + `isEqual`)
+
+By default a component re-renders when the data, the load state (`isLoaded`), or
+`error` of the subscribed document/collection changes, and the hook returns the
+**sync-agnostic default handle** (`data`, `isLoaded`, `error`, the writers, and
+`ref` — plus a collection's `isActive`). It deliberately omits `isSynced`, so a
+save settling does not re-render it (see [Sync status and loading status](#sync-status-and-loading-status)).
+Pass a `selector` to take further control: it receives the resource's *full*
+observable state — including `isLoading`/`isSynced` — and returns the slice the
+component reacts to, so the component re-renders **only** when that slice changes.
+
+A selected handle exposes exactly your slice as `data`, plus the writer surface
+(`update`/`set`/`delete`/`add`/`remove`/`load`/`sync`) and `ref` — the status
+flags are **not** on it. You react to precisely what you select; status is not a
+freebie, so read it from the state inside the selector when you need it. A
+selector changes what you *read*, never what you *write*.
+
+```typescript
+// Re-renders only when the title changes — not on any other field, and not on a
+// save (isSynced) flip, because the selector never reads it.
+const { data: title, update } = useDocument({
+    definition: projectDoc,
+    params: { projectId },
+    selector: (s) => s.data?.title,
+})
+update({ description: 'edited' }) // still a full-document update
+
+// Need a status flag? Select it — then, and only then, you re-render on it.
+const { data } = useDocument({
+    definition: projectDoc,
+    params: { projectId },
+    selector: (s) => ({ title: s.data?.title, saving: !s.isSynced }),
+})
+
+// On a collection, sub-select a single document or a derived value.
+const { data: space } = useCollection({
+    definition: spacesCollection,
+    params: { projectId },
+    selector: (s) => s.data[spaceId],
+})
+```
+
+`s.data` is `undefined` while a document is loading (and the collection record is
+`{}`), so selectors should handle the empty case.
+
+When writing from a narrowed handle, use `update` — it takes a *partial* and
+merges, so a selected field is just `update({ field: next })`. `set` still
+**replaces the entire document**, not the slice: never pass the selected value
+to `set` (e.g. `set(title)`) or you will overwrite every other field. Reach for
+`set` only when you hold the full document.
+
+By default the slice is compared with a deep value comparison, so a selector
+that returns a fresh object/array of the same shape does **not** over-render.
+Pass `isEqual` to tune it — `shallow` (exported) is a one-level compare for flat
+projections:
+
+```typescript
+import { shallow } from '@hvakr/firestate'
+
+const { data: ids } = useCollection({
+    definition: spacesCollection,
+    params: { projectId },
+    selector: (s) => Object.keys(s.data),
+    isEqual: shallow,
+})
+```
+
+Selectors do not need to be memoized; an inline selector is recomputed each
+render but only triggers a re-render when its result changes per `isEqual`.
+
+Selectors compose cleanly across components because subscriptions are shared:
+every hook reading the same resource (same definition, path, and query) shares
+one Firestore listener and one reconciled state, so many components each
+selecting a different slice cost a single listener. A write through any handle
+is observed by all of them. `readOnly` is a per-handle capability, not part of
+that key — a read-only hook shares the same listener and optimistic state as a
+writable hook on the same resource, so the common provider/leaf pattern (one
+writable owner, many `readOnly: true` read-selectors) sees the writer's
+optimistic edits live. Only the read-only handle's own writers are disabled.
+
+#### Sync status and loading status
+
+The default data handle is **sync-agnostic**: it carries `data`/`isLoaded`/
+`error` but never `isSynced`. That matters because `isSynced` flips on *every*
+autosave settle — so if the data handle carried it, every component that merely
+reads a record would re-render an extra time after each save. Most readers only
+want the data; the few that render save state (a "Saving…" indicator, a
+navigation blocker) opt in explicitly.
+
+For each registry entry, `createFirestate` generates two opt-in status hooks
+beside the data hook:
+
+```typescript
+const { useSpaces, useSpacesSyncStatus, useSpacesLoadingStatus } =
+    createFirestate({ spaces: spacesEntry })
+
+// Only this component re-renders when a save settles — not every data reader.
+function SaveIndicator(params) {
+    const { isSynced, isSaving } = useSpacesSyncStatus(params)
+    return isSaving ? <Spinner /> : <Check />
+}
+
+// A spinner that shows load progress WITHOUT re-rendering when data changes.
+function SpacesSpinner(params) {
+    const { isLoading, isLoaded } = useSpacesLoadingStatus(params)
+    return isLoading ? <Spinner /> : null
+}
+```
+
+Both share the entry's **one** `onSnapshot` listener with the data hook (and any
+slice hooks) — sharing is keyed by `(definition, path, query)`, not by which
+hook you call — so opting in costs no extra subscription. `useSpacesSyncStatus`
+re-renders only when sync state flips; `useSpacesLoadingStatus` re-renders only
+on the load transition, never on data. Collection status hooks take the same
+`queryConstraints` as the data hook (pass the same query to share the listener).
+
+On a **lazy** collection, a status hook does not call `load()` itself — so as
+the *only* subscriber it stays idle (`{ isSynced: true, isSaving: false }` /
+`{ isLoading: false, isLoaded: false }`) and attaches no listener. Pair it with
+the data hook, whose `load()` activates the one shared listener the status hook
+then rides. Non-lazy collections activate on mount, so this is lazy-only.
+
+`.select` (slice) entries do **not** get their own status hooks — a slice's sync
+and loading state is the resource's, read through the base entry's status hooks.
+
+With the lower-level API there are standalone equivalents —
+`useDocumentSyncStatus` / `useDocumentLoadingStatus` /
+`useCollectionSyncStatus` / `useCollectionLoadingStatus`, each taking
+`{ definition, params, enabled }` (collections also `queryConstraints`).
+
+This is the per-resource counterpart to [`useIsSynced()`](#useissynced), which
+reports a single provider-wide aggregate across *all* tracked resources.
+
 #### `useUndoManager()`
 
 Access the undo manager.
@@ -753,7 +985,7 @@ const combined = mergeDiffs(diff1, diff2)
 ## Notes
 
 - **`enabled` flag** — pass `enabled: false` to generated hooks or to `useDocument`/`useCollection` when route params or auth-derived ids are not ready yet. Disabled hooks do not resolve paths or attach listeners, which avoids building invalid Firestore paths like `projects//spaces`.
-- **Navigation flicker** — changing `params` rebuilds the listener and briefly shows `isLoading: true`. To keep the previous data visible across the transition, wrap your param in `useDeferredValue`.
+- **Navigation flicker** — changing `params` rebuilds the listener and briefly shows the loading state (`isLoaded: false`). To keep the previous data visible across the transition, wrap your param in `useDeferredValue`.
 - **No cross-doc transactions** — writes are atomic per document and per collection (via `writeBatch`), but not across them. For now, use Firestore's `runTransaction` directly via `handle.ref`.
 - **Per-client undo** — `useUndoManager` is local; one user's undo doesn't propagate to others.
 - **Multi-tab sync** — handled automatically by Firestore's listeners; no extra setup.
@@ -846,9 +1078,9 @@ const project = useDocument({
     params: { projectId: '123' },
 })
 
-// Missing documents are not errors — `data` is undefined and `isLoading`
-// is false. Render a create/empty state for that case.
-if (!project.isLoading && !project.data) {
+// Missing documents are not errors — once loaded, `data` is undefined.
+// Render a create/empty state for that case.
+if (project.isLoaded && !project.data) {
     return <CreateProject />
 }
 
@@ -913,8 +1145,7 @@ vi.mock('@hvakr/firestate', () => ({
         update: vi.fn(),
         set: vi.fn(),
         delete: vi.fn(),
-        isLoading: false,
-        isSynced: true,
+        isLoaded: true,
         sync: vi.fn(),
         error: undefined,
         ref: {},