@jgamaraalv/ts-dev-kit 1.0.0

package/skills/bullmq/references/patterns.md

@@ -0,0 +1,273 @@
+# Patterns
+
+## Table of Contents
+
+- [Process Step Jobs](#process-step-jobs)
+- [Idempotent Jobs](#idempotent-jobs)
+- [Throttle Jobs](#throttle-jobs)
+- [Manual Rate Limiting](#manual-rate-limiting)
+- [Static Rate Limiting](#static-rate-limiting)
+- [Global Concurrency](#global-concurrency)
+- [Failing Fast When Redis Is Down](#failing-fast-when-redis-is-down)
+- [Redis Cluster](#redis-cluster)
+
+## Process Step Jobs
+
+Break processor logic into resumable steps. Save step state in `job.data` so retries resume from the correct step.
+
+```ts
+import { Worker } from "bullmq";
+
+enum Step {
+  Initial,
+  Second,
+  Finish,
+}
+
+const worker = new Worker(
+  "queueName",
+  async (job) => {
+    let step = job.data.step;
+    while (step !== Step.Finish) {
+      switch (step) {
+        case Step.Initial: {
+          await doInitialStepStuff();
+          await job.updateData({ step: Step.Second });
+          step = Step.Second;
+          break;
+        }
+        case Step.Second: {
+          await doSecondStepStuff();
+          await job.updateData({ step: Step.Finish });
+          step = Step.Finish;
+          return Step.Finish;
+        }
+        default:
+          throw new Error("invalid step");
+      }
+    }
+  },
+  { connection },
+);
+```
+
+### Delaying Mid-Process
+
+Use `moveToDelayed` + `DelayedError` to pause a job and resume later:
+
+```ts
+import { DelayedError, Worker } from "bullmq";
+
+const worker = new Worker(
+  "queueName",
+  async (job, token) => {
+    let step = job.data.step;
+    switch (step) {
+      case Step.Initial: {
+        await doStuff();
+        await job.moveToDelayed(Date.now() + 5000, token);
+        await job.updateData({ step: Step.Second });
+        throw new DelayedError(); // signals worker to release the job
+      }
+      case Step.Second: {
+        // resumes here after 5s delay
+        return doMoreStuff();
+      }
+    }
+  },
+  { connection },
+);
+```
+
+### Waiting for Dynamic Children
+
+Add children at runtime, then wait for them with `moveToWaitingChildren`:
+
+```ts
+import { WaitingChildrenError, Worker } from "bullmq";
+
+const worker = new Worker(
+  "parentQueue",
+  async (job, token) => {
+    let step = job.data.step;
+    switch (step) {
+      case Step.Initial: {
+        // Add child dynamically
+        await childQueue.add(
+          "child-1",
+          { foo: "bar" },
+          {
+            parent: { id: job.id!, queue: job.queueQualifiedName },
+          },
+        );
+        await job.updateData({ step: Step.WaitForChildren });
+        step = Step.WaitForChildren;
+        break;
+      }
+      case Step.WaitForChildren: {
+        const shouldWait = await job.moveToWaitingChildren(token!);
+        if (shouldWait) {
+          throw new WaitingChildrenError();
+        }
+        // All children done — continue
+        return "done";
+      }
+    }
+  },
+  { connection },
+);
+```
+
+### Chaining Flows at Runtime
+
+```ts
+import { FlowProducer, WaitingChildrenError, Worker } from "bullmq";
+
+const flow = new FlowProducer({ connection });
+
+const worker = new Worker(
+  "parentQueue",
+  async (job, token) => {
+    // Add a full flow as children
+    await flow.add({
+      name: "child-job",
+      queueName: "childQueue",
+      data: {},
+      children: [
+        { name: "gc1", data: {}, queueName: "grandchildQueue" },
+        { name: "gc2", data: {}, queueName: "grandchildQueue" },
+      ],
+      opts: {
+        parent: { id: job.id!, queue: job.queueQualifiedName },
+      },
+    });
+
+    const shouldWait = await job.moveToWaitingChildren(token!);
+    if (shouldWait) throw new WaitingChildrenError();
+    return "all children done";
+  },
+  { connection },
+);
+```
+
+**Note:** `DelayedError`, `WaitingChildrenError`, and `RateLimitError` do NOT increment `attemptsMade`. Use `maxStartedAttempts` to limit how many times a job can start processing.
+
+## Idempotent Jobs
+
+Use `jobId` to prevent duplicate processing:
+
+```ts
+await queue.add(
+  "process-order",
+  { orderId: 123 },
+  {
+    jobId: "order-123",
+  },
+);
+// Second add with same jobId is silently ignored
+await queue.add(
+  "process-order",
+  { orderId: 123 },
+  {
+    jobId: "order-123",
+  },
+);
+```
+
+## Throttle Jobs
+
+Use deduplication throttle mode to limit how often a job type runs:
+
+```ts
+await queue.add("sync", data, {
+  deduplication: { id: "sync-user-42", ttl: 60000 },
+});
+// Any add with same dedup ID within 60s is ignored
+```
+
+## Manual Rate Limiting
+
+Handle external API rate limits (e.g., 429 responses):
+
+```ts
+import { Worker } from "bullmq";
+
+const worker = new Worker(
+  "api-calls",
+  async () => {
+    const [isRateLimited, duration] = await callExternalApi();
+    if (isRateLimited) {
+      await worker.rateLimit(duration);
+      throw Worker.RateLimitError();
+    }
+  },
+  {
+    connection,
+    limiter: { max: 1, duration: 500 }, // REQUIRED: must set limiter for rateLimit to work
+  },
+);
+```
+
+## Static Rate Limiting
+
+```ts
+const worker = new Worker("painter", async (job) => paintCar(job), {
+  limiter: {
+    max: 10, // max 10 jobs
+    duration: 1000, // per 1 second
+  },
+});
+```
+
+The rate limiter is **global** across all workers for the queue.
+
+## Global Concurrency
+
+Limit to 1 job processing at a time across all workers:
+
+```ts
+await queue.setGlobalConcurrency(1);
+```
+
+## Failing Fast When Redis Is Down
+
+For producer services (HTTP endpoints), disable offline queue so calls fail immediately:
+
+```ts
+import { Redis } from "ioredis";
+
+const connection = new Redis({
+  maxRetriesPerRequest: 1,
+  enableOfflineQueue: false,
+});
+
+const queue = new Queue("q", { connection });
+
+try {
+  await queue.add("job", data);
+} catch (err) {
+  // Redis is down — return 503 to the client
+}
+```
+
+## Redis Cluster
+
+```ts
+import { Cluster } from "ioredis";
+
+const connection = new Cluster(
+  [
+    { host: "node1", port: 6380 },
+    { host: "node2", port: 6380 },
+  ],
+  {
+    natMap: {
+      /* ... */
+    },
+  },
+);
+
+const queue = new Queue("q", { connection, prefix: "{myprefix}" });
+```
+
+Use `{hashTag}` prefix to ensure all keys for a queue land on the same slot.

package/skills/bullmq/references/production.md

@@ -0,0 +1,308 @@
+# Production Guide
+
+## Table of Contents
+
+- [Redis Configuration](#redis-configuration)
+- [Connection Strategy](#connection-strategy)
+- [Graceful Shutdown](#graceful-shutdown)
+- [Retry Strategies](#retry-strategies)
+- [Stalled Jobs](#stalled-jobs)
+- [Sandboxed Processors](#sandboxed-processors)
+- [Concurrency](#concurrency)
+- [Auto-Job Removal](#auto-job-removal)
+- [Error Handling](#error-handling)
+- [Monitoring with Prometheus](#monitoring-with-prometheus)
+- [Data Security](#data-security)
+- [Troubleshooting Checklist](#troubleshooting-checklist)
+
+## Redis Configuration
+
+### Persistence
+
+Enable AOF (Append Only File) for durability. 1-second fsync is sufficient for most apps:
+
+```
+# redis.conf
+appendonly yes
+appendfsync everysec
+```
+
+### Memory Policy
+
+**Critical:** BullMQ will malfunction if Redis evicts keys.
+
+```
+maxmemory-policy noeviction
+```
+
+## Connection Strategy
+
+Different needs for producers vs consumers:
+
+### Producers (Queue class) — fail fast
+
+```ts
+import { Redis } from "ioredis";
+
+const producerConn = new Redis({
+  host: "redis.example.com",
+  port: 6379,
+  maxRetriesPerRequest: 1, // fail quickly on disconnect
+  enableOfflineQueue: false, // don't queue commands when offline
+});
+
+const queue = new Queue("q", { connection: producerConn });
+```
+
+### Consumers (Worker class) — wait indefinitely
+
+```ts
+const workerConn = new Redis({
+  host: "redis.example.com",
+  port: 6379,
+  maxRetriesPerRequest: null, // REQUIRED for workers — retry forever
+  // enableOfflineQueue: true  // default, keeps queuing commands
+});
+
+const worker = new Worker("q", processor, { connection: workerConn });
+```
+
+### Retry Strategy
+
+BullMQ default (for internally created connections):
+
+```ts
+retryStrategy: (times) => Math.max(Math.min(Math.exp(times), 20000), 1000);
+// Exponential backoff: min 1s, max 20s
+```
+
+## Graceful Shutdown
+
+```ts
+const gracefulShutdown = async (signal: string) => {
+  console.log(`Received ${signal}, closing worker...`);
+  await worker.close();
+  process.exit(0);
+};
+
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
+```
+
+If the worker doesn't close before the process is killed, in-progress jobs become **stalled** and are re-processed after ~30 seconds by another worker.
+
+## Retry Strategies
+
+### Fixed Backoff
+
+Retry after a constant delay:
+
+```ts
+await queue.add("job", data, {
+  attempts: 3,
+  backoff: { type: "fixed", delay: 1000 }, // retry every 1s
+  // With jitter (0-1, randomizes between delay*jitter and delay):
+  // backoff: { type: "fixed", delay: 1000, jitter: 0.5 },
+});
+```
+
+### Exponential Backoff
+
+Retry after `2^(attempts-1) * delay` ms:
+
+```ts
+await queue.add("job", data, {
+  attempts: 5,
+  backoff: { type: "exponential", delay: 1000 },
+  // Attempt 1: 1s, Attempt 2: 2s, Attempt 3: 4s, Attempt 4: 8s, Attempt 5: 16s
+});
+```
+
+### Custom Backoff
+
+Define on the worker:
+
+```ts
+const worker = new Worker("q", processor, {
+  settings: {
+    backoffStrategy: (attemptsMade, type, err, job) => {
+      if (type === "linear") return attemptsMade * 1000;
+      if (type === "custom-exp") return Math.pow(2, attemptsMade) * 500;
+      throw new Error("unknown type");
+    },
+  },
+});
+
+// Use in job options
+await queue.add("job", data, {
+  attempts: 5,
+  backoff: { type: "linear" },
+});
+```
+
+**Special return values from `backoffStrategy`:**
+
+- `0` → move to end of waiting list (or back to prioritized if priority > 0)
+- `-1` → don't retry, move to failed immediately
+
+### Default Job Options
+
+Set retry defaults for all jobs in a queue:
+
+```ts
+const queue = new Queue("q", {
+  defaultJobOptions: {
+    attempts: 3,
+    backoff: { type: "exponential", delay: 1000 },
+    removeOnComplete: { count: 200 },
+    removeOnFail: { count: 1000 },
+  },
+});
+```
+
+## Stalled Jobs
+
+A job becomes stalled when the worker holding it doesn't renew its lock within `stalledInterval` (default: 30s). Causes:
+
+- CPU-intensive synchronous code blocking the event loop
+- Process crash or kill without graceful shutdown
+
+Stalled jobs are automatically moved back to waiting. After `maxStalledCount` (default: 1), they move to failed.
+
+**Prevention:**
+
+- Avoid blocking the event loop — use `async`/`await`, break CPU work into chunks
+- Use sandboxed processors for CPU-intensive tasks
+- Increase `stalledInterval` if jobs legitimately need long uninterrupted processing
+
+## Sandboxed Processors
+
+Run processors in separate child processes for CPU-intensive work:
+
+```ts
+// processor.ts (separate file)
+import { SandboxedJob } from "bullmq";
+
+export default async function (job: SandboxedJob) {
+  // CPU-intensive work — runs in a child process
+  return heavyComputation(job.data);
+}
+
+// main.ts
+const worker = new Worker("q", "./processor.ts", { connection });
+```
+
+Benefits: isolates CPU-heavy work, prevents stalled jobs, true parallelism with `concurrency > 1`.
+
+## Concurrency
+
+### Local Concurrency (single worker)
+
+```ts
+const worker = new Worker("q", processor, { concurrency: 50 });
+```
+
+Only effective for I/O-bound (async) work. For CPU-bound work, use sandboxed processors.
+
+### Multiple Workers (recommended for high availability)
+
+Run workers across multiple processes/machines. Combine with local concurrency:
+
+```ts
+// Each machine runs:
+const worker = new Worker("q", processor, { concurrency: 10 });
+// 5 machines × 10 concurrency = 50 jobs processed concurrently
+```
+
+### Global Concurrency
+
+Limit total concurrent processing across ALL workers:
+
+```ts
+await queue.setGlobalConcurrency(1); // only 1 job at a time, globally
+```
+
+### Global Rate Limit
+
+```ts
+const queue = new Queue("q");
+// Must configure on the queue, not the worker
+await queue.setGlobalConcurrency(5); // combined with worker limiter
+
+// Check if rate limited
+const ttl = await queue.getRateLimitTtl(100);
+if (ttl > 0) console.log("Queue is rate limited");
+
+// Reset rate limit
+await queue.removeRateLimitKey();
+```
+
+## Auto-Job Removal
+
+By default, completed and failed jobs are kept forever. Always configure removal:
+
+```ts
+const queue = new Queue("q", {
+  defaultJobOptions: {
+    removeOnComplete: { count: 100, age: 3600 }, // keep 100 or 1 hour
+    removeOnFail: { count: 5000 }, // keep last 5000 failures
+  },
+});
+```
+
+## Error Handling
+
+Always attach error handlers to prevent unhandled exceptions:
+
+```ts
+worker.on("error", (err) => {
+  logger.error(err, "Worker error");
+});
+
+queue.on("error", (err) => {
+  logger.error(err, "Queue error");
+});
+
+// Global safety net
+process.on("uncaughtException", (err) => {
+  logger.error(err, "Uncaught exception");
+});
+
+process.on("unhandledRejection", (reason, promise) => {
+  logger.error({ promise, reason }, "Unhandled rejection");
+});
+```
+
+**Important:** processor functions must throw `Error` objects (not strings or other types).
+
+## Monitoring with Prometheus
+
+```ts
+import { Queue, MetricsTime } from "bullmq";
+
+const queue = new Queue("q", {
+  metrics: {
+    maxDataPoints: MetricsTime.ONE_WEEK * 2, // collect 2 weeks of data
+  },
+});
+
+// Retrieve metrics
+const completedMetrics = await queue.getMetrics("completed");
+// { meta: { count, prevCount }, data: number[] }
+
+const failedMetrics = await queue.getMetrics("failed");
+```
+
+## Data Security
+
+Job data is stored in **plain text** in Redis. Never store sensitive data (passwords, tokens, PII) in job payloads. If unavoidable, encrypt sensitive fields before adding to the queue.
+
+## Troubleshooting Checklist
+
+1. **Jobs not processing?** Check worker is connected to the same queue name with matching `prefix`.
+2. **Stalled jobs?** CPU blocking the event loop — use sandboxed processors or break up work.
+3. **Missing error handler?** Worker may silently stop processing — always attach `worker.on("error", ...)`.
+4. **Redis memory growing?** Configure `removeOnComplete`/`removeOnFail`, check `maxmemory-policy`.
+5. **Delayed jobs not firing?** Ensure Redis is reachable and no clock skew issues.
+6. **Rate limiting not working?** `limiter` must be set on the worker options for `rateLimit()` to function.
+7. **ioredis keyPrefix?** Don't use it — use BullMQ's `prefix` option instead.

package/skills/composition-patterns/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: composition-patterns
+description: React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.
+---
+
+# React Composition Patterns
+
+Composition patterns for building flexible, maintainable React components. Avoid
+boolean prop proliferation by using compound components, lifting state, and
+composing internals. These patterns make codebases easier for both humans and AI
+agents to work with as they scale.
+
+## When NOT to Use
+
+Skip these patterns when: fewer than 3 props, simple variants, or single-use components.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Refactoring components with many boolean props
+- Building reusable component libraries
+- Designing flexible component APIs
+- Reviewing component architecture
+- Working with compound components or context providers
+
+## Rule Categories by Priority
+
+| Priority | Category                | Impact | Prefix          |
+| -------- | ----------------------- | ------ | --------------- |
+| 1        | Component Architecture  | HIGH   | `architecture-` |
+| 2        | State Management        | MEDIUM | `state-`        |
+| 3        | Implementation Patterns | MEDIUM | `patterns-`     |
+| 4        | React 19 APIs           | MEDIUM | `react19-`      |
+
+## Quick Reference
+
+### 1. Component Architecture (HIGH)
+
+- **Avoid boolean props** — Don't add boolean props like `isThread`, `isEditing`, `isDMThread` to customize behavior. Each boolean doubles possible states. Use composition instead — see [references/architecture-avoid-boolean-props.md](references/architecture-avoid-boolean-props.md)
+- **Compound components** — Structure complex components with shared context so each subcomponent accesses state via context, not props — see [references/architecture-compound-components.md](references/architecture-compound-components.md)
+
+### 2. State Management (MEDIUM)
+
+- **Decouple implementation** — Provider is the only place that knows how state is managed — see [references/state-decouple-implementation.md](references/state-decouple-implementation.md)
+- **Context interface** — Define generic interface with `state`, `actions`, `meta` for dependency injection — see [references/state-context-interface.md](references/state-context-interface.md)
+- **Lift state** — Move state into provider components for sibling access — see [references/state-lift-state.md](references/state-lift-state.md)
+
+### 3. Implementation Patterns (MEDIUM)
+
+- **Explicit variants** — Create explicit variant components instead of boolean modes — see [references/patterns-explicit-variants.md](references/patterns-explicit-variants.md)
+- **Children over render props** — Use `children` for composition instead of `renderX` props — see [references/patterns-children-over-render-props.md](references/patterns-children-over-render-props.md)
+
+### 4. React 19 APIs (MEDIUM)
+
+> **React 19+ only.** Skip this section if using React 18 or earlier.
+
+- **No forwardRef** — Don't use `forwardRef`; pass `ref` as a regular prop. Use `use()` instead of `useContext()` — see [references/react19-no-forwardref.md](references/react19-no-forwardref.md)