@hkdigital/lib-core 0.4.25 → 0.4.27

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

@@ -4,17 +4,18 @@ A specialized finite state machine designed for managing loading operations with
 
 ## 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.
+`LoadingStateMachine` extends `FiniteStateMachine` to provide a standardized way to handle loading workflows. It includes predefined states for initial, loading, loaded, unloading, aborted, and error conditions.
 
 ## States
 
-The machine defines seven primary states:
+The machine defines eight 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
+- **`ABORTING`** - Currently aborting loading operation
+- **`ABORTED`** - Loading operation was aborted
 - **`ERROR`** - An error occurred during loading
 - **`TIMEOUT`** - Loading operation exceeded time limit
 
@@ -25,7 +26,8 @@ Available events to trigger state transitions:
 - **`LOAD`** - Start loading operation
 - **`LOADED`** - Mark loading as complete
 - **`UNLOAD`** - Begin cleanup/unloading
-- **`CANCEL`** - Cancel the loading operation
+- **`ABORT`** - Start aborting the loading operation
+- **`ABORTED`** - Mark abort operation as complete
 - **`ERROR`** - Signal an error occurred
 - **`TIMEOUT`** - Signal operation has timed out
 - **`INITIAL`** - Return to initial state
@@ -44,7 +46,7 @@ import {
   LOAD,
   LOADED,
   ERROR,
-  CANCEL
+  ABORT
 } from '$lib/state/machines.js';
 
 const loader = new LoadingStateMachine();
@@ -67,10 +69,11 @@ console.log(loader.current); // STATE_LOADED
 
 ```
 INITIAL → LOADING
-LOADING → LOADED | CANCELLED | ERROR | TIMEOUT
+LOADING → LOADED | ABORTING | ERROR | TIMEOUT
 LOADED → LOADING | UNLOADING
 UNLOADING → INITIAL | ERROR
-CANCELLED → LOADING | UNLOADING
+ABORTING → ABORTED | ERROR
+ABORTED → LOADING | UNLOADING
 ERROR → LOADING | UNLOADING
 TIMEOUT → LOADING | UNLOADING
 ```
@@ -78,26 +81,26 @@ 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 │
+    ┌─────────┐
+    │ INITIAL │
+    └────┬────┘
+     LOAD│
+         ▼
+    ┌─────────┐            ABORT              ┌──────────┐
+    │ LOADING │──────────────────────────────→│ ABORTING │
+    └────┬────┘                               └─────┬────┘
+         │                                          │
+   LOADED│       ERROR        TIMEOUT      ABORTED  │ERROR
+         │         │             │            │     │
+         ▼         ▼             ▼            ▼     ▼
+    ┌────────┐ ┌───────┐    ┌─────────┐     ┌─────────┐
+    │ LOADED │ │ ERROR │    │ TIMEOUT │     │ ABORTED │
+    └────┬───┘ └───┬───┘    └────┬────┘     └────┬────┘
+         │         │             │               │
+   UNLOAD│     LOAD│UNLOAD   LOAD│UNLOAD     LOAD│UNLOAD
+         ▼         ▼             ▼               ▼
+    ┌──────────┐                                 │
+    │UNLOADING │◄────────────────────────────────┘
     └──────────┘
 ```
 
@@ -108,8 +111,8 @@ The `onenter` callback provides a reliable way to react to state changes, design
 ```javascript
 const loader = new LoadingStateMachine();
 
-loader.onenter = (state) => {
-  switch (state) {
+loader.onenter = (currentState) => {
+  switch (currentState) {
     case STATE_LOADING:
       console.log('Started loading...');
       showSpinner();
@@ -141,8 +144,8 @@ $effect(() => {
 });
 
 // onenter catches every transition
-loader.onenter = (state) => {
-  console.log(state); // Sees every state change
+loader.onenter = (currentState) => {
+  console.log(currentState); // Sees every state change
 };
 ```
 
@@ -184,12 +187,12 @@ const loader = new LoadingStateMachine();
 // External timeout management
 const timeoutId = setTimeout(() => {
   if (loader.current === STATE_LOADING) {
-    loader.doTimeout(); // Transitions to STATE_TIMEOUT
+    loader.timeout(); // Transitions to STATE_TIMEOUT
   }
 }, 10000); // 10 second timeout
 
-loader.onenter = (state) => {
-  switch (state) {
+loader.onenter = (currentState) => {
+  switch (currentState) {
     case STATE_TIMEOUT:
       console.log('Loading timed out');
       showRetryButton();
@@ -201,13 +204,22 @@ loader.onenter = (state) => {
 };
 ```
 
-### doTimeout Method
+### timeout Method
 
-Use `doTimeout()` to manually trigger a timeout transition:
+Use `timeout()` to manually trigger a timeout transition:
 
 ```javascript
 // Only works when in STATE_LOADING
-loader.doTimeout(); // Sends TIMEOUT signal
+loader.timeout(); // Sends TIMEOUT signal
+```
+
+### abort Method
+
+Use `abort()` to manually trigger an abort transition:
+
+```javascript
+// Only works when in STATE_LOADING
+loader.abort(); // Sends ABORT signal, transitions to STATE_ABORTING
 ```
 
 ## Integration with Svelte Reactivity
@@ -220,8 +232,8 @@ LoadingStateMachine inherits the `onenter` callback and Svelte reactivity integr
 ```javascript
 const loader = new LoadingStateMachine();
 
-loader.onenter = (state) => {
-  switch (state) {
+loader.onenter = (currentState) => {
+  switch (currentState) {
     case STATE_LOADING:
       this.#startLoading(); // Start async process immediately
       break;
@@ -267,8 +279,8 @@ export default class MultiSourceLoader {
 
   constructor() {
     // Handle immediate loading state actions
-    this.#loader.onenter = (state) => {
-      switch (state) {
+    this.#loader.onenter = (currentState) => {
+      switch (currentState) {
         case STATE_LOADING:
           this.#startAllSources();
           break;
@@ -282,7 +294,7 @@ export default class MultiSourceLoader {
           this.#handleTimeout();
           break;
       }
-      this.state = state;
+      this.state = currentState;
     };
 
     // Monitor reactive completion
@@ -313,14 +325,14 @@ export default class MultiSourceLoader {
     LOAD,
     LOADED,
     ERROR,
-    CANCEL
+    ABORT
   } from '$lib/state/machines.js';
   
   const loader = new LoadingStateMachine();
   let data = $state(null);
   
-  loader.onenter = (state) => {
-    if (state === STATE_LOADING) {
+  loader.onenter = (currentState) => {
+    if (currentState === STATE_LOADING) {
       loadData();
     }
   };
@@ -351,7 +363,7 @@ export default class MultiSourceLoader {
 {/if}
 ```
 
-### Advanced Component with Cancellation
+### Advanced Component with Abort Handling
 
 ```javascript
 <script>
@@ -360,24 +372,29 @@ export default class MultiSourceLoader {
     STATE_INITIAL,
     STATE_LOADING,
     STATE_LOADED,
-    STATE_CANCELLED,
+    STATE_ABORTING,
+    STATE_ABORTED,
     STATE_ERROR,
     LOAD,
     LOADED,
     ERROR,
-    CANCEL
+    ABORT,
+    ABORTED
   } from '$lib/state/machines.js';
   
   const loader = new LoadingStateMachine();
   let abortController = null;
   
-  loader.onenter = (state) => {
-    switch (state) {
+  loader.onenter = (currentState) => {
+    switch (currentState) {
       case STATE_LOADING:
         startLoad();
         break;
-      case STATE_CANCELLED:
+      case STATE_ABORTING:
+        // Start abort process
         abortController?.abort();
+        // Simulate abort completion
+        setTimeout(() => loader.send(ABORTED), 100);
         break;
     }
   };
@@ -393,7 +410,7 @@ export default class MultiSourceLoader {
       loader.send(LOADED);
     } catch (error) {
       if (error.name === 'AbortError') {
-        // Request was cancelled, machine already in cancelled state
+        // Request was aborted, machine will transition to STATE_ABORTED
       } else {
         loader.send(ERROR, error);
       }
@@ -405,13 +422,15 @@ export default class MultiSourceLoader {
   {#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>
+    <button onclick={() => loader.send(ABORT)}>Abort Loading</button>
     <div>Loading data...</div>
+  {:else if loader.current === STATE_ABORTING}
+    <div>Aborting...</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>
+  {:else if loader.current === STATE_ABORTED}
+    <div>Loading aborted</div>
     <button onclick={() => loader.send(LOAD)}>Try Again</button>
   {:else if loader.current === STATE_ERROR}
     <div>Error: {loader.error.message}</div>
@@ -426,8 +445,8 @@ export default class MultiSourceLoader {
 
 ```javascript
 // ✅ Good - use onenter for reliable side effects
-loader.onenter = (state) => {
-  if (state === STATE_LOADING) {
+loader.onenter = (currentState) => {
+  if (currentState === STATE_LOADING) {
     analytics.track('loading_started');
   }
 };
@@ -443,14 +462,17 @@ $effect(() => {
 ### 2. Handle All Error States
 
 ```javascript
-loader.onenter = (state) => {
-  switch (state) {
+loader.onenter = (currentState) => {
+  switch (currentState) {
     case STATE_ERROR:
       showErrorToast(loader.error.message);
       logError(loader.error);
       break;
-    case STATE_CANCELLED:
-      showMessage('Operation cancelled');
+    case STATE_ABORTING:
+      showMessage('Aborting operation...');
+      break;
+    case STATE_ABORTED:
+      showMessage('Operation aborted');
       break;
   }
 };
@@ -459,14 +481,15 @@ loader.onenter = (state) => {
 ### 3. Implement Proper Cleanup
 
 ```javascript
-loader.onenter = (state) => {
-  switch (state) {
+loader.onenter = (currentState) => {
+  switch (currentState) {
     case STATE_LOADING:
       showProgressBar();
       break;
     case STATE_LOADED:
     case STATE_ERROR:
-    case STATE_CANCELLED:
+    case STATE_ABORTING:
+    case STATE_ABORTED:
       hideProgressBar();
       break;
     case STATE_UNLOADING:
@@ -500,8 +523,8 @@ loader.send('load');
 const resourceLoader = new LoadingStateMachine();
 let resource = null;
 
-resourceLoader.onenter = async (state) => {
-  switch (state) {
+resourceLoader.onenter = async (currentState) => {
+  switch (currentState) {
     case STATE_LOADING:
       try {
         resource = await loadResource();
@@ -529,8 +552,8 @@ const retryLoader = new LoadingStateMachine();
 let retryCount = 0;
 const maxRetries = 3;
 
-retryLoader.onenter = async (state) => {
-  switch (state) {
+retryLoader.onenter = async (currentState) => {
+  switch (currentState) {
     case STATE_LOADING:
       try {
         await performLoad();
@@ -576,7 +599,8 @@ import {
   STATE_LOADING,
   STATE_LOADED,
   STATE_UNLOADING,
-  STATE_CANCELLED,
+  STATE_ABORTING,
+  STATE_ABORTED,
   STATE_ERROR,
   STATE_TIMEOUT,
   
@@ -584,7 +608,8 @@ import {
   LOAD,
   LOADED,
   UNLOAD,
-  CANCEL,
+  ABORT,
+  ABORTED,
   ERROR,
   INITIAL,
   TIMEOUT

package/dist/state/machines/loading-state-machine/constants.d.ts

@@ -2,12 +2,14 @@ export const STATE_INITIAL: "initial";
 export const STATE_LOADING: "loading";
 export const STATE_UNLOADING: "unloading";
 export const STATE_LOADED: "loaded";
-export const STATE_CANCELLED: "cancelled";
+export const STATE_ABORTING: "aborting";
+export const STATE_ABORTED: "aborted";
 export const STATE_ERROR: "error";
 export const STATE_TIMEOUT: "timeout";
 export const INITIAL: "initial";
 export const LOAD: "load";
-export const CANCEL: "cancel";
+export const ABORT: "abort";
+export const ABORTED: "aborted";
 export const ERROR: "error";
 export const LOADED: "loaded";
 export const UNLOAD: "unload";

package/dist/state/machines/loading-state-machine/constants.js

@@ -3,7 +3,8 @@ export const STATE_LOADING = 'loading';
 export const STATE_UNLOADING = 'unloading';
 export const STATE_LOADED = 'loaded';
 
-export const STATE_CANCELLED = 'cancelled';
+export const STATE_ABORTING = 'aborting';
+export const STATE_ABORTED = 'aborted';
 export const STATE_ERROR = 'error';
 export const STATE_TIMEOUT = 'timeout';
 
@@ -11,7 +12,8 @@ export const STATE_TIMEOUT = 'timeout';
 
 export const INITIAL = 'initial';
 export const LOAD = 'load';
-export const CANCEL = 'cancel';
+export const ABORT = 'abort';
+export const ABORTED = 'aborted';
 export const ERROR = 'error';
 export const LOADED = 'loaded';
 export const UNLOAD = 'unload';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.4.25",
+	"version": "0.4.27",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"