@jgamaraalv/ts-dev-kit 1.0.0

package/skills/fastify-best-practices/references/hooks-and-lifecycle.md

@@ -0,0 +1,122 @@
+# Hooks & Lifecycle
+
+## Table of Contents
+
+- [Request/Reply hooks (in execution order)](#requestreply-hooks-in-execution-order)
+- [Application hooks](#application-hooks)
+- [Hook signatures](#hook-signatures)
+- [Early response pattern](#early-response-pattern)
+- [Scope rules](#scope-rules)
+- [Common patterns](#common-patterns)
+- [Gotchas](#gotchas)
+
+## Request/Reply hooks (in execution order)
+
+| Hook               | Signature                   | When                                                                  | Can modify response?        |
+| ------------------ | --------------------------- | --------------------------------------------------------------------- | --------------------------- |
+| `onRequest`        | `(request, reply)`          | First hook; body is `undefined`                                       | Yes                         |
+| `preParsing`       | `(request, reply, payload)` | Before body parsing; receives raw stream                              | Yes (return new stream)     |
+| `preValidation`    | `(request, reply)`          | After parsing, before schema validation                               | Yes                         |
+| `preHandler`       | `(request, reply)`          | After validation, before handler                                      | Yes                         |
+| _handler_          | `(request, reply)`          | Route handler                                                         | Yes                         |
+| `preSerialization` | `(request, reply, payload)` | Before response serialization (skipped for string/buffer/stream/null) | Yes (return new payload)    |
+| `onSend`           | `(request, reply, payload)` | Before sending; payload is serialized string/buffer                   | Yes (return new payload)    |
+| `onResponse`       | `(request, reply)`          | After response sent                                                   | No                          |
+| `onError`          | `(request, reply, error)`   | When error thrown                                                     | No (read-only, for logging) |
+| `onTimeout`        | `(request, reply)`          | Request timed out                                                     | No                          |
+| `onRequestAbort`   | `(request)`                 | Client closed connection                                              | No                          |
+
+## Application hooks
+
+| Hook         | Signature          | When                                |
+| ------------ | ------------------ | ----------------------------------- |
+| `onReady`    | `()`               | Before server starts listening      |
+| `onListen`   | `()`               | After server starts listening       |
+| `preClose`   | `()`               | Before in-flight requests complete  |
+| `onClose`    | `(instance)`       | After in-flight requests complete   |
+| `onRoute`    | `(routeOptions)`   | New route registered (synchronous!) |
+| `onRegister` | `(instance, opts)` | New plugin context created          |
+
+## Hook signatures
+
+**Async (preferred):**
+
+```ts
+fastify.addHook("onRequest", async (request, reply) => {
+  // do work; throw to abort
+});
+```
+
+**Callback:**
+
+```ts
+fastify.addHook("onRequest", (request, reply, done) => {
+  // do work; call done() to continue, done(err) to abort
+  done();
+});
+```
+
+**With payload (preParsing, preSerialization, onSend):**
+
+```ts
+fastify.addHook("onSend", async (request, reply, payload) => {
+  return modifiedPayload; // must return new payload
+});
+```
+
+## Early response pattern
+
+Send response from a hook to short-circuit the lifecycle:
+
+```ts
+fastify.addHook("onRequest", async (request, reply) => {
+  if (!request.headers.authorization) {
+    return reply.code(401).send({ error: "Unauthorized" });
+    // Remaining hooks and handler are skipped
+  }
+});
+```
+
+In callback style: call `reply.send()` without calling `done()`.
+
+## Scope rules
+
+- **App-level hooks** run for ALL routes (including child plugin routes)
+- **Route-level hooks** run AFTER app-level hooks of the same type
+- **Encapsulated hooks** only affect routes within the same plugin scope
+- **Exception**: `onClose` does NOT respect encapsulation (always global)
+- Multiple hooks of the same type: specified as arrays `preHandler: [fn1, fn2]`
+
+## Common patterns
+
+**Request timing:**
+
+```ts
+fastify.addHook("onRequest", async (request) => {
+  request.startTime = Date.now();
+});
+fastify.addHook("onResponse", async (request, reply) => {
+  request.log.info({ ms: Date.now() - request.startTime }, "request completed");
+});
+```
+
+**Auth guard (plugin-scoped):**
+
+```ts
+function authPlugin(fastify, opts, done) {
+  fastify.addHook("onRequest", async (request, reply) => {
+    const token = request.headers.authorization;
+    if (!token) return reply.code(401).send({ error: "Unauthorized" });
+    request.user = await verifyToken(token);
+  });
+  done();
+}
+```
+
+## Gotchas
+
+- `onRequest`: body is always `undefined` (parsing hasn't happened yet)
+- `onError`: read-only — use `setErrorHandler()` to modify error responses
+- `preSerialization`: skipped for strings, buffers, streams, and null payloads
+- Don't use async functions with streams in hooks — use callback style
+- Hook errors in async: just `throw`; in callback: pass to `done(err)`

package/skills/fastify-best-practices/references/plugins-and-encapsulation.md

@@ -0,0 +1,137 @@
+# Plugins & Encapsulation
+
+## Table of Contents
+
+- [Creating a plugin](#creating-a-plugin)
+- [Registering plugins](#registering-plugins)
+- [fastify-plugin wrapper](#fastify-plugin-wrapper)
+  - [When to use fastify-plugin](#when-to-use-fastify-plugin)
+- [Encapsulation rules](#encapsulation-rules)
+- [Plugin structure pattern](#plugin-structure-pattern)
+- [Plugin timeout](#plugin-timeout)
+- [Checking plugin registration](#checking-plugin-registration)
+- [Gotchas](#gotchas)
+
+## Creating a plugin
+
+**Callback plugin (FastifyPluginCallback -- project convention):**
+
+```ts
+import type { FastifyPluginCallback } from "fastify";
+
+const myPlugin: FastifyPluginCallback = (fastify, opts, done) => {
+  fastify.decorate("myService", new MyService(opts));
+  done();
+};
+```
+
+**Async plugin:**
+
+```ts
+async function myPlugin(fastify, opts) {
+  fastify.decorate("myService", new MyService(opts));
+  fastify.get("/my-route", async (request) => {
+    return fastify.myService.getData();
+  });
+}
+```
+
+## Registering plugins
+
+```ts
+fastify.register(myPlugin, { option1: "value" });
+
+// With prefix (all routes inside get this prefix)
+fastify.register(myPlugin, { prefix: "/api/v1" });
+```
+
+## fastify-plugin wrapper
+
+By default, `register()` creates a **new encapsulation scope**. Decorators, hooks, and schemas registered inside are invisible to the parent and siblings.
+
+**Use `fastify-plugin` to break encapsulation** and share state with the parent:
+
+```ts
+import fp from "fastify-plugin";
+
+export default fp(myPlugin, {
+  name: "my-plugin", // for hasPlugin() checks
+  fastify: "5.x", // version constraint
+  dependencies: ["other-plugin"], // require other plugins first
+});
+```
+
+### When to use fastify-plugin
+
+| Scenario                           | Use fp? | Why                             |
+| ---------------------------------- | ------- | ------------------------------- |
+| Shared service (DB, Redis, auth)   | Yes     | Parent and siblings need access |
+| Scoped routes (e.g., `/admin/*`)   | No      | Routes stay isolated            |
+| Decorating request/reply           | Yes     | Available to all routes         |
+| Adding application hooks           | Yes     | Hooks apply globally            |
+| Feature module with its own routes | No      | Encapsulation is desired        |
+
+## Encapsulation rules
+
+```
+Root context (parent)
+├── Plugin A (registered with fp → shares with root)
+│   └── decorators visible to root and siblings
+├── Plugin B (registered WITHOUT fp → scoped)
+│   ├── decorators invisible to root and Plugin A
+│   └── BUT can see root decorators (inheritance flows DOWN)
+└── Plugin C
+    └── can see root + Plugin A decorators
+    └── cannot see Plugin B decorators
+```
+
+**Key rules:**
+
+1. Child contexts inherit from parent (decorators, hooks, schemas)
+2. Parent contexts CANNOT see child decorators/hooks
+3. `fastify-plugin` makes child behave as if registered in parent scope
+4. Hooks always execute parent-first, then child
+5. Same decorator name in different scopes = OK (no collision)
+
+## Plugin structure pattern
+
+Order inside a plugin: **decorators → hooks → routes**
+
+```ts
+import fp from "fastify-plugin";
+
+export default fp(
+  async (fastify, opts) => {
+    // 1. Decorators first
+    fastify.decorate("db", await connectDB(opts.dbUrl));
+
+    // 2. Hooks second
+    fastify.addHook("onClose", async () => {
+      await fastify.db.close();
+    });
+
+    // 3. Routes last (if any)
+    fastify.get("/health", async () => ({ status: "ok" }));
+  },
+  { name: "database" },
+);
+```
+
+## Plugin timeout
+
+Default: 10 seconds. If a plugin takes longer to load, Fastify throws `FST_ERR_PLUGIN_TIMEOUT`.
+
+Fix: set `pluginTimeout: 0` on the Fastify instance to disable, or increase the timeout.
+
+## Checking plugin registration
+
+```ts
+fastify.hasPlugin("my-plugin"); // true if registered (uses fp name)
+```
+
+## Gotchas
+
+- **Lint errors with async plugin signatures**: See CLAUDE.md for why callback plugins avoid the `require-await` lint issue
+- **Plugin options are scoped**: `prefix`, `logLevel`, `logSerializers` are ignored when using `fastify-plugin`
+- **Decorator reference types**: `decorateRequest("data", {})` shares one object across ALL requests. Use `null` + `onRequest` hook instead
+- **await register**: You can `await fastify.register(plugin)` for sequencing, but the plugin still loads in its own tick

package/skills/fastify-best-practices/references/request-reply-errors.md

@@ -0,0 +1,189 @@
+# Request, Reply & Error Handling
+
+## Table of Contents
+
+- [Request object](#request-object)
+  - [Key properties](#key-properties)
+  - [Methods](#methods)
+- [Reply object](#reply-object)
+  - [Key methods](#key-methods)
+  - [Key properties](#key-properties-1)
+- [Error handling](#error-handling)
+  - [Default behavior](#default-behavior)
+  - [Custom error handler](#custom-error-handler)
+  - [Creating errors with status codes](#creating-errors-with-status-codes)
+  - [Error handler scoping](#error-handler-scoping)
+  - [Key FST_ERR codes](#key-fst_err-codes)
+  - [404 handler](#404-handler)
+- [Gotchas](#gotchas)
+
+## Request object
+
+### Key properties
+
+| Property       | Type            | Description                     |
+| -------------- | --------------- | ------------------------------- |
+| `query`        | object          | Parsed query string             |
+| `body`         | any             | Parsed request body             |
+| `params`       | object          | URL parameters                  |
+| `headers`      | object          | Request headers                 |
+| `raw`          | IncomingMessage | Node.js raw request             |
+| `id`           | string          | Request ID                      |
+| `ip`           | string          | Client IP (respects trustProxy) |
+| `ips`          | string[]        | Proxy chain IPs                 |
+| `hostname`     | string          | Host from header                |
+| `protocol`     | string          | `http` or `https`               |
+| `method`       | string          | HTTP method                     |
+| `url`          | string          | Request URL                     |
+| `routeOptions` | object          | Route config, schema, bodyLimit |
+| `server`       | FastifyInstance | Fastify instance                |
+| `log`          | Logger          | Request-scoped Pino logger      |
+| `is404`        | boolean         | True if no route matched        |
+
+### Methods
+
+```ts
+request.getValidationFunction("body"); // get compiled validator
+request.validateInput(data, "querystring"); // validate arbitrary data
+```
+
+## Reply object
+
+### Key methods
+
+```ts
+reply.code(201); // set status code (chainable)
+reply.status(201); // alias for .code()
+reply.header("X-Custom", "val"); // set single header (chainable)
+reply.headers({ k: "v" }); // set multiple headers
+reply.type("application/json"); // set Content-Type (chainable)
+reply.redirect("/new-url"); // redirect (302 default)
+reply.redirect("/url", 301); // redirect with status
+
+reply.send(payload); // send response
+// payload can be: object, string, Buffer, Stream, Error, null
+
+reply.hijack(); // take over response (skips serialization + onSend)
+reply.callNotFound(); // invoke 404 handler
+
+reply.serialize(payload); // serialize using route's serializer
+reply.serializer(fn); // set custom serializer for this reply
+
+reply.getHeader("key"); // get response header
+reply.hasHeader("key"); // check header exists
+reply.removeHeader("key"); // remove header
+```
+
+### Key properties
+
+| Property      | Type            | Description               |
+| ------------- | --------------- | ------------------------- |
+| `statusCode`  | number          | Current status code       |
+| `sent`        | boolean         | True after response sent  |
+| `elapsedTime` | number          | Ms since request received |
+| `raw`         | ServerResponse  | Node.js raw response      |
+| `request`     | Request         | Associated request        |
+| `server`      | FastifyInstance | Fastify instance          |
+
+## Error handling
+
+### Default behavior
+
+Fastify catches errors from:
+
+- Sync `throw` in handler
+- Rejected promise in async handler
+- `done(error)` in callback handler
+
+Default error response:
+
+```json
+{ "statusCode": 500, "error": "Internal Server Error", "message": "..." }
+```
+
+### Custom error handler
+
+```ts
+fastify.setErrorHandler((error, request, reply) => {
+  request.log.error(error);
+
+  // Validation errors
+  if (error.validation) {
+    return reply.code(400).send({
+      error: "Validation Error",
+      message: error.message,
+      details: error.validation,
+    });
+  }
+
+  // Custom app errors
+  const statusCode = error.statusCode ?? 500;
+  reply.code(statusCode).send({
+    error: statusCode >= 500 ? "Internal Server Error" : error.message,
+    statusCode,
+  });
+});
+```
+
+### Creating errors with status codes
+
+```ts
+// Option 1: Set statusCode on Error
+const err = new Error("Not found");
+err.statusCode = 404;
+throw err;
+
+// Option 2: reply.send(error) with code
+reply.code(404).send(new Error("Not found"));
+
+// Option 3: Use http-errors
+import createError from "http-errors";
+throw createError(404, "User not found");
+```
+
+### Error handler scoping
+
+Error handlers are encapsulated. A plugin can set its own error handler:
+
+```ts
+fastify.register(async (instance) => {
+  instance.setErrorHandler((error, request, reply) => {
+    // handles errors only for routes in this plugin
+  });
+});
+```
+
+If a new error is thrown inside an error handler, the **parent** error handler handles it.
+
+### Key FST_ERR codes
+
+| Code                         | Description                  |
+| ---------------------------- | ---------------------------- |
+| `FST_ERR_CTP_BODY_TOO_LARGE` | Body exceeds bodyLimit       |
+| `FST_ERR_VALIDATION`         | Schema validation failed     |
+| `FST_ERR_BAD_STATUS_CODE`    | Invalid HTTP status code     |
+| `FST_ERR_REP_ALREADY_SENT`   | Reply already sent           |
+| `FST_ERR_HOOK_TIMEOUT`       | Hook timed out               |
+| `FST_ERR_PLUGIN_TIMEOUT`     | Plugin took too long to load |
+| `FST_ERR_DUPLICATED_ROUTE`   | Route already registered     |
+
+Access: `import { errorCodes } from "fastify"` → check with `instanceof`.
+
+### 404 handler
+
+```ts
+fastify.setNotFoundHandler((request, reply) => {
+  reply.code(404).send({ error: "Not Found", message: `Route ${request.url} not found` });
+});
+
+// With preHandler hooks:
+fastify.setNotFoundHandler({ preHandler: [authHook] }, handler);
+```
+
+## Gotchas
+
+- **reply.send() in async**: always `return reply.send()` or `return reply` — otherwise Fastify also sends the return value
+- **reply.sent**: check this before sending to avoid `FST_ERR_REP_ALREADY_SENT`
+- **reply.hijack()**: use for SSE, WebSockets — Fastify won't touch the response after this
+- **Error objects only**: `reply.send("string error")` sends as plain text, not through error handler. Always send `Error` instances
+- **Streams**: if a stream errors after headers are sent, Fastify can't change the status code

package/skills/fastify-best-practices/references/routes-and-handlers.md

@@ -0,0 +1,134 @@
+# Routes & Handlers
+
+## Table of Contents
+
+- [Route declaration](#route-declaration)
+- [URL parameters](#url-parameters)
+- [Async handler patterns](#async-handler-patterns)
+- [Route-level config](#route-level-config)
+- [Route constraints](#route-constraints)
+- [Gotchas](#gotchas)
+
+## Route declaration
+
+**Full form:**
+
+```ts
+fastify.route({
+  method: "GET",           // or ["GET", "POST"]
+  url: "/users/:id",
+  schema: { ... },         // validation + serialization
+  handler: async (request, reply) => { ... },
+  // Optional hooks (run AFTER app-level hooks):
+  onRequest: [fn],
+  preHandler: [fn],
+  preSerialization: [fn],
+  onSend: [fn],
+  onResponse: [fn],
+  onError: [fn],
+  onTimeout: [fn],
+  // Options:
+  config: { ... },         // access via reply.routeOptions.config
+  bodyLimit: 1048576,
+  logLevel: "warn",
+  constraints: { version: "1.0.0", host: "example.com" },
+});
+```
+
+**Shorthand:**
+
+```ts
+fastify.get(url, [options], handler);
+fastify.post(url, [options], handler);
+fastify.put(url, [options], handler);
+fastify.delete(url, [options], handler);
+fastify.patch(url, [options], handler);
+fastify.head(url, [options], handler);
+fastify.options(url, [options], handler);
+fastify.all(url, [options], handler); // all HTTP methods
+```
+
+## URL parameters
+
+```ts
+// Parametric
+fastify.get("/users/:id", handler); // request.params.id
+
+// Multiple params
+fastify.get("/users/:id/posts/:postId", handler);
+
+// Optional param
+fastify.get("/posts/:id?", handler); // id is optional
+
+// Wildcard (catch-all)
+fastify.get("/files/*", handler); // request.params["*"]
+
+// Multi-param with separators
+fastify.get("/near/:lat-:lng/radius/:r", handler);
+
+// Regex (expensive — avoid on hot paths)
+fastify.get("/file/:name(^\\d+).png", handler);
+
+// Escape colon (literal colon)
+fastify.post("/name::verb"); // matches /name:verb
+```
+
+## Async handler patterns
+
+**Return value (preferred):**
+
+```ts
+fastify.get("/", async (request, reply) => {
+  const data = await getData();
+  return data; // auto-sends with 200
+});
+```
+
+**With status code:**
+
+```ts
+fastify.post("/", async (request, reply) => {
+  const user = await createUser(request.body);
+  return reply.code(201).send(user);
+});
+```
+
+**Deferred reply (callback outside promise chain):**
+
+```ts
+fastify.get("/", async (request, reply) => {
+  setImmediate(() => reply.send({ hello: "world" }));
+  await reply; // MUST await reply when sending outside promise
+});
+```
+
+## Route-level config
+
+Access custom config via `reply.routeOptions.config`:
+
+```ts
+fastify.get("/hello", { config: { greeting: "Hi!" } }, (req, reply) => {
+  reply.send(reply.routeOptions.config.greeting);
+});
+```
+
+## Route constraints
+
+```ts
+// Version constraint (requires Accept-Version header)
+fastify.get("/", { constraints: { version: "1.0.0" } }, handlerV1);
+fastify.get("/", { constraints: { version: "2.0.0" } }, handlerV2);
+
+// Host constraint
+fastify.get("/", { constraints: { host: "api.example.com" } }, handler);
+```
+
+## Gotchas
+
+- **Don't mix async + callback** — pick one pattern per handler
+- **Don't return undefined** in async handlers (Fastify waits for response)
+- **Arrow functions** don't bind `this` to Fastify instance — use `function` if you need `this`
+- **Regex params** hurt routing performance — use sparingly
+- **Multiple params per path segment** (`:lat-:lng`) reduce router perf
+- **HEAD routes** auto-created from GET unless you define HEAD first; disable with `exposeHeadRoutes: false`
+- **Version constraints** require `Accept-Version` header in requests; add `Vary` header to prevent cache poisoning