DeepScan

What should hold

Each key has its own bucket, and the asynchronous resolve function is called once per key to determine that key's capacity and refill rate.

The promise

A key never gets more than capacity requests admitted in a burst, no matter how many calls are in flight.

README.md:71 CONCRETE

The code

   */  async check(key: string, cost = 1): Promise<Decision> {    let bucket = this.buckets.get(key);    if (!bucket) {      const limits = await this.resolve(key);      bucket = new TokenBucket({ ...limits, clock: this.clock });      this.buckets.set(key, bucket);    }    const allowed = bucket.tryTake(cost);

What happens

Call check("k") several times concurrently on a new key with a resolver returning { capacity: 1, ratePerSec: 1 }. Each call sees no stored bucket before awaiting resolve; after the await, each creates its own full bucket and admits one request before storing it. Thus multiple requests are admitted in the burst and resolve runs multiple times for the same key. The README promises one resolver call per key and a burst capped at capacity (README.md:69-72).

How to trigger it

Using the public KeyedRateLimiter export, create a limiter whose async resolve increments a counter and returns { capacity: 1, ratePerSec: 1 }. Run await Promise.all([limiter.check("k"), limiter.check("k"), limiter.check("k")]) immediately. All three decisions can be allowed and the counter becomes 3, instead of one allowed decision and one resolver call as promised.

Behaves correctly here

Sequential checks share the stored bucket: the test's sequential lookup case confirms one resolver call for two checks, then another only after reset (test/ratelimit.test.ts:57-70).

Fixes that don't work

• Checking buckets again after resolving but still creating a bucket before the check is insufficient; callers must use the already-installed bucket to share its tokens.
• Caching only the resolved limits would satisfy the lookup count but not the burst cap if each concurrent caller still creates and consumes a separate TokenBucket.

A maintainer's best answer, and why it doesn't hold

There is no reasonable one-line justification: the README explicitly promises the burst cap even when calls are in flight, and concurrent initialization defeats it.

What should hold

A job with maxAttempts set to N is executed no more than N times in total, counting its first execution.

The promise

- Attempts. maxAttempts is the total number of executions, including the first one. A job with maxAttempts: 3 runs at most three times.

README.md:36 CONCRETE

The code

      this.emitter.emit("completed", job);    } catch (err) {      job.attempts += 1;      job.error = err instanceof Error ? err.message : String(err);      if (job.attempts <= job.maxAttempts) {        job.status = "queued";        job.runAt = this.clock.now() + computeBackoff(this.backoff, job.attempts, this.random);

What happens

Enqueue a job with maxAttempts: 3 and register a handler that always throws. After the first failure, attempts is 1 and the <= 3 check requeues it; the same happens after failures two and three. The third failure therefore still makes it eligible for another execution, and the fourth invocation finally increments attempts to 4 and marks the job failed. The handler runs four times, despite the README promise of at most three.

How to trigger it

Using the public API, create new JobQueue({ backoff: { baseDelayMs: 0, maxDelayMs: 0, factor: 2 } }), register a handler that throws, and enqueue with { maxAttempts: 3 }. Call processNext() four times; zero backoff makes the job immediately ready after each of its first three failures. The handler is called four times, while the README says it should run at most three.

Behaves correctly here

A handler that succeeds on its first invocation completes without being requeued: the success path increments attempts and marks the job done (src/queue/queue.ts, lines 172–175).

Fixes that don't work

• Catching and retrying every error from the whole try block continues to treat persistence errors as handler failures; isolate handler execution errors from completion persistence errors.

A maintainer's best answer, and why it doesn't hold

The <= condition could be intended to allow a retry after the last counted failure, but that makes maxAttempts a retry count rather than the documented total execution limit.

What should hold

For items with unique IDs, cursor pagination orders items by sort key and then ID; following successive nextCursor values visits every item exactly once, including ties in the sort key.

The promise

Items are ordered by the sort key and then by id. Following nextCursor never skips or repeats an item, including when several items share the same sort key.

README.md:104 CONCRETE

The code

  const limit = clampLimit(req.limit);  const sorted = [...items].sort(    (a, b) => compareValues(sortKey(a), sortKey(b)) || compareValues(a.id, b.id),  );

  if (req.cursor) {    const after = decodeCursor(req.cursor);    remaining = sorted.filter((item) => compareValues(sortKey(item), after.k) > 0);  }

  return {    items: pageItems,    nextCursor: last && hasMore ? encodeCursor({ k: sortKey(last), id: last.id }) : null,  };}

What happens

Call paginate with items {id:"a", k:1}, {id:"b", k:1}, {id:"c", k:2} and {limit:1}, using item => item.k as sortKey. Sorting puts a before b, and the first page returns a with a cursor containing its key and ID. On the next call, the filter keeps only items whose key is greater than 1, so it drops b and returns c; following cursors therefore never visits b.

How to trigger it

Using the public paginate API, page through [{id:"a",k:1},{id:"b",k:1},{id:"c",k:2}] with limit 1 and sort key item => item.k, repeatedly passing each nextCursor. The collected IDs are ["a","c"], not all three IDs exactly once as promised.

Behaves correctly here

With unique sort keys, e.g. keys 1, 2, and 3 for IDs a, b, and c, the same limit-1 cursor walk returns all items in order.

Fixes that don't work

• Filtering only on after.id would skip or misorder items with different sort keys; resumption must compare the (sortKey, id) pair.

A maintainer's best answer, and why it doesn't hold

This is fine because callers can use unique sort keys, but the documented API explicitly promises correct pagination when sort keys tie and does not require them to be unique.