@hkdigital/lib-core 0.4.24 → 0.4.26

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

@@ -8,7 +8,7 @@ A specialized finite state machine designed for managing loading operations with
 
 ## States
 
-The machine defines six primary states:
+The machine defines seven primary states:
 
 - **`INITIAL`** - Starting state, ready to begin loading
 - **`LOADING`** - Currently loading data or resources
@@ -16,6 +16,7 @@ The machine defines six primary states:
 - **`UNLOADING`** - Cleaning up or releasing resources
 - **`CANCELLED`** - Loading operation was cancelled
 - **`ERROR`** - An error occurred during loading
+- **`TIMEOUT`** - Loading operation exceeded time limit
 
 ## Events
 
@@ -26,6 +27,7 @@ Available events to trigger state transitions:
 - **`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
@@ -65,35 +67,36 @@ console.log(loader.current); // STATE_LOADED
 
 ```
 INITIAL → LOADING
-LOADING → LOADED | CANCELLED | ERROR
+LOADING → LOADED | CANCELLED | ERROR | TIMEOUT
 LOADED → LOADING | UNLOADING
 UNLOADING → INITIAL | ERROR
 CANCELLED → LOADING | UNLOADING
 ERROR → LOADING | UNLOADING
+TIMEOUT → LOADING | UNLOADING
 ```
 
 ### Transition Diagram
 
 ```
-    ┌─────────┐
-    │ INITIAL │
-    └────┬────┘
-         │ LOAD
-         ▼
+        ┌─────────┐
+        │ INITIAL │
+        └────┬────┘
+             │ LOAD
+             ▼
     ┌─────────┐    CANCEL     ┌───────────┐
     │ LOADING │──────────────→│ CANCELLED │
     └────┬────┘               └─────┬─────┘
          │                          │
-    LOADED│  ERROR             LOAD │ UNLOAD
-         │     │                    │    │
-         ▼     ▼                    ▼    ▼
-    ┌────────┐ ┌───────┐        ┌──────────┐
-    │ LOADED │ │ ERROR │        │UNLOADING │
-    └────┬───┘ └───┬───┘        └────┬─────┘
-         │         │                 │
-   UNLOAD│    LOAD │ UNLOAD   INITIAL│ ERROR
-         ▼         ▼                 ▼
-    ┌──────────┐◄────────────────────┘
+    LOADED│  ERROR  TIMEOUT    LOAD │ UNLOAD
+         │     │       │            │    │
+         ▼     ▼       ▼            ▼    ▼
+    ┌────────┐ ┌───────┐ ┌─────────┐ ┌──────────┐
+    │ LOADED │ │ ERROR │ │ TIMEOUT │ │UNLOADING │
+    └────┬───┘ └───┬───┘ └────┬────┘ └────┬─────┘
+         │         │          │           │
+   UNLOAD│    LOAD │ UNLOAD  LOAD│ UNLOAD INITIAL│ ERROR
+         ▼         ▼            ▼           ▼
+    ┌──────────┐◄──────────────────────────┘
     │UNLOADING │
     └──────────┘
 ```
@@ -105,8 +108,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();
@@ -119,6 +122,10 @@ loader.onenter = (state) => {
       console.log('Loading failed');
       showError();
       break;
+    case STATE_TIMEOUT:
+      console.log('Loading timed out');
+      showRetryOption();
+      break;
   }
 };
 ```
@@ -134,8 +141,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
 };
 ```
 
@@ -167,6 +174,42 @@ if (loader.current === '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 = (currentState) => {
+  switch (currentState) {
+    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). 
@@ -177,8 +220,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;
@@ -224,8 +267,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;
@@ -235,8 +278,11 @@ export default class MultiSourceLoader {
         case STATE_ERROR:
           this.#handleLoadError();
           break;
+        case STATE_TIMEOUT:
+          this.#handleTimeout();
+          break;
       }
-      this.state = state;
+      this.state = currentState;
     };
 
     // Monitor reactive completion
@@ -273,8 +319,8 @@ export default class MultiSourceLoader {
   const loader = new LoadingStateMachine();
   let data = $state(null);
   
-  loader.onenter = (state) => {
-    if (state === STATE_LOADING) {
+  loader.onenter = (currentState) => {
+    if (currentState === STATE_LOADING) {
       loadData();
     }
   };
@@ -325,8 +371,8 @@ export default class MultiSourceLoader {
   const loader = new LoadingStateMachine();
   let abortController = null;
   
-  loader.onenter = (state) => {
-    switch (state) {
+  loader.onenter = (currentState) => {
+    switch (currentState) {
       case STATE_LOADING:
         startLoad();
         break;
@@ -380,8 +426,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');
   }
 };
@@ -397,8 +443,8 @@ $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);
@@ -413,8 +459,8 @@ loader.onenter = (state) => {
 ### 3. Implement Proper Cleanup
 
 ```javascript
-loader.onenter = (state) => {
-  switch (state) {
+loader.onenter = (currentState) => {
+  switch (currentState) {
     case STATE_LOADING:
       showProgressBar();
       break;
@@ -454,8 +500,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();
@@ -483,8 +529,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();
@@ -532,6 +578,7 @@ import {
   STATE_UNLOADING,
   STATE_CANCELLED,
   STATE_ERROR,
+  STATE_TIMEOUT,
   
   // Events
   LOAD,
@@ -539,6 +586,7 @@ import {
   UNLOAD,
   CANCEL,
   ERROR,
-  INITIAL
+  INITIAL,
+  TIMEOUT
 } from './constants.js';
 ```

package/dist/state/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";

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

@@ -5,6 +5,7 @@ export const STATE_LOADED = 'loaded';
 
 export const STATE_CANCELLED = 'cancelled';
 export const STATE_ERROR = 'error';
+export const STATE_TIMEOUT = 'timeout';
 
 // > Signals
 
@@ -14,3 +15,4 @@ export const CANCEL = 'cancel';
 export const ERROR = 'error';
 export const LOADED = 'loaded';
 export const UNLOAD = 'unload';
+export const TIMEOUT = 'timeout';

package/package.json

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

package/dist/logging/internal/adapters/pino.js__

@@ -1,260 +0,0 @@
-/**
- * Pino adapter for server-side logging
- */
-import pino from 'pino';
-import { dev } from '$app/environment';
-
-import {
-  detectErrorMeta,
-  findRelevantFrameIndex,
-  formatErrorDisplay
-} from './formatting.js';
-
-/**
- * Pino adapter that bridges Logger events to pino
- */
-export class PinoAdapter {
-  #projectRoot = null;
-
-  /**
-   * Create a new PinoAdapter
-   *
-   * @param {Object} [options] - Pino configuration options
-   */
-  constructor(options = {}) {
-    // Determine project root once for stack trace cleaning
-    this.#projectRoot = import.meta.env.VITE_PROJECT_ROOT || process.cwd();
-    const baseOptions = {
-      serializers: {
-        errors: (err) => {
-
-          /** @type {import('./typedef').ErrorSummary[]} */
-          const chain = [];
-          let loggedAt = null;
-
-          let current = err;
-          let isFirst = true;
-
-          while (current && current instanceof Error) {
-            // Check if this is the first error and it's a LoggerError - extract logging context
-            if (isFirst && current.name === 'LoggerError') {
-              if (current.stack) {
-                const cleanedStackString = this.#cleanStackTrace(current.stack);
-                const cleanedStackArray = cleanedStackString
-                  .split('\n')
-                  .map((line) => line.trim())
-                  .filter(
-                    (line) =>
-                      line && line !== current.name + ': ' + current.message
-                  );
-
-                // For LoggerError, we know it's a logger.error call, so find the relevant frame
-                const loggerErrorIndex = cleanedStackArray.findIndex(frame =>
-                  (frame.includes('Logger.error') && frame.includes('logger/Logger.js')) ||
-                  (frame.includes('error@') && frame.includes('logger/Logger.js'))
-                );
-
-                if (loggerErrorIndex >= 0 && loggerErrorIndex + 1 < cleanedStackArray.length) {
-                  const relevantFrame = cleanedStackArray[loggerErrorIndex + 1];
-
-                  // Extract function name from the relevant frame
-                  // const functionName = parseFunctionName(relevantFrame);
-
-                  // const errorType = functionName ? `logger.error in ${functionName}` : 'logger.error';
-                  loggedAt = relevantFrame.slice(3); // remove "at "
-                }
-              }
-
-              // Skip the LoggerError and move to the actual error
-              current = current.cause;
-              isFirst = false;
-              continue;
-            }
-            /** @type {import('./typedef').ErrorSummary} */
-            const serialized = {
-              name: current.name,
-              message: current.message
-            };
-
-            // Add error metadata for structured logging and terminal display
-            if (current.stack) {
-              // Convert cleaned stack string to array format expected by formatting functions
-              const cleanedStackString = this.#cleanStackTrace(current.stack);
-              const cleanedStackArray = cleanedStackString
-                .split('\n')
-                .map((line) => line.trim())
-                .filter(
-                  (line) =>
-                    line && line !== current.name + ': ' + current.message
-                );
-
-              const errorMeta = detectErrorMeta(current, cleanedStackArray);
-              const relevantFrameIndex = findRelevantFrameIndex(
-                current,
-                cleanedStackArray
-              );
-
-              serialized.meta = errorMeta;
-              serialized.errorType = formatErrorDisplay(errorMeta);
-
-              // Include stack frames for terminal display
-              serialized.stackFrames = cleanedStackArray
-                .slice(0, 9)
-                .map((frame, index) => {
-                  const marker = index === relevantFrameIndex ? '→' : ' ';
-
-                  return `${marker} ${frame}`;
-                });
-            }
-
-            // Include HttpError-specific properties
-            const httpError = /** @type {import('$lib/network/errors.js').HttpError} */ (current);
-            if (httpError.status !== undefined) {
-              serialized.status = httpError.status;
-            }
-            if (httpError.details !== undefined) {
-              serialized.details = httpError.details;
-            }
-
-            chain.push(serialized);
-            current = current.cause;
-            isFirst = false;
-          }
-
-          return loggedAt ? { chain, loggedAt } : chain;
-        }
-      }
-    };
-
-    // Add error handling for missing pino-pretty in dev
-    if ( dev) {
-      const devOptions = {
-        level: 'debug',
-        transport: {
-          target: 'pino-pretty',
-          options: {
-            colorize: true,
-            ignore: 'hostname,pid'
-          }
-        }
-      };
-
-      try {
-        this.pino = pino({ ...baseOptions, ...devOptions, ...options });
-      } catch (error) {
-        if (
-          error.message.includes('Cannot find module') &&
-          error.message.includes('pino-pretty')
-        ) {
-          const errorMessage = `
-╭─────────────────────────────────────────────────────────────╮
-│                     Missing Dependency                      │
-├─────────────────────────────────────────────────────────────┤
-│  'pino-pretty' is required for development logging          │
-│  Install it with: pnpm add -D pino-pretty                   │
-╰─────────────────────────────────────────────────────────────╯`;
-          console.error(errorMessage);
-          throw new Error('pino-pretty is required for development mode');
-        }
-        throw error;
-      }
-    } else {
-      this.pino = pino({ ...baseOptions, ...options });
-    }
-  }
-
-  /**
-   * Clean stack trace by removing project root path and simplifying node_modules
-   *
-   * @param {string} stack - Original stack trace
-   * @returns {string} Cleaned stack trace
-   */
-  #cleanStackTrace(stack) {
-    if (!stack || !this.#projectRoot) {
-      return stack;
-    }
-
-    let cleaned = stack;
-
-    // Escape special regex characters in the project root path
-    const escapedRoot = this.#projectRoot.replace(
-      /[.*+?^${}()|[\]\\]/g,
-      '\\$&'
-    );
-
-    // Replace project root path with relative path, handling file:// protocol
-    // Match both regular paths and file:// URLs
-    const rootRegex = new RegExp(
-      `(\\s+at\\s+.*\\()(file://)?${escapedRoot}[\\/\\\\]`,
-      'g'
-    );
-    cleaned = cleaned.replace(rootRegex, '$1');
-
-    // Simplify pnpm paths: node_modules/.pnpm/package@version_deps/node_modules/package
-    // becomes: node_modules/package
-    const pnpmRegex =
-      /node_modules\/\.pnpm\/([^@\/]+)@[^\/]+\/node_modules\/\1/g;
-    cleaned = cleaned.replace(pnpmRegex, 'node_modules/$1');
-
-    // Also handle cases where the package name might be different in the final path
-    const pnpmRegex2 = /node_modules\/\.pnpm\/[^\/]+\/node_modules\/([^\/]+)/g;
-    cleaned = cleaned.replace(pnpmRegex2, 'node_modules/$1');
-
-    return cleaned;
-  }
-
-  /**
-   * Handle log events from Logger
-   *
-   * @param {Object} logEvent - Log event from Logger
-   */
-  handleLog(logEvent) {
-    const { level, message, details, source, timestamp } = logEvent;
-
-    const logData = {
-      source,
-      timestamp
-    };
-
-    // Check if details contains an error and promote it to err property for pino serializer
-    if (details) {
-      if (details instanceof Error) {
-        // details is directly an error
-        logData.err = details;
-      } else if (details.error instanceof Error) {
-        // details has an error property
-        logData.err = details.error;
-        // Include other details except the error
-        // eslint-disable-next-line no-unused-vars
-        const { error, ...otherDetails } = details;
-        if (Object.keys(otherDetails).length > 0) {
-          logData.details = otherDetails;
-        }
-      } else {
-        // No error found in details, include all details
-        logData.details = details;
-      }
-    }
-
-    // Check if we have loggedAt info from the serializer
-    if (logData.err && typeof logData.err === 'object' && logData.err.loggedAt) {
-      logData.loggedAt = logData.err.loggedAt;
-      logData.err = logData.err.chain;
-    }
-
-    this.pino[level](logData, message);
-  }
-
-  /**
-   * Create a child logger with additional context
-   *
-   * @param {Object} context - Additional context data
-   * @returns {PinoAdapter} New adapter instance with context
-   */
-  child(context) {
-    const childPino = this.pino.child(context);
-    const adapter = new PinoAdapter();
-    adapter.pino = childPino;
-    return adapter;
-  }
-}