hyperchess-store 0.1.0

package/dist/adapters/sqlite.js

@@ -0,0 +1,379 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// HyperChess Core — hyperchess-store
+// File: packages/store/src/adapters/sqlite.ts
+// Version: 1.0.0
+// Copyright (c) 2026 HyperChess Developer Team
+import { GameNotFoundError } from '../types/game-record';
+/**
+ * SQLite adapter for mobile and offline-first apps
+ * Requires: npm install better-sqlite3
+ *
+ * Features:
+ * - WAL mode for concurrent access
+ * - Sync queue for offline-first architecture
+ * - Automatic timestamp management
+ * - Efficient local queries
+ *
+ * Schema is self-managing: the constructor runs `CREATE TABLE IF NOT EXISTS` for
+ * a `games` table plus indexes on `user_id`, `created_at` and `synced`, so no
+ * external migration step is needed. `players` and `metadata` are stored as JSON
+ * text; timestamps are stored as ISO 8601 strings (not SQLite date types), which
+ * is why lexicographic `ORDER BY created_at` sorts chronologically.
+ *
+ * Unlike the server-backed adapters this one treats `synced` as false by
+ * default: rows written locally are pending until something drains
+ * {@link SqliteGameStore.getSyncQueue} and calls
+ * {@link SqliteGameStore.markSynced}.
+ *
+ * `better-sqlite3` is synchronous; the async signatures exist purely to satisfy
+ * the {@link GameStore} contract and never actually yield.
+ */
+export class SqliteGameStore {
+    /**
+     * Open (or create) the database file and ensure the schema exists.
+     *
+     * Sets `journal_mode = WAL` so readers don't block the writer, and
+     * `synchronous = NORMAL`, which trades a small durability window on OS crash
+     * for markedly faster writes — an acceptable bargain for a local cache whose
+     * source of truth lives upstream.
+     *
+     * @param dbPath - Filesystem path to the database; `:memory:` is accepted for
+     *   an ephemeral database.
+     * @throws Error if the optional `better-sqlite3` package is not installed.
+     */
+    constructor(dbPath) {
+        this.watchers = new Map();
+        this.pollIntervals = new Map();
+        try {
+            const Database = require('better-sqlite3');
+            this.db = new Database(dbPath);
+            // Enable WAL mode for better concurrent access
+            this.db.pragma('journal_mode = WAL');
+            this.db.pragma('synchronous = NORMAL');
+            this.initSchema();
+        }
+        catch (error) {
+            throw new Error('SQLite adapter requires "better-sqlite3" package: npm install better-sqlite3');
+        }
+    }
+    /**
+     * Create the `games` table and its lookup indexes if they are missing.
+     * Idempotent, so it runs unconditionally on every open.
+     */
+    initSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS games (
+        id TEXT PRIMARY KEY,
+        hpgn TEXT NOT NULL,
+        hfen TEXT NOT NULL,
+        players TEXT,
+        metadata TEXT,
+        result TEXT,
+        user_id TEXT,
+        synced BOOLEAN DEFAULT 0,
+        created_at TEXT,
+        updated_at TEXT
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_user_id ON games(user_id);
+      CREATE INDEX IF NOT EXISTS idx_created_at ON games(created_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_synced ON games(synced);
+    `);
+    }
+    /**
+     * Write a game with `INSERT OR REPLACE`.
+     *
+     * This is a whole-row replace, not a merge: columns absent from `game` are
+     * reset rather than preserved. `updated_at` is stamped with the current time,
+     * and `synced` defaults to 0 so the record enters the offline sync queue.
+     *
+     * @param game - Record to persist; a missing `id` is generated locally.
+     * @returns The id the row was written under.
+     */
+    async saveGame(game) {
+        const id = game.id || this.generateId();
+        const now = new Date().toISOString();
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO games (
+        id, hpgn, hfen, players, metadata, result, user_id, synced, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(id, game.hpgn, game.hfen, game.players ? JSON.stringify(game.players) : null, game.metadata ? JSON.stringify(game.metadata) : null, game.result || null, game.userId || null, game.synced ?? 0, // Mark as unsynced by default
+        game.createdAt || now, now);
+        // Notify watchers
+        const updated = await this.loadGame(id);
+        this.watchers.get(id)?.forEach((cb) => cb(updated));
+        return id;
+    }
+    /**
+     * Fetch one row by primary key.
+     *
+     * @param id - Game id.
+     * @returns The row mapped to {@link GameRecord} shape, with `synced` coerced
+     *   from SQLite's integer boolean.
+     * @throws {@link GameNotFoundError} if no row matches.
+     */
+    async loadGame(id) {
+        const stmt = this.db.prepare('SELECT * FROM games WHERE id = ?');
+        const row = stmt.get(id);
+        if (!row) {
+            throw new GameNotFoundError(id);
+        }
+        return this.rowToRecord(row);
+    }
+    /**
+     * Delete a row and tear down its watcher, including the backing poll timer.
+     *
+     * @param id - Game id.
+     * @throws {@link GameNotFoundError} if the statement changed no rows.
+     */
+    async deleteGame(id) {
+        const stmt = this.db.prepare('DELETE FROM games WHERE id = ?');
+        const result = stmt.run(id);
+        if (result.changes === 0) {
+            throw new GameNotFoundError(id);
+        }
+        this.stopWatching(id);
+    }
+    /**
+     * List games, filtering and paginating in SQL.
+     *
+     * Ordering is by `created_at` and defaults to descending. Filter values are
+     * bound as parameters, never interpolated into the SQL text.
+     *
+     * @param options - `userId`/`result` filters, `sort` direction, `limit` and
+     *   `offset`.
+     * @returns Matching rows in the requested order.
+     */
+    async listGames(options) {
+        let query = 'SELECT * FROM games WHERE 1=1';
+        const params = [];
+        if (options?.userId) {
+            query += ' AND user_id = ?';
+            params.push(options.userId);
+        }
+        if (options?.result) {
+            query += ' AND result = ?';
+            params.push(options.result);
+        }
+        query += ` ORDER BY created_at ${options?.sort === 'asc' ? 'ASC' : 'DESC'}`;
+        if (options?.limit) {
+            query += ' LIMIT ?';
+            params.push(options.limit);
+        }
+        if (options?.offset) {
+            query += ' OFFSET ?';
+            params.push(options.offset);
+        }
+        const stmt = this.db.prepare(query);
+        const rows = stmt.all(...params);
+        return rows.map((row) => this.rowToRecord(row));
+    }
+    /**
+     * Count matching rows with `COUNT(*)`, ignoring `limit`/`offset`.
+     *
+     * @param options - Only `userId` and `result` are honoured.
+     * @returns Total number of matching rows.
+     */
+    async countGames(options) {
+        let query = 'SELECT COUNT(*) as count FROM games WHERE 1=1';
+        const params = [];
+        if (options?.userId) {
+            query += ' AND user_id = ?';
+            params.push(options.userId);
+        }
+        if (options?.result) {
+            query += ' AND result = ?';
+            params.push(options.result);
+        }
+        const stmt = this.db.prepare(query);
+        const result = stmt.get(...params);
+        return result.count;
+    }
+    /**
+     * Observe a game by polling.
+     *
+     * SQLite has no change-notification channel, so the first watcher for an id
+     * starts a 1s interval that re-reads the row and pushes it to every callback.
+     * Consequences worth knowing: updates arrive with up to a second of latency,
+     * the callback fires on every tick whether or not the row actually changed,
+     * and if the row disappears the poll stops and all watchers for that id are
+     * dropped without a final event.
+     *
+     * @param id - Game id to observe.
+     * @param callback - Receives the current record on each poll.
+     * @returns Unsubscribe handle; the interval is cleared once the last callback
+     *   for the id is removed.
+     */
+    watch(id, callback) {
+        if (!this.watchers.has(id)) {
+            this.watchers.set(id, new Set());
+            // Start polling
+            const interval = setInterval(async () => {
+                try {
+                    const game = await this.loadGame(id);
+                    const callbacks = this.watchers.get(id);
+                    callbacks?.forEach((cb) => cb(game));
+                }
+                catch {
+                    // Game deleted or doesn't exist
+                    this.stopWatching(id);
+                }
+            }, 1000); // Poll every 1 second
+            this.pollIntervals.set(id, interval);
+        }
+        this.watchers.get(id).add(callback);
+        return () => {
+            const callbacks = this.watchers.get(id);
+            if (callbacks) {
+                callbacks.delete(callback);
+                if (callbacks.size === 0) {
+                    this.stopWatching(id);
+                }
+            }
+        };
+    }
+    /**
+     * Clear the poll interval for an id and forget its callbacks. Safe to call
+     * for an id that is not being watched.
+     */
+    stopWatching(id) {
+        const interval = this.pollIntervals.get(id);
+        if (interval) {
+            clearInterval(interval);
+            this.pollIntervals.delete(id);
+        }
+        this.watchers.delete(id);
+    }
+    /**
+     * Probe the open database handle with `SELECT 1`.
+     *
+     * @returns `false` instead of throwing if the handle is closed or the file is
+     *   unreadable.
+     */
+    async isHealthy() {
+        try {
+            this.db.prepare('SELECT 1').get();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // Offline-first sync management
+    /**
+     * Return the games still pending upload — every row with `synced = 0`.
+     *
+     * Intended to be drained on reconnect and pushed to a remote store, marking
+     * each one with {@link SqliteGameStore.markSynced} as it lands.
+     *
+     * @returns Unsynced records, unordered.
+     */
+    async getSyncQueue() {
+        const stmt = this.db.prepare('SELECT * FROM games WHERE synced = 0');
+        return stmt.all().map((row) => this.rowToRecord(row));
+    }
+    /**
+     * Flag a single game as uploaded, refreshing its `updated_at`.
+     *
+     * A no-op if the id is unknown — this reports nothing and throws nothing, so
+     * callers cannot use it to detect a missing row.
+     *
+     * @param id - Game id to mark.
+     */
+    async markSynced(id) {
+        const stmt = this.db.prepare('UPDATE games SET synced = 1, updated_at = ? WHERE id = ?');
+        stmt.run(new Date().toISOString(), id);
+    }
+    /**
+     * Mark every pending game as synced in one statement, without uploading
+     * anything. Use only when the queue is known to be reconciled — it discards
+     * the record of what still needs pushing. `updated_at` is left alone here.
+     */
+    async clearSyncQueue() {
+        const stmt = this.db.prepare('UPDATE games SET synced = 1 WHERE synced = 0');
+        stmt.run();
+    }
+    /**
+     * Read every row, newest first, in one unpaginated query.
+     *
+     * @returns All stored games.
+     */
+    async exportAll() {
+        const stmt = this.db.prepare('SELECT * FROM games ORDER BY created_at DESC');
+        return stmt.all().map((row) => this.rowToRecord(row));
+    }
+    /**
+     * Write a batch of games one statement at a time.
+     *
+     * Not wrapped in a transaction, so a failure part-way leaves earlier rows
+     * committed. Because it routes through `saveGame()`, imported rows land
+     * unsynced unless the source record says otherwise.
+     *
+     * @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 row and stop all polling watchers.
+     *
+     * The table and indexes survive; only the data is removed.
+     *
+     * @returns Number of rows deleted.
+     */
+    async clear() {
+        const stmt = this.db.prepare('DELETE FROM games');
+        const result = stmt.run();
+        this.watchers.clear();
+        this.pollIntervals.forEach((interval) => clearInterval(interval));
+        this.pollIntervals.clear();
+        return result.changes;
+    }
+    /**
+     * Map a snake_case row to a {@link GameRecord}, parsing the JSON text columns
+     * and coercing SQLite's integer `synced` flag to a boolean. Timestamps pass
+     * through unchanged because they are already stored as ISO 8601 strings.
+     */
+    rowToRecord(row) {
+        return {
+            id: row.id,
+            hpgn: row.hpgn,
+            hfen: row.hfen,
+            players: row.players ? JSON.parse(row.players) : undefined,
+            metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+            result: row.result,
+            userId: row.user_id,
+            synced: !!row.synced,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        };
+    }
+    generateId() {
+        return `game_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * Stop every poll timer and close the database handle.
+     *
+     * Required for the process to exit cleanly, since active `watch()` intervals
+     * would otherwise keep the event loop alive. The store is unusable afterwards.
+     */
+    close() {
+        this.pollIntervals.forEach((interval) => clearInterval(interval));
+        this.pollIntervals.clear();
+        this.watchers.clear();
+        this.db.close();
+    }
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/adapters/sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../src/adapters/sqlite.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,qCAAqC;AACrC,8CAA8C;AAC9C,iBAAiB;AACjB,+CAA+C;AAG/C,OAAO,EAAgC,iBAAiB,EAAe,MAAM,sBAAsB,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,OAAO,eAAe;IAK1B;;;;;;;;;;;OAWG;IACH,YAAY,MAAc;QAflB,aAAQ,GAAiD,IAAI,GAAG,EAAE,CAAC;QACnE,kBAAa,GAAqB,IAAI,GAAG,EAAE,CAAC;QAelD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;YAC3C,IAAI,CAAC,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;YAE/B,+CAA+C;YAC/C,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;YACrC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;YAEvC,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;QAClG,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,UAAU;QAChB,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;KAiBZ,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,QAAQ,CAAC,IAAgB;QAC7B,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAErC,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC;;;;KAI5B,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CACN,EAAE,EACF,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAClD,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,EACpD,IAAI,CAAC,MAAM,IAAI,IAAI,EACnB,IAAI,CAAC,MAAM,IAAI,IAAI,EACnB,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,8BAA8B;QAChD,IAAI,CAAC,SAAS,IAAI,GAAG,EACrB,GAAG,CACJ,CAAC;QAEF,kBAAkB;QAClB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;QAEpD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAU;QACvB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,kCAAkC,CAAC,CAAC;QACjE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAEzB,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,MAAM,IAAI,iBAAiB,CAAC,EAAE,CAAC,CAAC;QAClC,CAAC;QAED,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,EAAU;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,gCAAgC,CAAC,CAAC;QAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAE5B,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,iBAAiB,CAAC,EAAE,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,SAAS,CAAC,OAA0B;QACxC,IAAI,KAAK,GAAG,+BAA+B,CAAC;QAC5C,MAAM,MAAM,GAAU,EAAE,CAAC;QAEzB,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,KAAK,IAAI,kBAAkB,CAAC;YAC5B,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,KAAK,IAAI,iBAAiB,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,KAAK,IAAI,wBAAwB,OAAO,EAAE,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;QAE5E,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;YACnB,KAAK,IAAI,UAAU,CAAC;YACpB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QAED,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,KAAK,IAAI,WAAW,CAAC;YACrB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACpC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QAEjC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IACvD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,OAA0B;QACzC,IAAI,KAAK,GAAG,+CAA+C,CAAC;QAC5D,MAAM,MAAM,GAAU,EAAE,CAAC;QAEzB,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,KAAK,IAAI,kBAAkB,CAAC;YAC5B,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,KAAK,IAAI,iBAAiB,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAQ,CAAC;QAE1C,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAU,EAAE,QAAoC;QACpD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAC3B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;YAEjC,gBAAgB;YAChB,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;gBACtC,IAAI,CAAC;oBACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;oBACrC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;oBACxC,SAAS,EAAE,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;gBACvC,CAAC;gBAAC,MAAM,CAAC;oBACP,gCAAgC;oBAChC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,sBAAsB;YAEhC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;QACvC,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAErC,OAAO,GAAG,EAAE;YACV,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACxC,IAAI,SAAS,EAAE,CAAC;gBACd,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;gBAC3B,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;oBACzB,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;;;OAGG;IACK,YAAY,CAAC,EAAU;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC5C,IAAI,QAAQ,EAAE,CAAC;YACb,aAAa,CAAC,QAAQ,CAAC,CAAC;YACxB,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAChC,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,SAAS;QACb,IAAI,CAAC;YACH,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,gCAAgC;IAEhC;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY;QAChB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,sCAAsC,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,UAAU,CAAC,EAAU;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,0DAA0D,CAAC,CAAC;QACzF,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,cAAc;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,8CAA8C,CAAC,CAAC;QAC7E,IAAI,CAAC,GAAG,EAAE,CAAC;IACb,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,SAAS;QACb,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,8CAA8C,CAAC,CAAC;QAC7E,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,WAAW,CAAC,KAAmB;QACnC,IAAI,KAAK,GAAG,CAAC,CAAC;QAEd,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;gBAC1B,KAAK,EAAE,CAAC;YACV,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,CAAC,yBAAyB,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC;QAClE,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;IAED;;;;OAIG;IACK,WAAW,CAAC,GAAQ;QAC1B,OAAO;YACL,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;YAC1D,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS;YAC7D,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,MAAM,EAAE,GAAG,CAAC,OAAO;YACnB,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM;YACpB,SAAS,EAAE,GAAG,CAAC,UAAU;YACzB,SAAS,EAAE,GAAG,CAAC,UAAU;SAC1B,CAAC;IACJ,CAAC;IAEO,UAAU;QAChB,OAAO,QAAQ,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACzE,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACH,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC;QAClE,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;CACF"}

package/dist/adapters/supabase.d.ts

@@ -0,0 +1,180 @@
+import { GameStore } from '../types/game-store';
+import { GameRecord, GameQueryOptions, Unsubscribe } from '../types/game-record';
+/**
+ * Supabase adapter - PostgreSQL + Realtime + Auth
+ * Requires: npm install @supabase/supabase-js
+ *
+ * Features:
+ * - Realtime subscriptions via postgres_changes
+ * - Row Level Security aware (games scoped to authenticated user)
+ * - Range-based pagination
+ *
+ * Schema assumption: a `public.games` table exposed through PostgREST with
+ * columns `id` (primary key), `hpgn`, `hfen`, `players`, `metadata`, `result`,
+ * `user_id`, `synced`, `created_at`, `updated_at`. `players` and `metadata` are
+ * sent as objects and read back as objects, so those columns must be `json`/
+ * `jsonb` — the opposite of the raw Postgres adapter, which round-trips them as
+ * JSON strings.
+ *
+ * Because every call goes through PostgREST, Row Level Security applies: what a
+ * query returns depends on the key the client was built with. Under RLS a
+ * "missing" row and a forbidden one are indistinguishable, so
+ * {@link GameNotFoundError} can also mean "not visible to you". Realtime
+ * subscriptions likewise require the `games` table to be in the realtime
+ * publication.
+ *
+ * Errors from the client are surfaced as plain `Error`s carrying the PostgREST
+ * message rather than being swallowed — only `isHealthy()` degrades quietly.
+ */
+export declare class SupabaseGameStore implements GameStore {
+    private client;
+    private channels;
+    /**
+     * Create the underlying Supabase client.
+     *
+     * The key determines the store's effective permissions: an anon key leaves RLS
+     * in force (games scoped to the signed-in user), a service-role key bypasses
+     * it entirely and must never reach a browser.
+     *
+     * @param supabaseUrl - Project URL, e.g. `https://<ref>.supabase.co`.
+     * @param supabaseKey - Anon or service-role API key.
+     * @throws Error if the optional `@supabase/supabase-js` package is not
+     *   installed.
+     */
+    constructor(supabaseUrl: string, supabaseKey: string);
+    /**
+     * Upsert a game, conflicting on `id`, and read the stored row back.
+     *
+     * `updated_at` is always stamped with the current time; `created_at` falls
+     * back to now only when the record carries none, which means re-saving a
+     * record whose `createdAt` was dropped will rewrite the creation time.
+     *
+     * @param game - Record to persist; a missing `id` is generated locally.
+     * @returns The id reported by the returned row.
+     * @throws Error carrying the PostgREST message if the upsert is rejected —
+     *   including RLS denials.
+     */
+    saveGame(game: GameRecord): Promise<string>;
+    /**
+     * Fetch one row by id.
+     *
+     * Uses `maybeSingle()` so an absent row comes back as `null` data rather than
+     * a PostgREST error, letting the missing case be reported as a typed
+     * {@link GameNotFoundError}.
+     *
+     * @param id - Game id.
+     * @returns The row in {@link GameRecord} shape.
+     * @throws {@link GameNotFoundError} if no row is visible under `id`.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    loadGame(id: string): Promise<GameRecord>;
+    /**
+     * Delete a row, using the returned representation to prove it existed.
+     *
+     * The trailing `.select()` is what makes the not-found case detectable: a
+     * `DELETE` matching nothing is not an error to PostgREST, it simply returns an
+     * empty set.
+     *
+     * @param id - Game id.
+     * @throws {@link GameNotFoundError} if no row was deleted.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    deleteGame(id: string): Promise<void>;
+    /**
+     * List games using PostgREST filters and range-based pagination.
+     *
+     * `range()` bounds are inclusive, so a page is expressed as
+     * `[offset, offset + limit - 1]`. An `offset` given without a `limit` falls
+     * back to a fixed 1000-row window, since PostgREST needs an upper bound.
+     *
+     * @param options - `userId`/`result` equality filters, `sort` direction
+     *   (default descending by `created_at`), `limit` and `offset`.
+     * @returns Matching rows in the requested order.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    listGames(options?: GameQueryOptions): Promise<GameRecord[]>;
+    /**
+     * Count matching rows without transferring them.
+     *
+     * `head: true` issues a `HEAD` request so only the count header comes back;
+     * `count: 'exact'` is accurate but does a full scan on large tables.
+     *
+     * @param options - Only `userId` and `result` are honoured.
+     * @returns Total number of matching rows, or 0 if the count header is absent.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    countGames(options?: GameQueryOptions): Promise<number>;
+    /**
+     * Subscribe to a game over a Realtime `postgres_changes` channel.
+     *
+     * Listens for `UPDATE` events only — inserts and deletes are not delivered, so
+     * watching an id before it exists yields nothing until the first update after
+     * creation. Each id gets its own channel, tracked so `clear()` can tear them
+     * all down.
+     *
+     * @param id - Game id to observe.
+     * @param callback - Receives the new row from the change payload.
+     * @returns Unsubscribe handle that removes the channel.
+     */
+    watch(id: string, callback: (game: GameRecord) => void): Unsubscribe;
+    /**
+     * Probe with a bounded head request against the `games` table.
+     *
+     * Verifies both reachability and that the table is readable under the current
+     * key and RLS policy.
+     *
+     * @returns `false` instead of throwing on any error.
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Read every visible row, newest first.
+     *
+     * No range is applied, so the result is still subject to the project's
+     * PostgREST `max-rows` setting — on a large table this may silently return a
+     * truncated backup.
+     *
+     * @returns All games visible to the current key.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    exportAll(): Promise<GameRecord[]>;
+    /**
+     * Upsert a batch of games with one request per record.
+     *
+     * Sequential and non-transactional; a record rejected by RLS or a constraint
+     * is logged and skipped, so a partial import is possible.
+     *
+     * @param games - Records to import.
+     * @returns How many were saved successfully.
+     */
+    importGames(games: GameRecord[]): Promise<number>;
+    /**
+     * Delete every visible row and close all Realtime channels.
+     *
+     * The `neq('id', '')` predicate exists because PostgREST refuses an unfiltered
+     * `DELETE` as a footgun guard; matching "id is not the empty string" selects
+     * everything while satisfying that requirement. RLS still applies, so this
+     * clears only what the current key can see.
+     *
+     * @returns Number of rows deleted.
+     * @throws Error carrying the PostgREST message on a query failure.
+     */
+    clear(): Promise<number>;
+    /**
+     * Map a snake_case PostgREST row to a {@link GameRecord}. The JSON columns
+     * arrive already deserialised, so only the key renaming and `null`-to-
+     * `undefined` normalisation is needed.
+     */
+    private rowToRecord;
+    private generateId;
+    /**
+     * Resolve the id of the currently signed-in Supabase user.
+     *
+     * Useful for stamping `GameRecord.userId` so saved games line up with the
+     * `user_id` an RLS policy filters on.
+     *
+     * @returns The auth user id, or `null` when nobody is signed in or the lookup
+     *   fails — the two cases are not distinguished.
+     */
+    getAuthenticatedUser(): Promise<string | null>;
+}
+//# sourceMappingURL=supabase.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"supabase.d.ts","sourceRoot":"","sources":["../../src/adapters/supabase.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAqB,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,iBAAkB,YAAW,SAAS;IACjD,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,QAAQ,CAA+B;IAE/C;;;;;;;;;;;OAWG;gBACS,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;IAWpD;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IA+BjD;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAa/C;;;;;;;;;;OAUG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3C;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAwBlE;;;;;;;;;OASG;IACG,UAAU,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAe7D;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,WAAW;IAmBpE;;;;;;;OAOG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IASnC;;;;;;;;;OASG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAUxC;;;;;;;;OAQG;IACG,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAevD;;;;;;;;;;OAUG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAa9B;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,UAAU;IAMlB;;;;;;;;OAQG;IACG,oBAAoB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CASrD"}