mongo-scheduler-more

Description

Persistent event scheduler using mongodb as storage.

Provide the scheduler with some storage and timing info and it will emit events with the corresponding document at the right time

This module, extend the original mongo-sheduler and work with up to date dependencies . You can also use the same event name multiple times, as long as the "id" and / or "after" is different, otherwise it will update the document.

And you can now use await / async with this module :) !

With this module, increase the performance of your Node.JS application !

You can completely replace your data scanning system in Data Base and more. Node.JS is EventDriven, exploit this power within your application!

You can visit my blog https://darkterra.fr/ for use case :)

Installation

npm install mongo-scheduler-more

Usage

Initialization

const MSM = require('mongo-scheduler-more');
const scheduler = new MSM('mongodb://localhost:27017/scheduler-db', options);

Arguments

connection <String> or <Object>

Type	Description	Optional
String or Object	Use for initiate the connexion with MongoDB, you can use an classical connexion string or a mongoose connection object.	false

options <Object>

Name	Type	Description	Driver Option	Optional
dbname	String	You can set (and overright) the name of DataBase to use. (only if you use the connexion string)	false	true
pollInterval	Number	Frequency in ms that the scheduler should poll the db. `Default: 60000 (1 minute)`.	false	true
doNotFire	Bool	If set to true, this instance will only schedule events, not fire them. `Default: false`.	false	true
customEventEmitter	Bool	You can pass an instance of custom eventEmitter if is compatible with the core Node.js EventEmmiter. But be carefull with this option	false	true
useNewUrlParser	Bool	If set to false, the mongo driver use the old parser. `Default: true`.	true	true
loggerLevel	String	The logging level (error / warn / info / debug).	true	true
logger	Object	Custom logger object.	true	true
validateOptions	Bool	Validate MongoClient passed in options for correctness. `Default: false` (only if you use the connection string)	true	true
auth	Object	{ user: 'your_ddb_user', password: 'your_ddb_password'}.	true	true
authMechanism	String	Mechanism for authentication: MDEFAULT, GSSAPI, PLAIN, MONGODB-X509, or SCRAM-SHA-1	true	true

How to use this module with custom eventEmitter

const EventEmitter3 = require('eventemitter3');
const customEventEmitter = new EventEmitter3();

const MSM = require('mongo-scheduler-more');
const scheduler = new MSM('mongodb://localhost:27017/scheduler-db', { customEventEmitter });

schedule()

schedule method allows to create event (stored in MongoDB) that will trigger according to the conditions described below.

Schedules the most basic event [callback]:

const moment = require('moment');
const event  = { name: 'basicUsage', after: moment().add(1, 'hours').toDate()};

scheduler.schedule(event, (err, result) => {
  if (err) {
    console.error(err);
  }
  else {
    // Do something with result event
  }
});
// This event should trigger the "scheduler.on('basicUsage', callback);" in one hour

If is your first scheduling event, it's create the scheduled_events collection with your first event stored.

You can also use the same event name multiple times, as long as the id and / or after is different, otherwise it will update the document stored in mongodb.

Schedules the most basic event [promise]:

const moment = require('moment');
const event  = { name: 'basicUsage', after: moment().add(1, 'hours').toDate()};

try {
  const result = await scheduler.schedule(event);
  // Do something with result event
}
catch (err) {
  console.error(err);
}
// This event should trigger the "scheduler.on('basicUsage', callback);" in one hour

Arguments

Event <Object>

Name	Type	Description	Optional
name	String	Name of event that should be fired.	false
after	Date	Time that the event should be triggered at, if left blank it will trigger the next time the scheduler polls.	true
id	ObjectId or String	_id field of the document this event corresponds to.	true
cron	String	(Override 'after'). A cron string representing a frequency this should fire on. Ex: `cron: '0 0 23 * * *'`, see: cron-parser.	true
endDate	Date	(Only if the cron option is use). Set a deadline to stop the infinite triggering of the cron option.	true
collection	Object	Name of the collection to use for the query parameter (just below) or for options.emitPerDoc.	true
query	Object	A MongoDB query expression to select document that this event should be triggered (only if the `collection` property is set) for. Ex: `{ payement: true }`, see: document-query-filter.	true
data	Object or Primitive	Extra data to attach to the event.	true
options	Object	If the property `emitPerDoc` === true and the collection property is setted, you will receave one js event for each doc found instead of array of found docs.	true

callback <Function> OR Promise

Name	Type	Description	Optional
err	String or Object	Tell you what wrong when the module try to create or update a schedule event	true
result	Object	The collection result callback. Contain 2 properties : `lastErrorObject`, `value`	true

Schedules an event with data (stored directly inside the event object) [callback]:

const moment = require('moment');
const event  = { 
  name: 'timeToCheckLicenceKey',
  after: moment().add(1, 'years').toDate(),
  data: 'First year offert ;)'
};

scheduler.schedule(event);
//
// This event (timeToCheckLicenceKey) should trigger in one year with extra data value

Schedules an event with data (stored directly inside the event object) [promise]:

const moment = require('moment');
const event  = { 
  name: 'timeToCheckLicenceKey',
  after: moment().add(1, 'years').toDate(),
  data: 'First year offert ;)'
};

try {
  await scheduler.schedule(event);
}
catch (err) {
  throw err;
}
// This event (timeToCheckLicenceKey) should trigger in one year with extra data value

Schedules an event with id (stored in the storage event object) [callback]:

const moment = require('moment');
const event  = {
  name: 'abandonedShoppingCart',
  id: '5a5dfd6c4879489ce958df0c',
  after: moment().add(15, 'minutes').toDate()
};

scheduler.schedule(event);
//
// This event trigger in 15 mins and allow my server to "remember" the shoppingCart _id: ('5a5dfd6c4879489ce958df0c')
// and let my server handle with to check if we need to remove this shopping cart

Schedules an event with id (stored in the storage event object) [promise]:

const moment = require('moment');
const event  = {
  name: 'abandonedShoppingCart',
  id: '5a5dfd6c4879489ce958df0c',
  after: moment().add(15, 'minutes').toDate()
};

try {
  await scheduler.schedule(event);
}
catch (err) {
  throw err;
}
//
// This event trigger in 15 mins and allow my server to "remember" the shoppingCart _id: ('5a5dfd6c4879489ce958df0c')
// and let my server handle with to check if we need to remove this shopping cart

Schedules an event with collection, query and cron [callback]:

const event  = {
  name: 'creditCardCheck',
  collection: 'users',
  query: {},
  cron: '0 0 23 * * *'
};

scheduler.schedule(event);
//
// This event is triggered daily at 23h00:00 and allows you to retrieve the list
// of all credit cards. When you receive the event, the server only has to send emails to users

Schedules an event with collection, query and cron [promise]:

const event  = {
  name: 'creditCardCheck',
  collection: 'users',
  query: {},
  cron: '0 0 23 * * *'
};

try {
  await scheduler.schedule(event);
}
catch (err) {
  throw err;
}
//
// This event is triggered daily at 23h00:00 and allows you to retrieve the list
// of all credit cards. When you receive the event, the server only has to send emails to users

Schedules an event with collection, query and cron with an end date [callback]:

const moment = require('moment');
const event  = {
  name: 'creditCardCheck',
  collection: 'users',
  query: { expire_next_month: true },
  cron: '0 0 10 * * *',
  endDate: moment().add(5, 'years').toDate()
};

scheduler.schedule(event);
//
// This event is triggered daily (for 5 years) at 10h00:00 and allows you to retrieve the list
// of credit cards that expires in a month. The server only has to send emails to users

Schedules an event with collection, query and cron with an end date [promise]:

const moment = require('moment');
const event  = {
  name: 'creditCardCheck',
  collection: 'users',
  query: { expire_next_month: true },
  cron: '0 0 10 * * *',
  endDate: moment().add(5, 'years').toDate()
};

try {
  await scheduler.schedule(event);
}
catch (err) {
  throw err;
}
//
// This event is triggered daily (for 5 years) at 10h00:00 and allows you to retrieve the list
// of credit cards that expires in a month. The server only has to send emails to users

Schedules whith `emitPerDoc` option [callback]:

/*
users collection:
[
  {
    username: 'A',
    actif: false,
    subscription: false,
  },
  {
    username: 'B',
    actif: true,
    subscription: false,
    need_to_pay_this_month: false,
  },
  {
    username: 'C',
    actif: true,
    subscription: true,
    need_to_pay_this_month: false,
  },
  {
    username: 'D',
    actif: true,
    subscription: true,
    need_to_pay_this_month: true,
  },
  {
    username: 'E',
    actif: true,
    subscription: true,
    need_to_pay_this_month: true,
  },
]
*/

const moment = require('moment');
const event  = {
  name: 'creditCardCheck',
  after: moment().add(15, 'minutes').toDate(),
  collection: 'users',
  query: { actif: true, subsciption: true, need_to_pay_this_month: true },
  options: { emitPerDoc: true }
};

scheduler.on('creditCardCheck', (event, doc) => {
  // Here beceause we use the emitPerDoc option and the query select only users how have actif: true, subsciption: true, need_to_pay_this_month: true
  // We get 2 emit (one for each result of the query)
});

scheduler.schedule(event);
//
// This event is triggered daily at 23h00:00 and allows you to retrieve the list
// of credit cards that expires in a month. The server only has to send emails to users

Schedules whith `emitPerDoc` option [promise]:

/*
users collection:
[
  {
    username: 'A',
    actif: false,
    subscription: false,
  },
  {
    username: 'B',
    actif: true,
    subscription: false,
    need_to_pay_this_month: false,
  },
  {
    username: 'C',
    actif: true,
    subscription: true,
    need_to_pay_this_month: false,
  },
  {
    username: 'D',
    actif: true,
    subscription: true,
    need_to_pay_this_month: true,
  },
  {
    username: 'E',
    actif: true,
    subscription: true,
    need_to_pay_this_month: true,
  },
]
*/

const moment = require('moment');
const event  = {
  name: 'creditCardCheck',
  after: moment().add(15, 'minutes').toDate(),
  collection: 'users',
  query: { actif: true, subsciption: true, need_to_pay_this_month: true },
  options: { emitPerDoc: true }
};

scheduler.on('creditCardCheck', (event, doc) => {
  // Here beceause we use the emitPerDoc option and the query select only users how have actif: true, subsciption: true, need_to_pay_this_month: true
  // We get 2 emit (one for each result of the query)
});

try {
  await scheduler.schedule(event);
}
catch (err) {
  throw err;
}

scheduleBulk()

scheduleBulk method allows to create multiple events at one time (stored in MongoDB) that will trigger according to the conditions described below.

Schedules the most basic event [callback]:

const events = [{ 
  name: 'event-to-bulk', 
  after: moment().add(15, 'm').toDate()
}, {
  name: 'event-to-bulk',
  after: moment().add(25, 'm').toDate()
}, {
  name: 'event-to-bulk',
  after: moment().add(8, 'm').toDate()
}, {
  name: 'event-to-bulk',
  after: moment().add(66, 'm').toDate()
}, {
  name: 'event-to-bulk',
  after: moment().add(5000, 'm').toDate()
}, {
  name: 'event-to-bulk',
  data: 'this is hacked scheduler !!!',
  after: moment().add(5000, 'm').toDate()  // This event has the same name and after value, so it will update the event just above
}];

scheduler.scheduleBulk(events, (err, result) => {
  if (err) {
    console.error(err);
  }
});
// This event should trigger the "scheduler.on('event-to-bulk', callback);" 8 min, and in 15 min, and in 15 min, and in 66 min, and in 5000 min

If is your first scheduling event, it's create the scheduled_events collection with your first event stored.

You can also use the same event name multiple times, as long as the id and / or after is different, otherwise it will update the document stored in mongodb.

Schedules the most basic event [promise]:

const events = [{ 
  name: 'event-to-bulk', 
  after: moment().add(15, 'm').toDate()
}, {
  name: 'event-to-bulk',
  after: moment().add(25, 'm').toDate()
}, {
  name: 'event-to-bulk',
  after: moment().add(8, 'm').toDate()
}, {
  name: 'event-to-bulk',
  after: moment().add(66, 'm').toDate()
}, {
  name: 'event-to-bulk',
  after: moment().add(5000, 'm').toDate()
}, {
  name: 'event-to-bulk',
  data: 'this is hacked scheduler !!!',
  after: moment().add(5000, 'm').toDate()  // This event has the same name and after value, so it will update the event just above
}];

try {
  await scheduler.scheduleBulk(events);
}
catch (err) {
  console.error(err);
}
// This event should trigger the "scheduler.on('event-to-bulk', callback);" 8 min, and in 15 min, and in 15 min, and in 66 min, and in 5000 min

Arguments

Events [<Object>]

Name	Type	Description	Optional
name	String	Name of event that should be fired.	false
after	Date	Time that the event should be triggered at, if left blank it will trigger the next time the scheduler polls.	true
id	ObjectId or String	_id field of the document this event corresponds to.	true
cron	String	(Override 'after'). A cron string representing a frequency this should fire on. Ex: `cron: '0 0 23 * * *'`, see: cron-parser.	true
endDate	Date	(Only if the cron option is use). Set a deadline to stop the infinite triggering of the cron option.	true
collection	Object	Name of the collection to use for the query parameter (just below).	true
query	Object	A MongoDB query expression to select document that this event should be triggered (only if the `collection` property is set) for. Ex: `{ payement: true }`, see: document-query-filter.	true
data	Object or Primitive	Extra data to attach to the event.	true

callback <Function> OR Promise

Name	Type	Description	Optional
err	String or Object	Tell you what wrong when the module try to create or update a schedule event	true
result	Object	The collection result callback.	true

scheduler.on

on method allows to listen trigger events (stored in MongoDB) described below.

Most basic event handler [callback]:

function callback (event) {
  console.log(`This is my basicUsage event content: ${event}`);
}

scheduler.on('basicUsage', callback);

Arguments

name <String>

Type	Description	Optional
String	Name of listened event	false

callback <Function>

Name	Type	Description	Optional
event	Object	This is the original event stored into MongoDB when you use the `scheduler.schedule()` function	true
docs	Object or Array	Return an array of docs if you use the properties `collection` and `query`. Return a single doc per triggered event when `emitPerDoc` is set to true, but there are as many triggered events as there are documents found by the 'query'	true

Event handler and data property [callback]:

function callback (event) {
  console.log(`This is my timeToCheckLicenceKey event content: ${event}`);
  
  // Do what you whant with this datas
}

scheduler.on('timeToCheckLicenceKey', callback);
// This handler will be fired in one year and the event object contain the "data" property

Event handler with the id property [callback]:

function callback (event) {
  console.log(`This is my abandonedShoppingCart event content: ${event}`);
  
  // Do what you whant with this datas
}

scheduler.on('abandonedShoppingCart', callback);
// This handler will be fired in 15 min and the event object contain the "id" property

Event handler with result [callback]:

function callback (event, docs) {
  console.log(`This is my creditCardCheck event content: ${event}`);
  console.log(`And this is the docs of the query saved when the event is declared: ${docs}`);
  
  // Do what you whant with this datas
}

scheduler.on('creditCardCheck', callback);
// Every days at 23h00:00, this event is trigger with the result query !

scheduler.list

list method allows to list all events (stored in MongoDB).

Get the list of all event saved [callback]:

const options = {};
scheduler.list(options, (err, events) => {
  // Do something with events, by default return by the date and time they were added to the db
});

Get the list of all event saved [promise]:

try {
  const options = {};
  const events = await scheduler.list(options);
  // Do something with events, by default return by the date and time they were added to the db
}
catch (err) {
  throw err;
}

Arguments

options <Object>

Name	Type	Description	Optional
bySchedule	Bool	Return list of events by schedule time (after property)	true
asc	Int	1 return ascendant schedule time. -1 return descendant schedule time `Default: 1`	true
query	Object	Filter the results like with valid mongodb query. For more infos take a look here	true

callback <Function> OR Promise

Name	Type	Description	Optional
err	String or Object	Tell you what wrong when the module try list all events	true
result	[Object]	List of object	true

scheduler.findByName

findByName method allows to get the first event by name (stored in MongoDB).

Find all event saved whith `abandonedShoppingCart` [callback]:

scheduler.findByName({ name: 'abandonedShoppingCart' }, (err, event) => {
  // Do something with events
});

Find all event saved whith `abandonedShoppingCart` [promise]:

try {
  const events = await scheduler.findByName({ name: 'abandonedShoppingCart' });
  // Do something with events
}
catch (err) {
  throw err;
}

Arguments

name <String>

Name	Type	Description	Optional
name	String	Name of listened event	false

callback <Function> OR Promise

Name	Type	Description	Optional
err	String or Object	Tell you what wrong when the module try trigger the event	true
event	Object	This is the original event stored into MongoDB when you use the `scheduler.schedule()` function	true

scheduler.findByStorageId

findByStorageId method allows to get the first event by id.

/!\ Be careful, this is not the id of the event itself, but the id stored in the id property (stored in MongoDB).

Find all event by id stored [callback]:

const params = { id: '5a5dfd6c4879489ce958df0c', name: 'abandonedShoppingCart' };
scheduler.findByStorageId(params, (err, event) => {
  // Do something with event
});

Find all event by id stored [promise]:

try {
  const params = { id: '5a5dfd6c4879489ce958df0c', name: 'abandonedShoppingCart' };
  const events = await scheduler.findByStorageId(params);
  // Do something with event
}
catch (err) {
  throw err;
}

Arguments

params <Object>

Name	Type	Description	Optional
id	ObjectId or String	The id searched (remember, this id is not the event itself id)	false
name	String	Name of listened event	true

callback <Function> OR Promise

Name	Type	Description	Optional
event	Object	This is the original event stored into MongoDB when you use the `scheduler.schedule()` function	true
result	Object or Array	If you use the properties `collection` and `query`, you get the result here.	true

scheduler.remove

remove method allows to remove events.

Remove all events saved whith `abandonedShoppingCart` [callback]:

const params = { name: 'abandonedShoppingCart' };
scheduler.remove(params, (err, event) => {
  // Event has been removed
});
// Remove every events find with the name = 'abandonedShoppingCart'

Remove all events saved whith `abandonedShoppingCart` [promise]:

try {
  const params = { name: 'abandonedShoppingCart' };
  const events = await scheduler.remove(params);
  // Event has been removed
}
catch (err) {
  throw err;
}
// Remove every events find with the name = 'abandonedShoppingCart'

Arguments

params <Object>

Name	Type	Description	Optional
name	String	Name of listened event	false
id	ObjectId or String	The id searched (remember, this id is not the event itself id)	true
eventId	ObjectId or String	This is the event id itself (you can use the 'list' method to get the event id)	true
after	Date	Remove only the events who have the exacte same date	true

callback <Function> OR Promise

Name	Type	Description	Optional
event	Object	This is the original event stored into MongoDB when you use the `scheduler.schedule()` function	true
result	Object or Array	If you use the properties `collection` and `query`, you get the result here	true

scheduler.purge

purge method allows to remove ALL events.

Remove all events [callback]:

const params = { force: true };
scheduler.purge(params, (err, event) => {
  // Event has been removed
});
// Remove every events

Remove all events [promise]:

try {
  const params = { force: true };
  const events = await scheduler.purge(params);
  // All event has been removed
}
catch (err) {
  throw err;
}
// Remove every events

Arguments

params <Object>

Name	Type	Description	Optional
force	Bool	It's a simple crazy guard, just not to delete all the events stored inadvertently	false

callback <Function> OR Promise

Name	Type	Description	Optional
event	Object	This is the original event stored into MongoDB when you use the `scheduler.schedule()` function	true
result	Object or Array	If you use the properties `collection` and `query`, you get the result here	true

scheduler.enable

enable method allows to enable scheduler.

scheduler.enable();

scheduler.disable

disable method allows to disable scheduler.

scheduler.disable();

scheduler.version

version this method show the actual version of mongo-scheduler-more.

WIP:

scheduler.version();
// Show in the console the actual version of mongo-scheduler-more

Error handling

If the scheduler encounters an error it will emit an 'error' event. In this case the handler, will receive two arguments: the Error object, and the event doc (if applicable).

Contribute

If you encounter problems, do not hesitate to create an issue (and / or pull requests) on the project github. If you like mongo-scheduler-more, do not hesitate to leave a star on the project github :)

License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 238 Commits
.github/workflows		.github/workflows
lib		lib
test		test
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
projectz.json		projectz.json

License

darkterra/mongo-scheduler

Folders and files

Latest commit

History

Repository files navigation

mongo-scheduler-more

Description

Installation

Usage

Initialization

Arguments

How to use this module with custom eventEmitter

schedule()

Schedules the most basic event [callback]:

Schedules the most basic event [promise]:

Arguments

Schedules an event with data (stored directly inside the event object) [callback]:

Schedules an event with data (stored directly inside the event object) [promise]:

Schedules an event with id (stored in the storage event object) [callback]:

Schedules an event with id (stored in the storage event object) [promise]:

Schedules an event with collection, query and cron [callback]:

Schedules an event with collection, query and cron [promise]:

Schedules an event with collection, query and cron with an end date [callback]:

Schedules an event with collection, query and cron with an end date [promise]:

Schedules whith emitPerDoc option [callback]:

Schedules whith emitPerDoc option [promise]:

scheduleBulk()

Schedules the most basic event [callback]:

Schedules the most basic event [promise]:

Arguments

scheduler.on

Most basic event handler [callback]:

Arguments

Event handler and data property [callback]:

Event handler with the id property [callback]:

Event handler with result [callback]:

scheduler.list

Get the list of all event saved [callback]:

Get the list of all event saved [promise]:

Arguments

scheduler.findByName

Find all event saved whith abandonedShoppingCart [callback]:

Find all event saved whith abandonedShoppingCart [promise]:

Arguments

scheduler.findByStorageId

Find all event by id stored [callback]:

Find all event by id stored [promise]:

Arguments

scheduler.remove

Remove all events saved whith abandonedShoppingCart [callback]:

Remove all events saved whith abandonedShoppingCart [promise]:

Arguments

scheduler.purge

Remove all events [callback]:

Remove all events [promise]:

Arguments

scheduler.enable

scheduler.disable

scheduler.version

WIP:

Error handling

Contribute

License

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 11

Packages 0

Languages

Schedules whith `emitPerDoc` option [callback]:

Schedules whith `emitPerDoc` option [promise]:

Find all event saved whith `abandonedShoppingCart` [callback]:

Find all event saved whith `abandonedShoppingCart` [promise]:

Remove all events saved whith `abandonedShoppingCart` [callback]:

Remove all events saved whith `abandonedShoppingCart` [promise]:

Packages