pulse-js-framework 1.4.4 → 1.4.6

package/runtime/hmr.js

@@ -0,0 +1,169 @@
+/**
+ * HMR (Hot Module Replacement) utilities for Pulse framework
+ * @module pulse-js-framework/runtime/hmr
+ *
+ * Provides state preservation and effect cleanup during hot module replacement.
+ *
+ * @example
+ * import { createHMRContext } from 'pulse-js-framework/runtime/hmr';
+ *
+ * const hmr = createHMRContext(import.meta.url);
+ *
+ * // State preserved across HMR updates
+ * const count = hmr.preservePulse('count', 0);
+ *
+ * // Effects tracked for cleanup
+ * hmr.setup(() => {
+ *   effect(() => console.log(count.get()));
+ * });
+ */
+
+import { pulse } from './pulse.js';
+import { setCurrentModule, clearCurrentModule, disposeModule } from './pulse.js';
+
+/**
+ * @typedef {Object} HMRContext
+ * @property {Object} data - Persistent data storage across HMR updates
+ * @property {function(string, *, Object=): Pulse} preservePulse - Create a pulse with preserved state
+ * @property {function(function): *} setup - Execute code with module tracking
+ * @property {function(function): void} accept - Register HMR accept callback
+ * @property {function(function): void} dispose - Register HMR dispose callback
+ */
+
+/**
+ * Create an HMR context for a module.
+ * Provides utilities for state preservation and effect cleanup during HMR.
+ *
+ * @param {string} moduleId - The module identifier (typically import.meta.url)
+ * @returns {HMRContext} HMR context with preservation utilities
+ *
+ * @example
+ * const hmr = createHMRContext(import.meta.url);
+ *
+ * // Preserve state across HMR
+ * const todos = hmr.preservePulse('todos', []);
+ * const filter = hmr.preservePulse('filter', 'all');
+ *
+ * // Setup effects with automatic cleanup
+ * hmr.setup(() => {
+ *   effect(() => {
+ *     document.title = `${todos.get().length} todos`;
+ *   });
+ * });
+ *
+ * // Accept HMR updates
+ * hmr.accept();
+ */
+export function createHMRContext(moduleId) {
+  // Check if HMR is available (Vite dev server)
+  if (typeof import.meta === 'undefined' || !import.meta.hot) {
+    return createNoopContext();
+  }
+
+  const hot = import.meta.hot;
+
+  // Initialize data storage if not present
+  if (!hot.data) {
+    hot.data = {};
+  }
+
+  return {
+    /**
+     * Persistent data storage across HMR updates.
+     * Values stored here survive module reloads.
+     */
+    data: hot.data,
+
+    /**
+     * Create a pulse with state preservation across HMR updates.
+     * If a value exists from a previous module load, it's restored.
+     *
+     * @param {string} key - Unique key for this pulse within the module
+     * @param {*} initialValue - Initial value (used on first load only)
+     * @param {Object} [options] - Pulse options (equals function, etc.)
+     * @returns {Pulse} A pulse instance with preserved state
+     */
+    preservePulse(key, initialValue, options) {
+      const fullKey = `__pulse_${key}`;
+
+      // Check if we have a preserved value from previous load
+      if (fullKey in hot.data) {
+        const p = pulse(hot.data[fullKey], options);
+        // Register to save state on next HMR update
+        hot.dispose(() => {
+          hot.data[fullKey] = p.peek();
+        });
+        return p;
+      }
+
+      // First load - create new pulse with initial value
+      const p = pulse(initialValue, options);
+      // Register to save state on HMR update
+      hot.dispose(() => {
+        hot.data[fullKey] = p.peek();
+      });
+      return p;
+    },
+
+    /**
+     * Execute code with module tracking enabled.
+     * Effects created within this callback will be registered
+     * for automatic cleanup during HMR.
+     *
+     * @param {function} callback - Code to execute with tracking
+     * @returns {*} The return value of the callback
+     */
+    setup(callback) {
+      setCurrentModule(moduleId);
+      try {
+        return callback();
+      } finally {
+        clearCurrentModule();
+      }
+    },
+
+    /**
+     * Register a callback to run when the module accepts an HMR update.
+     *
+     * @param {function} [callback] - Optional callback for custom handling
+     */
+    accept(callback) {
+      if (callback) {
+        hot.accept(callback);
+      } else {
+        hot.accept();
+      }
+    },
+
+    /**
+     * Register a callback to run before the module is replaced.
+     * Use this for custom cleanup logic.
+     *
+     * @param {function} callback - Cleanup callback
+     */
+    dispose(callback) {
+      hot.dispose(callback);
+    }
+  };
+}
+
+/**
+ * Create a no-op HMR context for production or non-HMR environments.
+ * All methods work normally but without HMR-specific behavior.
+ *
+ * @returns {HMRContext} A no-op HMR context
+ * @private
+ */
+function createNoopContext() {
+  return {
+    data: {},
+    preservePulse: (key, initialValue, options) => pulse(initialValue, options),
+    setup: (callback) => callback(),
+    accept: () => {},
+    dispose: () => {}
+  };
+}
+
+export default {
+  createHMRContext
+};

package/runtime/index.js

@@ -7,9 +7,11 @@ export * from './dom.js';
 export * from './router.js';
 export * from './store.js';
 export * from './native.js';
+export * from './logger.js';
 
 export { default as PulseCore } from './pulse.js';
 export { default as PulseDOM } from './dom.js';
 export { default as PulseRouter } from './router.js';
 export { default as PulseStore } from './store.js';
 export { default as PulseNative } from './native.js';
+export { default as PulseLogger } from './logger.js';

package/runtime/logger.js

@@ -0,0 +1,304 @@
+/**
+ * Pulse Logger - Centralized logging with namespaces and levels
+ * @module pulse-js-framework/runtime/logger
+ *
+ * @example
+ * import { logger, createLogger } from './logger.js';
+ *
+ * // Default logger
+ * logger.info('Hello');
+ * logger.warn('Warning');
+ * logger.error('Error');
+ *
+ * // Namespaced logger
+ * const log = createLogger('Router');
+ * log.info('Navigating to /home'); // [Router] Navigating to /home
+ */
+
+/**
+ * Log level constants
+ * @readonly
+ * @enum {number}
+ */
+export const LogLevel = {
+  /** No logging */
+  SILENT: 0,
+  /** Only errors */
+  ERROR: 1,
+  /** Errors and warnings */
+  WARN: 2,
+  /** Errors, warnings, and info (default) */
+  INFO: 3,
+  /** All messages including debug */
+  DEBUG: 4
+};
+
+/** @type {number} */
+let globalLevel = LogLevel.INFO;
+
+/** @type {LogFormatter|null} */
+let globalFormatter = null;
+
+/**
+ * @callback LogFormatter
+ * @param {'error'|'warn'|'info'|'debug'} level - The log level
+ * @param {string|null} namespace - The logger namespace
+ * @param {Array<*>} args - The arguments to log
+ * @returns {string} The formatted log message
+ */
+
+/**
+ * Set the global log level for all loggers
+ * @param {number} level - A LogLevel value (SILENT=0, ERROR=1, WARN=2, INFO=3, DEBUG=4)
+ * @returns {void}
+ * @example
+ * setLogLevel(LogLevel.DEBUG); // Enable all logging
+ * setLogLevel(LogLevel.SILENT); // Disable all logging
+ */
+export function setLogLevel(level) {
+  globalLevel = level;
+}
+
+/**
+ * Get the current global log level
+ * @returns {number} The current LogLevel value
+ * @example
+ * const level = getLogLevel();
+ * if (level >= LogLevel.DEBUG) {
+ *   // Debug logging is enabled
+ * }
+ */
+export function getLogLevel() {
+  return globalLevel;
+}
+
+/**
+ * Set a custom formatter function for all loggers
+ * @param {LogFormatter|null} formatter - Custom formatter function, or null to use default
+ * @returns {void}
+ * @example
+ * setFormatter((level, namespace, args) => {
+ *   const timestamp = new Date().toISOString();
+ *   const prefix = namespace ? `[${namespace}]` : '';
+ *   return `${timestamp} ${level.toUpperCase()} ${prefix} ${args.join(' ')}`;
+ * });
+ */
+export function setFormatter(formatter) {
+  globalFormatter = formatter;
+}
+
+/**
+ * Format message arguments with optional namespace prefix
+ * @private
+ * @param {string|null} namespace - The logger namespace
+ * @param {Array<*>} args - Arguments to format
+ * @returns {Array<*>} Formatted arguments array
+ */
+function formatArgs(namespace, args) {
+  if (!namespace) return args;
+
+  // If first arg is a string, prepend namespace
+  if (typeof args[0] === 'string') {
+    return [`[${namespace}] ${args[0]}`, ...args.slice(1)];
+  }
+
+  // Otherwise, add namespace as first arg
+  return [`[${namespace}]`, ...args];
+}
+
+/**
+ * @typedef {Object} Logger
+ * @property {function(...*): void} error - Log error message
+ * @property {function(...*): void} warn - Log warning message
+ * @property {function(...*): void} info - Log info message
+ * @property {function(...*): void} debug - Log debug message
+ * @property {function(string): void} group - Start a collapsed log group
+ * @property {function(): void} groupEnd - End the current log group
+ * @property {function(number, ...*): void} log - Log with custom level
+ * @property {function(string): Logger} child - Create a child logger with sub-namespace
+ */
+
+/**
+ * @typedef {Object} LoggerOptions
+ * @property {number} [level] - Override global level for this logger instance
+ */
+
+/**
+ * Create a logger instance with optional namespace
+ * @param {string|null} [namespace=null] - Logger namespace (e.g., 'Router', 'Store')
+ * @param {LoggerOptions} [options={}] - Logger configuration options
+ * @returns {Logger} A logger instance with error, warn, info, debug methods
+ * @example
+ * const log = createLogger('MyComponent');
+ * log.info('Initialized'); // [MyComponent] Initialized
+ * log.error('Failed', { code: 500 }); // [MyComponent] Failed { code: 500 }
+ *
+ * // With custom level
+ * const debugLog = createLogger('Debug', { level: LogLevel.DEBUG });
+ */
+export function createLogger(namespace = null, options = {}) {
+  const localLevel = options.level;
+
+  /**
+   * Check if a message at the given level should be logged
+   * @param {number} level - The log level to check
+   * @returns {boolean} True if the message should be logged
+   */
+  function shouldLog(level) {
+    const effectiveLevel = localLevel !== undefined ? localLevel : globalLevel;
+    return level <= effectiveLevel;
+  }
+
+  return {
+    /**
+     * Log an error message (shown unless level is SILENT)
+     * @param {...*} args - Values to log
+     * @returns {void}
+     */
+    error(...args) {
+      if (shouldLog(LogLevel.ERROR)) {
+        if (globalFormatter) {
+          console.error(globalFormatter('error', namespace, args));
+        } else {
+          console.error(...formatArgs(namespace, args));
+        }
+      }
+    },
+
+    /**
+     * Log a warning message (shown at WARN level and above)
+     * @param {...*} args - Values to log
+     * @returns {void}
+     */
+    warn(...args) {
+      if (shouldLog(LogLevel.WARN)) {
+        if (globalFormatter) {
+          console.warn(globalFormatter('warn', namespace, args));
+        } else {
+          console.warn(...formatArgs(namespace, args));
+        }
+      }
+    },
+
+    /**
+     * Log an info message (shown at INFO level and above)
+     * @param {...*} args - Values to log
+     * @returns {void}
+     */
+    info(...args) {
+      if (shouldLog(LogLevel.INFO)) {
+        if (globalFormatter) {
+          console.log(globalFormatter('info', namespace, args));
+        } else {
+          console.log(...formatArgs(namespace, args));
+        }
+      }
+    },
+
+    /**
+     * Log a debug message (only shown at DEBUG level)
+     * @param {...*} args - Values to log
+     * @returns {void}
+     */
+    debug(...args) {
+      if (shouldLog(LogLevel.DEBUG)) {
+        if (globalFormatter) {
+          console.log(globalFormatter('debug', namespace, args));
+        } else {
+          console.log(...formatArgs(namespace, args));
+        }
+      }
+    },
+
+    /**
+     * Start a collapsed log group (only shown at DEBUG level)
+     * @param {string} label - The group label
+     * @returns {void}
+     */
+    group(label) {
+      if (shouldLog(LogLevel.DEBUG)) {
+        console.group(namespace ? `[${namespace}] ${label}` : label);
+      }
+    },
+
+    /**
+     * End the current log group
+     * @returns {void}
+     */
+    groupEnd() {
+      if (shouldLog(LogLevel.DEBUG)) {
+        console.groupEnd();
+      }
+    },
+
+    /**
+     * Log a message at a custom level
+     * @param {number} level - The LogLevel to use
+     * @param {...*} args - Values to log
+     * @returns {void}
+     */
+    log(level, ...args) {
+      if (shouldLog(level)) {
+        const formatted = formatArgs(namespace, args);
+        switch (level) {
+          case LogLevel.ERROR:
+            console.error(...formatted);
+            break;
+          case LogLevel.WARN:
+            console.warn(...formatted);
+            break;
+          default:
+            console.log(...formatted);
+        }
+      }
+    },
+
+    /**
+     * Create a child logger with an additional namespace segment
+     * @param {string} childNamespace - The child namespace to append
+     * @returns {Logger} A new logger with combined namespace
+     * @example
+     * const log = createLogger('App');
+     * const routerLog = log.child('Router');
+     * routerLog.info('Navigate'); // [App:Router] Navigate
+     */
+    child(childNamespace) {
+      const combined = namespace
+        ? `${namespace}:${childNamespace}`
+        : childNamespace;
+      return createLogger(combined, options);
+    }
+  };
+}
+
+/**
+ * Default logger instance without namespace
+ * @type {Logger}
+ * @example
+ * import { logger } from './logger.js';
+ * logger.info('Application started');
+ */
+export const logger = createLogger();
+
+/**
+ * Pre-configured loggers for common Pulse subsystems
+ * @type {Object.<string, Logger>}
+ * @property {Logger} pulse - Logger for core reactivity system
+ * @property {Logger} dom - Logger for DOM operations
+ * @property {Logger} router - Logger for routing
+ * @property {Logger} store - Logger for state management
+ * @property {Logger} native - Logger for native/mobile features
+ * @property {Logger} hmr - Logger for hot module replacement
+ * @property {Logger} cli - Logger for CLI tools
+ */
+export const loggers = {
+  pulse: createLogger('Pulse'),
+  dom: createLogger('DOM'),
+  router: createLogger('Router'),
+  store: createLogger('Store'),
+  native: createLogger('Native'),
+  hmr: createLogger('HMR'),
+  cli: createLogger('CLI')
+};
+
+export default logger;

package/runtime/native.js

@@ -5,6 +5,9 @@
  */
 
 import { pulse, effect, batch } from './pulse.js';
+import { loggers } from './logger.js';
+
+const log = loggers.native;
 
 /**
  * Check if PulseMobile bridge is available
@@ -223,8 +226,8 @@ export const NativeUI = {
     if (isNativeAvailable()) {
       return getNative().UI.showToast(message, isLong);
     }
-    // Fallback: simple console log
-    console.log('[Toast]', message);
+    // Fallback: log toast message
+    log.info('Toast:', message);
     return Promise.resolve();
   },
 
@@ -335,7 +338,7 @@ export function exitApp() {
   if (isNativeAvailable() && getNative().isAndroid) {
     return getNative().App.exit();
   }
-  console.warn('exitApp is only available on Android');
+  log.warn('exitApp is only available on Android');
   return Promise.resolve();
 }
 
@@ -346,7 +349,7 @@ export function minimizeApp() {
   if (isNativeAvailable()) {
     return getNative().App.minimize();
   }
-  console.warn('minimizeApp is only available in native apps');
+  log.warn('minimizeApp is only available in native apps');
   return Promise.resolve();
 }