babavoss 0.0.1 → 0.0.2

package/src/ecs/system.ts

@@ -0,0 +1,256 @@
+// A system: one module of a baba, written as one expression. Its declaration
+// is data, what the state holds of it (model), how it reaches outside
+// (effects) and which systems it reads; its pieces are made from it, each
+// whole where it is written: a step, an effect's binding, an action or a
+// query with its contract beside its body. The system is one object: its
+// handles by name, `pond.fish`, everywhere, and under SYSTEM what the runtime
+// runs. Every piece sees the state as this system may touch it: a handle it
+// did not declare, and does not read, does not type-check.
+//
+//   export default system({ name: "pond", model, effects, reads: [tasks] }, (pond, p) => [
+//     p.step("swim", (w) => …),
+//     p.on(pond.fetch, { done: (w, e, r) => … }),
+//     p.action("feed", { summary, args, result, run: (w, a) => … }),
+//     p.query("pond", { result, read: (w) => … }),
+//   ]);
+//
+// A big system declares itself in a file of its own, `declare({...})`, and
+// writes pieces beside their helpers in parts, `part(decl, (trunk, p) => [...])`.
+// Pure: no IO, no Bun.
+import type { Schema } from "../kernel/schema.ts";
+import { declareModel, systemObject, dataOf, action as makeAction, query as makeQuery, SYSTEM, type AcceptDef, type ResourceDef, type EffectDef, type ActionDef, type QueryDef, type Refs, type Shape, type Of, type System, type SystemData, type Contract, type Binding, type Step } from "./baba.ts";
+import type { Ask, Component, Comps, Ress, Effs, Effect, Entity, Value, Args, Result, EventOf, Row, Values, Not, Change, Select, Done, Failed, Settlement } from "./state.ts";
+
+// ---- the declaration ----------------------------------------------------
+
+/** A model entry: a component's shape, an ask, or a resource. */
+export type Entry = Shape | AcceptDef | ResourceDef<any>;
+
+type ComponentsOf<M> = { [K in keyof M as M[K] extends ResourceDef<any> ? never : K]: Exclude<M[K], ResourceDef<any>> };
+type ResourcesOf<M> = { [K in keyof M as M[K] extends ResourceDef<any> ? K : never]: Extract<M[K], ResourceDef<any>> };
+/** The handles a declaration makes, by name, each branded with the system's name. */
+export type Handles<N extends string, M, E> = Refs<N, ComponentsOf<M>, ResourcesOf<M>, E>;
+
+type ComponentNames<M> = { [K in keyof M & string]: M[K] extends ResourceDef<any> ? never : K }[keyof M & string];
+/** Each effect, checked against the model: a mirror names one of its components, and what its list answers has that component's shape. */
+type Checked<M, E> = {
+  [K in keyof E]: E[K] extends EffectDef<any, any, any, infer Mi, infer L>
+    ? [Mi] extends [null] ? E[K]
+    : Mi extends ComponentNames<M> ? (unknown extends L ? E[K] : L extends Of<M[Mi & keyof M]> ? E[K] : { error: `source ${K & string}: what its list answers is not ${Mi}'s shape` })
+    : { error: `source ${K & string}: mirror ${Mi & string} is not a component of the model` }
+    : E[K];
+};
+
+/** A system's declaration: its name, what the state holds of it, how it reaches outside, which systems it reads. */
+export interface Decl<N extends string = string, M = any, E = any, R extends readonly System[] = readonly System[]> {
+  readonly name: N;
+  readonly model?: M;
+  readonly effects?: E;
+  /** The systems whose handles its pieces may read, and whose asks they may add. Reads go one way: two systems never read each other. */
+  readonly reads?: R;
+}
+const DECLARED: unique symbol = Symbol.for("babavoss.declared");
+type Named<D> = D extends Decl<infer N> ? N : never;
+type HandlesOfDecl<D> = D extends Decl<infer N, infer M, infer E> ? Handles<N, M, E> : never;
+type ReadsOfDecl<D> = D extends Decl<any, any, any, infer R> ? R : readonly [];
+
+// ---- the state as a system sees it ----------------------------------------
+
+/** A system's handles, as types. */
+export type HandlesOf<S> = S extends { readonly [SYSTEM]: { readonly $types?: { readonly handles: infer X } } } ? X : never;
+type ReadsOf<S> = S extends { readonly [SYSTEM]: { readonly $types?: { readonly reads: infer R } } } ? R : never;
+/** The handles of every system read, as one union: what a piece may read, and ask of. */
+export type ReadUnion<R> = R extends readonly (infer S)[] ? HandlesOf<S> : never;
+
+type See<X, R> = Comps<X> | Comps<R>;
+type TermOf<C extends Component> = C | Not | Change<C>;
+type Asks<R> = Extract<Comps<R>, Ask>;
+
+/**
+ * The state as a step, a binding or an action of a system sees it: it writes
+ * what it owns and asks of what it reads; it reads what it owns and what it
+ * reads; it runs its own effects. A handle it did not declare does not type-check.
+ */
+export interface Scope<X, R = never> {
+  /** The round's time, milliseconds since the epoch. */
+  readonly now: number;
+  /** Milliseconds since the previous round's time; 0 in the first. */
+  readonly elapsed: number;
+  readonly round: number;
+  random(): number;
+  transaction<T>(fn: () => T): T;
+  spawn(): Entity;
+  spawn<K extends Comps<X> | Asks<R>>(c: K, value: Value<K>): Entity;
+  despawn(e: Entity): void;
+  alive(e: Entity): boolean;
+  /** The system that made `e`, if one did. */
+  maker(e: Entity): string | undefined;
+  /** Every entity alive, in spawn order. */
+  all(): Entity[];
+  idsOf(c: See<X, R>): Entity[];
+  add<K extends (Comps<X> | Asks<R>) & Component<string, true>>(e: Entity, c: K): void;
+  add<K extends Comps<X> | Asks<R>>(e: Entity, c: K, value: Value<K>): void;
+  update<K extends Comps<X>>(e: Entity, c: K, fn: (value: Value<K>) => Value<K>): void;
+  update<K extends Ress<X>>(r: K, fn: (value: Value<K>) => Value<K>): void;
+  remove(e: Entity, ...cs: Comps<X>[]): void;
+  set<K extends Ress<X>>(r: K, value: Value<K>): void;
+  get<K extends See<X, R>>(e: Entity, c: K): Value<K> | undefined;
+  get<K extends Ress<X> | Ress<R>>(r: K): Value<K>;
+  has(e: Entity, c: See<X, R>): boolean;
+  count(c: See<X, R>): number;
+  find<K extends See<X, R>>(c: K, key: string | number): Entity | undefined;
+  query<const Cs extends readonly TermOf<See<X, R>>[]>(...terms: Cs): Row<Cs>[];
+  query<Cs extends readonly TermOf<See<X, R>>[]>(sel: Select<Cs>): Row<Cs>[];
+  each<const Cs extends readonly TermOf<See<X, R>>[]>(terms: Cs, fn: (e: Entity, ...values: Values<Cs>) => void): void;
+  each<Cs extends readonly TermOf<See<X, R>>[]>(sel: Select<Cs>, fn: (e: Entity, ...values: Values<Cs>) => void): void;
+  run<K extends Effs<X>>(effect: K, args?: Args<K>, entity?: Entity): void;
+  cancel(effect: Effs<X>, entity?: Entity): void;
+  running(effect: Effs<X>, entity?: Entity): boolean;
+  events<K extends Effs<X>>(effect: K): { entity: Entity | null; event: EventOf<K> }[];
+  done<K extends Effs<X>>(effect: K): Done<K>[];
+  failed<K extends Effs<X>>(effect: K): Failed<K>[];
+  settlement(of: Entity | Effs<X>): Settlement | undefined;
+}
+/** The state as a query sees it, between rounds: reads only. */
+export type Reader<X, R = never> = Pick<Scope<X, R>, "now" | "round" | "get" | "has" | "count" | "find" | "query" | "each" | "running" | "settlement" | "alive" | "maker" | "all" | "idsOf">;
+
+/** The state a system's pieces see, for a helper written outside them: `(w: StateOf<typeof pond>) => …`; a declaration's too. */
+export type StateOf<S> = S extends Decl ? Scope<HandlesOfDecl<S>, ReadUnion<ReadsOfDecl<S>>> : Scope<HandlesOf<S>, ReadUnion<ReadsOf<S>>>;
+/** The state a system's queries see, for a helper an action and a query share. */
+export type ReaderOf<S> = S extends Decl ? Reader<HandlesOfDecl<S>, ReadUnion<ReadsOfDecl<S>>> : Reader<HandlesOf<S>, ReadUnion<ReadsOf<S>>>;
+
+// ---- the pieces ---------------------------------------------------------
+
+const PIECE: unique symbol = Symbol.for("babavoss.piece");
+interface Of_<O extends string> { readonly [PIECE]: true; readonly of: O }
+/** A step: run every round, in the order the system lists its steps. */
+export interface StepPiece<O extends string = string> extends Of_<O> { readonly kind: "step"; readonly name: string; readonly run: Step }
+/** An effect's binding: how its answers land, and for which entities it runs. */
+export interface OnPiece<O extends string = string> extends Of_<O> { readonly kind: "on"; readonly effect: Effect; readonly binding: Binding }
+/** An action: its contract and its body. */
+export interface ActionPiece<O extends string = string, K extends string = string, A = any, R = any> extends Of_<O> { readonly kind: "action"; readonly name: K; readonly def: ActionDef<A, R> }
+/** A query: its contract and its body. */
+export interface QueryPiece<O extends string = string, K extends string = string, A = any, R = any> extends Of_<O> { readonly kind: "query"; readonly name: K; readonly def: QueryDef<A, R> }
+export type Piece<O extends string = string> = StepPiece<O> | OnPiece<O> | ActionPiece<O> | QueryPiece<O>;
+/** What a system's list may hold: a piece, or nothing, for a piece made only when a condition holds: `flag && p.step(…)`. */
+export type Maybe<O extends string = string> = Piece<O> | false | null | undefined;
+
+/** How one effect's answers land, and for which entities it runs. */
+export interface BindingOf<W, E> {
+  /** The entities to run it for, with the args of each; one job per entity, asked again only once answered. */
+  for?: (w: W) => Iterable<readonly [Entity, Args<E>]>;
+  done?: (w: W, entity: Entity | null, result: Result<E>) => void;
+  failed?: (w: W, entity: Entity | null, error: string) => void;
+}
+
+/** The maker of a system's pieces, `p`: each piece is typed by the system and recorded by it. */
+export interface Maker<O extends string, X, R> {
+  step(name: string, run: (w: Scope<X, R>) => void): StepPiece<O>;
+  on<E extends Effs<X>>(effect: E, binding: BindingOf<Scope<X, R>, E>): OnPiece<O>;
+  action<const K extends string, const S extends Shape = {}, Res = void>(name: K, def: { summary?: string; args?: S; positional?: (keyof Of<S> & string)[]; result?: Schema<Res>; run(w: Scope<X, R>, args: Of<S>): NoInfer<Res> }): ActionPiece<O, K, Of<S>, Res>;
+  query<const K extends string, const S extends Shape = {}, Res = unknown>(name: K, def: { summary?: string; args?: S; positional?: (keyof Of<S> & string)[]; result?: Schema<Res>; read(w: Reader<X, R>, args: Of<S>): NoInfer<Res> }): QueryPiece<O, K, Of<S>, Res>;
+}
+
+type Flat<T> = { [K in keyof T]: T[K] } & {};
+type Acts<P extends readonly unknown[]> = Flat<{ [I in keyof P & `${number}` as P[I] extends ActionPiece<any, infer K> ? K : never]: P[I] extends ActionPiece<any, any, infer A, infer R> ? { args: A; result: R } : never }>;
+type Queries<P extends readonly unknown[]> = Flat<{ [I in keyof P & `${number}` as P[I] extends QueryPiece<any, infer K> ? K : never]: P[I] extends QueryPiece<any, any, infer A, infer R> ? { args: A; result: R } : never }>;
+/** The system as its pieces see it while they are made: its handles, its contract not yet known. */
+export type Building<N extends string, X, R> = System<N, X, R, unknown>;
+
+/** Pieces of a system written in another file, typed by its declaration: `export const stages = part(decl, (trunk, p) => [ … ])`, listed as `...stages(trunk, p)`. */
+export type Part<D extends Decl, P extends readonly Maybe<Named<D>>[] = readonly Maybe<Named<D>>[]> = (system: Building<Named<D>, HandlesOfDecl<D>, ReadsOfDecl<D>>, p: Maker<Named<D>, HandlesOfDecl<D>, ReadUnion<ReadsOfDecl<D>>>) => P;
+
+// ---- making a system ----------------------------------------------------
+
+const isResource = (v: unknown): v is ResourceDef<any> => typeof v === "object" && v !== null && (v as ResourceDef<any>).isResource === true;
+const isPiece = (v: unknown): v is Piece => typeof v === "object" && v !== null && (v as Piece)[PIECE] === true;
+const describe = (pc: Piece) => pc.kind === "on" ? `binding of ${pc.effect.name}` : `${pc.kind} ${pc.name}`;
+
+/** A declaration's handles, made once: by declare() at import of its file, or by system() for an inline one. */
+function built(decl: Decl) {
+  const known = (decl as { [DECLARED]?: ReturnType<typeof declareModel> })[DECLARED];
+  if (known) return known;
+  if (typeof decl !== "object" || decl === null) throw new Error("system: the first argument is the declaration, { name, model, effects, reads }");
+  const components: Record<string, Shape | AcceptDef> = {};
+  const resources: Record<string, ResourceDef<any>> = {};
+  for (const [k, v] of Object.entries((decl.model ?? {}) as Record<string, Entry>)) { if (isResource(v)) resources[k] = v; else components[k] = v as Shape | AcceptDef; }
+  return declareModel(decl.name, { components, resources, effects: (decl.effects ?? {}) as Record<string, EffectDef<any, any>> });
+}
+
+/** A declaration in a file of its own, checked now: names, key fields, mirrors and initial values, at import. Parts and the system both take it. */
+export function declare<
+  const N extends string,
+  const M extends Record<string, Entry> = {},
+  const E extends Record<string, EffectDef<any, any, any, any, any>> = {},
+  const R extends readonly System[] = readonly [],
+>(decl: { name: N; model?: M; effects?: E & Checked<M, E>; reads?: R }): Decl<N, M, E, R> {
+  const d = built(decl as Decl);
+  return Object.freeze({ ...decl, [DECLARED]: d }) as never;
+}
+
+/** Pieces of a system written beside their helpers in another file; the system lists them with `...part(system, p)`. */
+export function part<const D extends Decl, const P extends readonly Maybe<Named<D>>[]>(decl: D, make: Part<D, P>): Part<D, P> {
+  return ((system, p) => {
+    if (dataOf(system).name !== decl.name) throw new Error(`a part of ${decl.name} was given ${dataOf(system).name}`);
+    return make(system, p);
+  }) as Part<D, P>;
+}
+
+/**
+ * A system: the declaration, and the function that makes its pieces from it.
+ * `make` gets the system itself, its handles by name, and `p`, which makes
+ * pieces; it answers the list of them, steps in the order they run. A piece
+ * made and not listed, or listed twice, or another system's, is refused.
+ */
+export function system<
+  const N extends string,
+  const M extends Record<string, Entry> = {},
+  const E extends Record<string, EffectDef<any, any, any, any, any>> = {},
+  const R extends readonly System[] = readonly [],
+  const P extends readonly Maybe<N>[] = readonly [],
+>(decl: { name: N; model?: M; effects?: E & Checked<M, E>; reads?: R } | Decl<N, M, E, R>, make?: (system: Building<N, Handles<N, M, E>, R>, p: Maker<N, Handles<N, M, E>, ReadUnion<R>>) => P): System<N, Handles<N, M, E>, R, Contract<Acts<P>, Queries<P>>> {
+  const d = built(decl as Decl);
+  const name = d.name;
+  const reads = [...((decl as Decl).reads ?? [])];
+  reads.forEach((r, i) => { try { dataOf(r); } catch { throw new Error(`${name} reads ${i === 0 ? "a" : `its ${i + 1}th`} system that is not one yet: ${r === undefined ? "undefined, a module read before it finished: two systems read each other, or an import cycle" : "not a system"}`); } });
+  const { system: sys, complete } = systemObject(d, reads);
+  const made = new Set<Piece>();
+  const piece = <T extends Piece>(pc: Omit<T, typeof PIECE | "of">): T => { const done = Object.freeze({ ...pc, [PIECE]: true, of: name }) as unknown as T; made.add(done); return done; };
+  const p: Maker<N, any, any> = {
+    step: (n, run) => piece<StepPiece<N>>({ kind: "step", name: n, run: run as Step }),
+    on: (effect, binding) => {
+      if ((effect as Effect | undefined)?.owner !== name) throw new Error(`${name} binds ${(effect as Effect | undefined)?.name ?? String(effect)}, which is not one of its effects`);
+      return piece<OnPiece<N>>({ kind: "on", effect: effect as Effect, binding: binding as Binding });
+    },
+    action: (n, def) => piece<ActionPiece<N>>({ kind: "action", name: n, def: makeAction(def as never) }) as never,
+    query: (n, def) => piece<QueryPiece<N>>({ kind: "query", name: n, def: makeQuery(def as never) }) as never,
+  };
+  const listed = (make ? make(sys as never, p) : []) as readonly unknown[];
+  if (!Array.isArray(listed)) throw new Error(`${name}: the function that makes its pieces answers a list of them: (${name}, p) => [ … ]`);
+  const steps: { name: string; run: Step }[] = [];
+  const on = new Map<Effect, Binding>();
+  const actions: Record<string, ActionDef> = {};
+  const queries: Record<string, QueryDef> = {};
+  const seen = new Set<Piece>();
+  for (const v of listed) {
+    if (v === false || v === null || v === undefined) continue;
+    if (!isPiece(v)) throw new Error(`${name} lists something that is not a piece; pieces are made with p: p.step, p.on, p.action, p.query`);
+    if (v.of !== name) throw new Error(`${name} lists ${describe(v)}, which is ${v.of}'s`);
+    if (seen.has(v)) throw new Error(`${name} lists its ${describe(v)} twice`);
+    seen.add(v);
+    if (v.kind === "step") { if (steps.some((x) => x.name === v.name)) throw new Error(`${name} has two steps named ${v.name}`); steps.push({ name: v.name, run: v.run }); }
+    else if (v.kind === "on") { if (on.has(v.effect)) throw new Error(`${name} binds ${v.effect.name} twice`); on.set(v.effect, v.binding); }
+    else if (v.kind === "action") { if (v.name in actions) throw new Error(`${name} has two actions named ${v.name}`); actions[v.name] = v.def; }
+    else { if (v.name in queries) throw new Error(`${name} has two queries named ${v.name}`); queries[v.name] = v.def; }
+  }
+  const forgotten = [...made].filter((pc) => !seen.has(pc));
+  if (forgotten.length) throw new Error(`${name} made ${forgotten.map(describe).join(", ")} and did not list ${forgotten.length === 1 ? "it" : "them"}: every piece p makes goes in the list it answers`);
+  return complete({ steps, on, actions, queries }) as never;
+}
+
+/** A system's data, for the framework: its name, model, reads, steps, bindings and contract. */
+export { dataOf, type SystemData };
+/** The actions of a system, as types. */
+export type Act<S> = S extends { readonly [SYSTEM]: { readonly $types?: { readonly contract: Contract<infer A, any> } } } ? A : never;
+/** The queries of a system, as types. */
+export type Read<S> = S extends { readonly [SYSTEM]: { readonly $types?: { readonly contract: Contract<any, infer Q> } } } ? Q : never;