@biggora/claude-plugins 1.2.2 → 1.3.1

package/src/skills/typescript-expert/references/core-utility-types.md

@@ -0,0 +1,235 @@
+# Built-in Utility Types
+
+TypeScript ships with utility types that transform existing types. These are invaluable for deriving new types without repetition.
+
+## Object Transformation
+
+### `Partial<T>` — Make All Properties Optional
+
+```typescript
+interface User {
+  name: string;
+  email: string;
+  age: number;
+}
+
+type PartialUser = Partial<User>;
+// { name?: string; email?: string; age?: number }
+
+// Common use: update functions that accept partial data
+function updateUser(id: string, updates: Partial<User>): User { ... }
+updateUser("1", { name: "Alice" }); // OK — only updating name
+```
+
+### `Required<T>` — Make All Properties Required
+
+```typescript
+interface Config {
+  host?: string;
+  port?: number;
+  debug?: boolean;
+}
+
+type FullConfig = Required<Config>;
+// { host: string; port: number; debug: boolean }
+```
+
+### `Readonly<T>` — Make All Properties Readonly
+
+```typescript
+type FrozenUser = Readonly<User>;
+// { readonly name: string; readonly email: string; readonly age: number }
+
+const user: FrozenUser = { name: "Alice", email: "a@b.com", age: 30 };
+user.name = "Bob"; // Error!
+
+// Note: Readonly is shallow — nested objects are still mutable
+```
+
+### `Pick<T, K>` — Select Specific Properties
+
+```typescript
+type UserPreview = Pick<User, "name" | "email">;
+// { name: string; email: string }
+```
+
+### `Omit<T, K>` — Remove Specific Properties
+
+```typescript
+type UserWithoutEmail = Omit<User, "email">;
+// { name: string; age: number }
+
+// Common: creating input types from entity types
+type CreateUserInput = Omit<User, "id" | "createdAt">;
+```
+
+### `Record<K, V>` — Object with Known Keys and Value Type
+
+```typescript
+// String-keyed dictionary
+type UserMap = Record<string, User>;
+
+// Enum/union-keyed object (ensures all keys are covered)
+type RolePermissions = Record<"admin" | "user" | "guest", string[]>;
+const perms: RolePermissions = {
+  admin: ["read", "write", "delete"],
+  user: ["read", "write"],
+  guest: ["read"],
+};
+// Missing a key would be an error
+```
+
+## Union Manipulation
+
+### `Exclude<T, U>` — Remove Types from Union
+
+```typescript
+type T = "a" | "b" | "c";
+type WithoutA = Exclude<T, "a">;     // "b" | "c"
+type OnlyStrings = Exclude<string | number | boolean, number | boolean>; // string
+```
+
+### `Extract<T, U>` — Keep Only Matching Types
+
+```typescript
+type T = string | number | (() => void);
+type Funcs = Extract<T, Function>;    // () => void
+type Primitives = Extract<T, string | number>; // string | number
+```
+
+### `NonNullable<T>` — Remove `null` and `undefined`
+
+```typescript
+type MaybeString = string | null | undefined;
+type DefiniteString = NonNullable<MaybeString>; // string
+```
+
+## Function Utilities
+
+### `ReturnType<T>` — Extract Return Type
+
+```typescript
+function getUser() {
+  return { id: "1", name: "Alice", roles: ["admin"] };
+}
+
+type User = ReturnType<typeof getUser>;
+// { id: string; name: string; roles: string[] }
+
+// Works with generics via conditional types
+type AsyncReturn<T extends (...args: any) => any> =
+  ReturnType<T> extends Promise<infer R> ? R : ReturnType<T>;
+```
+
+### `Parameters<T>` — Extract Parameter Types as Tuple
+
+```typescript
+function createUser(name: string, age: number, admin: boolean): User { ... }
+
+type CreateUserParams = Parameters<typeof createUser>;
+// [name: string, age: number, admin: boolean]
+
+// Access individual parameters
+type FirstParam = Parameters<typeof createUser>[0]; // string
+```
+
+### `ConstructorParameters<T>` — Constructor Parameter Types
+
+```typescript
+class User {
+  constructor(public name: string, public age: number) {}
+}
+
+type UserCtorParams = ConstructorParameters<typeof User>;
+// [name: string, age: number]
+```
+
+### `InstanceType<T>` — Instance Type from Constructor
+
+```typescript
+type UserInstance = InstanceType<typeof User>; // User
+```
+
+## String Manipulation Types
+
+```typescript
+type Upper = Uppercase<"hello">;      // "HELLO"
+type Lower = Lowercase<"HELLO">;      // "hello"
+type Cap = Capitalize<"hello">;       // "Hello"
+type Uncap = Uncapitalize<"Hello">;   // "hello"
+
+// Powerful with template literals
+type EventName<T extends string> = `on${Capitalize<T>}`;
+type ClickEvent = EventName<"click">; // "onClick"
+```
+
+## Promise Utilities
+
+### `Awaited<T>` — Unwrap Promise Types (TS 4.5+)
+
+```typescript
+type A = Awaited<Promise<string>>;              // string
+type B = Awaited<Promise<Promise<number>>>;     // number (recursive unwrap)
+type C = Awaited<boolean | Promise<string>>;    // boolean | string
+```
+
+## `NoInfer<T>` (TS 5.4+)
+
+Prevents a type parameter position from being used for inference:
+
+```typescript
+function createStreetLight<C extends string>(
+  colors: C[],
+  defaultColor?: NoInfer<C>
+) { ... }
+
+createStreetLight(["red", "yellow", "green"], "blue");
+// Error! "blue" is not "red" | "yellow" | "green"
+// Without NoInfer, TypeScript would widen C to include "blue"
+```
+
+## Composing Utility Types
+
+Utility types compose naturally:
+
+```typescript
+// Readonly partial (for frozen default configs)
+type Defaults<T> = Readonly<Partial<T>>;
+
+// Pick and make required
+type RequiredPick<T, K extends keyof T> = Required<Pick<T, K>>;
+
+// Omit and make readonly
+type ProtectedOmit<T, K extends keyof T> = Readonly<Omit<T, K>>;
+
+// Make some properties optional, keep the rest
+type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+type UserOptionalEmail = PartialBy<User, "email">;
+// { name: string; age: number; email?: string }
+
+// Make some properties required, keep the rest optional
+type RequiredBy<T, K extends keyof T> = Partial<Omit<T, K>> & Required<Pick<T, K>>;
+```
+
+## Quick Reference Table
+
+| Utility | Input | Output |
+|---------|-------|--------|
+| `Partial<T>` | `{ a: string; b: number }` | `{ a?: string; b?: number }` |
+| `Required<T>` | `{ a?: string; b?: number }` | `{ a: string; b: number }` |
+| `Readonly<T>` | `{ a: string }` | `{ readonly a: string }` |
+| `Pick<T, K>` | `{ a: string; b: number }, "a"` | `{ a: string }` |
+| `Omit<T, K>` | `{ a: string; b: number }, "a"` | `{ b: number }` |
+| `Record<K, V>` | `"a" \| "b", number` | `{ a: number; b: number }` |
+| `Exclude<T, U>` | `"a" \| "b" \| "c", "a"` | `"b" \| "c"` |
+| `Extract<T, U>` | `string \| number, string` | `string` |
+| `NonNullable<T>` | `string \| null` | `string` |
+| `ReturnType<T>` | `() => string` | `string` |
+| `Parameters<T>` | `(a: string, b: number) => void` | `[string, number]` |
+| `Awaited<T>` | `Promise<string>` | `string` |
+| `NoInfer<T>` | Prevents inference at position | Same type, no inference |
+| `Uppercase<S>` | `"hello"` | `"HELLO"` |
+| `Lowercase<S>` | `"HELLO"` | `"hello"` |
+| `Capitalize<S>` | `"hello"` | `"Hello"` |
+| `Uncapitalize<S>` | `"Hello"` | `"hello"` |

package/src/skills/typescript-expert/references/features-ts5x.md

@@ -0,0 +1,370 @@
+# TypeScript 5.x Features
+
+A comprehensive guide to features added in TypeScript 5.0 through 5.8.
+
+## TypeScript 5.0
+
+### TC39 Decorators
+
+Standard decorators without `experimentalDecorators`. See [advanced-decorators](advanced-decorators.md) for full details.
+
+```typescript
+function log(target: Function, context: ClassMethodDecoratorContext) {
+  return function (...args: any[]) {
+    console.log(`Calling ${String(context.name)}`);
+    return target.apply(this, args);
+  };
+}
+
+class Api {
+  @log
+  fetchData() { ... }
+}
+```
+
+### `const` Type Parameters
+
+Add `const` modifier to type parameters for const-like inference:
+
+```typescript
+function createConfig<const T extends Record<string, unknown>>(config: T): T {
+  return config;
+}
+
+// Infers literal types without 'as const' at call site
+const config = createConfig({
+  env: "production",
+  port: 3000,
+  features: ["auth", "logging"],
+});
+// Type: { readonly env: "production"; readonly port: 3000; readonly features: readonly ["auth", "logging"] }
+```
+
+### `--verbatimModuleSyntax`
+
+Forces explicit `type` annotations on type-only imports/exports:
+
+```typescript
+import type { User } from "./models";       // Erased
+import { type Role, createUser } from "./models"; // Role erased, createUser kept
+export type { User };                        // Erased
+```
+
+Replaces the older `importsNotUsedAsValues` and `preserveValueImports` flags.
+
+### `export type *`
+
+Re-export all types from a module as type-only:
+
+```typescript
+export type * from "./internal-types";
+export type * as models from "./models";
+```
+
+### Bundler Module Resolution
+
+`"moduleResolution": "bundler"` — use when a bundler handles resolution:
+
+```jsonc
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true // Optional: allow .ts imports
+  }
+}
+```
+
+## TypeScript 5.1
+
+### Easier Implicit Returns for `undefined`
+
+Functions returning `undefined` no longer need an explicit `return` statement:
+
+```typescript
+// Before 5.1: needed 'return;' or 'return undefined;'
+function logMessage(msg: string): undefined {
+  console.log(msg);
+  // No return needed — implicitly returns undefined
+}
+```
+
+### Unrelated Types for Getters and Setters
+
+Getters and setters can have different types:
+
+```typescript
+class State {
+  #value: number = 0;
+
+  get value(): number {
+    return this.#value;
+  }
+
+  set value(input: string | number) {
+    this.#value = typeof input === "string" ? parseInt(input) : input;
+  }
+}
+
+const s = new State();
+s.value = "42";    // Setter accepts string | number
+const n = s.value; // Getter returns number
+```
+
+### JSX Improvements
+
+Support for different JSX element types per-tag. Enables React Server Components to be typed differently from client components.
+
+## TypeScript 5.2
+
+### `using` Declarations (Explicit Resource Management)
+
+Deterministic cleanup with `Symbol.dispose` and `Symbol.asyncDispose`:
+
+```typescript
+class TempFile implements Disposable {
+  #path: string;
+
+  constructor(path: string) {
+    this.#path = path;
+    writeFileSync(path, "");
+  }
+
+  write(data: string) {
+    appendFileSync(this.#path, data);
+  }
+
+  [Symbol.dispose]() {
+    unlinkSync(this.#path);
+    console.log(`Cleaned up ${this.#path}`);
+  }
+}
+
+function processData() {
+  using file = new TempFile("/tmp/data.txt");
+  file.write("processing...");
+  // file is automatically disposed when scope exits
+  // Even if an exception is thrown
+}
+
+// Async version
+class DatabaseConnection implements AsyncDisposable {
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+}
+
+async function query() {
+  await using conn = await connect();
+  return await conn.query("SELECT ...");
+  // conn.close() called automatically
+}
+```
+
+### Decorator Metadata
+
+Access shared metadata object from decorator context:
+
+```typescript
+function route(path: string) {
+  return (target: any, context: ClassMethodDecoratorContext) => {
+    context.metadata[String(context.name)] = { path };
+  };
+}
+
+class Controller {
+  @route("/users")
+  getUsers() { ... }
+}
+
+const meta = Controller[Symbol.metadata];
+// { getUsers: { path: "/users" } }
+```
+
+## TypeScript 5.3
+
+### `import` Attributes
+
+```typescript
+import data from "./data.json" with { type: "json" };
+import styles from "./styles.css" with { type: "css" };
+```
+
+### `switch (true)` Narrowing
+
+TypeScript now properly narrows types in `switch (true)` patterns:
+
+```typescript
+function process(value: string | number | boolean) {
+  switch (true) {
+    case typeof value === "string":
+      value.toUpperCase(); // value is string
+      break;
+    case typeof value === "number":
+      value.toFixed(2);    // value is number
+      break;
+  }
+}
+```
+
+## TypeScript 5.4
+
+### `NoInfer<T>` Utility Type
+
+Prevents a position from contributing to type inference:
+
+```typescript
+function createStreetLight<C extends string>(
+  colors: C[],
+  defaultColor?: NoInfer<C>
+) { ... }
+
+createStreetLight(["red", "yellow", "green"], "blue");
+// Error! "blue" not in "red" | "yellow" | "green"
+// Without NoInfer, C would widen to include "blue"
+```
+
+### Closure Narrowing in `Array.isArray`
+
+```typescript
+function process(value: string | string[]) {
+  if (Array.isArray(value)) {
+    value.map(s => s.toUpperCase()); // value is string[]
+  }
+}
+```
+
+## TypeScript 5.5
+
+### Inferred Type Predicates
+
+TypeScript can now infer type guard return types:
+
+```typescript
+// Before: needed explicit annotation
+function isString(x: unknown): x is string {
+  return typeof x === "string";
+}
+
+// TS 5.5: inferred automatically for simple cases
+const isString = (x: unknown) => typeof x === "string";
+// Return type inferred as: x is string
+
+// filter(Boolean) just works now
+const items = [1, null, 2, undefined, 3];
+const numbers = items.filter(Boolean); // number[]
+// Previously: (number | null | undefined)[]
+```
+
+### Regular Expression Syntax Checking
+
+TypeScript now validates regex syntax at the type level:
+
+```typescript
+const re = /\p{Letter}/u; // OK
+const bad = /[/;           // Error: Unterminated character class
+```
+
+## TypeScript 5.6
+
+### Iterator Helper Methods
+
+Built-in iterator methods like `.map()`, `.filter()`, `.take()`:
+
+```typescript
+function* naturals() {
+  let n = 0;
+  while (true) yield n++;
+}
+
+const evens = naturals()
+  .filter(n => n % 2 === 0)
+  .take(5)
+  .toArray();
+// [0, 2, 4, 6, 8]
+
+// Works with any Iterable
+const map = new Map([["a", 1], ["b", 2]]);
+const keys = map.keys().filter(k => k !== "a").toArray();
+// ["b"]
+```
+
+### Disallowed Nullish and Truthy Checks
+
+```typescript
+// New errors for always-truthy or always-nullish comparisons
+function process(x: string) {
+  if (x) { }          // OK — string can be falsy ("")
+}
+
+function process(x: () => void) {
+  if (x) { }          // Error! Function is always truthy — did you mean x()?
+}
+```
+
+## TypeScript 5.7
+
+### `--squash` for Project References
+
+Faster `--build` by squashing intermediate outputs.
+
+### Relative Path Rewriting in Declaration Files
+
+Declaration files now preserve relative path structure, improving monorepo support.
+
+### Initialized `Symbol.dispose` in `using` Declarations
+
+```typescript
+using _ = {
+  [Symbol.dispose]() {
+    console.log("cleanup");
+  }
+};
+```
+
+## TypeScript 5.8
+
+### `--erasableSyntaxOnly`
+
+Ensures only erasable TypeScript syntax is used — no enums, namespaces, or parameter properties:
+
+```jsonc
+{
+  "compilerOptions": {
+    "erasableSyntaxOnly": true
+  }
+}
+```
+
+This flag is designed for use with Node.js `--strip-types` (Node 22.6+), which strips TypeScript annotations but doesn't transform:
+
+```typescript
+// Allowed: type annotations are erasable
+const x: string = "hello";
+function greet(name: string): void { }
+
+// Disallowed: these need transformation, not just erasure
+enum Color { Red, Green, Blue }          // Error
+namespace Foo { export const x = 1; }    // Error
+class C { constructor(public x: number) {} } // Error (parameter property)
+```
+
+### Granular Checks on Branches in Return Expressions
+
+TypeScript 5.8 checks individual branches of ternary expressions against the return type:
+
+```typescript
+function process(value: string | null): string {
+  return value ?? 42;
+  // Error on 42 specifically — previous versions gave a less helpful error
+}
+```
+
+## Migration Tips
+
+When upgrading TypeScript versions:
+
+1. **Read the release notes** — each version has breaking changes
+2. **Update `@types/*` packages** — they often need matching versions
+3. **Run `tsc --noEmit` first** — check for new errors before building
+4. **Enable new strict flags gradually** — add one at a time
+5. **Use `// @ts-expect-error`** — for known issues you'll fix later (not `@ts-ignore`)