move-by-move 3.1.0 → 4.0.1

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 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.
+`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,29 +39,29 @@ 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.)
+> 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, context]` tuple:
+A **rule** is a function over a `[state, action, context]` tuple:
 
 ```ts
-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>
+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>
 ```
 
-`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.
+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 `[action, state, context]` through every rule **in order** and uses the resulting state as the new state:
+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, context] → rule1 → rule2 → rule3 → [action, newState, context]
-                                                       └── becomes the new state
+[state, action, context] → rule1 → rule2 → rule3 → [newState, action, context]
+                                                     └── becomes the new state
 ```
 
 (`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:
+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),
@@ -71,9 +72,9 @@ Order matters — a validation rule should run before the rule that applies the
 
 ### 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.
+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, optionally, your `Action` union and `Context` shape) at the same time:
+`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, { createRuleFactory } from 'move-by-move'
@@ -85,39 +86,47 @@ type State = {
   winner: string | null
 }
 
-type Action = { type: 'PLACE'; index: number }
+type Action =
+  | { type: 'PLACE'; index: number }
+  | { type: 'GIVE_UP' }
 
 const createRule = createRuleFactory<State, Action>(produce)
 ```
 
-A recipe receives `(action, state, context)`:
+A recipe receives `(state, action, context)`:
 
-- `action` — the action being processed, **read-only**.
 - `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 (and unknown types are a compile error). Omit it to run on every action. Here's tic-tac-toe:
+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', (action, state, context) => {
+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          // action.index is typed: number
+  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', (action, state, context) => {
+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'
 })
 
-const game = createGame<State>(
-  [placeMark, switchTurn],
+// 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 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.
+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
 
@@ -134,23 +143,20 @@ 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
-```
+- 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.
 
-### `createRuleFactory<State, Action, Context>(produce)`
+### `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:
 
@@ -162,38 +168,39 @@ 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>`.
+- `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, Context>`:
+`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 `(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)).
+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 `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`.
+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>`
+### `Game<State, Action>`
 
 | Method | Description |
 | --- | --- |
-| `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. |
+| `getState(): State` | Returns the current state. |
+| `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,23 +1,19 @@
-export type GameAction<Payload = any> = Payload & {
+type GameAction = {
     type: string;
 };
-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> {
+interface Game<State, Action extends GameAction> {
     subscribe(listener: Function): () => void;
-    getState(): Immutable<State>;
-    move(action: GameAction): void;
+    getState(): State;
+    move(action: Action): void;
 }
-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 RuleIO<State, Action extends GameAction> = [state: State, action: Action, context: Record<string, unknown>];
+type Rule<State, Action extends GameAction> = (input: RuleIO<State, Action>) => RuleIO<State, Action>;
+type Produce = <S>(base: S, recipe: (draft: S) => void) => S;
+export declare function createRuleFactory<State, Action extends GameAction>(produce: Produce): {
+    (recipe: (state: State, action: Action, context: Record<string, unknown>) => void): Rule<State, Action>;
+    <Type extends Action["type"]>(type: Type, recipe: (state: State, action: Extract<Action, {
         type: Type;
-    }>>, state: State, context: Context) => void): Rule<State, Context>;
+    }>, context: Record<string, unknown>) => void): Rule<State, Action>;
 };
-export default function createGame<State>(rules: Array<Rule<State>>, initialGameState: State): Game<State>;
+export default function createGame<State, Action extends GameAction>(rules: Array<Rule<State, Action>>, initialGameState: State): Game<State, Action>;
+export {};

package/lib/index.js

@@ -3,15 +3,14 @@ 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 ?? {});
+        return ([state, action, context]) => {
             if (type !== undefined && action.type !== type) {
-                return [action, state, nextContext];
+                return [state, action, context];
             }
             const nextState = produce(state, (draft) => {
-                recipe(action, draft, nextContext);
+                recipe(draft, action, context);
             });
-            return [action, nextState, nextContext];
+            return [nextState, action, context];
         };
     }
     return createRule;
@@ -30,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.1.0",
+  "version": "4.0.1",
   "description": "Simple game engine for turn based games",
   "type": "module",
   "main": "lib/index.js",