feat(clients/typescript): experimental cooperative consumers

[NikolayS]

Summary

• Adds the experimental cooperative-consumers surface to the TypeScript client: subscribeSubconsumer, unsubscribeSubconsumer, receiveCoop, touchSubconsumer on Client, and a subconsumer / deadInterval option on newConsumer that routes the poll loop through receiveCoop.
• Marked experimental in 0.2 in the README, mirroring the SQL feature's status. deadInterval without subconsumer throws at construction.
• Updates the cross-client parity matrix in clients/README.md to flag TypeScript as the first client with cooperative coverage.

Test plan

• bun run check — typecheck clean
• PGQUE_TEST_DSN=postgres://nik@localhost/pgque_coop_ts bun run test — 69 tests pass (10 new in test/coop.test.ts):
  1. subscribeSubconsumer returns 1 then 0
  2. receiveCoop round-trips messages and ack finishes the batch
  3. Two subconsumers split batches without duplicate msg_id delivery
  4. unsubscribeSubconsumer default raises on active batch
  5. unsubscribeSubconsumer({ batchHandling: 1 }) routes the active batch through retry
  6. touchSubconsumer returns 1 on a registered row
  7. High-level Consumer with { subconsumer } dispatches handler and acks via the cooperative path
  8. High-level Consumer without subconsumer is unchanged (still calls receive)
  9. newConsumer({ deadInterval }) without subconsumer throws with a clear message
  10. Mock-based assertions on the receiveCoop call args (queue, name, subconsumer, options)
• Manual two-worker e2e (bun src/coop_e2e.ts):

  {
    "total_sent": 50,
    "worker_1_processed": 30,
    "worker_2_processed": 20,
    "sum": 50,
    "overlap_count": 0,
    "disjoint": true
  }

  Both workers received messages, totals sum to N, msg_id sets are disjoint.

Notes

• Heartbeats are intentionally manual: the high-level Consumer does not auto-call touchSubconsumer. README points to it as the long-handler escape valve.
• Test teardown for cooperative tests uses a dedicated teardownCoopTestQueue helper that nukes subscription / retry / dead-letter rows before drop_queue, because drop_queue(..., true) calls unregister_consumer which now refuses cooperative mains with active members.

🤖 Generated with Claude Code

[NikolayS]

REV Code Review Report

• PR: NikolayS/PgQue#214 - feat(clients/typescript): experimental cooperative consumers
• Author: @NikolayS
• AI-Assisted: Yes
• CI: ✅ success

---

POTENTIAL ISSUES (4)

Issues with moderate confidence (4-7/10). Review manually — may be false positives.

MEDIUM clients/typescript/src/coop_e2e.ts:518 - Incomplete cleanup in teardown (confidence: 5/10)

Teardown only deletes from pgque.subscription before calling drop_queue. It does not clean pgque.retry_queue or pgque.dead_letter. If a batch is retried or dead-lettered during the test run, drop_queue may silently fail or leave orphan rows. Compare with teardownCoopTestQueue in test/helpers.ts which cleans all three tables.
Suggestion: Mirror the helpers.ts teardown: delete from retry_queue and dead_letter before calling drop_queue.

MEDIUM clients/typescript/src/consumer.ts:384 - No construction-time guard for empty subconsumer string (confidence: 5/10)

ConsumerOptions.subconsumer is typed as string | undefined. If a caller passes subconsumer: '' (empty string), the Consumer constructor sets this.subconsumer = '' which is not undefined, so the poll loop routes to receiveCoop — which then throws a PgqueSqlError at runtime rather than at construction. The existing guard only catches deadInterval-without-subconsumer.
Suggestion: Add if (this.subconsumer !== undefined && !this.subconsumer) throw new Error(...) in the constructor, and add a test for it.

INFO clients/typescript/src/coop_e2e.ts - Manual harness placed in src/ instead of bench/ (confidence: 6/10)

src/ conventionally contains production-shipped code. coop_e2e.ts is a manual dev harness (run with bun src/coop_e2e.ts) that mirrors bench/coop_demo.ts in purpose. Placing it in src/ may confuse future contributors about what is shipped vs. what is tooling.
Suggestion: Move to bench/coop_e2e.ts and update the file's run instructions.

INFO clients/typescript/README.md:70 - touchSubconsumer table entry missing manual-call guidance (confidence: 5/10)

The README method table describes touchSubconsumer as "Refresh the subconsumer heartbeat…" but does not note that the high-level Consumer does not call it automatically, so users with long-running handlers must call it themselves. This detail appears only in the JSDoc. Users reading the table alone will miss a critical operational requirement.
Suggestion: Add a note such as "Not called automatically by the high-level Consumer — call manually from long-running handlers or set a conservative deadInterval."

---

Summary

Area	Findings	Potential	Filtered
CI/Actions	0	0	0
Security	0	0	1
Bugs	0	1	0
Tests	0	1	1
Guidelines	0	1	0
Docs	0	1	0
Metadata	0	0	0

---

REV-assisted review (AI analysis by postgres-ai/rev)