@owlmeans/state 0.1.18-rc.2 → 0.1.18-rc.21

package/build/types.d.ts

@@ -1,39 +1,108 @@
-import type { ListCriteria, Resource, ResourceRecord } from '@owlmeans/resource';
-export interface StateResource<T extends ResourceRecord> extends Resource<T> {
+import type { Criteria, FirstOptions, PubSubResource, Resource, ResourceRecord } from '@owlmeans/resource';
+/**
+ * How a state resource is keyed and what it shows before anything is loaded.
+ *
+ * Everything here is optional: an unconfigured resource keys records by `id`, holds as many of
+ * them as it is given, and shows an empty object until a record arrives.
+ */
+export interface StateConfig<T extends ResourceRecord> {
+    /** The field records are keyed by. Defaults to `id`. */
+    id?: keyof T & string;
     /**
-     * @returns unsubscribe function
+     * The resource 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: elsewhere there is no "the record" to address.
      */
-    subscribe: (params: StateSubscriptionOption<T>) => [() => void, StateModel<T>[]];
-    listen: (listener: StateListener<T>) => () => void;
-    erase: () => Promise<void>;
+    single?: boolean;
+    /**
+     * What {@link StateModel.record} shows while the model is empty. A screen that binds to a
+     * record before it has arrived reads the default instead of guarding every field — and the
+     * store still holds nothing, so nothing renders it as a row.
+     */
+    default?: () => T;
 }
-export interface StateSubscriptionOption<T extends ResourceRecord> {
-    id?: string | string[];
-    _systemId?: string;
-    query?: ListCriteria;
-    default?: Partial<T>;
-    listener: StateListener<T>;
+/** One change to the store, as its subscribers see it. */
+export interface StateEvent<T extends ResourceRecord> {
+    type: 'set' | 'remove';
+    records: T[];
 }
-export interface StateListener<T extends ResourceRecord> {
-    (record: StateModel<T>[], systemId?: string): void | Promise<void>;
+/**
+ * The framework's client store: a `Resource` like any other, registered ON the context — which is
+ * what separates it from a store held beside the app, since a screen, a service and a guard all
+ * reach the same records through the same container.
+ *
+ * Reads and writes are the resource vocabulary; `watch` and `query` are the live half, and they
+ * are synchronous on purpose — a React subscriber has to have its value before it renders.
+ */
+export interface StateResource<T extends ResourceRecord> extends Resource<T>, PubSubResource<StateEvent<T>> {
+    readonly config: StateConfig<T>;
+    /**
+     * Make 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.
+     */
+    replace(records: T[]): Promise<void>;
+    /** Drop every record. */
+    clear(): Promise<void>;
+    /**
+     * Follow one record. The listener is called with the current model straight away — before
+     * `watch` returns — and again on every change to that record, including its removal.
+     *
+     * `undefined` addresses the one record of a `single` resource; on any other it throws, since
+     * there is nothing for it to mean.
+     *
+     * An absent id on a listed resource watches nothing and reports an empty model — a screen
+     * binds before the record supplying the id exists, and that is a loading state, not an error.
+     * @returns unsubscribe
+     */
+    watch(id: string | undefined, listener: (model: StateModel<T>) => void): () => void;
+    /**
+     * Follow a live QUERY. The listener is called with the matching models straight away and again
+     * whenever a write changes the answer, so a list screen never recomputes ids and never
+     * re-subscribes to keep up. `undefined` matches every record.
+     *
+     * A query subscription creates nothing: an empty store yields an empty list.
+     *
+     * @returns unsubscribe
+     */
+    query(where: Criteria<T> | undefined, listener: (models: StateModel<T>[]) => void, opts?: FirstOptions<T>): () => void;
 }
+/**
+ * One record, as something bound to it can hold: what it currently says, and how to change it.
+ *
+ * `record` is a snapshot — assigning into it changes nothing anyone can see. `update` is how a
+ * change reaches the store and every other subscriber.
+ */
 export interface StateModel<T extends ResourceRecord> {
-    record: T;
-    commit: (force?: boolean) => void;
-    update: (data?: Partial<T>) => void;
-    clear: () => void;
-}
-export interface StateResourceAppend {
-    getStateResource: <T extends ResourceRecord>(alias?: string) => StateResource<T>;
-}
-export interface UseStoreHelper {
-    <T extends ResourceRecord>(id?: string | UseStoreHelperOptions<T>, opts?: string | boolean | UseStoreHelperOptions<T>): StateModel<T>;
+    readonly id: string | undefined;
+    /**
+     * Nothing is loaded yet: the store holds no record under this model's key. This — not a
+     * sentinel id, and not a placeholder record — is what "not there" looks like, so a subscription
+     * to an unknown id leaves the store exactly as empty as it found it.
+     */
+    readonly empty: boolean;
+    /** The record, or the configured `default` while {@link StateModel.empty} is true. */
+    readonly record: Readonly<T>;
+    /** Merge and write in one step. */
+    update(patch: Partial<T>): Promise<T>;
+    /** Write what {@link StateModel.record} currently holds — including a default not yet stored. */
+    commit(): Promise<T>;
+    clear(): Promise<void>;
 }
-export interface UseStoreListHelper {
-    <T extends ResourceRecord>(id?: string | string[] | UseStoreHelperOptions<T>, opts?: string | boolean | UseStoreHelperOptions<T>): StateModel<T>[];
+/**
+ * A state alias that remembers the record type it addresses, so `getStateResource(TASKS)` is
+ * typed without repeating `<Task>` at every call site. Built by {@link stateAlias}; it is a plain
+ * string at runtime, so it works anywhere an alias is expected.
+ */
+export type StateAlias<T extends ResourceRecord> = string & {
+    readonly _state?: T;
+};
+export interface GetStateResource {
+    <T extends ResourceRecord>(alias: StateAlias<T>): StateResource<T>;
+    <T extends ResourceRecord = ResourceRecord>(alias?: string): StateResource<T>;
 }
-export interface UseStoreHelperOptions<T extends ResourceRecord> extends Omit<StateSubscriptionOption<T>, "listener"> {
-    listen?: boolean;
-    resource?: string;
+export interface StateResourceAppend {
+    /** The state resource under `alias`, or the first one appended to the context. */
+    getStateResource: GetStateResource;
 }
 //# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEhF,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,cAAc,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC;IAC1E;;OAEG;IACH,SAAS,EAAE,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAChF,MAAM,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,CAAA;IAClD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,cAAc;IAC/D,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACpB,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;CAC3B;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,cAAc;IACrD,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnE;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,cAAc;IAClD,MAAM,EAAE,CAAC,CAAC;IAEV,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;IAEjC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IAEnC,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,EAAE,CAAC,CAAC,SAAS,cAAc,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,aAAa,CAAC,CAAC,CAAC,CAAA;CACjF;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,CAAC,SAAS,cAAc,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,qBAAqB,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,qBAAqB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAA;CACtI;AAED,MAAM,WAAW,kBAAkB;IACjC,CAAC,CAAC,SAAS,cAAc,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,qBAAqB,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,qBAAqB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,CAAA;CACnJ;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,cAAc,CAAE,SAAQ,IAAI,CAAC,uBAAuB,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC;IACnH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,EACjE,MAAM,oBAAoB,CAAA;AAE3B;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,SAAS,cAAc;IACnD,wDAAwD;IACxD,EAAE,CAAC,EAAE,MAAM,CAAC,GAAG,MAAM,CAAA;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,CAAA;CAClB;AAED,0DAA0D;AAC1D,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,cAAc;IAClD,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAA;IACtB,OAAO,EAAE,CAAC,EAAE,CAAA;CACb;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,cAAc,CAAE,SAAQ,QAAQ,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACzG,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAA;IAE/B;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEpC,yBAAyB;IACzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtB;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAEnF;;;;;;;;OAQG;IACH,KAAK,CACH,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,EAC9B,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,EAC3C,IAAI,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,GACrB,MAAM,IAAI,CAAA;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,cAAc;IAClD,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;IAC5B,mCAAmC;IACnC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACrC,iGAAiG;IACjG,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,CAAA;IACpB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,cAAc,IAAI,MAAM,GAAG;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;CAAE,CAAA;AAEnF,MAAM,WAAW,gBAAgB;IAC/B,CAAC,CAAC,SAAS,cAAc,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;IAClE,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;CAC9E;AAED,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,gBAAgB,EAAE,gBAAgB,CAAA;CACnC"}

package/build/utils/model.d.ts

@@ -1,4 +1,24 @@
 import type { ResourceRecord } from '@owlmeans/resource';
-import type { StateModel, StateResource } from '../types.js';
-export declare const createStateModel: <T extends ResourceRecord>(record: T, resource: StateResource<T>) => StateModel<T>;
+import type { StateModel } from '../types.js';
+/**
+ * What a model needs from the resource that made it: which record it stands for, and the two
+ * writes it can perform. The key stays on the resource side, so a model bound to the one record
+ * of a `single` resource works the same as one bound to an id.
+ */
+export interface StateModelBinding<T extends ResourceRecord> {
+    id: string | undefined;
+    /** The stored record, or `undefined` when the store holds none — an EMPTY model. */
+    record: T | undefined;
+    default?: () => T;
+    write: (record: T) => Promise<T>;
+    drop: () => Promise<void>;
+}
+/**
+ * Wrap one record — or its absence — as something a screen can bind to.
+ *
+ * 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.
+ */
+export declare const createStateModel: <T extends ResourceRecord>(binding: StateModelBinding<T>) => StateModel<T>;
 //# sourceMappingURL=model.d.ts.map

package/build/utils/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/utils/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAExD,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE5D,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,cAAc,UAC/C,CAAC,YAAY,aAAa,CAAC,CAAC,CAAC,KACpC,UAAU,CAAC,CAAC,CAmCd,CAAA"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/utils/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,cAAc;IACzD,EAAE,EAAE,MAAM,GAAG,SAAS,CAAA;IACtB,oFAAoF;IACpF,MAAM,EAAE,CAAC,GAAG,SAAS,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,CAAA;IACjB,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;IAChC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,cAAc,WAC9C,iBAAiB,CAAC,CAAC,CAAC,KAC5B,UAAU,CAAC,CAAC,CAmCd,CAAA"}

package/build/utils/model.js

@@ -1,28 +1,32 @@
-import { MisshapedRecord } from '@owlmeans/resource';
-export const createStateModel = (record, resource) => {
-    let before = record;
+/**
+ * Wrap one record — or its absence — as something a screen can bind to.
+ *
+ * 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.
+ */
+export const createStateModel = (binding) => {
+    /** What an empty model shows: the configured default, or nothing at all. */
+    const blank = () => binding.default?.() ?? {};
+    let working = binding.record ?? blank();
+    let stored = binding.record != null;
     const model = {
-        record: { ...record },
-        commit: force => {
-            if (force !== true) {
-                if (!Object.entries(before).reduce((changed, [key, value]) => changed || model.record[key] !== value, false) && !Object.entries(model.record).reduce((changed, [key, value]) => changed || before[key] !== value, false)) {
-                    return;
-                }
-            }
-            if (record.id == null) {
-                throw new MisshapedRecord('id');
-            }
-            before = model.record;
-            void resource.load(record.id).then(exists => {
-                exists != null && resource.update(model.record);
-            });
+        get id() { return binding.id; },
+        get empty() { return !stored; },
+        get record() { return working; },
+        update: async (patch) => {
+            working = { ...working, ...patch };
+            return model.commit();
         },
-        update: data => {
-            Object.assign(model.record, data);
-            model.commit();
+        commit: async () => {
+            working = await binding.write(working);
+            stored = true;
+            return working;
         },
-        clear: () => {
-            void resource.delete(record);
+        clear: async () => {
+            await binding.drop();
+            stored = false;
+            working = blank();
         }
     };
     return model;

package/build/utils/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/utils/model.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAGpD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,MAAS,EAAE,QAA0B,EACtB,EAAE;IACjB,IAAI,MAAM,GAAM,MAAM,CAAA;IACtB,MAAM,KAAK,GAAkB;QAC3B,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE;QAErB,MAAM,EAAE,KAAK,CAAC,EAAE;YACd,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAChC,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,GAAc,CAAC,KAAK,KAAK,EAAE,KAAK,CACpF,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,CACvC,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,OAAO,IAAI,MAAM,CAAC,GAAc,CAAC,KAAK,KAAK,EAAE,KAAK,CAC9E,EAAE,CAAC;oBACF,OAAM;gBACR,CAAC;YACH,CAAC;YACD,IAAI,MAAM,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC;gBACtB,MAAM,IAAI,eAAe,CAAC,IAAI,CAAC,CAAA;YACjC,CAAC;YACD,MAAM,GAAG,KAAK,CAAC,MAAM,CAAA;YACrB,KAAK,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;gBAC1C,MAAM,IAAI,IAAI,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;YACjD,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,MAAM,EAAE,IAAI,CAAC,EAAE;YACb,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;YACjC,KAAK,CAAC,MAAM,EAAE,CAAA;QAChB,CAAC;QAED,KAAK,EAAE,GAAG,EAAE;YACV,KAAK,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC9B,CAAC;KACF,CAAA;IAED,OAAO,KAAK,CAAA;AACd,CAAC,CAAA"}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/utils/model.ts"],"names":[],"mappings":"AAiBA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,OAA6B,EACd,EAAE;IACjB,4EAA4E;IAC5E,MAAM,KAAK,GAAG,GAAM,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,IAAI,EAAO,CAAA;IAErD,IAAI,OAAO,GAAM,OAAO,CAAC,MAAM,IAAI,KAAK,EAAE,CAAA;IAC1C,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAA;IAEnC,MAAM,KAAK,GAAkB;QAC3B,IAAI,EAAE,KAAK,OAAO,OAAO,CAAC,EAAE,CAAA,CAAC,CAAC;QAE9B,IAAI,KAAK,KAAK,OAAO,CAAC,MAAM,CAAA,CAAC,CAAC;QAE9B,IAAI,MAAM,KAAK,OAAO,OAAO,CAAA,CAAC,CAAC;QAE/B,MAAM,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACpB,OAAO,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,EAAO,CAAA;YAEvC,OAAO,KAAK,CAAC,MAAM,EAAE,CAAA;QACvB,CAAC;QAED,MAAM,EAAE,KAAK,IAAI,EAAE;YACjB,OAAO,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;YACtC,MAAM,GAAG,IAAI,CAAA;YAEb,OAAO,OAAO,CAAA;QAChB,CAAC;QAED,KAAK,EAAE,KAAK,IAAI,EAAE;YAChB,MAAM,OAAO,CAAC,IAAI,EAAE,CAAA;YACpB,MAAM,GAAG,KAAK,CAAA;YACd,OAAO,GAAG,KAAK,EAAE,CAAA;QACnB,CAAC;KACF,CAAA;IAED,OAAO,KAAK,CAAA;AACd,CAAC,CAAA"}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/state",
-  "version": "0.1.18-rc.2",
+  "version": "0.1.18-rc.21",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 342 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -21,8 +22,8 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.18-rc.2",
-    "@owlmeans/resource": "^0.1.18-rc.2"
+    "@owlmeans/context": "^0.1.18-rc.19",
+    "@owlmeans/resource": "^0.1.18-rc.20"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/src/errors.ts

@@ -1,23 +1,26 @@
 
 import { ResourceError } from '@owlmeans/resource'
 
-export class StateToolingError extends ResourceError {
-  public static override 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 {
+  public static override typeName = `${ResourceError.typeName}StateConfig`
 
-  constructor(msg: string) {
-    super(`tooling:${msg}`)
-    this.type = StateToolingError.typeName
-  }
-}
+  /**
+   * 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.
+   */
+  public static readonly NonSingle: string = 'non-single'
 
-export class StateListenerError extends StateToolingError {
-  public static override typeName = `${StateToolingError.typeName}Listener`
+  /** A write carried no value for the resource's id field, and nothing here mints one. */
+  public static readonly NoId: string = 'no-id'
 
   constructor(msg: string) {
-    super(`listener:${msg}`)
-    this.type = StateListenerError.typeName
+    super(`state-config:${msg}`)
+    this.type = StateConfigError.typeName
   }
 }
 
-ResourceError.registerErrorClass(StateToolingError)
-ResourceError.registerErrorClass(StateListenerError)
+ResourceError.registerErrorClass(StateConfigError)

package/src/helper.ts

@@ -0,0 +1,17 @@
+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 const stateAlias = <T extends ResourceRecord>(alias: string): StateAlias<T> =>
+  alias as StateAlias<T>

package/src/index.ts

@@ -1,6 +1,7 @@
 
 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'