diff --git a/agenda/agenda-tests.ts b/agenda/agenda-tests.ts new file mode 100644 index 0000000000..bb887c5372 --- /dev/null +++ b/agenda/agenda-tests.ts @@ -0,0 +1,106 @@ +/// + +import Agenda from "agenda"; + + +var mongoConnectionString = "mongodb://127.0.0.1/agenda"; + +var agenda = new Agenda({ db: { address: mongoConnectionString } }); + + +agenda.define('delete old users', (job, done) => { + +}); + +agenda.on('ready', () => { + agenda.every('3 minutes', 'delete old users'); + + // Alternatively, you could also do: + agenda.every('*/3 * * * *', 'delete old users'); + + agenda.start(); +}); + +agenda.define('send email report', { priority: 'high', concurrency: 10 }, (job, done) => { +}); + +agenda.on('ready', () => { + agenda.schedule('in 20 minutes', 'send email report', { to: 'admin@example.com' }); + agenda.start(); +}); + +agenda.on('ready', () => { + var weeklyReport = agenda.create('send email report', { to: 'another-guy@example.com' }); + weeklyReport.repeatEvery('1 week').save(); + agenda.start(); +}); + +var agenda = new Agenda({ processEvery: '30 seconds' }); + +agenda.defaultConcurrency(5); + +var agenda = new Agenda({ defaultConcurrency: 5 }); + +agenda.lockLimit(0); + +var agenda = new Agenda({ lockLimit: 0 }); + +agenda.defaultLockLimit(0); + +var agenda = new Agenda({ defaultLockLimit: 0 }); + +agenda.defaultLockLifetime(10000); + +var agenda = new Agenda({ defaultLockLifetime: 10000 }); + +agenda.define('some long running job', function(job, done) { + done(); +}); + +agenda.every('15 minutes', ['printAnalyticsReport', 'sendNotifications', 'updateUserRecords']); + +agenda.schedule('tomorrow at noon', 'printAnalyticsReport', { userCount: 100 }); + +agenda.schedule('tomorrow at noon', ['printAnalyticsReport', 'sendNotifications', 'updateUserRecords']); + +agenda.now('do the hokey pokey'); + +var job = agenda.create('printAnalyticsReport', { userCount: 100 }); +job.save(function(err) { + console.log("Job successfully saved"); +}); + +agenda.jobs({ name: 'printAnalyticsReport' }, function(err, jobs) { + // Work with jobs (see below) +}); + +agenda.cancel({ name: 'printAnalyticsReport' }, function(err, numRemoved) { +}); + +agenda.purge(function(err, numRemoved) { +}); + +agenda.stop(function() { + process.exit(0); +}); + +job.repeatEvery('10 minutes'); + +job.repeatAt('3:30pm'); + +job.schedule('tomorrow at 6pm'); + +job.priority('low'); +job.priority(10); + +job.unique({ 'data.type': 'active', 'data.userId': '123' }); +job.fail('insuficient disk space'); +job.fail(new Error('insufficient disk space')); +job.run(function(err, job) { + console.log("I don't know why you would need to do this..."); +}); +job.remove(function(err) { + if (!err) console.log("Successfully removed job from collection"); +}) + + diff --git a/agenda/agenda.d.ts b/agenda/agenda.d.ts new file mode 100644 index 0000000000..a3d89789f4 --- /dev/null +++ b/agenda/agenda.d.ts @@ -0,0 +1,352 @@ +// Type definitions for Agenda v0.8.9 +// Project: https://github.com/rschmukler/agenda +// Definitions by: Meir Gottlieb +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped + +/// +/// + +declare module "agenda" { + + import {EventEmitter} from "events"; + import {Db, Collection} from "mongodb"; + + interface Callback { + (err?: Error): void; + } + + interface ResultCallback { + (err?: Error, result?: T): void; + } + + /** + * Agenda Configuration. + */ + interface AgendaConfiguration { + + /** + * Sets the interval with which the queue is checked. A number in milliseconds or a frequency string. + */ + processEvery?: string | number; + + /** + * Takes a number which specifies the default number of a specific job that can be running at any given moment. + * By default it is 5. + */ + defaultConcurrency?: number; + + /** + * Takes a number which specifies the max number of jobs that can be running at any given moment. By default it + * is 20. + */ + maxConcurrency?: number; + + /** + * Takes a number which specifies the default number of a specific job that can be locked at any given moment. + * By default it is 0 for no max. + */ + defaultLockLimit?: number; + + /** + * Takes a number shich specifies the max number jobs that can be locked at any given moment. By default it is + * 0 for no max. + */ + lockLimit?: number; + + /** + * Takes a number which specifies the default lock lifetime in milliseconds. By default it is 10 minutes. This + * can be overridden by specifying the lockLifetime option to a defined job. + */ + defaultLockLifetime?: number; + + /** + * Specifies that Agenda should be initialized using and existing MongoDB connection. + */ + mongo?: { + /** + * The MongoDB database connection to use. + */ + db: Db; + + /** + * The name of the collection to use. + */ + collection?: string; + } + + /** + * Specifies that Agenda should connect to MongoDB. + */ + db?: { + /** + * The connection URL. + */ + address: string; + + /** + * The name of the collection to use. + */ + collection?: string; + + /** + * Connection options to pass to MongoDB. + */ + options?: any; + } + } + + /** + * A scheduled job. + */ + interface Job { + + /** + * Specifies an interval on which the job should repeat. + * @param interval A human-readable format String, a cron format String, or a Number. + * @param options An optional argument that can include a timezone field. The timezone should be a string as + * accepted by moment-timezone and is considered when using an interval in the cron string format. + */ + repeatEvery(interval: string | number, options?: { timezone?: string }): Job + + /** + * Specifies a time when the job should repeat. [Possible values](https://github.com/matthewmueller/date#examples). + * @param time + */ + repeatAt(time: string): Job + + /** + * Disables the job. + */ + disable(): Job; + + /** + * Enables the job. + */ + enable(): Job; + + /** + * Ensure that only one instance of this job exists with the specified properties + * @param value The properties associated with the job that must be unqiue. + * @param opts + */ + unique(value: any, opts?: { insertOnly?: boolean }): Job; + + /** + * Specifies the next time at which the job should run. + * @param time The next time at which the job should run. + */ + schedule(time: string | Date): Job; + + /** + * Specifies the priority weighting of the job. + * @param value The priority of the job (lowest|low|normal|high|highest|number). + */ + priority(value: string | number): Job; + + /** + * Sets job.attrs.failedAt to now, and sets job.attrs.failReason to reason. + * @param reason A message or Error object that indicates why the job failed. + */ + fail(reason: string | Error): Job; + + /** + * Runs the given job and calls callback(err, job) upon completion. Normally you never need to call this manually + * @param cb Called when the job is completed. + */ + run(cb?: ResultCallback): Job; + + /** + * Returns true if the job is running; otherwise, returns false. + */ + isRunning(): boolean; + + /** + * Saves the job into the database. + * @param cb Called when the job is saved. + */ + save(cb?: ResultCallback): Job; + + /** + * Removes the job from the database and cancels the job. + * @param cb Called after the job has beeb removed from the database. + */ + remove(cb?: Callback): void; + + /** + * Resets the lock on the job. Useful to indicate that the job hasn't timed out when you have very long running + * jobs. + * @param cb Called after the job has been saved to the database. + */ + touch(cb?: Callback): void; + } + + interface JobOptions { + + /** + * Maximum number of that job that can be running at once (per instance of agenda) + */ + concurrency?: number; + + /** + * Maximum number of that job that can be locked at once (per instance of agenda) + */ + lockLimit?: number; + + /** + * Interval in ms of how long the job stays locked for (see multiple job processors for more info). A job will + * automatically unlock if done() is called. + */ + lockLifetime?: number; + + /** + * (lowest|low|normal|high|highest|number) specifies the priority of the job. Higher priority jobs will run + * first. + */ + priority?: string | number; + } + + export default class Agenda extends EventEmitter { + + /** + * Constructs a new Agenda object. + * @param config Optional configuration to initialize the Agenda. + * @param cb Optional callback called with the MongoDB colleciton. + */ + constructor(config?: AgendaConfiguration, cb?: ResultCallback); + + /** + * Connect to the specified MongoDB server and database. + */ + database(url: string, collection?: string, options?: any, cb?: ResultCallback): Agenda; + + /** + * Initialize agenda with an existing MongoDB connection. + */ + mongo(db: Db, collection?: string, cb?: ResultCallback): Agenda; + + /** + * Sets the agenda name. + */ + name(value: string): Agenda; + + /** + * Sets the interval with which the queue is checked. A number in milliseconds or a frequency string. + */ + processEvery(interval: string | number): Agenda; + + /** + * Takes a number which specifies the max number of jobs that can be running at any given moment. By default it + * is 20. + * @param value The value to set. + */ + maxConcurrency(value: number): Agenda; + + /** + * Takes a number which specifies the default number of a specific job that can be running at any given moment. + * By default it is 5. + * @param value The value to set. + */ + defaultConcurrency(value: number): Agenda; + + /** + * Takes a number shich specifies the max number jobs that can be locked at any given moment. By default it is + * 0 for no max. + * @param value The value to set. + */ + lockLimit(value: number): Agenda; + + /** + * Takes a number which specifies the default number of a specific job that can be locked at any given moment. + * By default it is 0 for no max. + * @param value The value to set. + */ + defaultLockLimit(value: number): Agenda; + + /** + * Takes a number which specifies the default lock lifetime in milliseconds. By default it is 10 minutes. This + * can be overridden by specifying the lockLifetime option to a defined job. + * @param value The value to set. + */ + defaultLockLifetime(value: number): Agenda; + + /** + * Returns an instance of a jobName with data. This does NOT save the job in the database. See below to learn + * how to manually work with jobs. + * @param name The name of the job. + * @param data Data to associated with the job. + */ + create(name: string, data: any): Job; + + /** + * Find all Jobs matching `query` and pass same back in cb(). + * @param query + * @param cb + */ + jobs(query: any, cb: ResultCallback): void; + + /** + * Removes all jobs in the database without defined behaviors. Useful if you change a definition name and want + * to remove old jobs. + * @param cb Called with the number of jobs removed. + */ + purge(cb?: ResultCallback): void; + + /** + * Defines a job with the name of jobName. When a job of job name gets run, it will be passed to fn(job, done). + * To maintain asynchronous behavior, you must call done() when you are processing the job. If your function is + * synchronous, you may omit done from the signature. + * @param name The name of the jobs. + * @param options The options for the job. + * @param handler The handler to execute. + */ + define(name: string, handler: (job?: Job, done?: (err?: Error) => void) => void): void; + define(name: string, options: JobOptions, handler: (job?: Job, done?: (err?: Error) => void) => void): void; + + /** + * Runs job name at the given interval. Optionally, data and options can be passed in. + * @param interval Can be a human-readable format String, a cron format String, or a Number. + * @param names The name or names of the job(s) to run. + * @param data An optional argument that will be passed to the processing function under job.attrs.data. + * @param options An optional argument that will be passed to job.repeatEvery. + * @param cb An optional callback function which will be called when the job has been persisted in the database. + */ + every(interval: number | string, names: string, data?: any, options?: any, cb?: ResultCallback): Job; + every(interval: number | string, names: string[], data?: any, options?: any, cb?: ResultCallback): Job[]; + + /** + * Schedules a job to run name once at a given time. + * @param when A Date or a String such as tomorrow at 5pm. + * @param names The name or names of the job(s) to run. + * @param data An optional argument that will be passed to the processing function under job.attrs.data. + * @param cb An optional callback function which will be called when the job has been persisted in the database. + */ + schedule(when: Date | string, names: string, data?: any, cb?: ResultCallback): Job; + schedule(when: Date | string, names: string[], data?: any, cb?: ResultCallback): Job[]; + + /** + * Schedules a job to run name once immediately. + * @param name The name of the job to run. + * @param data An optional argument that will be passed to the processing function under job.attrs.data. + * @param cb An optional callback function which will be called when the job has been persisted in the database. + */ + now(name: string, data?: any, cb?: ResultCallback): Job; + + /** + * Cancels any jobs matching the passed mongodb-native query, and removes them from the database. + * @param query Mongodb native query. + * @param cb Called with the number of jobs removed. + */ + cancel(query: any, cb?: ResultCallback): void; + + /** + * Starts the job queue processing, checking processEvery time to see if there are new jobs. + */ + start(): void; + + /** + * Stops the job queue processing. Unlocks currently running jobs. + * @param cb Called after the job processing queue shuts down and unlocks all jobs. + */ + stop(cb: Callback): void; + } +}