@playfast/reform 1.1.1 → 1.2.1

package/src/feature/feature.ts

@@ -1,291 +1,251 @@
-import { Context, Effect, Layer, Option, type Scope } from 'effect'
-import { type Engine } from '../runtime/loop'
-import { type StoresOf } from '../internal/sources'
-import { FeatureLoadFailed } from '../internal/errors'
-import { definitionClass } from '../definition/definition'
-import { type CompositionClass } from '../compose/composition'
-import { type UiContract } from '../compose/ui'
-import { publish, type Tagged } from '../runtime/bus'
-import type { AnyValue } from '../internal/variance'
+import { Effect, type Schema } from 'effect'
+import type { AnyComposition, CompositionClass } from '../compose/composition'
+import type { UiContract } from '../compose/ui'
+import { FeatureGraphValidTypeId } from '../graph/closure'
+import type { EagerFeatureClass, LazyFeatureClass } from './featureClass'
 import {
-  type FeatureBinding,
-  FeatureBindingTypeId,
-  type FeatureManifest,
+  type EagerFeatureConfigExternalApi,
+  type ExactFeatureCompositionConfig,
+  type FeatureMountProps,
+  type FeatureUsesInput,
+  isMakeImplementationConfig,
+  type LazyFeatureConfigExternalApi,
+} from './featureConfig'
+import type { FeatureRequirement } from './featureRequirement'
+import { makeEagerFeature, makeLazyFeature } from './featureVariants'
+
+export type { EngineServices } from '../runtime/loop'
+export { FeatureGraphValidTypeId }
+export { FeatureInput } from './featureRequirement'
+export type {
+  FeatureModuleInput,
+  FeatureRequirement,
+  ProvidedBy,
+  RequireCarrier,
+} from './featureRequirement'
+export { featureModule, featureModuleFromInput, lazyImport } from './featureModule'
+export type { AnyLoadedModule, FeatureModule, LoadedModule, LoadedModuleCapture } from './featureModule'
+export { FeatureBindingTypeId, isFeatureBinding, tree } from './featureBinding'
+export type {
+  AnyFeatureBinding,
+  AnyFeatureBindingExternalApi,
+  CapturedFeatureBinding,
+  FailedProps,
+  FeatureBinding,
+  FeatureBindingCapture,
+  FeatureBindingType,
+  FeatureDefinition,
+  FeatureIdentityToken,
+  FeatureManifest,
+  FeatureOpenServices,
+  FeatureSupportOpenServices,
+  FeatureToken,
+  FeatureTreeCarrier,
+  ProvideableFeature,
 } from './featureBinding'
-export {
-  type FailedProps,
-  type FeatureBinding,
-  FeatureBindingTypeId,
-  type FeatureManifest,
-  isFeatureBinding,
-  type LoadedModule,
-} from './featureBinding'
-export type { FeatureBindingTypeId as FeatureBindingType } from './featureBinding'
-
-// Features must only name EngineServices as open RIn — never provide them (shared engine)
-export type EngineServices = Layer.Layer.Success<typeof Engine>
-
-const FeatureInputBase: Context.TagClass<FeatureInput, 'reform/FeatureInput', unknown> = Context.Tag(
-  'reform/FeatureInput',
-)<FeatureInput, unknown>()
-export class FeatureInput extends FeatureInputBase {}
-
-export type RequireCarrier =
-  | { readonly store: Context.Tag<AnyValue, AnyValue> }
-  | { readonly members: ReadonlyArray<{ readonly store: Context.Tag<AnyValue, AnyValue> }> }
-
-export type FeatureRequirement = RequireCarrier | Context.Tag<AnyValue, AnyValue>
-
-// Covariant RIn: layer reading outside EngineServices | ProvidedBy is unassignable
-export type ProvidedBy<Requires extends ReadonlyArray<FeatureRequirement>> = {
-  [I in keyof Requires]: Requires[I] extends Context.Tag<infer Identifier, AnyValue>
-    ? Identifier
-    : Requires[I] extends {
-    readonly members: infer M extends ReadonlyArray<unknown>
-  }
-    ? StoresOf<M>
-    : Requires[I] extends { readonly store: Context.Tag<infer Svc, AnyValue> }
-      ? Svc
-      : never
-}[number]
-
-export interface FeatureModule<
-  ROut,
-  Requires extends ReadonlyArray<FeatureRequirement>,
-  UsesInput extends boolean = false,
-> {
-  readonly requires: Requires
-  readonly usesInput: UsesInput
-  readonly layer: Layer.Layer<
-    ROut,
-    never,
-    | EngineServices
-    | ProvidedBy<Requires>
-    | (UsesInput extends true ? FeatureInput : never)
-  >
-}
-
-export const featureModule = <const Requires extends ReadonlyArray<FeatureRequirement>, ROut>(
-  requires: Requires,
-  layer: Layer.Layer<ROut, never, EngineServices | ProvidedBy<Requires>>,
-): FeatureModule<ROut, Requires, false> => ({ requires, usesInput: false, layer })
-
-export const featureModuleFromInput = <
-  const Requires extends ReadonlyArray<FeatureRequirement>,
-  ROut,
->(
-  requires: Requires,
-  layer: Layer.Layer<ROut, never, EngineServices | ProvidedBy<Requires> | FeatureInput>,
-): FeatureModule<ROut, Requires, true> => ({ requires, usesInput: true, layer })
-
-// Seals Promise import as Effect; rejection → FeatureLoadFailed
-export const lazyImport = <M>(
-  thunk: () => Promise<{ readonly default: M }>,
-): Effect.Effect<M, FeatureLoadFailed> =>
-  Effect.tryPromise({
-    try: thunk,
-    catch: (cause) => new FeatureLoadFailed({ cause }),
-  }).pipe(Effect.map((module) => module.default))
-
-export interface FeatureClass<
-  P,
-  C extends UiContract,
-  ROut,
-  Requires extends ReadonlyArray<FeatureRequirement>,
-  SupportRequires extends ReadonlyArray<FeatureRequirement> = readonly [],
-> {
-  new (): {}
-  readonly manifest: FeatureManifest
-  readonly Props: P
-  readonly Contract: C
-  readonly composition: CompositionClass<P, C>
-  readonly Requires: Requires
-  readonly load: Effect.Effect<FeatureModule<ROut, Requires, boolean>, FeatureLoadFailed>
-  readonly binding: FeatureBinding
-  readonly eagerModule: FeatureModule<ROut, Requires, false> | undefined
-  readonly supportModule: FeatureModule<never, SupportRequires, false> | undefined
-}
-
-export interface EagerFeatureClass<
-  P,
-  C extends UiContract,
-  ROut,
-  Requires extends ReadonlyArray<FeatureRequirement>,
-> extends FeatureClass<P, C, ROut, Requires> {
-  readonly eagerModule: FeatureModule<ROut, Requires, false>
-  readonly supportModule: undefined
-}
-
-export interface LazyFeatureClass<
-  P,
-  C extends UiContract,
-  ROut,
-  Requires extends ReadonlyArray<FeatureRequirement>,
-  SupportRequires extends ReadonlyArray<FeatureRequirement> = readonly [],
-> extends FeatureClass<P, C, ROut, Requires, SupportRequires> {
-  readonly eagerModule: undefined
-}
-
-export type AnyFeature = FeatureClass<
-  AnyValue,
-  AnyValue,
-  AnyValue,
-  ReadonlyArray<FeatureRequirement>,
-  ReadonlyArray<FeatureRequirement>
->
-
-export const isFeature = (candidate: unknown): candidate is AnyFeature =>
-  (typeof candidate === 'function' || typeof candidate === 'object') &&
-  candidate !== null &&
-  'manifest' in candidate &&
-  typeof candidate.manifest === 'object' &&
-  candidate.manifest !== null &&
-  'kind' in candidate.manifest &&
-  candidate.manifest.kind === 'Feature'
-
-export interface Placeholders {
-  readonly loading: CompositionClass<AnyValue, UiContract>
-  readonly failed: CompositionClass<AnyValue, UiContract>
-}
-
-interface FeatureConfigBaseExternalApi<P, C extends UiContract> {
-  readonly composition: CompositionClass<P, C>
-  readonly boot?: ReadonlyArray<Tagged>
-}
-
-type EagerFeatureConfigExternalApi<
-  P,
-  C extends UiContract,
-  ROut,
-  Requires extends ReadonlyArray<FeatureRequirement>,
-> = FeatureConfigBaseExternalApi<P, C> & {
-  readonly loadingStrategy?: 'default'
-  readonly module: FeatureModule<ROut, Requires, false>
-}
-
-type LazyFeatureConfigExternalApi<
-  P,
-  C extends UiContract,
-  ROut,
-  Requires extends ReadonlyArray<FeatureRequirement>,
-  SupportOut,
-  SupportRequires extends ReadonlyArray<FeatureRequirement>,
-> = FeatureConfigBaseExternalApi<P, C> & {
-  readonly loadingStrategy: 'lazy'
-  readonly load: Effect.Effect<FeatureModule<ROut, Requires, boolean>, FeatureLoadFailed>
-  readonly placeholder: Placeholders
-  readonly eager?: FeatureModule<SupportOut, SupportRequires, false>
-}
+export type {
+  EagerFeatureNativeTree,
+  FeatureNativeTree,
+  LazyFeatureNativeTree,
+} from './featureNativeTree'
+export type { EagerFeatureClass, FeatureClass, LazyFeatureClass } from './featureClass'
+export { isFeature } from './featureConfig'
+export type { FeatureMountProps, Placeholders } from './featureConfig'
+export { mountFeature } from './mountFeature'
 
 export function make<
   P,
   C extends UiContract,
   ROut,
-  Requires extends ReadonlyArray<FeatureRequirement>,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  const Composition extends CompositionClass<P, C, S, N, Identity>,
 >(
   name: string,
-  config: EagerFeatureConfigExternalApi<P, C, ROut, Requires>,
-): EagerFeatureClass<P, C, ROut, Requires>
-export function make<
+  config: EagerFeatureConfigExternalApi<
+    P,
+    C,
+    ROut,
+    DirectRequires,
+    OpenServices,
+    S,
+    N,
+    Identity
+  > & { readonly composition: Composition },
+): EagerFeatureClass<
+  Identity,
   P,
+  C,
+  ROut,
+  DirectRequires,
+  OpenServices,
+  S,
+  N,
+  Identity,
+  Composition
+>
+export function make<
+  CompositionProps,
   C extends UiContract,
   ROut,
-  Requires extends ReadonlyArray<FeatureRequirement>,
-  SupportOut,
-  SupportRequires extends ReadonlyArray<FeatureRequirement>,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  const Composition extends CompositionClass<CompositionProps, C, S, N, Identity>,
+  const Loading extends AnyComposition,
+  const Failed extends AnyComposition,
+  const InputSchema extends Schema.Schema.AnyNoContext = never,
+  SupportOut = never,
+  SupportDirectRequires extends ReadonlyArray<FeatureRequirement> = readonly [],
+  SupportOpenServices = never,
 >(
   name: string,
   config: LazyFeatureConfigExternalApi<
-    P,
+    CompositionProps,
     C,
     ROut,
-    Requires,
+    DirectRequires,
+    OpenServices,
     SupportOut,
-    SupportRequires
-  > & { readonly eager: FeatureModule<SupportOut, SupportRequires, false> },
-): LazyFeatureClass<P, C, ROut, Requires, SupportRequires>
+    SupportDirectRequires,
+    SupportOpenServices,
+    S,
+    N,
+    Identity,
+    InputSchema,
+    Loading,
+    Failed
+  > & { readonly composition: Composition },
+): LazyFeatureClass<
+  Identity,
+  FeatureMountProps<FeatureUsesInput<InputSchema>, CompositionProps, InputSchema>,
+  C,
+  ROut,
+  DirectRequires,
+  OpenServices,
+  SupportOut,
+  SupportDirectRequires,
+  SupportOpenServices,
+  FeatureUsesInput<InputSchema>,
+  S,
+  N,
+  CompositionProps,
+  Identity,
+  Composition
+>
 export function make<
-  P,
+  CompositionProps,
   C extends UiContract,
   ROut,
-  Requires extends ReadonlyArray<FeatureRequirement>,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  Composition extends CompositionClass<CompositionProps, C, S, N, Identity>,
+  Loading extends AnyComposition,
+  Failed extends AnyComposition,
+  InputSchema extends Schema.Schema.AnyNoContext = never,
+  SupportOut = never,
+  SupportDirectRequires extends ReadonlyArray<FeatureRequirement> = readonly [],
+  SupportOpenServices = never,
 >(
   name: string,
-  config: LazyFeatureConfigExternalApi<P, C, ROut, Requires, never, readonly []>,
-): LazyFeatureClass<P, C, ROut, Requires>
-export function make(
-  name: string,
-  config:
+  config: (
     | EagerFeatureConfigExternalApi<
-        AnyValue,
-        UiContract,
-        never,
-        ReadonlyArray<FeatureRequirement>
+        CompositionProps,
+        C,
+        ROut,
+        DirectRequires,
+        OpenServices,
+        S,
+        N,
+        Identity
       >
     | LazyFeatureConfigExternalApi<
-        AnyValue,
-        UiContract,
-        never,
-        ReadonlyArray<FeatureRequirement>,
-        never,
-        ReadonlyArray<FeatureRequirement>
-      >,
-): AnyFeature {
-  const strategy: 'lazy' | 'default' = config.loadingStrategy ?? 'default'
-  const load = 'load' in config ? config.load : Effect.succeed(config.module)
-  const eagerModule = 'module' in config ? config.module : undefined
-  const supportModule = 'eager' in config ? config.eager : undefined
-  const placeholder = 'placeholder' in config ? config.placeholder : undefined
-
-  const manifest: FeatureManifest = {
-    kind: 'Feature',
-    name,
-    strategy,
-    composition: config.composition.manifest,
-    placeholder: Option.fromNullable(placeholder).pipe(
-      Option.map((placeholders) => ({
-        loading: placeholders.loading.manifest,
-        failed: placeholders.failed.manifest,
-      })),
-    ),
+        CompositionProps,
+        C,
+        ROut,
+        DirectRequires,
+        OpenServices,
+        SupportOut,
+        SupportDirectRequires,
+        SupportOpenServices,
+        S,
+        N,
+        Identity,
+        InputSchema,
+        Loading,
+        Failed
+      >
+  ) &
+    ExactFeatureCompositionConfig<Composition>,
+):
+  | EagerFeatureClass<
+      Identity,
+      CompositionProps,
+      C,
+      ROut,
+      DirectRequires,
+      OpenServices,
+      S,
+      N,
+      Identity,
+      Composition
+    >
+  | LazyFeatureClass<
+      Identity,
+      FeatureMountProps<FeatureUsesInput<InputSchema>, CompositionProps, InputSchema>,
+      C,
+      ROut,
+      DirectRequires,
+      OpenServices,
+      SupportOut,
+      SupportDirectRequires,
+      SupportOpenServices,
+      FeatureUsesInput<InputSchema>,
+      S,
+      N,
+      CompositionProps,
+      Identity,
+      Composition
+    > {
+  if (!isMakeImplementationConfig(config)) {
+    return Effect.runSync(Effect.dieMessage(`Invalid Feature config for ${name}`))
   }
-
-  const binding: FeatureBinding = {
-    [FeatureBindingTypeId]: FeatureBindingTypeId,
-    manifest,
-    composition: config.composition,
-    strategy,
-    load,
-    ...(placeholder ? { placeholder: { loading: placeholder.loading, failed: placeholder.failed } } : {}),
-    boot: Option.getOrElse(Option.fromNullable(config.boot), () => []),
+  if (config.loadingStrategy === 'lazy') {
+    return makeLazyFeature<
+      CompositionProps,
+      C,
+      ROut,
+      DirectRequires,
+      OpenServices,
+      SupportOut,
+      SupportDirectRequires,
+      SupportOpenServices,
+      S,
+      N,
+      Identity,
+      Composition,
+      InputSchema,
+      Loading,
+      Failed
+    >(name, config)
   }
-
-  return definitionClass<AnyFeature>({
-    manifest,
-    load,
-    binding,
-    eagerModule,
-    supportModule,
-    composition: config.composition,
-  })
+  return makeEagerFeature<
+    CompositionProps,
+    C,
+    ROut,
+    DirectRequires,
+    OpenServices,
+    S,
+    N,
+    Identity,
+    Composition
+  >(name, config)
 }
-
-// oxlint-disable-next-line reform-rules/prefer-effect-fn -- generic export: Effect.fn's inferred type isn't portable under isolatedDeclarations
-export const mountFeature = <R>(
-  binding: FeatureBinding,
-  engineContext: Context.Context<R>,
-  props?: unknown,
-): Effect.Effect<Context.Context<unknown>, FeatureLoadFailed, Scope.Scope> =>
-  Effect.gen(function* () {
-    const module = yield* binding.load
-    // oxlint-disable-next-line reform-rules/no-type-assertion -- documented erasure boundary: re-attach the concrete engine context to the type-erased `LoadedModule` layer (mirrors `buildRuntime`); RIn was verified cast-free at `provide`/scene wiring
-    const featureLayer = module.layer as Layer.Layer<unknown, never, R | FeatureInput>
-    const featureContext = Context.add(engineContext, FeatureInput, props)
-    const context = yield* Layer.build(
-      Layer.provideMerge(featureLayer, Layer.succeedContext(featureContext)),
-    )
-    yield* Effect.forEach(binding.boot, (event) => publish('High', event), { discard: true }).pipe(
-      Effect.provide(context),
-    )
-    return context
-  })