@cubis/foundry 0.3.10

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/typescript-pro/references/type-guards.md

@@ -0,0 +1,355 @@
+# Type Guards and Narrowing
+
+> Reference for: TypeScript Pro
+> Load when: Type narrowing, discriminated unions, assertion functions
+
+## 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 |

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/windsurf/skills/typescript-pro/references/utility-types.md

@@ -0,0 +1,332 @@
+# Utility Types
+
+> Reference for: TypeScript Pro
+> Load when: Partial, Pick, Omit, Record, custom utilities
+
+## Built-in Utility Types
+
+```typescript
+// Partial - All properties optional
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+type PartialUser = Partial<User>;
+// { id?: number; name?: string; email?: string; }
+
+function updateUser(id: number, updates: Partial<User>) {
+  // Only pass fields to update
+}
+
+// Required - All properties required
+type RequiredUser = Required<PartialUser>;
+// { id: number; name: string; email: string; }
+
+// Readonly - All properties readonly
+type ReadonlyUser = Readonly<User>;
+// { readonly id: number; readonly name: string; readonly email: string; }
+
+// Pick - Select specific properties
+type UserSummary = Pick<User, 'id' | 'name'>;
+// { id: number; name: string; }
+
+// Omit - Exclude specific properties
+type UserWithoutEmail = Omit<User, 'email'>;
+// { id: number; name: string; }
+
+// Record - Create object type with specific keys
+type UserRoles = Record<string, 'admin' | 'user' | 'guest'>;
+// { [key: string]: 'admin' | 'user' | 'guest' }
+
+type PageInfo = Record<'home' | 'about' | 'contact', { title: string }>;
+// { home: { title: string }, about: { title: string }, contact: { title: string } }
+```
+
+## Type Extraction Utilities
+
+```typescript
+// Extract - Extract types from union
+type AllTypes = 'a' | 'b' | 'c' | 1 | 2 | 3;
+type StringTypes = Extract<AllTypes, string>; // 'a' | 'b' | 'c'
+type NumberTypes = Extract<AllTypes, number>; // 1 | 2 | 3
+
+// Exclude - Remove types from union
+type WithoutNumbers = Exclude<AllTypes, number>; // 'a' | 'b' | 'c'
+
+// NonNullable - Remove null and undefined
+type MaybeString = string | null | undefined;
+type DefiniteString = NonNullable<MaybeString>; // string
+
+// ReturnType - Extract function return type
+function getUser() {
+  return { id: 1, name: 'John' };
+}
+
+type User = ReturnType<typeof getUser>; // { id: number; name: string }
+
+// Parameters - Extract function parameter types
+function createUser(name: string, age: number) {
+  return { name, age };
+}
+
+type CreateUserParams = Parameters<typeof createUser>; // [string, number]
+
+// ConstructorParameters - Extract constructor parameters
+class Point {
+  constructor(public x: number, public y: number) {}
+}
+
+type PointParams = ConstructorParameters<typeof Point>; // [number, number]
+
+// InstanceType - Extract instance type from constructor
+type PointInstance = InstanceType<typeof Point>; // Point
+```
+
+## Custom Utility Types
+
+```typescript
+// DeepPartial - Recursive partial
+type DeepPartial<T> = T extends object ? {
+  [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+
+interface Config {
+  database: {
+    host: string;
+    port: number;
+    credentials: {
+      username: string;
+      password: string;
+    };
+  };
+}
+
+type PartialConfig = DeepPartial<Config>;
+// All nested properties are optional
+
+// DeepReadonly - Recursive readonly
+type DeepReadonly<T> = T extends object ? {
+  readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+
+// Mutable - Remove readonly
+type Mutable<T> = {
+  -readonly [K in keyof T]: T[K];
+};
+
+type MutableUser = Mutable<ReadonlyUser>;
+
+// PickByType - Pick properties by value type
+type PickByType<T, U> = {
+  [K in keyof T as T[K] extends U ? K : never]: T[K];
+};
+
+interface Mixed {
+  id: number;
+  name: string;
+  age: number;
+  email: string;
+}
+
+type StringProps = PickByType<Mixed, string>; // { name: string; email: string }
+type NumberProps = PickByType<Mixed, number>; // { id: number; age: number }
+
+// OmitByType - Omit properties by value type
+type OmitByType<T, U> = {
+  [K in keyof T as T[K] extends U ? never : K]: T[K];
+};
+
+type NoStrings = OmitByType<Mixed, string>; // { id: number; age: number }
+```
+
+## Function Utilities
+
+```typescript
+// Promisify - Convert sync to async
+type Promisify<T extends (...args: any[]) => any> = (
+  ...args: Parameters<T>
+) => Promise<ReturnType<T>>;
+
+function syncFunction(x: number): string {
+  return x.toString();
+}
+
+type AsyncVersion = Promisify<typeof syncFunction>;
+// (x: number) => Promise<string>
+
+// Awaited - Unwrap promise type
+type AwaitedString = Awaited<Promise<string>>; // string
+type DeepAwaited = Awaited<Promise<Promise<number>>>; // number
+
+// ThisParameterType - Extract this parameter
+function greet(this: User, message: string) {
+  return `${this.name}: ${message}`;
+}
+
+type ThisType = ThisParameterType<typeof greet>; // User
+
+// OmitThisParameter - Remove this parameter
+type GreetFunction = OmitThisParameter<typeof greet>;
+// (message: string) => string
+```
+
+## Advanced Custom Utilities
+
+```typescript
+// Nullable - Add null and undefined
+type Nullable<T> = T | null | undefined;
+
+// ValueOf - Get union of all property values
+type ValueOf<T> = T[keyof T];
+
+interface Codes {
+  success: 200;
+  notFound: 404;
+  error: 500;
+}
+
+type StatusCode = ValueOf<Codes>; // 200 | 404 | 500
+
+// RequireAtLeastOne - Require at least one property
+type RequireAtLeastOne<T, Keys extends keyof T = keyof T> =
+  Pick<T, Exclude<keyof T, Keys>> &
+  {
+    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+  }[Keys];
+
+interface Options {
+  id?: number;
+  name?: string;
+  email?: string;
+}
+
+type AtLeastOne = RequireAtLeastOne<Options>;
+// Must have at least one of id, name, or email
+
+// RequireOnlyOne - Require exactly one property
+type RequireOnlyOne<T, Keys extends keyof T = keyof T> =
+  Pick<T, Exclude<keyof T, Keys>> &
+  {
+    [K in Keys]-?:
+      Required<Pick<T, K>> &
+      Partial<Record<Exclude<Keys, K>, undefined>>;
+  }[Keys];
+
+type OnlyOne = RequireOnlyOne<Options>;
+// Must have exactly one of id, name, or email
+
+// Merge - Deep merge two types
+type Merge<T, U> = Omit<T, keyof U> & U;
+
+interface Base {
+  id: number;
+  name: string;
+}
+
+interface Extension {
+  name: string; // Override
+  email: string; // Add
+}
+
+type Combined = Merge<Base, Extension>;
+// { id: number; name: string; email: string }
+
+// ConditionalKeys - Get keys matching condition
+type ConditionalKeys<T, Condition> = {
+  [K in keyof T]: T[K] extends Condition ? K : never;
+}[keyof T];
+
+type FunctionKeys = ConditionalKeys<typeof Math, Function>;
+// 'abs' | 'acos' | 'sin' | ...
+```
+
+## Tuple Utilities
+
+```typescript
+// First - Get first element type
+type First<T extends any[]> = T extends [infer F, ...any[]] ? F : never;
+
+type FirstType = First<[string, number, boolean]>; // string
+
+// Last - Get last element type
+type Last<T extends any[]> = T extends [...any[], infer L] ? L : never;
+
+type LastType = Last<[string, number, boolean]>; // boolean
+
+// Tail - Remove first element
+type Tail<T extends any[]> = T extends [any, ...infer Rest] ? Rest : never;
+
+type TailTypes = Tail<[string, number, boolean]>; // [number, boolean]
+
+// Prepend - Add element to beginning
+type Prepend<T extends any[], U> = [U, ...T];
+
+type WithString = Prepend<[number, boolean], string>; // [string, number, boolean]
+
+// Reverse - Reverse tuple
+type Reverse<T extends any[]> =
+  T extends [infer First, ...infer Rest]
+    ? [...Reverse<Rest>, First]
+    : [];
+
+type Reversed = Reverse<[1, 2, 3]>; // [3, 2, 1]
+```
+
+## String Utilities
+
+```typescript
+// Split - Split string into tuple
+type Split<S extends string, D extends string> =
+  S extends `${infer T}${D}${infer U}`
+    ? [T, ...Split<U, D>]
+    : [S];
+
+type Parts = Split<'a-b-c', '-'>; // ['a', 'b', 'c']
+
+// Join - Join tuple into string
+type Join<T extends string[], D extends string> =
+  T extends [infer F extends string, ...infer R extends string[]]
+    ? R extends []
+      ? F
+      : `${F}${D}${Join<R, D>}`
+    : '';
+
+type Joined = Join<['a', 'b', 'c'], '-'>; // 'a-b-c'
+
+// Replace - Replace substring
+type Replace<
+  S extends string,
+  From extends string,
+  To extends string
+> = S extends `${infer L}${From}${infer R}`
+  ? `${L}${To}${R}`
+  : S;
+
+type Replaced = Replace<'hello world', 'world', 'TypeScript'>;
+// 'hello TypeScript'
+
+// TrimLeft - Remove leading whitespace
+type TrimLeft<S extends string> =
+  S extends ` ${infer Rest}` ? TrimLeft<Rest> : S;
+
+type Trimmed = TrimLeft<'  hello'>; // 'hello'
+```
+
+## Quick Reference
+
+| Utility | Purpose |
+|---------|---------|
+| `Partial<T>` | Make all properties optional |
+| `Required<T>` | Make all properties required |
+| `Readonly<T>` | Make all properties readonly |
+| `Pick<T, K>` | Select subset of properties |
+| `Omit<T, K>` | Remove subset of properties |
+| `Record<K, T>` | Create object type with keys K |
+| `Extract<T, U>` | Extract types assignable to U |
+| `Exclude<T, U>` | Remove types assignable to U |
+| `NonNullable<T>` | Remove null and undefined |
+| `ReturnType<T>` | Extract function return type |
+| `Parameters<T>` | Extract function parameters |
+| `Awaited<T>` | Unwrap Promise type |