@joystyk/storage 0.0.0 → 0.2.0

package/dist/saves.js

@@ -0,0 +1,100 @@
+import { MESSAGES, storageError } from "./backend.js";
+import { gamePrefix, slotKey } from "./keys.js";
+import { validate } from "./validate.js";
+import { createRecordStore, defineRecordKind } from "./record.js";
+import { saveEnvelope } from "./envelope.js";
+import { err, ok, runMigrations } from "@joystyk/contracts";
+import * as z from "zod/mini";
+//#region src/saves.ts
+/** Version 1 of the save record: the contracts' envelope plus the time it was written. */
+var SAVE_RECORD = defineRecordKind({
+	store: "saves",
+	version: 1,
+	schema: z.object({
+		savedAt: z.number().check(z.nonnegative()),
+		envelope: saveEnvelope
+	}),
+	onInvalid: "archive",
+	label: "saved game"
+});
+var createSaveStore = (context, playerId) => {
+	const records = createRecordStore(context, SAVE_RECORD);
+	const read = async (gameId, slot) => {
+		const key = slotKey(playerId, gameId, slot);
+		if (!key.ok) return key;
+		const record = await records.get(key.value);
+		if (!record.ok || record.value === null) return record;
+		if (record.value.envelope.gameId !== gameId) {
+			await records.reject(key.value, [`envelope.gameId: expected "${gameId}"`]);
+			return ok(null);
+		}
+		return ok({
+			slot,
+			...record.value
+		});
+	};
+	return {
+		list: async (gameId) => {
+			const prefix = gamePrefix(playerId, gameId);
+			if (!prefix.ok) return prefix;
+			const keys = await records.keys(prefix.value);
+			if (!keys.ok) return keys;
+			const saves = [];
+			for (const key of keys.value) {
+				const save = await read(gameId, key.slice(prefix.value.length));
+				if (!save.ok) return save;
+				if (save.value !== null) saves.push(save.value);
+			}
+			return ok(saves);
+		},
+		read,
+		load: async (gameId, slot, decoder) => {
+			const save = await read(gameId, slot);
+			if (!save.ok || save.value === null) return save;
+			const { envelope } = save.value;
+			const migrated = runMigrations(decoder.migrations, envelope.state, envelope.saveVersion, decoder.saveVersion);
+			if (!migrated.ok && migrated.error.code === "SaveFromFuture") {
+				context.notify({
+					code: "RecordFromFuture",
+					message: `This ${SAVE_RECORD.label} was made by a newer version of the game. Reload the page to open it.`,
+					store: SAVE_RECORD.store,
+					key: `${playerId}/${gameId}/${slot}`,
+					issues: [`${migrated.error.code}: ${migrated.error.message}`]
+				});
+				return ok(null);
+			}
+			const state = migrated.ok ? await validate(decoder.state, migrated.value) : err([`${migrated.error.code}: ${migrated.error.message}`]);
+			if (!state.ok) {
+				const key = slotKey(playerId, gameId, slot);
+				if (key.ok) await records.reject(key.value, state.error);
+				return ok(null);
+			}
+			return ok({
+				...save.value,
+				envelope: {
+					...envelope,
+					saveVersion: decoder.saveVersion,
+					state: state.value
+				}
+			});
+		},
+		write: async (gameId, slot, envelope) => {
+			const key = slotKey(playerId, gameId, slot);
+			if (!key.ok) return key;
+			if (envelope.gameId !== gameId) return err(storageError("InvalidValue", MESSAGES.InvalidValue, { gameId: envelope.gameId }));
+			return records.set(key.value, {
+				savedAt: context.now(),
+				envelope
+			});
+		},
+		delete: async (gameId, slot) => {
+			const key = slotKey(playerId, gameId, slot);
+			if (!key.ok) return key;
+			return records.delete(key.value);
+		}
+	};
+};
+//#endregion
+export { SAVE_RECORD, createSaveStore };
+
+//# sourceMappingURL=saves.js.map

package/dist/saves.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"saves.js","names":[],"sources":["../src/saves.ts"],"sourcesContent":["import {\n  err,\n  ok,\n  runMigrations,\n  type Json,\n  type Migration,\n  type Result,\n  type SaveEnvelope,\n  type Validator,\n} from '@joystyk/contracts';\nimport * as z from 'zod/mini';\nimport { MESSAGES, storageError, type StorageError } from './backend.ts';\nimport { saveEnvelope } from './envelope.ts';\nimport { gamePrefix, slotKey } from './keys.ts';\nimport { createRecordStore, defineRecordKind, type RecordContext } from './record.ts';\nimport { validate } from './validate.ts';\n\n/** One saved game in a slot. */\nexport type SavedGame = {\n  readonly slot: string;\n  /** Epoch milliseconds of the write. */\n  readonly savedAt: number;\n  readonly envelope: SaveEnvelope;\n};\n\n/** What a game supplies to bring its saved state up to date: the game module's chain and schema. */\nexport type SaveDecoder = {\n  /** The game's current save version (`manifest.versions.save`). */\n  readonly saveVersion: number;\n  readonly migrations: readonly Migration[];\n  /** The engine's `schemas.state` (or the simulation's). */\n  readonly state: Validator<Json>;\n};\n\ntype SaveRecord = { readonly savedAt: number; readonly envelope: SaveEnvelope };\n\n/** Version 1 of the save record: the contracts' envelope plus the time it was written. */\nexport const SAVE_RECORD = defineRecordKind<SaveRecord>({\n  store: 'saves',\n  version: 1,\n  schema: z.object({ savedAt: z.number().check(z.nonnegative()), envelope: saveEnvelope }),\n  onInvalid: 'archive',\n  label: 'saved game',\n});\n\n/** One player's save slots, by game id and slot name. */\nexport interface SaveStore {\n  /** Every readable save of one game, by slot name. Unreadable ones are archived with a notice. */\n  list(gameId: string): Promise<Result<readonly SavedGame[], StorageError>>;\n  /**\n   * The save in a slot with its envelope decoded, or null. The game's own state is not\n   * migrated or checked; use `load` to resume play.\n   */\n  read(gameId: string, slot: string): Promise<Result<SavedGame | null, StorageError>>;\n  /**\n   * The save in a slot, ready to resume: its state migrated from the saved version to the\n   * game's current one and validated with the game's schema. A save that can't be brought up\n   * to date is archived with a notice and comes back as null. The caller still compares\n   * `rulesVersion` with the game's (offline-and-updates.md, Rule 3).\n   */\n  load(gameId: string, slot: string, decoder: SaveDecoder): Promise<Result<SavedGame | null, StorageError>>;\n  /** Writes an envelope to a slot. The envelope's `gameId` must be `gameId`. */\n  write(gameId: string, slot: string, envelope: SaveEnvelope): Promise<Result<void, StorageError>>;\n  delete(gameId: string, slot: string): Promise<Result<void, StorageError>>;\n}\n\nexport const createSaveStore = (context: RecordContext, playerId: string): SaveStore => {\n  const records = createRecordStore(context, SAVE_RECORD);\n\n  const read = async (gameId: string, slot: string): Promise<Result<SavedGame | null, StorageError>> => {\n    const key = slotKey(playerId, gameId, slot);\n    if (!key.ok) return key;\n    const record = await records.get(key.value);\n    if (!record.ok || record.value === null) return record as Result<null, StorageError>;\n    if (record.value.envelope.gameId !== gameId) {\n      await records.reject(key.value, [`envelope.gameId: expected \"${gameId}\"`]);\n      return ok(null);\n    }\n    return ok({ slot, ...record.value });\n  };\n\n  return {\n    list: async (gameId) => {\n      const prefix = gamePrefix(playerId, gameId);\n      if (!prefix.ok) return prefix;\n      const keys = await records.keys(prefix.value);\n      if (!keys.ok) return keys;\n      const saves: SavedGame[] = [];\n      for (const key of keys.value) {\n        const save = await read(gameId, key.slice(prefix.value.length));\n        if (!save.ok) return save;\n        if (save.value !== null) saves.push(save.value);\n      }\n      return ok(saves);\n    },\n    read,\n    load: async (gameId, slot, decoder) => {\n      const save = await read(gameId, slot);\n      if (!save.ok || save.value === null) return save;\n      const { envelope } = save.value;\n      const migrated = runMigrations(decoder.migrations, envelope.state, envelope.saveVersion, decoder.saveVersion);\n      if (!migrated.ok && migrated.error.code === 'SaveFromFuture') {\n        // A newer build of the game wrote it: keep it for that build rather than archive it.\n        context.notify({\n          code: 'RecordFromFuture',\n          message: `This ${SAVE_RECORD.label} was made by a newer version of the game. Reload the page to open it.`,\n          store: SAVE_RECORD.store,\n          key: `${playerId}/${gameId}/${slot}`,\n          issues: [`${migrated.error.code}: ${migrated.error.message}`],\n        });\n        return ok(null);\n      }\n      const state = migrated.ok\n        ? await validate(decoder.state, migrated.value)\n        : err([`${migrated.error.code}: ${migrated.error.message}`]);\n      if (!state.ok) {\n        const key = slotKey(playerId, gameId, slot);\n        if (key.ok) await records.reject(key.value, state.error);\n        return ok(null);\n      }\n      return ok({\n        ...save.value,\n        envelope: { ...envelope, saveVersion: decoder.saveVersion, state: state.value },\n      });\n    },\n    write: async (gameId, slot, envelope) => {\n      const key = slotKey(playerId, gameId, slot);\n      if (!key.ok) return key;\n      if (envelope.gameId !== gameId) {\n        return err(storageError('InvalidValue', MESSAGES.InvalidValue, { gameId: envelope.gameId }));\n      }\n      return records.set(key.value, { savedAt: context.now(), envelope });\n    },\n    delete: async (gameId, slot) => {\n      const key = slotKey(playerId, gameId, slot);\n      if (!key.ok) return key;\n      return records.delete(key.value);\n    },\n  };\n};\n"],"mappings":"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"}

package/dist/stats.d.ts

@@ -0,0 +1,34 @@
+import { type Outcome, type Result } from '@joystyk/contracts';
+import type { StorageError } from './backend.js';
+import { type RecordContext } from './record.js';
+/** One player's totals for one game, across every mode played on this device. */
+export type GameStats = {
+    readonly played: number;
+    readonly won: number;
+    readonly lost: number;
+    readonly drawn: number;
+    /** Solo games that end without winning or losing, such as a solved puzzle. */
+    readonly completed: number;
+    readonly abandoned: number;
+    /** Active play time across all games, in milliseconds. */
+    readonly totalElapsedMs: number;
+    /** Epoch milliseconds of the last finished game, or null. */
+    readonly lastPlayedAt: number | null;
+};
+export declare const EMPTY_STATS: GameStats;
+/** Version 1 of the stats record. */
+export declare const STATS_RECORD: import("./record.js").RecordKind<GameStats>;
+/** Adds one finished game to the totals. Pure. `at` is epoch milliseconds. */
+export declare const recordOutcome: (stats: GameStats, outcome: Outcome, at: number) => GameStats;
+/**
+ * One player's stats, by game id. Written through this interface so v2 can sync them to an
+ * account without changing games.
+ */
+export interface StatsStore {
+    /** The game's stats, or `EMPTY_STATS` when there are none yet. */
+    get(gameId: string): Promise<Result<GameStats, StorageError>>;
+    set(gameId: string, stats: GameStats): Promise<Result<void, StorageError>>;
+    /** Reads, adds the outcome with `recordOutcome`, writes, and returns the new totals. */
+    record(gameId: string, outcome: Outcome): Promise<Result<GameStats, StorageError>>;
+}
+export declare const createStatsStore: (context: RecordContext, playerId: string) => StatsStore;

package/dist/stats.js

@@ -0,0 +1,78 @@
+import { gameKey } from "./keys.js";
+import { createRecordStore, defineRecordKind } from "./record.js";
+import { ok } from "@joystyk/contracts";
+import * as z from "zod/mini";
+//#region src/stats.ts
+var EMPTY_STATS = {
+	played: 0,
+	won: 0,
+	lost: 0,
+	drawn: 0,
+	completed: 0,
+	abandoned: 0,
+	totalElapsedMs: 0,
+	lastPlayedAt: null
+};
+var count = z.int().check(z.nonnegative());
+/** Version 1 of the stats record. */
+var STATS_RECORD = defineRecordKind({
+	store: "stats",
+	version: 1,
+	schema: z.object({
+		played: count,
+		won: count,
+		lost: count,
+		drawn: count,
+		completed: count,
+		abandoned: count,
+		totalElapsedMs: z.number().check(z.nonnegative()),
+		lastPlayedAt: z.nullable(z.number().check(z.nonnegative()))
+	}),
+	label: "set of game stats"
+});
+var COUNTERS = {
+	won: "won",
+	lost: "lost",
+	draw: "drawn",
+	completed: "completed",
+	abandoned: "abandoned"
+};
+/** Adds one finished game to the totals. Pure. `at` is epoch milliseconds. */
+var recordOutcome = (stats, outcome, at) => {
+	const counter = COUNTERS[outcome.result];
+	return {
+		...stats,
+		played: stats.played + 1,
+		[counter]: stats[counter] + 1,
+		totalElapsedMs: stats.totalElapsedMs + (outcome.elapsedMs ?? 0),
+		lastPlayedAt: at
+	};
+};
+var createStatsStore = (context, playerId) => {
+	const records = createRecordStore(context, STATS_RECORD);
+	const get = async (gameId) => {
+		const key = gameKey(playerId, gameId);
+		if (!key.ok) return key;
+		const stats = await records.get(key.value);
+		return stats.ok ? ok(stats.value ?? EMPTY_STATS) : stats;
+	};
+	const set = async (gameId, stats) => {
+		const key = gameKey(playerId, gameId);
+		return key.ok ? records.set(key.value, stats) : key;
+	};
+	return {
+		get,
+		set,
+		record: async (gameId, outcome) => {
+			const current = await get(gameId);
+			if (!current.ok) return current;
+			const next = recordOutcome(current.value, outcome, context.now());
+			const written = await set(gameId, next);
+			return written.ok ? ok(next) : written;
+		}
+	};
+};
+//#endregion
+export { EMPTY_STATS, STATS_RECORD, createStatsStore, recordOutcome };
+
+//# sourceMappingURL=stats.js.map

package/dist/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","names":[],"sources":["../src/stats.ts"],"sourcesContent":["import { ok, type Outcome, type Result } from '@joystyk/contracts';\nimport * as z from 'zod/mini';\nimport type { StorageError } from './backend.ts';\nimport { gameKey } from './keys.ts';\nimport { createRecordStore, defineRecordKind, type RecordContext } from './record.ts';\n\n/** One player's totals for one game, across every mode played on this device. */\nexport type GameStats = {\n  readonly played: number;\n  readonly won: number;\n  readonly lost: number;\n  readonly drawn: number;\n  /** Solo games that end without winning or losing, such as a solved puzzle. */\n  readonly completed: number;\n  readonly abandoned: number;\n  /** Active play time across all games, in milliseconds. */\n  readonly totalElapsedMs: number;\n  /** Epoch milliseconds of the last finished game, or null. */\n  readonly lastPlayedAt: number | null;\n};\n\nexport const EMPTY_STATS: GameStats = {\n  played: 0,\n  won: 0,\n  lost: 0,\n  drawn: 0,\n  completed: 0,\n  abandoned: 0,\n  totalElapsedMs: 0,\n  lastPlayedAt: null,\n};\n\nconst count = z.int().check(z.nonnegative());\n\n/** Version 1 of the stats record. */\nexport const STATS_RECORD = defineRecordKind<GameStats>({\n  store: 'stats',\n  version: 1,\n  schema: z.object({\n    played: count,\n    won: count,\n    lost: count,\n    drawn: count,\n    completed: count,\n    abandoned: count,\n    totalElapsedMs: z.number().check(z.nonnegative()),\n    lastPlayedAt: z.nullable(z.number().check(z.nonnegative())),\n  }),\n  label: 'set of game stats',\n});\n\nconst COUNTERS = {\n  won: 'won',\n  lost: 'lost',\n  draw: 'drawn',\n  completed: 'completed',\n  abandoned: 'abandoned',\n} as const satisfies Record<Outcome['result'], keyof GameStats>;\n\n/** Adds one finished game to the totals. Pure. `at` is epoch milliseconds. */\nexport const recordOutcome = (stats: GameStats, outcome: Outcome, at: number): GameStats => {\n  const counter = COUNTERS[outcome.result];\n  return {\n    ...stats,\n    played: stats.played + 1,\n    [counter]: stats[counter] + 1,\n    totalElapsedMs: stats.totalElapsedMs + (outcome.elapsedMs ?? 0),\n    lastPlayedAt: at,\n  };\n};\n\n/**\n * One player's stats, by game id. Written through this interface so v2 can sync them to an\n * account without changing games.\n */\nexport interface StatsStore {\n  /** The game's stats, or `EMPTY_STATS` when there are none yet. */\n  get(gameId: string): Promise<Result<GameStats, StorageError>>;\n  set(gameId: string, stats: GameStats): Promise<Result<void, StorageError>>;\n  /** Reads, adds the outcome with `recordOutcome`, writes, and returns the new totals. */\n  record(gameId: string, outcome: Outcome): Promise<Result<GameStats, StorageError>>;\n}\n\nexport const createStatsStore = (context: RecordContext, playerId: string): StatsStore => {\n  const records = createRecordStore(context, STATS_RECORD);\n  const get = async (gameId: string): Promise<Result<GameStats, StorageError>> => {\n    const key = gameKey(playerId, gameId);\n    if (!key.ok) return key;\n    const stats = await records.get(key.value);\n    return stats.ok ? ok(stats.value ?? EMPTY_STATS) : stats;\n  };\n  const set = async (gameId: string, stats: GameStats): Promise<Result<void, StorageError>> => {\n    const key = gameKey(playerId, gameId);\n    return key.ok ? records.set(key.value, stats) : key;\n  };\n  return {\n    get,\n    set,\n    record: async (gameId, outcome) => {\n      const current = await get(gameId);\n      if (!current.ok) return current;\n      const next = recordOutcome(current.value, outcome, context.now());\n      const written = await set(gameId, next);\n      return written.ok ? ok(next) : written;\n    },\n  };\n};\n"],"mappings":";;;;;AAqBA,IAAa,cAAyB;CACpC,QAAQ;CACR,KAAK;CACL,MAAM;CACN,OAAO;CACP,WAAW;CACX,WAAW;CACX,gBAAgB;CAChB,cAAc;AAChB;AAEA,IAAM,QAAQ,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC;;AAG3C,IAAa,eAAe,iBAA4B;CACtD,OAAO;CACP,SAAS;CACT,QAAQ,EAAE,OAAO;EACf,QAAQ;EACR,KAAK;EACL,MAAM;EACN,OAAO;EACP,WAAW;EACX,WAAW;EACX,gBAAgB,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC;EAChD,cAAc,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CAC5D,CAAC;CACD,OAAO;AACT,CAAC;AAED,IAAM,WAAW;CACf,KAAK;CACL,MAAM;CACN,MAAM;CACN,WAAW;CACX,WAAW;AACb;;AAGA,IAAa,iBAAiB,OAAkB,SAAkB,OAA0B;CAC1F,MAAM,UAAU,SAAS,QAAQ;CACjC,OAAO;EACL,GAAG;EACH,QAAQ,MAAM,SAAS;GACtB,UAAU,MAAM,WAAW;EAC5B,gBAAgB,MAAM,kBAAkB,QAAQ,aAAa;EAC7D,cAAc;CAChB;AACF;AAcA,IAAa,oBAAoB,SAAwB,aAAiC;CACxF,MAAM,UAAU,kBAAkB,SAAS,YAAY;CACvD,MAAM,MAAM,OAAO,WAA6D;EAC9E,MAAM,MAAM,QAAQ,UAAU,MAAM;EACpC,IAAI,CAAC,IAAI,IAAI,OAAO;EACpB,MAAM,QAAQ,MAAM,QAAQ,IAAI,IAAI,KAAK;EACzC,OAAO,MAAM,KAAK,GAAG,MAAM,SAAS,WAAW,IAAI;CACrD;CACA,MAAM,MAAM,OAAO,QAAgB,UAA0D;EAC3F,MAAM,MAAM,QAAQ,UAAU,MAAM;EACpC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,OAAO,KAAK,IAAI;CAClD;CACA,OAAO;EACL;EACA;EACA,QAAQ,OAAO,QAAQ,YAAY;GACjC,MAAM,UAAU,MAAM,IAAI,MAAM;GAChC,IAAI,CAAC,QAAQ,IAAI,OAAO;GACxB,MAAM,OAAO,cAAc,QAAQ,OAAO,SAAS,QAAQ,IAAI,CAAC;GAChE,MAAM,UAAU,MAAM,IAAI,QAAQ,IAAI;GACtC,OAAO,QAAQ,KAAK,GAAG,IAAI,IAAI;EACjC;CACF;AACF"}

package/dist/storage.d.ts

@@ -0,0 +1,45 @@
+import type { GameStorage, Json } from '@joystyk/contracts';
+import type { StorageBackend } from './backend.js';
+import type { ChangeFeed } from './changes.js';
+import { type PreferencesStore } from './preferences.js';
+import { type RecordKind, type RecordStore, type StorageNotice } from './record.js';
+import { type SaveStore } from './saves.js';
+import { type StatsStore } from './stats.js';
+import { type StreakStore } from './streaks.js';
+export type StorageOptions = {
+    /** `createMemoryBackend()` in tests and on the server; `openIndexedDbBackend()` in the browser. */
+    readonly backend: StorageBackend;
+    /** Receives every notice; the frame shows them to the player. */
+    readonly onNotice?: (notice: StorageNotice) => void;
+    /** Epoch milliseconds. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /**
+     * Tells other tabs about changes and hears theirs, so a preference set in one tab reaches
+     * the rest (gp-d4v). `openBrowserStorage` provides one; without it, changes stay in this tab.
+     */
+    readonly changes?: ChangeFeed;
+};
+/** Everything one player keeps. Every key starts with the player id, never a device id. */
+export interface PlayerStorage {
+    readonly playerId: string;
+    readonly saves: SaveStore;
+    readonly stats: StatsStore;
+    readonly streaks: StreakStore;
+    readonly preferences: PreferencesStore;
+    /** The `PlatformApi.storage` for one game. */
+    gameStorage(gameId: string): GameStorage;
+}
+/** The opened storage: typed record stores over one backend. */
+export interface Storage {
+    /**
+     * One player's data. Throws a `RangeError` for an id that can't be part of a key, which
+     * is a bug: ids come from `@joystyk/identity`.
+     */
+    player(playerId: string): PlayerStorage;
+    /** A typed store for a record kind another package defines, such as identity's profile. */
+    records<T extends Json>(kind: RecordKind<T>): RecordStore<T>;
+    /** Closes the backend and the change feed. Idempotent. */
+    close(): void;
+}
+/** Opens typed, validated storage over a backend. */
+export declare const openStorage: (options: StorageOptions) => Storage;

package/dist/storage.js

@@ -0,0 +1,43 @@
+import { isKeyPart } from "./keys.js";
+import { createRecordStore } from "./record.js";
+import { createGameStorage } from "./game-data.js";
+import { createPreferencesStore } from "./preferences.js";
+import { createSaveStore } from "./saves.js";
+import { createStatsStore } from "./stats.js";
+import { createStreakStore } from "./streaks.js";
+//#region src/storage.ts
+/** Opens typed, validated storage over a backend. */
+var openStorage = (options) => {
+	const context = {
+		backend: options.backend,
+		notify: options.onNotice ?? (() => {}),
+		now: options.now ?? Date.now
+	};
+	const players = /* @__PURE__ */ new Map();
+	return {
+		player: (playerId) => {
+			if (!isKeyPart(playerId)) throw new RangeError(`"${playerId}" is not a valid player id`);
+			const existing = players.get(playerId);
+			if (existing !== void 0) return existing;
+			const player = {
+				playerId,
+				saves: createSaveStore(context, playerId),
+				stats: createStatsStore(context, playerId),
+				streaks: createStreakStore(context, playerId),
+				preferences: createPreferencesStore(context, playerId, options.changes),
+				gameStorage: (gameId) => createGameStorage(context, playerId, gameId)
+			};
+			players.set(playerId, player);
+			return player;
+		},
+		records: (kind) => createRecordStore(context, kind),
+		close: () => {
+			options.changes?.close();
+			options.backend.close();
+		}
+	};
+};
+//#endregion
+export { openStorage };
+
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","names":[],"sources":["../src/storage.ts"],"sourcesContent":["import type { GameStorage, Json } from '@joystyk/contracts';\nimport type { StorageBackend } from './backend.ts';\nimport type { ChangeFeed } from './changes.ts';\nimport { createGameStorage } from './game-data.ts';\nimport { isKeyPart } from './keys.ts';\nimport { createPreferencesStore, type PreferencesStore } from './preferences.ts';\nimport {\n  createRecordStore,\n  type RecordContext,\n  type RecordKind,\n  type RecordStore,\n  type StorageNotice,\n} from './record.ts';\nimport { createSaveStore, type SaveStore } from './saves.ts';\nimport { createStatsStore, type StatsStore } from './stats.ts';\nimport { createStreakStore, type StreakStore } from './streaks.ts';\n\nexport type StorageOptions = {\n  /** `createMemoryBackend()` in tests and on the server; `openIndexedDbBackend()` in the browser. */\n  readonly backend: StorageBackend;\n  /** Receives every notice; the frame shows them to the player. */\n  readonly onNotice?: (notice: StorageNotice) => void;\n  /** Epoch milliseconds. Defaults to `Date.now`. */\n  readonly now?: () => number;\n  /**\n   * Tells other tabs about changes and hears theirs, so a preference set in one tab reaches\n   * the rest (gp-d4v). `openBrowserStorage` provides one; without it, changes stay in this tab.\n   */\n  readonly changes?: ChangeFeed;\n};\n\n/** Everything one player keeps. Every key starts with the player id, never a device id. */\nexport interface PlayerStorage {\n  readonly playerId: string;\n  readonly saves: SaveStore;\n  readonly stats: StatsStore;\n  readonly streaks: StreakStore;\n  readonly preferences: PreferencesStore;\n  /** The `PlatformApi.storage` for one game. */\n  gameStorage(gameId: string): GameStorage;\n}\n\n/** The opened storage: typed record stores over one backend. */\nexport interface Storage {\n  /**\n   * One player's data. Throws a `RangeError` for an id that can't be part of a key, which\n   * is a bug: ids come from `@joystyk/identity`.\n   */\n  player(playerId: string): PlayerStorage;\n  /** A typed store for a record kind another package defines, such as identity's profile. */\n  records<T extends Json>(kind: RecordKind<T>): RecordStore<T>;\n  /** Closes the backend and the change feed. Idempotent. */\n  close(): void;\n}\n\n/** Opens typed, validated storage over a backend. */\nexport const openStorage = (options: StorageOptions): Storage => {\n  const context: RecordContext = {\n    backend: options.backend,\n    notify: options.onNotice ?? (() => {}),\n    now: options.now ?? Date.now,\n  };\n  const players = new Map<string, PlayerStorage>();\n\n  return {\n    player: (playerId) => {\n      if (!isKeyPart(playerId)) throw new RangeError(`\"${playerId}\" is not a valid player id`);\n      const existing = players.get(playerId);\n      if (existing !== undefined) return existing;\n      const player: PlayerStorage = {\n        playerId,\n        saves: createSaveStore(context, playerId),\n        stats: createStatsStore(context, playerId),\n        streaks: createStreakStore(context, playerId),\n        preferences: createPreferencesStore(context, playerId, options.changes),\n        gameStorage: (gameId) => createGameStorage(context, playerId, gameId),\n      };\n      players.set(playerId, player);\n      return player;\n    },\n    records: (kind) => createRecordStore(context, kind),\n    close: () => {\n      options.changes?.close();\n      options.backend.close();\n    },\n  };\n};\n"],"mappings":";;;;;;;;;AAwDA,IAAa,eAAe,YAAqC;CAC/D,MAAM,UAAyB;EAC7B,SAAS,QAAQ;EACjB,QAAQ,QAAQ,mBAAmB,CAAC;EACpC,KAAK,QAAQ,OAAO,KAAK;CAC3B;CACA,MAAM,0BAAU,IAAI,IAA2B;CAE/C,OAAO;EACL,SAAS,aAAa;GACpB,IAAI,CAAC,UAAU,QAAQ,GAAG,MAAM,IAAI,WAAW,IAAI,SAAS,2BAA2B;GACvF,MAAM,WAAW,QAAQ,IAAI,QAAQ;GACrC,IAAI,aAAa,KAAA,GAAW,OAAO;GACnC,MAAM,SAAwB;IAC5B;IACA,OAAO,gBAAgB,SAAS,QAAQ;IACxC,OAAO,iBAAiB,SAAS,QAAQ;IACzC,SAAS,kBAAkB,SAAS,QAAQ;IAC5C,aAAa,uBAAuB,SAAS,UAAU,QAAQ,OAAO;IACtE,cAAc,WAAW,kBAAkB,SAAS,UAAU,MAAM;GACtE;GACA,QAAQ,IAAI,UAAU,MAAM;GAC5B,OAAO;EACT;EACA,UAAU,SAAS,kBAAkB,SAAS,IAAI;EAClD,aAAa;GACX,QAAQ,SAAS,MAAM;GACvB,QAAQ,QAAQ,MAAM;EACxB;CACF;AACF"}

package/dist/streaks.d.ts

@@ -0,0 +1,23 @@
+import { type Result } from '@joystyk/contracts';
+import type { StorageError } from './backend.js';
+import { type RecordContext } from './record.js';
+/**
+ * One player's daily streak for one game. The `daily` package decides how a streak grows
+ * or breaks; this package only keeps it.
+ */
+export type Streak = {
+    readonly current: number;
+    readonly best: number;
+    /** The last day played, `yyyy-mm-dd`, or null. */
+    readonly lastDay: string | null;
+};
+export declare const EMPTY_STREAK: Streak;
+/** Version 1 of the streak record. */
+export declare const STREAK_RECORD: import("./record.js").RecordKind<Streak>;
+/** One player's daily streaks, by game id. v2 syncs them as "max wins" (offline-and-updates.md). */
+export interface StreakStore {
+    /** The game's streak, or `EMPTY_STREAK`. */
+    get(gameId: string): Promise<Result<Streak, StorageError>>;
+    set(gameId: string, streak: Streak): Promise<Result<void, StorageError>>;
+}
+export declare const createStreakStore: (context: RecordContext, playerId: string) => StreakStore;

package/dist/streaks.js

@@ -0,0 +1,41 @@
+import { gameKey } from "./keys.js";
+import { createRecordStore, defineRecordKind } from "./record.js";
+import { ok } from "@joystyk/contracts";
+import * as z from "zod/mini";
+//#region src/streaks.ts
+var EMPTY_STREAK = {
+	current: 0,
+	best: 0,
+	lastDay: null
+};
+var count = z.int().check(z.nonnegative());
+/** Version 1 of the streak record. */
+var STREAK_RECORD = defineRecordKind({
+	store: "streaks",
+	version: 1,
+	schema: z.object({
+		current: count,
+		best: count,
+		lastDay: z.nullable(z.string().check(z.regex(/^\d{4}-\d{2}-\d{2}$/)))
+	}).check(z.refine((streak) => streak.best >= streak.current, "best must be at least current")),
+	label: "daily streak"
+});
+var createStreakStore = (context, playerId) => {
+	const records = createRecordStore(context, STREAK_RECORD);
+	return {
+		get: async (gameId) => {
+			const key = gameKey(playerId, gameId);
+			if (!key.ok) return key;
+			const streak = await records.get(key.value);
+			return streak.ok ? ok(streak.value ?? EMPTY_STREAK) : streak;
+		},
+		set: async (gameId, streak) => {
+			const key = gameKey(playerId, gameId);
+			return key.ok ? records.set(key.value, streak) : key;
+		}
+	};
+};
+//#endregion
+export { EMPTY_STREAK, STREAK_RECORD, createStreakStore };
+
+//# sourceMappingURL=streaks.js.map

package/dist/streaks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaks.js","names":[],"sources":["../src/streaks.ts"],"sourcesContent":["import { ok, type Result } from '@joystyk/contracts';\nimport * as z from 'zod/mini';\nimport type { StorageError } from './backend.ts';\nimport { gameKey } from './keys.ts';\nimport { createRecordStore, defineRecordKind, type RecordContext } from './record.ts';\n\n/**\n * One player's daily streak for one game. The `daily` package decides how a streak grows\n * or breaks; this package only keeps it.\n */\nexport type Streak = {\n  readonly current: number;\n  readonly best: number;\n  /** The last day played, `yyyy-mm-dd`, or null. */\n  readonly lastDay: string | null;\n};\n\nexport const EMPTY_STREAK: Streak = { current: 0, best: 0, lastDay: null };\n\nconst count = z.int().check(z.nonnegative());\n\n/** Version 1 of the streak record. */\nexport const STREAK_RECORD = defineRecordKind<Streak>({\n  store: 'streaks',\n  version: 1,\n  schema: z\n    .object({\n      current: count,\n      best: count,\n      lastDay: z.nullable(z.string().check(z.regex(/^\\d{4}-\\d{2}-\\d{2}$/))),\n    })\n    .check(z.refine((streak) => streak.best >= streak.current, 'best must be at least current')),\n  label: 'daily streak',\n});\n\n/** One player's daily streaks, by game id. v2 syncs them as \"max wins\" (offline-and-updates.md). */\nexport interface StreakStore {\n  /** The game's streak, or `EMPTY_STREAK`. */\n  get(gameId: string): Promise<Result<Streak, StorageError>>;\n  set(gameId: string, streak: Streak): Promise<Result<void, StorageError>>;\n}\n\nexport const createStreakStore = (context: RecordContext, playerId: string): StreakStore => {\n  const records = createRecordStore(context, STREAK_RECORD);\n  return {\n    get: async (gameId) => {\n      const key = gameKey(playerId, gameId);\n      if (!key.ok) return key;\n      const streak = await records.get(key.value);\n      return streak.ok ? ok(streak.value ?? EMPTY_STREAK) : streak;\n    },\n    set: async (gameId, streak) => {\n      const key = gameKey(playerId, gameId);\n      return key.ok ? records.set(key.value, streak) : key;\n    },\n  };\n};\n"],"mappings":";;;;;AAiBA,IAAa,eAAuB;CAAE,SAAS;CAAG,MAAM;CAAG,SAAS;AAAK;AAEzE,IAAM,QAAQ,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC;;AAG3C,IAAa,gBAAgB,iBAAyB;CACpD,OAAO;CACP,SAAS;CACT,QAAQ,EACL,OAAO;EACN,SAAS;EACT,MAAM;EACN,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,qBAAqB,CAAC,CAAC;CACtE,CAAC,CAAC,CACD,MAAM,EAAE,QAAQ,WAAW,OAAO,QAAQ,OAAO,SAAS,+BAA+B,CAAC;CAC7F,OAAO;AACT,CAAC;AASD,IAAa,qBAAqB,SAAwB,aAAkC;CAC1F,MAAM,UAAU,kBAAkB,SAAS,aAAa;CACxD,OAAO;EACL,KAAK,OAAO,WAAW;GACrB,MAAM,MAAM,QAAQ,UAAU,MAAM;GACpC,IAAI,CAAC,IAAI,IAAI,OAAO;GACpB,MAAM,SAAS,MAAM,QAAQ,IAAI,IAAI,KAAK;GAC1C,OAAO,OAAO,KAAK,GAAG,OAAO,SAAS,YAAY,IAAI;EACxD;EACA,KAAK,OAAO,QAAQ,WAAW;GAC7B,MAAM,MAAM,QAAQ,UAAU,MAAM;GACpC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,OAAO,MAAM,IAAI;EACnD;CACF;AACF"}

package/dist/validate.d.ts

@@ -0,0 +1,14 @@
+import { type Json, type Result, type StandardSchemaV1 } from '@joystyk/contracts';
+import * as z from 'zod/mini';
+/** One validation problem, flattened for notices and logs: `path: message`. */
+export type Issue = string;
+/**
+ * Runs any Standard Schema (D-18) and returns its output or its issues. Works with sync and
+ * async validators alike.
+ */
+export declare const validate: <Output>(schema: StandardSchemaV1<unknown, Output>, value: unknown) => Promise<Result<Output, readonly Issue[]>>;
+/**
+ * Any JSON value, checked with the contracts' `isJson`: no `undefined`, `NaN`, `Infinity`,
+ * `-0`, class instances or cycles.
+ */
+export declare const json: z.ZodMiniCustom<Json, Json>;

package/dist/validate.js

@@ -0,0 +1,24 @@
+import { err, isJson, ok } from "@joystyk/contracts";
+import * as z from "zod/mini";
+//#region src/validate.ts
+var describe = (issue) => {
+	const path = (issue.path ?? []).map((segment) => String(typeof segment === "object" ? segment.key : segment)).join(".");
+	return path === "" ? issue.message : `${path}: ${issue.message}`;
+};
+/**
+* Runs any Standard Schema (D-18) and returns its output or its issues. Works with sync and
+* async validators alike.
+*/
+var validate = async (schema, value) => {
+	const result = await schema["~standard"].validate(value);
+	return result.issues === void 0 ? ok(result.value) : err(result.issues.map(describe));
+};
+/**
+* Any JSON value, checked with the contracts' `isJson`: no `undefined`, `NaN`, `Infinity`,
+* `-0`, class instances or cycles.
+*/
+var json = z.custom(isJson, { error: "Expected a JSON value" });
+//#endregion
+export { json, validate };
+
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","names":[],"sources":["../src/validate.ts"],"sourcesContent":["import { err, isJson, ok, type Json, type Result, type StandardSchemaV1 } from '@joystyk/contracts';\nimport * as z from 'zod/mini';\n\n/** One validation problem, flattened for notices and logs: `path: message`. */\nexport type Issue = string;\n\nconst describe = (issue: StandardSchemaV1.Issue): Issue => {\n  const path = (issue.path ?? [])\n    .map((segment) => String(typeof segment === 'object' ? segment.key : segment))\n    .join('.');\n  return path === '' ? issue.message : `${path}: ${issue.message}`;\n};\n\n/**\n * Runs any Standard Schema (D-18) and returns its output or its issues. Works with sync and\n * async validators alike.\n */\nexport const validate = async <Output>(\n  schema: StandardSchemaV1<unknown, Output>,\n  value: unknown,\n): Promise<Result<Output, readonly Issue[]>> => {\n  const result = await schema['~standard'].validate(value);\n  return result.issues === undefined ? ok(result.value) : err(result.issues.map(describe));\n};\n\n/**\n * Any JSON value, checked with the contracts' `isJson`: no `undefined`, `NaN`, `Infinity`,\n * `-0`, class instances or cycles.\n */\nexport const json = z.custom<Json>(isJson, { error: 'Expected a JSON value' });\n"],"mappings":";;;AAMA,IAAM,YAAY,UAAyC;CACzD,MAAM,QAAQ,MAAM,QAAQ,CAAC,EAAA,CAC1B,KAAK,YAAY,OAAO,OAAO,YAAY,WAAW,QAAQ,MAAM,OAAO,CAAC,CAAC,CAC7E,KAAK,GAAG;CACX,OAAO,SAAS,KAAK,MAAM,UAAU,GAAG,KAAK,IAAI,MAAM;AACzD;;;;;AAMA,IAAa,WAAW,OACtB,QACA,UAC8C;CAC9C,MAAM,SAAS,MAAM,OAAO,YAAY,CAAC,SAAS,KAAK;CACvD,OAAO,OAAO,WAAW,KAAA,IAAY,GAAG,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,IAAI,QAAQ,CAAC;AACzF;;;;;AAMA,IAAa,OAAO,EAAE,OAAa,QAAQ,EAAE,OAAO,wBAAwB,CAAC"}

package/package.json

@@ -1,20 +1,54 @@
 {
   "name": "@joystyk/storage",
-  "version": "0.0.0",
-  "description": "Reserved for the first Joystyk library release.",
+  "version": "0.2.0",
+  "description": "Versioned, validated player data: saves, stats, streaks and preferences, over IndexedDB or memory.",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "4.6.5",
+    "@joystyk/contracts": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vite": "8.3.3",
+    "vitest": "4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=24.15.0"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/joystyk-games/game-libraries.git",
     "directory": "packages/storage"
   },
-  "homepage": "https://github.com/joystyk-games/game-libraries",
-  "files": [
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ],
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://github.com/joystyk-games/game-libraries/tree/main/packages/storage#readme",
+  "bugs": {
+    "url": "https://github.com/joystyk-games/game-libraries/issues"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.core.json",
+    "build": "node ../../scripts/build-package.ts"
   }
-}
+}