@arcadible/sdk 1.5.0 → 1.5.1

package/README.md

@@ -68,13 +68,11 @@ Off Arcadible, such as on your dev server, the package still works, with the sam
 
 ```js
 arcadible.on("pause", async () => {
-  loop.stop();
-  audio.mute();
+  // … stop your game loop and timers, and silence your audio …
   await arcadible.saves.write("progress", JSON.stringify(progress));
 });
 arcadible.on("resume", () => {
-  loop.start();
-  audio.unmute();
+  // … start your game loop and timers again, and your audio …
 });
 ```
 

package/dist/client.js

@@ -33,28 +33,36 @@ export function createClient(options = {}) {
         requestTimeout: options.requestTimeout,
         standalone: () => serve({ ...STANDALONE, backend: backend() }),
     });
-    const { saves, opened } = createSaves(bus, {
+    // each module's game side, made on the bus as the client starts, before
+    // anything arrives.
+    const saves = createSaves(bus, {
         timeout: options.requestTimeout ?? REQUEST_TIMEOUT,
     });
-    let settled = null;
     const system = createSystemClient(bus);
     const context = createContextClient(bus);
-    // ready once welcomed, and each module's first messages have arrived.
-    const ready = Promise.all([bus.welcomed, opened]).then(([welcome]) => {
-        system.settle();
-        context.settle();
+    const lifecycle = createLifecycle(bus, win);
+    const pause = createPause(bus);
+    // the ones `ready` waits on, or tells: lifecycle and pause do neither.
+    const parts = [saves, system, context];
+    let settled = null;
+    // ready once welcomed, and each module's first messages have arrived;
+    // then each is told, so its facts are known, or null.
+    const ready = Promise.all([
+        bus.welcomed,
+        ...parts.map((part) => part.opened),
+    ]).then(([welcome]) => {
+        for (const part of parts)
+            part.settle?.();
         settled = { build: buildOf(welcome.build) };
         return settled;
     });
-    const lifecycle = createLifecycle(bus, win);
-    const pause = createPause(bus);
     return {
         version: VERSION,
         ready,
         get build() {
             return settled ? settled.build : undefined;
         },
-        saves,
+        saves: saves.saves,
         get system() {
             return system.value;
         },

package/dist/context/client.d.ts

@@ -1,4 +1,5 @@
 import type { Bus } from "../bus/client.js";
+import { type Fact } from "../facts.js";
 /** How this run started, fixed for the run. */
 export interface Context {
     readonly launch: {
@@ -6,7 +7,4 @@ export interface Context {
         readonly at: string;
     };
 }
-export declare function createContextClient(bus: Bus): {
-    settle(): void;
-    readonly value: Context | null | undefined;
-};
+export declare function createContextClient(bus: Bus): Fact<Context>;

package/dist/context/client.js

@@ -1,31 +1,17 @@
 // The game's side of `context`: `arcadible.context`, how this run started,
 // fixed for the run. `undefined` before `ready`, and `null` where no page
 // says (standing alone, or an older page).
-import { isObject, log } from "../bus/protocol.js";
+import { fact } from "../facts.js";
 import { contextOf, Names } from "./rules.js";
 // [function]
 export function createContextClient(bus) {
-    let context = null;
-    let settled = false;
-    bus.on(Names.State, isObject, (data) => {
-        // fixed for the run: the first one stands, and none comes after `ready`.
-        if (context || settled)
-            return;
-        const next = contextOf(data);
-        if (!next) {
-            log("warn", "ignored a malformed context from the play page.");
-            return;
-        }
-        context = Object.freeze({ launch: Object.freeze({ ...next.launch }) });
-    });
-    return {
-        settle() {
-            settled = true;
-        },
-        get value() {
-            if (!settled)
-                return undefined;
-            return context;
+    return fact(bus, Names.State, {
+        fixed: true,
+        parse(data) {
+            const context = contextOf(data);
+            return context
+                ? Object.freeze({ launch: Object.freeze({ ...context.launch }) })
+                : null;
         },
-    };
+    });
 }

package/dist/facts.d.ts

@@ -0,0 +1,11 @@
+import type { Bus } from "./bus/client.js";
+export type Fact<T> = {
+    settle(): void;
+    readonly value: T | null | undefined;
+};
+export type FactOptions<T> = {
+    parse(value: unknown): T | null;
+    fixed?: boolean;
+    changed?(before: T, next: T): void;
+};
+export declare function fact<T>(bus: Bus, name: string, options: FactOptions<T>): Fact<T>;

package/dist/facts.js

@@ -0,0 +1,33 @@
+// A fact the page sends as its module opens, such as `system`'s state or
+// `context`: `undefined` before `ready`, the fact from then on, or `null`
+// where no page sent one (standing alone, or an older page). Only what
+// `parse` keeps is kept, so the host is trusted with nothing; a fixed fact
+// takes its first and nothing after `ready`, and a changing one tells
+// `changed` what came after it.
+import { isObject, log } from "./bus/protocol.js";
+// [function]
+export function fact(bus, name, options) {
+    let value = null;
+    let settled = false;
+    bus.on(name, isObject, (data) => {
+        if (options.fixed && (value !== null || settled))
+            return;
+        const next = options.parse(data);
+        if (next === null) {
+            log("warn", `ignored a malformed ${name} from the play page.`);
+            return;
+        }
+        const before = value;
+        value = next;
+        if (before !== null && settled)
+            options.changed?.(before, next);
+    });
+    return {
+        settle() {
+            settled = true;
+        },
+        get value() {
+            return settled ? value : undefined;
+        },
+    };
+}

package/dist/lifecycle/pause.d.ts

@@ -1,7 +1,5 @@
 import type { Bus } from "../bus/client.js";
-export type PauseListener = () => void | Promise<void>;
-export type ResumeListener = () => void;
 export type Pause = {
-    on(name: string, listener: unknown): () => void;
+    on(name: unknown, listener: unknown): () => void;
 };
 export declare function createPause(bus: Bus): Pause;

package/dist/lifecycle/pause.js

@@ -3,11 +3,9 @@
 // why; this side keeps that from the moment it connects, so a game that
 // subscribes while held still gets its pause, and tells the page once its
 // pause listeners have settled, which the page waits on only as it closes.
-import { ArcadibleError, Codes, isObject, log } from "../bus/protocol.js";
+import { isObject, log } from "../bus/protocol.js";
+import { listeners } from "../listeners.js";
 import { Names } from "./rules.js";
-// the events a game can listen for on `arcadible`: a closed list, so a typo
-// throws rather than never firing.
-const EVENTS = ["pause", "resume"];
 // [function]
 function isHeld(value) {
     return (isObject(value) &&
@@ -22,21 +20,14 @@ export function createPause(bus) {
     // whether the game heard this hold's pause: a resume goes only to a game
     // that did, so it never resumes from a pause it wasn't told of.
     let heard = false;
-    const pauses = new Set();
-    const resumes = new Set();
-    // runs pause listeners, each on its own, and tells the page once they've
-    // all settled, for pause `count`.
-    const pause = function (listeners, count) {
-        if (listeners.length > 0)
+    // the events a game can listen for on `arcadible`.
+    const on = listeners("arcadible", ["pause", "resume"]);
+    // runs pause listeners, and tells the page once they've all settled, for
+    // pause `count`.
+    const pause = function (run, count) {
+        const runs = run().map((result) => Promise.resolve(result));
+        if (runs.length > 0)
             heard = true;
-        const runs = listeners.map((listener) => {
-            try {
-                return Promise.resolve(listener());
-            }
-            catch (err) {
-                return Promise.reject(err);
-            }
-        });
         void Promise.allSettled(runs).then((results) => {
             for (const result of results) {
                 if (result.status === "rejected") {
@@ -46,45 +37,23 @@ export function createPause(bus) {
             bus.emit(Names.Paused, { n: count });
         });
     };
-    const resume = function () {
-        for (const listener of [...resumes]) {
-            try {
-                listener();
-            }
-            catch (err) {
-                log("error", "a resume listener failed.", err);
-            }
-        }
-    };
     bus.on(Names.Held, isHeld, (data) => {
         const was = held;
         held = data.held;
         n = data.n;
         if (held && !was)
-            pause([...pauses], n);
+            pause(() => on.call("pause"), n);
         else if (!held && was) {
             if (heard)
-                resume();
+                on.call("resume");
             heard = false;
         }
     });
     return {
         on(name, listener) {
-            if (!EVENTS.includes(name)) {
-                throw new ArcadibleError(Codes.Invalid, `arcadible.on takes "pause" or "resume", not ${JSON.stringify(name)}.`);
-            }
-            if (typeof listener !== "function") {
-                throw new ArcadibleError(Codes.Invalid, `arcadible.on("${name}") takes a function.`);
-            }
-            if (name === "resume") {
-                const fn = listener;
-                resumes.add(fn);
-                return () => {
-                    resumes.delete(fn);
-                };
-            }
-            const fn = listener;
-            pauses.add(fn);
+            const off = on.add(name, listener);
+            if (name !== "pause")
+                return off;
             if (!told) {
                 told = true;
                 bus.emit(Names.Listening);
@@ -94,13 +63,20 @@ export function createPause(bus) {
             if (held) {
                 const count = n;
                 queueMicrotask(() => {
-                    if (held && n === count && pauses.has(fn))
-                        pause([fn], count);
+                    if (held && n === count && on.has("pause", listener)) {
+                        pause(() => {
+                            try {
+                                return [listener()];
+                            }
+                            catch (err) {
+                                log("error", "a pause listener failed.", err);
+                                return [undefined];
+                            }
+                        }, count);
+                    }
                 });
             }
-            return () => {
-                pauses.delete(fn);
-            };
+            return off;
         },
     };
 }

package/dist/listeners.d.ts

@@ -0,0 +1,13 @@
+type Listener = (...args: never[]) => unknown;
+export type Listeners<N extends string> = {
+    add(name: unknown, listener: unknown): () => void;
+    of(name: N): Listener[];
+    has(name: N, listener: unknown): boolean;
+    call(name: N, ...args: unknown[]): unknown[];
+};
+/**
+ * The listeners for `names` on the object a game calls as `where`
+ * (`"arcadible"`, `"arcadible.system"`).
+ */
+export declare function listeners<N extends string>(where: string, names: readonly N[]): Listeners<N>;
+export {};

package/dist/listeners.js

@@ -0,0 +1,48 @@
+// The listeners behind every `on` a game calls (`arcadible.on`,
+// `arcadible.system.on`): a closed list of names, so a typo throws rather
+// than never firing; a listener that must be a function; the function that
+// unsubscribes; and each listener run on its own, so one that throws stops
+// none of the others. One shape for each, with the same messages.
+// [import]
+import { ArcadibleError, Codes, log } from "./bus/protocol.js";
+// [function]
+/**
+ * The listeners for `names` on the object a game calls as `where`
+ * (`"arcadible"`, `"arcadible.system"`).
+ */
+export function listeners(where, names) {
+    const sets = new Map(names.map((name) => [name, new Set()]));
+    const list = names.map((name) => JSON.stringify(name)).join(" or ");
+    const of = (name) => [...(sets.get(name) ?? [])];
+    return {
+        add(name, listener) {
+            const set = sets.get(name);
+            if (!set) {
+                throw new ArcadibleError(Codes.Invalid, `${where}.on takes ${list}, not ${JSON.stringify(name)}.`);
+            }
+            if (typeof listener !== "function") {
+                throw new ArcadibleError(Codes.Invalid, `${where}.on(${JSON.stringify(name)}) takes a function.`);
+            }
+            const fn = listener;
+            set.add(fn);
+            return () => {
+                set.delete(fn);
+            };
+        },
+        of,
+        has(name, listener) {
+            return sets.get(name)?.has(listener) ?? false;
+        },
+        call(name, ...args) {
+            return of(name).map((fn) => {
+                try {
+                    return fn(...args);
+                }
+                catch (err) {
+                    log("error", `a ${name} listener failed.`, err);
+                    return undefined;
+                }
+            });
+        },
+    };
+}

package/dist/system/client.d.ts

@@ -1,4 +1,5 @@
 import type { Bus } from "../bus/client.js";
+import { type Fact } from "../facts.js";
 /** Arcadible's state for the player, which changes while the game runs. */
 export interface System {
     /**
@@ -14,7 +15,4 @@ export interface System {
      */
     on(name: "change", listener: (system: System, changed: readonly string[]) => void): () => void;
 }
-export declare function createSystemClient(bus: Bus): {
-    settle(): void;
-    readonly value: System | null | undefined;
-};
+export declare function createSystemClient(bus: Bus): Fact<System>;

package/dist/system/client.js

@@ -2,61 +2,36 @@
 // player, read at any time, with one `change` event naming what changed.
 // `undefined` before `ready`, and `null` where no page says (standing
 // alone, or an older page).
-import { ArcadibleError, Codes, isObject, log } from "../bus/protocol.js";
+import { fact } from "../facts.js";
+import { listeners } from "../listeners.js";
 import { Names, stateOf } from "./rules.js";
 // [function]
 export function createSystemClient(bus) {
-    let state = null;
-    let settled = false;
-    const listeners = new Set();
+    // the events a game can listen for on `arcadible.system`.
+    const on = listeners("arcadible.system", ["change"]);
+    const kept = fact(bus, Names.State, {
+        parse: stateOf,
+        changed(before, next) {
+            const changed = Object.keys(next).filter((key) => next[key] !== before[key]);
+            if (changed.length > 0)
+                on.call("change", system, changed);
+        },
+    });
+    // one object for the run: what a game holds, and what `change` passes,
+    // reads the state as it is now.
     const system = {
         get language() {
-            return state.language;
-        },
-        on(name, listener) {
-            if (name !== "change") {
-                throw new ArcadibleError(Codes.Invalid, `arcadible.system.on takes "change", not ${JSON.stringify(name)}.`);
-            }
-            if (typeof listener !== "function") {
-                throw new ArcadibleError(Codes.Invalid, 'arcadible.system.on("change") takes a function.');
-            }
-            const fn = listener;
-            listeners.add(fn);
-            return () => {
-                listeners.delete(fn);
-            };
+            return kept.value.language;
         },
+        on: (name, listener) => on.add(name, listener),
     };
-    bus.on(Names.State, isObject, (data) => {
-        const next = stateOf(data);
-        if (!next) {
-            log("warn", "ignored a malformed system state from the play page.");
-            return;
-        }
-        const before = state;
-        state = next;
-        if (!before || !settled)
-            return;
-        const changed = Object.keys(next).filter((key) => next[key] !== before[key]);
-        if (changed.length === 0)
-            return;
-        for (const listener of [...listeners]) {
-            try {
-                listener(system, changed);
-            }
-            catch (err) {
-                log("error", "a system change listener failed.", err);
-            }
-        }
-    });
     return {
-        settle() {
-            settled = true;
-        },
+        settle: () => kept.settle(),
         get value() {
-            if (!settled)
+            const value = kept.value;
+            if (value === undefined)
                 return undefined;
-            return state ? system : null;
+            return value === null ? null : system;
         },
     };
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.5.0";
+export declare const VERSION = "1.5.1";

package/dist/version.js

@@ -1,3 +1,3 @@
 // The client's version, sent in its hello and shown as `arcadible.version`,
 // for bug reports. It matches package.json (test/unit/protocol.test.ts).
-export const VERSION = "1.5.0";
+export const VERSION = "1.5.1";

package/package.json

@@ -43,5 +43,5 @@
   ],
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "1.5.0"
+  "version": "1.5.1"
 }