agcel 1.0.1

package/skills/typescript-expert/references/typescript-cheatsheet.md

@@ -0,0 +1,383 @@
+# TypeScript Cheatsheet
+
+## Type Basics
+
+```typescript
+// Primitives
+const name: string = 'John'
+const age: number = 30
+const isActive: boolean = true
+const nothing: null = null
+const notDefined: undefined = undefined
+
+// Arrays
+const numbers: number[] = [1, 2, 3]
+const strings: Array<string> = ['a', 'b', 'c']
+
+// Tuple
+const tuple: [string, number] = ['hello', 42]
+
+// Object
+const user: { name: string; age: number } = { name: 'John', age: 30 }
+
+// Union
+const value: string | number = 'hello'
+
+// Literal
+const direction: 'up' | 'down' | 'left' | 'right' = 'up'
+
+// Any vs Unknown
+const anyValue: any = 'anything'     // ❌ Avoid
+const unknownValue: unknown = 'safe' // ✅ Prefer, requires narrowing
+```
+
+## Type Aliases & Interfaces
+
+```typescript
+// Type Alias
+type Point = {
+  x: number
+  y: number
+}
+
+// Interface (preferred for objects)
+interface User {
+  id: string
+  name: string
+  email?: string  // Optional
+  readonly createdAt: Date  // Readonly
+}
+
+// Extending
+interface Admin extends User {
+  permissions: string[]
+}
+
+// Intersection
+type AdminUser = User & { permissions: string[] }
+```
+
+## Generics
+
+```typescript
+// Generic function
+function identity<T>(value: T): T {
+  return value
+}
+
+// Generic with constraint
+function getLength<T extends { length: number }>(item: T): number {
+  return item.length
+}
+
+// Generic interface
+interface ApiResponse<T> {
+  data: T
+  status: number
+  message: string
+}
+
+// Generic with default
+type Container<T = string> = {
+  value: T
+}
+
+// Multiple generics
+function merge<T, U>(obj1: T, obj2: U): T & U {
+  return { ...obj1, ...obj2 }
+}
+```
+
+## Utility Types
+
+```typescript
+interface User {
+  id: string
+  name: string
+  email: string
+  age: number
+}
+
+// Partial - all optional
+type PartialUser = Partial<User>
+
+// Required - all required
+type RequiredUser = Required<User>
+
+// Readonly - all readonly
+type ReadonlyUser = Readonly<User>
+
+// Pick - select properties
+type UserName = Pick<User, 'id' | 'name'>
+
+// Omit - exclude properties
+type UserWithoutEmail = Omit<User, 'email'>
+
+// Record - key-value map
+type UserMap = Record<string, User>
+
+// Extract - extract from union
+type StringOrNumber = string | number | boolean
+type OnlyStrings = Extract<StringOrNumber, string>
+
+// Exclude - exclude from union
+type NotString = Exclude<StringOrNumber, string>
+
+// NonNullable - remove null/undefined
+type MaybeString = string | null | undefined
+type DefinitelyString = NonNullable<MaybeString>
+
+// ReturnType - get function return type
+function getUser() { return { name: 'John' } }
+type UserReturn = ReturnType<typeof getUser>
+
+// Parameters - get function parameters
+type GetUserParams = Parameters<typeof getUser>
+
+// Awaited - unwrap Promise
+type ResolvedUser = Awaited<Promise<User>>
+```
+
+## Conditional Types
+
+```typescript
+// Basic conditional
+type IsString<T> = T extends string ? true : false
+
+// Infer keyword
+type UnwrapPromise<T> = T extends Promise<infer U> ? U : T
+
+// Distributive conditional
+type ToArray<T> = T extends any ? T[] : never
+type Result = ToArray<string | number>  // string[] | number[]
+
+// NonDistributive
+type ToArrayNonDist<T> = [T] extends [any] ? T[] : never
+```
+
+## Template Literal Types
+
+```typescript
+type Color = 'red' | 'green' | 'blue'
+type Size = 'small' | 'medium' | 'large'
+
+// Combine
+type ColorSize = `${Color}-${Size}`
+// 'red-small' | 'red-medium' | 'red-large' | ...
+
+// Event handlers
+type EventName = 'click' | 'focus' | 'blur'
+type EventHandler = `on${Capitalize<EventName>}`
+// 'onClick' | 'onFocus' | 'onBlur'
+```
+
+## Mapped Types
+
+```typescript
+// Basic mapped type
+type Optional<T> = {
+  [K in keyof T]?: T[K]
+}
+
+// With key remapping
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K]
+}
+
+// Filter keys
+type OnlyStrings<T> = {
+  [K in keyof T as T[K] extends string ? K : never]: T[K]
+}
+```
+
+## Type Guards
+
+```typescript
+// typeof guard
+function process(value: string | number) {
+  if (typeof value === 'string') {
+    return value.toUpperCase()  // string
+  }
+  return value.toFixed(2)  // number
+}
+
+// instanceof guard
+class Dog { bark() {} }
+class Cat { meow() {} }
+
+function makeSound(animal: Dog | Cat) {
+  if (animal instanceof Dog) {
+    animal.bark()
+  } else {
+    animal.meow()
+  }
+}
+
+// in guard
+interface Bird { fly(): void }
+interface Fish { swim(): void }
+
+function move(animal: Bird | Fish) {
+  if ('fly' in animal) {
+    animal.fly()
+  } else {
+    animal.swim()
+  }
+}
+
+// Custom type guard
+function isString(value: unknown): value is string {
+  return typeof value === 'string'
+}
+
+// Assertion function
+function assertIsString(value: unknown): asserts value is string {
+  if (typeof value !== 'string') {
+    throw new Error('Not a string')
+  }
+}
+```
+
+## Discriminated Unions
+
+```typescript
+// With type discriminant
+type Success<T> = { type: 'success'; data: T }
+type Error = { type: 'error'; message: string }
+type Loading = { type: 'loading' }
+
+type State<T> = Success<T> | Error | Loading
+
+function handle<T>(state: State<T>) {
+  switch (state.type) {
+    case 'success':
+      return state.data  // T
+    case 'error':
+      return state.message  // string
+    case 'loading':
+      return null
+  }
+}
+
+// Exhaustive check
+function assertNever(value: never): never {
+  throw new Error(`Unexpected value: ${value}`)
+}
+```
+
+## Branded Types
+
+```typescript
+// Create branded type
+type Brand<K, T> = K & { __brand: T }
+
+type UserId = Brand<string, 'UserId'>
+type OrderId = Brand<string, 'OrderId'>
+
+// Constructor functions
+function createUserId(id: string): UserId {
+  return id as UserId
+}
+
+function createOrderId(id: string): OrderId {
+  return id as OrderId
+}
+
+// Usage - prevents mixing
+function getOrder(orderId: OrderId, userId: UserId) {}
+
+const userId = createUserId('user-123')
+const orderId = createOrderId('order-456')
+
+getOrder(orderId, userId)  // ✅ OK
+// getOrder(userId, orderId)  // ❌ Error - types don't match
+```
+
+## Module Declarations
+
+```typescript
+// Declare module for untyped package
+declare module 'untyped-package' {
+  export function doSomething(): void
+  export const value: string
+}
+
+// Augment existing module
+declare module 'express' {
+  interface Request {
+    user?: { id: string }
+  }
+}
+
+// Declare global
+declare global {
+  interface Window {
+    myGlobal: string
+  }
+}
+```
+
+## TSConfig Essentials
+
+```json
+{
+  "compilerOptions": {
+    // Strictness
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    
+    // Modules
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    
+    // Output
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    
+    // Performance
+    "skipLibCheck": true,
+    "incremental": true,
+    
+    // Paths
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+## Best Practices
+
+```typescript
+// ✅ Prefer interface for objects
+interface User {
+  name: string
+}
+
+// ✅ Use const assertions
+const routes = ['home', 'about'] as const
+
+// ✅ Use satisfies for validation
+const config = {
+  api: 'https://api.example.com'
+} satisfies Record<string, string>
+
+// ✅ Use unknown over any
+function parse(input: unknown) {
+  if (typeof input === 'string') {
+    return JSON.parse(input)
+  }
+}
+
+// ✅ Explicit return types for public APIs
+export function getUser(id: string): User | null {
+  // ...
+}
+
+// ❌ Avoid
+const data: any = fetchData()
+data.anything.goes.wrong  // No type safety
+```

package/skills/typescript-expert/references/utility-types.ts

@@ -0,0 +1,335 @@
+/**
+ * TypeScript Utility Types Library
+ * 
+ * A collection of commonly used utility types for TypeScript projects.
+ * Copy and use as needed in your projects.
+ */
+
+// =============================================================================
+// BRANDED TYPES
+// =============================================================================
+
+/**
+ * Create nominal/branded types to prevent primitive obsession.
+ * 
+ * @example
+ * type UserId = Brand<string, 'UserId'>
+ * type OrderId = Brand<string, 'OrderId'>
+ */
+export type Brand<K, T> = K & { readonly __brand: T }
+
+// Branded type constructors
+export type UserId = Brand<string, 'UserId'>
+export type Email = Brand<string, 'Email'>
+export type UUID = Brand<string, 'UUID'>
+export type Timestamp = Brand<number, 'Timestamp'>
+export type PositiveNumber = Brand<number, 'PositiveNumber'>
+
+// =============================================================================
+// RESULT TYPE (Error Handling)
+// =============================================================================
+
+/**
+ * Type-safe error handling without exceptions.
+ */
+export type Result<T, E = Error> =
+    | { success: true; data: T }
+    | { success: false; error: E }
+
+export const ok = <T>(data: T): Result<T, never> => ({
+    success: true,
+    data
+})
+
+export const err = <E>(error: E): Result<never, E> => ({
+    success: false,
+    error
+})
+
+// =============================================================================
+// OPTION TYPE (Nullable Handling)  
+// =============================================================================
+
+/**
+ * Explicit optional value handling.
+ */
+export type Option<T> = Some<T> | None
+
+export type Some<T> = { type: 'some'; value: T }
+export type None = { type: 'none' }
+
+export const some = <T>(value: T): Some<T> => ({ type: 'some', value })
+export const none: None = { type: 'none' }
+
+// =============================================================================
+// DEEP UTILITIES
+// =============================================================================
+
+/**
+ * Make all properties deeply readonly.
+ */
+export type DeepReadonly<T> = T extends (...args: any[]) => any
+    ? T
+    : T extends object
+    ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
+    : T
+
+/**
+ * Make all properties deeply optional.
+ */
+export type DeepPartial<T> = T extends object
+    ? { [K in keyof T]?: DeepPartial<T[K]> }
+    : T
+
+/**
+ * Make all properties deeply required.
+ */
+export type DeepRequired<T> = T extends object
+    ? { [K in keyof T]-?: DeepRequired<T[K]> }
+    : T
+
+/**
+ * Make all properties deeply mutable (remove readonly).
+ */
+export type DeepMutable<T> = T extends object
+    ? { -readonly [K in keyof T]: DeepMutable<T[K]> }
+    : T
+
+// =============================================================================
+// OBJECT UTILITIES
+// =============================================================================
+
+/**
+ * Get keys of object where value matches type.
+ */
+export type KeysOfType<T, V> = {
+    [K in keyof T]: T[K] extends V ? K : never
+}[keyof T]
+
+/**
+ * Pick properties by value type.
+ */
+export type PickByType<T, V> = Pick<T, KeysOfType<T, V>>
+
+/**
+ * Omit properties by value type.
+ */
+export type OmitByType<T, V> = Omit<T, KeysOfType<T, V>>
+
+/**
+ * Make specific keys optional.
+ */
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
+
+/**
+ * Make specific keys required.
+ */
+export type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>
+
+/**
+ * Make specific keys readonly.
+ */
+export type ReadonlyBy<T, K extends keyof T> = Omit<T, K> & Readonly<Pick<T, K>>
+
+/**
+ * Merge two types (second overrides first).
+ */
+export type Merge<T, U> = Omit<T, keyof U> & U
+
+// =============================================================================
+// ARRAY UTILITIES
+// =============================================================================
+
+/**
+ * Get element type from array.
+ */
+export type ElementOf<T> = T extends (infer E)[] ? E : never
+
+/**
+ * Tuple of specific length.
+ */
+export type Tuple<T, N extends number> = N extends N
+    ? number extends N
+    ? T[]
+    : _TupleOf<T, N, []>
+    : never
+
+type _TupleOf<T, N extends number, R extends unknown[]> = R['length'] extends N
+    ? R
+    : _TupleOf<T, N, [T, ...R]>
+
+/**
+ * Non-empty array.
+ */
+export type NonEmptyArray<T> = [T, ...T[]]
+
+/**
+ * At least N elements.
+ */
+export type AtLeast<T, N extends number> = [...Tuple<T, N>, ...T[]]
+
+// =============================================================================
+// FUNCTION UTILITIES
+// =============================================================================
+
+/**
+ * Get function arguments as tuple.
+ */
+export type Arguments<T> = T extends (...args: infer A) => any ? A : never
+
+/**
+ * Get first argument of function.
+ */
+export type FirstArgument<T> = T extends (first: infer F, ...args: any[]) => any
+    ? F
+    : never
+
+/**
+ * Async version of function.
+ */
+export type AsyncFunction<T extends (...args: any[]) => any> = (
+    ...args: Parameters<T>
+) => Promise<Awaited<ReturnType<T>>>
+
+/**
+ * Promisify return type.
+ */
+export type Promisify<T> = T extends (...args: infer A) => infer R
+    ? (...args: A) => Promise<Awaited<R>>
+    : never
+
+// =============================================================================
+// STRING UTILITIES
+// =============================================================================
+
+/**
+ * Split string by delimiter.
+ */
+export type Split<S extends string, D extends string> =
+    S extends `${infer T}${D}${infer U}`
+    ? [T, ...Split<U, D>]
+    : [S]
+
+/**
+ * Join tuple to string.
+ */
+export type Join<T extends string[], D extends string> =
+    T extends []
+    ? ''
+    : T extends [infer F extends string]
+    ? F
+    : T extends [infer F extends string, ...infer R extends string[]]
+    ? `${F}${D}${Join<R, D>}`
+    : never
+
+/**
+ * Path to nested object.
+ */
+export type PathOf<T, K extends keyof T = keyof T> = K extends string
+    ? T[K] extends object
+    ? K | `${K}.${PathOf<T[K]>}`
+    : K
+    : never
+
+// =============================================================================
+// UNION UTILITIES
+// =============================================================================
+
+/**
+ * Last element of union.
+ */
+export type UnionLast<T> = UnionToIntersection<
+    T extends any ? () => T : never
+> extends () => infer R
+    ? R
+    : never
+
+/**
+ * Union to intersection.
+ */
+export type UnionToIntersection<U> = (
+    U extends any ? (k: U) => void : never
+) extends (k: infer I) => void
+    ? I
+    : never
+
+/**
+ * Union to tuple.
+ */
+export type UnionToTuple<T, L = UnionLast<T>> = [T] extends [never]
+    ? []
+    : [...UnionToTuple<Exclude<T, L>>, L]
+
+// =============================================================================
+// VALIDATION UTILITIES
+// =============================================================================
+
+/**
+ * Assert type at compile time.
+ */
+export type AssertEqual<T, U> =
+    (<V>() => V extends T ? 1 : 2) extends (<V>() => V extends U ? 1 : 2)
+    ? true
+    : false
+
+/**
+ * Ensure type is not never.
+ */
+export type IsNever<T> = [T] extends [never] ? true : false
+
+/**
+ * Ensure type is any.
+ */
+export type IsAny<T> = 0 extends 1 & T ? true : false
+
+/**
+ * Ensure type is unknown.
+ */
+export type IsUnknown<T> = IsAny<T> extends true
+    ? false
+    : unknown extends T
+    ? true
+    : false
+
+// =============================================================================
+// JSON UTILITIES
+// =============================================================================
+
+/**
+ * JSON-safe types.
+ */
+export type JsonPrimitive = string | number | boolean | null
+export type JsonArray = JsonValue[]
+export type JsonObject = { [key: string]: JsonValue }
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject
+
+/**
+ * Make type JSON-serializable.
+ */
+export type Jsonify<T> = T extends JsonPrimitive
+    ? T
+    : T extends undefined | ((...args: any[]) => any) | symbol
+    ? never
+    : T extends { toJSON(): infer R }
+    ? R
+    : T extends object
+    ? { [K in keyof T]: Jsonify<T[K]> }
+    : never
+
+// =============================================================================
+// EXHAUSTIVE CHECK
+// =============================================================================
+
+/**
+ * Ensure all cases are handled in switch/if.
+ */
+export function assertNever(value: never, message?: string): never {
+    throw new Error(message ?? `Unexpected value: ${value}`)
+}
+
+/**
+ * Exhaustive check without throwing.
+ */
+export function exhaustiveCheck(_value: never): void {
+    // This function should never be called
+}