Merge pull request #964 from TNG/never-job

weissu42 · web-flow · commit 3d9b1a2ca139 · 2025-06-20T14:00:23.000+02:00
feat: implement option to schedule job to run "never"
diff --git a/README.md b/README.md
diff --git a/src/job/Job.ts b/src/job/Job.ts
@@ -2,7 +2,17 @@ import humanInterval from 'human-interval';
 import { Result, err, ok } from 'neverthrow';
 import CronExpressionParser from 'cron-parser';
 
-import { CronSchedule, Handler, IntervalSchedule, JobParameters, MomoJob, TypedMomoJob, isCronJob } from './MomoJob';
+import {
+  CronSchedule,
+  Handler,
+  IntervalSchedule,
+  JobParameters,
+  MomoJob,
+  NeverSchedule,
+  TypedMomoJob,
+  isCronJob,
+  isNeverJob,
+} from './MomoJob';
 import { momoError } from '../logging/error/MomoError';
 
 export const maxNodeTimeoutDelay = 2147483647;
@@ -13,7 +23,7 @@ export interface ParsedIntervalSchedule extends Required<IntervalSchedule> {
   parsedFirstRunAfter: number;
 }
 
-export interface JobDefinition<JobSchedule = ParsedIntervalSchedule | CronSchedule> {
+export interface JobDefinition<JobSchedule = ParsedIntervalSchedule | CronSchedule | NeverSchedule> {
   name: string;
   schedule: JobSchedule;
   concurrency: number;
@@ -22,7 +32,7 @@ export interface JobDefinition<JobSchedule = ParsedIntervalSchedule | CronSchedu
   parameters?: JobParameters;
 }
 
-export interface Job<Schedule = ParsedIntervalSchedule | CronSchedule> extends JobDefinition<Schedule> {
+export interface Job<Schedule = ParsedIntervalSchedule | CronSchedule | NeverSchedule> extends JobDefinition<Schedule> {
   handler: Handler;
 }
 
@@ -46,7 +56,19 @@ export function tryToJob(momoJob: MomoJob): Result<Job, Error> {
     return err(momoError.invalidTimeout);
   }
 
-  return isCronJob(momoJob) ? tryToCronJob(momoJob) : tryToIntervalJob(momoJob);
+  return isNeverJob(momoJob)
+    ? tryToNeverJob(momoJob)
+    : isCronJob(momoJob)
+      ? tryToCronJob(momoJob)
+      : tryToIntervalJob(momoJob);
+}
+
+export function tryToNeverJob(momoJob: TypedMomoJob<NeverSchedule>): Result<Job<NeverSchedule>, Error> {
+  return ok({
+    concurrency: 1,
+    maxRunning: 0,
+    ...momoJob,
+  });
 }
 
 /**
@@ -111,7 +133,7 @@ export function tryToCronJob(momoJob: TypedMomoJob<CronSchedule>): Result<Job<Cr
  * @param job
  */
 export function toJobDefinition<
-  Schedule extends ParsedIntervalSchedule | CronSchedule,
+  Schedule extends ParsedIntervalSchedule | CronSchedule | NeverSchedule,
   Type extends JobDefinition<Schedule>,
 >({ name, schedule, maxRunning, concurrency, timeout, parameters }: Type): JobDefinition<Schedule> {
   return { name, schedule, maxRunning, concurrency, timeout, parameters };
diff --git a/src/job/MomoJob.ts b/src/job/MomoJob.ts
@@ -14,7 +14,7 @@ export interface TypedMomoJob<Schedule> {
   parameters?: JobParameters;
 }
 
-export type MomoJob = TypedMomoJob<IntervalSchedule> | TypedMomoJob<CronSchedule>;
+export type MomoJob = TypedMomoJob<IntervalSchedule> | TypedMomoJob<CronSchedule> | TypedMomoJob<NeverSchedule>;
 
 export interface IntervalSchedule {
   interval: number | string;
@@ -25,18 +25,29 @@ export interface CronSchedule {
   cronSchedule: string;
 }
 
+export interface NeverSchedule {
+  interval: 'Never' | 'never';
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function isCronSchedule(input: any): input is CronSchedule {
   return input.cronSchedule !== undefined && typeof input.cronSchedule === 'string';
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function isNeverSchedule(input: any): input is NeverSchedule {
+  return input.interval !== undefined && (input.interval === 'Never' || input.interval === 'never');
+}
+
 /**
  * removes properties that are not part of the IntervalSchedule resp. CronSchedule interface
  *
  * @param schedule
  */
-export function toSchedule(schedule: ParsedIntervalSchedule | CronSchedule): Required<IntervalSchedule> | CronSchedule {
-  if (isCronSchedule(schedule)) {
+export function toSchedule(
+  schedule: ParsedIntervalSchedule | CronSchedule | NeverSchedule,
+): Required<IntervalSchedule> | CronSchedule | NeverSchedule {
+  if (isNeverSchedule(schedule) || isCronSchedule(schedule)) {
     return schedule;
   }
 
@@ -48,3 +59,7 @@ export function toSchedule(schedule: ParsedIntervalSchedule | CronSchedule): Req
 export function isCronJob(momoJob: MomoJob): momoJob is TypedMomoJob<CronSchedule> {
   return isCronSchedule(momoJob.schedule);
 }
+
+export function isNeverJob(momoJob: MomoJob): momoJob is TypedMomoJob<NeverSchedule> {
+  return isNeverSchedule(momoJob.schedule);
+}
diff --git a/src/job/MomoJobBuilder.ts b/src/job/MomoJobBuilder.ts
@@ -28,6 +28,11 @@ export class MomoJobBuilder {
 
   // The interval is either a number in milliseconds or an interval in human-readable form (see readme)
   withSchedule(interval: number | string, firstRunAfter: number | string = 0): MomoIntervalJobBuilder {
+    if (interval === 'Never' || interval === 'never') {
+      this.momoJob.schedule = { interval };
+      return this;
+    }
+
     this.momoJob.schedule = { firstRunAfter, interval };
     return this;
   }
diff --git a/src/job/MomoJobDescription.ts b/src/job/MomoJobDescription.ts
@@ -1,5 +1,5 @@
 import { JobEntity } from '../repository/JobEntity';
-import { CronSchedule, IntervalSchedule, JobParameters, toSchedule } from './MomoJob';
+import { CronSchedule, IntervalSchedule, JobParameters, NeverSchedule, toSchedule } from './MomoJob';
 
 /**
  * information about scheduled job
@@ -14,7 +14,7 @@ export interface JobSchedulerStatus {
 
 export interface MomoJobDescription {
   name: string;
-  schedule: IntervalSchedule | CronSchedule;
+  schedule: IntervalSchedule | CronSchedule | NeverSchedule;
   concurrency: number;
   maxRunning: number;
   parameters?: JobParameters;
diff --git a/src/repository/JobEntity.ts b/src/repository/JobEntity.ts
@@ -2,10 +2,13 @@ import { ObjectId } from 'mongodb';
 
 import { ExecutionInfo } from '../job/ExecutionInfo';
 import { JobDefinition, ParsedIntervalSchedule } from '../job/Job';
-import { CronSchedule } from '../job/MomoJob';
+import { CronSchedule, NeverSchedule } from '../job/MomoJob';
 
 export interface JobEntity<
-  Schedule extends ParsedIntervalSchedule | CronSchedule = ParsedIntervalSchedule | CronSchedule,
+  Schedule extends ParsedIntervalSchedule | CronSchedule | NeverSchedule =
+    | ParsedIntervalSchedule
+    | CronSchedule
+    | NeverSchedule,
 > extends JobDefinition<Schedule> {
   _id?: ObjectId;
   executionInfo?: ExecutionInfo;
diff --git a/src/repository/MomoJobStatus.ts b/src/repository/MomoJobStatus.ts
@@ -1,12 +1,12 @@
 import { JobEntity } from './JobEntity';
-import { CronSchedule, IntervalSchedule, toSchedule } from '../job/MomoJob';
+import { CronSchedule, IntervalSchedule, NeverSchedule, toSchedule } from '../job/MomoJob';
 import { ParsedIntervalSchedule } from '../job/Job';
 
 export interface MomoJobStatus extends Omit<JobEntity<never>, '_id' | 'schedule'> {
-  schedule: Required<IntervalSchedule> | CronSchedule;
+  schedule: Required<IntervalSchedule> | CronSchedule | NeverSchedule;
 }
 
-export function toMomoJobStatus<Schedule extends ParsedIntervalSchedule | CronSchedule>({
+export function toMomoJobStatus<Schedule extends ParsedIntervalSchedule | CronSchedule | NeverSchedule>({
   name,
   schedule,
   concurrency,
diff --git a/src/scheduler/JobScheduler.ts b/src/scheduler/JobScheduler.ts
@@ -12,7 +12,7 @@ import { momoError } from '../logging/error/MomoError';
 import { ExecutableIntervalSchedule } from './ExecutableIntervalSchedule';
 import { ExecutableCronSchedule } from './ExecutableCronSchedule';
 import { toExecutableSchedule } from './ExecutableSchedule';
-import { JobParameters } from '../job/MomoJob';
+import { JobParameters, isNeverSchedule } from '../job/MomoJob';
 import { setSafeTimeout } from '../timeout/safeTimeouts';
 
 export class JobScheduler {
@@ -82,6 +82,13 @@ export class JobScheduler {
       return;
     }
 
+    if (isNeverSchedule(jobEntity.schedule)) {
+      this.logger.debug(`do not start job specified to run 'never'`, {
+        name: this.jobName,
+      });
+      return;
+    }
+
     this.executableSchedule = toExecutableSchedule(jobEntity.schedule);
 
     const { nextExecution } = this.executableSchedule.execute({
diff --git a/test/job/MomoJobBuilder.spec.ts b/test/job/MomoJobBuilder.spec.ts
@@ -1,6 +1,26 @@
 import { MomoJobBuilder } from '../../src';
 
 describe('MomoJobBuilder', () => {
+  it('can build an interval job that never runs automatically', () => {
+    const momoJob = new MomoJobBuilder()
+      .withName('name')
+      .withSchedule('never')
+      .withConcurrency(1)
+      .withMaxRunning(1)
+      .withHandler(jest.fn())
+      .withParameters({ foo: 'bar' })
+      .withTimeout(1)
+      .build();
+
+    expect(momoJob.name).toEqual('name');
+    expect(momoJob.schedule).toEqual({ interval: 'never' });
+    expect(momoJob.concurrency).toEqual(1);
+    expect(momoJob.maxRunning).toEqual(1);
+    expect(momoJob.handler.toString()).toEqual(jest.fn().toString());
+    expect(momoJob.parameters).toEqual({ foo: 'bar' });
+    expect(momoJob.timeout).toEqual(1);
+  });
+
   it('can build an interval job with all attributes and an interval', () => {
     const momoJob = new MomoJobBuilder()
       .withName('name')
diff --git a/test/schedule/Schedule.spec.ts b/test/schedule/Schedule.spec.ts
@@ -97,6 +97,18 @@ describe('Schedule', () => {
       expect(momoJob.handler).toHaveBeenCalledTimes(1);
     });
 
+    it('runs a "never" job once', async () => {
+      await mongoSchedule.define({ ...momoJob, schedule: { interval: 'never' } });
+
+      when(jobRepository.findOne(deepEqual({ name: momoJob.name }))).thenResolve(entityWithId);
+      when(schedulesRepository.addExecution(momoJob.name, 0)).thenResolve({ added: true, running: 0 });
+
+      const result = await mongoSchedule.run(momoJob.name);
+
+      expect(result).toEqual({ status: ExecutionStatus.finished, handlerResult: 'finished' });
+      expect(momoJob.handler).toHaveBeenCalledTimes(1);
+    });
+
     it('does not run job once when job is not found', async () => {
       const result = await mongoSchedule.run('not defined');
 
diff --git a/test/scheduler/JobScheduler.spec.ts b/test/scheduler/JobScheduler.spec.ts
@@ -9,10 +9,11 @@ import { JobScheduler } from '../../src/scheduler/JobScheduler';
 import { MomoErrorType, momoError } from '../../src';
 import { loggerForTests } from '../utils/logging';
 import { sleep } from '../utils/sleep';
-import { CronSchedule } from '../../src/job/MomoJob';
+import { CronSchedule, NeverSchedule } from '../../src/job/MomoJob';
 import { JobEntity } from '../../src/repository/JobEntity';
 
 describe('JobScheduler', () => {
+  const debugFn = jest.fn();
   const errorFn = jest.fn();
 
   let schedulesRepository: SchedulesRepository;
@@ -32,15 +33,15 @@ describe('JobScheduler', () => {
     await jobScheduler.stop();
   });
 
-  function createJob<Schedule extends ParsedIntervalSchedule | CronSchedule>(
+  function createJob<Schedule extends ParsedIntervalSchedule | CronSchedule | NeverSchedule>(
     job: JobDefinition<Schedule>,
   ): JobDefinition<Schedule> {
     jobScheduler = new JobScheduler(
       job.name,
       instance(jobExecutor),
       instance(schedulesRepository),
       instance(jobRepository),
-      loggerForTests(errorFn),
+      loggerForTests(errorFn, debugFn),
     );
     const jobEntity: WithId<JobEntity> = {
       ...toJobDefinition(job),
@@ -51,6 +52,17 @@ describe('JobScheduler', () => {
     return job;
   }
 
+  function createNeverJob(partialJob: Partial<JobDefinition<NeverSchedule>> = {}): JobDefinition<NeverSchedule> {
+    const job: JobDefinition<NeverSchedule> = {
+      name: 'never job',
+      schedule: { interval: 'never' },
+      concurrency: 1,
+      maxRunning: 0,
+      ...partialJob,
+    };
+    return createJob(job);
+  }
+
   function createIntervalJob(
     partialJob: Partial<JobDefinition<ParsedIntervalSchedule>> = {},
   ): JobDefinition<ParsedIntervalSchedule> {
@@ -74,6 +86,15 @@ describe('JobScheduler', () => {
     });
   }
 
+  describe('single never job', () => {
+    it('does not start "never" job', async () => {
+      const job = createNeverJob();
+      await jobScheduler.start();
+
+      expect(debugFn).toHaveBeenCalledWith("do not start job specified to run 'never'", { name: job.name });
+    });
+  });
+
   describe('single interval job', () => {
     it('executes a job', async () => {
       createIntervalJob();
diff --git a/test/utils/logging.ts b/test/utils/logging.ts
@@ -19,9 +19,15 @@ export function initLoggingForTests(eventEmitter: TypedEmitter<MomoEvents>): voi
 
 export function loggerForTests(
   errorFn?: (message: string, type: MomoErrorType, data?: MomoEventData, error?: unknown) => void,
+  debugFn?: (message: string, data?: MomoEventData) => void,
 ): Logger {
   return {
-    debug: (message, data) => logger.info({ message, data }),
+    debug: (message, data) => {
+      logger.info({ message, data });
+      if (debugFn) {
+        debugFn(message, data);
+      }
+    },
     error: (message, type, data, error) => {
       errorLogger.error({ message, type, data, error });
       if (errorFn) {
