@biggora/claude-plugins 1.2.0 → 1.3.0

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
+```