phaser-hooks 0.3.0 → 0.5.0

package/README.md

@@ -1,3 +1,11 @@
+<p align="center">
+  <img src="data/image.png" alt="logo" style="max-width: 300px">
+</p>
+
+[![NPM Version](https://img.shields.io/npm/v/phaser-wind)](https://www.npmjs.com/package/phaser-wind)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
 # Phaser Hooks (like "use" hooks in React)
 
 A comprehensive state management library for Phaser games with React-like hooks pattern.
@@ -22,9 +30,14 @@ this.game.registry.events.on('changedata-volume', (game, value) => {
 // Using scene.data (local)
 this.data.set('score', 42); // too boring too
 const score = this.data.get('score');
-this.data.events.on('changedata-score', (scene, value) => {
+
+const onChangeFn = (scene, value) => {
   console.log('Score updated to', value);
-});
+};
+this.data.events.on('changedata-score', onChangeFn); // If you pass an anonymous function, you cannot unsubscribe :(
+
+// when move to another scene, you must unsubscribe. Boring and easy to forget
+this.data.events.off('changeset-score', onChangeFn);
 ```
 
 With _phaser-hooks_, you get a simple, React-like API:
@@ -34,7 +47,13 @@ With _phaser-hooks_, you get a simple, React-like API:
 const volume = withGlobalState(scene, 'volume', 0.5); // woow! awesome
 volume.get(); // 0.5
 volume.set(0.8); // updates value
-volume.onChange(v => console.log('Volume changed →', v)); // Nice callback <3
+
+const unsubscribe = volume.on('change', v =>
+  console.log('Volume changed →', v)
+); // Nice callback in event <3 - Return the easy unsubscribe function
+
+// when move to another scene, just call :)
+unsubscribe();
 
 // Persisted state (localStorage / sessionStorage)
 const score = withPersistState(scene, 'score', 0, { storage: 'local' }); // Wow! Saving in localStorage
@@ -59,6 +78,177 @@ Since this library is designed to work with Phaser games, which typically use pl
 
 This approach allows you to use these state management utilities in your Phaser games without having to modify your linting configuration or suppress warnings.
 
+## Hook API Reference
+
+All hooks return a `HookState` object with the following methods:
+
+| Method                     | Description                                          | Parameters                                | Returns                             |
+| -------------------------- | ---------------------------------------------------- | ----------------------------------------- | ----------------------------------- |
+| `get()`                    | Gets the current state value                         | None                                      | `T` - Current state value           |
+| `set(value)`               | Sets a new state value and triggers change listeners | `value: T \| ((currentState: T) => T)` - New value to set or updater function | `void`                              |
+| `patch(value)`             | Patches object state with partial updates            | `value: Partial<T> \| ((currentState: T) => Partial<T>)` - Partial object or updater function | `void`                              |
+| `on('change', callback)`   | Registers a callback for state changes               | `event: 'change'`, `callback: () => void` | `() => void` - Unsubscribe function |
+| `once('change', callback)` | Registers a callback that fires only once            | `event: 'change'`, `callback: () => void` | `() => void` - Unsubscribe function |
+| `off('change', callback)`  | Removes an event listener                            | `event: 'change'`, `callback: () => void` | `void`                              |
+| `clearListeners()`          | Removes all event listeners for this state           | None                                      | `void`                              |
+
+### State Updater Functions
+
+The `set()` method supports both direct values and updater functions, similar to React's `useState`:
+
+```typescript
+// Direct value assignment
+playerState.set({ hp: 100, level: 5 });
+
+// Using updater function (receives current state, returns new state)
+playerState.set((currentState) => ({ 
+  ...currentState, 
+  level: currentState.level + 1 
+}));
+
+// Equivalent to:
+const newState = { ...playerState.get(), level: playerState.get().level + 1 };
+playerState.set(newState);
+```
+
+**Benefits of updater functions:**
+- ✅ **Immutable updates**: Always work with the latest state
+- ✅ **Race condition safe**: No risk of using stale state
+- ✅ **Cleaner code**: No need to manually get current state
+- ✅ **Functional approach**: Encourages immutable state patterns
+
+**Example with complex state updates:**
+
+```typescript
+// Instead of this verbose approach:
+const currentPlayer = playerState.get();
+playerState.set({
+  ...currentPlayer,
+  hp: Math.min(currentPlayer.hp + 20, currentPlayer.maxHp),
+  level: currentPlayer.exp >= 100 ? currentPlayer.level + 1 : currentPlayer.level,
+  exp: currentPlayer.exp >= 100 ? 0 : currentPlayer.exp + 10
+});
+
+// Use this clean updater function:
+playerState.set((player) => ({
+  ...player,
+  hp: Math.min(player.hp + 20, player.maxHp),
+  level: player.exp >= 100 ? player.level + 1 : player.level,
+  exp: player.exp >= 100 ? 0 : player.exp + 10
+}));
+```
+
+### State Patching
+
+The `patch()` method allows you to update only specific properties of an object state, similar to React's state updates:
+
+```typescript
+// Direct partial object patching
+playerState.patch({ life: 90 });
+// Only updates 'life', preserves other properties
+
+// Using updater function for patching
+playerState.patch((currentState) => ({
+  life: currentState.life - 10,
+  level: currentState.level + 1
+}));
+// Updates multiple properties based on current state
+```
+
+**Benefits of patching:**
+- ✅ **Partial updates**: Only change the properties you need
+- ✅ **Preserves other data**: Unchanged properties remain untouched
+- ✅ **Deep merging**: Works with nested objects using lodash.merge
+- ✅ **Type safety**: TypeScript ensures you only patch valid properties
+- ✅ **Performance**: More efficient than full object replacement
+
+**Example with complex state updates:**
+
+```typescript
+// Instead of this verbose approach:
+const currentPlayer = playerState.get();
+playerState.set({
+  ...currentPlayer,
+  stats: {
+    ...currentPlayer.stats,
+    hp: currentPlayer.stats.hp - 20,
+    mp: currentPlayer.stats.mp + 10
+  },
+  position: {
+    ...currentPlayer.position,
+    x: currentPlayer.position.x + 5
+  }
+});
+
+// Use this clean patch approach:
+playerState.patch({
+  stats: {
+    hp: playerState.get().stats.hp - 20,
+    mp: playerState.get().stats.mp + 10
+  },
+  position: {
+    x: playerState.get().position.x + 5
+  }
+});
+
+// Or even cleaner with updater function:
+playerState.patch((player) => ({
+  stats: {
+    hp: player.stats.hp - 20,
+    mp: player.stats.mp + 10
+  },
+  position: {
+    x: player.position.x + 5
+  }
+}));
+```
+
+**Deep object patching:**
+
+```typescript
+// Patch deeply nested properties
+gameState.patch({
+  player: {
+    character: {
+      stats: {
+        primary: {
+          strength: 15
+        }
+      }
+    }
+  }
+});
+// Only updates the strength value, preserves all other nested properties
+```
+
+**Array property patching:**
+
+```typescript
+// Update array properties
+inventoryState.patch({
+  items: [...inventoryState.get().items, 'new-item']
+});
+
+// Or with updater function
+inventoryState.patch((inventory) => ({
+  items: [...inventory.items, 'new-item']
+}));
+```
+
+### Special Hook Methods
+
+Some hooks have additional methods beyond the standard `HookState` interface:
+
+#### `withUndoableState` Additional Methods:
+
+| Method           | Description                   | Parameters | Returns                    |
+| ---------------- | ----------------------------- | ---------- | -------------------------- |
+| `undo()`         | Reverts to the previous state | None       | `boolean` - Success status |
+| `redo()`         | Advances to the next state    | None       | `boolean` - Success status |
+| `canUndo()`      | Checks if undo is available   | None       | `boolean`                  |
+| `canRedo()`      | Checks if redo is available   | None       | `boolean`                  |
+| `clearHistory()` | Clears the undo/redo history  | None       | `void`                     |
+
 ## Available Hooks
 
 ### Core Hooks
@@ -68,6 +258,12 @@ This approach allows you to use these state management utilities in your Phaser
 Scene-specific state management that gets cleaned up when the scene is destroyed.
 
 ```typescript
+type PlayerData = {
+  hp: number;
+  level: number;
+  exp: number;
+};
+
 const playerState = withLocalState<PlayerData>(scene, 'player', {
   hp: 100,
   level: 1,
@@ -80,24 +276,17 @@ const playerState = withLocalState<PlayerData>(scene, 'player', {
 Application-wide state that persists across all scenes.
 
 ```typescript
+type GameSettings = {
+  soundVolume: number;
+  musicEnabled: true;
+};
+
 const settingsState = withGlobalState<GameSettings>(scene, 'settings', {
   soundVolume: 0.8,
   musicEnabled: true,
 });
 ```
 
-#### `withStateDef`
-
-Low-level state definition with custom behaviors and validation.
-
-```typescript
-const customState = withStateDef<number>(scene, 'score', {
-  initialValue: 0,
-  validator: value => value >= 0,
-  onChange: (newValue, oldValue) => console.log('Score changed!'),
-});
-```
-
 ### Enhanced Hooks
 
 #### `withPersistentState`
@@ -105,6 +294,11 @@ const customState = withStateDef<number>(scene, 'score', {
 State with automatic localStorage persistence.
 
 ```typescript
+type UserSettings = {
+  volume: number;
+  difficulty: 'easy' | 'normal' | 'hard';
+};
+
 const persistentSettings = withPersistentState<UserSettings>(
   'settings',
   {
@@ -163,13 +357,40 @@ Pre-built validation functions for common patterns.
 ```typescript
 import { validators } from 'phaser-hooks';
 
-const scoreState = withGlobalState<number>('score', 0, {
+// Number range validation (0-1000)
+const scoreState = withGlobalState<number>(scene, 'score', 0, {
   validator: validators.numberRange(0, 1000),
 });
 
-const nameState = withGlobalState<string>('name', '', {
+// Non-empty string validation
+const nameState = withGlobalState<string>(scene, 'name', '', {
   validator: validators.nonEmptyString,
 });
+
+// Array length validation (2-4 items)
+const inventoryState = withLocalState<string[]>(scene, 'inventory', [], {
+  validator: validators.arrayLength(2, 4),
+});
+
+// One of allowed values validation
+const difficultyState = withGlobalState<'easy' | 'normal' | 'hard'>(
+  scene,
+  'difficulty',
+  'normal',
+  {
+    validator: validators.oneOf(['easy', 'normal', 'hard']),
+  }
+);
+
+// Custom validator example
+const healthState = withLocalState<number>(scene, 'health', 100, {
+  validator: value => {
+    const health = value as number;
+    if (health < 0) return 'Health cannot be negative';
+    if (health > 100) return 'Health cannot exceed 100';
+    return true; // Valid
+  },
+});
 ```
 
 #### `batchStateUpdates`
@@ -211,15 +432,24 @@ export class GameScene extends Phaser.Scene {
     );
 
     // Listen to changes
-    playerState.onChange((newPlayer, oldPlayer) => {
+    const ubsubscribe = playerState.on('change', (newPlayer, oldPlayer) => {
       console.log('Player health changed:', newPlayer.hp);
     });
 
-    // Update state
-    playerState.set({
-      ...playerState.get(),
-      hp: playerState.get().hp - 10,
-    });
+    // Update state - using patch method (recommended for partial updates)
+    playerState.patch({ hp: playerState.get().hp - 10 });
+
+    // Alternative: using updater function with set
+    // playerState.set((currentPlayer) => ({
+    //   ...currentPlayer,
+    //   hp: currentPlayer.hp - 10,
+    // }));
+
+    // Alternative: direct value assignment
+    // playerState.set({
+    //   ...playerState.get(),
+    //   hp: playerState.get().hp - 10,
+    // });
   }
 }
 ```
@@ -311,10 +541,7 @@ function withPlayerEnergy(scene: Phaser.Scene) {
   });
 
   return {
-    get: () => player.get().energy,
-    set: (value: number) => player.set({ ...player.get(), energy: value }),
-    onChange: (fn: (energy: number) => void) =>
-      player.onChange(newVal => fn(newVal.energy)),
+    ...player,
   };
 }
 ```
@@ -326,15 +553,287 @@ const energy = withPlayerEnergy(this);
 
 console.log('Current energy:', energy.get());
 
-energy.set(energy.get() - 10);
+// Using updater function (recommended)
+energy.set((currentEnergy) => currentEnergy - 10);
+
+// Alternative: direct value
+// energy.set(energy.get() - 10);
 
-energy.onChange(newEnergy => {
-  if (newEnergy <= 0) {
+energy.on('change', () => {
+  if (energy.get() <= 0) {
     console.warn('You are out of energy!');
   }
 });
 ```
 
+## Unsubscribe Events
+
+When you subscribe to state changes using `.on('change', callback)`, it's crucial to properly unsubscribe to prevent memory leaks and unexpected behavior. Phaser Hooks provides two ways for unsubscribing from events.
+
+### Method 1: Using the Return Value from `.on('change')`
+
+The `.on('change', callback)` method returns an unsubscribe function that you can call to remove the listener:
+
+```typescript
+export class GameScene extends Phaser.Scene {
+  create() {
+    const playerState = withLocalState<{ hp: number }>(this, 'player', {
+      hp: 100,
+    });
+
+    // Subscribe to changes and get unsubscribe function
+    const unsubscribe = playerState.on('change', (newPlayer, oldPlayer) => {
+      console.log('Player health changed:', newPlayer.hp);
+    });
+
+    this.add
+      .text(centerX, centerY, 'Go to another scene')
+      .setInteractive()
+      .on('pointerdown', () => {
+        // Later, unsubscribe when needed
+        unsubscribe();
+
+        // To switch to another scene in Phaser, use:
+        this.scene.start('OtherSceneKey');
+      });
+  }
+}
+```
+
+### Method 2: Using `.off('change', callback)`
+
+You can also unsubscribe by passing the same callback function to `.off('change', callback)`:
+
+```typescript
+export class GameScene extends Phaser.Scene {
+  private healthCallback?: (newPlayer: any, oldPlayer: any) => void;
+
+  create() {
+    const playerState = withLocalState<{ hp: number }>(this, 'player', {
+      hp: 100,
+    });
+
+    // Define callback function
+    this.healthCallback = (newPlayer, oldPlayer) => {
+      console.log('Player health changed:', newPlayer.hp);
+    };
+
+    // Subscribe to changes
+    playerState.on('change', this.healthCallback);
+
+    this.add
+      .text(centerX, centerY, 'Go to another scene')
+      .setInteractive()
+      .on('pointerdown', () => {
+        // Later, unsubscribe when needed
+        playerState.off('change', this.healthCallback);
+
+        // To switch to another scene in Phaser, use:
+        this.scene.start('OtherSceneKey');
+      });
+  }
+}
+```
+
+> **Note:** When using `.off`, you must pass the exact same function instance that was used with `.on`. This means you cannot use an inline closure or anonymous function—use a named function or store the callback reference to unsubscribe properly.
+
+### Best Practices for Scene Cleanup
+
+**⚠️ IMPORTANT DISCLAIMER**: If you don't clean up event listeners when leaving a scene, you may encounter:
+
+- Memory leaks
+- Unexpected behavior when returning to the scene
+- Callbacks firing on destroyed or inactive scenes
+- Performance issues over time
+
+Always unsubscribe from events when transitioning between scenes:
+
+```typescript
+export class GameScene extends Phaser.Scene {
+  private unsubscribeFunctions: (() => void)[] = [];
+
+  create() {
+    const playerState = withLocalState<{ hp: number }>(this, 'player', {
+      hp: 100,
+    });
+    const scoreState = withGlobalState<number>(this, 'score', 0);
+
+    // Store unsubscribe functions
+    this.unsubscribeFunctions.push(
+      playerState.on('change', newPlayer => {
+        console.log('Player updated:', newPlayer);
+      })
+    );
+
+    this.unsubscribeFunctions.push(
+      scoreState.on('change', newScore => {
+        console.log('Score updated:', newScore);
+      })
+    );
+  }
+
+  // Clean up when scene is destroyed or when transitioning
+  shutdown() {
+    // Unsubscribe from all events
+    this.unsubscribeFunctions.forEach(unsubscribe => unsubscribe());
+    this.unsubscribeFunctions = [];
+  }
+
+  // Or clean up before transitioning to another scene
+  goToNextScene() {
+    // Clean up before changing scenes
+    this.unsubscribeFunctions.forEach(unsubscribe => unsubscribe());
+    this.unsubscribeFunctions = [];
+
+    // Then transition
+    this.scene.start('NextScene');
+  }
+}
+```
+
+### Using `clearListeners()` for Easy Cleanup
+
+For easier cleanup, you can use the `clearListeners()` method to remove all event listeners at once:
+
+```typescript
+export class GameScene extends Phaser.Scene {
+  private playerState: HookState<{ hp: number }>;
+  private scoreState: HookState<number>;
+
+  create() {
+    this.playerState = withLocalState<{ hp: number }>(this, 'player', { hp: 100 });
+    this.scoreState = withGlobalState<number>(this, 'score', 0);
+
+    // Add listeners
+    this.playerState.on('change', (newPlayer) => {
+      console.log('Player updated:', newPlayer);
+    });
+
+    this.scoreState.on('change', (newScore) => {
+      console.log('Score updated:', newScore);
+    });
+  }
+
+  shutdown() {
+    // Clear all listeners at once - much easier!
+    this.playerState.clearListeners();
+    this.scoreState.clearListeners();
+  }
+}
+```
+
+#### Important Notes about `clearListeners()`:
+
+- **`withLocalState`**: Automatically cleans up when the scene is destroyed, but you can still use `clearListeners()` for manual cleanup
+- **`withGlobalState`**: **Requires manual cleanup** since global state persists across scenes. Always call `clearListeners()` when the scene is destroyed:
+
+```typescript
+export class GameScene extends Phaser.Scene {
+  private globalState: HookState<GameSettings>;
+
+  create() {
+    this.globalState = withGlobalState<GameSettings>(this, 'settings', defaultSettings);
+    
+    this.globalState.on('change', (newSettings) => {
+      console.log('Settings updated:', newSettings);
+    });
+
+    // IMPORTANT: Clean up global state listeners when scene is destroyed
+    this.events.once('destroy', () => {
+      this.globalState.clearListeners();
+    });
+  }
+}
+```
+
+### Multiple Subscriptions Example
+
+You can have multiple listeners for the same state:
+
+```typescript
+export class GameScene extends Phaser.Scene {
+  create() {
+    const playerState = withLocalState<{ hp: number; level: number }>(
+      this,
+      'player',
+      {
+        hp: 100,
+        level: 1,
+      }
+    );
+
+    // Multiple listeners for the same state
+    const unsubscribeHealth = playerState.on('change', newPlayer => {
+      console.log('Health changed:', newPlayer.hp);
+    });
+
+    const unsubscribeLevel = playerState.on('change', newPlayer => {
+      console.log('Level changed:', newPlayer.level);
+    });
+
+    // Unsubscribe specific listeners
+    unsubscribeHealth(); // Only removes health listener
+    // unsubscribeLevel still active
+  }
+}
+```
+
+### Using `.once()` for One-Time Events
+
+The `.once()` method registers a callback that will only fire once, then automatically unsubscribes:
+
+```typescript
+export class GameScene extends Phaser.Scene {
+  create() {
+    const playerState = withLocalState<{ hp: number; level: number }>(
+      this,
+      'player',
+      {
+        hp: 100,
+        level: 1,
+      }
+    );
+
+    // One-time listener - fires only once then auto-unsubscribes
+    const unsubscribeOnce = playerState.once('change', newPlayer => {
+      console.log('First level up detected!', newPlayer.level);
+      // This callback will only run once, even if the state changes multiple times
+    });
+
+    // You can still manually unsubscribe if needed before it fires
+    // unsubscribeOnce();
+
+    // Simulate level up
+    playerState.set({ hp: 100, level: 2 }); // Fires the once callback
+    playerState.set({ hp: 100, level: 3 }); // Won't fire the once callback again
+  }
+}
+```
+
+### Validation Error Handling
+
+When using validators, invalid values will throw errors. Handle them appropriately:
+
+```typescript
+export class GameScene extends Phaser.Scene {
+  create() {
+    const healthState = withLocalState<number>(this, 'health', 100, {
+      validator: validators.numberRange(0, 100),
+    });
+
+    try {
+      healthState.set(150); // This will throw an error: "Value must be between 0 and 100"
+    } catch (error) {
+      console.error('Invalid health value:', error.message);
+      // Handle the error appropriately
+    }
+
+    // Valid value
+    healthState.set(75); // This works fine
+  }
+}
+```
+
 ### Why use this pattern?
 
 ✅ Keeps your scene code focused on intent (e.g., energy.get()) rather than structure (player.get().energy)
@@ -368,6 +867,105 @@ const playerState = withLocalState<PlayerData>(scene, 'player', {
 const currentPlayer: PlayerData = playerState.get();
 ```
 
+## Debug Mode / Dev tool
+
+Phaser Hooks includes a built-in debug mode that provides detailed logging for state operations. This is extremely useful for development and troubleshooting state management issues.
+
+### How to Enable Debug Mode
+
+To enable debug mode, simply pass `{ debug: true }` in the options parameter when creating any hook:
+
+```typescript
+import { withLocalState } from 'phaser-hooks';
+
+export class GameScene extends Phaser.Scene {
+  create() {
+    // Enable debug mode for this state
+    const playerState = withLocalState<{ hp: number; level: number }>(
+      this,
+      'player',
+      {
+        hp: 100,
+        level: 1,
+      },
+      { debug: true } // Enable debug logging
+    );
+
+    // All operations will now be logged to the console
+    playerState.set({ hp: 90, level: 2 });
+    const currentPlayer = playerState.get();
+
+    // Listen to changes with debug info
+    playerState.on('change', (newPlayer, oldPlayer) => {
+      console.log('Player state changed:', newPlayer);
+    });
+  }
+}
+```
+
+### What Debug Mode Shows
+
+When debug mode is enabled, you'll see detailed logs in your browser's developer console for:
+
+- **State Initialization**: When a state is first created
+- **State Updates**: When values are set with old and new values
+- **State Retrieval**: When values are accessed
+- **Event Listeners**: When listeners are added, removed, or cleared
+- **Validation**: When validators are applied and their results
+- **Errors**: Detailed error information with context
+
+### Viewing Debug Logs
+
+Debug logs appear in your browser's developer console. To view them:
+
+1. Open your browser's Developer Tools (F12 or right-click → Inspect)
+2. Go to the **Console** tab
+3. Run your Phaser game
+4. Look for logs prefixed with `[phaser-hooks]`
+
+![Debug Console Screenshot](data/debug-mode.png)
+*Screenshot showing debug logs in browser console*
+
+### Debug Log Format
+
+Debug logs follow a consistent format with timestamps and structured information:
+
+```
+[phaser-hooks] 2024-01-15 10:30:45 [INIT] player - Initializing state with value: {hp: 100, level: 1}
+[phaser-hooks] 2024-01-15 10:30:46 [SET] player - Updating state: {hp: 90, level: 2} (was: {hp: 100, level: 1})
+[phaser-hooks] 2024-01-15 10:30:47 [GET] player - Retrieved state: {hp: 90, level: 2}
+[phaser-hooks] 2024-01-15 10:30:48 [EVENT] player - Added change listener
+```
+
+### Best Practices for Debug Mode
+
+- **Development Only**: Only enable debug mode during development. Remove `{ debug: true }` in production builds
+- **Selective Debugging**: Enable debug mode only for the specific states you're troubleshooting
+- **Performance**: Debug mode adds overhead, so avoid enabling it for all states in production
+- **Console Filtering**: Use browser console filters to focus on specific log types
+
+### Example: Debugging State Issues
+
+```typescript
+export class DebugScene extends Phaser.Scene {
+  create() {
+    // Enable debug for problematic state
+    const inventoryState = withLocalState<string[]>(
+      this,
+      'inventory',
+      [],
+      { debug: true }
+    );
+
+    // Debug logs will show exactly what's happening
+    inventoryState.set(['sword', 'potion']);
+    inventoryState.set([...inventoryState.get(), 'shield']);
+    
+    // Check console for detailed operation logs
+  }
+}
+```
+
 ## License
 
 MIT