@playfast/reform 1.1.1 → 1.2.1

package/src/compose/composition.ts

@@ -1,105 +1,192 @@
-import { Context, Effect, Layer, type Schema } from 'effect'
+import { Context, Effect, GlobalValue, Layer, MutableRef, Option, Schema } from 'effect'
 import type { YieldWrap } from 'effect/Utils'
-import { type Manifest, definitionClass } from '../definition/definition'
-import { type Ctx } from '../internal/ctx'
-import type { Tracker } from '../internal/track'
+import { definitionClass } from '../definition/definition'
 import { CurrentTracker } from '../internal/track'
-import type { SlotClass } from './slot'
-import type { Structure } from './structure'
-import type { UiClass, UiContract } from './ui'
-import { Props } from './props'
-import type { AnyValue } from '../internal/variance'
+import { propsTag } from './props'
+import type { UiContract } from './ui'
+import type {
+  CompositionActivation,
+  CompositionActivationLayerInput,
+  CompositionCapture,
+  CompositionClass,
+  CompositionConfig,
+  CompositionDefinitionStatics,
+  CompositionId,
+  CompositionLayerInput,
+  CompositionManifest,
+  CompositionService,
+  ContextFreeProps,
+  ContractSlots,
+  EncodedPropsOf,
+  Frame,
+  GeneratorContext,
+  PropsOf,
+  RenderEnv,
+  RequiredSlotIdentities,
+  ScopedCompositionLiveConfig,
+  StatesOf,
+  UiCarrier,
+} from './compositionTypes'
 
-export type Frame<C extends UiContract = UiContract> = Structure<C>
+export { CompositionIdTypeId } from './compositionTypes'
+export type {
+  AnyComposition,
+  CompositionActivation,
+  CompositionCapture,
+  CompositionClass,
+  CompositionConfig,
+  CompositionId,
+  CompositionInstance,
+  CompositionManifest,
+  CompositionPropsReceiver,
+  CompositionReflection,
+  CompositionService,
+  CompositionTag,
+  Frame,
+  HasExactCompositionId,
+  RenderEnv,
+  RequiredSlotIdentities,
+  ScopedCompositionLiveConfig,
+  SlotClassesOf,
+} from './compositionTypes'
 
-export interface RenderEnv {
-  readonly props: unknown
-  readonly tracker: Tracker
-}
-
-export interface CompositionService {
-  readonly render: (env: RenderEnv) => Effect.Effect<Frame, never, never>
-}
-
-// Optional fields drive Config extends { props/states: … } inference — cannot be Option
-export interface CompositionConfig {
-  readonly title: string
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
-  readonly description?: string
-  // Schema variance needs any in encoded/context; only decoded P is used
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- drives `Config extends { props: … }` inference (PropsOf)
-  readonly props?: Schema.Schema.AnyNoContext
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- drives `Config extends { states: … }` inference (StatesOf)
-  readonly states?: ReadonlyArray<unknown>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
-  readonly calcs?: ReadonlyArray<unknown>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
-  readonly events?: ReadonlyArray<unknown>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
-  readonly slots?: Record<string, SlotClass>
-  // Manifest carrier only — full UiClass's invariant impl tag would leak C
-  readonly ui: { readonly manifest: Manifest & { readonly kind: 'Ui' } }
-}
-
-type PropsOf<Config> = Config extends { props: Schema.Schema<infer P, AnyValue> } ? P : unknown
 
-type StatesOf<Config> = Config extends { states: infer S extends ReadonlyArray<unknown> }
-  ? S
-  : readonly []
+const compositionDefinitionSequence: MutableRef.MutableRef<number> = GlobalValue.globalValue(
+  Symbol.for('reform/CompositionDefinitionSequence'),
+  () => MutableRef.make(0),
+)
 
-export interface CompositionClass<
-  out P,
-  out C extends UiContract = UiContract,
-  out S extends ReadonlyArray<unknown> = ReadonlyArray<unknown>,
-> {
-  new (): {}
-  readonly manifest: Manifest & { readonly kind: 'Composition' } & CompositionConfig
-  readonly Props: P
-  readonly Contract: C
-  readonly States: S
-  readonly tag: Context.Tag<CompositionService, CompositionService>
-}
+const nextCompositionTagKey = (name: string): string =>
+  `reform/composition/${name}/${MutableRef.incrementAndGet(compositionDefinitionSequence)}`
 
-interface UiCarrier<C extends UiContract> {
-  readonly ui: UiClass<C>
-}
+export const make =
+  <
+    const N extends string,
+    const Config extends CompositionConfig,
+    C extends UiContract,
+    const UiName extends string,
+  >(
+    name: N,
+    config: Config & UiCarrier<C, UiName> & ContractSlots<C> & ContextFreeProps<Config>,
+  ) =>
+  <Self>(): CompositionClass<PropsOf<Config>, C, StatesOf<Config>, N, Self> => {
+    const identity = Symbol(name)
+    const props = propsTag<PropsOf<Config>>()
+    const propsSchema = Schema.make<PropsOf<Config>, EncodedPropsOf<Config>>(
+      config.props?.ast ?? Schema.Unknown.ast,
+    )
+    const parseProps: (input: unknown) => Option.Option<PropsOf<Config>> =
+      Schema.decodeUnknownOption(propsSchema)
+    const tag = Context.GenericTag<
+      CompositionId<N, Self, RequiredSlotIdentities<C>>,
+      CompositionService<PropsOf<Config>, C>
+    >(nextCompositionTagKey(name))
+    const manifest = {
+      kind: 'Composition',
+      name,
+      ...config,
+    } satisfies CompositionManifest<C, N>
+    const composition = definitionClass<
+      CompositionClass<PropsOf<Config>, C, StatesOf<Config>, N, Self>
+    >({
+      manifest,
+      identity,
+      props,
+      parseProps,
+      acceptsProps: () => undefined,
+      tag,
+      capture: <Result>(visit: CompositionCapture<Result>): Result => visit(composition),
+    } satisfies CompositionDefinitionStatics<PropsOf<Config>, C, StatesOf<Config>, N, Self>)
+    return composition
+  }
 
-export const make = <const Config extends CompositionConfig, C extends UiContract>(
-  name: string,
-  // Constrain ui to full UiClass<C> for inference; stored manifest keeps erased carrier
-  config: Config & UiCarrier<C>,
-): CompositionClass<PropsOf<Config>, C, StatesOf<Config>> => {
-  const tag = Context.GenericTag<CompositionService, CompositionService>(
-    `reform/composition/${name}`,
-  )
-  const manifest = { kind: 'Composition' as const, name, ...config }
-  return definitionClass<CompositionClass<PropsOf<Config>, C, StatesOf<Config>>>({ manifest, tag })
-}
 
 export const live = <
   P,
   C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
   Eff extends YieldWrap<Effect.Effect<unknown, never, unknown>>,
 >(
-  composition: CompositionClass<P, C>,
+  composition: CompositionClass<P, C, S, N, Identity>,
   body: () => Generator<Eff, Frame<C>, never>,
-): Layer.Layer<CompositionService, never, Exclude<Ctx<Eff>, Props>> => {
-  const logic = Effect.gen(body)
+): Layer.Layer<
+  CompositionId<N, Identity, RequiredSlotIdentities<C>>,
+  never,
+  CompositionLayerInput<Eff>
+> => {
+  const logic: Effect.Effect<Frame<C>, never, GeneratorContext<Eff>> = Effect.gen(body).pipe(
+    Effect.orDie,
+  )
   return Layer.effect(
     composition.tag,
     Effect.gen(function* () {
-      const context = yield* Effect.context<Exclude<Ctx<Eff>, Props>>()
-      const render = (env: RenderEnv): Effect.Effect<Frame, never, never> =>
-        // oxlint-disable-next-line reform-rules/no-type-assertion -- the one documented render-boundary erasure: a fully-provided generic body's Structure<C> narrowed back to the contract-agnostic Frame service type
-        logic.pipe(
-          Effect.provideService(Props, env.props),
+      const context = yield* Effect.context<CompositionLayerInput<Eff>>()
+      const render = (env: RenderEnv<P>): Effect.Effect<Frame<C>, never, never> => {
+        return logic.pipe(
+          Effect.provideService(composition.props, env.props),
           Effect.provideService(CurrentTracker, env.tracker),
           Effect.provide(context),
-        ) as unknown as Effect.Effect<Frame, never, never>
-      return { render }
+        )
+      }
+      return { render, activation: () => Option.none() }
+    }),
+  )
+}
+
+export const liveScoped = <
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  RenderEff extends YieldWrap<Effect.Effect<unknown, never, unknown>>,
+  ActivationEff extends YieldWrap<Effect.Effect<unknown, never, unknown>>,
+>(
+  composition: CompositionClass<P, C, S, N, Identity>,
+  config: ScopedCompositionLiveConfig<C, RenderEff, ActivationEff>,
+): Layer.Layer<
+  CompositionId<N, Identity, RequiredSlotIdentities<C>>,
+  never,
+  CompositionLayerInput<RenderEff> | CompositionActivationLayerInput<ActivationEff>
+> => {
+  const renderLogic: Effect.Effect<Frame<C>, never, GeneratorContext<RenderEff>> = Effect.gen(
+    config.render,
+  ).pipe(Effect.orDie)
+  const activationLogic: Effect.Effect<void, never, GeneratorContext<ActivationEff>> = Effect.gen(
+    config.activate,
+  ).pipe(Effect.orDie)
+
+  return Layer.effect(
+    composition.tag,
+    Effect.gen(function* () {
+      const renderContext = yield* Effect.context<CompositionLayerInput<RenderEff>>()
+      const activationContext =
+        yield* Effect.context<CompositionActivationLayerInput<ActivationEff>>()
+      const render = (env: RenderEnv<P>): Effect.Effect<Frame<C>, never, never> =>
+        renderLogic.pipe(
+          Effect.provideService(composition.props, env.props),
+          Effect.provideService(CurrentTracker, env.tracker),
+          Effect.provide(renderContext),
+        )
+      const activation = (props: P): Option.Option<CompositionActivation> => {
+        const scoped = Layer.scopedDiscard(
+          activationLogic.pipe(Effect.provideService(composition.props, props)),
+        )
+        return Option.some(scoped.pipe(Layer.provide(Layer.succeedContext(activationContext))))
+      }
+      return { render, activation }
     }),
   )
 }
 
-export const render = (service: CompositionService, env: RenderEnv): Effect.Effect<Frame, never, never> =>
-  service.render(env)
+export const render = <P, C extends UiContract>(
+  service: CompositionService<P, C>,
+  env: RenderEnv<P>,
+): Effect.Effect<Frame<C>, never, never> => service.render(env)
+
+export const activation = <P, C extends UiContract>(
+  service: CompositionService<P, C>,
+  props: P,
+): Option.Option<CompositionActivation> => service.activation(props)

package/src/compose/compositionTypes.ts

@@ -0,0 +1,249 @@
+import type { Context, Effect, Layer, Option, Schema, Scope } from 'effect'
+import type { AST } from 'effect/SchemaAST'
+import type { YieldWrap } from 'effect/Utils'
+import type { Manifest } from '../definition/definition'
+import type { Tracker } from '../internal/track'
+import type { CurrentTracker } from '../internal/track'
+import type { PropsId, PropsTag } from './props'
+import type { AnySlot, AnySlotInstance, SlotClass, SlotInstance } from './slot'
+import type { Structure } from './structure'
+import type { UiClass, UiContract, UiReflection } from './ui'
+
+export type Frame<C extends UiContract = UiContract> = Structure<C>
+
+export interface RenderEnv<out P = unknown> {
+  readonly props: P
+  readonly tracker: Tracker
+}
+
+export type CompositionActivation = Layer.Layer<never, never, never>
+
+export interface CompositionService<in out P = unknown, out C extends UiContract = UiContract> {
+  readonly render: (env: RenderEnv<P>) => Effect.Effect<Frame<C>, never, never>
+  readonly activation: (props: P) => Option.Option<CompositionActivation>
+}
+
+export const CompositionIdTypeId: unique symbol = Symbol.for('reform/CompositionId')
+export type CompositionIdTypeId = typeof CompositionIdTypeId
+
+export interface CompositionId<
+  out N extends string,
+  out Identity = unknown,
+  out RequiredSlots = unknown,
+> {
+  readonly [CompositionIdTypeId]: {
+    readonly name: N
+    readonly identity: Identity
+    readonly requiredSlots: RequiredSlots
+  }
+}
+
+export type IsExact<Left, Right> = [Left] extends [Right] ? ([Right] extends [Left] ? true : false) : false
+
+export type IsExactCompositionId<Service, N extends string, Identity> = Service extends {
+  readonly [CompositionIdTypeId]: {
+    readonly name: infer ServiceName extends string
+    readonly identity: infer ServiceIdentity
+  }
+}
+  ? IsExact<ServiceName, N> extends true
+    ? IsExact<ServiceIdentity, Identity>
+    : false
+  : false
+
+export type IsAny<T> = 0 extends 1 & T ? true : false
+
+export type HasExactCompositionId<Services, N extends string, Identity> =
+  IsAny<Services> extends true
+    ? false
+    : true extends IsExactCompositionId<Services, N, Identity>
+      ? true
+      : false
+
+export type CompositionTag<
+  N extends string,
+  P,
+  C extends UiContract,
+  Identity = unknown,
+> = Context.Tag<CompositionId<N, Identity, RequiredSlotIdentities<C>>, CompositionService<P, C>>
+
+export type SlotClassesOf<C extends UiContract> = C extends {
+  readonly slots: infer Slots extends Record<string, AnySlotInstance>
+}
+  ? {
+      readonly [K in keyof Slots]: Slots[K] extends SlotInstance<
+        infer Child,
+        infer SlotName,
+        infer SlotIdentity
+      >
+        ? SlotClass<Child, SlotName, SlotIdentity>
+        : never
+    }
+  : Readonly<Record<PropertyKey, never>>
+
+export type RequiredSlotIdentity<Slot> =
+  Slot extends SlotInstance<infer _Target, infer _Name, infer Identity> ? Identity : never
+
+export type RequiredSlotIdentities<C extends UiContract> = C extends {
+  readonly slots: infer Slots extends Record<string, AnySlotInstance>
+}
+  ? RequiredSlotIdentity<Slots[keyof Slots]>
+  : never
+
+export type CompositionSlots<C extends UiContract> = C extends {
+  readonly slots: infer Slots extends Record<string, AnySlotInstance>
+}
+  ? [Slots[keyof Slots]] extends [never]
+    ? {}
+    : { readonly slots: SlotClassesOf<C> }
+  : {}
+
+export type CompositionManifest<
+  C extends UiContract = UiContract,
+  N extends string = string,
+> = Manifest &
+  Omit<CompositionConfig, 'slots' | 'ui'> &
+  CompositionSlots<C> & {
+    readonly kind: 'Composition'
+    readonly name: N
+    readonly ui: UiReflection<C>
+  }
+
+export interface CompositionInstance<out Identity = unknown> {
+  readonly _compositionIdentity: Identity
+}
+
+export interface CompositionReflection<
+  out P = unknown,
+  out C extends UiContract = UiContract,
+  out S extends ReadonlyArray<unknown> = ReadonlyArray<unknown>,
+  out N extends string = string,
+  out Identity = unknown,
+> {
+  new (): CompositionInstance<Identity>
+  readonly manifest: CompositionManifest<C, N>
+  readonly Props: P
+  readonly Contract: C
+  readonly States: S
+  readonly parseProps: (input: unknown) => Option.Option<P>
+}
+
+export interface CompositionPropsReceiver<in P> {
+  readonly acceptsProps: (props: P) => void
+}
+
+export type CompositionCapture<Result> = <
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+>(
+  composition: CompositionClass<P, C, S, N, Identity>,
+) => Result
+
+export interface AnyComposition extends CompositionReflection {
+  readonly capture: <Result>(visit: CompositionCapture<Result>) => Result
+}
+
+export interface CompositionSchema {
+  readonly ast: AST
+}
+
+export type GeneratorContext<Eff> = [Eff] extends [never]
+  ? never
+  : [Eff] extends [YieldWrap<Effect.Effect<infer _Success, infer _Error, infer R>>]
+    ? R
+    : never
+
+// Property presence drives Config conditional inference; Option would erase it.
+export interface CompositionConfigOptionalFields {
+  readonly description: string
+  readonly props: CompositionSchema
+  readonly states: ReadonlyArray<unknown>
+  readonly calcs: ReadonlyArray<unknown>
+  readonly events: ReadonlyArray<unknown>
+  readonly slots: Record<string, AnySlot>
+}
+
+export interface CompositionConfig extends Partial<CompositionConfigOptionalFields> {
+  readonly title: string
+  readonly ui: UiReflection
+}
+
+export type PropsOf<Config> = Config extends { props: infer PropsSchema }
+  ? PropsSchema extends Schema.Schema<infer P, infer _Encoded, infer _Context>
+    ? P
+    : unknown
+  : unknown
+
+export type EncodedPropsOf<Config> = Config extends { props: infer PropsSchema }
+  ? PropsSchema extends Schema.Schema<infer _Props, infer Encoded, infer _Context>
+    ? Encoded
+    : unknown
+  : unknown
+
+export type StatesOf<Config> = Config extends {
+  states: infer S extends ReadonlyArray<unknown>
+}
+  ? S
+  : readonly []
+
+export interface CompositionClass<
+  in out P,
+  in out C extends UiContract = UiContract,
+  out S extends ReadonlyArray<unknown> = ReadonlyArray<unknown>,
+  in out N extends string = string,
+  in out Identity = unknown,
+>
+  extends CompositionReflection<P, C, S, N, Identity>, CompositionPropsReceiver<P> {
+  readonly Props: P
+  readonly Contract: C
+  readonly States: S
+  readonly identity: symbol
+  readonly props: PropsTag<P>
+  readonly tag: CompositionTag<N, P, C, Identity>
+  readonly capture: <Result>(visit: CompositionCapture<Result>) => Result
+}
+
+export type CompositionDefinitionStatics<
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+> = Pick<
+  CompositionClass<P, C, S, N, Identity>,
+  'manifest' | 'identity' | 'props' | 'parseProps' | 'acceptsProps' | 'tag' | 'capture'
+>
+
+export interface UiCarrier<C extends UiContract, UiName extends string> {
+  readonly ui: UiClass<C, UiName>
+}
+
+export type ContractSlots<C extends UiContract> = CompositionSlots<C>
+
+export type ContextFreeProps<Config> = Config extends {
+  readonly props: infer PropsSchema
+}
+  ? PropsSchema extends Schema.Schema<infer _P, infer _Encoded, infer Context>
+    ? [Context] extends [never]
+      ? unknown
+      : { readonly propsSchemaMustNotRequireServices: never }
+    : unknown
+  : unknown
+export type CompositionLayerInput<Eff> = Exclude<Exclude<GeneratorContext<Eff>, PropsId>, CurrentTracker>
+
+export type CompositionActivationLayerInput<Eff> = Exclude<
+  Exclude<GeneratorContext<Eff>, PropsId>,
+  Scope.Scope
+>
+
+export interface ScopedCompositionLiveConfig<
+  C extends UiContract,
+  RenderEff extends YieldWrap<Effect.Effect<unknown, never, unknown>>,
+  ActivationEff extends YieldWrap<Effect.Effect<unknown, never, unknown>>,
+> {
+  readonly render: () => Generator<RenderEff, Frame<C>, never>
+  readonly activate: () => Generator<ActivationEff, void, never>
+}

package/src/compose/props.ts

@@ -1,8 +1,15 @@
 import { Context } from 'effect'
-import type { AnyValue } from '../internal/variance'
 
-const PropsBase: Context.TagClass<Props, 'reform/Props', AnyValue> = Context.Tag('reform/Props')<
-  Props,
-  AnyValue
->()
-export class Props extends PropsBase {}
+export const PropsIdTypeId: unique symbol = Symbol.for('reform/PropsId')
+export type PropsIdTypeId = typeof PropsIdTypeId
+
+export interface PropsId {
+  readonly [PropsIdTypeId]: PropsIdTypeId
+}
+
+export type PropsTag<P> = Context.Tag<PropsId, P>
+
+export const propsTag = <P>(): PropsTag<P> => Context.GenericTag<PropsId, P>('reform/Props')
+
+// Unknown keeps the compatibility reader from leaking untyped props.
+export const Props: PropsTag<unknown> = propsTag<unknown>()