move-by-move 3.0.0 → 4.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+`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 reads the current state and the action and produces the next state. 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
 
@@ -16,15 +16,16 @@ npm install move-by-move
 import createGame from 'move-by-move'
 
 type State = { count: number }
+type Action = { type: 'INCREMENT'; by: number }
 
-const game = createGame<State>(
+const game = createGame<State, Action>(
   [
-    // each rule receives [action, state] and returns [action, state]
-    ([action, state]) => {
+    // each rule receives [state, action, context] and returns [state, action, context]
+    ([state, action, context]) => {
       if (action.type === 'INCREMENT') {
-        return [action, { count: state.count + action.by }]
+        return [{ count: state.count + action.by }, action, context]
       }
-      return [action, state]
+      return [state, action, context]
     },
   ],
   { count: 0 }, // initial state
@@ -38,35 +39,46 @@ game.move({ type: 'INCREMENT', by: 5 }) // logs: state: { count: 6 }
 unsubscribe() // stop listening
 ```
 
+> The Quick start writes rules by hand to show the raw `[state, action, context]` contract. In a real game you'll usually reach for **`createRule`**, which lets you mutate state directly (via [immer](https://immerjs.github.io/immer/)) and run a rule only for a chosen action type — see [below](#authoring-rules-with-createrule). The third tuple slot, `context`, is a scratch bag shared by *every* rule — raw or `createRule` — for [passing information downstream](#context-sharing-data-between-rules); this example just threads it through untouched.
+
 ## Core concept: rules
 
-A **rule** is a function over a `[action, state]` tuple:
+A **rule** is a function over a `[state, action, context]` tuple:
 
 ```ts
-type RuleIO<State> = [action: GameAction, state: State]
-type Rule<State> = (input: RuleIO<State>) => RuleIO<State>
+type RuleIO<State, Action extends GameAction> = [state: State, action: Action, context: Record<string, unknown>]
+type Rule<State, Action extends GameAction> = (input: RuleIO<Immutable<State>, Immutable<Action>>) => RuleIO<State, Action>
 ```
 
-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:
+The `state` and `action` a rule **receives** are deeply read-only (`Immutable<…>`) for *every* rule — not just `createRule` ones. You read them freely, but mutating either is a compile error. To evolve state, return a new one (or mutate the draft inside `createRule`); to pass information downstream, write to `context`. This is a compile-time guard only, so it adds zero runtime cost.
+
+When you call `game.move(action)`, the engine pipes `[state, action, context]` 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
+[state, action, context] → rule1 → rule2 → rule3 → [newState, action, context]
+                                                     └── becomes the new state
 ```
 
-Because each rule receives both the action and the (possibly already-transformed) state, rules can:
+(`context` starts as a fresh, empty object on every move and is discarded once the move finishes — see [Context](#context-sharing-data-between-rules).)
+
+Because each rule receives the (possibly already-transformed) state, the action, and a shared context, 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,
+- **share information** with later rules through the `context` bag,
 - **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
+### Authoring rules with `createRule`
+
+Writing `[state, action, context]` tuples by hand gets verbose, and hand-rolled immutable updates (`{ ...state, board }`) are easy to get wrong. `createRule` lets you **mutate a draft** of the state with [immer](https://immerjs.github.io/immer/) — the engine turns your mutations into a new immutable state for you.
+
+`move-by-move` stays dependency-free and doesn't ship immer, so you inject your own `produce` once — binding your game's `State` and `Action` union at the same time:
 
 ```ts
-import createGame from 'move-by-move'
+import createGame, { createRuleFactory } from 'move-by-move'
+import { produce } from 'immer'
 
 type State = {
   board: (string | null)[]
@@ -74,50 +86,121 @@ type State = {
   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 }]
-}
+type Action =
+  | { type: 'PLACE'; index: number }
+  | { type: 'GIVE_UP' }
 
-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 createRule = createRuleFactory<State, Action>(produce)
+```
 
-const game = createGame<State>(
-  [placeMark, switchTurn],
+A recipe receives `(state, action, context)`:
+
+- `state` — a **mutable draft**; mutate it directly, no spreading.
+- `action` — the action being processed, **read-only**.
+- `context` — a mutable bag **shared by every rule in this move** (see below).
+
+Pass an action **type** as the first argument to run the rule only for that action — `action` is then narrowed to the matching member of your `Action` union, so its payload is fully typed (and passing a type your union doesn't include is a compile error). Omit it to run on every action, where `action` is the full union. Here's tic-tac-toe:
+
+```ts
+const placeMark = createRule('PLACE', (state, action, context) => {
+  if (state.winner) return
+  if (state.board[action.index] !== null) return // square already taken
+  state.board[action.index] = state.turn          // narrowed to PLACE, so action.index is typed
+  context.placed = true // tell downstream rules the move was accepted
+})
+
+const switchTurn = createRule('PLACE', (state, action, context) => {
+  if (!context.placed) return // only switch when placeMark accepted the move
+  state.turn = state.turn === 'X' ? 'O' : 'X'
+})
+
+// Handles the other action; the current player resigns and their opponent wins.
+const giveUp = createRule('GIVE_UP', (state) => {
+  if (state.winner) return
+  state.winner = state.turn === 'X' ? 'O' : 'X'
+})
+
+const game = createGame<State, Action>(
+  [placeMark, switchTurn, giveUp],
   { board: Array(9).fill(null), turn: 'X', winner: null },
 )
 ```
 
+For brevity `placeMark` omits win detection: a complete game adds a rule after it that checks the board and sets `state.winner` — which is what `placeMark`'s early `return` guards against.
+
+## Context: sharing data between rules
+
+Rules run one after another, and a later rule often needs to know what an earlier one decided. Above, both rules already fire only for `PLACE` actions, but `placeMark` does extra validation (no winner yet, square empty) before making the move. `switchTurn` should only swap the active player **when a mark was actually placed** — otherwise an invalid `PLACE` would still pass the turn.
+
+Without a shared channel, `switchTurn` would have to *repeat* every check `placeMark` already did — duplicated logic that drifts out of sync the moment a rule changes. `context` solves this: `placeMark` records its decision with `context.placed = true`, and `switchTurn` just reads it.
+
+**Why not put this on `state` or the `action`?**
+
+- `state` is your persistent game state — you don't want transient bookkeeping like "was this move valid?" leaking into it (and into your subscribers).
+- the `action` is read-only, by design.
+
+So `context` is a separate, mutable scratch space with a clear lifetime:
+
+- It's created **fresh (`{}`) at the start of every `move()`**, threaded through all rules, and **discarded** when the move ends. It never persists across moves.
+- It's a plain object — read it, write it, mutate it freely. (Unlike `state`, it is *not* an immer draft.)
+- It's typed as `Record<string, unknown>`: writing any value is fine, and reads come back as `unknown`, so narrow or cast when you need a specific type. (Truthiness checks like `if (context.placed)` work directly.)
+
 ## API
 
-### `createGame<State>(rules, initialState): Game<State>`
+### `createGame<State, Action>(rules, initialState): Game<State, Action>`
 
 Creates a new game instance.
 
+- `State` — your game state.
+- `Action` — your action union (a discriminated union on `type`); this types `move()` and the action each rule sees.
 - `rules` — an array of rule functions, applied in order on every move.
 - `initialState` — the starting state.
 
-### `Game<State>`
+### `createRuleFactory<State, Action>(produce)`
+
+Binds immer's `produce` (which you supply — `move-by-move` is dependency-free) plus your game's types, and returns a `createRule` helper:
+
+```ts
+import { produce } from 'immer'
+import { createRuleFactory } from 'move-by-move'
+
+const createRule = createRuleFactory<State, Action>(produce)
+```
+
+- `State` — your game state.
+- `Action` — your action union (a discriminated union on `type`). Enables payload narrowing on `action` and rejects unknown types passed to the `createRule(type, …)` form.
+
+`createRule` has two forms, both returning a `Rule<State, Action>`:
+
+| Call | Runs | `action` type |
+| --- | --- | --- |
+| `createRule(recipe)` | on every action | the full `Action` union |
+| `createRule(type, recipe)` | only when `action.type === type` | narrowed to that member |
+
+A recipe is `(state, action, context) => void`: `state` is a mutable immer draft (your mutations become the next immutable state), `action` is the read-only action (narrowed to the matching member in the `createRule(type, …)` form), and `context` is the per-move shared bag. To pass information to later rules, write to `context` (see [Context](#context-sharing-data-between-rules)).
+
+### `Immutable<T>`
+
+A recursive `readonly` helper used to type the `state` and `action` a rule receives (and the read-only `action` a `createRule` recipe sees). It's a **compile-time guard only** — nothing is frozen at runtime, so there's no performance cost. Reading is unrestricted; mutating is a compile error, which keeps state transitions explicit (return a new state, or mutate a `createRule` draft) and steers rule-to-rule communication through `context`.
+
+### `Game<State, Action>`
 
 | Method | Description |
 | --- | --- |
 | `getState(): State` | Returns the current state. |
-| `move(action: GameAction): void` | Runs `action` through the rule pipeline, updates state, and notifies subscribers. |
+| `move(action: Action): 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>`
+### `GameAction`
 
-An action is any payload object with a required `type` string:
+The base constraint every action satisfies — an object with a required `type` string:
 
 ```ts
-type GameAction<Payload = any> = Payload & { type: string }
+type GameAction = { type: string }
 ```
 
+Your own `Action` union must extend it (each member carrying a `type`). It's the upper bound on the `Action` generic throughout the API.
+
 ## License
 
 MIT © Andreas Riedmüller

package/lib/index.d.ts

@@ -1,10 +1,21 @@
-export type GameAction<Payload = any> = Payload & {
+export type Immutable<T> = 0 extends 1 & T ? T : T extends readonly (infer E)[] ? readonly Immutable<E>[] : T extends object ? {
+    readonly [K in keyof T]: Immutable<T[K]>;
+} : T;
+export type GameAction = {
     type: string;
 };
-export interface Game<Type> {
+export interface Game<State, Action extends GameAction> {
     subscribe(listener: Function): () => void;
-    getState(): Type;
-    move(action: GameAction): void;
+    getState(): State;
+    move(action: Action): void;
 }
-export type RuleIO<Type> = [action: GameAction, state: Type];
-export default function createGame<Type>(rules: Array<(input: RuleIO<Type>) => RuleIO<Type>>, initialGameState: Type): Game<Type>;
+export type RuleIO<State, Action extends GameAction> = [state: State, action: Action, context: Record<string, unknown>];
+export type Rule<State, Action extends GameAction> = (input: RuleIO<Immutable<State>, Immutable<Action>>) => RuleIO<State, Action>;
+export type Produce = <S>(base: S, recipe: (draft: S) => void) => S;
+export declare function createRuleFactory<State, Action extends GameAction>(produce: Produce): {
+    (recipe: (state: State, action: Immutable<Action>, context: Record<string, unknown>) => void): Rule<State, Action>;
+    <Type extends Action["type"]>(type: Type, recipe: (state: State, action: Immutable<Extract<Action, {
+        type: Type;
+    }>>, context: Record<string, unknown>) => void): Rule<State, Action>;
+};
+export default function createGame<State, Action extends GameAction>(rules: Array<Rule<State, Action>>, initialGameState: State): Game<State, Action>;

package/lib/index.js

@@ -1,4 +1,20 @@
 import { pipe } from './helpers.js';
+export function createRuleFactory(produce) {
+    function createRule(typeOrRecipe, maybeRecipe) {
+        const type = typeof typeOrRecipe === 'string' ? typeOrRecipe : undefined;
+        const recipe = typeof typeOrRecipe === 'string' ? maybeRecipe : typeOrRecipe;
+        return ([state, action, context]) => {
+            if (type !== undefined && action.type !== type) {
+                return [state, action, context];
+            }
+            const nextState = produce(state, (draft) => {
+                recipe(draft, action, context);
+            });
+            return [nextState, action, context];
+        };
+    }
+    return createRule;
+}
 export default function createGame(rules, initialGameState) {
     let listeners = [];
     let state = initialGameState;
@@ -13,8 +29,8 @@ export default function createGame(rules, initialGameState) {
         return state;
     };
     const move = (action) => {
-        const result = pipe(...rules)([action, state]);
-        state = result[1];
+        const result = pipe(...rules)([state, action, {}]);
+        state = result[0];
         for (const listener of listeners) {
             listener();
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "move-by-move",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Simple game engine for turn based games",
   "type": "module",
   "main": "lib/index.js",
@@ -16,9 +16,9 @@
     "lib"
   ],
   "scripts": {
-    "prepare": "npm run build",
-    "build": "tsc",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "prepare": "npm run test && npm run build",
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "npm run build && tsc -p tsconfig.test.json --noEmit && node --test test/*.test.ts"
   },
   "keywords": [
     "game",
@@ -27,6 +27,8 @@
   "author": "Andreas Riedmüller",
   "license": "MIT",
   "devDependencies": {
+    "@types/node": "^26.0.1",
+    "immer": "^11.1.8",
     "typescript": "^6.0.3"
   }
 }