castle-web-sdk 0.4.24 → 0.4.26

package/dist/store.d.ts

@@ -0,0 +1,67 @@
+import type { Json } from "./types";
+export interface StoreListOptions {
+    /** Only keys beginning with this. Omit for every key in the scope. */
+    prefix?: string;
+    /** Rows per page. The platform caps both the row count and the page's size. */
+    limit?: number;
+    /** The `cursor` from the previous page. Omit for the first page. */
+    cursor?: string | null;
+}
+export interface StoreListEntry<T extends Json = Json> {
+    key: string;
+    value: T;
+}
+export interface StoreListPage<T extends Json = Json> {
+    entries: StoreListEntry<T>[];
+    /**
+     * Pass to the next `list` call to continue. Null means there is nothing left,
+     * and is the only reliable end-of-range signal: a page can come back short
+     * because it hit its size cap rather than because the keys ran out.
+     */
+    cursor: string | null;
+}
+export interface StoreScopeApi {
+    /** Reads keys. Keys with no value are absent from the result. */
+    get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
+    /**
+     * Writes keys. Resolves once the platform has the write, so a deck can tell
+     * whether saving worked; the write itself is coalesced with nearby ones.
+     */
+    set(values: Record<string, Json>): Promise<void>;
+    remove(keys: string[]): Promise<void>;
+    /**
+     * Adds to a numeric key and returns the new total, creating the key at `delta`
+     * if it is absent. Atomic: simultaneous callers each see their own increment
+     * applied, which a read-modify-write cannot promise.
+     */
+    increment(key: string, delta?: number): Promise<number>;
+    /** A page of keys under a prefix, ordered by key. */
+    list<T extends Json = Json>(options?: StoreListOptions): Promise<StoreListPage<T>>;
+}
+export interface StoreBoardScore {
+    /** The user id whose score this is. */
+    subject: string;
+    score: number;
+    updatedAt: string;
+}
+export interface StoreBoardApi {
+    /** Records the current player's score. Later submissions replace earlier ones. */
+    submit(score: number): Promise<StoreBoardScore>;
+    /** The highest scores, best first. */
+    top(limit?: number): Promise<StoreBoardScore[]>;
+    /** One player's score, defaulting to the current player. Null if unset. */
+    get(userId?: string): Promise<StoreBoardScore | null>;
+}
+export interface CastleStoreApi {
+    /** Shared by everyone playing the deck. */
+    readonly deck: StoreScopeApi;
+    /** The current player's data, which other players can read. */
+    readonly me: StoreScopeApi;
+    /** Another player's public data. Readable by anyone; writable only by them. */
+    user(userId: string): StoreScopeApi;
+    /** The current player's own data. Nobody else can read it, not even a session server. */
+    readonly private: StoreScopeApi;
+    /** A leaderboard. */
+    board(name: string): StoreBoardApi;
+}
+export declare const Store: CastleStoreApi;

package/dist/store.js

@@ -0,0 +1,313 @@
+import { chunked } from "./chunk";
+import { decodeStorageValue, encodeStorageValue, storageError } from "./storageJson";
+import { hostRequest } from "./transport";
+import { onUnloadFlush } from "./unloadFlush";
+// Per-key deck storage for Cauldron decks.
+//
+// The older Storage/SharedStorage keep one document per bucket and rewrite the
+// whole thing on every change, which loses concurrent writes and stops at 2 MB.
+// This keeps one row per key instead: two players writing different keys no
+// longer overwrite each other, a counter can be incremented atomically, and a
+// deck can hold far more than one document's worth and read back a slice of it.
+//
+// Every operation here is a bounded request. A deck never supplies a filter or
+// an ordering, which is what lets the platform promise that no deck can make the
+// database do expensive work.
+// Writes coalesce by key for this long before being sent, so a deck that saves
+// on every change costs one request per burst rather than one per change.
+const FLUSH_INTERVAL_MS = 200;
+// The platform takes at most this many keys per call. A buffer that coalesced
+// past it goes out as several requests rather than as one the server rejects,
+// so a deck that saves many small keys in a burst never has to know the limit.
+const MAX_KEYS_PER_REQUEST = 32;
+const buckets = new Map();
+function bucketKey(scope, subject) {
+    return `${scope}|${subject ?? "self"}`;
+}
+function pendingBucket(scope, subject) {
+    const id = bucketKey(scope, subject);
+    let bucket = buckets.get(id);
+    if (!bucket) {
+        bucket = {
+            scope,
+            subject,
+            values: new Map(),
+            waiters: [],
+            timer: null,
+            inFlight: Promise.resolve(),
+            pending: 0,
+        };
+        buckets.set(id, bucket);
+    }
+    return bucket;
+}
+function queueWrite(scope, subject, values, unload = false) {
+    const bucket = pendingBucket(scope, subject);
+    for (const [key, value] of values)
+        bucket.values.set(key, value);
+    const settled = new Promise((resolve, reject) => {
+        bucket.waiters.push({ keys: Array.from(values.keys()), resolve, reject });
+    });
+    // A stable reference, so registering on every write leaves one handler.
+    onUnloadFlush(flushAllNow);
+    if (unload) {
+        void flushBucket(bucket, true);
+    }
+    else if (!bucket.timer) {
+        bucket.timer = setTimeout(() => {
+            bucket.timer = null;
+            void flushBucket(bucket, false);
+        }, FLUSH_INTERVAL_MS);
+    }
+    return settled;
+}
+// Never rejects: a failed request is reported to the waiters whose keys it
+// carried, which is what the deck is holding. Callers can `void` it safely.
+function flushBucket(bucket, unload) {
+    bucket.pending += 1;
+    // An unload flush does not wait its turn. Queueing it behind a request that
+    // may not come back before the frame does would lose the last save outright,
+    // and the host finishes an `unload` write with fetch keepalive, so what
+    // matters is that the message reaches it at all. The cost is that this one
+    // write can race the request already in flight: if they touch the same key
+    // and land out of order, the older value stays stored. Ordering that
+    // correctly needs a revision token the server checks, which does not exist
+    // yet -- a stale key beats a lost one until it does.
+    const run = unload
+        ? guarded(sendBucket(bucket, true))
+        : guarded(bucket.inFlight.then(() => sendBucket(bucket, false)));
+    // Later flushes queue behind this one either way, so only the unload write
+    // itself skips the queue. Counting it in `pending` matters as much: a bucket
+    // dropped while its request is still out would let the next write build a
+    // second bucket for the same scope, and the two would flush concurrently.
+    bucket.inFlight = Promise.all([bucket.inFlight, run]).then(() => {
+        bucket.pending -= 1;
+        pruneBucket(bucket);
+    });
+    return run;
+}
+// A rejection must never reach `inFlight`. The chain is built with `then`, so a
+// rejected link makes every later flush for this bucket skip its send and
+// reject in turn: the scope stops writing, permanently and silently. Failed
+// requests are already reported to their waiters, so anything arriving here is
+// a bug in this file rather than a write that did not land.
+function guarded(run) {
+    return run.catch(reportWriteError);
+}
+function reportWriteError(error) {
+    console.warn("Castle store flush failed unexpectedly", error);
+}
+async function sendBucket(bucket, unload) {
+    // Take the buffer before awaiting: writes made while this request is in flight
+    // belong to the next one, not to this one's waiters.
+    const values = bucket.values;
+    const waiters = bucket.waiters;
+    bucket.values = new Map();
+    bucket.waiters = [];
+    if (bucket.timer) {
+        clearTimeout(bucket.timer);
+        bucket.timer = null;
+    }
+    if (values.size === 0 && waiters.length === 0)
+        return;
+    const entries = [];
+    const removals = [];
+    for (const [key, value] of values) {
+        if (value === null)
+            removals.push(key);
+        else
+            entries.push({ key, value });
+    }
+    // Which keys failed to store, and why. Set and delete never share a key here:
+    // a key written and then removed inside one window is a single null in
+    // `values`, so the two lists are disjoint and their outcomes independent.
+    const failures = new Map();
+    // Anything escaping the per-request catch is a bug, not a write that failed.
+    // It still has to reach the waiters: an unsettled one is a deck awaiting a
+    // promise that will never resolve.
+    let unexpected = null;
+    try {
+        for (const request of buildRequests(bucket, entries, removals, unload)) {
+            try {
+                await request.send();
+            }
+            catch (error) {
+                for (const key of request.keys)
+                    failures.set(key, error);
+            }
+        }
+    }
+    catch (error) {
+        unexpected = error;
+    }
+    for (const waiter of waiters) {
+        if (unexpected !== null) {
+            waiter.reject(unexpected);
+            continue;
+        }
+        // `find`, not `some`: the first failing key supplies the error the deck sees.
+        const failed = waiter.keys.find((key) => failures.has(key));
+        // A caller that contributed no keys -- `set({})`, `remove([])` -- has nothing
+        // that can fail, and must still be settled rather than left hanging.
+        if (failed === undefined)
+            waiter.resolve();
+        else
+            waiter.reject(failures.get(failed));
+    }
+}
+function buildRequests(bucket, entries, removals, unload) {
+    const requests = [];
+    // Removals go first: within one window a key that was set and then removed
+    // should end up removed, and sending the set afterwards would resurrect it.
+    for (const keys of chunked(removals, MAX_KEYS_PER_REQUEST)) {
+        requests.push({
+            keys,
+            send: () => hostRequest("cauldronStorage.delete", {
+                scope: bucket.scope,
+                subject: bucket.subject,
+                keys,
+                unload,
+            }),
+        });
+    }
+    for (const chunk of chunked(entries, MAX_KEYS_PER_REQUEST)) {
+        requests.push({
+            keys: chunk.map((entry) => entry.key),
+            send: () => hostRequest("cauldronStorage.set", {
+                scope: bucket.scope,
+                subject: bucket.subject,
+                entries: chunk,
+                unload,
+            }),
+        });
+    }
+    return requests;
+}
+// A deck that reads many players' buckets would otherwise leave one empty entry
+// per user id behind for the life of the page.
+function pruneBucket(bucket) {
+    if (bucket.pending > 0 ||
+        bucket.values.size > 0 ||
+        bucket.waiters.length > 0 ||
+        bucket.timer) {
+        return;
+    }
+    const id = bucketKey(bucket.scope, bucket.subject);
+    if (buckets.get(id) === bucket)
+        buckets.delete(id);
+}
+function flushAllNow() {
+    for (const bucket of buckets.values()) {
+        // Nothing awaits these: the page is going away. The host is what finishes
+        // the request, and it outlives the deck's frame.
+        void flushBucket(bucket, true);
+    }
+}
+// ---------------------------------------------------------------------------
+function assertKeys(keys, operation) {
+    if (!Array.isArray(keys) || keys.some((key) => typeof key !== "string")) {
+        throw storageError("CASTLE_STORE_INVALID_KEYS", "Store keys must be an array of strings.", operation);
+    }
+    return keys;
+}
+function createScope(scope, subject) {
+    return {
+        async get(keys) {
+            const { entries } = await hostRequest("cauldronStorage.get", {
+                scope,
+                subject,
+                keys: assertKeys(keys, "Store.get"),
+            });
+            const result = {};
+            for (const entry of entries) {
+                // defineProperty rather than assignment: a stored key named "__proto__"
+                // would otherwise reach the prototype setter instead of becoming an own
+                // property, corrupting the object handed back to the deck.
+                Object.defineProperty(result, entry.key, {
+                    value: decodeStorageValue(entry.value, "Store.get"),
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+            return result;
+        },
+        set(values) {
+            const pending = new Map();
+            for (const [key, value] of Object.entries(values)) {
+                pending.set(key, encodeStorageValue(value, "Store.set"));
+            }
+            return queueWrite(scope, subject, pending);
+        },
+        remove(keys) {
+            const pending = new Map();
+            for (const key of assertKeys(keys, "Store.remove"))
+                pending.set(key, null);
+            return queueWrite(scope, subject, pending);
+        },
+        async increment(key, delta = 1) {
+            // Not coalesced. Merging increments locally would mean reporting a total
+            // the server has not agreed to, and the point of this verb is that the
+            // server is the one doing the adding.
+            const { value } = await hostRequest("cauldronStorage.increment", {
+                scope,
+                subject,
+                key,
+                delta,
+            });
+            return Number(value);
+        },
+        async list(options = {}) {
+            const { entries, cursor } = await hostRequest("cauldronStorage.list", {
+                scope,
+                subject,
+                prefix: options.prefix ?? null,
+                limit: options.limit ?? null,
+                cursor: options.cursor ?? null,
+            });
+            return {
+                entries: entries.map((entry) => ({
+                    key: entry.key,
+                    value: decodeStorageValue(entry.value, "Store.list"),
+                })),
+                cursor,
+            };
+        },
+    };
+}
+function createBoard(name) {
+    return {
+        async submit(score) {
+            const { entry } = await hostRequest("cauldronStorage.boardSubmit", {
+                board: name,
+                score,
+            });
+            return entry;
+        },
+        async top(limit) {
+            const { entries } = await hostRequest("cauldronStorage.boardTop", {
+                board: name,
+                limit: limit ?? null,
+            });
+            return entries;
+        },
+        async get(userId) {
+            const { entry } = await hostRequest("cauldronStorage.boardGet", {
+                board: name,
+                subject: userId ?? null,
+            });
+            return entry;
+        },
+    };
+}
+export const Store = {
+    deck: createScope("deck", null),
+    me: createScope("user", null),
+    user(userId) {
+        return createScope("user", userId);
+    },
+    private: createScope("private", null),
+    board(name) {
+        return createBoard(name);
+    },
+};

package/dist/unloadFlush.d.ts

@@ -0,0 +1,3 @@
+type FlushHandler = () => void;
+export declare function onUnloadFlush(handler: FlushHandler): void;
+export {};

package/dist/unloadFlush.js

@@ -0,0 +1,30 @@
+// Somewhere to hang "flush before the page goes away".
+//
+// Writes batch on a timer, so leaving the page inside that window would lose
+// them, and a deck saving progress as someone quits is exactly when it matters.
+// `pagehide` is the reliable signal on iOS, where unload often never fires, and
+// visibilitychange covers backgrounding without a navigation.
+//
+// Listeners are registered on the first write, so a deck that never stores
+// anything hooks nothing.
+//
+// Handlers are held in a Set, so registering on every write is fine as long as
+// the caller passes a STABLE function reference. A fresh closure per call would
+// accumulate, and every one of them would run at unload.
+const handlers = new Set();
+let hooked = false;
+export function onUnloadFlush(handler) {
+    handlers.add(handler);
+    if (hooked || typeof window === "undefined")
+        return;
+    hooked = true;
+    const flushAll = () => {
+        for (const flush of handlers)
+            flush();
+    };
+    window.addEventListener("pagehide", flushAll);
+    document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden")
+            flushAll();
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.24",
+  "version": "0.4.26",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",