@nockdev/awf 6.2.0

package/.agent/skills/languages/typescript/data/async.yaml

@@ -0,0 +1,397 @@
+# =============================================================================
+# TypeScript Async Patterns (Feb 2026)
+# Version: TypeScript 5.8/ES2025
+# =============================================================================
+
+metadata:
+  skill: typescript
+  domain: async
+  version: "5.8"
+  updated: "2026-02-05"
+  patterns_count: 5
+
+patterns:
+  - id: ts201
+    name: Promise Utilities
+    category: async
+    version: "ES2020+"
+    description: |
+      Modern Promise utilities and patterns.
+      allSettled, any, withResolvers.
+    text: promise all settled any withResolvers concurrent
+    example: |
+      // ✅ Promise.allSettled - all results, no short-circuit
+      async function fetchAllUsers(ids: number[]): Promise<Map<number, User | Error>> {
+        const results = await Promise.allSettled(
+          ids.map(id => fetchUser(id))
+        );
+        
+        return new Map(
+          results.map((result, i) => [
+            ids[i],
+            result.status === 'fulfilled' ? result.value : result.reason,
+          ])
+        );
+      }
+
+      // ✅ Promise.any - first success wins
+      async function fetchFromMirrors(url: string): Promise<Response> {
+        const mirrors = [
+          `https://mirror1.example.com${url}`,
+          `https://mirror2.example.com${url}`,
+          `https://mirror3.example.com${url}`,
+        ];
+        
+        try {
+          return await Promise.any(mirrors.map(fetch));
+        } catch (error) {
+          if (error instanceof AggregateError) {
+            console.error('All mirrors failed:', error.errors);
+          }
+          throw error;
+        }
+      }
+
+      // ✅ Promise.withResolvers (ES2024)
+      function createDeferred<T>() {
+        const { promise, resolve, reject } = Promise.withResolvers<T>();
+        return { promise, resolve, reject };
+      }
+
+      // Usage: External control over promise
+      const deferred = createDeferred<string>();
+
+      setTimeout(() => deferred.resolve('done'), 1000);
+
+      // Or in event handler
+      button.onclick = () => deferred.resolve('clicked');
+
+      const result = await deferred.promise;
+
+      // ✅ Parallel with limit
+      async function parallelLimit<T, R>(
+        items: T[],
+        limit: number,
+        fn: (item: T) => Promise<R>
+      ): Promise<R[]> {
+        const results: R[] = [];
+        const executing: Promise<void>[] = [];
+        
+        for (const item of items) {
+          const p = fn(item).then(result => {
+            results.push(result);
+          });
+          executing.push(p);
+          
+          if (executing.length >= limit) {
+            await Promise.race(executing);
+            executing.splice(executing.findIndex(p => p), 1);
+          }
+        }
+        
+        await Promise.all(executing);
+        return results;
+      }
+    severity: HIGH
+    docs_url: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
+  - id: ts202
+    name: Result Pattern
+    category: error-handling
+    version: "TypeScript 4.0+"
+    description: |
+      Functional error handling without exceptions.
+      Inspired by Rust Result type.
+    text: result pattern error handling either ok err
+    example: |
+      // ✅ Result type definition
+      type Result<T, E = Error> =
+        | { ok: true; value: T }
+        | { ok: false; error: E };
+
+      // Helper functions
+      function Ok<T>(value: T): Result<T, never> {
+        return { ok: true, value };
+      }
+
+      function Err<E>(error: E): Result<never, E> {
+        return { ok: false, error };
+      }
+
+      // ✅ Usage in functions
+      async function fetchUser(id: number): Promise<Result<User, ApiError>> {
+        try {
+          const response = await fetch(`/api/users/${id}`);
+          
+          if (!response.ok) {
+            return Err({
+              code: response.status,
+              message: `User ${id} not found`,
+            });
+          }
+          
+          const user = await response.json();
+          return Ok(user);
+        } catch (error) {
+          return Err({
+            code: 500,
+            message: error instanceof Error ? error.message : 'Unknown error',
+          });
+        }
+      }
+
+      // ✅ Consuming Result
+      async function getUserName(id: number): Promise<string> {
+        const result = await fetchUser(id);
+        
+        if (!result.ok) {
+          console.error(`Error ${result.error.code}: ${result.error.message}`);
+          return 'Unknown User';
+        }
+        
+        return result.value.name;
+      }
+
+      // ✅ Chaining Results
+      function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E> {
+        return result.ok ? Ok(fn(result.value)) : result;
+      }
+
+      function flatMap<T, U, E>(
+        result: Result<T, E>,
+        fn: (value: T) => Result<U, E>
+      ): Result<U, E> {
+        return result.ok ? fn(result.value) : result;
+      }
+
+      // Usage
+      const nameResult = map(await fetchUser(1), user => user.name);
+    severity: MEDIUM
+    docs_url: https://www.typescriptlang.org/docs/handbook/2/narrowing.html
+
+  - id: ts203
+    name: AbortController Pattern
+    category: cancellation
+    version: "ES2017+"
+    description: |
+      Cancel async operations with AbortController.
+      Timeout, user cancellation, cleanup.
+    text: abort controller cancel timeout signal cleanup
+    example: |
+      // ✅ Basic AbortController usage
+      async function fetchWithTimeout(
+        url: string,
+        timeoutMs: number
+      ): Promise<Response> {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        
+        try {
+          const response = await fetch(url, { signal: controller.signal });
+          return response;
+        } finally {
+          clearTimeout(timeoutId);
+        }
+      }
+
+      // ✅ User cancellation
+      function createCancellableRequest() {
+        const controller = new AbortController();
+        
+        const request = async (url: string) => {
+          const response = await fetch(url, { signal: controller.signal });
+          return response.json();
+        };
+        
+        const cancel = () => controller.abort();
+        
+        return { request, cancel };
+      }
+
+      // Usage
+      const { request, cancel } = createCancellableRequest();
+      button.onclick = cancel; // Cancel on button click
+      const data = await request('/api/data');
+
+      // ✅ AbortSignal.timeout (modern)
+      async function fetchWithModernTimeout(url: string): Promise<Response> {
+        return fetch(url, { signal: AbortSignal.timeout(5000) });
+      }
+
+      // ✅ Combine multiple signals
+      function combineSignals(...signals: AbortSignal[]): AbortSignal {
+        const controller = new AbortController();
+        
+        for (const signal of signals) {
+          if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+          }
+          signal.addEventListener('abort', () => {
+            controller.abort(signal.reason);
+          });
+        }
+        
+        return controller.signal;
+      }
+
+      // Usage: timeout + user cancellation
+      const userController = new AbortController();
+      const combined = combineSignals(
+        userController.signal,
+        AbortSignal.timeout(30000)
+      );
+
+      await fetch(url, { signal: combined });
+    severity: HIGH
+    docs_url: https://developer.mozilla.org/en-US/docs/Web/API/AbortController
+
+  - id: ts204
+    name: Iterator Helpers (ES2025)
+    category: iteration
+    version: "ES2025"
+    description: |
+      Built-in iterator helper methods.
+      map, filter, take, drop, flatMap on iterators.
+    text: iterator helpers map filter take drop flatMap
+    example: |
+      // ✅ Iterator helpers (ES2025)
+      // Available on all iterators, not just arrays
+
+      function* numbers() {
+        let i = 0;
+        while (true) yield i++;
+      }
+
+      // Chain operations lazily
+      const result = numbers()
+        .filter(n => n % 2 === 0)  // Even numbers
+        .map(n => n * 2)           // Double them
+        .take(5)                    // First 5
+        .toArray();                 // Materialize
+
+      console.log(result); // [0, 4, 8, 12, 16]
+
+      // ✅ Available methods
+      const iter = [1, 2, 3, 4, 5].values();
+
+      iter.map(x => x * 2);        // Transform each element
+      iter.filter(x => x > 2);     // Keep matching elements
+      iter.take(3);                // First n elements
+      iter.drop(2);                // Skip first n elements
+      iter.flatMap(x => [x, x]);   // Map and flatten
+      iter.reduce((a, b) => a + b);// Reduce to single value
+      iter.toArray();              // Convert to array
+      iter.forEach(console.log);   // Side effect each element
+      iter.some(x => x > 3);       // Any match?
+      iter.every(x => x > 0);      // All match?
+      iter.find(x => x === 3);     // First match
+
+      // ✅ Lazy evaluation benefit
+      function* infiniteUsers() {
+        let id = 0;
+        while (true) {
+          yield fetchUserSync(id++);
+        }
+      }
+
+      // Only fetches 10 active users, not all
+      const activeUsers = infiniteUsers()
+        .filter(user => user.active)
+        .take(10)
+        .toArray();
+
+      // ✅ Working with async iterators
+      async function* fetchPages(url: string) {
+        let page = 1;
+        while (true) {
+          const data = await fetch(`${url}?page=${page++}`).then(r => r.json());
+          if (!data.items.length) break;
+          yield* data.items;
+        }
+      }
+
+      // Async iterator helpers (proposal)
+      for await (const item of fetchPages('/api/items')) {
+        process(item);
+      }
+    severity: MEDIUM
+    docs_url: https://github.com/tc39/proposal-iterator-helpers
+
+  - id: ts205
+    name: Explicit Resource Management
+    category: cleanup
+    version: "ES2025/TS 5.2+"
+    description: |
+      using declaration for automatic cleanup.
+      RAII pattern in JavaScript/TypeScript.
+    text: using declaration dispose asyncDispose cleanup RAII
+    example: |
+      // ✅ using declaration (ES2025 / TS 5.2+)
+      // Automatically calls Symbol.dispose when scope exits
+
+      class FileHandle {
+        constructor(public path: string) {
+          console.log(`Opening ${path}`);
+        }
+        
+        read(): string {
+          return 'file contents';
+        }
+        
+        [Symbol.dispose](): void {
+          console.log(`Closing ${this.path}`);
+        }
+      }
+
+      function processFile(path: string): string {
+        using file = new FileHandle(path);
+        return file.read();
+        // file automatically closed here
+      }
+
+      // ✅ Async disposal
+      class DatabaseConnection {
+        async execute(sql: string): Promise<any> {
+          // ...
+        }
+        
+        async [Symbol.asyncDispose](): Promise<void> {
+          console.log('Closing database connection');
+          await this.execute('COMMIT');
+        }
+      }
+
+      async function queryDatabase() {
+        await using db = await getConnection();
+        const result = await db.execute('SELECT * FROM users');
+        return result;
+        // Connection automatically closed
+      }
+
+      // ✅ Multiple resources
+      async function copyFile(src: string, dest: string) {
+        await using srcFile = await openFile(src, 'r');
+        await using destFile = await openFile(dest, 'w');
+        
+        const content = await srcFile.read();
+        await destFile.write(content);
+        // Both files closed in reverse order
+      }
+
+      // ✅ DisposableStack for dynamic resources
+      async function processMultiple(paths: string[]) {
+        await using stack = new AsyncDisposableStack();
+        
+        const files = paths.map(path => {
+          const file = new FileHandle(path);
+          stack.use(file); // Track for disposal
+          return file;
+        });
+        
+        // Process files...
+        
+        // All files closed when stack disposes
+      }
+    severity: HIGH
+    docs_url: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management

package/.agent/skills/languages/typescript/data/core.yaml

@@ -0,0 +1,283 @@
+# =============================================================================
+# TypeScript Core Patterns (Feb 2026)
+# Version: TypeScript 5.8/6.0
+# =============================================================================
+
+metadata:
+  skill: typescript
+  domain: core
+  version: "6.0"
+  updated: "2026-02-05"
+  patterns_count: 5
+
+patterns:
+  - id: ts001
+    name: Utility Types
+    category: types
+    version: "4.0+"
+    description: |
+      Built-in utility types for type transformations.
+      Omit, Pick, Partial, Required, Record, etc.
+    text: utility types omit pick partial required record
+    example: |
+      // ✅ Pick/Omit - Select or exclude properties
+      interface User {
+        id: number;
+        name: string;
+        email: string;
+        password: string;
+      }
+
+      type UserPublic = Omit<User, 'password'>;
+      type UserCredentials = Pick<User, 'email' | 'password'>;
+
+      // ✅ Partial/Required - Make all props optional/required
+      type UserUpdate = Partial<User>; // All optional
+      type StrictUser = Required<User>; // All required
+
+      // ✅ Record - Object type with specified keys
+      type UserRole = 'admin' | 'user' | 'guest';
+      type RolePermissions = Record<UserRole, string[]>;
+
+      const permissions: RolePermissions = {
+        admin: ['read', 'write', 'delete'],
+        user: ['read', 'write'],
+        guest: ['read'],
+      };
+
+      // ✅ Readonly - Immutable types
+      type ImmutableUser = Readonly<User>;
+
+      // ✅ Extract/Exclude - Union type manipulation
+      type NumericKeys = Extract<keyof User, 'id'>; // 'id'
+      type StringKeys = Exclude<keyof User, 'id'>; // 'name' | 'email' | 'password'
+
+      // ✅ ReturnType/Parameters - Function type extraction
+      function createUser(name: string, age: number): User {
+        return { id: 1, name, email: '', password: '' };
+      }
+
+      type CreateUserReturn = ReturnType<typeof createUser>; // User
+      type CreateUserParams = Parameters<typeof createUser>; // [string, number]
+    severity: HIGH
+    docs_url: https://www.typescriptlang.org/docs/handbook/utility-types.html
+
+  - id: ts002
+    name: Discriminated Unions
+    category: types
+    version: "2.0+"
+    description: |
+      Type-safe unions with discriminant property.
+      Exhaustive pattern matching with never.
+    text: discriminated union tagged union pattern matching exhaustive
+    example: |
+      // ✅ Discriminated union with 'type' discriminant
+      type Result<T> =
+        | { type: 'success'; data: T }
+        | { type: 'error'; error: Error }
+        | { type: 'loading' };
+
+      function handleResult<T>(result: Result<T>): T | null {
+        switch (result.type) {
+          case 'success':
+            return result.data; // TypeScript knows data exists
+          case 'error':
+            console.error(result.error);
+            return null;
+          case 'loading':
+            return null;
+          default:
+            // Exhaustiveness check
+            const _exhaustive: never = result;
+            return _exhaustive;
+        }
+      }
+
+      // ✅ API response pattern
+      type ApiResponse<T> =
+        | { status: 'ok'; data: T; timestamp: Date }
+        | { status: 'error'; message: string; code: number }
+        | { status: 'pending' };
+
+      // ✅ State machine pattern
+      type ConnectionState =
+        | { state: 'disconnected' }
+        | { state: 'connecting'; attempt: number }
+        | { state: 'connected'; socket: WebSocket }
+        | { state: 'error'; error: Error; retryAt: Date };
+
+      function getConnectionInfo(conn: ConnectionState): string {
+        switch (conn.state) {
+          case 'disconnected':
+            return 'Not connected';
+          case 'connecting':
+            return `Connecting (attempt ${conn.attempt})`;
+          case 'connected':
+            return `Connected to ${conn.socket.url}`;
+          case 'error':
+            return `Error: ${conn.error.message}`;
+        }
+      }
+    severity: HIGH
+    docs_url: https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions
+
+  - id: ts003
+    name: Branded Types
+    category: types
+    version: "2.0+"
+    description: |
+      Nominal typing via branded types.
+      Prevent mixing similar primitive types.
+    text: branded types nominal typing type safety
+    example: |
+      // ✅ Branded type pattern
+      declare const __brand: unique symbol;
+      type Brand<T, B> = T & { [__brand]: B };
+
+      // Define branded types
+      type UserId = Brand<number, 'UserId'>;
+      type OrderId = Brand<number, 'OrderId'>;
+      type Email = Brand<string, 'Email'>;
+
+      // ✅ Type guards for creating branded types
+      function isValidEmail(email: string): email is Email {
+        return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+      }
+
+      function createEmail(value: string): Email {
+        if (!isValidEmail(value)) {
+          throw new Error('Invalid email');
+        }
+        return value;
+      }
+
+      function createUserId(id: number): UserId {
+        if (id <= 0) throw new Error('Invalid user ID');
+        return id as UserId;
+      }
+
+      // ✅ Usage - compiler prevents mixing IDs
+      function getUser(id: UserId): Promise<User> {
+        return fetch(`/users/${id}`).then(r => r.json());
+      }
+
+      function getOrder(id: OrderId): Promise<Order> {
+        return fetch(`/orders/${id}`).then(r => r.json());
+      }
+
+      const userId = createUserId(123);
+      const orderId = createUserId(456) as unknown as OrderId;
+
+      getUser(userId);   // ✅ OK
+      // getUser(orderId); // ❌ Type error: OrderId not assignable to UserId
+      // getUser(123);     // ❌ Type error: number not assignable to UserId
+    severity: MEDIUM
+    docs_url: https://www.typescriptlang.org/play#example/nominal-typing
+
+  - id: ts004
+    name: Template Literal Types
+    category: types
+    version: "4.1+"
+    description: |
+      String manipulation at type level.
+      Build complex string patterns from types.
+    text: template literal types string manipulation type level
+    example: |
+      // ✅ Basic template literal type
+      type EventName = 'click' | 'focus' | 'blur';
+      type EventHandler = `on${Capitalize<EventName>}`; // 'onClick' | 'onFocus' | 'onBlur'
+
+      // ✅ Route patterns
+      type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
+      type Resource = 'users' | 'posts' | 'comments';
+      type Route = `${Lowercase<Method>} /api/${Resource}`;
+      // 'get /api/users' | 'get /api/posts' | 'post /api/users' | ...
+
+      // ✅ CSS property types
+      type CSSUnit = 'px' | 'rem' | 'em' | '%';
+      type CSSValue = `${number}${CSSUnit}`;
+
+      function setWidth(width: CSSValue): void {
+        // ...
+      }
+
+      setWidth('100px');  // ✅
+      setWidth('2rem');   // ✅
+      // setWidth('100');  // ❌ Type error
+
+      // ✅ Object key transformation
+      type Getters<T> = {
+        [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+      };
+
+      interface Person {
+        name: string;
+        age: number;
+      }
+
+      type PersonGetters = Getters<Person>;
+      // { getName: () => string; getAge: () => number }
+
+      // ✅ Parse string patterns
+      type ParseRoute<T extends string> =
+        T extends `${infer Method} ${infer Path}`
+          ? { method: Method; path: Path }
+          : never;
+
+      type Parsed = ParseRoute<'GET /users'>; // { method: 'GET'; path: '/users' }
+    severity: MEDIUM
+    docs_url: https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html
+
+  - id: ts005
+    name: const Assertions
+    category: types
+    version: "3.4+"
+    description: |
+      Narrow literal types with 'as const'.
+      Readonly inference for objects and arrays.
+    text: const assertion literal type readonly inference
+    example: |
+      // ✅ Array as tuple
+      const colors = ['red', 'green', 'blue'] as const;
+      // type: readonly ['red', 'green', 'blue']
+
+      type Color = (typeof colors)[number]; // 'red' | 'green' | 'blue'
+
+      // ✅ Object literal types
+      const config = {
+        apiUrl: 'https://api.example.com',
+        timeout: 5000,
+        retries: 3,
+      } as const;
+
+      type Config = typeof config;
+      // { readonly apiUrl: 'https://api.example.com'; readonly timeout: 5000; readonly retries: 3 }
+
+      // ✅ Enum-like pattern
+      const HttpStatus = {
+        OK: 200,
+        NotFound: 404,
+        ServerError: 500,
+      } as const;
+
+      type HttpStatusCode = (typeof HttpStatus)[keyof typeof HttpStatus];
+      // 200 | 404 | 500
+
+      // ✅ Function with const type parameter (5.0+)
+      function createRoute<const T extends string>(path: T): { path: T } {
+        return { path };
+      }
+
+      const route = createRoute('/users/:id');
+      // type: { path: '/users/:id' } (not { path: string })
+
+      // ✅ satisfies with as const
+      const routes = {
+        home: '/',
+        users: '/users',
+        posts: '/posts',
+      } as const satisfies Record<string, string>;
+
+      type RouteName = keyof typeof routes; // 'home' | 'users' | 'posts'
+    severity: MEDIUM
+    docs_url: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#const-assertions