arvo-core/dist/utils.d.ts

The core Arvo package which provides application tier core primitives and contract system for building production-grade event-driven application. Provides ArvoEvent (CloudEvents-compliant), ArvoContract for type-safe service interfaces, event factories, O

import type { VersionedArvoContract } from './ArvoContract/VersionedArvoContract';
import type ArvoEvent from './ArvoEvent';
import type { ArvoErrorType, ArvoSemanticVersion } from './types';
/**
 * Cleans a string by removing leading/trailing whitespace from each line,
 * removing empty lines, and joining the remaining lines with newline characters.
 *
 * @param s - The input string to be cleaned.
 * @returns A new string with cleaned content.
 *
 * @example
 * const input = "  Hello  \n  World  \n\n  ";
 * const cleaned = cleanString(input);
 * console.log(cleaned); // Output: "Hello\nWorld"
 */
export declare function cleanString(s: string): string;
/**
 * Validates if a given string is a properly encoded URI.
 *
 * This function checks if the input string remains unchanged after being
 * decoded and then re-encoded, which indicates that it's a valid URI.
 *
 * @param value - The string to be validated as a URI.
 * @returns A boolean indicating whether the input is a valid URI (true) or not (false).
 *
 * @example
 * validateURI("https://example.com"); // Returns true
 * validateURI("https://example.com/path with spaces"); // Returns false
 * validateURI("https://example.com/path%20with%20spaces"); // Returns true
 */
export declare const validateURI: (value: string) => boolean;
/**
 * Creates an RFC 3339 compliant timestamp string with an optional UTC offset.
 *
 * @param offsetHours - The number of hours to offset from UTC. Positive values
 *                      represent hours ahead of UTC, negative values represent
 *                      hours behind UTC. Defaults to 0 (UTC).
 * @returns A string representing the current date and time in RFC 3339 format
 *          with the specified UTC offset.
 *
 * @example
 * // Returns current time in UTC
 * createTimestamp();
 *
 * @example
 * // Returns current time with +2 hours offset
 * createTimestamp(2);
 *
 * @example
 * // Returns current time with -5 hours offset
 * createTimestamp(-5);
 */
export declare const createTimestamp: (offsetHours?: number) => string;
/**
 * Parse semantic version string into its numeric components
 * @param version Semantic version string (e.g. "1.2.3")
 * @returns Object containing major, minor, and patch numbers
 */
type VersionComponents = {
    major: number;
    minor: number;
    patch: number;
};
export declare function parseSemanticVersion(version: ArvoSemanticVersion): VersionComponents;
/**
 * Compares two semantic versions according to semver rules
 * Returns:
 * - Positive number if version1 > version2
 * - Negative number if version1 < version2
 * - 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 {
    static build<TUri extends string, TVersion extends ArvoSemanticVersion>(uri: TUri, version: TVersion): `${TUri}/${TVersion}`;
    /**
     * 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<T extends VersionedArvoContract<any, any>>(contract: T): `${T["uri"]}/${T["version"]}`;
    /**
     * Creates dataschema string with wildcard version.
     * @param contract Versioned contract
     * @returns `{contract.uri}/{WildCardArvoSemanticVersion}`
     */
    static createWithWildCardVersion<T extends VersionedArvoContract<any, any>>(contract: T): `${T["uri"]}/0.0.0`;
    /**
     * 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;
    /**
     * Validates if a given ArvoEvent or dataschema string represents a valid dataschema.
     * A valid dataschema must:
     * - Follow the format {uri}/{version}
     * - Have a valid semantic version component
     * - Contain a non-empty URI
     *
     * @param data - ArvoEvent object or dataschema string to validate
     * @returns boolean - True if dataschema is valid, false otherwise
     */
    static isValid(data: ArvoEvent | string): boolean;
}
/**
 * Creates a standardized ArvoError payload from an Error object. This utility
 * ensures consistent error reporting across the event system by extracting and
 * structuring key error information.
 *
 * @param error - The source Error object to convert
 * @returns ArvoErrorType - The standardized error payload
 */
export declare const createArvoError: (error: Error) => ArvoErrorType;
export {};