@owlmeans/state 0.1.18-rc.8 → 0.1.18

package/src/types.local.ts

@@ -0,0 +1,16 @@
+import type { Criteria, FirstOptions, ResourceRecord } from '@owlmeans/resource'
+import type { StateEvent, StateModel } from './types.js'
+
+export interface QueryWatch<T extends ResourceRecord> {
+  where?: Criteria<T>
+  opts?: FirstOptions<T>
+  listener: (models: StateModel<T>[]) => void
+  last: StateModel<T>[]
+}
+
+export interface Subscription<T extends ResourceRecord> {
+  handler: (value: StateEvent<T>) => void | Promise<void>
+  channel: string
+  once: boolean
+  timer?: ReturnType<typeof setTimeout>
+}

package/src/types.ts

@@ -1,79 +1,122 @@
-import type { ListCriteria, Resource, ResourceRecord } from '@owlmeans/resource'
+import type {
+  Criteria, FirstOptions, PubSubResource, Resource, ResourceRecord
+} from '@owlmeans/resource'
 
-export interface StateResource<T extends ResourceRecord> extends Resource<T> {
+/**
+ * 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
+}
+
+/** One change to the store, as its subscribers see it. */
+export interface StateEvent<T extends ResourceRecord> {
+  type: 'set' | 'remove'
+  records: T[]
+}
+
+/**
+ * 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>
 
   /**
-   * Every record held, as a plain array.
-   *
-   * `list()` answers the `Resource` contract and therefore returns `{ items, pager }`; this is
-   * the same data without the envelope, for the overwhelmingly common case of "give me what is
-   * in the store". Destructuring the wrong one of the two is a silent empty render, so both
-   * spellings exist rather than one being the trap the other rescues.
+   * 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.
    */
-  all: () => Promise<T[]>
+  replace(records: T[]): Promise<void>
+
+  /** Drop every record. */
+  clear(): Promise<void>
 
   /**
-   * The records the criteria accepts, as a plain array.
+   * 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.
    *
-   * Same criteria language as the server resources (`@owlmeans/postgres-resource`), so a filter
-   * written for an endpoint means the same thing applied locally. Records the store does not
-   * hold cannot match — this filters what has been loaded, it never fetches.
+   * 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
    */
-  match: (criteria?: ListCriteria) => Promise<T[]>
-}
+  watch(id: string | undefined, listener: (model: StateModel<T>) => void): () => void
 
-export interface StateSubscriptionOption<T extends ResourceRecord> {
-  id?: string | string[]
-  _systemId?: string
   /**
-   * Subscribe to a live QUERY instead of to fixed ids.
+   * 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.
    *
-   * The listener is called with every record the criteria currently accepts, and again whenever
-   * a create, update or delete changes that answer — so a list screen never recomputes ids and
-   * never re-subscribes to keep up. Ignored when `id` is given: a subscription is either to
-   * named records or to a query, never to both.
+   * A query subscription creates nothing: an empty store yields an empty list.
    *
-   * Unlike an id subscription, this one creates nothing: an empty store yields an empty list
-   * rather than a placeholder record.
+   * @returns unsubscribe
    */
-  query?: ListCriteria
-  default?: Partial<T>
-  listener: StateListener<T>
-}
-
-export interface StateListener<T extends ResourceRecord> {
-  (record: StateModel<T>[], systemId?: string): void | Promise<void>
+  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>
+  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 UseStoreHelper {
-  <T extends ResourceRecord>(id?: 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 UseStoreListHelper {
-  <T extends ResourceRecord>(id?: string | string[] | UseStoreHelperOptions<T>, opts?: string | boolean | UseStoreHelperOptions<T>): StateModel<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
 }

package/src/utils/model.ts

@@ -1,40 +1,47 @@
 import type { ResourceRecord } from '@owlmeans/resource'
-import { MisshapedRecord } from '@owlmeans/resource'
-import type { StateModel, StateResource } from '../types.js'
+import type { StateModel } from '../types.js'
+import type { StateModelBinding } from './types.js'
 
+/**
+ * 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 = <T extends ResourceRecord>(
-  record: T, resource: StateResource<T>
+  binding: StateModelBinding<T>
 ): StateModel<T> => {
-  let before: T = record
+  /** What an empty model shows: the configured default, or nothing at all. */
+  const blank = (): T => binding.default?.() ?? {} as T
+
+  let working: T = binding.record ?? blank()
+  let stored = binding.record != null
+
   const model: StateModel<T> = {
-    record: { ...record },
-
-    commit: force => {
-      if (force !== true) {
-        if (!Object.entries(before).reduce(
-          (changed, [key, value]) => changed || model.record[key as keyof T] !== value, false
-        ) && !Object.entries(model.record).reduce(
-          (changed, [key, value]) => changed || before[key as keyof T] !== 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 } as T
+
+      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()
     }
   }
 

package/src/utils/types.ts

@@ -0,0 +1,15 @@
+import type { ResourceRecord } from '@owlmeans/resource'
+
+/**
+ * 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>
+}