From 13b9383974fdac14c14762678034346715398f5e Mon Sep 17 00:00:00 2001 From: Oskari Okko Ojala Date: Thu, 6 Aug 2026 10:56:10 +0300 Subject: [PATCH] docs(interfaces): clarify that `attempts` is 1-indexed during a run `attempts` is incremented when a job is locked for execution, so a running handler sees `attempts === 1` on the first run and `attempts === max_attempts` on the final run. The previous wording ("How many times it has been attempted") is easy to misread as "prior failures", which leads to off-by-one final-attempt checks. Spell out the semantics on `attempts` and refine the related `last_error` comment, which read as inaccurate for the first in-flight attempt. --- src/interfaces.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/interfaces.ts b/src/interfaces.ts index 9a9c5202..4be98890 100644 --- a/src/interfaces.ts +++ b/src/interfaces.ts @@ -475,11 +475,17 @@ export interface DbJob { priority: number; /** When it was due to run */ run_at: Date; - /** How many times it has been attempted */ + /** + * The number of attempts made so far, including any attempt currently in + * progress. Incremented atomically each time the job is locked for execution, + * so during a running handler this counts the in-flight attempt: + * `attempts === 1` on the first run and `attempts === max_attempts` on the + * final run. + */ attempts: number; /** The limit for the number of times it should be attempted */ max_attempts: number; - /** If attempts > 0, why did it fail last? */ + /** The error message from the previous failed attempt, if any (null on the first run). */ last_error: string | null; created_at: Date; updated_at: Date;