arvo-core 2.2.3 → 2.2.5

package/dist/errors.d.ts

@@ -0,0 +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

@@ -0,0 +1,63 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+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) {
+        var type = _a.type, message = _a.message, metadata = _a.metadata;
+        var _this = _super.call(this, "ViolationError<".concat(type, "> ").concat(message)) || this;
+        _this.type = type;
+        _this.name = "ViolationError<".concat(_this.type, ">");
+        _this.metadata = metadata !== null && metadata !== void 0 ? metadata : null;
+        return _this;
+    }
+    return ViolationError;
+}(Error));
+exports.ViolationError = ViolationError;

package/dist/index.d.ts

@@ -28,7 +28,7 @@ import { isWildCardArvoSematicVersion, WildCardArvoSemanticVersion } from './Arv
 import { createSimpleArvoContract } from './ArvoContract/SimpleArvoContract';
 import { SimpleArvoContract } from './ArvoContract/SimpleArvoContract/types';
 import { ArvoOrchestratorEventFactory } from './ArvoEventFactory/Orchestrator';
-import { ArvoContractViolationError } from './ArvoContract/errors';
+import { ViolationError, ViolationErrorParam } from './errors';
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.
@@ -103,4 +103,4 @@ declare const ArvoEventSchema: {
         parentSubject$$: string | null;
     }>;
 };
-export { ArvoEvent, createArvoEvent, ArvoDataContentType, ArvoEventData, CloudEventExtension, ArvoEventSchema, CloudEventContext, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent, exceptionToSpan, logToSpan, OpenTelemetryHeaders, TelemetryLogLevel, OTelNull, validateURI, cleanString, ArvoContract, ArvoContractViolationError, createArvoContract, ArvoContractValidators, ArvoContractRecord, IArvoContract, ResolveArvoContractRecord, ArvoEventFactory, createArvoEventFactory, currentOpenTelemetryHeaders, OpenInference, OpenInferenceSpanKind, ArvoExecution, ArvoExecutionSpanKind, ArvoContractJSONSchema, ArvoOrchestrationSubject, ArvoOrchestrationSubjectContent, ArvoSemanticVersion, InferArvoEvent, createArvoOrchestratorContract, ICreateArvoOrchestratorContract, ArvoOrchestratorEventTypeGen, EventDataschemaUtil, ArvoOrchestrationSubjectContentSchema, ArvoSemanticVersionSchema, ArvoErrorSchema, ArvoErrorType, compareSemanticVersions, parseSemanticVersion, createSimpleArvoContract, ArvoOrchestratorContract, VersionedArvoContract, InferVersionedArvoContract, isWildCardArvoSematicVersion, WildCardArvoSemanticVersion, isValidArvoSemanticVersion, SimpleArvoContract, ArvoOrchestratorEventFactory, createArvoOrchestratorEventFactory, ArvoOpenTelemetry, };
+export { ArvoEvent, createArvoEvent, ArvoDataContentType, ArvoEventData, CloudEventExtension, ArvoEventSchema, CloudEventContext, ArvoExtension, OpenTelemetryExtension, CreateArvoEvent, exceptionToSpan, logToSpan, OpenTelemetryHeaders, TelemetryLogLevel, OTelNull, validateURI, cleanString, ArvoContract, createArvoContract, ArvoContractValidators, ArvoContractRecord, IArvoContract, ResolveArvoContractRecord, ArvoEventFactory, createArvoEventFactory, currentOpenTelemetryHeaders, OpenInference, OpenInferenceSpanKind, ArvoExecution, ArvoExecutionSpanKind, ArvoContractJSONSchema, ArvoOrchestrationSubject, ArvoOrchestrationSubjectContent, ArvoSemanticVersion, InferArvoEvent, createArvoOrchestratorContract, ICreateArvoOrchestratorContract, ArvoOrchestratorEventTypeGen, EventDataschemaUtil, ArvoOrchestrationSubjectContentSchema, ArvoSemanticVersionSchema, ArvoErrorSchema, ArvoErrorType, compareSemanticVersions, parseSemanticVersion, createSimpleArvoContract, ArvoOrchestratorContract, VersionedArvoContract, InferVersionedArvoContract, isWildCardArvoSematicVersion, WildCardArvoSemanticVersion, isValidArvoSemanticVersion, SimpleArvoContract, ArvoOrchestratorEventFactory, createArvoOrchestratorEventFactory, ArvoOpenTelemetry, ViolationError, ViolationErrorParam, };

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ArvoOpenTelemetry = exports.createArvoOrchestratorEventFactory = exports.ArvoOrchestratorEventFactory = exports.isValidArvoSemanticVersion = exports.WildCardArvoSemanticVersion = exports.isWildCardArvoSematicVersion = exports.VersionedArvoContract = exports.createSimpleArvoContract = exports.parseSemanticVersion = exports.compareSemanticVersions = exports.ArvoErrorSchema = exports.ArvoSemanticVersionSchema = exports.ArvoOrchestrationSubjectContentSchema = exports.EventDataschemaUtil = exports.ArvoOrchestratorEventTypeGen = exports.createArvoOrchestratorContract = exports.ArvoOrchestrationSubject = exports.ArvoExecutionSpanKind = exports.ArvoExecution = exports.OpenInferenceSpanKind = exports.OpenInference = exports.currentOpenTelemetryHeaders = exports.createArvoEventFactory = exports.ArvoEventFactory = exports.ArvoContractValidators = exports.createArvoContract = exports.ArvoContractViolationError = exports.ArvoContract = exports.cleanString = exports.validateURI = exports.OTelNull = exports.logToSpan = exports.exceptionToSpan = exports.ArvoEventSchema = exports.ArvoDataContentType = exports.createArvoEvent = exports.ArvoEvent = void 0;
+exports.ViolationError = exports.ArvoOpenTelemetry = exports.createArvoOrchestratorEventFactory = exports.ArvoOrchestratorEventFactory = exports.isValidArvoSemanticVersion = exports.WildCardArvoSemanticVersion = exports.isWildCardArvoSematicVersion = exports.VersionedArvoContract = exports.createSimpleArvoContract = exports.parseSemanticVersion = exports.compareSemanticVersions = exports.ArvoErrorSchema = exports.ArvoSemanticVersionSchema = exports.ArvoOrchestrationSubjectContentSchema = exports.EventDataschemaUtil = exports.ArvoOrchestratorEventTypeGen = exports.createArvoOrchestratorContract = exports.ArvoOrchestrationSubject = exports.ArvoExecutionSpanKind = exports.ArvoExecution = exports.OpenInferenceSpanKind = exports.OpenInference = exports.currentOpenTelemetryHeaders = exports.createArvoEventFactory = exports.ArvoEventFactory = exports.ArvoContractValidators = exports.createArvoContract = exports.ArvoContract = exports.cleanString = exports.validateURI = exports.OTelNull = exports.logToSpan = exports.exceptionToSpan = exports.ArvoEventSchema = exports.ArvoDataContentType = exports.createArvoEvent = exports.ArvoEvent = void 0;
 var ArvoEvent_1 = __importDefault(require("./ArvoEvent"));
 exports.ArvoEvent = ArvoEvent_1.default;
 var schema_1 = require("./ArvoEvent/schema");
@@ -63,8 +63,8 @@ var SimpleArvoContract_1 = require("./ArvoContract/SimpleArvoContract");
 Object.defineProperty(exports, "createSimpleArvoContract", { enumerable: true, get: function () { return SimpleArvoContract_1.createSimpleArvoContract; } });
 var Orchestrator_1 = require("./ArvoEventFactory/Orchestrator");
 Object.defineProperty(exports, "ArvoOrchestratorEventFactory", { enumerable: true, get: function () { return Orchestrator_1.ArvoOrchestratorEventFactory; } });
-var errors_1 = require("./ArvoContract/errors");
-Object.defineProperty(exports, "ArvoContractViolationError", { enumerable: true, get: function () { return errors_1.ArvoContractViolationError; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "ViolationError", { enumerable: true, get: function () { return errors_1.ViolationError; } });
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-core",
-  "version": "2.2.3",
+  "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": {

package/dist/ArvoContract/errors.d.ts

@@ -1,10 +0,0 @@
-/**
- * Custom error class representing a violation of an ArvoContract.
- */
-export declare class ArvoContractViolationError extends Error {
-    /**
-     * Creates an instance of ArvoContractViolationError.
-     * @param {string} [message='ArvoContract violated'] - The error message. Default is 'ArvoContract violated'.
-     */
-    constructor(message?: string);
-}

package/dist/ArvoContract/errors.js

@@ -1,36 +0,0 @@
-"use strict";
-var __extends = (this && this.__extends) || (function () {
-    var extendStatics = function (d, b) {
-        extendStatics = Object.setPrototypeOf ||
-            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
-            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
-        return extendStatics(d, b);
-    };
-    return function (d, b) {
-        if (typeof b !== "function" && b !== null)
-            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
-        extendStatics(d, b);
-        function __() { this.constructor = d; }
-        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ArvoContractViolationError = void 0;
-/**
- * Custom error class representing a violation of an ArvoContract.
- */
-var ArvoContractViolationError = /** @class */ (function (_super) {
-    __extends(ArvoContractViolationError, _super);
-    /**
-     * Creates an instance of ArvoContractViolationError.
-     * @param {string} [message='ArvoContract violated'] - The error message. Default is 'ArvoContract violated'.
-     */
-    function ArvoContractViolationError(message) {
-        if (message === void 0) { message = 'ArvoContract violated'; }
-        var _this = _super.call(this, message) || this;
-        _this.name = 'ArvoContractViolationError';
-        return _this;
-    }
-    return ArvoContractViolationError;
-}(Error));
-exports.ArvoContractViolationError = ArvoContractViolationError;