debug-better 1.0.0

package/src/common.ts

@@ -0,0 +1,306 @@
+/**
+ * Common logic for both Node.js and browser implementations
+ */
+
+import ms = require('ms');
+import {
+  Debugger,
+  DebugFactory,
+  DebugOptions,
+  EnvironmentConfig,
+  FilterOptions,
+} from './types';
+import { FilterManager, globalFilter } from './filter';
+
+/**
+ * Setup function that creates the debug factory with environment-specific config
+ */
+export function setup(env: EnvironmentConfig): DebugFactory {
+  /**
+   * Create a new debugger instance
+   */
+  function createDebug(namespace: string, options: DebugOptions = {}): Debugger {
+    let prevTime: number | undefined;
+    let enableOverride: boolean | null = null;
+    let namespacesCache: string;
+    let enabledCache: boolean;
+
+    // Instance-specific filter
+    const instanceFilter = new FilterManager(options.filter);
+
+    function debug(...args: any[]): void {
+      // Check if disabled (using the property that will be defined below)
+      if (!(debug as any).enabled) {
+        return;
+      }
+
+      // Apply global and instance filters
+      if (!globalFilter.shouldLog(namespace, args)) {
+        return;
+      }
+
+      if (!instanceFilter.shouldLog(namespace, args)) {
+        return;
+      }
+
+      const self = debug;
+
+      // Set timestamp diffs
+      const curr = Number(new Date());
+      const ms = curr - (prevTime || curr);
+      self.diff = ms;
+      self.prev = prevTime || curr;
+      self.curr = curr;
+      prevTime = curr;
+
+      args[0] = (createDebug as any).coerce(args[0]);
+
+      if (typeof args[0] !== 'string') {
+        // Inspect with %O
+        args.unshift('%O');
+      }
+
+      // Apply formatters
+      let index = 0;
+      args[0] = args[0].replace(/%([a-zA-Z%])/g, (match: string, format: string) => {
+        // Handle escaped %
+        if (match === '%%') {
+          return '%';
+        }
+        index++;
+        const formatter = (createDebug as any).formatters[format];
+        if (typeof formatter === 'function') {
+          const val = args[index];
+          match = formatter.call(self, val);
+          // Remove the inlined argument
+          args.splice(index, 1);
+          index--;
+        }
+        return match;
+      });
+
+      // Apply environment-specific formatting
+      (createDebug as any).formatArgs.call(self, args);
+
+      const logFn = self.log || (createDebug as any).log;
+      logFn.apply(self, args);
+    }
+
+    debug.namespace = namespace;
+    debug.useColors = options.useColors ?? (createDebug as any).useColors();
+    debug.color = options.color ?? (createDebug as any).selectColor(namespace);
+    debug.diff = 0;
+    debug.prev = 0;
+    debug.curr = 0;
+    debug.metadata = options.metadata || {};
+    debug.log = options.log || env.log;
+
+    debug.extend = function (ns: string, delimiter?: string): Debugger {
+      const sep = typeof delimiter === 'undefined' ? ':' : delimiter;
+      const newDebug = createDebug(this.namespace + sep + ns);
+      newDebug.log = this.log;
+      return newDebug;
+    };
+
+    debug.destroy = (createDebug as any).destroy;
+
+    debug.setFilter = function (filter: FilterOptions) {
+      instanceFilter.setOptions(filter);
+    };
+
+    debug.setMetadata = function (key: string, value: any) {
+      this.metadata[key] = value;
+    };
+
+    debug.getMetadata = function (key: string) {
+      return this.metadata[key];
+    };
+
+    Object.defineProperty(debug, 'enabled', {
+      enumerable: true,
+      configurable: false,
+      get(): boolean {
+        if (enableOverride !== null) {
+          return enableOverride;
+        }
+        if (namespacesCache !== (createDebug as any).namespaces) {
+          namespacesCache = (createDebug as any).namespaces;
+          enabledCache = (createDebug as any).enabled(namespace);
+        }
+        return enabledCache;
+      },
+      set(v: boolean) {
+        enableOverride = v;
+      },
+    });
+
+    // Environment-specific initialization
+    if (typeof (createDebug as any).init === 'function') {
+      (createDebug as any).init(debug);
+    }
+
+    return debug as Debugger;
+  }
+
+  // Attach properties from environment config
+  (createDebug as any).names = [];
+  (createDebug as any).skips = [];
+  (createDebug as any).formatters = {};
+  (createDebug as any).namespaces = '';
+
+  // Copy environment-specific properties
+  Object.keys(env).forEach((key) => {
+    (createDebug as any)[key] = (env as any)[key];
+  });
+
+  createDebug.humanize = ms;
+
+  /**
+   * Select a color for a namespace
+   */
+  (createDebug as any).selectColor = function (namespace: string): string | number {
+    let hash = 0;
+    for (let i = 0; i < namespace.length; i++) {
+      hash = (hash << 5) - hash + namespace.charCodeAt(i);
+      hash |= 0; // Convert to 32bit integer
+    }
+    return (createDebug as any).colors[Math.abs(hash) % (createDebug as any).colors.length];
+  };
+
+  /**
+   * Enable namespaces
+   */
+  (createDebug as any).enable = function (namespaces: string): void {
+    (createDebug as any).save(namespaces);
+    (createDebug as any).namespaces = namespaces;
+
+    (createDebug as any).names = [];
+    (createDebug as any).skips = [];
+
+    const split = (typeof namespaces === 'string' ? namespaces : '')
+      .trim()
+      .replace(/\s+/g, ',')
+      .split(',')
+      .filter(Boolean);
+
+    for (const ns of split) {
+      if (ns[0] === '-') {
+        (createDebug as any).skips.push(ns.slice(1));
+      } else {
+        (createDebug as any).names.push(ns);
+      }
+    }
+  };
+
+  /**
+   * Disable all namespaces
+   */
+  (createDebug as any).disable = function (): string {
+    const namespaces = [
+      ...(createDebug as any).names,
+      ...(createDebug as any).skips.map((ns: string) => '-' + ns),
+    ].join(',');
+    (createDebug as any).enable('');
+    return namespaces;
+  };
+
+  /**
+   * Check if a namespace is enabled
+   */
+  (createDebug as any).enabled = function (name: string): boolean {
+    // Check skips first
+    for (const skip of (createDebug as any).skips) {
+      if (matchesTemplate(name, skip)) {
+        return false;
+      }
+    }
+
+    // Check names
+    for (const ns of (createDebug as any).names) {
+      if (matchesTemplate(name, ns)) {
+        return true;
+      }
+    }
+
+    return false;
+  };
+
+  /**
+   * Coerce a value
+   */
+  (createDebug as any).coerce = function (val: any): any {
+    if (val instanceof Error) {
+      return val.stack || val.message;
+    }
+    return val;
+  };
+
+  /**
+   * Destroy (deprecated)
+   */
+  (createDebug as any).destroy = function (): void {
+    console.warn(
+      'Instance method `debug.destroy()` is deprecated and no longer does anything. It will be removed in the next major version.'
+    );
+  };
+
+  /**
+   * Set global filter options
+   */
+  (createDebug as any).setGlobalFilter = function (filter: FilterOptions) {
+    globalFilter.setOptions(filter);
+  };
+
+  /**
+   * Get global filter options
+   */
+  (createDebug as any).getGlobalFilter = function () {
+    return globalFilter.getOptions();
+  };
+
+  // Load saved namespaces
+  (createDebug as any).enable((createDebug as any).load());
+
+  return createDebug as any as DebugFactory;
+}
+
+/**
+ * Match a namespace against a template with wildcards
+ */
+function matchesTemplate(search: string, template: string): boolean {
+  let searchIndex = 0;
+  let templateIndex = 0;
+  let starIndex = -1;
+  let matchIndex = 0;
+
+  while (searchIndex < search.length) {
+    if (
+      templateIndex < template.length &&
+      (template[templateIndex] === search[searchIndex] || template[templateIndex] === '*')
+    ) {
+      if (template[templateIndex] === '*') {
+        starIndex = templateIndex;
+        matchIndex = searchIndex;
+        templateIndex++;
+      } else {
+        searchIndex++;
+        templateIndex++;
+      }
+    } else if (starIndex !== -1) {
+      templateIndex = starIndex + 1;
+      matchIndex++;
+      searchIndex = matchIndex;
+    } else {
+      return false;
+    }
+  }
+
+  // Handle trailing wildcards
+  while (templateIndex < template.length && template[templateIndex] === '*') {
+    templateIndex++;
+  }
+
+  return templateIndex === template.length;
+}
+
+export { matchesTemplate };

package/src/filter.ts

@@ -0,0 +1,204 @@
+/**
+ * Advanced filtering capabilities for debug-utility
+ */
+
+import { FilterOptions, FilterPredicate } from './types';
+
+/**
+ * Filter manager class for handling complex filtering logic
+ */
+export class FilterManager {
+  private options: FilterOptions;
+
+  constructor(options: FilterOptions = {}) {
+    this.options = {
+      enabled: true,
+      patterns: [],
+      predicates: [],
+      tags: [],
+      include: [],
+      exclude: [],
+      ...options,
+    };
+  }
+
+  /**
+   * Update filter options
+   */
+  setOptions(options: Partial<FilterOptions>): void {
+    this.options = { ...this.options, ...options };
+  }
+
+  /**
+   * Get current filter options
+   */
+  getOptions(): FilterOptions {
+    return { ...this.options };
+  }
+
+  /**
+   * Check if a namespace passes the filter
+   */
+  shouldLog(namespace: string, args: any[] = []): boolean {
+    if (!this.options.enabled) {
+      return true;
+    }
+
+    // Check exclude list first (highest priority)
+    if (this.options.exclude && this.options.exclude.length > 0) {
+      for (const pattern of this.options.exclude) {
+        if (this.matchPattern(namespace, pattern)) {
+          return false;
+        }
+      }
+    }
+
+    // Check include list
+    if (this.options.include && this.options.include.length > 0) {
+      let included = false;
+      for (const pattern of this.options.include) {
+        if (this.matchPattern(namespace, pattern)) {
+          included = true;
+          break;
+        }
+      }
+      if (!included) {
+        return false;
+      }
+    }
+
+    // Check regex patterns
+    if (this.options.patterns && this.options.patterns.length > 0) {
+      let matched = false;
+      for (const pattern of this.options.patterns) {
+        if (pattern.test(namespace)) {
+          matched = true;
+          break;
+        }
+      }
+      if (!matched) {
+        return false;
+      }
+    }
+
+    // Check custom predicates
+    if (this.options.predicates && this.options.predicates.length > 0) {
+      for (const predicate of this.options.predicates) {
+        if (!predicate(namespace, ...args)) {
+          return false;
+        }
+      }
+    }
+
+    // Check tags (if first argument is an object with tags)
+    if (this.options.tags && this.options.tags.length > 0) {
+      if (args.length > 0 && typeof args[0] === 'object' && args[0].tags) {
+        const argTags = Array.isArray(args[0].tags) ? args[0].tags : [args[0].tags];
+        const hasMatchingTag = argTags.some((tag: string) =>
+          this.options.tags!.includes(tag)
+        );
+        if (!hasMatchingTag) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Match a namespace against a pattern (supports wildcards)
+   */
+  private matchPattern(namespace: string, pattern: string): boolean {
+    // Convert wildcard pattern to regex
+    const regexPattern = pattern
+      .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape special chars
+      .replace(/\*/g, '.*'); // Replace * with .*
+
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(namespace);
+  }
+
+  /**
+   * Add a custom predicate filter
+   */
+  addPredicate(predicate: FilterPredicate): void {
+    if (!this.options.predicates) {
+      this.options.predicates = [];
+    }
+    this.options.predicates.push(predicate);
+  }
+
+  /**
+   * Add a regex pattern filter
+   */
+  addPattern(pattern: RegExp): void {
+    if (!this.options.patterns) {
+      this.options.patterns = [];
+    }
+    this.options.patterns.push(pattern);
+  }
+
+  /**
+   * Add include pattern
+   */
+  addInclude(pattern: string): void {
+    if (!this.options.include) {
+      this.options.include = [];
+    }
+    this.options.include.push(pattern);
+  }
+
+  /**
+   * Add exclude pattern
+   */
+  addExclude(pattern: string): void {
+    if (!this.options.exclude) {
+      this.options.exclude = [];
+    }
+    this.options.exclude.push(pattern);
+  }
+
+  /**
+   * Add tag filter
+   */
+  addTag(tag: string): void {
+    if (!this.options.tags) {
+      this.options.tags = [];
+    }
+    this.options.tags.push(tag);
+  }
+
+  /**
+   * Clear all filters
+   */
+  clear(): void {
+    this.options = {
+      enabled: true,
+      patterns: [],
+      predicates: [],
+      tags: [],
+      include: [],
+      exclude: [],
+    };
+  }
+
+  /**
+   * Enable filtering
+   */
+  enable(): void {
+    this.options.enabled = true;
+  }
+
+  /**
+   * Disable filtering
+   */
+  disable(): void {
+    this.options.enabled = false;
+  }
+}
+
+/**
+ * Global filter instance
+ */
+export const globalFilter = new FilterManager();

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Main entry point - detects environment and loads appropriate implementation
+ */
+
+/**
+ * Detect Electron renderer / nwjs process, which is node, but should
+ * be treated as a browser.
+ */
+
+if (
+  typeof process === 'undefined' ||
+  (process as any).type === 'renderer' ||
+  (process as any).browser === true ||
+  (process as any).__nwjs
+) {
+  module.exports = require('./browser');
+} else {
+  module.exports = require('./node');
+}
+
+// Export types for TypeScript users
+export * from './types';
+export { FilterManager, globalFilter } from './filter';

package/src/node.ts

@@ -0,0 +1,161 @@
+/**
+ * Node.js implementation of debug-utility
+ */
+
+import * as tty from 'tty';
+import * as util from 'util';
+import { setup } from './common';
+import { EnvironmentConfig, Debugger } from './types';
+
+/**
+ * Colors for Node.js (ANSI color codes)
+ */
+const colors = [
+  20, 21, 26, 27, 32, 33, 38, 39, 40, 41, 42, 43, 44, 45, 56, 57, 62, 63, 68, 69, 74, 75, 76, 77,
+  78, 79, 80, 81, 92, 93, 98, 99, 112, 113, 128, 129, 134, 135, 148, 149, 160, 161, 162, 163, 164,
+  165, 166, 167, 168, 169, 170, 171, 172, 173, 178, 179, 184, 185, 196, 197, 198, 199, 200, 201,
+  202, 203, 204, 205, 206, 207, 208, 209, 214, 215, 220, 221,
+];
+
+/**
+ * Check if supports-color is available (optional dependency)
+ */
+try {
+  const supportsColor = require('supports-color');
+  if (supportsColor && (supportsColor.stderr || supportsColor).level >= 2) {
+    // Use extended color palette if available
+  }
+} catch (e) {
+  // supports-color is optional
+}
+
+/**
+ * Build inspect options from environment variables
+ */
+const inspectOpts = Object.keys(process.env)
+  .filter((key) => /^debug_/i.test(key))
+  .reduce((obj: Record<string, any>, key: string) => {
+    // Convert DEBUG_COLORS to colors
+    const prop = key
+      .substring(6)
+      .toLowerCase()
+      .replace(/_([a-z])/g, (_, k) => k.toUpperCase());
+
+    // Coerce string value
+    let val: any = process.env[key];
+    if (/^(yes|on|true|enabled)$/i.test(val)) {
+      val = true;
+    } else if (/^(no|off|false|disabled)$/i.test(val)) {
+      val = false;
+    } else if (val === 'null') {
+      val = null;
+    } else {
+      val = Number(val);
+    }
+
+    obj[prop] = val;
+    return obj;
+  }, {});
+
+/**
+ * Check if colors should be used
+ */
+function useColors(): boolean {
+  if ('colors' in inspectOpts) {
+    return Boolean(inspectOpts.colors);
+  }
+  return tty.isatty(process.stderr.fd);
+}
+
+/**
+ * Format arguments with ANSI colors
+ */
+function formatArgs(this: Debugger, args: any[]): void {
+  const { namespace, useColors: shouldUseColors } = this;
+
+  if (shouldUseColors) {
+    const c = this.color as number;
+    const colorCode = '\u001B[3' + (c < 8 ? c : '8;5;' + c);
+    const prefix = `  ${colorCode};1m${namespace} \u001B[0m`;
+
+    args[0] = prefix + args[0].split('\n').join('\n' + prefix);
+    args.push(colorCode + 'm+' + ms(this.diff) + '\u001B[0m');
+  } else {
+    args[0] = getDate() + namespace + ' ' + args[0];
+  }
+}
+
+/**
+ * Get formatted date
+ */
+function getDate(): string {
+  if (inspectOpts.hideDate) {
+    return '';
+  }
+  return new Date().toISOString() + ' ';
+}
+
+/**
+ * Log to stderr
+ */
+function log(...args: any[]): void {
+  process.stderr.write(util.formatWithOptions(inspectOpts, ...args) + '\n');
+}
+
+/**
+ * Save namespaces to environment
+ */
+function save(namespaces: string): void {
+  if (namespaces) {
+    process.env.DEBUG = namespaces;
+  } else {
+    delete process.env.DEBUG;
+  }
+}
+
+/**
+ * Load namespaces from environment
+ */
+function load(): string {
+  return process.env.DEBUG || '';
+}
+
+/**
+ * Destroy function (deprecated)
+ */
+function destroy(): void {
+  console.warn(
+    'Instance method `debug.destroy()` is deprecated and no longer does anything.'
+  );
+}
+
+/**
+ * Initialize a debug instance (optional)
+ */
+function init(debug: Debugger): void {
+  // Initialization logic can be added here if needed
+  (debug as any).inspectOpts = inspectOpts;
+}
+
+// Import ms for humanizing time
+import ms = require('ms');
+
+/**
+ * Create environment config for Node.js
+ */
+const nodeEnv: EnvironmentConfig = {
+  formatArgs,
+  save,
+  load,
+  useColors,
+  colors,
+  log,
+  inspectOpts,
+  init,
+  destroy,
+};
+
+/**
+ * Export the debug factory
+ */
+export = setup(nodeEnv);