New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documention to Job#moveToCompleted/Failed #1017

Merged
merged 5 commits into from Aug 20, 2018
Merged
Diff settings

Always

Just for now

Copy path View file
@@ -10,6 +10,7 @@ Here are a few examples of useful patterns that are often implemented with Bull:
- [Redis Cluster](#redis-cluster)
- [Debugging](#debugging)
- [Custom backoff strategy](#custom-backoff-strategy)
- [Async multiple-repo job processor](#async-multiple-repo-job-processor)

If you have any other common patterns you want to add, pull request them!

@@ -197,3 +198,52 @@ myQueue.add({msg: 'Specific Error'}, {
}
});
```

Manually fetching jobs
----------------------------------

If you want the actual job processing to be done in a seperate repo/service than where `bull` is running, this pattern may be for you.

Manually transitioning states for jobs can be done with a few simple methods.

1. Adding a job to the 'waiting' queue. Grab the queue and call `add`.

```typescript
import Queue from "bull";
const queue = new Queue(description, queueOptions);
queue.add({ random_attr: "random_value" });
```

2. Pulling a job from 'waiting' and moving it to 'active'.

```typescript
const job: Job = await queue.getNextJob();
```

3. Move the job to the 'failed' queue if something goes wrong.

```typescript
const (nextJobData, nextJobId) = await job.moveToFailed(
{
message: "Call to external service failed!",
},
true,
);
```

3. Move the job to the 'completed' queue.

```typescript
const (nextJobData, nextJobId) = await job.moveToCompleted("succeeded", true);
```

4. Return the next job if one is returned.

```typescript
if (nextJobdata) {
return Job.fromJSON(queue, nextJobData, nextJobId);
}
```

Then you can easily wrap `bull` in an API for use with external systems.
Copy path View file
@@ -37,6 +37,8 @@ Reference
- [Job#discard](#jobdiscard)
- [Job#promote](#jobpromote)
- [Job#finished](#jobfinished)
- [Job#moveToCompleted](#jobMoveToCompleted)
- [Job#moveToFailed](#moveToFailed)

- [Events](#events)
- [Global events](#global-events)
@@ -694,6 +696,26 @@ Returns a promise that resolves or rejects when the job completes or fails.

---

### Job#moveToCompleted

```ts
moveToCompleted(returnValue, ignoreLock): Promise<string[Jobdata, JobId] | null>
```

Moves a job to the `completed` queue. Pulls a job from 'waiting' to 'active' and returns a tuple containing the next jobs data and id. If no job is in the `waiting` queue, returns null.

---

### Job#moveToFailed

```ts
moveToFailed(errorInfo, ignoreLock): Promise<string[Jobdata, JobId] | null>
```

Moves a job to the `failed` queue. Pulls a job from 'waiting' to 'active' and returns a tuple containing the next jobs data and id. If no job is in the `waiting` queue, returns null.

---


Events
------
Copy path View file
@@ -179,6 +179,13 @@ Job.prototype.releaseLock = function() {
});
};

/**
* Moves a job to the completed queue.
* Returned job to be used with Queue.prototype.nextJobFromJobData.
* @param returnValue {string} The jobs success message.
* @param ignoreLock {boolean} True when wanting to ignore the redis lock on this job.
* @returns {Promise} Returns the jobData of the next job in the waiting queue.
*/
Job.prototype.moveToCompleted = function(returnValue, ignoreLock) {
this.returnvalue = returnValue || 0;

@@ -200,6 +207,12 @@ Job.prototype.discard = function() {
this._discarded = true;
};

/**
* Moves a job to the failed queue.
* @param err {string} The jobs error message.
* @param ignoreLock {boolean} True when wanting to ignore the redis lock on this job.
* @returns void
*/
Job.prototype.moveToFailed = function(err, ignoreLock) {
var _this = this;
this.failedReason = err.message;
Copy path View file
@@ -297,22 +297,25 @@ describe('Job', function() {
});

describe('.moveToCompleted', function() {
it('marks the job as completed', function() {
return Job.create(queue, { foo: 'bar' }).then(function(job) {
return job
.isCompleted()
.then(function(isCompleted) {
expect(isCompleted).to.be(false);
})
.then(function() {
return job.moveToCompleted('succeeded', true);
})
.then(function(/*moved*/) {
return job.isCompleted().then(function(isCompleted) {
expect(isCompleted).to.be(true);
expect(job.returnvalue).to.be('succeeded');
it('marks the job as completed and returns new job', function() {
return Job.create(queue, { foo: 'bar' }).then(function(job1) {
return Job.create(queue, { foo: 'bar' }).then(function(job2) {
return job2
.isCompleted()
.then(function(isCompleted) {
expect(isCompleted).to.be(false);
})
.then(function() {
return job2.moveToCompleted('succeeded', true);
})
.then(function(job1Id) {
return job2.isCompleted().then(function(isCompleted) {
expect(isCompleted).to.be(true);
expect(job2.returnvalue).to.be('succeeded');
expect(job1Id[1]).to.be(job1.id);
});
});
});
});
});
});
});
ProTip! Use n and p to navigate between commits in a pull request.