Added Job lifecycle callbacks functionality.

Author: billmalarky

Models/Queue.js

@@ -308,7 +308,9 @@ export class Queue {
 
   /**
    *
-   * Execute a job.
+   * Process a job.
+   *
+   * Job lifecycle callbacks are called as appropriate throughout the job processing lifecycle.
    *
    * Job is deleted upon successful completion.
    *
@@ -321,25 +323,39 @@ export class Queue {
    */
   async processJob(job) {
 
+    // Data must be cloned off the realm job object for several lifecycle callbacks to work correctly.
+    // This is because realm job is deleted before some callbacks are called if job processed successfully.
+    // More info: https://github.com/billmalarky/react-native-queue/issues/2#issuecomment-361418965
+    const jobName = job.name;
+    const jobId = job.id;
+    const jobPayload = JSON.parse(job.payload);
+
+    // Fire onStart job lifecycle callback
+    this.worker.executeJobLifecycleCallback('onStart', jobName, jobId, jobPayload);
+
     try {
 
       await this.worker.executeJob(job);
 
-      // On job completion, remove job
+      // On successful job completion, remove job
       this.realm.write(() => {
 
         this.realm.delete(job);
 
       });
 
+      // Job has processed successfully, fire onSuccess and onComplete job lifecycle callbacks.
+      this.worker.executeJobLifecycleCallback('onSuccess', jobName, jobId, jobPayload);
+      this.worker.executeJobLifecycleCallback('onComplete', jobName, jobId, jobPayload);
+
     } catch (error) {
 
       // Handle job failure logic, including retries.
+      let jobData = JSON.parse(job.data);
+
       this.realm.write(() => {
 
         // Increment failed attempts number
-        let jobData = JSON.parse(job.data);
-
         if (!jobData.failedAttempts) {
           jobData.failedAttempts = 1;
         } else {
@@ -365,6 +381,15 @@ export class Queue {
 
       });
 
+      // Execute job onFailure lifecycle callback.
+      this.worker.executeJobLifecycleCallback('onFailure', jobName, jobId, jobPayload);
+
+      // If job has failed all attempts execute job onFailed and onComplete lifecycle callbacks.
+      if (jobData.failedAttempts >= jobData.attempts) {
+        this.worker.executeJobLifecycleCallback('onFailed', jobName, jobId, jobPayload);
+        this.worker.executeJobLifecycleCallback('onComplete', jobName, jobId, jobPayload);
+      }
+
     }
 
   }

Models/Worker.js

@@ -41,7 +41,12 @@ export default class Worker {
 
     // Attach options to worker
     worker.options = {
-      concurrency: options.concurrency || 1
+      concurrency: options.concurrency || 1,
+      onStart: options.onStart || null,
+      onSuccess: options.onSuccess || null,
+      onFailure: options.onFailure || null,
+      onFailed: options.onFailed || null,
+      onComplete: options.onComplete || null
     };
 
     Worker.workers[jobName] = worker;
@@ -119,4 +124,35 @@ export default class Worker {
 
   }
 
+  /**
+   *
+   * Execute an asynchronous job lifecycle callback associated with related worker.
+   *
+   * @param callbackName {string} - Job lifecycle callback name.
+   * @param jobName {string} - Name associated with jobs assigned to related worker.
+   * @param jobId {string} - Unique id associated with job.
+   * @param jobPayload {object} - Data payload associated with job.
+   */
+  async executeJobLifecycleCallback(callbackName, jobName, jobId, jobPayload) {
+
+    // Validate callback name
+    const validCallbacks = ['onStart', 'onSuccess', 'onFailure', 'onFailed', 'onComplete'];
+    if (!validCallbacks.includes(callbackName)) {
+      throw new Error('Invalid job lifecycle callback name.');
+    }
+
+    // Fire job lifecycle callback if set.
+    // Uses a try catch statement to gracefully degrade errors in production.
+    if (Worker.workers[jobName].options[callbackName]) {
+
+      try {
+        await Worker.workers[jobName].options[callbackName](jobId, jobPayload);
+      } catch (error) {
+        console.error(error); // eslint-disable-line no-console
+      }
+
+    }
+
+  }
+
 }

README.md

@@ -17,7 +17,7 @@ A React Native at-least-once priority job queue / task queue backed by persisten
 * [Example Use Cases](#example-use-cases)
 * [Installation](#installation)
 * [Basic Usage](#basic-usage)
-* [Options](#options)
+* [Options and Job Lifecycle Callbacks](#options-and-job-lifecycle-callbacks)
 * [Testing with Jest](#testing-with-jest)
 * [Caveats](#caveats)
 * [Advanced Usage Examples](#advanced-usage-examples)
@@ -30,7 +30,7 @@ A React Native at-least-once priority job queue / task queue backed by persisten
 * **Simple API:** Set up job workers and begin creating your jobs in minutes with just two basic API calls
   * queue.addWorker(name, workerFunction, options = {})  
   * queue.createJob(name, payload = {}, options = {}, startQueue = true) 
-* **Powerful options:** Easily modify default functionality. Set job timeouts, number of retry attempts, priority, and worker concurrency with an options object. Start queue processing with a lifespan to easily meet OS background task time limits.
+* **Powerful options:** Easily modify default functionality. Set job timeouts, number of retry attempts, priority, job lifecycle callbacks, and worker concurrency with an options object. Start queue processing with a lifespan to easily meet OS background task time limits.
 * **Persistent Jobs:** Jobs are persisted with Realm. Because jobs persist, you can easily continue to process jobs across app restarts or in OS background tasks until completed or failed (or app is uninstalled).
 * **Powerful Integrations:** React Native Queue was designed to play well with others. The queue quickly integrates with a variety of OS background task and Worker packages so  processing your jobs in a background service or dedicated thread have never been easier.
 
@@ -147,19 +147,63 @@ console.log('The above jobs are processing in the background of app now.');
 
 ```
 
-## Options
+## Options and Job Lifecycle Callbacks
 
-#### Worker Options
+#### Worker Options (includes async job lifecycle callbacks)
 
-queue.addWorker() accepts an options object in order to tweak standard functionality.
+queue.addWorker() accepts an options object in order to tweak standard functionality and allow you to hook into asynchronous job lifecycle callbacks.
+
+**IMPORTANT: Job Lifecycle callbacks are called asynchronously.** They do not block job processing or each other. Don't put logic in onStart that you expect to be completed before the actual job process begins executing. Don't put logic in onFailure you expect to be completed before onFailed is called. You can, of course, assume that the job process has completed (or failed) before onSuccess, onFailure, onFailed, or onComplete are asynchonrously called.
 
 ```js
 
-queue.addWorker('job-name-here', (id, payload) => { console.log(id); }, {
+queue.addWorker('job-name-here', async (id, payload) => { console.log(id); }, {
 
   // Set max number of jobs for this worker to process concurrently.
   // Defaults to 1.
-  concurrency: 5
+  concurrency: 5,
+  
+  // JOB LIFECYCLE CALLBACKS
+  
+  // onStart job callback handler is fired when a job begins processing.
+  //
+  // IMPORTANT: Job lifecycle callbacks are executed asynchronously and do not block job processing 
+  // (even if the callback returns a promise it will not be "awaited" on).
+  // As such, do not place any logic in onStart that your actual job worker function will depend on,
+  // this type of logic should of course go inside the job worker function itself.
+  onStart: async (id, payload) => {
+    
+    console.log('Job "job-name-here" with id ' + id + ' has started processing.');  
+    
+  },
+  
+  // onSuccess job callback handler is fired after a job successfully completes processing.
+  onSuccess: async (id, payload) => {
+    
+    console.log('Job "job-name-here" with id ' + id + ' was successful.');
+    
+  },
+  
+  // onFailure job callback handler is fired after each time a job fails (onFailed also fires if job has reached max number of attempts).
+  onFailure: async (id, payload) => {
+    
+    console.log('Job "job-name-here" with id ' + id + ' had an attempt end in failure.');
+    
+  },
+  
+  // onFailed job callback handler is fired if job fails enough times to reach max number of attempts.
+  onFailed: async (id, payload) => {
+    
+    console.log('Job "job-name-here" with id ' + id + ' has failed.');
+    
+  },
+  
+  // onComplete job callback handler fires after job has completed processing successfully or failed entirely.
+  onComplete: async (id, payload) => {
+    
+    console.log('Job "job-name-here" with id ' + id + ' has completed processing.');
+    
+  }
 
 });