tina4-nodejs 3.13.42 → 3.13.44

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.44)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
@@ -1239,6 +1239,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **Don't break the test files** — run `npm test` before committing
 - **Don't add unnecessary dependencies** — minimal footprint is a core principle
 - **Parity across all frameworks** — Every new feature, fix, or optimization must be implemented with equivalent logic AND tests in all 4 Tina4 frameworks (Python, PHP, Ruby, Node.js). Never ship to one without shipping to all.
+- **NO mock testing. Mocks are not acceptable in any circumstances.** A test double (mock, stub, fake, spy, monkeypatch, script-introspection assertion, or any in-test object standing in for a real collaborator) may never substitute for a real dependency, under any justification. There is no "supplement" exception and no "hard to reproduce" exception. Any test that touches a dependency (a DB engine, MongoDB, Redis/Valkey/Memcached, RabbitMQ/Kafka, an HTTP/SMTP service, the filesystem, a socket) must exercise the REAL service; if a failure mode is hard to trigger, reproduce it for real, never simulate it. "Verified"/"green" requires a real run; a passing mock test is not verification. CI provisions the services; use them and add any that is missing. The only tests that need no live dependency are pure functions with no dependency and no double; that is not a mock test. (The MongoDB queue re-delivered every completed job for two releases because its queue tests were mock/script-introspection-based and never ran against a real Mongo.)
 - **Don't use `url.parse()`** — use the WHATWG `URL` constructor instead (deprecated in Node 20+)
 
 ## Tina4 Maintainer Skill

package/package.json

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

package/packages/core/src/graphql.ts

@@ -510,8 +510,13 @@ export class GraphQL {
   /**
    * Decorator-style resolver registration.
    *
+   * Resolvers may be synchronous OR async (return a Promise) — `execute()`
+   * awaits every resolver, so an `async` resolver's value is resolved before
+   * the field is serialized. Return a value directly, or `await` your data
+   * (e.g. an async DB driver) and the executor will await it for you.
+   *
    *     GraphQL.resolve("Query", "products", async (root, args) =>
-   *       db.fetchAll("SELECT * FROM products"));
+   *       (await db.fetch("SELECT * FROM products")).records);
    *
    *     GraphQL.resolve("Mutation", "createProduct", async (root, args) => {
    *       const p = new Product(args.input);
@@ -520,7 +525,7 @@ export class GraphQL {
    *     });
    *
    *     GraphQL.resolve("Product", "reviews", async (product, args) =>
-   *       db.fetchAll("SELECT * FROM reviews WHERE product_id = ?", [product.id]));
+   *       (await db.fetch("SELECT * FROM reviews WHERE product_id = ?", [product.id])).records);
    *
    * Resolvers registered before any GraphQL instance exists accumulate
    * in the class-level registry. `new GraphQL()` drains them into its
@@ -647,7 +652,7 @@ export class GraphQL {
   /**
    * Execute a GraphQL query string.
    */
-  execute(query: string, variables?: Record<string, unknown>, context?: Record<string, unknown>): GraphQLResult {
+  async execute(query: string, variables?: Record<string, unknown>, context?: Record<string, unknown>): Promise<GraphQLResult> {
     const vars = variables ?? {};
     const ctx = context ?? {};
     const errors: Array<{ message: string; path?: string[] }> = [];
@@ -690,7 +695,7 @@ export class GraphQL {
 
     const data: Record<string, unknown> = {};
     // Top-level selections start at depth 1.
-    const errs = this.resolveSelectionsInto(op.selections, resolvers, null, vars, ctx, fragments, data, 1);
+    const errs = await this.resolveSelectionsInto(op.selections, resolvers, null, vars, ctx, fragments, data, 1);
     errors.push(...errs);
 
     const result: GraphQLResult = { data };
@@ -710,7 +715,7 @@ export class GraphQL {
    * instead of recursing until the interpreter stack overflows. Top-level
    * starts at depth 1; `maxDepth <= 0` disables the guard.
    */
-  private resolveSelectionsInto(
+  private async resolveSelectionsInto(
     selections: ParsedSelection[],
     resolvers: Map<string, QueryConfig>,
     parent: unknown,
@@ -719,7 +724,7 @@ export class GraphQL {
     fragments: Map<string, ParsedFragment>,
     target: Record<string, unknown>,
     depth: number,
-  ): Array<{ message: string; path?: string[] }> {
+  ): Promise<Array<{ message: string; path?: string[] }>> {
     const errors: Array<{ message: string; path?: string[] }> = [];
 
     if (this.maxDepth > 0 && depth > this.maxDepth) {
@@ -736,7 +741,7 @@ export class GraphQL {
           errors.push({ message: `Fragment not found: ${sel.name}` });
           continue;
         }
-        const errs = this.resolveSelectionsInto(
+        const errs = await this.resolveSelectionsInto(
           frag.selections, resolvers, parent, variables, context, fragments, target, depth + 1,
         );
         errors.push(...errs);
@@ -744,14 +749,14 @@ export class GraphQL {
       }
 
       if (sel.kind === "inline_fragment") {
-        const errs = this.resolveSelectionsInto(
+        const errs = await this.resolveSelectionsInto(
           sel.selections, resolvers, parent, variables, context, fragments, target, depth + 1,
         );
         errors.push(...errs);
         continue;
       }
 
-      const [value, errs] = this.resolveField(sel, resolvers, parent, variables, context, fragments, depth);
+      const [value, errs] = await this.resolveField(sel, resolvers, parent, variables, context, fragments, depth);
       errors.push(...errs);
       const key = sel.alias ?? sel.name;
       target[key] = value;
@@ -1010,7 +1015,7 @@ export class GraphQL {
     return `(${parts.join(", ")})`;
   }
 
-  private resolveField(
+  private async resolveField(
     sel: ParsedField,
     resolvers: Map<string, QueryConfig>,
     parent: unknown,
@@ -1018,7 +1023,7 @@ export class GraphQL {
     context: Record<string, unknown> = {},
     fragments: Map<string, ParsedFragment> = new Map(),
     depth: number = 1,
-  ): [unknown, Array<{ message: string; path?: string[] }>] {
+  ): Promise<[unknown, Array<{ message: string; path?: string[] }>]> {
     const errors: Array<{ message: string; path?: string[] }> = [];
     const name = sel.name;
     const args = this.resolveArgs(sel.args, variables);
@@ -1046,7 +1051,11 @@ export class GraphQL {
       // Inject sub-selections into context for DataLoader/eager-loading
       const ctx = { ...context, __selections: sel.selections ?? [] };
       try {
-        value = config.resolver(null, args, ctx);
+        // Resolvers may be sync or async. Awaiting a plain value is a no-op;
+        // awaiting a Promise (async resolver) resolves it before serialization.
+        // A rejected Promise throws here, into the same catch below, so async
+        // resolver errors are masked/detailed exactly like sync ones.
+        value = await config.resolver(null, args, ctx);
       } catch (e: unknown) {
         // Log the real cause; only surface the detail to the client in debug
         // mode — a resolver exception can carry internal state (DB errors,
@@ -1067,7 +1076,7 @@ export class GraphQL {
       const result: Record<string, unknown>[] = [];
       for (const item of value) {
         const obj: Record<string, unknown> = {};
-        const errs = this.resolveSelectionsInto(
+        const errs = await this.resolveSelectionsInto(
           sel.selections, new Map(), item, variables, context, fragments, obj, depth + 1,
         );
         errors.push(...errs);
@@ -1078,7 +1087,7 @@ export class GraphQL {
 
     if (value !== null && value !== undefined) {
       const obj: Record<string, unknown> = {};
-      const errs = this.resolveSelectionsInto(
+      const errs = await this.resolveSelectionsInto(
         sel.selections, new Map(), value, variables, context, fragments, obj, depth + 1,
       );
       errors.push(...errs);

package/packages/core/src/mcp.ts

@@ -1231,7 +1231,17 @@ export function registerDevTools(server: McpServer): void {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
-        return { info: "Migration status not yet implemented for Node.js" };
+        // Use the real migration API (parity with the Python master, whose MCP
+        // migration_status calls MigrationRunner(db).status()). Previously a stub.
+        // Load orm via dynamic ESM import (the same mechanism server.ts uses for
+        // autoMigrateOnStartup) — reqSibling()'s createRequire fails here because
+        // @tina4/orm imports @tina4/core (no CJS "exports" main).
+        const orm = await import("../../orm/src/index.js");
+        if (typeof orm.status !== "function") {
+          return { error: "Migration API not available (install @tina4/orm)" };
+        }
+        const st = await orm.status(db, { migrationsDir: path.join(projectRoot, "migrations") });
+        return { completed: st.completed, pending: st.pending };
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -1264,7 +1274,16 @@ export function registerDevTools(server: McpServer): void {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
-        return { info: "Migration run not yet implemented for Node.js" };
+        // Run pending migrations for real (parity with the Python master's MCP
+        // migration_run -> Migration(db).migrate()). Previously a stub. Load orm
+        // via dynamic ESM import (server.ts's mechanism); reqSibling's createRequire
+        // fails because @tina4/orm imports @tina4/core.
+        const orm = await import("../../orm/src/index.js");
+        if (typeof orm.migrate !== "function") {
+          return { error: "Migration API not available (install @tina4/orm)" };
+        }
+        const result = await orm.migrate(db, { migrationsDir: path.join(projectRoot, "migrations") });
+        return { applied: result.applied, skipped: result.skipped, failed: result.failed };
       } catch (e) {
         return { error: (e as Error).message };
       }

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);
   }
 }