@blac/core 2.0.0-rc-11 → 2.0.0-rc-14

package/src/utils/RerenderLogger.ts

@@ -0,0 +1,265 @@
+import { Blac } from '../Blac';
+import { BlocBase } from '../BlocBase';
+
+export interface RerenderInfo {
+  componentName: string;
+  blocName: string;
+  blocId: string;
+  renderCount: number;
+  reason: RerenderReason;
+  timestamp: number;
+  duration?: number;
+  stackTrace?: string;
+}
+
+export interface RerenderReason {
+  type:
+    | 'state-change'
+    | 'dependency-change'
+    | 'mount'
+    | 'props-change'
+    | 'unknown';
+  changedPaths?: string[];
+  oldValues?: Record<string, any>;
+  newValues?: Record<string, any>;
+  dependencies?: string[];
+  description?: string;
+}
+
+/**
+ * Utility class for logging component rerenders with detailed debugging information
+ */
+export class RerenderLogger {
+  private static componentRenderCounts = new Map<string, number>();
+  private static lastRenderTimestamps = new Map<string, number>();
+  private static groupedLogs = new Map<string, RerenderInfo[]>();
+  private static groupTimeouts = new Map<string, NodeJS.Timeout>();
+
+  /**
+   * Log a component rerender with detailed information
+   */
+  static logRerender(info: RerenderInfo): void {
+    // RerenderLogger is now controlled by the RenderLoggingPlugin
+    // This method is called by the plugin which already handles configuration
+    const config = (Blac as any)._config?.rerenderLogging;
+    if (!config) return;
+
+    // Parse config
+    const loggingConfig = this.parseConfig(config);
+    if (!loggingConfig.enabled) return;
+
+    // Apply filter if provided
+    if (
+      loggingConfig.filter &&
+      !loggingConfig.filter({
+        componentName: info.componentName,
+        blocName: info.blocName,
+      })
+    ) {
+      return;
+    }
+
+    // Track render count
+    const key = `${info.componentName}-${info.blocId}`;
+    const currentCount = this.componentRenderCounts.get(key) || 0;
+    this.componentRenderCounts.set(key, currentCount + 1);
+    info.renderCount = currentCount + 1;
+
+    // Calculate duration if possible
+    const lastTimestamp = this.lastRenderTimestamps.get(key);
+    if (lastTimestamp) {
+      info.duration = info.timestamp - lastTimestamp;
+    }
+    this.lastRenderTimestamps.set(key, info.timestamp);
+
+    // Add stack trace if requested
+    if (loggingConfig.includeStackTrace && loggingConfig.level === 'detailed') {
+      info.stackTrace = new Error().stack;
+    }
+
+    // Handle grouping
+    if (loggingConfig.groupRerenders) {
+      this.logGrouped(info, loggingConfig);
+    } else {
+      this.logImmediate(info, loggingConfig);
+    }
+  }
+
+  /**
+   * Parse the logging configuration
+   */
+  private static parseConfig(config: any) {
+    if (config === true) {
+      return { enabled: true, level: 'normal' as const };
+    }
+    if (typeof config === 'string') {
+      return {
+        enabled: true,
+        level:
+          config === 'minimal' ? ('minimal' as const) : ('detailed' as const),
+      };
+    }
+    return {
+      enabled: config.enabled,
+      level: config.level || ('normal' as const),
+      filter: config.filter,
+      includeStackTrace: config.includeStackTrace,
+      groupRerenders: config.groupRerenders,
+    };
+  }
+
+  /**
+   * Log immediately without grouping
+   */
+  private static logImmediate(
+    info: RerenderInfo,
+    config: ReturnType<typeof RerenderLogger.parseConfig>,
+  ): void {
+    const message = this.formatMessage(info, config.level!);
+
+    if (config.level === 'detailed') {
+      console.group(message.header);
+      if (message.details) console.log(message.details);
+      if (message.values) console.table(message.values);
+      if (info.stackTrace) console.log('Stack trace:', info.stackTrace);
+      console.groupEnd();
+    } else {
+      console.log(message.header, message.details || '');
+    }
+  }
+
+  /**
+   * Log with grouping (batch multiple rerenders)
+   */
+  private static logGrouped(
+    info: RerenderInfo,
+    config: ReturnType<typeof RerenderLogger.parseConfig>,
+  ): void {
+    const groupKey = `${info.componentName}-${info.blocId}`;
+
+    // Clear existing timeout
+    const existingTimeout = this.groupTimeouts.get(groupKey);
+    if (existingTimeout) {
+      clearTimeout(existingTimeout);
+    }
+
+    // Add to group
+    const group = this.groupedLogs.get(groupKey) || [];
+    group.push(info);
+    this.groupedLogs.set(groupKey, group);
+
+    // Set new timeout
+    const timeout = setTimeout(() => {
+      const logs = this.groupedLogs.get(groupKey) || [];
+      this.groupedLogs.delete(groupKey);
+      this.groupTimeouts.delete(groupKey);
+
+      if (logs.length === 1) {
+        this.logImmediate(logs[0], config);
+      } else {
+        console.group(
+          `🔄 ${info.componentName} rendered ${logs.length} times (${info.blocName})`,
+        );
+        logs.forEach((log, index) => {
+          const message = this.formatMessage(log, config.level!);
+          console.log(`  ${index + 1}. ${message.details || message.header}`);
+        });
+        console.groupEnd();
+      }
+    }, 50); // 50ms debounce
+
+    this.groupTimeouts.set(groupKey, timeout);
+  }
+
+  /**
+   * Format the log message based on level
+   */
+  private static formatMessage(
+    info: RerenderInfo,
+    level: 'minimal' | 'normal' | 'detailed',
+  ) {
+    const emoji = this.getReasonEmoji(info.reason.type);
+
+    if (level === 'minimal') {
+      return {
+        header: `${emoji} ${info.componentName} #${info.renderCount}`,
+        details: null,
+        values: null,
+      };
+    }
+
+    const header = `${emoji} ${info.componentName} rerender #${info.renderCount} (${info.blocName})`;
+
+    let details = `Reason: ${info.reason.description || info.reason.type}`;
+
+    if (info.duration !== undefined) {
+      details += ` | Time since last: ${info.duration}ms`;
+    }
+
+    if (
+      level === 'normal' &&
+      info.reason.changedPaths &&
+      info.reason.changedPaths.length > 0
+    ) {
+      details += ` | Changed: ${info.reason.changedPaths.join(', ')}`;
+    }
+
+    let values: Record<string, { old: any; new: any }> | null = null;
+    if (
+      level === 'detailed' &&
+      info.reason.changedPaths &&
+      info.reason.changedPaths.length > 0
+    ) {
+      values = {};
+      info.reason.changedPaths.forEach((path) => {
+        values![path] = {
+          old: info.reason.oldValues?.[path],
+          new: info.reason.newValues?.[path],
+        };
+      });
+
+      // If we have values to show in detailed mode, ensure they're not empty
+      if (Object.keys(values).length === 0) {
+        values = null;
+      }
+    }
+
+    return { header, details, values };
+  }
+
+  /**
+   * Get emoji for reason type
+   */
+  private static getReasonEmoji(type: RerenderReason['type']): string {
+    switch (type) {
+      case 'state-change':
+        return '📊';
+      case 'dependency-change':
+        return '🔗';
+      case 'mount':
+        return '🚀';
+      case 'props-change':
+        return '📦';
+      default:
+        return '🔄';
+    }
+  }
+
+  /**
+   * Clear all tracking data
+   */
+  static clear(): void {
+    this.componentRenderCounts.clear();
+    this.lastRenderTimestamps.clear();
+    this.groupedLogs.clear();
+    this.groupTimeouts.forEach((timeout) => clearTimeout(timeout));
+    this.groupTimeouts.clear();
+  }
+
+  /**
+   * Get render count for a component
+   */
+  static getRenderCount(componentName: string, blocId: string): number {
+    return this.componentRenderCounts.get(`${componentName}-${blocId}`) || 0;
+  }
+}

package/src/utils/__tests__/generateInstanceId.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { generateInstanceIdFromProps } from '../generateInstanceId';
+
+describe('generateInstanceIdFromProps', () => {
+  it('returns undefined for non-object props', () => {
+    expect(generateInstanceIdFromProps(null)).toBeUndefined();
+    expect(generateInstanceIdFromProps(undefined)).toBeUndefined();
+    expect(generateInstanceIdFromProps('string')).toBeUndefined();
+    expect(generateInstanceIdFromProps(123)).toBeUndefined();
+    expect(generateInstanceIdFromProps(true)).toBeUndefined();
+  });
+
+  it('returns undefined for objects with no primitive values', () => {
+    expect(generateInstanceIdFromProps({})).toBeUndefined();
+    expect(
+      generateInstanceIdFromProps({ obj: {}, arr: [], fn: () => {} }),
+    ).toBeUndefined();
+    expect(
+      generateInstanceIdFromProps({ date: new Date(), regex: /test/ }),
+    ).toBeUndefined();
+  });
+
+  it('generates ID from string values', () => {
+    expect(generateInstanceIdFromProps({ id: 'user123' })).toBe('id:user123');
+    expect(generateInstanceIdFromProps({ name: 'John', role: 'admin' })).toBe(
+      'name:John|role:admin',
+    );
+  });
+
+  it('generates ID from number values', () => {
+    expect(generateInstanceIdFromProps({ page: 1 })).toBe('page:1');
+    expect(generateInstanceIdFromProps({ x: 10, y: 20 })).toBe('x:10|y:20');
+    expect(generateInstanceIdFromProps({ float: 3.14 })).toBe('float:3.14');
+  });
+
+  it('generates ID from boolean values', () => {
+    expect(generateInstanceIdFromProps({ active: true })).toBe('active:true');
+    expect(generateInstanceIdFromProps({ visible: false })).toBe(
+      'visible:false',
+    );
+  });
+
+  it('generates ID from null and undefined values', () => {
+    expect(generateInstanceIdFromProps({ val: null })).toBe('val:null');
+    expect(generateInstanceIdFromProps({ val: undefined })).toBe(
+      'val:undefined',
+    );
+  });
+
+  it('generates ID from mixed primitive types', () => {
+    const props = {
+      id: 'abc',
+      page: 2,
+      active: true,
+      extra: null,
+      missing: undefined,
+    };
+    expect(generateInstanceIdFromProps(props)).toBe(
+      'active:true|extra:null|id:abc|missing:undefined|page:2',
+    );
+  });
+
+  it('ignores non-primitive values', () => {
+    const props = {
+      id: 'test',
+      obj: { nested: true },
+      arr: [1, 2, 3],
+      fn: () => {},
+      page: 5,
+    };
+    expect(generateInstanceIdFromProps(props)).toBe('id:test|page:5');
+  });
+
+  it('sorts keys alphabetically for deterministic output', () => {
+    const props1 = { z: 1, a: 2, m: 3 };
+    const props2 = { m: 3, z: 1, a: 2 };
+    const props3 = { a: 2, m: 3, z: 1 };
+
+    const expected = 'a:2|m:3|z:1';
+    expect(generateInstanceIdFromProps(props1)).toBe(expected);
+    expect(generateInstanceIdFromProps(props2)).toBe(expected);
+    expect(generateInstanceIdFromProps(props3)).toBe(expected);
+  });
+
+  it('handles edge cases', () => {
+    expect(generateInstanceIdFromProps({ '': 'empty' })).toBe(':empty');
+    expect(generateInstanceIdFromProps({ 'key|with|pipes': 'value' })).toBe(
+      'key|with|pipes:value',
+    );
+    expect(generateInstanceIdFromProps({ 'key:with:colons': 'value' })).toBe(
+      'key:with:colons:value',
+    );
+  });
+
+  it('handles special number values', () => {
+    expect(generateInstanceIdFromProps({ inf: Infinity })).toBe('inf:Infinity');
+    expect(generateInstanceIdFromProps({ ninf: -Infinity })).toBe(
+      'ninf:-Infinity',
+    );
+    expect(generateInstanceIdFromProps({ nan: NaN })).toBe('nan:NaN');
+    expect(generateInstanceIdFromProps({ zero: 0 })).toBe('zero:0');
+    expect(generateInstanceIdFromProps({ negZero: -0 })).toBe('negZero:0');
+  });
+});

package/src/utils/__tests__/shallowEqual.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect } from 'vitest';
+import { shallowEqual } from '../shallowEqual';
+
+describe('shallowEqual', () => {
+  describe('Primitive values', () => {
+    it('should return true for identical primitives', () => {
+      expect(shallowEqual(1, 1)).toBe(true);
+      expect(shallowEqual('hello', 'hello')).toBe(true);
+      expect(shallowEqual(true, true)).toBe(true);
+      expect(shallowEqual(null, null)).toBe(true);
+      expect(shallowEqual(undefined, undefined)).toBe(true);
+    });
+
+    it('should return false for different primitives', () => {
+      expect(shallowEqual(1, 2)).toBe(false);
+      expect(shallowEqual('hello', 'world')).toBe(false);
+      expect(shallowEqual(true, false)).toBe(false);
+      expect(shallowEqual(null, undefined)).toBe(false);
+      expect(shallowEqual(0, false)).toBe(false);
+    });
+
+    it('should handle special numeric values using Object.is', () => {
+      expect(shallowEqual(NaN, NaN)).toBe(true); // Object.is(NaN, NaN) is true
+      expect(shallowEqual(0, -0)).toBe(false); // Object.is can distinguish +0 and -0
+      expect(shallowEqual(-0, -0)).toBe(true);
+      expect(shallowEqual(Infinity, Infinity)).toBe(true);
+      expect(shallowEqual(-Infinity, -Infinity)).toBe(true);
+      expect(shallowEqual(Infinity, -Infinity)).toBe(false);
+    });
+  });
+
+  describe('Object comparison', () => {
+    it('should return true for objects with same properties', () => {
+      expect(shallowEqual({ a: 1, b: 2 }, { a: 1, b: 2 })).toBe(true);
+      expect(
+        shallowEqual({ name: 'John', age: 30 }, { name: 'John', age: 30 }),
+      ).toBe(true);
+      expect(shallowEqual({}, {})).toBe(true);
+    });
+
+    it('should return false for objects with different values', () => {
+      expect(shallowEqual({ a: 1 }, { a: 2 })).toBe(false);
+      expect(shallowEqual({ name: 'John' }, { name: 'Jane' })).toBe(false);
+    });
+
+    it('should return false for objects with different keys', () => {
+      expect(shallowEqual({ a: 1 }, { b: 1 })).toBe(false);
+      expect(shallowEqual({ a: 1, b: 2 }, { a: 1 })).toBe(false);
+      expect(shallowEqual({ a: 1 }, { a: 1, b: 2 })).toBe(false);
+    });
+
+    it('should return true for same object reference', () => {
+      const obj = { a: 1, b: 2 };
+      expect(shallowEqual(obj, obj)).toBe(true);
+    });
+
+    it('should only compare one level deep (shallow)', () => {
+      const obj1 = { a: 1, b: { c: 2 } };
+      const obj2 = { a: 1, b: { c: 2 } };
+      expect(shallowEqual(obj1, obj2)).toBe(false); // Different object references for b
+
+      const sharedNested = { c: 2 };
+      const obj3 = { a: 1, b: sharedNested };
+      const obj4 = { a: 1, b: sharedNested };
+      expect(shallowEqual(obj3, obj4)).toBe(true); // Same reference for b
+    });
+
+    it('should handle objects with null/undefined values', () => {
+      expect(shallowEqual({ a: null }, { a: null })).toBe(true);
+      expect(shallowEqual({ a: undefined }, { a: undefined })).toBe(true);
+      expect(shallowEqual({ a: null }, { a: undefined })).toBe(false);
+    });
+  });
+
+  describe('Array comparison', () => {
+    it('should compare arrays shallowly', () => {
+      expect(shallowEqual([1, 2, 3], [1, 2, 3])).toBe(true);
+      expect(shallowEqual([1, 2, 3], [1, 2, 4])).toBe(false);
+      expect(shallowEqual([1, 2], [1, 2, 3])).toBe(false);
+      expect(shallowEqual([], [])).toBe(true);
+    });
+
+    it('should return true for same array reference', () => {
+      const arr = [1, 2, 3];
+      expect(shallowEqual(arr, arr)).toBe(true);
+    });
+
+    it('should handle nested arrays shallowly', () => {
+      const nested = [4, 5];
+      expect(shallowEqual([1, [2, 3]], [1, [2, 3]])).toBe(false); // Different array references
+      expect(shallowEqual([1, nested], [1, nested])).toBe(true); // Same reference
+    });
+  });
+
+  describe('Mixed types', () => {
+    it('should return false when comparing different types', () => {
+      // Arrays and objects with same keys will be considered equal by shallowEqual
+      // since it only checks enumerable keys
+      const arr: any[] = [];
+      const obj = {};
+      expect(shallowEqual(obj, arr)).toBe(true); // Both have 0 enumerable keys
+
+      const arr2 = [1, 2];
+      const obj2 = { 0: 1, 1: 2 };
+      expect(shallowEqual(obj2, arr2)).toBe(true); // Same enumerable keys and values
+
+      // These should return false because of type differences
+      expect(
+        shallowEqual('hello', { 0: 'h', 1: 'e', 2: 'l', 3: 'l', 4: 'o' }),
+      ).toBe(false);
+      expect(shallowEqual(42, { valueOf: () => 42 })).toBe(false);
+    });
+
+    it('should return false when comparing objects with primitives', () => {
+      expect(shallowEqual({}, null)).toBe(false);
+      expect(shallowEqual({}, undefined)).toBe(false);
+      expect(shallowEqual({}, 'object')).toBe(false);
+      expect(shallowEqual({}, 123)).toBe(false);
+      expect(shallowEqual({}, true)).toBe(false);
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('should handle objects with prototype properties correctly', () => {
+      const obj1 = Object.create({ inherited: true });
+      obj1.own = 'property';
+
+      const obj2 = { own: 'property' };
+
+      expect(shallowEqual(obj1, obj2)).toBe(true); // Only compares own properties
+    });
+
+    it('should handle objects with Symbol properties', () => {
+      const sym = Symbol('test');
+      const obj1 = { [sym]: 'value', a: 1 };
+      const obj2 = { [sym]: 'value', a: 1 };
+
+      // Symbol properties are not enumerated by Object.keys
+      expect(shallowEqual(obj1, obj2)).toBe(true);
+    });
+
+    it('should handle Date objects', () => {
+      const date1 = new Date('2023-01-01');
+      const date2 = new Date('2023-01-01');
+      const sameDate = date1;
+
+      // Date objects have no enumerable properties, so they're considered equal
+      expect(shallowEqual(date1, date2)).toBe(true); // Both have 0 enumerable keys
+      expect(shallowEqual(date1, sameDate)).toBe(true); // Same reference
+    });
+
+    it('should handle RegExp objects', () => {
+      const regex1 = /test/g;
+      const regex2 = /test/g;
+      const sameRegex = regex1;
+
+      // RegExp objects have no enumerable properties, so they're considered equal
+      expect(shallowEqual(regex1, regex2)).toBe(true); // Both have 0 enumerable keys
+      expect(shallowEqual(regex1, sameRegex)).toBe(true); // Same reference
+    });
+
+    it('should handle functions', () => {
+      const fn1 = () => {};
+      const fn2 = () => {};
+      const sameFn = fn1;
+
+      expect(shallowEqual(fn1, fn2)).toBe(false);
+      expect(shallowEqual(fn1, sameFn)).toBe(true);
+    });
+  });
+});

package/src/utils/__tests__/uuid.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { generateUUID } from '../uuid';
+
+describe('generateUUID', () => {
+  const UUID_REGEX =
+    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+  describe('crypto.randomUUID available', () => {
+    it('should use crypto.randomUUID when available', () => {
+      const mockRandomUUID = vi.fn(
+        () => '550e8400-e29b-41d4-a716-446655440000',
+      );
+
+      // Mock the crypto object
+      vi.stubGlobal('crypto', {
+        randomUUID: mockRandomUUID,
+      });
+
+      const uuid = generateUUID();
+
+      expect(mockRandomUUID).toHaveBeenCalled();
+      expect(uuid).toBe('550e8400-e29b-41d4-a716-446655440000');
+
+      vi.unstubAllGlobals();
+    });
+
+    it('should return valid UUID v4 format from native crypto.randomUUID', () => {
+      // Test with real crypto.randomUUID if available
+      if (typeof crypto !== 'undefined' && crypto.randomUUID !== undefined) {
+        const uuid = generateUUID();
+        expect(uuid).toMatch(UUID_REGEX);
+      } else {
+        // Skip test if crypto.randomUUID is not available in test environment
+        expect(true).toBe(true);
+      }
+    });
+  });
+
+  describe('Fallback implementation', () => {
+    beforeEach(() => {
+      // Remove crypto to force fallback
+      vi.stubGlobal('crypto', undefined);
+    });
+
+    afterEach(() => {
+      vi.unstubAllGlobals();
+    });
+
+    it('should generate valid UUID v4 format using fallback', () => {
+      const uuid = generateUUID();
+      expect(uuid).toMatch(UUID_REGEX);
+    });
+
+    it('should generate unique UUIDs', () => {
+      const uuids = new Set();
+      const count = 1000;
+
+      for (let i = 0; i < count; i++) {
+        uuids.add(generateUUID());
+      }
+
+      // All generated UUIDs should be unique
+      expect(uuids.size).toBe(count);
+    });
+
+    it('should have correct version and variant bits', () => {
+      for (let i = 0; i < 100; i++) {
+        const uuid = generateUUID();
+        const parts = uuid.split('-');
+
+        // Version 4 UUID should have '4' in the third group
+        expect(parts[2][0]).toBe('4');
+
+        // Variant bits should be correct (8, 9, a, or b)
+        const variantChar = parts[3][0].toLowerCase();
+        expect(['8', '9', 'a', 'b']).toContain(variantChar);
+      }
+    });
+
+    it('should have correct length and format', () => {
+      const uuid = generateUUID();
+
+      expect(uuid.length).toBe(36);
+      expect(uuid.split('-').length).toBe(5);
+
+      const parts = uuid.split('-');
+      expect(parts[0].length).toBe(8);
+      expect(parts[1].length).toBe(4);
+      expect(parts[2].length).toBe(4);
+      expect(parts[3].length).toBe(4);
+      expect(parts[4].length).toBe(12);
+    });
+  });
+
+  describe('Environment compatibility', () => {
+    it('should work when crypto is defined but randomUUID is not', () => {
+      // Mock crypto without randomUUID
+      vi.stubGlobal('crypto', {});
+
+      const uuid = generateUUID();
+      expect(uuid).toMatch(UUID_REGEX);
+
+      vi.unstubAllGlobals();
+    });
+
+    it('should work with different Math.random implementations', () => {
+      // First remove crypto to ensure fallback
+      vi.stubGlobal('crypto', undefined);
+
+      const originalMathRandom = Math.random;
+      let callCount = 0;
+
+      // Mock Math.random to return predictable values
+      Math.random = vi.fn(() => {
+        callCount++;
+        return (callCount % 16) / 16;
+      });
+
+      const uuid = generateUUID();
+      expect(uuid).toMatch(UUID_REGEX);
+      expect(Math.random).toHaveBeenCalled();
+
+      Math.random = originalMathRandom;
+      vi.unstubAllGlobals();
+    });
+  });
+
+  describe('Performance', () => {
+    it('should generate UUIDs efficiently', () => {
+      const startTime = performance.now();
+      const iterations = 10000;
+
+      for (let i = 0; i < iterations; i++) {
+        generateUUID();
+      }
+
+      const endTime = performance.now();
+      const totalTime = endTime - startTime;
+
+      // Should generate 10,000 UUIDs in less than 100ms
+      expect(totalTime).toBeLessThan(100);
+    });
+  });
+});