@bastani/atomic 0.6.8 → 0.7.0-1

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

@@ -1,383 +0,0 @@
-# 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/.agents/skills/typescript-expert/references/utility-types.ts

@@ -1,335 +0,0 @@
-/**
- * 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
-}