arvo-core 2.2.4 → 2.2.5

package/dist/errors.d.ts

@@ -1,11 +1,55 @@
+/**
+ * Parameters for constructing a ViolationError
+ */
 export type ViolationErrorParam<T extends string = string> = {
+    /** The specific type/category of the violation */
     type: T;
+    /** A human-readable description of what went wrong */
     message: string;
+    /** Optional structured data providing additional context about the error */
     metadata?: Record<string, any>;
 };
+/**
+ * ViolationError represents errors that require explicit handling in the system.
+ * These are distinct from recoverable errors that can be automatically handled
+ * by workflow logic. The explicit handling may be required for severe
+ * violation of service contracts or explict retry handling
+ *
+ * Common violation scenarios include:
+ * - Rate limit exceeded on external API calls
+ * - Contract violations (invalid input/output)
+ * - Configuration errors
+ * - Permission/authorization failures
+ *
+ * @example
+ * ```typescript
+ * // Creating a rate limit violation
+ * throw new ViolationError({
+ *   type: 'RATE_LIMIT_EXCEEDED',
+ *   message: 'API rate limit reached, retry after 60 seconds',
+ *   metadata: { retryAfter: 60 }
+ * });
+ *
+ * // Handling violations
+ * try {
+ *   await apiCall();
+ * } catch (error) {
+ *   if (error instanceof ViolationError && error.type === 'RATE_LIMIT_EXCEEDED') {
+ *     const retryAfter = error.metadata?.retryAfter;
+ *     // Handle rate limiting...
+ *   }
+ * }
+ * ```
+ */
 export declare class ViolationError<T extends string = string> extends Error {
+    /** The specific type/category of the violation */
     readonly type: T;
+    /** Additional structured data about the violation */
     readonly metadata: Record<string, any> | null;
+    /**
+     * The error name, formatted as ViolationError<TYPE>
+     * This helps with error identification in logs and stack traces
+     */
     readonly name: `ViolationError<${T}>`;
     constructor({ type, message, metadata }: ViolationErrorParam<T>);
 }

package/dist/errors.js

@@ -16,6 +16,38 @@ var __extends = (this && this.__extends) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ViolationError = void 0;
+/**
+ * ViolationError represents errors that require explicit handling in the system.
+ * These are distinct from recoverable errors that can be automatically handled
+ * by workflow logic. The explicit handling may be required for severe
+ * violation of service contracts or explict retry handling
+ *
+ * Common violation scenarios include:
+ * - Rate limit exceeded on external API calls
+ * - Contract violations (invalid input/output)
+ * - Configuration errors
+ * - Permission/authorization failures
+ *
+ * @example
+ * ```typescript
+ * // Creating a rate limit violation
+ * throw new ViolationError({
+ *   type: 'RATE_LIMIT_EXCEEDED',
+ *   message: 'API rate limit reached, retry after 60 seconds',
+ *   metadata: { retryAfter: 60 }
+ * });
+ *
+ * // Handling violations
+ * try {
+ *   await apiCall();
+ * } catch (error) {
+ *   if (error instanceof ViolationError && error.type === 'RATE_LIMIT_EXCEEDED') {
+ *     const retryAfter = error.metadata?.retryAfter;
+ *     // Handle rate limiting...
+ *   }
+ * }
+ * ```
+ */
 var ViolationError = /** @class */ (function (_super) {
     __extends(ViolationError, _super);
     function ViolationError(_a) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-core",
-  "version": "2.2.4",
+  "version": "2.2.5",
   "description": "This core package contains all the core classes and components of the Arvo Event Driven System",
   "main": "dist/index.js",
   "scripts": {