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

package/src/core/offline/hub-kinds/resume-kind.ts

@@ -0,0 +1,108 @@
+/**
+ * The hub's resume kind (`hub.resume`): send a game's saved run, or clear it.
+ * One slot per game, so a new op replaces any waiting one (a clear after a
+ * save drops the save, and the other way round).
+ *
+ * A save op carries only the run's facts and time: when it runs it sends
+ * the newest run in the device copy (`LocalResumeStore`), which keeps the
+ * outbox small. When the device copy couldn't be stored, the op carries the
+ * state itself. A session that lapsed (401) gets a guest session and tries
+ * once more, so a player's very first save can't be lost to it.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../../errors';
+import type { LocalResumeStore } from '../../resume/local-resume';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind, ReplayContext } from '../outbox-kinds';
+import type { GameFieldsSource } from './game-fields';
+
+/** The kind name. */
+export const RESUME_KIND = 'hub.resume';
+
+/** Send the run saved at `savedAt`; `state` only when the device copy couldn't hold it. */
+export type ResumeSavePayload = {
+  readonly action: 'save';
+  readonly savedAt: number;
+  readonly label: string;
+  readonly fraction: number | null;
+  readonly title: string | null;
+  readonly version: number;
+  readonly state?: Json;
+};
+
+/** Clear the run, unless one was saved after `before`. */
+export type ResumeClearPayload = { readonly action: 'clear'; readonly before: number };
+
+/** One resume op. */
+export type ResumePayload = ResumeSavePayload | ResumeClearPayload;
+
+function readResume(stored: Json): ResumePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  if (stored.action === 'clear') {
+    const before = optionalNumber(stored.before);
+    return before === undefined ? undefined : { action: 'clear', before };
+  }
+  const savedAt = optionalNumber(stored.savedAt);
+  const label = optionalString(stored.label);
+  const version = optionalNumber(stored.version);
+  const fraction = stored.fraction === null ? null : optionalNumber(stored.fraction);
+  if (stored.action !== 'save' || savedAt === undefined || label === undefined || version === undefined || fraction === undefined
+    || !isNullableString(stored.title) || (stored.state !== undefined && !isJson(stored.state))) {
+    return undefined;
+  }
+  const base = { action: 'save', savedAt, label, fraction, title: stored.title, version } as const;
+  return stored.state === undefined ? base : { ...base, state: stored.state };
+}
+
+/** The run to send: the device copy when it is at least as new as the op, else the op's own state; `undefined` when there is none. */
+function runToSend(save: ResumeSavePayload, local: LocalResumeStore, slug: string): ResumeSavePayload | undefined {
+  const copy = local.read(slug);
+  if (copy?.status === 'saved' && copy.at >= save.savedAt) {
+    return { action: 'save', savedAt: copy.at, label: copy.label, fraction: copy.fraction, title: copy.title, version: copy.version, state: copy.state };
+  }
+  return save.state === undefined ? undefined : save;
+}
+
+/** Run `call`; on a lapsed session (401) start a guest session and run it once more. */
+async function withSession<Reply>(context: ReplayContext, call: () => Promise<Reply>): Promise<Reply> {
+  try {
+    return await call();
+  } catch (failure) {
+    if (!(failure instanceof HubError) || failure.status !== 401) {
+      throw failure;
+    }
+    await context.call('ensureGuestSession');
+    return call();
+  }
+}
+
+/** The resume kind, by name, over the device copies in `local`. */
+export function resumeKinds(game: GameFieldsSource, local: LocalResumeStore): Record<string, RegisteredKind> {
+  return {
+    [RESUME_KIND]: checkedKind(readResume, {
+      mergeKey: () => 'resume',
+      replaces: true,
+      run: async (op, context) => {
+        const { slug } = game();
+        if (op.action === 'clear') {
+          await withSession(context, () => context.call('clearResumeSlot', { slug, before: op.before }));
+          local.markSynced(slug, op.before);
+          return undefined;
+        }
+        const run = runToSend(op, local, slug);
+        if (run?.state === undefined) {
+          return undefined;
+        }
+        const { state } = run;
+        await withSession(context, () => context.call('saveResumeSlot', {
+          slug, state, progress: { label: run.label, fraction: run.fraction }, title: run.title, version: run.version, savedAt: run.savedAt,
+        }));
+        local.markSynced(slug, run.savedAt);
+        return undefined;
+      },
+    }),
+  };
+}

package/src/core/offline/hub-kinds/saved-kind.ts

@@ -0,0 +1,93 @@
+/**
+ * The hub's saved-games kind (`hub.saved`): send a daily challenge's state,
+ * or discard the day, from the device copy (`LocalDailyStore`). One op per
+ * (game, day): a newer one replaces a waiting one, so a discard after a
+ * save drops the save. The op carries only which day and when; when it runs
+ * it sends the newest state the device holds, so the outbox stays small.
+ *
+ * A day started offline has a device-only id (`local:<slug>:<day>`): the op
+ * first starts the day on the hub, which finds or makes its saved game (one
+ * per player, game and day), then saves to that. A save or discard that
+ * finds the day already finished or discarded elsewhere (409, 404) is done:
+ * the device copy is dropped.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../../errors';
+import type { LocalDaily, LocalDailyStore } from '../../saved/local-saved';
+import { isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind, ReplayContext } from '../outbox-kinds';
+
+/** The kind name. */
+export const SAVED_KIND = 'hub.saved';
+
+/** Send (`save`) or discard a day's saved game; `at` is when the device copy changed. */
+export type SavedPayload = { readonly action: 'save' | 'discard'; readonly game: string; readonly day: string; readonly at: number };
+
+function readSaved(stored: Json): SavedPayload | undefined {
+  if (!isRecord(stored) || (stored.action !== 'save' && stored.action !== 'discard')) {
+    return undefined;
+  }
+  const game = optionalString(stored.game);
+  const day = optionalString(stored.day);
+  const at = optionalNumber(stored.at);
+  return game === undefined || day === undefined || at === undefined ? undefined : { action: stored.action, game, day, at };
+}
+
+/** Whether a failure means the instance is gone or closed on the hub (the change is moot). */
+function isGoneOrClosed(failure: Error): boolean {
+  return failure instanceof HubError && (failure.status === 404 || failure.status === 409);
+}
+
+/** The hub's id for the copy's day: its own, or the one the hub gives the day when it was started offline (`null`: already completed). */
+async function resolveId(copy: LocalDaily, context: ReplayContext): Promise<string | null> {
+  if (!copy.id.startsWith('local:')) {
+    return copy.id;
+  }
+  const started = await context.call('startDailyChallenge', { slug: copy.game, day: copy.day });
+  return started.instanceId;
+}
+
+/** Run one op against the copy it names. */
+async function runSaved(op: SavedPayload, local: LocalDailyStore, context: ReplayContext): Promise<undefined> {
+  const copy = local.read(op.game, op.day);
+  if (copy === null) {
+    return undefined;
+  }
+  try {
+    const id = await resolveId(copy, context);
+    if (id === null) {
+      local.remove(op.game, op.day);
+      return undefined;
+    }
+    if (op.action === 'discard') {
+      await context.call('discardSavedGame', { id });
+      local.remove(op.game, op.day);
+      return undefined;
+    }
+    // A null state is sent too: it is hub.resume.clear() during the day (start over from the seed).
+    if (copy.status === 'active') {
+      await context.call('saveSavedGameState', {
+        id, state: copy.state, progress: { label: copy.label, fraction: copy.fraction }, title: copy.title, version: copy.version, savedAt: copy.at,
+      });
+    }
+    local.markSynced(op.game, op.day, copy.at, id);
+  } catch (failure) {
+    if (!(failure instanceof Error) || !isGoneOrClosed(failure)) {
+      throw failure;
+    }
+    local.remove(op.game, op.day);
+  }
+  return undefined;
+}
+
+/** The saved-games kind, by name, over the device copies in `local`. */
+export function savedKinds(local: LocalDailyStore): Record<string, RegisteredKind> {
+  return {
+    [SAVED_KIND]: checkedKind(readSaved, {
+      mergeKey: (op) => `daily:${op.game}#${op.day}`,
+      replaces: true,
+      run: (op, context) => runSaved(op, local, context),
+    }),
+  };
+}

package/src/core/offline/kind-adapters.ts

@@ -0,0 +1,48 @@
+/**
+ * Turning a typed kind definition into the JSON-in, JSON-out form the outbox
+ * runs: the hub's kinds check their stored payloads with a reader; a game's
+ * kinds vouch for their own payload type, as with saves.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { toGameData, toStoredJson, type GamePayload } from '../game-data';
+import type { OfflineHandler, OfflineKindDefinition, RegisteredKind } from './outbox-kinds';
+
+/** Reads a stored payload back, or `undefined` when it is malformed. */
+export type PayloadReader<Payload> = (stored: Json) => Payload | undefined;
+
+/** A kind whose payloads are checked by `read` (the hub's own kinds). */
+export function checkedKind<Payload extends Json>(read: PayloadReader<Payload>, definition: OfflineKindDefinition<Payload>): RegisteredKind {
+  const readOrThrow = (stored: Json): Payload => {
+    const payload = read(stored);
+    if (payload === undefined) {
+      throw new Error('Malformed offline operation payload.');
+    }
+    return payload;
+  };
+  const { mergeKey, merge } = definition;
+  return {
+    run: (stored, context) => definition.run(readOrThrow(stored), context),
+    accepts: (stored) => read(stored) !== undefined,
+    ...(mergeKey === undefined ? {} : { mergeKey: (stored: Json) => mergeKey(readOrThrow(stored)) }),
+    ...(merge === undefined ? {} : { merge: (waiting: Json, incoming: Json) => merge(readOrThrow(waiting), readOrThrow(incoming)) }),
+    replaces: definition.replaces === true,
+  };
+}
+
+/** A game's kind: a bare handler or a full definition, its payload typed by the game. */
+export function gameKind<Payload extends GamePayload>(definition: OfflineHandler<Payload> | OfflineKindDefinition<Payload>): RegisteredKind {
+  const full: OfflineKindDefinition<Payload> = typeof definition === 'function' ? { run: definition } : definition;
+  const { mergeKey, merge } = full;
+  return {
+    run: (stored, context) => full.run(toGameData<Payload>(stored), context),
+    accepts: () => true,
+    ...(mergeKey === undefined ? {} : { mergeKey: (stored: Json) => mergeKey(toGameData<Payload>(stored)) }),
+    ...(merge === undefined ? {} : {
+      merge: (waiting: Json, incoming: Json) => {
+        const merged = merge(toGameData<Payload>(waiting), toGameData<Payload>(incoming));
+        return merged === undefined ? undefined : toStoredJson(merged);
+      },
+    }),
+    replaces: full.replaces === true,
+  };
+}

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

@@ -0,0 +1,64 @@
+/**
+ * The cached inventory, changed the way the hub would change it, so grants
+ * and house exchanges made offline show at once. The hub has the last word
+ * when they replay.
+ */
+import type { Inventory } from '@diffenderfer-games/hub-contract';
+import { isRecord, optionalNumber, optionalString } from '../storage/json-guards';
+
+/** Goods moved by a grant or an exchange: item key to quantity, and coins. */
+export type GoodsPayload = { readonly items?: { readonly [key: string]: number }; readonly coins?: number };
+
+/** An empty inventory. */
+export const EMPTY_INVENTORY: Inventory = { items: [], coins: 0 };
+
+/** A cached inventory, or `null` when there is none or it is malformed. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: an inventory read back from localStorage
+export function readInventory(stored: unknown): Inventory | null {
+  if (!isRecord(stored) || !Array.isArray(stored.items)) {
+    return null;
+  }
+  const coins = optionalNumber(stored.coins);
+  const items = stored.items.flatMap((item): Inventory['items'] => {
+    const key = isRecord(item) ? optionalString(item.key) : undefined;
+    const qty = isRecord(item) ? optionalNumber(item.qty) : undefined;
+    return key === undefined || qty === undefined ? [] : [{ key, qty }];
+  });
+  return coins === undefined ? null : { items, coins };
+}
+
+/** The holdings as a key-to-quantity map. */
+function quantities(inventory: Inventory): Map<string, number> {
+  return new Map(inventory.items.map((item) => [item.key, item.qty]));
+}
+
+/** The holdings from a map (positive counts only, sorted by key). */
+function fromQuantities(held: ReadonlyMap<string, number>, coins: number): Inventory {
+  const items = [...held].filter(([, qty]) => qty > 0).sort(([first], [second]) => first.localeCompare(second)).map(([key, qty]) => ({ key, qty }));
+  return { items, coins };
+}
+
+/** `inventory` with `goods` added. */
+export function withGoods(inventory: Inventory, goods: GoodsPayload): Inventory {
+  const held = quantities(inventory);
+  for (const [key, qty] of Object.entries(goods.items ?? {})) {
+    held.set(key, (held.get(key) ?? 0) + qty);
+  }
+  return fromQuantities(held, inventory.coins + (goods.coins ?? 0));
+}
+
+/** `inventory` with `goods` removed, or the hub's refusal message when it can't cover them. */
+export function withoutGoods(inventory: Inventory, goods: GoodsPayload): Inventory | string {
+  if ((goods.coins ?? 0) > inventory.coins) {
+    return "You don't have enough coins.";
+  }
+  const held = quantities(inventory);
+  for (const [key, qty] of Object.entries(goods.items ?? {})) {
+    const have = held.get(key) ?? 0;
+    if (qty > have) {
+      return `You don't have ${String(qty)}× "${key}".`;
+    }
+    held.set(key, have - qty);
+  }
+  return fromQuantities(held, inventory.coins - (goods.coins ?? 0));
+}