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
TypeScript
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;
};
}