@booklib/core 2.0.0

package/skills/effective-typescript/references/api_reference.md

@@ -0,0 +1,118 @@
+# Effective TypeScript — All 62 Items
+
+All items from Dan Vanderkam's "Effective TypeScript" organized by chapter with priority levels.
+
+## Chapter 1: Getting to Know TypeScript (Items 1–5)
+
+| Item | Title | Priority |
+|------|-------|----------|
+| 1 | Understand the Relationship Between TypeScript and JavaScript | Important |
+| 2 | Know Which TypeScript Options You're Using | **Critical** |
+| 3 | Understand That Code Generation Is Independent of Types | Important |
+| 4 | Get Comfortable with Structural Typing | Important |
+| 5 | Limit Use of the `any` Type | **Critical** |
+
+## Chapter 2: TypeScript's Type System (Items 6–18)
+
+| Item | Title | Priority |
+|------|-------|----------|
+| 6 | Use Your Editor to Interrogate and Explore the Type System | Suggestion |
+| 7 | Think of Types as Sets of Values | Important |
+| 8 | Know How to Tell Whether a Symbol Is in the Type Space or Value Space | Important |
+| 9 | Prefer Type Declarations to Type Assertions | **Critical** |
+| 10 | Avoid Object Wrapper Types (String, Number, Boolean, Symbol, BigInt) | **Critical** |
+| 11 | Recognize the Limits of Excess Property Checking | Important |
+| 12 | Apply Types to Entire Function Expressions When Possible | Important |
+| 13 | Know the Differences Between `type` and `interface` | Important |
+| 14 | Use Type Operations and Generics to Avoid Repeating Yourself | Important |
+| 15 | Use Index Signatures for Dynamic Data | Important |
+| 16 | Prefer Arrays, Tuples, and ArrayLike to `number` Index Signatures | Suggestion |
+| 17 | Use `readonly` to Avoid Errors Associated with Mutation | Important |
+| 18 | Use Mapped Types to Keep Values in Sync | Important |
+
+## Chapter 3: Type Inference (Items 19–27)
+
+| Item | Title | Priority |
+|------|-------|----------|
+| 19 | Avoid Cluttering Your Code with Inferable Types | Suggestion |
+| 20 | Use Different Variables for Different Types | Important |
+| 21 | Understand Type Widening | Important |
+| 22 | Understand Type Narrowing | **Critical** |
+| 23 | Create Objects All at Once | Important |
+| 24 | Be Consistent in Your Use of Aliases | Important |
+| 25 | Use `async` Functions Instead of Callbacks for Asynchronous Code | Important |
+| 26 | Understand How Context Is Used in Type Inference | Important |
+| 27 | Use Functional Constructs and Libraries to Help Types Flow | Suggestion |
+
+## Chapter 4: Type Design (Items 28–37)
+
+| Item | Title | Priority |
+|------|-------|----------|
+| 28 | Prefer Types That Always Represent Valid States | **Critical** |
+| 29 | Be Liberal in What You Accept and Strict in What You Produce | Important |
+| 30 | Don't Repeat Type Information in Documentation | Important |
+| 31 | Push Null Values to the Perimeter of Your Types | **Critical** |
+| 32 | Prefer Unions of Interfaces to Interfaces of Unions | **Critical** |
+| 33 | Prefer More Precise Alternatives to String Types | Important |
+| 34 | Prefer Incomplete Types to Inaccurate Types | Important |
+| 35 | Generate Types from APIs and Specs, Not Data | Suggestion |
+| 36 | Name Types Using the Language of Your Problem Domain | Important |
+| 37 | Consider "Brands" for Nominal Typing | Suggestion |
+
+## Chapter 5: Working with any (Items 38–44)
+
+| Item | Title | Priority |
+|------|-------|----------|
+| 38 | Use the Narrowest Possible Scope for `any` Types | **Critical** |
+| 39 | Prefer More Precise Variants of `any` to Plain `any` | Important |
+| 40 | Hide Unsafe Type Assertions in Well-Typed Functions | Important |
+| 41 | Understand Evolving `any` | Important |
+| 42 | Use `unknown` Instead of `any` for Values with an Unknown Type | **Critical** |
+| 43 | Prefer Type-Safe Approaches to Monkey Patching | Important |
+| 44 | Track Your Type Coverage to Prevent Regressions in Type Safety | Suggestion |
+
+## Chapter 6: Type Declarations and @types (Items 45–52)
+
+| Item | Title | Priority |
+|------|-------|----------|
+| 45 | Put TypeScript and `@types` in devDependencies | Important |
+| 46 | Understand the Three Versions Involved in Type Declarations | Important |
+| 47 | Export All Types That Appear in Public APIs | Important |
+| 48 | Use TSDoc for API Comments | Important |
+| 49 | Provide a Type for `this` in Callbacks | Important |
+| 50 | Prefer Conditional Types to Overloaded Declarations | Suggestion |
+| 51 | Mirror Types to Sever Dependencies | Suggestion |
+| 52 | Be Aware of the Pitfalls of Testing Types | Important |
+
+## Chapter 7: Writing and Running Your Code (Items 53–57)
+
+| Item | Title | Priority |
+|------|-------|----------|
+| 53 | Prefer ECMAScript Features to TypeScript Features | Important |
+| 54 | Know How to Iterate Over Objects | Important |
+| 55 | Understand the DOM Hierarchy | Important |
+| 56 | Don't Rely on `private` to Hide Information | Important |
+| 57 | Use Source Maps to Debug TypeScript | Suggestion |
+
+## Chapter 8: Migrating to TypeScript (Items 58–62)
+
+| Item | Title | Priority |
+|------|-------|----------|
+| 58 | Write Modern JavaScript | Important |
+| 59 | Use `@ts-check` and JSDoc to Experiment with TypeScript | Suggestion |
+| 60 | Use `allowJs` to Mix TypeScript and JavaScript | Important |
+| 61 | Convert Module by Module Up Your Dependency Graph | Important |
+| 62 | Don't Consider Migration Complete Until You Enable `noImplicitAny` | **Critical** |
+
+---
+
+## Priority Summary
+
+**Critical (fix immediately — correctness or safety)**
+Items: 2, 5, 9, 10, 22, 28, 31, 32, 38, 42, 62
+
+**Important (fix soon — maintainability and idiom)**
+Items: 3, 4, 7, 8, 11, 12, 13, 14, 15, 17, 18, 20, 21, 23, 24, 25, 26, 29, 30, 33, 34, 36, 39, 40, 41, 43, 45, 46, 47, 48, 49, 52, 53, 54, 55, 56, 58, 60, 61
+
+**Suggestion (polish when time allows)**
+Items: 6, 16, 19, 27, 35, 37, 44, 50, 51, 57, 59

package/skills/effective-typescript/references/practices-catalog.md

@@ -0,0 +1,371 @@
+# Effective TypeScript — Practices Catalog
+
+Deep before/after examples for the 20 most impactful items.
+
+---
+
+## Item 2: Know Which TypeScript Options You're Using
+
+Always use `strict: true`. It enables `noImplicitAny` and `strictNullChecks` which catch the most common TypeScript bugs.
+
+**Before:**
+```json
+{ "compilerOptions": {} }
+```
+**After:**
+```json
+{ "compilerOptions": { "strict": true, "target": "ES2020", "module": "commonjs" } }
+```
+
+---
+
+## Item 9: Prefer Type Declarations to Type Assertions
+
+**Before:**
+```typescript
+const user = {} as User;  // bypasses type checking — user is actually empty
+const input = document.getElementById('name') as HTMLInputElement;
+```
+**After:**
+```typescript
+const user: User = { id: '1', name: 'Alice', email: 'a@example.com' }; // checked
+const input = document.getElementById('name');
+if (input instanceof HTMLInputElement) {
+  console.log(input.value); // narrowed, not asserted
+}
+```
+
+---
+
+## Item 10: Avoid Object Wrapper Types
+
+**Before:**
+```typescript
+function greet(name: String) { // String, not string
+  return 'Hello ' + name;
+}
+const s = new String('world');
+greet(s); // works but s !== 'world' as a primitive
+```
+**After:**
+```typescript
+function greet(name: string) {  // primitive type
+  return 'Hello ' + name;
+}
+```
+
+---
+
+## Item 13: Know the Differences Between `type` and `interface`
+
+- Use `interface` for object shapes that consumers may need to extend (open for augmentation)
+- Use `type` for unions, intersections, tuples, and mapped types (cannot be augmented)
+
+**Before:**
+```typescript
+type User = { id: string; name: string }; // fine, but can't be augmented by consumers
+type StringOrNumber = string | number;     // correct use of type
+```
+**After:**
+```typescript
+interface User { id: string; name: string; }  // open for extension
+type StringOrNumber = string | number;         // unions must be type aliases
+type ReadonlyUser = Readonly<User>;            // mapped type must be type alias
+```
+
+---
+
+## Item 14: Use Type Operations and Generics to Avoid Repeating Yourself
+
+**Before:**
+```typescript
+interface SavedState { userId: string; name: string; lastSaved: Date; }
+interface UnsavedState { userId: string; name: string; }  // repeated fields
+```
+**After:**
+```typescript
+interface State { userId: string; name: string; }
+interface SavedState extends State { lastSaved: Date; }
+// Or with Pick/Omit:
+type UnsavedState = Omit<SavedState, 'lastSaved'>;
+```
+
+---
+
+## Item 17: Use `readonly` to Avoid Errors Associated with Mutation
+
+**Before:**
+```typescript
+function sort(arr: number[]): number[] {
+  return arr.sort(); // mutates the original array!
+}
+```
+**After:**
+```typescript
+function sort(arr: readonly number[]): number[] {
+  return [...arr].sort(); // forced to copy — cannot mutate readonly input
+}
+```
+
+---
+
+## Item 22: Understand Type Narrowing
+
+**Before:**
+```typescript
+function processInput(val: string | null) {
+  console.log(val.toUpperCase()); // error: val is possibly null
+}
+```
+**After:**
+```typescript
+function processInput(val: string | null) {
+  if (val === null) return;
+  console.log(val.toUpperCase()); // narrowed to string
+}
+
+// instanceof narrowing
+function format(val: Date | string) {
+  if (val instanceof Date) return val.toISOString();
+  return val.toUpperCase();
+}
+```
+
+---
+
+## Item 25: Use async Functions Instead of Callbacks for Asynchronous Code
+
+Callbacks produce `any`-typed errors and complex nested types. `async`/`await` lets TypeScript infer `Promise<T>` cleanly.
+
+**Before:**
+```typescript
+function fetchData(url: string, cb: (err: any, data: any) => void) {
+  fetch(url)
+    .then(r => r.json())
+    .then(d => cb(null, d))
+    .catch(e => cb(e, null));
+}
+```
+**After:**
+```typescript
+async function fetchData<T>(url: string): Promise<T> {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return response.json() as T;
+}
+```
+
+---
+
+## Item 28: Prefer Types That Always Represent Valid States
+
+**Before:**
+```typescript
+interface Page {
+  pageText: string;
+  isLoading: boolean;
+  error: string; // What does isLoading:true + error:'...' mean?
+}
+```
+**After:**
+```typescript
+type Page =
+  | { state: 'loading' }
+  | { state: 'success'; pageText: string }
+  | { state: 'error'; error: string };
+// Every combination is meaningful — no impossible states
+```
+
+---
+
+## Item 31: Push Null Values to the Perimeter
+
+**Before:**
+```typescript
+// null scattered throughout
+function getUser(id: string | null): User | null {
+  if (!id) return null;
+  const user: User | null = db.find(id) ?? null;
+  return user;
+}
+```
+**After:**
+```typescript
+// null handled once at the boundary
+function getUser(id: string): User {
+  const user = db.find(id);
+  if (!user) throw new Error(`User ${id} not found`);
+  return user;
+}
+// Callers who might not have an id handle it at their boundary
+```
+
+---
+
+## Item 32: Prefer Unions of Interfaces to Interfaces of Unions
+
+**Before:**
+```typescript
+interface Layer {
+  type: 'fill' | 'line' | 'point';
+  fillColor?: string;   // only for fill
+  lineWidth?: number;   // only for line
+  pointRadius?: number; // only for point
+  // { type: 'fill', lineWidth: 5 } is representable but invalid
+}
+```
+**After:**
+```typescript
+interface FillLayer   { type: 'fill';  fillColor: string; }
+interface LineLayer   { type: 'line';  lineWidth: number; }
+interface PointLayer  { type: 'point'; pointRadius: number; }
+type Layer = FillLayer | LineLayer | PointLayer;
+// Each valid state has exactly the right fields
+```
+
+---
+
+## Item 33: Prefer More Precise Alternatives to String Types
+
+**Before:**
+```typescript
+function setAlignment(align: string) {} // accepts anything
+interface Album { genre: string; }      // 'rock', 'jazz', or 'anything'?
+```
+**After:**
+```typescript
+type Alignment = 'left' | 'center' | 'right';
+function setAlignment(align: Alignment) {}
+
+type Genre = 'rock' | 'jazz' | 'pop' | 'classical';
+interface Album { genre: Genre; }
+```
+
+---
+
+## Item 38: Use the Narrowest Possible Scope for `any` Types
+
+**Before:**
+```typescript
+const config: any = JSON.parse(rawConfig); // entire variable is any
+console.log(config.timeout);               // no type checking from here on
+```
+**After:**
+```typescript
+const config = JSON.parse(rawConfig) as { timeout: number; retries: number };
+// or better — parse with unknown and narrow:
+const raw: unknown = JSON.parse(rawConfig);
+const timeout = (raw as { timeout: number }).timeout; // any scoped to one property access
+```
+
+---
+
+## Item 40: Hide Unsafe Type Assertions in Well-Typed Functions
+
+**Before:**
+```typescript
+// Assertion visible at every call site
+const user = fetchUser() as User;
+```
+**After:**
+```typescript
+// Assertion encapsulated once — all callers get proper types
+async function fetchUser(id: string): Promise<User> {
+  const raw: unknown = await fetch(`/api/users/${id}`).then(r => r.json());
+  return raw as User; // single controlled assertion inside typed boundary
+}
+```
+
+---
+
+## Item 42: Use `unknown` Instead of `any` for Values with an Unknown Type
+
+**Before:**
+```typescript
+function parseYaml(yaml: string): any { // callers never have to narrow
+  return parse(yaml);
+}
+const config = parseYaml(raw);
+config.port.toFixed(); // no error — but crashes if port is missing
+```
+**After:**
+```typescript
+function parseYaml(yaml: string): unknown { // callers must narrow before use
+  return parse(yaml);
+}
+const config = parseYaml(raw);
+if (typeof config === 'object' && config !== null && 'port' in config) {
+  const port = (config as { port: number }).port;
+}
+```
+
+---
+
+## Item 47: Export All Types That Appear in Public APIs
+
+**Before:**
+```typescript
+// Unexported — users have to use ReturnType<typeof getUser> hacks
+interface User { id: string; name: string; }
+export function getUser(id: string): User { ... }
+```
+**After:**
+```typescript
+export interface User { id: string; name: string; } // exported explicitly
+export function getUser(id: string): User { ... }
+```
+
+---
+
+## Item 48: Use TSDoc for API Comments
+
+**Before:**
+```typescript
+// Fetches user by id. Returns null if not found.
+function getUser(id: string): User | null { ... }
+```
+**After:**
+```typescript
+/**
+ * Fetches a user by their unique identifier.
+ *
+ * @param id - The user's unique identifier
+ * @returns The user, or null if no user exists with that id
+ * @throws {NetworkError} If the network request fails
+ */
+function getUser(id: string): User | null { ... }
+```
+
+---
+
+## Item 53: Prefer ECMAScript Features to TypeScript Features
+
+Avoid TypeScript-specific features that don't map cleanly to JavaScript. Prefer standard ES features.
+
+**Before:**
+```typescript
+// TypeScript enums — compiled to objects with side effects, can't be tree-shaken
+enum Direction { North, South, East, West }
+```
+**After:**
+```typescript
+// Const object + type — tree-shakeable, maps cleanly to JS
+const Direction = { North: 'North', South: 'South', East: 'East', West: 'West' } as const;
+type Direction = typeof Direction[keyof typeof Direction];
+```
+
+---
+
+## Item 62: Don't Consider Migration Complete Until You Enable `noImplicitAny`
+
+The final step of any JS→TS migration. Without it, TypeScript silently accepts untyped code.
+
+```json
+// tsconfig.json — final migration milestone
+{
+  "compilerOptions": {
+    "strict": true,          // includes noImplicitAny and strictNullChecks
+    "noImplicitAny": true    // explicit — every value must have a type
+  }
+}
+```

package/skills/effective-typescript/scripts/review.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""
+review.py — Pre-analysis script for Effective TypeScript reviews.
+Usage: python review.py <file.ts|file.tsx>
+
+Scans a TypeScript source file for anti-patterns from the book's 62 items:
+any usage, type assertions, object wrapper types, non-null assertions,
+missing strict mode, interface-of-unions, plain string types, and more.
+"""
+
+import re
+import sys
+from pathlib import Path
+
+
+CHECKS = [
+    (
+        r":\s*any\b",
+        "Item 5/38: any type annotation",
+        "replace with a specific type, generic parameter, or unknown for truly unknown values",
+    ),
+    (
+        r"\bas\s+any\b",
+        "Item 38/40: 'as any' assertion",
+        "scope 'as any' as narrowly as possible — hide inside a well-typed wrapper function; prefer 'as unknown as T' for safer double assertion",
+    ),
+    (
+        r"\bString\b|\bNumber\b|\bBoolean\b|\bObject\b|\bSymbol\b",
+        "Item 10: Object wrapper type (String/Number/Boolean)",
+        "use primitive types: string, number, boolean — never the wrapper class types",
+    ),
+    (
+        r"!\.",
+        "Item 28/31: Non-null assertion (!).",
+        "non-null assertions are usually a symptom of an imprecise type — fix the type instead; consider optional chaining (?.) or a type guard",
+    ),
+    (
+        r"@ts-ignore|@ts-nocheck",
+        "Item 38: @ts-ignore suppresses type errors",
+        "fix the underlying type issue; if unavoidable use @ts-expect-error with a comment explaining why",
+    ),
+    (
+        r"function\s+\w+[^{]*\{[^}]{0,20}\}",
+        None,  # skip — too noisy
+        None,
+    ),
+    (
+        r"interface\s+\w+\s*\{[^}]*\?[^}]*\?[^}]*\}",
+        "Item 32: Interface with multiple optional fields",
+        "multiple optional fields that have implicit relationships suggest an interface-of-unions — convert to a tagged discriminated union",
+    ),
+    (
+        r"param(?:eter)?\s*:\s*string(?!\s*[|&])",
+        "Item 33: Plain string parameter",
+        "consider a string literal union if the parameter has a finite set of valid values (e.g. 'asc' | 'desc')",
+    ),
+    (
+        r"\.json\(\)\s*as\s+\w",
+        "Item 9/40: Direct type assertion on .json()",
+        "assign to unknown first, then narrow: 'const raw: unknown = await res.json()' — assertion inside a well-typed wrapper is acceptable (Item 40)",
+    ),
+    (
+        r"Promise<any>",
+        "Item 38: Promise<any> return type",
+        "replace with Promise<unknown> or a concrete type — Promise<any> disables type checking on the resolved value",
+    ),
+]
+
+
+def scan(source: str) -> list[dict]:
+    findings = []
+    lines = source.splitlines()
+    for lineno, line in enumerate(lines, start=1):
+        stripped = line.strip()
+        if stripped.startswith("//") or stripped.startswith("*"):
+            continue
+        for pattern, label, advice in CHECKS:
+            if label is None:
+                continue
+            if re.search(pattern, line):
+                findings.append({
+                    "line": lineno,
+                    "text": line.rstrip(),
+                    "label": label,
+                    "advice": advice,
+                })
+    return findings
+
+
+def check_strict(source: str) -> bool:
+    """Returns True if this looks like a tsconfig with strict mode enabled."""
+    return bool(re.search(r'"strict"\s*:\s*true', source))
+
+
+def sep(char="-", width=70) -> str:
+    return char * width
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python review.py <file.ts|file.tsx>")
+        sys.exit(1)
+
+    path = Path(sys.argv[1])
+    if not path.exists():
+        print(f"Error: file not found: {path}")
+        sys.exit(1)
+
+    if path.suffix.lower() not in (".ts", ".tsx", ".json"):
+        print(f"Warning: expected .ts/.tsx, got '{path.suffix}' — continuing anyway")
+
+    source = path.read_text(encoding="utf-8", errors="replace")
+
+    # Special case: tsconfig.json
+    if path.name == "tsconfig.json":
+        print(sep("="))
+        print("EFFECTIVE TYPESCRIPT — TSCONFIG CHECK")
+        print(sep("="))
+        if check_strict(source):
+            print("  [OK] strict: true is enabled (Item 2)")
+        else:
+            print("  [!] strict: true is NOT enabled — Item 2: always enable strict mode")
+            print("       Add: \"strict\": true to compilerOptions")
+        print()
+        print(sep("="))
+        return
+
+    findings = scan(source)
+    groups: dict[str, list] = {}
+    for f in findings:
+        groups.setdefault(f["label"], []).append(f)
+
+    print(sep("="))
+    print("EFFECTIVE TYPESCRIPT — PRE-REVIEW REPORT")
+    print(sep("="))
+    print(f"File   : {path}")
+    print(f"Lines  : {len(source.splitlines())}")
+    print(f"Issues : {len(findings)} potential violations across {len(groups)} categories")
+    print()
+
+    if not findings:
+        print("  [OK] No common Effective TypeScript anti-patterns detected.")
+        print()
+    else:
+        for label, items in groups.items():
+            print(sep())
+            print(f"  {label}  ({len(items)} occurrence{'s' if len(items) != 1 else ''})")
+            print(sep())
+            print(f"  Advice: {items[0]['advice']}")
+            print()
+            for item in items[:5]:
+                print(f"  line {item['line']:>4}:  {item['text'][:100]}")
+            if len(items) > 5:
+                print(f"  ... and {len(items) - 5} more")
+            print()
+
+    severity = (
+        "HIGH" if len(findings) >= 5
+        else "MEDIUM" if len(findings) >= 2
+        else "LOW" if findings
+        else "NONE"
+    )
+    print(sep("="))
+    print(f"SEVERITY: {severity}  |  Key items: Item 2 (strict), Item 5/38 (any/unknown), Item 9 (assertions), Item 28/32 (tagged unions), Item 33 (literal types)")
+    print(sep("="))
+
+
+if __name__ == "__main__":
+    main()