@sylphx/flow 1.0.1 → 1.0.3

package/src/core/error-handling.ts

@@ -0,0 +1,519 @@
+/**
+ * Error Handling - 統一錯誤處理
+ * Functional, composable error handling system
+ */
+
+import { logger } from '../utils/logger.js';
+import type { Result } from './result.js';
+
+/**
+ * Base error class
+ */
+export class BaseError extends Error {
+  public readonly code: string;
+  public readonly statusCode: number;
+  public readonly details?: Record<string, unknown>;
+
+  constructor(
+    message: string,
+    code: string,
+    statusCode = 500,
+    details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+
+    // Maintains proper stack trace for where our error was thrown
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Validation error
+ */
+export class ValidationError extends BaseError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'VALIDATION_ERROR', 400, details);
+  }
+}
+
+/**
+ * Configuration error
+ */
+export class ConfigurationError extends BaseError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'CONFIGURATION_ERROR', 500, details);
+  }
+}
+
+/**
+ * Storage error
+ */
+export class StorageError extends BaseError {
+  constructor(message: string, operation?: string, details?: Record<string, unknown>) {
+    super(message, 'STORAGE_ERROR', 500, { operation, ...details });
+  }
+}
+
+/**
+ * Network error
+ */
+export class NetworkError extends BaseError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'NETWORK_ERROR', 503, details);
+  }
+}
+
+/**
+ * Authentication error
+ */
+export class AuthenticationError extends BaseError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'AUTHENTICATION_ERROR', 401, details);
+  }
+}
+
+/**
+ * Authorization error
+ */
+export class AuthorizationError extends BaseError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'AUTHORIZATION_ERROR', 403, details);
+  }
+}
+
+/**
+ * Not found error
+ */
+export class NotFoundError extends BaseError {
+  constructor(message: string, resource?: string, details?: Record<string, unknown>) {
+    super(message, 'NOT_FOUND', 404, { resource, ...details });
+  }
+}
+
+/**
+ * Timeout error
+ */
+export class TimeoutError extends BaseError {
+  constructor(message: string, timeout?: number, details?: Record<string, unknown>) {
+    super(message, 'TIMEOUT_ERROR', 408, { timeout, ...details });
+  }
+}
+
+/**
+ * Error types
+ */
+export const ErrorTypes = {
+  ValidationError,
+  ConfigurationError,
+  StorageError,
+  NetworkError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  TimeoutError,
+} as const;
+
+/**
+ * Error codes
+ */
+export const ErrorCodes = {
+  // Validation errors
+  INVALID_INPUT: 'INVALID_INPUT',
+  MISSING_REQUIRED_FIELD: 'MISSING_REQUIRED_FIELD',
+  INVALID_FORMAT: 'INVALID_FORMAT',
+
+  // Configuration errors
+  MISSING_CONFIG: 'MISSING_CONFIG',
+  INVALID_CONFIG: 'INVALID_CONFIG',
+  CONFIG_PARSE_ERROR: 'CONFIG_PARSE_ERROR',
+
+  // Storage errors
+  STORAGE_CONNECTION_FAILED: 'STORAGE_CONNECTION_FAILED',
+  STORAGE_OPERATION_FAILED: 'STORAGE_OPERATION_FAILED',
+  STORAGE_TIMEOUT: 'STORAGE_TIMEOUT',
+  STORAGE_FULL: 'STORAGE_FULL',
+
+  // Network errors
+  CONNECTION_FAILED: 'CONNECTION_FAILED',
+  REQUEST_FAILED: 'REQUEST_FAILED',
+  REQUEST_TIMEOUT: 'REQUEST_TIMEOUT',
+  RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
+
+  // Authentication errors
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
+  TOKEN_EXPIRED: 'TOKEN_EXPIRED',
+
+  // Authorization errors
+  FORBIDDEN: 'FORBIDDEN',
+  INSUFFICIENT_PERMISSIONS: 'INSUFFICIENT_PERMISSIONS',
+
+  // Not found errors
+  RESOURCE_NOT_FOUND: 'RESOURCE_NOT_FOUND',
+  ENDPOINT_NOT_FOUND: 'ENDPOINT_NOT_FOUND',
+
+  // System errors
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+  TIMEOUT: 'TIMEOUT',
+} as const;
+
+/**
+ * Error handler interface
+ */
+export interface ErrorHandler {
+  canHandle(error: Error): boolean;
+  handle(error: Error): void | Promise<void>;
+}
+
+/**
+ * Logger error handler
+ */
+export class LoggerErrorHandler implements ErrorHandler {
+  constructor(private level: 'error' | 'warn' | 'info' | 'debug' = 'error') {}
+
+  canHandle(error: Error): boolean {
+    return true; // Logger can handle all errors
+  }
+
+  handle(error: Error): void {
+    const errorData = {
+      name: error.name,
+      message: error.message,
+      code: (error as BaseError).code,
+      statusCode: (error as BaseError).statusCode,
+      stack: error.stack,
+      details: (error as BaseError).details,
+    };
+
+    switch (this.level) {
+      case 'error':
+        logger.error(error.message, errorData);
+        break;
+      case 'warn':
+        logger.warn(error.message, errorData);
+        break;
+      case 'info':
+        logger.info(error.message, errorData);
+        break;
+      case 'debug':
+        logger.debug(error.message, errorData);
+        break;
+    }
+  }
+}
+
+/**
+ * Console error handler
+ */
+export class ConsoleErrorHandler implements ErrorHandler {
+  canHandle(error: Error): boolean {
+    return true; // Console can handle all errors
+  }
+
+  handle(error: Error): void {
+    if (error instanceof BaseError) {
+      console.error(`[${error.code}] ${error.message}`);
+      if (error.details) {
+        console.error('Details:', error.details);
+      }
+    } else {
+      console.error(error.message);
+    }
+
+    if (process.env.NODE_ENV === 'development' && error.stack) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    }
+  }
+}
+
+/**
+ * Error handler chain
+ */
+export class ErrorHandlerChain {
+  private handlers: ErrorHandler[] = [];
+
+  constructor(handlers: ErrorHandler[] = []) {
+    this.handlers = handlers;
+  }
+
+  addHandler(handler: ErrorHandler): void {
+    this.handlers.push(handler);
+  }
+
+  removeHandler(handler: ErrorHandler): void {
+    const index = this.handlers.indexOf(handler);
+    if (index > -1) {
+      this.handlers.splice(index, 1);
+    }
+  }
+
+  async handle(error: Error): Promise<void> {
+    for (const handler of this.handlers) {
+      if (handler.canHandle(error)) {
+        await handler.handle(error);
+        return;
+      }
+    }
+
+    // If no handler can handle the error, use default console handler
+    new ConsoleErrorHandler().handle(error);
+  }
+}
+
+/**
+ * Global error handler
+ */
+export const globalErrorHandler = new ErrorHandlerChain([
+  new LoggerErrorHandler('error'),
+]);
+
+/**
+ * Set up global error handlers
+ */
+export function setupGlobalErrorHandlers(): void {
+  // Handle uncaught exceptions
+  process.on('uncaughtException', (error: Error) => {
+    logger.error('Uncaught Exception:', { error: error.message, stack: error.stack });
+    globalErrorHandler.handle(error);
+    process.exit(1);
+  });
+
+  // Handle unhandled promise rejections
+  process.on('unhandledRejection', (reason: unknown, promise: Promise<unknown>) => {
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+    logger.error('Unhandled Rejection:', { error: error.message, reason, promise });
+    globalErrorHandler.handle(error);
+  });
+
+  // Handle process termination
+  process.on('SIGINT', () => {
+    logger.info('Process terminated by user');
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    logger.info('Process terminated');
+    process.exit(0);
+  });
+}
+
+/**
+ * Safe function wrapper with error handling
+ */
+export async function withErrorHandling<T>(
+  fn: () => Promise<T>,
+  errorHandler?: (error: Error) => void | Promise<void>
+): Promise<Result<T>> {
+  try {
+    const data = await fn();
+    return { success: true, data };
+  } catch (error) {
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+
+    if (errorHandler) {
+      await errorHandler(errorObj);
+    } else {
+      await globalErrorHandler.handle(errorObj);
+    }
+
+    return { success: false, error: errorObj };
+  }
+}
+
+/**
+ * Safe sync function wrapper with error handling
+ */
+export function withSyncErrorHandling<T>(
+  fn: () => T,
+  errorHandler?: (error: Error) => void | Promise<void>
+): Result<T> {
+  try {
+    const data = fn();
+    return { success: true, data };
+  } catch (error) {
+    const errorObj = error instanceof Error ? error : new Error(String(error));
+
+    if (errorHandler) {
+      // For sync error handlers, we need to handle them asynchronously
+      void errorHandler(errorObj);
+    } else {
+      void globalErrorHandler.handle(errorObj);
+    }
+
+    return { success: false, error: errorObj };
+  }
+}
+
+/**
+ * Retry function with error handling
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: {
+    maxAttempts?: number;
+    delay?: number;
+    backoff?: 'linear' | 'exponential';
+    retryableErrors?: string[];
+    onRetry?: (attempt: number, error: Error) => void;
+  } = {}
+): Promise<Result<T>> {
+  const {
+    maxAttempts = 3,
+    delay = 1000,
+    backoff = 'exponential',
+    retryableErrors = [],
+    onRetry,
+  } = options;
+
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const data = await fn();
+      return { success: true, data };
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      // Check if error is retryable
+      const isRetryable = retryableErrors.length === 0 ||
+        retryableErrors.includes((lastError as BaseError).code) ||
+        retryableErrors.includes(lastError.constructor.name);
+
+      if (!isRetryable || attempt === maxAttempts) {
+        await globalErrorHandler.handle(lastError);
+        return { success: false, error: lastError };
+      }
+
+      // Call retry callback
+      if (onRetry) {
+        onRetry(attempt, lastError);
+      }
+
+      // Calculate delay
+      const retryDelay = backoff === 'exponential'
+        ? delay * Math.pow(2, attempt - 1)
+        : delay * attempt;
+
+      // Wait before retry
+      await new Promise(resolve => setTimeout(resolve, retryDelay));
+    }
+  }
+
+  await globalErrorHandler.handle(lastError!);
+  return { success: false, error: lastError! };
+}
+
+/**
+ * Timeout wrapper
+ */
+export async function withTimeout<T>(
+  fn: () => Promise<T>,
+  timeoutMs: number,
+  timeoutMessage = 'Operation timed out'
+): Promise<Result<T>> {
+  return new Promise((resolve) => {
+    const timeoutId = setTimeout(() => {
+      resolve({
+        success: false,
+        error: new TimeoutError(timeoutMessage, timeoutMs),
+      });
+    }, timeoutMs);
+
+    fn()
+      .then((data) => {
+        clearTimeout(timeoutId);
+        resolve({ success: true, data });
+      })
+      .catch((error) => {
+        clearTimeout(timeoutId);
+        resolve({
+          success: false,
+          error: error instanceof Error ? error : new Error(String(error)),
+        });
+      });
+  });
+}
+
+/**
+ * Circuit breaker pattern
+ */
+export class CircuitBreaker {
+  private failures = 0;
+  private lastFailureTime = 0;
+  private state: 'closed' | 'open' | 'half-open' = 'closed';
+
+  constructor(
+    private options: {
+      failureThreshold?: number;
+      recoveryTimeMs?: number;
+      monitoringPeriodMs?: number;
+    } = {}
+  ) {
+    const {
+      failureThreshold = 5,
+      recoveryTimeMs = 60000,
+      monitoringPeriodMs = 10000,
+    } = options;
+
+    this.options = { failureThreshold, recoveryTimeMs, monitoringPeriodMs };
+  }
+
+  async execute<T>(fn: () => Promise<T>): Promise<Result<T>> {
+    if (this.state === 'open') {
+      if (Date.now() - this.lastFailureTime > this.options.recoveryTimeMs!) {
+        this.state = 'half-open';
+      } else {
+        return {
+          success: false,
+          error: new Error('Circuit breaker is open'),
+        };
+      }
+    }
+
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return { success: true, data: result };
+    } catch (error) {
+      this.onFailure();
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+  }
+
+  private onSuccess(): void {
+    this.failures = 0;
+    this.state = 'closed';
+  }
+
+  private onFailure(): void {
+    this.failures++;
+    this.lastFailureTime = Date.now();
+
+    if (this.failures >= this.options.failureThreshold!) {
+      this.state = 'open';
+    }
+  }
+
+  getState(): 'closed' | 'open' | 'half-open' {
+    return this.state;
+  }
+
+  getFailures(): number {
+    return this.failures;
+  }
+
+  reset(): void {
+    this.failures = 0;
+    this.state = 'closed';
+    this.lastFailureTime = 0;
+  }
+}

package/src/core/formatting/bytes.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Tests for Byte Formatting Utilities
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { formatBytes, formatFileSize } from './bytes.js';
+
+describe('formatBytes', () => {
+  describe('default options (decimals: 2, longUnits)', () => {
+    it('formats 0 bytes', () => {
+      expect(formatBytes(0)).toBe('0 Bytes');
+    });
+
+    it('formats bytes', () => {
+      expect(formatBytes(500)).toBe('500 Bytes');
+    });
+
+    it('formats kilobytes', () => {
+      expect(formatBytes(1024)).toBe('1 KB');
+      expect(formatBytes(1536)).toBe('1.5 KB');
+    });
+
+    it('formats megabytes', () => {
+      expect(formatBytes(1048576)).toBe('1 MB');
+      expect(formatBytes(1572864)).toBe('1.5 MB');
+    });
+
+    it('formats gigabytes', () => {
+      expect(formatBytes(1073741824)).toBe('1 GB');
+      expect(formatBytes(1610612736)).toBe('1.5 GB');
+    });
+
+    it('formats terabytes', () => {
+      expect(formatBytes(1099511627776)).toBe('1 TB');
+    });
+
+    it('rounds to 2 decimal places', () => {
+      expect(formatBytes(1587)).toBe('1.55 KB');
+      expect(formatBytes(1638400)).toBe('1.56 MB');
+    });
+  });
+
+  describe('with decimals option', () => {
+    it('formats with 0 decimals', () => {
+      expect(formatBytes(1536, { decimals: 0 })).toBe('2 KB');
+      expect(formatBytes(1024, { decimals: 0 })).toBe('1 KB');
+    });
+
+    it('formats with 1 decimal', () => {
+      expect(formatBytes(1536, { decimals: 1 })).toBe('1.5 KB');
+      expect(formatBytes(1587, { decimals: 1 })).toBe('1.5 KB');
+    });
+
+    it('formats with 3 decimals', () => {
+      expect(formatBytes(1587, { decimals: 3 })).toBe('1.55 KB'); // toFixed trims to 1.550, then trimmed
+    });
+  });
+
+  describe('with shortUnits option', () => {
+    it('uses short unit for 0 bytes', () => {
+      expect(formatBytes(0, { shortUnits: true })).toBe('0 B');
+    });
+
+    it('uses short unit for bytes', () => {
+      expect(formatBytes(500, { shortUnits: true })).toBe('500 B');
+    });
+
+    it('uses short units for kilobytes', () => {
+      expect(formatBytes(1024, { shortUnits: true })).toBe('1 KB');
+    });
+
+    it('uses short units for megabytes', () => {
+      expect(formatBytes(1048576, { shortUnits: true })).toBe('1 MB');
+    });
+  });
+
+  describe('combined options', () => {
+    it('uses short units with 1 decimal', () => {
+      expect(formatBytes(1536, { decimals: 1, shortUnits: true })).toBe('1.5 KB');
+    });
+
+    it('uses short units with 0 decimals', () => {
+      expect(formatBytes(1536, { decimals: 0, shortUnits: true })).toBe('2 KB');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('handles 1 byte', () => {
+      expect(formatBytes(1)).toBe('1 Bytes');
+    });
+
+    it('handles very large numbers', () => {
+      const result = formatBytes(1099511627776 * 1024); // 1 PB
+      expect(result).toContain('TB'); // Will show in TB since we only go up to TB
+    });
+
+    it('handles fractional KB', () => {
+      expect(formatBytes(1500)).toBe('1.46 KB');
+    });
+  });
+});
+
+describe('formatFileSize', () => {
+  it('formats with 1 decimal and short units', () => {
+    expect(formatFileSize(0)).toBe('0 B');
+    expect(formatFileSize(1024)).toBe('1 KB'); // toFixed(1) gives "1.0", trimmed to "1"
+    expect(formatFileSize(1536)).toBe('1.5 KB');
+    expect(formatFileSize(1048576)).toBe('1 MB'); // toFixed(1) gives "1.0", trimmed to "1"
+  });
+
+  it('is an alias for formatBytes with specific options', () => {
+    const bytes = 1572864;
+    expect(formatFileSize(bytes)).toBe(formatBytes(bytes, { decimals: 1, shortUnits: true }));
+  });
+});

package/src/core/formatting/bytes.ts

@@ -0,0 +1,64 @@
+/**
+ * Byte Formatting Utilities
+ * Shared utilities for formatting byte sizes with configurable options
+ */
+
+export interface ByteFormatOptions {
+  /** Decimal places to round to (default: 2) */
+  decimals?: number;
+  /** Use short unit names like 'B', 'KB' instead of 'Bytes', 'KB' (default: false) */
+  shortUnits?: boolean;
+}
+
+/**
+ * Format bytes to human-readable size
+ * Pure - number to string formatting
+ *
+ * @param bytes - The number of bytes to format
+ * @param options - Formatting options
+ * @returns Formatted string like "1.5 MB" or "2.3 KB"
+ *
+ * @example
+ * formatBytes(0) // '0 Bytes'
+ * formatBytes(1024) // '1 KB'
+ * formatBytes(1536, { decimals: 1 }) // '1.5 KB'
+ * formatBytes(1024, { shortUnits: true }) // '1 KB'
+ * formatBytes(0, { shortUnits: true }) // '0 B'
+ */
+export function formatBytes(bytes: number, options: ByteFormatOptions = {}): string {
+  const { decimals = 2, shortUnits = false } = options;
+
+  const units = shortUnits
+    ? ['B', 'KB', 'MB', 'GB', 'TB']
+    : ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+
+  if (bytes === 0) {
+    return `0 ${units[0]}`;
+  }
+
+  const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+  const value = bytes / Math.pow(1024, i);
+
+  // Format with specified decimal places
+  const formatted = value.toFixed(decimals);
+
+  // Remove trailing zeros and decimal point if not needed
+  const trimmed = decimals > 0 ? formatted.replace(/\.?0+$/, '') : formatted;
+
+  return `${trimmed} ${units[i]}`;
+}
+
+/**
+ * Format file size - alias for formatBytes with 1 decimal place
+ * Kept for backward compatibility
+ *
+ * @param bytes - The number of bytes to format
+ * @returns Formatted string like "1.5 MB"
+ *
+ * @example
+ * formatFileSize(1536) // '1.5 KB'
+ * formatFileSize(1048576) // '1.0 MB'
+ */
+export function formatFileSize(bytes: number): string {
+  return formatBytes(bytes, { decimals: 1, shortUnits: true });
+}