@typeonce/ritmo-browser 0.10.0 → 0.11.0

package/src/InputCapture.ts

@@ -8,12 +8,22 @@
  * every system in that run reads the same snapshot and press edges are
  * observed exactly once per run.
  *
- * The source is any service with `snapshot()`: `Keyboard.actions(...)`
- * directly, or a game-specific adapter that merges several devices. The
- * resource's value type must be exactly the snapshot type.
+ * The source is any service with `snapshot()`: one device such as
+ * `Keyboard.actions(...)`, a `Controls` merge of several, or a
+ * `Controls.players(...)` pool. The resource's
+ * value type must be exactly the snapshot type (declare it as
+ * `InputCapture.SnapshotOf<typeof Source>`): not a wider type, and not one
+ * with extra optional fields.
  *
- * Its spec is erased, so it does not count as a writer of the resource for
- * `Game.System.thisTick(...)` order checks: place it first yourself.
+ * The system declares its access like any other: it writes the resource, so
+ * a reader declared with `Game.System.thisTick(...)` placed before it does
+ * not compile, and it consumes the source (`Game.System.consumeService`), so
+ * `describe()` warns with `service-consumed-twice` when one source is
+ * captured at more than one placement (in named schedules, or wherever a
+ * debug runtime saw it run). Every input source marks `snapshot()` with
+ * `System.Consumes`, so another system that declares the source with
+ * `Game.System.service` (to rebind it, say) cannot call `snapshot()`.
+ * Capture each source once and read the resource everywhere else.
  *
  * @module InputCapture
  * @docGroup browser
@@ -34,14 +44,17 @@
  * }).value
  * ```
  */
+import type * as System from "@typeonce/ritmo/System"
 import type { Descriptor } from "@typeonce/ritmo/Descriptor"
-import type { Condition, ConditionNeedsFromConditions } from "@typeonce/ritmo/Machine"
+import type { Condition } from "@typeonce/ritmo/Machine"
 import type { Schema } from "@typeonce/ritmo/Schema"
 
 /**
- * Anything that produces one input snapshot per call.
+ * Anything that produces one input snapshot per call. `snapshot()` drains
+ * the source, so only a system that declares it with
+ * `Game.System.consumeService` (like `InputCapture.system`) calls it.
  */
-export interface Source<Value> {
+export interface Source<Value> extends System.Consumes<"snapshot"> {
   readonly snapshot: () => Value
 }
 
@@ -55,18 +68,29 @@ type ResourceDescriptor = Descriptor<"resource", string, any>
 export type SnapshotOf<Service extends ServiceDescriptor> =
   Descriptor.Value<Service> extends Source<infer Value> ? Value : never
 
+/** Whether `A` and `B` are the same type, not merely assignable both ways. */
+type Same<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false
+
+/** The resource when its value type is exactly the source's snapshot type, otherwise an error naming the fix. */
+type MatchingResource<Resource extends ResourceDescriptor, Service extends ServiceDescriptor> =
+  Same<Descriptor.Value<Resource>, SnapshotOf<Service>> extends true
+    ? Resource
+    : "The resource's value type must be exactly the source's snapshot type: declare it with InputCapture.SnapshotOf<typeof Source>"
+
+/** Options for {@link system}. */
 export interface Options<
   S extends Schema.Any,
   Service extends ServiceDescriptor,
   Resource extends Schema.ResourceDescriptor<S>,
-  When extends ReadonlyArray<Condition> = readonly []
+  When extends ReadonlyArray<Condition> = readonly [],
+  Name extends string = string
 > {
   /** The system name. */
-  readonly name: string
+  readonly name: Name
   /** The service to read snapshots from; its value must have `snapshot()`. */
   readonly source: Descriptor.Value<Service> extends Source<any> ? Service : "The source service must provide snapshot()"
   /** The resource to write each snapshot into; its value type must be exactly the snapshot type. */
-  readonly resource: Resource & Descriptor<"resource", string, SnapshotOf<Service>>
+  readonly resource: MatchingResource<Resource, Service>
   /**
    * Run conditions, like a system's `when`. While they fail, snapshots are
    * not taken, so presses stay in the device until capture resumes (for
@@ -75,12 +99,6 @@ export interface Options<
   readonly when?: When
 }
 
-/**
- * The generated system. It requires the source service and the resource.
- */
-export type CaptureSystem<S extends Schema.Any, Root, Needs extends ServiceDescriptor | ResourceDescriptor | ConditionNeedsFromConditions<ReadonlyArray<Condition>>> =
-  Schema.BoundSystem<S, Root, any, never, string, Needs>
-
 /**
  * Builds the system that writes `source.snapshot()` into `resource`.
  */
@@ -89,15 +107,16 @@ export const system = <
   Root,
   const Service extends ServiceDescriptor,
   const Resource extends Schema.ResourceDescriptor<S>,
-  const When extends ReadonlyArray<Condition<Root>> = readonly []
+  const When extends ReadonlyArray<Condition<Root>> = readonly [],
+  const Name extends string = string
 >(
   Game: Schema.Game<S, Root>,
-  options: Options<S, Service, Resource, When>
-): CaptureSystem<S, Root, Service | Resource | ConditionNeedsFromConditions<When>> =>
+  options: Options<S, Service, Resource, When, Name>
+) =>
   Game.System(options.name, {
-    resources: { input: Game.System.writeResource(options.resource) },
-    services: { source: Game.System.service(options.source as Service) },
-    when: (options.when ?? []) as ReadonlyArray<Condition<Root>>
+    resources: { input: Game.System.writeResource(options.resource as Resource) },
+    services: { source: Game.System.consumeService(options.source as Service) },
+    when: (options.when ?? []) as When
   }, ({ resources, services }) => {
     resources.input.set(services.source.snapshot() as never)
-  }) as unknown as CaptureSystem<S, Root, Service | Resource | ConditionNeedsFromConditions<When>>
+  })