Apologies for the commit churn -- It's taking a little while to get my build/test configuration running in a Docker container....

I have undone the destructuring syntax, and fixed the test (grrr, so I thought... Tests are failing due to timeout; I still have a lot to learn aboue bee-queue and bee-queue testing...).

The question about emitting both 'failed' and 'retrying' is interesting. My gut reaction is that the two messages is a more surprising behavior than what the docs imply will happen, and what the names of the events imply. But, two messages doesn't contradict what the docs say, and the retrying docs even mention that the job being retried has just failed. But that's also just being explicit -- 'retrying' means the job failed.

Emitting only one of 'retrying' or 'failed' for the queue when a job fails seems less surprising. It's what the PubSub events do. It's what the jobs do. The retrying messages let you know the job is still viable. 'succeeded' or 'failed' are the final word on the job. Otherwise you have to actively dig around in implementation-specific details to make a determination about the job's final status...

Indeed, the reason I filed the issue, #184 was that Queue Local is a simple way to manage job lifecycle that didn't have the complexity or overhead of the PubSub or the Job callbacks. It would be very surprising that Queue Local callbacks have different semantics than the other two sets, and have no simple way to know if a job has really failed yet...

I agree with everything you're saying, and I don't think we're in a position to ship a new major revision of the library. Shipping the change that makes retrying fire instead of failed represents a major change in the API surface and since we don't know what downstream folks are doing with the library this can break their expectations (even though the API does seem like it should only emit one or the other). Maybe as a compromise we can create a new event on the Queue like failure:final or finalFailure that signals that a job has finished and is not being retried, and in bee-queue v2 can remove or deprecate the new event in favor of a fixed failure event.

Thanks also for pointing out the documentation/confusion problems here - I think we can help with that some with more documentation, but I don't see an optimal/foolproof solution here.

I agree.

Here's the simplest path forward that I can see:

• we make no code changes
• we update the documentation to remove any mention of a Queue Local 'retrying' event
• we update the Queue Local 'failed' documentation to be explicit that:
  • all job failures emit the event, regardless of whether the job will be retried
  • using only Queue Local events, there is no simple, stateless way to determine that a job has failed for good (won't be retried)
  • perhaps mention job.status as a potential work-around in the disclaimer regarding Queue Local events and job failure? (At present it is only documented in example code for Queue#getJob -- not sure if you want to promote job.status as a bona-fide feature? -- would definitely want to protect it with a getter)
• we add a comment or two to the code regarding how things could be changed in order to unify the 'succeeded', 'retrying', 'failed' callbacks across the three classes of events