@gzl10/ts-helpers 4.2.1

package/dist/node/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/environment.ts"],"sourcesContent":["/**\n * Environment detection utilities for universal browser/Node.js compatibility\n */\n\n/**\n * Detailed criteria used for environment debugging and analysis\n */\nexport interface EnvironmentCriteria {\n  /** True if hostname is localhost, 127.0.0.1, ::1, or .localhost/.local domain */\n  isLocalhost: boolean\n  /** True if hostname is within private IP ranges (10.x, 192.168.x, 172.16-31.x) */\n  isPrivateIP: boolean\n  /** True if port is in development range (3000-9999) */\n  isDevelopmentPort: boolean\n  /** True if development tools are detected (Vue DevTools, __DEV__ global) */\n  hasDevtools: boolean\n  /** Current NODE_ENV value (Node.js only) */\n  nodeEnv?: string\n}\n\n/**\n * Complete environment information with platform detection and debugging criteria\n */\nexport interface EnvironmentInfo {\n  /** Runtime platform: 'browser', 'node', or 'unknown' */\n  platform: 'browser' | 'node' | 'unknown'\n  /** Detected environment: 'development', 'production', or 'test' */\n  environment: 'development' | 'production' | 'test'\n  /** Protocol used (http/https) - from location or request headers */\n  protocol?: string\n  /** Hostname - from location or request headers */\n  hostname?: string\n  /** Browser user agent string (browser only) */\n  userAgent?: string\n  /** Detailed debugging criteria */\n  criteria?: EnvironmentCriteria\n}\n\n/**\n * Detects if the current runtime is Node.js environment\n *\n * Checks for the presence of Node.js-specific globals (process, process.versions.node)\n * and absence of browser globals (window).\n *\n * @returns True if running in Node.js, false otherwise\n *\n * @example\n * ```typescript\n * if (isNodeEnvironment()) {\n *   // Node.js specific code\n *   const fs = require('fs')\n * }\n * ```\n */\nexport function isNodeEnvironment(): boolean {\n  return typeof window === 'undefined' && typeof process !== 'undefined' && !!process.versions?.node\n}\n\n/**\n * Detects if the current runtime is a browser environment\n *\n * Checks for the presence of browser-specific globals (window, document).\n * Also handles testing environments that may mock these globals.\n *\n * @returns True if running in browser, false otherwise\n *\n * @example\n * ```typescript\n * if (isBrowserEnvironment()) {\n *   // Browser specific code\n *   const url = window.location.href\n * }\n * ```\n */\nexport function isBrowserEnvironment(): boolean {\n  // Check both global.window (for tests) and window (for actual browser)\n  const win = typeof window !== 'undefined' ? window : (global as any).window\n  const doc = typeof document !== 'undefined' ? document : (global as any).document\n  return typeof win !== 'undefined' && win !== null && typeof doc !== 'undefined' && doc !== null\n}\n\n/**\n * Detects if the application is running in development mode\n *\n * Uses sophisticated detection logic based on multiple criteria:\n * - Node.js: NODE_ENV variable, request headers (for Express), hostname/protocol analysis\n * - Browser: __DEV__ global, development ports (3000-9999), localhost/private IPs, dev tools\n *\n * Handles reverse proxies correctly by checking forwarded headers.\n *\n * @param req - Optional Express request object for server-side detection\n * @returns True if in development mode, false if production\n *\n * @example\n * ```typescript\n * // Node.js - simple check\n * if (isDevelopment()) {\n *   console.log('Development mode')\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Express - with request context\n * app.get('/api/status', (req, res) => {\n *   const isDev = isDevelopment(req)\n *   res.json({ environment: isDev ? 'dev' : 'prod' })\n * })\n * ```\n *\n * @example\n * ```typescript\n * // Browser - automatic detection\n * if (isDevelopment()) {\n *   // Enable debug logging, dev tools, etc.\n *   enableDebugMode()\n * }\n * ```\n */\nexport function isDevelopment(req?: any): boolean {\n  if (isNodeEnvironment()) {\n    // En Node.js, verificar NODE_ENV primero\n    if (process.env.NODE_ENV === 'production') {\n      return false\n    }\n    if (process.env.NODE_ENV === 'development') {\n      return true\n    }\n\n    // Si hay request object (Express), usar lógica de servidor\n    if (req) {\n      const protocol = detectProtocol(req)\n      const hostname = detectHostname(req)\n\n      return protocol === 'http' || isLocalhost(hostname) || isPrivateIP(hostname)\n    }\n\n    // Fallback para Node.js sin request\n    // NODE_ENV undefined se asume como development\n    return !process.env.NODE_ENV || process.env.NODE_ENV === 'development'\n  }\n\n  if (isBrowserEnvironment()) {\n    // Verificar variable global de desarrollo (webpack/vite)\n    if (\n      typeof (globalThis as any).__DEV__ !== 'undefined' &&\n      (globalThis as any).__DEV__ === true\n    ) {\n      return true\n    }\n\n    // Verificar si hay herramientas de desarrollo activas\n    if (\n      typeof window !== 'undefined' &&\n      (window as any).__VUE_DEVTOOLS_GLOBAL_HOOK__ &&\n      typeof location !== 'undefined' &&\n      isLocalhost(location.hostname)\n    ) {\n      return true\n    }\n\n    // Si location no está disponible, considerar como producción\n    if (typeof location === 'undefined') {\n      return false\n    }\n\n    const hostname = location.hostname || ''\n    const port = parseInt(location.port || '80')\n\n    // Criterios basados en hostname y puerto\n    const isDevelopmentPort = port >= 3000 && port <= 9999\n\n    // Solo considerar HTTP como desarrollo si el hostname también lo indica\n    const isHttpDevelopment =\n      location.protocol === 'http:' && (isLocalhost(hostname) || isPrivateIP(hostname))\n\n    return isLocalhost(hostname) || isPrivateIP(hostname) || isDevelopmentPort || isHttpDevelopment\n  }\n\n  return false\n}\n\n/**\n * Detects if the application is running in production mode\n *\n * Simple inverse of isDevelopment() with additional NODE_ENV validation for Node.js.\n *\n * @returns True if in production mode, false if development\n *\n * @example\n * ```typescript\n * if (isProduction()) {\n *   // Enable performance optimizations\n *   enableProductionMode()\n * }\n * ```\n */\nexport function isProduction(): boolean {\n  if (isNodeEnvironment()) {\n    return process.env.NODE_ENV === 'production'\n  }\n\n  // Browser: inverso de isDevelopment (que ya excluye test)\n  return !isDevelopment()\n}\n\n/**\n * Detects if the application is running in test mode\n *\n * Checks explicitly for NODE_ENV === 'test' in Node.js environments.\n * Vitest and Jest automatically set this value when running tests.\n *\n * @returns True if NODE_ENV is 'test', false otherwise\n *\n * @example\n * ```typescript\n * if (isTest()) {\n *   // Test-specific behavior (mocks, fixtures, etc.)\n *   enableTestMode()\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Conditional imports for testing\n * if (isTest()) {\n *   const { mockAPI } = await import('./test/mocks')\n *   mockAPI.setup()\n * }\n * ```\n */\nexport function isTest(): boolean {\n  if (isNodeEnvironment()) {\n    return process.env.NODE_ENV === 'test'\n  }\n\n  return false\n}\n\n/**\n * Detects if the application is NOT running in production mode\n *\n * Returns true for development, test, undefined, or any non-production environment.\n * Useful for enabling debugging, logging, or development-only features\n * across all non-production environments.\n *\n * @returns True if not in production (development, test, or undefined)\n *\n * @example\n * ```typescript\n * if (isNonProduction()) {\n *   // Enable debug logging for dev and test\n *   console.log('Debug mode enabled')\n *   enableVerboseLogging()\n * }\n * ```\n *\n * @example\n * ```typescript\n * // Security: Disable strict checks in non-production\n * if (isNonProduction()) {\n *   allowSelfSignedCertificates()\n *   disableCSRFProtection()\n * }\n * ```\n */\nexport function isNonProduction(): boolean {\n  if (isNodeEnvironment()) {\n    return process.env.NODE_ENV !== 'production'\n  }\n\n  return !isProduction()\n}\n\n/**\n * Detects the protocol (HTTP/HTTPS) from browser location or request headers\n *\n * Handles reverse proxies correctly by checking forwarded headers in priority order:\n * 1. X-Forwarded-Proto (most common)\n * 2. X-Forwarded-Protocol\n * 3. X-Url-Scheme\n * 4. Front-End-Https\n * 5. CF-Visitor (Cloudflare specific)\n *\n * @param req - Optional Express request object with headers\n * @returns Protocol as 'http' or 'https'\n *\n * @example\n * ```typescript\n * // Browser usage\n * const protocol = detectProtocol() // 'https' from window.location\n * ```\n *\n * @example\n * ```typescript\n * // Express server with proxy\n * app.get('/api', (req, res) => {\n *   const protocol = detectProtocol(req) // Detects from X-Forwarded-Proto\n *   const fullUrl = `${protocol}://${req.get('host')}${req.path}`\n * })\n * ```\n */\nexport function detectProtocol(req?: any): 'http' | 'https' {\n  if (isBrowserEnvironment()) {\n    if (typeof location !== 'undefined') {\n      return location.protocol === 'https:' ? 'https' : 'http'\n    }\n    return 'https' // Default seguro para browser\n  }\n\n  if (req) {\n    // Headers comunes de proxies reversos en orden de prioridad\n    const forwardedProto = req.get?.('X-Forwarded-Proto') || req.headers?.['x-forwarded-proto']\n    const forwardedProtocol =\n      req.get?.('X-Forwarded-Protocol') || req.headers?.['x-forwarded-protocol']\n    const urlScheme = req.get?.('X-Url-Scheme') || req.headers?.['x-url-scheme']\n    const frontEndHttps = req.get?.('Front-End-Https') || req.headers?.['front-end-https']\n    const cloudflareVisitor = req.get?.('CF-Visitor') || req.headers?.['cf-visitor']\n\n    // Verificar headers de proxy\n    if (forwardedProto) {\n      return forwardedProto.split(',')[0].trim().toLowerCase() as 'http' | 'https'\n    }\n    if (forwardedProtocol) {\n      return forwardedProtocol.toLowerCase() as 'http' | 'https'\n    }\n    if (urlScheme) {\n      return urlScheme.toLowerCase() as 'http' | 'https'\n    }\n    if (frontEndHttps === 'on') {\n      return 'https'\n    }\n    if (cloudflareVisitor) {\n      try {\n        const visitor = JSON.parse(cloudflareVisitor)\n        if (visitor.scheme) {\n          return visitor.scheme.toLowerCase() as 'http' | 'https'\n        }\n      } catch (_e) {\n        // Ignorar errores de parsing JSON\n      }\n    }\n\n    // Fallback al protocolo directo\n    if (req.protocol) return req.protocol\n    if (req.secure) return 'https'\n  }\n\n  // Default para Node.js sin request context\n  return 'http'\n}\n\n/**\n * Extracts hostname from browser location or request headers\n *\n * Handles reverse proxies by checking forwarded headers in priority order:\n * 1. X-Forwarded-Host (most common, supports multiple hosts)\n * 2. X-Original-Host\n * 3. Host header\n *\n * Automatically strips port numbers and handles multiple comma-separated hosts.\n *\n * @param req - Optional Express request object with headers\n * @returns Hostname without port number\n *\n * @example\n * ```typescript\n * // Browser usage\n * const hostname = detectHostname() // 'example.com' from window.location\n * ```\n *\n * @example\n * ```typescript\n * // Express server behind proxy\n * app.get('/api', (req, res) => {\n *   const hostname = detectHostname(req) // 'api.example.com' from X-Forwarded-Host\n *   const isLocal = isLocalhost(hostname)\n * })\n * ```\n */\nexport function detectHostname(req?: any): string {\n  if (isBrowserEnvironment()) {\n    if (typeof location !== 'undefined') {\n      return location.hostname\n    }\n    return 'localhost'\n  }\n\n  if (req) {\n    // Headers comunes de proxies reversos en orden de prioridad\n    const forwardedHost = req.get?.('X-Forwarded-Host') || req.headers?.['x-forwarded-host']\n    const originalHost = req.get?.('X-Original-Host') || req.headers?.['x-original-host']\n    const host = req.get?.('Host') || req.headers?.['host']\n\n    // Verificar headers de proxy\n    if (forwardedHost) {\n      return forwardedHost.split(',')[0].trim().split(':')[0]\n    }\n    if (originalHost) {\n      return originalHost.split(':')[0]\n    }\n    if (host) {\n      return host.split(':')[0]\n    }\n\n    // Fallback al hostname directo\n    if (req.hostname) return req.hostname\n  }\n\n  // Default para Node.js sin request context\n  return 'localhost'\n}\n\n/**\n * Checks if a hostname represents localhost or local development\n *\n * Recognizes various localhost representations:\n * - 'localhost' (standard)\n * - '127.0.0.1' (IPv4 loopback)\n * - '::1' (IPv6 loopback)\n * - '*.localhost' (local development domains)\n * - '*.local' (mDNS local domains)\n *\n * @param hostname - Hostname to check\n * @returns True if hostname represents localhost\n *\n * @example\n * ```typescript\n * isLocalhost('localhost')        // true\n * isLocalhost('127.0.0.1')        // true\n * isLocalhost('app.localhost')    // true\n * isLocalhost('macbook.local')    // true\n * isLocalhost('example.com')      // false\n * ```\n */\nexport function isLocalhost(hostname: string): boolean {\n  return (\n    hostname === 'localhost' ||\n    hostname === '127.0.0.1' ||\n    hostname === '::1' ||\n    hostname.endsWith('.localhost') ||\n    hostname.endsWith('.local')\n  )\n}\n\n/**\n * Checks if a hostname is within private IP address ranges\n *\n * Recognizes private/internal IP ranges according to RFC 1918:\n * - IPv4: 10.x.x.x, 192.168.x.x, 172.16-31.x.x, 127.x.x.x (loopback)\n * - IPv6: ::1 (loopback), fc00::/7 (unique local), fe80::/10 (link-local)\n * - Also includes localhost detection\n *\n * @param hostname - Hostname or IP address to check\n * @returns True if hostname is private/local, false if public\n *\n * @example\n * ```typescript\n * isPrivateIP('192.168.1.1')      // true\n * isPrivateIP('10.0.0.1')         // true\n * isPrivateIP('172.16.0.1')       // true\n * isPrivateIP('localhost')        // true\n * isPrivateIP('8.8.8.8')          // false\n * isPrivateIP('example.com')      // false\n * ```\n */\nexport function isPrivateIP(hostname: string): boolean {\n  // IPv4 private ranges\n  const ipv4Patterns = [\n    /^10\\./, // 10.0.0.0/8\n    /^172\\.(1[6-9]|2[0-9]|3[0-1])\\./, // 172.16.0.0/12\n    /^192\\.168\\./, // 192.168.0.0/16\n    /^127\\./, // 127.0.0.0/8 (loopback)\n  ]\n\n  // IPv6 private/local ranges\n  const ipv6Patterns = [\n    /^::1$/, // IPv6 loopback\n    /^fc[0-9a-f]{2}:/i, // Unique local addresses\n    /^fd[0-9a-f]{2}:/i, // Unique local addresses\n    /^fe80:/i, // Link-local addresses\n  ]\n\n  return (\n    ipv4Patterns.some(pattern => pattern.test(hostname)) ||\n    ipv6Patterns.some(pattern => pattern.test(hostname)) ||\n    isLocalhost(hostname)\n  )\n}\n\n/**\n * Gathers complete environment information for debugging and analysis\n *\n * Returns comprehensive environment data including platform detection,\n * development/production status, protocol/hostname information, and\n * detailed debugging criteria.\n *\n * @param req - Optional Express request object for server-side context\n * @returns Complete environment information object\n *\n * @example\n * ```typescript\n * // Basic usage\n * const env = getEnvironmentInfo()\n * console.log(env.platform)     // 'node' | 'browser' | 'unknown'\n * console.log(env.environment)  // 'development' | 'production' | 'test'\n * ```\n *\n * @example\n * ```typescript\n * // Express server usage\n * app.get('/api/debug', (req, res) => {\n *   const envInfo = getEnvironmentInfo(req)\n *   res.json({\n *     platform: envInfo.platform,\n *     isDev: envInfo.environment === 'development',\n *     protocol: envInfo.protocol,\n *     host: envInfo.hostname,\n *     criteria: envInfo.criteria\n *   })\n * })\n * ```\n *\n * @example\n * ```typescript\n * // Conditional features based on environment\n * const env = getEnvironmentInfo()\n * if (env.criteria?.hasDevtools) {\n *   enableVueDevtools()\n * }\n * if (env.criteria?.isDevelopmentPort) {\n *   enableHotReload()\n * }\n * ```\n */\nexport function getEnvironmentInfo(req?: any): EnvironmentInfo {\n  const platform = isNodeEnvironment() ? 'node' : isBrowserEnvironment() ? 'browser' : 'unknown'\n\n  let environment: EnvironmentInfo['environment'] = 'production'\n  if (isNodeEnvironment()) {\n    const nodeEnv = process.env.NODE_ENV\n    if (nodeEnv === 'development' || nodeEnv === 'test') {\n      environment = nodeEnv\n    }\n  } else if (isDevelopment()) {\n    environment = 'development'\n  }\n\n  const protocol = detectProtocol(req)\n  const hostname = detectHostname(req)\n\n  const info: EnvironmentInfo = {\n    platform,\n    environment,\n    protocol,\n    hostname,\n  }\n\n  if (isBrowserEnvironment() && typeof navigator !== 'undefined') {\n    info.userAgent = navigator.userAgent\n  }\n\n  // Criterios detallados para debugging\n  const criteria: EnvironmentCriteria = {\n    isLocalhost: isLocalhost(hostname),\n    isPrivateIP: isPrivateIP(hostname),\n    isDevelopmentPort: false,\n    hasDevtools: false,\n  }\n\n  if (isBrowserEnvironment() && typeof location !== 'undefined') {\n    const port = parseInt(location.port || '80')\n    criteria.isDevelopmentPort = port >= 3000 && port <= 9999\n    criteria.hasDevtools = !!(\n      typeof window !== 'undefined' && (window as any).__VUE_DEVTOOLS_GLOBAL_HOOK__\n    )\n  }\n\n  if (isNodeEnvironment()) {\n    criteria.nodeEnv = process.env.NODE_ENV || 'undefined'\n  }\n\n  info.criteria = criteria\n\n  return info\n}\n\n/**\n * Alias for isNodeEnvironment() - detects Node.js runtime\n * @see {@link isNodeEnvironment}\n */\nexport const isNode = isNodeEnvironment\n\n/**\n * Alias for isBrowserEnvironment() - detects browser runtime\n * @see {@link isBrowserEnvironment}\n */\nexport const isBrowser = isBrowserEnvironment\n\n/**\n * Parses environment variable string values to their native JavaScript types\n *\n * Automatically detects and converts:\n * - Booleans: 'true', 'false', 'yes', 'no', '1', '0'\n * - Numbers: '42', '3.14', '-100'\n * - JSON arrays: '[1,2,3]', '[\"a\",\"b\"]'\n * - JSON objects: '{\"key\":\"value\"}'\n * - Comma-separated arrays: 'item1,item2,item3' (when not valid JSON)\n * - null/undefined: 'null', 'undefined', empty string\n *\n * Falls back to original string if no conversion applies.\n *\n * @param value - Environment variable string value to parse\n * @returns Parsed value with appropriate native type\n *\n * @example\n * ```typescript\n * // Boolean conversion\n * parseEnvValue('true')      // true\n * parseEnvValue('false')     // false\n * parseEnvValue('yes')       // true\n * parseEnvValue('1')         // true (as boolean)\n *\n * // Number conversion\n * parseEnvValue('42')        // 42\n * parseEnvValue('3.14')      // 3.14\n * parseEnvValue('-100')      // -100\n *\n * // JSON arrays\n * parseEnvValue('[1,2,3]')   // [1, 2, 3]\n * parseEnvValue('[\"a\",\"b\"]') // ['a', 'b']\n *\n * // JSON objects\n * parseEnvValue('{\"port\":3000,\"host\":\"localhost\"}')\n * // { port: 3000, host: 'localhost' }\n *\n * // Comma-separated arrays (fallback when not JSON)\n * parseEnvValue('red,green,blue')  // ['red', 'green', 'blue']\n *\n * // Null/undefined\n * parseEnvValue('null')      // null\n * parseEnvValue('undefined') // undefined\n * parseEnvValue('')          // undefined\n *\n * // Strings (no conversion)\n * parseEnvValue('hello')     // 'hello'\n * ```\n *\n * @example\n * ```typescript\n * // Real-world usage with process.env\n * const config = {\n *   debug: parseEnvValue(process.env.DEBUG),           // 'true' → true\n *   port: parseEnvValue(process.env.PORT),             // '3000' → 3000\n *   features: parseEnvValue(process.env.FEATURES),     // 'auth,api' → ['auth', 'api']\n *   database: parseEnvValue(process.env.DB_CONFIG),    // '{\"host\":\"localhost\"}' → object\n * }\n * ```\n */\nexport function parseEnvValue(value: string | undefined): any {\n  // Handle null/undefined/empty\n  if (value === undefined || value === null || value === '') {\n    return undefined\n  }\n\n  const trimmed = value.trim()\n\n  // Handle explicit null/undefined strings\n  if (trimmed === 'null') return null\n  if (trimmed === 'undefined') return undefined\n\n  // Handle booleans\n  const lowerValue = trimmed.toLowerCase()\n  if (lowerValue === 'true' || lowerValue === 'yes') return true\n  if (lowerValue === 'false' || lowerValue === 'no') return false\n\n  // Handle boolean-like numbers\n  if (trimmed === '1') return true\n  if (trimmed === '0') return false\n\n  // Try parsing as number (but not if it starts with 0 and has more digits - could be octal/string)\n  if (/^-?\\d+\\.?\\d*$/.test(trimmed)) {\n    // Avoid treating leading-zero strings as numbers (e.g., postal codes '01234')\n    if (trimmed.length > 1 && trimmed[0] === '0' && trimmed[1] !== '.') {\n      return trimmed // Keep as string (e.g., '01234')\n    }\n    const num = Number(trimmed)\n    if (!isNaN(num)) return num\n  }\n\n  // Try parsing as JSON (arrays, objects)\n  if (\n    (trimmed.startsWith('[') && trimmed.endsWith(']')) ||\n    (trimmed.startsWith('{') && trimmed.endsWith('}'))\n  ) {\n    try {\n      return JSON.parse(trimmed)\n    } catch {\n      // Not valid JSON, continue to next check\n    }\n  }\n\n  // Try parsing comma-separated values as array\n  if (trimmed.includes(',')) {\n    const parts = trimmed.split(',').map(s => s.trim())\n    // Only convert to array if all parts are non-empty\n    if (parts.every(p => p.length > 0)) {\n      return parts\n    }\n  }\n\n  // Return as-is string\n  return trimmed\n}\n"],"mappings":"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","names":[]}

package/dist/node/errors.js

@@ -0,0 +1,89 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/errors.ts
+var errors_exports = {};
+__export(errors_exports, {
+  DataError: () => DataError,
+  TsHelpersError: () => TsHelpersError,
+  TsHelpersErrorCode: () => TsHelpersErrorCode,
+  createCryptoError: () => createCryptoError,
+  createMathError: () => createMathError,
+  createValidationError: () => createValidationError
+});
+module.exports = __toCommonJS(errors_exports);
+var TsHelpersErrorCode = /* @__PURE__ */ ((TsHelpersErrorCode2) => {
+  TsHelpersErrorCode2["VALIDATION_FAILED"] = "VALIDATION_FAILED";
+  TsHelpersErrorCode2["DATA_PROCESSING_FAILED"] = "DATA_PROCESSING_FAILED";
+  TsHelpersErrorCode2["ENVIRONMENT_NOT_SUPPORTED"] = "ENVIRONMENT_NOT_SUPPORTED";
+  TsHelpersErrorCode2["UNSUPPORTED_FORMAT"] = "UNSUPPORTED_FORMAT";
+  TsHelpersErrorCode2["FILE_ERROR"] = "FILE_ERROR";
+  TsHelpersErrorCode2["NETWORK_ERROR"] = "NETWORK_ERROR";
+  TsHelpersErrorCode2["INVALID_OPERATION"] = "INVALID_OPERATION";
+  TsHelpersErrorCode2["CRYPTO_ERROR"] = "CRYPTO_ERROR";
+  TsHelpersErrorCode2["MATH_ERROR"] = "MATH_ERROR";
+  TsHelpersErrorCode2["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+  return TsHelpersErrorCode2;
+})(TsHelpersErrorCode || {});
+var TsHelpersError = class _TsHelpersError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "TsHelpersError";
+    this.code = options.code;
+    this.data = options.data;
+    this.cause = options.cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _TsHelpersError);
+    }
+  }
+};
+var DataError = class extends TsHelpersError {
+  constructor(message, code, data) {
+    super(message, { code, data });
+    this.name = "DataError";
+  }
+};
+function createValidationError(message, field, value) {
+  return new TsHelpersError(`Validation failed: ${message}`, {
+    code: "VALIDATION_FAILED" /* VALIDATION_FAILED */,
+    data: { field, value }
+  });
+}
+function createCryptoError(message, operation, details) {
+  return new TsHelpersError(`Crypto error: ${message}`, {
+    code: "CRYPTO_ERROR" /* CRYPTO_ERROR */,
+    data: { operation, details }
+  });
+}
+function createMathError(message, operation, input) {
+  return new TsHelpersError(`Math error: ${message}`, {
+    code: "MATH_ERROR" /* MATH_ERROR */,
+    data: { operation, input }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DataError,
+  TsHelpersError,
+  TsHelpersErrorCode,
+  createCryptoError,
+  createMathError,
+  createValidationError
+});
+//# sourceMappingURL=errors.js.map

package/dist/node/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors.ts"],"sourcesContent":["/**\n * Error handling utilities with specific error types and codes\n * Provides structured error handling for validation, data processing, and environment issues\n */\n\n/**\n * Enumeration of specific error codes for different failure scenarios\n * @example\n * ```ts\n * // Using error codes for type-safe error handling\n * try {\n *   validateNIF('invalid')\n * } catch (error) {\n *   if (error.code === TsHelpersErrorCode.VALIDATION_FAILED) {\n *     console.log('Validation error:', error.data)\n *   }\n * }\n * ```\n */\nexport enum TsHelpersErrorCode {\n  /** Validation of input data failed (NIF, email, etc.) */\n  VALIDATION_FAILED = 'VALIDATION_FAILED',\n  /** Error processing data (CSV, JSON, aggregations, etc.) */\n  DATA_PROCESSING_FAILED = 'DATA_PROCESSING_FAILED',\n  /** Current environment doesn't support the operation */\n  ENVIRONMENT_NOT_SUPPORTED = 'ENVIRONMENT_NOT_SUPPORTED',\n  /** File format not supported for import/export */\n  UNSUPPORTED_FORMAT = 'UNSUPPORTED_FORMAT',\n  /** File system operation failed */\n  FILE_ERROR = 'FILE_ERROR',\n  /** Network or fetch operation failed */\n  NETWORK_ERROR = 'NETWORK_ERROR',\n  /** Invalid operation or function call */\n  INVALID_OPERATION = 'INVALID_OPERATION',\n  /** Crypto operation failed (hash, token generation) */\n  CRYPTO_ERROR = 'CRYPTO_ERROR',\n  /** Math calculation failed (invalid input, division by zero) */\n  MATH_ERROR = 'MATH_ERROR',\n  /** Generic unknown error */\n  UNKNOWN_ERROR = 'UNKNOWN_ERROR',\n}\n\n/**\n * Options for creating TsHelpersError instances\n */\nexport interface TsHelpersErrorOptions {\n  /** Specific error code for categorization */\n  code?: TsHelpersErrorCode\n  /** Additional data about the error context */\n  data?: any\n  /** Original error that caused this error */\n  cause?: Error\n}\n\n/**\n * Main error class for @g10/ts-helpers with structured error information\n * @example\n * ```ts\n * // Creating structured errors\n * throw new TsHelpersError('Invalid NIF format', {\n *   code: TsHelpersErrorCode.VALIDATION_FAILED,\n *   data: { input: '12345', expected: '8 digits + letter' }\n * })\n *\n * // Error handling with type checking\n * try {\n *   someOperation()\n * } catch (error) {\n *   if (error instanceof TsHelpersError) {\n *     console.log('Error code:', error.code)\n *     console.log('Error data:', error.data)\n *   }\n * }\n * ```\n */\nexport class TsHelpersError extends Error {\n  public readonly code?: TsHelpersErrorCode\n  public readonly data?: any\n  public readonly cause?: Error\n\n  constructor(message: string, options: TsHelpersErrorOptions = {}) {\n    super(message)\n    this.name = 'TsHelpersError'\n    this.code = options.code\n    this.data = options.data\n    this.cause = options.cause\n\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, TsHelpersError)\n    }\n  }\n}\n\n/**\n * Specialized error class for data processing operations\n * @example\n * ```ts\n * // Data processing errors\n * throw new DataError(\n *   'Failed to parse CSV',\n *   TsHelpersErrorCode.DATA_PROCESSING_FAILED,\n *   { line: 5, column: 'amount' }\n * )\n * ```\n */\nexport class DataError extends TsHelpersError {\n  constructor(message: string, code?: TsHelpersErrorCode, data?: any) {\n    super(message, { code, data })\n    this.name = 'DataError'\n  }\n}\n\n/**\n * Creates a validation error with structured information\n * @param message - Descriptive error message\n * @param field - Field name that failed validation\n * @param value - Value that failed validation\n * @returns TsHelpersError with validation context\n * @example\n * ```ts\n * // Using in validation functions\n * if (!isValidEmail(email)) {\n *   throw createValidationError('Invalid email format', 'email', email)\n * }\n *\n * // Error contains structured data\n * // error.code === TsHelpersErrorCode.VALIDATION_FAILED\n * // error.data === { field: 'email', value: 'invalid-email' }\n * ```\n */\nexport function createValidationError(message: string, field: string, value: any): TsHelpersError {\n  return new TsHelpersError(`Validation failed: ${message}`, {\n    code: TsHelpersErrorCode.VALIDATION_FAILED,\n    data: { field, value },\n  })\n}\n\n/**\n * Creates a crypto operation error\n * @param message - Descriptive error message\n * @param operation - Crypto operation that failed\n * @param details - Additional error details\n * @returns TsHelpersError with crypto context\n * @example\n * ```ts\n * // Using in crypto functions\n * if (!crypto.getRandomValues) {\n *   throw createCryptoError('Web Crypto API not available', 'generateSecureToken', {\n *     environment: 'browser',\n *     fallback: 'Math.random'\n *   })\n * }\n * ```\n */\nexport function createCryptoError(\n  message: string,\n  operation: string,\n  details?: any\n): TsHelpersError {\n  return new TsHelpersError(`Crypto error: ${message}`, {\n    code: TsHelpersErrorCode.CRYPTO_ERROR,\n    data: { operation, details },\n  })\n}\n\n/**\n * Creates a math calculation error\n * @param message - Descriptive error message\n * @param operation - Math operation that failed\n * @param input - Input data that caused the error\n * @returns TsHelpersError with math context\n * @example\n * ```ts\n * // Using in math functions\n * if (values.length === 0) {\n *   throw createMathError('Cannot calculate median of empty array', 'calculateMedian', values)\n * }\n * ```\n */\nexport function createMathError(message: string, operation: string, input?: any): TsHelpersError {\n  return new TsHelpersError(`Math error: ${message}`, {\n    code: TsHelpersErrorCode.MATH_ERROR,\n    data: { operation, input },\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmBO,IAAK,qBAAL,kBAAKA,wBAAL;AAEL,EAAAA,oBAAA,uBAAoB;AAEpB,EAAAA,oBAAA,4BAAyB;AAEzB,EAAAA,oBAAA,+BAA4B;AAE5B,EAAAA,oBAAA,wBAAqB;AAErB,EAAAA,oBAAA,gBAAa;AAEb,EAAAA,oBAAA,mBAAgB;AAEhB,EAAAA,oBAAA,uBAAoB;AAEpB,EAAAA,oBAAA,kBAAe;AAEf,EAAAA,oBAAA,gBAAa;AAEb,EAAAA,oBAAA,mBAAgB;AApBN,SAAAA;AAAA,GAAA;AAwDL,IAAM,iBAAN,MAAM,wBAAuB,MAAM;AAAA,EAKxC,YAAY,SAAiB,UAAiC,CAAC,GAAG;AAChE,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO,QAAQ;AACpB,SAAK,OAAO,QAAQ;AACpB,SAAK,QAAQ,QAAQ;AAErB,QAAI,MAAM,mBAAmB;AAC3B,YAAM,kBAAkB,MAAM,eAAc;AAAA,IAC9C;AAAA,EACF;AACF;AAcO,IAAM,YAAN,cAAwB,eAAe;AAAA,EAC5C,YAAY,SAAiB,MAA2B,MAAY;AAClE,UAAM,SAAS,EAAE,MAAM,KAAK,CAAC;AAC7B,SAAK,OAAO;AAAA,EACd;AACF;AAoBO,SAAS,sBAAsB,SAAiB,OAAe,OAA4B;AAChG,SAAO,IAAI,eAAe,sBAAsB,OAAO,IAAI;AAAA,IACzD,MAAM;AAAA,IACN,MAAM,EAAE,OAAO,MAAM;AAAA,EACvB,CAAC;AACH;AAmBO,SAAS,kBACd,SACA,WACA,SACgB;AAChB,SAAO,IAAI,eAAe,iBAAiB,OAAO,IAAI;AAAA,IACpD,MAAM;AAAA,IACN,MAAM,EAAE,WAAW,QAAQ;AAAA,EAC7B,CAAC;AACH;AAgBO,SAAS,gBAAgB,SAAiB,WAAmB,OAA6B;AAC/F,SAAO,IAAI,eAAe,eAAe,OAAO,IAAI;AAAA,IAClD,MAAM;AAAA,IACN,MAAM,EAAE,WAAW,MAAM;AAAA,EAC3B,CAAC;AACH;","names":["TsHelpersErrorCode"]}