nmtjs 0.15.0-beta.20 → 0.15.0-beta.22

package/src/runtime/jobs/manager.ts

@@ -8,7 +8,6 @@ import type {
   QueueEventsListener,
   RedisClient,
 } from 'bullmq'
-import { pick } from '@nmtjs/core'
 import {
   Queue,
   QueueEvents,
@@ -19,6 +18,7 @@ import {
 import type { ServerStoreConfig } from '../server/config.ts'
 import type { Store } from '../types.ts'
 import type { AnyJob, JobBackoffOptions } from './job.ts'
+import type { JobDefinitionInfo, JobProgressCheckpoint } from './types.ts'
 import { createStoreClient } from '../store/index.ts'
 
 /**
@@ -64,33 +64,29 @@ export class QueueJobResult<T extends AnyJob = AnyJob> {
   }
 }
 
-export type JobItem<T extends AnyJob = AnyJob> = Pick<
-  Job<T['_']['input'], T['_']['output'], T['options']['name']>,
-  | 'queueName'
-  | 'priority'
-  | 'progress'
-  | 'name'
-  | 'data'
-  | 'returnvalue'
-  | 'attemptsMade'
-  | 'processedOn'
-  | 'finishedOn'
-  | 'failedReason'
-  | 'stacktrace'
-> & { id: string; status: JobState | 'unknown' }
+export type { JobDefinitionInfo, JobItem, JobStepInfo } from './types.ts'
+
+import type { JobItem, JobStatus } from './types.ts'
+
+/** Job item type with generic job typing for internal use */
+export type JobItemOf<T extends AnyJob = AnyJob> = JobItem<
+  T['_']['input'],
+  T['_']['output']
+>
 
 export interface JobManagerInstance {
   list<T extends AnyJob>(
     job: T,
-    options?: { page?: number; limit?: number; state?: JobState[] },
+    options?: { page?: number; limit?: number; status?: JobStatus[] },
   ): Promise<{
-    items: JobItem<T>[]
+    items: JobItemOf<T>[]
     page: number
     limit: number
     pages: number
     total: number
   }>
-  get<T extends AnyJob>(job: T, id: string): Promise<JobItem<T> | null>
+  get<T extends AnyJob>(job: T, id: string): Promise<JobItemOf<T> | null>
+  getInfo(job: AnyJob): JobDefinitionInfo
   add<T extends AnyJob>(
     job: T,
     data: T['_']['input'],
@@ -133,6 +129,7 @@ export class JobManager {
       list: this.list.bind(this),
       add: this.add.bind(this),
       get: this.get.bind(this),
+      getInfo: this.getInfo.bind(this),
       retry: this.retry.bind(this),
       remove: this.remove.bind(this),
       cancel: this.cancel.bind(this),
@@ -188,20 +185,32 @@ export class JobManager {
     return entry
   }
 
+  getInfo(job: AnyJob): JobDefinitionInfo {
+    return {
+      name: job.options.name,
+      steps: job.steps.map((step, index) => ({
+        label: step.label,
+        conditional: job.conditions.has(index),
+      })),
+    }
+  }
+
   async list<T extends AnyJob>(
     job: T,
     {
       limit = 20,
       page = 1,
-      state = [],
-    }: { page?: number; limit?: number; state?: JobType[] },
+      status = [],
+    }: { page?: number; limit?: number; status?: JobStatus[] },
   ) {
     const { queue } = this.getJobQueue(job)
-    const jobsCount = await queue.getJobCountByTypes(...state)
+    // Convert vendor-agnostic status to BullMQ JobType for querying
+    const bullJobTypes = status.flatMap((s) => this._mapStatusToJobType(s))
+    const jobsCount = await queue.getJobCountByTypes(...bullJobTypes)
     const totalPages = Math.ceil(jobsCount / limit)
     if (page > totalPages) return []
     const jobs = await queue.getJobs(
-      state,
+      bullJobTypes,
       (page - 1) * limit,
       page * limit - 1,
     )
@@ -307,26 +316,77 @@ export class JobManager {
     return this.getJobQueue(job)
   }
 
-  protected async _mapJob(bullJob: Job): Promise<JobItem> {
-    const status = await bullJob.getState()
+  protected async _mapJob(bullJob: Job): Promise<JobItemOf> {
+    const bullState = await bullJob.getState()
     const id = bullJob.id
     assert(typeof id === 'string', 'Expected job id to be a string')
+
+    // Map BullMQ state to vendor-agnostic status
+    const status = this._mapStatus(bullState)
+
+    // Extract progress only if it's a valid checkpoint object
+    const progress =
+      typeof bullJob.progress === 'object' &&
+      bullJob.progress !== null &&
+      'stepIndex' in bullJob.progress
+        ? (bullJob.progress as JobProgressCheckpoint)
+        : undefined
+
     return {
-      ...pick(bullJob, {
-        queueName: true,
-        priority: true,
-        progress: true,
-        name: true,
-        data: true,
-        returnvalue: true,
-        attemptsMade: true,
-        processedOn: true,
-        finishedOn: true,
-        failedReason: true,
-        stacktrace: true,
-      }),
       id,
+      name: bullJob.name,
+      queue: bullJob.queueName,
+      data: bullJob.data,
+      output: bullJob.returnvalue,
       status,
+      priority: bullJob.priority,
+      progress,
+      attempts: bullJob.attemptsMade,
+      startedAt: bullJob.processedOn,
+      completedAt: bullJob.finishedOn,
+      error: bullJob.failedReason,
+      stacktrace: bullJob.stacktrace,
+    }
+  }
+
+  /** Map BullMQ JobState to vendor-agnostic JobStatus */
+  protected _mapStatus(state: JobState | 'unknown'): JobStatus {
+    switch (state) {
+      case 'waiting':
+      case 'prioritized':
+      case 'waiting-children':
+        return 'pending'
+      case 'active':
+        return 'active'
+      case 'completed':
+        return 'completed'
+      case 'failed':
+        return 'failed'
+      case 'delayed':
+        return 'delayed'
+      default:
+        return 'unknown'
+    }
+  }
+
+  /** Map vendor-agnostic JobStatus to BullMQ JobType for queries */
+  protected _mapStatusToJobType(status: JobStatus): JobType[] {
+    switch (status) {
+      case 'pending':
+        return ['waiting', 'prioritized', 'waiting-children']
+      case 'active':
+        return ['active']
+      case 'completed':
+        return ['completed']
+      case 'failed':
+        return ['failed']
+      case 'delayed':
+        return ['delayed']
+      case 'cancelled':
+        return [] // BullMQ doesn't have a cancelled state
+      case 'unknown':
+      default:
+        return []
     }
   }
 }

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'
@@ -37,6 +37,10 @@ export type ListOperationConfig<Deps extends Dependencies = {}> =
 export type GetOperationConfig<Deps extends Dependencies = {}> =
   BaseOperationConfig<Deps>
 
+/** Info operation config (read-only, no hooks) */
+export type InfoOperationConfig<Deps extends Dependencies = {}> =
+  BaseOperationConfig<Deps>
+
 /** Add queue options */
 export type AddQueueOptions = {
   priority?: number
@@ -103,6 +107,7 @@ export type CancelOperationConfig<Deps extends Dependencies = {}> =
 
 /** All operations for a job (false = disabled) */
 export type JobOperations<T extends AnyJob = AnyJob> = {
+  info?: InfoOperationConfig<any> | false
   list?: ListOperationConfig<any> | false
   get?: GetOperationConfig<any> | false
   add?: AddOperationConfig<T, any> | false
@@ -113,6 +118,7 @@ export type JobOperations<T extends AnyJob = AnyJob> = {
 
 /** Default operations config */
 export type DefaultOperations = {
+  info?: InfoOperationConfig<any> | false
   list?: ListOperationConfig<any> | false
   get?: GetOperationConfig<any> | false
   add?: AddOperationConfig<AnyJob, any> | false
@@ -136,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<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 */
@@ -165,6 +185,9 @@ type ListOutputSchemaType<T extends AnyJob> = t.ObjectType<{
 /** Type-level representation of createGetOutputSchema output */
 type GetOutputSchemaType<T extends AnyJob> = NullableType<JobItemSchemaType<T>>
 
+/** Type-level representation of infoOutputSchema */
+type InfoOutputSchemaType = typeof infoOutputSchema
+
 /** Type-level representation of createAddInputSchema output */
 type AddInputSchemaType<T extends AnyJob> = t.ObjectType<{
   data: T['input']
@@ -175,6 +198,7 @@ type AddInputSchemaType<T extends AnyJob> = t.ObjectType<{
 
 /** Operations contract for a single job - now properly typed per job */
 type JobOperationsProcedures<T extends AnyJob> = {
+  info: TProcedureContract<NeverType, InfoOutputSchemaType>
   list: TProcedureContract<typeof listInputSchema, ListOutputSchemaType<T>>
   get: TProcedureContract<typeof getInputSchema, GetOutputSchemaType<T>>
   add: TProcedureContract<AddInputSchemaType<T>, typeof addOutputSchema>
@@ -206,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 */
@@ -224,22 +248,49 @@ const retryInputSchema = t.object({
 /** Input schema for cancel/remove operations */
 const idInputSchema = t.object({ id: t.string() })
 
+/** Output schema for info operation */
+const infoOutputSchema = t.object({
+  name: t.string(),
+  steps: t.array(
+    t.object({ label: t.string().optional(), conditional: t.boolean() }),
+  ),
+})
+
+/** 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.optional(),
-    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(),
   })
 }
 
@@ -352,6 +403,33 @@ type JobManagerDeps = {
   logger: typeof CoreInjectables.logger
 }
 
+function createInfoProcedure(
+  job: AnyJob,
+  config: InfoOperationConfig<any> = {},
+  shared: { guards?: AnyGuard[]; middlewares?: AnyMiddleware[] },
+): AnyProcedure {
+  const allGuards = [...(shared.guards ?? []), ...(config.guards ?? [])]
+  const allMiddlewares = [
+    ...(shared.middlewares ?? []),
+    ...(config.middlewares ?? []),
+  ]
+
+  const deps: JobManagerDeps = { jobManager, logger: CoreInjectables.logger }
+
+  return createProcedure({
+    output: infoOutputSchema,
+    dependencies: { ...deps, ...(config.dependencies ?? {}) },
+    guards: allGuards,
+    middlewares: allMiddlewares,
+    metadata: config.metadata,
+    timeout: config.timeout,
+    handler: (ctx: DependencyContext<JobManagerDeps>) => {
+      ctx.logger.trace({ jobName: job.options.name }, 'Getting job info')
+      return ctx.jobManager.getInfo(job)
+    },
+  })
+}
+
 function createListProcedure(
   job: AnyJob,
   config: ListOperationConfig<any> = {},
@@ -379,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 },
@@ -677,7 +755,15 @@ function mergeOperations(
 ): JobOperations {
   const result: JobOperations = {}
 
-  const ops = ['list', 'get', 'add', 'retry', 'cancel', 'remove'] as const
+  const ops = [
+    'info',
+    'list',
+    'get',
+    'add',
+    'retry',
+    'cancel',
+    'remove',
+  ] as const
 
   for (const op of ops) {
     const override = overrides[op]
@@ -778,6 +864,14 @@ export function createJobsRouter<const Jobs extends Record<string, AnyJob>>(
     const jobRoutes: Record<string, AnyProcedure> = {}
 
     // Generate each enabled operation
+    if (operations.info !== false) {
+      jobRoutes.info = createInfoProcedure(
+        job,
+        operations.info as InfoOperationConfig,
+        shared,
+      )
+    }
+
     if (operations.list !== false) {
       jobRoutes.list = createListProcedure(
         job,

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/step.ts

@@ -28,6 +28,7 @@ export interface JobStep<
   Data = any,
 > extends Dependant {
   [kJobStepKey]: any
+  label?: string
   input: Input
   output: Output
   dependencies: Deps