@playfast/reform 1.1.1 → 1.2.1

package/src/remote/remoteStateSend.ts

@@ -2,24 +2,80 @@ import { Context, Effect, Either, Layer } from 'effect'
 import * as Channel from '../channel/channel'
 import * as Event from '../event/event'
 import { Bus, narrowHandled } from '../runtime/bus'
-import type { SettleLink } from './remoteStateLiveTypes'
+import { type ReducerEntry, Reducers } from '../runtime/loop'
+import type { PendingQueue } from './pendingQueue'
+import type { QueueFoldEventExternalApi, SettleLink } from './remoteStateTypes'
 
-interface SendProcedureOptions<I, R> {
+export interface IntentEvents<I> {
+  readonly queued: Event.EventClass<string, { readonly opId: string; readonly intent: I }>
   readonly acked: Event.EventClass<string, { readonly opId: string }>
+  readonly settled: Event.EventClass<string, { readonly opId: string }>
+  readonly invalidated: Event.EventClass<string, {}>
+}
+
+interface QueueReducerOptions<I> {
+  readonly name: string
+  readonly queueTag: Context.Tag<PendingQueue<I>, PendingQueue<I>>
+  readonly events: IntentEvents<I>
+}
+
+// Direct registry assembly avoids deferred conditional parameters while Intents is generic.
+export const queueReducerLayer = <I>(
+  options: QueueReducerOptions<I>,
+): Layer.Layer<never, never, Reducers | PendingQueue<I>> =>
+  Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const reducers = yield* Reducers
+      if (reducers.entries.some((entry) => entry.name === options.name)) {
+        yield* Effect.logWarning(`reform: duplicate reducer name '${options.name}' registered`)
+      }
+      const queue = yield* options.queueTag
+      const entry: ReducerEntry = {
+        name: options.name,
+        handles: new Set([
+          options.events.queued.tag,
+          options.events.acked.tag,
+          options.events.settled.tag,
+        ]),
+        apply: (event) => {
+          const handled = narrowHandled<QueueFoldEventExternalApi<I>>(event)
+          if (handled._tag === options.events.queued.tag) {
+            if (handled.intent !== undefined) {
+              queue.append({
+                opId: handled.opId,
+                intent: handled.intent,
+                status: 'sending',
+              })
+            }
+            return
+          }
+          if (handled._tag === options.events.acked.tag) {
+            queue.ack(handled.opId)
+            return
+          }
+          queue.settle(handled.opId)
+        },
+      }
+      yield* Effect.acquireRelease(
+        Effect.sync(() => reducers.register(entry)),
+        () => Effect.sync(() => reducers.unregister(entry)),
+      )
+    }),
+  )
+
+interface SendProcedureOptions<I, R2> {
+  readonly name: string
   readonly channel: Channel.ChannelClass
-  readonly failed: Event.EventClass<string, { readonly intent: I; readonly error: unknown }>
   readonly handles: ReadonlySet<string>
-  readonly invalidated: Event.EventClass<string, {}>
   readonly linkTag: Context.Tag<SettleLink, SettleLink>
-  readonly name: string
-  readonly queued: Event.EventClass<string, { readonly opId: string; readonly intent: I }>
-  readonly send: (intent: I) => Effect.Effect<unknown, unknown, R>
-  readonly settled: Event.EventClass<string, { readonly opId: string }>
+  readonly failed: Event.EventClass<string, { readonly intent: I; readonly error: unknown }>
+  readonly send: (intent: I) => Effect.Effect<unknown, unknown, R2>
+  readonly events: IntentEvents<I>
 }
 
-export const makeSendProcedureLayer = <I, R>(
-  options: SendProcedureOptions<I, R>,
-): Layer.Layer<never, never, Channel.Procedures | SettleLink | Bus | R> =>
+export const sendProcedureLayer = <I, R2>(
+  options: SendProcedureOptions<I, R2>,
+): Layer.Layer<never, never, Channel.Procedures | Bus | R2 | SettleLink> =>
   Layer.scopedDiscard(
     Effect.gen(function* () {
       const procedures = yield* Channel.Procedures
@@ -27,38 +83,40 @@ export const makeSendProcedureLayer = <I, R>(
         yield* Effect.logWarning(`reform: duplicate procedure name '${options.name}' registered`)
       }
       const link = yield* options.linkTag
-      const runtime = yield* Effect.runtime<Bus | R>()
-      const deliver = Effect.fn('deliver')(
-        function* (intent: I): Effect.fn.Return<void, never, Bus | R> {
-          const opId = yield* Effect.sync(() => crypto.randomUUID())
-          yield* Event.dispatch(options.queued, { opId, intent })
-          const outcome = yield* options.send(intent).pipe(
-            Effect.catchAllDefect((defect) => Effect.fail(defect)),
-            Effect.either,
-            Effect.onInterrupt(() => Event.dispatch(options.settled, { opId })),
-          )
-          yield* Either.match(outcome, {
-            onLeft: (error) =>
-              Effect.zipRight(
-                Event.dispatch(options.failed, { intent, error }),
-                Event.dispatch(options.settled, { opId }),
-              ),
-            onRight: () =>
-              Effect.sync(() => link.register(opId, link.requested() + 1)).pipe(
-                Effect.zipRight(Event.dispatch(options.acked, { opId })),
-                Effect.zipRight(Event.dispatch(options.invalidated, {})),
-              ),
-          })
-        },
-      )
+      const runtime = yield* Effect.runtime<Bus | R2>()
+      const deliver = Effect.fn('deliver')(function* (
+        intent: I,
+      ): Effect.fn.Return<void, never, Bus | R2> {
+        const opId = yield* Effect.sync(() => crypto.randomUUID())
+        yield* Event.dispatch(options.events.queued, { opId, intent })
+        const outcome = yield* options.send(intent).pipe(
+          Effect.catchAllDefect((defect) => Effect.fail(defect)),
+          Effect.either,
+          Effect.onInterrupt(() => Event.dispatch(options.events.settled, { opId })),
+        )
+        yield* Either.match(outcome, {
+          onLeft: (error) =>
+            Effect.zipRight(
+              Event.dispatch(options.failed, { intent, error }),
+              Event.dispatch(options.events.settled, { opId }),
+            ),
+          onRight: () =>
+            // Register before invalidation so a pre-ack refetch cannot settle this intent.
+            Effect.sync(() => link.register(opId, link.requested() + 1)).pipe(
+              Effect.zipRight(Event.dispatch(options.events.acked, { opId })),
+              Effect.zipRight(Event.dispatch(options.events.invalidated, {})),
+            ),
+        })
+      })
       const entry: Channel.ProcedureEntry = {
         name: options.name,
         channelName: options.channel.manifest.name,
         handles: options.handles,
         run: (event) => Effect.provide(deliver(narrowHandled<I>(event)), runtime),
       }
-      yield* Effect.acquireRelease(Effect.sync(() => procedures.register(entry)), () =>
-        Effect.sync(() => procedures.unregister(entry)),
+      yield* Effect.acquireRelease(
+        Effect.sync(() => procedures.register(entry)),
+        () => Effect.sync(() => procedures.unregister(entry)),
       )
     }),
   )

package/src/remote/remoteStateTypes.ts

@@ -0,0 +1,155 @@
+import type { Context, Effect, Schema } from 'effect'
+import type { Effect as EffectType } from 'effect/Effect'
+import type { AsyncData, AsyncError, AsyncSuccess } from '../calc/asyncData'
+import type * as Channel from '../channel/channel'
+import type { Manifest } from '../definition/definition'
+import type * as Event from '../event/event'
+import type { QueryCodec } from '../internal/queryDriver'
+import type { InputsObject, InvalidateBy } from '../internal/sources'
+import type { Store } from '../internal/store'
+import type { AnySource, SourceCapture, StateToken } from '../state/token'
+
+// An intent acked at generation g settles only on Success with generation > g.
+// `apply` must be idempotent while refetched truth and the pending intent overlap.
+
+export interface PendingIntent<I> {
+  readonly opId: string
+  readonly intent: I
+  readonly status: 'sending' | 'confirmed'
+}
+
+export interface FailedIntent<I> {
+  readonly intent: I
+  readonly error: unknown
+}
+
+export type RemoteStateSettled<A, E> = AsyncSuccess<A> | AsyncError<E>
+
+export const RemoteStateVisibleStoreTypeId: unique symbol = Symbol.for(
+  'reform/RemoteStateVisibleStore',
+)
+export type RemoteStateVisibleStoreTypeId = typeof RemoteStateVisibleStoreTypeId
+
+export interface RemoteStateVisibleStore<N extends string> {
+  readonly [RemoteStateVisibleStoreTypeId]: N
+}
+
+export const RemoteStateTruthStoreTypeId: unique symbol = Symbol.for('reform/RemoteStateTruthStore')
+export type RemoteStateTruthStoreTypeId = typeof RemoteStateTruthStoreTypeId
+
+export interface RemoteStateTruthStore<N extends string> {
+  readonly [RemoteStateTruthStoreTypeId]: N
+}
+
+export const RemoteStatePendingStoreTypeId: unique symbol = Symbol.for(
+  'reform/RemoteStatePendingStore',
+)
+export type RemoteStatePendingStoreTypeId = typeof RemoteStatePendingStoreTypeId
+
+export interface RemoteStatePendingStore<N extends string> {
+  readonly [RemoteStatePendingStoreTypeId]: N
+}
+
+export type EventPayload<Ev extends Event.AnyEvent> =
+  Ev extends Event.EventClass<string, infer P> ? P : never
+
+// ExternalApi: optional `intent` only on Queued envelopes.
+export interface QueueFoldEventExternalApi<I> {
+  readonly _tag: string
+  readonly opId: string
+  readonly intent?: I
+}
+
+export interface RemoteStateSchemaReflection {
+  readonly ast: Schema.Schema<unknown, unknown, unknown>['ast']
+}
+
+export interface RemoteStateManifestExternalApi<N extends string> extends Manifest {
+  readonly kind: 'RemoteState'
+  readonly name: N
+  readonly output: RemoteStateSchemaReflection
+  readonly error?: RemoteStateSchemaReflection
+  readonly gated: boolean
+  readonly intents: ReadonlyArray<string>
+}
+
+export interface RemoteStateClass<
+  N extends string,
+  out Inputs extends ReadonlyArray<AnySource>,
+  in out Intents extends ReadonlyArray<Event.AnyEvent>,
+  in out A,
+  in out E,
+  in out Gated extends boolean,
+> extends EffectType<AsyncData<A, E, Gated>, never, RemoteStateVisibleStore<N>> {
+  new (): {}
+  readonly manifest: RemoteStateManifestExternalApi<N>
+  readonly codec: QueryCodec<A>
+  readonly store: Context.Tag<RemoteStateVisibleStore<N>, Store<AsyncData<A, E, Gated>>>
+  readonly name: N
+  readonly inputs: Inputs
+  readonly intents: Intents
+  readonly gated: Gated
+  readonly capture: <Result>(visit: SourceCapture<Result>) => Result
+  readonly truth: StateToken<`${N}/truth`, AsyncData<A, E, Gated>, RemoteStateTruthStore<N>>
+  // pending is a Source, not a StateClass, so user reducers cannot target it.
+  readonly pending: StateToken<
+    `${N}/pending`,
+    ReadonlyArray<PendingIntent<Event.EventType<Intents[number]>>>,
+    RemoteStatePendingStore<N>
+  >
+  readonly Failed: Event.EventClass<`${N}/Failed`, FailedIntent<Event.EventType<Intents[number]>>>
+}
+
+export interface RemoteStateConfigExternalApi<
+  Inputs extends ReadonlyArray<AnySource>,
+  Intents extends ReadonlyArray<Event.AnyEvent>,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+  ErrorSchema extends Schema.Schema.AnyNoContext | undefined,
+  AlwaysOn extends boolean,
+> {
+  readonly inputs: Inputs
+  readonly output: OutputSchema
+  readonly error?: ErrorSchema
+  readonly alwaysOn?: AlwaysOn
+  readonly intents: Intents
+}
+export type RemoteStateLiveExternalApi<
+  Inputs extends ReadonlyArray<AnySource>,
+  Intents extends ReadonlyArray<Event.AnyEvent>,
+  A,
+  E,
+  Gated extends boolean,
+  R,
+  R2,
+  SettledEvent extends Event.AnyEvent,
+> = {
+  readonly query: (inputs: InputsObject<Inputs>) => Effect.Effect<A, E, R>
+  // Any failure settles and emits Failed; truth comes only from the invalidated query.
+  readonly send: (intent: Event.EventType<Intents[number]>) => Effect.Effect<unknown, unknown, R2>
+  readonly apply: (value: A, intent: Event.EventType<Intents[number]>) => A
+  readonly channel?: Channel.ChannelClass
+  readonly invalidateBy?: InvalidateBy<Inputs>
+  readonly invalidateOn?: ReadonlyArray<Event.AnyEvent>
+  readonly coalesce?: 'switch' | 'trailing'
+  readonly reuse?: boolean
+  readonly settled?: {
+    readonly event: SettledEvent
+    readonly payload: (result: RemoteStateSettled<A, E>) => EventPayload<SettledEvent>
+  }
+  // Only settled server truth is persisted; the optimistic overlay is a separate store.
+  readonly persist?:
+    | boolean
+    | { readonly key?: string | ((inputs: InputsObject<Inputs>) => string) }
+} & (Gated extends true
+  ? { readonly disabled?: (inputs: InputsObject<Inputs>) => boolean }
+  : { readonly disabled?: never })
+
+export interface SettleLink {
+  readonly requested: () => number
+  readonly register: (opId: string, waitFor: number) => void
+}
+
+export interface WaiterRegistration {
+  readonly opId: string
+  readonly waitFor: number
+}

package/src/runtime/appRuntime.activation.test.ts

@@ -0,0 +1,104 @@
+import { Context, Effect, Layer, Option, Schema } from 'effect'
+import { expect, it } from '@effect/vitest'
+import * as Composition from '../compose/composition'
+import { mount } from '../compose/structure'
+import { ui } from '../compose/ui'
+import { scene } from '../scene/scene'
+import { flush, until } from '../testkit/flight.testkit'
+import { Engine } from './loop'
+import { makeAppRuntime } from './appRuntime'
+
+interface ActivationProbeService {
+  readonly acquired: Array<string>
+  readonly released: Array<string>
+}
+
+class ActivationProbe extends Context.Tag('appRuntime.ActivationProbe')<
+  ActivationProbe,
+  ActivationProbeService
+>() {}
+
+class ScopedUi extends ui('appRuntime.ScopedUi')<{
+  props: { readonly id: string }
+}>() {}
+
+class ScopedComposition extends Composition.make('appRuntime.Scoped', {
+  title: 'Scoped',
+  props: Schema.Struct({ id: Schema.String }),
+  ui: ScopedUi,
+})<ScopedComposition>() {}
+
+const ScopedLive = Composition.liveScoped(ScopedComposition, {
+  render: function* () {
+    const { id } = yield* ScopedComposition.props
+    return mount({ props: { id }, slots: {} })
+  },
+  activate: function* () {
+    const { id } = yield* ScopedComposition.props
+    const probe = yield* ActivationProbe
+    yield* Effect.acquireRelease(
+      Effect.sync(() => probe.acquired.push(id)),
+      () => Effect.sync(() => probe.released.push(id)),
+    )
+  },
+})
+
+class PlainUi extends ui('appRuntime.PlainUi')<{ props: {} }>() {}
+class PlainComposition extends Composition.make('appRuntime.Plain', {
+  title: 'Plain',
+  ui: PlainUi,
+})<PlainComposition>() {}
+
+const PlainLive = Composition.live(PlainComposition, function* () {
+  return mount({ props: {}, slots: {} })
+})
+
+const makeScene = (probe: ActivationProbeService) =>
+  scene(ScopedComposition, {
+    provide: [
+      Layer.mergeAll(ScopedLive, PlainLive).pipe(
+        Layer.provideMerge(Layer.succeed(ActivationProbe, probe)),
+        Layer.provideMerge(Engine),
+      ),
+    ],
+  })
+
+// Wait for the count, then quiesce: the exact `toEqual` is what proves no extra
+// acquire/release slipped in behind it.
+const settledAt = (read: () => ReadonlyArray<string>, count: number): Effect.Effect<void> =>
+  until(read, (entries) => entries.length >= count).pipe(Effect.zipRight(flush()))
+
+it.scopedLive(
+  'keeps activation lazy, scopes sibling mounts independently, and closes them at teardown',
+  () =>
+    Effect.gen(function* () {
+      const probe: ActivationProbeService = { acquired: [], released: [] }
+      const app = makeAppRuntime(makeScene(probe))
+      yield* Effect.addFinalizer(() => Effect.sync(() => app.dispose()))
+      const service = app.read(ScopedComposition.tag)
+      const plain = app.read(PlainComposition.tag)
+
+      yield* Composition.render(service, {
+        props: { id: 'first' },
+        tracker: { add: () => undefined },
+      })
+      expect(probe.acquired).toEqual([])
+      expect(Option.isNone(Composition.activation(plain, {}))).toBe(true)
+
+      const first = app.mountScoped(
+        Option.getOrThrow(Composition.activation(service, { id: 'first' })),
+      )
+      app.mountScoped(Option.getOrThrow(Composition.activation(service, { id: 'second' })))
+      yield* settledAt(() => probe.acquired, 2)
+      expect(probe.acquired).toEqual(['first', 'second'])
+
+      first()
+      first()
+      yield* settledAt(() => probe.released, 1)
+      expect(probe.released).toEqual(['first'])
+
+      app.dispose()
+      yield* settledAt(() => probe.released, 2)
+      expect(probe.released).toEqual(['first', 'second'])
+    }),
+)