@tngtech/momo-scheduler

A scheduler that persists jobs in MongoDB

Showing:

Popularity

Downloads/wk

22

GitHub Stars

8

Maintenance

Last Commit

16d ago

Contributors

6

Package

Dependencies

7

License

Apache-2.0

Type Definitions

Built-In

Tree-Shakeable

No?

Categories

Readme

momo-scheduler

momo is a light-weight, easy-to-use interval-based scheduler that persists jobs in a MongoDB.

In essence, it provides an easy way to tell your application to "run that job every five minutes".

Features

  • allows concurrent jobs
  • allows immediate jobs
  • supports long-running jobs
  • allows error handling
  • allows updating jobs during runtime
  • supports cluster mode (e.g. several services using the same job database)

Installation

Install via npm:

npm install @tngtech/momo-scheduler

or yarn:

yarn add @tngtech/momo-scheduler

You're all set!

Usage

import { MongoSchedule, MomoJob, MomoErrorEvent, MomoEvent } from 'momo-scheduler';
import { MongoMemoryServer } from 'mongodb-memory-server';

const mongo = await MongoMemoryServer.create();
const mongoSchedule = await MongoSchedule.connect({ url: await mongo.getUri() });

const job: MomoJob = { name: 'momo test', interval: '1 minute', handler: () => console.log('This is momo') };
await mongoSchedule.define(job);

// optional: listen to error and debug events
mongoSchedule.on('error', (error: MomoErrorEvent) => { /* handle error */ });
mongoSchedule.on('debug', (debug: MomoEvent) => { /* ... */ });

await mongoSchedule.start();

// ...

await mongoSchedule.disconnect();

MomoJob

propertytypeoptionaldefaultdescription
namestringfalseThe name of the job. Used as a unique identifier.
intervalstringfalseSpecifies the time interval at which the job is started. Time intervals in human-readable formats (like '1 minute', 'ten days' or 'twenty-one days and 2 hours') are accepted. Check documentation of human-interval library for details.
immediatebooleantruefalseIf set to true AND the job was never run before, the job will be started immediately after start.
concurrencynumbertrue1How many instances of a job are started at a time.
maxRunningnumbertrue0Maximum number of job executions that is allowed at a time. Set to 0 for no max. The schedule will trigger no more job executions if maxRunning is reached. However, there is no guarantee that the schedule always respects the limit; in rare cases with multiple Momo instances maxRunning may be exceeded.
handlerfunctionfalseThe function to execute.

MongoSchedule

The start/stop/cancel/remove methods can take a job's name as an optional parameter. Only the job with the provided name is started/stopped/cancelled/removed. If there is no job with this name on the schedule, nothing is done. If the parameter is omitted, all jobs are started/stopped/cancelled/removed.

functionparametersdescription
defineMomoJobCreates a new MomoJob on the schedule.
startStarts jobs that are on the schedule.
stopStops jobs, but does not remove them from either the schedule or the database.
cancelStops and removes jobs from the schedule, does not remove them from the database.
removeStops and removes jobs from both the schedule and the database.
startJobstringStarts the job with the provided name (if on the schedule).
stopJobstringStops the job with the provided name (if on the schedule), but does not remove it from either the schedule or the database.
cancelJobstringStops and removes the job with the provided name (if on the schedule) from the schedule, does not remove it from the database.
removeJobstringStops and removes the job with the provided name (if on the schedule) from both the schedule and the database.
countboolean (optional)Returns the number of jobs on the schedule. Only started jobs are counted if parameter is set to true.
listReturns descriptions of all jobs on the schedule.
checkstringReturns execution information of the job with the provided name from the database. This also works if the job is not on the schedule.
clearRemoves all jobs from the database. This also removes jobs that are not on this schedule, but were defined by other schedules. However, does NOT stop job executions - this will cause currently running jobs to fail. Consider using stop/cancel/remove methods instead!
getstringReturns a description of the job. Returns undefined if no job with the provided name is defined.
runstringRuns the job with the provided name once, immediately. Note that maxRunning is respected, ie. the execution is skipped if the job is already running maxRunning times.
on'debug' or 'error', functionDefine a callback for debug or error events.

MomoJobDescription

The job description returned by the list and getfunctions contains the following properties:

propertytypeoptionaldescription
namestringfalseThe name of the job. Used as a unique identifier.
intervalstringfalseSpecifies the time interval at which the job is started.
concurrencynumberfalseHow many instances of a job are started at a time.
maxRunningnumberfalseMaximum number of job executions that is allowed at a time. Set to 0 for no max. The job will not be started anymore if maxRunning is reached.
schedulerStatus{ interval: string, running: number }trueOnly present if the job was started, reports the number of currently running executions of the job and the time interval at which job execution is triggered. This might differ from the top-level interval as the interval of an already started job is not changed automatically when the job is updated.

The MongoSchedule is an EventEmitter, emitting 'debug' and 'error' events. You can define callbacks to handle them:

mongoSchedule.on('error', ({ error, data, message, type }: MomoErrorEvent) => {
  console.log(`An error of type ${type} occurred`, { error, data, message });
});

mongoSchedule.on('debug', ({ data, message }: MomoEvent) => {
  console.log('A debug event occurred', { data, message });
});

MomoEvent and MomoErrorEvent

eventpropertytypedescription
bothmessagestringSome information about the event that occurred.
bothdata (optional){ name?: string; ... }Contains additional information like the name of the affected job.
errortypeMomoErrorType'defining job failed' or 'scheduling job failed' or 'executing job failed' or 'stopping job failed'
errorerror (optional)ErrorThe root cause of the error.

License

This project is open source and licensed under Apache 2.0.

Licenses and Copyrights of dependencies can be found in THIRD_PARTY_NOTICE for the latest release.

For contribution guidelines see CONTRIBUTING.md.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100