move-by-move 2.0.0 → 3.1.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 action and the current state 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
 
@@ -38,35 +38,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 `[action, state]` 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). (A third tuple slot, `context`, is shared by *every* rule — raw or `createRule` — for [passing information downstream](#context-sharing-data-between-rules); this example just doesn't need it.)
+
 ## Core concept: rules
 
-A **rule** is a function over a `[action, state]` tuple:
+A **rule** is a function over a `[action, state, context]` tuple:
 
 ```ts
-type RuleIO<State> = [action: GameAction, state: State]
-type Rule<State> = (input: RuleIO<State>) => RuleIO<State>
+type RuleIO<State, Context = any> = [action: Immutable<GameAction>, state: Immutable<State>, context?: Context]
+type Rule<State, Context = any> = (input: RuleIO<State, Context>) => RuleIO<State, Context>
 ```
 
-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` and `state` 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 `[action, state, 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
+[action, state, context] → rule1 → rule2 → rule3 → [action, newState, 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 action, the (possibly already-transformed) state, 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 `[action, state]` 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, optionally, your `Action` union and `Context` shape) 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,18 +85,31 @@ 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 }
 
-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)
+```
+
+A recipe receives `(action, state, context)`:
+
+- `action` — the action being processed, **read-only**.
+- `state` — a **mutable draft**; mutate it directly, no spreading.
+- `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 (and unknown types are a compile error). Omit it to run on every action. Here's tic-tac-toe:
+
+```ts
+const placeMark = createRule('PLACE', (action, state, context) => {
+  if (state.winner) return
+  if (state.board[action.index] !== null) return // square already taken
+  state.board[action.index] = state.turn          // action.index is typed: number
+  context.placed = true // tell downstream rules the move was accepted
+})
+
+const switchTurn = createRule('PLACE', (action, state, context) => {
+  if (!context.placed) return // only switch when placeMark accepted the move
+  state.turn = state.turn === 'X' ? 'O' : 'X'
+})
 
 const game = createGame<State>(
   [placeMark, switchTurn],
@@ -93,6 +117,30 @@ const game = createGame<State>(
 )
 ```
 
+For brevity this omits win detection: a complete game adds a rule after `placeMark` 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.)
+- Type it via the third generic of `createRuleFactory` when you want safety — every rule then shares that shape:
+
+```ts
+const createRule = createRuleFactory<State, Action, { placed?: boolean }>(produce)
+// inside any rule, context.placed is now typed as boolean | undefined
+```
+
 ## API
 
 ### `createGame<State>(rules, initialState): Game<State>`
@@ -102,11 +150,39 @@ Creates a new game instance.
 - `rules` — an array of rule functions, applied in order on every move.
 - `initialState` — the starting state.
 
+### `createRuleFactory<State, Action, Context>(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`). Defaults to `GameAction`; supplying it enables payload narrowing and rejects unknown action types.
+- `Context` — the shape of the per-move shared bag (see [Context](#context-sharing-data-between-rules)). Defaults to `Record<string, any>`.
+
+`createRule` has two forms, both returning a `Rule<State, Context>`:
+
+| 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 `(action, state, context) => void`: `action` is read-only, `state` is a mutable immer draft, and your mutations are turned into the next immutable state. 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 `action` and `state` seen by rules (and the return of `getState`). 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>`
 
 | Method | Description |
 | --- | --- |
-| `getState(): State` | Returns the current state. |
+| `getState(): Immutable<State>` | Returns the current state, deeply read-only. |
 | `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. |
 

package/lib/helpers.d.ts

@@ -1 +1 @@
-export declare const pipe: <T>(...fns: ((arg: T) => T)[]) => (value: T) => T;
+export declare const pipe: <T>(...fns: Array<(arg: T) => T>) => (value: T) => T;

package/lib/helpers.js

@@ -1,5 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pipe = void 0;
-const pipe = (...fns) => (value) => fns.reduce((acc, fn) => fn(acc), value);
-exports.pipe = pipe;
+export const pipe = (...fns) => (value) => fns.reduce((acc, fn) => fn(acc), value);

package/lib/index.d.ts

@@ -1,10 +1,23 @@
-export declare type GameAction<Payload = any> = Payload & {
+export type GameAction<Payload = any> = Payload & {
     type: string;
 };
-export interface Game<Type> {
+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 interface Game<State> {
     subscribe(listener: Function): () => void;
-    getState(): Type;
+    getState(): Immutable<State>;
     move(action: GameAction): void;
 }
-export declare 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, Context = any> = [action: Immutable<GameAction>, state: Immutable<State>, context?: Context];
+export type Rule<State, Context = any> = (input: RuleIO<State, Context>) => RuleIO<State, Context>;
+export type Produce = <S>(base: S, recipe: (draft: S) => void) => S;
+export declare function createRuleFactory<State, Action extends {
+    type: string;
+} = GameAction, Context extends object = Record<string, any>>(produce: Produce): {
+    (recipe: (action: Immutable<Action>, state: State, context: Context) => void): Rule<State, Context>;
+    <Type extends Action["type"]>(type: Type, recipe: (action: Immutable<Extract<Action, {
+        type: Type;
+    }>>, state: State, context: Context) => void): Rule<State, Context>;
+};
+export default function createGame<State>(rules: Array<Rule<State>>, initialGameState: State): Game<State>;

package/lib/index.js

@@ -1,7 +1,22 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const helpers_1 = require("./helpers");
-function createGame(rules, initialGameState) {
+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 ([action, state, context]) => {
+            const nextContext = (context ?? {});
+            if (type !== undefined && action.type !== type) {
+                return [action, state, nextContext];
+            }
+            const nextState = produce(state, (draft) => {
+                recipe(action, draft, nextContext);
+            });
+            return [action, nextState, nextContext];
+        };
+    }
+    return createRule;
+}
+export default function createGame(rules, initialGameState) {
     let listeners = [];
     let state = initialGameState;
     const unsubscribe = (listener) => {
@@ -15,7 +30,7 @@ function createGame(rules, initialGameState) {
         return state;
     };
     const move = (action) => {
-        const result = (0, helpers_1.pipe)(...rules)([action, state]);
+        const result = pipe(...rules)([action, state, {}]);
         state = result[1];
         for (const listener of listeners) {
             listener();
@@ -27,4 +42,3 @@ function createGame(rules, initialGameState) {
         move,
     };
 }
-exports.default = createGame;

package/package.json

@@ -1,16 +1,24 @@
 {
   "name": "move-by-move",
-  "version": "2.0.0",
+  "version": "3.1.0",
   "description": "Simple game engine for turn based games",
+  "type": "module",
   "main": "lib/index.js",
-  "typings": "lib/index.d.ts",
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
   "files": [
     "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",
@@ -19,6 +27,8 @@
   "author": "Andreas Riedmüller",
   "license": "MIT",
   "devDependencies": {
-    "typescript": "^4.5.4"
+    "@types/node": "^26.0.1",
+    "immer": "^11.1.8",
+    "typescript": "^6.0.3"
   }
 }