@couch-kit/core 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @couch-kit/core
 
+## 0.8.0
+
+### Minor Changes
+
+- [#21](https://github.com/faluciano/react-native-couch-kit/pull/21) [`f1e836d`](https://github.com/faluciano/react-native-couch-kit/commit/f1e836d8f17821f0da20db7c3c552552c9b22133) Thanks [@faluciano](https://github.com/faluciano)! - Add `replayActions` utility function for replaying recorded game sessions against a reducer. Includes `Recording`, `RecordedAction`, `StateSnapshot`, and `ReplayResult` types.
+
+## 0.7.0
+
+### Minor Changes
+
+- [#19](https://github.com/faluciano/react-native-couch-kit/pull/19) [`978616b`](https://github.com/faluciano/react-native-couch-kit/commit/978616b767031e02e24fe48de8dbdf37d15be783) Thanks [@faluciano](https://github.com/faluciano)! - Add middleware system with `applyMiddleware`, `actionLogger`, and `actionValidator`. Middleware can observe and transform actions flowing through `createGameReducer`. Includes error boundaries for fault tolerance.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -33,12 +33,12 @@ interface GameState extends IGameState {
   score: number;
 }
 
-type GameAction = { type: "SCORE" } | { type: "RESET" };
+type GameAction = { type: "SCORE"; payload: number } | { type: "RESET" };
 
 const gameReducer = (state: GameState, action: GameAction): GameState => {
   switch (action.type) {
     case "SCORE":
-      return { ...state, score: state.score + 1 };
+      return { ...state, score: state.score + action.payload };
     case "RESET":
       return { ...state, score: 0 };
     default:
@@ -47,6 +47,75 @@ const gameReducer = (state: GameState, action: GameAction): GameState => {
 };
 ```
 
+### Middleware
+
+`createGameReducer` accepts an optional second argument with a `middleware` array. Middlewares follow the Redux pattern — each is a three-layer curried function that can observe, transform, or block actions before they reach the reducer.
+
+```typescript
+import {
+  createGameReducer,
+  actionLogger,
+  actionValidator,
+  type Middleware,
+} from "@couch-kit/core";
+
+const reducer = createGameReducer(gameReducer, {
+  middleware: [
+    actionLogger(),
+    actionValidator({ SCORE: (action) => action.payload > 0 }),
+  ],
+});
+```
+
+Middlewares execute in array order: the first middleware sees the action first on the way in and last on the way out. Each middleware is wrapped in an error boundary — if one throws, it is skipped and the action continues to the next layer.
+
+#### `actionLogger(options?)`
+
+Logs every dispatched action with its previous state, action payload, and resulting state.
+
+| Option      | Type      | Default | Description                                     |
+| ----------- | --------- | ------- | ----------------------------------------------- |
+| `collapsed` | `boolean` | `true`  | Use `console.groupCollapsed` instead of `group` |
+
+```typescript
+actionLogger(); // collapsed groups (default)
+actionLogger({ collapsed: false }); // expanded groups
+```
+
+#### `actionValidator(schema)`
+
+Validates actions against a schema before they reach the reducer. If a validator returns `false`, the action is dropped and a warning is logged.
+
+```typescript
+import { actionValidator, type ActionSchema } from "@couch-kit/core";
+
+const schema: ActionSchema<GameAction> = {
+  SCORE: (action) => typeof action.payload === "number" && action.payload > 0,
+  RESET: () => true,
+};
+
+const validator = actionValidator<GameState, GameAction>(schema);
+```
+
+Actions without a matching validator in the schema pass through unchanged. Internal actions (types prefixed with `__`) are never validated.
+
+#### Custom middleware
+
+A middleware is a function with the signature:
+
+```typescript
+const myMiddleware: Middleware<GameState, GameAction> =
+  (api) => (next) => (action) => {
+    // `api.getState()` returns the current state
+    // `next(action)` passes the action to the next layer
+    // Return the resulting state
+    const result = next(action);
+    return result;
+  };
+```
+
+> **Note:** Internal actions (`__HYDRATE__`, `__PLAYER_JOINED__`, etc.) flow through middleware and are observable, but custom middleware should **not** block them. Doing so will break framework behaviour.
+
 ### Interfaces
 
 #### `IPlayer`

package/dist/index.js

@@ -1,3 +1,77 @@
+// src/middleware.ts
+function applyMiddleware(...middlewares) {
+  return (reducer) => {
+    let currentState;
+    const api = {
+      getState: () => currentState
+    };
+    const baseDispatch = (action) => {
+      currentState = reducer(currentState, action);
+      return currentState;
+    };
+    const chain = middlewares.map((mw, index) => {
+      const layer = mw(api);
+      return (next) => {
+        return (action) => {
+          let nextCalled = false;
+          const safeNext = (a) => {
+            nextCalled = true;
+            return next(a);
+          };
+          const safeHandler = layer(safeNext);
+          try {
+            return safeHandler(action);
+          } catch (error) {
+            console.error(`[couch-kit] Middleware ${index} threw on action "${action.type}":`, error);
+            return nextCalled ? api.getState() : next(action);
+          }
+        };
+      };
+    });
+    const dispatch = chain.reduceRight((next, layer) => layer(next), baseDispatch);
+    return (state, action) => {
+      currentState = state;
+      return dispatch(action);
+    };
+  };
+}
+function actionLogger(options) {
+  const collapsed = options?.collapsed ?? true;
+  return (api) => (next) => (action) => {
+    const prevState = api.getState();
+    const group = collapsed ? console.groupCollapsed : console.group;
+    group(`[couch-kit] action ${action.type}`);
+    console.log("prev state", prevState);
+    console.log("action", action);
+    try {
+      const nextState = next(action);
+      console.log("next state", nextState);
+      return nextState;
+    } finally {
+      console.groupEnd();
+    }
+  };
+}
+var _internalTypes;
+function getInternalTypes() {
+  if (!_internalTypes) {
+    _internalTypes = new Set(Object.values(InternalActionTypes));
+  }
+  return _internalTypes;
+}
+function actionValidator(schema) {
+  return (_api) => (next) => (action) => {
+    if (getInternalTypes().has(action.type))
+      return next(action);
+    const validate = schema[action.type];
+    if (validate && !validate(action)) {
+      console.warn(`[couch-kit] Action "${action.type}" failed validation, skipping`);
+      return _api.getState();
+    }
+    return next(action);
+  };
+}
+
 // src/types.ts
 var InternalActionTypes = {
   HYDRATE: "__HYDRATE__",
@@ -6,8 +80,8 @@ var InternalActionTypes = {
   PLAYER_RECONNECTED: "__PLAYER_RECONNECTED__",
   PLAYER_REMOVED: "__PLAYER_REMOVED__"
 };
-function createGameReducer(reducer) {
-  return (state, action) => {
+function createGameReducer(reducer, options) {
+  const baseReducer = (state, action) => {
     switch (action.type) {
       case InternalActionTypes.HYDRATE:
         return action.payload;
@@ -67,6 +141,10 @@ function createGameReducer(reducer) {
         return reducer(state, action);
     }
   };
+  const middlewares = options?.middleware;
+  if (!middlewares || middlewares.length === 0)
+    return baseReducer;
+  return applyMiddleware(...middlewares)(baseReducer);
 }
 // src/protocol.ts
 var MessageTypes = {
@@ -122,13 +200,39 @@ function toErrorMessage(error) {
     return error.message;
   return String(error);
 }
+// src/replay.ts
+function replayActions(recording, reducer) {
+  const snapshots = [];
+  let currentState = recording.initialState;
+  for (let i = 0;i < recording.actions.length; i++) {
+    const { action, timestamp } = recording.actions[i];
+    currentState = reducer(currentState, action);
+    snapshots.push({
+      state: currentState,
+      action,
+      timestamp,
+      index: i
+    });
+  }
+  const endTimestamp = recording.endTimestamp ?? (recording.actions.length > 0 ? recording.actions[recording.actions.length - 1].timestamp : recording.startTimestamp);
+  return {
+    finalState: currentState,
+    snapshots,
+    duration: endTimestamp - recording.startTimestamp,
+    actionCount: recording.actions.length
+  };
+}
 export {
   toErrorMessage,
+  replayActions,
   isValidSecret,
   generateId,
   derivePlayerIdLegacy,
   derivePlayerId,
   createGameReducer,
+  applyMiddleware,
+  actionValidator,
+  actionLogger,
   MessageTypes,
   MAX_PENDING_PINGS,
   MAX_FRAME_SIZE,

package/lib/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./types";
 export * from "./protocol";
 export * from "./constants";
+export * from "./replay";
+export * from "./middleware";
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC"}

package/lib/middleware.d.ts

@@ -0,0 +1,67 @@
+import type { IGameState, IAction, InternalAction, GameReducer } from "./types";
+/** The API surface available to each middleware. */
+export interface MiddlewareAPI<S extends IGameState> {
+    getState: () => S;
+}
+/** A dispatch function that accepts user actions or internal actions. */
+export type MiddlewareDispatch<S extends IGameState, A extends IAction> = (action: A | InternalAction<S>) => S;
+/**
+ * Redux-style middleware — a three-layer curried function:
+ *
+ * 1. Receives the middleware API (`getState`).
+ * 2. Receives `next` (the downstream dispatch).
+ * 3. Receives the `action` and returns the new state.
+ */
+export type Middleware<S extends IGameState = IGameState, A extends IAction = IAction> = (api: MiddlewareAPI<S>) => (next: MiddlewareDispatch<S, A>) => (action: A | InternalAction<S>) => S;
+/**
+ * Composes an array of middlewares into a higher-order function that wraps a
+ * game reducer.
+ *
+ * Middleware ordering follows the Redux convention: the **first** middleware in
+ * the array is the outermost layer — it sees the action first on the way in and
+ * last on the way out.
+ *
+ * Each middleware layer is wrapped in a try / catch. If a middleware throws, the
+ * error is logged and the action falls through to the next layer so a single
+ * broken middleware never tears down the entire dispatch chain. If the middleware
+ * already called `next` before throwing, the error boundary returns the current
+ * state instead of re-dispatching to prevent double-dispatch.
+ */
+export declare function applyMiddleware<S extends IGameState, A extends IAction>(...middlewares: Middleware<S, A>[]): (reducer: GameReducer<S, A | InternalAction<S>>) => GameReducer<S, A | InternalAction<S>>;
+/** Options for the built-in action logger middleware. */
+export interface ActionLoggerOptions {
+    /** Use `console.groupCollapsed` instead of `console.group`. Defaults to `true`. */
+    collapsed?: boolean;
+}
+/**
+ * Middleware that logs every dispatched action together with the previous and
+ * next state.
+ *
+ * ```ts
+ * createGameReducer(reducer, { middleware: [actionLogger()] });
+ * ```
+ */
+export declare function actionLogger<S extends IGameState, A extends IAction>(options?: ActionLoggerOptions): Middleware<S, A>;
+/**
+ * A map from action type strings to validator functions. Each validator receives
+ * the fully-typed action and returns `true` if the action is valid.
+ */
+export type ActionSchema<A extends IAction> = {
+    [K in A["type"]]?: (action: A & {
+        type: K;
+    }) => boolean;
+};
+/**
+ * Middleware that validates actions against a schema before they reach the
+ * reducer. Invalid actions are silently dropped (with a console warning).
+ *
+ * Internal actions are never validated — they always pass through.
+ *
+ * ```ts
+ * const validator = actionValidator<GameState, GameAction>({
+ *   SCORE: (action) => action.payload > 0,
+ * });
+ * ```
+ */
+export declare function actionValidator<S extends IGameState, A extends IAction>(schema: ActionSchema<A>): Middleware<S, A>;
+//# sourceMappingURL=middleware.d.ts.map

package/lib/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAOhF,oDAAoD;AACpD,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,UAAU;IACjD,QAAQ,EAAE,MAAM,CAAC,CAAC;CACnB;AAED,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,IAAI,CACxE,MAAM,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,KAC1B,CAAC,CAAC;AAEP;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,CAAC,SAAS,OAAO,GAAG,OAAO,IACzB,CACF,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,KAClB,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAM9E;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EACrE,GAAG,WAAW,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GACjC,CACD,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,KAC3C,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAwDzC;AAMD,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EAClE,OAAO,CAAC,EAAE,mBAAmB,GAC5B,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAmBlB;AAeD;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,OAAO,IAAI;KAC3C,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,CAAA;KAAE,KAAK,OAAO;CACxD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EACrE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GACtB,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAgBlB"}

package/lib/replay.d.ts

@@ -0,0 +1,42 @@
+import type { GameReducer, IAction, IGameState } from "./types";
+/**
+ * A recorded action with timing metadata.
+ */
+export interface RecordedAction<A extends IAction = IAction> {
+    action: A;
+    timestamp: number;
+}
+/**
+ * A snapshot of state at a point in time during replay.
+ */
+export interface StateSnapshot<S extends IGameState = IGameState> {
+    state: S;
+    action: IAction;
+    timestamp: number;
+    index: number;
+}
+/**
+ * A recording that can be replayed against a reducer.
+ */
+export interface Recording<S extends IGameState = IGameState, A extends IAction = IAction> {
+    initialState: S;
+    actions: RecordedAction<A>[];
+    startTimestamp: number;
+    endTimestamp?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The result of replaying a recording.
+ */
+export interface ReplayResult<S extends IGameState = IGameState> {
+    finalState: S;
+    snapshots: StateSnapshot<S>[];
+    duration: number;
+    actionCount: number;
+}
+/**
+ * Replays a recording against a reducer, producing the final state
+ * and intermediate snapshots for each action applied.
+ */
+export declare function replayActions<S extends IGameState = IGameState, A extends IAction = IAction>(recording: Recording<S, A>, reducer: GameReducer<S, A>): ReplayResult<S>;
+//# sourceMappingURL=replay.d.ts.map

package/lib/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO;IACzD,MAAM,EAAE,CAAC,CAAC;IACV,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IAC9D,KAAK,EAAE,CAAC,CAAC;IACT,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,SAAS,CACxB,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,CAAC,SAAS,OAAO,GAAG,OAAO;IAE3B,YAAY,EAAE,CAAC,CAAC;IAChB,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU;IAC7D,UAAU,EAAE,CAAC,CAAC;IACd,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,CAAC,SAAS,UAAU,GAAG,UAAU,EACjC,CAAC,SAAS,OAAO,GAAG,OAAO,EAC3B,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CA4BzE"}

package/lib/types.d.ts

@@ -1,3 +1,4 @@
+import type { Middleware } from "./middleware";
 /**
  * Represents a player connected to the game session.
  *
@@ -84,6 +85,18 @@ export declare const InternalActionTypes: {
  * Used by both `GameHostProvider` and `useGameClient` to define game logic.
  */
 export type GameReducer<S extends IGameState, A extends IAction> = (state: S, action: A) => S;
+/** Options for `createGameReducer`. */
+export interface CreateGameReducerOptions<S extends IGameState, A extends IAction> {
+    /**
+     * Optional middleware stack. Middlewares are applied in order — the first
+     * middleware in the array is the outermost layer and sees every action first.
+     *
+     * Middleware can observe **and** transform both user actions and internal
+     * actions. Custom middleware should avoid blocking internal actions (types
+     * prefixed with `__`) to prevent breaking framework behaviour.
+     */
+    middleware?: Middleware<S, A>[];
+}
 /**
  * Wraps a user-provided reducer with automatic handling of internal actions:
  *
@@ -95,6 +108,10 @@ export type GameReducer<S extends IGameState, A extends IAction> = (state: S, ac
  *
  * The wrapped reducer accepts both `A` (user actions) and `InternalAction<S>`.
  * User reducers only need to handle their own action types.
+ *
+ * When `options.middleware` is provided, the middleware stack wraps around the
+ * entire reducer (including internal-action handling). Middleware can observe
+ * all actions flowing through the reducer.
  */
-export declare function createGameReducer<S extends IGameState, A extends IAction>(reducer: GameReducer<S, A>): GameReducer<S, A | InternalAction<S>>;
+export declare function createGameReducer<S extends IGameState, A extends IAction>(reducer: GameReducer<S, A>, options?: CreateGameReducerOptions<S, A>): GameReducer<S, A | InternalAction<S>>;
 //# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IACxD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAE,GACnC;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD,GACD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAElE,+CAA+C;AAC/C,eAAO,MAAM,mBAAmB;;;;;;CAMtB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,IAAI,CACjE,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,KACN,CAAC,CAAC;AAEP;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EACvE,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GACzB,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAuEvC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IACxD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAE,GACnC;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD,GACD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAElE,+CAA+C;AAC/C,eAAO,MAAM,mBAAmB;;;;;;CAMtB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,IAAI,CACjE,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,KACN,CAAC,CAAC;AAEP,uCAAuC;AACvC,MAAM,WAAW,wBAAwB,CACvC,CAAC,SAAS,UAAU,EACpB,CAAC,SAAS,OAAO;IAEjB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,UAAU,EAAE,CAAC,SAAS,OAAO,EACvE,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,OAAO,CAAC,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,GACvC,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAgFvC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public",
     "provenance": true

package/src/index.ts

@@ -1,3 +1,5 @@
 export * from "./types";
 export * from "./protocol";
 export * from "./constants";
+export * from "./replay";
+export * from "./middleware";

package/src/middleware.ts

@@ -0,0 +1,204 @@
+import type { IGameState, IAction, InternalAction, GameReducer } from "./types";
+import { InternalActionTypes } from "./types";
+
+// ---------------------------------------------------------------------------
+// Middleware types
+// ---------------------------------------------------------------------------
+
+/** The API surface available to each middleware. */
+export interface MiddlewareAPI<S extends IGameState> {
+  getState: () => S;
+}
+
+/** A dispatch function that accepts user actions or internal actions. */
+export type MiddlewareDispatch<S extends IGameState, A extends IAction> = (
+  action: A | InternalAction<S>,
+) => S;
+
+/**
+ * Redux-style middleware — a three-layer curried function:
+ *
+ * 1. Receives the middleware API (`getState`).
+ * 2. Receives `next` (the downstream dispatch).
+ * 3. Receives the `action` and returns the new state.
+ */
+export type Middleware<
+  S extends IGameState = IGameState,
+  A extends IAction = IAction,
+> = (
+  api: MiddlewareAPI<S>,
+) => (next: MiddlewareDispatch<S, A>) => (action: A | InternalAction<S>) => S;
+
+// ---------------------------------------------------------------------------
+// applyMiddleware
+// ---------------------------------------------------------------------------
+
+/**
+ * Composes an array of middlewares into a higher-order function that wraps a
+ * game reducer.
+ *
+ * Middleware ordering follows the Redux convention: the **first** middleware in
+ * the array is the outermost layer — it sees the action first on the way in and
+ * last on the way out.
+ *
+ * Each middleware layer is wrapped in a try / catch. If a middleware throws, the
+ * error is logged and the action falls through to the next layer so a single
+ * broken middleware never tears down the entire dispatch chain. If the middleware
+ * already called `next` before throwing, the error boundary returns the current
+ * state instead of re-dispatching to prevent double-dispatch.
+ */
+export function applyMiddleware<S extends IGameState, A extends IAction>(
+  ...middlewares: Middleware<S, A>[]
+): (
+  reducer: GameReducer<S, A | InternalAction<S>>,
+) => GameReducer<S, A | InternalAction<S>> {
+  return (reducer: GameReducer<S, A | InternalAction<S>>) => {
+    // Mutable ref so `getState()` always returns the latest state.
+    let currentState: S;
+
+    const api: MiddlewareAPI<S> = {
+      getState: () => currentState,
+    };
+
+    // The innermost dispatch simply runs the actual reducer and updates the
+    // mutable ref.
+    const baseDispatch: MiddlewareDispatch<S, A> = (action) => {
+      currentState = reducer(currentState, action);
+      return currentState;
+    };
+
+    // Build the chain by initialising each middleware with the API, then
+    // composing right-to-left so the first middleware is outermost.
+    const chain = middlewares.map((mw, index) => {
+      const layer = mw(api);
+      // Return a wrapper that adds an error boundary around each layer.
+      // We call `layer(safeNext)` inside the action handler so we can track
+      // whether `next` was already called — preventing double-dispatch.
+      return (next: MiddlewareDispatch<S, A>): MiddlewareDispatch<S, A> => {
+        return (action: A | InternalAction<S>): S => {
+          let nextCalled = false;
+          const safeNext: MiddlewareDispatch<S, A> = (a) => {
+            nextCalled = true;
+            return next(a);
+          };
+          const safeHandler = layer(safeNext);
+          try {
+            return safeHandler(action);
+          } catch (error) {
+            console.error(
+              `[couch-kit] Middleware ${index} threw on action "${action.type}":`,
+              error,
+            );
+            return nextCalled ? api.getState() : next(action);
+          }
+        };
+      };
+    });
+
+    // Compose right-to-left: last middleware wraps baseDispatch first.
+    const dispatch = chain.reduceRight<MiddlewareDispatch<S, A>>(
+      (next, layer) => layer(next),
+      baseDispatch,
+    );
+
+    // Return a reducer with the same signature that threads through the chain.
+    return (state: S, action: A | InternalAction<S>): S => {
+      currentState = state;
+      return dispatch(action);
+    };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// actionLogger
+// ---------------------------------------------------------------------------
+
+/** Options for the built-in action logger middleware. */
+export interface ActionLoggerOptions {
+  /** Use `console.groupCollapsed` instead of `console.group`. Defaults to `true`. */
+  collapsed?: boolean;
+}
+
+/**
+ * Middleware that logs every dispatched action together with the previous and
+ * next state.
+ *
+ * ```ts
+ * createGameReducer(reducer, { middleware: [actionLogger()] });
+ * ```
+ */
+export function actionLogger<S extends IGameState, A extends IAction>(
+  options?: ActionLoggerOptions,
+): Middleware<S, A> {
+  const collapsed = options?.collapsed ?? true;
+
+  return (api) => (next) => (action) => {
+    const prevState = api.getState();
+    const group = collapsed ? console.groupCollapsed : console.group;
+
+    group(`[couch-kit] action ${action.type}`);
+    console.log("prev state", prevState);
+    console.log("action", action);
+
+    try {
+      const nextState = next(action);
+      console.log("next state", nextState);
+      return nextState;
+    } finally {
+      console.groupEnd();
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// actionValidator
+// ---------------------------------------------------------------------------
+
+/** Lazily-initialised set of internal action type strings for fast lookup. */
+let _internalTypes: Set<string> | undefined;
+function getInternalTypes(): Set<string> {
+  if (!_internalTypes) {
+    _internalTypes = new Set<string>(Object.values(InternalActionTypes));
+  }
+  return _internalTypes;
+}
+
+/**
+ * A map from action type strings to validator functions. Each validator receives
+ * the fully-typed action and returns `true` if the action is valid.
+ */
+export type ActionSchema<A extends IAction> = {
+  [K in A["type"]]?: (action: A & { type: K }) => boolean;
+};
+
+/**
+ * Middleware that validates actions against a schema before they reach the
+ * reducer. Invalid actions are silently dropped (with a console warning).
+ *
+ * Internal actions are never validated — they always pass through.
+ *
+ * ```ts
+ * const validator = actionValidator<GameState, GameAction>({
+ *   SCORE: (action) => action.payload > 0,
+ * });
+ * ```
+ */
+export function actionValidator<S extends IGameState, A extends IAction>(
+  schema: ActionSchema<A>,
+): Middleware<S, A> {
+  return (_api) => (next) => (action) => {
+    // Internal actions always pass through — never validate them.
+    if (getInternalTypes().has(action.type)) return next(action);
+
+    const validate = schema[action.type as A["type"]];
+
+    if (validate && !validate(action as A & { type: A["type"] })) {
+      console.warn(
+        `[couch-kit] Action "${action.type}" failed validation, skipping`,
+      );
+      return _api.getState();
+    }
+
+    return next(action);
+  };
+}

package/src/replay.ts

@@ -0,0 +1,80 @@
+import type { GameReducer, IAction, IGameState } from "./types";
+
+/**
+ * A recorded action with timing metadata.
+ */
+export interface RecordedAction<A extends IAction = IAction> {
+  action: A;
+  timestamp: number;
+}
+
+/**
+ * A snapshot of state at a point in time during replay.
+ */
+export interface StateSnapshot<S extends IGameState = IGameState> {
+  state: S;
+  action: IAction;
+  timestamp: number;
+  index: number;
+}
+
+/**
+ * A recording that can be replayed against a reducer.
+ */
+export interface Recording<
+  S extends IGameState = IGameState,
+  A extends IAction = IAction,
+> {
+  initialState: S;
+  actions: RecordedAction<A>[];
+  startTimestamp: number;
+  endTimestamp?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * The result of replaying a recording.
+ */
+export interface ReplayResult<S extends IGameState = IGameState> {
+  finalState: S;
+  snapshots: StateSnapshot<S>[];
+  duration: number;
+  actionCount: number;
+}
+
+/**
+ * Replays a recording against a reducer, producing the final state
+ * and intermediate snapshots for each action applied.
+ */
+export function replayActions<
+  S extends IGameState = IGameState,
+  A extends IAction = IAction,
+>(recording: Recording<S, A>, reducer: GameReducer<S, A>): ReplayResult<S> {
+  const snapshots: StateSnapshot<S>[] = [];
+  let currentState = recording.initialState;
+
+  for (let i = 0; i < recording.actions.length; i++) {
+    const { action, timestamp } = recording.actions[i];
+    currentState = reducer(currentState, action);
+
+    snapshots.push({
+      state: currentState,
+      action,
+      timestamp,
+      index: i,
+    });
+  }
+
+  const endTimestamp =
+    recording.endTimestamp ??
+    (recording.actions.length > 0
+      ? recording.actions[recording.actions.length - 1].timestamp
+      : recording.startTimestamp);
+
+  return {
+    finalState: currentState,
+    snapshots,
+    duration: endTimestamp - recording.startTimestamp,
+    actionCount: recording.actions.length,
+  };
+}

package/src/types.ts

@@ -1,3 +1,6 @@
+import { applyMiddleware } from "./middleware";
+import type { Middleware } from "./middleware";
+
 /**
  * Represents a player connected to the game session.
  *
@@ -76,6 +79,22 @@ export type GameReducer<S extends IGameState, A extends IAction> = (
   action: A,
 ) => S;
 
+/** Options for `createGameReducer`. */
+export interface CreateGameReducerOptions<
+  S extends IGameState,
+  A extends IAction,
+> {
+  /**
+   * Optional middleware stack. Middlewares are applied in order — the first
+   * middleware in the array is the outermost layer and sees every action first.
+   *
+   * Middleware can observe **and** transform both user actions and internal
+   * actions. Custom middleware should avoid blocking internal actions (types
+   * prefixed with `__`) to prevent breaking framework behaviour.
+   */
+  middleware?: Middleware<S, A>[];
+}
+
 /**
  * Wraps a user-provided reducer with automatic handling of internal actions:
  *
@@ -87,11 +106,19 @@ export type GameReducer<S extends IGameState, A extends IAction> = (
  *
  * The wrapped reducer accepts both `A` (user actions) and `InternalAction<S>`.
  * User reducers only need to handle their own action types.
+ *
+ * When `options.middleware` is provided, the middleware stack wraps around the
+ * entire reducer (including internal-action handling). Middleware can observe
+ * all actions flowing through the reducer.
  */
 export function createGameReducer<S extends IGameState, A extends IAction>(
   reducer: GameReducer<S, A>,
+  options?: CreateGameReducerOptions<S, A>,
 ): GameReducer<S, A | InternalAction<S>> {
-  return (state: S, action: A | InternalAction<S>): S => {
+  const baseReducer: GameReducer<S, A | InternalAction<S>> = (
+    state: S,
+    action: A | InternalAction<S>,
+  ): S => {
     switch (action.type) {
       case InternalActionTypes.HYDRATE:
         return (action as InternalAction<S> & { type: "__HYDRATE__" }).payload;
@@ -161,4 +188,10 @@ export function createGameReducer<S extends IGameState, A extends IAction>(
         return reducer(state, action as A);
     }
   };
+
+  const middlewares = options?.middleware;
+
+  if (!middlewares || middlewares.length === 0) return baseReducer;
+
+  return applyMiddleware<S, A>(...middlewares)(baseReducer);
 }