@arcadible/sdk 1.1.0 → 1.2.0

package/dist/saves/backend/indexeddb.js

@@ -1,4 +1,5 @@
 // [import]
+import { ArcadibleError, Codes, log } from "../../bus/protocol.js";
 import { listenersByKey } from "./listeners.js";
 import { memoryBackend } from "./memory.js";
 // [declare]
@@ -12,9 +13,6 @@ const CHANNEL = "arcadible-saves";
 // every save is a guest's for One; a signed-in player's sit beside them
 // later, under their own id, with no migration.
 const GUEST = "guest";
-// how long opening may take before saves are kept in memory instead: some
-// browsers can leave an open hanging.
-const OPEN_TIMEOUT = 5000;
 // [function]
 function settle(request) {
     return new Promise((resolve, reject) => {
@@ -31,9 +29,10 @@ function finish(tx) {
     });
 }
 // [function]
-function open(factory, timeout) {
+// Opens the database, however long it takes: a slow open is waited for,
+// since the saves are late, not gone (the game's calls wait, or time out).
+function open(factory) {
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error("Opening IndexedDB timed out.")), timeout);
         const request = factory.open(DB_NAME, DB_VERSION);
         request.onupgradeneeded = () => {
             const db = request.result;
@@ -45,14 +44,8 @@ function open(factory, timeout) {
             saves.createIndex(BY_SCOPE, ["player", "game", "channel"]);
             db.createObjectStore(GAMES, { keyPath: ["player", "game", "channel"] });
         };
-        request.onsuccess = () => {
-            clearTimeout(timer);
-            resolve(request.result);
-        };
-        request.onerror = () => {
-            clearTimeout(timer);
-            reject(request.error);
-        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
     });
 }
 // [function]
@@ -69,8 +62,11 @@ function isClosed(err) {
 }
 // [function]
 // Saves kept in IndexedDB: the play page's, which every game shares, and a
-// game standing alone on its own origin. Where IndexedDB won't open, such as
-// some `file://` pages, they're kept in memory, and `status()` says so.
+// game standing alone on its own origin. Where there's no IndexedDB, or it
+// refuses to open (a browser blocking site data, some `file://` pages),
+// they're kept in memory, and `status()` says so. Once it has opened, it
+// never switches: a lost connection fails calls with `unavailable` until it
+// opens again, rather than show an empty copy.
 export function indexedDBBackend(options = {}) {
     const factory = options.factory === undefined
         ? (globalThis.indexedDB ?? null)
@@ -78,35 +74,64 @@ export function indexedDBBackend(options = {}) {
     const player = options.player ?? GUEST;
     const fallback = memoryBackend();
     const listeners = listenersByKey();
-    let status = "local";
+    // memory only when the first open fails; never once it has opened.
+    let status = "device";
+    let opened = false;
+    let current = null;
+    let opening = null;
     let asked = false;
     const keyOf = (scope) => `${player}\u0000${scope.game}\u0000${scope.channel}`;
     const rangeOf = (scope) => IDBKeyRange.only([player, scope.game, scope.channel]);
+    const lost = function (db) {
+        if (current === db)
+            current = null;
+    };
     const connect = async function () {
         try {
             if (!factory)
                 throw new Error("IndexedDB isn't available here.");
-            const db = await open(factory, options.openTimeout ?? OPEN_TIMEOUT);
+            const db = await open(factory);
             // a newer version of this page wants to upgrade: step aside.
-            db.onversionchange = () => db.close();
+            db.onversionchange = () => {
+                db.close();
+                lost(db);
+            };
+            // the browser closed it under us (Safari can).
+            db.onclose = () => lost(db);
             if (options.persist && !asked) {
                 asked = true;
                 globalThis.navigator?.storage?.persist?.().catch(() => false);
             }
+            opened = true;
+            current = db;
             return db;
         }
         catch (err) {
-            console.warn("arcadible: saves are kept in memory only:", err);
-            status = "ephemeral";
+            if (opened) {
+                log("warn", "the saves' storage couldn't be opened again.", err);
+                throw new ArcadibleError(Codes.Unavailable, "Saves can't be reached right now. Try again.");
+            }
+            log("warn", "this browser won't keep saves here, so they're kept in memory until the page closes.", err);
+            status = "memory";
             return null;
         }
+        finally {
+            opening = null;
+        }
+    };
+    // the database, opening it once however many ask; null in memory.
+    const database = function () {
+        if (status === "memory")
+            return Promise.resolve(null);
+        if (current)
+            return Promise.resolve(current);
+        opening ??= connect();
+        return opening;
     };
-    let opening = connect();
     // runs `op` on the database, opening it again once if it was closed, or
     // on the memory fallback when there's none.
     const run = async function (op, otherwise) {
-        const current = opening;
-        const db = await current;
+        const db = await database();
         if (!db)
             return otherwise();
         try {
@@ -115,13 +140,12 @@ export function indexedDBBackend(options = {}) {
         catch (err) {
             if (!isClosed(err))
                 throw err;
-            // once, however many operations found it closed.
-            if (opening === current)
-                opening = connect();
-            const again = await opening;
+            lost(db);
+            const again = await database();
             return again ? op(again) : otherwise();
         }
     };
+    database().catch(() => undefined);
     const broadcast = typeof BroadcastChannel === "undefined"
         ? null
         : new BroadcastChannel(CHANNEL);
@@ -218,7 +242,8 @@ export function indexedDBBackend(options = {}) {
         },
         close() {
             broadcast?.close();
-            opening.then((db) => db?.close()).catch(() => undefined);
+            current?.close();
+            opening?.then((db) => db?.close()).catch(() => undefined);
         },
     };
 }

package/dist/saves/backend/listeners.js

@@ -1,4 +1,5 @@
 // [import]
+import { log } from "../../bus/protocol.js";
 // [function]
 // Each game's subscribers, by key, for a backend to tell of changes. Each
 // gets its own copy, so one can't change what the next one sees, and one
@@ -25,7 +26,7 @@ export function listenersByKey() {
                     listener(structuredClone(change), source);
                 }
                 catch (err) {
-                    console.error("arcadible: a change's listener failed:", err);
+                    log("error", "a change's listener failed.", err);
                 }
             }
         },

package/dist/saves/backend/memory.d.ts

@@ -1,7 +1,7 @@
-import type { SaveStatus } from "../rules.js";
+import type { BackendStatus } from "../rules.js";
 import type { Backend, Scope } from "./types.js";
 export declare function memoryBackend({ status, }?: {
-    status?: SaveStatus;
+    status?: BackendStatus;
 }): Backend & {
     used(scope: Scope): string | undefined;
 };

package/dist/saves/backend/memory.js

@@ -5,10 +5,11 @@ function keyOf(scope) {
     return `${scope.game}\u0000${scope.channel}`;
 }
 // [function]
-// Saves kept in memory, for tests, `arc preview`, and wherever IndexedDB
+// Saves kept in memory, for tests, and wherever IndexedDB
 // won't open. Hosts sharing one act like tabs sharing a device. Its saves
-// last as long as the page, so it says `ephemeral`.
-export function memoryBackend({ status = "ephemeral", } = {}) {
+// last as long as the page, so it says `memory`; tests pretend it's a
+// device's with `device`.
+export function memoryBackend({ status = "memory", } = {}) {
     const games = new Map();
     const listeners = listenersByKey();
     const gameOf = function (scope) {

package/dist/saves/backend/types.d.ts

@@ -1,4 +1,4 @@
-import type { SaveStatus } from "../rules.js";
+import type { BackendStatus } from "../rules.js";
 export type Scope = {
     game: string;
     channel: string;
@@ -18,7 +18,7 @@ export type Change = {
     revision: number;
 };
 export interface Backend {
-    status(): SaveStatus;
+    status(): BackendStatus;
     list(scope: Scope): Promise<SaveRecord[]>;
     get(scope: Scope, name: string): Promise<SaveRecord | null>;
     change(scope: Scope, name: string, decide: (saves: SaveRecord[]) => NewRecord | null, source: string): Promise<Change | null>;

package/dist/saves/client.d.ts

@@ -1,12 +1,30 @@
-import type { Bus } from "../bus/client.js";
-import { type SaveInfo } from "./rules.js";
+import { type Bus } from "../bus/client.js";
+import { type SaveInfo, type Where } from "./rules.js";
+/** `arcadible.saves`: each save is a name holding one string. */
 export interface Saves {
+    /** Keeps `data` as the save `name`, replacing what it held. */
     write(name: string, data: string): Promise<SaveInfo>;
+    /** The save's string, or `null` when there's none. */
     read(name: string): Promise<string | null>;
+    /** The names of the game's saves, sorted. */
     list(): Promise<string[]>;
+    /** Which version wrote the save, and when, or `null` when there's none. */
     info(name: string): Promise<SaveInfo | null>;
+    /** Removes the save, if there is one. */
     remove(name: string): Promise<void>;
+    /** After `ready`, the save's string from memory; before it, throws `not_ready`. */
     readSync(name: string): string | null;
+    /** After `ready`, the names of the game's saves from memory, sorted. */
+    listSync(): string[];
+    /** After `ready`, the save's version and time from memory, or `null`. */
+    infoSync(name: string): SaveInfo | null;
+    /**
+     * Who can read the saves back, once `ready` has settled: `"game"` (every
+     * version of the game), `"build"` (only this build), or `"memory"` (only
+     * until the page closes). `undefined` until it's known. Other values may
+     * be added: treat one you don't know as `"game"`.
+     */
+    readonly where: Where | undefined;
 }
 export declare function createSaves(bus: Bus, { timeout }: {
     timeout: number;

package/dist/saves/client.js

@@ -1,11 +1,12 @@
 // Saves, the game's side: `arcadible.saves`, and its memory copy of the
 // game's saves, so reads after `ready` answer at once.
-import { ArcadibleError, Codes, utf8Size } from "../bus/protocol.js";
-import { checkName, checkWrite, } from "./rules.js";
+// [import]
+import { mayHaveLanded } from "../bus/client.js";
+import { ArcadibleError, buildOf, Codes, isStringArray, isStringOrNull, log, utf8Size, } from "../bus/protocol.js";
+import { checkName, checkWrite, isRevisionOrNull, isSaveInfoOrNull, isSaveMeta, isSavesChange, isSavesLoad, } from "./rules.js";
 // [function]
-// a call that failed this way may still have been kept by the page.
-function mayHaveLanded(err) {
-    return err instanceof ArcadibleError && err.code === Codes.Timeout;
+function isAnything(_value) {
+    return true;
 }
 // [function]
 function infoOf(meta) {
@@ -20,11 +21,17 @@ export function createSaves(bus, { timeout }) {
     let settled = false;
     // whether the memory copy holds the game's saves.
     let loaded = false;
+    let where;
     let version = null;
     const mirror = new Map();
     // the newest revision seen of each save, removals included.
     const revisions = new Map();
     const early = [];
+    // the newest write of each save, until the page answers it: an older
+    // write's answer, merged with it or ahead of it, mustn't replace it in
+    // the memory copy.
+    const writing = new Map();
+    let writes = 0;
     let open = () => undefined;
     const opened = new Promise((resolve) => {
         open = () => {
@@ -52,6 +59,14 @@ export function createSaves(bus, { timeout }) {
         kept(name, revision, save);
     };
     // [function]
+    // the answer to a write or remove that timed out, once it comes: the
+    // page did keep it, so the memory copy takes it, unless a newer write of
+    // the save is waiting, whose answer will be newer still.
+    const landed = function (name, revision, save) {
+        if (!writing.has(name))
+            kept(name, revision, save);
+    };
+    // [function]
     const restore = function (name, previous) {
         if (previous)
             mirror.set(name, previous);
@@ -72,131 +87,160 @@ export function createSaves(bus, { timeout }) {
         }
     };
     // [function]
-    const request = async function (name, params) {
-        await opened;
-        return bus.request(name, params);
+    // runs `call` once `ready` has settled: at once when it has, so a write
+    // changes the memory copy in the same tick, and a `readSync` right after
+    // it sees the save.
+    const whenOpened = function (call) {
+        return settled ? call() : opened.then(call);
+    };
+    // [function]
+    const send = function (name, data) {
+        // before the saves have loaded, only the name and document can be
+        // checked here; the page checks the rest once they have.
+        const optimistic = loaded;
+        const refused = checkWrite(optimistic ? mirror : new Map(), name, data);
+        if (refused)
+            return Promise.reject(refused);
+        // the memory copy changes at once, so the next read sees it; the
+        // promise settles once the page has kept it.
+        const previous = mirror.get(name);
+        const ticket = ++writes;
+        writing.set(name, ticket);
+        if (optimistic) {
+            mirror.set(name, {
+                name,
+                data,
+                info: {
+                    version,
+                    savedAt: new Date().toISOString(),
+                    size: utf8Size(data),
+                    revision: previous?.info.revision ?? 0,
+                },
+            });
+        }
+        const save = (meta) => ({ name, data, info: meta });
+        return bus
+            .request("saves.write", { name, data }, isSaveMeta, {
+            late: (meta) => landed(name, meta.revision, save(meta)),
+        })
+            .then((meta) => {
+            if (writing.get(name) === ticket) {
+                writing.delete(name);
+                kept(name, meta.revision, save(meta));
+            }
+            return infoOf(meta);
+        }, (err) => {
+            if (writing.get(name) === ticket)
+                writing.delete(name);
+            // one the page refused is rolled back, unless something newer
+            // replaced it meanwhile; one it may have kept stays.
+            if (optimistic &&
+                !mayHaveLanded(err) &&
+                mirror.get(name)?.data === data) {
+                restore(name, previous);
+            }
+            throw err;
+        });
+    };
+    // [function]
+    const erase = function (name) {
+        const optimistic = loaded;
+        const previous = mirror.get(name);
+        if (optimistic)
+            mirror.delete(name);
+        return bus
+            .request("saves.remove", { name }, isRevisionOrNull, {
+            late: (revision) => {
+                if (revision !== null)
+                    landed(name, revision, null);
+            },
+        })
+            .then((revision) => {
+            if (revision !== null)
+                kept(name, revision, null);
+        }, (err) => {
+            if (optimistic && !mayHaveLanded(err) && !mirror.has(name)) {
+                restore(name, previous);
+            }
+            throw err;
+        });
     };
     // [start]
     let timer;
-    bus.on("saves.load", (data) => {
+    // the load is checked here, not by the bus, so even a malformed one
+    // settles `ready` at once: the saves didn't load, and the sync reads say so.
+    bus.on("saves.load", isAnything, (load) => {
         if (loaded)
             return;
         clearTimeout(timer);
-        const load = data;
-        try {
-            if (!load?.error && Array.isArray(load?.items)) {
-                for (const save of load.items) {
-                    mirror.set(save.name, save);
-                    revisions.set(save.name, save.info.revision);
-                }
-                loaded = true;
-                for (const change of early.splice(0))
-                    apply(change);
-            }
+        if (!isSavesLoad(load)) {
+            log("warn", "the play page sent saves the game couldn't read.");
+            open();
+            return;
         }
-        finally {
-            // even a malformed load settles `ready`.
+        if (load.error) {
             open();
+            return;
+        }
+        for (const save of load.items) {
+            mirror.set(save.name, save);
+            revisions.set(save.name, save.info.revision);
         }
+        loaded = true;
+        where = typeof load.where === "string" ? load.where : undefined;
+        for (const change of early.splice(0))
+            apply(change);
+        open();
     });
-    bus.on("saves.change", (data) => {
+    bus.on("saves.change", isSavesChange, (change) => {
         // one that comes before the saves is kept until they do.
         if (loaded)
-            apply(data);
+            apply(change);
         else
-            early.push(data);
+            early.push(change);
     });
     bus.welcomed.then((welcome) => {
-        version = welcome.build?.version ?? null;
+        version = buildOf(welcome.build)?.version ?? null;
         // the memory copy doesn't pretend to be empty while the saves are late:
         // a game that took that for "no save yet" could start over, and
         // overwrite the player's progress once they arrived.
         if (!settled) {
             timer = setTimeout(() => {
-                console.warn("arcadible: the game's saves haven't arrived yet.");
+                if (!loaded) {
+                    log("warn", "the game's saves haven't arrived yet, so the sync reads throw unavailable until they do.");
+                }
                 open();
             }, timeout);
         }
     });
     const saves = {
-        async write(name, data) {
-            await opened;
-            // before the saves have loaded, only the name and document can be
-            // checked here; the page checks the rest once they have.
-            const optimistic = loaded;
-            const refused = checkWrite(optimistic ? mirror : new Map(), name, data);
-            if (refused)
-                throw refused;
-            // the memory copy changes at once, so the next read sees it; the
-            // promise settles once the page has kept it.
-            const previous = mirror.get(name);
-            if (optimistic) {
-                mirror.set(name, {
-                    name,
-                    data,
-                    info: {
-                        version,
-                        savedAt: new Date().toISOString(),
-                        size: utf8Size(data),
-                        revision: previous?.info.revision ?? 0,
-                    },
-                });
-            }
-            try {
-                const meta = (await bus.request("saves.write", {
-                    name,
-                    data,
-                }));
-                kept(name, meta.revision, { name, data, info: meta });
-                return infoOf(meta);
-            }
-            catch (err) {
-                // one the page refused is rolled back, unless something newer
-                // replaced it meanwhile.
-                if (optimistic &&
-                    !mayHaveLanded(err) &&
-                    mirror.get(name)?.data === data) {
-                    restore(name, previous);
-                }
-                throw err;
-            }
+        write(name, data) {
+            return whenOpened(() => send(name, data));
         },
         async read(name) {
             const refused = checkName(name);
             if (refused)
                 throw refused;
-            return (await request("saves.read", { name }));
+            await opened;
+            return bus.request("saves.read", { name }, isStringOrNull);
         },
         async list() {
-            return (await request("saves.list"));
+            await opened;
+            return bus.request("saves.list", undefined, isStringArray);
         },
         async info(name) {
             const refused = checkName(name);
             if (refused)
                 throw refused;
-            const meta = (await request("saves.info", { name }));
+            await opened;
+            const meta = await bus.request("saves.info", { name }, isSaveInfoOrNull);
             return meta ? infoOf(meta) : null;
         },
         async remove(name) {
             const refused = checkName(name);
             if (refused)
                 throw refused;
-            await opened;
-            const optimistic = loaded;
-            const previous = mirror.get(name);
-            if (optimistic)
-                mirror.delete(name);
-            try {
-                const revision = (await bus.request("saves.remove", { name }));
-                if (revision !== null)
-                    kept(name, revision, null);
-            }
-            catch (err) {
-                if (optimistic && !mayHaveLanded(err) && !mirror.has(name)) {
-                    restore(name, previous);
-                }
-                throw err;
-            }
+            return whenOpened(() => erase(name));
         },
         readSync(name) {
             assertLoaded();
@@ -205,6 +249,21 @@ export function createSaves(bus, { timeout }) {
                 throw refused;
             return mirror.get(name)?.data ?? null;
         },
+        listSync() {
+            assertLoaded();
+            return [...mirror.keys()].sort();
+        },
+        infoSync(name) {
+            assertLoaded();
+            const refused = checkName(name);
+            if (refused)
+                throw refused;
+            const save = mirror.get(name);
+            return save ? infoOf(save.info) : null;
+        },
+        get where() {
+            return where;
+        },
     };
     return { saves, opened };
 }

package/dist/saves/rules.d.ts

@@ -1,9 +1,22 @@
 import { ArcadibleError } from "../bus/protocol.js";
 export declare const MAX_SAVES = 32;
 export declare const MAX_TOTAL: number;
-export type SaveStatus = "local" | "ephemeral";
+/**
+ * Who can read the saves back: every version of the game (`"game"`), only
+ * this build (`"build"`), or only until the page closes (`"memory"`). Other
+ * values may be added, such as `"account"`: a game treats one it doesn't
+ * know as `"game"`.
+ */
+export type Where = "game" | "build" | "memory" | (string & {});
+export type BackendStatus = "device" | "memory";
+/** What a game is told of a save. */
 export type SaveInfo = {
+    /**
+     * The game's version that wrote it, stamped by the page; `null` when it
+     * was written standing alone, where there's no version to stamp.
+     */
     version: string | null;
+    /** When it was written, as an ISO 8601 time. */
     savedAt: string;
 };
 export type SaveMeta = SaveInfo & {
@@ -16,7 +29,7 @@ export type Save = {
     info: SaveMeta;
 };
 export type SavesLoad = {
-    status: SaveStatus;
+    where?: Where;
     items: Save[];
     error?: {
         code: string;
@@ -32,3 +45,9 @@ export declare function checkName(name: unknown): ArcadibleError | null;
 export declare function checkWrite(saves: ReadonlyMap<string, {
     info: SaveMeta;
 }>, name: unknown, data: unknown): ArcadibleError | null;
+export declare function isSaveMeta(value: unknown): value is SaveMeta;
+export declare function isSaveInfoOrNull(value: unknown): value is SaveInfo | null;
+export declare function isSave(value: unknown): value is Save;
+export declare function isSavesLoad(value: unknown): value is SavesLoad;
+export declare function isSavesChange(value: unknown): value is SavesChange;
+export declare function isRevisionOrNull(value: unknown): value is number | null;

package/dist/saves/rules.js

@@ -1,7 +1,7 @@
 // Saves' rules, shared by the game's side and the page's so they can't drift
 // apart: the shapes, the limits, and their checks (DESIGN.md, section 6).
 // [import]
-import { ArcadibleError, Codes, utf8Size } from "../bus/protocol.js";
+import { ArcadibleError, Codes, isNumber, isObject, isStringOrNull, utf8Size, } from "../bus/protocol.js";
 // [declare]
 // Saves' limits, the same everywhere (DESIGN.md, section 6, Limits).
 export const MAX_SAVES = 32;
@@ -47,3 +47,48 @@ export function checkWrite(saves, name, data) {
     }
     return null;
 }
+// [function]
+// What the page sends of a save, checked for only what a game relies on
+// (DESIGN.md, The host is never trusted): extra fields pass.
+export function isSaveMeta(value) {
+    return (isObject(value) &&
+        isStringOrNull(value["version"]) &&
+        typeof value["savedAt"] === "string" &&
+        isNumber(value["size"]) &&
+        isNumber(value["revision"]));
+}
+// [function]
+export function isSaveInfoOrNull(value) {
+    return (value === null ||
+        (isObject(value) &&
+            isStringOrNull(value["version"]) &&
+            typeof value["savedAt"] === "string"));
+}
+// [function]
+export function isSave(value) {
+    return (isObject(value) &&
+        checkName(value["name"]) === null &&
+        typeof value["data"] === "string" &&
+        isSaveMeta(value["info"]));
+}
+// [function]
+// A load the memory copy can take whole: every save readable, or none.
+export function isSavesLoad(value) {
+    return (isObject(value) &&
+        Array.isArray(value["items"]) &&
+        (value["error"] !== undefined || value["items"].every(isSave)));
+}
+// [function]
+export function isSavesChange(value) {
+    if (!isObject(value) ||
+        checkName(value["name"]) !== null ||
+        !isNumber(value["revision"])) {
+        return false;
+    }
+    const save = value["save"];
+    return save === null || (isSave(save) && save.name === value["name"]);
+}
+// [function]
+export function isRevisionOrNull(value) {
+    return value === null || isNumber(value);
+}

package/dist/saves/server.d.ts

@@ -1,8 +1,10 @@
 import type { Module, ModuleContext } from "../bus/server.js";
 import type { Backend, Scope } from "./backend/types.js";
+import { type Where } from "./rules.js";
 type SavesServerOptions = {
     scope: Scope;
     version: string | null;
+    where: Where;
     backend: Backend;
     now: () => Date;
 };