aigroup-workflow 2.2.0 → 2.2.2

package/skills/javascript/typescript-pro/references/type-guards.md

@@ -1,352 +1,352 @@
-# Type Guards and Narrowing
-
-## Type Predicates
-
-```typescript
-// Basic type predicate
-function isString(value: unknown): value is string {
-  return typeof value === 'string';
-}
-
-function processValue(value: string | number) {
-  if (isString(value)) {
-    console.log(value.toUpperCase()); // value is string
-  } else {
-    console.log(value.toFixed(2)); // value is number
-  }
-}
-
-// Generic type predicate
-function isArray<T>(value: T | T[]): value is T[] {
-  return Array.isArray(value);
-}
-
-// Narrowing to specific interface
-interface User {
-  type: 'user';
-  name: string;
-  email: string;
-}
-
-interface Admin {
-  type: 'admin';
-  name: string;
-  permissions: string[];
-}
-
-function isAdmin(account: User | Admin): account is Admin {
-  return account.type === 'admin';
-}
-```
-
-## Discriminated Unions
-
-```typescript
-// Tagged union pattern
-type Result<T, E = Error> =
-  | { status: 'success'; data: T }
-  | { status: 'error'; error: E }
-  | { status: 'loading' };
-
-function handleResult<T>(result: Result<T>) {
-  switch (result.status) {
-    case 'success':
-      console.log(result.data); // Narrowed to success
-      break;
-    case 'error':
-      console.error(result.error); // Narrowed to error
-      break;
-    case 'loading':
-      console.log('Loading...'); // Narrowed to loading
-      break;
-  }
-}
-
-// Complex discriminated union
-type Shape =
-  | { kind: 'circle'; radius: number }
-  | { kind: 'rectangle'; width: number; height: number }
-  | { kind: 'triangle'; base: number; height: number };
-
-function getArea(shape: Shape): number {
-  switch (shape.kind) {
-    case 'circle':
-      return Math.PI * shape.radius ** 2;
-    case 'rectangle':
-      return shape.width * shape.height;
-    case 'triangle':
-      return (shape.base * shape.height) / 2;
-  }
-}
-
-// Exhaustive checking
-function assertNever(x: never): never {
-  throw new Error('Unexpected value: ' + x);
-}
-
-function processShape(shape: Shape): number {
-  switch (shape.kind) {
-    case 'circle':
-      return shape.radius;
-    case 'rectangle':
-      return shape.width;
-    case 'triangle':
-      return shape.base;
-    default:
-      return assertNever(shape); // Compile error if not exhaustive
-  }
-}
-```
-
-## Built-in Type Guards
-
-```typescript
-// typeof narrowing
-function printValue(value: string | number | boolean) {
-  if (typeof value === 'string') {
-    console.log(value.toUpperCase());
-  } else if (typeof value === 'number') {
-    console.log(value.toFixed(2));
-  } else {
-    console.log(value ? 'yes' : 'no');
-  }
-}
-
-// instanceof narrowing
-class Dog {
-  bark() { console.log('woof'); }
-}
-
-class Cat {
-  meow() { console.log('meow'); }
-}
-
-function makeSound(animal: Dog | Cat) {
-  if (animal instanceof Dog) {
-    animal.bark();
-  } else {
-    animal.meow();
-  }
-}
-
-// in operator narrowing
-type Fish = { swim: () => void };
-type Bird = { fly: () => void };
-
-function move(animal: Fish | Bird) {
-  if ('swim' in animal) {
-    animal.swim();
-  } else {
-    animal.fly();
-  }
-}
-
-// Truthiness narrowing
-function printLength(value: string | null | undefined) {
-  if (value) {
-    console.log(value.length); // Narrowed to string
-  }
-}
-
-// Equality narrowing
-function compare(x: string | number, y: string | boolean) {
-  if (x === y) {
-    // x and y are both string
-    console.log(x.toUpperCase(), y.toUpperCase());
-  }
-}
-```
-
-## Assertion Functions
-
-```typescript
-// Basic assertion function
-function assert(condition: unknown, message?: string): asserts condition {
-  if (!condition) {
-    throw new Error(message || 'Assertion failed');
-  }
-}
-
-function processUser(user: unknown) {
-  assert(typeof user === 'object' && user !== null);
-  assert('name' in user && typeof user.name === 'string');
-  console.log(user.name.toUpperCase()); // user is narrowed
-}
-
-// Type assertion function
-function assertIsString(value: unknown): asserts value is string {
-  if (typeof value !== 'string') {
-    throw new Error('Value is not a string');
-  }
-}
-
-function greet(name: unknown) {
-  assertIsString(name);
-  console.log(`Hello, ${name.toUpperCase()}`); // name is string
-}
-
-// Generic assertion function
-function assertIsDefined<T>(value: T): asserts value is NonNullable<T> {
-  if (value === null || value === undefined) {
-    throw new Error('Value is null or undefined');
-  }
-}
-
-function processValue(value: string | null) {
-  assertIsDefined(value);
-  console.log(value.length); // value is string
-}
-
-// Assert with type predicate
-function assertIsUser(value: unknown): asserts value is User {
-  if (
-    typeof value !== 'object' ||
-    value === null ||
-    !('type' in value) ||
-    value.type !== 'user'
-  ) {
-    throw new Error('Not a user');
-  }
-}
-```
-
-## Control Flow Analysis
-
-```typescript
-// Assignment narrowing
-let x: string | number = Math.random() > 0.5 ? 'hello' : 42;
-
-if (typeof x === 'string') {
-  x; // string
-} else {
-  x; // number
-}
-
-// Return statement narrowing
-function getValue(flag: boolean): string | number {
-  if (flag) {
-    return 'hello';
-  }
-  return 42; // TypeScript knows this must be number
-}
-
-// Throw statement narrowing
-function processValue(value: string | null) {
-  if (!value) {
-    throw new Error('Value is required');
-  }
-  console.log(value.length); // value is string (null thrown above)
-}
-
-// Type guards in array methods
-const mixed: (string | number)[] = ['a', 1, 'b', 2];
-const strings = mixed.filter((x): x is string => typeof x === 'string');
-// strings is string[]
-```
-
-## Branded Types
-
-```typescript
-// Nominal typing with branded types
-type Brand<K, T> = K & { __brand: T };
-
-type UserId = Brand<string, 'UserId'>;
-type Email = Brand<string, 'Email'>;
-type Url = Brand<string, 'Url'>;
-
-// Constructor functions
-function createUserId(id: string): UserId {
-  return id as UserId;
-}
-
-function createEmail(email: string): Email {
-  if (!email.includes('@')) {
-    throw new Error('Invalid email');
-  }
-  return email as Email;
-}
-
-// Usage prevents mixing
-const userId: UserId = createUserId('user-123');
-const email: Email = createEmail('user@example.com');
-
-// const wrongAssignment: UserId = email; // Error!
-
-// Type guard for branded types
-function isUserId(value: string): value is UserId {
-  return /^user-\d+$/.test(value);
-}
-
-// Branded numbers
-type Positive = Brand<number, 'Positive'>;
-type Integer = Brand<number, 'Integer'>;
-
-function createPositive(n: number): Positive {
-  if (n <= 0) throw new Error('Must be positive');
-  return n as Positive;
-}
-
-function createInteger(n: number): Integer {
-  if (!Number.isInteger(n)) throw new Error('Must be integer');
-  return n as Integer;
-}
-```
-
-## Advanced Narrowing Patterns
-
-```typescript
-// Array.isArray with generics
-function processInput<T>(input: T | T[]): T[] {
-  return Array.isArray(input) ? input : [input];
-}
-
-// Object key narrowing
-function getProperty<T extends object, K extends keyof T>(
-  obj: T,
-  key: K
-): T[K] {
-  return obj[key];
-}
-
-// Mapped type narrowing
-type Nullable<T> = { [K in keyof T]: T[K] | null };
-
-function isComplete<T extends object>(
-  obj: Nullable<T>
-): obj is T {
-  return Object.values(obj).every((v) => v !== null);
-}
-
-// Custom narrowing with type maps
-type TypeMap = {
-  string: string;
-  number: number;
-  boolean: boolean;
-};
-
-function is<K extends keyof TypeMap>(
-  type: K,
-  value: unknown
-): value is TypeMap[K] {
-  return typeof value === type;
-}
-
-if (is('string', someValue)) {
-  someValue.toUpperCase(); // someValue is string
-}
-```
-
-## Quick Reference
-
-| Pattern | Use Case |
-|---------|----------|
-| `value is Type` | Type predicate function |
-| `asserts condition` | Assertion function |
-| `asserts value is Type` | Type assertion function |
-| Discriminated union | Tagged union with literal type |
-| `typeof` guard | Primitive type checking |
-| `instanceof` guard | Class instance checking |
-| `in` operator | Property existence check |
-| `assertNever` | Exhaustive switch checking |
-| Branded types | Nominal typing simulation |
-| `NonNullable<T>` | Remove null/undefined |
+# Type Guards and Narrowing
+
+## Type Predicates
+
+```typescript
+// Basic type predicate
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+function processValue(value: string | number) {
+  if (isString(value)) {
+    console.log(value.toUpperCase()); // value is string
+  } else {
+    console.log(value.toFixed(2)); // value is number
+  }
+}
+
+// Generic type predicate
+function isArray<T>(value: T | T[]): value is T[] {
+  return Array.isArray(value);
+}
+
+// Narrowing to specific interface
+interface User {
+  type: 'user';
+  name: string;
+  email: string;
+}
+
+interface Admin {
+  type: 'admin';
+  name: string;
+  permissions: string[];
+}
+
+function isAdmin(account: User | Admin): account is Admin {
+  return account.type === 'admin';
+}
+```
+
+## Discriminated Unions
+
+```typescript
+// Tagged union pattern
+type Result<T, E = Error> =
+  | { status: 'success'; data: T }
+  | { status: 'error'; error: E }
+  | { status: 'loading' };
+
+function handleResult<T>(result: Result<T>) {
+  switch (result.status) {
+    case 'success':
+      console.log(result.data); // Narrowed to success
+      break;
+    case 'error':
+      console.error(result.error); // Narrowed to error
+      break;
+    case 'loading':
+      console.log('Loading...'); // Narrowed to loading
+      break;
+  }
+}
+
+// Complex discriminated union
+type Shape =
+  | { kind: 'circle'; radius: number }
+  | { kind: 'rectangle'; width: number; height: number }
+  | { kind: 'triangle'; base: number; height: number };
+
+function getArea(shape: Shape): number {
+  switch (shape.kind) {
+    case 'circle':
+      return Math.PI * shape.radius ** 2;
+    case 'rectangle':
+      return shape.width * shape.height;
+    case 'triangle':
+      return (shape.base * shape.height) / 2;
+  }
+}
+
+// Exhaustive checking
+function assertNever(x: never): never {
+  throw new Error('Unexpected value: ' + x);
+}
+
+function processShape(shape: Shape): number {
+  switch (shape.kind) {
+    case 'circle':
+      return shape.radius;
+    case 'rectangle':
+      return shape.width;
+    case 'triangle':
+      return shape.base;
+    default:
+      return assertNever(shape); // Compile error if not exhaustive
+  }
+}
+```
+
+## Built-in Type Guards
+
+```typescript
+// typeof narrowing
+function printValue(value: string | number | boolean) {
+  if (typeof value === 'string') {
+    console.log(value.toUpperCase());
+  } else if (typeof value === 'number') {
+    console.log(value.toFixed(2));
+  } else {
+    console.log(value ? 'yes' : 'no');
+  }
+}
+
+// instanceof narrowing
+class Dog {
+  bark() { console.log('woof'); }
+}
+
+class Cat {
+  meow() { console.log('meow'); }
+}
+
+function makeSound(animal: Dog | Cat) {
+  if (animal instanceof Dog) {
+    animal.bark();
+  } else {
+    animal.meow();
+  }
+}
+
+// in operator narrowing
+type Fish = { swim: () => void };
+type Bird = { fly: () => void };
+
+function move(animal: Fish | Bird) {
+  if ('swim' in animal) {
+    animal.swim();
+  } else {
+    animal.fly();
+  }
+}
+
+// Truthiness narrowing
+function printLength(value: string | null | undefined) {
+  if (value) {
+    console.log(value.length); // Narrowed to string
+  }
+}
+
+// Equality narrowing
+function compare(x: string | number, y: string | boolean) {
+  if (x === y) {
+    // x and y are both string
+    console.log(x.toUpperCase(), y.toUpperCase());
+  }
+}
+```
+
+## Assertion Functions
+
+```typescript
+// Basic assertion function
+function assert(condition: unknown, message?: string): asserts condition {
+  if (!condition) {
+    throw new Error(message || 'Assertion failed');
+  }
+}
+
+function processUser(user: unknown) {
+  assert(typeof user === 'object' && user !== null);
+  assert('name' in user && typeof user.name === 'string');
+  console.log(user.name.toUpperCase()); // user is narrowed
+}
+
+// Type assertion function
+function assertIsString(value: unknown): asserts value is string {
+  if (typeof value !== 'string') {
+    throw new Error('Value is not a string');
+  }
+}
+
+function greet(name: unknown) {
+  assertIsString(name);
+  console.log(`Hello, ${name.toUpperCase()}`); // name is string
+}
+
+// Generic assertion function
+function assertIsDefined<T>(value: T): asserts value is NonNullable<T> {
+  if (value === null || value === undefined) {
+    throw new Error('Value is null or undefined');
+  }
+}
+
+function processValue(value: string | null) {
+  assertIsDefined(value);
+  console.log(value.length); // value is string
+}
+
+// Assert with type predicate
+function assertIsUser(value: unknown): asserts value is User {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    !('type' in value) ||
+    value.type !== 'user'
+  ) {
+    throw new Error('Not a user');
+  }
+}
+```
+
+## Control Flow Analysis
+
+```typescript
+// Assignment narrowing
+let x: string | number = Math.random() > 0.5 ? 'hello' : 42;
+
+if (typeof x === 'string') {
+  x; // string
+} else {
+  x; // number
+}
+
+// Return statement narrowing
+function getValue(flag: boolean): string | number {
+  if (flag) {
+    return 'hello';
+  }
+  return 42; // TypeScript knows this must be number
+}
+
+// Throw statement narrowing
+function processValue(value: string | null) {
+  if (!value) {
+    throw new Error('Value is required');
+  }
+  console.log(value.length); // value is string (null thrown above)
+}
+
+// Type guards in array methods
+const mixed: (string | number)[] = ['a', 1, 'b', 2];
+const strings = mixed.filter((x): x is string => typeof x === 'string');
+// strings is string[]
+```
+
+## Branded Types
+
+```typescript
+// Nominal typing with branded types
+type Brand<K, T> = K & { __brand: T };
+
+type UserId = Brand<string, 'UserId'>;
+type Email = Brand<string, 'Email'>;
+type Url = Brand<string, 'Url'>;
+
+// Constructor functions
+function createUserId(id: string): UserId {
+  return id as UserId;
+}
+
+function createEmail(email: string): Email {
+  if (!email.includes('@')) {
+    throw new Error('Invalid email');
+  }
+  return email as Email;
+}
+
+// Usage prevents mixing
+const userId: UserId = createUserId('user-123');
+const email: Email = createEmail('user@example.com');
+
+// const wrongAssignment: UserId = email; // Error!
+
+// Type guard for branded types
+function isUserId(value: string): value is UserId {
+  return /^user-\d+$/.test(value);
+}
+
+// Branded numbers
+type Positive = Brand<number, 'Positive'>;
+type Integer = Brand<number, 'Integer'>;
+
+function createPositive(n: number): Positive {
+  if (n <= 0) throw new Error('Must be positive');
+  return n as Positive;
+}
+
+function createInteger(n: number): Integer {
+  if (!Number.isInteger(n)) throw new Error('Must be integer');
+  return n as Integer;
+}
+```
+
+## Advanced Narrowing Patterns
+
+```typescript
+// Array.isArray with generics
+function processInput<T>(input: T | T[]): T[] {
+  return Array.isArray(input) ? input : [input];
+}
+
+// Object key narrowing
+function getProperty<T extends object, K extends keyof T>(
+  obj: T,
+  key: K
+): T[K] {
+  return obj[key];
+}
+
+// Mapped type narrowing
+type Nullable<T> = { [K in keyof T]: T[K] | null };
+
+function isComplete<T extends object>(
+  obj: Nullable<T>
+): obj is T {
+  return Object.values(obj).every((v) => v !== null);
+}
+
+// Custom narrowing with type maps
+type TypeMap = {
+  string: string;
+  number: number;
+  boolean: boolean;
+};
+
+function is<K extends keyof TypeMap>(
+  type: K,
+  value: unknown
+): value is TypeMap[K] {
+  return typeof value === type;
+}
+
+if (is('string', someValue)) {
+  someValue.toUpperCase(); // someValue is string
+}
+```
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| `value is Type` | Type predicate function |
+| `asserts condition` | Assertion function |
+| `asserts value is Type` | Type assertion function |
+| Discriminated union | Tagged union with literal type |
+| `typeof` guard | Primitive type checking |
+| `instanceof` guard | Class instance checking |
+| `in` operator | Property existence check |
+| `assertNever` | Exhaustive switch checking |
+| Branded types | Nominal typing simulation |
+| `NonNullable<T>` | Remove null/undefined |