arvo-core 2.0.9 → 2.1.0

package/dist/types.d.ts

@@ -1,192 +1,72 @@
 import { z } from 'zod';
-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).
- *
- * Format:
- * MAJOR.MINOR.PATCH where each component is a non-negative integer
- *
- * Restrictions:
- * Must not contain semicolons (;)
- *
- * @example
- * ```typescript
- * const version: ArvoSemanticVersion = "1.0.0";
- * const preRelease: ArvoSemanticVersion = "0.5.2";
- * const major: ArvoSemanticVersion = "2.0.0";
- * ```
+ * Represents a semantic version string following the SemVer format (MAJOR.MINOR.PATCH).
  */
 export type ArvoSemanticVersion = `${number}.${number}.${number}`;
 /**
- * A type utility that infers the structure of an ArvoEvent.
- *
- * @template TData - The type of the event payload
- * @template TExtension - Additional extension properties for the event
- * @template TType - The literal type string identifying the event
- *
- * @property id - Unique identifier for the event (UUID v4 recommended)
- * @property source - Identifier for the context where the event occurred
- * @property specversion - CloudEvents specification version
- * @property type - Event type identifier
- * @property subject - Event subject in the producer's context
- * @property datacontenttype - MIME type of the event payload
- * @property dataschema - URI reference to the event's JSON schema
- * @property data - The actual event payload
- * @property time - ISO 8601 timestamp of event occurrence
+ * Infers the complete structure of an ArvoEvent by combining base CloudEvents fields,
+ * Arvo-specific extensions, OpenTelemetry extensions, and custom extensions.
  *
  * @example
  * ```typescript
- * type UserCreatedEvent = InferArvoEvent<ArvoEvent<
+ * type UserCreatedEvent = InferArvoEvent<ArvoEvent
  *   { userId: string; email: string },
  *   { region: string },
  *   'user.created'
  * >>;
- *
- * // Results in:
- * // {
- * //   id: string;
- * //   source: string;
- * //   specversion: string;
- * //   type: 'user.created';
- * //   subject: string;
- * //   datacontenttype: string;
- * //   dataschema: string | null;
- * //   data: { userId: string; email: string };
- * //   time: string;
- * //   region: string;
- * //   // ... plus ArvoExtension & OpenTelemetryExtension properties
- * // }
  * ```
  */
-export type InferArvoEvent<T> = T extends ArvoEvent<infer TData, infer TExtension, infer TType> ? {
-    /** Unique identifier of the event */
+export type InferArvoEvent<TEvent extends ArvoEvent<any, any, any>> = {
     id: string;
-    /** Identifies the context in which an event happened */
     source: string;
-    /** The version of the CloudEvents specification */
     specversion: string;
-    /** Describes the type of event related to the originating occurrence */
-    type: TType;
-    /** Describes the subject of the event in the context of the event producer */
+    type: TEvent['type'];
     subject: string;
-    /** Content type of the data value */
     datacontenttype: string;
-    /** A link to the schema that the data adheres to */
     dataschema: string | null;
-    /** Event payload */
-    data: TData;
-    /** Timestamp of when the occurrence happened */
+    data: TEvent['data'];
     time: string;
-} & ArvoExtension & OpenTelemetryExtension & TExtension : never;
-type InferZodSchema<T> = T extends z.ZodTypeAny ? z.infer<T> : never;
+} & ArvoExtension & OpenTelemetryExtension & TEvent['extensions'];
 /**
- * A comprehensive type utility that infers the complete structure of an ArvoContract,
- * including versioned event types, accepted events, and emitted events.
- *
- * @template T - The ArvoContract type to infer from
- *
- * @property uri - Unique identifier for the contract
- * @property type - The event type this contract handles
- * @property versions - Version-specific contract definitions
- * @property versions[version].accepts - Events this contract version can handle
- * @property versions[version].emits - Events this contract version can produce
- * @property systemError - System error event definition for this contract
- *
- * @example
- * ```typescript
- * const userContract = new ArvoContract(
- *   'user-service',
- *   'user.operation',
- *   {
- *     '1.0.0': {
- *       accepts: z.object({ userId: z.string() }),
- *       emits: {
- *         'user.created': z.object({ userId: z.string(), timestamp: z.string() }),
- *         'user.failed': z.object({ error: z.string() })
- *       }
- *     }
- *   }
- * );
- *
- * type UserContractType = InferArvoContract<typeof userContract>;
- * // Results in:
- * // {
- * //   uri: 'user-service';
- * //   type: 'user.operation';
- * //   versions: {
- * //     '1.0.0': {
- * //       accepts: { ... inferred input event type ... };
- * //       emits: {
- * //         'user.created': { ... inferred output event type ... };
- * //         'user.failed': { ... inferred error event type ... };
- * //       }
- * //     }
- * //   };
- * //   systemError: { ... inferred system error event type ... };
- * // }
- * ```
+ * Utility type to infer the TypeScript type from a Zod schema.
  */
-export type InferArvoContract<T extends ArvoContract<string, string, Record<ArvoSemanticVersion, {
-    accepts: z.ZodTypeAny;
-    emits: Record<string, z.ZodTypeAny>;
-}>>> = T extends ArvoContract<infer TUri, infer TType, infer TVersion> ? {
-    uri: TUri;
-    type: TType;
-    versions: {
-        [V in ArvoSemanticVersion & keyof TVersion]: {
-            accepts: InferArvoEvent<ArvoEvent<InferZodSchema<TVersion[V]['accepts']>, {}, TType>>;
-            emits: {
-                [K in keyof TVersion[V]['emits']]: InferArvoEvent<ArvoEvent<InferZodSchema<TVersion[V]['emits'][K]>, {}, K & string>>;
-            };
-        };
-    };
-    systemError: InferArvoEvent<ArvoEvent<InferZodSchema<T['systemError']['schema']>, {}, T['systemError']['type']>>;
-} : never;
+type InferZodSchema<T extends z.ZodTypeAny> = z.infer<T>;
 /**
- * Represents the structure of an Arvo system error.
- * This type is inferred from the ArvoErrorSchema and provides
- * the standard error format used across all Arvo contracts.
- *
- * @property errorName - The classification or type of the error
- * @property errorMessage - A human-readable description of what went wrong
- * @property errorStack - Optional stack trace for debugging (null if not available)
- *
- * @example
- * ```typescript
- * const error: ArvoErrorType = {
- *   errorName: 'ValidationError',
- *   errorMessage: 'Invalid input format',
- *   errorStack: 'Error: Invalid input format\n    at validate (/app.js:10)'
- * };
- * ```
+ * Represents the structure of an Arvo system error, inferred from the ArvoErrorSchema.
+ * Provides the standard error format used across all Arvo contracts.
  *
  * @see {@link ArvoErrorSchema} for the underlying Zod schema definition
  */
 export type ArvoErrorType = z.infer<typeof ArvoErrorSchema>;
 /**
- * A type utility that infers the complete event structure from a versioned Arvo contract.
- * This type extracts and transforms all event types, schemas, and error definitions
- * from a specific version of a contract into their fully resolved event forms.
- *
- * @template TVersion - The versioned contract to infer from, must extend VersionedArvoContract
+ * Infers the complete contract structure from a versioned Arvo contract.
+ * This provides type-safe access to all events, schemas, and metadata defined in a contract.
  *
- * @property accepts - The fully resolved accept event type for this version
- * @property systemError - The fully resolved system error event type
- * @property emits - Record of all fully resolved emit event types
+ * @remarks
+ * The inferred contract includes:
+ * - `accepts`: Events the contract can receive
+ * - `systemError`: Standard error events
+ * - `emitMap`: Dictionary of all possible emit events
+ * - `emits`: Array type containing all possible emit events
+ * - `metadata`: Contract metadata
  *
  * @see {@link VersionedArvoContract} for the input contract structure
  * @see {@link InferArvoEvent} for the event inference utility
  * @see {@link ArvoEvent} for the base event structure
  */
-export type InferVersionedArvoContract<TVersion extends VersionedArvoContract<ArvoContract, ArvoSemanticVersion>> = {
+export type InferVersionedArvoContract<TVersion extends VersionedArvoContract<any, any, any>> = {
     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>>;
+    emitMap: {
+        [K in string & keyof TVersion['emitMap']]: InferArvoEvent<ArvoEvent<InferZodSchema<TVersion['emitMap'][K]>, {}, K>>;
     };
+    emits: Array<{
+        [K in string & keyof TVersion['emitMap']]: InferArvoEvent<ArvoEvent<InferZodSchema<TVersion['emitMap'][K]>, {}, K>>;
+    }[string & keyof TVersion['emitMap']]>;
+    metadata: TVersion['metadata'];
 };
 export {};

package/dist/utils.d.ts

@@ -1,3 +1,6 @@
+import ArvoContract from './ArvoContract';
+import { VersionedArvoContract } from './ArvoContract/VersionedArvoContract';
+import ArvoEvent from './ArvoEvent';
 import { ArvoSemanticVersion } from './types';
 /**
  * Cleans a string by removing leading/trailing whitespace from each line,
@@ -68,4 +71,49 @@ export declare function parseSemanticVersion(version: ArvoSemanticVersion): Vers
  * - 0 if version1 === version2
  */
 export declare function compareSemanticVersions(version1: ArvoSemanticVersion, version2: ArvoSemanticVersion): number;
+/**
+ * Manages event dataschema strings for versioned contracts.
+ * Handles creation and parsing of dataschema identifiers.
+ */
+export declare class EventDataschemaUtil {
+    /**
+     * Creates a dataschema string from a versioned contract.
+     * Format: `{contract.uri}/{contract.version}`
+     *
+     * @param contract - Versioned contract instance
+     * @returns Formatted dataschema string
+     *
+     * @example
+     * ```typescript
+     * const schema = EventDataschema.create(versionedContract);
+     * // Returns: "my-contract/1.0.0"
+     * ```
+     */
+    static create(contract: VersionedArvoContract<ArvoContract, ArvoSemanticVersion>): string;
+    /**
+     * Creates dataschema string with wildcard version.
+     * @param contract Versioned contract
+     * @returns `{contract.uri}/{WildCardArvoSemanticVersion}`
+     */
+    static createWithWildCardVersion(contract: VersionedArvoContract<ArvoContract, ArvoSemanticVersion>): string;
+    /**
+     * Extracts URI and version from dataschema string.
+     *
+     * @param data - Event object or dataschema string
+     * @returns Parsed URI and version, or null if invalid
+     *
+     * @example
+     * ```typescript
+     * const result = EventDataschema.parse("my-contract/1.0.0");
+     * // Returns: { uri: "my-contract", version: "1.0.0" }
+     *
+     * const invalid = EventDataschema.parse("invalid-schema");
+     * // Returns: null
+     * ```
+     */
+    static parse(data: ArvoEvent | string): {
+        uri: string;
+        version: ArvoSemanticVersion;
+    } | null;
+}
 export {};

package/dist/utils.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTimestamp = exports.validateURI = void 0;
+exports.EventDataschemaUtil = exports.createTimestamp = exports.validateURI = void 0;
 exports.cleanString = cleanString;
 exports.parseSemanticVersion = parseSemanticVersion;
 exports.compareSemanticVersions = compareSemanticVersions;
+var WildCardArvoSemanticVersion_1 = require("./ArvoContract/WildCardArvoSemanticVersion");
+var OpenTelemetry_1 = require("./OpenTelemetry");
+var schema_1 = require("./schema");
 /**
  * Cleans a string by removing leading/trailing whitespace from each line,
  * removing empty lines, and joining the remaining lines with newline characters.
@@ -110,3 +113,69 @@ function compareSemanticVersions(version1, version2) {
     }
     return v1.patch - v2.patch;
 }
+/**
+ * Manages event dataschema strings for versioned contracts.
+ * Handles creation and parsing of dataschema identifiers.
+ */
+var EventDataschemaUtil = /** @class */ (function () {
+    function EventDataschemaUtil() {
+    }
+    /**
+     * Creates a dataschema string from a versioned contract.
+     * Format: `{contract.uri}/{contract.version}`
+     *
+     * @param contract - Versioned contract instance
+     * @returns Formatted dataschema string
+     *
+     * @example
+     * ```typescript
+     * const schema = EventDataschema.create(versionedContract);
+     * // Returns: "my-contract/1.0.0"
+     * ```
+     */
+    EventDataschemaUtil.create = function (contract) {
+        return "".concat(contract.uri, "/").concat(contract.version);
+    };
+    /**
+     * Creates dataschema string with wildcard version.
+     * @param contract Versioned contract
+     * @returns `{contract.uri}/{WildCardArvoSemanticVersion}`
+     */
+    EventDataschemaUtil.createWithWildCardVersion = function (contract) {
+        return "".concat(contract.uri, "/").concat(WildCardArvoSemanticVersion_1.WildCardArvoSemanticVersion);
+    };
+    /**
+     * Extracts URI and version from dataschema string.
+     *
+     * @param data - Event object or dataschema string
+     * @returns Parsed URI and version, or null if invalid
+     *
+     * @example
+     * ```typescript
+     * const result = EventDataschema.parse("my-contract/1.0.0");
+     * // Returns: { uri: "my-contract", version: "1.0.0" }
+     *
+     * const invalid = EventDataschema.parse("invalid-schema");
+     * // Returns: null
+     * ```
+     */
+    EventDataschemaUtil.parse = function (data) {
+        var _a;
+        try {
+            var dataschema = typeof data === 'string' ? data : ((_a = data.dataschema) !== null && _a !== void 0 ? _a : '');
+            var items = dataschema.split('/');
+            var version = schema_1.ArvoSemanticVersionSchema.parse(items.pop());
+            var uri = items.join('/');
+            return { uri: uri, version: version };
+        }
+        catch (e) {
+            (0, OpenTelemetry_1.logToSpan)({
+                level: 'ERROR',
+                message: "Unable to parse the event dataschema: ".concat(e.message),
+            });
+            return null;
+        }
+    };
+    return EventDataschemaUtil;
+}());
+exports.EventDataschemaUtil = EventDataschemaUtil;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-core",
-  "version": "2.0.9",
+  "version": "2.1.0",
   "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/VersionedArvoContract.d.ts

@@ -1,39 +0,0 @@
-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'];
-};