cfsa-antigravity 1.0.0

package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: typescript-advanced-patterns
+description: Advanced TypeScript patterns for type-safe, maintainable code using sophisticated type system features. Use when building type-safe APIs, implementing complex domain models, or leveraging TypeScript's advanced type capabilities.
+---
+
+# TypeScript Advanced Patterns
+
+Expert guidance for leveraging TypeScript's advanced type system features to build robust, type-safe applications with sophisticated type inference, compile-time guarantees, and maintainable domain models.
+
+## When to Use This Skill
+
+- Building type-safe APIs with strict contracts and validation
+- Implementing complex domain models with compile-time enforcement
+- Creating reusable libraries with sophisticated type inference
+- Enforcing business rules through the type system
+- Building type-safe state machines and builders
+- Developing framework integrations requiring advanced types
+- Implementing runtime validation with type-level guarantees
+
+## Core Concepts
+
+TypeScript's type system enables compile-time safety through:
+
+1. **Conditional Types**: Type selection based on conditions (type-level if/else)
+2. **Mapped Types**: Transform object types systematically (Partial, Readonly, Pick, Omit)
+3. **Template Literal Types**: String manipulation at compile time
+4. **Type Guards**: Runtime checking with type narrowing (`value is Type`)
+5. **Discriminated Unions**: Type-safe state machines with exhaustiveness checking
+6. **Branded Types**: Nominal types for preventing primitive mixing
+7. **Builder Pattern**: Type-safe fluent APIs with progressive type constraints
+8. **Advanced Generics**: Constraints, inference, and higher-kinded type patterns
+9. **Utility Types**: Deep transformations and compositions
+10. **Type Inference**: Const assertions and contextual typing
+
+## Quick Reference
+
+Load detailed references on-demand:
+
+| Topic | Reference File |
+|-------|----------------|
+| Conditional Types | `skills/typescript-advanced-patterns/references/conditional-types.md` |
+| Mapped Types | `skills/typescript-advanced-patterns/references/mapped-types.md` |
+| Template Literal Types | `skills/typescript-advanced-patterns/references/template-literal-types.md` |
+| Type Guards | `skills/typescript-advanced-patterns/references/type-guards.md` |
+| Discriminated Unions | `skills/typescript-advanced-patterns/references/discriminated-unions.md` |
+| Branded Types | `skills/typescript-advanced-patterns/references/branded-types.md` |
+| Builder Pattern | `skills/typescript-advanced-patterns/references/builder-pattern.md` |
+| Advanced Generics | `skills/typescript-advanced-patterns/references/advanced-generics.md` |
+| Utility Types | `skills/typescript-advanced-patterns/references/utility-types.md` |
+| Type Inference | `skills/typescript-advanced-patterns/references/type-inference.md` |
+| Decorators | `skills/typescript-advanced-patterns/references/decorators.md` |
+| Performance Best Practices | `skills/typescript-advanced-patterns/references/performance-best-practices.md` |
+| Common Pitfalls | `skills/typescript-advanced-patterns/references/common-pitfalls.md` |
+| Testing Types | `skills/typescript-advanced-patterns/references/testing-types.md` |
+
+## Implementation Workflow
+
+### 1. Identify Pattern Need
+- Analyze type safety requirements
+- Identify runtime vs compile-time constraints
+- Choose appropriate pattern from Quick Reference
+
+### 2. Load Reference
+- Read specific reference file for pattern
+- Review examples and use cases
+- Understand trade-offs
+
+### 3. Implement Pattern
+- Start simple, add complexity as needed
+- Use strict mode (`tsconfig.json` with `"strict": true`)
+- Test with type assertions
+
+### 4. Validate
+- Ensure type errors caught at compile time
+- Verify runtime behavior matches types
+- Check performance (avoid excessive type complexity)
+
+### 5. Document
+- Add JSDoc comments for public APIs
+- Document type constraints and assumptions
+- Provide usage examples
+
+## Common Mistakes to Avoid
+
+1. **Using `any` instead of `unknown`**: Loses all type safety
+   - Use `unknown` and type guards instead
+
+2. **Type assertions without validation**: Unsafe runtime behavior
+   - Prefer type guards (`value is Type`) over `as Type`
+
+3. **Overusing generics**: Unnecessary complexity
+   - Only use generics when types truly vary
+
+4. **Deep type nesting**: Slow compilation, hard to debug
+   - Keep types composable and shallow
+
+5. **Forgetting `readonly`**: Accidental mutations
+   - Mark immutable data structures as `readonly`
+
+6. **Not enabling strict mode**: Missing null checks and type errors
+   - Always use `"strict": true` in `tsconfig.json`
+
+7. **Mixing type and interface incorrectly**: Confusing semantics
+   - Use `type` for unions/utilities, `interface` for object shapes
+
+## Quick Patterns
+
+### Type-Safe ID
+```typescript
+type UserId = string & { readonly __brand: 'UserId' };
+function createUserId(id: string): UserId { return id as UserId; }
+```
+
+### Discriminated Union
+```typescript
+type State =
+  | { status: 'loading' }
+  | { status: 'success'; data: string }
+  | { status: 'error'; error: Error };
+```
+
+### Mapped Type Transformation
+```typescript
+type Readonly<T> = { readonly [P in keyof T]: T[P] };
+type Partial<T> = { [P in keyof T]?: T[P] };
+```
+
+### Type Guard
+```typescript
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+```
+
+## Resources
+
+- **TypeScript Handbook**: https://www.typescriptlang.org/docs/handbook/
+- **Type Challenges**: https://github.com/type-challenges/type-challenges
+- **ts-toolbelt**: Advanced type utilities library
+- **zod**: Runtime validation with TypeScript inference
+- **tsd**: Test TypeScript type definitions

package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/advanced-generics.md

@@ -0,0 +1,90 @@
+# Advanced Generics
+
+**Generic constraints and inference:**
+
+## Basic Constraints
+
+```typescript
+// Constrain to objects with specific keys
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+const user = { name: 'John', age: 30 };
+const name = getProperty(user, 'name');  // Type: string
+// const invalid = getProperty(user, 'invalid');  // Error
+
+// Multiple constraints
+function merge<T extends object, U extends object>(
+  obj1: T,
+  obj2: U
+): T & U {
+  return { ...obj1, ...obj2 };
+}
+```
+
+## Generic Inference
+
+```typescript
+// Infer from function implementation
+function createAction<T extends string, P>(
+  type: T,
+  payload: P
+) {
+  return { type, payload };
+}
+
+const action = createAction('UPDATE_USER', { id: 1, name: 'John' });
+// Type: { type: 'UPDATE_USER'; payload: { id: number; name: string } }
+
+// Infer generic types from usage
+function useState<S>(
+  initialState: S | (() => S)
+): [S, (newState: S) => void] {
+  // Implementation
+}
+
+const [count, setCount] = useState(0);  // S inferred as number
+const [user, setUser] = useState({ name: 'John' });  // S inferred as { name: string }
+```
+
+## Higher-Kinded Types Pattern
+
+```typescript
+// Type-safe data structures
+interface Functor<F> {
+  map<A, B>(fa: F extends { value: any } ? F : never, f: (a: A) => B): any;
+}
+
+interface Box<T> {
+  value: T;
+}
+
+const boxFunctor: Functor<Box<any>> = {
+  map<A, B>(fa: Box<A>, f: (a: A) => B): Box<B> {
+    return { value: f(fa.value) };
+  }
+};
+```
+
+## Conditional Generic Types
+
+```typescript
+// Return type varies based on parameter
+type ApiResponse<T extends string> =
+  T extends 'json' ? object :
+  T extends 'text' ? string :
+  T extends 'blob' ? Blob :
+  never;
+
+async function fetch<T extends 'json' | 'text' | 'blob'>(
+  url: string,
+  type: T
+): Promise<ApiResponse<T>> {
+  // Implementation
+}
+
+const json = await fetch('/api', 'json');    // Type: object
+const text = await fetch('/api', 'text');    // Type: string
+const blob = await fetch('/api', 'blob');    // Type: Blob
+```

package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/branded-types.md

@@ -0,0 +1,57 @@
+# Branded Types
+
+**Create nominal types for type safety:**
+
+## Preventing Primitive Mixing
+
+```typescript
+// Prevent mixing similar primitive types
+type UserId = string & { readonly __brand: 'UserId' };
+type PostId = string & { readonly __brand: 'PostId' };
+
+function createUserId(id: string): UserId {
+  return id as UserId;
+}
+
+function createPostId(id: string): PostId {
+  return id as PostId;
+}
+
+function getUser(userId: UserId): User {
+  // Implementation
+}
+
+const userId = createUserId('user-123');
+const postId = createPostId('post-456');
+
+getUser(userId);  // Valid
+// getUser(postId);  // Type error: PostId not assignable to UserId
+```
+
+## Validation with Branded Types
+
+```typescript
+type ValidEmail = string & { readonly __brand: 'ValidEmail' };
+type ValidURL = string & { readonly __brand: 'ValidURL' };
+
+function validateEmail(email: string): ValidEmail | null {
+  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return regex.test(email) ? (email as ValidEmail) : null;
+}
+
+function sendEmail(to: ValidEmail, subject: string, body: string) {
+  // Guaranteed to have valid email
+}
+
+const email = validateEmail('user@example.com');
+if (email) {
+  sendEmail(email, 'Hello', 'World');
+}
+```
+
+## Benefits
+
+- Compile-time prevention of ID mixing
+- Self-documenting code through type names
+- Enforced validation at boundaries
+- Zero runtime overhead

package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/builder-pattern.md

@@ -0,0 +1,71 @@
+# Builder Pattern with Types
+
+**Type-safe fluent APIs:**
+
+## Query Builder Example
+
+```typescript
+interface QueryBuilder<TSelect = unknown, TWhere = unknown> {
+  select<T>(): QueryBuilder<T, TWhere>;
+  where<T>(): QueryBuilder<TSelect, T>;
+  execute(): TSelect extends unknown ? never : Promise<TSelect[]>;
+}
+
+// Usage ensures select() called before execute()
+const results = await query
+  .select<User>()
+  .where<{ age: number }>()
+  .execute();  // Type: Promise<User[]>
+
+// query.execute();  // Error: select() not called
+```
+
+## Progressive Builder Types
+
+```typescript
+interface ConfigBuilder<
+  THost extends string | undefined = undefined,
+  TPort extends number | undefined = undefined
+> {
+  host: THost;
+  port: TPort;
+
+  withHost<H extends string>(host: H): ConfigBuilder<H, TPort>;
+  withPort<P extends number>(port: P): ConfigBuilder<THost, P>;
+
+  build: THost extends string
+    ? TPort extends number
+      ? () => { host: THost; port: TPort }
+      : never
+    : never;
+}
+
+const config = new ConfigBuilder()
+  .withHost('localhost')
+  .withPort(3000)
+  .build();  // Valid
+
+// new ConfigBuilder().build();  // Error: host and port required
+```
+
+## Type State Pattern
+
+```typescript
+// Enforce method call order at compile time
+interface EmptyBuilder {
+  addItem<T>(item: T): FilledBuilder<T>;
+}
+
+interface FilledBuilder<T> {
+  addItem(item: T): FilledBuilder<T>;
+  build(): T[];
+}
+
+// Must call addItem() before build()
+const items = builder
+  .addItem('first')
+  .addItem('second')
+  .build();  // Valid
+
+// builder.build();  // Error: can't build empty
+```

package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/common-pitfalls.md

@@ -0,0 +1,135 @@
+# Common Pitfalls
+
+## Type Assertions vs Type Guards
+
+```typescript
+// Bad - unsafe type assertion
+const value = input as string;
+
+// Good - safe type guard
+function assertString(value: unknown): asserts value is string {
+  if (typeof value !== 'string') {
+    throw new Error('Not a string');
+  }
+}
+
+assertString(input);
+// input is now narrowed to string
+```
+
+## Any vs Unknown
+
+```typescript
+// Bad - loses type safety
+function process(data: any) {
+  return data.toUpperCase();  // No type checking
+}
+
+// Good - maintains type safety
+function processUnknown(data: unknown) {
+  if (typeof data === 'string') {
+    return data.toUpperCase();  // Type guard required
+  }
+  throw new Error('Expected string');
+}
+```
+
+## Overusing Generics
+
+```typescript
+// Bad - unnecessary complexity
+function add<T extends number, U extends number>(a: T, b: U): number {
+  return a + b;
+}
+
+// Good - simple and clear
+function add(a: number, b: number): number {
+  return a + b;
+}
+```
+
+## Incorrect Type Narrowing
+
+```typescript
+// Bad - doesn't narrow type
+function isString(value: any): boolean {
+  return typeof value === 'string';
+}
+
+// Good - properly narrows type
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+```
+
+## Forgetting Readonly
+
+```typescript
+// Bad - mutable when should be immutable
+interface Config {
+  apiUrl: string;
+  timeout: number;
+}
+
+// Good - prevent accidental mutations
+interface Config {
+  readonly apiUrl: string;
+  readonly timeout: number;
+}
+```
+
+## Enum Pitfalls
+
+```typescript
+// Bad - numeric enums allow invalid values
+enum Status {
+  Active,
+  Inactive
+}
+
+const status: Status = 999;  // Valid but meaningless
+
+// Good - use string enums or const objects
+enum Status {
+  Active = 'ACTIVE',
+  Inactive = 'INACTIVE'
+}
+
+// Or use const object with as const
+const Status = {
+  Active: 'ACTIVE',
+  Inactive: 'INACTIVE'
+} as const;
+```
+
+## Not Using Strict Mode
+
+```typescript
+// Always enable in tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictPropertyInitialization": true
+  }
+}
+```
+
+## Type vs Interface Confusion
+
+```typescript
+// Use type for unions, intersections, utilities
+type ID = string | number;
+type Point = { x: number } & { y: number };
+
+// Use interface for object shapes that may be extended
+interface User {
+  id: ID;
+  name: string;
+}
+
+interface Admin extends User {
+  permissions: string[];
+}
+```

package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/conditional-types.md

@@ -0,0 +1,27 @@
+# Conditional Types
+
+**Type selection based on conditions:**
+
+```typescript
+type IsString<T> = T extends string ? true : false;
+
+type A = IsString<string>;  // true
+type B = IsString<number>;  // false
+
+// Extract function return types
+type ReturnTypeOf<T> = T extends (...args: any[]) => infer R ? R : never;
+
+type Fn = () => { name: string; age: number };
+type Result = ReturnTypeOf<Fn>;  // { name: string; age: number }
+
+// Extract array element types
+type ElementOf<T> = T extends (infer E)[] ? E : never;
+
+type Items = ElementOf<string[]>;  // string
+```
+
+## Use Cases
+- Type transformation and extraction
+- Conditional API responses based on request types
+- Generic utility type creation
+- Framework integration types

package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/decorators.md

@@ -0,0 +1,98 @@
+# Decorators (Stage 3)
+
+**Class and method decorators for cross-cutting concerns:**
+
+## Method Decorators
+
+```typescript
+// Method decorator for logging
+function log(
+  target: any,
+  propertyKey: string,
+  descriptor: PropertyDescriptor
+) {
+  const original = descriptor.value;
+
+  descriptor.value = function(...args: any[]) {
+    console.log(`Calling ${propertyKey} with`, args);
+    const result = original.apply(this, args);
+    console.log(`Result:`, result);
+    return result;
+  };
+
+  return descriptor;
+}
+
+class Calculator {
+  @log
+  add(a: number, b: number): number {
+    return a + b;
+  }
+}
+```
+
+## Property Decorators
+
+```typescript
+// Property decorator for validation
+function validate(validator: (value: any) => boolean) {
+  return function(target: any, propertyKey: string) {
+    let value = target[propertyKey];
+
+    Object.defineProperty(target, propertyKey, {
+      get: () => value,
+      set: (newValue) => {
+        if (!validator(newValue)) {
+          throw new Error(`Invalid value for ${propertyKey}`);
+        }
+        value = newValue;
+      }
+    });
+  };
+}
+
+class User {
+  @validate(email => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
+  email: string;
+}
+```
+
+## Class Decorators
+
+```typescript
+// Class decorator for metadata
+function sealed(constructor: Function) {
+  Object.seal(constructor);
+  Object.seal(constructor.prototype);
+}
+
+@sealed
+class SealedClass {
+  constructor(public name: string) {}
+}
+```
+
+## Decorator Factories
+
+```typescript
+// Decorator with parameters
+function component(config: { selector: string }) {
+  return function(constructor: Function) {
+    constructor.prototype.selector = config.selector;
+  };
+}
+
+@component({ selector: 'app-user' })
+class UserComponent {
+  // selector property added at runtime
+}
+```
+
+## Common Use Cases
+
+- **Logging**: Automatic method call logging
+- **Validation**: Property value validation
+- **Memoization**: Cache method results
+- **Authorization**: Check permissions before execution
+- **Dependency Injection**: Inject dependencies into classes
+- **Metadata**: Attach runtime metadata for frameworks

package/template/.agent/skill-library/stack/languages/typescript-advanced-patterns/references/discriminated-unions.md

@@ -0,0 +1,62 @@
+# Discriminated Unions
+
+**Type-safe state machines and variants:**
+
+## State Machines
+
+```typescript
+// State machine with exhaustive checking
+type LoadingState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: string[] }
+  | { status: 'error'; error: Error };
+
+function renderState(state: LoadingState): string {
+  switch (state.status) {
+    case 'idle':
+      return 'Not started';
+    case 'loading':
+      return 'Loading...';
+    case 'success':
+      return `Loaded ${state.data.length} items`;
+    case 'error':
+      return `Error: ${state.error.message}`;
+  }
+  // Exhaustiveness checking ensures all cases handled
+}
+```
+
+## Action Types
+
+```typescript
+// API action types
+type Action =
+  | { type: 'FETCH_USER'; payload: { userId: string } }
+  | { type: 'UPDATE_USER'; payload: { userId: string; data: Partial<User> } }
+  | { type: 'DELETE_USER'; payload: { userId: string } }
+  | { type: 'CLEAR_USERS' };
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'FETCH_USER':
+      // action.payload is { userId: string }
+      return { ...state, loading: true };
+    case 'UPDATE_USER':
+      // action.payload is { userId: string; data: Partial<User> }
+      return updateUser(state, action.payload);
+    case 'DELETE_USER':
+      return deleteUser(state, action.payload.userId);
+    case 'CLEAR_USERS':
+      // action has no payload
+      return { ...state, users: [] };
+  }
+}
+```
+
+## Best Practices
+
+- Always include a discriminant property (e.g., `status`, `type`)
+- Use string literal types for discriminant values
+- Enable `strictNullChecks` for exhaustiveness checking
+- Use `never` to ensure all cases are handled