@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.2

package/src/core/offline/local-store.ts

@@ -1,261 +1,259 @@
-/**
- * The offline cache: what the client serves when the hub can't be reached,
- * and where queued writes and buffered events wait. Keys are the v1 client's
- * (`hub:user`, `hub:<slug>:save:<slot>`, `hub:<slug>:queue`, ...), so a page
- * upgraded from a vendored copy keeps that copy's cache and queues.
- */
-import type { Board, Json, SortDir, Stats } from '@diffenderfer-games/hub-contract';
-import { isJson, isNullableString, isNumberRecord, isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
-import { createPageStore, type KeyValueStore } from '../storage/key-value';
-import type { Profile, Save, SaveMeta, SnapshotResponse, User } from '../types';
-import { appendEvent, readEvents, type BufferedEvent } from './events';
-import { betterScore, enqueueOp, readQueue, type QueueOp, type QueueOpInput, type QueuedScoreOptions } from './queue';
-
-/** The key of the locally known user, shared by every game (like the real session). */
-export const USER_KEY = 'hub:user';
-
-/** A board this player has a local best on. */
-export interface LocalBoard {
-  /** The board. */
-  readonly board: Board;
-  /** This player's best score. */
-  readonly best: number;
-}
-
-/** How a stat update combines with the stored value. */
-export type StatUpdateMode = 'set' | 'incr' | 'max';
-
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached user read back from localStorage
-function readUser(stored: unknown): User | null {
-  if (!isRecord(stored)) {
-    return null;
-  }
-  const id = optionalNumber(stored.id);
-  const username = optionalString(stored.username);
-  if (id === undefined || username === undefined) {
-    return null;
-  }
-  return typeof stored.guest === 'boolean' ? { id, username, guest: stored.guest } : { id, username };
-}
-
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached save read back from localStorage
-function readSave(stored: unknown): Save | null {
-  if (!isRecord(stored)) {
-    return null;
-  }
-  const slot = optionalString(stored.slot);
-  const updatedAt = optionalNumber(stored.updatedAt);
-  if (slot === undefined || updatedAt === undefined || !isNullableString(stored.label) || !isJson(stored.data)) {
-    return null;
-  }
-  return { slot, label: stored.label, data: stored.data, updatedAt };
-}
-
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached profile read back from localStorage
-function readProfile(stored: unknown): Profile | null {
-  if (!isRecord(stored)) {
-    return null;
-  }
-  const game = optionalString(stored.game);
-  const updatedAt = optionalNumber(stored.updatedAt);
-  if (game === undefined || updatedAt === undefined || !isNullableString(stored.displayName) || !isJson(stored.data)) {
-    return null;
-  }
-  return { game, displayName: stored.displayName, data: stored.data, updatedAt };
-}
-
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached board read back from localStorage
-function readLocalBoard(stored: unknown): LocalBoard | null {
-  if (!isRecord(stored) || !isRecord(stored.board)) {
-    return null;
-  }
-  const key = optionalString(stored.board.key);
-  const title = optionalString(stored.board.title);
-  const sortDir = stored.board.sortDir === 'asc' || stored.board.sortDir === 'desc' ? stored.board.sortDir : undefined;
-  const best = optionalNumber(stored.best);
-  if (key === undefined || title === undefined || sortDir === undefined || best === undefined) {
-    return null;
-  }
-  return { board: { key, title, sortDir }, best };
-}
-
-/** One game's offline cache, queue and event buffer. */
-export class LocalStore {
-  private readonly prefix: string;
-  private readonly store: KeyValueStore;
-  private sequence = 0;
-
-  /** The cache for game `slug` in `store` (default: `localStorage`, or memory without it). */
-  constructor(slug: string, store: KeyValueStore = createPageStore()) {
-    this.prefix = `hub:${slug}:`;
-    this.store = store;
-  }
-
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON read back from storage, checked by each caller's guard
-  private readStored(key: string): unknown {
-    const text = this.store.read(key);
-    return text === null ? undefined : parseJsonText(text);
-  }
-
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: any JSON-serializable value the cache stores
-  private writeStored(key: string, stored: unknown): void {
-    this.store.write(key, JSON.stringify(stored));
-  }
-
-  /** The locally known user. */
-  getUser(): User | null {
-    return readUser(this.readStored(USER_KEY));
-  }
-
-  /** Remember the user (offline sign-in, or a snapshot). */
-  setUser(user: User): void {
-    this.writeStored(USER_KEY, user);
-  }
-
-  /** Forget the user (offline sign-out). */
-  clearUser(): void {
-    this.store.remove(USER_KEY);
-  }
-
-  /** This game's cached profile. */
-  getProfile(): Profile | null {
-    return readProfile(this.readStored(`${this.prefix}profile`));
-  }
-
-  /** Store this game's profile and return it. */
-  setProfile(game: string, displayName: string | null, profileData: Json): Profile {
-    const profile: Profile = { game, displayName, data: profileData, updatedAt: Date.now() };
-    this.writeStored(`${this.prefix}profile`, profile);
-    return profile;
-  }
-
-  /** Every cached save's metadata, newest first. */
-  listSaves(): SaveMeta[] {
-    return this.store.keys()
-      .filter((key) => key.startsWith(`${this.prefix}save:`))
-      .flatMap((key) => {
-        const save = readSave(this.readStored(key));
-        return save === null ? [] : [{ slot: save.slot, label: save.label, updatedAt: save.updatedAt }];
-      })
-      .sort((first, second) => second.updatedAt - first.updatedAt);
-  }
-
-  /** One cached save, or `null`. */
-  getSave(slot: string): Save | null {
-    return readSave(this.readStored(`${this.prefix}save:${slot}`));
-  }
-
-  /** Store a save and return its `updatedAt`. */
-  putSave(slot: string, saveData: Json, label: string | null): number {
-    const updatedAt = Date.now();
-    this.writeStored(`${this.prefix}save:${slot}`, { slot, label, data: saveData, updatedAt });
-    return updatedAt;
-  }
-
-  /** Forget a save. */
-  deleteSave(slot: string): void {
-    this.store.remove(`${this.prefix}save:${slot}`);
-  }
-
-  /** This game's cached stats. */
-  getStats(): Stats {
-    const stored = this.readStored(`${this.prefix}stats`);
-    return isNumberRecord(stored) ? { ...stored } : {};
-  }
-
-  /** Apply one stat update and return the stat's new value. */
-  updateStat(key: string, amount: number, mode: StatUpdateMode): number {
-    const stats = this.getStats();
-    const current = stats[key] ?? 0;
-    const updated = mode === 'incr' ? current + amount : mode === 'max' ? Math.max(current, amount) : amount;
-    this.writeStored(`${this.prefix}stats`, { ...stats, [key]: updated });
-    return updated;
-  }
-
-  /** The boards this player has a local best on (offline boards only know the player's own best). */
-  listBoards(): Board[] {
-    return this.store.keys()
-      .filter((key) => key.startsWith(`${this.prefix}lb:`))
-      .flatMap((key) => {
-        const local = readLocalBoard(this.readStored(key));
-        return local === null ? [] : [local.board];
-      });
-  }
-
-  /** One board's local best, or `null`. */
-  getBoard(key: string): LocalBoard | null {
-    return readLocalBoard(this.readStored(`${this.prefix}lb:${key}`));
-  }
-
-  /** Record a score locally, keeping the best one; returns the board and best. */
-  submitScore(key: string, score: number, options: QueuedScoreOptions): LocalBoard {
-    const existing = this.getBoard(key);
-    const sortDir: SortDir = existing?.board.sortDir ?? (options.sort === 'asc' ? 'asc' : 'desc');
-    const board: Board = existing?.board ?? { key, title: options.title !== undefined && options.title !== '' ? options.title : key, sortDir };
-    const best = existing === null ? score : betterScore(existing.best, score, sortDir);
-    this.writeStored(`${this.prefix}lb:${key}`, { board, best });
-    return { board, best };
-  }
-
-  /** The queued writes, oldest first. */
-  getQueue(): QueueOp[] {
-    return readQueue(this.readStored(`${this.prefix}queue`));
-  }
-
-  /** Replace the queue. */
-  setQueue(queue: readonly QueueOp[]): void {
-    this.writeStored(`${this.prefix}queue`, queue);
-  }
-
-  /** How many writes are queued. */
-  queueLength(): number {
-    return this.getQueue().length;
-  }
-
-  /** Queue a write, collapsing it with a compatible queued one. */
-  enqueue(input: QueueOpInput): void {
-    this.sequence += 1;
-    const now = Date.now();
-    this.setQueue(enqueueOp(this.getQueue(), { ...input, id: `${String(now)}-${String(this.sequence)}`, ts: now }));
-  }
-
-  /** The buffered analytics events, oldest first. */
-  getEvents(): BufferedEvent[] {
-    return readEvents(this.readStored(`${this.prefix}events`));
-  }
-
-  /** Replace the event buffer. */
-  setEvents(events: readonly BufferedEvent[]): void {
-    this.writeStored(`${this.prefix}events`, events);
-  }
-
-  /** Buffer one event (capped; heartbeats are dropped first). */
-  bufferEvent(type: string): void {
-    this.setEvents(appendEvent(this.getEvents(), { type, ts: Date.now() }));
-  }
-
-  /** Fan a `/me/snapshot` reply out across every game's cache keys. */
-  hydrate(snapshot: SnapshotResponse): void {
-    if (snapshot.user !== null) {
-      this.writeStored(USER_KEY, snapshot.user);
-    }
-    for (const [slug, game] of Object.entries(snapshot.games)) {
-      const gamePrefix = `hub:${slug}:`;
-      if (game.profile !== null) {
-        this.writeStored(`${gamePrefix}profile`, game.profile);
-      }
-      for (const save of game.saves) {
-        this.writeStored(`${gamePrefix}save:${save.slot}`, save);
-      }
-      this.writeStored(`${gamePrefix}stats`, game.stats);
-      this.writeStored(`${gamePrefix}inventory`, game.inventory);
-    }
-    for (const gameRecords of snapshot.records) {
-      for (const record of gameRecords.records) {
-        this.writeStored(`hub:${gameRecords.slug}:lb:${record.key}`, { board: { key: record.key, title: record.title, sortDir: record.sortDir }, best: record.score });
-      }
-    }
-    this.writeStored('hub:records', snapshot.records);
-    this.writeStored('hub:leaderboards', snapshot.leaderboards);
-  }
-}
+/**
+ * The offline cache: what the client serves when the hub can't be reached,
+ * and where buffered analytics events wait (queued writes live in the
+ * outbox, `outbox.ts`). Keys are the v1 client's (`hub:user`,
+ * `hub:<slug>:save:<slot>`, `hub:<slug>:events`, ...), so a page upgraded
+ * from a vendored copy keeps that copy's cache, and its `hub:<slug>:queue`
+ * moves into the outbox.
+ */
+import type { Board, Inventory, Json, SortDir, Stats } from '@diffenderfer-games/hub-contract';
+import { isJson, isNullableString, isNumberRecord, isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
+import { createPageStore, type KeyValueStore } from '../storage/key-value';
+import type { Profile, Save, SaveMeta, SnapshotResponse, User } from '../types';
+import { appendEvent, readEvents, type BufferedEvent } from './events';
+import { EMPTY_INVENTORY, readInventory } from './local-inventory';
+import { betterScore, readQueue, type QueueOp, type QueuedScoreOptions } from './queue';
+
+/** The key of the locally known user, shared by every game (like the real session). */
+export const USER_KEY = 'hub:user';
+
+/** A board this player has a local best on. */
+export interface LocalBoard {
+  /** The board. */
+  readonly board: Board;
+  /** This player's best score. */
+  readonly best: number;
+}
+
+/** How a stat update combines with the stored value. */
+export type StatUpdateMode = 'set' | 'incr' | 'max';
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached user read back from localStorage
+function readUser(stored: unknown): User | null {
+  if (!isRecord(stored)) {
+    return null;
+  }
+  const id = optionalNumber(stored.id);
+  const username = optionalString(stored.username);
+  if (id === undefined || username === undefined) {
+    return null;
+  }
+  return typeof stored.guest === 'boolean' ? { id, username, guest: stored.guest } : { id, username };
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached save read back from localStorage
+function readSave(stored: unknown): Save | null {
+  if (!isRecord(stored)) {
+    return null;
+  }
+  const slot = optionalString(stored.slot);
+  const updatedAt = optionalNumber(stored.updatedAt);
+  if (slot === undefined || updatedAt === undefined || !isNullableString(stored.label) || !isJson(stored.data)) {
+    return null;
+  }
+  return { slot, label: stored.label, data: stored.data, updatedAt };
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached profile read back from localStorage
+function readProfile(stored: unknown): Profile | null {
+  if (!isRecord(stored)) {
+    return null;
+  }
+  const game = optionalString(stored.game);
+  const updatedAt = optionalNumber(stored.updatedAt);
+  if (game === undefined || updatedAt === undefined || !isNullableString(stored.displayName) || !isJson(stored.data)) {
+    return null;
+  }
+  return { game, displayName: stored.displayName, data: stored.data, updatedAt };
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached board read back from localStorage
+function readLocalBoard(stored: unknown): LocalBoard | null {
+  if (!isRecord(stored) || !isRecord(stored.board)) {
+    return null;
+  }
+  const key = optionalString(stored.board.key);
+  const title = optionalString(stored.board.title);
+  const sortDir = stored.board.sortDir === 'asc' || stored.board.sortDir === 'desc' ? stored.board.sortDir : undefined;
+  const best = optionalNumber(stored.best);
+  if (key === undefined || title === undefined || sortDir === undefined || best === undefined) {
+    return null;
+  }
+  return { board: { key, title, sortDir }, best };
+}
+
+/** One game's offline cache, queue and event buffer. */
+export class LocalStore {
+  private readonly prefix: string;
+  private readonly store: KeyValueStore;
+
+  /** The cache for game `slug` in `store` (default: `localStorage`, or memory without it). */
+  constructor(slug: string, store: KeyValueStore = createPageStore()) {
+    this.prefix = `hub:${slug}:`;
+    this.store = store;
+  }
+
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON read back from storage, checked by each caller's guard
+  private readStored(key: string): unknown {
+    const text = this.store.read(key);
+    return text === null ? undefined : parseJsonText(text);
+  }
+
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: any JSON-serializable value the cache stores
+  private writeStored(key: string, stored: unknown): void {
+    this.store.write(key, JSON.stringify(stored));
+  }
+
+  /** The locally known user. */
+  getUser(): User | null {
+    return readUser(this.readStored(USER_KEY));
+  }
+
+  /** Remember the user (offline sign-in, or a snapshot). */
+  setUser(user: User): void {
+    this.writeStored(USER_KEY, user);
+  }
+
+  /** Forget the user (offline sign-out). */
+  clearUser(): void {
+    this.store.remove(USER_KEY);
+  }
+
+  /** This game's cached profile. */
+  getProfile(): Profile | null {
+    return readProfile(this.readStored(`${this.prefix}profile`));
+  }
+
+  /** Store this game's profile and return it. */
+  setProfile(game: string, displayName: string | null, profileData: Json): Profile {
+    const profile: Profile = { game, displayName, data: profileData, updatedAt: Date.now() };
+    this.writeStored(`${this.prefix}profile`, profile);
+    return profile;
+  }
+
+  /** Every cached save's metadata, newest first. */
+  listSaves(): SaveMeta[] {
+    return this.store.keys()
+      .filter((key) => key.startsWith(`${this.prefix}save:`))
+      .flatMap((key) => {
+        const save = readSave(this.readStored(key));
+        return save === null ? [] : [{ slot: save.slot, label: save.label, updatedAt: save.updatedAt }];
+      })
+      .sort((first, second) => second.updatedAt - first.updatedAt);
+  }
+
+  /** One cached save, or `null`. */
+  getSave(slot: string): Save | null {
+    return readSave(this.readStored(`${this.prefix}save:${slot}`));
+  }
+
+  /** Store a save and return its `updatedAt`. */
+  putSave(slot: string, saveData: Json, label: string | null): number {
+    const updatedAt = Date.now();
+    this.writeStored(`${this.prefix}save:${slot}`, { slot, label, data: saveData, updatedAt });
+    return updatedAt;
+  }
+
+  /** Forget a save. */
+  deleteSave(slot: string): void {
+    this.store.remove(`${this.prefix}save:${slot}`);
+  }
+
+  /** This game's cached stats. */
+  getStats(): Stats {
+    const stored = this.readStored(`${this.prefix}stats`);
+    return isNumberRecord(stored) ? { ...stored } : {};
+  }
+
+  /** Apply one stat update and return the stat's new value. */
+  updateStat(key: string, amount: number, mode: StatUpdateMode): number {
+    const stats = this.getStats();
+    const current = stats[key] ?? 0;
+    const updated = mode === 'incr' ? current + amount : mode === 'max' ? Math.max(current, amount) : amount;
+    this.writeStored(`${this.prefix}stats`, { ...stats, [key]: updated });
+    return updated;
+  }
+
+  /** The boards this player has a local best on (offline boards only know the player's own best). */
+  listBoards(): Board[] {
+    return this.store.keys()
+      .filter((key) => key.startsWith(`${this.prefix}lb:`))
+      .flatMap((key) => {
+        const local = readLocalBoard(this.readStored(key));
+        return local === null ? [] : [local.board];
+      });
+  }
+
+  /** One board's local best, or `null`. */
+  getBoard(key: string): LocalBoard | null {
+    return readLocalBoard(this.readStored(`${this.prefix}lb:${key}`));
+  }
+
+  /** Record a score locally, keeping the best one; returns the board and best. */
+  submitScore(key: string, score: number, options: QueuedScoreOptions): LocalBoard {
+    const existing = this.getBoard(key);
+    const sortDir: SortDir = existing?.board.sortDir ?? (options.sort === 'asc' ? 'asc' : 'desc');
+    const board: Board = existing?.board ?? { key, title: options.title !== undefined && options.title !== '' ? options.title : key, sortDir };
+    const best = existing === null ? score : betterScore(existing.best, score, sortDir);
+    this.writeStored(`${this.prefix}lb:${key}`, { board, best });
+    return { board, best };
+  }
+
+  /** The v1 client's queued writes, removed from storage (the caller moves them into the outbox). */
+  takeLegacyQueue(): QueueOp[] {
+    const queue = readQueue(this.readStored(`${this.prefix}queue`));
+    this.store.remove(`${this.prefix}queue`);
+    return queue;
+  }
+
+  /** This game's cached inventory (empty when none is cached). */
+  getInventory(): Inventory {
+    return readInventory(this.readStored(`${this.prefix}inventory`)) ?? EMPTY_INVENTORY;
+  }
+
+  /** Store this game's inventory and return it. */
+  setInventory(inventory: Inventory): Inventory {
+    this.writeStored(`${this.prefix}inventory`, inventory);
+    return inventory;
+  }
+
+  /** The buffered analytics events, oldest first. */
+  getEvents(): BufferedEvent[] {
+    return readEvents(this.readStored(`${this.prefix}events`));
+  }
+
+  /** Replace the event buffer. */
+  setEvents(events: readonly BufferedEvent[]): void {
+    this.writeStored(`${this.prefix}events`, events);
+  }
+
+  /** Buffer one event (capped; heartbeats are dropped first). */
+  bufferEvent(type: string): void {
+    this.setEvents(appendEvent(this.getEvents(), { type, ts: Date.now() }));
+  }
+
+  /** Fan a `/me/snapshot` reply out across every game's cache keys. */
+  hydrate(snapshot: SnapshotResponse): void {
+    if (snapshot.user !== null) {
+      this.writeStored(USER_KEY, snapshot.user);
+    }
+    for (const [slug, game] of Object.entries(snapshot.games)) {
+      const gamePrefix = `hub:${slug}:`;
+      if (game.profile !== null) {
+        this.writeStored(`${gamePrefix}profile`, game.profile);
+      }
+      for (const save of game.saves) {
+        this.writeStored(`${gamePrefix}save:${save.slot}`, save);
+      }
+      this.writeStored(`${gamePrefix}stats`, game.stats);
+      this.writeStored(`${gamePrefix}inventory`, game.inventory);
+    }
+    for (const gameRecords of snapshot.records) {
+      for (const record of gameRecords.records) {
+        this.writeStored(`hub:${gameRecords.slug}:lb:${record.key}`, { board: { key: record.key, title: record.title, sortDir: record.sortDir }, best: record.score });
+      }
+    }
+    this.writeStored('hub:records', snapshot.records);
+    this.writeStored('hub:leaderboards', snapshot.leaderboards);
+  }
+}

package/src/core/offline/offline-api.ts

@@ -0,0 +1,65 @@
+/**
+ * `hub.offline`: the outbox, opened to games. A game defines its own kinds
+ * (a handler per kind, which may make several dependent calls) and enqueues
+ * operations of them; the hub queues them in order, replays them when it is
+ * reachable, and reports what happened.
+ */
+import { toStoredJson, type GamePayload } from '../game-data';
+import { HubError } from '../errors';
+import { gameKind } from './kind-adapters';
+import type { OfflineEventName, OfflineListener, OfflineOp, Outbox } from './outbox';
+import { HUB_KIND_PREFIX, type OfflineHandler, type OfflineKindDefinition } from './outbox-kinds';
+
+/** What `hub.offline` drives. */
+export interface OfflineHost {
+  /** The game's outbox. */
+  readonly outbox: Outbox;
+  /** Replay now when the hub is reachable (and nothing else is replaying). */
+  requestSync(): void;
+}
+
+/** The game-facing outbox API. */
+export class OfflineApi {
+  private readonly host: OfflineHost;
+
+  /** The API over `host`. */
+  constructor(host: OfflineHost) {
+    this.host = host;
+  }
+
+  /**
+   * Define what an operation of `kind` does when it replays. Define every
+   * kind at load, before or after enqueueing: waiting ops of an undefined
+   * kind hold the queue until it is defined. `hub.*` kinds are the hub's own.
+   */
+  define<Payload extends GamePayload>(kind: string, definition: OfflineHandler<Payload> | OfflineKindDefinition<Payload>): void {
+    if (kind.startsWith(HUB_KIND_PREFIX) || kind === '') {
+      throw new HubError(`Offline kinds starting with "${HUB_KIND_PREFIX}" are the hub's own; name yours after your game.`);
+    }
+    this.host.outbox.define(kind, gameKind(definition));
+    this.host.requestSync();
+  }
+
+  /**
+   * Queue an operation of `kind` and replay it as soon as the hub is
+   * reachable (at once when online). Resolves the queued op; its outcome
+   * arrives as a `replayed` or `failed` event. Throws a `HubError` (code
+   * `offline_queue_full`) when the outbox is full.
+   */
+  enqueue(kind: string, payload: GamePayload): OfflineOp {
+    const op = this.host.outbox.stamp(kind, toStoredJson(payload));
+    this.host.outbox.add(op);
+    this.host.requestSync();
+    return op;
+  }
+
+  /** The waiting operations (the hub's and the game's), oldest first. */
+  pending(): OfflineOp[] {
+    return this.host.outbox.pending();
+  }
+
+  /** Listen for `queued`, `replayed` or `failed`; returns the unsubscribe function. */
+  on<Name extends OfflineEventName>(name: Name, listener: OfflineListener<Name>): () => void {
+    return this.host.outbox.on(name, listener);
+  }
+}