@hkdigital/lib-core 0.4.25 → 0.4.27

package/dist/state/machines/finite-state-machine/FiniteStateMachine.svelte.js

@@ -8,7 +8,7 @@ import { isTestEnv } from '../../../util/env.js';
 import EventEmitter from '../../../generic/events/classes/EventEmitter.js';
 import { ENTER, EXIT } from './constants.js';
 
-/** @typedef {import('./typedef.js').StateTransitionMetadata} StateTransitionMetadata */
+/** @typedef {import('./typedef.js').TransitionData} TransitionData */
 /** @typedef {import('./typedef.js').OnEnterCallback} OnEnterCallback */
 /** @typedef {import('./typedef.js').OnExitCallback} OnExitCallback */
 
@@ -57,17 +57,17 @@ export default class FiniteStateMachine extends EventEmitter {
     this.states = states;
 
     // synthetically trigger _enter for the initial state.
-    const initialMetadata = {
+    const initialTransitionData = {
       from: null,
       to: initial,
       event: null,
       args: []
     };
 
-    this.#executeAction('_enter', initialMetadata);
+    this.#executeAction('_enter', initialTransitionData);
 
     // Emit ENTER event for external listeners for initial state
-    this.emit(ENTER, { state: initial, metadata: initialMetadata });
+    this.emit(ENTER, { state: initial, transition: initialTransitionData });
   }
 
   /**
@@ -78,24 +78,24 @@ export default class FiniteStateMachine extends EventEmitter {
    * @param {any[]} [args]
    */
   #transition(newState, event, args) {
-    /** @type {StateTransitionMetadata} */
-    const metadata = { from: this.#current, to: newState, event, args };
+    /** @type {TransitionData} */
+    const transition = { from: this.#current, to: newState, event, args };
 
     // Call onexit callback before leaving current state
-    this.onexit?.(this.#current, metadata);
+    this.onexit?.(this.#current, transition);
 
     // Emit EXIT event for external listeners
-    this.emit(EXIT, { state: this.#current, metadata });
+    this.emit(EXIT, { state: this.#current, transition });
 
-    this.#executeAction('_exit', metadata);
+    this.#executeAction('_exit', transition);
     this.#current = newState;
-    this.#executeAction('_enter', metadata);
+    this.#executeAction('_enter', transition);
 
     // Emit ENTER event for external listeners
-    this.emit(ENTER, { state: newState, metadata });
+    this.emit(ENTER, { state: newState, transition });
 
     // Call onenter callback after state change
-    this.onenter?.(newState, metadata);
+    this.onenter?.(newState, transition);
   }
 
   /**
@@ -116,7 +116,7 @@ export default class FiniteStateMachine extends EventEmitter {
           if (isLifecycleFnMeta(args[0])) {
             return action(args[0]);
           } else {
-            throw new Error(`Invalid metadata passed to lifecycle function`);
+            throw new Error(`Invalid transition data passed to lifecycle function`);
           }
 
         // Normal state events

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

@@ -56,16 +56,16 @@ Each state can define:
 ```javascript
 const machine = new FiniteStateMachine('idle', {
   idle: {
-    _enter: (metadata) => {
+    _enter: (transition) => {
       console.log('Entered idle state');
     },
-    _exit: (metadata) => {
+    _exit: (transition) => {
       console.log('Leaving idle state');
     },
     start: 'running'
   },
   running: {
-    _enter: (metadata) => {
+    _enter: (transition) => {
       console.log('Started running');
     },
     stop: 'idle'
@@ -73,14 +73,14 @@ const machine = new FiniteStateMachine('idle', {
 });
 ```
 
-## Callback Metadata
+## Callback TransitionData
 
-Enter and exit callbacks receive metadata about the transition:
+Enter and exit callbacks receive transition data about the state change:
 
 ```javascript
-/** @typedef {import('./typedef.js').StateTransitionMetadata} StateTransitionMetadata */
+/** @typedef {import('./typedef.js').TransitionData} TransitionData */
 
-// Metadata structure:
+// TransitionData structure:
 {
   from: 'previousState',    // State being exited
   to: 'newState',          // State being entered
@@ -94,18 +94,18 @@ Enter and exit callbacks receive metadata about the transition:
 For better type safety, import the type definitions:
 
 ```javascript
-/** @typedef {import('./typedef.js').StateTransitionMetadata} StateTransitionMetadata */
+/** @typedef {import('./typedef.js').TransitionData} TransitionData */
 /** @typedef {import('./typedef.js').OnEnterCallback} OnEnterCallback */
 /** @typedef {import('./typedef.js').OnExitCallback} OnExitCallback */
 
 /** @type {OnEnterCallback} */
-const handleEnter = (state, metadata) => {
-  console.log(`Entering ${state} from ${metadata.from}`);
+const handleEnter = (currentState, transition) => {
+  console.log(`Entering ${currentState} from ${transition.from}`);
 };
 
 /** @type {OnExitCallback} */
-const handleExit = (state, metadata) => {
-  console.log(`Leaving ${state} to ${metadata.to}`);
+const handleExit = (currentState, transition) => {
+  console.log(`Leaving ${currentState} to ${transition.to}`);
 };
 
 machine.onenter = handleEnter;
@@ -209,8 +209,8 @@ const machine = new FiniteStateMachine('idle', {
   error: { retry: 'loading', reset: 'idle' }
 });
 
-machine.onexit = (state, metadata) => {
-  switch (state) {
+machine.onexit = (currentState, transition) => {
+  switch (currentState) {
     case 'loading':
       console.log('Leaving loading state...');
       // Cancel ongoing requests
@@ -224,8 +224,8 @@ machine.onexit = (state, metadata) => {
   }
 };
 
-machine.onenter = (state, metadata) => {
-  switch (state) {
+machine.onenter = (currentState, transition) => {
+  switch (currentState) {
     case 'loading':
       console.log('Started loading...');
       showSpinner();
@@ -236,7 +236,7 @@ machine.onenter = (state, metadata) => {
       break;
     case 'error':
       console.log('Loading failed');
-      showError(metadata.args[0]);
+      showError(transition.args[0]);
       break;
   }
 };
@@ -264,8 +264,8 @@ const machine = new FiniteStateMachine('idle', {
   }
 });
 
-machine.onexit = (state) => console.log(`3. onexit ${state}`);
-machine.onenter = (state) => console.log(`6. onenter ${state}`);
+machine.onexit = (currentState) => console.log(`3. onexit ${currentState}`);
+machine.onenter = (currentState) => console.log(`6. onenter ${currentState}`);
 
 // Initial state triggers _enter and onenter
 // Output:
@@ -313,8 +313,8 @@ machine.onexit = (state) => {
   }
 };
 
-machine.onenter = (state) => {
-  switch (state) {
+machine.onenter = (label) => {
+  switch (label) {
     case 'loading':
       this.#startProcess(); // Start async process immediately
       break;
@@ -381,8 +381,8 @@ export default class TaskProcessor {
 
   constructor() {
     // onexit: Handle cleanup when leaving states
-    this.#machine.onexit = (state) => {
-      switch (state) {
+    this.#machine.onexit = (currentState) => {
+      switch (currentState) {
         case 'processing':
           this.#cancelTasks(); // Cancel ongoing tasks if interrupted
           break;
@@ -390,8 +390,8 @@ export default class TaskProcessor {
     };
 
     // onenter: Handle immediate state actions
-    this.#machine.onenter = (state) => {
-      switch (state) {
+    this.#machine.onenter = (currentState) => {
+      switch (currentState) {
         case 'processing':
           this.#startAllTasks(); // Start processing immediately
           break;
@@ -399,7 +399,7 @@ export default class TaskProcessor {
           this.#notifyComplete(); // Cleanup/notify when done
           break;
       }
-      this.state = state;
+      this.state = currentState;
     };
 
     // $effect: Monitor reactive completion
@@ -435,8 +435,8 @@ export default class TaskProcessor {
   });
 
   // Handle state-specific actions
-  machine.onexit = (state) => {
-    switch (state) {
+  machine.onexit = (currentState) => {
+    switch (currentState) {
       case 'loading':
         // Cancel any ongoing requests
         cancelRequests();
@@ -444,8 +444,8 @@ export default class TaskProcessor {
     }
   };
 
-  machine.onenter = (state) => {
-    switch (state) {
+  machine.onenter = (currentState) => {
+    switch (currentState) {
       case 'loading':
         loadData();
         break;
@@ -526,7 +526,7 @@ const auth = new FiniteStateMachine('anonymous', {
     failure: 'anonymous'
   },
   authenticated: {
-    _enter: (meta) => console.log('Welcome!'),
+    _enter: (transition) => console.log('Welcome!'),
     logout: 'anonymous',
     expire: 'anonymous'
   }

package/dist/state/machines/finite-state-machine/typedef.d.ts

@@ -1,7 +1,7 @@
 /**
  * Metadata object passed to state transition callbacks
  */
-export type StateTransitionMetadata = {
+export type TransitionData = {
     /**
      * - The state being exited
      */
@@ -22,8 +22,8 @@ export type StateTransitionMetadata = {
 /**
  * Callback function called when entering a state
  */
-export type OnEnterCallback = (arg0: string, arg1: StateTransitionMetadata) => void;
+export type OnEnterCallback = (currentState: string, transition: TransitionData) => void;
 /**
  * Callback function called when exiting a state
  */
-export type OnExitCallback = (arg0: string, arg1: StateTransitionMetadata) => void;
+export type OnExitCallback = (currentState: string, transition: TransitionData) => void;

package/dist/state/machines/finite-state-machine/typedef.js

@@ -5,24 +5,30 @@
 /**
  * Metadata object passed to state transition callbacks
  *
- * @typedef {object} StateTransitionMetadata
+ * @typedef {object} TransitionData
  * @property {string} from - The state being exited
  * @property {string} to - The state being entered
  * @property {string} event - The event that triggered the transition
  * @property {any[]} args - Arguments passed to the send() method
  */
 
-/**
- * Callback function called when entering a state
- *
- * @typedef {function(string, StateTransitionMetadata): void} OnEnterCallback
- */
+  /**
+   * Callback function called when entering a state
+   *
+   * @callback OnEnterCallback
+   * @param {string} currentState - The state being entered
+   * @param {TransitionData} transition - Details about the transition
+   * @returns {void}
+   */
 
-/**
- * Callback function called when exiting a state
- *
- * @typedef {function(string, StateTransitionMetadata): void} OnExitCallback
- */
+  /**
+   * Callback function called when exiting a state
+   *
+   * @callback OnExitCallback
+   * @param {string} currentState - The state being exited
+   * @param {TransitionData} transition - Details about the transition
+   * @returns {void}
+   */
 
-// Export types for external use (this is just for JSDoc, no actual exports needed)
+// Export types for JSdoc
 export {};

package/dist/state/machines/loading-state-machine/LoadingStateMachine.svelte.d.ts

@@ -10,13 +10,13 @@ export default class LoadingStateMachine extends FiniteStateMachine {
      * - Only valid when currently loading
      * - Useful for external timeout management
      */
-    doTimeout(): void;
+    timeout(): void;
     /**
-     * Transition to cancelled state
+     * Transition to aborting state
      * - Only valid when currently loading
-     * - Useful for external cancellation management
+     * - Useful for external abort management
      */
-    doCancel(): void;
+    abort(): void;
     #private;
 }
 import FiniteStateMachine from '../finite-state-machine/FiniteStateMachine.svelte.js';

package/dist/state/machines/loading-state-machine/LoadingStateMachine.svelte.js

@@ -8,14 +8,16 @@ import {
   STATE_LOADING,
   STATE_UNLOADING,
   STATE_LOADED,
-  STATE_CANCELLED,
+  STATE_ABORTING,
+  STATE_ABORTED,
   STATE_ERROR,
   STATE_TIMEOUT,
 
   // > Signals
   INITIAL,
   LOAD,
-  CANCEL,
+  ABORT,
+  ABORTED,
   ERROR,
   LOADED,
   UNLOAD,
@@ -41,7 +43,7 @@ export default class LoadingStateMachine extends FiniteStateMachine {
         // _enter: () => {
         //   console.log('LoadingStateMachine: enter LOADING');
         // },
-        [CANCEL]: STATE_CANCELLED,
+        [ABORT]: STATE_ABORTING,
         [ERROR]: STATE_ERROR,
         [LOADED]: STATE_LOADED,
         [TIMEOUT]: STATE_TIMEOUT
@@ -57,7 +59,11 @@ export default class LoadingStateMachine extends FiniteStateMachine {
         [ERROR]: STATE_ERROR,
         [INITIAL]: STATE_INITIAL
       },
-      [STATE_CANCELLED]: {
+      [STATE_ABORTING]: {
+        [ERROR]: STATE_ERROR,
+        [ABORTED]: STATE_ABORTED
+      },
+      [STATE_ABORTED]: {
         [LOAD]: STATE_LOADING,
         [UNLOAD]: STATE_UNLOADING
       },
@@ -99,16 +105,16 @@ export default class LoadingStateMachine extends FiniteStateMachine {
    * - Only valid when currently loading
    * - Useful for external timeout management
    */
-  doTimeout() {
+  timeout() {
     this.send(TIMEOUT);
   }
 
   /**
-   * Transition to cancelled state
+   * Transition to aborting state
    * - Only valid when currently loading
-   * - Useful for external cancellation management
+   * - Useful for external abort management
    */
-  doCancel() {
-    this.send(CANCEL);
+  abort() {
+    this.send(ABORT);
   }
 }