@playfast/reform 1.1.1 → 1.2.1

package/src/feature/featureRequirement.ts

@@ -0,0 +1,82 @@
+import { Context } from 'effect'
+import { CompositionIdTypeId } from '../compose/composition'
+import type { OpenServicesFromFeatureSlotWitnesses } from '../graph/closure'
+import type { EngineServices } from '../runtime/loop'
+
+const FeatureInputBase: Context.TagClass<FeatureInput, 'reform/FeatureInput', unknown> =
+  Context.Tag('reform/FeatureInput')<FeatureInput, unknown>()
+export class FeatureInput extends FeatureInputBase {}
+
+// Context.Tag is invariant, so erased requirements use its structural identity carrier.
+export interface FeatureServiceTag<out Identifier = unknown, out Service = unknown> {
+  readonly [Context.TagTypeId]: object
+  readonly Identifier: Identifier
+  readonly Service: Service
+}
+
+export interface StoredFeatureRequirement<out Identifier = unknown, out Service = unknown> {
+  readonly store: FeatureServiceTag<Identifier, Service>
+}
+
+export type RequireCarrier =
+  | StoredFeatureRequirement
+  | {
+      readonly members: ReadonlyArray<StoredFeatureRequirement>
+    }
+
+export type FeatureRequirement = RequireCarrier | FeatureServiceTag
+
+export type TagRequirement<Tag> =
+  Tag extends FeatureServiceTag<infer Identifier, infer _Service> ? Identifier : never
+
+export type StoredRequirementIdentifier<Carrier> = Carrier extends {
+  readonly store: infer Tag
+}
+  ? TagRequirement<Tag>
+  : never
+
+export type RequirementIdentifier<Requirement> = Requirement extends FeatureServiceTag
+  ? TagRequirement<Requirement>
+  : Requirement extends {
+        readonly members: infer Members extends ReadonlyArray<StoredFeatureRequirement>
+      }
+    ? StoredRequirementIdentifier<Members[number]>
+    : StoredRequirementIdentifier<Requirement>
+
+export type ProvidedBy<Requires extends ReadonlyArray<FeatureRequirement>> = RequirementIdentifier<
+  Requires[number]
+>
+
+export type DefaultFeatureOpenServices<ROut, DirectRequires extends ReadonlyArray<FeatureRequirement>> =
+  | ProvidedBy<DirectRequires>
+  | OpenServicesFromFeatureSlotWitnesses<ROut>
+
+export type CompositionNames<ROut> = ROut extends {
+  readonly [CompositionIdTypeId]: {
+    readonly name: infer Name extends string
+  }
+}
+  ? Name
+  : never
+
+export type CompositionIdentities<ROut> = ROut extends {
+  readonly [CompositionIdTypeId]: {
+    readonly identity: infer Identity
+  }
+}
+  ? Identity
+  : never
+
+export type RootCompositionName<ROut> = [CompositionNames<ROut>] extends [never]
+  ? string
+  : CompositionNames<ROut>
+
+export type RootCompositionIdentity<ROut> = [CompositionIdentities<ROut>] extends [never]
+  ? unknown
+  : CompositionIdentities<ROut>
+
+// Feature layers may require the shared engine but must never provide it.
+export type FeatureModuleInput<OpenServices, UsesInput extends boolean> =
+  | EngineServices
+  | OpenServices
+  | (UsesInput extends true ? FeatureInput : never)

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

@@ -0,0 +1,222 @@
+import type { Layer } from 'effect'
+import { CompositionIdTypeId } from '../compose/composition'
+import { SlotServiceTypeId } from '../compose/slot'
+import type { FeatureRequirement, ProvidedBy } from '../feature/feature'
+import type { EngineServices } from '../runtime/loop'
+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
+    ? {
+        readonly featureLayerErrorMustBeNever: 'A feature layer error channel cannot be erased'
+      }
+    : [Layer.Layer.Error<L>] extends [never]
+      ? GraphValidationPassed
+      : {
+          readonly featureLayerErrorMustBeNever: 'A feature layer must have an error channel of exactly never'
+        }
+
+type LayerOutputsAreExact<L extends Layer.Layer.Any> =
+  IsErased<Layer.Layer.Success<L>> extends true
+    ? {
+        readonly featureLayerOutputsMustBeExact: 'A feature layer output cannot be erased'
+      }
+    : GraphValidationPassed
+
+type DescendantOpenServicesAreExact<L extends Layer.Layer.Any> =
+  IsErased<DescendantOpenServices<L>> extends true
+    ? {
+        readonly featureDescendantOpenServicesMustBeExact: "A child feature's open services cannot be erased"
+      }
+    : GraphValidationPassed
+
+type UnexpectedOpenServices<
+  L extends Layer.Layer.Any,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  UsesInput extends boolean,
+> = ExactServiceExclude<
+  Layer.Layer.Context<L>,
+  EngineServices | InputService<UsesInput> | ProvidedBy<DirectRequires> | DescendantOpenServices<L>
+>
+
+type OpenServicesAreDeclared<
+  L extends Layer.Layer.Any,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  UsesInput extends boolean,
+> =
+  IsErased<Layer.Layer.Context<L>> extends true
+    ? {
+        readonly featureLayerContextMustBeExact: 'A feature layer context cannot be erased'
+      }
+    : [UnexpectedOpenServices<L, DirectRequires, UsesInput>] extends [never]
+      ? GraphValidationPassed
+      : {
+          readonly undeclaredFeatureOpenServices: UnexpectedOpenServices<
+            L,
+            DirectRequires,
+            UsesInput
+          >
+        }
+
+type MissingDirectRequirements<
+  L extends Layer.Layer.Any,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+> = ExactServiceExclude<ProvidedBy<DirectRequires>, Layer.Layer.Context<L>>
+
+type DirectRequirementsAreOpen<
+  L extends Layer.Layer.Any,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+> = [MissingDirectRequirements<L, DirectRequires>] extends [never]
+  ? GraphValidationPassed
+  : {
+      readonly unusedDirectFeatureRequirements: MissingDirectRequirements<L, DirectRequires>
+    }
+
+type PrivateEngineOutputs<L extends Layer.Layer.Any> = Extract<
+  Layer.Layer.Success<L>,
+  EngineServices
+>
+
+type EngineOutputsAreShared<L extends Layer.Layer.Any> = [PrivateEngineOutputs<L>] extends [never]
+  ? GraphValidationPassed
+  : {
+      readonly featureCannotProvideEngineServices: PrivateEngineOutputs<L>
+    }
+
+type SelfRequiredOutputs<L extends Layer.Layer.Any> = ExactServiceExtract<
+  Layer.Layer.Context<L>,
+  Layer.Layer.Success<L>
+>
+
+type OutputsAreNotSelfRequired<L extends Layer.Layer.Any> = [SelfRequiredOutputs<L>] extends [never]
+  ? GraphValidationPassed
+  : {
+      readonly featureCannotRequireItsOwnOutputs: SelfRequiredOutputs<L>
+    }
+
+type SlotIdentity<Descriptor> =
+  // Erased descriptors must FAIL validation: `unknown` never matches a bound
+  // identity, so it surfaces in `unboundFeatureSlotIdentities`.
+  IsErased<Descriptor> extends true
+    ? unknown
+    : Descriptor extends ReadonlyArray<infer Entry>
+      ? SlotIdentity<Entry>
+      : Descriptor extends {
+            readonly [SlotServiceTypeId]: {
+              readonly identity: infer Identity
+            }
+          }
+        ? Identity
+        : Descriptor
+
+type RequiredSlotIdentities<Services> = Services extends {
+  readonly [CompositionIdTypeId]: {
+    readonly requiredSlots: infer RequiredSlots
+  }
+}
+  ? SlotIdentity<RequiredSlots>
+  : never
+
+type BoundSlotIdentities<Services> = Services extends {
+  readonly [SlotServiceTypeId]: {
+    readonly identity: infer Identity
+  }
+}
+  ? ExactIdentity<Identity>
+  : never
+
+type MissingSlotBindings<L extends Layer.Layer.Any> = Exclude<
+  RequiredSlotIdentities<Layer.Layer.Success<L>>,
+  BoundSlotIdentities<Layer.Layer.Success<L>>
+>
+
+type RequiredSlotsAreBound<L extends Layer.Layer.Any> = [MissingSlotBindings<L>] extends [never]
+  ? GraphValidationPassed
+  : {
+      readonly unboundFeatureSlotIdentities: MissingSlotBindings<L>
+    }
+
+type PlainChildCompositionIdentities<Services> = Services extends {
+  readonly [SlotServiceTypeId]: {
+    readonly binding: CompositionChildSummary<infer CompositionIdentity>
+  }
+}
+  ? CompositionIdentity
+  : never
+
+type LiveCompositionIdentities<Services> = Services extends {
+  readonly [CompositionIdTypeId]: {
+    readonly identity: infer Identity
+  }
+}
+  ? ExactIdentity<Identity>
+  : never
+
+type MissingPlainChildCompositions<L extends Layer.Layer.Any> = Exclude<
+  PlainChildCompositionIdentities<Layer.Layer.Success<L>>,
+  LiveCompositionIdentities<Layer.Layer.Success<L> | Layer.Layer.Context<L>>
+>
+
+type PlainChildrenAreLive<L extends Layer.Layer.Any> = [MissingPlainChildCompositions<L>] extends [
+  never,
+]
+  ? GraphValidationPassed
+  : {
+      readonly missingPlainChildCompositions: MissingPlainChildCompositions<L>
+    }
+
+export type ValidateFeatureGraphLayer<
+  L extends Layer.Layer.Any,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  UsesInput extends boolean,
+> = LayerErrorIsNever<L> &
+  LayerOutputsAreExact<L> &
+  DescendantOpenServicesAreExact<L> &
+  OpenServicesAreDeclared<L, DirectRequires, UsesInput> &
+  DirectRequirementsAreOpen<L, DirectRequires> &
+  EngineOutputsAreShared<L> &
+  OutputsAreNotSelfRequired<L> &
+  RequiredSlotsAreBound<L> &
+  PlainChildrenAreLive<L>

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>
+>