@oasys/oecs 0.5.4 → 0.6.0

package/dist/core/ecs/plugin.d.cts

@@ -0,0 +1,125 @@
+import { Store } from './store.cjs';
+import { ChangeFeed } from './change_feed.cjs';
+import { SystemContext } from './system_context.cjs';
+import { ECS } from './ecs.cjs';
+import { RouteDispatch } from './schedule.cjs';
+import { SystemConfig, SystemDescriptor } from './system.cjs';
+export type { ChangeFeed } from './change_feed.cjs';
+/** How a plugin claims the body of a system, and builds what one dispatch of
+ * it reads.
+ *
+ * The world asks the planner about every system it registers. A planner that
+ * has nothing to say about one answers `undefined`, and the system keeps its
+ * `fn`. Cold: registration only. */
+export interface SystemRoutePlanner {
+    /** Build what one routed dispatch reads, or `undefined` for a system this
+     * route does not claim. The world freezes the result onto the descriptor as
+     * `routePlan` and never looks inside it, so the plan's shape belongs to the
+     * plugin. The plugin validates its own config here, which is why a world
+     * without the plugin validates none. */
+    plan(config: SystemConfig): object | undefined;
+}
+/** What a route holds back from the world after it installs.
+ *
+ * One call, and the world holds one route. `null` puts every claimed system
+ * back on its own `fn`. Cold: an attach and a detach, never a frame. */
+export interface RouteControl {
+    route(dispatch: RouteDispatch | null): void;
+}
+/** Where the world's bytes are, for a plugin that reads them directly.
+ *
+ * A worker, a compute backend and a wasm module all need the same three
+ * facts. The memory travels and not its current buffer, because the two grow
+ * differently and a reader survives both. */
+export interface PluginMemory {
+    /** The bytes a foreign reader reaches: the `WebAssembly.Memory` on the
+     * wasm backing, the `SharedArrayBuffer` on the shared backing, `null` on
+     * any other. */
+    readonly backing: SharedArrayBuffer | WebAssembly.Memory | null;
+    /** What `memory.backing` resolved to. A refusal on a backing the reader
+     * cannot reach names it. */
+    readonly backingSource: string;
+    /** The byte offset of the store header inside the backing. */
+    readonly storeBase: number;
+}
+/** What one plugin may reach during `install`, and nothing wider.
+ *
+ * The world hands this record out once, at construction. A member that a bare
+ * store cannot answer is a method and not a field, so `storeOnlyHost` below
+ * can throw on the ones a store has no answer for. */
+export interface PluginHost {
+    /** Where the subsystem seams live. A plugin builds its service from a
+     * host record the store hands out, and gives the service back through an
+     * install method. */
+    readonly store: Store;
+    /** The bare world, for a plugin that registers a system, reads a
+     * field, builds a cursor or reaches a resource. It carries no facade of
+     * any plugin, including the one installing. */
+    readonly world: ECS;
+    /** The store's change feed, typed to what a consumer of it may touch. */
+    readonly changes: ChangeFeed;
+    /** The one system context an observer callback receives, shared with the
+     * schedule so an observer sees the same access span a system does. */
+    readonly context: SystemContext;
+    /** Run `fn` at the tail of every `update()`, after every system of the
+     * frame. `run` is the change tick of the detection point, above every
+     * stamp the frame made. Hooks run in install order. */
+    onSettle(fn: (run: number) => void): void;
+    /** Contribute the access shapes `startup()` folds into the archetype
+     * closure, so a callback that spawns or transitions gets its target
+     * archetype planted rather than first-touched mid-tick. Read once, at
+     * startup. */
+    onPrewarm(fn: () => readonly SystemDescriptor[]): void;
+    /** Run `fn` when the world goes away. A plugin that holds a thread, a
+     * timer or a socket ends it here. Hooks run in install order. */
+    onDispose(fn: () => void): void;
+    /** Where the world's bytes are. A plugin that hands the bytes to a worker
+     * or to a wasm module reads the three facts here. */
+    readonly memory: PluginMemory;
+    /** Claim the body of the systems this plugin routes, and take back the one
+     * call that turns the route on and off. A world holds one route, so a
+     * second install is a fault. */
+    installRoute(planner: SystemRoutePlanner): RouteControl;
+}
+/** An optional subsystem, and the facade surface it contributes.
+ *
+ * `install` receives the host because that is where the seams live: a plugin
+ * builds its service from a host record the store hands out, gives the service
+ * back through an install method, and returns its facade.
+ *
+ * `out X` (declared covariance) is what lets a plugin list be typed
+ * `readonly Plugin<object>[]`: `X` appears only in `install`'s return, so
+ * covariance is the honest direction and a concrete plugin is usable where
+ * any plugin is expected. Left unannotated, the compiler measures `X` from
+ * the whole interface and the list bound rejects every real plugin. */
+export interface Plugin<out X extends object> {
+    /** Names the plugin in a `PLUGIN_NOT_INSTALLED` fault. Matches the
+     * published subpath, so the message can name the import that fixes it. */
+    readonly name: string;
+    /** The plugins this one reads through, by name. `ECS.create` walks
+     * the plugin list in order, so a dependency has to come first in the list,
+     * and a missing one is a fault at construction. */
+    readonly requires?: readonly string[];
+    install(host: PluginHost): X;
+}
+/** The facade surface of one plugin, or `never` for a non-plugin. */
+type SurfaceOf<E> = E extends Plugin<infer X> ? X : never;
+/** Turn a union into an intersection. A plugin list is a tuple, so its element
+ * type is the union of the plugins in it, and a world carries all of them
+ * at once. The inference site is contravariant, which is what performs the
+ * conversion. */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/** The combined facade surface of a plugin list. `ECS.create` intersects this
+ * with the world, so `ecs.relations` exists exactly when `relations()` is in
+ * the list. */
+export type PluginsOf<P extends readonly unknown[]> = UnionToIntersection<SurfaceOf<P[number]>> & object;
+/** A host for a bare `Store`, with no world around it.
+ *
+ * Every plugin that only needs store seams installs through this, which is
+ * what a test driving a raw store uses. `store` and `changes` are both the
+ * store, so the change feed works here. Every world-level member throws: a
+ * bare store has no world, no system context, no schedule tail and nowhere to
+ * keep an observer registry, so reaching for one is a mistake worth naming
+ * rather than a case to silently support. */
+export declare function storeOnlyHost(store: Store): PluginHost;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/core/ecs/plugin.d.ts

@@ -0,0 +1,125 @@
+import { Store } from './store.js';
+import { ChangeFeed } from './change_feed.js';
+import { SystemContext } from './system_context.js';
+import { ECS } from './ecs.js';
+import { RouteDispatch } from './schedule.js';
+import { SystemConfig, SystemDescriptor } from './system.js';
+export type { ChangeFeed } from './change_feed.js';
+/** How a plugin claims the body of a system, and builds what one dispatch of
+ * it reads.
+ *
+ * The world asks the planner about every system it registers. A planner that
+ * has nothing to say about one answers `undefined`, and the system keeps its
+ * `fn`. Cold: registration only. */
+export interface SystemRoutePlanner {
+    /** Build what one routed dispatch reads, or `undefined` for a system this
+     * route does not claim. The world freezes the result onto the descriptor as
+     * `routePlan` and never looks inside it, so the plan's shape belongs to the
+     * plugin. The plugin validates its own config here, which is why a world
+     * without the plugin validates none. */
+    plan(config: SystemConfig): object | undefined;
+}
+/** What a route holds back from the world after it installs.
+ *
+ * One call, and the world holds one route. `null` puts every claimed system
+ * back on its own `fn`. Cold: an attach and a detach, never a frame. */
+export interface RouteControl {
+    route(dispatch: RouteDispatch | null): void;
+}
+/** Where the world's bytes are, for a plugin that reads them directly.
+ *
+ * A worker, a compute backend and a wasm module all need the same three
+ * facts. The memory travels and not its current buffer, because the two grow
+ * differently and a reader survives both. */
+export interface PluginMemory {
+    /** The bytes a foreign reader reaches: the `WebAssembly.Memory` on the
+     * wasm backing, the `SharedArrayBuffer` on the shared backing, `null` on
+     * any other. */
+    readonly backing: SharedArrayBuffer | WebAssembly.Memory | null;
+    /** What `memory.backing` resolved to. A refusal on a backing the reader
+     * cannot reach names it. */
+    readonly backingSource: string;
+    /** The byte offset of the store header inside the backing. */
+    readonly storeBase: number;
+}
+/** What one plugin may reach during `install`, and nothing wider.
+ *
+ * The world hands this record out once, at construction. A member that a bare
+ * store cannot answer is a method and not a field, so `storeOnlyHost` below
+ * can throw on the ones a store has no answer for. */
+export interface PluginHost {
+    /** Where the subsystem seams live. A plugin builds its service from a
+     * host record the store hands out, and gives the service back through an
+     * install method. */
+    readonly store: Store;
+    /** The bare world, for a plugin that registers a system, reads a
+     * field, builds a cursor or reaches a resource. It carries no facade of
+     * any plugin, including the one installing. */
+    readonly world: ECS;
+    /** The store's change feed, typed to what a consumer of it may touch. */
+    readonly changes: ChangeFeed;
+    /** The one system context an observer callback receives, shared with the
+     * schedule so an observer sees the same access span a system does. */
+    readonly context: SystemContext;
+    /** Run `fn` at the tail of every `update()`, after every system of the
+     * frame. `run` is the change tick of the detection point, above every
+     * stamp the frame made. Hooks run in install order. */
+    onSettle(fn: (run: number) => void): void;
+    /** Contribute the access shapes `startup()` folds into the archetype
+     * closure, so a callback that spawns or transitions gets its target
+     * archetype planted rather than first-touched mid-tick. Read once, at
+     * startup. */
+    onPrewarm(fn: () => readonly SystemDescriptor[]): void;
+    /** Run `fn` when the world goes away. A plugin that holds a thread, a
+     * timer or a socket ends it here. Hooks run in install order. */
+    onDispose(fn: () => void): void;
+    /** Where the world's bytes are. A plugin that hands the bytes to a worker
+     * or to a wasm module reads the three facts here. */
+    readonly memory: PluginMemory;
+    /** Claim the body of the systems this plugin routes, and take back the one
+     * call that turns the route on and off. A world holds one route, so a
+     * second install is a fault. */
+    installRoute(planner: SystemRoutePlanner): RouteControl;
+}
+/** An optional subsystem, and the facade surface it contributes.
+ *
+ * `install` receives the host because that is where the seams live: a plugin
+ * builds its service from a host record the store hands out, gives the service
+ * back through an install method, and returns its facade.
+ *
+ * `out X` (declared covariance) is what lets a plugin list be typed
+ * `readonly Plugin<object>[]`: `X` appears only in `install`'s return, so
+ * covariance is the honest direction and a concrete plugin is usable where
+ * any plugin is expected. Left unannotated, the compiler measures `X` from
+ * the whole interface and the list bound rejects every real plugin. */
+export interface Plugin<out X extends object> {
+    /** Names the plugin in a `PLUGIN_NOT_INSTALLED` fault. Matches the
+     * published subpath, so the message can name the import that fixes it. */
+    readonly name: string;
+    /** The plugins this one reads through, by name. `ECS.create` walks
+     * the plugin list in order, so a dependency has to come first in the list,
+     * and a missing one is a fault at construction. */
+    readonly requires?: readonly string[];
+    install(host: PluginHost): X;
+}
+/** The facade surface of one plugin, or `never` for a non-plugin. */
+type SurfaceOf<E> = E extends Plugin<infer X> ? X : never;
+/** Turn a union into an intersection. A plugin list is a tuple, so its element
+ * type is the union of the plugins in it, and a world carries all of them
+ * at once. The inference site is contravariant, which is what performs the
+ * conversion. */
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/** The combined facade surface of a plugin list. `ECS.create` intersects this
+ * with the world, so `ecs.relations` exists exactly when `relations()` is in
+ * the list. */
+export type PluginsOf<P extends readonly unknown[]> = UnionToIntersection<SurfaceOf<P[number]>> & object;
+/** A host for a bare `Store`, with no world around it.
+ *
+ * Every plugin that only needs store seams installs through this, which is
+ * what a test driving a raw store uses. `store` and `changes` are both the
+ * store, so the change feed works here. Every world-level member throws: a
+ * bare store has no world, no system context, no schedule tail and nowhere to
+ * keep an observer registry, so reaching for one is a mistake worth naming
+ * rather than a case to silently support. */
+export declare function storeOnlyHost(store: Store): PluginHost;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/core/ecs/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/plugin.ts"],"names":[],"mappings":"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"}

package/dist/core/ecs/plugin_slots.d.cts

@@ -0,0 +1,26 @@
+/***
+ * The plugin slots a bare world carries, and the guard that fills them.
+ *
+ * What this file owns: the value a world puts in the member of a plugin it
+ * never installed, and the dev refusal of a facade member that would overwrite
+ * something the world already has.
+ *
+ * What it refuses: the `PluginHost` and every type that names a world. The
+ * surface guard takes the world as a plain object, so this module stays out of
+ * the type cycle that `plugin.ts` and `ecs.ts` share.
+ *
+ * Cold path. The slots are built once per process, and the guard runs once per
+ * plugin under a `__DEV__` build.
+ ***/
+export declare const MISSING_RELATIONS: object;
+export declare const MISSING_EVENTS: object;
+export declare const MISSING_WORKERS: object;
+/** The reserved `observe` slot. A function, because a caller calls it. */
+export declare function missingObserve(): never;
+/** Refuse a facade member that would overwrite something the world already
+ * carries. `Object.assign` is silent about it, and the loss is a method the
+ * world needs. The reserved slots are the exception: a bare world
+ * declares each one so it can name the missing plugin, and the
+ * plugin that fills the slot is meant to replace it. Dev-only. */
+export declare function assertPluginSurface(world: object, plugin: string, surface: object): void;
+//# sourceMappingURL=plugin_slots.d.ts.map

package/dist/core/ecs/plugin_slots.d.ts

@@ -0,0 +1,26 @@
+/***
+ * The plugin slots a bare world carries, and the guard that fills them.
+ *
+ * What this file owns: the value a world puts in the member of a plugin it
+ * never installed, and the dev refusal of a facade member that would overwrite
+ * something the world already has.
+ *
+ * What it refuses: the `PluginHost` and every type that names a world. The
+ * surface guard takes the world as a plain object, so this module stays out of
+ * the type cycle that `plugin.ts` and `ecs.ts` share.
+ *
+ * Cold path. The slots are built once per process, and the guard runs once per
+ * plugin under a `__DEV__` build.
+ ***/
+export declare const MISSING_RELATIONS: object;
+export declare const MISSING_EVENTS: object;
+export declare const MISSING_WORKERS: object;
+/** The reserved `observe` slot. A function, because a caller calls it. */
+export declare function missingObserve(): never;
+/** Refuse a facade member that would overwrite something the world already
+ * carries. `Object.assign` is silent about it, and the loss is a method the
+ * world needs. The reserved slots are the exception: a bare world
+ * declares each one so it can name the missing plugin, and the
+ * plugin that fills the slot is meant to replace it. Dev-only. */
+export declare function assertPluginSurface(world: object, plugin: string, surface: object): void;
+//# sourceMappingURL=plugin_slots.d.ts.map

package/dist/core/ecs/plugin_slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin_slots.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/plugin_slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;KAaK;AAmCL,eAAO,MAAM,iBAAiB,EAAE,MAAuC,CAAC;AACxE,eAAO,MAAM,cAAc,EAAE,MAAoC,CAAC;AAClE,eAAO,MAAM,eAAe,EAAE,MAAqC,CAAC;AAapE,0EAA0E;AAC1E,wBAAgB,cAAc,IAAI,KAAK,CAEtC;AAED;;;;kEAIkE;AAClE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAaxF"}