@arcadible/sdk 0.0.0-stage → 0.3.0

package/dist/saves/backend/types.js

@@ -0,0 +1,2 @@
+// [import]
+export {};

package/dist/saves/client.d.ts

@@ -0,0 +1,16 @@
+import type { Bus } from "../bus/client.js";
+import { type SaveInfo } from "./rules.js";
+export interface Saves {
+    write(name: string, data: string): Promise<SaveInfo>;
+    read(name: string): Promise<string | null>;
+    list(): Promise<string[]>;
+    info(name: string): Promise<SaveInfo | null>;
+    remove(name: string): Promise<void>;
+    readSync(name: string): string | null;
+}
+export declare function createSaves(bus: Bus, { timeout }: {
+    timeout: number;
+}): {
+    saves: Saves;
+    opened: Promise<void>;
+};

package/dist/saves/client.js

@@ -0,0 +1,210 @@
+// 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";
+// [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]
+function infoOf(meta) {
+    return { version: meta.version, savedAt: meta.savedAt };
+}
+// [function]
+// The saves module on `bus`. `opened` settles once the game's saves have
+// arrived, the channel's first message, or after `timeout` if they haven't,
+// since `ready` never fails.
+export function createSaves(bus, { timeout }) {
+    // whether `opened` has settled: the sync calls answer from then.
+    let settled = false;
+    // whether the memory copy holds the game's saves.
+    let loaded = false;
+    let version = null;
+    const mirror = new Map();
+    // the newest revision seen of each save, removals included.
+    const revisions = new Map();
+    const early = [];
+    let open = () => undefined;
+    const opened = new Promise((resolve) => {
+        open = () => {
+            settled = true;
+            resolve();
+        };
+    });
+    // [function]
+    // what the page kept for `name`, unless a newer change got there first:
+    // changes can arrive out of order. Whether it was newer.
+    const kept = function (name, revision, save) {
+        if (revision <= (revisions.get(name) ?? 0))
+            return false;
+        revisions.set(name, revision);
+        if (save)
+            mirror.set(name, save);
+        else
+            mirror.delete(name);
+        return true;
+    };
+    // [function]
+    // another tab's change (later, another device's): the memory copy keeps
+    // up, so the next read sees it.
+    const apply = function ({ name, save, revision }) {
+        kept(name, revision, save);
+    };
+    // [function]
+    const restore = function (name, previous) {
+        if (previous)
+            mirror.set(name, previous);
+        else
+            mirror.delete(name);
+    };
+    // [function]
+    const assertReady = function () {
+        if (!settled) {
+            throw new ArcadibleError(Codes.NotReady, "Saves aren't loaded yet. Wait for arcadible.ready first.");
+        }
+    };
+    // [function]
+    const assertLoaded = function () {
+        assertReady();
+        if (!loaded) {
+            throw new ArcadibleError(Codes.Unavailable, "Saves haven't loaded yet. Try again, or use the async calls.");
+        }
+    };
+    // [function]
+    const request = async function (name, params) {
+        await opened;
+        return bus.request(name, params);
+    };
+    // [start]
+    let timer;
+    bus.on("saves.load", (data) => {
+        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);
+            }
+        }
+        finally {
+            // even a malformed load settles `ready`.
+            open();
+        }
+    });
+    bus.on("saves.change", (data) => {
+        // one that comes before the saves is kept until they do.
+        if (loaded)
+            apply(data);
+        else
+            early.push(data);
+    });
+    bus.welcomed.then((welcome) => {
+        version = 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.");
+                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;
+            }
+        },
+        async read(name) {
+            const refused = checkName(name);
+            if (refused)
+                throw refused;
+            return (await request("saves.read", { name }));
+        },
+        async list() {
+            return (await request("saves.list"));
+        },
+        async info(name) {
+            const refused = checkName(name);
+            if (refused)
+                throw refused;
+            const meta = (await request("saves.info", { name }));
+            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;
+            }
+        },
+        readSync(name) {
+            assertLoaded();
+            const refused = checkName(name);
+            if (refused)
+                throw refused;
+            return mirror.get(name)?.data ?? null;
+        },
+    };
+    return { saves, opened };
+}

package/dist/saves/rules.d.ts

@@ -0,0 +1,35 @@
+import { ArcadibleError } from "../bus/protocol.js";
+export declare const MAX_SAVES = 32;
+export declare const MAX_TOTAL: number;
+export type SaveStatus = "local" | "ephemeral";
+export type SaveInfo = {
+    version: string | null;
+    savedAt: string;
+};
+export type SaveMeta = SaveInfo & {
+    size: number;
+    revision: number;
+};
+export type Save = {
+    name: string;
+    data: string;
+    info: SaveMeta;
+};
+export type SavesLoad = {
+    status: SaveStatus;
+    items: Save[];
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+export type SavesChange = {
+    name: string;
+    save: Save | null;
+    revision: number;
+};
+export declare function isWellFormed(text: string): boolean;
+export declare function checkName(name: unknown): ArcadibleError | null;
+export declare function checkWrite(saves: ReadonlyMap<string, {
+    info: SaveMeta;
+}>, name: unknown, data: unknown): ArcadibleError | null;

package/dist/saves/rules.js

@@ -0,0 +1,49 @@
+// 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";
+// [declare]
+// Saves' limits, the same everywhere (DESIGN.md, section 6, Limits).
+export const MAX_SAVES = 32;
+// Every save's document together, in UTF-8 bytes.
+export const MAX_TOTAL = 1024 * 1024;
+const NAME = /^[A-Za-z0-9_.-]{1,64}$/u;
+// A lone surrogate: half a character, which storage and the network corrupt.
+const LONE_SURROGATE = /\p{Surrogate}/u;
+// [function]
+export function isWellFormed(text) {
+    return !LONE_SURROGATE.test(text);
+}
+// [function]
+// Why a save's name is refused, or null.
+export function checkName(name) {
+    if (typeof name !== "string" || !NAME.test(name)) {
+        return new ArcadibleError(Codes.Invalid, "A save's name is 1 to 64 letters, digits, '-', '_', or '.'.");
+    }
+    return null;
+}
+// [function]
+// Why a save is refused, given the saves already kept (`saves`), or null.
+export function checkWrite(saves, name, data) {
+    const refused = checkName(name);
+    if (refused)
+        return refused;
+    if (typeof data !== "string") {
+        return new ArcadibleError(Codes.Invalid, "A save is a string: serialize it first, such as with JSON.stringify.");
+    }
+    if (!isWellFormed(data)) {
+        return new ArcadibleError(Codes.Invalid, "A save can't hold half a character (a lone surrogate).");
+    }
+    if (!saves.has(name) && saves.size >= MAX_SAVES) {
+        return new ArcadibleError(Codes.TooMany, `A game keeps at most ${MAX_SAVES} saves. Remove one, or combine them.`);
+    }
+    let total = utf8Size(data);
+    for (const [other, save] of saves) {
+        if (other !== name)
+            total += save.info.size;
+    }
+    if (total > MAX_TOTAL) {
+        return new ArcadibleError(Codes.TooLarge, `A game's saves hold at most ${MAX_TOTAL / 1024 / 1024} MB together.`);
+    }
+    return null;
+}

package/dist/saves/server.d.ts

@@ -0,0 +1,11 @@
+import type { Module, ModuleContext } from "../bus/server.js";
+import type { Backend, SaveRecord, Scope } from "./backend/types.js";
+import { type Save } from "./rules.js";
+export type SavesServerOptions = {
+    scope: Scope;
+    version: string | null;
+    backend: Backend;
+    now: () => Date;
+};
+export declare function toSave(record: SaveRecord): Save;
+export declare function savesServer(options: SavesServerOptions): (context: ModuleContext) => Module;

package/dist/saves/server.js

@@ -0,0 +1,120 @@
+// Saves, the page's side: it answers a game's saves requests from its
+// backend, enforces the limits, and stamps each save with the game's
+// version. Its first message on each channel is the game's saves.
+// [import]
+import { ArcadibleError, Codes, utf8Size } from "../bus/protocol.js";
+import { checkName, checkWrite, } from "./rules.js";
+// [function]
+export function toSave(record) {
+    const { name, data, version, savedAt, size, revision } = record;
+    return { name, data, info: { version, savedAt, size, revision } };
+}
+// [function]
+// A writer's name, so the backend doesn't tell it of its own changes. It
+// needn't be secret, and `crypto.randomUUID` isn't on plain-http pages.
+function sourceId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+// [function]
+function nameOf(params) {
+    const refused = checkName(params["name"]);
+    if (refused)
+        throw refused;
+    return params["name"];
+}
+// [function]
+// the device is out of room: retrying won't help until the player frees
+// some. Anything else is the bus's `unavailable`.
+function storageError(err) {
+    if (err?.name === "QuotaExceededError") {
+        return new ArcadibleError(Codes.Full, "This device has no room left for saves.");
+    }
+    return err;
+}
+// [function]
+export function savesServer(options) {
+    const { backend, now, scope, version } = options;
+    const source = sourceId();
+    // a write, checked against the game's saves in the same step as it's kept.
+    const write = async function (params) {
+        const { name, data } = params;
+        const change = await backend
+            .change(scope, name, (saves) => {
+            const refused = checkWrite(new Map(saves.map((r) => [r.name, toSave(r)])), name, data);
+            if (refused)
+                throw refused;
+            return {
+                name: name,
+                data: data,
+                version,
+                savedAt: now().toISOString(),
+                size: utf8Size(data),
+            };
+        }, source)
+            .catch((err) => {
+            throw storageError(err);
+        });
+        return change?.record ? toSave(change.record).info : null;
+    };
+    const load = async function () {
+        const [list] = await Promise.all([
+            backend.list(scope),
+            backend.touch(scope, now().toISOString()),
+        ]);
+        return { status: backend.status(), items: list.map(toSave) };
+    };
+    return (context) => {
+        // another tab (later, another device) changed a save: tell the game,
+        // with the change's revision, so it can ignore one that arrives late.
+        const unsubscribe = backend.subscribe(scope, (change, from) => {
+            if (from === source)
+                return;
+            context.broadcast("saves.change", {
+                name: change.name,
+                save: change.record ? toSave(change.record) : null,
+                revision: change.revision,
+            });
+        });
+        return {
+            handlers: {
+                "saves.read": {
+                    run: async (params) => (await backend.get(scope, nameOf(params)))?.data ?? null,
+                },
+                "saves.info": {
+                    run: async (params) => {
+                        const record = await backend.get(scope, nameOf(params));
+                        return record ? toSave(record).info : null;
+                    },
+                },
+                "saves.list": {
+                    run: async () => (await backend.list(scope)).map((record) => record.name).sort(),
+                },
+                "saves.write": { run: write, coalesce: (p) => String(p["name"]) },
+                // the removal's revision, or null when there was nothing to remove.
+                "saves.remove": {
+                    run: async (params) => {
+                        const change = await backend.change(scope, nameOf(params), () => null, source);
+                        return change?.revision ?? null;
+                    },
+                },
+            },
+            async open(send) {
+                try {
+                    send("saves.load", await load());
+                }
+                catch (err) {
+                    console.error("arcadible: the game's saves couldn't load:", err);
+                    const error = err instanceof ArcadibleError
+                        ? err.toJSON()
+                        : { code: Codes.Unavailable, message: "Saves couldn't load." };
+                    send("saves.load", {
+                        status: "ephemeral",
+                        items: [],
+                        error,
+                    });
+                }
+            },
+            close: unsubscribe,
+        };
+    };
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.3.0";

package/dist/version.js

@@ -0,0 +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 = "0.3.0";

package/package.json

@@ -1,6 +1,47 @@
 {
+  "author": "Offst, Inc.",
+  "description": "The Arcadible SDK: how a game talks to Arcadible, over a bus between the game and the play page, starting with saves that survive updates.",
+  "devDependencies": {
+    "@playwright/test": "1.63.0",
+    "@types/node": "^25.0.3",
+    "esbuild": "^0.28.2",
+    "fake-indexeddb": "^6.2.5",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/play.*",
+    "!dist/v1.*"
+  ],
+  "homepage": "https://developer.arcadible.com/references/arcadible-sdk",
+  "keywords": [
+    "arcadible",
+    "games",
+    "saves",
+    "sdk"
+  ],
+  "license": "Apache-2.0",
   "name": "@arcadible/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "scripts": {
+    "build": "tsc && node scripts/bundle.mjs",
+    "prepack": "rm -rf dist && npm run build",
+    "test": "npm run test:unit && npm run test:browser",
+    "test:browser": "npm run build && playwright test",
+    "test:unit": "tsc && tsc -p tsconfig.test.json && node --test --test-force-exit 'dist-test/test/unit/**/*.test.js'"
+  },
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/v1.js",
+    "./src/index.ts",
+    "./src/v1.ts"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "version": "0.3.0"
+}