Can we have some more clarity on moving jobs and throwing specific errors?

[devlzcode]

There is a specific interaction when using job#moveToDelayed and then throwing a DelayedError that while it exists in the documentation, it is not explained why we should do this. Also it isn't shown anywhere in the docs (the property is of course shown in the API reference) what token is or what token should be. A good example of where a concept like this is properly clarified is when UnrecoverableError is shown how to be used.

EDIT: I think it would also help if you provided clarity on what context certain functions should/can be used in. E.g., you can not use job#moveToCompleted inside of a job processor function because when it completes it will try to acquire the lock which is now missing because it was moved. However if you throw a DelayedError it will not complain, which is expectedly unexpected behavior because it isn't a delay, nor is this pattern shown to be used anywhere outside of job#moveToDelayed. Maybe rename DelayedError to something like Passthrough (note the removal of -Error since it isn't exactly an error)?

EDIT 2: Alternatively, throw passthrough(options?). This pattern is used in Remix, a React framework when redirecting a user in an action, e.g. throw redirect(302).

[manast]

There is some information on how to use DelayedError here: https://docs.bullmq.io/patterns/process-step-jobs#delaying I noticed that the "token" is missing on the example though, it should be the second parameter of the processor function. But you are right, we could improve the documentation in some areas explaining more about the underlying mechanisms that make the special error types necessary.

[manast]

hmm, yes, I think this is actually a recent addition, so you could also use the job.token as they will be the same. We cannot just remove the second parameter as that would be a breaking change.

[devlzcode]

The doc updates you made were great however the section right after uses the WaitingChildrenError. Is there any difference between the two errors, or do they do the same thing but are just named differently? Clarifying this error's use case as well would be nice.

[devlzcode]

Checking the source code, yeah they do the same thing.

[manast]

I will write a section just on the processor predefined errors as these are a new concept that we introduced recently and I did not expect it to grow so much.

[devlzcode]

Alright thanks. I really appreciate your concern for the documentation and seeing you do this for all other discussions, you make the service as a whole much better!