@joystyk/storage 0.0.0-stage → 0.2.0

package/dist/browser/indexeddb.js

@@ -0,0 +1,145 @@
+import { MESSAGES, STORE_NAMES, storageError } from "../backend.js";
+import { err, ok } from "@joystyk/contracts";
+//#region src/browser/indexeddb.ts
+/**
+* The database schema, oldest first. Record shapes are versioned per record (see
+* `RecordKind`); this list changes only when an object store is added or removed.
+*/
+var DATABASE_UPGRADES = [{
+	version: 1,
+	upgrade: (db) => {
+		for (const name of STORE_NAMES) db.createObjectStore(name);
+	}
+}];
+var QUOTA_NAMES = /* @__PURE__ */ new Set(["QuotaExceededError", "NS_ERROR_DOM_QUOTA_REACHED"]);
+/** Maps a DOMException (or anything thrown) to a StorageError. */
+var toStorageError = (cause) => {
+	const name = typeof cause === "object" && cause !== null ? String(cause.name) : "";
+	const detail = cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause);
+	if (QUOTA_NAMES.has(name)) return storageError("QuotaExceeded", MESSAGES.QuotaExceeded, detail);
+	if (name === "InvalidStateError" || name === "SecurityError" || name === "UnknownError") return storageError("Unavailable", MESSAGES.Unavailable, detail);
+	if (name === "DataCloneError" || name === "DataError") return storageError("InvalidValue", MESSAGES.InvalidValue, detail);
+	return storageError("Failed", MESSAGES.Failed, detail);
+};
+var checkUpgrades = (upgrades) => {
+	upgrades.forEach((step, index) => {
+		if (step.version !== index + 1) throw new RangeError(`Database upgrades must be numbered 1, 2, 3…; step ${index} is version ${step.version}`);
+	});
+	if (upgrades.length === 0) throw new RangeError("At least one database upgrade is required");
+	return upgrades.length;
+};
+/**
+* Opens (creating or upgrading) the database and returns a backend over it. Runs every
+* upgrade step newer than the stored version, in order, inside one `versionchange`
+* transaction. Resolves to `Unavailable` where IndexedDB is missing or refused.
+*/
+var openIndexedDbBackend = (options = {}) => {
+	const upgrades = options.upgrades ?? DATABASE_UPGRADES;
+	const version = checkUpgrades(upgrades);
+	const factory = options.factory ?? globalThis.indexedDB;
+	if (factory === void 0) return Promise.resolve(err(storageError("Unavailable", MESSAGES.Unavailable)));
+	return new Promise((resolve) => {
+		let request;
+		try {
+			request = factory.open(options.name ?? "joystyk", version);
+		} catch (cause) {
+			resolve(err(toStorageError(cause)));
+			return;
+		}
+		request.onupgradeneeded = (event) => {
+			const transaction = request.transaction;
+			if (transaction === null) return;
+			for (const step of upgrades) if (step.version > event.oldVersion) step.upgrade(request.result, transaction);
+		};
+		request.onblocked = () => options.onBlocked?.();
+		request.onerror = (event) => {
+			event.preventDefault();
+			resolve(err(toStorageError(request.error)));
+		};
+		request.onsuccess = () => resolve(ok(createBackend(request.result, options)));
+	});
+};
+var createBackend = (db, options) => {
+	let closed = false;
+	const close = () => {
+		if (closed) return;
+		closed = true;
+		db.close();
+	};
+	db.onversionchange = () => {
+		close();
+		options.onVersionChange?.();
+	};
+	db.onclose = () => {
+		closed = true;
+	};
+	/**
+	* Runs `work` in a transaction on one store and resolves when the transaction commits, so
+	* a write counts as done only once it is durable. Quota errors often surface only as the
+	* transaction aborting, so the abort is mapped too.
+	*/
+	const run = (store, mode, work) => new Promise((resolve) => {
+		if (closed) {
+			resolve(err(storageError("Unavailable", MESSAGES.Unavailable)));
+			return;
+		}
+		let value;
+		let transaction;
+		try {
+			transaction = db.transaction(store, mode);
+			work(transaction.objectStore(store), (result) => {
+				value = result;
+			});
+		} catch (cause) {
+			resolve(err(toStorageError(cause)));
+			return;
+		}
+		transaction.oncomplete = () => resolve(ok(value));
+		transaction.onabort = () => resolve(err(toStorageError(transaction.error)));
+		transaction.onerror = (event) => event.preventDefault();
+	});
+	return {
+		get: (store, key) => run(store, "readonly", (objectStore, done) => {
+			const request = objectStore.get(key);
+			request.onsuccess = () => done(request.result);
+		}),
+		put: (store, key, value) => run(store, "readwrite", (objectStore) => {
+			objectStore.put(value, key);
+		}),
+		putIfAbsent: (store, key, value) => run(store, "readwrite", (objectStore, done) => {
+			const request = objectStore.get(key);
+			request.onsuccess = () => {
+				if (request.result !== void 0) return done({
+					written: false,
+					value: request.result
+				});
+				objectStore.add(value, key);
+				done({ written: true });
+			};
+		}),
+		delete: (store, key) => run(store, "readwrite", (objectStore) => {
+			objectStore.delete(key);
+		}),
+		keys: (store, prefix) => run(store, "readonly", (objectStore, done) => {
+			const keys = [];
+			done(keys);
+			const request = objectStore.openKeyCursor(prefix === "" ? null : IDBKeyRange.lowerBound(prefix));
+			request.onsuccess = () => {
+				const cursor = request.result;
+				if (cursor === null) return;
+				const key = cursor.key;
+				if (typeof key !== "string" || !key.startsWith(prefix)) return;
+				keys.push(key);
+				cursor.continue();
+			};
+		}),
+		clear: (store) => run(store, "readwrite", (objectStore) => {
+			objectStore.clear();
+		}),
+		close
+	};
+};
+//#endregion
+export { DATABASE_UPGRADES, openIndexedDbBackend, toStorageError };
+
+//# sourceMappingURL=indexeddb.js.map

package/dist/browser/indexeddb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexeddb.js","names":[],"sources":["../../src/browser/indexeddb.ts"],"sourcesContent":["// A thin IndexedDB backend: one database, one object store per StoreName, string keys, JSON\n// values. No IndexedDB library; just requests wrapped in promises and errors mapped to\n// StorageError results.\nimport { err, ok, type Json, type Result } from '@joystyk/contracts';\nimport {\n  MESSAGES,\n  STORE_NAMES,\n  storageError,\n  type PutIfAbsent,\n  type StorageBackend,\n  type StorageError,\n  type StoreName,\n} from '../backend.ts';\n\n/** One step of the database's own schema: which object stores exist. */\nexport type DatabaseUpgrade = {\n  /** The database version this step produces, from 1, with no gaps. */\n  readonly version: number;\n  /** Runs inside the `versionchange` transaction. Create or delete object stores here. */\n  upgrade(db: IDBDatabase, transaction: IDBTransaction): void;\n};\n\n/**\n * The database schema, oldest first. Record shapes are versioned per record (see\n * `RecordKind`); this list changes only when an object store is added or removed.\n */\nexport const DATABASE_UPGRADES: readonly DatabaseUpgrade[] = [\n  {\n    version: 1,\n    upgrade: (db) => {\n      for (const name of STORE_NAMES) db.createObjectStore(name);\n    },\n  },\n];\n\nexport type IndexedDbOptions = {\n  /** Defaults to \"joystyk\". */\n  readonly name?: string;\n  /** Defaults to the global `indexedDB`. */\n  readonly factory?: IDBFactory;\n  /** Defaults to `DATABASE_UPGRADES`. */\n  readonly upgrades?: readonly DatabaseUpgrade[];\n  /**\n   * Another tab holds an older connection open, so the upgrade waits. The frame can ask the\n   * player to close other tabs of the site.\n   */\n  readonly onBlocked?: () => void;\n  /**\n   * Another tab needs a newer database version. This connection closes so that tab can\n   * upgrade, and later operations fail with `Unavailable`; the frame should offer a reload.\n   */\n  readonly onVersionChange?: () => void;\n};\n\nconst QUOTA_NAMES = new Set(['QuotaExceededError', 'NS_ERROR_DOM_QUOTA_REACHED']);\n\n/** Maps a DOMException (or anything thrown) to a StorageError. */\nexport const toStorageError = (cause: unknown): StorageError => {\n  const name = typeof cause === 'object' && cause !== null ? String((cause as { name?: unknown }).name) : '';\n  const detail = cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause);\n  if (QUOTA_NAMES.has(name)) return storageError('QuotaExceeded', MESSAGES.QuotaExceeded, detail);\n  if (name === 'InvalidStateError' || name === 'SecurityError' || name === 'UnknownError') {\n    return storageError('Unavailable', MESSAGES.Unavailable, detail);\n  }\n  if (name === 'DataCloneError' || name === 'DataError')\n    return storageError('InvalidValue', MESSAGES.InvalidValue, detail);\n  return storageError('Failed', MESSAGES.Failed, detail);\n};\n\nconst checkUpgrades = (upgrades: readonly DatabaseUpgrade[]): number => {\n  upgrades.forEach((step, index) => {\n    if (step.version !== index + 1) {\n      throw new RangeError(`Database upgrades must be numbered 1, 2, 3…; step ${index} is version ${step.version}`);\n    }\n  });\n  if (upgrades.length === 0) throw new RangeError('At least one database upgrade is required');\n  return upgrades.length;\n};\n\n/**\n * Opens (creating or upgrading) the database and returns a backend over it. Runs every\n * upgrade step newer than the stored version, in order, inside one `versionchange`\n * transaction. Resolves to `Unavailable` where IndexedDB is missing or refused.\n */\nexport const openIndexedDbBackend = (options: IndexedDbOptions = {}): Promise<Result<StorageBackend, StorageError>> => {\n  const upgrades = options.upgrades ?? DATABASE_UPGRADES;\n  const version = checkUpgrades(upgrades);\n  const factory = options.factory ?? (globalThis as { indexedDB?: IDBFactory }).indexedDB;\n  if (factory === undefined) return Promise.resolve(err(storageError('Unavailable', MESSAGES.Unavailable)));\n\n  return new Promise((resolve) => {\n    let request: IDBOpenDBRequest;\n    try {\n      request = factory.open(options.name ?? 'joystyk', version);\n    } catch (cause) {\n      resolve(err(toStorageError(cause)));\n      return;\n    }\n    request.onupgradeneeded = (event) => {\n      const transaction = request.transaction;\n      if (transaction === null) return;\n      for (const step of upgrades) {\n        if (step.version > event.oldVersion) step.upgrade(request.result, transaction);\n      }\n    };\n    request.onblocked = () => options.onBlocked?.();\n    request.onerror = (event) => {\n      event.preventDefault();\n      resolve(err(toStorageError(request.error)));\n    };\n    request.onsuccess = () => resolve(ok(createBackend(request.result, options)));\n  });\n};\n\nconst createBackend = (db: IDBDatabase, options: IndexedDbOptions): StorageBackend => {\n  let closed = false;\n  const close = (): void => {\n    if (closed) return;\n    closed = true;\n    db.close();\n  };\n  db.onversionchange = () => {\n    close();\n    options.onVersionChange?.();\n  };\n  // The browser closed the connection itself, e.g. when site data was cleared.\n  db.onclose = () => {\n    closed = true;\n  };\n\n  /**\n   * Runs `work` in a transaction on one store and resolves when the transaction commits, so\n   * a write counts as done only once it is durable. Quota errors often surface only as the\n   * transaction aborting, so the abort is mapped too.\n   */\n  const run = <T>(\n    store: StoreName,\n    mode: IDBTransactionMode,\n    work: (objectStore: IDBObjectStore, done: (value: T) => void) => void,\n  ): Promise<Result<T, StorageError>> =>\n    new Promise((resolve) => {\n      if (closed) {\n        resolve(err(storageError('Unavailable', MESSAGES.Unavailable)));\n        return;\n      }\n      let value: T | undefined;\n      let transaction: IDBTransaction;\n      try {\n        transaction = db.transaction(store, mode);\n        work(transaction.objectStore(store), (result) => {\n          value = result;\n        });\n      } catch (cause) {\n        resolve(err(toStorageError(cause)));\n        return;\n      }\n      transaction.oncomplete = () => resolve(ok(value as T));\n      transaction.onabort = () => resolve(err(toStorageError(transaction.error)));\n      // An error event is followed by an abort; prevent it from reaching window.onerror.\n      transaction.onerror = (event) => event.preventDefault();\n    });\n\n  return {\n    get: (store, key) =>\n      run<unknown>(store, 'readonly', (objectStore, done) => {\n        const request = objectStore.get(key);\n        request.onsuccess = () => done(request.result);\n      }),\n    put: (store, key, value: Json) =>\n      run<void>(store, 'readwrite', (objectStore) => {\n        objectStore.put(value, key);\n      }),\n    // One readwrite transaction reads and adds. IndexedDB runs readwrite transactions on the\n    // same store one at a time, across every connection to the database, so two tabs can't\n    // both find the key absent.\n    putIfAbsent: (store, key, value: Json) =>\n      run<PutIfAbsent>(store, 'readwrite', (objectStore, done) => {\n        const request = objectStore.get(key);\n        request.onsuccess = () => {\n          if (request.result !== undefined) return done({ written: false, value: request.result });\n          objectStore.add(value, key);\n          done({ written: true });\n        };\n      }),\n    delete: (store, key) =>\n      run<void>(store, 'readwrite', (objectStore) => {\n        objectStore.delete(key);\n      }),\n    keys: (store, prefix) =>\n      run<readonly string[]>(store, 'readonly', (objectStore, done) => {\n        const keys: string[] = [];\n        done(keys);\n        const request = objectStore.openKeyCursor(prefix === '' ? null : IDBKeyRange.lowerBound(prefix));\n        request.onsuccess = () => {\n          const cursor = request.result;\n          if (cursor === null) return;\n          const key = cursor.key;\n          if (typeof key !== 'string' || !key.startsWith(prefix)) return;\n          keys.push(key);\n          cursor.continue();\n        };\n      }),\n    clear: (store) =>\n      run<void>(store, 'readwrite', (objectStore) => {\n        objectStore.clear();\n      }),\n    close,\n  };\n};\n"],"mappings":"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"}

package/dist/browser/persist.d.ts

@@ -0,0 +1,24 @@
+/** The parts of `navigator.storage` these helpers use. */
+export type StorageManagerLike = {
+    persist?(): Promise<boolean>;
+    persisted?(): Promise<boolean>;
+    estimate?(): Promise<{
+        usage?: number;
+        quota?: number;
+    }>;
+};
+/** `persisted`: the browser won't evict this site's data. `denied`: it may. `unsupported`: it can't say. */
+export type PersistResult = 'persisted' | 'denied' | 'unsupported';
+/**
+ * Asks the browser to keep this site's data. Call it from the player's gesture of pinning a
+ * game; never on page load. Already-persisted storage resolves without asking again, and a
+ * browser that throws counts as `unsupported`.
+ */
+export declare const requestPersistentStorage: (manager?: StorageManagerLike | undefined) => Promise<PersistResult>;
+/** Whether the browser already keeps this site's data, without asking. */
+export declare const isStoragePersisted: (manager?: StorageManagerLike | undefined) => Promise<PersistResult>;
+/** Bytes used and available to this site, or null where the browser won't say. */
+export declare const estimateStorage: (manager?: StorageManagerLike | undefined) => Promise<{
+    readonly usage: number;
+    readonly quota: number;
+} | null>;

package/dist/browser/persist.js

@@ -0,0 +1,42 @@
+//#region src/browser/persist.ts
+var defaultManager = () => globalThis.navigator?.storage;
+/**
+* Asks the browser to keep this site's data. Call it from the player's gesture of pinning a
+* game; never on page load. Already-persisted storage resolves without asking again, and a
+* browser that throws counts as `unsupported`.
+*/
+var requestPersistentStorage = async (manager = defaultManager()) => {
+	if (manager?.persist === void 0) return "unsupported";
+	try {
+		if (await manager.persisted?.() === true) return "persisted";
+		return await manager.persist() ? "persisted" : "denied";
+	} catch {
+		return "unsupported";
+	}
+};
+/** Whether the browser already keeps this site's data, without asking. */
+var isStoragePersisted = async (manager = defaultManager()) => {
+	if (manager?.persisted === void 0) return "unsupported";
+	try {
+		return await manager.persisted() ? "persisted" : "denied";
+	} catch {
+		return "unsupported";
+	}
+};
+/** Bytes used and available to this site, or null where the browser won't say. */
+var estimateStorage = async (manager = defaultManager()) => {
+	if (manager?.estimate === void 0) return null;
+	try {
+		const { usage, quota } = await manager.estimate();
+		return usage === void 0 || quota === void 0 ? null : {
+			usage,
+			quota
+		};
+	} catch {
+		return null;
+	}
+};
+//#endregion
+export { estimateStorage, isStoragePersisted, requestPersistentStorage };
+
+//# sourceMappingURL=persist.js.map

package/dist/browser/persist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist.js","names":[],"sources":["../../src/browser/persist.ts"],"sourcesContent":["// Persistent storage (offline-and-updates.md, \"Cache tiers\"): the PWA asks for it when a\n// player first pins a game, so the browser won't evict saves and pinned games under pressure.\n\n/** The parts of `navigator.storage` these helpers use. */\nexport type StorageManagerLike = {\n  persist?(): Promise<boolean>;\n  persisted?(): Promise<boolean>;\n  estimate?(): Promise<{ usage?: number; quota?: number }>;\n};\n\n/** `persisted`: the browser won't evict this site's data. `denied`: it may. `unsupported`: it can't say. */\nexport type PersistResult = 'persisted' | 'denied' | 'unsupported';\n\nconst defaultManager = (): StorageManagerLike | undefined =>\n  (globalThis as { navigator?: { storage?: StorageManagerLike } }).navigator?.storage;\n\n/**\n * Asks the browser to keep this site's data. Call it from the player's gesture of pinning a\n * game; never on page load. Already-persisted storage resolves without asking again, and a\n * browser that throws counts as `unsupported`.\n */\nexport const requestPersistentStorage = async (\n  manager: StorageManagerLike | undefined = defaultManager(),\n): Promise<PersistResult> => {\n  if (manager?.persist === undefined) return 'unsupported';\n  try {\n    if ((await manager.persisted?.()) === true) return 'persisted';\n    return (await manager.persist()) ? 'persisted' : 'denied';\n  } catch {\n    return 'unsupported';\n  }\n};\n\n/** Whether the browser already keeps this site's data, without asking. */\nexport const isStoragePersisted = async (\n  manager: StorageManagerLike | undefined = defaultManager(),\n): Promise<PersistResult> => {\n  if (manager?.persisted === undefined) return 'unsupported';\n  try {\n    return (await manager.persisted()) ? 'persisted' : 'denied';\n  } catch {\n    return 'unsupported';\n  }\n};\n\n/** Bytes used and available to this site, or null where the browser won't say. */\nexport const estimateStorage = async (\n  manager: StorageManagerLike | undefined = defaultManager(),\n): Promise<{ readonly usage: number; readonly quota: number } | null> => {\n  if (manager?.estimate === undefined) return null;\n  try {\n    const { usage, quota } = await manager.estimate();\n    return usage === undefined || quota === undefined ? null : { usage, quota };\n  } catch {\n    return null;\n  }\n};\n"],"mappings":";AAaA,IAAM,uBACH,WAAgE,WAAW;;;;;;AAO9E,IAAa,2BAA2B,OACtC,UAA0C,eAAe,MAC9B;CAC3B,IAAI,SAAS,YAAY,KAAA,GAAW,OAAO;CAC3C,IAAI;EACF,IAAK,MAAM,QAAQ,YAAY,MAAO,MAAM,OAAO;EACnD,OAAQ,MAAM,QAAQ,QAAQ,IAAK,cAAc;CACnD,QAAQ;EACN,OAAO;CACT;AACF;;AAGA,IAAa,qBAAqB,OAChC,UAA0C,eAAe,MAC9B;CAC3B,IAAI,SAAS,cAAc,KAAA,GAAW,OAAO;CAC7C,IAAI;EACF,OAAQ,MAAM,QAAQ,UAAU,IAAK,cAAc;CACrD,QAAQ;EACN,OAAO;CACT;AACF;;AAGA,IAAa,kBAAkB,OAC7B,UAA0C,eAAe,MACc;CACvE,IAAI,SAAS,aAAa,KAAA,GAAW,OAAO;CAC5C,IAAI;EACF,MAAM,EAAE,OAAO,UAAU,MAAM,QAAQ,SAAS;EAChD,OAAO,UAAU,KAAA,KAAa,UAAU,KAAA,IAAY,OAAO;GAAE;GAAO;EAAM;CAC5E,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/changes.d.ts

@@ -0,0 +1,26 @@
+/** A change another tab should hear about. Preferences are the only kind so far. */
+export type StorageChange = {
+    readonly kind: 'preferences';
+    readonly playerId: string;
+};
+/** Parses a message from another tab. It crossed a boundary, so anything else is null. */
+export declare const parseStorageChange: (message: unknown) => Promise<StorageChange | null>;
+/**
+ * Carries changes between the tabs of one browser. A feed never hands a change back to the
+ * tab that published it; that tab has already told its own listeners.
+ */
+export interface ChangeFeed {
+    /** Tells the other tabs. Never throws: a tab that can't be told simply isn't. */
+    publish(change: StorageChange): void;
+    /** Called with each message from another tab, unparsed. Returns an idempotent unsubscribe. */
+    subscribe(listener: (message: unknown) => void): () => void;
+    /** Stops listening and publishing. Idempotent. */
+    close(): void;
+}
+/**
+ * Feeds that reach each other in memory, for tests: each `feed()` stands for one tab, and a
+ * change reaches every other feed asynchronously, as a browser delivers it.
+ */
+export declare const createMemoryChangeHub: () => {
+    feed(): ChangeFeed;
+};

package/dist/changes.js

@@ -0,0 +1,50 @@
+import { isKeyPart } from "./keys.js";
+import { validate } from "./validate.js";
+import * as z from "zod/mini";
+//#region src/changes.ts
+var { structuredClone } = globalThis;
+var STORAGE_CHANGE = z.object({
+	kind: z.literal("preferences"),
+	playerId: z.string().check(z.refine(isKeyPart))
+});
+/** Parses a message from another tab. It crossed a boundary, so anything else is null. */
+var parseStorageChange = async (message) => {
+	const parsed = await validate(STORAGE_CHANGE, message);
+	return parsed.ok ? parsed.value : null;
+};
+/**
+* Feeds that reach each other in memory, for tests: each `feed()` stands for one tab, and a
+* change reaches every other feed asynchronously, as a browser delivers it.
+*/
+var createMemoryChangeHub = () => {
+	const feeds = /* @__PURE__ */ new Set();
+	return { feed: () => {
+		const listeners = /* @__PURE__ */ new Set();
+		feeds.add(listeners);
+		return {
+			publish: (change) => {
+				for (const other of feeds) {
+					if (other === listeners) continue;
+					Promise.resolve().then(() => {
+						for (const listener of [...other]) listener(structuredClone(change));
+					});
+				}
+			},
+			subscribe: (listener) => {
+				const entry = (message) => listener(message);
+				listeners.add(entry);
+				return () => {
+					listeners.delete(entry);
+				};
+			},
+			close: () => {
+				listeners.clear();
+				feeds.delete(listeners);
+			}
+		};
+	} };
+};
+//#endregion
+export { createMemoryChangeHub, parseStorageChange };
+
+//# sourceMappingURL=changes.js.map

package/dist/changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.js","names":[],"sources":["../src/changes.ts"],"sourcesContent":["// Telling a browser's other tabs that stored data changed (gp-d4v). The core only describes\n// the feed; '@joystyk/storage/browser' builds one over BroadcastChannel, or over the `storage`\n// event where BroadcastChannel is missing. A change carries no data, only what changed:\n// a tab that hears of one reads the record back from storage, through its schema.\nimport * as z from 'zod/mini';\nimport { isKeyPart } from './keys.ts';\nimport { validate } from './validate.ts';\n\n// Node, browsers and workers all have structuredClone; the core's ES-only lib doesn't name it.\nconst { structuredClone } = globalThis as unknown as { structuredClone: <T>(value: T) => T };\n\n/** A change another tab should hear about. Preferences are the only kind so far. */\nexport type StorageChange = { readonly kind: 'preferences'; readonly playerId: string };\n\nconst STORAGE_CHANGE = z.object({\n  kind: z.literal('preferences'),\n  playerId: z.string().check(z.refine(isKeyPart)),\n});\n\n/** Parses a message from another tab. It crossed a boundary, so anything else is null. */\nexport const parseStorageChange = async (message: unknown): Promise<StorageChange | null> => {\n  const parsed = await validate(STORAGE_CHANGE, message);\n  return parsed.ok ? parsed.value : null;\n};\n\n/**\n * Carries changes between the tabs of one browser. A feed never hands a change back to the\n * tab that published it; that tab has already told its own listeners.\n */\nexport interface ChangeFeed {\n  /** Tells the other tabs. Never throws: a tab that can't be told simply isn't. */\n  publish(change: StorageChange): void;\n  /** Called with each message from another tab, unparsed. Returns an idempotent unsubscribe. */\n  subscribe(listener: (message: unknown) => void): () => void;\n  /** Stops listening and publishing. Idempotent. */\n  close(): void;\n}\n\n/**\n * Feeds that reach each other in memory, for tests: each `feed()` stands for one tab, and a\n * change reaches every other feed asynchronously, as a browser delivers it.\n */\nexport const createMemoryChangeHub = (): { feed(): ChangeFeed } => {\n  const feeds = new Set<Set<(message: unknown) => void>>();\n  return {\n    feed: () => {\n      const listeners = new Set<(message: unknown) => void>();\n      feeds.add(listeners);\n      return {\n        publish: (change) => {\n          for (const other of feeds) {\n            if (other === listeners) continue;\n            void Promise.resolve().then(() => {\n              for (const listener of [...other]) listener(structuredClone(change));\n            });\n          }\n        },\n        subscribe: (listener) => {\n          const entry = (message: unknown): void => listener(message);\n          listeners.add(entry);\n          return () => {\n            listeners.delete(entry);\n          };\n        },\n        close: () => {\n          listeners.clear();\n          feeds.delete(listeners);\n        },\n      };\n    },\n  };\n};\n"],"mappings":";;;;AASA,IAAM,EAAE,oBAAoB;AAK5B,IAAM,iBAAiB,EAAE,OAAO;CAC9B,MAAM,EAAE,QAAQ,aAAa;CAC7B,UAAU,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,OAAO,SAAS,CAAC;AAChD,CAAC;;AAGD,IAAa,qBAAqB,OAAO,YAAoD;CAC3F,MAAM,SAAS,MAAM,SAAS,gBAAgB,OAAO;CACrD,OAAO,OAAO,KAAK,OAAO,QAAQ;AACpC;;;;;AAmBA,IAAa,8BAAsD;CACjE,MAAM,wBAAQ,IAAI,IAAqC;CACvD,OAAO,EACL,YAAY;EACV,MAAM,4BAAY,IAAI,IAAgC;EACtD,MAAM,IAAI,SAAS;EACnB,OAAO;GACL,UAAU,WAAW;IACnB,KAAK,MAAM,SAAS,OAAO;KACzB,IAAI,UAAU,WAAW;KACzB,QAAa,QAAQ,CAAC,CAAC,WAAW;MAChC,KAAK,MAAM,YAAY,CAAC,GAAG,KAAK,GAAG,SAAS,gBAAgB,MAAM,CAAC;KACrE,CAAC;IACH;GACF;GACA,YAAY,aAAa;IACvB,MAAM,SAAS,YAA2B,SAAS,OAAO;IAC1D,UAAU,IAAI,KAAK;IACnB,aAAa;KACX,UAAU,OAAO,KAAK;IACxB;GACF;GACA,aAAa;IACX,UAAU,MAAM;IAChB,MAAM,OAAO,SAAS;GACxB;EACF;CACF,EACF;AACF"}

package/dist/envelope.d.ts

@@ -0,0 +1,4 @@
+import { type SaveEnvelope } from '@joystyk/contracts';
+import * as z from 'zod/mini';
+/** Decodes a `SaveEnvelope`. `state` is only checked to be JSON. */
+export declare const saveEnvelope: z.ZodMiniType<SaveEnvelope>;

package/dist/envelope.js

@@ -0,0 +1,109 @@
+import { json } from "./validate.js";
+import { ASSIST_KINDS } from "@joystyk/contracts";
+import * as z from "zod/mini";
+//#region src/envelope.ts
+var count = z.int().check(z.nonnegative());
+var version = z.int().check(z.positive());
+var milliseconds = z.number().check(z.nonnegative());
+var rngState = z.object({
+	algorithm: z.string(),
+	words: z.array(z.number())
+});
+var controller = z.enum(["human", "ai"]);
+var seatInfo = z.object({
+	id: count,
+	name: z.string(),
+	controller,
+	aiLevel: z.optional(z.string())
+});
+var seatChange = z.discriminatedUnion("type", [z.object({
+	type: z.literal("controller"),
+	controller,
+	name: z.string(),
+	aiLevel: z.optional(z.string())
+}), z.object({ type: z.literal("left") })]);
+var jobOutcome = z.union([z.object({
+	ok: z.literal(true),
+	value: json,
+	presentation: z.optional(json)
+}), z.object({
+	ok: z.literal(false),
+	reason: z.enum(["timeout", "failed"])
+})]);
+var engineInput = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("command"),
+		seat: count,
+		command: json
+	}),
+	z.object({
+		kind: z.literal("seat"),
+		seat: count,
+		change: seatChange
+	}),
+	z.object({
+		kind: z.literal("timeout"),
+		seat: count
+	}),
+	z.object({
+		kind: z.literal("resign"),
+		seat: count
+	}),
+	z.object({
+		kind: z.literal("job"),
+		jobId: z.string(),
+		outcome: jobOutcome
+	})
+]);
+var replay = z.discriminatedUnion("layer", [z.object({
+	layer: z.literal(2),
+	gameId: z.string(),
+	rulesVersion: version,
+	config: json,
+	seats: z.array(seatInfo),
+	seed: rngState,
+	inputs: z.array(engineInput)
+}), z.object({
+	layer: z.literal(3),
+	gameId: z.string(),
+	rulesVersion: version,
+	config: json,
+	seed: rngState,
+	inputs: z.array(z.object({
+		tick: count,
+		input: json
+	})),
+	endTick: count
+})]);
+/** Decodes a `SaveEnvelope`. `state` is only checked to be JSON. */
+var saveEnvelope = z.object({
+	gameId: z.string(),
+	build: z.string(),
+	rulesVersion: version,
+	saveVersion: version,
+	daily: z.optional(z.object({
+		puzzleId: z.string().check(z.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*:\d{4}-\d{2}-\d{2}$/)),
+		contentHash: z.string().check(z.minLength(1))
+	})),
+	rng: rngState,
+	seats: z.array(seatInfo),
+	state: json,
+	tick: z.optional(count),
+	elapsedMs: z.optional(milliseconds),
+	clockStarted: z.optional(z.boolean()),
+	replay: z.optional(replay),
+	aiRng: z.optional(rngState),
+	undosUsed: z.optional(count),
+	assists: z.optional(z.array(z.enum(ASSIST_KINDS))),
+	assistCounts: z.optional(z.strictObject({
+		undo: z.optional(count),
+		hint: z.optional(count),
+		check: z.optional(count),
+		reveal: z.optional(count),
+		shuffle: z.optional(count)
+	}))
+});
+//#endregion
+export { saveEnvelope };
+
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","names":[],"sources":["../src/envelope.ts"],"sourcesContent":["// Standard Schemas for the contracts' save envelope (game-contract.md, \"Saves\"). The game's\n// own state inside it stays `Json` here; the game's migrations and `schemas.state` decode it.\nimport {\n  ASSIST_KINDS,\n  type AssistKind,\n  type EngineInput,\n  type Json,\n  type Replay,\n  type SaveEnvelope,\n} from '@joystyk/contracts';\nimport * as z from 'zod/mini';\nimport { json } from './validate.ts';\n\nconst count = z.int().check(z.nonnegative());\nconst version = z.int().check(z.positive());\nconst milliseconds = z.number().check(z.nonnegative());\n\nconst rngState = z.object({ algorithm: z.string(), words: z.array(z.number()) });\n\nconst controller = z.enum(['human', 'ai']);\n\nconst seatInfo = z.object({\n  id: count,\n  name: z.string(),\n  controller,\n  aiLevel: z.optional(z.string()),\n});\n\nconst seatChange = z.discriminatedUnion('type', [\n  z.object({ type: z.literal('controller'), controller, name: z.string(), aiLevel: z.optional(z.string()) }),\n  z.object({ type: z.literal('left') }),\n]);\n\nconst jobOutcome = z.union([\n  z.object({ ok: z.literal(true), value: json, presentation: z.optional(json) }),\n  z.object({ ok: z.literal(false), reason: z.enum(['timeout', 'failed']) }),\n]);\n\nconst engineInput: z.ZodMiniType<EngineInput<Json>> = z.discriminatedUnion('kind', [\n  z.object({ kind: z.literal('command'), seat: count, command: json }),\n  z.object({ kind: z.literal('seat'), seat: count, change: seatChange }),\n  z.object({ kind: z.literal('timeout'), seat: count }),\n  z.object({ kind: z.literal('resign'), seat: count }),\n  z.object({ kind: z.literal('job'), jobId: z.string(), outcome: jobOutcome }),\n]);\n\nconst replay: z.ZodMiniType<Replay> = z.discriminatedUnion('layer', [\n  z.object({\n    layer: z.literal(2),\n    gameId: z.string(),\n    rulesVersion: version,\n    config: json,\n    seats: z.array(seatInfo),\n    seed: rngState,\n    inputs: z.array(engineInput),\n  }),\n  z.object({\n    layer: z.literal(3),\n    gameId: z.string(),\n    rulesVersion: version,\n    config: json,\n    seed: rngState,\n    inputs: z.array(z.object({ tick: count, input: json })),\n    endTick: count,\n  }),\n]);\n\n/** Decodes a `SaveEnvelope`. `state` is only checked to be JSON. */\nexport const saveEnvelope: z.ZodMiniType<SaveEnvelope> = z.object({\n  gameId: z.string(),\n  build: z.string(),\n  rulesVersion: version,\n  saveVersion: version,\n  daily: z.optional(\n    z.object({\n      puzzleId: z.string().check(z.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*:\\d{4}-\\d{2}-\\d{2}$/)),\n      contentHash: z.string().check(z.minLength(1)),\n    }),\n  ),\n  rng: rngState,\n  seats: z.array(seatInfo),\n  state: json,\n  tick: z.optional(count),\n  elapsedMs: z.optional(milliseconds),\n  clockStarted: z.optional(z.boolean()),\n  replay: z.optional(replay),\n  // The runner's records. The schema keeps them: an object schema drops keys it doesn't name.\n  aiRng: z.optional(rngState),\n  undosUsed: z.optional(count),\n  assists: z.optional(z.array(z.enum(ASSIST_KINDS as readonly [AssistKind, ...AssistKind[]]))),\n  assistCounts: z.optional(\n    z.strictObject({\n      undo: z.optional(count),\n      hint: z.optional(count),\n      check: z.optional(count),\n      reveal: z.optional(count),\n      shuffle: z.optional(count),\n    }),\n  ),\n});\n"],"mappings":"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"}

package/dist/game-data.d.ts

@@ -0,0 +1,17 @@
+import type { GameStorage, Json } from '@joystyk/contracts';
+import type { StorageError } from './backend.js';
+import { type RecordContext } from './record.js';
+/** Version 1 of a game's own key-value record: any JSON. */
+export declare const GAME_DATA_RECORD: import("./record.js").RecordKind<Json>;
+/** Thrown (as a rejection) by a `GameStorage` write that failed; `error` says why. */
+export declare class StorageFailure extends Error {
+    readonly error: StorageError;
+    constructor(error: StorageError);
+}
+/**
+ * The contracts' `GameStorage` (`PlatformApi.storage`) for one player and game. The game's
+ * keys are free-form, 1–256 characters. A read that fails resolves to null (the player has
+ * already been told); a failed write rejects with a `StorageFailure`, because the contract's
+ * `Promise<void>` has no other way to report it.
+ */
+export declare const createGameStorage: (context: RecordContext, playerId: string, gameId: string) => GameStorage;

package/dist/game-data.js

@@ -0,0 +1,54 @@
+import { gameDataKey } from "./keys.js";
+import { json } from "./validate.js";
+import { createRecordStore, defineRecordKind } from "./record.js";
+//#region src/game-data.ts
+/** Version 1 of a game's own key-value record: any JSON. */
+var GAME_DATA_RECORD = defineRecordKind({
+	store: "game-data",
+	version: 1,
+	schema: json,
+	label: "piece of game data"
+});
+/** Thrown (as a rejection) by a `GameStorage` write that failed; `error` says why. */
+var StorageFailure = class extends Error {
+	error;
+	constructor(error) {
+		super(error.message);
+		this.name = "StorageFailure";
+		this.error = error;
+	}
+};
+var orThrow = async (result) => {
+	const settled = await result;
+	if (!settled.ok) throw new StorageFailure(settled.error);
+	return settled.value;
+};
+/**
+* The contracts' `GameStorage` (`PlatformApi.storage`) for one player and game. The game's
+* keys are free-form, 1–256 characters. A read that fails resolves to null (the player has
+* already been told); a failed write rejects with a `StorageFailure`, because the contract's
+* `Promise<void>` has no other way to report it.
+*/
+var createGameStorage = (context, playerId, gameId) => {
+	const records = createRecordStore(context, GAME_DATA_RECORD);
+	return {
+		get: async (key) => {
+			const full = gameDataKey(playerId, gameId, key);
+			if (!full.ok) return null;
+			const value = await records.get(full.value);
+			return value.ok ? value.value : null;
+		},
+		set: async (key, value) => {
+			const full = gameDataKey(playerId, gameId, key);
+			await orThrow(full.ok ? records.set(full.value, value) : Promise.resolve(full));
+		},
+		delete: async (key) => {
+			const full = gameDataKey(playerId, gameId, key);
+			await orThrow(full.ok ? records.delete(full.value) : Promise.resolve(full));
+		}
+	};
+};
+//#endregion
+export { GAME_DATA_RECORD, StorageFailure, createGameStorage };
+
+//# sourceMappingURL=game-data.js.map

package/dist/game-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"game-data.js","names":[],"sources":["../src/game-data.ts"],"sourcesContent":["import type { GameStorage, Json, Result } from '@joystyk/contracts';\nimport type { StorageError } from './backend.ts';\nimport { gameDataKey } from './keys.ts';\nimport { createRecordStore, defineRecordKind, type RecordContext } from './record.ts';\nimport { json } from './validate.ts';\n\n/** Version 1 of a game's own key-value record: any JSON. */\nexport const GAME_DATA_RECORD = defineRecordKind<Json>({\n  store: 'game-data',\n  version: 1,\n  schema: json,\n  label: 'piece of game data',\n});\n\n/** Thrown (as a rejection) by a `GameStorage` write that failed; `error` says why. */\nexport class StorageFailure extends Error {\n  readonly error: StorageError;\n  constructor(error: StorageError) {\n    super(error.message);\n    this.name = 'StorageFailure';\n    this.error = error;\n  }\n}\n\nconst orThrow = async <T>(result: Promise<Result<T, StorageError>>): Promise<T> => {\n  const settled = await result;\n  if (!settled.ok) throw new StorageFailure(settled.error);\n  return settled.value;\n};\n\n/**\n * The contracts' `GameStorage` (`PlatformApi.storage`) for one player and game. The game's\n * keys are free-form, 1–256 characters. A read that fails resolves to null (the player has\n * already been told); a failed write rejects with a `StorageFailure`, because the contract's\n * `Promise<void>` has no other way to report it.\n */\nexport const createGameStorage = (context: RecordContext, playerId: string, gameId: string): GameStorage => {\n  const records = createRecordStore(context, GAME_DATA_RECORD);\n  return {\n    get: async (key) => {\n      const full = gameDataKey(playerId, gameId, key);\n      if (!full.ok) return null;\n      const value = await records.get(full.value);\n      return value.ok ? value.value : null;\n    },\n    set: async (key, value) => {\n      const full = gameDataKey(playerId, gameId, key);\n      await orThrow(full.ok ? records.set(full.value, value) : Promise.resolve(full));\n    },\n    delete: async (key) => {\n      const full = gameDataKey(playerId, gameId, key);\n      await orThrow(full.ok ? records.delete(full.value) : Promise.resolve(full));\n    },\n  };\n};\n"],"mappings":";;;;;AAOA,IAAa,mBAAmB,iBAAuB;CACrD,OAAO;CACP,SAAS;CACT,QAAQ;CACR,OAAO;AACT,CAAC;;AAGD,IAAa,iBAAb,cAAoC,MAAM;CACxC;CACA,YAAY,OAAqB;EAC/B,MAAM,MAAM,OAAO;EACnB,KAAK,OAAO;EACZ,KAAK,QAAQ;CACf;AACF;AAEA,IAAM,UAAU,OAAU,WAAyD;CACjF,MAAM,UAAU,MAAM;CACtB,IAAI,CAAC,QAAQ,IAAI,MAAM,IAAI,eAAe,QAAQ,KAAK;CACvD,OAAO,QAAQ;AACjB;;;;;;;AAQA,IAAa,qBAAqB,SAAwB,UAAkB,WAAgC;CAC1G,MAAM,UAAU,kBAAkB,SAAS,gBAAgB;CAC3D,OAAO;EACL,KAAK,OAAO,QAAQ;GAClB,MAAM,OAAO,YAAY,UAAU,QAAQ,GAAG;GAC9C,IAAI,CAAC,KAAK,IAAI,OAAO;GACrB,MAAM,QAAQ,MAAM,QAAQ,IAAI,KAAK,KAAK;GAC1C,OAAO,MAAM,KAAK,MAAM,QAAQ;EAClC;EACA,KAAK,OAAO,KAAK,UAAU;GACzB,MAAM,OAAO,YAAY,UAAU,QAAQ,GAAG;GAC9C,MAAM,QAAQ,KAAK,KAAK,QAAQ,IAAI,KAAK,OAAO,KAAK,IAAI,QAAQ,QAAQ,IAAI,CAAC;EAChF;EACA,QAAQ,OAAO,QAAQ;GACrB,MAAM,OAAO,YAAY,UAAU,QAAQ,GAAG;GAC9C,MAAM,QAAQ,KAAK,KAAK,QAAQ,OAAO,KAAK,KAAK,IAAI,QAAQ,QAAQ,IAAI,CAAC;EAC5E;CACF;AACF"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { MESSAGES, STORE_NAMES, storageError, type PutIfAbsent, type StorageBackend, type StorageError, type StorageErrorCode, type StoreName, } from './backend.js';
+export { createMemoryChangeHub, parseStorageChange, type ChangeFeed, type StorageChange } from './changes.js';
+export { createMemoryBackend, type MemoryBackend, type MemoryBackendOptions } from './memory.js';
+export { createRecordStore, decodeRecord, defineRecordKind, putWithQuotaRetry, type ArchivedRecord, type RecordContext, type RecordKind, type RecordStore, type StorageNotice, type StorageNoticeCode, } from './record.js';
+export { isKeyPart, MAX_GAME_KEY_LENGTH } from './keys.js';
+export { json, validate, type Issue } from './validate.js';
+export { saveEnvelope } from './envelope.js';
+export { SAVE_RECORD, type SavedGame, type SaveDecoder, type SaveStore } from './saves.js';
+export { EMPTY_STATS, recordOutcome, STATS_RECORD, type GameStats, type StatsStore } from './stats.js';
+export { EMPTY_STREAK, STREAK_RECORD, type Streak, type StreakStore } from './streaks.js';
+export { DEFAULT_PREFERENCES, PREFERENCES_RECORD, resolvePreferences, type PreferencesSource, type PreferencesStore, type ResolvedPreferences, type StoredPreferences, type SystemEnvironment, } from './preferences.js';
+export { GAME_DATA_RECORD, StorageFailure } from './game-data.js';
+export { openStorage, type PlayerStorage, type Storage, type StorageOptions } from './storage.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+import { MESSAGES, STORE_NAMES, storageError } from "./backend.js";
+import { createMemoryBackend } from "./memory.js";
+import { MAX_GAME_KEY_LENGTH, isKeyPart } from "./keys.js";
+import { json, validate } from "./validate.js";
+import { createRecordStore, decodeRecord, defineRecordKind, putWithQuotaRetry } from "./record.js";
+import { GAME_DATA_RECORD, StorageFailure } from "./game-data.js";
+import { createMemoryChangeHub, parseStorageChange } from "./changes.js";
+import { DEFAULT_PREFERENCES, PREFERENCES_RECORD, resolvePreferences } from "./preferences.js";
+import { saveEnvelope } from "./envelope.js";
+import { SAVE_RECORD } from "./saves.js";
+import { EMPTY_STATS, STATS_RECORD, recordOutcome } from "./stats.js";
+import { EMPTY_STREAK, STREAK_RECORD } from "./streaks.js";
+import { openStorage } from "./storage.js";
+export { DEFAULT_PREFERENCES, EMPTY_STATS, EMPTY_STREAK, GAME_DATA_RECORD, MAX_GAME_KEY_LENGTH, MESSAGES, PREFERENCES_RECORD, SAVE_RECORD, STATS_RECORD, STORE_NAMES, STREAK_RECORD, StorageFailure, createMemoryBackend, createMemoryChangeHub, createRecordStore, decodeRecord, defineRecordKind, isKeyPart, json, openStorage, parseStorageChange, putWithQuotaRetry, recordOutcome, resolvePreferences, saveEnvelope, storageError, validate };

package/dist/keys.d.ts

@@ -0,0 +1,14 @@
+import { type Result } from '@joystyk/contracts';
+import { type StorageError } from './backend.js';
+/** True for a player id or slot name that can be part of a key: 1–64 letters, digits, `_` or `-`. */
+export declare const isKeyPart: (value: unknown) => value is string;
+/** The longest free-form key a game may use through `PlatformApi.storage`. */
+export declare const MAX_GAME_KEY_LENGTH = 256;
+/** `<playerId>/<gameId>/`: the prefix of everything one player keeps for one game. */
+export declare const gamePrefix: (playerId: string, gameId: string) => Result<string, StorageError>;
+/** `<playerId>/<gameId>/<slot>`, for saves. */
+export declare const slotKey: (playerId: string, gameId: string, slot: string) => Result<string, StorageError>;
+/** `<playerId>/<gameId>/<key>`, for a game's own key-value data. The key is free-form. */
+export declare const gameDataKey: (playerId: string, gameId: string, key: string) => Result<string, StorageError>;
+/** `<playerId>/<gameId>`, for per-game records with one value each (stats, streaks). */
+export declare const gameKey: (playerId: string, gameId: string) => Result<string, StorageError>;

package/dist/keys.js

@@ -0,0 +1,29 @@
+import { MESSAGES, storageError } from "./backend.js";
+import { err, isGameId, ok } from "@joystyk/contracts";
+//#region src/keys.ts
+var PART = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** True for a player id or slot name that can be part of a key: 1–64 letters, digits, `_` or `-`. */
+var isKeyPart = (value) => typeof value === "string" && PART.test(value);
+/** The longest free-form key a game may use through `PlatformApi.storage`. */
+var MAX_GAME_KEY_LENGTH = 256;
+var invalid = (what, value) => err(storageError("InvalidKey", MESSAGES.InvalidKey, { [what]: value }));
+/** `<playerId>/<gameId>/`: the prefix of everything one player keeps for one game. */
+var gamePrefix = (playerId, gameId) => isGameId(gameId) ? ok(`${playerId}/${gameId}/`) : invalid("gameId", gameId);
+/** `<playerId>/<gameId>/<slot>`, for saves. */
+var slotKey = (playerId, gameId, slot) => {
+	const prefix = gamePrefix(playerId, gameId);
+	if (!prefix.ok) return prefix;
+	return isKeyPart(slot) ? ok(prefix.value + slot) : invalid("slot", slot);
+};
+/** `<playerId>/<gameId>/<key>`, for a game's own key-value data. The key is free-form. */
+var gameDataKey = (playerId, gameId, key) => {
+	const prefix = gamePrefix(playerId, gameId);
+	if (!prefix.ok) return prefix;
+	return key.length > 0 && key.length <= 256 ? ok(prefix.value + key) : invalid("key", key);
+};
+/** `<playerId>/<gameId>`, for per-game records with one value each (stats, streaks). */
+var gameKey = (playerId, gameId) => isGameId(gameId) ? ok(`${playerId}/${gameId}`) : invalid("gameId", gameId);
+//#endregion
+export { MAX_GAME_KEY_LENGTH, gameDataKey, gameKey, gamePrefix, isKeyPart, slotKey };
+
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","names":[],"sources":["../src/keys.ts"],"sourcesContent":["import { err, isGameId, ok, type Result } from '@joystyk/contracts';\nimport { MESSAGES, storageError, type StorageError } from './backend.ts';\n\n// Keys are paths: `<playerId>/<gameId>/<slot>`. Every part but a game's own free-form key is\n// restricted, so a part can never contain the separator and a prefix lists exactly one\n// player's or one game's records.\n\nconst PART = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;\n\n/** True for a player id or slot name that can be part of a key: 1–64 letters, digits, `_` or `-`. */\nexport const isKeyPart = (value: unknown): value is string => typeof value === 'string' && PART.test(value);\n\n/** The longest free-form key a game may use through `PlatformApi.storage`. */\nexport const MAX_GAME_KEY_LENGTH = 256;\n\nconst invalid = (what: string, value: string): Result<never, StorageError> =>\n  err(storageError('InvalidKey', MESSAGES.InvalidKey, { [what]: value }));\n\n/** `<playerId>/<gameId>/`: the prefix of everything one player keeps for one game. */\nexport const gamePrefix = (playerId: string, gameId: string): Result<string, StorageError> =>\n  isGameId(gameId) ? ok(`${playerId}/${gameId}/`) : invalid('gameId', gameId);\n\n/** `<playerId>/<gameId>/<slot>`, for saves. */\nexport const slotKey = (playerId: string, gameId: string, slot: string): Result<string, StorageError> => {\n  const prefix = gamePrefix(playerId, gameId);\n  if (!prefix.ok) return prefix;\n  return isKeyPart(slot) ? ok(prefix.value + slot) : invalid('slot', slot);\n};\n\n/** `<playerId>/<gameId>/<key>`, for a game's own key-value data. The key is free-form. */\nexport const gameDataKey = (playerId: string, gameId: string, key: string): Result<string, StorageError> => {\n  const prefix = gamePrefix(playerId, gameId);\n  if (!prefix.ok) return prefix;\n  return key.length > 0 && key.length <= MAX_GAME_KEY_LENGTH ? ok(prefix.value + key) : invalid('key', key);\n};\n\n/** `<playerId>/<gameId>`, for per-game records with one value each (stats, streaks). */\nexport const gameKey = (playerId: string, gameId: string): Result<string, StorageError> =>\n  isGameId(gameId) ? ok(`${playerId}/${gameId}`) : invalid('gameId', gameId);\n"],"mappings":";;;AAOA,IAAM,OAAO;;AAGb,IAAa,aAAa,UAAoC,OAAO,UAAU,YAAY,KAAK,KAAK,KAAK;;AAG1G,IAAa,sBAAsB;AAEnC,IAAM,WAAW,MAAc,UAC7B,IAAI,aAAa,cAAc,SAAS,YAAY,GAAG,OAAO,MAAM,CAAC,CAAC;;AAGxE,IAAa,cAAc,UAAkB,WAC3C,SAAS,MAAM,IAAI,GAAG,GAAG,SAAS,GAAG,OAAO,EAAE,IAAI,QAAQ,UAAU,MAAM;;AAG5E,IAAa,WAAW,UAAkB,QAAgB,SAA+C;CACvG,MAAM,SAAS,WAAW,UAAU,MAAM;CAC1C,IAAI,CAAC,OAAO,IAAI,OAAO;CACvB,OAAO,UAAU,IAAI,IAAI,GAAG,OAAO,QAAQ,IAAI,IAAI,QAAQ,QAAQ,IAAI;AACzE;;AAGA,IAAa,eAAe,UAAkB,QAAgB,QAA8C;CAC1G,MAAM,SAAS,WAAW,UAAU,MAAM;CAC1C,IAAI,CAAC,OAAO,IAAI,OAAO;CACvB,OAAO,IAAI,SAAS,KAAK,IAAI,UAAA,MAAgC,GAAG,OAAO,QAAQ,GAAG,IAAI,QAAQ,OAAO,GAAG;AAC1G;;AAGA,IAAa,WAAW,UAAkB,WACxC,SAAS,MAAM,IAAI,GAAG,GAAG,SAAS,GAAG,QAAQ,IAAI,QAAQ,UAAU,MAAM"}