@owlmeans/state 0.1.18-rc.0 → 0.1.18-rc.10

package/README.md

@@ -1,85 +1,131 @@
 # @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
 
 ```bash
-bun add @owlmeans/state
+bun add @owlmeans/state@^0.1.18-rc.9
 ```
 
 ## 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>`
+
+The bare factory, when the resource is registered by hand. `appendStateResource` is the usual way.
+
+### `StateConfig<T>`
 
-Creates an in-memory resource with subscription support. Registers under `alias` (default: `'state'`).
+| 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 |
 
-### `StateResource<T>` (extends `Resource<T>`)
+### `StateResource<T>` (extends `Resource<T>`, `PubSubResource<StateEvent<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
+- `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
+
+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
@@ -89,7 +135,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.12
 ```
 
 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.10",
+  "generatedAt": "2026-09-04T22:43:25.442Z",
   "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.10"` 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<ClientEntrypoint<Task[]>>(TASK_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"}

package/build/index.d.ts

@@ -1,5 +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/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"}
+{"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,4 +1,5 @@
-export * from './consts.js';
 export * from './errors.js';
+export * from './helper.js';
 export * from './resource.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"}
+{"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"}

package/build/resource.d.ts

@@ -1,6 +1,13 @@
+import type { BasicConfig as Config, BasicContext as Context } from '@owlmeans/context';
 import type { ResourceRecord } from '@owlmeans/resource';
-import type { StateResource, StateResourceAppend } from './types.js';
-import type { BasicContext as Context, BasicConfig as Config } from '@owlmeans/context';
-export declare const createStateResource: <R extends ResourceRecord>(alias?: string) => StateResource<R>;
-export declare const appendStateResource: <C extends Config, T extends Context<C>>(ctx: T, alias?: string) => T & StateResourceAppend;
+import type { StateConfig, StateResource, StateResourceAppend } from './types.js';
+export declare const createStateResource: <T extends ResourceRecord>(alias?: string, cfg?: StateConfig<T>) => StateResource<T>;
+/**
+ * Register a state resource on the context and expose `getStateResource`.
+ *
+ * Idempotent: appending the same alias twice keeps the resource that is already there, so a
+ * setup that runs more than once does not drop what the store has collected. The first alias
+ * appended is the one `getStateResource()` answers with when it is called without one.
+ */
+export declare const appendStateResource: <C extends Config, T extends Context<C>, R extends ResourceRecord = ResourceRecord>(ctx: T, alias?: string, cfg?: StateConfig<R>) => T & StateResourceAppend;
 //# sourceMappingURL=resource.d.ts.map

package/build/resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAgC,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACtF,OAAO,KAAK,EAAiB,aAAa,EAAE,mBAAmB,EAA2B,MAAM,YAAY,CAAA;AAI5G,OAAO,KAAK,EAAE,YAAY,IAAI,OAAO,EAAE,WAAW,IAAI,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAEvF,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,cAAc,UAAS,MAAM,KAAmB,aAAa,CAAC,CAAC,CA6N5G,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,OACnE,CAAC,UAAS,MAAM,KACpB,CAAC,GAAG,mBAWN,CAAA"}
+{"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,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"}