pulse-js-framework 1.4.4 → 1.4.5

package/cli/index.js

@@ -7,11 +7,14 @@
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
 import { existsSync, mkdirSync, writeFileSync, readFileSync, cpSync } from 'fs';
+import { log } from './logger.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const VERSION = '1.4.3';
+// Version - read dynamically from package.json
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+const VERSION = pkg.version;
 
 // Command handlers
 const commands = {
@@ -38,8 +41,8 @@ async function main() {
   if (command in commands) {
     await commands[command](args.slice(1));
   } else {
-    console.error(`Unknown command: ${command}`);
-    console.log('Run "pulse help" for usage information.');
+    log.error(`Unknown command: ${command}`);
+    log.info('Run "pulse help" for usage information.');
     process.exit(1);
   }
 }
@@ -48,7 +51,7 @@ async function main() {
  * Show help message
  */
 function showHelp() {
-  console.log(`
+  log.info(`
 Pulse Framework CLI v${VERSION}
 
 Usage: pulse <command> [options]
@@ -102,7 +105,7 @@ Documentation: https://github.com/vincenthirtz/pulse-js-framework
  * Show version
  */
 function showVersion() {
-  console.log(`Pulse Framework v${VERSION}`);
+  log.info(`Pulse Framework v${VERSION}`);
 }
 
 /**
@@ -112,19 +115,19 @@ async function createProject(args) {
   const projectName = args[0];
 
   if (!projectName) {
-    console.error('Please provide a project name.');
-    console.log('Usage: pulse create <project-name>');
+    log.error('Please provide a project name.');
+    log.info('Usage: pulse create <project-name>');
     process.exit(1);
   }
 
   const projectPath = resolve(process.cwd(), projectName);
 
   if (existsSync(projectPath)) {
-    console.error(`Directory "${projectName}" already exists.`);
+    log.error(`Directory "${projectName}" already exists.`);
     process.exit(1);
   }
 
-  console.log(`Creating new Pulse project: ${projectName}`);
+  log.info(`Creating new Pulse project: ${projectName}`);
 
   // Create project structure
   mkdirSync(projectPath);
@@ -281,7 +284,7 @@ dist
 
   writeFileSync(join(projectPath, '.gitignore'), gitignore);
 
-  console.log(`
+  log.info(`
 Project created successfully!
 
 Next steps:
@@ -297,7 +300,7 @@ Happy coding with Pulse!
  * Run development server
  */
 async function runDev(args) {
-  console.log('Starting Pulse development server...');
+  log.info('Starting Pulse development server...');
 
   // Use dynamic import for the dev server module
   const { startDevServer } = await import('./dev.js');
@@ -308,7 +311,7 @@ async function runDev(args) {
  * Build for production
  */
 async function runBuild(args) {
-  console.log('Building Pulse project for production...');
+  log.info('Building Pulse project for production...');
 
   const { buildProject } = await import('./build.js');
   await buildProject(args);
@@ -318,7 +321,7 @@ async function runBuild(args) {
  * Preview production build
  */
 async function runPreview(args) {
-  console.log('Starting Pulse preview server...');
+  log.info('Starting Pulse preview server...');
 
   const { previewBuild } = await import('./build.js');
   await previewBuild(args);
@@ -363,13 +366,13 @@ async function compileFile(args) {
   const inputFile = args[0];
 
   if (!inputFile) {
-    console.error('Please provide a file to compile.');
-    console.log('Usage: pulse compile <file.pulse>');
+    log.error('Please provide a file to compile.');
+    log.info('Usage: pulse compile <file.pulse>');
     process.exit(1);
   }
 
   if (!existsSync(inputFile)) {
-    console.error(`File not found: ${inputFile}`);
+    log.error(`File not found: ${inputFile}`);
     process.exit(1);
   }
 
@@ -381,11 +384,11 @@ async function compileFile(args) {
   if (result.success) {
     const outputFile = inputFile.replace(/\.pulse$/, '.js');
     writeFileSync(outputFile, result.code);
-    console.log(`Compiled: ${inputFile} -> ${outputFile}`);
+    log.info(`Compiled: ${inputFile} -> ${outputFile}`);
   } else {
-    console.error('Compilation failed:');
+    log.error('Compilation failed:');
     for (const error of result.errors) {
-      console.error(`  ${error.message}`);
+      log.error(`  ${error.message}`);
     }
     process.exit(1);
   }
@@ -393,6 +396,6 @@ async function compileFile(args) {
 
 // Run main
 main().catch(error => {
-  console.error('Error:', error.message);
+  log.error('Error:', error.message);
   process.exit(1);
 });

package/cli/logger.js

@@ -0,0 +1,122 @@
+/**
+ * Pulse CLI Logger
+ * Lightweight logger for CLI tools with support for verbose mode
+ * @module pulse-cli/logger
+ */
+
+/** @type {boolean} */
+let verboseMode = false;
+
+/**
+ * Enable or disable verbose mode for debug output
+ * @param {boolean} enabled - Whether to enable verbose mode
+ * @returns {void}
+ * @example
+ * setVerbose(true);
+ * log.debug('This will now be shown');
+ */
+export function setVerbose(enabled) {
+  verboseMode = enabled;
+}
+
+/**
+ * Check if verbose mode is currently enabled
+ * @returns {boolean} True if verbose mode is enabled
+ * @example
+ * if (isVerbose()) {
+ *   // Perform additional logging
+ * }
+ */
+export function isVerbose() {
+  return verboseMode;
+}
+
+/**
+ * CLI Logger object with console-like API
+ * @namespace log
+ */
+export const log = {
+  /**
+   * Log an info message (always shown)
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.info('Starting server on port', 3000);
+   */
+  info(...args) {
+    console.log(...args);
+  },
+
+  /**
+   * Log a success message (always shown)
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.success('Build completed successfully!');
+   */
+  success(...args) {
+    console.log(...args);
+  },
+
+  /**
+   * Log a warning message
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.warn('Deprecated feature used');
+   */
+  warn(...args) {
+    console.warn(...args);
+  },
+
+  /**
+   * Log an error message
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.error('Failed to compile:', error.message);
+   */
+  error(...args) {
+    console.error(...args);
+  },
+
+  /**
+   * Log a debug message (only shown in verbose mode)
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.debug('Processing file:', filename);
+   */
+  debug(...args) {
+    if (verboseMode) {
+      console.log('[debug]', ...args);
+    }
+  },
+
+  /**
+   * Log a verbose message (only shown in verbose mode)
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.verbose('Additional details:', data);
+   */
+  verbose(...args) {
+    if (verboseMode) {
+      console.log(...args);
+    }
+  },
+
+  /**
+   * Print a blank line for spacing
+   * @returns {void}
+   * @example
+   * log.info('Section 1');
+   * log.newline();
+   * log.info('Section 2');
+   */
+  newline() {
+    console.log();
+  }
+};
+
+export default log;

package/index.js

@@ -4,14 +4,20 @@
  * A declarative DOM framework with CSS selector-based structure
  */
 
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
 // Runtime exports
 export * from './runtime/index.js';
 
 // Compiler exports
 export { compile, parse, tokenize } from './compiler/index.js';
 
-// Version
-export const VERSION = '1.4.3';
+// Version - read dynamically from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf-8'));
+export const VERSION = pkg.version;
 
 // Default export
 export default {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.4.4",
+  "version": "1.4.5",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "main": "index.js",
@@ -17,6 +17,14 @@
       "types": "./types/index.d.ts",
       "default": "./runtime/index.js"
     },
+    "./runtime/pulse": {
+      "types": "./types/pulse.d.ts",
+      "default": "./runtime/pulse.js"
+    },
+    "./runtime/dom": {
+      "types": "./types/dom.d.ts",
+      "default": "./runtime/dom.js"
+    },
     "./runtime/router": {
       "types": "./types/router.d.ts",
       "default": "./runtime/router.js"
@@ -25,9 +33,27 @@
       "types": "./types/store.d.ts",
       "default": "./runtime/store.js"
     },
-    "./runtime/*": "./runtime/*.js",
-    "./compiler": "./compiler/index.js",
-    "./vite": "./loader/vite-plugin.js"
+    "./runtime/native": {
+      "types": "./types/index.d.ts",
+      "default": "./runtime/native.js"
+    },
+    "./runtime/logger": {
+      "types": "./types/logger.d.ts",
+      "default": "./runtime/logger.js"
+    },
+    "./compiler": {
+      "types": "./types/index.d.ts",
+      "default": "./compiler/index.js"
+    },
+    "./compiler/lexer": "./compiler/lexer.js",
+    "./compiler/parser": "./compiler/parser.js",
+    "./compiler/transformer": "./compiler/transformer.js",
+    "./vite": {
+      "types": "./types/index.d.ts",
+      "default": "./loader/vite-plugin.js"
+    },
+    "./mobile": "./mobile/bridge/pulse-native.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "index.js",
@@ -50,7 +76,8 @@
     "test:lint": "node test/lint.test.js",
     "test:format": "node test/format.test.js",
     "test:analyze": "node test/analyze.test.js",
-    "build:netlify": "node scripts/build-netlify.js"
+    "build:netlify": "node scripts/build-netlify.js",
+    "version": "node scripts/sync-version.js"
   },
   "keywords": [
     "framework",

package/runtime/dom.js

@@ -6,6 +6,9 @@
  */
 
 import { effect, pulse, batch, onCleanup } from './pulse.js';
+import { loggers } from './logger.js';
+
+const log = loggers.dom;
 
 // Lifecycle tracking
 let mountCallbacks = [];
@@ -523,7 +526,7 @@ export function component(setup) {
           try {
             cb();
           } catch (e) {
-            console.error('Mount callback error:', e);
+            log.error('Mount callback error:', e);
           }
         }
       });
@@ -559,7 +562,7 @@ export function portal(children, target) {
     : target;
 
   if (!resolvedTarget) {
-    console.warn('Portal target not found:', target);
+    log.warn('Portal target not found:', target);
     return document.createComment('portal-target-not-found');
   }
 
@@ -653,7 +656,7 @@ export function errorBoundary(children, fallback) {
         marker.parentNode?.insertBefore(fragment, marker.nextSibling);
       }
     } catch (e) {
-      console.error('Error in component:', e);
+      log.error('Error in component:', e);
       error.set(e);
       // Re-render with error
       if (!hasError) {

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;