@hvakr/firestate 0.1.2 → 0.1.3

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)
@@ -394,9 +426,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 +451,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 +467,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 +520,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)`
@@ -602,6 +686,84 @@ const id = add({ name: 'New Space', area: 500, floor: 1 })
 remove('oldSpaceId')
 ```
 
+#### Selecting a slice (`selector` + `isEqual`)
+
+By default a component re-renders whenever *any* field — or any status flag — of
+the subscribed document or collection changes, and the hook returns the **full
+handle** (`data`, `isLoading`, `isSynced`, `error`, the writers, and `ref`). Pass
+a `selector` to take control: it receives the resource's full observable state
+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.
+
 #### `useUndoManager()`
 
 Access the undo manager.