@owlmeans/state 0.1.18-rc.9 → 0.1.18

package/src/resource.ts

@@ -1,49 +1,17 @@
-import { appendContextual } from '@owlmeans/context'
-import type { BasicConfig as Config, BasicContext as Context } from '@owlmeans/context'
-import {
-  applyQuery, filterRecords, firstMatch, RecordExists, sortRecords, UnknownRecordError,
-  UnsupportedArgumentError
-} from '@owlmeans/resource'
-import type {
-  Criteria, FirstOptions, ListOptions, ResourceRecord, SubscribeOptions, Ttl, Unsubscribe,
-  WriteOptions
-} from '@owlmeans/resource'
+import { appendContextual, type BasicConfig as Config, type BasicContext as Context } from '@owlmeans/context'
+import { RecordExists, recordQueryHelper, UnknownRecordError, UnsupportedArgumentError, type Criteria, type FirstOptions, type ListOptions, type ResourceRecord, type SubscribeOptions, type Ttl, type Unsubscribe, type WriteOptions } from '@owlmeans/resource'
 import { StateConfigError } from './errors.js'
 import { createStateModel } from './utils/model.js'
 import type {
   StateConfig, StateEvent, StateModel, StateResource, StateResourceAppend
 } from './types.js'
-
-/**
- * The one slot of a `single` resource. It is a KEY and never a value: nothing writes it into a
- * record, so a single resource's record still carries whatever id it arrived with, or none.
- */
-const SOLE = ''
-
-/** The channel writes publish on, and the one a subscriber gets when it names none. */
-const CHANGES = 'changes'
-
-/** The alias a context's first state resource takes when nothing else is asked for. */
-const STATE = 'state'
+import { CHANGES, SOLE, STATE } from './consts.local.js'
+import type { QueryWatch, Subscription } from './types.local.js'
 
 /** Milliseconds until a subscription expires: a number is seconds from now, a Date the instant. */
 const expiresIn = (ttl: Ttl): number =>
   ttl instanceof Date ? ttl.getTime() - Date.now() : ttl * 1000
 
-interface QueryWatch<T extends ResourceRecord> {
-  where?: Criteria<T>
-  opts?: FirstOptions<T>
-  listener: (models: StateModel<T>[]) => void
-  last: StateModel<T>[]
-}
-
-interface Subscription<T extends ResourceRecord> {
-  handler: (value: StateEvent<T>) => void | Promise<void>
-  channel: string
-  once: boolean
-  timer?: ReturnType<typeof setTimeout>
-}
-
 export const createStateResource = <T extends ResourceRecord>(
   alias: string = STATE, cfg?: StateConfig<T>
 ): StateResource<T> => {
@@ -124,7 +92,7 @@ export const createStateResource = <T extends ResourceRecord>(
   }
 
   const first = (idOrWhere: string | Criteria<T>, opts?: FirstOptions<T>): T | null =>
-    typeof idOrWhere === 'string' ? read(idOrWhere) : firstMatch(records(), idOrWhere, opts)
+    typeof idOrWhere === 'string' ? read(idOrWhere) : recordQueryHelper.firstMatch(records(), idOrWhere, opts)
 
   /** The store keeps no expiring records, so a ttl would be silently dropped. */
   const refuseTtl = (opts?: WriteOptions): void => {
@@ -167,8 +135,25 @@ export const createStateResource = <T extends ResourceRecord>(
     return model
   }
 
+  /**
+   * The model for "nothing is addressed yet" — one instance, reused.
+   *
+   * It must be the SAME reference every time: a React subscriber compares snapshots by identity,
+   * and a freshly built model would read as a change on every render and loop. Writing through it
+   * is refused rather than silently dropped, because a caller that writes without an id has lost
+   * track of which record it meant.
+   */
+  let blank: StateModel<T> | undefined
+  const emptyModel = (): StateModel<T> => blank ??= createStateModel<T>({
+    id: undefined,
+    record: undefined,
+    default: config.default,
+    write: async () => { throw new StateConfigError(StateConfigError.NoId) },
+    drop: async () => { throw new StateConfigError(StateConfigError.NoId) }
+  })
+
   const queryModels = (watch: QueryWatch<T>): StateModel<T>[] =>
-    sortRecords(filterRecords(records(), watch.where), watch.opts?.sort)
+    recordQueryHelper.sortRecords(recordQueryHelper.filterRecords(records(), watch.where), watch.opts?.sort)
       .map(record => modelFor(storedKey(record)))
 
   const same = (left: StateModel<T>[], right: StateModel<T>[]): boolean =>
@@ -263,10 +248,10 @@ export const createStateResource = <T extends ResourceRecord>(
         throw new UnsupportedArgumentError('page-without-size')
       }
 
-      return applyQuery(records(), where, opts)
+      return recordQueryHelper.applyQuery(records(), where, opts)
     },
 
-    count: async (where?: Criteria<T>) => filterRecords(records(), where).length,
+    count: async (where?: Criteria<T>) => recordQueryHelper.filterRecords(records(), where).length,
 
     create: async (record: Partial<T>, opts?: WriteOptions) => {
       refuseTtl(opts)
@@ -320,7 +305,7 @@ export const createStateResource = <T extends ResourceRecord>(
       if (where == null || Object.keys(where).length < 1) {
         throw new UnsupportedArgumentError('purge:empty-criteria')
       }
-      const removed = filterRecords(records(), where)
+      const removed = recordQueryHelper.filterRecords(records(), where)
         .map((record): [string, T] => [storedKey(record), record])
       for (const [key] of removed) {
         store.delete(key)
@@ -356,6 +341,22 @@ export const createStateResource = <T extends ResourceRecord>(
     },
 
     watch: (id, listener) => {
+      /**
+       * Watching before there is anything to watch is a RENDERING state, not a mistake.
+       *
+       * A screen binds to `useStoreModel(project.record.id)` while the project is still loading,
+       * so the id is legitimately absent for the first renders. Treating that as the
+       * configuration error it would be on `load()` or `save()` crashes the component tree over
+       * data that is simply not here yet. So an absent id on a listed resource watches nothing
+       * and reports an empty model; the error stays where it means something — a direct read or
+       * write with no id, which cannot be anything but a mistake.
+       */
+      if (id == null && !single) {
+        listener(emptyModel())
+
+        return () => { }
+      }
+
       const key = keyFor(id)
       let listeners = watchers.get(key)
       if (listeners == null) {

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

@@ -59,7 +59,8 @@ export interface StateResource<T extends ResourceRecord> extends Resource<T>, Pu
    * `undefined` addresses the one record of a `single` resource; on any other it throws, since
    * there is nothing for it to mean.
    *
-   * @throws {StateConfigError} `NonSingle` — no id, on a resource that holds many records.
+   * 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

package/src/utils/model.ts

@@ -1,19 +1,6 @@
 import type { ResourceRecord } from '@owlmeans/resource'
 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>
-}
+import type { StateModelBinding } from './types.js'
 
 /**
  * Wrap one record — or its absence — as something a screen can bind to.

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

package/tests/resource.spec.ts

@@ -222,9 +222,59 @@ describe('@owlmeans/state — watching one record', () => {
     stop()
   })
 
-  test('an id addresses no record without a single resource', async () => {
+  /**
+   * A screen binds to `watch(project.id)` while the project is still loading, so an absent id is
+   * a rendering state and must not take the component tree down with it. Reading with no id is a
+   * different question — there the caller has lost track of which record it meant.
+   */
+  test('watching with no id reports empty rather than throwing', async () => {
     const resource = await seeded()
-    expect(() => resource.watch(undefined, () => { })).toThrow(StateConfigError)
+    let model!: StateModel<Session>
+    const stop = resource.watch(undefined, current => { model = current })
+
+    expect(model.empty).toBe(true)
+    expect(model.id).toBeUndefined()
+
+    stop()
+  })
+
+  test('the empty model is one reference, so a subscriber sees no change', async () => {
+    const resource = await seeded()
+    const seen: StateModel<Session>[] = []
+    const first = resource.watch(undefined, current => { seen.push(current) })
+    const second = resource.watch(undefined, current => { seen.push(current) })
+
+    expect(seen).toHaveLength(2)
+    expect(seen[0]).toBe(seen[1])
+
+    first()
+    second()
+  })
+
+  test('writing through the empty model is refused', async () => {
+    const resource = await seeded()
+    let model!: StateModel<Session>
+    const stop = resource.watch(undefined, current => { model = current })
+
+    await expect(model.update({ token: 'x' } as Partial<Session>)).rejects.toThrow(StateConfigError)
+
+    stop()
+  })
+
+  /**
+   * The reason the empty model exists at all: the store it stands in for must be untouched. The
+   * placeholder record this replaced put a blank row into every list reading the same store.
+   */
+  test('watching with no id writes nothing into the store', async () => {
+    const resource = await seeded()
+    const before = await resource.list()
+    const stop = resource.watch(undefined, () => { })
+    const after = await resource.list()
+
+    expect(after.total).toBe(before.total)
+    expect(after.items.some(item => item.id == null)).toBe(false)
+
+    stop()
   })
 })