tina4-nodejs 3.13.42 → 3.13.43

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.42)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.43)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.42",
+  "version": "3.13.43",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/queue.ts

@@ -81,9 +81,17 @@ export interface ProcessOptions {
   maxJobs?: number;
   maxRetries?: number;
   batchSize?: number;
+  /**
+   * Override the queue's topic for this drain (parity with Python's
+   * process(handler, topic=...)). When set, process() retargets the queue so
+   * pop() reads the requested topic instead of the construction-time one.
+   */
+  topic?: string;
 }
 
 export interface ConsumeOptions {
+  /** Topic to consume (defaults to the constructor topic). */
+  topic?: string;
   batchSize?: number;
   pollInterval?: number;
   iterations?: number;
@@ -95,6 +103,18 @@ export interface QueueBackendInterface {
   pop(queue: string): QueueJob | null;
   size(queue: string): number;
   clear(queue: string): void;
+  // Optional full lifecycle. Reservation-based backends (MongoDB) implement
+  // these so complete()/fail() ack the ACTIVE store — without complete(), a
+  // reserved Mongo job is re-delivered after the visibility window. Backends
+  // that auto-ack on pop (RabbitMQ no-ack) or delegate to the broker (Kafka
+  // offsets) omit them, and the Queue keeps its prior behaviour for them.
+  complete?(queue: string, id: string): void;
+  fail?(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number): void;
+  retry?(queue: string, id: string, delaySeconds?: number): void;
+  deadLetters?(queue: string, maxRetries?: number): QueueJob[];
+  failed?(queue: string, maxRetries?: number): QueueJob[];
+  retryFailed?(queue: string, maxRetries?: number): number;
+  purge?(queue: string, status?: string): number;
 }
 
 // ── Queue ────────────────────────────────────────────────────
@@ -152,6 +172,22 @@ export class Queue {
     }
   }
 
+  /**
+   * Point this queue at ``topic`` in place.
+   *
+   * produce()/consume()/process() call this so a topic argument actually
+   * changes which topic is read or written. Without it the argument was
+   * accepted but ignored on the read path — pop() always used the
+   * construction-time topic, so consume("other") silently drained the wrong
+   * queue. The lite + external backends are topic-per-call (every push/pop/size
+   * takes the queue name), so changing this.topic retargets all of them; the
+   * job lifecycle (complete()/fail()/retry()) routes by the job's own .topic, so
+   * it is unaffected. Mirrors Python's Queue._retarget().
+   */
+  private retarget(topic: string): void {
+    this.topic = topic;
+  }
+
   // ── Unified API (topic-aware) ────────────────────────────────
 
   /**
@@ -197,6 +233,12 @@ export class Queue {
     handler: (job: QueueJob | QueueJob[]) => Promise<void> | void,
     options?: ProcessOptions,
   ): void {
+    // Honour an explicit topic: retarget so pop() drains the requested topic
+    // (parity with Python's process(handler, topic=...)). Without this the
+    // argument was accepted but ignored on the read path.
+    if (options?.topic !== undefined) {
+      this.retarget(options.topic);
+    }
     const queue = this.topic;
     const opts = options;
 
@@ -275,6 +317,9 @@ export class Queue {
    * auto-retry lifecycle; dead-lettered jobs are returned by deadLetters().
    */
   failed(): QueueJob[] {
+    if (this.externalBackend?.failed) {
+      return this.externalBackend.failed(this.topic, this._maxRetries);
+    }
     return this.liteBackend.failed(this.topic, this._maxRetries);
   }
 
@@ -288,6 +333,10 @@ export class Queue {
   retry(jobId?: string, delaySeconds?: number): boolean {
     if (jobId) {
       // Retry a specific job by ID
+      if (this.externalBackend?.retry) {
+        this.externalBackend.retry(this.topic, jobId, delaySeconds);
+        return true;
+      }
       return this.liteBackend.retry(this.topic, jobId, delaySeconds);
     }
     // Retry all dead-letter jobs
@@ -295,8 +344,12 @@ export class Queue {
     if (deadJobs.length === 0) return false;
     let retried = false;
     for (const job of deadJobs) {
-      const ok = this.liteBackend.retry(this.topic, job.id, delaySeconds);
-      if (ok) retried = true;
+      if (this.externalBackend?.retry) {
+        this.externalBackend.retry(this.topic, job.id, delaySeconds);
+        retried = true;
+      } else if (this.liteBackend.retry(this.topic, job.id, delaySeconds)) {
+        retried = true;
+      }
     }
     return retried;
   }
@@ -305,6 +358,9 @@ export class Queue {
    * Get dead letter jobs — failed jobs that exceeded max retries.
    */
   deadLetters(maxRetries?: number): QueueJob[] {
+    if (this.externalBackend?.deadLetters) {
+      return this.externalBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
+    }
     return this.liteBackend.deadLetters(this.topic, maxRetries ?? this._maxRetries);
   }
 
@@ -312,6 +368,9 @@ export class Queue {
    * Delete messages by status (e.g. "completed", "failed", "dead").
    */
   purge(status: string, maxRetries?: number): number {
+    if (this.externalBackend?.purge) {
+      return this.externalBackend.purge(this.topic, status);
+    }
     return this.liteBackend.purge(this.topic, status, maxRetries ?? this._maxRetries);
   }
 
@@ -319,17 +378,27 @@ export class Queue {
    * Re-queue failed jobs that haven't exceeded max retries back to pending.
    */
   retryFailed(maxRetries?: number): number {
+    if (this.externalBackend?.retryFailed) {
+      return this.externalBackend.retryFailed(this.topic, maxRetries ?? this._maxRetries);
+    }
     return this.liteBackend.retryFailed(this.topic, maxRetries ?? this._maxRetries);
   }
 
   /**
    * Produce a message onto a topic. Convenience wrapper around push().
+   *
+   * Retargets to the requested topic (restoring the prior one afterwards) so it
+   * shares the same retarget path consume()/process() use — keeping produce and
+   * consume symmetric on the same topic argument.
    */
   produce(topic: string, payload: unknown, priority: number = 0, delay: number = 0): string {
-    if (this.externalBackend) {
-      return this.externalBackend.push(topic, payload, delay);
+    const previous = this.topic;
+    this.retarget(topic);
+    try {
+      return this.push(payload, delay, priority);
+    } finally {
+      this.retarget(previous);
     }
-    return this.liteBackend.push(topic, payload, delay, priority);
   }
 
   /**
@@ -368,7 +437,9 @@ export class Queue {
 
     if (topicOrOptions !== null && typeof topicOrOptions === "object") {
       const opts = topicOrOptions as ConsumeOptions;
-      q = this.topic;
+      // Honour opts.topic (parity with the string-arg form) — previously the
+      // options-object form ignored it and always drained the constructor topic.
+      q = opts.topic ?? this.topic;
       resolvedId = opts.id;
       resolvedPollInterval = opts.pollInterval ?? 1000;
       resolvedIterations = opts.iterations ?? 0;
@@ -381,6 +452,12 @@ export class Queue {
       resolvedBatchSize = batchSize;
     }
 
+    // Honour the topic argument: point the queue (and the backend pop()/
+    // popById() route through) at it. Previously the resolved topic was
+    // computed but never used — pop()/popById() read this.topic, so
+    // consume("other") silently drained the construction-time topic.
+    this.retarget(q);
+
     if (resolvedId !== undefined) {
       const raw = this.popById(resolvedId);
       if (raw) yield createJob(raw as any, this);
@@ -453,6 +530,10 @@ export class Queue {
    * after retryBackoff seconds) or dead-letter (attempts >= maxRetries).
    */
   _failJob(queue: string, job: QueueJob, error: string, maxRetries: number): void {
+    if (this.externalBackend?.fail) {
+      this.externalBackend.fail(queue, job.id, error, maxRetries, this._retryBackoff);
+      return;
+    }
     this.liteBackend.failJob(queue, job, error, maxRetries, this._retryBackoff);
   }
 
@@ -460,15 +541,26 @@ export class Queue {
    * Re-queue a job back to the main queue directory with incremented attempts.
    */
   _retryJob(queue: string, job: QueueJob, delaySeconds?: number): void {
+    if (this.externalBackend?.retry) {
+      this.externalBackend.retry(queue, job.id, delaySeconds);
+      return;
+    }
     this.liteBackend.retryJob(queue, job, delaySeconds);
   }
 
   /**
-   * Acknowledge a completed job — drop its reservation record so the visibility
-   * reclaim never re-delivers it. No-op for external backends (they ack their
-   * own way; lite-backend reservations are file records).
+   * Acknowledge a completed job — drop its reservation so the visibility reclaim
+   * never re-delivers it. Routes to the active backend: a reservation-based
+   * external backend (MongoDB) acks there (without this its reserved doc would
+   * be re-delivered after the visibility window); RabbitMQ (no-ack on get) and
+   * Kafka (offset-based) expose no complete(), so the lite path is used and is a
+   * harmless no-op for them since they already acked/own redelivery.
    */
   _completeJob(queue: string, job: QueueJob): void {
+    if (this.externalBackend?.complete) {
+      this.externalBackend.complete(queue, job.id);
+      return;
+    }
     this.liteBackend.completeJob(queue, job);
   }
 }

package/packages/core/src/queueBackends/mongoBackend.ts

@@ -229,12 +229,20 @@ export class MongoBackend implements QueueBackend {
             if (result && result.value) {
               // findOneAndUpdate returns { value: doc } in older drivers
               const doc = result.value;
+              // Carry the framework topic on the job so complete()/fail()
+              // route the ack/requeue back to THIS topic's docs (the Mongo
+              // internal queue field is dropped from the returned shape).
+              doc.topic = queueName;
               delete doc._id;
               delete doc.queue;
               process.stdout.write(JSON.stringify(doc));
             } else if (result && result._id) {
               // Some driver versions return the doc directly
               const doc = { ...result };
+              // Carry the framework topic on the job so complete()/fail()
+              // route the ack/requeue back to THIS topic's docs (the Mongo
+              // internal queue field is dropped from the returned shape).
+              doc.topic = queueName;
               delete doc._id;
               delete doc.queue;
               process.stdout.write(JSON.stringify(doc));
@@ -253,6 +261,95 @@ export class MongoBackend implements QueueBackend {
             await col.deleteMany({ queue: queueName });
             process.stdout.write("__CLEARED__");
           }
+          else if (operation === "complete") {
+            // Ack a finished job so the reclaim never re-delivers it. data = job id.
+            // (The pop reserved this doc; without this it stays reserved and is
+            // re-delivered after the visibility window — the redelivery bug.)
+            await col.updateOne(
+              { queue: queueName, id: data },
+              { $set: { status: "completed", completedAt: new Date().toISOString(), reservedAt: null } },
+            );
+            process.stdout.write("__OK__");
+          }
+          else if (operation === "fail") {
+            // Requeue while retries remain (reset availableAt -> visible again),
+            // else dead-letter. Atomic decision in Mongo. data = JSON
+            // { id, error, maxRetries, retryBackoff }.
+            const info = JSON.parse(data);
+            const now = new Date().toISOString();
+            const doc = await col.findOne({ queue: queueName, id: info.id });
+            if (doc) {
+              const attempts = (doc.attempts || 0) + 1;
+              if (attempts >= info.maxRetries) {
+                await col.insertOne({
+                  ...doc, _id: undefined, attempts,
+                  status: "dead", queue: queueName + ".dead_letter", error: info.error,
+                });
+                await col.deleteOne({ _id: doc._id, queue: queueName });
+              } else {
+                const avail = info.retryBackoff > 0
+                  ? new Date(Date.now() + info.retryBackoff * 1000).toISOString()
+                  : now;
+                await col.updateOne(
+                  { _id: doc._id, queue: queueName },
+                  { $set: { status: "pending", availableAt: avail, reservedAt: null, error: info.error },
+                    $inc: { attempts: 1 } },
+                );
+              }
+            }
+            process.stdout.write("__OK__");
+          }
+          else if (operation === "retry") {
+            // Explicit manual re-queue (always re-enqueues). data = JSON
+            // { id, delaySeconds }.
+            const info = JSON.parse(data);
+            const avail = info.delaySeconds > 0
+              ? new Date(Date.now() + info.delaySeconds * 1000).toISOString()
+              : new Date().toISOString();
+            await col.updateOne(
+              { queue: queueName, id: info.id },
+              { $set: { status: "pending", availableAt: avail, reservedAt: null }, $inc: { attempts: 1 } },
+            );
+            process.stdout.write("__OK__");
+          }
+          else if (operation === "deadLetters") {
+            const docs = await col.find({ queue: queueName + ".dead_letter" }).toArray();
+            const out = docs.map((d) => { delete d._id; delete d.queue; return d; });
+            process.stdout.write(JSON.stringify(out));
+          }
+          else if (operation === "failed") {
+            const docs = await col
+              .find({ queue: queueName, status: "failed", attempts: { $lt: maxRetries } })
+              .toArray();
+            const out = docs.map((d) => { delete d._id; delete d.queue; return d; });
+            process.stdout.write(JSON.stringify(out));
+          }
+          else if (operation === "retryFailed") {
+            // Revive dead-lettered jobs under the (possibly raised) limit back to
+            // the main queue as pending. data = the max-retries limit.
+            const mr = data ? Number(data) : maxRetries;
+            const now = new Date().toISOString();
+            let revived = 0;
+            while (true) {
+              const doc = await col.findOneAndUpdate(
+                { queue: queueName + ".dead_letter", attempts: { $lt: mr } },
+                { $set: { status: "pending", availableAt: now, reservedAt: null, queue: queueName, error: null } },
+                { returnDocument: "after" },
+              );
+              const updated = doc && doc.value ? doc.value : (doc && doc._id ? doc : null);
+              if (!updated) break;
+              revived++;
+            }
+            process.stdout.write(String(revived));
+          }
+          else if (operation === "purge") {
+            // Delete docs by status (default: all for the topic). data = JSON { status }.
+            const info = data ? JSON.parse(data) : {};
+            const filter = { queue: queueName };
+            if (info.status) filter.status = info.status;
+            const res = await col.deleteMany(filter);
+            process.stdout.write(String(res.deletedCount || 0));
+          }
         } catch (err) {
           process.stderr.write(err.message || String(err));
           process.exit(1);
@@ -328,4 +425,50 @@ export class MongoBackend implements QueueBackend {
   clear(queue: string): void {
     this.execSync("clear", queue);
   }
+
+  /**
+   * Acknowledge a completed job — drop its reservation so the reclaim never
+   * re-delivers it. Without this a Mongo-popped job stayed reserved and was
+   * re-delivered after the visibility window (the redelivery bug).
+   */
+  complete(queue: string, id: string): void {
+    this.execSync("complete", queue, id);
+  }
+
+  /**
+   * Record a failed attempt: requeue (reset availableAt, ++attempts) while
+   * retries remain, else dead-letter. Mirrors the file/lite backend.
+   */
+  fail(queue: string, id: string, error: string, maxRetries: number, retryBackoff: number = 0): void {
+    this.execSync("fail", queue, JSON.stringify({ id, error, maxRetries, retryBackoff }));
+  }
+
+  /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
+  retry(queue: string, id: string, delaySeconds: number = 0): void {
+    this.execSync("retry", queue, JSON.stringify({ id, delaySeconds }));
+  }
+
+  /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */
+  deadLetters(queue: string, maxRetries?: number): QueueJob[] {
+    const out = this.execSync("deadLetters", queue, String(maxRetries ?? this.maxRetries));
+    try { return JSON.parse(out) as QueueJob[]; } catch { return []; }
+  }
+
+  /** Jobs that failed but are still eligible for retry (status=failed, attempts < max). */
+  failed(queue: string, maxRetries?: number): QueueJob[] {
+    const out = this.execSync("failed", queue, String(maxRetries ?? this.maxRetries));
+    try { return JSON.parse(out) as QueueJob[]; } catch { return []; }
+  }
+
+  /** Revive dead-lettered jobs under the (possibly raised) limit. Returns count revived. */
+  retryFailed(queue: string, maxRetries?: number): number {
+    const out = this.execSync("retryFailed", queue, String(maxRetries ?? this.maxRetries));
+    return parseInt(out, 10) || 0;
+  }
+
+  /** Remove jobs by status (default: every doc for the topic). Returns count removed. */
+  purge(queue: string, status?: string): number {
+    const out = this.execSync("purge", queue, JSON.stringify({ status: status ?? "" }));
+    return parseInt(out, 10) || 0;
+  }
 }