hyperchess-store 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# hyperchess-store
+
+Game persistence for [HyperChess](https://github.com/KyrpyDev/hyperchess-core) — one
+`GameStore` interface, five adapters. Save, load, list, and watch games without coupling your app
+to a backend.
+
+```js
+import { MemoryGameStore } from 'hyperchess-store/memory';       // zero-config, great for tests
+import { SqliteGameStore } from 'hyperchess-store/sqlite';       // better-sqlite3
+import { PostgresGameStore } from 'hyperchess-store/postgres';   // pg
+import { FirebaseGameStore } from 'hyperchess-store/firebase';   // firebase
+import { SupabaseGameStore } from 'hyperchess-store/supabase';   // @supabase/supabase-js
+```
+
+Every backend driver is an **optional peer dependency** — install only what you use; the memory
+adapter needs nothing.
+
+## Quick start
+
+```js
+import { MemoryGameStore } from 'hyperchess-store/memory';
+
+const store = new MemoryGameStore();
+
+const id = await store.saveGame(record);        // record: GameRecord
+const game = await store.loadGame(id);
+const recent = await store.listGames({ limit: 10 });
+
+const unsubscribe = store.watch(id, (updated) => {
+  console.log('game changed', updated);
+});
+```
+
+All adapters implement the same `GameStore` interface (`saveGame`, `loadGame`, `deleteGame`,
+`listGames`, `countGames`, `watch`, `isHealthy`, `exportAll`, `importGames`, `clear`), so
+swapping backends is a one-line change. `syncStores` copies games between two stores — e.g.
+local SQLite up to Postgres.
+
+Part of the [HyperChess Core](https://github.com/KyrpyDev/hyperchess-core) monorepo —
+see the repository README for the full stack, contributing guide, and license
+(GPL-3.0-or-later).

package/dist/adapters/firebase.d.ts

@@ -0,0 +1,157 @@
+import { GameStore } from '../types/game-store';
+import { GameRecord, GameQueryOptions, Unsubscribe } from '../types/game-record';
+/**
+ * Firebase Firestore adapter for real-time multiplayer
+ * Requires: npm install firebase
+ *
+ * Features:
+ * - Real-time updates via onSnapshot
+ * - Server-side count (getCountFromServer) with client fallback
+ * - Batched deletes (respects Firestore's 500-op batch limit)
+ *
+ * Schema assumption: a single top-level `games` collection whose document id is
+ * the game id, so `id` is never stored as a field. Fields are camelCase and
+ * written as native Firestore values — `players` and `metadata` are nested maps
+ * rather than JSON strings, unlike the SQL adapters. Timestamps are ISO 8601
+ * strings, not Firestore `Timestamp`s, which keeps ordering lexicographic and
+ * comparable across backends.
+ *
+ * Composite queries (`listGames` with a filter plus `orderBy('createdAt')`)
+ * require matching composite indexes in the project's Firestore configuration;
+ * without them Firestore rejects the query at runtime.
+ */
+export declare class FirebaseGameStore implements GameStore {
+    private db;
+    private fs;
+    /**
+     * Bind the store to an already-initialised Firebase app.
+     *
+     * The whole `firebase/firestore` module is captured rather than individual
+     * functions, because the modular v9+ SDK exposes everything as free functions
+     * that must be called with the `Firestore` instance.
+     *
+     * @param firebaseApp - A `FirebaseApp` from `initializeApp()`; authentication
+     *   and security-rule context come from that app, not from this store.
+     * @throws Error if the optional `firebase` package is not installed.
+     */
+    constructor(firebaseApp: any);
+    /** Reference to the top-level `games` collection this adapter operates on. */
+    private collectionRef;
+    /**
+     * Write a game as a merged document under `games/{id}`.
+     *
+     * Reads the existing document first so an update preserves its original
+     * `createdAt` — that costs an extra round trip on every save, but it is the
+     * only way to keep creation time stable given `{ merge: true }` would happily
+     * overwrite it. Optional fields are written as explicit `null` rather than
+     * omitted, so a cleared field is actually cleared instead of surviving the
+     * merge.
+     *
+     * @param game - Record to persist; a missing `id` is generated locally.
+     * @returns The document id the game was written to.
+     */
+    saveGame(game: GameRecord): Promise<string>;
+    /**
+     * Fetch one document by id.
+     *
+     * @param id - Game id, used directly as the document id.
+     * @returns The document data with `id` reattached from the document key.
+     * @throws {@link GameNotFoundError} if the document does not exist.
+     */
+    loadGame(id: string): Promise<GameRecord>;
+    /**
+     * Delete a document, first confirming it exists.
+     *
+     * The existence check is a deliberate extra read: Firestore's `deleteDoc`
+     * succeeds silently on a missing document, which would make it impossible to
+     * report {@link GameNotFoundError} consistently with the other adapters.
+     *
+     * @param id - Game id.
+     * @throws {@link GameNotFoundError} if the document does not exist.
+     */
+    deleteGame(id: string): Promise<void>;
+    /**
+     * List games, filtering and ordering server-side.
+     *
+     * Firestore has no `OFFSET`, so pagination is emulated by fetching
+     * `limit + offset` documents and slicing locally — deep pages therefore cost
+     * proportionally more reads. With neither `limit` nor `offset` set, no limit
+     * constraint is applied and the whole collection is read.
+     *
+     * @param options - `userId`/`result` equality filters, `sort` direction
+     *   (default descending by `createdAt`), `limit` and `offset`.
+     * @returns Matching games in the requested order.
+     */
+    listGames(options?: GameQueryOptions): Promise<GameRecord[]>;
+    /**
+     * Count matching documents, preferring the server-side aggregation.
+     *
+     * Uses `getCountFromServer` where the installed SDK provides it, which bills a
+     * single aggregation query instead of a read per document. Older SDKs fall
+     * back to fetching every match and taking `snap.size`, which is correct but
+     * far more expensive.
+     *
+     * @param options - Only `userId` and `result` are honoured.
+     * @returns Total number of matching documents.
+     */
+    countGames(options?: GameQueryOptions): Promise<number>;
+    /**
+     * Subscribe to a document with Firestore's native `onSnapshot` listener.
+     *
+     * This is the only adapter with true push updates and no polling. The callback
+     * fires immediately with the current value on attach, then on every remote
+     * change. Deletions are swallowed — a snapshot for a removed document does not
+     * invoke the callback.
+     *
+     * @param id - Game id to observe.
+     * @param callback - Receives the document each time it changes.
+     * @returns Firestore's own unsubscribe function.
+     */
+    watch(id: string, callback: (game: GameRecord) => void): Unsubscribe;
+    /**
+     * Probe by reading at most one document from the `games` collection.
+     *
+     * Stricter than a bare connectivity check: a security rule that denies reads
+     * will report unhealthy, which is the useful answer for a store.
+     *
+     * @returns `false` instead of throwing if the read fails.
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Read the entire `games` collection, newest first.
+     *
+     * Costs one document read per game, so this is a backup operation rather than
+     * something to call on a request path.
+     *
+     * @returns All stored games.
+     */
+    exportAll(): Promise<GameRecord[]>;
+    /**
+     * Write a batch of games one document at a time.
+     *
+     * Sequential rather than batched, and each save costs a read plus a write
+     * because of the `createdAt` preservation in `saveGame()`. Failures are logged
+     * and skipped, so a partial import is possible.
+     *
+     * @param games - Records to import.
+     * @returns How many were written successfully.
+     */
+    importGames(games: GameRecord[]): Promise<number>;
+    /**
+     * Delete every document in the `games` collection.
+     *
+     * Firestore caps a write batch at 500 operations, so deletions are chunked and
+     * each chunk committed in turn. That makes this non-atomic: a failure midway
+     * leaves earlier chunks already deleted.
+     *
+     * @returns Number of documents deleted.
+     */
+    clear(): Promise<number>;
+    /**
+     * Rebuild a {@link GameRecord} from a document's id and data, normalising the
+     * `null`s Firestore stores for absent optional fields back to `undefined`.
+     */
+    private docToRecord;
+    private generateId;
+}
+//# sourceMappingURL=firebase.d.ts.map

package/dist/adapters/firebase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firebase.d.ts","sourceRoot":"","sources":["../../src/adapters/firebase.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAqB,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAkB,YAAW,SAAS;IACjD,OAAO,CAAC,EAAE,CAAM;IAChB,OAAO,CAAC,EAAE,CAAM;IAEhB;;;;;;;;;;OAUG;gBACS,WAAW,EAAE,GAAG;IAU5B,8EAA8E;IAC9E,OAAO,CAAC,aAAa;IAIrB;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BjD;;;;;;OAMG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAW/C;;;;;;;;;OASG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY3C;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqBlE;;;;;;;;;;OAUG;IACG,UAAU,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAkB7D;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,WAAW;IASpE;;;;;;;OAOG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAUnC;;;;;;;OAOG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAMxC;;;;;;;;;OASG;IACG,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAevD;;;;;;;;OAQG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAqB9B;;;OAGG;IACH,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,UAAU;CAGnB"}

package/dist/adapters/firebase.js

@@ -0,0 +1,300 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// HyperChess Core — hyperchess-store
+// File: packages/store/src/adapters/firebase.ts
+// Version: 1.0.0
+// Copyright (c) 2026 HyperChess Developer Team
+import { GameNotFoundError } from '../types/game-record';
+/**
+ * Firebase Firestore adapter for real-time multiplayer
+ * Requires: npm install firebase
+ *
+ * Features:
+ * - Real-time updates via onSnapshot
+ * - Server-side count (getCountFromServer) with client fallback
+ * - Batched deletes (respects Firestore's 500-op batch limit)
+ *
+ * Schema assumption: a single top-level `games` collection whose document id is
+ * the game id, so `id` is never stored as a field. Fields are camelCase and
+ * written as native Firestore values — `players` and `metadata` are nested maps
+ * rather than JSON strings, unlike the SQL adapters. Timestamps are ISO 8601
+ * strings, not Firestore `Timestamp`s, which keeps ordering lexicographic and
+ * comparable across backends.
+ *
+ * Composite queries (`listGames` with a filter plus `orderBy('createdAt')`)
+ * require matching composite indexes in the project's Firestore configuration;
+ * without them Firestore rejects the query at runtime.
+ */
+export class FirebaseGameStore {
+    /**
+     * Bind the store to an already-initialised Firebase app.
+     *
+     * The whole `firebase/firestore` module is captured rather than individual
+     * functions, because the modular v9+ SDK exposes everything as free functions
+     * that must be called with the `Firestore` instance.
+     *
+     * @param firebaseApp - A `FirebaseApp` from `initializeApp()`; authentication
+     *   and security-rule context come from that app, not from this store.
+     * @throws Error if the optional `firebase` package is not installed.
+     */
+    constructor(firebaseApp) {
+        try {
+            const firestoreApi = require('firebase/firestore');
+            this.fs = firestoreApi;
+            this.db = firestoreApi.getFirestore(firebaseApp);
+        }
+        catch (error) {
+            throw new Error('Firebase adapter requires "firebase" package: npm install firebase');
+        }
+    }
+    /** Reference to the top-level `games` collection this adapter operates on. */
+    collectionRef() {
+        return this.fs.collection(this.db, 'games');
+    }
+    /**
+     * Write a game as a merged document under `games/{id}`.
+     *
+     * Reads the existing document first so an update preserves its original
+     * `createdAt` — that costs an extra round trip on every save, but it is the
+     * only way to keep creation time stable given `{ merge: true }` would happily
+     * overwrite it. Optional fields are written as explicit `null` rather than
+     * omitted, so a cleared field is actually cleared instead of surviving the
+     * merge.
+     *
+     * @param game - Record to persist; a missing `id` is generated locally.
+     * @returns The document id the game was written to.
+     */
+    async saveGame(game) {
+        const { doc, getDoc, setDoc } = this.fs;
+        const id = game.id || this.generateId();
+        const now = new Date().toISOString();
+        const ref = doc(this.db, 'games', id);
+        const existing = await getDoc(ref);
+        const createdAt = existing.exists() ? existing.data().createdAt : game.createdAt || now;
+        await setDoc(ref, {
+            hpgn: game.hpgn,
+            hfen: game.hfen,
+            players: game.players ?? null,
+            metadata: game.metadata ?? null,
+            result: game.result ?? null,
+            userId: game.userId ?? null,
+            synced: game.synced ?? true,
+            createdAt,
+            updatedAt: now,
+        }, { merge: true });
+        return id;
+    }
+    /**
+     * Fetch one document by id.
+     *
+     * @param id - Game id, used directly as the document id.
+     * @returns The document data with `id` reattached from the document key.
+     * @throws {@link GameNotFoundError} if the document does not exist.
+     */
+    async loadGame(id) {
+        const { doc, getDoc } = this.fs;
+        const snap = await getDoc(doc(this.db, 'games', id));
+        if (!snap.exists()) {
+            throw new GameNotFoundError(id);
+        }
+        return this.docToRecord(id, snap.data());
+    }
+    /**
+     * Delete a document, first confirming it exists.
+     *
+     * The existence check is a deliberate extra read: Firestore's `deleteDoc`
+     * succeeds silently on a missing document, which would make it impossible to
+     * report {@link GameNotFoundError} consistently with the other adapters.
+     *
+     * @param id - Game id.
+     * @throws {@link GameNotFoundError} if the document does not exist.
+     */
+    async deleteGame(id) {
+        const { doc, getDoc, deleteDoc } = this.fs;
+        const ref = doc(this.db, 'games', id);
+        const snap = await getDoc(ref);
+        if (!snap.exists()) {
+            throw new GameNotFoundError(id);
+        }
+        await deleteDoc(ref);
+    }
+    /**
+     * List games, filtering and ordering server-side.
+     *
+     * Firestore has no `OFFSET`, so pagination is emulated by fetching
+     * `limit + offset` documents and slicing locally — deep pages therefore cost
+     * proportionally more reads. With neither `limit` nor `offset` set, no limit
+     * constraint is applied and the whole collection is read.
+     *
+     * @param options - `userId`/`result` equality filters, `sort` direction
+     *   (default descending by `createdAt`), `limit` and `offset`.
+     * @returns Matching games in the requested order.
+     */
+    async listGames(options) {
+        const { query, where, orderBy, limit: fsLimit, getDocs } = this.fs;
+        const constraints = [];
+        if (options?.userId)
+            constraints.push(where('userId', '==', options.userId));
+        if (options?.result)
+            constraints.push(where('result', '==', options.result));
+        constraints.push(orderBy('createdAt', options?.sort === 'asc' ? 'asc' : 'desc'));
+        // Firestore has no offset primitive; over-fetch to (limit + offset) and slice client-side.
+        const fetchLimit = (options?.limit ?? 0) + (options?.offset ?? 0);
+        if (fetchLimit > 0)
+            constraints.push(fsLimit(fetchLimit));
+        const snap = await getDocs(query(this.collectionRef(), ...constraints));
+        let rows = snap.docs.map((d) => this.docToRecord(d.id, d.data()));
+        if (options?.offset)
+            rows = rows.slice(options.offset);
+        if (options?.limit)
+            rows = rows.slice(0, options.limit);
+        return rows;
+    }
+    /**
+     * Count matching documents, preferring the server-side aggregation.
+     *
+     * Uses `getCountFromServer` where the installed SDK provides it, which bills a
+     * single aggregation query instead of a read per document. Older SDKs fall
+     * back to fetching every match and taking `snap.size`, which is correct but
+     * far more expensive.
+     *
+     * @param options - Only `userId` and `result` are honoured.
+     * @returns Total number of matching documents.
+     */
+    async countGames(options) {
+        const { query, where, getCountFromServer, getDocs } = this.fs;
+        const constraints = [];
+        if (options?.userId)
+            constraints.push(where('userId', '==', options.userId));
+        if (options?.result)
+            constraints.push(where('result', '==', options.result));
+        const q = query(this.collectionRef(), ...constraints);
+        if (getCountFromServer) {
+            const snap = await getCountFromServer(q);
+            return snap.data().count;
+        }
+        const snap = await getDocs(q);
+        return snap.size;
+    }
+    /**
+     * Subscribe to a document with Firestore's native `onSnapshot` listener.
+     *
+     * This is the only adapter with true push updates and no polling. The callback
+     * fires immediately with the current value on attach, then on every remote
+     * change. Deletions are swallowed — a snapshot for a removed document does not
+     * invoke the callback.
+     *
+     * @param id - Game id to observe.
+     * @param callback - Receives the document each time it changes.
+     * @returns Firestore's own unsubscribe function.
+     */
+    watch(id, callback) {
+        const { doc, onSnapshot } = this.fs;
+        return onSnapshot(doc(this.db, 'games', id), (snap) => {
+            if (snap.exists()) {
+                callback(this.docToRecord(id, snap.data()));
+            }
+        });
+    }
+    /**
+     * Probe by reading at most one document from the `games` collection.
+     *
+     * Stricter than a bare connectivity check: a security rule that denies reads
+     * will report unhealthy, which is the useful answer for a store.
+     *
+     * @returns `false` instead of throwing if the read fails.
+     */
+    async isHealthy() {
+        try {
+            const { query, limit: fsLimit, getDocs } = this.fs;
+            await getDocs(query(this.collectionRef(), fsLimit(1)));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Read the entire `games` collection, newest first.
+     *
+     * Costs one document read per game, so this is a backup operation rather than
+     * something to call on a request path.
+     *
+     * @returns All stored games.
+     */
+    async exportAll() {
+        const { query, orderBy, getDocs } = this.fs;
+        const snap = await getDocs(query(this.collectionRef(), orderBy('createdAt', 'desc')));
+        return snap.docs.map((d) => this.docToRecord(d.id, d.data()));
+    }
+    /**
+     * Write a batch of games one document at a time.
+     *
+     * Sequential rather than batched, and each save costs a read plus a write
+     * because of the `createdAt` preservation in `saveGame()`. Failures are logged
+     * and skipped, so a partial import is possible.
+     *
+     * @param games - Records to import.
+     * @returns How many were written successfully.
+     */
+    async importGames(games) {
+        let count = 0;
+        for (const game of games) {
+            try {
+                await this.saveGame(game);
+                count++;
+            }
+            catch (error) {
+                console.warn(`Failed to import game ${game.id}:`, error);
+            }
+        }
+        return count;
+    }
+    /**
+     * Delete every document in the `games` collection.
+     *
+     * Firestore caps a write batch at 500 operations, so deletions are chunked and
+     * each chunk committed in turn. That makes this non-atomic: a failure midway
+     * leaves earlier chunks already deleted.
+     *
+     * @returns Number of documents deleted.
+     */
+    async clear() {
+        const { doc, getDocs, writeBatch } = this.fs;
+        const snap = await getDocs(this.collectionRef());
+        const docs = snap.docs;
+        const BATCH_LIMIT = 500; // Firestore's max writes per batch
+        let deleted = 0;
+        for (let i = 0; i < docs.length; i += BATCH_LIMIT) {
+            const batch = writeBatch(this.db);
+            const chunk = docs.slice(i, i + BATCH_LIMIT);
+            for (const d of chunk) {
+                batch.delete(doc(this.db, 'games', d.id));
+            }
+            await batch.commit();
+            deleted += chunk.length;
+        }
+        return deleted;
+    }
+    /**
+     * Rebuild a {@link GameRecord} from a document's id and data, normalising the
+     * `null`s Firestore stores for absent optional fields back to `undefined`.
+     */
+    docToRecord(id, data) {
+        return {
+            id,
+            hpgn: data.hpgn,
+            hfen: data.hfen,
+            players: data.players ?? undefined,
+            metadata: data.metadata ?? undefined,
+            result: data.result ?? undefined,
+            userId: data.userId ?? undefined,
+            synced: data.synced ?? undefined,
+            createdAt: data.createdAt,
+            updatedAt: data.updatedAt,
+        };
+    }
+    generateId() {
+        return `game_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+}
+//# sourceMappingURL=firebase.js.map

package/dist/adapters/firebase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"firebase.js","sourceRoot":"","sources":["../../src/adapters/firebase.ts"],"names":[],"mappings":"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"}

package/dist/adapters/memory.d.ts

@@ -0,0 +1,110 @@
+import { GameStore } from '../types/game-store';
+import { GameRecord, GameQueryOptions } from '../types/game-record';
+/**
+ * In-memory game store for testing and development.
+ *
+ * Backed by a plain `Map`, so all data is lost when the process exits. It is the
+ * package default export and the reference implementation of {@link GameStore}:
+ * every other adapter is expected to match its observable behaviour.
+ *
+ * Records are deep-copied with `structuredClone` on the way out (and into
+ * watcher callbacks) so a caller mutating a returned object cannot corrupt the
+ * store — a hazard the database adapters don't have because they deserialise
+ * fresh rows on every read.
+ */
+export declare class MemoryGameStore implements GameStore {
+    private games;
+    private watchers;
+    /**
+     * Insert or replace a game, stamping `updatedAt` with the current time.
+     *
+     * The record fully replaces any existing entry rather than merging into it,
+     * and watchers of this id are notified synchronously before returning.
+     *
+     * @param game - Record to store; if `id` is empty a new one is generated.
+     * @returns The id the game was stored under.
+     */
+    saveGame(game: GameRecord): Promise<string>;
+    /**
+     * Fetch a game by id.
+     *
+     * @param id - Game id to look up.
+     * @returns A deep copy of the stored record, safe for the caller to mutate.
+     * @throws {@link GameNotFoundError} if no game is stored under `id`.
+     */
+    loadGame(id: string): Promise<GameRecord>;
+    /**
+     * Remove a game and drop every watcher registered against it.
+     *
+     * Watchers are discarded silently — they receive no final notification, so a
+     * subscriber must treat "no further updates" as a possible deletion.
+     *
+     * @param id - Game id to remove.
+     * @throws {@link GameNotFoundError} if no game is stored under `id`.
+     */
+    deleteGame(id: string): Promise<void>;
+    /**
+     * List games, filtering, sorting and paginating entirely in memory.
+     *
+     * Sorting is by `createdAt`, treating a missing timestamp as the epoch so
+     * undated records sort oldest. Note the default order is ascending here,
+     * whereas the SQL-backed adapters default to descending.
+     *
+     * @param options - Filters (`userId`, `result`), `sort` direction and
+     *   `offset`/`limit` window; omitting `limit` returns everything after
+     *   `offset`.
+     * @returns Deep copies of the matching records.
+     */
+    listGames(options?: GameQueryOptions): Promise<GameRecord[]>;
+    /**
+     * Count games matching the filters.
+     *
+     * `limit` and `offset` are deliberately ignored so the result is the total
+     * size of the match set, not the size of one page.
+     *
+     * @param options - Only `userId` and `result` are honoured.
+     * @returns Number of matching records.
+     */
+    countGames(options?: GameQueryOptions): Promise<number>;
+    /**
+     * Subscribe to writes for a single game.
+     *
+     * Fires only on subsequent `saveGame()` calls — there is no initial emission
+     * of the current value, and deletions produce no event.
+     *
+     * @param id - Game id to observe. Watching an id that does not exist yet is
+     *   valid; the callback fires when it is first saved.
+     * @param callback - Receives a deep copy of the saved record.
+     * @returns Unsubscribe handle; the id's watcher set is dropped once empty.
+     */
+    watch(id: string, callback: (game: GameRecord) => void): () => void;
+    /**
+     * Always resolves `true` — there is no backend that can be unreachable.
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Dump every stored game, unfiltered and in insertion order.
+     *
+     * @returns Deep copies of all records.
+     */
+    exportAll(): Promise<GameRecord[]>;
+    /**
+     * Bulk-load records, overwriting any existing game with the same id.
+     *
+     * Each import goes through `saveGame()`, so `updatedAt` is rewritten to now
+     * and watchers fire — importing a backup is not a silent restore.
+     *
+     * @param games - Records to load.
+     * @returns The number of records supplied.
+     */
+    importGames(games: GameRecord[]): Promise<number>;
+    /**
+     * Drop every game and every registered watcher.
+     *
+     * @returns How many games were removed.
+     */
+    clear(): Promise<number>;
+    private notifyWatchers;
+    private generateId;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/adapters/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAqB,MAAM,sBAAsB,CAAC;AAEvF;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,QAAQ,CAA2D;IAE3E;;;;;;;;OAQG;IACG,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBjD;;;;;;OAMG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAQ/C;;;;;;;;OAQG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa3C;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA6BlE;;;;;;;;OAQG;IACG,UAAU,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAc7D;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;IAmBnE;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAIxC;;;;;;;;OAQG;IACG,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAOvD;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAO9B,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,UAAU;CAGnB"}