t3core 1.1.1 → 1.1.2

package/dist/src/core/Board.d.ts

@@ -2,13 +2,16 @@ import type { IBoard } from "./types/Board";
 import type { PlayerSymbol } from "./types/Symbol";
 export declare const BOARD_SIZE = 9;
 export declare class Board implements IBoard {
-    private fields;
+    private _fields;
+    private _snapshot;
     /**
-     * Returns the current board state.
-     * @returns The current board state.
-     * @type {number[] | PlayerSymbol[]}
+     * Returns a stable snapshot of the current board state.
+     * The same array reference is returned on repeated calls until a field is
+     * mutated or the board is reset, making it safe for referential-equality
+     * checks (e.g. `useSyncExternalStore`).
+     * @returns A cached shallow copy of the board fields.
      */
-    getFields(): (number | "O" | "X")[];
+    get fields(): (number | "O" | "X")[];
     /**
      * Returns the value of a field by its number.
      * @param fieldNumber The field number (1-9) to get.
@@ -31,6 +34,7 @@ export declare class Board implements IBoard {
     isFull(): boolean;
     /**
      * Sets a field's value by its number.
+     * Invalidates the cached snapshot so the next `fields` access returns a new reference.
      * @param fieldNumber The field number (1-9) to set.
      * @param symbol The symbol to set.
      * @deprecated Use `setFieldByIndex` instead.
@@ -38,12 +42,14 @@ export declare class Board implements IBoard {
     setFieldByNumber(fieldNumber: number, symbol: PlayerSymbol): void;
     /**
      * Sets a field's value by its index.
+     * Invalidates the cached snapshot so the next `fields` access returns a new reference.
      * @param index The index of the field to set.
      * @param symbol The symbol to set.
      */
     setFieldByIndex(index: number, symbol: PlayerSymbol): void;
     /**
      * Resets the board to its initial state.
+     * Invalidates the cached snapshot so the next `fields` access returns a new reference.
      */
     reset(): void;
 }

package/dist/src/core/Board.js

@@ -5,17 +5,23 @@ const fillFields = (_, idx) => idx + 1;
 exports.BOARD_SIZE = 9;
 class Board {
     constructor() {
-        this.fields = new Array(exports.BOARD_SIZE)
+        this._fields = new Array(exports.BOARD_SIZE)
             .fill(0)
             .map(fillFields);
+        this._snapshot = null;
     }
     /**
-     * Returns the current board state.
-     * @returns The current board state.
-     * @type {number[] | PlayerSymbol[]}
+     * Returns a stable snapshot of the current board state.
+     * The same array reference is returned on repeated calls until a field is
+     * mutated or the board is reset, making it safe for referential-equality
+     * checks (e.g. `useSyncExternalStore`).
+     * @returns A cached shallow copy of the board fields.
      */
-    getFields() {
-        return [...this.fields];
+    get fields() {
+        if (!this._snapshot) {
+            this._snapshot = [...this._fields];
+        }
+        return this._snapshot;
     }
     /**
      * Returns the value of a field by its number.
@@ -25,7 +31,7 @@ class Board {
      * @deprecated Use `getFieldByIndex` instead.
      */
     getFieldByNumber(fieldNumber) {
-        return this.fields[fieldNumber - 1];
+        return this._fields[fieldNumber - 1];
     }
     /**
      * Returns the value of a field by its index.
@@ -34,37 +40,43 @@ class Board {
      * @type {number | TSymbol}
      */
     getFieldByIndex(index) {
-        return this.fields[index];
+        return this._fields[index];
     }
     /**
      * Checks if the board is full.
      * @returns `true` if the board is full, `false` otherwise.
      */
     isFull() {
-        return this.fields.every((field) => typeof field === "string");
+        return this._fields.every((field) => typeof field === "string");
     }
     /**
      * Sets a field's value by its number.
+     * Invalidates the cached snapshot so the next `fields` access returns a new reference.
      * @param fieldNumber The field number (1-9) to set.
      * @param symbol The symbol to set.
      * @deprecated Use `setFieldByIndex` instead.
      */
     setFieldByNumber(fieldNumber, symbol) {
-        this.fields[fieldNumber - 1] = symbol;
+        this._fields[fieldNumber - 1] = symbol;
+        this._snapshot = null;
     }
     /**
      * Sets a field's value by its index.
+     * Invalidates the cached snapshot so the next `fields` access returns a new reference.
      * @param index The index of the field to set.
      * @param symbol The symbol to set.
      */
     setFieldByIndex(index, symbol) {
-        this.fields[index] = symbol;
+        this._fields[index] = symbol;
+        this._snapshot = null;
     }
     /**
      * Resets the board to its initial state.
+     * Invalidates the cached snapshot so the next `fields` access returns a new reference.
      */
     reset() {
-        this.fields = new Array(exports.BOARD_SIZE).fill(0).map(fillFields);
+        this._fields = new Array(exports.BOARD_SIZE).fill(0).map(fillFields);
+        this._snapshot = null;
     }
 }
 exports.Board = Board;

package/dist/src/core/Game.d.ts

@@ -1,13 +1,20 @@
 import type { PlayerSymbol } from "./types/Symbol";
-import { type EventEmitHandler, type GameEventMap, type GameStatus, type IGame } from "./types/Game";
+import { type GameEventMap, type GameEventPayload, type GameStatus, type IGame } from "./types/Game";
 export declare class Game implements IGame {
     private _currentPlayer;
     private _gameStatus;
     private _symbols;
     private _board;
     private _emitter;
+    private _snapshot;
     private _togglePlayer;
     private _updateGameStatus;
+    /**
+     * Returns a stable snapshot of the current game state.
+     * The same object reference is returned between moves, making it safe
+     * as a `getSnapshot` argument for `useSyncExternalStore`.
+     */
+    get snapshot(): GameEventPayload;
     /**
      * Returns the current player.
      * @returns The current player.
@@ -31,14 +38,14 @@ export declare class Game implements IGame {
      * @param fn The function to call when the event is emitted.
      * @returns This Game instance for method chaining.
      */
-    on<K extends keyof GameEventMap>({ event, fn }: EventEmitHandler<K>): this;
+    on<K extends keyof GameEventMap>(event: K, fn: (...args: GameEventMap[K]) => void): this;
     /**
      * Removes an event listener for the specified event.
      * @param event The event to remove the listener from.
      * @param fn The function to remove.
      * @returns This Game instance for method chaining.
      */
-    off<K extends keyof GameEventMap>({ event, fn }: EventEmitHandler<K>): this;
+    off<K extends keyof GameEventMap>(event: K, fn: (...args: GameEventMap[K]) => void): this;
     /**
      * Returns the current board state.
      * @returns The current board state.

package/dist/src/core/Game.js

@@ -16,6 +16,11 @@ class Game {
         this._symbols = constants_1.DEFAULT_GAME_SYMBOLS;
         this._board = new Board_1.Board();
         this._emitter = new eventemitter3_1.default();
+        this._snapshot = {
+            board: this._board.fields,
+            currentPlayer: this._currentPlayer,
+            gameStatus: this._gameStatus,
+        };
     }
     _togglePlayer() {
         this._currentPlayer =
@@ -25,7 +30,7 @@ class Game {
     }
     _updateGameStatus() {
         const board = this._board;
-        const winner = (0, getWinnerFromFields_1.getWinnerFromFields)(board.getFields());
+        const winner = (0, getWinnerFromFields_1.getWinnerFromFields)(board.fields);
         const isDraw = board.isFull() && !winner;
         if (winner) {
             this._gameStatus = { status: "win", winner };
@@ -37,6 +42,14 @@ class Game {
         }
         this._gameStatus = { status: "running" };
     }
+    /**
+     * Returns a stable snapshot of the current game state.
+     * The same object reference is returned between moves, making it safe
+     * as a `getSnapshot` argument for `useSyncExternalStore`.
+     */
+    get snapshot() {
+        return this._snapshot;
+    }
     /**
      * Returns the current player.
      * @returns The current player.
@@ -58,7 +71,7 @@ class Game {
      * @type {(number | PlayerSymbol)[]}
      */
     get board() {
-        return this._board.getFields();
+        return this._board.fields;
     }
     /**
      * Registers an event listener for the specified event.
@@ -66,7 +79,7 @@ class Game {
      * @param fn The function to call when the event is emitted.
      * @returns This Game instance for method chaining.
      */
-    on({ event, fn }) {
+    on(event, fn) {
         this._emitter.on(event, fn);
         return this;
     }
@@ -76,7 +89,7 @@ class Game {
      * @param fn The function to remove.
      * @returns This Game instance for method chaining.
      */
-    off({ event, fn }) {
+    off(event, fn) {
         this._emitter.off(event, fn);
         return this;
     }
@@ -87,7 +100,7 @@ class Game {
      * @deprecated Use `board` instead.
      */
     getBoard() {
-        return this._board.getFields();
+        return this._board.fields;
     }
     /**
      * Checks if a field is already selected by a player.
@@ -133,12 +146,12 @@ class Game {
         this._board.setFieldByIndex(index, this._currentPlayer);
         this._togglePlayer();
         this._updateGameStatus();
-        this._emitter.emit(Game_1.GameEvent.PLAYER_MOVE, {
-            index,
-            board: this._board.getFields(),
+        this._snapshot = {
+            board: this._board.fields,
             currentPlayer: this._currentPlayer,
             gameStatus: this._gameStatus,
-        });
+        };
+        this._emitter.emit(Game_1.GameEvent.PLAYER_MOVE, Object.assign({ index }, this._snapshot));
         return Game_1.PlayerMoveStatus.SUCCESS;
     }
     /**
@@ -149,11 +162,12 @@ class Game {
         this._gameStatus = { status: "running" };
         this._currentPlayer = this._symbols[0];
         this._board.reset();
-        this._emitter.emit(Game_1.GameEvent.RESET, {
-            board: this._board.getFields(),
+        this._snapshot = {
+            board: this._board.fields,
             currentPlayer: this._currentPlayer,
             gameStatus: this._gameStatus,
-        });
+        };
+        this._emitter.emit(Game_1.GameEvent.RESET, this._snapshot);
     }
 }
 exports.Game = Game;

package/dist/src/core/tests/gameCore.test.js

@@ -52,7 +52,7 @@ const Game_2 = require("../types/Game");
 (0, vitest_1.test)("PLAYER_MOVE event fires with correct payload on savePlayerMove", () => {
     const game = new Game_1.Game();
     const listener = vitest_1.vi.fn();
-    game.on({ event: Game_2.GameEvent.PLAYER_MOVE, fn: listener });
+    game.on(Game_2.GameEvent.PLAYER_MOVE, listener);
     game.savePlayerMove(4);
     (0, vitest_1.expect)(listener).toHaveBeenCalledOnce();
     const payload = listener.mock.calls[0][0];
@@ -66,7 +66,7 @@ const Game_2 = require("../types/Game");
     game.savePlayerMove(0);
     game.savePlayerMove(1);
     const listener = vitest_1.vi.fn();
-    game.on({ event: Game_2.GameEvent.RESET, fn: listener });
+    game.on(Game_2.GameEvent.RESET, listener);
     game.reset();
     (0, vitest_1.expect)(listener).toHaveBeenCalledOnce();
     const payload = listener.mock.calls[0][0];
@@ -78,7 +78,7 @@ const Game_2 = require("../types/Game");
     const game = new Game_1.Game();
     game.savePlayerMove(0);
     const listener = vitest_1.vi.fn();
-    game.on({ event: Game_2.GameEvent.PLAYER_MOVE, fn: listener });
+    game.on(Game_2.GameEvent.PLAYER_MOVE, listener);
     game.savePlayerMove(0);
     (0, vitest_1.expect)(listener).not.toHaveBeenCalled();
 });

package/dist/src/core/types/Board.d.ts

@@ -1,9 +1,8 @@
 import type { PlayerSymbol } from "./Symbol";
 export interface IBoard {
-    /** Cell value for field **1–9** (grid label shown to the player). */
+    fields: (number | PlayerSymbol)[];
     getFieldByNumber: (fieldNumber: number) => number | PlayerSymbol;
     setFieldByNumber: (fieldNumber: number, symbol: PlayerSymbol) => void;
-    getFields: () => (number | PlayerSymbol)[];
     isFull: () => boolean;
     reset: () => void;
 }

package/dist/src/core/types/Game.d.ts

@@ -32,14 +32,11 @@ export type GameEventMap = {
     }];
     [GameEvent.RESET]: [payload: GameEventPayload];
 };
-export type EventEmitHandler<K extends keyof GameEventMap> = {
-    event: K;
-    fn: (...args: GameEventMap[K]) => void;
-};
-export type EventEmit = <K extends keyof GameEventMap>(emitter: EventEmitHandler<K>) => void;
+export type EventEmit = <K extends keyof GameEventMap>(event: K, fn: (...args: GameEventMap[K]) => void) => void;
 export interface IGame {
     on: EventEmit;
     off: EventEmit;
+    readonly snapshot: GameEventPayload;
     readonly gameStatus: GameStatus;
     readonly currentPlayer: PlayerSymbol;
     savePlayerSelection: (field: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "t3core",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "tic tac toe core - tttc - t3c",
   "main": "dist/index.js",
   "scripts": {