@playfast/reform 1.2.0 → 1.2.1

package/src/feature/featureVariants.ts

@@ -0,0 +1,234 @@
+import { Effect, Option, type Schema } from 'effect'
+import type { AnyComposition, CompositionClass } from '../compose/composition'
+import type { UiContract } from '../compose/ui'
+import { definitionClass } from '../definition/definition'
+import {
+  FeatureNativeTypeId,
+  type FeatureToken,
+  FeatureTokenIdentityTypeId,
+} from './featureBinding'
+import type { EagerFeatureClass, LazyFeatureClass } from './featureClass'
+import type {
+  EagerFeatureConfigExternalApi,
+  ExactFeatureCompositionConfig,
+  FeatureInputValue,
+  FeatureMountProps,
+  FeatureUsesInput,
+  LazyFeatureConfigExternalApi,
+  RuntimePlaceholders,
+} from './featureConfig'
+import { makeFeatureBinding, makeFeatureManifest, makeFeatureSummary } from './featureFactory'
+import type { EagerFeatureNativeTree, LazyFeatureNativeTree } from './featureNativeTree'
+import type { FeatureRequirement } from './featureRequirement'
+
+export const makeEagerFeature = <
+  P,
+  C extends UiContract,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  Composition extends CompositionClass<P, C, S, N, Identity>,
+>(
+  name: string,
+  config: EagerFeatureConfigExternalApi<P, C, ROut, DirectRequires, OpenServices, S, N, Identity> &
+    ExactFeatureCompositionConfig<Composition>,
+): EagerFeatureClass<
+  Identity,
+  P,
+  C,
+  ROut,
+  DirectRequires,
+  OpenServices,
+  S,
+  N,
+  Identity,
+  Composition
+> => {
+  const featureIdentity = Symbol(name)
+  const placeholder = Option.none<RuntimePlaceholders>()
+  const manifest = makeFeatureManifest(name, 'default', config.composition, placeholder)
+  const load = Effect.succeed(config.module)
+  const summary = makeFeatureSummary<
+    Identity,
+    P,
+    P,
+    C,
+    S,
+    N,
+    Identity,
+    OpenServices,
+    never,
+    false,
+    never
+  >(config.composition)
+  const binding = makeFeatureBinding<typeof summary, ROut, DirectRequires>(
+    featureIdentity,
+    manifest,
+    summary,
+    config.composition,
+    load,
+    placeholder,
+    undefined,
+    Option.getOrElse(Option.fromNullable(config.boot), () => []),
+  )
+  const native: EagerFeatureNativeTree<typeof summary, ROut, DirectRequires, Composition> = {
+    identity: featureIdentity,
+    summary,
+    composition: config.composition,
+    load,
+    binding,
+    eagerModule: config.module,
+    supportModule: undefined,
+  }
+  const token: FeatureToken<Identity, typeof native> = {
+    identity: featureIdentity,
+    [FeatureTokenIdentityTypeId]: [],
+    [FeatureNativeTypeId]: native,
+  }
+  return definitionClass<
+    EagerFeatureClass<
+      Identity,
+      P,
+      C,
+      ROut,
+      DirectRequires,
+      OpenServices,
+      S,
+      N,
+      Identity,
+      Composition
+    >
+  >({
+    manifest,
+    summary,
+    token,
+  })
+}
+
+export const makeLazyFeature = <
+  CompositionProps,
+  C extends UiContract,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices,
+  SupportOut,
+  SupportDirectRequires extends ReadonlyArray<FeatureRequirement>,
+  SupportOpenServices,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  Composition extends CompositionClass<CompositionProps, C, S, N, Identity>,
+  InputSchema extends Schema.Schema.AnyNoContext,
+  Loading extends AnyComposition,
+  Failed extends AnyComposition,
+>(
+  name: string,
+  config: LazyFeatureConfigExternalApi<
+    CompositionProps,
+    C,
+    ROut,
+    DirectRequires,
+    OpenServices,
+    SupportOut,
+    SupportDirectRequires,
+    SupportOpenServices,
+    S,
+    N,
+    Identity,
+    InputSchema,
+    Loading,
+    Failed
+  > &
+    ExactFeatureCompositionConfig<Composition>,
+): LazyFeatureClass<
+  Identity,
+  FeatureMountProps<FeatureUsesInput<InputSchema>, CompositionProps, InputSchema>,
+  C,
+  ROut,
+  DirectRequires,
+  OpenServices,
+  SupportOut,
+  SupportDirectRequires,
+  SupportOpenServices,
+  FeatureUsesInput<InputSchema>,
+  S,
+  N,
+  CompositionProps,
+  Identity,
+  Composition
+> => {
+  const featureIdentity = Symbol(name)
+  const placeholder = Option.some<RuntimePlaceholders>(config.placeholder)
+  const manifest = makeFeatureManifest(name, 'lazy', config.composition, placeholder)
+  const inputSchema = 'input' in config ? config.input : undefined
+  const summary = makeFeatureSummary<
+    Identity,
+    FeatureMountProps<FeatureUsesInput<InputSchema>, CompositionProps, InputSchema>,
+    CompositionProps,
+    C,
+    S,
+    N,
+    Identity,
+    OpenServices,
+    SupportOpenServices,
+    FeatureUsesInput<InputSchema>,
+    FeatureInputValue<InputSchema>
+  >(config.composition)
+  const binding = makeFeatureBinding<typeof summary, ROut, DirectRequires>(
+    featureIdentity,
+    manifest,
+    summary,
+    config.composition,
+    config.load,
+    placeholder,
+    inputSchema,
+    Option.getOrElse(Option.fromNullable(config.boot), () => []),
+  )
+  const native: LazyFeatureNativeTree<
+    typeof summary,
+    ROut,
+    DirectRequires,
+    SupportOut,
+    SupportDirectRequires,
+    Composition
+  > = {
+    identity: featureIdentity,
+    summary,
+    composition: config.composition,
+    load: config.load,
+    binding,
+    eagerModule: undefined,
+    supportModule: config.eager,
+  }
+  const token: FeatureToken<Identity, typeof native> = {
+    identity: featureIdentity,
+    [FeatureTokenIdentityTypeId]: [],
+    [FeatureNativeTypeId]: native,
+  }
+  return definitionClass<
+    LazyFeatureClass<
+      Identity,
+      FeatureMountProps<FeatureUsesInput<InputSchema>, CompositionProps, InputSchema>,
+      C,
+      ROut,
+      DirectRequires,
+      OpenServices,
+      SupportOut,
+      SupportDirectRequires,
+      SupportOpenServices,
+      FeatureUsesInput<InputSchema>,
+      S,
+      N,
+      CompositionProps,
+      Identity,
+      Composition
+    >
+  >({
+    manifest,
+    summary,
+    token,
+  })
+}

package/src/feature/mountFeature.ts

@@ -0,0 +1,54 @@
+import { Context, Effect, Layer, type Scope } from 'effect'
+import type {
+  AnyFeatureGraphSummary,
+  FeatureSummaryInput,
+  FeatureSummaryOpenServices,
+} from '../graph/closure'
+import type { FeatureLoadFailed } from '../internal/errors'
+import { Bus, publish } from '../runtime/bus'
+import type { EngineServices } from '../runtime/loop'
+import type { FeatureBinding } from './featureBinding'
+import { FeatureInput, type FeatureRequirement } from './featureRequirement'
+
+type MountFeature = <
+  Summary extends AnyFeatureGraphSummary,
+  ROut,
+  const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  HostServices,
+>(
+  binding: FeatureBinding<Summary, ROut, DirectRequires>,
+  engineContext: Context.Context<
+    HostServices | EngineServices | FeatureSummaryOpenServices<Summary>
+  >,
+  props?: FeatureSummaryInput<Summary>,
+) => Effect.Effect<
+  Context.Context<HostServices | EngineServices | FeatureSummaryOpenServices<Summary> | ROut>,
+  FeatureLoadFailed,
+  Scope.Scope
+>
+
+export const mountFeature: MountFeature = Effect.fn('mountFeature')(function* <
+  Summary extends AnyFeatureGraphSummary,
+  ROut,
+  const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  HostServices,
+>(
+  binding: FeatureBinding<Summary, ROut, DirectRequires>,
+  engineContext: Context.Context<
+    HostServices | EngineServices | FeatureSummaryOpenServices<Summary>
+  >,
+  props: FeatureSummaryInput<Summary> | undefined = undefined,
+): Effect.fn.Return<
+  Context.Context<HostServices | EngineServices | FeatureSummaryOpenServices<Summary> | ROut>,
+  FeatureLoadFailed,
+  Scope.Scope
+> {
+  const { layer } = yield* binding.load
+  const bus = Context.get(engineContext, Bus)
+  const featureContext = Context.add(engineContext, FeatureInput, props)
+  const context = yield* Layer.build(Layer.provide(layer, Layer.succeedContext(featureContext)))
+  yield* Effect.forEach(binding.boot, (event) => publish('High', event), {
+    discard: true,
+  }).pipe(Effect.provideService(Bus, bus))
+  return Context.merge(engineContext, context)
+})

package/src/graph/closure.ts

@@ -1,232 +1,51 @@
-import { Layer } from 'effect'
+import type { Layer } from 'effect'
 import { CompositionIdTypeId } from '../compose/composition'
-import type { UiContract } from '../compose/ui'
 import { SlotServiceTypeId } from '../compose/slot'
-import type { FeatureInput, FeatureRequirement, ProvidedBy } from '../feature/feature'
+import type { FeatureRequirement, ProvidedBy } from '../feature/feature'
 import type { EngineServices } from '../runtime/loop'
-import type { StateStore } from '../state/state'
-import type { StateFamilyStore } from '../state/stateFamily'
-
-export const FeatureGraphValidTypeId: unique symbol = Symbol.for('reform/FeatureGraphValid')
-export type FeatureGraphValidTypeId = typeof FeatureGraphValidTypeId
-
-export const FeatureModuleGraphValidTypeId: unique symbol = Symbol.for(
-  'reform/FeatureModuleGraphValid',
-)
-export type FeatureModuleGraphValidTypeId = typeof FeatureModuleGraphValidTypeId
-
-export const FeatureChildSummaryTypeId: unique symbol = Symbol.for('reform/FeatureChildSummary')
-export type FeatureChildSummaryTypeId = typeof FeatureChildSummaryTypeId
-
-export const FeatureGraphSummaryTypeId: unique symbol = Symbol.for('reform/FeatureGraphSummary')
-export type FeatureGraphSummaryTypeId = typeof FeatureGraphSummaryTypeId
-
-export const SlotBindingSummaryTypeId: unique symbol = Symbol.for('reform/SlotBindingSummary')
-export type SlotBindingSummaryTypeId = typeof SlotBindingSummaryTypeId
-
-export interface SlotBindingSummary {
-  readonly [SlotBindingSummaryTypeId]: SlotBindingSummaryTypeId
-}
-
-/**
- * The constant-size proof published after a Feature's current module has passed
- * graph validation. Type-only facts use empty-or-singleton tuples so the runtime
- * summary stays compact while direct indexed access recovers their exact types.
- */
-export interface FeatureGraphSummary<
-  out FeatureIdentity,
-  out MountProps,
-  out CompositionProps,
-  out C extends UiContract,
-  out S extends ReadonlyArray<unknown>,
-  out N extends string,
-  out CompositionIdentity,
-  out OpenServices,
-  out SupportOpenServices,
-  out UsesInput extends boolean,
-  out Input,
-> extends SlotBindingSummary {
-  readonly [FeatureGraphSummaryTypeId]: {
-    readonly featureIdentity: readonly [] | readonly [FeatureIdentity]
-    readonly mountProps: readonly [] | readonly [MountProps]
-    readonly compositionProps: readonly [] | readonly [CompositionProps]
-    readonly contract: readonly [] | readonly [C]
-    readonly states: readonly [] | readonly [S]
-    readonly name: N
-    readonly compositionIdentity: readonly [] | readonly [CompositionIdentity]
-    readonly openServices: readonly [] | readonly [OpenServices]
-    readonly supportOpenServices: readonly [] | readonly [SupportOpenServices]
-    readonly usesInput: readonly [] | readonly [UsesInput]
-    readonly input: readonly [] | readonly [Input]
-    readonly validated: FeatureModuleGraphValidTypeId
-  }
-  readonly [FeatureChildSummaryTypeId]: {
-    readonly featureIdentity: readonly [] | readonly [FeatureIdentity]
-    readonly compositionIdentity: readonly [] | readonly [CompositionIdentity]
-  }
-}
-
-export type FeatureChildSummary<
-  FeatureIdentity,
-  MountProps,
-  CompositionProps,
-  C extends UiContract,
-  S extends ReadonlyArray<unknown>,
-  N extends string,
-  CompositionIdentity,
-  OpenServices,
-  SupportOpenServices,
-  UsesInput extends boolean,
-  Input,
-> = FeatureGraphSummary<
-  FeatureIdentity,
-  MountProps,
-  CompositionProps,
-  C,
-  S,
-  N,
-  CompositionIdentity,
-  OpenServices,
-  SupportOpenServices,
-  UsesInput,
-  Input
->
-
-export type AnyFeatureGraphSummary = FeatureGraphSummary<
-  unknown,
-  unknown,
-  unknown,
-  UiContract,
-  ReadonlyArray<unknown>,
-  string,
-  unknown,
-  unknown,
-  unknown,
-  boolean,
-  unknown
->
-
-export type FeatureSummaryIdentity<Summary extends AnyFeatureGraphSummary> =
-  Summary[FeatureGraphSummaryTypeId]['featureIdentity'][number]
-export type FeatureSummaryMountProps<Summary extends AnyFeatureGraphSummary> =
-  Summary[FeatureGraphSummaryTypeId]['mountProps'][number]
-export type FeatureSummaryCompositionProps<Summary extends AnyFeatureGraphSummary> =
-  Summary[FeatureGraphSummaryTypeId]['compositionProps'][number]
-export type FeatureSummaryContract<Summary extends AnyFeatureGraphSummary> =
-  Summary[FeatureGraphSummaryTypeId]['contract'][number]
-export type FeatureSummaryStates<Summary extends AnyFeatureGraphSummary> =
-  Summary[FeatureGraphSummaryTypeId]['states'][number]
-export type FeatureSummaryName<Summary extends AnyFeatureGraphSummary> =
-  Summary[FeatureGraphSummaryTypeId]['name']
-export type FeatureSummaryCompositionIdentity<Summary extends AnyFeatureGraphSummary> =
-  Summary[FeatureGraphSummaryTypeId]['compositionIdentity'][number]
-export type FeatureSummaryOpenServices<Summary extends AnyFeatureGraphSummary> =
-  Summary[FeatureGraphSummaryTypeId]['openServices'][number]
-export type FeatureSummarySupportOpenServices<Summary extends AnyFeatureGraphSummary> =
-  Summary[FeatureGraphSummaryTypeId]['supportOpenServices'][number]
-export type FeatureSummaryUsesInput<Summary extends AnyFeatureGraphSummary> =
-  Summary[FeatureGraphSummaryTypeId]['usesInput'][number]
-export type FeatureSummaryInput<Summary extends AnyFeatureGraphSummary> =
-  Summary[FeatureGraphSummaryTypeId]['input'][number]
-
-export const CompositionChildSummaryTypeId: unique symbol = Symbol.for(
-  'reform/CompositionChildSummary',
-)
-export type CompositionChildSummaryTypeId = typeof CompositionChildSummaryTypeId
-
-export interface CompositionChildSummary<out CompositionIdentity> extends SlotBindingSummary {
-  readonly [CompositionChildSummaryTypeId]: {
-    readonly compositionIdentity: CompositionIdentity
-  }
-}
-
-type IsAny<Value> = 0 extends 1 & Value ? true : false
-
-type IsErased<Value> = IsAny<Value> extends true ? true : unknown extends Value ? true : false
-
-type ExactStateStoreName<Service> =
-  IsAny<Service> extends true
-    ? never
-    : Service extends StateStore<infer Name, infer _Value>
-      ? string extends Name
-        ? never
-        : Name
-      : never
-
-type ExactStateFamilyStoreName<Service> =
-  IsAny<Service> extends true
-    ? never
-    : Service extends StateFamilyStore<infer Name, infer _Key, infer _Value>
-      ? string extends Name
-        ? never
-        : Name
-      : never
-
-type ServiceIsProvided<Required, Provided> =
-  IsErased<Provided> extends true
-    ? false
-    : Required extends StateStore<infer Name, infer _Value>
-      ? Name extends ExactStateStoreName<Provided>
-        ? true
-        : false
-      : Required extends StateFamilyStore<infer Name, infer _Key, infer _Value>
-        ? Name extends ExactStateFamilyStoreName<Provided>
-          ? true
-          : false
-        : [Required] extends [Provided]
-          ? true
-          : false
-
-/**
- * Remove only services the provider can satisfy by their runtime Context tag.
- * Named State/StateFamily identifiers intentionally do not collapse into their
- * structurally broader Store/FamilyStore service APIs.
- */
-export type ExactServiceExclude<Required, Provided> = Required extends unknown
-  ? ServiceIsProvided<Required, Provided> extends true
-    ? never
-    : Required
-  : never
-
-type ExactServiceExtract<Required, Provided> = Required extends unknown
-  ? ServiceIsProvided<Required, Provided> extends true
-    ? Required
-    : never
-  : never
-
-type GraphValidationPassed = object
-
-type ExactIdentity<Identity> = IsErased<Identity> extends true ? never : Identity
-
-type InputService<UsesInput extends boolean> = UsesInput extends true ? FeatureInput : never
-
-export type OpenServicesFromFeatureSlotWitnesses<Services> = Services extends {
-  readonly [SlotServiceTypeId]: {
-    readonly binding: FeatureChildSummary<
-      infer _FeatureIdentity,
-      infer _MountProps,
-      infer _CompositionProps,
-      infer _Contract,
-      infer _States,
-      infer _Name,
-      infer _CompositionIdentity,
-      infer OpenServices,
-      infer SupportOpenServices,
-      infer _UsesInput,
-      infer _Input
-    >
-  }
-}
-  ? OpenServices | SupportOpenServices
-  : never
-
-export type DescendantOpenServices<L extends Layer.Layer.Any> =
-  OpenServicesFromFeatureSlotWitnesses<Layer.Layer.Success<L>>
-
-export type ModuleOpenServices<L extends Layer.Layer.Any, UsesInput extends boolean> = Exclude<
-  Layer.Layer.Context<L>,
-  EngineServices | InputService<UsesInput>
->
+import type {
+  ExactIdentity,
+  ExactServiceExclude,
+  ExactServiceExtract,
+  GraphValidationPassed,
+  InputService,
+  IsErased,
+} from './services'
+import type { CompositionChildSummary } from './summary'
+import type { DescendantOpenServices } from './services'
+
+export {
+  CompositionChildSummaryTypeId,
+  FeatureChildSummaryTypeId,
+  FeatureGraphSummaryTypeId,
+  FeatureGraphValidTypeId,
+  FeatureModuleGraphValidTypeId,
+  SlotBindingSummaryTypeId,
+} from './summary'
+export type {
+  AnyFeatureGraphSummary,
+  CompositionChildSummary,
+  FeatureChildSummary,
+  FeatureGraphSummary,
+  FeatureSummaryCompositionIdentity,
+  FeatureSummaryCompositionProps,
+  FeatureSummaryContract,
+  FeatureSummaryIdentity,
+  FeatureSummaryInput,
+  FeatureSummaryMountProps,
+  FeatureSummaryName,
+  FeatureSummaryOpenServices,
+  FeatureSummaryStates,
+  FeatureSummarySupportOpenServices,
+  FeatureSummaryUsesInput,
+  SlotBindingSummary,
+} from './summary'
+export type {
+  DescendantOpenServices,
+  ExactServiceExclude,
+  ModuleOpenServices,
+  OpenServicesFromFeatureSlotWitnesses,
+} from './services'
 
 type LayerErrorIsNever<L extends Layer.Layer.Any> =
   IsErased<Layer.Layer.Error<L>> extends true

package/src/graph/services.ts

@@ -0,0 +1,95 @@
+import type { Layer } from 'effect'
+import { SlotServiceTypeId } from '../compose/slot'
+import type { FeatureInput } from '../feature/feature'
+import type { EngineServices } from '../runtime/loop'
+import type { StateStore } from '../state/state'
+import type { StateFamilyStore } from '../state/stateFamily'
+import type { FeatureChildSummary } from './summary'
+
+export type IsAny<Value> = 0 extends 1 & Value ? true : false
+
+export type IsErased<Value> = IsAny<Value> extends true ? true : unknown extends Value ? true : false
+
+export type ExactStateStoreName<Service> =
+  IsAny<Service> extends true
+    ? never
+    : Service extends StateStore<infer Name, infer _Value>
+      ? string extends Name
+        ? never
+        : Name
+      : never
+
+export type ExactStateFamilyStoreName<Service> =
+  IsAny<Service> extends true
+    ? never
+    : Service extends StateFamilyStore<infer Name, infer _Key, infer _Value>
+      ? string extends Name
+        ? never
+        : Name
+      : never
+
+export type ServiceIsProvided<Required, Provided> =
+  IsErased<Provided> extends true
+    ? false
+    : Required extends StateStore<infer Name, infer _Value>
+      ? Name extends ExactStateStoreName<Provided>
+        ? true
+        : false
+      : Required extends StateFamilyStore<infer Name, infer _Key, infer _Value>
+        ? Name extends ExactStateFamilyStoreName<Provided>
+          ? true
+          : false
+        : [Required] extends [Provided]
+          ? true
+          : false
+
+/**
+ * Remove only services the provider can satisfy by their runtime Context tag.
+ * Named State/StateFamily identifiers intentionally do not collapse into their
+ * structurally broader Store/FamilyStore service APIs.
+ */
+export type ExactServiceExclude<Required, Provided> = Required extends unknown
+  ? ServiceIsProvided<Required, Provided> extends true
+    ? never
+    : Required
+  : never
+
+export type ExactServiceExtract<Required, Provided> = Required extends unknown
+  ? ServiceIsProvided<Required, Provided> extends true
+    ? Required
+    : never
+  : never
+
+export type GraphValidationPassed = object
+
+export type ExactIdentity<Identity> = IsErased<Identity> extends true ? never : Identity
+
+export type InputService<UsesInput extends boolean> = UsesInput extends true ? FeatureInput : never
+
+export type OpenServicesFromFeatureSlotWitnesses<Services> = Services extends {
+  readonly [SlotServiceTypeId]: {
+    readonly binding: FeatureChildSummary<
+      infer _FeatureIdentity,
+      infer _MountProps,
+      infer _CompositionProps,
+      infer _Contract,
+      infer _States,
+      infer _Name,
+      infer _CompositionIdentity,
+      infer OpenServices,
+      infer SupportOpenServices,
+      infer _UsesInput,
+      infer _Input
+    >
+  }
+}
+  ? OpenServices | SupportOpenServices
+  : never
+
+export type DescendantOpenServices<L extends Layer.Layer.Any> =
+  OpenServicesFromFeatureSlotWitnesses<Layer.Layer.Success<L>>
+
+export type ModuleOpenServices<L extends Layer.Layer.Any, UsesInput extends boolean> = Exclude<
+  Layer.Layer.Context<L>,
+  EngineServices | InputService<UsesInput>
+>