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

package/src/core/offline/hub-kinds/economy-kinds.ts

@@ -0,0 +1,86 @@
+/**
+ * The hub's economy and catalog kinds: inventory grants and house
+ * exchanges (each one replayable call, never folded: every grant counts),
+ * and starring a game (a game's last star or unstar wins).
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { GoodsPayload } from '../local-inventory';
+import type { RegisteredKind } from '../outbox-kinds';
+import type { GameFieldsSource } from './game-fields';
+
+/** A house exchange: what the player gives up and gets. */
+export type ExchangePayload = { readonly take?: GoodsPayload; readonly give?: GoodsPayload };
+
+/** A star or unstar. */
+export type FavoritePayload = { readonly slug: string; readonly on: boolean };
+
+/** The kind names. */
+export const ECONOMY_KINDS = { grant: 'hub.grant', exchange: 'hub.exchange', favorite: 'hub.favorite' } as const;
+
+/** Goods read back, or `undefined` when malformed. */
+export function readGoods(stored: Json | undefined): GoodsPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const coins = stored.coins === undefined ? undefined : optionalNumber(stored.coins);
+  if (stored.coins !== undefined && coins === undefined) {
+    return undefined;
+  }
+  const items: Record<string, number> = {};
+  if (stored.items !== undefined) {
+    if (!isRecord(stored.items)) {
+      return undefined;
+    }
+    for (const [key, qty] of Object.entries(stored.items)) {
+      const count = optionalNumber(qty);
+      if (count === undefined) {
+        return undefined;
+      }
+      items[key] = count;
+    }
+  }
+  return { ...(stored.items === undefined ? {} : { items }), ...(coins === undefined ? {} : { coins }) };
+}
+
+function readExchange(stored: Json): ExchangePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const take = stored.take === undefined ? undefined : readGoods(stored.take);
+  const give = stored.give === undefined ? undefined : readGoods(stored.give);
+  if ((stored.take !== undefined && take === undefined) || (stored.give !== undefined && give === undefined)) {
+    return undefined;
+  }
+  return { ...(take === undefined ? {} : { take }), ...(give === undefined ? {} : { give }) };
+}
+
+function readFavorite(stored: Json): FavoritePayload | undefined {
+  if (!isRecord(stored) || typeof stored.on !== 'boolean') {
+    return undefined;
+  }
+  const slug = optionalString(stored.slug);
+  return slug === undefined ? undefined : { slug, on: stored.on };
+}
+
+/** The economy kinds, by name; `onFavorites` hears the starred list each star answers with. */
+export function economyKinds(game: GameFieldsSource, onFavorites: (games: string[]) => void): Record<string, RegisteredKind> {
+  return {
+    [ECONOMY_KINDS.grant]: checkedKind(readGoods, {
+      run: (goods, context) => context.call('grantInventoryItems', { ...game(), ...goods }),
+    }),
+    [ECONOMY_KINDS.exchange]: checkedKind(readExchange, {
+      run: (exchange, context) => context.call('exchangeInventoryItems', { ...game(), ...exchange }),
+    }),
+    [ECONOMY_KINDS.favorite]: checkedKind(readFavorite, {
+      mergeKey: (favorite) => favorite.slug,
+      replaces: true,
+      run: async (favorite, context) => {
+        const reply = await context.call('setGameFavorite', { slug: favorite.slug, on: favorite.on });
+        onFavorites(reply.games);
+        return reply;
+      },
+    }),
+  };
+}

package/src/core/offline/hub-kinds/game-fields.ts

@@ -0,0 +1,2 @@
+/** The `{ slug }` path field the hub kinds' calls need, read when they run (it throws when the slug is unknown). */
+export type GameFieldsSource = () => { readonly slug: string };

package/src/core/offline/hub-kinds/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Every kind the hub itself queues offline (`hub.*`), registered on a
+ * client's outbox. The docs' "Offline and replay" table lists them.
+ */
+import { writeLocalFavorites } from '../favorites';
+import type { Outbox } from '../outbox';
+import { dailyKinds, type DailyCompletion, type DailyPayload } from './daily-kind';
+import { economyKinds } from './economy-kinds';
+import type { GameFieldsSource } from './game-fields';
+import { progressKinds } from './progress-kinds';
+
+export { DAILY_KIND, type DailyPayload } from './daily-kind';
+export { ECONOMY_KINDS, type ExchangePayload, type FavoritePayload } from './economy-kinds';
+export { legacyOperation } from './legacy-ops';
+export { PROGRESS_KINDS, type ProfilePayload, type SavePayload, type ScorePayload, type StatPayload } from './progress-kinds';
+
+/** What the hub kinds report back to their client. */
+export interface HubKindHooks {
+  /** This game's `{ slug }`. */
+  readonly game: GameFieldsSource;
+  /** A daily completion landed (the menu's calendar listens for `hub:daily-complete`). */
+  readonly onDailyComplete: (payload: DailyPayload, completion: DailyCompletion) => void;
+}
+
+/** Register every hub kind on `outbox`. */
+export function registerHubKinds(outbox: Outbox, hooks: HubKindHooks): void {
+  const kinds = {
+    ...progressKinds(hooks.game),
+    ...dailyKinds(hooks.game, hooks.onDailyComplete),
+    ...economyKinds(hooks.game, writeLocalFavorites),
+  };
+  for (const [kind, definition] of Object.entries(kinds)) {
+    outbox.define(kind, definition);
+  }
+}

package/src/core/offline/hub-kinds/legacy-ops.ts

@@ -0,0 +1,37 @@
+/**
+ * The v1 client's queued writes (`hub:<slug>:queue`) as outbox operations,
+ * so a page upgraded from a vendored copy still replays what that copy queued.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import type { QueueOp } from '../queue';
+import { PROGRESS_KINDS, readProfile, readScoreOptions } from './progress-kinds';
+
+/** One outbox operation, before it is stamped. */
+export interface KindedPayload {
+  readonly kind: string;
+  readonly payload: Json;
+}
+
+/** The outbox operation for a v1 queued write, or `undefined` when it no longer reads as one. */
+export function legacyOperation(op: QueueOp): KindedPayload | undefined {
+  switch (op.kind) {
+    case 'putSave':
+      return { kind: PROGRESS_KINDS.save, payload: { slot: op.slot, data: op.data, label: op.label } };
+    case 'deleteSave':
+      return { kind: PROGRESS_KINDS.save, payload: { slot: op.slot, deleted: true } };
+    case 'setStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'set', value: op.value } };
+    case 'maxStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'max', value: op.value } };
+    case 'incrStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'incr', value: op.amount } };
+    case 'submitScore': {
+      const opts = readScoreOptions({ ...op.opts });
+      return opts === undefined ? undefined : { kind: PROGRESS_KINDS.score, payload: { key: op.key, score: op.score, opts } };
+    }
+    case 'setProfile': {
+      const patch = readProfile({ ...op.patch });
+      return patch === undefined ? undefined : { kind: PROGRESS_KINDS.profile, payload: patch };
+    }
+  }
+}

package/src/core/offline/hub-kinds/progress-kinds.ts

@@ -0,0 +1,148 @@
+/**
+ * The hub's progress kinds: saves, stats, scores and the game profile. Each
+ * is one replayable call, and each folds new writes into waiting ones so the
+ * backlog stays small: a save slot's last write wins, `incr`s add up, `max`es
+ * keep the largest, `set`s keep the last, a board keeps its best, and profile
+ * patches merge.
+ */
+import type { Json, SortDir } from '@diffenderfer-games/hub-contract';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind } from '../outbox-kinds';
+import { betterScore } from '../queue';
+import type { GameFieldsSource } from './game-fields';
+
+/** A save slot write: new contents, or a delete. */
+export type SavePayload =
+  | { readonly slot: string; readonly data: Json; readonly label: string | null }
+  | { readonly slot: string; readonly deleted: true };
+
+/** How a stat update combines with the stored value. */
+export type StatMode = 'set' | 'incr' | 'max';
+
+/** One stat update. */
+export type StatPayload = { readonly key: string; readonly mode: StatMode; readonly value: number };
+
+/** A score's board options, as queued. */
+export type ScoreOptionsPayload = { readonly title?: string; readonly sort?: SortDir; readonly meta?: Json };
+
+/** One score submission. */
+export type ScorePayload = { readonly key: string; readonly score: number; readonly opts: ScoreOptionsPayload };
+
+/** A profile change; either part may be left out. */
+export type ProfilePayload = { readonly displayName?: string | null; readonly data?: Json };
+
+/** The kind names. */
+export const PROGRESS_KINDS = { save: 'hub.save', stat: 'hub.stat', score: 'hub.score', profile: 'hub.profile' } as const;
+
+function readSave(stored: Json): SavePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const slot = optionalString(stored.slot);
+  if (slot === undefined) {
+    return undefined;
+  }
+  if (stored.deleted === true) {
+    return { slot, deleted: true };
+  }
+  return isJson(stored.data) && isNullableString(stored.label) ? { slot, data: stored.data, label: stored.label } : undefined;
+}
+
+function readStat(stored: Json): StatPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const key = optionalString(stored.key);
+  const value = optionalNumber(stored.value);
+  const mode = stored.mode === 'set' || stored.mode === 'incr' || stored.mode === 'max' ? stored.mode : undefined;
+  return key === undefined || value === undefined || mode === undefined ? undefined : { key, mode, value };
+}
+
+/** Score options read back, or `undefined` when malformed. */
+export function readScoreOptions(stored: Json): ScoreOptionsPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const title = optionalString(stored.title);
+  const sort = stored.sort === 'asc' || stored.sort === 'desc' ? stored.sort : undefined;
+  if (stored.meta !== undefined && !isJson(stored.meta)) {
+    return undefined;
+  }
+  return { ...(title === undefined ? {} : { title }), ...(sort === undefined ? {} : { sort }), ...(stored.meta === undefined ? {} : { meta: stored.meta }) };
+}
+
+function readScore(stored: Json): ScorePayload | undefined {
+  if (!isRecord(stored) || !isJson(stored.opts)) {
+    return undefined;
+  }
+  const key = optionalString(stored.key);
+  const score = optionalNumber(stored.score);
+  const opts = readScoreOptions(stored.opts);
+  return key === undefined || score === undefined || opts === undefined ? undefined : { key, score, opts };
+}
+
+/** A profile patch read back, or `undefined` when malformed. */
+export function readProfile(stored: Json): ProfilePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const { displayName, data: profileData } = stored;
+  if ((displayName !== undefined && !isNullableString(displayName)) || (profileData !== undefined && !isJson(profileData))) {
+    return undefined;
+  }
+  return { ...(displayName === undefined ? {} : { displayName }), ...(profileData === undefined ? {} : { data: profileData }) };
+}
+
+/** Two waiting stat updates of one key folded together, or `undefined` when their modes differ. */
+export function mergeStats(waiting: StatPayload, incoming: StatPayload): StatPayload | undefined {
+  if (waiting.mode !== incoming.mode) {
+    return undefined;
+  }
+  switch (incoming.mode) {
+    case 'incr':
+      return { ...waiting, value: waiting.value + incoming.value };
+    case 'max':
+      return { ...waiting, value: Math.max(waiting.value, incoming.value) };
+    case 'set':
+      return incoming;
+  }
+}
+
+/** The progress kinds, by name. */
+export function progressKinds(game: GameFieldsSource): Record<string, RegisteredKind> {
+  return {
+    [PROGRESS_KINDS.save]: checkedKind(readSave, {
+      mergeKey: (save) => save.slot,
+      replaces: true,
+      run: async (save, context) => {
+        if ('deleted' in save) {
+          await context.call('deleteSave', { ...game(), slot: save.slot });
+        } else {
+          await context.call('writeSave', { ...game(), slot: save.slot, data: save.data, label: save.label });
+        }
+      },
+    }),
+    [PROGRESS_KINDS.stat]: checkedKind(readStat, {
+      mergeKey: (stat) => stat.key,
+      merge: mergeStats,
+      run: async (stat, context) => {
+        await context.call('updateGameStat', { ...game(), key: stat.key, value: stat.value, mode: stat.mode });
+      },
+    }),
+    [PROGRESS_KINDS.score]: checkedKind(readScore, {
+      mergeKey: (submission) => submission.key,
+      merge: (waiting, incoming) => ({ ...waiting, score: betterScore(waiting.score, incoming.score, incoming.opts.sort), opts: incoming.opts }),
+      run: async (submission, context) => {
+        await context.call('submitScore', { ...game(), key: submission.key, score: submission.score, ...submission.opts });
+      },
+    }),
+    [PROGRESS_KINDS.profile]: checkedKind(readProfile, {
+      mergeKey: () => 'profile',
+      merge: (waiting, incoming) => ({ ...waiting, ...incoming }),
+      run: async (patch, context) => {
+        await context.call('setGameProfile', { ...game(), ...patch });
+      },
+    }),
+  };
+}

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));
+}