@owlmeans/state 0.1.18-rc.8 → 0.1.18

package/README.md

@@ -1,107 +1,212 @@
 # @owlmeans/state
 
-In-memory reactive state management with subscription-based updates for OwlMeans apps.
-
-## Overview
-
-- `createStateResource()` creates an in-memory store that implements the `Resource<T>` interface
-- Subscriptions trigger listeners whenever records are created, updated, or deleted
-- Used on the client to hold UI state (projects, stories, thinking journal entries) as reactive records
-- `DEFAULT_ID` (`'_default'`) is the conventional ID for single-record resources
+The framework's client store: an in-memory `Resource` with live subscriptions, registered on the
+client context. Use it for records a screen binds to: the projects list, the current user, a wizard
+draft, optimistic updates, a socket feed being rendered. It is a store, not a security boundary,
+and it does not survive a reload. Data that must outlive the tab goes in
+[`@owlmeans/client-resource`](../client-resource) (IndexedDB through `web-db`). The truth stays on
+the server, behind entrypoints and a database resource.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/state
+bun add @owlmeans/state@^0.1.18
 ```
 
+## Concepts
+
+- **State resource**: a `StateResource<T>` registered with `appendStateResource(context, alias,
+  config?)`. It uses the full `Resource<T>` vocabulary (`get`, `load`, `list`, `count`, `create`,
+  `update`, `save`, `delete`, `take`, `purge`) plus `replace` and `clear`. Every client context
+  already carries a default one (`state`).
+- **Typed alias**: `stateAlias<T>('tasks')` is a plain string at runtime that carries the record
+  type, so `context.getStateResource(TASKS)` is typed without repeating `<Task>`.
+- **Model**: a `StateModel<T>` wraps one record. `empty` means "nothing loaded yet", `record` is a
+  read-only snapshot (the configured default while empty), and `update(patch)` merges and writes.
+- **Live subscriptions**: `watch(id, listener)` follows one record, and `query(where, listener,
+  opts?)` follows a live set. Both are synchronous and call the listener with the current value
+  before they return, which lets React render without a loading frame.
+- **Single store**: `{ single: true }` holds exactly one record that needs no id, for things like
+  the current account or the active wizard.
+
 ## Usage
 
-Create and register a state resource in context setup:
+### Register stores in the context factory
+
+```ts
+import { appendStateResource, stateAlias } from '@owlmeans/state'
 
-```typescript
-import { createStateResource } from '@owlmeans/state'
+export const PROJECTS = stateAlias<Project>('project-state')
+export const STORIES = stateAlias<Story>('story-state')
 
-// In context.ts
-context.registerResource(createStateResource<ProjectState>('project-state'))
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
+  const context = makeBasicContext<C, T>(cfg)
+  appendStateResource<C, T, Project>(context, PROJECTS)
+  appendStateResource<C, T, Story>(context, STORIES)
+
+  context.projectStore = () => context.getStateResource(PROJECTS)
+
+  return context
+}
 ```
 
-Subscribe to state changes in a service or component:
+`appendStateResource` is idempotent: appending an alias that already exists keeps the resource and
+what it has collected. The `projectStore` accessor is an app-level convenience declared on the
+app's own `Context` type.
 
-```typescript
-import { DEFAULT_ID } from '@owlmeans/state'
-import type { StateModel, StateResource } from '@owlmeans/state'
+### Fetch, then write what the server answered
 
-const resource = context.resource<StateResource<ProjectState>>('project-state')
+```ts
+const store = context.getStateResource(PROJECTS)
 
-const [unsubscribe] = resource.subscribe({
-  id: DEFAULT_ID,
-  listener: (models) => {
-    const [model] = models
-    console.log('project updated:', model.record)
-  }
-})
+const { items } = await context.entrypoint(appProtocols.project.list).call({ query: { size: 50 } })
+await store.replace(items)                              // write these, drop every other record
+
+const project = await context.entrypoint(appProtocols.project.get).call({ params: { id } })
+await store.save(project)                               // create or replace one
 ```
 
-Update state and commit:
+### Read it from React
 
-```typescript
-const [model] = resource.subscribe({ id: projectId, listener: ... })[1]
-model.update({ status: 'active' })
-model.commit()  // triggers listeners
-```
+The hooks live in [`@owlmeans/client`](../client):
 
-## API
+```tsx
+import { useStoreList, useStoreModel } from '@owlmeans/client'
 
-### `createStateResource<T>(alias?): StateResource<T>`
+export const useProjectState = (id?: string) => useStoreModel<Project>(id, PROJECTS)
 
-Creates an in-memory resource with subscription support. Registers under `alias` (default: `'state'`).
+export const ProjectCard: FC<{ id: string }> = ({ id }) => {
+  const project = useProjectState(id)
+  const stories = useStoreList<Story>({
+    query: { projectId: id, status: ['planned', 'active'] },
+    sort: [{ field: 'createdAt', order: 'desc' }],
+    resource: STORIES
+  })
 
-### `StateResource<T>` (extends `Resource<T>`)
+  if (project.empty) {
+    return <Spinner />
+  }
 
-- `subscribe(params): [unsubscribe, StateModel<T>[]]` — subscribe to records by `id`, or to a live
-  `query`; returns the current records
-- `listen(listener)` — global listener for any change in the resource
-- `erase()` — clear all records
-- `all(): Promise<T[]>` — every record, as a plain array
-- `match(criteria?): Promise<T[]>` — the records the criteria accepts, as a plain array
-- `list(criteria?, opts?)` — the `Resource` envelope `{ items, pager }`. Unpaged unless a pager is
-  given, so `list()` returns everything
+  return <Card title={project.record.title} count={stories.length}
+    onRename={title => project.update({ title })} />
+}
+```
 
-### Criteria
+### A single-record store with a default
 
-`list`, `match` and a `query` subscription share the criteria language of the server resources — a
-bare value is equality, a bare array means "any of these", and `$eq $ne $gt $gte $lt $lte $in $nin
-$exists $null $like $ilike $regex $startsWith $endsWith $between $contains $contained $overlaps`
-combine under `$and` / `$or` / `$not`. A dotted key reaches into the record; a value of `undefined`
-is skipped. `matchCriteria`, `filterRecords` and `sortRecords` are exported for filtering a list
-already in hand.
+```ts
+export const DRAFT = stateAlias<InvoiceDraft>('invoice-draft')
 
-```typescript
-const open = await resource.match({ status: 'open' })
-const [unsubscribe] = resource.subscribe({
-  query: { status: 'open' },
-  listener: models => { /* re-runs on every write that changes the answer */ }
+appendStateResource<C, T, InvoiceDraft>(context, DRAFT, {
+  single: true,
+  default: () => ({ customerId: '', lines: [], currency: 'EUR' })
 })
+
+const draft = useStoreModel<InvoiceDraft>(undefined, DRAFT)   // no id: the sole record
+await draft.update({ customerId })                            // persists default + patch
+await draft.clear()                                           // back to empty after submit
 ```
 
-### `StateModel<T>`
+### Fold a live feed into the store outside React
 
-- `record: T` — the current record
-- `update(data?)` — merge partial data into the record
-- `commit(force?)` — apply changes and notify subscribers
-- `clear()` — remove the record
+```ts
+const store = context.getStateResource(STORIES)
 
-### `DEFAULT_ID`
+const stopQuery = store.query({ status: 'active' }, models => {
+  badge.set(models.length)                              // called now, then on every change to the set
+})
 
-```typescript
-const DEFAULT_ID = '_default'  // conventional ID for single-item resources
+socket.on('story', async (event: StoryEvent) => {
+  if (event.type === 'removed') {
+    await store.delete(event.id)
+  } else {
+    await store.save(event.story)
+  }
+})
 ```
 
-## Related Packages
+## API
+
+### `appendStateResource<C, T, R>(context, alias?, config?): T & StateResourceAppend`
+
+Registers a state resource on the context (unless the alias is already registered) and installs
+`getStateResource`. Without an alias it registers the default `state` store.
+
+### `createStateResource<T>(alias?, config?): StateResource<T>`
+
+The bare factory, for registering the resource by hand. `appendStateResource` is the usual way.
+
+### `StateConfig<T>`
+
+| Field | Meaning |
+|-------|---------|
+| `id` | The field records are keyed by. Defaults to `id` |
+| `single` | The resource holds exactly ONE record, which needs no id: the current user, the active session, a wizard being filled in |
+| `default` | `() => T`, what `StateModel.record` shows while the model is empty |
+
+### `StateResource<T>` (extends `Resource<T>`, `PubSubResource<StateEvent<T>>`)
+
+- `config`, the `StateConfig` it was created with
+- `replace(records)`, which writes every record given and drops every record the list does not
+  name. This is the shape of "the server just told us what exists", and subscribers wake once
+- `clear()`, which drops everything
+- `watch(id, listener): () => void`, which follows one record. An absent id on a listed store
+  reports an empty model; on a `single` store it addresses the sole record
+- `query(where, listener, opts?): () => void`, which follows a live set, re-evaluated on every
+  write that changes the answer. `undefined` matches everything; `opts.sort` orders it
+- `publish(event, channel?)` / `subscribe(handler, opts?)`, the change stream. Every write
+  announces itself as a `StateEvent` on the default channel
+
+Reads are unpaged: `list()` returns the whole store, and `list(where, { page })` without a `size`
+is refused rather than silently answering with everything. Writes take no `ttl`, since nothing here
+expires. The criteria language is the one from [`@owlmeans/resource`](../resource), including
+dotted keys into nested fields.
+
+### `StateModel<T>`
 
-- [`@owlmeans/resource`](../resource) — `Resource<T>` interface implemented by StateResource
-- [`@owlmeans/client`](../client) — `useStoreModel` / `useStoreList` React hooks for state resources
+- `id` / `empty` / `record`: `empty` is what "nothing loaded yet" looks like; `record` is the
+  configured `default` while it is true
+- `update(patch)`, which merges and writes in one step
+- `commit()`, which writes what `record` currently holds, including a default not yet stored
+- `clear()`, which deletes the record
+
+### Exports
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `appendStateResource` | function | Register a state resource on the context and install `getStateResource` |
+| `createStateResource` | function | The bare factory |
+| `stateAlias<T>(alias)` | function | An alias typed with its record |
+| `createStateModel(binding)` | function | Wrap a record, or its absence, as a model for a store of your own |
+| `StateResource<T>` | type | The resource interface |
+| `StateModel<T>`, `StateModelBinding<T>` | type | The model and what `createStateModel` binds to |
+| `StateConfig<T>`, `StateEvent<T>`, `StateAlias<T>` | type | Keying config, change event `{ type: 'set' \| 'remove', records }`, typed alias |
+| `StateResourceAppend`, `GetStateResource` | type | The `getStateResource` mixin |
+| `StateConfigError` | class | `NoId`: a write with no key value on a many-record store (`NonSingle` is declared beside it) |
+
+## Common pitfalls
+
+- **Assigning into `model.record`.** It does not reach subscribers and nothing re-renders. Write
+  with `model.update({ ... })`.
+- **Saving a server list record by record.** Records deleted elsewhere stay behind and subscribers
+  wake once per record. Use `replace(records)`.
+- **Treating an empty model as an error.** An unknown or not-yet-known id yields `empty: true` and
+  writes nothing, so render a loading state.
+- **Calling `getStateResource()` with no alias for a store you appended.** Without an alias it
+  answers the default store. Always pass the alias.
+- **Writing with no id on a many-record store.** It throws `StateConfigError` (`NoId`), because
+  nothing here mints ids.
+- **Passing `{ ttl }`**, or expecting data to survive a reload. Use `client-resource` for that.
+- **Trusting the store on the server side.** The server re-validates everything that arrives.
+- **Importing the React hooks from `@owlmeans/web-client`.** They are only exported by
+  `@owlmeans/client`.
+
+## Related packages
+
+- [`@owlmeans/resource`](../resource): the `Resource<T>` contract and the criteria engine
+- [`@owlmeans/client`](../client): `useStoreModel` / `useStoreList` React hooks
+- [`@owlmeans/client-resource`](../client-resource): the client store that survives a reload
+- [`@owlmeans/client-job`](../client-job): a worked example, a socket feed folded into a state resource
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -111,7 +216,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "package": "@owlmeans/state",
-  "version": "0.1.18-rc.8",
-  "generatedAt": "2026-08-24T21:14:00.121Z",
+  "version": "0.1.18",
+  "generatedAt": "2026-10-28T00:31:34.730Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: state
-description: How to use @owlmeans/state — appendStateResource() to register a client state resource on a context, useStoreModel/useStoreList to read it from React, live query subscriptions, and the StateModel commit semantics. Auto-invoked when importing state primitives or building client-side application state.
+description: How to use @owlmeans/state — appendStateResource() to register a client state resource on a context, useStoreModel/useStoreList to read it from React, watch/query live subscriptions, and the StateModel commit semantics. Auto-invoked when importing state primitives or building client-side application state.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,22 +8,30 @@ user-invocable: false
 # @owlmeans/state
 
 **Layer:** Core
-**Install:** `"@owlmeans/state": "^0.1.18-rc.8"` in `dependencies`
+**Install:** `"@owlmeans/state": "^0.1.18"` in `dependencies`
 
 The framework's client store. A state resource is a `Resource` like any other, registered **on the
 context** — which is what separates it from a store held beside the app: a screen, a service and a
-guard all reach the same records through the same container.
+guard all reach the same records through the same container. Reads and writes are the resource
+vocabulary of [[resource]]; `watch` and `query` are the live half.
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
-| `appendStateResource<C, T>(context, alias?)` | Register a state resource on the context |
-| `createStateResource<T>(alias?)` | The bare factory, when you register it yourself |
-| `StateResource<T>` | The resource interface — full CRUD plus `all`, `match`, `subscribe`, `listen`, `erase` |
-| `StateModel<T>` | The subscribed wrapper — `record`, `update`, `commit`, `clear` |
-| `matchCriteria`, `filterRecords`, `sortRecords` | The criteria evaluator, for filtering a list you already hold |
-| `DEFAULT_ID` (`_default`), `DEFAULT_ALIAS` (`state`) | Constants |
+| `appendStateResource<C, T, R>(context, alias?, cfg?)` | Register a state resource on the context |
+| `createStateResource<T>(alias?, cfg?)` | The bare factory, when you register it yourself |
+| `stateAlias<T>(alias)` | Name a store once with the record type attached — `StateAlias<T>` |
+| `StateResource<T>` | The resource interface — full CRUD plus `replace`, `clear`, `watch`, `query`, `publish`/`subscribe` |
+| `StateModel<T>` | The subscribed wrapper — `id`, `empty`, `record`, `update`, `commit`, `clear` |
+| `StateConfig<T>` | How the store is keyed — `id`, `single`, `default`. Readable back as `resource.config` |
+| `StateEvent<T>` | What a change looks like on the wire — `{ type: 'set' \| 'remove', records }` |
+| `createStateModel(binding)` / `StateModelBinding<T>` | Wrap a record — or its absence — as a model, for a store of your own |
+| `StateResourceAppend` / `GetStateResource` | The `getStateResource` mixin `appendStateResource` installs |
+| `StateConfigError` | `NoId` — a write with no value for the key field on a store that holds many records. `NonSingle` is declared beside it for an id-less address on a many-record store, but every such path either answers an empty model (`watch`) or raises `NoId`, so `NoId` is the one a caller meets |
+
+The criteria evaluator (`matchCriteria`, `filterRecords`, `sortRecords`, `applyQuery`) lives in
+**`@owlmeans/resource`** — the same engine the store runs on, for filtering a list you already hold.
 
 The React hooks live in **`@owlmeans/client`** — `useStoreModel`, `useStoreList`. They are not
 re-exported by `@owlmeans/web-client`, so import them from `@owlmeans/client` directly.
@@ -35,21 +43,31 @@ no setup at all. Register a named one per entity when records of different kinds
 id space:
 
 ```typescript
-import { appendStateResource } from '@owlmeans/state'
+import { appendStateResource, stateAlias } from '@owlmeans/state'
 
-export const TASK_STATE = 'task-state'
+export const TASKS = stateAlias<Task>('task-state')
 
 export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
-  const context = makeBasicContext<C, T>(cfg)
-  appendStateResource<C, T>(context, TASK_STATE)
-  // A child context must inherit THIS factory, or it is built without the resource above.
-  context.makeContext = makeContext as typeof context.makeContext
+  const context = makeClientContext<C, T>(cfg)
+  appendStateResource<C, T, Task>(context, TASKS)
   return context
 }
 ```
 
-Reach it with `context.getStateResource<Task>(TASK_STATE)`. A typed accessor on the context
-(`context.taskStore = () => context.getStateResource(TASK_STATE)`) is optional sugar.
+Reach it with `context.getStateResource(TASKS)` — a `StateAlias<T>` carries the record type, so the
+accessor is typed without repeating `<Task>` at every call site. `getStateResource()` with no alias
+answers the context's own default store (`state`), so always name the alias for a store you
+appended. `appendStateResource` is idempotent: appending the same alias twice keeps the resource
+already there, so a setup that runs more than once does not drop what the store has collected.
+
+`StateConfig` decides how the store is keyed and what it shows before anything is loaded — all of it
+optional:
+
+| Field | Meaning |
+|---|---|
+| `id` | The field records are keyed by. Defaults to `id`. |
+| `single` | The store holds exactly ONE record, which therefore needs no id — the current user, the active session, a wizard being filled in. It is what makes `watch(undefined, …)` (and so `useStoreModel()` with no id) answerable. |
+| `default` | `() => T` — what `model.record` shows while the model is empty. A screen binds to it instead of guarding every field, and the store still holds nothing. |
 
 ## Reading it from React
 
@@ -57,95 +75,156 @@ Reach it with `context.getStateResource<Task>(TASK_STATE)`. A typed accessor on
 import { useStoreList, useStoreModel } from '@owlmeans/client'
 
 // One record, by id. Re-renders whenever that record changes.
-const task = useStoreModel<Task>(id, TASK_STATE)
+const task = useStoreModel<Task>(id, TASKS)
 task.record.title
 
 // A LIVE QUERY. Re-renders whenever any write changes which records match.
-const open = useStoreList<Task>({ query: { status: 'open' }, resource: TASK_STATE })
+const open = useStoreList<Task>({ query: { status: 'open' }, resource: TASKS })
 open.map(model => model.record.title)
 
-// Everything in the store.
-const all = useStoreList<Task>({ query: {}, resource: TASK_STATE })
+// Everything in the store, newest first.
+const all = useStoreList<Task>({ sort: [{ field: 'createdAt', order: 'desc' }], resource: TASKS })
 ```
 
 A query subscription creates nothing and re-evaluates on every create, update and delete — a list
 screen never recomputes ids and never re-subscribes to keep up. The criteria object is compared by
-content, so a filter that changes narrows the list.
+content, so a filter that changes narrows the list. An omitted `query` matches everything.
 
-An **id** subscription is different on purpose: it CREATES a placeholder record so a screen has
-something to bind to before the real one arrives. `useStoreModel(undefined)` therefore hands back a
-record whose id is `DEFAULT_ID` — that sentinel, not `null`, is what "nothing loaded yet" looks
-like:
+**"Nothing loaded yet" is `model.empty`.** An id the store knows nothing about yields a model whose
+`empty` is true, and nothing is written into the store on the way — so `useStoreModel` never throws
+for missing data, and a screen bound to an unknown id does not put a blank row into every list
+reading the same store:
 
 ```typescript
-const loading = task.record.id === DEFAULT_ID
+if (task.empty) {
+  return <Spinner/>
+}
 ```
 
+`model.record` is still readable while empty: it holds the resource's configured `default`, or `{}`
+when there is none. Calling `model.update(...)` or `model.commit()` on an empty model writes it —
+including the default it was showing.
+
+An ABSENT id answers the same way. A screen binds to `useStoreModel(project.record.id)` while the
+project is still loading, so a missing id is a rendering state rather than a mistake: on a listed
+store it watches nothing and reports an empty model, and on a `single` store it addresses that
+store's sole record. The empty model it hands back is one shared instance, so a React subscriber
+does not see a new value on every render — and writing through it throws `StateConfigError`
+(`NoId`), because a caller writing with no id has lost track of which record it meant.
+
 ## Writing to it
 
 The server is the source of truth; the store is what the screen reads. Fetch, then write what came
 back into the store, and let the subscriptions render it:
 
 ```typescript
-const store = ctx.getStateResource<Task>(TASK_STATE)
+const store = ctx.getStateResource(TASKS)
 
-const [tasks] = await ctx.entrypoint<ClientEntrypoint<Task[]>>(TASK_LIST).call()
-for (const task of tasks) {
-  await store.save(task)
-}
+const tasks = await ctx.entrypoint(taskEntrypoints.list).call()
+await store.replace(tasks)
 ```
 
-`save` creates or replaces. `update` requires the record to exist. `delete(id)` removes it. Each
-one notifies every subscriber that cares.
+`replace(records)` makes the store agree with an authoritative list: every record given is written,
+and every record the list does not name is dropped. That is the shape of "the server just told us
+what exists" — saving each record one by one leaves the ones deleted elsewhere behind, and one
+write wakes the subscribers once instead of once per record. The store is rewritten before anything
+is told about it, so a subscriber never sees the half-applied set.
+
+For single records: `save` creates or replaces, `create` refuses an id already there, `update`
+requires the record to exist, `delete(id)` removes it and answers with what it removed, `take(id)`
+is the same read but throws when the record is absent, `purge(where)` bulk-deletes (and refuses an
+empty criteria object rather than emptying the store), and `clear()` drops everything. Each one
+notifies every subscriber that cares.
+
+On a store that holds many records, a write carrying no value for the key field throws
+`StateConfigError` (`NoId`) — nothing here mints ids. A write carrying a `ttl` throws
+`UnsupportedArgumentError`: the store keeps no expiring records, so a ttl would be silently
+dropped.
+
+On a `single` store every write lands in the one slot, so `replace([a, b])` keeps only the last of
+them. The key field is never consulted on the way in: an id-less `save`, `create`, `update` or
+`replace` is filed there normally and the record keeps whatever id it arrived with, or none.
+`create` still refuses a slot already filled and `update` still requires it filled, both naming the
+resource alias rather than an id.
+
+`get(id)` / `load(id)` answer the sole record unless it carries a DIFFERENT id: a record stored with
+`id: 'sid'` is a miss for any other name, while a record stored without an id at all — the shape a
+single store invites, since it needs none — answers to every id asked for. Give the record an id
+whenever a screen reads it by one, and treat an id-keyed read on an id-less single store as an
+unconditional hit.
 
 ### The commit rule
 
-`StateModel.record` is a COPY. Assigning to it changes nothing anyone else can see:
+`StateModel.record` is a SNAPSHOT. Assigning to it changes nothing anyone else can see:
 
 ```typescript
-model.record.title = 'renamed'   // WRONG — a silent no-op, nothing re-renders
-model.update({ title: 'renamed' })  // RIGHT — merges and commits
+model.record.title = 'renamed'      // WRONG — a silent no-op, nothing re-renders
+await model.update({ title: 'renamed' })  // RIGHT — merges and commits
 ```
 
-`update(data)` merges and commits in one step; `commit()` writes the current `record` back and is
-what you call after assigning several fields; `clear()` deletes the record. `commit()` skips the
-write when nothing actually changed, so calling it twice is free.
+`update(patch)` merges and commits in one step — batch several fields into one patch rather than
+writing them one at a time. `commit()` writes what `record` currently holds, which is how an empty
+model bound to a `default` is persisted as it stands. `clear()` deletes the record and leaves the
+model empty again. The working copy is replaced rather than mutated on every write, so the record a
+caller is holding never changes underneath it and two models of the same record stay comparable by
+reference — which is what lets a React subscriber tell a real change from an unrelated one.
 
 ## Querying
 
-`list`, `match` and the `query` subscription all take the same criteria language as the server
-resources, so a filter written for an endpoint means the same thing applied locally:
+Reads take the same criteria language as the server resources, so a filter written for an endpoint
+means the same thing applied locally:
 
 ```typescript
-await store.all()                                   // every record, plain array
-await store.match({ status: 'open' })               // the matching records, plain array
-await store.list({ status: ['open', 'blocked'] })   // the Resource envelope: { items, pager }
-await store.list({ criteria: { status: 'open' }, pager: { page: 0, size: 20, sort: ['createdAt'] } })
+await store.get(id)                                  // the record, or UnknownRecordError
+await store.load({ status: 'open' })                 // the first match, or null
+await store.list({ status: ['open', 'blocked'] })    // { items, total }
+await store.list({ status: 'open' }, { sort: ['createdAt'], size: 20 })
+await store.count({ status: 'open' })
 ```
 
 - A bare value is equality; a bare **array means "any of these"**.
 - Operators: `$eq $ne $gt $gte $lt $lte $in $nin $exists $null $like $ilike $regex $startsWith
   $endsWith $between $contains $contained $overlaps`, and `$and $or $not` to combine.
 - A dotted key reaches into the record (`'owner.team'`).
-- A criteria value of `undefined` is SKIPPED — an untouched filter must not empty the list.
-- `list()` with no arguments returns everything: a state resource is unpaged unless a pager is
-  asked for, unlike a server resource that defaults to a page size.
+- `null` matches absence; a criteria value of `undefined` is SKIPPED — an untouched filter must not
+  empty the list.
+- `Sort<T>` is a field name (ascending) or `{ field, order: 'asc' | 'desc' }`.
 
-`all()` and `match()` return plain arrays; `list()` returns `{ items, pager }` because that is the
-`Resource` contract. Destructuring the wrong one is a silently empty render, so pick by shape.
+`list()` returns `{ items, total }` and is **unpaged**: the store is already in memory and a screen
+reading it expects all of it. Ask for a `size` to page, and `size: 0` still means no limit. A `page`
+with no `size` throws `UnsupportedArgumentError('page-without-size')` — there is no default page
+size to count against.
 
 ## Subscribing outside React
 
 ```typescript
-const [unsubscribe] = store.subscribe({ query: { status: 'open' }, listener: models => { ... } })
-const stop = store.listen(models => { ... })   // every change, whatever it is
-await store.erase()                            // drop everything
+const stopOne = store.watch(id, model => { … })                    // one record
+const stopMany = store.query({ status: 'open' }, models => { … })  // a live query
+const stopAll = store.query(undefined, models => { … }, { sort: ['createdAt'] })
 ```
 
-Subscribing the same listener function twice throws — hold the unsubscribe and call it instead.
+Both are **synchronous** and both are seeded before they return: the listener is called with the
+current value straight away, then again on every change — including a removal, which reaches a
+`watch` listener as an empty model. `watch(undefined, …)` on a listed store seeds an empty model
+and subscribes to nothing. Each returns its unsubscribe, and a `query` listener is called again
+only when the set of matching models actually changed, so an unrelated write re-renders nothing.
+
+Writes announce themselves on the default channel, so `publish` is for what the store cannot know
+it did — a change that arrived from elsewhere, or a channel of a caller's own:
+
+```typescript
+const stop = await store.subscribe(event => { … })                  // every write: StateEvent<T>
+await store.publish({ type: 'set', records: [task] }, 'from-socket')
+const once = await store.subscribe(handler, { channel: 'from-socket', once: true, ttl: 60 })
+```
 
 ## Depends On
 
-- `@owlmeans/resource` — `StateResource` extends `Resource`
-- `@owlmeans/context` — for `getStateResource`
-- React hooks: `@owlmeans/client`
+- `@owlmeans/resource` — `StateResource` extends `Resource` and `PubSubResource`
+- `@owlmeans/context` — `appendContextual`, and the `getStateResource` mixin
+
+## Related
+
+- `resource` — the criteria language, paging and the base contract this implements
+- `client` — where the React hooks live; it depends on this package, not the other way round
+- `client-job` — a worked store: a socket feed folded into a state resource

package/build/consts.local.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The one slot of a `single` resource. It is a KEY and never a value: nothing writes it into a
+ * record, so a single resource's record still carries whatever id it arrived with, or none.
+ */
+export declare const SOLE = "";
+/** The channel writes publish on, and the one a subscriber gets when it names none. */
+export declare const CHANGES = "changes";
+/** The alias a context's first state resource takes when nothing else is asked for. */
+export declare const STATE = "state";
+//# sourceMappingURL=consts.local.d.ts.map

package/build/consts.local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.d.ts","sourceRoot":"","sources":["../src/consts.local.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,IAAI,KAAK,CAAA;AAEtB,uFAAuF;AACvF,eAAO,MAAM,OAAO,YAAY,CAAA;AAEhC,uFAAuF;AACvF,eAAO,MAAM,KAAK,UAAU,CAAA"}

package/build/consts.local.js

@@ -0,0 +1,10 @@
+/**
+ * The one slot of a `single` resource. It is a KEY and never a value: nothing writes it into a
+ * record, so a single resource's record still carries whatever id it arrived with, or none.
+ */
+export const SOLE = '';
+/** The channel writes publish on, and the one a subscriber gets when it names none. */
+export const CHANGES = 'changes';
+/** The alias a context's first state resource takes when nothing else is asked for. */
+export const STATE = 'state';
+//# sourceMappingURL=consts.local.js.map

package/build/consts.local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.local.js","sourceRoot":"","sources":["../src/consts.local.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,CAAA;AAEtB,uFAAuF;AACvF,MAAM,CAAC,MAAM,OAAO,GAAG,SAAS,CAAA;AAEhC,uFAAuF;AACvF,MAAM,CAAC,MAAM,KAAK,GAAG,OAAO,CAAA"}