@jgamaraalv/ts-dev-kit 1.0.0

package/skills/ioredis/references/connection-options.md

@@ -0,0 +1,187 @@
+# ioredis Connection Options Reference
+
+## Table of Contents
+
+- [RedisOptions type alias](#redisoptions-type-alias)
+- [CommonRedisOptions](#commonredisoptions)
+- [StandaloneConnectionOptions](#standaloneconnectionoptions)
+- [SentinelConnectionOptions](#sentinelconnectionoptions-summary)
+- [retryStrategy patterns](#retrystrategy-patterns)
+- [reconnectOnError patterns](#reconnectonerror-patterns)
+- [TLS configuration](#tls-configuration)
+- [Blocking command timeout](#blocking-command-timeout)
+- [Connection lifecycle](#connection-lifecycle)
+
+## RedisOptions type alias
+
+```ts
+type RedisOptions = CommonRedisOptions & SentinelConnectionOptions & StandaloneConnectionOptions;
+```
+
+All three interfaces are merged. Standalone options include `host`, `port`, `path`, `tls`, and `disconnectTimeout`.
+
+## CommonRedisOptions
+
+| Property                        | Type                                                | Default             | Description                                                             |
+| ------------------------------- | --------------------------------------------------- | ------------------- | ----------------------------------------------------------------------- |
+| `retryStrategy`                 | `(times: number) => number \| void`                 | exponential backoff | Return ms to wait before reconnect. Return `undefined` to stop          |
+| `commandTimeout`                | `number`                                            | `undefined`         | Ms before "Command timed out" error                                     |
+| `blockingTimeout`               | `number`                                            | `undefined`         | Client-side timeout for blocking commands (opt-in, disabled by default) |
+| `blockingTimeoutGrace`          | `number`                                            | `100`               | Grace period ms added to blocking timeouts                              |
+| `socketTimeout`                 | `number`                                            | `undefined`         | Ms of socket inactivity before destroying                               |
+| `keepAlive`                     | `number`                                            | `0`                 | TCP keepalive initial delay in ms. `0` = disabled                       |
+| `noDelay`                       | `boolean`                                           | `true`              | Disable Nagle's algorithm (TCP_NODELAY)                                 |
+| `connectionName`                | `string`                                            | `undefined`         | CLIENT SETNAME value                                                    |
+| `disableClientInfo`             | `boolean`                                           | `false`             | Skip CLIENT SETINFO                                                     |
+| `clientInfoTag`                 | `string`                                            | `undefined`         | Tag appended to library name in CLIENT SETINFO                          |
+| `username`                      | `string`                                            | `undefined`         | AUTH username (Redis >= 6 ACL)                                          |
+| `password`                      | `string`                                            | `undefined`         | AUTH password                                                           |
+| `db`                            | `number`                                            | `0`                 | Database index                                                          |
+| `autoResubscribe`               | `boolean`                                           | `true`              | Re-subscribe channels on reconnect                                      |
+| `autoResendUnfulfilledCommands` | `boolean`                                           | `true`              | Resend pending blocking commands on reconnect                           |
+| `reconnectOnError`              | `(err: Error) => boolean \| 0 \| 1 \| 2`            | `null`              | See reconnectOnError patterns below                                     |
+| `readOnly`                      | `boolean`                                           | `false`             | Send READONLY after connect                                             |
+| `stringNumbers`                 | `boolean`                                           | `false`             | Return numbers as strings (safe for > 2^53)                             |
+| `connectTimeout`                | `number`                                            | `10000`             | Ms before killing socket during initial connection                      |
+| `monitor`                       | `boolean`                                           | `false`             | Enter MONITOR mode on connect (internal use)                            |
+| `maxRetriesPerRequest`          | `number \| null`                                    | `20`                | Flush queue after N reconnects. `null` = wait forever                   |
+| `maxLoadingRetryTime`           | `number`                                            | `10000`             | Max ms to wait for server to finish loading                             |
+| `enableAutoPipelining`          | `boolean`                                           | `false`             | Auto-batch commands per event loop tick                                 |
+| `autoPipeliningIgnoredCommands` | `string[]`                                          | `[]`                | Commands excluded from auto-pipelining                                  |
+| `enableOfflineQueue`            | `boolean`                                           | `true`              | Queue commands before "ready". `false` = error immediately              |
+| `enableReadyCheck`              | `boolean`                                           | `true`              | Wait for INFO loading:0 before emitting "ready"                         |
+| `lazyConnect`                   | `boolean`                                           | `false`             | Delay connection until first command or explicit `connect()`            |
+| `scripts`                       | `Record<string, { lua, numberOfKeys?, readOnly? }>` | `undefined`         | Pre-define Lua commands                                                 |
+| `keyPrefix`                     | `string`                                            | `undefined`         | Auto-prefix all keys                                                    |
+| `showFriendlyErrorStack`        | `boolean`                                           | `false`             | Better stacks in dev (perf cost — never in production)                  |
+| `Connector`                     | `ConnectorConstructor`                              | `undefined`         | Custom connector class                                                  |
+
+## StandaloneConnectionOptions
+
+```ts
+type StandaloneConnectionOptions = Partial<TcpOptions & IpcOptions> & {
+  disconnectTimeout?: number;
+  tls?: ConnectionOptions;
+};
+```
+
+Includes Node.js `net.connect()` options:
+
+- `host`: string (default `"127.0.0.1"`)
+- `port`: number (default `6379`)
+- `path`: string (Unix socket path, overrides host/port)
+- `tls`: Node.js `tls.connect()` options
+- `disconnectTimeout`: ms to wait for graceful disconnect
+
+## SentinelConnectionOptions (summary)
+
+See [cluster-sentinel.md](cluster-sentinel.md) for full Sentinel reference.
+
+Key properties: `sentinels`, `name`, `role`, `sentinelPassword`, `sentinelUsername`, `sentinelTLS`, `enableTLSForSentinelMode`, `failoverDetector`, `sentinelRetryStrategy`, `sentinelReconnectStrategy`, `updateSentinels`, `natMap`, `preferredSlaves`, `sentinelMaxConnections`, `sentinelCommandTimeout`.
+
+## retryStrategy patterns
+
+```ts
+// Default: exponential backoff capped at 2s
+retryStrategy(times) {
+  return Math.min(times * 50, 2000);
+}
+
+// Stop after 10 attempts:
+retryStrategy(times) {
+  if (times > 10) return undefined; // stop reconnecting
+  return Math.min(times * 100, 3000);
+}
+
+// Immediate reconnect for first 3 attempts, then backoff:
+retryStrategy(times) {
+  if (times <= 3) return 0;
+  return Math.min(times * 100, 5000);
+}
+
+// Never reconnect (disable auto-reconnect):
+retryStrategy() {
+  return undefined;
+}
+```
+
+`times` is the number of reconnection attempts so far (starts at 1). When the function returns `undefined` or a non-number, ioredis stops reconnecting and emits the `end` event.
+
+## reconnectOnError patterns
+
+```ts
+// Reconnect on READONLY (AWS ElastiCache failover):
+reconnectOnError(err) {
+  if (err.message.includes("READONLY")) return true;
+  return false;
+}
+```
+
+Return values:
+
+- `false` / `0` — do not reconnect
+- `true` / `1` — reconnect
+- `2` — reconnect AND resend the failed command after reconnection
+
+Default is `null` (never reconnect on Redis errors).
+
+## TLS configuration
+
+```ts
+// Minimal (system CAs):
+new Redis({ host: "redis.example.com", tls: {} });
+
+// With CA certificate:
+new Redis({
+  host: "redis.example.com",
+  tls: { ca: fs.readFileSync("ca.pem") },
+});
+
+// Via URL (rediss:// = TLS):
+new Redis("rediss://redis.example.com:6380");
+
+// TLS profiles (deprecated, will be removed in v6):
+new Redis({ host: "localhost", tls: "RedisCloudFixed" });
+new Redis({ host: "localhost", tls: "RedisCloudFlexible" });
+```
+
+## Blocking command timeout
+
+Opt-in client-side protection for blocking commands (`blpop`, `brpop`, `xread`, etc.):
+
+```ts
+const redis = new Redis({
+  blockingTimeout: 30000, // Enable — 30s safety net for "block forever" commands
+  blockingTimeoutGrace: 100, // Grace period added to finite timeouts (default: 100ms)
+});
+```
+
+- Disabled by default (`blockingTimeout` undefined, 0, or negative)
+- For finite-timeout commands (e.g., `blpop("key", 5)`): deadline = command timeout + grace
+- For infinite-timeout commands (`timeout = 0`): deadline = `blockingTimeout` value
+- On timeout: resolves with `null` (same as Redis native timeout behavior)
+
+## Connection lifecycle
+
+```
+[new Redis()] → connecting → connect → ready → (commands execute)
+                    ↑                     ↓
+                    └── reconnecting ← close → end (if retryStrategy returns undefined)
+```
+
+- `connect`: TCP established
+- `ready`: Server loaded and accepting commands
+- `close` → `reconnecting`: Auto-reconnect cycle
+- `end`: Final — no more reconnection attempts
+
+Graceful shutdown:
+
+```ts
+await redis.quit(); // Waits for pending replies, sends QUIT, closes
+```
+
+Force shutdown:
+
+```ts
+redis.disconnect(); // Immediate close, pending commands rejected
+```

package/skills/ioredis/references/core-api.md

@@ -0,0 +1,179 @@
+# ioredis Core API Reference
+
+## Quick Start
+
+```ts
+const redis = new Redis(); // localhost:6379
+
+// All Redis commands are methods: redis.hset(), redis.zadd(), redis.xadd(), etc.
+// Format: redis[commandInLowerCase](...args) — returns Promise
+// Buffer variants: redis.getBuffer("key") returns Buffer instead of string
+```
+
+## Connection
+
+```ts
+new Redis(); // 127.0.0.1:6379
+new Redis(6380); // 127.0.0.1:6380
+new Redis(6379, "192.168.1.1"); // 192.168.1.1:6379
+new Redis("/tmp/redis.sock"); // Unix socket
+new Redis("redis://:password@host:6379/0"); // URL (redis:// or rediss://)
+new Redis("redis://user:pass@host:6379/4"); // With username (Redis >= 6)
+
+new Redis({
+  host: "127.0.0.1",
+  port: 6379,
+  username: "default", // Redis >= 6 ACL
+  password: "secret",
+  db: 0, // Database index (default: 0)
+  keyPrefix: "app:", // Auto-prefix all keys
+  lazyConnect: false, // true = don't connect until first command
+  enableReadyCheck: true, // Wait for server to finish loading
+  maxRetriesPerRequest: 20, // null = wait forever
+  connectTimeout: 10000, // ms
+  commandTimeout: undefined, // ms, throws "Command timed out"
+  keepAlive: 0, // ms, 0 = disabled
+  noDelay: true, // Nagle's algorithm
+  connectionName: "my-app", // CLIENT SETNAME
+  enableAutoPipelining: false,
+  retryStrategy(times) {
+    return Math.min(times * 50, 2000); // ms delay, or undefined to stop
+  },
+});
+```
+
+**Full options reference**: See [connection-options.md](connection-options.md)
+
+### TLS
+
+```ts
+new Redis({ host: "redis.example.com", tls: {} });
+// or
+new Redis("rediss://redis.example.com");
+// or with CA:
+new Redis({ host: "redis.example.com", tls: { ca: fs.readFileSync("cert.pem") } });
+```
+
+## Pipeline
+
+Batch commands for 50-300% throughput improvement:
+
+```ts
+const pipeline = redis.pipeline();
+pipeline.set("foo", "bar");
+pipeline.get("foo");
+const results = await pipeline.run();
+// results === [[null, "OK"], [null, "bar"]]
+// Each entry: [error, result]
+```
+
+**Note:** The actual method to run a pipeline is `.exec()` — shown as `.run()` here for brevity. In ioredis, both pipelines and transactions use the `.exec()` method to send queued commands to Redis.
+
+## Transaction (multi)
+
+```ts
+const tx = redis.multi();
+tx.set("foo", "bar");
+tx.get("foo");
+const results = await tx.exec();
+// results === [[null, "OK"], [null, "bar"]]
+
+// Without pipeline (sends immediately):
+redis.multi({ pipeline: false });
+redis.set("foo", "bar");
+redis.get("foo");
+await redis.exec();
+```
+
+## Pub/Sub
+
+A subscribed connection cannot run other commands. Use separate instances:
+
+```ts
+const sub = new Redis();
+const pub = new Redis();
+
+await sub.subscribe("channel-1", "channel-2");
+sub.on("message", (channel, message) => {
+  /* ... */
+});
+// Also: "messageBuffer" for binary data
+
+pub.publish("channel-1", JSON.stringify({ data: 123 }));
+```
+
+## Lua Scripting
+
+```ts
+// Define at runtime:
+redis.defineCommand("mycommand", {
+  numberOfKeys: 2,
+  lua: "return {KEYS[1],KEYS[2],ARGV[1],ARGV[2]}",
+});
+const result = await redis.mycommand("k1", "k2", "a1", "a2");
+
+// Define via constructor:
+const redis = new Redis({
+  scripts: {
+    mycommand: {
+      numberOfKeys: 2,
+      lua: "return {KEYS[1],KEYS[2],ARGV[1],ARGV[2]}",
+    },
+  },
+});
+
+// Dynamic key count — pass numberOfKeys as first arg:
+redis.defineCommand("dynamicCmd", { lua: "return KEYS[1]" });
+await redis.dynamicCmd(1, "mykey");
+```
+
+## Scan (Streaming)
+
+```ts
+const stream = redis.scanStream({ match: "user:*", count: 100 });
+stream.on("data", (keys) => {
+  // keys: string[], may contain duplicates
+  stream.pause();
+  processKeys(keys).then(() => stream.resume());
+});
+stream.on("end", () => console.log("done"));
+
+// Hash/Set/ZSet variants:
+redis.hscanStream("myhash", { match: "field:*" });
+redis.sscanStream("myset", { match: "*" });
+redis.zscanStream("myzset", { match: "*" });
+```
+
+## Connection Events
+
+| Event          | Description                                                     |
+| -------------- | --------------------------------------------------------------- |
+| `connect`      | TCP connection established                                      |
+| `ready`        | Server ready for commands (after loading if `enableReadyCheck`) |
+| `error`        | Connection error (emitted silently — only if listener exists)   |
+| `close`        | Connection closed                                               |
+| `reconnecting` | Reconnection scheduled, arg = delay in ms                       |
+| `end`          | No more reconnections will be made                              |
+| `wait`         | `lazyConnect` is set, waiting for first command                 |
+
+```ts
+redis.on("error", (err) => console.error("Redis error:", err));
+redis.on("ready", () => console.log("Redis ready"));
+
+// Check status programmatically:
+redis.status; // "wait" | "reconnecting" | "connecting" | "connect" | "ready" | "close" | "end"
+```
+
+## Key Methods
+
+| Method                  | Description                                                  |
+| ----------------------- | ------------------------------------------------------------ |
+| `redis.connect()`       | Connect manually (when `lazyConnect: true`). Returns Promise |
+| `redis.disconnect()`    | Force close. No reconnect. Pending commands rejected         |
+| `redis.quit()`          | Graceful close. Waits for pending replies, then sends QUIT   |
+| `redis.duplicate()`     | Create new instance with same options                        |
+| `redis.pipeline()`      | Create pipeline                                              |
+| `redis.multi()`         | Create transaction                                           |
+| `redis.defineCommand()` | Register Lua script as command                               |
+| `redis.monitor()`       | Enter MONITOR mode (returns monitor instance)                |
+| `redis.scanStream()`    | Create readable stream for SCAN                              |

package/skills/nextjs-best-practices/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: nextjs-best-practices
+description: "Next.js App Router best practices — file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling. Use when writing, reviewing, or debugging Next.js App Router code."
+---
+
+# Next.js Best Practices
+
+Apply these rules when writing or reviewing Next.js code.
+
+> **Note:** Next.js 16 renamed `middleware.ts` to `proxy.ts`. Verify `proxy.ts` support in your version; `middleware.ts` remains the stable API.
+
+## Table of Contents
+
+- [File Conventions](#file-conventions)
+- [RSC Boundaries](#rsc-boundaries)
+- [Async Patterns](#async-patterns)
+- [Runtime Selection](#runtime-selection)
+- [Directives](#directives)
+- [Functions](#functions)
+- [Error Handling](#error-handling)
+- [Data Patterns](#data-patterns)
+- [Route Handlers](#route-handlers)
+- [Metadata & OG Images](#metadata--og-images)
+- [Image Optimization](#image-optimization)
+- [Font Optimization](#font-optimization)
+- [Bundling](#bundling)
+- [Scripts](#scripts)
+- [Hydration Errors](#hydration-errors)
+- [Suspense Boundaries](#suspense-boundaries)
+- [Parallel & Intercepting Routes](#parallel--intercepting-routes)
+- [Self-Hosting](#self-hosting)
+- [Debug Tricks](#debug-tricks)
+
+## File Conventions
+
+See [file-conventions.md](references/file-conventions.md) for:
+
+- Project structure and special files
+- Route segments (dynamic, catch-all, groups)
+- Parallel and intercepting routes
+- Middleware rename in v16 (middleware → proxy)
+
+## RSC Boundaries
+
+Detect invalid React Server Component patterns.
+
+See [rsc-boundaries.md](references/rsc-boundaries.md) for:
+
+- Async client component detection (invalid)
+- Non-serializable props detection
+- Server Action exceptions
+
+## Async Patterns
+
+Next.js 16.1.6+ async API changes.
+
+See [async-patterns.md](references/async-patterns.md) for:
+
+- Async `params` and `searchParams`
+- Async `cookies()` and `headers()`
+- Migration codemod
+
+## Runtime Selection
+
+See [runtime-selection.md](references/runtime-selection.md) for:
+
+- Default to Node.js runtime
+- When Edge runtime is appropriate
+
+## Directives
+
+See [directives.md](references/directives.md) for:
+
+- `'use client'`, `'use server'` (React)
+- `'use cache'` (Next.js)
+
+## Functions
+
+See [functions.md](references/functions.md) for:
+
+- Navigation hooks: `useRouter`, `usePathname`, `useSearchParams`, `useParams`
+- Server functions: `cookies`, `headers`, `draftMode`, `after`
+- Generate functions: `generateStaticParams`, `generateMetadata`
+
+## Error Handling
+
+See [error-handling.md](references/error-handling.md) for:
+
+- `error.tsx`, `global-error.tsx`, `not-found.tsx`
+- `redirect`, `permanentRedirect`, `notFound`
+- `forbidden`, `unauthorized` (auth errors)
+- `unstable_rethrow` for catch blocks
+
+## Data Patterns
+
+See [data-patterns.md](references/data-patterns.md) for:
+
+- Server Components vs Server Actions vs Route Handlers
+- Avoiding data waterfalls (`Promise.all`, Suspense, preload)
+- Client component data fetching
+
+## Route Handlers
+
+See [route-handlers.md](references/route-handlers.md) for:
+
+- `route.ts` basics
+- GET handler conflicts with `page.tsx`
+- Environment behavior (no React DOM)
+- When to use vs Server Actions
+
+## Metadata & OG Images
+
+See [metadata.md](references/metadata.md) for:
+
+- Static and dynamic metadata
+- `generateMetadata` function
+- OG image generation with `next/og`
+- File-based metadata conventions
+
+## Image Optimization
+
+See [image.md](references/image.md) for:
+
+- Always use `next/image` over `<img>`
+- Remote images configuration
+- Responsive `sizes` attribute
+- Blur placeholders
+- Priority loading for LCP
+
+## Font Optimization
+
+See [font.md](references/font.md) for:
+
+- `next/font` setup
+- Google Fonts, local fonts
+- Tailwind CSS integration
+- Preloading subsets
+
+## Bundling
+
+See [bundling.md](references/bundling.md) for:
+
+- Server-incompatible packages
+- CSS imports (not link tags)
+- Polyfills (already included)
+- ESM/CommonJS issues
+- Bundle analysis
+
+## Scripts
+
+See [scripts.md](references/scripts.md) for:
+
+- `next/script` vs native script tags
+- Inline scripts need `id`
+- Loading strategies
+- Google Analytics with `@next/third-parties`
+
+## Hydration Errors
+
+See [hydration-error.md](references/hydration-error.md) for:
+
+- Common causes (browser APIs, dates, invalid HTML)
+- Debugging with error overlay
+- Fixes for each cause
+
+## Suspense Boundaries
+
+See [suspense-boundaries.md](references/suspense-boundaries.md) for:
+
+- CSR bailout with `useSearchParams` and `usePathname`
+- Which hooks require Suspense boundaries
+
+## Parallel & Intercepting Routes
+
+See [parallel-routes.md](references/parallel-routes.md) for:
+
+- Modal patterns with `@slot` and `(.)` interceptors
+- `default.tsx` for fallbacks
+- Closing modals correctly with `router.back()`
+
+## Self-Hosting
+
+See [self-hosting.md](references/self-hosting.md) for:
+
+- `output: 'standalone'` for Docker
+- Cache handlers for multi-instance ISR
+- What works vs needs extra setup
+
+## Debug Tricks
+
+See [debug-tricks.md](references/debug-tricks.md) for:
+
+- MCP endpoint for AI-assisted debugging
+- Rebuild specific routes with `--debug-build-paths`

package/skills/nextjs-best-practices/references/async-patterns.md

@@ -0,0 +1,84 @@
+# Async Patterns
+
+In Next.js 16.1.6+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous.
+
+## Async Params and SearchParams
+
+Always type them as `Promise<...>` and await them.
+
+### Pages and Layouts
+
+```tsx
+type Props = { params: Promise<{ slug: string }> };
+
+export default async function Page({ params }: Props) {
+  const { slug } = await params;
+}
+```
+
+### Route Handlers
+
+```tsx
+export async function GET(request: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+}
+```
+
+### SearchParams
+
+```tsx
+type Props = {
+  params: Promise<{ slug: string }>;
+  searchParams: Promise<{ query?: string }>;
+};
+
+export default async function Page({ params, searchParams }: Props) {
+  const { slug } = await params;
+  const { query } = await searchParams;
+}
+```
+
+### Synchronous Components
+
+Use `React.use()` for non-async components:
+
+```tsx
+import { use } from "react";
+
+type Props = { params: Promise<{ slug: string }> };
+
+export default function Page({ params }: Props) {
+  const { slug } = use(params);
+}
+```
+
+### generateMetadata
+
+```tsx
+type Props = { params: Promise<{ slug: string }> };
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug } = await params;
+  return { title: slug };
+}
+```
+
+## Async Cookies and Headers
+
+```tsx
+import { cookies, headers } from "next/headers";
+
+export default async function Page() {
+  const cookieStore = await cookies();
+  const headersList = await headers();
+
+  const theme = cookieStore.get("theme");
+  const userAgent = headersList.get("user-agent");
+}
+```
+
+## Migration Codemod
+
+```bash
+npx @next/codemod@latest next-async-request-api .
+```