@dsai-io/tools 0.0.1 → 1.1.0

package/dist/{types-Idj08nad.d.ts → types-CtE9f0G0.d.ts}

@@ -11,6 +11,10 @@ interface DsaiConfig {
     tokens?: TokensConfig;
     /** Icon generation configuration */
     icons?: IconsConfig;
+    /** Path aliases for component installation */
+    aliases?: AliasesConfig;
+    /** Component distribution configuration */
+    components?: ComponentsConfig;
     /** Global settings */
     global?: GlobalConfig;
 }
@@ -130,6 +134,10 @@ interface TokensConfig {
      * @example '_variables.scss' or 'path/to/custom-base.scss'
      */
     scssImportHeader?: string;
+    /**
+     * SCSS/CSS output style options
+     */
+    scss?: ScssOutputConfig;
     /** Theme mode settings */
     themes?: ThemesConfig;
     /** Custom Style Dictionary transforms */
@@ -194,11 +202,33 @@ interface TokensConfig {
      * Controls which steps run and their paths
      */
     pipeline?: TokensBuildPipeline;
+    /**
+     * Postprocess configuration for CSS file transformations
+     * Applied after SASS compilation
+     */
+    postprocess?: PostprocessConfig;
+}
+/**
+ * Postprocess configuration for CSS file transformations
+ */
+interface PostprocessConfig {
+    /** Whether postprocessing is enabled */
+    enabled?: boolean;
+    /** Directory containing CSS files to process */
+    cssDir?: string;
+    /** File names to process */
+    files?: string[];
+    /** Replacement rules to apply */
+    replacements?: Array<{
+        description?: string;
+        from: string | RegExp;
+        to: string;
+    }>;
 }
 /**
  * Build pipeline step names
  */
-type BuildPipelineStep = 'validate' | 'transform' | 'style-dictionary' | 'sync' | 'sass-theme' | 'sass-theme-minified' | 'postprocess' | 'sass-utilities' | 'sass-utilities-minified' | 'bundle';
+type BuildPipelineStep = 'validate' | 'snapshot' | 'preprocess' | 'transform' | 'style-dictionary' | 'multi-theme' | 'sync' | 'sass-theme' | 'sass-theme-minified' | 'postprocess' | 'sass-utilities' | 'sass-utilities-minified' | 'bundle';
 /**
  * Build pipeline paths configuration
  */
@@ -263,18 +293,181 @@ interface BuildSummary {
         themes: string[];
     };
 }
+/**
+ * CSS/SCSS output style options
+ * Controls whether to generate expanded, compressed, or both formats
+ */
+interface ScssOutputConfig {
+    /**
+     * Output format styles to generate
+     * - 'expanded': Human-readable, formatted CSS
+     * - 'compressed': Minified CSS for production
+     * @default ['expanded']
+     */
+    outputStyles?: ('expanded' | 'compressed')[];
+    /**
+     * Generate source maps for debugging
+     * @default false
+     */
+    generateSourceMaps?: boolean;
+    /**
+     * Suffix for minified/compressed output files
+     * @default '.min'
+     * @example '.min' produces 'theme.min.css' alongside 'theme.css'
+     */
+    minifiedSuffix?: string;
+    /**
+     * Entry SCSS file for theme compilation
+     * Relative to config file location
+     * @example 'src/scss/dsai-theme-bs.scss'
+     */
+    themeEntry?: string;
+    /**
+     * Entry SCSS file for utilities compilation
+     * Relative to config file location
+     * @example 'src/scss/dsai-utilities.scss'
+     */
+    utilitiesEntry?: string;
+    /**
+     * Output directory for compiled CSS files
+     * Relative to config file location
+     * @default 'src/generated'
+     */
+    cssOutputDir?: string;
+    /**
+     * Additional Sass load paths for @use and @import resolution
+     * @default ['node_modules']
+     */
+    loadPaths?: string[];
+    /**
+     * Target CSS framework for variable naming conventions
+     * Controls how token names are mapped to framework-specific names
+     * @default 'bootstrap'
+     */
+    framework?: FrameworkTarget;
+    /**
+     * Custom name mappings for token → framework variable names
+     * Merged with framework defaults (custom mappings take precedence)
+     * @example { 'typography-text-base': 'font-size-base', 'typography-heading-h1': 'h1-font-size' }
+     */
+    nameMapping?: Record<string, string>;
+    /**
+     * Output path for generated SCSS variables file
+     * Relative to config file location
+     * @default 'src/scss/_variables.scss'
+     */
+    variablesOutput?: string;
+}
+/**
+ * Supported CSS framework targets
+ * Each framework has its own naming conventions for variables
+ */
+type FrameworkTarget = 'bootstrap' | 'shadcn' | 'tailwind' | 'mui' | 'custom';
+/**
+ * Framework mapping configuration
+ * Defines how Figma token names map to framework-specific variable names
+ */
+interface FrameworkMappingConfig {
+    /**
+     * Framework identifier
+     */
+    framework: FrameworkTarget;
+    /**
+     * Token name → framework variable name mappings
+     * Keys are Figma/DTCG token names, values are framework variable names
+     */
+    mappings: Record<string, string>;
+    /**
+     * Pattern-based mappings using regex
+     * Applied after explicit mappings
+     * @example [{ pattern: /^typography-heading-(.+)$/, replacement: 'h$1-font-size' }]
+     */
+    patterns?: FrameworkMappingPattern[];
+    /**
+     * Variable prefix for this framework
+     * @example '$' for SCSS, '--' for CSS custom properties
+     */
+    variablePrefix?: string;
+    /**
+     * File header comment
+     */
+    header?: string;
+}
+/**
+ * Pattern-based name mapping rule
+ */
+interface FrameworkMappingPattern {
+    /**
+     * Regex pattern to match token names
+     */
+    pattern: RegExp | string;
+    /**
+     * Replacement string (supports $1, $2, etc. for capture groups)
+     */
+    replacement: string;
+    /**
+     * Optional description for documentation
+     */
+    description?: string;
+}
+/**
+ * Individual theme definition
+ * Specifies how a theme is discovered and built
+ */
+interface ThemeDefinition {
+    /**
+     * Whether this is the default theme (uses :root selector)
+     * Only one theme can be default
+     * @default false
+     */
+    isDefault?: boolean;
+    /**
+     * File suffix pattern for this theme
+     * null means files without any theme suffix (default theme)
+     * e.g., '-dark' matches files like 'foundation-dark.json'
+     * @default null for default theme, '-{themeName}' for others
+     */
+    suffix?: string | null;
+    /**
+     * CSS selector for this theme
+     * @example ':root' for default, '[data-dsai-theme="dark"]' for dark
+     */
+    selector: string;
+    /**
+     * Optional media query for automatic switching
+     * @example '(prefers-color-scheme: dark)'
+     */
+    mediaQuery?: string;
+    /**
+     * Optional data attribute (derived from selector if not specified)
+     */
+    dataAttribute?: string;
+    /**
+     * Custom output file names per format
+     * If not specified, uses default naming pattern with theme suffix
+     */
+    outputFiles?: Partial<Record<OutputFormat, string>>;
+}
 /**
  * Theme configuration
  */
 interface ThemesConfig {
+    /**
+     * Enable/disable theme processing
+     * @default true
+     */
+    enabled?: boolean;
     /**
      * Auto-detect available modes from Figma export
+     * When true, scans for files with theme suffixes
+     * When false, only builds themes explicitly defined in definitions
      * @default true
      */
     autoDetect?: boolean;
     /**
      * Default theme mode (uses :root selector)
-     * @default 'Light'
+     * @default 'light'
+     * @deprecated Use definitions with isDefault: true instead
      */
     default?: string;
     /**
@@ -286,6 +479,12 @@ interface ThemesConfig {
      * CSS selector patterns for themes
      */
     selectorPattern?: ThemeSelectorPattern;
+    /**
+     * Explicit theme definitions
+     * Key is theme name, value is theme configuration
+     * When specified, provides explicit control over theme builds
+     */
+    definitions?: Record<string, ThemeDefinition>;
 }
 /**
  * Theme selector pattern configuration
@@ -443,14 +642,70 @@ interface IconsConfig {
      */
     prefix?: string;
 }
+/**
+ * Path aliases for component installation.
+ * Controls where `dsai add` writes files in the consumer's project.
+ */
+interface AliasesConfig {
+    /** Import alias prefix used in tsconfig paths (e.g., "@/", "~/", "@dsai/") @default '@/' */
+    importAlias?: string;
+    /** Where UI components are installed @default 'src/components/ui' */
+    ui?: string;
+    /** Where shared hooks are installed @default 'src/hooks' */
+    hooks?: string;
+    /** Where utility functions are installed @default 'src/lib/utils' */
+    utils?: string;
+    /** Where higher-level composed components go @default 'src/components' */
+    components?: string;
+    /** Where lib files go @default 'src/lib' */
+    lib?: string;
+}
+/**
+ * Configuration for component distribution (shadcn-style).
+ */
+interface ComponentsConfig {
+    /** Enable component distribution features @default true */
+    enabled?: boolean;
+    /** Registry URL or local path @default 'https://registry.dsai.dev' */
+    registryUrl?: string;
+    /** Whether to use TypeScript (.tsx) or JavaScript (.jsx) @default true */
+    tsx?: boolean;
+    /** Overwrite existing files when adding components @default false */
+    overwrite?: boolean;
+}
+/**
+ * Resolved theme definition with all required fields
+ */
+interface ResolvedThemeDefinition {
+    /** Whether this is the default theme */
+    isDefault: boolean;
+    /** File suffix pattern (null for default theme) */
+    suffix: string | null;
+    /** CSS selector */
+    selector: string;
+    /** Optional media query */
+    mediaQuery?: string;
+    /** Optional data attribute */
+    dataAttribute?: string;
+    /** Output file names per format */
+    outputFiles: Record<OutputFormat, string>;
+}
 /**
  * Resolved themes config with all defaults applied
  */
 interface ResolvedThemesConfig {
+    /** Whether themes are enabled */
+    enabled: boolean;
+    /** Auto-detect themes from files */
     autoDetect: boolean;
+    /** Default theme name (for backward compat) */
     default: string;
+    /** Modes to ignore */
     ignoreModes: string[];
+    /** Selector patterns */
     selectorPattern: Required<ThemeSelectorPattern>;
+    /** Resolved theme definitions */
+    definitions: Record<string, ResolvedThemeDefinition>;
 }
 /**
  * Resolved tokens config with all defaults applied
@@ -486,6 +741,19 @@ interface ResolvedTokensConfig {
     watch: boolean;
     watchDirectories: string[];
     pipeline?: TokensBuildPipeline;
+    scss?: {
+        cssOutputDir?: string;
+    };
+    postprocess?: {
+        enabled?: boolean;
+        cssDir?: string;
+        files?: string[];
+        replacements?: Array<{
+            description?: string;
+            from: string | RegExp;
+            to: string;
+        }>;
+    };
 }
 /**
  * Resolved icons config with all defaults applied
@@ -498,6 +766,26 @@ interface ResolvedIconsConfig {
     optimize: boolean;
     prefix: string;
 }
+/**
+ * Resolved aliases config with all defaults applied
+ */
+interface ResolvedAliasesConfig {
+    importAlias: string;
+    ui: string;
+    hooks: string;
+    utils: string;
+    components: string;
+    lib: string;
+}
+/**
+ * Resolved components config with all defaults applied
+ */
+interface ResolvedComponentsConfig {
+    enabled: boolean;
+    registryUrl: string;
+    tsx: boolean;
+    overwrite: boolean;
+}
 /**
  * Resolved global config with all defaults applied
  */
@@ -512,6 +800,8 @@ interface ResolvedGlobalConfig {
 interface ResolvedConfig {
     tokens: ResolvedTokensConfig;
     icons: ResolvedIconsConfig;
+    aliases: ResolvedAliasesConfig;
+    components: ResolvedComponentsConfig;
     global: ResolvedGlobalConfig;
     /** Absolute path to config file (if loaded from file) */
     configPath?: string;
@@ -543,4 +833,4 @@ interface LoadConfigResult {
     warnings: string[];
 }
 
-export type { BuildSummary as B, CustomTransform as C, DsaiConfig as D, FormatArgs as F, GlobalConfig as G, IconsConfig as I, LoadConfigOptions as L, OutputFormat as O, Platform as P, ResolvedConfig as R, TokensConfig as T, ThemesConfig as a, ThemeSelectorPattern as b, ResolvedGlobalConfig as c, ResolvedTokensConfig as d, ResolvedIconsConfig as e, ResolvedThemesConfig as f, CustomFormat as g, CustomPreprocessor as h, CustomFilter as i, TokenData as j, TransformOptions as k, Dictionary as l, FileConfig as m, LoadConfigResult as n, LogLevel as o, IconFramework as p };
+export type { AliasesConfig as A, BuildSummary as B, ComponentsConfig as C, Dictionary as D, FileConfig as F, GlobalConfig as G, IconFramework as I, LoadConfigOptions as L, OutputFormat as O, Platform as P, ResolvedAliasesConfig as R, ScssOutputConfig as S, ThemeDefinition as T, ResolvedComponentsConfig as a, CustomFilter as b, CustomFormat as c, CustomPreprocessor as d, CustomTransform as e, DsaiConfig as f, FormatArgs as g, FrameworkMappingConfig as h, FrameworkMappingPattern as i, FrameworkTarget as j, IconsConfig as k, LoadConfigResult as l, LogLevel as m, ResolvedConfig as n, ResolvedGlobalConfig as o, ResolvedIconsConfig as p, ResolvedThemeDefinition as q, ResolvedThemesConfig as r, ResolvedTokensConfig as s, ThemeSelectorPattern as t, ThemesConfig as u, TokenData as v, TokensConfig as w, TransformOptions as x };

package/dist/utils/circuit-breaker.cjs

@@ -0,0 +1,173 @@
+'use strict';
+
+/* @dsai-io/tools - DSAi Design System Build Tools */
+
+// src/utils/circuit-breaker.ts
+var CircuitState = /* @__PURE__ */ ((CircuitState2) => {
+  CircuitState2["CLOSED"] = "CLOSED";
+  CircuitState2["OPEN"] = "OPEN";
+  CircuitState2["HALF_OPEN"] = "HALF_OPEN";
+  return CircuitState2;
+})(CircuitState || {});
+var CircuitBreakerOpenError = class extends Error {
+  constructor(circuitName, resetAt) {
+    super(`Circuit breaker "${circuitName}" is open. Will retry at ${resetAt.toISOString()}`);
+    this.circuitName = circuitName;
+    this.resetAt = resetAt;
+    this.name = "CircuitBreakerOpenError";
+  }
+};
+var CircuitBreaker = class {
+  state = "CLOSED" /* CLOSED */;
+  failures = 0;
+  successes = 0;
+  totalCalls = 0;
+  openedAt;
+  resetAt;
+  lastError;
+  failureThreshold;
+  cooldownMs;
+  timeout;
+  name;
+  constructor(config = {}) {
+    this.failureThreshold = config.failureThreshold ?? 5;
+    this.cooldownMs = config.cooldownMs ?? 3e4;
+    this.timeout = config.timeout ?? 1e4;
+    this.name = config.name ?? "CircuitBreaker";
+  }
+  /**
+   * Execute a function with circuit breaker protection
+   */
+  async execute(fn) {
+    this.totalCalls++;
+    if (this.state === "OPEN" /* OPEN */ && this.canAttemptReset()) {
+      this.state = "HALF_OPEN" /* HALF_OPEN */;
+      this.failures = 0;
+    }
+    if (this.state === "OPEN" /* OPEN */) {
+      if (!this.resetAt) {
+        throw new Error(`Circuit breaker "${this.name}" is open but has no reset time`);
+      }
+      throw new CircuitBreakerOpenError(this.name, this.resetAt);
+    }
+    try {
+      const result = await this.executeWithTimeout(fn);
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure(error);
+      throw error;
+    }
+  }
+  /**
+   * Execute function with timeout
+   */
+  async executeWithTimeout(fn) {
+    return Promise.race([
+      fn(),
+      new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(new Error(`Circuit breaker timeout after ${this.timeout}ms`));
+        }, this.timeout);
+      })
+    ]);
+  }
+  /**
+   * Handle successful execution
+   */
+  onSuccess() {
+    this.successes++;
+    if (this.state === "HALF_OPEN" /* HALF_OPEN */) {
+      this.state = "CLOSED" /* CLOSED */;
+      this.failures = 0;
+      this.openedAt = void 0;
+      this.resetAt = void 0;
+      this.lastError = void 0;
+    }
+  }
+  /**
+   * Handle failed execution
+   */
+  onFailure(error) {
+    this.failures++;
+    this.lastError = error instanceof Error ? error.message : String(error);
+    if (this.state === "HALF_OPEN" /* HALF_OPEN */) {
+      this.openCircuit();
+    } else if (this.failures >= this.failureThreshold) {
+      this.openCircuit();
+    }
+  }
+  /**
+   * Open the circuit
+   */
+  openCircuit() {
+    this.state = "OPEN" /* OPEN */;
+    this.openedAt = /* @__PURE__ */ new Date();
+    this.resetAt = new Date(Date.now() + this.cooldownMs);
+  }
+  /**
+   * Check if circuit can attempt reset
+   */
+  canAttemptReset() {
+    if (!this.resetAt) {
+      return false;
+    }
+    return Date.now() >= this.resetAt.getTime();
+  }
+  /**
+   * Get current circuit breaker state
+   */
+  getState() {
+    return this.state;
+  }
+  /**
+   * Get circuit breaker statistics
+   */
+  getStats() {
+    return {
+      state: this.state,
+      failures: this.failures,
+      successes: this.successes,
+      totalCalls: this.totalCalls,
+      openedAt: this.openedAt,
+      resetAt: this.resetAt,
+      lastError: this.lastError
+    };
+  }
+  /**
+   * Manually reset circuit breaker
+   */
+  reset() {
+    this.state = "CLOSED" /* CLOSED */;
+    this.failures = 0;
+    this.successes = 0;
+    this.totalCalls = 0;
+    this.openedAt = void 0;
+    this.resetAt = void 0;
+    this.lastError = void 0;
+  }
+  /**
+   * Check if circuit is open
+   */
+  isOpen() {
+    return this.state === "OPEN" /* OPEN */;
+  }
+  /**
+   * Check if circuit is closed
+   */
+  isClosed() {
+    return this.state === "CLOSED" /* CLOSED */;
+  }
+  /**
+   * Check if circuit is half-open
+   */
+  isHalfOpen() {
+    return this.state === "HALF_OPEN" /* HALF_OPEN */;
+  }
+};
+
+exports.CircuitBreaker = CircuitBreaker;
+exports.CircuitBreakerOpenError = CircuitBreakerOpenError;
+exports.CircuitState = CircuitState;
+//# sourceMappingURL=circuit-breaker.cjs.map
+//# sourceMappingURL=circuit-breaker.cjs.map

package/dist/utils/circuit-breaker.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/circuit-breaker.ts"],"names":["CircuitState"],"mappings":"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","file":"circuit-breaker.cjs","sourcesContent":["/**\r\n * @fileoverview Circuit Breaker pattern implementation\r\n * Prevents cascade failures by tracking error rates and temporarily blocking requests\r\n */\r\n\r\n/**\r\n * Circuit breaker states\r\n */\r\nexport enum CircuitState {\r\n  /** Normal operation - requests are allowed */\r\n  CLOSED = 'CLOSED',\r\n  /** Failing - all requests are rejected immediately */\r\n  OPEN = 'OPEN',\r\n  /** Testing recovery - limited requests are allowed */\r\n  HALF_OPEN = 'HALF_OPEN',\r\n}\r\n\r\n/**\r\n * Circuit breaker configuration\r\n */\r\nexport interface CircuitBreakerConfig {\r\n  /** Number of failures before opening circuit */\r\n  failureThreshold?: number;\r\n  /** Time in ms before attempting to close circuit */\r\n  cooldownMs?: number;\r\n  /** Request timeout in ms */\r\n  timeout?: number;\r\n  /** Name for logging */\r\n  name?: string;\r\n}\r\n\r\n/**\r\n * Circuit breaker statistics\r\n */\r\nexport interface CircuitBreakerStats {\r\n  /** Current state */\r\n  state: CircuitState;\r\n  /** Total failures */\r\n  failures: number;\r\n  /** Total successes */\r\n  successes: number;\r\n  /** Total calls */\r\n  totalCalls: number;\r\n  /** Time circuit opened (if open) */\r\n  openedAt?: Date;\r\n  /** Time circuit will attempt to close */\r\n  resetAt?: Date;\r\n  /** Last error */\r\n  lastError?: string;\r\n}\r\n\r\n/**\r\n * Circuit breaker error thrown when circuit is open\r\n */\r\nexport class CircuitBreakerOpenError extends Error {\r\n  constructor(\r\n    public readonly circuitName: string,\r\n    public readonly resetAt: Date\r\n  ) {\r\n    super(`Circuit breaker \"${circuitName}\" is open. Will retry at ${resetAt.toISOString()}`);\r\n    this.name = 'CircuitBreakerOpenError';\r\n  }\r\n}\r\n\r\n/**\r\n * Circuit breaker implementation\r\n * Tracks failures and opens circuit to prevent cascade failures\r\n */\r\nexport class CircuitBreaker {\r\n  private state: CircuitState = CircuitState.CLOSED;\r\n  private failures = 0;\r\n  private successes = 0;\r\n  private totalCalls = 0;\r\n  private openedAt?: Date;\r\n  private resetAt?: Date;\r\n  private lastError?: string;\r\n\r\n  private readonly failureThreshold: number;\r\n  private readonly cooldownMs: number;\r\n  private readonly timeout: number;\r\n  private readonly name: string;\r\n\r\n  constructor(config: CircuitBreakerConfig = {}) {\r\n    this.failureThreshold = config.failureThreshold ?? 5;\r\n    this.cooldownMs = config.cooldownMs ?? 30000; // 30 seconds\r\n    this.timeout = config.timeout ?? 10000; // 10 seconds\r\n    this.name = config.name ?? 'CircuitBreaker';\r\n  }\r\n\r\n  /**\r\n   * Execute a function with circuit breaker protection\r\n   */\r\n  async execute<T>(fn: () => Promise<T>): Promise<T> {\r\n    this.totalCalls++;\r\n\r\n    // Check if circuit should transition from OPEN to HALF_OPEN\r\n    if (this.state === CircuitState.OPEN && this.canAttemptReset()) {\r\n      this.state = CircuitState.HALF_OPEN;\r\n      this.failures = 0; // Reset failure count for half-open state\r\n    }\r\n\r\n    // Reject immediately if circuit is open\r\n    if (this.state === CircuitState.OPEN) {\r\n      if (!this.resetAt) {\r\n        throw new Error(`Circuit breaker \"${this.name}\" is open but has no reset time`);\r\n      }\r\n      throw new CircuitBreakerOpenError(this.name, this.resetAt);\r\n    }\r\n\r\n    try {\r\n      // Execute with timeout\r\n      const result = await this.executeWithTimeout(fn);\r\n\r\n      // Record success\r\n      this.onSuccess();\r\n\r\n      return result;\r\n    } catch (error) {\r\n      // Record failure\r\n      this.onFailure(error);\r\n      throw error;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Execute function with timeout\r\n   */\r\n  private async executeWithTimeout<T>(fn: () => Promise<T>): Promise<T> {\r\n    return Promise.race([\r\n      fn(),\r\n      new Promise<T>((_, reject) => {\r\n        setTimeout(() => {\r\n          reject(new Error(`Circuit breaker timeout after ${this.timeout}ms`));\r\n        }, this.timeout);\r\n      }),\r\n    ]);\r\n  }\r\n\r\n  /**\r\n   * Handle successful execution\r\n   */\r\n  private onSuccess(): void {\r\n    this.successes++;\r\n\r\n    if (this.state === CircuitState.HALF_OPEN) {\r\n      // Successful call in HALF_OPEN state closes the circuit\r\n      this.state = CircuitState.CLOSED;\r\n      this.failures = 0;\r\n      this.openedAt = undefined;\r\n      this.resetAt = undefined;\r\n      this.lastError = undefined;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Handle failed execution\r\n   */\r\n  private onFailure(error: unknown): void {\r\n    this.failures++;\r\n    this.lastError = error instanceof Error ? error.message : String(error);\r\n\r\n    if (this.state === CircuitState.HALF_OPEN) {\r\n      // Failure in HALF_OPEN state immediately reopens circuit\r\n      this.openCircuit();\r\n    } else if (this.failures >= this.failureThreshold) {\r\n      // Threshold reached, open circuit\r\n      this.openCircuit();\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Open the circuit\r\n   */\r\n  private openCircuit(): void {\r\n    this.state = CircuitState.OPEN;\r\n    this.openedAt = new Date();\r\n    this.resetAt = new Date(Date.now() + this.cooldownMs);\r\n  }\r\n\r\n  /**\r\n   * Check if circuit can attempt reset\r\n   */\r\n  private canAttemptReset(): boolean {\r\n    if (!this.resetAt) {\r\n      return false;\r\n    }\r\n    return Date.now() >= this.resetAt.getTime();\r\n  }\r\n\r\n  /**\r\n   * Get current circuit breaker state\r\n   */\r\n  getState(): CircuitState {\r\n    return this.state;\r\n  }\r\n\r\n  /**\r\n   * Get circuit breaker statistics\r\n   */\r\n  getStats(): CircuitBreakerStats {\r\n    return {\r\n      state: this.state,\r\n      failures: this.failures,\r\n      successes: this.successes,\r\n      totalCalls: this.totalCalls,\r\n      openedAt: this.openedAt,\r\n      resetAt: this.resetAt,\r\n      lastError: this.lastError,\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Manually reset circuit breaker\r\n   */\r\n  reset(): void {\r\n    this.state = CircuitState.CLOSED;\r\n    this.failures = 0;\r\n    this.successes = 0;\r\n    this.totalCalls = 0;\r\n    this.openedAt = undefined;\r\n    this.resetAt = undefined;\r\n    this.lastError = undefined;\r\n  }\r\n\r\n  /**\r\n   * Check if circuit is open\r\n   */\r\n  isOpen(): boolean {\r\n    return this.state === CircuitState.OPEN;\r\n  }\r\n\r\n  /**\r\n   * Check if circuit is closed\r\n   */\r\n  isClosed(): boolean {\r\n    return this.state === CircuitState.CLOSED;\r\n  }\r\n\r\n  /**\r\n   * Check if circuit is half-open\r\n   */\r\n  isHalfOpen(): boolean {\r\n    return this.state === CircuitState.HALF_OPEN;\r\n  }\r\n}\r\n"]}

package/dist/utils/circuit-breaker.d.cts

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Circuit Breaker pattern implementation
+ * Prevents cascade failures by tracking error rates and temporarily blocking requests
+ */
+/**
+ * Circuit breaker states
+ */
+declare enum CircuitState {
+    /** Normal operation - requests are allowed */
+    CLOSED = "CLOSED",
+    /** Failing - all requests are rejected immediately */
+    OPEN = "OPEN",
+    /** Testing recovery - limited requests are allowed */
+    HALF_OPEN = "HALF_OPEN"
+}
+/**
+ * Circuit breaker configuration
+ */
+interface CircuitBreakerConfig {
+    /** Number of failures before opening circuit */
+    failureThreshold?: number;
+    /** Time in ms before attempting to close circuit */
+    cooldownMs?: number;
+    /** Request timeout in ms */
+    timeout?: number;
+    /** Name for logging */
+    name?: string;
+}
+/**
+ * Circuit breaker statistics
+ */
+interface CircuitBreakerStats {
+    /** Current state */
+    state: CircuitState;
+    /** Total failures */
+    failures: number;
+    /** Total successes */
+    successes: number;
+    /** Total calls */
+    totalCalls: number;
+    /** Time circuit opened (if open) */
+    openedAt?: Date;
+    /** Time circuit will attempt to close */
+    resetAt?: Date;
+    /** Last error */
+    lastError?: string;
+}
+/**
+ * Circuit breaker error thrown when circuit is open
+ */
+declare class CircuitBreakerOpenError extends Error {
+    readonly circuitName: string;
+    readonly resetAt: Date;
+    constructor(circuitName: string, resetAt: Date);
+}
+/**
+ * Circuit breaker implementation
+ * Tracks failures and opens circuit to prevent cascade failures
+ */
+declare class CircuitBreaker {
+    private state;
+    private failures;
+    private successes;
+    private totalCalls;
+    private openedAt?;
+    private resetAt?;
+    private lastError?;
+    private readonly failureThreshold;
+    private readonly cooldownMs;
+    private readonly timeout;
+    private readonly name;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Execute function with timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Handle successful execution
+     */
+    private onSuccess;
+    /**
+     * Handle failed execution
+     */
+    private onFailure;
+    /**
+     * Open the circuit
+     */
+    private openCircuit;
+    /**
+     * Check if circuit can attempt reset
+     */
+    private canAttemptReset;
+    /**
+     * Get current circuit breaker state
+     */
+    getState(): CircuitState;
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * Manually reset circuit breaker
+     */
+    reset(): void;
+    /**
+     * Check if circuit is open
+     */
+    isOpen(): boolean;
+    /**
+     * Check if circuit is closed
+     */
+    isClosed(): boolean;
+    /**
+     * Check if circuit is half-open
+     */
+    isHalfOpen(): boolean;
+}
+
+export { CircuitBreaker, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitBreakerStats, CircuitState };