UNPKG

nestjs-temporal-core

Version:

Complete NestJS integration for Temporal.io with auto-discovery, declarative scheduling, enhanced monitoring, and enterprise-ready features

915 lines (914 loc) 25.4 kB
export { RetryPolicy, Duration, SearchAttributes } from '@temporalio/common'; export { WorkflowHandle, Client, ConnectionOptions as TemporalConnectionOptions, } from '@temporalio/client'; export { Worker } from '@temporalio/worker'; import { Type } from '@nestjs/common'; import { ScheduleClient, ScheduleHandle } from '@temporalio/client'; import { NativeConnection, Worker } from '@temporalio/worker'; import { TypedSearchAttributes } from '@temporalio/common'; import { TLSConfig } from '@temporalio/common/lib/internal-non-workflow'; export interface ClientConnectionOptions { address: string; tls?: boolean | TLSConfig; metadata?: Record<string, string>; apiKey?: string; namespace?: string; } export type ConnectionOptions = import('@temporalio/client').ConnectionOptions; export interface RetryPolicyConfig { maximumAttempts: number; initialInterval: string; maximumInterval: string; backoffCoefficient: number; } export interface WorkerDefinition { taskQueue: string; workflowsPath?: string; workflowBundle?: Record<string, unknown>; activityClasses?: Array<Type<object>>; autoStart?: boolean; workerOptions?: WorkerCreateOptions; } export interface TemporalOptions extends LoggerConfig { connection?: { address: string; namespace?: string; tls?: boolean | TLSConfig; apiKey?: string; metadata?: Record<string, string>; }; taskQueue?: string; worker?: { workflowsPath?: string; workflowBundle?: Record<string, unknown>; activityClasses?: Array<Type<object>>; autoStart?: boolean; workerOptions?: WorkerCreateOptions; }; workers?: WorkerDefinition[]; autoRestart?: boolean; isGlobal?: boolean; allowConnectionFailure?: boolean; enableShutdownHooks?: boolean; shutdownTimeout?: number; } export interface WorkerCreateOptions { identity?: string; buildId?: string; useVersioning?: boolean; workerDeploymentOptions?: Record<string, unknown>; shutdownGraceTime?: string | number; shutdownForceTime?: string | number; dataConverter?: Record<string, unknown>; tuner?: Record<string, unknown>; maxConcurrentActivityTaskExecutions?: number; maxConcurrentLocalActivityExecutions?: number; maxConcurrentActivityTaskPolls?: number; enableNonLocalActivities?: boolean; maxActivitiesPerSecond?: number; maxTaskQueueActivitiesPerSecond?: number; maxConcurrentWorkflowTaskExecutions?: number; maxConcurrentWorkflowTaskPolls?: number; nonStickyToStickyPollRatio?: number; maxCachedWorkflows?: number; stickyQueueScheduleToStartTimeout?: string | number; workflowThreadPoolSize?: number; reuseV8Context?: boolean; maxHeartbeatThrottleInterval?: string | number; defaultHeartbeatThrottleInterval?: string | number; debugMode?: boolean; enableLoggingInReplay?: boolean; showStackTraceSources?: boolean; interceptors?: { activityInbound?: unknown[]; activity?: unknown[]; workflowModules?: string[]; }; sinks?: Record<string, unknown>; bundlerOptions?: Record<string, unknown>; enableSDKTracing?: boolean; enableOpenTelemetry?: boolean; } export interface WorkerModuleOptions { connection?: { address?: string; namespace?: string; tls?: boolean | object; apiKey?: string; metadata?: Record<string, string>; }; taskQueue?: string; workflowsPath?: string; workflowBundle?: Record<string, unknown>; activityClasses?: Array<Type<object>>; autoStart?: boolean; autoRestart?: boolean; allowWorkerFailure?: boolean; workerOptions?: WorkerCreateOptions; enableLogger?: boolean; logLevel?: LogLevel; } export type LogLevel = 'error' | 'warn' | 'info' | 'debug' | 'verbose'; export interface GlobalLoggerConfig extends LoggerConfig { appName?: string; formatter?: (level: string, message: string, context: string, timestamp: string) => string; logToFile?: boolean; logFilePath?: string; } export interface LoggerConfig { enableLogger?: boolean; logLevel?: LogLevel; } export interface TemporalOptionsFactory { createTemporalOptions(): Promise<TemporalOptions> | TemporalOptions; } export interface TemporalAsyncOptions { useExisting?: Type<TemporalOptionsFactory>; useClass?: Type<TemporalOptionsFactory>; useFactory?: (...args: unknown[]) => Promise<TemporalOptions> | TemporalOptions; inject?: Array<string | symbol | Type<unknown>>; imports?: Array<Type<unknown>>; isGlobal?: boolean; } export interface ActivityMethodMetadata { name: string; originalName: string; options?: Record<string, string | number | boolean | object>; handler: ActivityMethodHandler; } export interface ActivityMethodOptions { name?: string; timeout?: string | number; maxRetries?: number; } export interface ActivityMetadata { name?: string; options?: Record<string, string | number | boolean | object>; } export interface ActivityOptions { name?: string; } export interface DiscoveryStats { controllers: number; methods: number; signals: number; queries: number; workflows: number; childWorkflows: number; } export interface QueryMethodInfo { methodName: string; queryName: string; options: QueryOptions; handler: (...args: unknown[]) => unknown | Promise<unknown>; } export interface QueryOptions { name?: string; } export interface SignalMethodInfo { methodName: string; signalName: string; options?: Record<string, string | number | boolean | object>; handler: (...args: unknown[]) => unknown | Promise<unknown>; } export interface SignalOptions { name?: string; } export interface StartWorkflowOptions { taskQueue: string; workflowId?: string; signal?: { name: string; args?: unknown[]; }; [key: string]: unknown; } export interface SystemStatus { client: { available: boolean; healthy: boolean; }; worker: { available: boolean; status?: WorkerStatus; health?: string; }; discovery: DiscoveryStats; } export interface WorkerStatus { isInitialized: boolean; isRunning: boolean; isHealthy: boolean; taskQueue: string; namespace: string; workflowSource: 'bundle' | 'filesystem' | 'registered' | 'none'; activitiesCount: number; workflowsCount?: number; lastError?: string; startedAt?: Date; uptime?: number; } export interface MultipleWorkersInfo { workers: Map<string, WorkerStatus>; totalWorkers: number; runningWorkers: number; healthyWorkers: number; } export interface CreateWorkerResult { success: boolean; taskQueue: string; error?: Error; worker?: Worker; } export interface WorkerInstance { worker: Worker; taskQueue: string; namespace: string; isRunning: boolean; isInitialized: boolean; lastError: string | null; startedAt: Date | null; restartCount: number; activities: Map<string, Function>; workflowSource: 'bundle' | 'filesystem' | 'registered' | 'none'; } export interface SignalMethodMetadata { signalName: string; methodName: string; } export interface QueryMethodMetadata { queryName: string; methodName: string; } export interface ChildWorkflowMetadata { workflowType: string | Type<unknown>; options?: Record<string, string | number | boolean | object>; propertyKey: string | symbol; } export type ActivityMethodHandler = (...args: unknown[]) => Promise<unknown> | unknown; export type QueryMethodHandler = (...args: unknown[]) => unknown; export type SignalMethodHandler = (...args: unknown[]) => void | Promise<void>; export interface ActivityModuleOptions extends LoggerConfig { activityClasses?: Array<Type<unknown>>; timeout?: string | number; global?: boolean; } export interface ActivityInfo { className: string; instance: Record<string, unknown>; targetClass: Type<unknown>; methods: Array<{ name: string; methodName: string; options: ActivityMethodOptions; }>; totalMethods: number; } export interface ExtendedSignalMethodInfo { className: string; signalName: string; methodName: string; handler: (...args: unknown[]) => unknown | Promise<unknown>; instance: Record<string, unknown>; } export interface ExtendedQueryMethodInfo { className: string; queryName: string; methodName: string; handler: (...args: unknown[]) => unknown | Promise<unknown>; instance: Record<string, unknown>; options?: Record<string, string | number | boolean | object>; } export interface ChildWorkflowInfo { className: string; propertyKey: string | symbol; workflowType: Type<unknown>; options?: Record<string, string | number | boolean | object>; instance: Record<string, unknown>; } export type ActivityFunction = (...args: unknown[]) => unknown | Promise<unknown>; export interface ActivityMethodInfo { methodName: string; name: string; metadata: ActivityMethodOptions; } export interface ActivityContext { activityType: string; className?: string; methodName?: string; executionId?: string; timestamp?: Date; } export interface ScheduleSpec { intervals?: Array<{ every: string | number; }>; cronExpressions?: string[]; timezones?: string[]; startAt?: Date; endAt?: Date; jitter?: string | number; } export interface ScheduleAction { type: 'startWorkflow'; workflowType: string; args?: unknown[]; taskQueue: string; workflowId?: string; } export interface ScheduleCreateOptions { scheduleId: string; spec: ScheduleSpec; action: ScheduleAction; memo?: Record<string, string | number | boolean | object>; searchAttributes?: Record<string, string | number | boolean | object>; workflowType?: string; args?: unknown[]; taskQueue?: string; interval?: string | number; cron?: string; timezone?: string; overlapPolicy?: 'skip' | 'buffer_one' | 'buffer_all' | 'cancel_other' | 'terminate_other' | 'allow_all'; catchupWindow?: string | number; pauseOnFailure?: boolean; description?: string; paused?: boolean; limitedActions?: number; } export interface WorkflowStartOptions { workflowId?: string; taskQueue?: string; searchAttributes?: TypedSearchAttributes; memo?: Record<string, string | number | boolean | object>; workflowIdReusePolicy?: 'ALLOW_DUPLICATE' | 'ALLOW_DUPLICATE_FAILED_ONLY' | 'REJECT_DUPLICATE'; workflowExecutionTimeout?: string; workflowRunTimeout?: string; workflowTaskTimeout?: string; } export type HealthStatus = 'healthy' | 'unhealthy' | 'degraded'; export interface ServiceHealth { status: HealthStatus; details?: Record<string, string | number | boolean | object>; timestamp?: Date; } export interface ServiceStats { activities: { classes: number; methods: number; total: number; }; schedules: number; discoveries: DiscoveryStats; worker: WorkerStatus; client: ServiceHealth; } export type OverlapPolicy = 'skip' | 'buffer_one' | 'buffer_all' | 'cancel_other' | 'terminate_other' | 'allow_all'; export type TemporalOverlapPolicy = 'SKIP' | 'BUFFER_ONE' | 'BUFFER_ALL' | 'CANCEL_OTHER' | 'TERMINATE_OTHER' | 'ALLOW_ALL'; export interface MetadataInfo { [key: string]: string | number | boolean | object | null; } export type ActivityWrapper = (...args: unknown[]) => Promise<unknown>; export interface ProviderInstance { [key: string]: string | number | boolean | object | null | undefined; } export interface NestJSWrapper { instance?: Record<string, unknown>; metatype?: new (...args: unknown[]) => Record<string, unknown>; } export interface InstanceWithConstructor { constructor: new (...args: unknown[]) => Record<string, unknown>; } export interface DiscoveredActivity { name: string; className: string; method: ActivityMethodInfo | ActivityMethodHandler; instance: Record<string, unknown>; handler: ActivityMethodHandler; } export interface WorkflowSignalConfig { name: string; args?: unknown[]; } export type WorkflowHandleWithMetadata = import('@temporalio/client').WorkflowHandle & { handle: import('@temporalio/client').WorkflowHandle; }; export interface ClientServiceStatus { available: boolean; healthy: boolean; initialized: boolean; lastHealthCheck: Date | null; namespace: string; } export interface ClientHealthStatus { status: 'healthy' | 'unhealthy' | 'degraded'; } export interface GenericClient { workflow: { start: (type: string, options: Record<string, string | number | boolean | object>) => Promise<import('@temporalio/client').WorkflowHandle>; getHandle: (id: string, runId?: string) => import('@temporalio/client').WorkflowHandle; }; } export interface ScheduleDescription { spec: ScheduleSpec; action: ScheduleAction; policies: { overlap: TemporalOverlapPolicy; catchupWindow: number; pauseOnFailure: boolean; }; state: { paused: boolean; note?: string; remainingActions?: number; }; } export interface DiscoveryServiceStats { methods: number; activities: number; totalComponents: number; } export interface DiscoveryHealthStatus { isComplete: boolean; status: 'healthy' | 'degraded' | 'unhealthy'; discoveredItems?: { activities: number; }; lastDiscovery?: Date | null; discoveryDuration?: number | null; totalComponents?: number; } export interface DiscoveryServiceConfig { enableLogging: boolean; logLevel: LogLevel; activityClasses: Array<Type<unknown>>; } export interface ComponentDiscoveryResult { success: boolean; discoveredCount: number; errors: Array<{ component: string; error: string; }>; duration: number; } export interface ActivityMethodValidationResult { isValid: boolean; issues: string[]; warnings?: string[]; } export interface DiscoveryServiceOptions { enableLogger?: boolean; logLevel?: LogLevel; activityClasses?: Array<Type<unknown>>; validateOnDiscovery?: boolean; cacheResults?: boolean; } export interface WrapperProcessingResult { success: boolean; processedCount: number; errors: Array<{ component: string; error: string; }>; } export interface ActivityDiscoveryContext { className: string; instance: Record<string, unknown>; metatype: Type<unknown>; validationResult?: ActivityMethodValidationResult; } export interface ActivityMethodMetadataResult { name: string; originalName: string; methodName: string; className: string; options?: Record<string, unknown>; handler?: Function; } export interface ActivityMetadataExtractionResult { success: boolean; methods: Map<string, ActivityMethodMetadataResult>; errors: Array<{ method: string; error: string; }>; extractedCount: number; } export interface ActivityClassValidationResult { isValid: boolean; issues: string[]; warnings?: string[]; className?: string; methodCount?: number; } export interface MetadataValidationResult { isValid: boolean; missing: string[]; present: string[]; target: string; } export interface ActivityInfoResult { className: string; isActivity: boolean; activityName: string | null; methodNames: string[]; metadata: unknown; activityOptions: unknown; methodCount: number; } export interface CacheStatsResult { size: number; entries: string[]; message?: string; note?: string; hitRate?: number; missRate?: number; } export interface SignalMethodExtractionResult { success: boolean; methods: Record<string, string>; errors: Array<{ method: string; error: string; }>; } export interface QueryMethodExtractionResult { success: boolean; methods: Record<string, string>; errors: Array<{ method: string; error: string; }>; } export interface ChildWorkflowExtractionResult { success: boolean; workflows: Record<string, unknown>; errors: Array<{ workflow: string; error: string; }>; } export interface MetadataExtractionOptions { includeOptions?: boolean; validateMethods?: boolean; cacheResults?: boolean; strictMode?: boolean; } export interface ActivityMethodExtractionContext { instance: unknown; className: string; methodName: string; prototype: object; metadata: unknown; } export interface ScheduleCreationOptions { scheduleId: string; spec: ScheduleSpec; action: ScheduleAction; memo?: Record<string, unknown>; searchAttributes?: Record<string, unknown>; } export interface ScheduleCreationResult { success: boolean; scheduleId?: string; handle?: ScheduleHandle; error?: Error; } export interface ScheduleRetrievalResult { success: boolean; handle?: ScheduleHandle; error?: Error; } export interface ScheduleServiceStatus { available: boolean; healthy: boolean; schedulesSupported: boolean; initialized: boolean; } export interface ScheduleServiceHealth { status: 'healthy' | 'unhealthy' | 'degraded'; schedulesCount: number; isInitialized: boolean; details: Record<string, unknown>; lastError?: string; } export interface ScheduleServiceStats { total: number; active: number; inactive: number; errors: number; lastUpdated?: Date; } export interface ScheduleDiscoveryResult { success: boolean; discoveredCount: number; errors: Array<{ schedule: string; error: string; }>; duration: number; } export interface ScheduleRegistrationResult { success: boolean; scheduleId: string; handle?: ScheduleHandle; error?: Error; } export interface ScheduleMetadataValidationResult { isValid: boolean; issues: string[]; warnings?: string[]; scheduleId?: string; } export interface ScheduleClientInitResult { success: boolean; client?: ScheduleClient; error?: Error; source: 'existing' | 'new' | 'none'; } export interface ScheduleWorkflowOptions { taskQueue?: string; workflowId?: string; workflowExecutionTimeout?: string; workflowRunTimeout?: string; workflowTaskTimeout?: string; retryPolicy?: Record<string, unknown>; args?: unknown[]; } export interface ScheduleSpecBuilderResult { success: boolean; spec?: Record<string, unknown>; error?: Error; } export interface ScheduleIntervalParseResult { success: boolean; interval?: Record<string, unknown>; error?: Error; } export interface TemporalConnection { address: string; namespace?: string; tls?: boolean | object; metadata?: Record<string, string>; } export interface ScheduleWorkflowAction { type: 'startWorkflow'; workflowType: string; taskQueue: string; args?: unknown[]; workflowId?: string; workflowExecutionTimeout?: string; workflowRunTimeout?: string; workflowTaskTimeout?: string; retryPolicy?: Record<string, unknown>; } export interface ScheduleOptions { scheduleId: string; spec: Record<string, unknown>; action: ScheduleWorkflowAction; memo?: Record<string, unknown>; searchAttributes?: Record<string, unknown>; } export interface WorkerConnectionOptions { address: string; tls?: boolean | object; metadata?: Record<string, string>; apiKey?: string; namespace?: string; } export interface WorkerConfig { taskQueue: string; namespace: string; connection: NativeConnection; activities: Record<string, Function>; workflowsPath?: string; workflowBundle?: unknown; workerOptions?: Record<string, unknown>; [key: string]: unknown; } export interface WorkerInitResult { success: boolean; worker?: Worker; error?: Error; activitiesCount: number; taskQueue: string; namespace: string; } export interface WorkerRestartResult { success: boolean; error?: Error; restartCount: number; maxRestarts: number; } export interface WorkerShutdownResult { success: boolean; error?: Error; shutdownTime: number; } export interface WorkerHealthStatus { isHealthy: boolean; isRunning: boolean; isInitialized: boolean; lastError?: string; uptime?: number; activitiesCount: number; restartCount: number; maxRestarts: number; } export interface WorkerStats { isInitialized: boolean; isRunning: boolean; activitiesCount: number; restartCount: number; maxRestarts: number; uptime?: number; startedAt?: Date; lastError?: string; taskQueue: string; namespace: string; workflowSource: 'bundle' | 'filesystem' | 'registered' | 'none'; } export interface ActivityRegistrationResult { success: boolean; registeredCount: number; errors: Array<{ activityName: string; error: string; }>; } export interface WorkerDiscoveryResult { success: boolean; discoveredActivities: number; loadedActivities: number; errors: Array<{ component: string; error: string; }>; duration: number; } export interface TemporalServiceInitResult { success: boolean; error?: Error; servicesInitialized: { client: boolean; worker: boolean; schedule: boolean; discovery: boolean; metadata: boolean; }; initializationTime: number; } export interface WorkflowExecutionResult<T = unknown> { success: boolean; result?: T; error?: Error; workflowId?: string; runId?: string; executionTime?: number; } export interface WorkflowSignalResult { success: boolean; error?: Error; workflowId: string; signalName: string; } export interface WorkflowQueryResult<T = unknown> { success: boolean; result?: T; error?: Error; workflowId: string; queryName: string; } export interface WorkflowTerminationResult { success: boolean; error?: Error; workflowId: string; reason?: string; } export interface WorkflowCancellationResult { success: boolean; error?: Error; workflowId: string; } export interface ActivityExecutionResult<T = unknown> { success: boolean; result?: T; error?: Error; activityName: string; executionTime?: number; args?: unknown[]; } export interface ServiceHealthStatus { status: 'healthy' | 'unhealthy' | 'degraded'; isInitialized: boolean; lastError?: string; uptime?: number; details?: Record<string, unknown>; } export interface ComponentHealthStatus { client: ServiceHealthStatus; worker: ServiceHealthStatus; schedule: ServiceHealthStatus; activity: ServiceHealthStatus; discovery: ServiceHealthStatus; } export interface OverallHealthStatus { status: 'healthy' | 'unhealthy' | 'degraded'; components: ComponentHealthStatus; isInitialized: boolean; namespace: string; summary: { totalActivities: number; totalSchedules: number; workerRunning: boolean; clientConnected: boolean; }; timestamp: Date; } export interface ServiceStatistics { activities: { classes: number; methods: number; total: number; registered: number; available: number; }; schedules: { total: number; active: number; paused: number; }; worker: { isRunning: boolean; isHealthy: boolean; activitiesCount: number; uptime?: number; }; client: { isConnected: boolean; isHealthy: boolean; namespace: string; }; discovery: { isComplete: boolean; discoveredCount: number; errors: number; }; } export interface ServiceInitOptions { waitForServices?: boolean; maxWaitTime?: number; retryAttempts?: number; retryDelay?: number; } export interface ServiceShutdownOptions { graceful?: boolean; timeout?: number; stopWorker?: boolean; } export interface ServiceShutdownResult { success: boolean; error?: Error; shutdownTime: number; servicesShutdown: { worker: boolean; client: boolean; schedule: boolean; }; } export interface HealthResponse { status: 'healthy' | 'degraded' | 'unhealthy'; timestamp: string; uptime: number; client: { available: boolean; healthy: boolean; connected: boolean; }; worker: { available: boolean; running: boolean; healthy: boolean; activitiesCount: number; }; discovery: { activities: number; complete: boolean; discoveredCount: number; }; schedules: { total: number; active: number; paused: number; }; metadata: { classes: number; methods: number; total: number; }; summary: { totalComponents: number; healthyComponents: number; degradedComponents: number; unhealthyComponents: number; }; }