@hkdigital/lib-core 0.5.86 → 0.5.88

package/dist/services/service-base/ServiceBase.js

@@ -152,7 +152,8 @@ export class ServiceBase extends EventEmitter {
     try {
       this._setTargetState(wasRunning ? STATE_RUNNING : STATE_CONFIGURED);
       this._setState(STATE_CONFIGURING);
-      this.logger.debug('Configuring service', { config });
+
+      this.logger.debug('Configuring service', { keys: Object.keys(config ?? {})});
 
       await this._configure(config, this.#lastConfig);
       this.#lastConfig = config;
@@ -160,9 +161,10 @@ export class ServiceBase extends EventEmitter {
       this._setState(wasRunning ? STATE_RUNNING : STATE_CONFIGURED);
       this.logger.info('Service configured');
       return { ok: true };
-    } catch (error) {
-      this._setError('configuration', /** @type {Error} */ (error));
-      return { ok: false, error: this.error };
+    } catch (thing) {
+      const error = /** @type {Error} */ (thing);
+      this._setError('configuration', error);
+      return { ok: false, error };
     }
   }
 

package/dist/state/machines/page-machine/PageMachine.svelte.d.ts

@@ -189,6 +189,138 @@ export default class PageMachine {
      * @returns {number} Number of data entries
      */
     get dataSize(): number;
+    /**
+     * Set a dev data property value
+     *
+     * Automatically reactive - effects watching this key will re-run.
+     * Only available in dev mode - no-op in production.
+     *
+     * @param {string} key - Property key (use KEY_DEV_ constant)
+     * @param {any} value - Property value
+     *
+     * @example
+     * ```javascript
+     * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
+     * const KEY_DEV_SKIP_ANIMATIONS = 'dev-skip-animations';
+     *
+     * machine.setDevData(KEY_DEV_AUTO_NAVIGATION, true);
+     * machine.setDevData(KEY_DEV_SKIP_ANIMATIONS, false);
+     * ```
+     */
+    setDevData(key: string, value: any): void;
+    /**
+     * Get a dev data property value
+     *
+     * Automatically reactive - creates a dependency on this specific key.
+     * Only available in dev mode - returns undefined in production.
+     *
+     * @param {string} key - Property key (use KEY_DEV_ constant)
+     *
+     * @returns {any} Property value or undefined
+     *
+     * @example
+     * ```javascript
+     * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
+     *
+     * // Reactive - re-runs only when KEY_DEV_AUTO_NAVIGATION changes
+     * $effect(() => {
+     *   const autoNav = machine.getDevData(KEY_DEV_AUTO_NAVIGATION);
+     *   console.log('Auto-navigation:', autoNav);
+     * });
+     * ```
+     */
+    getDevData(key: string): any;
+    /**
+     * Get all dev data properties as plain object
+     *
+     * Note: Returns a snapshot (plain object), not reactive.
+     * Only available in dev mode - returns empty object in production.
+     *
+     * @returns {Record<string, any>} Plain object with all dev data
+     *
+     * @example
+     * ```javascript
+     * const allDevData = machine.getAllDevData();
+     * console.log('Dev settings:', allDevData);
+     * ```
+     */
+    getAllDevData(): Record<string, any>;
+    /**
+     * Update multiple dev data properties at once
+     *
+     * Each property update triggers fine-grained reactivity.
+     * Only available in dev mode - no-op in production.
+     *
+     * @param {Record<string, any>} dataUpdates
+     *   Object with key-value pairs (use KEY_DEV_ constants for keys)
+     *
+     * @example
+     * ```javascript
+     * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
+     * const KEY_DEV_SKIP_ANIMATIONS = 'dev-skip-animations';
+     *
+     * machine.updateDevData({
+     *   [KEY_DEV_AUTO_NAVIGATION]: true,
+     *   [KEY_DEV_SKIP_ANIMATIONS]: false
+     * });
+     * ```
+     */
+    updateDevData(dataUpdates: Record<string, any>): void;
+    /**
+     * Delete a dev data property
+     *
+     * Only available in dev mode - no-op in production.
+     *
+     * @param {string} key - Property key to delete (use KEY_DEV_ constant)
+     *
+     * @returns {boolean} True if the key existed and was deleted
+     *
+     * @example
+     * ```javascript
+     * const KEY_DEV_TEMP_FLAG = 'dev-temp-flag';
+     *
+     * machine.deleteDevData(KEY_DEV_TEMP_FLAG);
+     * ```
+     */
+    deleteDevData(key: string): boolean;
+    /**
+     * Check if dev data property exists
+     *
+     * Only available in dev mode - returns false in production.
+     *
+     * @param {string} key - Property key to check (use KEY_DEV_ constant)
+     *
+     * @returns {boolean} True if the key exists
+     *
+     * @example
+     * ```javascript
+     * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
+     *
+     * if (machine.hasDevData(KEY_DEV_AUTO_NAVIGATION)) {
+     *   // Dev setting exists
+     * }
+     * ```
+     */
+    hasDevData(key: string): boolean;
+    /**
+     * Clear all dev data properties
+     *
+     * Only available in dev mode - no-op in production.
+     *
+     * @example
+     * ```javascript
+     * machine.clearDevData();  // Reset all dev settings
+     * ```
+     */
+    clearDevData(): void;
+    /**
+     * Get number of dev data properties
+     *
+     * Only available in dev mode - returns 0 in production.
+     *
+     * @returns {number} Number of dev data entries
+     */
+    get devDataSize(): number;
     /**
      * Check if a route has been visited
      *

package/dist/state/machines/page-machine/PageMachine.svelte.js

@@ -8,12 +8,14 @@
  * - Current route tracking and synchronization
  * - Start path management
  * - Data properties for business/domain state (using SvelteMap)
+ * - Dev data properties for dev-mode helpers (using SvelteMap)
  * - Visited routes tracking (using SvelteSet)
  * - Fine-grained reactivity without manual revision tracking
  *
  * Best practices:
  * - Use constants for routes: `const ROUTE_INTRO = '/intro/start'`
  * - Use KEY_ constants for data: `const KEY_SCORE = 'score'`
+ * - Use KEY_DEV_ constants for dev data: `const KEY_DEV_AUTO_NAV = 'dev-auto-navigation'`
  *
  * Basic usage:
  * ```javascript
@@ -21,6 +23,7 @@
  * const ROUTE_INTRO = '/intro/start';
  * const KEY_SCORE = 'score';
  * const KEY_TUTORIAL_SEEN = 'tutorial-seen';
+ * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
  *
  * const machine = new PageMachine({
  *   startPath: ROUTE_INTRO,
@@ -48,6 +51,10 @@
  *   const score = machine.getData(KEY_SCORE);
  *   console.log('Score changed:', score);
  * });
+ *
+ * // Dev-mode helpers (only available in dev)
+ * machine.setDevData(KEY_DEV_AUTO_NAVIGATION, true);
+ * const autoNavEnabled = machine.getDevData(KEY_DEV_AUTO_NAVIGATION);
  * ```
  *
  * Animations and page-specific logic should use $effect in pages:
@@ -63,6 +70,7 @@
  * ```
  */
 import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import { dev } from '$app/environment';
 
 export default class PageMachine {
 	/**
@@ -97,6 +105,14 @@ export default class PageMachine {
 	 */
 	#data;
 
+	/**
+	 * Reactive map for dev-mode helper data
+	 * Uses SvelteMap for fine-grained reactivity
+	 * Only available in dev mode
+	 * @type {SvelteMap<string, any>|null}
+	 */
+	#devData;
+
 	/**
 	 * Reactive set for visited routes
 	 * Uses SvelteSet for automatic reactivity
@@ -147,6 +163,11 @@ export default class PageMachine {
 		this.#data = new SvelteMap();
 		this.#visitedRoutes = new SvelteSet();
 
+		// Initialize dev data (only in dev mode)
+		if (dev) {
+			this.#devData = new SvelteMap();
+		}
+
 		// Populate initial data
 		for (const [key, value] of Object.entries(initialData)) {
 			this.#data.set(key, value);
@@ -387,6 +408,174 @@ export default class PageMachine {
 		return this.#data.size;
 	}
 
+	/* ===== Dev Data Properties (Dev-Mode Helpers) ===== */
+
+	/**
+	 * Set a dev data property value
+	 *
+	 * Automatically reactive - effects watching this key will re-run.
+	 * Only available in dev mode - no-op in production.
+	 *
+	 * @param {string} key - Property key (use KEY_DEV_ constant)
+	 * @param {any} value - Property value
+	 *
+	 * @example
+	 * ```javascript
+	 * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
+	 * const KEY_DEV_SKIP_ANIMATIONS = 'dev-skip-animations';
+	 *
+	 * machine.setDevData(KEY_DEV_AUTO_NAVIGATION, true);
+	 * machine.setDevData(KEY_DEV_SKIP_ANIMATIONS, false);
+	 * ```
+	 */
+	setDevData(key, value) {
+		if (!dev) return;
+		this.#devData.set(key, value);
+	}
+
+	/**
+	 * Get a dev data property value
+	 *
+	 * Automatically reactive - creates a dependency on this specific key.
+	 * Only available in dev mode - returns undefined in production.
+	 *
+	 * @param {string} key - Property key (use KEY_DEV_ constant)
+	 *
+	 * @returns {any} Property value or undefined
+	 *
+	 * @example
+	 * ```javascript
+	 * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
+	 *
+	 * // Reactive - re-runs only when KEY_DEV_AUTO_NAVIGATION changes
+	 * $effect(() => {
+	 *   const autoNav = machine.getDevData(KEY_DEV_AUTO_NAVIGATION);
+	 *   console.log('Auto-navigation:', autoNav);
+	 * });
+	 * ```
+	 */
+	getDevData(key) {
+		if (!dev) return undefined;
+		return this.#devData.get(key);
+	}
+
+	/**
+	 * Get all dev data properties as plain object
+	 *
+	 * Note: Returns a snapshot (plain object), not reactive.
+	 * Only available in dev mode - returns empty object in production.
+	 *
+	 * @returns {Record<string, any>} Plain object with all dev data
+	 *
+	 * @example
+	 * ```javascript
+	 * const allDevData = machine.getAllDevData();
+	 * console.log('Dev settings:', allDevData);
+	 * ```
+	 */
+	getAllDevData() {
+		if (!dev) return {};
+		return Object.fromEntries(this.#devData);
+	}
+
+	/**
+	 * Update multiple dev data properties at once
+	 *
+	 * Each property update triggers fine-grained reactivity.
+	 * Only available in dev mode - no-op in production.
+	 *
+	 * @param {Record<string, any>} dataUpdates
+	 *   Object with key-value pairs (use KEY_DEV_ constants for keys)
+	 *
+	 * @example
+	 * ```javascript
+	 * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
+	 * const KEY_DEV_SKIP_ANIMATIONS = 'dev-skip-animations';
+	 *
+	 * machine.updateDevData({
+	 *   [KEY_DEV_AUTO_NAVIGATION]: true,
+	 *   [KEY_DEV_SKIP_ANIMATIONS]: false
+	 * });
+	 * ```
+	 */
+	updateDevData(dataUpdates) {
+		if (!dev) return;
+		for (const [key, value] of Object.entries(dataUpdates)) {
+			this.#devData.set(key, value);
+		}
+	}
+
+	/**
+	 * Delete a dev data property
+	 *
+	 * Only available in dev mode - no-op in production.
+	 *
+	 * @param {string} key - Property key to delete (use KEY_DEV_ constant)
+	 *
+	 * @returns {boolean} True if the key existed and was deleted
+	 *
+	 * @example
+	 * ```javascript
+	 * const KEY_DEV_TEMP_FLAG = 'dev-temp-flag';
+	 *
+	 * machine.deleteDevData(KEY_DEV_TEMP_FLAG);
+	 * ```
+	 */
+	deleteDevData(key) {
+		if (!dev) return false;
+		return this.#devData.delete(key);
+	}
+
+	/**
+	 * Check if dev data property exists
+	 *
+	 * Only available in dev mode - returns false in production.
+	 *
+	 * @param {string} key - Property key to check (use KEY_DEV_ constant)
+	 *
+	 * @returns {boolean} True if the key exists
+	 *
+	 * @example
+	 * ```javascript
+	 * const KEY_DEV_AUTO_NAVIGATION = 'dev-auto-navigation';
+	 *
+	 * if (machine.hasDevData(KEY_DEV_AUTO_NAVIGATION)) {
+	 *   // Dev setting exists
+	 * }
+	 * ```
+	 */
+	hasDevData(key) {
+		if (!dev) return false;
+		return this.#devData.has(key);
+	}
+
+	/**
+	 * Clear all dev data properties
+	 *
+	 * Only available in dev mode - no-op in production.
+	 *
+	 * @example
+	 * ```javascript
+	 * machine.clearDevData();  // Reset all dev settings
+	 * ```
+	 */
+	clearDevData() {
+		if (!dev) return;
+		this.#devData.clear();
+	}
+
+	/**
+	 * Get number of dev data properties
+	 *
+	 * Only available in dev mode - returns 0 in production.
+	 *
+	 * @returns {number} Number of dev data entries
+	 */
+	get devDataSize() {
+		if (!dev) return 0;
+		return this.#devData.size;
+	}
+
 	/* ===== Visited Routes Tracking ===== */
 
 	/**

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

@@ -79,7 +79,7 @@ const KEY_HIGHEST_LEVEL = 'highest-level';
 const KEY_DIFFICULTY = 'difficulty';
 
 export class PuzzleState extends PageMachine {
-  #gameLogic;
+  #logic;
 
   constructor() {
     // Call PageMachine constructor with route config
@@ -99,11 +99,11 @@ export class PuzzleState extends PageMachine {
       }
     });
 
-    this.#gameLogic = new PuzzleGameLogic();
+    this.#logic = new PuzzleGameLogic();
   }
 
-  get gameLogic() {
-    return this.#gameLogic;
+  get logic() {
+    return this.#logic;
   }
 
   // Computed properties for convenience
@@ -161,7 +161,7 @@ export class PuzzleState extends PageMachine {
   }
 
   reset() {
-    this.#gameLogic = new PuzzleGameLogic();
+    this.#logic = new PuzzleGameLogic();
   }
 }
 
@@ -209,12 +209,12 @@ export const [createOrGetPuzzleState, createPuzzleState, getPuzzleState] =
 {:else if puzzleState.isOnTutorial}
   <TutorialView />
 {:else if puzzleState.isOnLevel1}
-  <Level1View gameLogic={puzzleState.gameLogic} />
+  <Level1View gameLogic={puzzleState.logic} />
 {:else if puzzleState.isOnLevel2}
-  <Level2View gameLogic={puzzleState.gameLogic} />
+  <Level2View gameLogic={puzzleState.logic} />
 {:else if puzzleState.isComplete}
   <CompleteView
-    score={puzzleState.gameLogic.score}
+    score={puzzleState.logic.score}
     highestLevel={puzzleState.highestLevel} />
 {/if}
 ```

package/dist/util/object/index.d.ts

@@ -37,35 +37,35 @@ export function exportNotNullish(obj: object, onlyKeys?: string[]): object;
  * - This method can e.g. be used to export a data object without it's
  *   'internal' properties
  *
- * @param {object} obj
+ * @param {Record<string,any>} obj
  *
  * @param {string[]} [keepKeys]
  *   If specified, the specified private keys will be exported (e.g. `_id`)
  *
  * @returns {object} new object without properties that start with an underscore
  */
-export function exportPublic(obj: object, keepKeys?: string[]): object;
+export function exportPublic(obj: Record<string, any>, keepKeys?: string[]): object;
 /**
  * Creates a copy of an object or array that contains only primitive values
  * - Nested objects and arrays are completely removed
  * - Only string, number, boolean, null, undefined values are kept
  *
- * @param {object|array} objectOrArray
+ * @param {Record<string,any>|Array<any>} objectOrArray
  *
- * @returns {object|array} new object or array with only primitive values
+ * @returns {Record<string,any>|Array<any>} new object or array with only primitive values
  */
-export function exportNotNested(objectOrArray: object | array): object | array;
+export function exportNotNested(objectOrArray: Record<string, any> | Array<any>): Record<string, any> | Array<any>;
 /**
  * Keep only the specified keys in the object
  * - deletes all other key-value pairs in the object
  *
- * @param {object} obj
- * @param {string[]|Set} keys
+ * @param {Record<string,any>} obj
+ * @param {string[]|Set<string>} keys
  * @param {boolean} [removeNullAndUndefined=true]
  *
  * @returns {object} object that only contains the specified keys
  */
-export function keep(obj: object, keys: string[] | Set<any>, removeNullAndUndefined?: boolean): object;
+export function keep(obj: Record<string, any>, keys: string[] | Set<string>, removeNullAndUndefined?: boolean): object;
 /**
  * Freezes an object recursively
  * - Allows non-objects to be passed as input parameter (non-objects are
@@ -73,49 +73,51 @@ export function keep(obj: object, keys: string[] | Set<any>, removeNullAndUndefi
  *
  * @param {any} value
  *
+ * @param {Set<any>} [_found]
+ *
  * @returns {any}
  *   recursively frozen object or original input value if a non-object was
  *   supplied as input parameter
  */
-export function deepFreeze(value: any, _found: any): any;
+export function deepFreeze(value: any, _found?: Set<any>): any;
 /**
  * Set a value in an object using a path and value pair.
  * - Automatically creates parent objects
  *
  * @param {object} obj - Object to set the value in
- * @param {string|Array} path - Dot separated string path or array path
+ * @param {string|Array<string>} path - Dot separated string path or array path
  * @param {any} value - value to set
  *
  * @returns {boolean} true if the value was changed
  */
-export function objectSet(obj: object, path: string | any[], value: any, ...args: any[]): boolean;
+export function objectSet(obj: object, path: string | Array<string>, value: any, ...args: any[]): boolean;
 /**
  * Removes a value at the specified object path from the object.
  * - All parent objects that remain empty will be removed too (recursively)
  *
- * @param {object} obj - Object to delete the path from
- * @param {string|Array} path - Dot separated string path or array path
+ * @param {Record<string,any>} obj - Object to delete the path from
+ * @param {string|Array<string>} path - Dot separated string path or array path
  */
-export function deletePath(obj: object, path: string | any[]): void;
+export function deletePath(obj: Record<string, any>, path: string | Array<string>): void;
 /**
  * Get a value from an object using a path
  * - Returns a default value if not found, with is [undefined] by default
  *
- * @param {object} obj - Object to get the value from
- * @param {string|Array} path - Dot separated string path or array path
+ * @param {Record<string,any>} obj - Object to get the value from
+ * @param {string|Array<string>} path - Dot separated string path or array path
  *
  * @param {any} [defaultValue=undefined]
  *   Value to return if the value does not exist
  *
  * @return {any} value found at path, defaultValue or undefined
  */
-export function objectGet(obj: object, path: string | any[], defaultValue?: any): any;
+export function objectGet(obj: Record<string, any>, path: string | Array<string>, defaultValue?: any): any;
 /**
  * Get a value from an object using a path
  * - Throws an exception if the path does not exist or the value is undefined
  *
- * @param {object} obj - Object to get the value from
- * @param {string|Array} path - Dot separated string path or array path
+ * @param {Record<string,any>} obj - Object to get the value from
+ * @param {string|Array<string>} path - Dot separated string path or array path
  *
  * @param {function} [parseFn]
  *   Optional parser function that checks and converts the value
@@ -125,7 +127,7 @@ export function objectGet(obj: object, path: string | any[], defaultValue?: any)
  *
  * @return {any} value found at path
  */
-export function objectGetWithThrow(obj: object, path: string | any[], parseFn?: Function): any;
+export function objectGetWithThrow(obj: Record<string, any>, path: string | Array<string>, parseFn?: Function): any;
 /**
  * Get an iterator that returns the value of a path for each item (object)
  * in the list of objects

package/dist/util/object/index.js

@@ -112,7 +112,7 @@ export function exportNotNullish(obj, onlyKeys) {
  * - This method can e.g. be used to export a data object without it's
  *   'internal' properties
  *
- * @param {object} obj
+ * @param {Record<string,any>} obj
  *
  * @param {string[]} [keepKeys]
  *   If specified, the specified private keys will be exported (e.g. `_id`)
@@ -122,6 +122,7 @@ export function exportNotNullish(obj, onlyKeys) {
 export function exportPublic(obj, keepKeys) {
 	expect.object(obj);
 
+	/** @type {Record<string,any>} */
 	const newObj = {};
 
 	const keepKeysSet = keepKeys ? new Set(keepKeys) : null;
@@ -153,9 +154,9 @@ export function exportPublic(obj, keepKeys) {
  * - Nested objects and arrays are completely removed
  * - Only string, number, boolean, null, undefined values are kept
  *
- * @param {object|array} objectOrArray
+ * @param {Record<string,any>|Array<any>} objectOrArray
  *
- * @returns {object|array} new object or array with only primitive values
+ * @returns {Record<string,any>|Array<any>} new object or array with only primitive values
  */
 export function exportNotNested(objectOrArray) {
 	expect.object(objectOrArray);
@@ -209,6 +210,7 @@ export function exportNotNested(objectOrArray) {
 			return objectOrArray;
 		}
 
+		/** @type {Record<string,any>} */
 		const outputObj = {};
 
 		for (const key in objectOrArray) {
@@ -233,8 +235,8 @@ export function exportNotNested(objectOrArray) {
  * Keep only the specified keys in the object
  * - deletes all other key-value pairs in the object
  *
- * @param {object} obj
- * @param {string[]|Set} keys
+ * @param {Record<string,any>} obj
+ * @param {string[]|Set<string>} keys
  * @param {boolean} [removeNullAndUndefined=true]
  *
  * @returns {object} object that only contains the specified keys
@@ -272,6 +274,8 @@ export function keep(obj, keys, removeNullAndUndefined = true) {
  *
  * @param {any} value
  *
+ * @param {Set<any>} [_found]
+ *
  * @returns {any}
  *   recursively frozen object or original input value if a non-object was
  *   supplied as input parameter
@@ -311,7 +315,7 @@ export function deepFreeze(value, _found) {
  * - Automatically creates parent objects
  *
  * @param {object} obj - Object to set the value in
- * @param {string|Array} path - Dot separated string path or array path
+ * @param {string|Array<string>} path - Dot separated string path or array path
  * @param {any} value - value to set
  *
  * @returns {boolean} true if the value was changed
@@ -382,8 +386,8 @@ export function objectSet(obj, path, value) {
  * Removes a value at the specified object path from the object.
  * - All parent objects that remain empty will be removed too (recursively)
  *
- * @param {object} obj - Object to delete the path from
- * @param {string|Array} path - Dot separated string path or array path
+ * @param {Record<string,any>} obj - Object to delete the path from
+ * @param {string|Array<string>} path - Dot separated string path or array path
  */
 export function deletePath(obj, path) {
 	expect.object(obj);
@@ -500,8 +504,8 @@ export function deletePath(obj, path) {
  * Get a value from an object using a path
  * - Returns a default value if not found, with is [undefined] by default
  *
- * @param {object} obj - Object to get the value from
- * @param {string|Array} path - Dot separated string path or array path
+ * @param {Record<string,any>} obj - Object to get the value from
+ * @param {string|Array<string>} path - Dot separated string path or array path
  *
  * @param {any} [defaultValue=undefined]
  *   Value to return if the value does not exist
@@ -541,8 +545,8 @@ export function objectGet(obj, path, defaultValue) {
  * Get a value from an object using a path
  * - Throws an exception if the path does not exist or the value is undefined
  *
- * @param {object} obj - Object to get the value from
- * @param {string|Array} path - Dot separated string path or array path
+ * @param {Record<string,any>} obj - Object to get the value from
+ * @param {string|Array<string>} path - Dot separated string path or array path
  *
  * @param {function} [parseFn]
  *   Optional parser function that checks and converts the value

package/package.json

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