tina4-nodejs 3.13.104 → 3.13.105

package/packages/orm/src/migration.ts

@@ -297,7 +297,16 @@ const MIGRATION_TABLE = "tina4_migration";
  * sql_mode, so they are always correct there.
  */
 function mt(db: DatabaseAdapter): string {
-  return engineOf(db) === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
+  const engine = engineOf(db);
+
+  // Firebird: leave it UNQUOTED so it folds to the upper-case TINA4_MIGRATION
+  // that the PHP and Python masters create. A quoted lower-case identifier is a
+  // DIFFERENT, case-sensitive table there, so a quoted spelling cannot see a
+  // ledger written by another Tina4 language — while tableExists() matches
+  // case-insensitively and reports it present, so the INSERT fails alone.
+  if (engine === "firebird") return MIGRATION_TABLE;
+
+  return engine === "mysql" ? `\`${MIGRATION_TABLE}\`` : `"${MIGRATION_TABLE}"`;
 }
 
 /**
@@ -347,9 +356,9 @@ async function ensureMigrationTableOn(db: DatabaseAdapter): Promise<void> {
         id INTEGER NOT NULL PRIMARY KEY,
         migration_name VARCHAR(500) NOT NULL UNIQUE,
         description VARCHAR(500),
-        batch INTEGER NOT NULL DEFAULT 1,
+        batch INTEGER DEFAULT 1 NOT NULL,
         executed_at VARCHAR(50) NOT NULL,
-        passed INTEGER NOT NULL DEFAULT 1
+        passed INTEGER DEFAULT 1 NOT NULL
       )`);
     } else {
       // Engine-aware bookkeeping DDL (non-Firebird). Each engine spells an
@@ -517,11 +526,11 @@ async function recordApplied(
 
   if (isFirebirdAdapter(db)) {
     // Firebird: generate the id from the sequence.
-    const rows = await adapterQuery<{ NEXT_ID: number }>(db,
+    const rows = await adapterQuery<{ next_id: number }>(db,
       "SELECT GEN_ID(GEN_TINA4_MIGRATION_ID, 1) AS NEXT_ID FROM RDB$DATABASE",
     );
     insertCols.unshift("id");
-    values.unshift(rows[0]?.NEXT_ID ?? 1);
+    values.unshift(rows[0]?.next_id ?? 1);
   }
 
   const placeholders = insertCols.map(() => "?").join(", ");

package/types/core/src/queue.d.ts

@@ -74,7 +74,13 @@ export interface QueueBackendInterface {
     close(): void;
     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;
+    /**
+     * Explicit manual re-queue: returns true if the id was found and revived,
+     * false otherwise (parity with Python's backend.retry_job()). A backend may
+     * legacy-return void; callers coerce a void return to true so nothing that
+     * used to be reported as success silently flips to failure.
+     */
+    retry?(queue: string, id: string, delaySeconds?: number): boolean | void;
     deadLetters?(queue: string, maxRetries?: number): QueueJob[];
     failed?(queue: string, maxRetries?: number): QueueJob[];
     retryFailed?(queue: string, maxRetries?: number): number;
@@ -137,7 +143,19 @@ export declare class Queue {
      */
     process(handler: (job: QueueJob | QueueJob[]) => Promise<void> | void, options?: ProcessOptions): void;
     /**
-     * Count jobs filtered by status. Defaults to "pending".
+     * Count jobs by status. Defaults to "pending".
+     *
+     * ``"pending"`` counts jobs waiting to be popped -- INCLUDES retryable-
+     * but-attempted ones, because they live in the pending queue under the
+     * auto-retry lifecycle (see failed()).
+     * ``"reserved"`` counts jobs a consumer has popped but not yet
+     * completed/failed (in-flight against the visibility timeout).
+     * ``"completed"`` counts jobs the consumer has finished successfully.
+     * ``"failed"``, ``"dead"``, ``"dead_letter"`` are ALIASES that all count
+     * the dead-letter store -- jobs whose attempts >= maxRetries and that
+     * have given up. Use deadLetters() to list them. Retryable-but-attempted
+     * jobs are NOT counted by size("failed"); use failed() to list them or
+     * size("pending") to include them in a total.
      */
     size(status?: string): number;
     /**
@@ -172,7 +190,11 @@ export declare class Queue {
     /**
      * Get jobs that failed at least once but are still being retried
      * (0 < attempts < maxRetries). These live in the pending queue under the
-     * auto-retry lifecycle; dead-lettered jobs are returned by deadLetters().
+     * auto-retry lifecycle (fail() re-queues them with an incremented attempts
+     * count and a retryBackoff delay) so pop() picks them up again. They are
+     * NOT counted by size("failed") -- that alias counts the dead-letter store,
+     * matching deadLetters(). To include retryable-failed jobs in a total, use
+     * size("pending"). Terminal failures are returned by deadLetters().
      */
     failed(): QueueJob[];
     /**
@@ -184,7 +206,22 @@ export declare class Queue {
      */
     retry(jobId?: string, delaySeconds?: number): boolean;
     /**
-     * Get dead letter jobs — failed jobs that exceeded max retries.
+     * Get jobs that exceeded max_retries -- terminal failures.
+     *
+     * Same set counted by size("failed") / size("dead") / size("dead_letter")
+     * (three aliases for the dead-letter store). To LIST retryable-but-
+     * attempted jobs (attempts > 0 AND attempts < maxRetries) that are still
+     * being auto-retried, use failed() -- those live in the pending queue and
+     * are NOT dead letters.
+     *
+     * Returns Job objects with the failure reason on ``.error`` (not raw dicts)
+     * so callers can iterate uniformly with the rest of the queue API and, in
+     * particular, call ``.retry()`` on each to manually revive it:
+     *
+     *     for (const job of queue.deadLetters()) {
+     *       Log.warn(`revived ${job.id}: ${job.error}`);
+     *       job.retry();
+     *     }
      */
     deadLetters(maxRetries?: number): QueueJob[];
     /**

package/types/core/src/queueBackends/liteBackend.d.ts

@@ -122,7 +122,13 @@ export declare class LiteBackend {
      * Explicit re-queue requested by the caller (job.retry()).
      *
      * Always re-enqueues regardless of the retry limit — manual override,
-     * distinct from the automatic failJob() path.
+     * distinct from the automatic failJob() path. Cleans up BOTH the
+     * reservation record AND any dead-letter file for this id, so a caller
+     * that iterates deadLetters() and calls .retry() on each doesn't leave
+     * the failed/ directory carrying duplicates (PY-12-05, 3.13.105).
+     * Aligns with retry(queue, jobId) which had always unlinked the
+     * dead-letter file -- two spellings of the same intent that previously
+     * diverged.
      */
     retryJob(queue: string, job: QueueJob, delaySeconds?: number): void;
 }

package/types/core/src/queueBackends/mongoBackend.d.ts

@@ -87,8 +87,13 @@ export declare class MongoBackend implements QueueBackend {
      * retries remain, else dead-letter. Mirrors the file/lite backend.
      */
     fail(queue: string, id: string, error: string, maxRetries: number, retryBackoff?: number): void;
-    /** Explicit manual re-queue (always re-enqueues regardless of the retry limit). */
-    retry(queue: string, id: string, delaySeconds?: number): void;
+    /**
+     * Revive a specific dead-letter job by id. Returns true if the DL was found
+     * and revived, false otherwise (parity with LiteBackend.retry(queue, id)
+     * and Python's mongo_backend.retry_job()). Pre-3.13.105 this returned void
+     * and Queue.retry(id) reported success for every call, even for unknown ids.
+     */
+    retry(queue: string, id: string, delaySeconds?: number): boolean;
     /** Jobs that exceeded max retries (the `<queue>.dead_letter` collection topic). */
     deadLetters(queue: string, maxRetries?: number): QueueJob[];
     /** Jobs that failed but are still eligible for retry (status=failed, attempts < max). */

package/types/orm/src/baseModel.d.ts

@@ -339,11 +339,16 @@ export declare class BaseModel {
     /**
      * Invalidate every cached query that touches this model's table.
      *
-     * Tag-scoped, NOT a wholesale flush: a cached JOIN on another model that reads
-     * this table is busted too (it carries this table's tag), while a query that
-     * never touches this table is left intact. Called after every ORM write
-     * (save/delete/forceDelete/restore) so a read-after-write never serves a
-     * stale/deleted row (CACHE-DEC-01).
+     * Tag-scoped in the ORM layer (a cached JOIN on another model that reads
+     * this table is busted too because it carries this table's tag; a query
+     * that never touches this table is left intact), then cascaded to the
+     * DB layer on this model's bound connection so an out-of-band write /
+     * deliberate refresh / race-with-another-process cannot leave stale rows
+     * in db.fetch()'s persistent cache. Called after every ORM write
+     * (save/delete/forceDelete/restore) so a read-after-write never serves
+     * a stale/deleted row (CACHE-DEC-01). PY-06-22 (3.13.105) added the
+     * DB-layer cascade -- previously the two cache layers disagreed under
+     * TINA4_AUTO_CACHING=true + TINA4_DB_CACHE=true.
      */
     static clearCache(): void;
     /**