@playfast/reform 0.0.10 → 0.1.0

package/src/state/stateFamily.ts

@@ -1,4 +1,4 @@
-import { Context, Effect, Layer, type Schema } from 'effect'
+import { Context, Effect, Layer, Option, type Schema } from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
 import { resolveScheduler, type Scheduler } from '../internal/scheduler'
 import { claimStateTag } from '../internal/stateRegistry'
@@ -31,7 +31,7 @@ export interface FamilyStore<K, V> {
 }
 
 /** Options for a family's keyed store. */
-export interface FamilyOptions {
+export interface FamilyOptionsExternalApi {
   /**
    * Drop a key's store automatically once it has no live subscribers (checked on
    * the next microtask, so a same-commit re-subscribe — e.g. a key that just moved
@@ -44,6 +44,7 @@ export interface FamilyOptions {
    */
   readonly evictWhenUnused?: boolean
 }
+export type FamilyOptions = FamilyOptionsExternalApi
 
 const makeFamilyStore = <K, V>(
   seed: (key: K) => V,
@@ -54,6 +55,8 @@ const makeFamilyStore = <K, V>(
   const evictWhenUnused = options.evictWhenUnused === true
   // Live subscriber count per key — maintained only when eviction is on.
   const subscribers = new Map<K, number>()
+  const liveSubscriberCount = (key: K): number =>
+    Option.getOrElse(Option.fromNullable(subscribers.get(key)), () => 0)
 
   // Wrap a store's `subscribe` to ref-count, evicting the key when it falls idle.
   // `get`/`set`/`getVersion` are delegated unchanged, so the loop writes and the
@@ -61,11 +64,13 @@ const makeFamilyStore = <K, V>(
   const refCounted = (key: K, store: Store<V>): Store<V> => ({
     ...store,
     subscribe: (listener) => {
-      subscribers.set(key, (subscribers.get(key) ?? 0) + 1)
+      subscribers.set(key, liveSubscriberCount(key) + 1)
       const off = store.subscribe(listener)
       const released = { done: false }
       return () => {
-        if (released.done) return
+        if (released.done) {
+          return
+        }
         released.done = true
         off()
         const remaining = (subscribers.get(key) ?? 1) - 1
@@ -75,7 +80,9 @@ const makeFamilyStore = <K, V>(
         }
         subscribers.delete(key)
         queueMicrotask(() => {
-          if ((subscribers.get(key) ?? 0) === 0) entries.delete(key)
+          if (liveSubscriberCount(key) === 0) {
+            entries.delete(key)
+          }
         })
       }
     },
@@ -84,7 +91,9 @@ const makeFamilyStore = <K, V>(
   return {
     at: (key) => {
       const existing = entries.get(key)
-      if (existing !== undefined) return existing
+      if (existing !== undefined) {
+        return existing
+      }
       const base = makeStore(seed(key), scheduler)
       const created = evictWhenUnused ? refCounted(key, base) : base
       entries.set(key, created)
@@ -102,7 +111,7 @@ const makeFamilyStore = <K, V>(
   }
 }
 
-export interface StateFamilyManifest<N extends string, K, V> extends Manifest {
+export interface StateFamilyManifestExternalApi<N extends string, K, V> extends Manifest {
   readonly kind: 'StateFamily'
   readonly name: N
   readonly key: Schema.Schema<K, any>
@@ -110,6 +119,7 @@ export interface StateFamilyManifest<N extends string, K, V> extends Manifest {
   readonly title?: string
   readonly description?: string
 }
+export type StateFamilyManifest<N extends string, K, V> = StateFamilyManifestExternalApi<N, K, V>
 
 export interface StateFamilyClass<out N extends string, in out K, in out V> {
   /** Instance carries the key phantom so `Family['Key']` resolves in `keyOf` types. */
@@ -126,11 +136,16 @@ export type FamilyValue<F> = F extends StateFamilyClass<any, any, infer V> ? V :
  * Normalized keyed state: one logical State per key, backed by a single family
  * store. Scales with the collection without re-rendering unrelated entries.
  */
+export interface StateFamilyMakeOptionsExternalApi {
+  readonly title?: string
+  readonly description?: string
+}
+
 export const make = <const N extends string, K, V>(
   name: N,
   key: Schema.Schema<K, any>,
-  value: Schema.Schema<V, any>,
-  options: { readonly title?: string; readonly description?: string } = {},
+  valueSchema: Schema.Schema<V, any>,
+  options: StateFamilyMakeOptionsExternalApi = {},
 ): StateFamilyClass<N, K, V> => {
   const identifier = `reform/family/${name}`
   claimStateTag(identifier)
@@ -139,7 +154,7 @@ export const make = <const N extends string, K, V>(
     kind: 'StateFamily',
     name,
     key,
-    value,
+    value: valueSchema,
     ...(options.title !== undefined ? { title: options.title } : {}),
     ...(options.description !== undefined ? { description: options.description } : {}),
   }
@@ -154,7 +169,7 @@ export const read = <N extends string, K, V>(
   family: StateFamilyClass<N, K, V>,
   key: K,
 ): Effect.Effect<V, never, FamilyStore<K, V>> =>
-  Effect.flatMap(family.store, (fs) => readTracked(fs.at(key)))
+  Effect.flatMap(family.store, (familyStore) => readTracked(familyStore.at(key)))
 
 /**
  * Allocate a family's keyed store — `StateFamily.live(ItemUi, seed)`. The seed
@@ -166,6 +181,7 @@ export const live = <N extends string, K, V>(
   initial: V | ((key: K) => V),
   options: FamilyOptions = {},
 ): Layer.Layer<FamilyStore<K, V>> => {
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- value-or-factory union can't be discriminated for a generic V without a cast
   const seed: (key: K) => V = typeof initial === 'function' ? (initial as (key: K) => V) : () => initial
   return Layer.effect(
     family.store,

package/src/state/stateGroup.ts

@@ -1,4 +1,4 @@
-import { Layer } from 'effect'
+import { Array as Arr, Layer, Option } from 'effect'
 import { definitionClass } from '../definition/definition'
 import { DuplicateRegistration, UnknownGroupState } from '../internal/errors'
 // A group's members each carry a `store` tag, so the shared `StoresOf` (used for
@@ -77,13 +77,21 @@ export const make = <const Members extends ReadonlyArray<AnyState>>(
 ): StateGroupClass<Members> => {
   // `byName` already de-dupes, so a smaller map than the member list means two
   // members claimed one name — unaddressable, and a silent footgun on merge.
-  const names = members.map((m) => m.manifest.name)
-  const duplicate = names.find((name, i) => names.indexOf(name) !== i)
-  if (duplicate !== undefined) throw new DuplicateRegistration({ kind: 'state in group', name: duplicate })
+  const names = members.map((member) => member.manifest.name)
+  const duplicate = Arr.findFirst(names, (name, index) =>
+    Option.exists(
+      Arr.findFirstIndex(names, (candidate) => candidate === name),
+      (firstIndex) => firstIndex !== index,
+    ),
+  )
+  if (Option.isSome(duplicate)) {
+    // oxlint-disable-next-line reform-rules/no-throw -- definition-time invariant; sync factory has no Effect context (see internal/errors.ts)
+    throw new DuplicateRegistration({ kind: 'state in group', name: duplicate.value })
+  }
   return definitionClass<StateGroupClass<Members>>({
     kind: 'StateGroup' as const,
     members,
-    byName: new Map(members.map((m) => [m.manifest.name, m] as const)),
+    byName: new Map(members.map((member) => [member.manifest.name, member] as const)),
   })
 }
 
@@ -102,8 +110,11 @@ export const select = <Members extends ReadonlyArray<AnyState>, N extends StateN
   name: N,
 ): StateToken<N, ValueForName<Members, N>> => {
   const member = group.byName.get(name)
-  if (member === undefined) throw new UnknownGroupState({ name })
-  return new StateToken(name, member.store) as StateToken<N, ValueForName<Members, N>>
+  if (member === undefined) {
+    // oxlint-disable-next-line reform-rules/no-throw -- definition-time invariant; sync lookup has no Effect context (see internal/errors.ts)
+    throw new UnknownGroupState({ name })
+  }
+  return new StateToken(name, member.store)
 }
 
 /**
@@ -118,8 +129,10 @@ export const live = <Members extends ReadonlyArray<AnyState>>(
   // reflection boundary (string key into a mapped type). Each member's store
   // layer is then merged; the union of stores is exactly `StoresOf<Members>`,
   // which `reduce`'s single-layer accumulator can't express, so restate it.
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- reflection boundary: index a mapped seed type by runtime member name
   const seedRecord = seeds as Record<string, unknown>
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- union-of-stores Rout can't be expressed by reduce's single-layer accumulator
   return group.members
-    .map((m) => stateLive(m, seedRecord[m.manifest.name]))
-    .reduce((a, b) => Layer.merge(a, b)) as Layer.Layer<StoresOf<Members>>
+    .map((member) => stateLive(member, seedRecord[member.manifest.name]))
+    .reduce((accumulator, layer) => Layer.merge(accumulator, layer)) as Layer.Layer<StoresOf<Members>>
 }

package/src/synced/syncedStore.ts

@@ -1,4 +1,4 @@
-import { Context, Effect, Layer, type Schema, type Scope } from 'effect'
+import { Context, Effect, Layer, Option, type Schema, type Scope } from 'effect'
 import { type Manifest, yieldableClass } from '../definition/definition'
 import { resolveScheduler } from '../internal/scheduler'
 import { makeDerivedStore, type Store } from '../internal/store'
@@ -31,8 +31,8 @@ export interface SyncedStoreManifest<N extends string, A> extends Manifest {
   readonly kind: 'SyncedStore'
   readonly name: N
   readonly schema: Schema.Schema<A, any>
-  readonly title?: string
-  readonly description?: string
+  readonly title: Option.Option<string>
+  readonly description: Option.Option<string>
 }
 
 export interface SyncedStoreClass<out N extends string, in out A>
@@ -46,6 +46,15 @@ export interface SyncedStoreClass<out N extends string, in out A>
   readonly name: N
 }
 
+/**
+ * A minimal store-carrier — satisfied by a `SyncedStoreClass` and by any
+ * companion primitive (e.g. `@playfast/reform-db`'s `DbQuery`) that allocates
+ * its own `Store` tag, so `SyncedStore.live` is reusable beyond `SyncedStore`.
+ */
+export interface StoreCarrier<A> {
+  readonly store: Context.Tag<Store<A>, Store<A>>
+}
+
 export type AnySyncedStore = SyncedStoreClass<string, any>
 export type SyncedValue<S> = S extends SyncedStoreClass<string, infer A> ? A : never
 
@@ -65,8 +74,8 @@ export const make = <const N extends string, A>(
     kind: 'SyncedStore',
     name,
     schema,
-    ...(options.title !== undefined ? { title: options.title } : {}),
-    ...(options.description !== undefined ? { description: options.description } : {}),
+    title: Option.fromNullable(options.title),
+    description: Option.fromNullable(options.description),
   }
   const read = Effect.flatMap(store, readTracked)
   return yieldableClass(read, { manifest, store, name })
@@ -81,10 +90,7 @@ export const make = <const N extends string, A>(
  * the layer's scope.
  */
 export const live = <A, R>(
-  // A minimal store-carrier — satisfied by a `SyncedStoreClass` and by any
-  // companion primitive (e.g. `@playfast/reform-db`'s `DbQuery`) that allocates
-  // its own `Store` tag, so the seam is reusable beyond `SyncedStore` itself.
-  def: { readonly store: Context.Tag<Store<A>, Store<A>> },
+  def: StoreCarrier<A>,
   acquire: Effect.Effect<SyncedSource<A>, never, R>,
 ): Layer.Layer<Store<A>, never, Exclude<R, Scope.Scope>> =>
   Layer.scoped(

package/src/wire/tree.ts

@@ -1,4 +1,5 @@
-import { Match } from 'effect'
+import { Array, Match, Option, Order, Record as Rec } from 'effect'
+import { sort as sortArray } from 'effect/Array'
 
 /**
  * The serializable model of a rendered UI tree, and the pure diff/apply over it.
@@ -18,8 +19,9 @@ export type WireProp =
   | { readonly _tag: 'Data'; readonly name: string; readonly value: unknown }
   | { readonly _tag: 'Event'; readonly name: string; readonly handle: string }
 
-/** One rendered UI contract instance, identified stably across frames. */
-export interface WireNode {
+/** One rendered UI contract instance, identified stably across frames. The serializable
+ * wire-boundary shape (hence the `ExternalApi` postfix; `null` is part of the JSON contract). */
+export interface WireNodeExternalApi {
   /** Stable identity across renders — the unit of diffing. */
   readonly id: string
   /** The UI contract name (`UiCapture.name`) the client looks up a presentation by. */
@@ -42,6 +44,9 @@ export interface WireNode {
   readonly props: ReadonlyArray<WireProp>
 }
 
+/** Public alias preserving the established name across the codebase. */
+export type WireNode = WireNodeExternalApi
+
 export type WireTree = ReadonlyArray<WireNode>
 
 /** A change to apply to a client's tree: upsert a node, or drop one by id. */
@@ -49,34 +54,54 @@ export type WirePatch =
   | { readonly _tag: 'Upsert'; readonly node: WireNode }
   | { readonly _tag: 'Delete'; readonly id: string }
 
-const arraysEqual = (a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>): boolean =>
-  a.length === b.length && a.every((item, index) => deepEqual(item, b[index]))
+interface EqualPair {
+  readonly left: unknown
+  readonly right: unknown
+}
+
+const isRecord = (candidate: unknown): candidate is Record<string, unknown> =>
+  typeof candidate === 'object' && candidate !== null
+
+const arraysEqual = (left: ReadonlyArray<unknown>, right: ReadonlyArray<unknown>): boolean =>
+  left.length === right.length &&
+  left.every((element, index) => deepEqual({ left: element, right: right[index] }))
 
-const recordsEqual = (a: Record<string, unknown>, b: Record<string, unknown>): boolean => {
-  const aKeys = Object.keys(a)
-  const bKeys = Object.keys(b)
-  return aKeys.length === bKeys.length && aKeys.every((key) => deepEqual(a[key], b[key]))
+const recordsEqual = (left: Record<string, unknown>, right: Record<string, unknown>): boolean => {
+  const leftKeys = Rec.keys(left)
+  const rightKeys = Rec.keys(right)
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every((key) => deepEqual({ left: left[key], right: right[key] }))
+  )
 }
 
 /** Structural equality over serializable wire values (and the tagged props that carry them). */
-const deepEqual = (a: unknown, b: unknown): boolean => {
-  if (a === b) return true
-  if (a === null || b === null) return false
-  if (Array.isArray(a)) return Array.isArray(b) && arraysEqual(a, b)
-  if (Array.isArray(b)) return false
-  if (typeof a === 'object' && typeof b === 'object') {
-    return recordsEqual(a as Record<string, unknown>, b as Record<string, unknown>)
+const deepEqual = ({ left, right }: EqualPair): boolean => {
+  if (left === right) {
+    return true
+  }
+  if (left === null || right === null) {
+    return false
+  }
+  if (Array.isArray(left)) {
+    return Array.isArray(right) && arraysEqual(left, right)
+  }
+  if (Array.isArray(right)) {
+    return false
+  }
+  if (isRecord(left) && isRecord(right)) {
+    return recordsEqual(left, right)
   }
   return false
 }
 
-const nodesEqual = (a: WireNode, b: WireNode): boolean =>
-  a.name === b.name &&
-  a.parentId === b.parentId &&
-  a.childIndex === b.childIndex &&
-  a.slot === b.slot &&
-  a.key === b.key &&
-  deepEqual(a.props, b.props)
+const nodesEqual = (leftNode: WireNode, rightNode: WireNode): boolean =>
+  leftNode.name === rightNode.name &&
+  leftNode.parentId === rightNode.parentId &&
+  leftNode.childIndex === rightNode.childIndex &&
+  leftNode.slot === rightNode.slot &&
+  leftNode.key === rightNode.key &&
+  deepEqual({ left: leftNode.props, right: rightNode.props })
 
 const isUnchanged = (node: WireNode, previousById: ReadonlyMap<string, WireNode>): boolean => {
   const previous = previousById.get(node.id)
@@ -102,11 +127,14 @@ export const diff = (previous: WireTree, next: WireTree): ReadonlyArray<WirePatc
   return [...deletes, ...upserts]
 }
 
-const upsertNode = (state: WireTree, node: WireNode): WireTree => {
-  const index = state.findIndex((existing) => existing.id === node.id)
-  if (index < 0) return [...state, node]
-  return [...state.slice(0, index), node, ...state.slice(index + 1)]
-}
+const upsertNode = (state: WireTree, node: WireNode): WireTree =>
+  Option.match(
+    Array.findFirstIndex(state, (existing) => existing.id === node.id),
+    {
+      onNone: () => [...state, node],
+      onSome: (index) => [...state.slice(0, index), node, ...state.slice(index + 1)],
+    },
+  )
 
 /** Fold patches into a client's tree (the receiving side's reducer). */
 export const apply = (state: WireTree, patches: ReadonlyArray<WirePatch>): WireTree =>
@@ -120,10 +148,18 @@ export const apply = (state: WireTree, patches: ReadonlyArray<WirePatch>): WireT
     state,
   )
 
+const bySiblingOrder = Order.mapInput(Order.number, (node: WireNode) => node.childIndex)
+
 /** The root nodes of a tree, in sibling order. */
 export const roots = (tree: WireTree): WireTree =>
-  tree.filter((node) => node.parentId === null).sort((a, b) => a.childIndex - b.childIndex)
+  sortArray(
+    tree.filter((node) => node.parentId === null),
+    bySiblingOrder,
+  )
 
 /** The children of a node, in sibling order. */
 export const childrenOf = (tree: WireTree, parentId: string): WireTree =>
-  tree.filter((node) => node.parentId === parentId).sort((a, b) => a.childIndex - b.childIndex)
+  sortArray(
+    tree.filter((node) => node.parentId === parentId),
+    bySiblingOrder,
+  )

package/src/wire/triggers.ts

@@ -73,16 +73,17 @@ export const make: Effect.Effect<TriggerRegistryApi> = Effect.gen(function* () {
   ): Effect.Effect<void> =>
     Ref.update(entries, (map) => new Map(map).set(handle, { trigger, schema }))
 
-  const invoke = (
+  const invoke = Effect.fn('invoke')(function* (
     handle: TriggerHandle,
     encodedPayload: unknown,
-  ): Effect.Effect<void, UnknownTrigger | ParseResult.ParseError> =>
-    Effect.gen(function* () {
-      const entry = (yield* Ref.get(entries)).get(handle)
-      if (entry === undefined) return yield* Effect.fail(new UnknownTrigger({ handle }))
-      const payload = yield* Schema.decodeUnknown(entry.schema)(encodedPayload)
-      entry.trigger(payload)
-    })
+  ): Effect.fn.Return<void, UnknownTrigger | ParseResult.ParseError> {
+    const entry = (yield* Ref.get(entries)).get(handle)
+    if (entry === undefined) {
+      return yield* Effect.fail(new UnknownTrigger({ handle }))
+    }
+    const payload = yield* Schema.decodeUnknown(entry.schema)(encodedPayload)
+    entry.trigger(payload)
+  })
 
   const revoke = (handle: TriggerHandle): Effect.Effect<void> =>
     Ref.update(entries, (map) => {