@jgamaraalv/ts-dev-kit 1.0.0

package/skills/fastify-best-practices/references/server-and-options.md

@@ -0,0 +1,127 @@
+# Server Factory & Options
+
+## Table of Contents
+
+- [Factory: fastify(options)](#factory-fastifyoptions)
+  - [Core options](#core-options)
+  - [Router options](#router-options)
+  - [Security options](#security-options)
+  - [Validation/serialization options](#validationserialization-options)
+  - [Advanced options](#advanced-options)
+- [Key server methods](#key-server-methods)
+- [Key properties](#key-properties)
+- [Graceful shutdown pattern](#graceful-shutdown-pattern)
+
+## Factory: `fastify(options)`
+
+### Core options
+
+| Option                  | Type                  | Default         | Description                                      |
+| ----------------------- | --------------------- | --------------- | ------------------------------------------------ |
+| `logger`                | bool/object           | `false`         | Pino logger config. `true` enables with defaults |
+| `loggerInstance`        | object                | —               | Custom Pino-compatible logger instance           |
+| `disableRequestLogging` | bool/fn               | `false`         | Disable auto request/response logging            |
+| `trustProxy`            | bool/string/number/fn | `false`         | Trust X-Forwarded-\* headers                     |
+| `bodyLimit`             | number                | `1048576` (1MB) | Max request body bytes                           |
+| `maxParamLength`        | number                | 100             | Max URL parameter length                         |
+| `pluginTimeout`         | number                | `10000`         | Max ms for plugin load                           |
+| `requestTimeout`        | number                | `0`             | Max ms to receive full request                   |
+| `connectionTimeout`     | number                | `0`             | Socket timeout ms                                |
+| `keepAliveTimeout`      | number                | `72000`         | HTTP/1 keep-alive timeout ms                     |
+| `requestIdHeader`       | string                | `'request-id'`  | Header for request ID                            |
+| `genReqId`              | fn(rawReq)            | auto-increment  | Custom request ID generator                      |
+
+### Router options
+
+| Option                   | Type | Default | Description                          |
+| ------------------------ | ---- | ------- | ------------------------------------ |
+| `caseSensitive`          | bool | `true`  | Case-sensitive route matching        |
+| `ignoreTrailingSlash`    | bool | `false` | Match `/foo` and `/foo/`             |
+| `ignoreDuplicateSlashes` | bool | `false` | Treat `//` as `/`                    |
+| `exposeHeadRoutes`       | bool | `true`  | Auto-create HEAD for GET routes      |
+| `return503OnClosing`     | bool | `true`  | 503 for new requests during shutdown |
+
+### Security options
+
+| Option                   | Type   | Default   | Description                                                 |
+| ------------------------ | ------ | --------- | ----------------------------------------------------------- |
+| `onProtoPoisoning`       | string | `'error'` | Handle `__proto__` in JSON: `'error'`/`'remove'`/`'ignore'` |
+| `onConstructorPoisoning` | string | `'error'` | Handle `constructor` in JSON                                |
+
+### Validation/serialization options
+
+| Option           | Type   | Default | Description                             |
+| ---------------- | ------ | ------- | --------------------------------------- |
+| `ajv`            | object | —       | `{ customOptions, plugins }` for Ajv v8 |
+| `serializerOpts` | object | —       | fast-json-stringify options             |
+
+### Advanced options
+
+| Option              | Type    | Default | Description                   |
+| ------------------- | ------- | ------- | ----------------------------- |
+| `http2`             | bool    | `false` | Enable HTTP/2                 |
+| `https`             | object  | —       | TLS options                   |
+| `serverFactory`     | fn      | —       | Custom HTTP server factory    |
+| `rewriteUrl`        | fn(req) | —       | Rewrite request URL           |
+| `querystringParser` | fn      | —       | Custom query string parser    |
+| `frameworkErrors`   | fn      | —       | Handle framework-level errors |
+
+## Key server methods
+
+```
+.listen({ port, host })          → Start server (returns Promise)
+.close()                         → Graceful shutdown (returns Promise)
+.ready()                         → Wait for plugins to load (returns Promise)
+.inject(request)                 → Fake HTTP request for testing (returns Promise)
+
+.register(plugin, opts?)         → Register plugin (creates new scope)
+.addHook(name, handler)          → Add lifecycle hook
+.route(options)                  → Add route (full form)
+.get/post/put/delete/patch(...)  → Add route (shorthand)
+
+.decorate(name, value)           → Decorate server instance
+.decorateRequest(name, value)    → Decorate Request prototype
+.decorateReply(name, value)      → Decorate Reply prototype
+.hasDecorator(name)              → Check if decorator exists
+
+.addSchema({ $id, ... })         → Add reusable JSON schema
+.getSchema(id)                   → Retrieve schema by $id
+.getSchemas()                    → Get all schemas (encapsulation-aware)
+
+.setErrorHandler(fn)             → Set custom error handler
+.setNotFoundHandler(fn)          → Set custom 404 handler
+.setValidatorCompiler(fn)        → Set schema validator compiler
+.setSerializerCompiler(fn)       → Set response serializer compiler
+
+.addContentTypeParser(type, fn)  → Register custom content-type parser
+.hasContentTypeParser(type)      → Check if parser exists
+
+.printRoutes()                   → Print route tree (debugging)
+.printPlugins()                  → Print plugin tree (debugging)
+.addresses()                     → Get listening addresses [{port, family, address}]
+```
+
+## Key properties
+
+```
+.server          → Node.js HTTP/HTTPS server instance
+.log             → Pino logger instance
+.prefix          → Current route prefix (scoped to plugin)
+.pluginName      → Current plugin name (root = 'fastify')
+.version         → Fastify version string
+.initialConfig   → Frozen read-only initial options
+.listeningOrigin → Current listening address string
+```
+
+## Graceful shutdown pattern
+
+```ts
+const signals = ["SIGTERM", "SIGINT"];
+for (const signal of signals) {
+  process.on(signal, async () => {
+    fastify.log.info(`Received ${signal}, shutting down...`);
+    await fastify.close();
+    process.exit(0);
+  });
+}
+```

package/skills/fastify-best-practices/references/typescript-and-logging.md

@@ -0,0 +1,223 @@
+# TypeScript & Logging
+
+## Table of Contents
+
+- [TypeScript Patterns](#typescript-patterns)
+  - [Route generics](#route-generics)
+  - [Type providers (Zod integration)](#type-providers-zod-integration)
+  - [Augmenting FastifyInstance (custom decorators)](#augmenting-fastifyinstance-custom-decorators)
+  - [Plugin typing](#plugin-typing)
+  - [Decorator typing gotchas](#decorator-typing-gotchas)
+  - [Import style (ESM)](#import-style-esm)
+- [Logging with Pino](#logging-with-pino)
+  - [Basic setup](#basic-setup)
+  - [Development (pretty printing)](#development-pretty-printing)
+  - [Production recommendations](#production-recommendations)
+  - [Disable request logging](#disable-request-logging)
+  - [Request-scoped logging](#request-scoped-logging)
+  - [Custom request ID](#custom-request-id)
+
+## TypeScript Patterns
+
+## Route generics
+
+Type request parts using generics:
+
+```ts
+interface CreateUserBody {
+  email: string;
+  name: string;
+}
+
+interface UserParams {
+  id: string;
+}
+
+interface UserQuery {
+  include?: string;
+}
+
+fastify.post<{
+  Body: CreateUserBody;
+  Params: UserParams;
+  Querystring: UserQuery;
+  Headers: { "x-api-key": string };
+}>("/users/:id", async (request) => {
+  request.body.email; // typed as string
+  request.params.id; // typed as string
+  request.query.include; // typed as string | undefined
+});
+```
+
+## Type providers (Zod integration)
+
+```ts
+import Fastify from "fastify";
+import { serializerCompiler, validatorCompiler, ZodTypeProvider } from "fastify-type-provider-zod";
+import { z } from "zod";
+
+const fastify = Fastify().withTypeProvider<ZodTypeProvider>();
+fastify.setValidatorCompiler(validatorCompiler);
+fastify.setSerializerCompiler(serializerCompiler);
+
+fastify.post(
+  "/users",
+  {
+    schema: {
+      body: z.object({ email: z.string().email() }),
+      response: { 201: z.object({ id: z.string() }) },
+    },
+  },
+  async (request) => {
+    request.body.email; // inferred from Zod schema
+    return { id: "123" };
+  },
+);
+```
+
+## Augmenting FastifyInstance (custom decorators)
+
+```ts
+declare module "fastify" {
+  interface FastifyInstance {
+    db: Pool;
+    redis: Redis;
+  }
+  interface FastifyRequest {
+    user?: { id: string; email: string };
+  }
+}
+```
+
+## Plugin typing
+
+See [plugins-and-encapsulation.md](plugins-and-encapsulation.md) for the full `FastifyPluginCallback` and `FastifyPluginAsync` patterns.
+
+**Quick reference for type annotations:**
+
+```ts
+import type { FastifyPluginCallback, FastifyPluginAsync } from "fastify";
+```
+
+## Logging with Pino
+
+## Pino logging configuration
+
+### Basic setup
+
+```ts
+const fastify = Fastify({
+  logger: true, // default Pino with info level
+});
+
+// Or with options:
+const fastify = Fastify({
+  logger: {
+    level: "info",
+  },
+});
+```
+
+### Development (pretty printing)
+
+```ts
+const fastify = Fastify({
+  logger: {
+    level: "debug",
+    transport: {
+      target: "pino-pretty",
+      options: {
+        translateTime: "HH:MM:ss Z",
+        ignore: "pid,hostname",
+      },
+    },
+  },
+});
+```
+
+### Production recommendations
+
+```ts
+const fastify = Fastify({
+  logger: {
+    level: process.env.LOG_LEVEL ?? "info",
+    // Redact sensitive data
+    redact: ["req.headers.authorization", "req.headers.cookie"],
+    serializers: {
+      req(request) {
+        return {
+          method: request.method,
+          url: request.url,
+          hostname: request.hostname,
+          remoteAddress: request.ip,
+        };
+      },
+    },
+  },
+});
+```
+
+### Disable request logging
+
+```ts
+const fastify = Fastify({
+  disableRequestLogging: true, // no auto req/res logs
+});
+
+// Or conditionally:
+const fastify = Fastify({
+  disableRequestLogging: (req) => req.url === "/health",
+});
+```
+
+### Request-scoped logging
+
+Every request has `request.log` — a child logger with `reqId` bound:
+
+```ts
+fastify.get("/", async (request) => {
+  request.log.info("processing request"); // includes reqId
+  request.log.info({ userId: 123 }, "user found"); // structured data
+});
+```
+
+### Custom request ID
+
+```ts
+const fastify = Fastify({
+  requestIdHeader: "x-request-id", // read from header
+  genReqId: (req) => crypto.randomUUID(), // or generate
+  requestIdLogLabel: "reqId", // log field name
+});
+```
+
+## Decorator typing gotchas
+
+**Wrong — shared reference:**
+
+```ts
+fastify.decorateRequest("data", {}); // ALL requests share same object!
+```
+
+**Right — null initial + onRequest assignment:**
+
+```ts
+fastify.decorateRequest("user", null);
+
+fastify.addHook("onRequest", async (request) => {
+  request.user = await getUser(request); // unique per request
+});
+```
+
+## Import style (ESM)
+
+```ts
+// Fastify:
+import Fastify from "fastify";
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+
+// fastify-plugin:
+import fp from "fastify-plugin";
+```
+
+> **ioredis**: See CLAUDE.md for the canonical ioredis import convention (`import { Redis } from "ioredis"`).

package/skills/fastify-best-practices/references/validation-and-serialization.md

@@ -0,0 +1,190 @@
+# Validation & Serialization
+
+## Table of Contents
+
+- [Request validation (JSON Schema + Ajv v8)](#request-validation-json-schema--ajv-v8)
+  - [Ajv defaults](#ajv-defaults)
+  - [Customizing Ajv](#customizing-ajv)
+- [Response serialization (fast-json-stringify)](#response-serialization-fast-json-stringify)
+- [Schema reuse with $ref](#schema-reuse-with-ref)
+- [Custom validator compiler (e.g., Zod)](#custom-validator-compiler-eg-zod)
+- [Error formatting](#error-formatting)
+- [Gotchas](#gotchas)
+
+## Request validation (JSON Schema + Ajv v8)
+
+Fastify validates request data against JSON Schema. Invalid requests get **400** automatically.
+
+```ts
+fastify.post("/users", {
+  schema: {
+    body: {
+      type: "object",
+      required: ["email"],
+      properties: {
+        email: { type: "string", format: "email" },
+        name: { type: "string", minLength: 1, maxLength: 100 },
+        age: { type: "integer", minimum: 0 },
+      },
+      additionalProperties: false,
+    },
+    querystring: {
+      type: "object",
+      properties: {
+        page: { type: "integer", default: 1 },
+        limit: { type: "integer", default: 20, maximum: 100 },
+      },
+    },
+    params: {
+      type: "object",
+      properties: {
+        id: { type: "string", format: "uuid" },
+      },
+    },
+    headers: {
+      type: "object",
+      properties: {
+        "x-api-key": { type: "string" },
+      },
+      required: ["x-api-key"],
+    },
+  },
+  handler: async (request, reply) => { ... },
+});
+```
+
+### Ajv defaults
+
+Fastify configures Ajv with:
+
+- `coerceTypes: true` — strings coerced to numbers/booleans for query/params
+- `removeAdditional: true` — extra properties stripped
+- `useDefaults: true` — missing properties get defaults
+- `allErrors: false` — stops at first error (faster)
+
+### Customizing Ajv
+
+```ts
+const fastify = Fastify({
+  ajv: {
+    customOptions: {
+      allErrors: true, // return all errors
+      removeAdditional: "all", // strip all extra properties
+    },
+    plugins: [ajvFormats], // add format validators
+  },
+});
+```
+
+## Response serialization (fast-json-stringify)
+
+Define response schemas per status code. Fastify uses `fast-json-stringify` for 2-5x faster serialization than `JSON.stringify`, and it **prevents leaking fields** not in the schema.
+
+```ts
+schema: {
+  response: {
+    200: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        email: { type: "string" },
+      },
+    },
+    "4xx": {
+      type: "object",
+      properties: {
+        error: { type: "string" },
+        message: { type: "string" },
+      },
+    },
+    default: {
+      type: "object",
+      properties: {
+        error: { type: "string" },
+      },
+    },
+  },
+}
+```
+
+## Schema reuse with $ref
+
+**Register shared schemas:**
+
+```ts
+fastify.addSchema({
+  $id: "user",
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    email: { type: "string" },
+    name: { type: "string" },
+  },
+});
+
+fastify.addSchema({
+  $id: "pagination",
+  type: "object",
+  properties: {
+    page: { type: "integer", default: 1 },
+    limit: { type: "integer", default: 20 },
+    total: { type: "integer" },
+  },
+});
+```
+
+**Reference in routes:**
+
+```ts
+schema: {
+  response: {
+    200: { $ref: "user#" },           // whole schema
+  },
+}
+
+// Or reference properties:
+schema: {
+  body: {
+    type: "object",
+    properties: {
+      user: { $ref: "user#" },
+      meta: { $ref: "pagination#" },
+    },
+  },
+}
+```
+
+## Custom validator compiler (e.g., Zod)
+
+```ts
+import { serializerCompiler, validatorCompiler } from "fastify-type-provider-zod";
+
+fastify.setValidatorCompiler(validatorCompiler);
+fastify.setSerializerCompiler(serializerCompiler);
+
+// Then in routes:
+fastify.post("/users", {
+  schema: {
+    body: z.object({ email: z.string().email(), name: z.string() }),
+    response: { 201: z.object({ id: z.string(), email: z.string() }) },
+  },
+  handler: async (request) => { ... },
+});
+```
+
+## Error formatting
+
+```ts
+fastify.setSchemaErrorFormatter((errors, dataVar) => {
+  const message = errors.map((e) => `${dataVar}${e.instancePath} ${e.message}`).join("; ");
+  return new Error(message);
+});
+```
+
+## Gotchas
+
+- **No response schema = slow + leaky** — `JSON.stringify()` is used, and all object properties are included
+- **`additionalProperties: false`** is important — without it, extra fields pass validation
+- **Ajv formats** (`email`, `uuid`, `date-time`, etc.) require `ajv-formats` plugin
+- **Schema compilation** happens at startup — errors are thrown during `.listen()`, not at runtime
+- **Shared schemas** are encapsulation-aware — schemas in child plugins are invisible to parents unless using `fastify-plugin`

package/skills/ioredis/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ioredis
+description: "ioredis v5 reference for Node.js Redis client — connection setup, RedisOptions, pipelines, transactions, Pub/Sub, Lua scripting, Cluster, and Sentinel. Use when: (1) creating or configuring Redis connections (standalone, cluster, sentinel), (2) writing Redis commands with ioredis (get/set, pipelines, multi/exec), (3) setting up Pub/Sub or Streams, (4) configuring retryStrategy, TLS, or auto-pipelining, (5) working with Redis Cluster options (scaleReads, NAT mapping), or (6) debugging ioredis connection issues. Important: use named import `import { Redis } from 'ioredis'` for correct TypeScript types with NodeNext."
+---
+
+# ioredis v5 — Node.js Redis Client
+
+ioredis v5.x. Requires Node.js >= 12, Redis >= 2.6.12. 100% TypeScript.
+
+## Critical: Import Style
+
+```ts
+// CORRECT — named import (required for NodeNext / moduleResolution: "nodenext")
+import { Redis } from "ioredis";
+
+// For Cluster:
+import { Redis, Cluster } from "ioredis";
+```
+
+## When to Load References
+
+| Need                                                                           | Reference file                                                       |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| Connection setup, RedisOptions, TLS, retryStrategy, lifecycle                  | [references/connection-options.md](references/connection-options.md) |
+| Core API: pipelines, transactions, Pub/Sub, Lua scripting, scanning, events    | [references/core-api.md](references/core-api.md)                     |
+| Streams, auto-pipelining, transformers, binary data, error handling, debugging | [references/advanced-patterns.md](references/advanced-patterns.md)   |
+| Redis Cluster setup, ClusterOptions, Sentinel config, failover                 | [references/cluster-sentinel.md](references/cluster-sentinel.md)     |
+
+## Quick Reference
+
+| Operation      | Code                                                                       |
+| -------------- | -------------------------------------------------------------------------- |
+| Connect        | `new Redis()` or `new Redis(6379, "host")` or `new Redis("redis://...")`   |
+| Get/Set        | `await redis.set("key", "val")` / `await redis.get("key")`                 |
+| Pipeline       | `await redis.pipeline().set("a","1").get("a").exec()`                      |
+| Transaction    | `await redis.multi().set("a","1").get("a").exec()`                         |
+| Pub/Sub        | `sub.subscribe("ch")` / `sub.on("message", cb)` / `pub.publish("ch", msg)` |
+| Lua script     | `redis.defineCommand("name", { numberOfKeys: 1, lua: "..." })`             |
+| Scan           | `redis.scanStream({ match: "prefix:*", count: 100 })`                      |
+| Graceful close | `await redis.quit()`                                                       |
+| Force close    | `redis.disconnect()`                                                       |
+
+## Common Gotchas
+
+1. **Named import**: Always `import { Redis } from "ioredis"` with NodeNext resolution
+2. **Pub/Sub isolation**: A subscribed client cannot run other commands — use separate instances
+3. **`maxRetriesPerRequest`**: Default is 20. Set to `null` for infinite retries (required by BullMQ)
+4. **Pipeline errors**: `pipeline.exec()` never rejects — errors are in each result's `[0]` position
+5. **`showFriendlyErrorStack`**: Performance cost — never enable in production
+6. **Cluster pipelines**: All keys in a pipeline must hash to slots served by the same node
+7. **`enableAutoPipelining`**: 35-50% throughput improvement, safe to enable globally