@playfast/reform 1.3.0 → 1.4.0

package/src/state/stateFamily.ts

@@ -1,10 +1,12 @@
-import { Context, Effect, Layer, Option, Schema } from 'effect'
+import { Context, Effect, Layer, MutableRef, Schema } from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
+import { makeKeyCanonicalizer } from '../internal/familyKeys'
 import { resolveScheduler, type Scheduler } from '../internal/scheduler'
 import { claimStateTag } from '../internal/stateRegistry'
 import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentation'
 import { makeStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
+import { microtask } from '../internal/platform'
 
 export const Tombstone: unique symbol = Symbol.for('reform/StateFamily/Tombstone')
 export type Tombstone = typeof Tombstone
@@ -28,56 +30,102 @@ const makeFamilyStore = <K, V>(
   onChange: () => void = () => {},
 ): FamilyStore<K, V> => {
   const entries = new Map<K, Store<V>>()
+  const keys = makeKeyCanonicalizer<K>()
   const evictWhenUnused = options.evictWhenUnused === true
-  const subscribers = new Map<K, number>()
-  const liveSubscriberCount = (key: K): number =>
-    Option.getOrElse(Option.fromNullable(subscribers.get(key)), () => 0)
-
-  const refCounted = (key: K, store: Store<V>): Store<V> => ({
+  // Stamps identify a store *instance*, not a key: `forget` lets one key hold a
+  // succession of stores, and a stale unsubscribe from an earlier one must not
+  // decrement — or evict — the one that replaced it.
+  const stamps = new Map<K, number>()
+  const nextStamp = MutableRef.make(0)
+
+  // A forgotten key's store is orphaned — `at(key)` mints a fresh one — so its
+  // subscribers must be woken to re-read, or they hold a store nothing writes to
+  // again and never hear about the key another way.
+  const wakers = new Map<K, Set<() => void>>()
+  const wakersFor = (key: K): Set<() => void> => {
+    const existing = wakers.get(key)
+    if (existing !== undefined) {
+      return existing
+    }
+    const created = new Set<() => void>()
+    wakers.set(key, created)
+    return created
+  }
+  const wakeable = (key: K, store: Store<V>): Store<V> => ({
     ...store,
     subscribe: (listener) => {
-      subscribers.set(key, liveSubscriberCount(key) + 1)
+      const registered = wakersFor(key)
+      registered.add(listener)
       const off = store.subscribe(listener)
-      const released = { done: false }
       return () => {
-        if (released.done) {
-          return
-        }
-        released.done = true
+        registered.delete(listener)
         off()
-        const remaining = (subscribers.get(key) ?? 1) - 1
-        if (remaining > 0) {
-          subscribers.set(key, remaining)
-          return
-        }
-        subscribers.delete(key)
-        queueMicrotask(() => {
-          if (liveSubscriberCount(key) === 0) {
-            entries.delete(key)
-          }
-        })
       }
     },
   })
+  const dropKey = (key: K): void => {
+    entries.delete(key)
+    stamps.delete(key)
+    keys.release(key)
+    const woken = wakers.get(key)
+    wakers.delete(key)
+    if (woken !== undefined && woken.size > 0) {
+      scheduler.schedule(woken)
+    }
+  }
+
+  const refCounted = (key: K, store: Store<V>, stamp: number): Store<V> => {
+    const count = MutableRef.make(0)
+    return {
+      ...store,
+      subscribe: (listener) => {
+        MutableRef.update(count, (current) => current + 1)
+        const off = store.subscribe(listener)
+        const released = { done: false }
+        return () => {
+          if (released.done) {
+            return
+          }
+          released.done = true
+          off()
+          MutableRef.update(count, (current) => Math.max(0, current - 1))
+          if (MutableRef.get(count) > 0) {
+            return
+          }
+          microtask(() => {
+            // Still unused, and still the store this key holds.
+            if (MutableRef.get(count) === 0 && stamps.get(key) === stamp) {
+              entries.delete(key)
+              stamps.delete(key)
+              keys.release(key)
+              if (wakersFor(key).size === 0) {
+                wakers.delete(key)
+              }
+            }
+          })
+        }
+      },
+    }
+  }
 
   return {
-    at: (key) => {
+    at: (rawKey) => {
+      const key = keys.canonical(rawKey)
       const existing = entries.get(key)
       if (existing !== undefined) {
         return existing
       }
+      const stamp = MutableRef.updateAndGet(nextStamp, (current) => current + 1)
       const base = makeStore(seed(key), scheduler, onChange)
-      const created = evictWhenUnused ? refCounted(key, base) : base
+      const created = wakeable(key, evictWhenUnused ? refCounted(key, base, stamp) : base)
       entries.set(key, created)
+      stamps.set(key, stamp)
       return created
     },
-    forget: (key) => {
-      entries.delete(key)
-      subscribers.delete(key)
-    },
+    forget: (key) => dropKey(keys.canonical(key)),
     clear: () => {
-      entries.clear()
-      subscribers.clear()
+      Array.from(entries.keys()).forEach(dropKey)
+      keys.reset()
     },
     size: () => entries.size,
   }
@@ -120,8 +168,10 @@ export interface StateFamilyClass<N extends string, K, V> {
   readonly manifest: StateFamilyManifest<N>
   readonly capture: <Result>(visit: StateFamilyCapture<Result>) => Result
   readonly store: Context.Tag<StateFamilyStore<N, K, V>, FamilyStore<K, V>>
-  readonly decodeKeySync: (input: unknown) => K
-  readonly decodeValueSync: (input: unknown) => V
+  // Type-side checks: keys and values reaching these are already-decoded domain
+  // values, which a transforming schema's decoder would reject.
+  readonly validateKeySync: (input: unknown) => K
+  readonly validateValueSync: (input: unknown) => V
 }
 
 export type FamilyName<F> = F extends StateFamilyClass<infer N, infer _K, infer _V> ? N : never
@@ -153,8 +203,8 @@ export const make = <const N extends string, K, KeyEncoded, V, ValueEncoded>(
   const family: StateFamilyClass<N, K, V> = definitionClass<StateFamilyClass<N, K, V>>({
     manifest,
     store,
-    decodeKeySync: Schema.decodeUnknownSync(key),
-    decodeValueSync: Schema.decodeUnknownSync(valueSchema),
+    validateKeySync: Schema.validateSync(key),
+    validateValueSync: Schema.validateSync(valueSchema),
     capture: <Result>(visit: StateFamilyCapture<Result>): Result => visit(family),
   })
   return family
@@ -173,7 +223,7 @@ export const live = <N extends string, K, V>(
 ): Layer.Layer<StateFamilyStore<N, K, V>> => {
   const seed = (key: K): V =>
     typeof initial === 'function'
-      ? family.decodeValueSync(Reflect.apply(initial, undefined, [key]))
+      ? family.validateValueSync(Reflect.apply(initial, undefined, [key]))
       : initial
   return Layer.effect(
     family.store,

package/src/state/stateGroup.ts

@@ -32,18 +32,36 @@ export type AnyStateGroup = StateGroupClass<ReadonlyArray<AnyState>>
 
 type DuplicateStateName<N extends string> = readonly ['reform: duplicate state name in group', N]
 
+// TAIL-RECURSIVE ON PURPOSE, and the accumulator is the whole reason it is
+// written this way. The obvious formulation puts the recursive call inside the
+// tuple it returns -- `readonly [Checked, ...NoDuplicateNames<Tail, ...>]` --
+// which is NOT a tail call, so TypeScript keeps a frame per member and the
+// depth of this type is the SIZE OF THE GROUP. A group grows one state at a
+// time and nothing warns, so the limit is reached by an append that is correct
+// on its own: measured at a forty-member group, where two independent additions
+// of one state each produced
+// `error TS2589: Type instantiation is excessively deep and possibly infinite`
+// at the `StateGroup.make` call and at no other site.
+//
+// With the result carried in `Acc` the recursive call IS the whole true branch,
+// which TypeScript eliminates, and the ceiling goes from ~50 to ~1000.
 type NoDuplicateNames<
   Members extends ReadonlyArray<AnyState>,
   Seen extends string = never,
+  Acc extends ReadonlyArray<unknown> = readonly [],
 > = Members extends readonly [
   infer Head extends AnyState,
   ...infer Tail extends ReadonlyArray<AnyState>,
 ]
-  ? readonly [
-      StateName<Head> extends Seen ? DuplicateStateName<StateName<Head>> : Head,
-      ...NoDuplicateNames<Tail, Seen | StateName<Head>>,
-    ]
-  : readonly []
+  ? NoDuplicateNames<
+      Tail,
+      Seen | StateName<Head>,
+      readonly [
+        ...Acc,
+        StateName<Head> extends Seen ? DuplicateStateName<StateName<Head>> : Head,
+      ]
+    >
+  : Acc
 
 export type GroupSeeds<G extends AnyStateGroup> =
   G extends StateGroupClass<infer Members>
@@ -113,7 +131,7 @@ export function live(
   const layers = group.members.map((member) =>
     member.capture<Layer.Layer<never>>((state) =>
       Layer.unwrapEffect(
-        state.decodeUnknown(seeds[state.manifest.name]).pipe(
+        state.validate(seeds[state.manifest.name]).pipe(
           Effect.orDie,
           Effect.map((seed) => stateLive(state, seed)),
         ),

package/src/testkit/flight.testkit.ts

@@ -1,4 +1,5 @@
 import { Deferred, Duration, Effect, MutableRef, Option } from 'effect'
+import { microtask } from '../internal/platform'
 
 // Coalescing/cancellation semantics are only meaningful while a query is still
 // in flight. Tests used to build that overlap by racing wall-clock — a 25ms
@@ -15,7 +16,7 @@ export const tick = (ms = 10): Effect.Effect<void> => Effect.sleep(Duration.mill
 // starved by host load the way a 10ms budget can. Use this to let the graph
 // quiesce before asserting that something did NOT happen.
 export const flush = (turns = 3): Effect.Effect<void> =>
-  Effect.promise(() => new Promise<void>((resolve) => queueMicrotask(resolve))).pipe(
+  Effect.promise(() => new Promise<void>((resolve) => microtask(resolve))).pipe(
     Effect.repeatN(Math.max(turns - 1, 0)),
   )
 

package/src/wire/tree-key-presence.test.ts

@@ -0,0 +1,46 @@
+import { expect, it } from '@effect/vitest'
+import { Effect, Schema as S } from 'effect'
+import * as Wire from './tree'
+import type { WireNode } from './tree'
+
+// ---------------------------------------------------------------------------
+// BUG 3 — `Wire.deepEqual` compares key COUNT and then reads `right[key]`, so
+// two prop records with the same number of keys but different key sets are
+// reported unchanged whenever the differing keys hold `undefined`.
+//
+// `compose/structure.ts`'s `deepEquals` guards this with
+// `Object.prototype.hasOwnProperty.call(right, key)`; `wire/tree.ts` does not.
+// The gap is reachable: `Schema.encodeUnknown` of a plain `S.optional` field
+// keeps the key when its value is `undefined` (asserted below), so the encoded
+// props a composition hands the wire really can carry `undefined`-valued keys.
+// The consequence is a dropped frame: `diff` emits no patch, so the client
+// keeps rendering the previous props forever.
+// ---------------------------------------------------------------------------
+it.effect('wire diff reports a prop record whose key set changed', () =>
+  Effect.gen(function* () {
+    const FormProps = S.Struct({
+      draftTitle: S.optional(S.String),
+      draftBody: S.optional(S.String),
+      id: S.String,
+    })
+    const before = yield* S.encodeUnknown(FormProps)({ draftTitle: undefined, id: 'post-1' })
+    const after = yield* S.encodeUnknown(FormProps)({ draftBody: undefined, id: 'post-1' })
+
+    // Encoding really does keep an `undefined`-valued optional key.
+    expect(Object.keys(before)).toEqual(['draftTitle', 'id'])
+    expect(Object.keys(after)).toEqual(['draftBody', 'id'])
+
+    const node = (value: unknown): WireNode => ({
+      id: 'form',
+      name: 'FormUi',
+      parentId: null,
+      childIndex: 0,
+      slot: null,
+      key: null,
+      props: [{ _tag: 'Data', name: 'form', value }],
+    })
+
+    // `draftTitle` was dropped and `draftBody` added — the node changed.
+    expect(Wire.diff([node(before)], [node(after)])).toHaveLength(1)
+  }),
+)

package/src/wire/tree.ts

@@ -40,7 +40,15 @@ const recordsEqual = (left: Record<string, unknown>, right: Record<string, unkno
   const rightKeys = Rec.keys(right)
   return (
     leftKeys.length === rightKeys.length &&
-    leftKeys.every((key) => deepEqual({ left: left[key], right: right[key] }))
+    // Presence, not just value: two records of the same size whose keys differ both
+    // read `undefined` for the other's key and would compare equal. An encoded
+    // `S.optional` field keeps its key when its value is undefined, so a frame can
+    // really swap one such key for another and diff to no patches at all.
+    leftKeys.every(
+      (key) =>
+        Object.prototype.hasOwnProperty.call(right, key) &&
+        deepEqual({ left: left[key], right: right[key] }),
+    )
   )
 }