@happyvertical/smrt-core 0.30.0

package/dist/errors.js

@@ -0,0 +1,669 @@
+import { createLogger } from "@happyvertical/logger";
+const logger = createLogger({ level: "info" });
+class SmrtError extends Error {
+  code;
+  category;
+  details;
+  cause;
+  constructor(message, code, category, details, cause) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.category = category;
+    this.details = details;
+    this.cause = cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Converts error to a serializable object for logging/debugging
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      category: this.category,
+      details: this.details,
+      stack: this.stack,
+      cause: this.cause ? {
+        name: this.cause.name,
+        message: this.cause.message,
+        stack: this.cause.stack
+      } : void 0
+    };
+  }
+}
+function collectErrorMessages(value, messages, visited, depth = 0) {
+  if (!value || visited.has(value) || depth > 10) {
+    return;
+  }
+  visited.add(value);
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed) {
+      messages.push(trimmed);
+    }
+    return;
+  }
+  if (!(value instanceof Error)) {
+    return;
+  }
+  const message = value.message?.trim();
+  if (message) {
+    messages.push(message);
+  }
+  const errorWithContext = value;
+  collectErrorMessages(
+    errorWithContext.context?.originalError,
+    messages,
+    visited,
+    depth + 1
+  );
+  collectErrorMessages(errorWithContext.cause, messages, visited, depth + 1);
+}
+function getPrimaryCauseMessage(cause) {
+  if (!cause) {
+    return {};
+  }
+  const collected = [];
+  collectErrorMessages(cause, collected, /* @__PURE__ */ new Set());
+  const uniqueMessages = [...new Set(collected.filter(Boolean))];
+  if (uniqueMessages.length === 0) {
+    return {};
+  }
+  return {
+    message: uniqueMessages[uniqueMessages.length - 1],
+    messages: uniqueMessages
+  };
+}
+class DatabaseError extends SmrtError {
+  constructor(message, code, details, cause) {
+    super(message, code, "database", details, cause);
+  }
+  static connectionFailed(dbUrl, cause) {
+    return new DatabaseError(
+      `Failed to connect to database: ${dbUrl}`,
+      "DB_CONNECTION_FAILED",
+      { dbUrl },
+      cause
+    );
+  }
+  static queryFailed(query, cause) {
+    const causeInfo = getPrimaryCauseMessage(cause);
+    const causeMsg = causeInfo.message ? `
+Cause: ${causeInfo.message}` : "";
+    return new DatabaseError(
+      `Database query failed: ${query.substring(0, 100)}${query.length > 100 ? "..." : ""}${causeMsg}`,
+      "DB_QUERY_FAILED",
+      {
+        query,
+        causeMessage: causeInfo.message,
+        causeMessages: causeInfo.messages
+      },
+      cause
+    );
+  }
+  static schemaError(tableName, operation, cause) {
+    return new DatabaseError(
+      `Schema operation failed for table '${tableName}': ${operation}`,
+      "DB_SCHEMA_ERROR",
+      { tableName, operation },
+      cause
+    );
+  }
+  static constraintViolation(constraint, value, cause) {
+    return new DatabaseError(
+      `Database constraint violation: ${constraint}`,
+      "DB_CONSTRAINT_VIOLATION",
+      { constraint, value },
+      cause
+    );
+  }
+  static corruptedData(fieldName, className, cause) {
+    return new DatabaseError(
+      `Corrupted data in field '${fieldName}' for ${className}. The data cannot be parsed or is malformed. This may indicate database corruption or incompatible schema changes.`,
+      "DB_CORRUPTED_DATA",
+      { fieldName, className },
+      cause
+    );
+  }
+  static missingDiscriminator(className, rowId) {
+    return new DatabaseError(
+      `Missing discriminator (_meta_type) for STI class ${className}${rowId ? ` (row id: ${rowId})` : ""}. STI classes require a discriminator column to determine the correct subclass. This may indicate a schema mismatch or manual database modification.`,
+      "DB_MISSING_DISCRIMINATOR",
+      { className, rowId }
+    );
+  }
+  static stiDiscriminatorConflict(details) {
+    const identityText = Object.entries(details.conflictIdentity).map(([key, value]) => `${key} '${String(value)}'`).join(", ");
+    return new DatabaseError(
+      `Legacy STI discriminator collision for ${details.className} (${details.tableName}). Row '${details.id}' would upgrade _meta_type from '${details.legacyMetaType}' to '${details.qualifiedMetaType}', but row '${details.duplicateId}' already uses the qualified discriminator for ${identityText || "the same conflict identity"}. Merge or remove the duplicate legacy/qualified rows before saving.`,
+      "DB_STI_DISCRIMINATOR_CONFLICT",
+      details
+    );
+  }
+  static schemaMissing(tableName, className) {
+    return new DatabaseError(
+      `Table '${tableName}' does not exist for class '${className}'. Run 'smrt db:migrate' to create database schema.`,
+      "DB_SCHEMA_MISSING",
+      { tableName, className }
+    );
+  }
+}
+class AIError extends SmrtError {
+  constructor(message, code, details, cause) {
+    super(message, code, "ai", details, cause);
+  }
+  static providerError(provider, operation, cause) {
+    return new AIError(
+      `AI provider '${provider}' failed during ${operation}`,
+      "AI_PROVIDER_ERROR",
+      { provider, operation },
+      cause
+    );
+  }
+  static rateLimitExceeded(provider, retryAfter) {
+    return new AIError(
+      `AI provider '${provider}' rate limit exceeded`,
+      "AI_RATE_LIMIT",
+      { provider, retryAfter }
+    );
+  }
+  static invalidResponse(provider, response) {
+    return new AIError(
+      `AI provider '${provider}' returned invalid response`,
+      "AI_INVALID_RESPONSE",
+      { provider, response }
+    );
+  }
+  static authenticationFailed(provider) {
+    return new AIError(
+      `AI provider '${provider}' authentication failed`,
+      "AI_AUTH_FAILED",
+      { provider }
+    );
+  }
+}
+class FilesystemError extends SmrtError {
+  constructor(message, code, details, cause) {
+    super(message, code, "filesystem", details, cause);
+  }
+  static fileNotFound(path) {
+    return new FilesystemError(`File not found: ${path}`, "FS_FILE_NOT_FOUND", {
+      path
+    });
+  }
+  static permissionDenied(path, operation) {
+    return new FilesystemError(
+      `Permission denied for ${operation} on: ${path}`,
+      "FS_PERMISSION_DENIED",
+      { path, operation }
+    );
+  }
+  static diskSpaceExceeded(path, requiredBytes) {
+    return new FilesystemError(
+      `Insufficient disk space for operation on: ${path}`,
+      "FS_DISK_SPACE_EXCEEDED",
+      { path, requiredBytes }
+    );
+  }
+}
+class ValidationError extends SmrtError {
+  constructor(message, code, details, cause) {
+    super(message, code, "validation", details, cause);
+  }
+  static requiredField(fieldName, objectType) {
+    return new ValidationError(
+      `Required field '${fieldName}' is missing for ${objectType}`,
+      "VALIDATION_REQUIRED_FIELD",
+      { fieldName, objectType }
+    );
+  }
+  static invalidValue(fieldName, value, expectedType) {
+    return new ValidationError(
+      `Invalid value for field '${fieldName}': expected ${expectedType}, got ${typeof value}`,
+      "VALIDATION_INVALID_VALUE",
+      { fieldName, value, expectedType }
+    );
+  }
+  static uniqueConstraint(fieldName, value) {
+    return new ValidationError(
+      `Unique constraint violation for field '${fieldName}' with value: ${value}`,
+      "VALIDATION_UNIQUE_CONSTRAINT",
+      { fieldName, value }
+    );
+  }
+  static rangeError(fieldName, value, min, max) {
+    const range = min !== void 0 && max !== void 0 ? `between ${min} and ${max}` : min !== void 0 ? `>= ${min}` : `<= ${max}`;
+    return new ValidationError(
+      `Value for field '${fieldName}' must be ${range}, got: ${value}`,
+      "VALIDATION_RANGE_ERROR",
+      { fieldName, value, min, max }
+    );
+  }
+}
+class NetworkError extends SmrtError {
+  constructor(message, code, details, cause) {
+    super(message, code, "network", details, cause);
+  }
+  static requestFailed(url, status, responseBody) {
+    const cause = responseBody instanceof Error ? responseBody : void 0;
+    const body = typeof responseBody === "string" ? responseBody : void 0;
+    return new NetworkError(
+      `Network request failed: ${url}${status ? ` (Status: ${status})` : ""}${body ? ` - ${body.substring(0, 200)}` : ""}`,
+      "NETWORK_REQUEST_FAILED",
+      { url, status, responseBody: body },
+      cause
+    );
+  }
+  static timeout(url, timeoutMs) {
+    return new NetworkError(
+      `Network request timed out after ${timeoutMs}ms: ${url}`,
+      "NETWORK_TIMEOUT",
+      { url, timeoutMs }
+    );
+  }
+  static serviceUnavailable(service, reason) {
+    return new NetworkError(
+      reason ? `External service unavailable: ${service} - ${reason}` : `External service unavailable: ${service}`,
+      "NETWORK_SERVICE_UNAVAILABLE",
+      { service, reason }
+    );
+  }
+}
+class ConfigurationError extends SmrtError {
+  constructor(message, code, details, cause) {
+    super(message, code, "configuration", details, cause);
+  }
+  static missingConfiguration(configKey, context) {
+    return new ConfigurationError(
+      `Missing required configuration: ${configKey}${context ? ` in ${context}` : ""}`,
+      "CONFIG_MISSING",
+      { configKey, context }
+    );
+  }
+  static invalidConfiguration(configKey, value, expected) {
+    return new ConfigurationError(
+      `Invalid configuration for ${configKey}: expected ${expected}, got ${typeof value}`,
+      "CONFIG_INVALID",
+      { configKey, value, expected }
+    );
+  }
+  static initializationFailed(component, cause) {
+    return new ConfigurationError(
+      `Failed to initialize component: ${component}`,
+      "CONFIG_INIT_FAILED",
+      { component },
+      cause
+    );
+  }
+  static circularInheritance(className, inheritanceChain) {
+    return new ConfigurationError(
+      `Circular inheritance detected for class '${className}'. Inheritance chain: ${inheritanceChain.join(" → ")} → ${className}. Classes cannot inherit from themselves directly or indirectly.`,
+      "CONFIG_CIRCULAR_INHERITANCE",
+      { className, inheritanceChain }
+    );
+  }
+  static incompatibleStrategy(className, classStrategy, parentClass, parentStrategy) {
+    return new ConfigurationError(
+      `Incompatible table strategy for class '${className}' (${classStrategy}). Parent class '${parentClass}' uses ${parentStrategy} strategy. Child classes must use the same table strategy as their parent. Either change ${className} to use ${parentStrategy}, or remove the inheritance.`,
+      "CONFIG_INCOMPATIBLE_STRATEGY",
+      { className, classStrategy, parentClass, parentStrategy }
+    );
+  }
+  static unregisteredBaseClass(childClass, baseClass) {
+    return new ConfigurationError(
+      `STI base class '${baseClass}' is not registered for child class '${childClass}'. When using Single Table Inheritance, the base class must be registered before any child classes. Ensure ${baseClass} is decorated with @smrt({ tableStrategy: 'sti' }) and imported before ${childClass}.`,
+      "CONFIG_UNREGISTERED_BASE",
+      { childClass, baseClass }
+    );
+  }
+}
+class RuntimeError extends SmrtError {
+  constructor(message, code, details, cause) {
+    super(message, code, "runtime", details, cause);
+  }
+  static operationFailed(operation, context, cause) {
+    return new RuntimeError(
+      `Operation failed: ${operation}${context ? ` in ${context}` : ""}`,
+      "RUNTIME_OPERATION_FAILED",
+      { operation, context },
+      cause
+    );
+  }
+  static invalidState(message, context) {
+    return new RuntimeError(message, "RUNTIME_INVALID_STATE", context);
+  }
+  static resourceExhausted(resource, limit) {
+    return new RuntimeError(
+      `Resource exhausted: ${resource} exceeded limit of ${limit}`,
+      "RUNTIME_RESOURCE_EXHAUSTED",
+      { resource, limit }
+    );
+  }
+}
+class TenantIsolationError extends SmrtError {
+  /** The tenant ID of the object that owns the relationship. */
+  tenantId;
+  /** The tenant ID of the related object that was reached (and rejected). */
+  attemptedTenantId;
+  constructor(message, details, cause) {
+    super(message, "TENANT_ISOLATION_VIOLATION", "validation", details, cause);
+    this.tenantId = details?.tenantId;
+    this.attemptedTenantId = details?.attemptedTenantId;
+  }
+  /**
+   * Builds a {@link TenantIsolationError} for a blocked cross-tenant
+   * relationship resolution, with a descriptive message and structured details.
+   */
+  static crossTenantReference(details) {
+    const target = details.targetClass ? `${details.targetClass} (tenant '${details.targetTenantId}')` : `tenant '${details.targetTenantId}'`;
+    return new TenantIsolationError(
+      `Cross-tenant relationship access blocked on ${details.sourceClass}.${details.fieldName}: owning tenant '${details.sourceTenantId}' does not match ${target}. Pass { allowCrossTenant: true } to loadRelated()/loadRelatedMany()/getRelated() to override.`,
+      {
+        tenantId: details.sourceTenantId,
+        attemptedTenantId: details.targetTenantId,
+        sourceClass: details.sourceClass,
+        fieldName: details.fieldName,
+        targetClass: details.targetClass
+      }
+    );
+  }
+}
+class ErrorUtils {
+  /**
+   * Wraps a function with error handling and automatic retry logic
+   */
+  static async withRetry(operation, maxRetries = 3, delay = 1e3, backoffMultiplier = 2) {
+    let lastError = new Error("Operation failed without error details");
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt === maxRetries) {
+          throw lastError;
+        }
+        if (error instanceof ValidationError || error instanceof ConfigurationError || error instanceof TenantIsolationError) {
+          throw error;
+        }
+        try {
+          await new Promise((resolve) => {
+            setTimeout(() => resolve(), delay * backoffMultiplier ** attempt);
+          });
+        } catch (timerError) {
+          logger.error("Timer error during retry", { error: timerError });
+        }
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Checks if an error is retryable
+   */
+  static isRetryable(error) {
+    if (error instanceof SmrtError) {
+      return error.category === "network" || error.category === "ai";
+    }
+    const retryablePatterns = [
+      /ECONNRESET/,
+      /ETIMEDOUT/,
+      /ENOTFOUND/,
+      /rate.?limit/i,
+      /timeout/i,
+      /503/,
+      /502/,
+      /500/
+    ];
+    return retryablePatterns.some((pattern) => pattern.test(error.message));
+  }
+  /**
+   * Sanitizes an error for safe logging (removes sensitive information)
+   */
+  static sanitizeError(error) {
+    const sanitized = {
+      name: error.name,
+      message: error.message,
+      stack: error.stack
+    };
+    if (error instanceof SmrtError) {
+      sanitized.code = error.code;
+      sanitized.category = error.category;
+      if (error.details) {
+        sanitized.details = { ...error.details };
+        const sensitiveFields = [
+          "password",
+          "token",
+          "key",
+          "secret",
+          "apiKey"
+        ];
+        for (const field of sensitiveFields) {
+          if (sanitized.details[field]) {
+            sanitized.details[field] = "[REDACTED]";
+          }
+        }
+      }
+    }
+    return sanitized;
+  }
+}
+class ValidationReport {
+  errors = [];
+  objectType;
+  constructor(objectType) {
+    this.objectType = objectType;
+  }
+  /**
+   * Add a validation error to the report
+   */
+  addError(error) {
+    this.errors.push(error);
+  }
+  /**
+   * Check if there are any validation errors
+   */
+  hasErrors() {
+    return this.errors.length > 0;
+  }
+  /**
+   * Get all validation errors
+   */
+  getErrors() {
+    return [...this.errors];
+  }
+  /**
+   * Get the number of validation errors
+   */
+  getErrorCount() {
+    return this.errors.length;
+  }
+  /**
+   * Convert to a human-readable string
+   */
+  toString() {
+    if (this.errors.length === 0) {
+      return `Validation passed for ${this.objectType}`;
+    }
+    const errorList = this.errors.map((err, idx) => `  ${idx + 1}. ${err.message}`).join("\n");
+    return `Validation failed for ${this.objectType} with ${this.errors.length} error(s):
+${errorList}`;
+  }
+  /**
+   * Convert to JSON format
+   */
+  toJSON() {
+    return {
+      objectType: this.objectType,
+      errorCount: this.errors.length,
+      errors: this.errors.map((err) => err.toJSON())
+    };
+  }
+  /**
+   * Throw the first error if there are any errors
+   */
+  throwIfErrors() {
+    if (this.errors.length > 0) {
+      throw this.errors[0];
+    }
+  }
+  /**
+   * Clear all errors
+   */
+  clear() {
+    this.errors = [];
+  }
+}
+class ValidationUtils {
+  /**
+   * Validate a single field value
+   *
+   * @param fieldName - Name of the field
+   * @param value - Value to validate
+   * @param options - Validation options (required, min, max, etc.)
+   * @returns ValidationError if validation fails, null otherwise
+   */
+  static async validateField(fieldName, value, options, objectType = "Object") {
+    if (options.required && (value === null || value === void 0 || value === "")) {
+      return ValidationError.requiredField(fieldName, objectType);
+    }
+    if (value === null || value === void 0) {
+      return null;
+    }
+    if (typeof value === "number") {
+      if (options.min !== void 0 && value < options.min) {
+        return ValidationError.rangeError(
+          fieldName,
+          value,
+          options.min,
+          options.max
+        );
+      }
+      if (options.max !== void 0 && value > options.max) {
+        return ValidationError.rangeError(
+          fieldName,
+          value,
+          options.min,
+          options.max
+        );
+      }
+    }
+    if (typeof value === "string") {
+      if (options.minLength !== void 0 && value.length < options.minLength) {
+        return ValidationError.invalidValue(
+          fieldName,
+          value,
+          `string with minimum length ${options.minLength}`
+        );
+      }
+      if (options.maxLength !== void 0 && value.length > options.maxLength) {
+        return ValidationError.invalidValue(
+          fieldName,
+          value,
+          `string with maximum length ${options.maxLength}`
+        );
+      }
+      if (options.pattern) {
+        const regex = typeof options.pattern === "string" ? new RegExp(options.pattern) : options.pattern;
+        if (!regex.test(value)) {
+          return ValidationError.invalidValue(
+            fieldName,
+            value,
+            `string matching pattern ${options.pattern}`
+          );
+        }
+      }
+    }
+    if (options.customValidator) {
+      try {
+        const isValid = await options.customValidator(value);
+        if (!isValid) {
+          return ValidationError.invalidValue(
+            fieldName,
+            value,
+            options.customMessage || "custom validation failed"
+          );
+        }
+      } catch (error) {
+        return ValidationError.invalidValue(
+          fieldName,
+          value,
+          `custom validation error: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    return null;
+  }
+  /**
+   * Validate required field
+   */
+  static validateRequired(fieldName, value, objectType = "Object") {
+    if (value === null || value === void 0 || value === "") {
+      return ValidationError.requiredField(fieldName, objectType);
+    }
+    return null;
+  }
+  /**
+   * Validate numeric range
+   */
+  static validateRange(fieldName, value, min, max) {
+    if (min !== void 0 && value < min) {
+      return ValidationError.rangeError(fieldName, value, min, max);
+    }
+    if (max !== void 0 && value > max) {
+      return ValidationError.rangeError(fieldName, value, min, max);
+    }
+    return null;
+  }
+  /**
+   * Validate string length
+   */
+  static validateLength(fieldName, value, minLength, maxLength) {
+    if (minLength !== void 0 && value.length < minLength) {
+      return ValidationError.invalidValue(
+        fieldName,
+        value,
+        `string with minimum length ${minLength}`
+      );
+    }
+    if (maxLength !== void 0 && value.length > maxLength) {
+      return ValidationError.invalidValue(
+        fieldName,
+        value,
+        `string with maximum length ${maxLength}`
+      );
+    }
+    return null;
+  }
+  /**
+   * Validate string pattern
+   */
+  static validatePattern(fieldName, value, pattern) {
+    const regex = typeof pattern === "string" ? new RegExp(pattern) : pattern;
+    if (!regex.test(value)) {
+      return ValidationError.invalidValue(
+        fieldName,
+        value,
+        `string matching pattern ${pattern}`
+      );
+    }
+    return null;
+  }
+}
+export {
+  AIError,
+  ConfigurationError,
+  DatabaseError,
+  ErrorUtils,
+  FilesystemError,
+  NetworkError,
+  RuntimeError,
+  SmrtError,
+  TenantIsolationError,
+  ValidationError,
+  ValidationReport,
+  ValidationUtils
+};
+//# sourceMappingURL=errors.js.map