+
+
+ 
+
+-Before using bulls-eye, please consider if it is the right solution for your problem. Here's a bunch of cool things it can do: +## Starting -- Run arbitrary or scheduled (like in cron) jobs in the background. -- Set prios, retry, pause, resume and limit the rate of your jobs. -- Concurrently run in a sandboxed process that will not crash your app. -- Render a UI in your app with all the info you'll need to manage the jobs. +To add it to your project start by adding the library to your dependencies list: -Most background jobs tools depend on multiple processes to work. This means you would need to use something like a Procfile to keep your server and all your workers running. bulls-eye will use your node service process as the manager of executions and (if you so wish) spawn child processes in your instances to deal with the workload. +```sh +yarn add bulls-eye +``` -On the other hand this is also one of its disadvantages. That is, you probably should not use bulls-eye if: +Or -- you can't afford your server to be doing something else than serving requests. - - in this case, consider having a separate service to be a queue manager, or lambdas. -- you need to aggressively scale your workers independently of your instances. - - in this case, probably lambdas. -- all you need is a simple cron job (UI is just a luxury). - - use a cron job. perhaps [node-cron](https://www.npmjs.com/package/node-cron)? +```sh +npm i bulls-eye +``` ## Hello world +Remember that it depends on Redis as well, so the first step is to configure all of your queues: + ```js -const { createQueues, UI } = require('bulls-eye') +const { createQueues } = require('bulls-eye') -const queues = createQueues(redisConfig) // sets up your queues +const redisConfig = { + redis: { + port: process.env.REDIS_PORT, + host: process.env.REDIS_HOST, + password: process.env.REDIS_PASSWORD, + }, +} + +const queues = createQueues(redisConfig) +``` +And then you can setup how your queues will work: + +```js const helloQueue = queues.add('helloQueue') // adds a queue +// defines how the queue works helloQueue.process(async job => { console.log(`Hello ${job.data.hello}`) -}) // defines how the queue works +}) helloQueue.add({ hello: 'world' }) // adds a job to the queue +``` + +And finally, add `UI` to your middlewares (this can be set up using an admin endpoint with some authentication method): -app.use('/queues', UI) // serves the UI at /queues, don't forget authentication! +```js +const app = require('express')() +const { UI } = require('bulls-eye') + +app.use('/admin/queues', UI) + +// other configurations for your server ``` +## Developing + +To try it out locally you can clone this repo and run: + +```sh +yarn && yarn start:example +``` + +Just make sure you spin up a Redis instance locally (default port is 6379). + ## Further ref -For further ref, please check [bull's docs](https://github.com/OptimalBits/bull). Appart from the way you config and start your UI, this library doesn't hijack bull's way of working. +For further ref, please check [Bull's docs](https://optimalbits.github.io/bull/). Apart from the way you configure and start your UI, this library doesn't hijack Bull's way of working. + +If you want to learn more about queues and Redis: https://redis.io/ ## UI diff --git a/package.json b/package.json index e7e37990b..c2016601a 100644 --- a/package.json +++ b/package.json @@ -16,9 +16,10 @@ }, "scripts": { "build": "NODE_ENV=production webpack", - "start:example": "node example.js", - "start": "yarn watch & yarn start:example", - "watch": "NODE_ENV=production webpack --watch" + "build:watch": "NODE_ENV=production webpack --watch", + "start": "node example.js", + "start:dev": "yarn build:watch && yarn start", + "start:example": "yarn build && yarn start" }, "devDependencies": { "babel-preset-react-app": "^7.0.2",