arvo-core 2.0.3 → 2.0.4

package/dist/ArvoContract/VersionedArvoContract.d.ts

@@ -0,0 +1,39 @@
+import ArvoContract from '.';
+import { ArvoErrorSchema } from '../schema';
+import { ArvoSemanticVersion } from '../types';
+/**
+ * Represents a version-specific view of an ArvoContract, providing a structured way to access
+ * all contract specifications for a particular semantic version. This type ensures type-safe
+ * access to version-specific schemas and event types.
+ *
+ * @template TContract - The base ArvoContract type to extract version-specific information from
+ * @template TVersion - The specific semantic version of the contract to extract
+ *
+ * @property uri - The URI identifying the contract
+ * @property version - The specific semantic version being represented
+ * @property description - Optional description of the contract version
+ * @property accepts - Specification for accepted events in this version
+ * @property accepts.type - The event type this version accepts
+ * @property accepts.schema - Zod schema for validating accepted events
+ * @property systemError - System error event specification
+ * @property systemError.type - System error event type (sys.[type].error)
+ * @property systemError.schema - Zod schema for system error events
+ * @property emits - Record of emittable event types and their Zod schemas
+ *
+ * @see {@link ArvoContract} for the base contract class
+ * @see {@link ArvoContract.version} for the method to create a versioned view
+ */
+export type VersionedArvoContract<TContract extends ArvoContract, TVersion extends ArvoSemanticVersion & keyof TContract['versions']> = {
+    uri: TContract['uri'];
+    version: TVersion;
+    description: string | null;
+    accepts: {
+        type: TContract['type'];
+        schema: TContract['versions'][TVersion]['accepts'];
+    };
+    systemError: {
+        type: `sys.${TContract['type']}.error`;
+        schema: typeof ArvoErrorSchema;
+    };
+    emits: TContract['versions'][TVersion]['emits'];
+};

package/dist/ArvoContract/VersionedArvoContract.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/ArvoContract/index.d.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { ArvoContractJSONSchema, ArvoContractRecord, IArvoContract } from './types';
 import { ArvoErrorSchema } from '../schema';
 import { ArvoSemanticVersion } from '../types';
+import { VersionedArvoContract } from './VersionedArvoContract';
 /**
  * ArvoContract class represents a contract with defined input and output schemas.
  * It provides methods for validating inputs and outputs based on the contract's specifications.
@@ -32,6 +33,21 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * Gets the URI of the contract.
      */
     get uri(): TUri;
+    /**
+     * Creates a version-specific view of the contract, providing easy access to all
+     * schemas and specifications for a particular semantic version.
+     *
+     * @template V - The semantic version to create a view for, must be a valid version in the contract
+     *
+     * @param ver - The semantic version string (e.g., "1.0.0")
+     * @returns A VersionedArvoContract instance containing all specifications for the requested version
+     *
+     * The returned object provides a simpler, flatter structure compared to
+     * accessing version-specific information through the main contract methods.
+     *
+     * @see {@link VersionedArvoContract} for the structure of the returned object
+     */
+    version<V extends ArvoSemanticVersion & keyof TVersions>(ver: V): VersionedArvoContract<typeof this, V>;
     /**
      * Get the type of the event the handler
      * bound to the contract accepts
@@ -55,6 +71,25 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * contract bound handler.
      */
     emits<V extends ArvoSemanticVersion & keyof TVersions>(version: V): TVersions[V]['emits'];
+    /**
+     * Gets the system error event specification for this contract.
+     * System errors follow a standardized format to handle exceptional conditions
+     * and failures in a consistent way across all contracts.
+     *
+     * The error schema includes:
+     *   - errorName: The name/type of the error
+     *   - errorMessage: A descriptive message about what went wrong
+     *   - errorStack: Optional stack trace information (null if not available)
+     *
+     * System errors are special events that:
+     * - Are automatically prefixed with 'sys.' and suffixed with '.error'
+     * - Use a standardized schema across all contracts
+     * - Can capture error details, messages, and stack traces
+     * - Are version-independent (work the same across all contract versions)
+     *
+     * @see {@link ArvoErrorSchema} for the detailed error schema definition
+     * @see {@link ArvoContractRecord} for the structure of the returned record
+     */
     get systemError(): ArvoContractRecord<`sys.${TType}.error`, typeof ArvoErrorSchema>;
     /**
      * Validates the contract bound handler's input/ accept event against the
@@ -90,11 +125,7 @@ export default class ArvoContract<TUri extends string = string, TType extends st
      * This method provides a way to represent the contract's structure and validation rules
      * in a format that conforms to the JSON Schema specification.
      *
-     * @returns An object representing the contract in JSON Schema format, including:
-     *   - uri: The contract's URI
-     *   - description: The contract's description (if available)
-     *   - accepts: An object containing the accepted input type and its JSON Schema representation
-     *   - emits: An array of objects, each containing an emitted event type and its JSON Schema representation
+     * @returns An object representing the contract in JSON Schema format:
      */
     toJsonSchema(): ArvoContractJSONSchema;
 }

package/dist/ArvoContract/index.js

@@ -46,6 +46,33 @@ var ArvoContract = /** @class */ (function () {
         enumerable: false,
         configurable: true
     });
+    /**
+     * Creates a version-specific view of the contract, providing easy access to all
+     * schemas and specifications for a particular semantic version.
+     *
+     * @template V - The semantic version to create a view for, must be a valid version in the contract
+     *
+     * @param ver - The semantic version string (e.g., "1.0.0")
+     * @returns A VersionedArvoContract instance containing all specifications for the requested version
+     *
+     * The returned object provides a simpler, flatter structure compared to
+     * accessing version-specific information through the main contract methods.
+     *
+     * @see {@link VersionedArvoContract} for the structure of the returned object
+     */
+    ArvoContract.prototype.version = function (ver) {
+        return {
+            uri: this._uri,
+            description: this.description,
+            version: ver,
+            accepts: {
+                type: this._type,
+                schema: this._versions[ver].accepts,
+            },
+            systemError: this.systemError,
+            emits: this._versions[ver].emits,
+        };
+    };
     Object.defineProperty(ArvoContract.prototype, "type", {
         /**
          * Get the type of the event the handler
@@ -97,6 +124,25 @@ var ArvoContract = /** @class */ (function () {
         return __assign({}, this._versions[version].emits);
     };
     Object.defineProperty(ArvoContract.prototype, "systemError", {
+        /**
+         * Gets the system error event specification for this contract.
+         * System errors follow a standardized format to handle exceptional conditions
+         * and failures in a consistent way across all contracts.
+         *
+         * The error schema includes:
+         *   - errorName: The name/type of the error
+         *   - errorMessage: A descriptive message about what went wrong
+         *   - errorStack: Optional stack trace information (null if not available)
+         *
+         * System errors are special events that:
+         * - Are automatically prefixed with 'sys.' and suffixed with '.error'
+         * - Use a standardized schema across all contracts
+         * - Can capture error details, messages, and stack traces
+         * - Are version-independent (work the same across all contract versions)
+         *
+         * @see {@link ArvoErrorSchema} for the detailed error schema definition
+         * @see {@link ArvoContractRecord} for the structure of the returned record
+         */
         get: function () {
             return {
                 type: "sys.".concat(this._type, ".error"),
@@ -159,11 +205,7 @@ var ArvoContract = /** @class */ (function () {
      * This method provides a way to represent the contract's structure and validation rules
      * in a format that conforms to the JSON Schema specification.
      *
-     * @returns An object representing the contract in JSON Schema format, including:
-     *   - uri: The contract's URI
-     *   - description: The contract's description (if available)
-     *   - accepts: An object containing the accepted input type and its JSON Schema representation
-     *   - emits: An array of objects, each containing an emitted event type and its JSON Schema representation
+     * @returns An object representing the contract in JSON Schema format:
      */
     ArvoContract.prototype.toJsonSchema = function () {
         var _this = this;
@@ -178,6 +220,10 @@ var ArvoContract = /** @class */ (function () {
                         type: _this._type,
                         schema: (0, zod_to_json_schema_1.zodToJsonSchema)(contract.accepts),
                     },
+                    systemError: {
+                        type: _this.systemError.type,
+                        schema: (0, zod_to_json_schema_1.zodToJsonSchema)(_this.systemError.schema)
+                    },
                     emits: Object.entries(contract.emits).map(function (_a) {
                         var key = _a[0], value = _a[1];
                         return ({

package/dist/ArvoContract/types.d.ts

@@ -62,6 +62,13 @@ export type ArvoContractJSONSchema = {
             /** JSON Schema representation of the input validation schema */
             schema: ReturnType<typeof zodToJsonSchema>;
         };
+        /** The system error event */
+        systemError: {
+            /** The type of the event */
+            type: string;
+            /** The schema of the error */
+            schema: ReturnType<typeof zodToJsonSchema>;
+        };
         /** Array of schemas for events that can be emitted in this version */
         emits: {
             /** The type identifier for the emitted event */

package/dist/index.d.ts

@@ -21,10 +21,11 @@ import { ArvoOrchestrationSubjectContentSchema } from './ArvoOrchestrationSubjec
 import { ArvoOrchestrationSubjectContent } from './ArvoOrchestrationSubject/type';
 import ArvoEventHttp from './ArvoEventHttp';
 import { ArvoEventHttpConfig } from './ArvoEventHttp/types';
-import { InferArvoContract, InferArvoEvent, ArvoSemanticVersion, ArvoErrorType } from './types';
+import { InferArvoContract, InferArvoEvent, ArvoSemanticVersion, ArvoErrorType, InferVersionedArvoContract } from './types';
 import { createArvoOrchestratorContract } from './ArvoOrchestratorContract';
 import { ICreateArvoOrchestratorContract, ArvoOrchestratorContract } from './ArvoOrchestratorContract/types';
 import { ArvoOrchestratorEventTypeGen } from './ArvoOrchestratorContract/typegen';
+import { VersionedArvoContract } from './ArvoContract/VersionedArvoContract';
 /**
  * Collection of Zod schemas for validating various aspects of Arvo events.
  * @property {z.ZodObject} CloudEventContextSchema - Schema for core CloudEvent properties.
@@ -99,4 +100,4 @@ declare const ArvoEventSchema: {
         parentSubject$$: string | null;
     }>;
 };
-export { ArvoEventHttpConfig, ArvoEventHttp, 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, InferArvoContract, createArvoOrchestratorContract, ICreateArvoOrchestratorContract, ArvoOrchestratorEventTypeGen, ExecutionOpenTelemetryConfiguration, parseEventDataSchema, ArvoOrchestrationSubjectContentSchema, ArvoSemanticVersionSchema, ArvoErrorSchema, ArvoErrorType, compareSemanticVersions, parseSemanticVersion, createSimpleArvoContract, ArvoOrchestratorContract, };
+export { ArvoEventHttpConfig, ArvoEventHttp, 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, InferArvoContract, createArvoOrchestratorContract, ICreateArvoOrchestratorContract, ArvoOrchestratorEventTypeGen, ExecutionOpenTelemetryConfiguration, parseEventDataSchema, ArvoOrchestrationSubjectContentSchema, ArvoSemanticVersionSchema, ArvoErrorSchema, ArvoErrorType, compareSemanticVersions, parseSemanticVersion, createSimpleArvoContract, ArvoOrchestratorContract, VersionedArvoContract, InferVersionedArvoContract, };

package/dist/types.d.ts

@@ -3,6 +3,7 @@ import ArvoContract from './ArvoContract';
 import ArvoEvent from './ArvoEvent';
 import { ArvoExtension, OpenTelemetryExtension } from './ArvoEvent/types';
 import { ArvoErrorSchema } from './schema';
+import { VersionedArvoContract } from './ArvoContract/VersionedArvoContract';
 /**
  * Represents the version of Arvo components following Semantic Versioning (SemVer).
  *
@@ -152,4 +153,11 @@ export type InferArvoContract<T extends ArvoContract<string, string, Record<Arvo
     systemError: InferArvoEvent<ArvoEvent<InferZodSchema<T['systemError']['schema']>, {}, T['systemError']['type']>>;
 } : never;
 export type ArvoErrorType = z.infer<typeof ArvoErrorSchema>;
+export type InferVersionedArvoContract<TVersion extends VersionedArvoContract<ArvoContract, ArvoSemanticVersion>> = {
+    accepts: InferArvoEvent<ArvoEvent<InferZodSchema<TVersion['accepts']['schema']>, {}, TVersion['accepts']['type']>>;
+    systemError: InferArvoEvent<ArvoEvent<InferZodSchema<TVersion['systemError']['schema']>, {}, TVersion['systemError']['type']>>;
+    emits: {
+        [K in string & keyof TVersion['emits']]: InferArvoEvent<ArvoEvent<InferZodSchema<TVersion['emits'][K]>, {}, K>>;
+    };
+};
 export {};

package/package.json

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