React Native Queue
Simple. Powerful. Persistent.
A React Native at-least-once priority job queue / task queue backed by persistent Realm storage. Jobs will persist until completed, even if user closes and re-opens app. React Native Queue is easily integrated into OS background processes (services) so you can ensure the queue will continue to process until all jobs are completed even if app isn't in focus. It also plays well with Workers so your jobs can be thrown on the queue, then processed in dedicated worker threads for greatly improved processing performance.
Table of Contents
- Features
- Example Use Cases
- Installation
- Basic Usage
- Options and Job Lifecycle Callbacks
- Testing with Jest
- Caveats
- Advanced Usage Examples
- Tutorials
Features
- 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, 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.
Example Use Cases
React Native Queue is designed to be a swiss army knife for task management in React Native. It abstracts away the many annoyances related to processing complex tasks, like durability, retry-on-failure, timeouts, chaining processes, and more. Just throw your jobs onto the queue and relax - they're covered.
Need advanced task functionality like dedicated worker threads or OS services? Easy:
- React Native Queue + React Native Background Task: Simple and Powerful OS services that fire when your app is closed.
- React Native Queue + React Native Workers: Spinning up dedicated worker threads for CPU intensive tasks has never been easier.
Example Queue Tasks:
- Downloading content for offline access.
- Media processing.
- Cache Warming.
- Durable API calls to external services, such as publishing content to a variety of 3rd party distribution channel APIs.
- Complex and time-consuming jobs that you want consistently processed regardless if app is open, closed, or repeatedly opened and closed.
- Complex tasks with multiple linked dependant steps (job chaining).
Installation
$ npm install --save react-native-queue
Or
$ yarn add react-native-queue
Then, because this package has a depedency on Realm you will need to link this native package by running:
$ react-native link realm
Linking realm should only be done once, reinstalling node_modules with npm or yarn does not require running the above command again.
To troubleshoot linking, refer to the realm installation instructions.
Basic Usage
React Native Queue is a standard job/task queue built specifically for react native applications. If you have a long-running task, or a large number of tasks, consider turning that task into a job(s) and throwing it/them onto the queue to be processed in the background instead of blocking your UI until task(s) complete.
Creating and processing jobs consists of:
- Importing and initializing React Native Queue
- Registering worker functions (the functions that execute your jobs).
- Creating jobs.
- Starting the queue (note this happens automatically on job creation, but sometimes the queue must be explicitly started such as in a OS background task or on app restart). Queue can be started with a lifespan in order to limit queue processing time.
; // Of course this line needs to be in the context of an async function, // otherwise use queueFactory.then((queue) => { console.log('add workers and jobs here'); });const queue = await ; // Register the worker function for "example-job" jobs.queue; // Create a couple "example-job" jobs. // Example job passes a payload of data to 'example-job' worker.// Default settings are used (note the empty options object).// Because false is passed, the queue won't automatically start when this job is created, so usually queue.start() // would have to be manually called. However in the final createJob() below we don't pass false so it will start the queue.// NOTE: We pass false for example purposes. In most scenarios starting queue on createJob() is perfectly fine.queue; // Create another job with an example timeout option set.// false is passed so queue still hasn't started up.queue; // This will automatically start the queue after adding the new job so we don't have to manually call queue.start().queue; console;
Options and Job Lifecycle Callbacks
Worker Options (includes async job lifecycle callbacks)
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.
queue;
Job Options
queue.createJob() accepts an options object in order to tweak standard functionality.
queue;
Testing with Jest
Because realm will write database files to the root test directory when running jest tests, you will need to add the following to your gitignore file if you use tests.
/reactNativeQueue.realm*
Caveats
Jobs must be idempotent. As with most queues, there are certain scenarios that could lead to React Native Queue processing a job more than once. For example, a job could timeout locally but remote server actions kicked off by the job could continue to execute. If the job is retried then effectively the remote code will be run twice. Furthermore, a job could fail due to some sort of exception halfway through then the next time it runs the first half of the job has already been executed once. Always design your React Native Queue jobs to be idempotent. If this is not possible, set job "attempts" option to be 1 (the default setting), and then you will have to write custom logic to handle the event of a job failing (perhaps via a job chain).
Advanced Usage Examples
Advanced Job Full Example
;; ; <{}> { superprops; thisstate = queue: null ; this; } async { const queue = await ; // // Standard Job Example // Nothing fancy about this job. // queue; // // Recursive Job Example // This job creates itself over and over. // let recursionCounter = 1; queue; // // Job Chaining Example // When job completes, it creates a new job to handle the next step // of your process. Breaking large jobs up into smaller jobs and then // chaining them together will allow you to handle large tasks in // OS background tasks, that are limited to 30 seconds of // execution every 15 minutes on iOS and Android. // queue; queue; queue; // Start queue to process any jobs that hadn't finished when app was last closed. queuestart; // Attach initialized queue to state. this; } { thisstatequeue; } { return <View style=stylescontainer> <Text style=styleswelcome> Welcome to React Native! </Text> thisstatequeue && <Button title="Press For Standard Example" onPress= { this } /> thisstatequeue && <Button title="Press For Recursive Example" onPress= { this } /> thisstatequeue && <Button title="Press For Job Chain Example" onPress= { this } /> </View> ; } const styles = StyleSheet;
OS Background Task Full Example
For the purpose of this example we will use the React Native Background Task module, but you could integrate React Native Queue with any acceptable OS background task module.
Follow the installation steps for React Native Background Task.
;; ; BackgroundTask; <{}> { superprops; thisstate = queue: null data: null ; this; } async { const queue = await ; // Add the worker. queue; // Attach initialized queue to state. this; } { BackgroundTask; // Schedule the task to run every ~15 min if app is closed. } { console; thisstatequeue; // Pass false so queue doesn't get started here (we want the queue to start only in OS background task in this example). } async { const lukeData = await AsyncStorage; const c3poData = await AsyncStorage; this; } { let output = 'No data loaded from OS background task yet.'; if thisstatedata output = JSON; return <View style=stylescontainer> <Text style=styleswelcome> Welcome to React Native! </Text> <Text>Click buttons below to add OS background task jobs</Text> <Text>Then Close </Text> <Text>Job will exec in ~15 min in OS background</Text> thisstatequeue && <Button title="Press To Queue Luke Skywalker Job" onPress= { this } /> thisstatequeue && <Button title="Press To Queue C-3PO Job" onPress= { this } /> <Button title="Check if Data was loaded in OS background" onPress= { this } /> <Text>output</Text> </View> ; } const styles = StyleSheet;
Tutorials
Easy OS Background Tasks in React Native
An in-depth guide to setting up background tasks / services that run periodically when the app is closed.