cfsa-antigravity 3.0.2 → 3.1.0

package/template/.codex/skill-library/stack/languages/typescript-advanced-patterns/references/mapped-types.md

@@ -0,0 +1,53 @@
+# Mapped Types
+
+**Transform object types systematically:**
+
+```typescript
+// Make all properties optional
+type Partial<T> = {
+  [P in keyof T]?: T[P];
+};
+
+// Make all properties readonly
+type Readonly<T> = {
+  readonly [P in keyof T]: T[P];
+};
+
+// Pick specific properties
+type Pick<T, K extends keyof T> = {
+  [P in K]: T[P];
+};
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  password: string;
+}
+
+// Create API response type
+type UserResponse = Omit<User, 'password'>;
+
+// Create update type (all optional)
+type UserUpdate = Partial<User>;
+
+// Create creation type (no id)
+type UserCreate = Omit<User, 'id'>;
+```
+
+## Advanced Mapping
+
+```typescript
+// Add prefix to all keys
+type Prefixed<T, Prefix extends string> = {
+  [K in keyof T as `${Prefix}${string & K}`]: T[K];
+};
+
+type Events = {
+  click: MouseEvent;
+  focus: FocusEvent;
+};
+
+type Handlers = Prefixed<Events, 'on'>;
+// { onclick: MouseEvent; onfocus: FocusEvent }
+```

package/template/.codex/skill-library/stack/languages/typescript-advanced-patterns/references/performance-best-practices.md

@@ -0,0 +1,104 @@
+# Performance Best Practices
+
+## Avoid Excessive Type Complexity
+
+**Keep types simple and composable:**
+
+```typescript
+// Bad - deeply nested types
+type Complex<T> = T extends Array<infer U>
+  ? U extends Array<infer V>
+    ? V extends Array<infer W>
+      ? W extends Array<infer X>
+        ? X
+        : never
+      : never
+    : never
+  : never;
+
+// Good - iterative approach
+type ElementType<T> = T extends (infer E)[] ? E : T;
+
+type Deep1<T> = ElementType<T>;
+type Deep2<T> = ElementType<Deep1<T>>;
+```
+
+## Use Type Aliases for Reusability
+
+**Extract common patterns:**
+
+```typescript
+// Define once, reuse everywhere
+type ID = string | number;
+type Timestamp = number;
+type Optional<T> = T | null | undefined;
+
+interface User {
+  id: ID;
+  createdAt: Timestamp;
+  lastLogin: Optional<Timestamp>;
+}
+```
+
+## Leverage Inference
+
+**Let TypeScript infer when possible:**
+
+```typescript
+// Don't over-annotate
+const users = [
+  { id: 1, name: 'John' },
+  { id: 2, name: 'Jane' }
+];  // Type inferred automatically
+
+// Use inference in generics
+function identity<T>(value: T): T {
+  return value;
+}
+
+const num = identity(42);  // T inferred as 42 (literal type)
+```
+
+## Avoid Type Computation Overhead
+
+```typescript
+// Bad - expensive type computation on every use
+type ExpensiveUnion<T> = T extends any
+  ? { [K in keyof T]: SomeComplexType<T[K]> }
+  : never;
+
+// Good - compute once, reuse
+type PrecomputedType = ExpensiveUnion<MyType>;
+function useType(value: PrecomputedType) { }
+```
+
+## Use Index Signatures Wisely
+
+```typescript
+// Bad - loses type safety
+interface LooseMap {
+  [key: string]: any;
+}
+
+// Good - constrained types
+interface TypedMap {
+  [key: string]: string | number;
+}
+
+// Better - use Record for known types
+type StrictMap = Record<'id' | 'name' | 'age', string | number>;
+```
+
+## Optimize Union Types
+
+```typescript
+// Bad - large union causes slow checking
+type ManyStrings = 'a' | 'b' | 'c' | /* ...100 more */ | 'z';
+
+// Good - use branded types or enums for large sets
+enum StringEnum {
+  A = 'a',
+  B = 'b',
+  // ...
+}
+```

package/template/.codex/skill-library/stack/languages/typescript-advanced-patterns/references/template-literal-types.md

@@ -0,0 +1,49 @@
+# Template Literal Types
+
+**String type manipulation at compile time:**
+
+```typescript
+// Event handler types
+type EventNames = 'click' | 'focus' | 'blur';
+type EventHandlers = `on${Capitalize<EventNames>}`;
+// 'onClick' | 'onFocus' | 'onBlur'
+
+// URL path types
+type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type Endpoint = `/api/${'users' | 'posts' | 'comments'}`;
+type Route = `${HTTPMethod} ${Endpoint}`;
+// 'GET /api/users' | 'POST /api/users' | ...
+
+// CSS property types
+type CSSUnit = 'px' | 'em' | 'rem' | '%';
+type Size = `${number}${CSSUnit}`;
+
+const width: Size = '100px';  // Valid
+const height: Size = '2em';   // Valid
+// const invalid: Size = '100';  // Error
+```
+
+## Nested Template Literals
+
+```typescript
+type DeepKey<T> = T extends object
+  ? {
+      [K in keyof T & string]: K | `${K}.${DeepKey<T[K]>}`;
+    }[keyof T & string]
+  : never;
+
+interface Config {
+  database: {
+    host: string;
+    port: number;
+    credentials: {
+      username: string;
+      password: string;
+    };
+  };
+}
+
+type ConfigKeys = DeepKey<Config>;
+// 'database' | 'database.host' | 'database.port' |
+// 'database.credentials' | 'database.credentials.username' | ...
+```

package/template/.codex/skill-library/stack/languages/typescript-advanced-patterns/references/testing-types.md

@@ -0,0 +1,112 @@
+# Testing Type-Safe Code
+
+## Type Assertion Tests
+
+```typescript
+// Type equality checker
+type AssertEqual<T, U> = T extends U ? (U extends T ? true : false) : false;
+
+type Test1 = AssertEqual<Pick<User, 'name'>, { name: string }>;  // true
+type Test2 = AssertEqual<string, number>;  // false
+```
+
+## Compile-Time Validation
+
+```typescript
+// Expect type to match
+function expectType<T>(value: T): T {
+  return value;
+}
+
+const user: User = { id: 1, name: 'John', email: 'john@example.com', password: 'secret' };
+expectType<UserResponse>(user);  // Error: password should not exist
+```
+
+## Test Helper Types
+
+```typescript
+// Assert never (for exhaustiveness checking)
+type AssertNever<T extends never> = T;
+
+// Assert extends
+type AssertExtends<T, U extends T> = U;
+
+// Assert assignable
+type AssertAssignable<T, U> = U extends T ? true : false;
+```
+
+## Runtime Type Testing
+
+```typescript
+import { expectType, expectError, expectAssignable } from 'tsd';
+
+// Test type inference
+const result = identity(42);
+expectType<number>(result);
+
+// Test error cases
+// @ts-expect-error
+expectError(getUser('invalid-id'));
+
+// Test assignability
+interface Base { id: number; }
+interface Extended extends Base { name: string; }
+
+expectAssignable<Base>({} as Extended);
+```
+
+## Property-Based Type Testing
+
+```typescript
+// Test all properties of a type
+type TestUserProperties = {
+  [K in keyof User]: User[K] extends string | number ? true : false;
+};
+
+// Ensure required properties exist
+type RequiredFields = Required<Pick<User, 'id' | 'name' | 'email'>>;
+```
+
+## Testing Discriminated Unions
+
+```typescript
+type State =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: string };
+
+// Test exhaustiveness
+function testExhaustive(state: State) {
+  switch (state.status) {
+    case 'idle':
+    case 'loading':
+    case 'success':
+      return;
+    default:
+      // Should be never
+      const _exhaustive: never = state;
+      return _exhaustive;
+  }
+}
+```
+
+## Type Coverage Tools
+
+Use `type-coverage` to ensure high type safety:
+
+```bash
+npm install --save-dev type-coverage
+
+# Check type coverage
+npx type-coverage
+
+# Require 100% coverage
+npx type-coverage --at-least 100
+```
+
+## Testing Frameworks
+
+- **tsd**: Test TypeScript type definitions
+- **dtslint**: Linter for .d.ts files
+- **type-coverage**: Measure type coverage percentage
+- **ts-expect**: Runtime type checking for tests

package/template/.codex/skill-library/stack/languages/typescript-advanced-patterns/references/type-guards.md

@@ -0,0 +1,70 @@
+# Type Guards
+
+**Runtime type checking with type narrowing:**
+
+## Basic Type Guards
+
+```typescript
+// Basic type guard
+function isString(value: unknown): value is string {
+  return typeof value === 'string';
+}
+
+// Discriminated union guard
+interface Success {
+  status: 'success';
+  data: string;
+}
+
+interface Error {
+  status: 'error';
+  message: string;
+}
+
+type Result = Success | Error;
+
+function isSuccess(result: Result): result is Success {
+  return result.status === 'success';
+}
+
+function handleResult(result: Result) {
+  if (isSuccess(result)) {
+    console.log(result.data);  // Type narrowed to Success
+  } else {
+    console.log(result.message);  // Type narrowed to Error
+  }
+}
+```
+
+## Generic Type Guards
+
+```typescript
+function isArrayOf<T>(
+  value: unknown,
+  check: (item: unknown) => item is T
+): value is T[] {
+  return Array.isArray(value) && value.every(check);
+}
+
+const data: unknown = [1, 2, 3];
+
+if (isArrayOf(data, (x): x is number => typeof x === 'number')) {
+  data.forEach(n => n.toFixed(2));  // Type: number[]
+}
+```
+
+## Assertion Functions
+
+```typescript
+// Type assertion function
+function assertString(value: unknown): asserts value is string {
+  if (typeof value !== 'string') {
+    throw new Error('Not a string');
+  }
+}
+
+const input: unknown = 'hello';
+assertString(input);
+// input is now narrowed to string
+input.toUpperCase();  // Valid
+```

package/template/.codex/skill-library/stack/languages/typescript-advanced-patterns/references/type-inference.md

@@ -0,0 +1,101 @@
+# Type Inference Techniques
+
+**Leverage TypeScript's type inference:**
+
+## Const Assertions
+
+```typescript
+// Without const assertion
+const colors1 = ['red', 'green', 'blue'];
+// Type: string[]
+
+// With const assertion
+const colors2 = ['red', 'green', 'blue'] as const;
+// Type: readonly ['red', 'green', 'blue']
+
+// Narrow object types
+const config = {
+  endpoint: '/api/users',
+  method: 'GET'
+} as const;
+// Type: { readonly endpoint: '/api/users'; readonly method: 'GET' }
+```
+
+## Inference from Implementation
+
+```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 } }
+```
+
+## Inference with Generics
+
+```typescript
+// Let TypeScript infer generic types
+function identity<T>(value: T): T {
+  return value;
+}
+
+const num = identity(42);  // T inferred as 42 (literal type)
+const str = identity('hello');  // T inferred as 'hello'
+
+// Inference from array methods
+const numbers = [1, 2, 3];
+const doubled = numbers.map(n => n * 2);  // Type: number[]
+```
+
+## Discriminated Union Inference
+
+```typescript
+// Use in discriminated unions
+type Action =
+  | ReturnType<typeof createAction<'INCREMENT'>>
+  | ReturnType<typeof createAction<'DECREMENT'>>;
+
+function reducer(state: number, action: Action): number {
+  switch (action.type) {
+    case 'INCREMENT':
+      return state + 1;
+    case 'DECREMENT':
+      return state - 1;
+  }
+}
+```
+
+## Tuple Inference
+
+```typescript
+// Infer tuple types
+function tuple<T extends any[]>(...args: T): T {
+  return args;
+}
+
+const pair = tuple(1, 'hello');  // Type: [number, string]
+const triple = tuple(1, 'hello', true);  // Type: [number, string, boolean]
+```
+
+## Contextual Typing
+
+```typescript
+// Type inferred from context
+interface Point {
+  x: number;
+  y: number;
+}
+
+const points: Point[] = [
+  { x: 0, y: 0 },  // Type inferred from array type
+  { x: 1, y: 1 }
+];
+
+// Callback inference
+['1', '2', '3'].map(str => parseInt(str));  // str inferred as string
+```

package/template/.codex/skill-library/stack/languages/typescript-advanced-patterns/references/utility-types.md

@@ -0,0 +1,98 @@
+# Utility Types Composition
+
+**Combine utility types for complex transformations:**
+
+## Deep Transformations
+
+```typescript
+// Deep partial
+type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+// Make specific keys required
+type RequireKeys<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+
+interface User {
+  id?: number;
+  name?: string;
+  email?: string;
+}
+
+type UserWithId = RequireKeys<User, 'id'>;
+// { id: number; name?: string; email?: string }
+```
+
+## Function Type Utilities
+
+```typescript
+// Extract function parameter types
+type Parameters<T extends (...args: any[]) => any> =
+  T extends (...args: infer P) => any ? P : never;
+
+function processUser(id: number, name: string): void {}
+
+type ProcessUserParams = Parameters<typeof processUser>;
+// [number, string]
+
+// Extract return type
+type ReturnType<T extends (...args: any[]) => any> =
+  T extends (...args: any[]) => infer R ? R : never;
+```
+
+## Advanced Transformations
+
+```typescript
+// Flatten nested types
+type Flatten<T> = T extends any[] ? T[number] : T;
+
+type Nested = (string | number)[][];
+type Flat = Flatten<Nested>;  // (string | number)[]
+
+// Exclude nullable values
+type NonNullable<T> = T extends null | undefined ? never : T;
+
+// Recursive type definitions
+type JSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JSONValue[]
+  | { [key: string]: JSONValue };
+```
+
+## Readonly Utilities
+
+```typescript
+// Deep readonly
+type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends object
+    ? DeepReadonly<T[P]>
+    : T[P];
+};
+
+// Mutable (remove readonly)
+type Mutable<T> = {
+  -readonly [P in keyof T]: T[P];
+};
+```
+
+## Key Manipulation
+
+```typescript
+// Extract keys of specific type
+type KeysOfType<T, U> = {
+  [K in keyof T]: T[K] extends U ? K : never;
+}[keyof T];
+
+interface Example {
+  name: string;
+  age: number;
+  active: boolean;
+  count: number;
+}
+
+type StringKeys = KeysOfType<Example, string>;  // 'name'
+type NumberKeys = KeysOfType<Example, number>;  // 'age' | 'count'
+```