@owlmeans/state 0.1.18-rc.9 → 0.1.18

package/README.md

@@ -1,131 +1,212 @@
 # @owlmeans/state
 
-The framework's client store: an in-memory `Resource` with live subscriptions.
-
-## Overview
-
-- `appendStateResource(context, alias, config?)` registers a store ON the context, so a screen, a
-  service and a guard all reach the same records through the same container
-- Reads and writes are the ordinary `Resource<T>` vocabulary — `get`, `load`, `list`, `count`,
-  `create`, `update`, `save`, `delete`, `take`, `purge` — with the same criteria language the
-  server resources speak
-- `watch` follows one record and `query` follows a live set; both hand their listener a value
-  synchronously, which is what lets React render from them without a loading frame
-- A subscription READS the store. Watching an id the store knows nothing about creates nothing;
-  the model it answers with is `empty`
+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
 
-Register a store per record type, and name it once with the type attached:
+### Register stores in the context factory
 
-```typescript
+```ts
 import { appendStateResource, stateAlias } from '@owlmeans/state'
 
-export const TASKS = stateAlias<Task>('tasks')
+export const PROJECTS = stateAlias<Project>('project-state')
+export const STORIES = stateAlias<Story>('story-state')
 
 export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
-  const context = makeClientContext<C, T>(cfg)
-  appendStateResource<C, T, Task>(context, TASKS)
+  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
 }
+```
+
+`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.
+
+### Fetch, then write what the server answered
+
+```ts
+const store = context.getStateResource(PROJECTS)
 
-const tasks = context.getStateResource(TASKS)   // StateResource<Task>
+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
 ```
 
-Every client context already carries one default `state` resource, so a store is only registered
-when records of different kinds must not share an id space.
+### Read it from React
 
-Read it from React with the hooks in [`@owlmeans/client`](../client):
+The hooks live in [`@owlmeans/client`](../client):
 
-```typescript
+```tsx
 import { useStoreList, useStoreModel } from '@owlmeans/client'
 
-const task = useStoreModel<Task>(id, 'tasks')                       // one record, live
-const open = useStoreList<Task>({ query: { status: 'open' }, resource: 'tasks' })
+export const useProjectState = (id?: string) => useStoreModel<Project>(id, PROJECTS)
+
+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
+  })
+
+  if (project.empty) {
+    return <Spinner />
+  }
+
+  return <Card title={project.record.title} count={stories.length}
+    onRename={title => project.update({ title })} />
+}
 ```
 
-Write through the resource, or through the model a subscription handed you:
+### A single-record store with a default
 
-```typescript
-const tasks = context.getStateResource(TASKS)
+```ts
+export const DRAFT = stateAlias<InvoiceDraft>('invoice-draft')
 
-await tasks.save(record)                 // create or replace
-await tasks.replace(fromTheServer)       // write these, drop everything else
-await tasks.purge({ status: 'done' })
-await tasks.clear()
+appendStateResource<C, T, InvoiceDraft>(context, DRAFT, {
+  single: true,
+  default: () => ({ customerId: '', lines: [], currency: 'EUR' })
+})
 
-model.update({ status: 'done' })         // merge and write in one step
+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
+```
+
+### Fold a live feed into the store outside React
+
+```ts
+const store = context.getStateResource(STORIES)
+
+const stopQuery = store.query({ status: 'active' }, models => {
+  badge.set(models.length)                              // called now, then on every change to the set
+})
+
+socket.on('story', async (event: StoryEvent) => {
+  if (event.type === 'removed') {
+    await store.delete(event.id)
+  } else {
+    await store.save(event.story)
+  }
+})
 ```
 
 ## 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, when the resource is registered by hand. `appendStateResource` is the usual way.
+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` | What `StateModel.record` shows while the model is empty |
+| `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>>`)
 
-- `replace(records)` — write every record given and drop every record the list does not name, which
-  is the shape of "the server just told us what exists"
-- `clear()` — drop everything
-- `watch(id, listener): () => void` — follow one record. `undefined` addresses the one record of a
-  `single` resource and throws `StateConfigError.NonSingle` on any other
-- `query(where, listener, opts?): () => void` — follow a live set, re-evaluated on every write that
-  changes the answer. `undefined` matches everything
-- `publish(event, channel?)` / `subscribe(handler, opts?)` — the change stream. Every write
+- `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` — nothing here
-expires.
+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>`
 
-- `id` / `empty` / `record` — `empty` is what "nothing loaded yet" looks like; `record` is the
+- `id` / `empty` / `record`: `empty` is what "nothing loaded yet" looks like; `record` is the
   configured `default` while it is true
-- `update(patch)` — merge and write in one step
-- `commit()` — write what `record` currently holds, including a default not yet stored
-- `clear()` — delete the record
-
-`record` is a snapshot: assigning into it changes nothing anyone else can see. `update` is how a
-change reaches the store and every other subscriber.
-
-### `stateAlias<T>(alias)`
-
-An alias that remembers the record type it addresses, so `getStateResource(TASKS)` is typed without
-repeating `<Task>` at every call site. It is the plain string at runtime.
-
-### `StateConfigError`
-
-`NonSingle` — a record was addressed without an id on a resource that holds many.
-`NoId` — a write carried no value for the id field, and nothing here mints one.
-
-## Criteria
-
-The criteria language, the operators and the in-memory engine (`matchCriteria`, `filterRecords`,
-`sortRecords`, `firstMatch`, `applyQuery`) all live in
-[`@owlmeans/resource`](../resource) — one filter object means the same thing whether it is
-evaluated here or by a relational store.
-
-## Related Packages
-
-- [`@owlmeans/resource`](../resource) — the `Resource<T>` contract and the criteria engine
-- [`@owlmeans/client`](../client) — `useStoreModel` / `useStoreList` React hooks
+- `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
@@ -135,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.9",
-  "generatedAt": "2026-09-01T16:28:56.989Z",
+  "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

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/state
 
 **Layer:** Core
-**Install:** `"@owlmeans/state": "^0.1.18-rc.9"` 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
@@ -24,9 +24,11 @@ vocabulary of [[resource]]; `watch` and `query` are the live half.
 | `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` |
+| `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 }` |
-| `StateConfigError` | `NonSingle` (no id on a many-record store), `NoId` (a write with no key) |
+| `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.
@@ -103,8 +105,12 @@ if (task.empty) {
 when there is none. Calling `model.update(...)` or `model.commit()` on an empty model writes it —
 including the default it was showing.
 
-`useStoreModel()` with no id addresses the one record of a `single` resource. On any other that is a
-wiring mistake and throws `StateConfigError` (`NonSingle`).
+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
 
@@ -114,7 +120,7 @@ back into the store, and let the subscriptions render it:
 ```typescript
 const store = ctx.getStateResource(TASKS)
 
-const tasks = await ctx.entrypoint<ClientEntrypoint<Task[]>>(TASK_LIST).call()
+const tasks = await ctx.entrypoint(taskEntrypoints.list).call()
 await store.replace(tasks)
 ```
 
@@ -130,9 +136,22 @@ is the same read but throws when the record is absent, `purge(where)` bulk-delet
 empty criteria object rather than emptying the store), and `clear()` drops everything. Each one
 notifies every subscriber that cares.
 
-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 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
 
@@ -186,7 +205,9 @@ const stopAll = store.query(undefined, models => { … }, { sort: ['createdAt']
 
 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. Each returns its unsubscribe.
+`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:
@@ -200,5 +221,10 @@ const once = await store.subscribe(handler, { channel: 'from-socket', once: true
 ## Depends On
 
 - `@owlmeans/resource` — `StateResource` extends `Resource` and `PubSubResource`
-- `@owlmeans/context` — for `getStateResource`
-- React hooks: `@owlmeans/client`
+- `@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.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_ID = "_default";
+export declare const DEFAULT_ALIAS = "state";
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,UAAU,aAAa,CAAA;AACpC,eAAO,MAAM,aAAa,UAAU,CAAA"}

package/build/consts.js

@@ -0,0 +1,3 @@
+export const DEFAULT_ID = '_default';
+export const DEFAULT_ALIAS = 'state';
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAA;AACpC,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAA"}

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

package/build/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,aAAa;IACjD,OAAuB,QAAQ,SAAyC;IAExE;;;OAGG;IACH,gBAAuB,SAAS,EAAE,MAAM,CAAe;IAEvD,wFAAwF;IACxF,gBAAuB,IAAI,EAAE,MAAM,CAAU;gBAEjC,GAAG,EAAE,MAAM;CAIxB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,aAAa;IACjD,OAAuB,QAAQ,SAAyC;IAExE;;;OAGG;IACH,gBAAuB,SAAS,EAAE,MAAM,CAAe;IAEvD,wFAAwF;IACxF,gBAAuB,IAAI,EAAE,MAAM,CAAU;IAE7C,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF"}

package/build/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,aAAa;IAC1C,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,aAAa,CAAA;IAExE;;;OAGG;IACI,MAAM,CAAU,SAAS,GAAW,YAAY,CAAA;IAEvD,wFAAwF;IACjF,MAAM,CAAU,IAAI,GAAW,OAAO,CAAA;IAE7C,YAAY,GAAW;QACrB,KAAK,CAAC,gBAAgB,GAAG,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAA;IACvC,CAAC;;AAGH,aAAa,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,aAAa;IAC1C,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,aAAa,CAAA;IAExE;;;OAGG;IACI,MAAM,CAAU,SAAS,GAAW,YAAY,CAAA;IAEvD,wFAAwF;IACjF,MAAM,CAAU,IAAI,GAAW,OAAO,CAAA;IAE7C,YAAY,GAAW;QACrB,KAAK,CAAC,gBAAgB,GAAG,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAA;IACvC,CAAC;CACF;AAED,aAAa,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA"}

package/build/helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,cAAc,EAAE,OAAO,MAAM,KAAG,UAAU,CAAC,CAAC,CACzD,CAAA"}
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,SAAS,cAAc,SAAS,MAAM,KAAG,UAAU,CAAC,CAAC,CACzD,CAAA"}

package/build/index.d.ts

@@ -3,4 +3,5 @@ export * from './errors.js';
 export * from './helper.js';
 export * from './resource.js';
 export * from './utils/model.js';
+export type * from './utils/types.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,mBAAmB,kBAAkB,CAAA"}

package/build/resource.d.ts

@@ -1,5 +1,5 @@
-import type { BasicConfig as Config, BasicContext as Context } from '@owlmeans/context';
-import type { ResourceRecord } from '@owlmeans/resource';
+import { type BasicConfig as Config, type BasicContext as Context } from '@owlmeans/context';
+import { type ResourceRecord } from '@owlmeans/resource';
 import type { StateConfig, StateResource, StateResourceAppend } from './types.js';
 export declare const createStateResource: <T extends ResourceRecord>(alias?: string, cfg?: StateConfig<T>) => StateResource<T>;
 /**

package/build/resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,IAAI,MAAM,EAAE,YAAY,IAAI,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAKvF,OAAO,KAAK,EAC2B,cAAc,EAEpD,MAAM,oBAAoB,CAAA;AAG3B,OAAO,KAAK,EACV,WAAW,EAA0B,aAAa,EAAE,mBAAmB,EACxE,MAAM,YAAY,CAAA;AAgCnB,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,cAAc,EAC1D,QAAO,MAAc,EAAE,MAAM,WAAW,CAAC,CAAC,CAAC,KAC1C,aAAa,CAAC,CAAC,CA6XjB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC9B,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,cAAc,GAAG,cAAc,EACjF,KAAK,CAAC,EAAE,QAAO,MAAc,EAAE,MAAM,WAAW,CAAC,CAAC,CAAC,KAAG,CAAC,GAAG,mBAa3D,CAAA"}
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,WAAW,IAAI,MAAM,EAAE,KAAK,YAAY,IAAI,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAC9G,OAAO,EAAqI,KAAK,cAAc,EAAwE,MAAM,oBAAoB,CAAA;AAGjQ,OAAO,KAAK,EACV,WAAW,EAA0B,aAAa,EAAE,mBAAmB,EACxE,MAAM,YAAY,CAAA;AAQnB,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,cAAc,UACnD,MAAM,QAAgB,WAAW,CAAC,CAAC,CAAC,KAC1C,aAAa,CAAC,CAAC,CA8ZjB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC9B,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,cAAc,GAAG,cAAc,OAC5E,CAAC,UAAS,MAAM,QAAgB,WAAW,CAAC,CAAC,CAAC,KAAG,CAAC,GAAG,mBAa3D,CAAA"}

package/build/resource.js

@@ -1,16 +1,8 @@
 import { appendContextual } from '@owlmeans/context';
-import { applyQuery, filterRecords, firstMatch, RecordExists, sortRecords, UnknownRecordError, UnsupportedArgumentError } from '@owlmeans/resource';
+import { RecordExists, recordQueryHelper, UnknownRecordError, UnsupportedArgumentError } from '@owlmeans/resource';
 import { StateConfigError } from './errors.js';
 import { createStateModel } from './utils/model.js';
-/**
- * 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.
- */
-const SOLE = '';
-/** The channel writes publish on, and the one a subscriber gets when it names none. */
-const CHANGES = 'changes';
-/** The alias a context's first state resource takes when nothing else is asked for. */
-const STATE = 'state';
+import { CHANGES, SOLE, STATE } from './consts.local.js';
 /** Milliseconds until a subscription expires: a number is seconds from now, a Date the instant. */
 const expiresIn = (ttl) => ttl instanceof Date ? ttl.getTime() - Date.now() : ttl * 1000;
 export const createStateResource = (alias = STATE, cfg) => {
@@ -76,7 +68,7 @@ export const createStateResource = (alias = STATE, cfg) => {
         }
         return record;
     };
-    const first = (idOrWhere, opts) => typeof idOrWhere === 'string' ? read(idOrWhere) : firstMatch(records(), idOrWhere, opts);
+    const first = (idOrWhere, opts) => typeof idOrWhere === 'string' ? read(idOrWhere) : recordQueryHelper.firstMatch(records(), idOrWhere, opts);
     /** The store keeps no expiring records, so a ttl would be silently dropped. */
     const refuseTtl = (opts) => {
         if (opts?.ttl != null) {
@@ -113,7 +105,23 @@ export const createStateResource = (alias = STATE, cfg) => {
         models.set(key, { from: record, model });
         return model;
     };
-    const queryModels = (watch) => sortRecords(filterRecords(records(), watch.where), watch.opts?.sort)
+    /**
+     * The model for "nothing is addressed yet" — one instance, reused.
+     *
+     * It must be the SAME reference every time: a React subscriber compares snapshots by identity,
+     * and a freshly built model would read as a change on every render and loop. Writing through it
+     * is refused rather than silently dropped, because a caller that writes without an id has lost
+     * track of which record it meant.
+     */
+    let blank;
+    const emptyModel = () => blank ??= createStateModel({
+        id: undefined,
+        record: undefined,
+        default: config.default,
+        write: async () => { throw new StateConfigError(StateConfigError.NoId); },
+        drop: async () => { throw new StateConfigError(StateConfigError.NoId); }
+    });
+    const queryModels = (watch) => recordQueryHelper.sortRecords(recordQueryHelper.filterRecords(records(), watch.where), watch.opts?.sort)
         .map(record => modelFor(storedKey(record)));
     const same = (left, right) => left.length === right.length && left.every((model, index) => model === right[index]);
     /** Deliver on one channel. Returns what the handlers gave back, for a caller that awaits. */
@@ -194,9 +202,9 @@ export const createStateResource = (alias = STATE, cfg) => {
             if (opts?.page != null && opts.size == null) {
                 throw new UnsupportedArgumentError('page-without-size');
             }
-            return applyQuery(records(), where, opts);
+            return recordQueryHelper.applyQuery(records(), where, opts);
         },
-        count: async (where) => filterRecords(records(), where).length,
+        count: async (where) => recordQueryHelper.filterRecords(records(), where).length,
         create: async (record, opts) => {
             refuseTtl(opts);
             const key = keyOf(record);
@@ -239,7 +247,7 @@ export const createStateResource = (alias = STATE, cfg) => {
             if (where == null || Object.keys(where).length < 1) {
                 throw new UnsupportedArgumentError('purge:empty-criteria');
             }
-            const removed = filterRecords(records(), where)
+            const removed = recordQueryHelper.filterRecords(records(), where)
                 .map((record) => [storedKey(record), record]);
             for (const [key] of removed) {
                 store.delete(key);
@@ -271,6 +279,20 @@ export const createStateResource = (alias = STATE, cfg) => {
             notify('remove', dropped);
         },
         watch: (id, listener) => {
+            /**
+             * Watching before there is anything to watch is a RENDERING state, not a mistake.
+             *
+             * A screen binds to `useStoreModel(project.record.id)` while the project is still loading,
+             * so the id is legitimately absent for the first renders. Treating that as the
+             * configuration error it would be on `load()` or `save()` crashes the component tree over
+             * data that is simply not here yet. So an absent id on a listed resource watches nothing
+             * and reports an empty model; the error stays where it means something — a direct read or
+             * write with no id, which cannot be anything but a mistake.
+             */
+            if (id == null && !single) {
+                listener(emptyModel());
+                return () => { };
+            }
             const key = keyFor(id);
             let listeners = watchers.get(key);
             if (listeners == null) {