@cubis/foundry 0.3.67 → 0.3.69

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/typescript-pro/references/type-guards.md

@@ -1,355 +0,0 @@
-# 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/workflows/workflows/agent-environment-setup/platforms/cursor/skills/typescript-pro/references/utility-types.md

@@ -1,332 +0,0 @@
-# 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 |