Imported from owlmeans/common (.agents/skills/state/SKILL.md). Install upstream with npx skills add owlmeans/common --skill state. Copyright stays with the author.

@owlmeans/state

Layer: Core 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. Reads and writes are the resource vocabulary of [[resource]]; watch and query are the live half.

Key Exports

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.

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:

import { appendStateResource, stateAlias } from '@owlmeans/state'

export const TASKS = stateAlias<Task>('task-state')

export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
  const context = makeClientContext<C, T>(cfg)
  appendStateResource<C, T, Task>(context, TASKS)
  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:

Reading it from React

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:

if (task.empty) {
  return <Spinner/>
}

model.record is still readable while empty: it holds the resource's configured default, or {} when there is none. Calling model.update(...) or model.commit() on an empty model writes it — including the default it was showing.

An ABSENT id answers the same way. A screen binds to useStoreModel(project.record.id) while the project is still loading, so a missing id is a rendering state rather than a mistake: on a listed store it watches nothing and reports an empty model, and on a single store it addresses that store's sole record. The empty model it hands back is one shared instance, so a React subscriber does not see a new value on every render — and writing through it throws StateConfigError (NoId), because a caller writing with no id has lost track of which record it meant.

Writing to it

The server is the source of truth; the store is what the screen reads. Fetch, then write what came back into the store, and let the subscriptions render it:

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:

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:

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

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:

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