@arcadible/sdk 1.2.0 → 1.2.2

package/README.md

@@ -27,34 +27,31 @@ Each build of a game on [Arcadible](https://arcadible.com) has its own origin, s
 npm install @arcadible/sdk
 ```
 
-Use the package in a game with a build step, such as a Vite project. A game without one includes the hosted script instead, which Arcadible serves from every build's own origin, as `arc serve` does locally:
-
-```html
-<script src="/arcadible/sdk/v1.js"></script>
-```
+The package is for a game with a build step, such as a Vite project. A game without one uses the [hosted script](https://developer.arcadible.com/references/arcadible-sdk#install) instead.
 
 ## Save and load
 
 ```js
 import { arcadible } from "@arcadible/sdk";
 
+// at startup: once the saves have loaded, the player's progress, or a new game.
 await arcadible.ready;
-
-const saved = arcadible.saves.readSync("progress");
+const saved = await arcadible.saves.read("progress");
 const progress = saved ? JSON.parse(saved) : { level: 1 };
 
+// at a checkpoint:
 await arcadible.saves.write("progress", JSON.stringify(progress));
 ```
 
-A save is a name holding one string. `ready` settles once the game's saves have loaded, and never fails; from then on, `readSync`, `listSync`, and `infoSync` answer from memory. Every call that fails rejects (or, for the sync calls, throws) with an `ArcadibleError`, whose `code` says what to do. `arcadible.saves.where` says who can read the saves back: every version of the game, only this build, or only until the page closes.
+A save is a name holding one string. `arcadible.ready` settles once the game's saves have loaded, and never fails; calls made before it wait for it, and from then on `readSync`, `listSync`, and `infoSync` answer at once from memory, for reads during play. Every call that fails rejects (or, for the sync calls, throws) with an `ArcadibleError`, whose `code` says what to do. `arcadible.saves.where` says who can read the saves back: every version of the game, only this build, or only until the page closes.
 
 Off Arcadible, such as on your dev server, the package works on its own, with the same rules and limits: saves are kept on the page's own origin, `arcadible.saves.where` is `"build"`, and `arcadible.build` is `null`.
 
 ## Learn more
 
-- [Saves](https://developer.arcadible.com/build/saves): adding the SDK, what to save, and other versions' saves.
+- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): installing it, the hosted script, `ready` and `build`, and every code.
 - [`arcadible.saves`](https://developer.arcadible.com/references/arcadible-sdk/saves): every call, what it returns, and when it fails.
-- [Arcadible SDK](https://developer.arcadible.com/references/arcadible-sdk): `ready` and `build`, and every code.
+- [Saves](https://developer.arcadible.com/build/saves): using saves well, across versions, channels, and tabs, and where they're kept.
 - [Limits](https://developer.arcadible.com/references/limits#saves): how many saves, and how large.
 
 ## License

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

@@ -3,6 +3,7 @@ export type IndexedDBOptions = {
     factory?: IDBFactory | null;
     player?: string;
     persist?: boolean;
+    reopenWait?: number;
 };
 export declare function indexedDBBackend(options?: IndexedDBOptions): Backend & {
     close(): void;

package/dist/saves/backend/indexeddb.js

@@ -13,6 +13,9 @@ 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";
+// after a failed reopen, how long calls fail at once before it's tried again,
+// so a game saving every frame doesn't try, and fail, every frame.
+const REOPEN_WAIT = 1000;
 // [function]
 function settle(request) {
     return new Promise((resolve, reject) => {
@@ -66,7 +69,7 @@ function isClosed(err) {
 // 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.
+// opens again, trying at most once a second, rather than show an empty copy.
 export function indexedDBBackend(options = {}) {
     const factory = options.factory === undefined
         ? (globalThis.indexedDB ?? null)
@@ -79,6 +82,9 @@ export function indexedDBBackend(options = {}) {
     let opened = false;
     let current = null;
     let opening = null;
+    // whether reopening has failed since it last worked, and when to try again.
+    let down = false;
+    let retryAt = 0;
     let asked = false;
     const keyOf = (scope) => `${player}\u0000${scope.game}\u0000${scope.channel}`;
     const rangeOf = (scope) => IDBKeyRange.only([player, scope.game, scope.channel]);
@@ -86,6 +92,7 @@ export function indexedDBBackend(options = {}) {
         if (current === db)
             current = null;
     };
+    const unreachable = () => new ArcadibleError(Codes.Unavailable, "Saves can't be reached right now. Try again.");
     const connect = async function () {
         try {
             if (!factory)
@@ -103,13 +110,19 @@ export function indexedDBBackend(options = {}) {
                 globalThis.navigator?.storage?.persist?.().catch(() => false);
             }
             opened = true;
+            down = false;
             current = db;
             return db;
         }
         catch (err) {
             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.");
+                // once until it works again: the calls failing meanwhile say so.
+                if (!down) {
+                    log("warn", "the saves' storage couldn't be opened again.", err);
+                }
+                down = true;
+                retryAt = Date.now() + (options.reopenWait ?? REOPEN_WAIT);
+                throw unreachable();
             }
             log("warn", "this browser won't keep saves here, so they're kept in memory until the page closes.", err);
             status = "memory";
@@ -125,6 +138,9 @@ export function indexedDBBackend(options = {}) {
             return Promise.resolve(null);
         if (current)
             return Promise.resolve(current);
+        if (down && !opening && Date.now() < retryAt) {
+            return Promise.reject(unreachable());
+        }
         opening ??= connect();
         return opening;
     };

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.2.0";
+export declare const VERSION = "1.2.2";

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.2.0";
+export const VERSION = "1.2.2";

package/package.json

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