@playfast/reform 1.2.0 → 1.3.0

package/src/feature/feature.typecheck.ts

@@ -1,4 +1,4 @@
-import { Context, Layer, Schema as S } from 'effect'
+import { Layer, Schema as S } from 'effect'
 import * as Composition from '../compose/composition'
 import { provide } from '../compose/provide'
 import {
@@ -12,61 +12,10 @@ import {
 import { mount } from '../compose/structure'
 import { type Contract, type UiClass, ui } from '../compose/ui'
 import { scene } from '../scene/scene'
-import * as State from '../state/state'
-import * as StateGroup from '../state/stateGroup'
 import { type EngineServices, type FeatureModule, featureModule, lazyImport } from './feature'
 import * as Feature from './feature'
+import { Clock, okService } from './featureModule.typecheck'
 
-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>()
-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>
-
-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)
 
 const AppUiBase: UiClass<{ props: { readonly a: string }; events: {} }, 'AppUi'> = ui('AppUi')<{
   props: { readonly a: string }
@@ -143,9 +92,6 @@ declare const broadRootLayer: Layer.Layer<Composition.CompositionId<string, unkn
 // @ts-expect-error a broad composition identifier does not prove the exact scene root
 const broadRootScene = scene(AppComp, { provide: [broadRootLayer] })
 
-declare const privateEngine: Layer.Layer<EngineServices, never, EngineServices>
-// @ts-expect-error a Feature module cannot provide its own Engine services
-const invalidPrivateEngine = featureModule([], privateEngine)
 
 const wired = provide(AppFeatureSlot, AppFeature)
 
@@ -297,10 +243,6 @@ void featureTypeProofs
 void appNative
 void otherNative
 void AppFeatureTwin
-void okState
-void okGroup
-void badEmpty
-void badService
 void EmptyAppFeature
 void ExactUnionAppFeature
 void UnknownRootAppFeature
@@ -308,6 +250,5 @@ void BroadRootAppFeature
 void exactUnionScene
 void unknownRootScene
 void broadRootScene
-void invalidPrivateEngine
 
 export {}

package/src/feature/featureBinding.ts

@@ -0,0 +1,158 @@
+import type { Effect, Option } from 'effect'
+import type { AnyComposition, CompositionClass } from '../compose/composition'
+import type { Manifest } from '../definition/definition'
+import {
+  type AnyFeatureGraphSummary,
+  FeatureGraphValidTypeId,
+  type FeatureSummaryCompositionIdentity,
+  type FeatureSummaryCompositionProps,
+  type FeatureSummaryContract,
+  type FeatureSummaryInput,
+  type FeatureSummaryName,
+  type FeatureSummaryOpenServices,
+  type FeatureSummaryStates,
+  type FeatureSummarySupportOpenServices,
+  type FeatureSummaryUsesInput,
+} from '../graph/closure'
+import type { FeatureLoadFailed } from '../internal/errors'
+import type { Tagged } from '../runtime/bus'
+import type { LoadedModule } from './featureModule'
+import type { FeatureRequirement } from './featureRequirement'
+
+export interface FailedProps {
+  readonly error: FeatureLoadFailed
+  readonly retry: () => void
+}
+
+export interface FeatureManifest extends Manifest {
+  readonly kind: 'Feature'
+  readonly name: string
+  readonly strategy: 'lazy' | 'default'
+  readonly composition: Manifest & { readonly kind: 'Composition' }
+  readonly placeholder: Option.Option<{
+    readonly loading: Manifest & { readonly kind: 'Composition' }
+    readonly failed: Manifest & { readonly kind: 'Composition' }
+  }>
+}
+
+export const FeatureBindingTypeId: unique symbol = Symbol.for('reform/FeatureBinding')
+export type FeatureBindingTypeId = typeof FeatureBindingTypeId
+export type FeatureBindingType = FeatureBindingTypeId
+
+export const FeatureTokenIdentityTypeId: unique symbol = Symbol('reform/FeatureTokenIdentity')
+export const FeatureNativeTypeId: unique symbol = Symbol('reform/FeatureNative')
+
+export interface FeatureIdentityToken<out FeatureIdentity> {
+  readonly identity: symbol
+  readonly [FeatureTokenIdentityTypeId]: readonly [] | readonly [FeatureIdentity]
+}
+
+export interface FeatureToken<
+  out FeatureIdentity,
+  out NativeTree extends object,
+> extends FeatureIdentityToken<FeatureIdentity> {
+  readonly [FeatureNativeTypeId]: NativeTree
+}
+
+export interface FeatureTreeCarrier {
+  readonly token: FeatureToken<unknown, object>
+}
+
+type Native<
+  Feature extends FeatureTreeCarrier,
+  Token extends Feature['token'] = Feature['token'],
+> = Token[typeof FeatureNativeTypeId]
+
+export const tree = <
+  Feature extends FeatureTreeCarrier,
+  Token extends Feature['token'] = Feature['token'],
+>(
+  token: Token,
+): Native<Feature, Token> => token[FeatureNativeTypeId]
+
+export interface ProvideableFeature<
+  out FeatureIdentity,
+  out Summary extends AnyFeatureGraphSummary,
+> {
+  new (): {}
+  readonly manifest: FeatureManifest
+  readonly token: FeatureIdentityToken<FeatureIdentity>
+  readonly summary: Summary
+}
+
+export interface FeatureDefinition<
+  out FeatureIdentity,
+  out Summary extends AnyFeatureGraphSummary,
+  out NativeTree extends object,
+> extends ProvideableFeature<FeatureIdentity, Summary> {
+  readonly token: FeatureToken<FeatureIdentity, NativeTree>
+}
+
+export type FeatureOpenServices<Feature extends { readonly summary: AnyFeatureGraphSummary }> =
+  FeatureSummaryOpenServices<Feature['summary']>
+
+export type FeatureSupportOpenServices<
+  Feature extends { readonly summary: AnyFeatureGraphSummary },
+> = FeatureSummarySupportOpenServices<Feature['summary']>
+
+export interface AnyFeatureBindingExternalApi {
+  readonly [FeatureBindingTypeId]: FeatureBindingTypeId
+  readonly [FeatureGraphValidTypeId]: FeatureGraphValidTypeId
+  readonly capture: <Result>(visit: FeatureBindingCapture<Result>) => Result
+}
+
+export type AnyFeatureBinding = AnyFeatureBindingExternalApi
+
+export interface FeatureBinding<
+  Summary extends AnyFeatureGraphSummary,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+> extends AnyFeatureBindingExternalApi {
+  readonly manifest: FeatureManifest
+  readonly identity: symbol
+  readonly summary: Summary
+  readonly composition: CompositionClass<
+    FeatureSummaryCompositionProps<Summary>,
+    FeatureSummaryContract<Summary>,
+    FeatureSummaryStates<Summary>,
+    FeatureSummaryName<Summary>,
+    FeatureSummaryCompositionIdentity<Summary>
+  >
+  readonly strategy: 'lazy' | 'default'
+  readonly load: Effect.Effect<
+    LoadedModule<
+      ROut,
+      DirectRequires,
+      FeatureSummaryOpenServices<Summary>,
+      FeatureSummaryUsesInput<Summary>,
+      FeatureSummaryInput<Summary>
+    >,
+    FeatureLoadFailed
+  >
+  readonly placeholder: Option.Option<{
+    readonly loading: AnyComposition
+    readonly failed: AnyComposition
+  }>
+  readonly parseInput: (input: unknown) => Option.Option<unknown>
+  readonly boot: ReadonlyArray<Tagged>
+}
+
+export type CapturedFeatureBinding<
+  Summary extends AnyFeatureGraphSummary,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+> = FeatureBinding<Summary, ROut, DirectRequires>
+
+export type FeatureBindingCapture<Result> = <
+  Summary extends AnyFeatureGraphSummary,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+>(
+  binding: FeatureBinding<Summary, ROut, DirectRequires>,
+) => Result
+
+export const isFeatureBinding = (candidate: unknown): candidate is AnyFeatureBinding =>
+  typeof candidate === 'object' &&
+  candidate !== null &&
+  FeatureBindingTypeId in candidate &&
+  FeatureGraphValidTypeId in candidate

package/src/feature/featureClass.ts

@@ -0,0 +1,162 @@
+import type { CompositionClass } from '../compose/composition'
+import type { UiContract } from '../compose/ui'
+import type { FeatureDefinition } from './featureBinding'
+import type {
+  EagerFeatureNativeTree,
+  FeatureNativeTree,
+  FeatureSummaryOf,
+  LazyFeatureNativeTree,
+} from './featureNativeTree'
+import type {
+  DefaultFeatureOpenServices,
+  FeatureRequirement,
+  RootCompositionIdentity,
+  RootCompositionName,
+} from './featureRequirement'
+
+export interface FeatureClass<
+  FeatureIdentity,
+  P,
+  C extends UiContract,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices = DefaultFeatureOpenServices<ROut, DirectRequires>,
+  SupportOut = never,
+  SupportDirectRequires extends ReadonlyArray<FeatureRequirement> = readonly [],
+  SupportOpenServices = DefaultFeatureOpenServices<SupportOut, SupportDirectRequires>,
+  UsesInput extends boolean = false,
+  Input = UsesInput extends true ? P : never,
+  S extends ReadonlyArray<unknown> = ReadonlyArray<unknown>,
+  N extends string = RootCompositionName<ROut>,
+  CompositionProps = P,
+  Identity = RootCompositionIdentity<ROut>,
+  Composition extends CompositionClass<CompositionProps, C, S, N, Identity> = CompositionClass<
+    CompositionProps,
+    C,
+    S,
+    N,
+    Identity
+  >,
+> extends FeatureDefinition<
+  FeatureIdentity,
+  FeatureSummaryOf<
+    FeatureIdentity,
+    P,
+    CompositionProps,
+    C,
+    S,
+    N,
+    Identity,
+    OpenServices,
+    SupportOpenServices,
+    UsesInput,
+    Input
+  >,
+  FeatureNativeTree<
+    FeatureSummaryOf<
+      FeatureIdentity,
+      P,
+      CompositionProps,
+      C,
+      S,
+      N,
+      Identity,
+      OpenServices,
+      SupportOpenServices,
+      UsesInput,
+      Input
+    >,
+    ROut,
+    DirectRequires,
+    SupportOut,
+    SupportDirectRequires,
+    Composition
+  >
+> {}
+
+export type EagerFeatureClass<
+  FeatureIdentity,
+  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> = CompositionClass<
+    P,
+    C,
+    S,
+    N,
+    Identity
+  >,
+> = FeatureDefinition<
+  FeatureIdentity,
+  FeatureSummaryOf<FeatureIdentity, P, P, C, S, N, Identity, OpenServices, never, false, never>,
+  EagerFeatureNativeTree<
+    FeatureSummaryOf<FeatureIdentity, P, P, C, S, N, Identity, OpenServices, never, false, never>,
+    ROut,
+    DirectRequires,
+    Composition
+  >
+>
+
+export type LazyFeatureClass<
+  FeatureIdentity,
+  P,
+  C extends UiContract,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices,
+  SupportOut,
+  SupportDirectRequires extends ReadonlyArray<FeatureRequirement>,
+  SupportOpenServices,
+  UsesInput extends boolean,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  CompositionProps,
+  Identity,
+  Composition extends CompositionClass<CompositionProps, C, S, N, Identity> = CompositionClass<
+    CompositionProps,
+    C,
+    S,
+    N,
+    Identity
+  >,
+> = FeatureDefinition<
+  FeatureIdentity,
+  FeatureSummaryOf<
+    FeatureIdentity,
+    P,
+    CompositionProps,
+    C,
+    S,
+    N,
+    Identity,
+    OpenServices,
+    SupportOpenServices,
+    UsesInput,
+    UsesInput extends true ? P : never
+  >,
+  LazyFeatureNativeTree<
+    FeatureSummaryOf<
+      FeatureIdentity,
+      P,
+      CompositionProps,
+      C,
+      S,
+      N,
+      Identity,
+      OpenServices,
+      SupportOpenServices,
+      UsesInput,
+      UsesInput extends true ? P : never
+    >,
+    ROut,
+    DirectRequires,
+    SupportOut,
+    SupportDirectRequires,
+    Composition
+  >
+>

package/src/feature/featureConfig.ts

@@ -0,0 +1,192 @@
+import type { Effect } from 'effect'
+import { Schema } from 'effect'
+import type {
+  AnyComposition,
+  CompositionClass,
+  CompositionPropsReceiver,
+  HasExactCompositionId,
+} from '../compose/composition'
+import type { UiContract } from '../compose/ui'
+import type { AnyFeatureGraphSummary } from '../graph/closure'
+import type { FeatureLoadFailed } from '../internal/errors'
+import type { Tagged } from '../runtime/bus'
+import {
+  type AnyFeatureBinding,
+  type FailedProps,
+  type FeatureManifest,
+  FeatureNativeTypeId,
+  type FeatureToken,
+} from './featureBinding'
+import type { AnyLoadedModule, FeatureModule } from './featureModule'
+import type { FeatureRequirement } from './featureRequirement'
+
+export interface RuntimeFeatureTree {
+  readonly composition: AnyComposition
+  readonly load: Effect.Effect<AnyLoadedModule, FeatureLoadFailed>
+  readonly binding: AnyFeatureBinding
+  readonly eagerModule: AnyLoadedModule | undefined
+  readonly supportModule: AnyLoadedModule | undefined
+}
+
+export interface RuntimeFeature {
+  new (): {}
+  readonly manifest: FeatureManifest
+  readonly token: FeatureToken<unknown, RuntimeFeatureTree>
+  readonly summary: AnyFeatureGraphSummary
+}
+
+const isRuntimeFeatureToken = (
+  candidate: unknown,
+): candidate is FeatureToken<unknown, RuntimeFeatureTree> =>
+  typeof candidate === 'object' && candidate !== null && FeatureNativeTypeId in candidate
+
+export const isFeature = (candidate: unknown): candidate is RuntimeFeature =>
+  (typeof candidate === 'function' || typeof candidate === 'object') &&
+  candidate !== null &&
+  'token' in candidate &&
+  isRuntimeFeatureToken(candidate.token)
+
+export type PlaceholderComposition<P> = AnyComposition & CompositionPropsReceiver<P>
+
+export interface Placeholders<P> {
+  readonly loading: PlaceholderComposition<P>
+  readonly failed: PlaceholderComposition<FailedProps>
+}
+
+export type FeatureMountProps<
+  UsesInput extends boolean,
+  CompositionProps,
+  InputSchema extends Schema.Schema.AnyNoContext,
+> = UsesInput extends true ? Schema.Schema.Type<InputSchema> : CompositionProps
+
+export type FeatureUsesInput<InputSchema extends Schema.Schema.AnyNoContext> = [InputSchema] extends [
+  never,
+]
+  ? false
+  : true
+
+export type FeatureInputValue<InputSchema extends Schema.Schema.AnyNoContext> = [InputSchema] extends [
+  never,
+]
+  ? never
+  : Schema.Schema.Type<InputSchema>
+
+export interface FeatureConfigBaseExternalApi<
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+> {
+  readonly composition: CompositionClass<P, C, S, N, Identity>
+  readonly boot?: ReadonlyArray<Tagged>
+}
+
+export interface ExactFeatureCompositionConfig<Composition extends AnyComposition> {
+  readonly composition: Composition
+}
+
+export type IncludesComposition<ROut, N extends string, Identity> =
+  HasExactCompositionId<ROut, N, Identity> extends true
+    ? object
+    : {
+        readonly missingCompositionService: 'The feature module must provide its root composition'
+      }
+
+export type EagerFeatureConfigExternalApi<
+  P,
+  C extends UiContract,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+> = FeatureConfigBaseExternalApi<P, C, S, N, Identity> & {
+  readonly loadingStrategy?: 'default'
+  readonly module: FeatureModule<ROut, DirectRequires, OpenServices, false, never> &
+    IncludesComposition<ROut, N, Identity>
+}
+
+export type LazyFeatureConfigExternalApi<
+  CompositionProps,
+  C extends UiContract,
+  ROut,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices,
+  SupportOut,
+  SupportDirectRequires extends ReadonlyArray<FeatureRequirement>,
+  SupportOpenServices,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  InputSchema extends Schema.Schema.AnyNoContext,
+  Loading extends AnyComposition,
+  Failed extends AnyComposition,
+> = FeatureConfigBaseExternalApi<CompositionProps, C, S, N, Identity> & {
+  readonly composition: CompositionClass<CompositionProps, C, S, N, Identity> &
+    CompositionPropsReceiver<
+      NoInfer<FeatureMountProps<FeatureUsesInput<InputSchema>, CompositionProps, InputSchema>>
+    >
+  readonly loadingStrategy: 'lazy'
+  readonly input?: InputSchema
+  readonly load: Effect.Effect<
+    FeatureModule<
+      ROut,
+      DirectRequires,
+      OpenServices,
+      FeatureUsesInput<InputSchema>,
+      FeatureInputValue<InputSchema>
+    > &
+      IncludesComposition<ROut, N, Identity>,
+    FeatureLoadFailed
+  >
+  readonly placeholder: {
+    readonly loading: Loading &
+      CompositionPropsReceiver<
+        NoInfer<FeatureMountProps<FeatureUsesInput<InputSchema>, CompositionProps, InputSchema>>
+      >
+    readonly failed: Failed & CompositionPropsReceiver<FailedProps>
+  }
+  readonly eager?: FeatureModule<
+    SupportOut,
+    SupportDirectRequires,
+    SupportOpenServices,
+    false,
+    never
+  >
+} & (FeatureUsesInput<InputSchema> extends true ? { readonly input: InputSchema } : object)
+
+export type MakeImplementationConfigExternalApi =
+  | {
+      readonly composition: AnyComposition
+      readonly boot?: ReadonlyArray<Tagged>
+      readonly loadingStrategy?: 'default'
+      readonly module: AnyLoadedModule
+    }
+  | {
+      readonly composition: AnyComposition
+      readonly boot?: ReadonlyArray<Tagged>
+      readonly loadingStrategy: 'lazy'
+      readonly input?: Schema.Schema.Any
+      readonly load: Effect.Effect<AnyLoadedModule, FeatureLoadFailed>
+      readonly placeholder: {
+        readonly loading: AnyComposition
+        readonly failed: AnyComposition
+      }
+      readonly eager?: AnyLoadedModule
+    }
+
+export const isMakeImplementationConfig = (
+  candidate: unknown,
+): candidate is MakeImplementationConfigExternalApi =>
+  typeof candidate === 'object' &&
+  candidate !== null &&
+  'composition' in candidate &&
+  (!('input' in candidate) || Schema.isSchema(candidate.input)) &&
+  ('module' in candidate || ('load' in candidate && 'placeholder' in candidate))
+
+export type RuntimePlaceholders = {
+  readonly loading: AnyComposition
+  readonly failed: AnyComposition
+}