@owlmeans/state 0.1.18-rc.7 → 0.1.18-rc.9

package/README.md

@@ -1,13 +1,18 @@
 # @owlmeans/state
 
-In-memory reactive state management with subscription-based updates for OwlMeans apps.
+The framework's client store: an in-memory `Resource` with live subscriptions.
 
 ## 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
+- `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`
 
 ## Installation
 
@@ -17,91 +22,110 @@ bun add @owlmeans/state
 
 ## Usage
 
-Create and register a state resource in context setup:
+Register a store per record type, and name it once with the type attached:
 
 ```typescript
-import { createStateResource } from '@owlmeans/state'
+import { appendStateResource, stateAlias } from '@owlmeans/state'
 
-// In context.ts
-context.registerResource(createStateResource<ProjectState>('project-state'))
+export const TASKS = stateAlias<Task>('tasks')
+
+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)
+
+  return context
+}
+
+const tasks = context.getStateResource(TASKS)   // StateResource<Task>
 ```
 
-Subscribe to state changes in a service or component:
+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 with the hooks in [`@owlmeans/client`](../client):
 
 ```typescript
-import { DEFAULT_ID } from '@owlmeans/state'
-import type { StateModel, StateResource } from '@owlmeans/state'
-
-const resource = context.resource<StateResource<ProjectState>>('project-state')
-
-const [unsubscribe] = resource.subscribe({
-  id: DEFAULT_ID,
-  listener: (models) => {
-    const [model] = models
-    console.log('project updated:', model.record)
-  }
-})
+import { useStoreList, useStoreModel } from '@owlmeans/client'
+
+const task = useStoreModel<Task>(id, 'tasks')                       // one record, live
+const open = useStoreList<Task>({ query: { status: 'open' }, resource: 'tasks' })
 ```
 
-Update state and commit:
+Write through the resource, or through the model a subscription handed you:
 
 ```typescript
-const [model] = resource.subscribe({ id: projectId, listener: ... })[1]
-model.update({ status: 'active' })
-model.commit()  // triggers listeners
+const tasks = context.getStateResource(TASKS)
+
+await tasks.save(record)                 // create or replace
+await tasks.replace(fromTheServer)       // write these, drop everything else
+await tasks.purge({ status: 'done' })
+await tasks.clear()
+
+model.update({ status: 'done' })         // merge and write in one step
 ```
 
 ## API
 
-### `createStateResource<T>(alias?): StateResource<T>`
+### `createStateResource<T>(alias?, config?): StateResource<T>`
 
-Creates an in-memory resource with subscription support. Registers under `alias` (default: `'state'`).
+The bare factory, when the resource is registered by hand. `appendStateResource` is the usual way.
 
-### `StateResource<T>` (extends `Resource<T>`)
+### `StateConfig<T>`
 
-- `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
+| 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 |
 
-### Criteria
+### `StateResource<T>` (extends `Resource<T>`, `PubSubResource<StateEvent<T>>`)
 
-`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.
+- `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
+  announces itself as a `StateEvent` on the default channel
 
-```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 */ }
-})
-```
+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.
 
 ### `StateModel<T>`
 
-- `record: T` — the current record
-- `update(data?)` — merge partial data into the record
-- `commit(force?)` — apply changes and notify subscribers
-- `clear()` — remove the record
+- `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
 
-### `DEFAULT_ID`
+`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.
 
-```typescript
-const DEFAULT_ID = '_default'  // conventional ID for single-item resources
-```
+### `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) — `Resource<T>` interface implemented by StateResource
-- [`@owlmeans/client`](../client) — `useStoreModel` / `useStoreList` React hooks for state resources
+- [`@owlmeans/resource`](../resource) — the `Resource<T>` contract and the criteria engine
+- [`@owlmeans/client`](../client) — `useStoreModel` / `useStoreList` React hooks
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/state",
-  "version": "0.1.18-rc.7",
-  "generatedAt": "2026-08-22T23:28:30.595Z",
+  "version": "0.1.18-rc.9",
+  "generatedAt": "2026-09-01T16:28:56.989Z",
   "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,28 @@ user-invocable: false
 # @owlmeans/state
 
 **Layer:** Core
-**Install:** `"@owlmeans/state": "^0.1.18-rc.7"` in `dependencies`
+**Install:** `"@owlmeans/state": "^0.1.18-rc.9"` 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` |
+| `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) |
+
+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 +41,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 +73,132 @@ 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.
+
+`useStoreModel()` with no id addresses the one record of a `single` resource. On any other that is a
+wiring mistake and throws `StateConfigError` (`NonSingle`).
+
 ## 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<ClientEntrypoint<Task[]>>(TASK_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.
+
+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.
 
 ### 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. Each returns its unsubscribe.
+
+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/resource` — `StateResource` extends `Resource` and `PubSubResource`
 - `@owlmeans/context` — for `getStateResource`
 - React hooks: `@owlmeans/client`

package/build/errors.d.ts

@@ -1,10 +1,17 @@
 import { ResourceError } from '@owlmeans/resource';
-export declare class StateToolingError extends ResourceError {
-    static typeName: string;
-    constructor(msg: string);
-}
-export declare class StateListenerError extends StateToolingError {
+/**
+ * The resource was asked for something its {@link StateConfig} does not allow. Both cases are
+ * wiring mistakes rather than missing data, so they throw instead of answering with nothing.
+ */
+export declare class StateConfigError extends ResourceError {
     static typeName: string;
+    /**
+     * A record was addressed without an id on a resource that holds many of them. Only a `single`
+     * resource has a record that needs no naming.
+     */
+    static readonly NonSingle: string;
+    /** A write carried no value for the resource's id field, and nothing here mints one. */
+    static readonly NoId: string;
     constructor(msg: string);
 }
 //# sourceMappingURL=errors.d.ts.map

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,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,OAAuB,QAAQ,SAAqC;gBAExD,GAAG,EAAE,MAAM;CAIxB;AAED,qBAAa,kBAAmB,SAAQ,iBAAiB;IACvD,OAAuB,QAAQ,SAA0C;gBAE7D,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;gBAEjC,GAAG,EAAE,MAAM;CAIxB"}

package/build/errors.js

@@ -1,18 +1,21 @@
 import { ResourceError } from '@owlmeans/resource';
-export class StateToolingError extends ResourceError {
-    static typeName = `${ResourceError.typeName}Tooling`;
+/**
+ * The resource was asked for something its {@link StateConfig} does not allow. Both cases are
+ * wiring mistakes rather than missing data, so they throw instead of answering with nothing.
+ */
+export class StateConfigError extends ResourceError {
+    static typeName = `${ResourceError.typeName}StateConfig`;
+    /**
+     * A record was addressed without an id on a resource that holds many of them. Only a `single`
+     * resource has a record that needs no naming.
+     */
+    static NonSingle = 'non-single';
+    /** A write carried no value for the resource's id field, and nothing here mints one. */
+    static NoId = 'no-id';
     constructor(msg) {
-        super(`tooling:${msg}`);
-        this.type = StateToolingError.typeName;
+        super(`state-config:${msg}`);
+        this.type = StateConfigError.typeName;
     }
 }
-export class StateListenerError extends StateToolingError {
-    static typeName = `${StateToolingError.typeName}Listener`;
-    constructor(msg) {
-        super(`listener:${msg}`);
-        this.type = StateListenerError.typeName;
-    }
-}
-ResourceError.registerErrorClass(StateToolingError);
-ResourceError.registerErrorClass(StateListenerError);
+ResourceError.registerErrorClass(StateConfigError);
 //# sourceMappingURL=errors.js.map

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,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAC3C,MAAM,CAAU,QAAQ,GAAG,GAAG,aAAa,CAAC,QAAQ,SAAS,CAAA;IAEpE,YAAY,GAAW;QACrB,KAAK,CAAC,WAAW,GAAG,EAAE,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC,QAAQ,CAAA;IACxC,CAAC;;AAGH,MAAM,OAAO,kBAAmB,SAAQ,iBAAiB;IAChD,MAAM,CAAU,QAAQ,GAAG,GAAG,iBAAiB,CAAC,QAAQ,UAAU,CAAA;IAEzE,YAAY,GAAW;QACrB,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAA;IACzC,CAAC;;AAGH,aAAa,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAA;AACnD,aAAa,CAAC,kBAAkB,CAAC,kBAAkB,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;;AAGH,aAAa,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA"}

package/build/helper.d.ts

@@ -0,0 +1,16 @@
+import type { ResourceRecord } from '@owlmeans/resource';
+import type { StateAlias } from './types.js';
+/**
+ * Name a state resource once, with the record type it holds attached:
+ *
+ * ```typescript
+ * export const TASKS = stateAlias<Task>('tasks')
+ * const tasks = context.getStateResource(TASKS)   // StateResource<Task>
+ * ```
+ *
+ * The handle is the string itself at runtime — the type rides along only so that every reader of
+ * the alias gets the record type without repeating it, and so that a mismatch is a compile error
+ * instead of a record shaped like nothing anyone expected.
+ */
+export declare const stateAlias: <T extends ResourceRecord>(alias: string) => StateAlias<T>;
+//# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -0,0 +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"}

package/build/helper.js

@@ -0,0 +1,14 @@
+/**
+ * Name a state resource once, with the record type it holds attached:
+ *
+ * ```typescript
+ * export const TASKS = stateAlias<Task>('tasks')
+ * const tasks = context.getStateResource(TASKS)   // StateResource<Task>
+ * ```
+ *
+ * The handle is the string itself at runtime — the type rides along only so that every reader of
+ * the alias gets the record type without repeating it, and so that a mismatch is a compile error
+ * instead of a record shaped like nothing anyone expected.
+ */
+export const stateAlias = (alias) => alias;
+//# sourceMappingURL=helper.js.map

package/build/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAA2B,KAAa,EAAiB,EAAE,CACnF,KAAsB,CAAA"}

package/build/index.d.ts

@@ -1,6 +1,6 @@
 export type * from './types.js';
-export * from './consts.js';
 export * from './errors.js';
+export * from './helper.js';
 export * from './resource.js';
-export * from './utils/criteria.js';
+export * from './utils/model.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,qBAAqB,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"}

package/build/index.js

@@ -1,5 +1,5 @@
-export * from './consts.js';
 export * from './errors.js';
+export * from './helper.js';
 export * from './resource.js';
-export * from './utils/criteria.js';
+export * from './utils/model.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA"}