@biggora/claude-plugins 1.2.2 → 1.3.1

package/src/skills/typescript-expert/references/advanced-decorators.md

@@ -0,0 +1,243 @@
+# TC39 Decorators (TypeScript 5.0+)
+
+TypeScript 5.0 introduced support for the TC39 Stage 3 decorator proposal. These are **not** the same as legacy `experimentalDecorators` — they have different semantics, no `reflect-metadata`, and work without any compiler flag.
+
+## When to Use Which
+
+- **TC39 decorators** (default, no flag): The standard going forward. Use for new code.
+- **`experimentalDecorators`** (tsconfig flag): Legacy. Required by Angular, NestJS, TypeORM, and other frameworks that depend on `reflect-metadata`. Keep using if your framework requires it.
+
+Check your framework's documentation — many are migrating to TC39 decorators.
+
+## Class Decorators
+
+```typescript
+// A class decorator receives the class itself and an optional context
+function sealed(target: Function, context: ClassDecoratorContext) {
+  Object.seal(target);
+  Object.seal(target.prototype);
+}
+
+@sealed
+class Greeter {
+  greeting: string;
+  constructor(message: string) {
+    this.greeting = message;
+  }
+}
+```
+
+### Adding Functionality
+
+```typescript
+function withTimestamp<T extends new (...args: any[]) => any>(
+  target: T,
+  context: ClassDecoratorContext
+) {
+  return class extends target {
+    createdAt = new Date();
+  };
+}
+
+@withTimestamp
+class User {
+  name: string;
+  constructor(name: string) { this.name = name; }
+}
+```
+
+## Method Decorators
+
+```typescript
+function log(
+  target: Function,
+  context: ClassMethodDecoratorContext
+) {
+  const methodName = String(context.name);
+  return function (this: any, ...args: any[]) {
+    console.log(`Calling ${methodName} with`, args);
+    const result = target.call(this, ...args);
+    console.log(`${methodName} returned`, result);
+    return result;
+  };
+}
+
+class Calculator {
+  @log
+  add(a: number, b: number): number {
+    return a + b;
+  }
+}
+```
+
+### Bound Method Decorator
+
+```typescript
+function bound(
+  target: Function,
+  context: ClassMethodDecoratorContext
+) {
+  const methodName = context.name;
+  context.addInitializer(function (this: any) {
+    this[methodName] = this[methodName].bind(this);
+  });
+}
+
+class Button {
+  label = "Click me";
+
+  @bound
+  handleClick() {
+    console.log(this.label); // Always correct `this`
+  }
+}
+```
+
+## Field Decorators
+
+```typescript
+function min(minValue: number) {
+  return function (
+    target: undefined, // field decorators receive undefined
+    context: ClassFieldDecoratorContext
+  ) {
+    return function (initialValue: number) {
+      if (initialValue < minValue) {
+        throw new Error(`${String(context.name)} must be >= ${minValue}`);
+      }
+      return initialValue;
+    };
+  };
+}
+
+class Product {
+  @min(0)
+  price: number;
+
+  constructor(price: number) {
+    this.price = price;
+  }
+}
+```
+
+## Accessor Decorators
+
+The `accessor` keyword (TS 5.0+) creates auto-accessor fields with implicit getter/setter:
+
+```typescript
+class Person {
+  accessor name: string;
+
+  constructor(name: string) {
+    this.name = name;
+  }
+}
+
+// Decorator for accessors
+function validate(
+  target: ClassAccessorDecoratorTarget<any, string>,
+  context: ClassAccessorDecoratorContext
+) {
+  return {
+    set(value: string) {
+      if (!value.trim()) throw new Error(`${String(context.name)} cannot be empty`);
+      target.set.call(this, value);
+    },
+    get() {
+      return target.get.call(this);
+    },
+  };
+}
+
+class User {
+  @validate
+  accessor name: string = "";
+}
+```
+
+## Decorator Factories
+
+Most real-world decorators are factories — functions that return decorators:
+
+```typescript
+function retry(attempts: number) {
+  return function (
+    target: Function,
+    context: ClassMethodDecoratorContext
+  ) {
+    return async function (this: any, ...args: any[]) {
+      for (let i = 0; i < attempts; i++) {
+        try {
+          return await target.call(this, ...args);
+        } catch (err) {
+          if (i === attempts - 1) throw err;
+        }
+      }
+    };
+  };
+}
+
+class ApiClient {
+  @retry(3)
+  async fetchData(url: string): Promise<Response> {
+    return fetch(url);
+  }
+}
+```
+
+## Decorator Context Types
+
+Each decorator kind has a specific context type:
+
+| Decorator Target | Context Type |
+|------------------|-------------|
+| Class | `ClassDecoratorContext` |
+| Method | `ClassMethodDecoratorContext` |
+| Getter | `ClassGetterDecoratorContext` |
+| Setter | `ClassSetterDecoratorContext` |
+| Field | `ClassFieldDecoratorContext` |
+| Auto-accessor | `ClassAccessorDecoratorContext` |
+
+All context types include:
+- `name`: The name of the decorated element
+- `kind`: "class", "method", "getter", "setter", "field", or "accessor"
+- `static`: Whether the element is static
+- `private`: Whether the element is private
+- `addInitializer()`: Register a callback to run during construction
+- `metadata`: Shared metadata object (replaces `reflect-metadata`)
+
+## Metadata (TC39 Decorator Metadata)
+
+TC39 decorators have a built-in metadata mechanism:
+
+```typescript
+function meta(key: string, value: any) {
+  return function (_target: any, context: ClassMethodDecoratorContext) {
+    context.metadata[key] = value;
+  };
+}
+
+class Routes {
+  @meta("path", "/users")
+  @meta("method", "GET")
+  getUsers() { ... }
+}
+
+// Access metadata
+const metadata = Routes[Symbol.metadata];
+// { path: "/users", method: "GET" }
+```
+
+## Migration from `experimentalDecorators`
+
+Key differences:
+
+| `experimentalDecorators` | TC39 Decorators |
+|--------------------------|-----------------|
+| Receives `(target, key, descriptor)` | Receives `(value, context)` |
+| Uses `reflect-metadata` for metadata | Uses `context.metadata` |
+| Parameter decorators supported | No parameter decorators |
+| `emitDecoratorMetadata` flag | No equivalent (use `context.metadata`) |
+| Runs at class definition time | Runs at class definition time |
+
+Parameter decorators are **not** part of TC39 decorators. Frameworks that need them (like NestJS for DI) still require `experimentalDecorators`.

package/src/skills/typescript-expert/references/advanced-mapped-types.md

@@ -0,0 +1,223 @@
+# Mapped Types
+
+Mapped types transform every property in an existing type, producing a new type. They iterate over keys and apply transformations.
+
+## Basic Syntax
+
+```typescript
+type Mapped<T> = {
+  [K in keyof T]: T[K];
+};
+```
+
+This is the identity mapped type — it produces the same type. The power comes from modifying the value type or the key.
+
+## Adding/Removing Modifiers
+
+```typescript
+// Add readonly to all properties
+type Readonly<T> = {
+  readonly [K in keyof T]: T[K];
+};
+
+// Remove readonly with -readonly
+type Mutable<T> = {
+  -readonly [K in keyof T]: T[K];
+};
+
+// Make all properties optional
+type Partial<T> = {
+  [K in keyof T]?: T[K];
+};
+
+// Remove optionality with -?
+type Required<T> = {
+  [K in keyof T]-?: T[K];
+};
+
+// Combine: mutable and required
+type Concrete<T> = {
+  -readonly [K in keyof T]-?: T[K];
+};
+```
+
+## Key Remapping with `as` (TS 4.1+)
+
+Remap keys during iteration using `as`:
+
+```typescript
+// Rename keys with a template literal
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+interface Person { name: string; age: number }
+type PersonGetters = Getters<Person>;
+// { getName: () => string; getAge: () => number }
+
+// Filter keys by remapping to never
+type RemoveFunctions<T> = {
+  [K in keyof T as T[K] extends Function ? never : K]: T[K];
+};
+
+interface Mixed {
+  name: string;
+  age: number;
+  greet(): void;
+}
+type DataOnly = RemoveFunctions<Mixed>;
+// { name: string; age: number }
+```
+
+## Iterating Over Unions
+
+Mapped types can iterate over any union of string literals, not just `keyof`:
+
+```typescript
+type EventMap = {
+  [K in "click" | "hover" | "focus"]: (e: Event) => void;
+};
+// { click: (e: Event) => void; hover: (e: Event) => void; focus: (e: Event) => void }
+
+// Using a union of string literals from an enum-like const
+const EVENTS = ["click", "hover", "focus"] as const;
+type EventHandlers = {
+  [K in (typeof EVENTS)[number] as `on${Capitalize<K>}`]: (e: Event) => void;
+};
+// { onClick: (e: Event) => void; onHover: (e: Event) => void; onFocus: (e: Event) => void }
+```
+
+## Practical Patterns
+
+### Making Specific Properties Optional
+
+```typescript
+type OptionalBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+type CreateUser = OptionalBy<User, "id">;
+// { name: string; email: string; id?: string }
+```
+
+### Deep Partial
+
+```typescript
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+interface Config {
+  server: { host: string; port: number };
+  db: { url: string; pool: { min: number; max: number } };
+}
+
+type PartialConfig = DeepPartial<Config>;
+// All nested properties are optional
+```
+
+### Deep Readonly
+
+```typescript
+type DeepReadonly<T> = {
+  readonly [K in keyof T]: T[K] extends object
+    ? T[K] extends Function
+      ? T[K]
+      : DeepReadonly<T[K]>
+    : T[K];
+};
+```
+
+### Nullable Properties
+
+```typescript
+type Nullable<T> = {
+  [K in keyof T]: T[K] | null;
+};
+```
+
+### Event Emitter Types
+
+```typescript
+type EventEmitter<Events extends Record<string, any[]>> = {
+  on<K extends keyof Events>(event: K, handler: (...args: Events[K]) => void): void;
+  emit<K extends keyof Events>(event: K, ...args: Events[K]): void;
+};
+
+interface MyEvents {
+  login: [user: User];
+  error: [code: number, message: string];
+  logout: [];
+}
+
+declare const emitter: EventEmitter<MyEvents>;
+emitter.on("login", (user) => { ... });        // user: User
+emitter.on("error", (code, msg) => { ... });   // code: number, msg: string
+emitter.emit("logout");                         // no args
+```
+
+### API Route Types
+
+```typescript
+type ApiRoutes = {
+  "/users": { GET: User[]; POST: User };
+  "/users/:id": { GET: User; PUT: User; DELETE: void };
+};
+
+type RouteHandler<
+  Routes extends Record<string, Record<string, any>>,
+  Path extends keyof Routes,
+  Method extends keyof Routes[Path]
+> = () => Promise<Routes[Path][Method]>;
+```
+
+### Record-Like with Constraints
+
+```typescript
+// Like Record, but values depend on the key
+type TypedRecord<K extends string, ValueFn extends Record<K, any>> = {
+  [P in K]: ValueFn[P];
+};
+
+// Each validator returns the type it validates
+type Validators = TypedRecord<
+  "name" | "age",
+  { name: string; age: number }
+>;
+// { name: string; age: number }
+```
+
+## Combining with Conditional Types
+
+```typescript
+// Make all function properties async
+type Asyncify<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R
+    ? (...args: A) => Promise<R>
+    : T[K];
+};
+
+interface Sync {
+  getData(): string;
+  count: number;
+}
+type Async = Asyncify<Sync>;
+// { getData: () => Promise<string>; count: number }
+```
+
+## Homomorphic vs Non-Homomorphic
+
+A mapped type is **homomorphic** when it maps over `keyof T` (preserving modifiers from the original):
+
+```typescript
+// Homomorphic — preserves optional/readonly from T
+type Clone<T> = { [K in keyof T]: T[K] };
+
+// Non-homomorphic — uses an independent key set
+type FromKeys<K extends string> = { [P in K]: unknown };
+```
+
+Homomorphic mapped types automatically preserve `readonly` and `?` modifiers unless explicitly removed with `-readonly` or `-?`.

package/src/skills/typescript-expert/references/advanced-template-literals.md

@@ -0,0 +1,209 @@
+# Template Literal Types
+
+Template literal types build string types from other types using template literal syntax. They're TypeScript's most powerful tool for type-safe string manipulation.
+
+## Basic Syntax
+
+```typescript
+type Greeting = `Hello, ${string}`;
+// Matches "Hello, Alice", "Hello, Bob", "Hello, " — any string after "Hello, "
+
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+type Endpoint = `/api/${string}`;
+type ApiCall = `${HttpMethod} ${Endpoint}`;
+// "GET /api/..." | "POST /api/..." | "PUT /api/..." | "DELETE /api/..."
+```
+
+## Union Expansion
+
+When unions appear in template literal positions, the result is the cross product:
+
+```typescript
+type Suit = "hearts" | "diamonds" | "clubs" | "spades";
+type Rank = "A" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "J" | "Q" | "K";
+type Card = `${Rank} of ${Suit}`;
+// "A of hearts" | "A of diamonds" | ... | "K of spades" (52 members)
+
+type Size = "sm" | "md" | "lg";
+type Color = "red" | "blue" | "green";
+type Variant = `${Size}-${Color}`;
+// "sm-red" | "sm-blue" | "sm-green" | "md-red" | ... (9 members)
+```
+
+## Intrinsic String Manipulation Types
+
+TypeScript provides four built-in types that transform string literals:
+
+```typescript
+type A = Uppercase<"hello">;       // "HELLO"
+type B = Lowercase<"HELLO">;       // "hello"
+type C = Capitalize<"hello">;      // "Hello"
+type D = Uncapitalize<"Hello">;    // "hello"
+
+// Combined with template literals
+type EventHandler<T extends string> = `on${Capitalize<T>}`;
+type Click = EventHandler<"click">;     // "onClick"
+type KeyDown = EventHandler<"keyDown">; // "onKeyDown"
+```
+
+## Pattern Matching with `infer`
+
+Template literals can extract parts of string types:
+
+```typescript
+// Extract the event name from "on{Event}"
+type ExtractEvent<T> = T extends `on${infer E}` ? Uncapitalize<E> : never;
+type A = ExtractEvent<"onClick">;   // "click"
+type B = ExtractEvent<"onKeyDown">; // "keyDown"
+type C = ExtractEvent<"submit">;    // never
+
+// Parse dot-separated paths
+type FirstSegment<T extends string> = T extends `${infer Head}.${string}` ? Head : T;
+type D = FirstSegment<"user.address.city">; // "user"
+type E = FirstSegment<"name">;               // "name"
+
+// Split a string type
+type Split<S extends string, D extends string> =
+  S extends `${infer Head}${D}${infer Tail}`
+    ? [Head, ...Split<Tail, D>]
+    : [S];
+
+type F = Split<"a.b.c", ".">;  // ["a", "b", "c"]
+```
+
+## Practical Patterns
+
+### Type-Safe Event System
+
+```typescript
+type EventMap = {
+  click: { x: number; y: number };
+  keydown: { key: string };
+  resize: { width: number; height: number };
+};
+
+type EventHandlerName<T extends string> = `on${Capitalize<T>}`;
+
+type EventHandlers<E extends Record<string, any>> = {
+  [K in keyof E as EventHandlerName<string & K>]?: (event: E[K]) => void;
+};
+
+type MyHandlers = EventHandlers<EventMap>;
+// { onClick?: (event: { x: number; y: number }) => void;
+//   onKeydown?: (event: { key: string }) => void;
+//   onResize?: (event: { width: number; height: number }) => void; }
+```
+
+### Type-Safe CSS Properties
+
+```typescript
+type CSSUnit = "px" | "em" | "rem" | "%" | "vh" | "vw";
+type CSSValue = `${number}${CSSUnit}` | "auto" | "inherit";
+
+function setWidth(el: HTMLElement, width: CSSValue) {
+  el.style.width = width;
+}
+
+setWidth(el, "100px");   // OK
+setWidth(el, "2.5rem");  // OK
+setWidth(el, "auto");    // OK
+setWidth(el, "100");     // Error — missing unit
+```
+
+### Route Parameter Extraction
+
+```typescript
+type ExtractParams<T extends string> =
+  T extends `${string}:${infer Param}/${infer Rest}`
+    ? Param | ExtractParams<`/${Rest}`>
+    : T extends `${string}:${infer Param}`
+      ? Param
+      : never;
+
+type Params = ExtractParams<"/users/:userId/posts/:postId">;
+// "userId" | "postId"
+
+type RouteParams<T extends string> = {
+  [K in ExtractParams<T>]: string;
+};
+
+type UserPostParams = RouteParams<"/users/:userId/posts/:postId">;
+// { userId: string; postId: string }
+```
+
+### SQL Column Type Mapping
+
+```typescript
+type SQLType = "TEXT" | "INTEGER" | "BOOLEAN" | "TIMESTAMP";
+
+type TSTypeMap = {
+  TEXT: string;
+  INTEGER: number;
+  BOOLEAN: boolean;
+  TIMESTAMP: Date;
+};
+
+type ColumnDef<Name extends string, Type extends SQLType> = `${Name} ${Type}`;
+
+type ParseColumn<T> = T extends `${infer Name} ${infer Type extends SQLType}`
+  ? { name: Name; type: TSTypeMap[Type] }
+  : never;
+
+type Col = ParseColumn<"username TEXT">;
+// { name: "username"; type: string }
+```
+
+### Deep Property Paths
+
+```typescript
+type PropPath<T, Prefix extends string = ""> = {
+  [K in keyof T & string]: T[K] extends object
+    ? PropPath<T[K], `${Prefix}${K}.`>
+    : `${Prefix}${K}`;
+}[keyof T & string];
+
+interface User {
+  name: string;
+  address: {
+    city: string;
+    zip: string;
+  };
+}
+
+type UserPaths = PropPath<User>;
+// "name" | "address.city" | "address.zip"
+```
+
+## Template Literals as Discriminants (TS 4.5+)
+
+Template literal types can serve as discriminants in unions:
+
+```typescript
+interface SuccessResponse {
+  type: `${string}Success`;
+  data: unknown;
+}
+
+interface ErrorResponse {
+  type: `${string}Error`;
+  message: string;
+}
+
+function handle(r: SuccessResponse | ErrorResponse) {
+  if (r.type === "ApiSuccess") {
+    r.data;  // SuccessResponse narrowed
+  }
+}
+```
+
+## Performance Considerations
+
+Template literal unions grow multiplicatively. A cross product of two unions with 10 members each creates 100 members. TypeScript limits union sizes (around 100,000 members), so avoid unbounded cross products:
+
+```typescript
+// This is fine — 3 x 3 = 9 members
+type Small = `${1 | 2 | 3}-${"a" | "b" | "c"}`;
+
+// This would be problematic — string has infinite members
+// type Bad = `${string}-${string}`; // Works but can't enumerate
+```