nmtjs 0.15.0-beta.21 → 0.15.0-beta.22

package/src/runtime/jobs/router.ts

@@ -3,7 +3,6 @@ import type { TProcedureContract, TRouterContract } from '@nmtjs/contract'
 import type { Dependencies, DependencyContext, Metadata } from '@nmtjs/core'
 import type { NullableType, OptionalType } from '@nmtjs/type'
 import type { NeverType } from '@nmtjs/type/never'
-import type { JobState } from 'bullmq'
 import { CoreInjectables } from '@nmtjs/core'
 import { t } from '@nmtjs/type'
 
@@ -12,6 +11,7 @@ import type { AnyMiddleware } from '../application/api/middlewares.ts'
 import type { AnyProcedure } from '../application/api/procedure.ts'
 import type { AnyRouter, Router } from '../application/api/router.ts'
 import type { AnyJob } from './job.ts'
+import type { JobStatus } from './types.ts'
 import { createProcedure } from '../application/api/procedure.ts'
 import { createRouter } from '../application/api/router.ts'
 import { jobManager } from '../injectables.ts'
@@ -142,21 +142,35 @@ export type CreateJobsRouterOptions<Jobs extends Record<string, AnyJob>> = {
 // Router Contract Types
 // ============================================================================
 
+/** Type-level schema for JobProgressCheckpoint - typed per job */
+type JobProgressCheckpointSchemaType<T extends AnyJob> = t.ObjectType<{
+  stepIndex: t.NumberType
+  stepLabel: OptionalType<t.StringType>
+  result: t.RecordType<t.StringType, t.AnyType>
+  stepResults: t.ArrayType<
+    t.ObjectType<{
+      data: NullableType<t.RecordType<t.StringType, t.AnyType>>
+      duration: t.NumberType
+    }>
+  >
+  progress: T['progress']
+}>
+
 /** Type-level representation of createJobItemSchema output */
 type JobItemSchemaType<T extends AnyJob> = t.ObjectType<{
   id: t.StringType
-  queueName: t.StringType
-  priority: OptionalType<t.NumberType>
-  progress: t.AnyType
   name: t.StringType
+  queue: t.StringType
   data: T['input']
-  returnvalue: OptionalType<NullableType<T['output']>>
-  attemptsMade: t.NumberType
-  processedOn: OptionalType<t.NumberType>
-  finishedOn: OptionalType<t.NumberType>
-  failedReason: OptionalType<t.StringType>
-  stacktrace: OptionalType<t.ArrayType<t.StringType>>
+  output: OptionalType<NullableType<T['output']>>
   status: t.StringType
+  priority: OptionalType<t.NumberType>
+  progress: OptionalType<JobProgressCheckpointSchemaType<T>>
+  attempts: t.NumberType
+  startedAt: OptionalType<t.NumberType>
+  completedAt: OptionalType<t.NumberType>
+  error: OptionalType<t.StringType>
+  stacktrace: OptionalType<t.ArrayType<t.StringType>>
 }>
 
 /** Type-level representation of createListOutputSchema output */
@@ -216,7 +230,7 @@ export type JobsRouter<Jobs extends Record<string, AnyJob>> = Router<
 const listInputSchema = t.object({
   page: t.number().optional(),
   limit: t.number().optional(),
-  state: t.array(t.string()).optional(),
+  status: t.array(t.string()).optional(),
 })
 
 /** Input schema for get operation */
@@ -242,22 +256,41 @@ const infoOutputSchema = t.object({
   ),
 })
 
+/** Schema for step result entry */
+const stepResultEntrySchema = t.object({
+  data: t.record(t.string(), t.any()).nullable(),
+  duration: t.number(),
+})
+
+/** Creates JobProgressCheckpoint schema for a specific job */
+function createJobProgressCheckpointSchema<T extends AnyJob>(
+  job: T,
+): JobProgressCheckpointSchemaType<T> {
+  return t.object({
+    stepIndex: t.number(),
+    stepLabel: t.string().optional(),
+    result: t.record(t.string(), t.any()),
+    stepResults: t.array(stepResultEntrySchema),
+    progress: job.progress,
+  })
+}
+
 /** JobItem schema for list/get responses - typed per job */
 function createJobItemSchema<T extends AnyJob>(job: T): JobItemSchemaType<T> {
   return t.object({
     id: t.string(),
-    queueName: t.string(),
-    priority: t.number().optional(),
-    progress: t.any(),
     name: t.string(),
+    queue: t.string(),
     data: job.input,
-    returnvalue: job.output.nullish(),
-    attemptsMade: t.number(),
-    processedOn: t.number().optional(),
-    finishedOn: t.number().optional(),
-    failedReason: t.string().optional(),
-    stacktrace: t.array(t.string()).optional(),
+    output: job.output.nullish(),
     status: t.string(),
+    priority: t.number().optional(),
+    progress: createJobProgressCheckpointSchema(job).optional(),
+    attempts: t.number(),
+    startedAt: t.number().optional(),
+    completedAt: t.number().optional(),
+    error: t.string().optional(),
+    stacktrace: t.array(t.string()).optional(),
   })
 }
 
@@ -424,14 +457,14 @@ function createListProcedure(
           jobName: job.options.name,
           page: input.page,
           limit: input.limit,
-          state: input.state,
+          status: input.status,
         },
         'Listing jobs',
       )
       const result = await ctx.jobManager.list(job, {
         page: input.page,
         limit: input.limit,
-        state: input.state as JobState[],
+        status: input.status as JobStatus[],
       })
       ctx.logger.debug(
         { jobName: job.options.name, total: result.total, pages: result.pages },

package/src/runtime/jobs/runner.ts

@@ -7,15 +7,21 @@ import { UnrecoverableError } from 'bullmq'
 import type { LifecycleHooks } from '../core/hooks.ts'
 import type { AnyJob } from './job.ts'
 import type { AnyJobStep } from './step.ts'
+import type {
+  JobExecutionContext,
+  JobProgressCheckpoint,
+  StepResultEntry,
+} from './types.ts'
 import { LifecycleHook } from '../enums.ts'
-import { jobAbortSignal } from '../injectables.ts'
+import {
+  currentJobInfo,
+  jobAbortSignal,
+  saveJobProgress,
+} from '../injectables.ts'
 
 export type JobRunnerOptions = { logging?: LoggingOptions }
 
-export interface StepResultEntry {
-  data: Record<string, unknown> | null
-  duration: number
-}
+export type { StepResultEntry } from './types.ts'
 
 export interface JobRunnerRunOptions {
   signal: AbortSignal
@@ -42,6 +48,18 @@ export interface JobRunnerRunAfterStepParams<
   stepResult: StepResultEntry
 }
 
+/** Context for saveProgress function - contains mutable state references */
+export interface SaveProgressContext<
+  Options extends JobRunnerRunOptions = JobRunnerRunOptions,
+> {
+  job: AnyJob
+  progress: Record<string, unknown>
+  result: Record<string, unknown>
+  stepResults: StepResultEntry[] | null
+  currentStepIndex: number
+  options: Options | null
+}
+
 export class JobRunner<
   RunOptions extends JobRunnerRunOptions = JobRunnerRunOptions,
 > {
@@ -61,6 +79,28 @@ export class JobRunner<
     return this.runtime.container
   }
 
+  /**
+   * Creates a function that saves the current job progress state.
+   * Override in subclasses to implement actual persistence.
+   */
+  protected createSaveProgressFn(
+    _context: SaveProgressContext<RunOptions>,
+  ): () => Promise<void> {
+    // No-op in base runner - subclasses implement actual persistence
+    return async () => {}
+  }
+
+  /**
+   * Creates the current job info object.
+   * Override in subclasses to include additional info (e.g., BullMQ job ID).
+   */
+  protected createJobInfo(
+    job: AnyJob,
+    _options: Partial<RunOptions>,
+  ): JobExecutionContext {
+    return { name: job.options.name }
+  }
+
   async runJob<T extends AnyJob>(
     job: T,
     data: any,
@@ -91,6 +131,23 @@ export class JobRunner<
     const signal = anyAbortSignal(runSignal, stopListener.signal)
     await using container = this.container.fork(Scope.Global)
     await container.provide(jobAbortSignal, signal)
+    await container.provide(currentJobInfo, this.createJobInfo(job, options))
+
+    // Create mutable state context for saveProgress
+    const progressContext = {
+      job,
+      progress,
+      result,
+      stepResults: null as StepResultEntry[] | null, // Will be set below
+      currentStepIndex,
+      options: null as RunOptions | null, // Will be set below
+    }
+
+    // Provide saveProgress injectable
+    await container.provide(
+      saveJobProgress,
+      this.createSaveProgressFn(progressContext),
+    )
 
     const jobDependencyContext = await container.createContext(job.dependencies)
     const jobData = job.options.data
@@ -116,6 +173,10 @@ export class JobRunner<
       ...rest,
     } satisfies JobRunnerRunOptions
 
+    // Update mutable context references
+    progressContext.stepResults = stepResults
+    progressContext.options = runOptions
+
     for (
       let stepIndex = currentStepIndex;
       stepIndex < steps.length;
@@ -279,6 +340,51 @@ export class ApplicationWorkerJobRunner extends JobRunner<
     super(runtime)
   }
 
+  protected createJobInfo(
+    job: AnyJob,
+    options: Partial<JobRunnerRunOptions & { queueJob: Job }>,
+  ): JobExecutionContext {
+    const { queueJob } = options
+    return {
+      name: job.options.name,
+      id: queueJob?.id,
+      queue: queueJob?.queueName,
+      attempts: queueJob?.attemptsMade,
+      stepIndex: options.currentStepIndex,
+    }
+  }
+
+  protected createSaveProgressFn(
+    context: SaveProgressContext<JobRunnerRunOptions & { queueJob: Job }>,
+  ): () => Promise<void> {
+    return async () => {
+      const { job, progress, result, stepResults, options } = context
+      if (!options || !stepResults) return
+
+      const { queueJob } = options
+
+      // Find current step index based on completed steps
+      let currentStepIndex = 0
+      for (let i = 0; i < stepResults.length; i++) {
+        if (stepResults[i]) currentStepIndex = i + 1
+      }
+
+      // Encode progress before persisting if schema is defined
+      const encodedProgress = job.progress
+        ? job.progress.encode(progress)
+        : progress
+
+      const checkpoint: JobProgressCheckpoint = {
+        stepIndex: currentStepIndex,
+        result,
+        stepResults,
+        progress: encodedProgress,
+      }
+
+      await queueJob.updateProgress(checkpoint)
+    }
+  }
+
   protected async afterStep(
     params: JobRunnerRunAfterStepParams<
       JobRunnerRunOptions & { queueJob: Job }
@@ -295,26 +401,25 @@ export class ApplicationWorkerJobRunner extends JobRunner<
       options: { queueJob, progress },
     } = params
     const nextStepIndex = stepIndex + 1
-    const totalSteps = job.steps.length
-    const percentage = Math.round((nextStepIndex / totalSteps) * 100)
 
     // Encode progress before persisting if schema is defined
     const encodedProgress = job.progress
       ? job.progress.encode(progress)
       : progress
 
+    const checkpoint: JobProgressCheckpoint = {
+      stepIndex: nextStepIndex,
+      stepLabel: step.label,
+      result,
+      stepResults,
+      progress: encodedProgress,
+    }
+
     await Promise.all([
       queueJob.log(
         `Step ${step.label || nextStepIndex} completed in ${(stepResult.duration / 1000).toFixed(3)}s`,
       ),
-      queueJob.updateProgress({
-        stepIndex: nextStepIndex,
-        stepLabel: step.label,
-        result,
-        stepResults,
-        progress: encodedProgress,
-        percentage,
-      }),
+      queueJob.updateProgress(checkpoint),
     ])
   }
 }

package/src/runtime/jobs/types.ts

@@ -0,0 +1,110 @@
+// ============================================================================
+// Job Definition Types (metadata about job structure)
+// ============================================================================
+
+/** Metadata about a job step in a job definition */
+export interface JobStepInfo {
+  /** Optional human-readable label for the step */
+  label?: string
+  /** Whether this step has a condition that may skip it */
+  conditional: boolean
+}
+
+/** Metadata about a job definition (not a running job instance) */
+export interface JobDefinitionInfo {
+  /** Job name from definition */
+  name: string
+  /** Information about each step in the job */
+  steps: JobStepInfo[]
+}
+
+// ============================================================================
+// Job Execution Types (runtime state of a running job)
+// ============================================================================
+
+/** Result of a single step execution */
+export interface StepResultEntry {
+  /** Output data produced by the step, or null if skipped */
+  data: Record<string, unknown> | null
+  /** Duration in milliseconds */
+  duration: number
+}
+
+/** Checkpoint data persisted for job resume support */
+export interface JobProgressCheckpoint {
+  /** Index of the next step to execute (0 = not started, length = completed) */
+  stepIndex: number
+  /** Label of the last completed step */
+  stepLabel?: string
+  /** Accumulated result from all completed steps */
+  result: Record<string, unknown>
+  /** Results of each individual step */
+  stepResults: StepResultEntry[]
+  /** User-defined progress state */
+  progress: Record<string, unknown>
+}
+
+/** Information about the currently executing job, available via injectable */
+export interface JobExecutionContext {
+  /** Job definition name */
+  name: string
+  /** Queue job ID */
+  id?: string
+  /** Queue name */
+  queue?: string
+  /** Number of attempts made so far */
+  attempts?: number
+  /** Current step index being executed */
+  stepIndex?: number
+}
+
+// ============================================================================
+// Job Item Types (job instances from queue)
+// ============================================================================
+
+/** Vendor-agnostic job status */
+export type JobStatus =
+  | 'pending' // Queued, waiting to be picked up
+  | 'active' // Currently executing
+  | 'completed' // Successfully finished
+  | 'failed' // Failed (may retry)
+  | 'delayed' // Scheduled for future
+  | 'cancelled' // Manually cancelled
+  | 'unknown' // State cannot be determined
+
+/** A job instance retrieved from the queue */
+export interface JobItem<TInput = unknown, TOutput = unknown> {
+  /** Unique job instance ID */
+  id: string
+  /** Job definition name */
+  name: string
+  /** Queue name this job belongs to */
+  queue: string
+  /** Input data passed to the job */
+  data: TInput
+  /** Output produced by the job (if completed) */
+  output?: TOutput | null
+  /** Current job status */
+  status: JobStatus
+  /** Job priority (lower = higher priority) */
+  priority?: number
+  /** Job progress checkpoint (includes step state and user progress) */
+  progress?: JobProgressCheckpoint
+  /** Number of execution attempts */
+  attempts: number
+  /** Timestamp when job started processing (ms) */
+  startedAt?: number
+  /** Timestamp when job completed (ms) */
+  completedAt?: number
+  /** Error message if job failed */
+  error?: string
+  /** Stack trace if job failed */
+  stacktrace?: string[]
+}
+
+// ============================================================================
+// Injectable Types
+// ============================================================================
+
+/** Function to manually trigger saving job progress state */
+export type SaveJobProgress = () => Promise<void>

package/src/runtime/server/jobs.ts

@@ -203,6 +203,8 @@ export class ApplicationServerJobs {
 
   async stop() {
     const { logger } = this.params
+    // TODO: make configurable
+    const closeTimeout = 10_000 // 10 seconds timeout for graceful close
 
     if (this.ui) {
       await new Promise<void>((resolve) => {
@@ -212,29 +214,43 @@ export class ApplicationServerJobs {
       })
     }
 
+    // Stop accepting new jobs first.
     await Promise.all(
-      this.uiQueues.map(async (queue) => {
+      [...this.queueWorkers].map(async (worker) => {
         try {
-          await queue.close()
+          // Try graceful close with timeout
+          const closePromise = worker.close()
+          const timeoutPromise = new Promise<'timeout'>((resolve) =>
+            setTimeout(() => resolve('timeout'), closeTimeout),
+          )
+
+          const result = await Promise.race([closePromise, timeoutPromise])
+
+          if (result === 'timeout') {
+            logger.warn(
+              { worker: worker.name },
+              'Worker close timed out, forcing close',
+            )
+            await worker.close(true)
+          }
         } catch (error) {
-          logger.warn({ error }, 'Failed to close Jobs UI queue')
+          logger.warn({ error }, 'Failed to close BullMQ worker')
         }
       }),
     )
-    this.uiQueues = []
-    this.ui = undefined
+    this.queueWorkers.clear()
 
-    // Stop accepting new jobs first.
     await Promise.all(
-      [...this.queueWorkers].map(async (worker) => {
+      this.uiQueues.map(async (queue) => {
         try {
-          await worker.close()
+          await queue.close()
         } catch (error) {
-          logger.warn({ error }, 'Failed to close BullMQ worker')
+          logger.warn({ error }, 'Failed to close Jobs UI queue')
         }
       }),
     )
-    this.queueWorkers.clear()
+    this.uiQueues = []
+    this.ui = undefined
 
     await Promise.all(
       Array.from(this.pools.values()).map(async (pool) => {

package/src/runtime/workers/job.ts

@@ -3,7 +3,7 @@ import type { MessagePort } from 'node:worker_threads'
 import { UnrecoverableError } from 'bullmq'
 
 import type { JobWorkerPool } from '../enums.ts'
-import type { StepResultEntry } from '../jobs/runner.ts'
+import type { JobProgressCheckpoint } from '../jobs/types.ts'
 import type { ServerConfig } from '../server/config.ts'
 import type { ServerPortMessage, ThreadPortMessage } from '../types.ts'
 import { LifecycleHook, WorkerType } from '../enums.ts'
@@ -95,12 +95,7 @@ export class JobWorkerRuntime extends BaseWorkerRuntime {
 
           // Load checkpoint from BullMQ progress for resume support
           const checkpoint = bullJob.progress as
-            | {
-                stepIndex: number
-                result: Record<string, unknown>
-                stepResults: StepResultEntry[]
-                progress: Record<string, unknown>
-              }
+            | JobProgressCheckpoint
             | undefined
 
           const result = await this.jobRunner.runJob(job, task.data, {