arvo-core 2.0.10 → 2.1.0

package/CHANGELOG.md

@@ -76,3 +76,7 @@
 
 - Remove potential security bug of reading the file system
 
+## [2.0.4] - 2024-12-01
+
+- Refactored code implementation architecture for better maintainability
+

package/dist/ArvoContract/SimpleArvoContract/index.d.ts

@@ -0,0 +1,55 @@
+import { ArvoSemanticVersion } from '../../types';
+import { z } from 'zod';
+import { SimpleArvoContract } from './types';
+/**
+ * Creates an ArvoContract with standardized naming conventions and a simplified event pattern.
+ * Use this to create contracts with one emit type only.
+ *
+ * @param param - Contract configuration
+ * @param param.uri - Contract identifier URI
+ * @param param.type - Base event type (will be prefixed with "com.")
+ * @param param.versions - Version-specific schema definitions
+ * @param param.metadata - Optional metadata for the contract
+ * @param param.description - Optional contract description
+ *
+ * @returns ArvoContract with standardized type formatting and metadata
+ *
+ * @throws {Error} If any of the validations in {@link ArvoContract} or {@link createArvoContract} fail
+ *
+ * @example
+ * ```typescript
+ * const contract = createSimpleArvoContract({
+ *   uri: 'api.example/contracts/user',
+ *   type: 'user.create',
+ *   description: 'User creation contract',
+ *   versions: {
+ *     '1.0.0': {
+ *       accepts: z.object({
+ *         name: z.string(),
+ *         email: z.string().email()
+ *       }),
+ *       emits: z.object({
+ *         userId: z.string(),
+ *         timestamp: z.date()
+ *       })
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @remarks
+ * Provides a simplified contract creation pattern with standardized conventions:
+ * - Automatically prefixes accept types with "com."
+ * - Creates a single emit type with "evt." prefix and ".success" suffix
+ * - Adds standard metadata identifying it as a SimpleArvoContract
+ */
+export declare const createSimpleArvoContract: <TUri extends string, TType extends string, TVersions extends Record<ArvoSemanticVersion, {
+    accepts: z.ZodTypeAny;
+    emits: z.ZodTypeAny;
+}>, TMetaData extends Record<string, any>>(param: {
+    uri: TUri;
+    type: TType;
+    versions: TVersions;
+    metadata?: TMetaData;
+    description?: string;
+}) => SimpleArvoContract<TUri, TType, TVersions, TMetaData>;

package/dist/ArvoContract/SimpleArvoContract/index.js

@@ -0,0 +1,81 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSimpleArvoContract = void 0;
+var helpers_1 = require("../helpers");
+/**
+ * Creates an ArvoContract with standardized naming conventions and a simplified event pattern.
+ * Use this to create contracts with one emit type only.
+ *
+ * @param param - Contract configuration
+ * @param param.uri - Contract identifier URI
+ * @param param.type - Base event type (will be prefixed with "com.")
+ * @param param.versions - Version-specific schema definitions
+ * @param param.metadata - Optional metadata for the contract
+ * @param param.description - Optional contract description
+ *
+ * @returns ArvoContract with standardized type formatting and metadata
+ *
+ * @throws {Error} If any of the validations in {@link ArvoContract} or {@link createArvoContract} fail
+ *
+ * @example
+ * ```typescript
+ * const contract = createSimpleArvoContract({
+ *   uri: 'api.example/contracts/user',
+ *   type: 'user.create',
+ *   description: 'User creation contract',
+ *   versions: {
+ *     '1.0.0': {
+ *       accepts: z.object({
+ *         name: z.string(),
+ *         email: z.string().email()
+ *       }),
+ *       emits: z.object({
+ *         userId: z.string(),
+ *         timestamp: z.date()
+ *       })
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @remarks
+ * Provides a simplified contract creation pattern with standardized conventions:
+ * - Automatically prefixes accept types with "com."
+ * - Creates a single emit type with "evt." prefix and ".success" suffix
+ * - Adds standard metadata identifying it as a SimpleArvoContract
+ */
+var createSimpleArvoContract = function (param) {
+    var _a;
+    var mergedMetadata = __assign(__assign({}, ((_a = param.metadata) !== null && _a !== void 0 ? _a : {})), { contractType: 'SimpleArvoContract', rootType: param.type });
+    return (0, helpers_1.createArvoContract)({
+        uri: param.uri,
+        type: "com.".concat(param.type),
+        description: param.description,
+        metadata: mergedMetadata,
+        versions: Object.fromEntries(Object.entries(param.versions).map(function (_a) {
+            var _b;
+            var version = _a[0], contract = _a[1];
+            return [
+                version,
+                {
+                    accepts: contract.accepts,
+                    emits: (_b = {},
+                        _b["evt.".concat(param.type, ".success")] = contract.emits,
+                        _b),
+                },
+            ];
+        })),
+    });
+};
+exports.createSimpleArvoContract = createSimpleArvoContract;

package/dist/ArvoContract/SimpleArvoContract/types.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import ArvoContract from '..';
+import { ArvoSemanticVersion } from '../../types';
+export type SimpleArvoContract<TUri extends string = string, TType extends string = string, TVersions extends Record<ArvoSemanticVersion, {
+    accepts: z.ZodTypeAny;
+    emits: z.ZodTypeAny;
+}> = Record<ArvoSemanticVersion, {
+    accepts: z.ZodTypeAny;
+    emits: z.ZodTypeAny;
+}>, TMetaData extends Record<string, any> = Record<string, any>> = ArvoContract<TUri, `com.${TType}`, {
+    [V in ArvoSemanticVersion & keyof TVersions]: {
+        accepts: TVersions[V]['accepts'];
+        emits: {
+            [K in `evt.${TType}.succes`]: TVersions[V]['emits'];
+        };
+    };
+}, TMetaData & {
+    contractType: 'SimpleArvoContract';
+    rootType: TType;
+}>;

package/dist/ArvoContract/VersionedArvoContract/index.d.ts

@@ -0,0 +1,32 @@
+import ArvoContract from '..';
+import { ArvoSemanticVersion } from '../../types';
+import { ArvoContractRecord } from '../types';
+import { IVersionedArvoContract, VersionedArvoContractJSONSchema } from './types';
+/**
+ * Implements a version-specific view of an ArvoContract with type-safe schema validation
+ * and JSON Schema generation capabilities.
+ */
+export declare class VersionedArvoContract<TContract extends ArvoContract, TVersion extends ArvoSemanticVersion & keyof TContract['versions'], TMetaData extends Record<string, any> = Record<string, any>> {
+    private readonly _uri;
+    private readonly _version;
+    private readonly _description;
+    private readonly _accepts;
+    private readonly _emitMap;
+    private readonly _emits;
+    private readonly _metadata;
+    private readonly _systemError;
+    get uri(): TContract["uri"];
+    get version(): TVersion;
+    get description(): string | null;
+    get accepts(): ArvoContractRecord<TContract["type"], TContract["versions"][TVersion]["accepts"]>;
+    get emitMap(): TContract["versions"][TVersion]["emits"];
+    get metadata(): TMetaData;
+    get systemError(): TContract["systemError"];
+    get emits(): { [K in keyof TContract["versions"][TVersion]["emits"] & string]: ArvoContractRecord<K, TContract["versions"][TVersion]["emits"][K]>; }[keyof TContract["versions"][TVersion]["emits"] & string][];
+    constructor(param: IVersionedArvoContract<TContract, TVersion, TMetaData>);
+    /**
+     * Converts the contract to JSON Schema format
+     * @returns Contract specification in JSON Schema format for documentation/serialization
+     */
+    toJsonSchema(): VersionedArvoContractJSONSchema;
+}

package/dist/ArvoContract/VersionedArvoContract/index.js

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VersionedArvoContract = void 0;
+var zod_to_json_schema_1 = __importDefault(require("zod-to-json-schema"));
+var utils_1 = require("./utils");
+var OpenTelemetry_1 = require("../../OpenTelemetry");
+/**
+ * Implements a version-specific view of an ArvoContract with type-safe schema validation
+ * and JSON Schema generation capabilities.
+ */
+var VersionedArvoContract = /** @class */ (function () {
+    function VersionedArvoContract(param) {
+        this._uri = param.uri;
+        this._version = param.version;
+        this._description = param.description;
+        this._accepts = param.accepts;
+        this._emitMap = param.emits;
+        this._emits = (0, utils_1.transformEmitsToArray)(this.emitMap);
+        this._metadata = param.metadata;
+        this._systemError = param.systemError;
+    }
+    Object.defineProperty(VersionedArvoContract.prototype, "uri", {
+        get: function () {
+            return this._uri;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(VersionedArvoContract.prototype, "version", {
+        get: function () {
+            return this._version;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(VersionedArvoContract.prototype, "description", {
+        get: function () {
+            return this._description;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(VersionedArvoContract.prototype, "accepts", {
+        get: function () {
+            return this._accepts;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(VersionedArvoContract.prototype, "emitMap", {
+        get: function () {
+            return this._emitMap;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(VersionedArvoContract.prototype, "metadata", {
+        get: function () {
+            return this._metadata;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(VersionedArvoContract.prototype, "systemError", {
+        get: function () {
+            return this._systemError;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(VersionedArvoContract.prototype, "emits", {
+        get: function () {
+            return this._emits;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * Converts the contract to JSON Schema format
+     * @returns Contract specification in JSON Schema format for documentation/serialization
+     */
+    VersionedArvoContract.prototype.toJsonSchema = function () {
+        try {
+            return {
+                uri: this._uri,
+                description: this._description,
+                version: this._version,
+                metadata: this._metadata,
+                accepts: {
+                    type: this._accepts.type,
+                    schema: (0, zod_to_json_schema_1.default)(this._accepts.schema),
+                },
+                systemError: {
+                    type: this._systemError.type,
+                    schema: (0, zod_to_json_schema_1.default)(this._systemError.schema),
+                },
+                emits: Object.entries(this._emitMap).map(function (_a) {
+                    var key = _a[0], value = _a[1];
+                    return ({
+                        type: key,
+                        schema: (0, zod_to_json_schema_1.default)(value),
+                    });
+                }),
+            };
+        }
+        catch (e) {
+            var errorMessage = "VersionedArvoContract.toJsonSchema failed: ".concat(e.message);
+            (0, OpenTelemetry_1.logToSpan)({
+                level: 'ERROR',
+                message: errorMessage,
+            });
+            throw new Error(errorMessage);
+        }
+    };
+    return VersionedArvoContract;
+}());
+exports.VersionedArvoContract = VersionedArvoContract;

package/dist/ArvoContract/VersionedArvoContract/types.d.ts

@@ -0,0 +1,44 @@
+import zodToJsonSchema from 'zod-to-json-schema';
+import ArvoContract from '..';
+import { ArvoSemanticVersion } from '../../types';
+import { ArvoContractRecord } from '../types';
+/**
+ * Represents a version-specific view of an ArvoContract, providing type-safe access
+ * to contract specifications for a particular semantic version. This interface acts as
+ * a bridge between the base contract and its versioned implementation.
+ */
+export interface IVersionedArvoContract<TContract extends ArvoContract, TVersion extends ArvoSemanticVersion & keyof TContract['versions'], TMetaData extends Record<string, any> = Record<string, any>> {
+    uri: TContract['uri'];
+    version: TVersion;
+    description: string | null;
+    accepts: ArvoContractRecord<TContract['type'], TContract['versions'][TVersion]['accepts']>;
+    systemError: TContract['systemError'];
+    emits: TContract['versions'][TVersion]['emits'];
+    metadata: TMetaData;
+}
+/**
+ * Represents the standardized JSON Schema structure for an Arvo contract record.
+ * This type is used when converting Zod schemas to JSON Schema format for documentation
+ * and external system integration.
+ */
+export type ArvoContractRecordJsonSchema = {
+    type: string;
+    schema: ReturnType<typeof zodToJsonSchema>;
+};
+/**
+ * Defines the complete JSON Schema representation of a versioned Arvo contract.
+ * This type provides a serializable format suitable for documentation generation,
+ * API specifications, and cross-system compatibility.
+ *
+ * The structure follows JSON Schema conventions while maintaining all essential
+ * contract information including versioning, event specifications, and validation rules.
+ */
+export type VersionedArvoContractJSONSchema = {
+    uri: string;
+    description: string | null;
+    version: ArvoSemanticVersion;
+    accepts: ArvoContractRecordJsonSchema;
+    systemError: ArvoContractRecordJsonSchema;
+    emits: ArvoContractRecordJsonSchema[];
+    metadata: Record<string, any> | null;
+};

package/dist/ArvoContract/VersionedArvoContract/types.js

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

package/dist/ArvoContract/VersionedArvoContract/utils.d.ts

@@ -0,0 +1,4 @@
+import ArvoContract from '..';
+import { ArvoSemanticVersion } from '../../types';
+import { ArvoContractRecord } from '../types';
+export declare const transformEmitsToArray: <T extends ArvoContract, V extends ArvoSemanticVersion>(emitMap: T["versions"][V]["emits"]) => Array<{ [K in keyof T["versions"][V]["emits"] & string]: ArvoContractRecord<K, T["versions"][V]["emits"][K]>; }[keyof T["versions"][V]["emits"] & string]>;

package/dist/ArvoContract/VersionedArvoContract/utils.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformEmitsToArray = void 0;
+var transformEmitsToArray = function (emitMap) {
+    return Object.entries(emitMap).map(function (_a) {
+        var type = _a[0], schema = _a[1];
+        return ({
+            type: type,
+            schema: schema,
+        });
+    });
+};
+exports.transformEmitsToArray = transformEmitsToArray;

package/dist/ArvoContract/WildCardArvoSemanticVersion.d.ts

@@ -0,0 +1,14 @@
+import { ArvoSemanticVersion } from '../types';
+/**
+ * Special semantic version used as a wildcard matcher.
+ * Represents version '0.0.0' which is reserved for system use.
+ */
+export declare const WildCardArvoSemanticVersion: ArvoSemanticVersion & '0.0.0';
+/**
+ * Checks if a version is the special wildcard version.
+ * Validates that the input is both a valid semantic version and matches the wildcard value.
+ *
+ * @param version - Semantic version to check
+ * @returns True if version is the wildcard version, false otherwise
+ */
+export declare const isWildCardArvoSematicVersion: (version: ArvoSemanticVersion) => boolean;

package/dist/ArvoContract/WildCardArvoSemanticVersion.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWildCardArvoSematicVersion = exports.WildCardArvoSemanticVersion = void 0;
+var schema_1 = require("../schema");
+/**
+ * Special semantic version used as a wildcard matcher.
+ * Represents version '0.0.0' which is reserved for system use.
+ */
+exports.WildCardArvoSemanticVersion = '0.0.0';
+/**
+ * Checks if a version is the special wildcard version.
+ * Validates that the input is both a valid semantic version and matches the wildcard value.
+ *
+ * @param version - Semantic version to check
+ * @returns True if version is the wildcard version, false otherwise
+ */
+var isWildCardArvoSematicVersion = function (version) {
+    return (0, schema_1.isValidArvoSemanticVersion)(version) &&
+        version === exports.WildCardArvoSemanticVersion;
+};
+exports.isWildCardArvoSematicVersion = isWildCardArvoSematicVersion;

package/dist/ArvoContract/helpers.d.ts

@@ -1,29 +1,28 @@
-import { IArvoContract } from './types';
 import ArvoContract from '.';
 import { ArvoSemanticVersion } from '../types';
 import { z } from 'zod';
 /**
- * Infers the ArvoContract type from a given IArvoContract interface.
+ * Creates a validated ArvoContract instance with full control over event types and schemas.
  *
- * @template T - The IArvoContract interface to infer from
- */
-type InferArvoContract<T> = T extends IArvoContract<infer Uri, infer Type, infer Versions> ? ArvoContract<Uri, Type, Versions> : never;
-/**
- * Creates and validates an ArvoContract instance from a contract specification.
+ * @param contract - Contract specification object
  *
- * @template TContract - The contract specification type, must extend IArvoContract
- * @param contract - The contract specification object containing URI, type, and versioned schemas
- * @throws {Error} If any event type uses the reserved orchestrator prefix
- * @throws {Error} If URI or event types fail validation
- * @returns A properly typed ArvoContract instance
+ * @throws {Error} If the event types contain reserved prefix ({@link ArvoOrchestratorEventTypeGen})
+ * @throws {Error} If any of the ArvoContract's internal validations fail. See {@link ArvoContract}
+ *
+ * @returns A fully typed and validated ArvoContract instance
  *
  * @example
  * ```typescript
  * const contract = createArvoContract({
  *   uri: 'com.example.contract',
  *   type: 'input.event',
+ *   description: "Some example contract",
+ *   metadata: {
+ *     owner: 'team-a',
+ *     priority: 'high'
+ *   },
  *   versions: {
- *     '0.0.1': {
+ *     '1.0.0': {
  *       accepts: z.object({ data: z.string() }),
  *       emits: {
  *         'output.event': z.object({ result: z.number() })
@@ -33,100 +32,13 @@ type InferArvoContract<T> = T extends IArvoContract<infer Uri, infer Type, infer
  * });
  * ```
  */
-export declare const createArvoContract: <const TContract extends IArvoContract>(contract: TContract, isOrchestrationContract?: boolean) => InferArvoContract<TContract>;
-/**
- * Creates a simplified ArvoContract with standardized type prefixes and emit patterns.
- * This is a convenience function that automatically formats event types according to conventions:
- * - Accept types are prefixed with "com."
- * - Emit types are prefixed with "evt." and suffixed with ".success"
- *
- * @template TUri - The URI type for the contract
- * @template TType - The base type name (without prefixes) for the contract
- * @template TVersions - Record of versions containing accept and emit schemas
- *
- * @param param - The configuration object for creating the contract
- * @param param.uri - The URI identifying the contract
- * @param param.type - The base type name (will be prefixed with "com.")
- * @param param.versions - Version-specific schema definitions
- * @param param.versions[version].accepts - Zod schema for validating incoming events
- * @param param.versions[version].emits - Zod schema for validating outgoing events
- *
- * @returns An ArvoContract instance with standardized type formatting:
- *          - Accept type will be "com.[type]"
- *          - Emit type will be "evt.[type].success"
- *
- * @example
- * ```typescript
- * const contract = createSimpleArvoContract({
- *   uri: 'example.com/contracts/processor',
- *   type: 'document.process',
- *   versions: {
- *     '1.0.0': {
- *       accepts: z.object({
- *         documentId: z.string(),
- *         options: z.object({ format: z.string() })
- *       }),
- *       emits: z.object({
- *         processedDocument: z.string(),
- *         metadata: z.object({ size: z.number() })
- *       })
- *     }
- *   }
- * });
- *
- * // Results in a contract where:
- * // - Accept type is "com.document.process"
- * // - Emit type is "evt.document.process.success"
- * ```
- *
- * @example
- * ```typescript
- * // Multiple versions example
- * const contract = createSimpleArvoContract({
- *   uri: 'api.example/contracts/user',
- *   type: 'user.create',
- *   versions: {
- *     '1.0.0': {
- *       accepts: z.object({ name: z.string() }),
- *       emits: z.object({ id: z.string() })
- *     },
- *     '2.0.0': {
- *       accepts: z.object({
- *         name: z.string(),
- *         email: z.string().email()
- *       }),
- *       emits: z.object({
- *         id: z.string(),
- *         created: z.date()
- *       })
- *     }
- *   }
- * });
- * ```
- *
- * @remarks
- * This function simplifies contract creation by:
- * 1. Automatically prefixing accept types with "com."
- * 2. Creating a single emit type prefixed with "evt." and suffixed with ".success"
- * 3. Maintaining type safety and schema validation
- *
- * Use this when you have a simple contract pattern with:
- * - A single accept type
- * - A single success emit type
- * - Standard type naming conventions
- *
- * For more complex contracts with multiple emit types or custom type naming,
- * use {@link createArvoContract} instead.
- */
-export declare const createSimpleArvoContract: <TUri extends string, TType extends string, TVersions extends Record<ArvoSemanticVersion, {
+export declare const createArvoContract: <TUri extends string, TType extends string, TVersions extends Record<ArvoSemanticVersion, {
     accepts: z.ZodTypeAny;
-    emits: z.ZodTypeAny;
-}>>(param: {
+    emits: Record<string, z.ZodTypeAny>;
+}>, TMetaData extends Record<string, any> = Record<string, any>>(contract: {
     uri: TUri;
     type: TType;
     versions: TVersions;
-}) => ArvoContract<TUri, `com.${TType}`, { [V in ArvoSemanticVersion & keyof TVersions]: {
-    accepts: TVersions[V]["accepts"];
-    emits: { [K in `evt.${TType}.succes`]: TVersions[V]["emits"]; };
-}; }>;
-export {};
+    metadata?: TMetaData;
+    description?: string;
+}) => ArvoContract<TUri, TType, TVersions, TMetaData>;