@playfast/reform 1.2.0 → 1.3.0

package/src/feature/featureFactory.ts

@@ -0,0 +1,163 @@
+import { type Effect, Option, Schema } from 'effect'
+import type { AnyComposition, CompositionClass } from '../compose/composition'
+import type { UiContract } from '../compose/ui'
+import {
+  type AnyFeatureGraphSummary,
+  FeatureChildSummaryTypeId,
+  FeatureGraphSummaryTypeId,
+  FeatureGraphValidTypeId,
+  FeatureModuleGraphValidTypeId,
+  type FeatureSummaryCompositionIdentity,
+  type FeatureSummaryCompositionProps,
+  type FeatureSummaryContract,
+  type FeatureSummaryInput,
+  type FeatureSummaryName,
+  type FeatureSummaryOpenServices,
+  type FeatureSummaryStates,
+  type FeatureSummaryUsesInput,
+  SlotBindingSummaryTypeId,
+} from '../graph/closure'
+import type { FeatureLoadFailed } from '../internal/errors'
+import type { Tagged } from '../runtime/bus'
+import {
+  type FeatureBinding,
+  type FeatureBindingCapture,
+  FeatureBindingTypeId,
+  type FeatureManifest,
+} from './featureBinding'
+import type { RuntimePlaceholders } from './featureConfig'
+import type { LoadedModule } from './featureModule'
+import type { FeatureSummaryOf } from './featureNativeTree'
+import type { FeatureRequirement } from './featureRequirement'
+
+export const makeFeatureManifest = (
+  name: string,
+  strategy: 'lazy' | 'default',
+  composition: AnyComposition,
+  placeholder: Option.Option<RuntimePlaceholders>,
+): FeatureManifest => ({
+  kind: 'Feature',
+  name,
+  strategy,
+  composition: composition.manifest,
+  placeholder: Option.map(placeholder, (placeholders) => ({
+    loading: placeholders.loading.manifest,
+    failed: placeholders.failed.manifest,
+  })),
+})
+
+const makeFeatureInputParser =
+  (
+    composition: AnyComposition,
+    inputSchema: Schema.Schema.AnyNoContext | undefined,
+    placeholder: Option.Option<RuntimePlaceholders>,
+  ): ((input: unknown) => Option.Option<unknown>) =>
+  (input) =>
+    Option.flatMap(
+      Option.match(Option.fromNullable(inputSchema), {
+        onNone: () => Option.some(input),
+        onSome: (schema) => Schema.validateOption(schema)(input),
+      }),
+      (decoded) =>
+        Option.flatMap(composition.parseProps(decoded), () =>
+          Option.match(placeholder, {
+            onNone: () => Option.some(decoded),
+            onSome: (placeholders) =>
+              Option.map(placeholders.loading.parseProps(decoded), () => decoded),
+          }),
+        ),
+    )
+
+export const makeFeatureSummary = <
+  FeatureIdentity,
+  MountProps,
+  CompositionProps,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  OpenServices,
+  SupportOpenServices,
+  UsesInput extends boolean,
+  Input,
+>(
+  composition: CompositionClass<CompositionProps, C, S, N, Identity>,
+): FeatureSummaryOf<
+  FeatureIdentity,
+  MountProps,
+  CompositionProps,
+  C,
+  S,
+  N,
+  Identity,
+  OpenServices,
+  SupportOpenServices,
+  UsesInput,
+  Input
+> => ({
+  [SlotBindingSummaryTypeId]: SlotBindingSummaryTypeId,
+  [FeatureChildSummaryTypeId]: {
+    featureIdentity: [],
+    compositionIdentity: [],
+  },
+  [FeatureGraphSummaryTypeId]: {
+    featureIdentity: [],
+    mountProps: [],
+    compositionProps: [],
+    contract: [],
+    states: [],
+    name: composition.manifest.name,
+    compositionIdentity: [],
+    openServices: [],
+    supportOpenServices: [],
+    usesInput: [],
+    input: [],
+    validated: FeatureModuleGraphValidTypeId,
+  },
+})
+
+export const makeFeatureBinding = <
+  Summary extends AnyFeatureGraphSummary,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+>(
+  identity: symbol,
+  manifest: FeatureManifest,
+  summary: Summary,
+  composition: CompositionClass<
+    FeatureSummaryCompositionProps<Summary>,
+    FeatureSummaryContract<Summary>,
+    FeatureSummaryStates<Summary>,
+    FeatureSummaryName<Summary>,
+    FeatureSummaryCompositionIdentity<Summary>
+  >,
+  load: Effect.Effect<
+    LoadedModule<
+      ROut,
+      DirectRequires,
+      FeatureSummaryOpenServices<Summary>,
+      FeatureSummaryUsesInput<Summary>,
+      FeatureSummaryInput<Summary>
+    >,
+    FeatureLoadFailed
+  >,
+  placeholder: Option.Option<RuntimePlaceholders>,
+  inputSchema: Schema.Schema.AnyNoContext | undefined,
+  boot: ReadonlyArray<Tagged>,
+): FeatureBinding<Summary, ROut, DirectRequires> => {
+  const binding: FeatureBinding<Summary, ROut, DirectRequires> = {
+    [FeatureBindingTypeId]: FeatureBindingTypeId,
+    [FeatureGraphValidTypeId]: FeatureGraphValidTypeId,
+    manifest,
+    identity,
+    summary,
+    composition,
+    strategy: manifest.strategy,
+    load,
+    placeholder,
+    parseInput: makeFeatureInputParser(composition, inputSchema, placeholder),
+    boot,
+    capture: <Result>(visit: FeatureBindingCapture<Result>): Result => visit(binding),
+  }
+  return binding
+}

package/src/feature/featureModule.ts

@@ -0,0 +1,136 @@
+import { Effect, type Layer, type Schema } from 'effect'
+import {
+  FeatureModuleGraphValidTypeId,
+  type ModuleOpenServices,
+  type ValidateFeatureGraphLayer,
+} from '../graph/closure'
+import { FeatureLoadFailed } from '../internal/errors'
+import type {
+  DefaultFeatureOpenServices,
+  FeatureModuleInput,
+  FeatureRequirement,
+} from './featureRequirement'
+
+export interface FeatureModule<
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices = DefaultFeatureOpenServices<ROut, DirectRequires>,
+  UsesInput extends boolean = false,
+  Input = never,
+> extends AnyLoadedModule {
+  readonly [FeatureModuleGraphValidTypeId]: FeatureModuleGraphValidTypeId
+  readonly requires: DirectRequires
+  readonly usesInput: UsesInput
+  readonly layer: Layer.Layer<ROut, never, FeatureModuleInput<OpenServices, UsesInput>>
+  readonly inputSchema: UsesInput extends true ? Schema.Schema.AnyNoContext : undefined
+  readonly Input: (input: Input) => void
+}
+
+export type LoadedModuleCapture<Result> = <
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices,
+  UsesInput extends boolean,
+  Input,
+>(
+  module: LoadedModule<ROut, DirectRequires, OpenServices, UsesInput, Input>,
+) => Result
+
+export interface AnyLoadedModule {
+  readonly capture: <Result>(visit: LoadedModuleCapture<Result>) => Result
+}
+
+export type FeatureLayerOutput<L extends Layer.Layer.Any> = Layer.Layer.Success<L>
+
+// Reject erased contexts before graph validation can mistake them for permissive inputs.
+export type ExactFeatureLayer<L extends Layer.Layer.Any, UsesInput extends boolean> = Layer.Layer<
+  FeatureLayerOutput<L>,
+  never,
+  FeatureModuleInput<ModuleOpenServices<L, UsesInput>, UsesInput>
+> &
+  (unknown extends Layer.Layer.Context<L>
+    ? {
+        readonly featureLayerContextMustBeExact: 'A feature layer context cannot be erased'
+      }
+    : object)
+
+export const featureModule = <
+  const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  L extends Layer.Layer.Any,
+>(
+  requires: DirectRequires,
+  layer: L & ExactFeatureLayer<L, false> & ValidateFeatureGraphLayer<L, DirectRequires, false>,
+): FeatureModule<
+  FeatureLayerOutput<L>,
+  DirectRequires,
+  ModuleOpenServices<L, false>,
+  false,
+  never
+> => {
+  const module: FeatureModule<
+    FeatureLayerOutput<L>,
+    DirectRequires,
+    ModuleOpenServices<L, false>,
+    false,
+    never
+  > = {
+    [FeatureModuleGraphValidTypeId]: FeatureModuleGraphValidTypeId,
+    requires,
+    usesInput: false,
+    layer,
+    inputSchema: undefined,
+    Input: () => undefined,
+    capture: <Result>(visit: LoadedModuleCapture<Result>): Result => visit(module),
+  }
+  return module
+}
+
+export const featureModuleFromInput = <
+  const InputSchema extends Schema.Schema.AnyNoContext,
+  const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  L extends Layer.Layer.Any,
+>(
+  input: InputSchema,
+  requires: DirectRequires,
+  layer: L & ExactFeatureLayer<L, true> & ValidateFeatureGraphLayer<L, DirectRequires, true>,
+): FeatureModule<
+  FeatureLayerOutput<L>,
+  DirectRequires,
+  ModuleOpenServices<L, true>,
+  true,
+  Schema.Schema.Type<InputSchema>
+> => {
+  const module: FeatureModule<
+    FeatureLayerOutput<L>,
+    DirectRequires,
+    ModuleOpenServices<L, true>,
+    true,
+    Schema.Schema.Type<InputSchema>
+  > = {
+    [FeatureModuleGraphValidTypeId]: FeatureModuleGraphValidTypeId,
+    requires,
+    usesInput: true,
+    layer,
+    inputSchema: input,
+    Input: () => undefined,
+    capture: <Result>(visit: LoadedModuleCapture<Result>): Result => visit(module),
+  }
+  return module
+}
+
+// Seal dynamic imports as typed Effects so chunk failures become 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 LoadedModule<
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices = DefaultFeatureOpenServices<ROut, DirectRequires>,
+  UsesInput extends boolean = false,
+  Input = never,
+> extends FeatureModule<ROut, DirectRequires, OpenServices, UsesInput, Input> {}

package/src/feature/featureModule.typecheck.ts

@@ -0,0 +1,63 @@
+import { Context, Layer, Schema as S } from 'effect'
+import * as State from '../state/state'
+import * as StateGroup from '../state/stateGroup'
+import { type EngineServices, type FeatureModule, featureModule } from './feature'
+
+const FeedStateBase: State.StateClass<'feed', string> = State.make('feed', S.String)
+class FeedState extends FeedStateBase {}
+const FilterStateBase: State.StateClass<'filter', string> = State.make('filter', S.String)
+class FilterState extends FilterStateBase {}
+const TodosStatesBase: StateGroup.StateGroupClass<readonly [typeof FeedState, typeof FilterState]> =
+  StateGroup.make(FeedState, FilterState)
+class TodosStates extends TodosStatesBase {}
+
+interface ClockService {
+  readonly now: () => number
+}
+const ClockBase: Context.TagClass<Clock, 'feature.typecheck.Clock', ClockService> = Context.Tag(
+  'feature.typecheck.Clock',
+)<Clock, ClockService>()
+export class Clock extends ClockBase {}
+
+declare const readsFeed: Layer.Layer<
+  { readonly _out: true },
+  never,
+  State.StateStore<'feed', string> | EngineServices
+>
+
+declare const readsTodos: Layer.Layer<
+  { readonly _out: true },
+  never,
+  State.StateStore<'feed', string> | State.StateStore<'filter', string> | EngineServices
+>
+
+const okState: FeatureModule<{ readonly _out: true }, readonly [typeof FeedState]> = featureModule(
+  [FeedState],
+  readsFeed,
+)
+
+const okGroup: FeatureModule<{ readonly _out: true }, readonly [typeof TodosStates]> =
+  featureModule([TodosStates], readsTodos)
+
+const badEmpty =
+  // @ts-expect-error feature layer reads a store it does not declare in `requires`
+  featureModule([], readsFeed)
+
+declare const readsClock: Layer.Layer<{ readonly _clock: true }, never, Clock | EngineServices>
+
+export const okService: FeatureModule<{ readonly _clock: true }, readonly [typeof Clock]> =
+  featureModule([Clock], readsClock)
+
+const badService =
+  // @ts-expect-error feature layer reads an ordinary Context service it did not declare
+  featureModule([], readsClock)
+
+declare const privateEngine: Layer.Layer<EngineServices, never, EngineServices>
+// @ts-expect-error a Feature module cannot provide its own Engine services
+const invalidPrivateEngine = featureModule([], privateEngine)
+
+void okState
+void okGroup
+void badEmpty
+void badService
+void invalidPrivateEngine

package/src/feature/featureNativeTree.ts

@@ -0,0 +1,152 @@
+import type { Effect } from 'effect'
+import type { CompositionClass } from '../compose/composition'
+import type { UiContract } from '../compose/ui'
+import type {
+  AnyFeatureGraphSummary,
+  FeatureGraphSummary,
+  FeatureSummaryCompositionIdentity,
+  FeatureSummaryCompositionProps,
+  FeatureSummaryContract,
+  FeatureSummaryInput,
+  FeatureSummaryName,
+  FeatureSummaryOpenServices,
+  FeatureSummaryStates,
+  FeatureSummarySupportOpenServices,
+  FeatureSummaryUsesInput,
+} from '../graph/closure'
+import type { FeatureLoadFailed } from '../internal/errors'
+import type { CapturedFeatureBinding } from './featureBinding'
+import type { FeatureModule } from './featureModule'
+import type { FeatureRequirement } from './featureRequirement'
+
+export interface FeatureNativeTree<
+  Summary extends AnyFeatureGraphSummary,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  SupportOut,
+  SupportDirectRequires extends ReadonlyArray<FeatureRequirement>,
+  Composition extends CompositionClass<
+    FeatureSummaryCompositionProps<Summary>,
+    FeatureSummaryContract<Summary>,
+    FeatureSummaryStates<Summary>,
+    FeatureSummaryName<Summary>,
+    FeatureSummaryCompositionIdentity<Summary>
+  > = CompositionClass<
+    FeatureSummaryCompositionProps<Summary>,
+    FeatureSummaryContract<Summary>,
+    FeatureSummaryStates<Summary>,
+    FeatureSummaryName<Summary>,
+    FeatureSummaryCompositionIdentity<Summary>
+  >,
+> {
+  readonly identity: symbol
+  readonly summary: Summary
+  readonly composition: Composition
+  readonly load: Effect.Effect<
+    FeatureModule<
+      ROut,
+      DirectRequires,
+      FeatureSummaryOpenServices<Summary>,
+      FeatureSummaryUsesInput<Summary>,
+      FeatureSummaryInput<Summary>
+    >,
+    FeatureLoadFailed
+  >
+  readonly binding: CapturedFeatureBinding<Summary, ROut, DirectRequires>
+  readonly eagerModule:
+    | FeatureModule<ROut, DirectRequires, FeatureSummaryOpenServices<Summary>, false, never>
+    | undefined
+  readonly supportModule:
+    | FeatureModule<
+        SupportOut,
+        SupportDirectRequires,
+        FeatureSummarySupportOpenServices<Summary>,
+        false,
+        never
+      >
+    | undefined
+}
+
+export interface EagerFeatureNativeTree<
+  Summary extends AnyFeatureGraphSummary,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  Composition extends CompositionClass<
+    FeatureSummaryCompositionProps<Summary>,
+    FeatureSummaryContract<Summary>,
+    FeatureSummaryStates<Summary>,
+    FeatureSummaryName<Summary>,
+    FeatureSummaryCompositionIdentity<Summary>
+  > = CompositionClass<
+    FeatureSummaryCompositionProps<Summary>,
+    FeatureSummaryContract<Summary>,
+    FeatureSummaryStates<Summary>,
+    FeatureSummaryName<Summary>,
+    FeatureSummaryCompositionIdentity<Summary>
+  >,
+> extends FeatureNativeTree<Summary, ROut, DirectRequires, never, readonly [], Composition> {
+  readonly eagerModule: FeatureModule<
+    ROut,
+    DirectRequires,
+    FeatureSummaryOpenServices<Summary>,
+    false,
+    never
+  >
+  readonly supportModule: undefined
+}
+
+export interface LazyFeatureNativeTree<
+  Summary extends AnyFeatureGraphSummary,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  SupportOut,
+  SupportDirectRequires extends ReadonlyArray<FeatureRequirement>,
+  Composition extends CompositionClass<
+    FeatureSummaryCompositionProps<Summary>,
+    FeatureSummaryContract<Summary>,
+    FeatureSummaryStates<Summary>,
+    FeatureSummaryName<Summary>,
+    FeatureSummaryCompositionIdentity<Summary>
+  > = CompositionClass<
+    FeatureSummaryCompositionProps<Summary>,
+    FeatureSummaryContract<Summary>,
+    FeatureSummaryStates<Summary>,
+    FeatureSummaryName<Summary>,
+    FeatureSummaryCompositionIdentity<Summary>
+  >,
+> extends FeatureNativeTree<
+  Summary,
+  ROut,
+  DirectRequires,
+  SupportOut,
+  SupportDirectRequires,
+  Composition
+> {
+  readonly eagerModule: undefined
+}
+
+export type FeatureSummaryOf<
+  FeatureIdentity,
+  MountProps,
+  CompositionProps,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  OpenServices,
+  SupportOpenServices,
+  UsesInput extends boolean,
+  Input,
+> = FeatureGraphSummary<
+  FeatureIdentity,
+  MountProps,
+  CompositionProps,
+  C,
+  S,
+  N,
+  Identity,
+  OpenServices,
+  SupportOpenServices,
+  UsesInput,
+  Input
+>

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)