@jgamaraalv/ts-dev-kit 1.0.0

package/skills/drizzle-pg/references/schema-pg.md

@@ -0,0 +1,256 @@
+# PostgreSQL Schema Reference
+
+## Table of Contents
+
+- [Column Types](#column-types)
+- [Column Modifiers](#column-modifiers)
+- [Enums](#enums)
+- [Indexes](#indexes)
+- [Constraints](#constraints)
+- [Foreign Keys](#foreign-keys)
+- [PostGIS](#postgis)
+- [pg_vector](#pg_vector)
+
+## Column Types
+
+All imports from `drizzle-orm/pg-core`.
+
+### Integer types
+
+```typescript
+integer("age"); // 4-byte signed integer
+smallint("small"); // 2-byte integer
+bigint("big", { mode: "number" }); // 8-byte; mode: "number" | "bigint"
+serial("id"); // auto-increment 4-byte (NOT NULL by default)
+smallserial("small_id"); // auto-increment 2-byte
+bigserial("big_id", { mode: "number" }); // auto-increment 8-byte
+```
+
+### Text types
+
+```typescript
+text("bio"); // unlimited length
+text("role", { enum: ["admin", "user"] }); // text with enum check
+varchar("name", { length: 256 }); // variable length
+char("code", { length: 3 }); // fixed length
+```
+
+### Numeric types
+
+```typescript
+numeric("price", { precision: 10, scale: 2 }); // exact; mode: "string" (default) | "number" | "bigint"
+real("score"); // float4
+doublePrecision("precise"); // float8
+```
+
+### JSON types
+
+```typescript
+json("data"); // textual JSON
+jsonb("metadata"); // binary JSON (preferred for queries)
+// Type-safe:
+jsonb("config").$type<{ theme: string; lang: string }>();
+```
+
+### Date/time types
+
+```typescript
+timestamp("created_at", { withTimezone: true, mode: "date" }); // mode: "date" | "string"
+timestamp("updated_at", { precision: 3, withTimezone: true }).defaultNow();
+date("birth_date", { mode: "date" }); // mode: "date" | "string"
+time("start_time", { precision: 0 });
+interval("duration", { fields: "day" });
+```
+
+### Special types
+
+```typescript
+uuid("id").defaultRandom(); // UUID v4 default
+boolean("active");
+bytea("file_data"); // binary
+point("location", { mode: "xy" }); // { x: number, y: number } or mode: "tuple" for [number, number]
+line("path", { mode: "abc" }); // { a, b, c } or mode: "tuple"
+```
+
+### Identity columns (PG 10+)
+
+```typescript
+integer("id").generatedAlwaysAsIdentity({ startWith: 1000 });
+integer("id").generatedByDefaultAsIdentity(); // allows manual override
+```
+
+## Column Modifiers
+
+```typescript
+column
+  .notNull() // NOT NULL
+  .primaryKey() // PRIMARY KEY
+  .default(42) // static default
+  .default(sql`gen_random_uuid()`) // SQL-level default
+  .defaultNow() // timestamp shortcut: default now()
+  .defaultRandom() // UUID shortcut: default gen_random_uuid()
+  .$defaultFn(() => cuid2()) // runtime JS default (insert-time)
+  .$onUpdateFn(() => new Date()) // runtime JS default (update-time)
+  .$type<MyType>() // override TS type (compile-time only)
+  .references(() => otherTable.id) // inline foreign key
+  .unique(); // UNIQUE constraint
+```
+
+## Enums
+
+```typescript
+import { pgEnum } from "drizzle-orm/pg-core";
+
+export const roleEnum = pgEnum("role", ["admin", "user", "moderator"]);
+
+// Use in table:
+export const users = pgTable("users", {
+  role: roleEnum().default("user").notNull(),
+});
+```
+
+## Indexes
+
+Defined in pgTable's third argument (callback returning array):
+
+```typescript
+import { pgTable, index, uniqueIndex } from "drizzle-orm/pg-core";
+
+export const users = pgTable(
+  "users",
+  {
+    id: serial("id").primaryKey(),
+    email: text("email").notNull(),
+    name: text("name"),
+    age: integer("age"),
+  },
+  (t) => [
+    // Single column
+    index("name_idx").on(t.name),
+
+    // Composite
+    index("name_age_idx").on(t.name, t.age),
+
+    // Unique index
+    uniqueIndex("email_idx").on(t.email),
+
+    // Partial index
+    index("active_idx")
+      .on(t.id)
+      .where(sql`${t.age} >= 18`),
+
+    // Expression index with btree
+    index("lower_name_idx").using("btree", sql`lower(${t.name})`),
+
+    // Advanced sorting
+    index("sorted_idx")
+      .on(t.name.asc(), t.age.desc().nullsFirst())
+      .concurrently()
+      .with({ fillfactor: "70" }),
+
+    // GiST index (for PostGIS/pg_vector)
+    index("geo_idx").using("gist", t.location),
+
+    // HNSW index (for pg_vector)
+    index("embedding_idx").using("hnsw", t.embedding.op("vector_cosine_ops")),
+  ],
+);
+```
+
+## Constraints
+
+```typescript
+import { pgTable, unique, check, primaryKey, foreignKey } from "drizzle-orm/pg-core";
+
+export const table = pgTable(
+  "table",
+  {
+    id: serial("id").primaryKey(),
+    email: text("email").notNull().unique(),
+    age: integer("age"),
+    firstName: text("first_name"),
+    lastName: text("last_name"),
+  },
+  (t) => [
+    // Composite unique
+    unique("name_unique").on(t.firstName, t.lastName),
+
+    // Unique with NULLS NOT DISTINCT (PG 15+)
+    unique("email_unique").on(t.email).nullsNotDistinct(),
+
+    // Check constraint
+    check("age_positive", sql`${t.age} >= 0`),
+
+    // Composite primary key
+    primaryKey({ columns: [t.firstName, t.lastName] }),
+  ],
+);
+```
+
+## Foreign Keys
+
+### Inline (single column)
+
+```typescript
+integer("author_id").references(() => users.id);
+integer("author_id").references(() => users.id, { onDelete: "cascade", onUpdate: "cascade" });
+```
+
+### Self-reference (requires AnyPgColumn)
+
+```typescript
+import type { AnyPgColumn } from "drizzle-orm/pg-core";
+
+integer("parent_id").references((): AnyPgColumn => categories.id);
+```
+
+### Multi-column (in third argument)
+
+```typescript
+pgTable("profile", { firstName, lastName }, (t) => [
+  foreignKey({
+    columns: [t.firstName, t.lastName],
+    foreignColumns: [users.firstName, users.lastName],
+    name: "profile_user_fk",
+  })
+    .onDelete("cascade")
+    .onUpdate("cascade"),
+]);
+```
+
+### onDelete/onUpdate values
+
+`"cascade"` | `"restrict"` | `"no action"` | `"set null"` | `"set default"`
+
+## PostGIS
+
+```typescript
+import { geometry } from "drizzle-orm/pg-core";
+
+const places = pgTable("places", {
+  location: geometry("location", { type: "point", mode: "xy", srid: 4326 }),
+  // mode: "xy" → { x: number, y: number }
+  // mode: "tuple" → [number, number]
+});
+
+// GiST index for spatial queries
+pgTable("places", { location }, (t) => [index("geo_idx").using("gist", t.location)]);
+```
+
+## pg_vector
+
+```typescript
+import { vector } from "drizzle-orm/pg-core";
+import { l2Distance, cosineDistance, innerProduct } from "drizzle-orm";
+
+const items = pgTable(
+  "items",
+  {
+    embedding: vector("embedding", { dimensions: 1536 }),
+  },
+  (t) => [index("embedding_idx").using("hnsw", t.embedding.op("vector_cosine_ops"))],
+);
+
+// Similarity search
+await db.select().from(items).orderBy(cosineDistance(items.embedding, queryVector)).limit(10);
+```

package/skills/drizzle-pg/references/sql-operator.md

@@ -0,0 +1,215 @@
+# Magic sql`` Operator Reference
+
+## Table of Contents
+
+- [Basic Usage](#basic-usage)
+- [Type Annotations](#type-annotations)
+- [sql.raw()](#sqlraw)
+- [sql.empty() + append()](#sqlempty--append)
+- [sql.join()](#sqljoin)
+- [sql.identifier()](#sqlidentifier)
+- [Placeholders](#placeholders)
+- [Helpers: .as(), .mapWith()](#helpers)
+- [Converting to String](#converting-to-string)
+- [Usage in Queries](#usage-in-queries)
+
+## Basic Usage
+
+The `sql` template literal auto-parameterizes values and escapes table/column references:
+
+```typescript
+import { sql } from "drizzle-orm";
+
+const id = 69;
+await db.execute(sql`select * from ${usersTable} where ${usersTable.id} = ${id}`);
+// → select * from "users" where "users"."id" = $1;  params: [69]
+```
+
+Table/column references (`${usersTable}`, `${usersTable.id}`) are escaped as identifiers.
+Scalar values (`${id}`) become parameterized placeholders.
+
+## Type Annotations
+
+Use `sql<T>` to annotate the return type:
+
+```typescript
+const result = await db
+  .select({
+    lowerName: sql<string>`lower(${users.name})`,
+    count: sql<number>`count(*)`,
+  })
+  .from(users);
+// result[0].lowerName → string
+// result[0].count → number
+```
+
+For nullable contexts (e.g., LEFT JOIN), explicitly type as nullable:
+
+```typescript
+sql<string | null>`upper(${pets.name})`;
+```
+
+## sql.raw()
+
+Insert raw, unescaped SQL (no parameterization). Use for dynamic SQL fragments, not user input:
+
+```typescript
+const column = "name";
+sql`select ${sql.raw(column)} from users`;
+// → select name from users  (no quoting, no $1)
+
+// vs parameterized
+sql`select * from users where id = ${12}`;
+// → select * from users where id = $1; params: [12]
+```
+
+## sql.empty() + append()
+
+Build SQL incrementally:
+
+```typescript
+const query = sql.empty();
+query.append(sql`select * from users`);
+query.append(sql` where `);
+
+const conditions = [sql`id = ${1}`, sql`name = ${"Dan"}`];
+for (let i = 0; i < conditions.length; i++) {
+  query.append(conditions[i]);
+  if (i < conditions.length - 1) query.append(sql` or `);
+}
+// → select * from users where id = $1 or name = $2; params: [1, "Dan"]
+```
+
+## sql.join()
+
+Join an array of SQL chunks with a separator:
+
+```typescript
+const conditions: SQL[] = [sql`id = ${1}`, sql`name = ${"Dan"}`, sql`age > ${18}`];
+
+const where = sql.join(conditions, sql` AND `);
+const query = sql`select * from users where ${where}`;
+// → select * from users where id = $1 AND name = $2 AND age > $3
+```
+
+## sql.identifier()
+
+Escape a dynamic identifier (table/column name):
+
+```typescript
+const tableName = "users";
+sql`SELECT * FROM ${sql.identifier(tableName)}`;
+// → SELECT * FROM "users"
+```
+
+## Placeholders
+
+Use `sql.placeholder()` for prepared statements:
+
+```typescript
+const stmt = db
+  .select()
+  .from(users)
+  .where(eq(users.id, sql.placeholder("userId")))
+  .prepare("get_user_by_id");
+
+// Execute with named params
+await stmt.execute({ userId: 42 });
+```
+
+## Helpers
+
+### .as() — alias a column
+
+```typescript
+sql<number>`count(*)`.as("total_count");
+// → count(*) AS "total_count"
+```
+
+### .mapWith() — transform driver output
+
+```typescript
+sql<number>`count(*)`.mapWith(Number);
+// Converts string "42" from driver to number 42
+```
+
+### .inlineParams() — inline parameters instead of $N
+
+```typescript
+sql`select * from users where id = ${42}`.inlineParams();
+// → select * from users where id = 42 (no parameterization)
+```
+
+## Converting to String
+
+```typescript
+import { PgDialect } from "drizzle-orm/pg-core";
+
+const pgDialect = new PgDialect();
+const { sql: sqlStr, params } = pgDialect.sqlToQuery(
+  sql`select * from ${usersTable} where ${usersTable.id} = ${12}`,
+);
+// sqlStr: 'select * from "users" where "users"."id" = $1'
+// params: [12]
+```
+
+## Usage in Queries
+
+### In SELECT
+
+```typescript
+await db
+  .select({
+    id: users.id,
+    fullName: sql<string>`${users.firstName} || ' ' || ${users.lastName}`.as("full_name"),
+  })
+  .from(users);
+```
+
+### In WHERE
+
+```typescript
+await db
+  .select()
+  .from(users)
+  .where(sql`${users.age} > 18 AND ${users.role} = 'admin'`);
+
+// Full-text search
+await db
+  .select()
+  .from(users)
+  .where(sql`to_tsvector('english', ${users.bio}) @@ to_tsquery('english', ${searchTerm})`);
+```
+
+### In ORDER BY
+
+```typescript
+await db
+  .select()
+  .from(users)
+  .orderBy(sql`${users.id} desc nulls first`);
+```
+
+### In GROUP BY / HAVING
+
+```typescript
+await db
+  .select({
+    category: products.category,
+    total: sql<number>`sum(${products.price})`.mapWith(Number),
+  })
+  .from(products)
+  .groupBy(sql`${products.category}`)
+  .having(sql`sum(${products.price}) > 1000`);
+```
+
+### In schema defaults
+
+```typescript
+const users = pgTable("users", {
+  id: uuid("id")
+    .default(sql`gen_random_uuid()`)
+    .primaryKey(),
+  createdAt: timestamp("created_at").default(sql`now()`),
+});
+```

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

@@ -0,0 +1,143 @@
+---
+name: fastify-best-practices
+description: "Fastify 5 best practices, API reference, and patterns for routes, plugins, hooks, validation, error handling, and TypeScript. Use when: (1) writing new Fastify routes, plugins, or hooks, (2) looking up Fastify API signatures or options, (3) debugging Fastify issues (lifecycle, encapsulation, validation, plugin timeout), (4) reviewing Fastify code for anti-patterns. Triggers: 'add a route', 'create plugin', 'Fastify hook', 'validation schema', 'Fastify error', 'setErrorHandler', 'fastify-plugin'."
+---
+
+# Fastify 5 Best Practices
+
+## Table of Contents
+
+- [Request lifecycle](#request-lifecycle-exact-order)
+- [Top anti-patterns](#top-anti-patterns)
+- [Quick patterns](#quick-patterns)
+  - [Plugin with fastify-plugin (FastifyPluginCallback)](#plugin-with-fastify-plugin-fastifyplugincallback)
+  - [Route with validation](#route-with-validation)
+  - [Hook (application-level)](#hook-application-level)
+  - [Error handler](#error-handler)
+- [Reference files](#reference-files)
+
+## Request lifecycle (exact order)
+
+```
+Incoming Request
+  └─ Routing
+      └─ onRequest hooks
+          └─ preParsing hooks
+              └─ Content-Type Parsing
+                  └─ preValidation hooks
+                      └─ Schema Validation (→ 400 on failure)
+                          └─ preHandler hooks
+                              └─ Route Handler
+                                  └─ preSerialization hooks
+                                      └─ onSend hooks
+                                          └─ Response Sent
+                                              └─ onResponse hooks
+```
+
+Error at any stage → `onError` hooks → error handler → `onSend` → response → `onResponse`.
+
+## Top anti-patterns
+
+1. **Mixing async/callback in handlers** — Use `async` OR callbacks, never both. With async, `return` the value; don't call `reply.send()` AND return.
+
+2. **Returning `undefined` from async handler** — Fastify treats this as "no response yet". Return the data or call `reply.send()`.
+
+3. **Using arrow functions when you need `this`** — Arrow functions don't bind `this` to the Fastify instance. Use `function` declarations for handlers that need `this`.
+
+4. **Forgetting `fastify-plugin` wrapper** — Without it, decorators/hooks stay scoped to the child context. Parent and sibling plugins won't see them.
+
+5. **Decorating with reference types directly** — `decorateRequest('data', {})` shares the SAME object across all requests. Use `null` initial + `onRequest` hook to assign per-request.
+
+6. **Sending response in `onError` hook** — `onError` is read-only for logging. Use `setErrorHandler()` to modify error responses.
+
+7. **Not handling `reply.send()` in async hooks** — Call `return reply` after `reply.send()` in async hooks to prevent "Reply already sent" errors.
+
+8. **Ignoring encapsulation** — Decorators/hooks registered in child plugins are invisible to parents. Design your plugin tree carefully.
+
+9. **String concatenation in SQL from route params** — Always use parameterized queries. Fastify validates input shape, not content safety.
+
+10. **Missing response schema** — Without `response` schema, Fastify serializes with `JSON.stringify()` (slow) and may leak sensitive fields. Use `fast-json-stringify` via response schemas.
+
+## Quick patterns
+
+### Plugin with fastify-plugin (FastifyPluginCallback)
+
+Project convention: use `FastifyPluginCallback` + `done()` (avoids `require-await` lint errors).
+
+```ts
+import fp from "fastify-plugin";
+import type { FastifyPluginCallback } from "fastify";
+
+const myPlugin: FastifyPluginCallback = (fastify, opts, done) => {
+  fastify.decorate("myService", new MyService());
+  done();
+};
+
+export default fp(myPlugin, { name: "my-plugin" });
+```
+
+### Route with validation
+
+```ts
+fastify.post<{ Body: CreateUserBody }>("/users", {
+  schema: {
+    body: {
+      type: "object",
+      required: ["email", "name"],
+      properties: {
+        email: { type: "string", format: "email" },
+        name: { type: "string", minLength: 1 },
+      },
+    },
+    response: {
+      201: {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          email: { type: "string" },
+        },
+      },
+    },
+  },
+  handler: async (request, reply) => {
+    const user = await createUser(request.body);
+    return reply.code(201).send(user);
+  },
+});
+```
+
+### Hook (application-level)
+
+```ts
+fastify.addHook("onRequest", async (request, reply) => {
+  request.startTime = Date.now();
+});
+
+fastify.addHook("onResponse", async (request, reply) => {
+  request.log.info({ elapsed: Date.now() - request.startTime }, "request completed");
+});
+```
+
+### Error handler
+
+```ts
+fastify.setErrorHandler((error, request, reply) => {
+  request.log.error(error);
+  const statusCode = error.statusCode ?? 500;
+  reply.code(statusCode).send({
+    error: statusCode >= 500 ? "Internal Server Error" : error.message,
+  });
+});
+```
+
+## Reference files
+
+Load the relevant file when you need detailed API information:
+
+- **Server factory & options** — constructor options, server methods, properties: [references/server-and-options.md](references/server-and-options.md)
+- **Routes & handlers** — declaration, URL params, async patterns, constraints: [references/routes-and-handlers.md](references/routes-and-handlers.md)
+- **Hooks & lifecycle** — all 16 hook types, signatures, scope, early response: [references/hooks-and-lifecycle.md](references/hooks-and-lifecycle.md)
+- **Plugins & encapsulation** — creating plugins, fastify-plugin, context inheritance: [references/plugins-and-encapsulation.md](references/plugins-and-encapsulation.md)
+- **Validation & serialization** — JSON Schema, Ajv, response schemas, custom validators: [references/validation-and-serialization.md](references/validation-and-serialization.md)
+- **Request, Reply & errors** — request/reply API, error handling, FST_ERR codes: [references/request-reply-errors.md](references/request-reply-errors.md)
+- **TypeScript & logging** — route generics, type providers, Pino config, decorators: [references/typescript-and-logging.md](references/typescript-and-logging.md)