@typeonce/ritmo 0.6.0 → 0.7.0

package/src/Feature.ts

@@ -1,241 +0,0 @@
-/**
- * Pre-bind features: reusable slices that contribute a schema fragment and the
- * schedules that operate on it.
- *
- * A feature builds its schedules only after the final merged schema is bound,
- * and its builder can only reach descriptors from its own fragment and from
- * the features it `requires`.
- *
- * @module Feature
- * @docGroup core
- *
- * @example
- * ```ts
- * const Combat = Schema.Feature.define("Combat", {
- *   schema: CombatSchema,
- *   requires: [Core],
- *   build: (Game) => ({ update: [Game.Schedule(Attack, Game.Schedule.applyDeferred())] })
- * })
- *
- * const project = Schema.Feature.compose({ root: Root, features: [Core, Combat] })
- * const runtime = project.Game.Runtime.make({ services: project.Game.Runtime.services() })
- * runtime.tick(...project.schedules.update)
- * ```
- */
-import { buildSchema } from "./internal/fragments.ts"
-import { makeGame } from "./internal/game.ts"
-import type * as Schedule from "./Schedule.ts"
-import type { MergeSchemaDefinitions, Schema, SchemaDefinition, ValidateFragments } from "./Schema.ts"
-
-type EmptySchema = SchemaDefinition<{}, {}, {}, {}>
-
-type AnyFeature = {
-  readonly kind: "feature"
-  readonly name: string
-  readonly schema: Schema.Any
-  readonly requires: ReadonlyArray<AnyFeature>
-  readonly build: unknown
-  readonly output: FeatureBuildOutput
-}
-
-type AnySchedule = Schedule.ScheduleDefinition<any, any, any, any, any>
-
-/**
- * What a feature builder returns: bootstrap and update schedules, plus any
- * other values the feature wants to expose on the composed project.
- */
-export type FeatureBuildOutput = {
-  readonly bootstrap?: ReadonlyArray<AnySchedule>
-  readonly update?: ReadonlyArray<AnySchedule>
-}
-
-/**
- * The bound authoring surface a feature builder receives. It is the normal
- * `Game` API restricted to the descriptors the feature can see; runtimes are
- * built from the composed project instead.
- */
-export type FeatureBuildGame<Accessible extends Schema.Any, Root = unknown> =
-  Omit<Schema.Game<Accessible, Root>, "Runtime">
-
-type FeatureBuildFunction<
-  Accessible extends Schema.Any,
-  Output extends FeatureBuildOutput = FeatureBuildOutput
-> = (Game: FeatureBuildGame<Accessible>) => Output
-
-export interface FeatureDefinition<
-  Name extends string = string,
-  FeatureSchema extends Schema.Any = Schema.Any,
-  Requires extends ReadonlyArray<AnyFeature> = ReadonlyArray<AnyFeature>,
-  Output extends FeatureBuildOutput = FeatureBuildOutput
-> {
-  readonly kind: "feature"
-  readonly name: Name
-  readonly schema: FeatureSchema
-  readonly requires: Requires
-  readonly build: FeatureBuildFunction<MergeSchemaDefinitions<FeatureSchema, MergeFeatureSchemas<Requires>>, Output>
-  readonly output: Output
-}
-
-type MergeFeatureSchemas<Features extends ReadonlyArray<AnyFeature>> =
-  Features extends readonly [infer Head extends AnyFeature, ...infer Tail extends Array<AnyFeature>]
-    ? MergeSchemaDefinitions<FeatureClosureSchema<Head>, MergeFeatureSchemas<Tail>>
-    : EmptySchema
-
-type FeatureClosureSchema<F extends AnyFeature> =
-  F extends FeatureDefinition<any, infer FeatureSchema extends Schema.Any, infer Requires extends ReadonlyArray<AnyFeature>, any>
-    ? MergeSchemaDefinitions<FeatureSchema, MergeFeatureSchemas<Requires>>
-    : EmptySchema
-
-type FeatureNames<Features extends ReadonlyArray<AnyFeature>> = Features[number]["name"]
-
-type DuplicateFeatureNames<
-  Features extends ReadonlyArray<AnyFeature>,
-  Seen extends string = never
-> = Features extends readonly [infer Head extends AnyFeature, ...infer Tail extends Array<AnyFeature>]
-  ? Head["name"] extends Seen
-    ? Head["name"] | DuplicateFeatureNames<Tail, Seen>
-    : DuplicateFeatureNames<Tail, Seen | Head["name"]>
-  : never
-
-type MissingFeatureDependencies<Features extends ReadonlyArray<AnyFeature>> =
-  Exclude<Features[number]["requires"][number]["name"], FeatureNames<Features>>
-
-type FeatureSchemas<Features extends ReadonlyArray<AnyFeature>> = {
-  readonly [K in keyof Features]: Features[K]["schema"]
-}
-
-/**
- * Rejects duplicate feature names, missing required features, and schema
- * fragments whose keys or descriptor names collide.
- */
-type ValidateFeatureSelection<Features extends ReadonlyArray<AnyFeature>> =
-  [DuplicateFeatureNames<Features>] extends [never]
-    ? [MissingFeatureDependencies<Features>] extends [never]
-      ? ValidateFragments<FeatureSchemas<Features>>
-      : { readonly __fixFeatureDependencies__: MissingFeatureDependencies<Features> }
-    : { readonly __fixFeatureSelection__: DuplicateFeatureNames<Features> }
-
-type RebindFeatureSchedule<ScheduleValue, S extends Schema.Any, Root> =
-  ScheduleValue extends Schedule.ScheduleDefinition<any, infer Requirements, any, infer Carried, infer Failure>
-    ? Schedule.ScheduleDefinition<S, Requirements, Root, Carried, Failure>
-    : never
-
-type FeatureScheduleArray<Output, Key extends "bootstrap" | "update"> =
-  Key extends keyof Output
-    ? Extract<Output[Key], ReadonlyArray<AnySchedule>>
-    : readonly []
-
-type NormalizeFeatureOutput<Output extends object, S extends Schema.Any, Root> = {
-  readonly [K in Exclude<keyof Output, "bootstrap" | "update">]: Output[K]
-} & {
-  readonly bootstrap: ReadonlyArray<RebindFeatureSchedule<FeatureScheduleArray<Output, "bootstrap">[number], S, Root>>
-  readonly update: ReadonlyArray<RebindFeatureSchedule<FeatureScheduleArray<Output, "update">[number], S, Root>>
-}
-
-type FeatureOutputRecord<Features extends ReadonlyArray<AnyFeature>, S extends Schema.Any, Root> = {
-  readonly [K in FeatureNames<Features>]:
-    NormalizeFeatureOutput<Extract<Features[number], { readonly name: K }>["output"], S, Root>
-}
-
-/**
- * The result of composing features: the merged schema, the bound `Game`,
- * each feature's normalized output, and the aggregated schedules in feature
- * order.
- */
-export interface ComposedFeatureProject<
-  Features extends ReadonlyArray<AnyFeature>,
-  Root = unknown,
-  S extends Schema.Any = MergeFeatureSchemas<Features>
-> {
-  readonly schema: S
-  readonly Game: Schema.Game<S, Root>
-  readonly features: FeatureOutputRecord<Features, S, Root>
-  readonly schedules: {
-    readonly bootstrap: ReadonlyArray<FeatureOutputRecord<Features, S, Root>[FeatureNames<Features>]["bootstrap"][number]>
-    readonly update: ReadonlyArray<FeatureOutputRecord<Features, S, Root>[FeatureNames<Features>]["update"][number]>
-  }
-}
-
-/**
- * Defines one pre-bind feature.
- */
-export const define = <
-  const Name extends string,
-  FeatureSchema extends Schema.Any,
-  const Requires extends ReadonlyArray<AnyFeature> = [],
-  Output extends FeatureBuildOutput = FeatureBuildOutput
->(
-  name: Name,
-  options: {
-    readonly schema: FeatureSchema
-    readonly requires?: Requires
-    readonly build: FeatureBuildFunction<MergeSchemaDefinitions<FeatureSchema, MergeFeatureSchemas<Requires>>, Output>
-  }
-): FeatureDefinition<Name, FeatureSchema, Requires, Output> => ({
-  kind: "feature",
-  name,
-  schema: options.schema,
-  requires: (options.requires ?? []) as Requires,
-  build: options.build,
-  output: undefined as unknown as Output
-})
-
-/**
- * Composes features into one merged schema and one bound `Game`, then builds
- * every feature against it.
- *
- * Aggregated schedule order is the selected feature order, not dependency
- * order. Run them with `runtime.tick(...project.schedules.update)`.
- */
-export const compose = <
-  Root,
-  const Features extends readonly [AnyFeature, ...Array<AnyFeature>]
->(options: {
-  readonly root: Root
-  readonly features: Features
-} & ValidateFeatureSelection<Features>): ComposedFeatureProject<Features, Root> => {
-  const featureNames = new Set<string>()
-  for (const feature of options.features) {
-    if (featureNames.has(feature.name)) {
-      throw new Error(`Duplicate feature name: ${feature.name}`)
-    }
-    featureNames.add(feature.name)
-  }
-  for (const feature of options.features) {
-    for (const requirement of feature.requires) {
-      if (!featureNames.has(requirement.name)) {
-        throw new Error(`Missing required feature: ${requirement.name}`)
-      }
-    }
-  }
-
-  const schema = buildSchema(options.features.map((feature) => feature.schema))
-  const Game = makeGame(schema, options.root)
-  const features: Record<string, object> = Object.create(null)
-  const bootstrap: Array<AnySchedule> = []
-  const update: Array<AnySchedule> = []
-
-  for (const feature of options.features) {
-    const built = (feature.build as (Game: unknown) => FeatureBuildOutput & Record<string, unknown>)(Game)
-    const normalized = {
-      ...built,
-      bootstrap: [...(built.bootstrap ?? [])],
-      update: [...(built.update ?? [])]
-    }
-    bootstrap.push(...normalized.bootstrap)
-    update.push(...normalized.update)
-    features[feature.name] = normalized
-  }
-
-  return {
-    schema,
-    Game,
-    features,
-    schedules: { bootstrap, update }
-  } as unknown as ComposedFeatureProject<Features, Root>
-}
-
-export const Feature = {
-  define,
-  compose
-}

package/src/Fx.ts

@@ -1,176 +0,0 @@
-/**
- * Small explicit effect type used for systems and runtime orchestration.
- *
- * `Fx` models delayed computation with typed success, failure, and environment
- * channels. Expected failures are returned as `Result` values; exceptions are
- * reserved for unexpected defects in user code.
- *
- * Systems that cannot fail return nothing. A system returns an `Fx` when it
- * has an expected failure: `Fx.fail(...)` rolls back the system's ECS writes
- * and surfaces a typed `SystemFailure` from `runtime.tick(...)`. `map` and
- * `flatMap` compose such effects.
- *
- * @example
- * ```ts
- * // Build one small delayed computation.
- * const program = Fx.map(Fx.succeed(1), (value) => value + 1)
- *
- * // Execute it explicitly at the runtime boundary.
- * const result = Fx.runSync(program)
- * ```
- *
- * @module Fx
- * @docGroup runtime
- *
- * @groupDescription Namespaces
- * Grouped helper types that extract success, error, and environment information from effects.
- *
- * @groupDescription Interfaces
- * Public effect contracts used by systems and runtime orchestration.
- *
- * @groupDescription Type Aliases
- * Shared helper types derived from one `Fx` value.
- *
- * @groupDescription Functions
- * Minimal constructors and combinators for explicit delayed computations.
- */
-import * as Result from "./Result.ts"
-
-/**
- * String-literal type id used to mirror Effect's current `~effect/...` style.
- */
-export type FxTypeId = "~ritmo/Fx"
-
-/**
- * Runtime value for the `Fx` type id.
- */
-const fxTypeId: FxTypeId = "~ritmo/Fx"
-
-/**
- * A minimal Effect-style computation used by the runtime.
- *
- * `Fx<A, E, R>` models a computation that succeeds with `A`, may fail with `E`,
- * and requires an environment `R`.
- */
-export interface Fx<A, E = never, R = unknown> {
-  readonly [fxTypeId]: {
-    readonly _A: (_: never) => A
-    readonly _E: (_: never) => E
-    readonly _R: (_: R) => void
-  }
-  readonly run: (environment: R) => Result.Result<A, E>
-}
-
-/**
- * Type-level helpers for `Fx`.
- */
-export namespace Fx {
-  /**
-   * Extracts the success type from an effect.
-   */
-  export type Success<T extends Fx<any, any, any>> = T extends Fx<infer A, infer _E, infer _R> ? A : never
-  /**
-   * Extracts the error type from an effect.
-   */
-  export type Error<T extends Fx<any, any, any>> = T extends Fx<infer _A, infer E, infer _R> ? E : never
-  /**
-   * Extracts the required environment from an effect.
-   */
-  export type Context<T extends Fx<any, any, any>> = T extends Fx<infer _A, infer _E, infer R> ? R : never
-}
-
-/**
- * Low-level constructor for `Fx`.
- *
- * All public constructors eventually delegate here so the runtime shape stays
- * consistent.
- */
-const make = <A, E, R>(run: (environment: R) => Result.Result<A, E>): Fx<A, E, R> =>
-  ({
-    [fxTypeId]: {
-      _A: (_: never) => undefined as A,
-      _E: (_: never) => undefined as E,
-      _R: (_: R) => undefined
-    },
-    run
-  }) as Fx<A, E, R>
-
-/**
- * Creates an effect that immediately succeeds with a value.
- *
- * Use this for pure values that should still participate in the typed effect
- * composition model.
- */
-export const succeed = <A, R = unknown>(value: A): Fx<A, never, R> =>
-  make(() => Result.success(value))
-
-/**
- * Wraps a synchronous computation in an `Fx`.
- *
- * This is the most common constructor for system implementations in the current
- * runtime because systems are executed synchronously.
- */
-export const sync = <A, R = unknown>(evaluate: () => A): Fx<A, never, R> =>
-  make(() => Result.success(evaluate()))
-
-/**
- * Creates an effect that returns one expected failure when run.
- */
-export const fail = <E, R = unknown>(error: E): Fx<never, E, R> =>
-  make(() => Result.failure(error))
-
-/**
- * Transforms the success value of an effect.
- */
-export const map = <A, B, E, R>(
-  self: Fx<A, E, R>,
-  f: (value: A) => B
-): Fx<B, E, R> => make((environment) => {
-  const result = self.run(environment)
-  return result.ok ? Result.success(f(result.value)) : result
-})
-
-/**
- * Sequences two effects, allowing the second one to depend on the first result.
- */
-export const flatMap = <A, B, E1, E2, R1, R2>(
-  self: Fx<A, E1, R1>,
-  f: (value: A) => Fx<B, E2, R2>
-): Fx<B, E1 | E2, R1 & R2> => make<B, E1 | E2, R1 & R2>((environment) => {
-  const first = self.run(environment as R1)
-  return first.ok ? f(first.value).run(environment as R2) : first
-})
-
-/**
- * Reads the whole effect environment.
- *
- * Use this when a system helper wants access to all declared services at once.
- */
-export const access = <R>(): Fx<R, never, R> =>
-  make((environment) => Result.success(environment))
-
-/**
- * Reads a single service from the environment by key.
- *
- * This is useful for small helpers that need one dependency without threading
- * the entire environment type manually.
- */
-export const accessService = <R, K extends keyof R>(key: K): Fx<R[K], never, R> =>
-  make((environment) => Result.success(environment[key]))
-
-/**
- * Supplies the environment needed by an effect.
- */
-export const provide = <A, E, R>(
-  self: Fx<A, E, R>,
-  environment: R
-): Fx<A, E, unknown> => make(() => self.run(environment))
-
-/**
- * Runs an effect that no longer requires any environment.
- *
- * The runtime uses this at the edge after it has provided the services declared
- * by a system spec.
- */
-export const runSync = <A, E>(self: Fx<A, E, unknown>): Result.Result<A, E> =>
-  self.run(undefined)

package/src/internal/definition.ts

@@ -1,56 +0,0 @@
-import * as Result from "../Result.ts"
-
-export type Entry<Value, Error> = Result.Result<Value, Error>
-
-export type ResultConstructor<Value, Raw, Error> = {
-  readonly result: (raw: Raw) => Result.Result<Value, Error>
-}
-
-type AnyEntry = Result.Result<any, any>
-
-export type Entries = Readonly<Record<string, AnyEntry>>
-
-export type SuccessOf<Input extends Entries> = {
-  readonly [Key in keyof Input]:
-    Input[Key] extends Result.Result<infer Value, any> ? Value : never
-}
-
-export type ErrorOf<Input extends Entries> = {
-  readonly [Key in keyof Input]:
-    Input[Key] extends Result.Result<any, infer Error> ? Error | null : never
-}
-
-export const entry = <Value, Raw, Error>(
-  constructor: ResultConstructor<Value, Raw, Error>,
-  raw: Raw
-): Entry<Value, Error> => constructor.result(raw)
-
-export const all = <Input extends Entries>(
-  input: Input
-): Result.Result<SuccessOf<Input>, ErrorOf<Input>> => {
-  const values: Record<string, unknown> = {}
-  const errors: Record<string, unknown> = {}
-  let hasFailure = false
-
-  for (const key of Object.keys(input)) {
-    const entry = input[key]
-    if (entry === undefined) {
-      continue
-    }
-
-    if (entry.ok) {
-      values[key] = entry.value
-      errors[key] = null
-      continue
-    }
-
-    hasFailure = true
-    errors[key] = entry.error
-  }
-
-  if (hasFailure) {
-    return Result.failure(errors as ErrorOf<Input>)
-  }
-
-  return Result.success(values as SuccessOf<Input>)
-}