@owlmeans/state 0.1.18-rc.3 → 0.1.18-rc.30

package/README.md

@@ -1,85 +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-rc.29
 ```
 
+## 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
+```
+
+### Read it from React
+
+The hooks live in [`@owlmeans/client`](../client):
+
+```tsx
+import { useStoreList, useStoreModel } from '@owlmeans/client'
+
+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 })} />
+}
+```
+
+### A single-record store with a default
+
+```ts
+export const DRAFT = stateAlias<InvoiceDraft>('invoice-draft')
+
+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
 ```
 
-Update state and commit:
+### 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
+})
 
-```typescript
-const [model] = resource.subscribe({ id: projectId, listener: ... })[1]
-model.update({ status: 'active' })
-model.commit()  // triggers listeners
+socket.on('story', async (event: StoryEvent) => {
+  if (event.type === 'removed') {
+    await store.delete(event.id)
+  } else {
+    await store.save(event.story)
+  }
+})
 ```
 
 ## API
 
-### `createStateResource<T>(alias?): StateResource<T>`
+### `appendStateResource<C, T, R>(context, alias?, config?): T & StateResourceAppend`
 
-Creates an in-memory resource with subscription support. Registers under `alias` (default: `'state'`).
+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.
 
-### `StateResource<T>` (extends `Resource<T>`)
+### `createStateResource<T>(alias?, config?): StateResource<T>`
 
-- `subscribe(params): [unsubscribe, StateModel<T>[]]` — subscribe to record changes; returns current records
-- `listen(listener)` — global listener for any change in the resource
-- `erase()` — clear all records
+The bare factory, for registering the resource by hand. `appendStateResource` is the usual way.
 
-### `StateModel<T>`
+### `StateConfig<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
+| 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 |
 
-### `DEFAULT_ID`
+### `StateResource<T>` (extends `Resource<T>`, `PubSubResource<StateEvent<T>>`)
 
-```typescript
-const DEFAULT_ID = '_default'  // conventional ID for single-item resources
-```
+- `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.
 
-## Related Packages
+### `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
@@ -89,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-rc.33
 ```
 
 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,
   "package": "@owlmeans/state",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.505Z",
+  "version": "0.1.18-rc.30",
+  "generatedAt": "2026-09-22T17:39:02.518Z",
   "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 state resource on a context, then ctx.getStateResource(alias) to read/write typed application state. Auto-invoked when importing state primitives.
+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,40 +8,223 @@ user-invocable: false
 # @owlmeans/state
 
 **Layer:** Core
-**Install:** `"@owlmeans/state": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/state": "^0.1.18-rc.30"` 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. 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 |
-| `StateResource<T>` types | Typed state container interface |
-| Errors | Typed state errors |
-| Constants | Default state aliases |
+| `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.
 
-## Usage
+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.
 
-Append a state resource at context construction time, expose a typed accessor:
+## Registering
+
+Every client context already carries one default state resource, so `useStoreModel(id)` works with
+no setup at all. Register a named one per entity when records of different kinds must not share an
+id space:
 
 ```typescript
-import { appendStateResource } from '@owlmeans/state'
+import { appendStateResource, stateAlias } from '@owlmeans/state'
 
-export const VIB_PROJECT_STATE = 'vib-project-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, VIB_PROJECT_STATE)
-  context.projectStore = () => context.getStateResource(VIB_PROJECT_STATE)
+  const context = makeClientContext<C, T>(cfg)
+  appendStateResource<C, T, Task>(context, TASKS)
   return context
 }
+```
+
+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
+
+```typescript
+import { useStoreList, useStoreModel } from '@owlmeans/client'
+
+// One record, by id. Re-renders whenever that record changes.
+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: TASKS })
+open.map(model => model.record.title)
+
+// 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. An omitted `query` matches everything.
+
+**"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
+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.
 
-// Later, in a component or handler:
-const store = ctx.projectStore()
-const current = await store.get('current')
+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(TASKS)
+
+const tasks = await ctx.entrypoint(taskEntrypoints.list).call()
+await store.replace(tasks)
+```
+
+`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 SNAPSHOT. Assigning to it changes nothing anyone else can see:
+
+```typescript
+model.record.title = 'renamed'      // WRONG — a silent no-op, nothing re-renders
+await model.update({ title: 'renamed' })  // RIGHT — merges and commits
+```
+
+`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
+
+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.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'`).
+- `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' }`.
+
+`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 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'] })
+```
+
+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`
-- `@owlmeans/error`, `@owlmeans/i18n`
+- `@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/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;IAEpE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF;AAED,qBAAa,kBAAmB,SAAQ,iBAAiB;IACvD,OAAuB,QAAQ,SAA0C;IAEzE,YAAY,GAAG,EAAE,MAAM,EAGtB;CACF"}
+{"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

@@ -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;CACF;AAED,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;CACF;AAED,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;CACF;AAED,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,SAAS,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"}