@contractspec/lib.contracts 1.49.0 → 1.51.0

package/dist/versioning/refs.d.ts

@@ -0,0 +1,179 @@
+//#region src/versioning/refs.d.ts
+/**
+ * Base reference types for ContractSpec versioning.
+ *
+ * Provides canonical reference types for linking between specs.
+ * Domain-specific refs (OpRef, EventRef, etc.) should alias these
+ * base types for consistency and maintainability.
+ *
+ * @module versioning/refs
+ */
+/**
+ * Base reference type for versioned specs.
+ * Used to reference any spec by its key and version.
+ *
+ * @example
+ * ```typescript
+ * const opRef: VersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
+ * ```
+ */
+interface VersionedSpecRef {
+  /** Unique key identifying the spec (e.g., "auth.login", "user.created"). */
+  key: string;
+  /** Semantic version of the spec (e.g., "1.0.0", "2.1.0"). */
+  version: string;
+}
+/**
+ * Base reference type for specs with optional version.
+ * When version is omitted, typically refers to the latest version.
+ *
+ * @example
+ * ```typescript
+ * // Reference to latest version
+ * const latestRef: OptionalVersionedSpecRef = { key: 'auth.login' };
+ *
+ * // Reference to specific version
+ * const specificRef: OptionalVersionedSpecRef = { key: 'auth.login', version: '1.0.0' };
+ * ```
+ */
+interface OptionalVersionedSpecRef {
+  /** Unique key identifying the spec. */
+  key: string;
+  /** Optional semantic version. When omitted, refers to the latest version. */
+  version?: string;
+}
+/**
+ * Base reference type for unversioned spec keys.
+ * Used when only the key is needed without version information.
+ *
+ * @example
+ * ```typescript
+ * const featureRef: SpecKeyRef = { key: 'premium-features' };
+ * ```
+ */
+interface SpecKeyRef {
+  /** Unique key identifying the spec. */
+  key: string;
+}
+/**
+ * Checks if a value is a valid VersionedSpecRef.
+ *
+ * @param ref - The value to check
+ * @returns True if the value has both key and version as strings
+ *
+ * @example
+ * ```typescript
+ * const ref = { key: 'auth.login', version: '1.0.0' };
+ * if (isVersionedSpecRef(ref)) {
+ *   console.log(`Spec: ${ref.key}@${ref.version}`);
+ * }
+ * ```
+ */
+declare function isVersionedSpecRef(ref: unknown): ref is VersionedSpecRef;
+/**
+ * Checks if a value is a valid OptionalVersionedSpecRef.
+ *
+ * @param ref - The value to check
+ * @returns True if the value has a key string and optional version string
+ *
+ * @example
+ * ```typescript
+ * const ref = { key: 'auth.login' };
+ * if (isOptionalVersionedSpecRef(ref)) {
+ *   console.log(`Spec: ${ref.key}${ref.version ? `@${ref.version}` : ''}`);
+ * }
+ * ```
+ */
+declare function isOptionalVersionedSpecRef(ref: unknown): ref is OptionalVersionedSpecRef;
+/**
+ * Checks if a value is a valid SpecKeyRef.
+ *
+ * @param ref - The value to check
+ * @returns True if the value has a key string
+ *
+ * @example
+ * ```typescript
+ * const ref = { key: 'premium-features' };
+ * if (isSpecKeyRef(ref)) {
+ *   console.log(`Feature: ${ref.key}`);
+ * }
+ * ```
+ */
+declare function isSpecKeyRef(ref: unknown): ref is SpecKeyRef;
+/**
+ * Creates a versioned spec reference.
+ *
+ * @param key - The spec key (e.g., "auth.login")
+ * @param version - The semantic version (e.g., "1.0.0")
+ * @returns A VersionedSpecRef object
+ * @throws {Error} If key or version is empty
+ *
+ * @example
+ * ```typescript
+ * const ref = createVersionedRef('auth.login', '1.0.0');
+ * // { key: 'auth.login', version: '1.0.0' }
+ * ```
+ */
+declare function createVersionedRef(key: string, version: string): VersionedSpecRef;
+/**
+ * Creates an optional versioned spec reference.
+ *
+ * @param key - The spec key (e.g., "auth.login")
+ * @param version - Optional semantic version
+ * @returns An OptionalVersionedSpecRef object
+ * @throws {Error} If key is empty
+ *
+ * @example
+ * ```typescript
+ * // Reference to latest version
+ * const latestRef = createOptionalRef('auth.login');
+ * // { key: 'auth.login' }
+ *
+ * // Reference to specific version
+ * const specificRef = createOptionalRef('auth.login', '1.0.0');
+ * // { key: 'auth.login', version: '1.0.0' }
+ * ```
+ */
+declare function createOptionalRef(key: string, version?: string): OptionalVersionedSpecRef;
+/**
+ * Creates a spec key reference.
+ *
+ * @param key - The spec key (e.g., "premium-features")
+ * @returns A SpecKeyRef object
+ * @throws {Error} If key is empty
+ *
+ * @example
+ * ```typescript
+ * const ref = createKeyRef('premium-features');
+ * // { key: 'premium-features' }
+ * ```
+ */
+declare function createKeyRef(key: string): SpecKeyRef;
+/**
+ * Formats a versioned ref as a string key.
+ *
+ * @param ref - The versioned spec reference
+ * @returns A string in the format "key.vversion"
+ *
+ * @example
+ * ```typescript
+ * const str = formatVersionedRefKey({ key: 'auth.login', version: '1.0.0' });
+ * // "auth.login.v1.0.0"
+ * ```
+ */
+declare function formatVersionedRefKey(ref: VersionedSpecRef): string;
+/**
+ * Parses a versioned ref string back into a ref object.
+ *
+ * @param refKey - A string in the format "key.vversion"
+ * @returns A VersionedSpecRef or undefined if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const ref = parseVersionedRefKey('auth.login.v1.0.0');
+ * // { key: 'auth.login', version: '1.0.0' }
+ * ```
+ */
+declare function parseVersionedRefKey(refKey: string): VersionedSpecRef | undefined;
+//#endregion
+export { OptionalVersionedSpecRef, SpecKeyRef, VersionedSpecRef, createKeyRef, createOptionalRef, createVersionedRef, formatVersionedRefKey, isOptionalVersionedSpecRef, isSpecKeyRef, isVersionedSpecRef, parseVersionedRefKey };

package/dist/versioning/refs.js

@@ -0,0 +1,161 @@
+//#region src/versioning/refs.ts
+/**
+* Checks if a value is a valid VersionedSpecRef.
+*
+* @param ref - The value to check
+* @returns True if the value has both key and version as strings
+*
+* @example
+* ```typescript
+* const ref = { key: 'auth.login', version: '1.0.0' };
+* if (isVersionedSpecRef(ref)) {
+*   console.log(`Spec: ${ref.key}@${ref.version}`);
+* }
+* ```
+*/
+function isVersionedSpecRef(ref) {
+	return typeof ref === "object" && ref !== null && "key" in ref && typeof ref.key === "string" && ref.key.length > 0 && "version" in ref && typeof ref.version === "string" && ref.version.length > 0;
+}
+/**
+* Checks if a value is a valid OptionalVersionedSpecRef.
+*
+* @param ref - The value to check
+* @returns True if the value has a key string and optional version string
+*
+* @example
+* ```typescript
+* const ref = { key: 'auth.login' };
+* if (isOptionalVersionedSpecRef(ref)) {
+*   console.log(`Spec: ${ref.key}${ref.version ? `@${ref.version}` : ''}`);
+* }
+* ```
+*/
+function isOptionalVersionedSpecRef(ref) {
+	if (typeof ref !== "object" || ref === null) return false;
+	if (!("key" in ref)) return false;
+	if (typeof ref.key !== "string" || ref.key.length === 0) return false;
+	if ("version" in ref && ref.version != null) return typeof ref.version === "string";
+	return true;
+}
+/**
+* Checks if a value is a valid SpecKeyRef.
+*
+* @param ref - The value to check
+* @returns True if the value has a key string
+*
+* @example
+* ```typescript
+* const ref = { key: 'premium-features' };
+* if (isSpecKeyRef(ref)) {
+*   console.log(`Feature: ${ref.key}`);
+* }
+* ```
+*/
+function isSpecKeyRef(ref) {
+	return typeof ref === "object" && ref !== null && "key" in ref && typeof ref.key === "string" && ref.key.length > 0;
+}
+/**
+* Creates a versioned spec reference.
+*
+* @param key - The spec key (e.g., "auth.login")
+* @param version - The semantic version (e.g., "1.0.0")
+* @returns A VersionedSpecRef object
+* @throws {Error} If key or version is empty
+*
+* @example
+* ```typescript
+* const ref = createVersionedRef('auth.login', '1.0.0');
+* // { key: 'auth.login', version: '1.0.0' }
+* ```
+*/
+function createVersionedRef(key, version) {
+	if (!key || key.trim().length === 0) throw new Error("Spec key cannot be empty");
+	if (!version || version.trim().length === 0) throw new Error("Spec version cannot be empty");
+	return {
+		key: key.trim(),
+		version: version.trim()
+	};
+}
+/**
+* Creates an optional versioned spec reference.
+*
+* @param key - The spec key (e.g., "auth.login")
+* @param version - Optional semantic version
+* @returns An OptionalVersionedSpecRef object
+* @throws {Error} If key is empty
+*
+* @example
+* ```typescript
+* // Reference to latest version
+* const latestRef = createOptionalRef('auth.login');
+* // { key: 'auth.login' }
+*
+* // Reference to specific version
+* const specificRef = createOptionalRef('auth.login', '1.0.0');
+* // { key: 'auth.login', version: '1.0.0' }
+* ```
+*/
+function createOptionalRef(key, version) {
+	if (!key || key.trim().length === 0) throw new Error("Spec key cannot be empty");
+	const ref = { key: key.trim() };
+	if (version != null && version.trim().length > 0) ref.version = version.trim();
+	return ref;
+}
+/**
+* Creates a spec key reference.
+*
+* @param key - The spec key (e.g., "premium-features")
+* @returns A SpecKeyRef object
+* @throws {Error} If key is empty
+*
+* @example
+* ```typescript
+* const ref = createKeyRef('premium-features');
+* // { key: 'premium-features' }
+* ```
+*/
+function createKeyRef(key) {
+	if (!key || key.trim().length === 0) throw new Error("Spec key cannot be empty");
+	return { key: key.trim() };
+}
+/**
+* Formats a versioned ref as a string key.
+*
+* @param ref - The versioned spec reference
+* @returns A string in the format "key.vversion"
+*
+* @example
+* ```typescript
+* const str = formatVersionedRefKey({ key: 'auth.login', version: '1.0.0' });
+* // "auth.login.v1.0.0"
+* ```
+*/
+function formatVersionedRefKey(ref) {
+	return `${ref.key}.v${ref.version}`;
+}
+/**
+* Parses a versioned ref string back into a ref object.
+*
+* @param refKey - A string in the format "key.vversion"
+* @returns A VersionedSpecRef or undefined if parsing fails
+*
+* @example
+* ```typescript
+* const ref = parseVersionedRefKey('auth.login.v1.0.0');
+* // { key: 'auth.login', version: '1.0.0' }
+* ```
+*/
+function parseVersionedRefKey(refKey) {
+	const match = refKey.match(/^(.+)\.v(\d+\.\d+\.\d+(?:-.+)?)$/);
+	if (!match) return void 0;
+	const key = match[1];
+	const version = match[2];
+	if (!key || !version) return void 0;
+	return {
+		key,
+		version
+	};
+}
+
+//#endregion
+export { createKeyRef, createOptionalRef, createVersionedRef, formatVersionedRefKey, isOptionalVersionedSpecRef, isSpecKeyRef, isVersionedSpecRef, parseVersionedRefKey };

package/dist/workflow/context.d.ts

@@ -0,0 +1,191 @@
+import { Step, WorkflowSpec } from "./spec.js";
+import { StepExecution, WorkflowState } from "./state.js";
+
+//#region src/workflow/context.d.ts
+
+/**
+ * Error thrown when a workflow operation fails.
+ */
+declare class WorkflowContextError extends Error {
+  readonly errorType: WorkflowContextErrorType;
+  readonly workflowId: string;
+  readonly details?: Record<string, unknown>;
+  constructor(type: WorkflowContextErrorType, workflowId: string, message: string, details?: Record<string, unknown>);
+}
+type WorkflowContextErrorType = 'invalid_transition' | 'workflow_completed' | 'workflow_failed' | 'step_not_found' | 'guard_rejected' | 'sla_violated';
+interface WorkflowTransitionResult {
+  success: boolean;
+  previousStep: string;
+  currentStep: string;
+  status: WorkflowState['status'];
+  error?: string;
+}
+interface AvailableTransition {
+  from: string;
+  to: string;
+  label?: string;
+  condition?: string;
+}
+interface SlaStatus {
+  key: string;
+  type: 'workflow' | 'step';
+  stepId?: string;
+  limitMs: number;
+  elapsedMs: number;
+  remainingMs: number;
+  violated: boolean;
+  percentUsed: number;
+}
+interface WorkflowEvent {
+  timestamp: Date;
+  type: 'step_started' | 'step_completed' | 'step_failed' | 'step_retried' | 'transition';
+  stepId?: string;
+  fromStep?: string;
+  toStep?: string;
+  input?: unknown;
+  output?: unknown;
+  error?: string;
+}
+/**
+ * Runtime context for interacting with a workflow instance.
+ *
+ * Provides a simplified interface over WorkflowRunner for common
+ * workflow operations like state access, transitions, and SLA tracking.
+ */
+interface WorkflowContext<TData = Record<string, unknown>> {
+  /** Unique workflow instance identifier. */
+  readonly workflowId: string;
+  /** Workflow spec key. */
+  readonly workflowKey: string;
+  /** Workflow spec version. */
+  readonly workflowVersion: string;
+  /** Current step identifier. */
+  readonly currentStep: string;
+  /** Current workflow status. */
+  readonly status: WorkflowState['status'];
+  /** Workflow data/state. */
+  readonly data: TData;
+  /** Execution history. */
+  readonly history: readonly StepExecution[];
+  /**
+   * Get the current workflow state.
+   * @returns Full workflow state object
+   */
+  getState(): WorkflowState;
+  /**
+   * Get a value from workflow data.
+   * @param key - Data key to retrieve
+   * @returns Value or undefined
+   */
+  getData<T = unknown>(key: string): T | undefined;
+  /**
+   * Check if workflow is in a terminal state.
+   * @returns True if completed, failed, or cancelled
+   */
+  isTerminal(): boolean;
+  /**
+   * Check if workflow is running.
+   * @returns True if status is 'running'
+   */
+  isRunning(): boolean;
+  /**
+   * Get the current step definition.
+   * @returns Step definition or undefined
+   */
+  getCurrentStepDef(): Step | undefined;
+  /**
+   * Get the retry count for a step.
+   * @param stepId - Step to check (defaults to current step)
+   * @returns Number of retry attempts
+   */
+  getRetryCount(stepId?: string): number;
+  /**
+   * Check if a transition to a target step is valid.
+   * @param toStepId - Target step identifier
+   * @returns True if transition is valid from current step
+   */
+  canTransition(toStepId: string): boolean;
+  /**
+   * Get all available transitions from current step.
+   * @returns Array of available transitions
+   */
+  getAvailableTransitions(): AvailableTransition[];
+  /**
+   * Check if the current step has any outgoing transitions.
+   * @returns True if there are outgoing transitions
+   */
+  hasNextStep(): boolean;
+  /**
+   * Get remaining time for an SLA constraint.
+   * @param slaKey - 'totalDuration' or step ID
+   * @returns Remaining milliseconds, or null if no SLA configured
+   */
+  getRemainingTime(slaKey: string): number | null;
+  /**
+   * Check if an SLA constraint has been violated.
+   * @param slaKey - 'totalDuration' or step ID
+   * @returns True if SLA has been violated
+   */
+  isSlaViolated(slaKey: string): boolean;
+  /**
+   * Get status of all SLA constraints.
+   * @returns Array of SLA statuses
+   */
+  getAllSlaStatuses(): SlaStatus[];
+  /**
+   * Check if compensation/rollback is available.
+   * @returns True if workflow has compensation strategy
+   */
+  hasCompensation(): boolean;
+  /**
+   * Get steps that have compensation handlers.
+   * @returns Array of step IDs with compensation
+   */
+  getCompensableSteps(): string[];
+  /**
+   * Convert execution history to workflow events.
+   * @returns Array of workflow events
+   */
+  getEvents(): WorkflowEvent[];
+}
+/**
+ * Creates a workflow context from state and spec.
+ *
+ * @param state - Current workflow state
+ * @param spec - Workflow specification
+ * @returns WorkflowContext for interacting with the workflow
+ *
+ * @example
+ * ```typescript
+ * const state = await runner.getState(workflowId);
+ * const spec = registry.get(state.workflowName, state.workflowVersion);
+ * const ctx = createWorkflowContext(state, spec);
+ *
+ * console.log('Current step:', ctx.currentStep);
+ * console.log('Available transitions:', ctx.getAvailableTransitions());
+ * ```
+ */
+declare function createWorkflowContext<TData = Record<string, unknown>>(state: WorkflowState, spec: WorkflowSpec): WorkflowContext<TData>;
+/**
+ * Calculate workflow progress as a percentage.
+ *
+ * @param ctx - Workflow context
+ * @returns Progress percentage (0-100)
+ */
+declare function calculateWorkflowProgress(ctx: WorkflowContext): number;
+/**
+ * Get the duration of a workflow in milliseconds.
+ *
+ * @param ctx - Workflow context
+ * @returns Duration in milliseconds
+ */
+declare function getWorkflowDuration(ctx: WorkflowContext): number;
+/**
+ * Get the average step duration in milliseconds.
+ *
+ * @param ctx - Workflow context
+ * @returns Average duration or 0 if no completed steps
+ */
+declare function getAverageStepDuration(ctx: WorkflowContext): number;
+//#endregion
+export { AvailableTransition, SlaStatus, WorkflowContext, WorkflowContextError, WorkflowContextErrorType, WorkflowEvent, WorkflowTransitionResult, calculateWorkflowProgress, createWorkflowContext, getAverageStepDuration, getWorkflowDuration };