@hkdigital/lib-core 0.4.22 → 0.4.24

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

@@ -0,0 +1,544 @@
+# 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 six 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
+
+## 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
+- **`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
+LOADED → LOADING | UNLOADING
+UNLOADING → INITIAL | ERROR
+CANCELLED → LOADING | UNLOADING
+ERROR → LOADING | UNLOADING
+```
+
+### Transition Diagram
+
+```
+    ┌─────────┐
+    │ INITIAL │
+    └────┬────┘
+         │ LOAD
+         ▼
+    ┌─────────┐    CANCEL     ┌───────────┐
+    │ LOADING │──────────────→│ CANCELLED │
+    └────┬────┘               └─────┬─────┘
+         │                          │
+    LOADED│  ERROR             LOAD │ UNLOAD
+         │     │                    │    │
+         ▼     ▼                    ▼    ▼
+    ┌────────┐ ┌───────┐        ┌──────────┐
+    │ LOADED │ │ ERROR │        │UNLOADING │
+    └────┬───┘ └───┬───┘        └────┬─────┘
+         │         │                 │
+   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;
+  }
+};
+```
+
+### 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);
+}
+```
+
+## 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;
+      }
+      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,
+  
+  // Events
+  LOAD,
+  LOADED,
+  UNLOAD,
+  CANCEL,
+  ERROR,
+  INITIAL
+} from './constants.js';
+```

package/dist/state/machines/typedef.d.ts

@@ -0,0 +1 @@
+export * from "./finite-state-machine/typedef.js";

package/dist/state/machines/typedef.js

@@ -0,0 +1 @@
+export * from './finite-state-machine/typedef.js';

package/dist/state/machines.d.ts

@@ -0,0 +1,2 @@
+export * from "./machines/finite-state-machine/index.js";
+export * from "./machines/loading-state-machine/index.js";

package/dist/state/machines.js

@@ -0,0 +1,2 @@
+export * from './machines/finite-state-machine/index.js';
+export * from './machines/loading-state-machine/index.js';

package/dist/state/typedef.d.ts

@@ -1,3 +1,4 @@
 export * from "./context/typedef.js";
+export * from "./machines/typedef.js";
 declare const _default: {};
 export default _default;

package/dist/state/typedef.js

@@ -1,3 +1,4 @@
 export * from './context/typedef.js';
+export * from './machines/typedef.js';
 
 export default {};