@hkdigital/lib-core 0.4.23 → 0.4.25

package/dist/state/{classes → machines}/loading-state-machine/LoadingStateMachine.svelte.js

@@ -10,6 +10,7 @@ import {
   STATE_LOADED,
   STATE_CANCELLED,
   STATE_ERROR,
+  STATE_TIMEOUT,
 
   // > Signals
   INITIAL,
@@ -17,7 +18,8 @@ import {
   CANCEL,
   ERROR,
   LOADED,
-  UNLOAD
+  UNLOAD,
+  TIMEOUT
 } from './constants.js';
 
 /**
@@ -30,49 +32,36 @@ export default class LoadingStateMachine extends FiniteStateMachine {
   /** @type {Error|null} */
   #error = null;
 
-  /** @type {(( state: string )=>void)|null} */
-  onenter = null;
-
   constructor() {
-    let superCalled = false;
     super(STATE_INITIAL, {
       [STATE_INITIAL]: {
-        _enter: () => {
-          if (superCalled) {
-            this.onenter?.(STATE_INITIAL);
-          }
-          superCalled = true;
-        },
         [LOAD]: STATE_LOADING
       },
       [STATE_LOADING]: {
-        _enter: () => {
-          // console.log('LoadingStateMachine: enter LOADING');
-          this.onenter?.(STATE_LOADING);
-        },
+        // _enter: () => {
+        //   console.log('LoadingStateMachine: enter LOADING');
+        // },
         [CANCEL]: STATE_CANCELLED,
         [ERROR]: STATE_ERROR,
-        [LOADED]: STATE_LOADED
+        [LOADED]: STATE_LOADED,
+        [TIMEOUT]: STATE_TIMEOUT
       },
       [STATE_LOADED]: {
-        _enter: () => {
-          // console.log('LoadingStateMachine: enter LOADED');
-          this.onenter?.(STATE_LOADED);
-        },
+        // _enter: () => {
+        //   console.log('LoadingStateMachine: enter LOADED');
+        // },
         [LOAD]: STATE_LOADING,
         [UNLOAD]: STATE_UNLOADING
       },
       [STATE_UNLOADING]: {
-        _enter: () => {
-          this.onenter?.(STATE_UNLOADING);
-        },
         [ERROR]: STATE_ERROR,
         [INITIAL]: STATE_INITIAL
       },
       [STATE_CANCELLED]: {
-        _enter: () => {
-          this.onenter?.(STATE_CANCELLED);
-        },
+        [LOAD]: STATE_LOADING,
+        [UNLOAD]: STATE_UNLOADING
+      },
+      [STATE_TIMEOUT]: {
         [LOAD]: STATE_LOADING,
         [UNLOAD]: STATE_UNLOADING
       },
@@ -90,10 +79,8 @@ export default class LoadingStateMachine extends FiniteStateMachine {
               this.#error = new Error('The state machine entered STATE_ERROR');
             }
           }
-
-          this.onenter?.(STATE_CANCELLED);
         },
-        _leave: () => {
+        _exit: () => {
           this.#error = null;
         },
         [LOAD]: STATE_LOADING,
@@ -106,4 +93,22 @@ export default class LoadingStateMachine extends FiniteStateMachine {
   get error() {
     return this.#error;
   }
+
+  /**
+   * Transition to timeout state
+   * - Only valid when currently loading
+   * - Useful for external timeout management
+   */
+  doTimeout() {
+    this.send(TIMEOUT);
+  }
+
+  /**
+   * Transition to cancelled state
+   * - Only valid when currently loading
+   * - Useful for external cancellation management
+   */
+  doCancel() {
+    this.send(CANCEL);
+  }
 }

package/dist/state/machines/loading-state-machine/README.md

@@ -0,0 +1,592 @@
+# LoadingStateMachine
+
+A specialized finite state machine designed for managing loading operations with comprehensive state tracking and error handling.
+
+## Overview
+
+`LoadingStateMachine` extends `FiniteStateMachine` to provide a standardized way to handle loading workflows. It includes predefined states for initial, loading, loaded, unloading, cancelled, and error conditions.
+
+## States
+
+The machine defines seven primary states:
+
+- **`INITIAL`** - Starting state, ready to begin loading
+- **`LOADING`** - Currently loading data or resources
+- **`LOADED`** - Successfully loaded, data available
+- **`UNLOADING`** - Cleaning up or releasing resources
+- **`CANCELLED`** - Loading operation was cancelled
+- **`ERROR`** - An error occurred during loading
+- **`TIMEOUT`** - Loading operation exceeded time limit
+
+## Events
+
+Available events to trigger state transitions:
+
+- **`LOAD`** - Start loading operation
+- **`LOADED`** - Mark loading as complete
+- **`UNLOAD`** - Begin cleanup/unloading
+- **`CANCEL`** - Cancel the loading operation
+- **`ERROR`** - Signal an error occurred
+- **`TIMEOUT`** - Signal operation has timed out
+- **`INITIAL`** - Return to initial state
+
+## Basic Usage
+
+```javascript
+import { LoadingStateMachine } from '$lib/state/machines.js';
+import {
+  // States
+  STATE_INITIAL,
+  STATE_LOADING,
+  STATE_LOADED,
+  STATE_ERROR,
+  // Events
+  LOAD,
+  LOADED,
+  ERROR,
+  CANCEL
+} from '$lib/state/machines.js';
+
+const loader = new LoadingStateMachine();
+
+// Check initial state
+console.log(loader.current); // STATE_INITIAL
+
+// Start loading
+loader.send(LOAD);
+console.log(loader.current); // STATE_LOADING
+
+// Complete successfully
+loader.send(LOADED);
+console.log(loader.current); // STATE_LOADED
+```
+
+## State Transitions
+
+### Valid Transitions
+
+```
+INITIAL → LOADING
+LOADING → LOADED | CANCELLED | ERROR | TIMEOUT
+LOADED → LOADING | UNLOADING
+UNLOADING → INITIAL | ERROR
+CANCELLED → LOADING | UNLOADING
+ERROR → LOADING | UNLOADING
+TIMEOUT → LOADING | UNLOADING
+```
+
+### Transition Diagram
+
+```
+        ┌─────────┐
+        │ INITIAL │
+        └────┬────┘
+             │ LOAD
+             ▼
+    ┌─────────┐    CANCEL     ┌───────────┐
+    │ LOADING │──────────────→│ CANCELLED │
+    └────┬────┘               └─────┬─────┘
+         │                          │
+    LOADED│  ERROR  TIMEOUT    LOAD │ UNLOAD
+         │     │       │            │    │
+         ▼     ▼       ▼            ▼    ▼
+    ┌────────┐ ┌───────┐ ┌─────────┐ ┌──────────┐
+    │ LOADED │ │ ERROR │ │ TIMEOUT │ │UNLOADING │
+    └────┬───┘ └───┬───┘ └────┬────┘ └────┬─────┘
+         │         │          │           │
+   UNLOAD│    LOAD │ UNLOAD  LOAD│ UNLOAD INITIAL│ ERROR
+         ▼         ▼            ▼           ▼
+    ┌──────────┐◄──────────────────────────┘
+    │UNLOADING │
+    └──────────┘
+```
+
+## onenter Callback
+
+The `onenter` callback provides a reliable way to react to state changes, designed to work around Svelte's reactive batching behavior.
+
+```javascript
+const loader = new LoadingStateMachine();
+
+loader.onenter = (state) => {
+  switch (state) {
+    case STATE_LOADING:
+      console.log('Started loading...');
+      showSpinner();
+      break;
+    case STATE_LOADED:
+      console.log('Loading complete!');
+      hideSpinner();
+      break;
+    case STATE_ERROR:
+      console.log('Loading failed');
+      showError();
+      break;
+    case STATE_TIMEOUT:
+      console.log('Loading timed out');
+      showRetryOption();
+      break;
+  }
+};
+```
+
+### Why onenter?
+
+The `onenter` callback was added because there might be issues when the stats machine is combined with Svelte's `$effect`. This callback ensures you can reliably respond to every state change.
+
+```javascript
+// Svelte $effect might miss rapid transitions
+$effect(() => {
+  console.log(loader.current); // May only see final state
+});
+
+// onenter catches every transition
+loader.onenter = (state) => {
+  console.log(state); // Sees every state change
+};
+```
+
+## Error Handling
+
+The machine includes sophisticated error handling with automatic error object creation:
+
+```javascript
+const loader = new LoadingStateMachine();
+
+// Send error with Error object
+loader.send(ERROR, new Error('Network failed'));
+console.log(loader.error.message); // 'Network failed'
+
+// Send error with error details
+loader.send(ERROR, { error: 'Timeout occurred' });
+console.log(loader.error.message); // 'Timeout occurred'
+
+// Send error with just a string
+loader.send(ERROR, { error: new Error('Parse error') });
+console.log(loader.error.message); // 'Parse error'
+```
+
+The `error` getter provides access to the last error:
+
+```javascript
+if (loader.current === 'error') {
+  console.error('Loading failed:', loader.error);
+}
+```
+
+## Timeout Handling
+
+The machine supports timeout functionality for managing loading operations that exceed expected duration:
+
+```javascript
+const loader = new LoadingStateMachine();
+
+// External timeout management
+const timeoutId = setTimeout(() => {
+  if (loader.current === STATE_LOADING) {
+    loader.doTimeout(); // Transitions to STATE_TIMEOUT
+  }
+}, 10000); // 10 second timeout
+
+loader.onenter = (state) => {
+  switch (state) {
+    case STATE_TIMEOUT:
+      console.log('Loading timed out');
+      showRetryButton();
+      break;
+    case STATE_LOADED:
+      clearTimeout(timeoutId); // Cancel timeout on success
+      break;
+  }
+};
+```
+
+### doTimeout Method
+
+Use `doTimeout()` to manually trigger a timeout transition:
+
+```javascript
+// Only works when in STATE_LOADING
+loader.doTimeout(); // Sends TIMEOUT signal
+```
+
+## Integration with Svelte Reactivity
+
+LoadingStateMachine inherits the `onenter` callback and Svelte reactivity integration patterns from [FiniteStateMachine](../finite-state-machine/README.md#integration-with-svelte-reactivity). 
+
+### Quick Reference: Loading State Pattern
+
+**✅ Use `onenter` for immediate loading actions:**
+```javascript
+const loader = new LoadingStateMachine();
+
+loader.onenter = (state) => {
+  switch (state) {
+    case STATE_LOADING:
+      this.#startLoading(); // Start async process immediately
+      break;
+    case STATE_LOADED:
+      this.#cleanup(); // Cleanup when complete
+      break;
+    case STATE_ERROR:
+      this.#handleError(); // Handle error state
+      break;
+  }
+  this.state = state; // Update public state
+};
+```
+
+**✅ Use `$effect` for reactive completion monitoring:**
+```javascript
+// Monitor derived/computed values and trigger transitions when conditions are met
+$effect(() => {
+  if (loader.current === STATE_LOADING) {
+    // Check completion based on reactive derived values
+    if (this.#sourcesLoaded === this.#numberOfSources && this.#numberOfSources > 0) {
+      loader.send(LOADED); // Trigger transition when condition met
+    }
+  }
+});
+```
+
+### Loading-Specific Example
+
+```javascript
+export default class MultiSourceLoader {
+  #loader = new LoadingStateMachine();
+  #sources = $state([]);
+  
+  // Derived progress calculation  
+  #progress = $derived.by(() => {
+    let completed = 0;
+    for (const source of this.#sources) {
+      if (source.loaded) completed++;
+    }
+    return { completed, total: this.#sources.length };
+  });
+
+  constructor() {
+    // Handle immediate loading state actions
+    this.#loader.onenter = (state) => {
+      switch (state) {
+        case STATE_LOADING:
+          this.#startAllSources();
+          break;
+        case STATE_LOADED:
+          this.#notifyComplete();
+          break;
+        case STATE_ERROR:
+          this.#handleLoadError();
+          break;
+        case STATE_TIMEOUT:
+          this.#handleTimeout();
+          break;
+      }
+      this.state = state;
+    };
+
+    // Monitor reactive completion
+    $effect(() => {
+      if (this.#loader.current === STATE_LOADING) {
+        const { completed, total } = this.#progress;
+        if (completed === total && total > 0) {
+          this.#loader.send(LOADED);
+        }
+      }
+    });
+  }
+}
+```
+
+**📖 For complete documentation** of the `onenter` callback and Svelte reactivity patterns, see the [FiniteStateMachine README](../finite-state-machine/README.md#integration-with-svelte-reactivity).
+
+### Basic Component Integration
+
+```javascript
+// LoadingComponent.svelte
+<script>
+  import { LoadingStateMachine } from '$lib/state/machines.js';
+  import {
+    STATE_LOADING,
+    STATE_LOADED,
+    STATE_ERROR,
+    LOAD,
+    LOADED,
+    ERROR,
+    CANCEL
+  } from '$lib/state/machines.js';
+  
+  const loader = new LoadingStateMachine();
+  let data = $state(null);
+  
+  loader.onenter = (state) => {
+    if (state === STATE_LOADING) {
+      loadData();
+    }
+  };
+  
+  async function loadData() {
+    try {
+      const response = await fetch('/api/data');
+      data = await response.json();
+      loader.send(LOADED);
+    } catch (error) {
+      loader.send(ERROR, error);
+    }
+  }
+</script>
+
+<button onclick={() => loader.send(LOAD)} disabled={loader.current === STATE_LOADING}>
+  {#if loader.current === STATE_LOADING}
+    Loading...
+  {:else}
+    Load Data
+  {/if}
+</button>
+
+{#if loader.current === STATE_LOADED}
+  <div>Data loaded successfully!</div>
+{:else if loader.current === STATE_ERROR}
+  <div>Error: {loader.error.message}</div>
+{/if}
+```
+
+### Advanced Component with Cancellation
+
+```javascript
+<script>
+  import { LoadingStateMachine } from '$lib/state/machines.js';
+  import {
+    STATE_INITIAL,
+    STATE_LOADING,
+    STATE_LOADED,
+    STATE_CANCELLED,
+    STATE_ERROR,
+    LOAD,
+    LOADED,
+    ERROR,
+    CANCEL
+  } from '$lib/state/machines.js';
+  
+  const loader = new LoadingStateMachine();
+  let abortController = null;
+  
+  loader.onenter = (state) => {
+    switch (state) {
+      case STATE_LOADING:
+        startLoad();
+        break;
+      case STATE_CANCELLED:
+        abortController?.abort();
+        break;
+    }
+  };
+  
+  async function startLoad() {
+    abortController = new AbortController();
+    
+    try {
+      const response = await fetch('/api/slow-data', {
+        signal: abortController.signal
+      });
+      const data = await response.json();
+      loader.send(LOADED);
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        // Request was cancelled, machine already in cancelled state
+      } else {
+        loader.send(ERROR, error);
+      }
+    }
+  }
+</script>
+
+<div>
+  {#if loader.current === STATE_INITIAL}
+    <button onclick={() => loader.send(LOAD)}>Start Loading</button>
+  {:else if loader.current === STATE_LOADING}
+    <button onclick={() => loader.send(CANCEL)}>Cancel Loading</button>
+    <div>Loading data...</div>
+  {:else if loader.current === STATE_LOADED}
+    <div>Data loaded successfully!</div>
+    <button onclick={() => loader.send(LOAD)}>Reload</button>
+  {:else if loader.current === STATE_CANCELLED}
+    <div>Loading cancelled</div>
+    <button onclick={() => loader.send(LOAD)}>Try Again</button>
+  {:else if loader.current === STATE_ERROR}
+    <div>Error: {loader.error.message}</div>
+    <button onclick={() => loader.send(LOAD)}>Retry</button>
+  {/if}
+</div>
+```
+
+## Best Practices
+
+### 1. Use onenter for Side Effects
+
+```javascript
+// ✅ Good - use onenter for reliable side effects
+loader.onenter = (state) => {
+  if (state === STATE_LOADING) {
+    analytics.track('loading_started');
+  }
+};
+
+// ❌ Avoid - $effect may miss rapid transitions
+$effect(() => {
+  if (loader.current === STATE_LOADING) {
+    analytics.track('loading_started'); // May not fire
+  }
+});
+```
+
+### 2. Handle All Error States
+
+```javascript
+loader.onenter = (state) => {
+  switch (state) {
+    case STATE_ERROR:
+      showErrorToast(loader.error.message);
+      logError(loader.error);
+      break;
+    case STATE_CANCELLED:
+      showMessage('Operation cancelled');
+      break;
+  }
+};
+```
+
+### 3. Implement Proper Cleanup
+
+```javascript
+loader.onenter = (state) => {
+  switch (state) {
+    case STATE_LOADING:
+      showProgressBar();
+      break;
+    case STATE_LOADED:
+    case STATE_ERROR:
+    case STATE_CANCELLED:
+      hideProgressBar();
+      break;
+    case STATE_UNLOADING:
+      cleanup();
+      break;
+  }
+};
+```
+
+### 4. Use Constants for Events
+
+```javascript
+import {
+  LOAD,
+  LOADED,
+  ERROR
+} from '$lib/state/machines.js';
+
+// ✅ Good - type safe and refactor friendly
+loader.send(LOAD);
+
+// ❌ Avoid - prone to typos
+loader.send('load');
+```
+
+## Common Patterns
+
+### Resource Loading with Cleanup
+
+```javascript
+const resourceLoader = new LoadingStateMachine();
+let resource = null;
+
+resourceLoader.onenter = async (state) => {
+  switch (state) {
+    case STATE_LOADING:
+      try {
+        resource = await loadResource();
+        resourceLoader.send(LOADED);
+      } catch (error) {
+        resourceLoader.send(ERROR, error);
+      }
+      break;
+      
+    case STATE_UNLOADING:
+      if (resource) {
+        await resource.cleanup();
+        resource = null;
+      }
+      resourceLoader.send(INITIAL);
+      break;
+  }
+};
+```
+
+### Retry Logic
+
+```javascript
+const retryLoader = new LoadingStateMachine();
+let retryCount = 0;
+const maxRetries = 3;
+
+retryLoader.onenter = async (state) => {
+  switch (state) {
+    case STATE_LOADING:
+      try {
+        await performLoad();
+        retryCount = 0; // Reset on success
+        retryLoader.send(LOADED);
+      } catch (error) {
+        retryLoader.send(ERROR, error);
+      }
+      break;
+      
+    case STATE_ERROR:
+      if (retryCount < maxRetries) {
+        retryCount++;
+        setTimeout(() => {
+          retryLoader.send(LOAD);
+        }, 1000 * retryCount); // Exponential backoff
+      }
+      break;
+  }
+};
+```
+
+## Testing
+
+The LoadingStateMachine includes comprehensive tests covering:
+
+- All state transitions
+- onenter callback functionality
+- Error handling with different error types
+- Null safety when no callback is set
+- Dynamic callback changes
+
+See `LoadingStateMachine.test.js` for detailed examples.
+
+## Constants
+
+Import state and event constants from the constants file:
+
+```javascript
+import {
+  // States
+  STATE_INITIAL,
+  STATE_LOADING,
+  STATE_LOADED,
+  STATE_UNLOADING,
+  STATE_CANCELLED,
+  STATE_ERROR,
+  STATE_TIMEOUT,
+  
+  // Events
+  LOAD,
+  LOADED,
+  UNLOAD,
+  CANCEL,
+  ERROR,
+  INITIAL,
+  TIMEOUT
+} from './constants.js';
+```

package/dist/state/{classes → machines}/loading-state-machine/constants.d.ts

@@ -4,9 +4,11 @@ export const STATE_UNLOADING: "unloading";
 export const STATE_LOADED: "loaded";
 export const STATE_CANCELLED: "cancelled";
 export const STATE_ERROR: "error";
+export const STATE_TIMEOUT: "timeout";
 export const INITIAL: "initial";
 export const LOAD: "load";
 export const CANCEL: "cancel";
 export const ERROR: "error";
 export const LOADED: "loaded";
 export const UNLOAD: "unload";
+export const TIMEOUT: "timeout";