hyperchess-store 0.1.0

package/dist/adapters/postgres.js

@@ -0,0 +1,341 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// HyperChess Core — hyperchess-store
+// File: packages/store/src/adapters/postgres.ts
+// Version: 1.0.0
+// Copyright (c) 2026 HyperChess Developer Team
+import { GameNotFoundError } from '../types/game-record';
+/**
+ * PostgreSQL adapter for production game storage
+ * Requires: npm install pg
+ *
+ * Features:
+ * - Connection pooling
+ * - LISTEN/NOTIFY for real-time updates
+ * - Full-text search ready
+ * - Automatic timestamp management
+ *
+ * Schema assumption: a `games` table must already exist — unlike the SQLite
+ * adapter this one never runs DDL, so migrations are the deployment's job. Its
+ * columns are `id` (primary key), `hpgn`, `hfen`, `players`, `metadata`,
+ * `result`, `user_id`, `synced`, `created_at`, `updated_at`. `players` and
+ * `metadata` are written as JSON strings and read back with `JSON.parse`, so
+ * they must be `text`/`json` rather than `jsonb` (a `jsonb` column would be
+ * returned pre-parsed by `pg` and fail to parse again). The timestamp columns
+ * are read as `Date` objects and converted to ISO strings.
+ *
+ * Real-time updates rely on a database-side trigger publishing
+ * `NOTIFY game_updates` with a `{ id, game }` JSON payload; without that trigger
+ * `watch()` still fires locally for writes made through this instance.
+ */
+export class PostgresGameStore {
+    /**
+     * Open a connection pool and begin listening for `game_updates` notifications.
+     *
+     * The pool is capped at 20 connections with a 2s connect timeout and 30s idle
+     * timeout. One extra connection is checked out and held for the lifetime of
+     * the store to service `LISTEN`; call {@link PostgresGameStore.close} to give
+     * it back.
+     *
+     * @param connectionString - Standard `postgres://` DSN passed to `pg.Pool`.
+     * @throws Error if the optional `pg` package is not installed.
+     */
+    constructor(connectionString) {
+        this.listeners = new Map();
+        // Dynamic import to make pg optional
+        try {
+            const { Pool } = require('pg');
+            this.pool = new Pool({
+                connectionString,
+                max: 20,
+                idleTimeoutMillis: 30000,
+                connectionTimeoutMillis: 2000,
+            });
+            // Setup LISTEN for notifications
+            this.setupNotifications();
+        }
+        catch (error) {
+            throw new Error('PostgreSQL adapter requires "pg" package: npm install pg');
+        }
+    }
+    /**
+     * Dedicate a pooled client to `LISTEN game_updates` and fan payloads out to
+     * local watchers. Failures are logged rather than thrown so a database without
+     * the notification trigger still yields a usable store.
+     */
+    async setupNotifications() {
+        try {
+            this.client = await this.pool.connect();
+            await this.client.query('LISTEN game_updates');
+            this.client.on('notification', (msg) => {
+                try {
+                    const payload = JSON.parse(msg.payload);
+                    const callbacks = this.listeners.get(payload.id);
+                    if (callbacks) {
+                        callbacks.forEach((cb) => cb(payload.game));
+                    }
+                }
+                catch (error) {
+                    console.warn('Failed to parse notification:', error);
+                }
+            });
+        }
+        catch (error) {
+            console.warn('Failed to setup notifications:', error);
+        }
+    }
+    /**
+     * Upsert a game via `INSERT ... ON CONFLICT (id) DO UPDATE`.
+     *
+     * `updated_at` is always set to now. `created_at` is only meaningful on the
+     * insert path — the conflict branch deliberately leaves it untouched so the
+     * original creation time survives edits. `synced` defaults to `true` here,
+     * the opposite of the SQLite adapter, because a successful write to the
+     * central database *is* the synced state.
+     *
+     * @param game - Record to persist; a missing `id` is generated locally.
+     * @returns The id reported back by the `RETURNING` clause.
+     */
+    async saveGame(game) {
+        const id = game.id || this.generateId();
+        const now = new Date().toISOString();
+        const query = `
+      INSERT INTO games (
+        id, hpgn, hfen, players, metadata, result, user_id, synced, created_at, updated_at
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+      ON CONFLICT (id) DO UPDATE SET
+        hpgn = $2, hfen = $3, players = $4, metadata = $5,
+        result = $6, synced = $8, updated_at = $10
+      RETURNING id
+    `;
+        const result = await this.pool.query(query, [
+            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 ?? true,
+            game.createdAt || now,
+            now,
+        ]);
+        // Notify listeners
+        if (this.listeners.has(id)) {
+            const updated = await this.loadGame(id);
+            this.listeners.get(id)?.forEach((cb) => cb(updated));
+        }
+        return result.rows[0].id;
+    }
+    /**
+     * Fetch one row by primary key.
+     *
+     * @param id - Game id.
+     * @returns The row mapped back to camelCase {@link GameRecord} shape.
+     * @throws {@link GameNotFoundError} if the query returns no rows.
+     */
+    async loadGame(id) {
+        const result = await this.pool.query('SELECT * FROM games WHERE id = $1', [id]);
+        if (result.rows.length === 0) {
+            throw new GameNotFoundError(id);
+        }
+        return this.rowToRecord(result.rows[0]);
+    }
+    /**
+     * Delete one row and forget any watchers registered for it.
+     *
+     * @param id - Game id.
+     * @throws {@link GameNotFoundError} if the `DELETE` affected no rows.
+     */
+    async deleteGame(id) {
+        const result = await this.pool.query('DELETE FROM games WHERE id = $1', [id]);
+        if (result.rowCount === 0) {
+            throw new GameNotFoundError(id);
+        }
+        this.listeners.delete(id);
+    }
+    /**
+     * List games with SQL-side filtering, ordering and pagination.
+     *
+     * Filters are appended as parameterised predicates, never string-interpolated.
+     * Ordering is by `created_at` and defaults to descending — the reverse of the
+     * memory adapter's default.
+     *
+     * @param options - `userId`/`result` filters, `sort` direction, `limit` and
+     *   `offset`. An `offset` without a `limit` is passed through to Postgres,
+     *   which permits it.
+     * @returns Matching rows in the requested order.
+     */
+    async listGames(options) {
+        let query = 'SELECT * FROM games WHERE 1=1';
+        const params = [];
+        let paramCount = 1;
+        if (options?.userId) {
+            query += ` AND user_id = $${paramCount}`;
+            params.push(options.userId);
+            paramCount++;
+        }
+        if (options?.result) {
+            query += ` AND result = $${paramCount}`;
+            params.push(options.result);
+            paramCount++;
+        }
+        query += ` ORDER BY created_at ${options?.sort === 'asc' ? 'ASC' : 'DESC'}`;
+        if (options?.limit) {
+            query += ` LIMIT $${paramCount}`;
+            params.push(options.limit);
+            paramCount++;
+        }
+        if (options?.offset) {
+            query += ` OFFSET $${paramCount}`;
+            params.push(options.offset);
+        }
+        const result = await this.pool.query(query, params);
+        return result.rows.map((row) => this.rowToRecord(row));
+    }
+    /**
+     * Count matching rows with `COUNT(*)`, ignoring `limit`/`offset`.
+     *
+     * Postgres returns `count` as a bigint string, so the result is parsed to a
+     * number before being handed back.
+     *
+     * @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 = $1`;
+            params.push(options.userId);
+        }
+        if (options?.result) {
+            query += ` AND result = $${params.length + 1}`;
+            params.push(options.result);
+        }
+        const result = await this.pool.query(query, params);
+        return parseInt(result.rows[0].count, 10);
+    }
+    /**
+     * Subscribe to changes for one game.
+     *
+     * Two paths feed the callback: writes made through this instance notify
+     * directly, and writes made by other processes arrive over the `game_updates`
+     * `LISTEN` channel — the latter only if the database publishes them. Watching
+     * is purely local bookkeeping and issues no query, so it is cheap.
+     *
+     * @param id - Game id to observe.
+     * @param callback - Receives the updated record.
+     * @returns Unsubscribe handle.
+     */
+    watch(id, callback) {
+        if (!this.listeners.has(id)) {
+            this.listeners.set(id, new Set());
+        }
+        this.listeners.get(id).add(callback);
+        return () => {
+            const callbacks = this.listeners.get(id);
+            if (callbacks) {
+                callbacks.delete(callback);
+                if (callbacks.size === 0) {
+                    this.listeners.delete(id);
+                }
+            }
+        };
+    }
+    /**
+     * Probe the pool with `SELECT 1`.
+     *
+     * Confirms connectivity only — it does not verify that the `games` table
+     * exists or is readable.
+     *
+     * @returns `false` instead of throwing if the query fails.
+     */
+    async isHealthy() {
+        try {
+            await this.pool.query('SELECT 1');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Read every row, newest first, in a single unpaginated query.
+     *
+     * Materialises the whole table in memory — fine for backups, unsuitable for
+     * very large datasets.
+     *
+     * @returns All stored games.
+     */
+    async exportAll() {
+        const result = await this.pool.query('SELECT * FROM games ORDER BY created_at DESC');
+        return result.rows.map((row) => this.rowToRecord(row));
+    }
+    /**
+     * Upsert a batch of games one statement at a time.
+     *
+     * Not wrapped in a transaction: a row that fails is logged and skipped, so a
+     * partial import is a possible outcome.
+     *
+     * @param games - Records to import.
+     * @returns How many were saved 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 in the `games` table and drop all local watchers.
+     *
+     * @returns Number of rows deleted.
+     */
+    async clear() {
+        const result = await this.pool.query('DELETE FROM games');
+        this.listeners.clear();
+        return result.rowCount;
+    }
+    /**
+     * Map a snake_case database row to a {@link GameRecord}, parsing the JSON
+     * columns and rendering `timestamptz` values 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?.toISOString(),
+            updatedAt: row.updated_at?.toISOString(),
+        };
+    }
+    generateId() {
+        return `game_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * Release the `LISTEN` client and drain the pool.
+     *
+     * Must be called for the process to exit cleanly — the held notification
+     * client keeps an open socket that would otherwise pin the event loop. The
+     * store is unusable afterwards.
+     */
+    async close() {
+        if (this.client) {
+            await this.client.release();
+        }
+        await this.pool.end();
+    }
+}
+//# sourceMappingURL=postgres.js.map

package/dist/adapters/postgres.js.map

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

package/dist/adapters/sqlite.d.ts

@@ -0,0 +1,186 @@
+import { GameStore } from '../types/game-store';
+import { GameRecord, GameQueryOptions, Unsubscribe } 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 declare class SqliteGameStore implements GameStore {
+    private db;
+    private watchers;
+    private pollIntervals;
+    /**
+     * 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: string);
+    /**
+     * Create the `games` table and its lookup indexes if they are missing.
+     * Idempotent, so it runs unconditionally on every open.
+     */
+    private initSchema;
+    /**
+     * 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.
+     */
+    saveGame(game: GameRecord): Promise<string>;
+    /**
+     * 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.
+     */
+    loadGame(id: string): Promise<GameRecord>;
+    /**
+     * 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.
+     */
+    deleteGame(id: string): Promise<void>;
+    /**
+     * 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.
+     */
+    listGames(options?: GameQueryOptions): Promise<GameRecord[]>;
+    /**
+     * Count matching rows with `COUNT(*)`, ignoring `limit`/`offset`.
+     *
+     * @param options - Only `userId` and `result` are honoured.
+     * @returns Total number of matching rows.
+     */
+    countGames(options?: GameQueryOptions): Promise<number>;
+    /**
+     * 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: string, callback: (game: GameRecord) => void): Unsubscribe;
+    /**
+     * Clear the poll interval for an id and forget its callbacks. Safe to call
+     * for an id that is not being watched.
+     */
+    private stopWatching;
+    /**
+     * Probe the open database handle with `SELECT 1`.
+     *
+     * @returns `false` instead of throwing if the handle is closed or the file is
+     *   unreadable.
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * 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.
+     */
+    getSyncQueue(): Promise<GameRecord[]>;
+    /**
+     * 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.
+     */
+    markSynced(id: string): Promise<void>;
+    /**
+     * 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.
+     */
+    clearSyncQueue(): Promise<void>;
+    /**
+     * Read every row, newest first, in one unpaginated query.
+     *
+     * @returns All stored games.
+     */
+    exportAll(): Promise<GameRecord[]>;
+    /**
+     * 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.
+     */
+    importGames(games: GameRecord[]): Promise<number>;
+    /**
+     * Delete every row and stop all polling watchers.
+     *
+     * The table and indexes survive; only the data is removed.
+     *
+     * @returns Number of rows deleted.
+     */
+    clear(): Promise<number>;
+    /**
+     * 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.
+     */
+    private rowToRecord;
+    private generateId;
+    /**
+     * 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(): void;
+}
+//# sourceMappingURL=sqlite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/adapters/sqlite.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAqB,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,eAAgB,YAAW,SAAS;IAC/C,OAAO,CAAC,EAAE,CAAM;IAChB,OAAO,CAAC,QAAQ,CAA2D;IAC3E,OAAO,CAAC,aAAa,CAA+B;IAEpD;;;;;;;;;;;OAWG;gBACS,MAAM,EAAE,MAAM;IAe1B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAqBlB;;;;;;;;;OASG;IACG,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IA8BjD;;;;;;;OAOG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAW/C;;;;;OAKG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3C;;;;;;;;;OASG;IACG,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAgClE;;;;;OAKG;IACG,UAAU,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAoB7D;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,WAAW;IAgCpE;;;OAGG;IACH,OAAO,CAAC,YAAY;IASpB;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAWnC;;;;;;;OAOG;IACG,YAAY,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAK3C;;;;;;;OAOG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK3C;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrC;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAKxC;;;;;;;;;OASG;IACG,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAevD;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAS9B;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,UAAU;IAIlB;;;;;OAKG;IACH,KAAK,IAAI,IAAI;CAMd"}