pulse-js-framework 1.10.4 → 1.11.0

package/README.md

@@ -354,10 +354,21 @@ const count: Pulse<number> = pulse(0);
 | [Chat App](examples/chat) | Real-time messaging |
 | [E-commerce](examples/ecommerce) | Shopping cart |
 | [Dashboard](examples/dashboard) | Admin UI |
+| [Weather App](examples/meteo) | API integration, async data fetching |
+| [Sports News](examples/sports) | HTTP client with interceptors |
 | [HMR Demo](examples/hmr) | Hot module replacement |
 | [Router Demo](examples/router) | SPA routing |
 | [Store Demo](examples/store) | State with undo/redo |
 | [Electron App](examples/electron) | Desktop notes app |
+| [Server Actions](examples/server-actions-ratelimit) | Rate limiting, CSRF protection |
+| [LESS Example](examples/less-example) | LESS preprocessor support |
+| [Stylus Example](examples/stylus-example) | Stylus preprocessor support |
+| [Webpack](examples/webpack-example) | Webpack 5 loader integration |
+| [Rollup](examples/rollup-example) | Rollup plugin with tree-shaking |
+| [ESBuild](examples/esbuild-example) | ESBuild ultra-fast builds |
+| [Parcel](examples/parcel-example) | Parcel zero-config bundling |
+| [SASS Example](examples/sass-example) | SASS/SCSS preprocessor support |
+| [Form Validation](examples/form-validation) | useForm, validators, file upload |
 
 ## Server-Side Rendering
 

package/cli/build.js

@@ -512,15 +512,25 @@ export async function previewBuild(args) {
     }
   });
 
-  server.listen(port, () => {
-    log.success(`
+  return new Promise((resolve, reject) => {
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        log.error(`Port ${port} is already in use. Try a different port.`);
+      }
+      reject(err);
+    });
+
+    server.listen(port, () => {
+      log.success(`
   Pulse Preview Server running at:
 
     Local:   http://localhost:${port}/
 
   Serving production build from: dist/
   Press Ctrl+C to stop.
-    `);
+      `);
+      resolve(server);
+    });
   });
 }
 

package/compiler/directives.js

@@ -0,0 +1,356 @@
+/**
+ * Pulse Compiler - Directive Detection
+ *
+ * Detects and handles file-level directives for Server Components:
+ * - 'use client' - Marks component as Client Component (runs on client only)
+ * - 'use server' - Marks component as Server Component (runs on server only)
+ *
+ * These are different from element-level @client/@server directives:
+ * - File-level: Affects entire component, used for bundle splitting
+ * - Element-level: Affects individual elements, used for SSR (ClientOnly/ServerOnly)
+ *
+ * @module pulse-js-framework/compiler/directives
+ */
+
+import { TokenType } from './lexer.js';
+import { CompileError } from '../runtime/errors.js';
+
+// ============================================================================
+// Directive Constants
+// ============================================================================
+
+/**
+ * Supported file-level directives
+ */
+export const Directive = {
+  USE_CLIENT: 'use client',
+  USE_SERVER: 'use server'
+};
+
+/**
+ * Check if a string value is a valid directive
+ * @param {string} value - String literal value
+ * @returns {string|null} Directive type or null
+ */
+export function isDirective(value) {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === Directive.USE_CLIENT) return Directive.USE_CLIENT;
+  if (normalized === Directive.USE_SERVER) return Directive.USE_SERVER;
+  return null;
+}
+
+/**
+ * Check if a token is a directive string literal
+ * @param {Object} token - Token to check
+ * @returns {string|null} Directive type or null
+ */
+export function isDirectiveToken(token) {
+  if (!token || token.type !== TokenType.STRING) return null;
+  return isDirective(token.value);
+}
+
+// ============================================================================
+// Directive Parsing
+// ============================================================================
+
+/**
+ * Parse file-level directives at the beginning of a .pulse file
+ * Directives must appear before any other statements (imports, blocks, etc.)
+ *
+ * @param {Parser} parser - Parser instance
+ * @returns {string|null} Directive type ('use client' | 'use server' | null)
+ *
+ * @example
+ * // .pulse file with directive:
+ * // 'use client';
+ * // import Button from './Button.pulse'
+ * // ...
+ *
+ * // Parsed as:
+ * // { directive: 'use client', imports: [...], ... }
+ */
+export function parseDirective(parser) {
+  // Check if first token is a string literal
+  const token = parser.current();
+  if (token?.type !== TokenType.STRING) {
+    return null;
+  }
+
+  // Check if it's a valid directive
+  const directive = isDirective(token.value);
+  if (!directive) {
+    return null;
+  }
+
+  // Consume the directive token
+  parser.advance();
+
+  // Optional semicolon after directive
+  if (parser.is(TokenType.SEMICOLON)) {
+    parser.advance();
+  }
+
+  return directive;
+}
+
+/**
+ * Validate directive usage rules
+ * @param {string} directive - Directive type
+ * @param {Object} program - Program AST node
+ * @throws {Error} If directive usage is invalid
+ */
+export function validateDirective(directive, program) {
+  if (!directive) return;
+
+  // Rule 1: Cannot have both 'use client' and 'use server'
+  if (directive === Directive.USE_CLIENT && program.serverDirective) {
+    throw new CompileError("Cannot use both 'use client' and 'use server' in the same file", { code: 'DIRECTIVE_CONFLICT', suggestion: 'Choose either \'use client\' or \'use server\' per file, not both' });
+  }
+  if (directive === Directive.USE_SERVER && program.clientDirective) {
+    throw new CompileError("Cannot use both 'use client' and 'use server' in the same file", { code: 'DIRECTIVE_CONFLICT', suggestion: 'Choose either \'use client\' or \'use server\' per file, not both' });
+  }
+
+  // Rule 2: Server Components cannot have interactive features
+  // (This will be enforced in transformer/linter)
+}
+
+// ============================================================================
+// Component Type Detection
+// ============================================================================
+
+/**
+ * Determine component type from directive
+ * @param {string|null} directive - File-level directive
+ * @returns {'client'|'server'|'shared'} Component type
+ */
+export function getComponentType(directive) {
+  if (directive === Directive.USE_CLIENT) return 'client';
+  if (directive === Directive.USE_SERVER) return 'server';
+  return 'shared'; // Default: can run on both server and client
+}
+
+/**
+ * Check if component is a Client Component
+ * @param {string|null} directive - File-level directive
+ * @returns {boolean} True if Client Component
+ */
+export function isClientComponent(directive) {
+  return directive === Directive.USE_CLIENT;
+}
+
+/**
+ * Check if component is a Server Component
+ * @param {string|null} directive - File-level directive
+ * @returns {boolean} True if Server Component
+ */
+export function isServerComponent(directive) {
+  return directive === Directive.USE_SERVER;
+}
+
+/**
+ * Check if component is a Shared Component (runs on both)
+ * @param {string|null} directive - File-level directive
+ * @returns {boolean} True if Shared Component
+ */
+export function isSharedComponent(directive) {
+  return !directive || (directive !== Directive.USE_CLIENT && directive !== Directive.USE_SERVER);
+}
+
+// ============================================================================
+// JavaScript/TypeScript Source Code Parsing
+// ============================================================================
+
+/**
+ * Parse directives from raw JavaScript/TypeScript source code
+ * Used by build tools to detect 'use client' and 'use server' in .js/.ts files
+ *
+ * @param {string} source - Source code
+ * @returns {{ useClient: boolean, useServer: boolean, line?: number }}
+ *
+ * @example
+ * parseDirectivesFromSource("'use client';\nimport foo from 'bar';")
+ * // { useClient: true, useServer: false, line: 1 }
+ */
+export function parseDirectivesFromSource(source) {
+  const result = {
+    useClient: false,
+    useServer: false,
+    line: undefined
+  };
+
+  if (!source || typeof source !== 'string') {
+    return result;
+  }
+
+  // Split into lines for analysis
+  const lines = source.split('\n');
+  let seenCode = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+
+    // Skip empty lines
+    if (line === '') {
+      continue;
+    }
+
+    // Skip comments
+    if (line.startsWith('//') || line.startsWith('/*') || line.startsWith('*')) {
+      continue;
+    }
+
+    // Check for 'use client' directive
+    if (/^['"]use client['"];?$/.test(line)) {
+      if (seenCode) {
+        return result; // Directive after code - invalid
+      }
+      result.useClient = true;
+      result.line = i + 1;
+      return result;
+    }
+
+    // Check for 'use server' directive
+    if (/^['"]use server['"];?$/.test(line)) {
+      if (seenCode) {
+        return result; // Directive after code - invalid
+      }
+      result.useServer = true;
+      result.line = i + 1;
+      return result;
+    }
+
+    // Any other non-empty, non-comment line is "code"
+    seenCode = true;
+  }
+
+  return result;
+}
+
+/**
+ * Check if source code is a Client Component (has 'use client' directive)
+ *
+ * @param {string} source - Source code
+ * @returns {boolean}
+ *
+ * @example
+ * isClientComponentSource("'use client';\nexport function Button() {}")  // true
+ */
+export function isClientComponentSource(source) {
+  const directives = parseDirectivesFromSource(source);
+  return directives.useClient;
+}
+
+/**
+ * Check if source code is a Server Component (has 'use server' directive)
+ *
+ * @param {string} source - Source code
+ * @returns {boolean}
+ *
+ * @example
+ * isServerComponentSource("'use server';\nexport async function createUser() {}")  // true
+ */
+export function isServerComponentSource(source) {
+  const directives = parseDirectivesFromSource(source);
+  return directives.useServer;
+}
+
+/**
+ * Check if a file path matches *.server.js pattern
+ *
+ * @param {string} filePath - File path
+ * @returns {boolean}
+ *
+ * @example
+ * isServerFile('src/api/users.server.js')  // true
+ * isServerFile('src/api/users.js')         // false
+ */
+export function isServerFile(filePath) {
+  if (!filePath || typeof filePath !== 'string') {
+    return false;
+  }
+  return /\.server\.(js|ts|jsx|tsx)$/.test(filePath);
+}
+
+/**
+ * Check if a file should be treated as a Server Component
+ * (either has 'use server' directive OR matches *.server.js pattern)
+ *
+ * @param {string} source - Source code
+ * @param {string} filePath - File path
+ * @returns {boolean}
+ */
+export function isServerModule(source, filePath) {
+  return isServerComponentSource(source) || isServerFile(filePath);
+}
+
+/**
+ * Check if a file should be treated as a Client Component
+ *
+ * @param {string} source - Source code
+ * @returns {boolean}
+ */
+export function isClientModule(source) {
+  return isClientComponentSource(source);
+}
+
+/**
+ * Get component type from source and file path
+ *
+ * @param {string} source - Source code
+ * @param {string} filePath - File path
+ * @returns {'client' | 'server' | 'shared'}
+ *
+ * @example
+ * getComponentTypeFromSource("'use client';", 'Button.js')  // 'client'
+ * getComponentTypeFromSource("'use server';", 'api.js')     // 'server'
+ * getComponentTypeFromSource("export const utils = {}", 'utils.js')  // 'shared'
+ */
+export function getComponentTypeFromSource(source, filePath) {
+  if (isClientModule(source)) return 'client';
+  if (isServerModule(source, filePath)) return 'server';
+  return 'shared';
+}
+
+/**
+ * Validate that source doesn't have both directives
+ *
+ * @param {string} source - Source code
+ * @returns {{ valid: boolean, error?: string }}
+ */
+export function validateDirectivesInSource(source) {
+  const directives = parseDirectivesFromSource(source);
+
+  if (directives.useClient && directives.useServer) {
+    return {
+      valid: false,
+      error: "Cannot have both 'use client' and 'use server' directives in the same file"
+    };
+  }
+
+  return { valid: true };
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default {
+  Directive,
+  isDirective,
+  isDirectiveToken,
+  parseDirective,
+  validateDirective,
+  getComponentType,
+  isClientComponent,
+  isServerComponent,
+  isSharedComponent,
+  // Source code parsing
+  parseDirectivesFromSource,
+  isClientComponentSource,
+  isServerComponentSource,
+  isServerFile,
+  isServerModule,
+  isClientModule,
+  getComponentTypeFromSource,
+  validateDirectivesInSource
+};

package/compiler/lexer.js

@@ -97,6 +97,7 @@ export const TokenType = {
   MINUS_ASSIGN: 'MINUS_ASSIGN', // -=
   STAR_ASSIGN: 'STAR_ASSIGN',   // *=
   SLASH_ASSIGN: 'SLASH_ASSIGN', // /=
+  PIPE: 'PIPE',                 // | (bitwise OR)
 
   // Literals
   STRING: 'STRING',
@@ -495,8 +496,8 @@ export class Lexer {
       // If not scientific notation, leave 'e' for the next token (e.g., 'em' unit)
     }
 
-    // Check for BigInt suffix 'n'
-    if (this.current() === 'n') {
+    // Check for BigInt suffix 'n' (only valid on integers, not floats)
+    if (this.current() === 'n' && !value.includes('.') && !value.includes('e') && !value.includes('E')) {
       rawValue += this.advance();
       isBigInt = true;
     }
@@ -822,6 +823,9 @@ export class Lexer {
             } else {
               this.tokens.push(new Token(TokenType.OR, '||', startLine, startColumn));
             }
+          } else {
+            // Single | is bitwise OR
+            this.tokens.push(new Token(TokenType.PIPE, '|', startLine, startColumn));
           }
           continue;
       }
@@ -985,9 +989,20 @@ export class Lexer {
         lookahead++;
         continue;
       }
-      if (char === '.' || char === '#' || char === '[' || char === '{' || char === ' ') {
+      if (char === '.' || char === '#' || char === '[' || char === '{') {
         return true;
       }
+      // Space followed by { indicates element with children (selector context)
+      if (char === ' ') {
+        // Peek past whitespace to check for selector continuation
+        let spaceEnd = this.pos + lookahead + 1;
+        while (spaceEnd < this.source.length && this.source[spaceEnd] === ' ') spaceEnd++;
+        const afterSpace = this.source[spaceEnd];
+        if (afterSpace === '{' || afterSpace === '.' || afterSpace === '#' || afterSpace === '[') {
+          return true;
+        }
+        return false;
+      }
       break;
     }
     return false;

package/compiler/parser/core.js

@@ -8,6 +8,7 @@
 
 import { TokenType } from '../lexer.js';
 import { ParserError, SUGGESTIONS, getDocsUrl } from '../../runtime/errors.js';
+import { parseDirective, validateDirective } from '../directives.js';
 
 // ============================================================
 // AST Node Types
@@ -192,6 +193,7 @@ export class Parser {
    */
   parse() {
     const program = new ASTNode(NodeType.Program, {
+      directive: null,  // 'use client' | 'use server' | null
       imports: [],
       page: null,
       route: null,
@@ -204,6 +206,10 @@ export class Parser {
       store: null
     });
 
+    // Parse file-level directive (must be first)
+    program.directive = parseDirective(this);
+    validateDirective(program.directive, program);
+
     while (!this.is(TokenType.EOF)) {
       // Import declarations (must come first)
       if (this.is(TokenType.IMPORT)) {

package/compiler/parser/view.js

@@ -281,12 +281,8 @@ Parser.prototype.parseDirective = function() {
     modifiers.push(this.advance().value);
   }
 
-  if (name === 'if') {
-    return this.parseIfDirective();
-  }
-  if (name === 'each' || name === 'for') {
-    return this.parseEachDirective();
-  }
+  // Note: 'if', 'each', 'for' are handled above as keyword tokens (IF, EACH, FOR)
+  // They will never reach here as IDENT tokens
 
   // Accessibility directives
   if (name === 'a11y') {

package/compiler/preprocessor.js

@@ -10,14 +10,18 @@
 
 import { createRequire } from 'module';
 
-// Cache for the sass module (null = not checked, false = not available, object = sass module)
+// Cache for the sass module (null = not checked, false = not available, object = module)
+// Separate sync/async caches so sync failure doesn't prevent async import from succeeding
 let sassModule = null;
+let sassModuleAsync = null;
 
-// Cache for the less module (null = not checked, false = not available, object = less module)
+// Cache for the less module
 let lessModule = null;
+let lessModuleAsync = null;
 
-// Cache for the stylus module (null = not checked, false = not available, object = stylus module)
+// Cache for the stylus module
 let stylusModule = null;
+let stylusModuleAsync = null;
 
 /**
  * Patterns that indicate SASS/SCSS syntax
@@ -62,9 +66,8 @@ const LESS_PATTERNS = [
  * Patterns that indicate Stylus syntax
  */
 const STYLUS_PATTERNS = [
-  /^[\w-]+\s*=/m,           // Variables without $ or @: primary-color = #333
+  /^[\w-]+\s*=\s+/m,        // Variables without $ or @: primary-color = #333 (require space after =)
   /^\s*[\w-]+\([^)]*\)$/m,  // Mixins without braces: button-style()
-  /^\s*[\w-]+$/m,           // Mixin calls without parens or semicolon
   /\{\s*\$[\w-]+\s*\}/,     // Interpolation: {$variable}
   /^\s*if\s+/m,             // Conditionals: if condition
   /^\s*unless\s+/m,         // Unless: unless condition
@@ -72,7 +75,7 @@ const STYLUS_PATTERNS = [
   /^\s*@css\s+\{/m,         // Literal CSS blocks: @css { }
   /^\s*@extends?\s+/m,      // Extend: @extend or @extends
   /^\s*\+[\w-]+/m,          // Mixin calls with +: +button-style
-  /arguments/,              // Stylus arguments variable
+  /\barguments\b/,           // Stylus arguments variable (word boundary)
   /^[\w-]+\s*\?=/m,         // Conditional assignment: var ?= value
 ];
 
@@ -188,18 +191,25 @@ export function tryLoadSassSync() {
  * @returns {Promise<object|false>} The sass module or false if not available
  */
 export async function tryLoadSass() {
-  // Return cached result if already checked
-  if (sassModule !== null) {
+  // Return cached async result first, then sync cache
+  if (sassModuleAsync !== null) {
+    return sassModuleAsync;
+  }
+  if (sassModule !== null && sassModule !== false) {
     return sassModule;
   }
 
   try {
     // Try to import sass from the user's project
-    sassModule = await import('sass');
-    return sassModule;
+    const mod = await import('sass');
+    sassModule = mod;
+    sassModuleAsync = mod;
+    return mod;
   } catch {
     // Fall back to sync require
-    return tryLoadSassSync();
+    const syncResult = tryLoadSassSync();
+    sassModuleAsync = syncResult || false;
+    return syncResult;
   }
 }
 
@@ -355,17 +365,22 @@ export function tryLoadLessSync() {
  * @returns {Promise<object|false>} The less module or false if not available
  */
 export async function tryLoadLess() {
-  // Return cached result if already checked
-  if (lessModule !== null) {
+  if (lessModuleAsync !== null) {
+    return lessModuleAsync;
+  }
+  if (lessModule !== null && lessModule !== false) {
     return lessModule;
   }
 
   try {
-    lessModule = await import('less');
-    return lessModule;
+    const mod = await import('less');
+    lessModule = mod;
+    lessModuleAsync = mod;
+    return mod;
   } catch {
-    // Fall back to sync require
-    return tryLoadLessSync();
+    const syncResult = tryLoadLessSync();
+    lessModuleAsync = syncResult || false;
+    return syncResult;
   }
 }
 
@@ -498,17 +513,22 @@ export function tryLoadStylusSync() {
  * @returns {Promise<object|false>} The stylus module or false if not available
  */
 export async function tryLoadStylus() {
-  // Return cached result if already checked
-  if (stylusModule !== null) {
+  if (stylusModuleAsync !== null) {
+    return stylusModuleAsync;
+  }
+  if (stylusModule !== null && stylusModule !== false) {
     return stylusModule;
   }
 
   try {
-    stylusModule = await import('stylus');
-    return stylusModule;
+    const mod = await import('stylus');
+    stylusModule = mod;
+    stylusModuleAsync = mod;
+    return mod;
   } catch {
-    // Fall back to sync require
-    return tryLoadStylusSync();
+    const syncResult = tryLoadStylusSync();
+    stylusModuleAsync = syncResult || false;
+    return syncResult;
   }
 }
 

package/compiler/sourcemap.js

@@ -21,7 +21,7 @@ const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz012345
 export function encodeVLQ(value) {
   let encoded = '';
   // Convert to unsigned and add sign bit
-  let vlq = value < 0 ? ((-value) << 1) + 1 : (value << 1);
+  let vlq = value < 0 ? ((-value) * 2) + 1 : (value * 2);
 
   do {
     let digit = vlq & 0x1F; // 5 bits
@@ -350,6 +350,8 @@ export class SourceMapConsumer {
         lineData.push(mapping);
       }
 
+      // Sort by generatedColumn to ensure binary-search-safe ordering
+      lineData.sort((a, b) => a.generatedColumn - b.generatedColumn);
       this._decodedMappings.push(lineData);
     }
   }