move-by-move 1.0.6 → 2.0.0

package/README.md

@@ -0,0 +1,123 @@
+# move-by-move
+
+A simple, dependency-free game engine for turn-based games.
+
+`move-by-move` gives you a tiny state container in the spirit of Redux, but built around **rules** instead of reducers. Every move runs through a pipeline of rules, each of which sees both the action and the current state and can transform either. This makes it natural to express turn-based game logic — validation, the move itself, win checks, turn switching — as a sequence of small, composable steps.
+
+## Installation
+
+```bash
+npm install move-by-move
+```
+
+## Quick start
+
+```ts
+import createGame from 'move-by-move'
+
+type State = { count: number }
+
+const game = createGame<State>(
+  [
+    // each rule receives [action, state] and returns [action, state]
+    ([action, state]) => {
+      if (action.type === 'INCREMENT') {
+        return [action, { count: state.count + action.by }]
+      }
+      return [action, state]
+    },
+  ],
+  { count: 0 }, // initial state
+)
+
+const unsubscribe = game.subscribe(() => console.log('state:', game.getState()))
+
+game.move({ type: 'INCREMENT', by: 1 }) // logs: state: { count: 1 }
+game.move({ type: 'INCREMENT', by: 5 }) // logs: state: { count: 6 }
+
+unsubscribe() // stop listening
+```
+
+## Core concept: rules
+
+A **rule** is a function over a `[action, state]` tuple:
+
+```ts
+type RuleIO<State> = [action: GameAction, state: State]
+type Rule<State> = (input: RuleIO<State>) => RuleIO<State>
+```
+
+When you call `game.move(action)`, the engine pipes `[action, state]` through every rule **in order** and uses the resulting state as the new state:
+
+```
+[action, state] → rule1 → rule2 → rule3 → [action, newState]
+                                              └── becomes the new state
+```
+
+Because each rule receives both the action and the (possibly already-transformed) state, rules can:
+
+- **transform state** based on the action,
+- **ignore** actions they don't care about (just return the input unchanged),
+- **rewrite the action** for downstream rules,
+- **run unconditionally**, e.g. a rule that switches the active player or checks for a winner after every move.
+
+Order matters — a validation rule should run before the rule that applies the move, and a "check for win" rule should run after it.
+
+### Example: composing rules
+
+```ts
+import createGame from 'move-by-move'
+
+type State = {
+  board: (string | null)[]
+  turn: 'X' | 'O'
+  winner: string | null
+}
+
+const placeMark = ([action, state]: RuleIO<State>): RuleIO<State> => {
+  if (action.type !== 'PLACE' || state.winner) return [action, state]
+  if (state.board[action.index] !== null) return [action, state] // square taken
+  const board = [...state.board]
+  board[action.index] = state.turn
+  return [action, { ...state, board }]
+}
+
+const switchTurn = ([action, state]: RuleIO<State>): RuleIO<State> => {
+  if (action.type !== 'PLACE' || state.winner) return [action, state]
+  return [action, { ...state, turn: state.turn === 'X' ? 'O' : 'X' }]
+}
+
+const game = createGame<State>(
+  [placeMark, switchTurn],
+  { board: Array(9).fill(null), turn: 'X', winner: null },
+)
+```
+
+## API
+
+### `createGame<State>(rules, initialState): Game<State>`
+
+Creates a new game instance.
+
+- `rules` — an array of rule functions, applied in order on every move.
+- `initialState` — the starting state.
+
+### `Game<State>`
+
+| Method | Description |
+| --- | --- |
+| `getState(): State` | Returns the current state. |
+| `move(action: GameAction): void` | Runs `action` through the rule pipeline, updates state, and notifies subscribers. |
+| `subscribe(listener: Function): () => void` | Registers a listener called (with no arguments) after every move. Use `getState()` inside it to read the new state. Returns an unsubscribe function — call it to remove the listener. |
+
+### `GameAction<Payload>`
+
+An action is any payload object with a required `type` string:
+
+```ts
+type GameAction<Payload = any> = Payload & { type: string }
+```
+
+## License
+
+MIT © Andreas Riedmüller

package/lib/index.d.ts

@@ -2,8 +2,7 @@ export declare type GameAction<Payload = any> = Payload & {
     type: string;
 };
 export interface Game<Type> {
-    subscribe(listener: Function): void;
-    unsubscribe(listener: Function): void;
+    subscribe(listener: Function): () => void;
     getState(): Type;
     move(action: GameAction): void;
 }

package/lib/index.js

@@ -4,12 +4,13 @@ const helpers_1 = require("./helpers");
 function createGame(rules, initialGameState) {
     let listeners = [];
     let state = initialGameState;
-    const subscribe = (listener) => {
-        listeners = [...listeners, listener];
-    };
     const unsubscribe = (listener) => {
         listeners = listeners.filter(item => item !== listener);
     };
+    const subscribe = (listener) => {
+        listeners = [...listeners, listener];
+        return () => unsubscribe(listener);
+    };
     const getState = () => {
         return state;
     };
@@ -22,7 +23,6 @@ function createGame(rules, initialGameState) {
     };
     return {
         subscribe,
-        unsubscribe,
         getState,
         move,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "move-by-move",
-  "version": "1.0.6",
+  "version": "2.0.0",
   "description": "Simple game engine for turn based games",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",