aigroup-workflow 2.1.2 → 2.2.0

package/skills/javascript/nestjs-expert/references/services-di.md

@@ -0,0 +1,140 @@
+# Services & Dependency Injection
+
+## Service Pattern
+
+```typescript
+import { Injectable, Logger, NotFoundException, ConflictException } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+@Injectable()
+export class UsersService {
+  private readonly logger = new Logger(UsersService.name);
+
+  constructor(
+    @InjectRepository(User)
+    private readonly repo: Repository<User>,
+    private readonly emailService: EmailService,
+  ) {}
+
+  async create(dto: CreateUserDto): Promise<User> {
+    try {
+      const user = this.repo.create(dto);
+      const saved = await this.repo.save(user);
+      await this.emailService.sendWelcome(saved.email);
+      return saved;
+    } catch (error) {
+      if (error.code === '23505') {
+        throw new ConflictException('Email already exists');
+      }
+      this.logger.error(`Failed to create user: ${error.message}`);
+      throw error;
+    }
+  }
+
+  async findOne(id: string): Promise<User> {
+    const user = await this.repo.findOne({ where: { id } });
+    if (!user) {
+      throw new NotFoundException(`User ${id} not found`);
+    }
+    return user;
+  }
+
+  async update(id: string, dto: UpdateUserDto): Promise<User> {
+    const user = await this.findOne(id);
+    Object.assign(user, dto);
+    return this.repo.save(user);
+  }
+
+  async remove(id: string): Promise<void> {
+    const result = await this.repo.delete(id);
+    if (result.affected === 0) {
+      throw new NotFoundException(`User ${id} not found`);
+    }
+  }
+}
+```
+
+## Module with Providers
+
+```typescript
+@Module({
+  imports: [TypeOrmModule.forFeature([User])],
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService],  // Make available to other modules
+})
+export class UsersModule {}
+```
+
+## Custom Providers
+
+```typescript
+// Value provider
+{ provide: 'API_KEY', useValue: process.env.API_KEY }
+
+// Factory provider
+{
+  provide: 'CONFIG',
+  useFactory: (configService: ConfigService) => ({
+    apiUrl: configService.get('API_URL'),
+  }),
+  inject: [ConfigService],
+}
+
+// Class provider
+{ provide: LoggerService, useClass: CustomLoggerService }
+
+// Async factory
+{
+  provide: 'DATABASE_CONNECTION',
+  useFactory: async () => {
+    const connection = await createConnection();
+    return connection;
+  },
+}
+```
+
+## Injection Patterns
+
+```typescript
+// Constructor injection (preferred)
+constructor(private readonly usersService: UsersService) {}
+
+// Token injection
+constructor(@Inject('API_KEY') private apiKey: string) {}
+
+// Optional injection
+constructor(@Optional() private readonly cache?: CacheService) {}
+
+// Property injection (use sparingly)
+@Inject() private readonly logger: Logger;
+```
+
+## Scope
+
+```typescript
+// Default: Singleton (shared across app)
+@Injectable()
+export class SharedService {}
+
+// Request-scoped: New instance per request
+@Injectable({ scope: Scope.REQUEST })
+export class RequestService {
+  constructor(@Inject(REQUEST) private request: Request) {}
+}
+
+// Transient: New instance every injection
+@Injectable({ scope: Scope.TRANSIENT })
+export class HelperService {}
+```
+
+## Quick Reference
+
+| Pattern | Use When |
+|---------|----------|
+| Constructor DI | Most cases (recommended) |
+| `@Inject(token)` | Non-class tokens |
+| `@Optional()` | Optional dependency |
+| Factory provider | Dynamic configuration |
+| Scope.REQUEST | Per-request state |

package/skills/javascript/nestjs-expert/references/testing-patterns.md

@@ -0,0 +1,186 @@
+# Testing Patterns
+
+## Unit Test Setup
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { getRepositoryToken } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { NotFoundException } from '@nestjs/common';
+
+describe('UsersService', () => {
+  let service: UsersService;
+  let repo: jest.Mocked<Repository<User>>;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        UsersService,
+        {
+          provide: getRepositoryToken(User),
+          useValue: {
+            create: jest.fn(),
+            save: jest.fn(),
+            findOne: jest.fn(),
+            delete: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get(UsersService);
+    repo = module.get(getRepositoryToken(User));
+  });
+
+  afterEach(() => jest.clearAllMocks());
+});
+```
+
+## Service Tests
+
+```typescript
+describe('create', () => {
+  it('should create user', async () => {
+    const dto = { email: 'test@test.com', password: 'pass', name: 'Test' };
+    const user = { id: '1', ...dto };
+
+    repo.create.mockReturnValue(user as User);
+    repo.save.mockResolvedValue(user as User);
+
+    const result = await service.create(dto);
+
+    expect(repo.create).toHaveBeenCalledWith(dto);
+    expect(repo.save).toHaveBeenCalledWith(user);
+    expect(result).toEqual(user);
+  });
+});
+
+describe('findOne', () => {
+  it('should return user', async () => {
+    const user = { id: '1', email: 'test@test.com' };
+    repo.findOne.mockResolvedValue(user as User);
+
+    const result = await service.findOne('1');
+    expect(result).toEqual(user);
+  });
+
+  it('should throw NotFoundException', async () => {
+    repo.findOne.mockResolvedValue(null);
+    await expect(service.findOne('1')).rejects.toThrow(NotFoundException);
+  });
+});
+```
+
+## Controller Tests
+
+```typescript
+describe('UsersController', () => {
+  let controller: UsersController;
+  let service: jest.Mocked<UsersService>;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      controllers: [UsersController],
+      providers: [
+        {
+          provide: UsersService,
+          useValue: {
+            create: jest.fn(),
+            findOne: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    controller = module.get(UsersController);
+    service = module.get(UsersService);
+  });
+
+  it('should create user', async () => {
+    const dto = { email: 'test@test.com', password: 'pass', name: 'Test' };
+    const user = { id: '1', ...dto };
+    service.create.mockResolvedValue(user as User);
+
+    const result = await controller.create(dto);
+    expect(result).toEqual(user);
+  });
+});
+```
+
+## E2E Tests
+
+```typescript
+import { INestApplication } from '@nestjs/common';
+import * as request from 'supertest';
+
+describe('UsersController (e2e)', () => {
+  let app: INestApplication;
+  let authToken: string;
+
+  beforeAll(async () => {
+    const moduleFixture = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
+    await app.init();
+
+    // Get auth token
+    const response = await request(app.getHttpServer())
+      .post('/auth/login')
+      .send({ email: 'test@test.com', password: 'password' });
+    authToken = response.body.access_token;
+  });
+
+  afterAll(() => app.close());
+
+  it('/users (POST)', () => {
+    return request(app.getHttpServer())
+      .post('/users')
+      .set('Authorization', `Bearer ${authToken}`)
+      .send({ email: 'new@test.com', password: 'Test1234', name: 'New' })
+      .expect(201)
+      .expect((res) => {
+        expect(res.body.email).toBe('new@test.com');
+      });
+  });
+
+  it('/users/:id (GET) - 404', () => {
+    return request(app.getHttpServer())
+      .get('/users/nonexistent-id')
+      .set('Authorization', `Bearer ${authToken}`)
+      .expect(404);
+  });
+});
+```
+
+## Mock Factory
+
+```typescript
+export const createMockRepository = <T>() => ({
+  create: jest.fn(),
+  save: jest.fn(),
+  find: jest.fn(),
+  findOne: jest.fn(),
+  update: jest.fn(),
+  delete: jest.fn(),
+  createQueryBuilder: jest.fn(() => ({
+    where: jest.fn().mockReturnThis(),
+    andWhere: jest.fn().mockReturnThis(),
+    getOne: jest.fn(),
+    getMany: jest.fn(),
+  })),
+});
+```
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| `Test.createTestingModule()` | Create test module |
+| `jest.fn()` | Mock function |
+| `mockResolvedValue()` | Mock async return |
+| `mockReturnValue()` | Mock sync return |
+| `supertest` | E2E HTTP testing |
+| `beforeAll` / `afterAll` | Setup/teardown |

package/skills/javascript/typescript-pro/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: typescript-pro
+description: Implements advanced TypeScript type systems, creates custom type guards, utility types, and branded types, and configures tRPC for end-to-end type safety. Use when building TypeScript applications requiring advanced generics, conditional or mapped types, discriminated unions, monorepo setup, or full-stack type safety with tRPC.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: language
+  triggers: TypeScript, generics, type safety, conditional types, mapped types, tRPC, tsconfig, type guards, discriminated unions
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fullstack-guardian, api-designer
+---
+
+# TypeScript Pro
+
+## Core Workflow
+
+1. **Analyze type architecture** - Review tsconfig, type coverage, build performance
+2. **Design type-first APIs** - Create branded types, generics, utility types
+3. **Implement with type safety** - Write type guards, discriminated unions, conditional types; run `tsc --noEmit` to catch type errors before proceeding
+4. **Optimize build** - Configure project references, incremental compilation, tree shaking; re-run `tsc --noEmit` to confirm zero errors after changes
+5. **Test types** - Confirm type coverage with a tool like `type-coverage`; validate that all public APIs have explicit return types; iterate on steps 3–4 until all checks pass
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Advanced Types | `references/advanced-types.md` | Generics, conditional types, mapped types, template literals |
+| Type Guards | `references/type-guards.md` | Type narrowing, discriminated unions, assertion functions |
+| Utility Types | `references/utility-types.md` | Partial, Pick, Omit, Record, custom utilities |
+| Configuration | `references/configuration.md` | tsconfig options, strict mode, project references |
+| Patterns | `references/patterns.md` | Builder pattern, factory pattern, type-safe APIs |
+
+## Code Examples
+
+### Branded Types
+```typescript
+// Branded type for domain modeling
+type Brand<T, B extends string> = T & { readonly __brand: B };
+type UserId  = Brand<string, "UserId">;
+type OrderId = Brand<number, "OrderId">;
+
+const toUserId  = (id: string): UserId  => id as UserId;
+const toOrderId = (id: number): OrderId => id as OrderId;
+
+// Usage — prevents accidental id mix-ups at compile time
+function getOrder(userId: UserId, orderId: OrderId) { /* ... */ }
+```
+
+### Discriminated Unions & Type Guards
+```typescript
+type LoadingState = { status: "loading" };
+type SuccessState = { status: "success"; data: string[] };
+type ErrorState   = { status: "error";   error: Error };
+type RequestState = LoadingState | SuccessState | ErrorState;
+
+// Type predicate guard
+function isSuccess(state: RequestState): state is SuccessState {
+  return state.status === "success";
+}
+
+// Exhaustive switch with discriminated union
+function renderState(state: RequestState): string {
+  switch (state.status) {
+    case "loading": return "Loading…";
+    case "success": return state.data.join(", ");
+    case "error":   return state.error.message;
+    default: {
+      const _exhaustive: never = state;
+      throw new Error(`Unhandled state: ${_exhaustive}`);
+    }
+  }
+}
+```
+
+### Custom Utility Types
+```typescript
+// Deep readonly — immutable nested objects
+type DeepReadonly<T> = {
+  readonly [K in keyof T]: T[K] extends object ? DeepReadonly<T[K]> : T[K];
+};
+
+// Require exactly one of a set of keys
+type RequireExactlyOne<T, Keys extends keyof T = keyof T> =
+  Pick<T, Exclude<keyof T, Keys>> &
+  { [K in Keys]-?: Required<Pick<T, K>> & Partial<Record<Exclude<Keys, K>, never>> }[Keys];
+```
+
+### Recommended tsconfig.json
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "isolatedModules": true,
+    "declaration": true,
+    "declarationMap": true,
+    "incremental": true,
+    "skipLibCheck": false
+  }
+}
+```
+
+## Constraints
+
+### MUST DO
+- Enable strict mode with all compiler flags
+- Use type-first API design
+- Implement branded types for domain modeling
+- Use `satisfies` operator for type validation
+- Create discriminated unions for state machines
+- Use `Annotated` pattern with type predicates
+- Generate declaration files for libraries
+- Optimize for type inference
+
+### MUST NOT DO
+- Use explicit `any` without justification
+- Skip type coverage for public APIs
+- Mix type-only and value imports
+- Disable strict null checks
+- Use `as` assertions without necessity
+- Ignore compiler performance warnings
+- Skip declaration file generation
+- Use enums (prefer const objects with `as const`)
+
+## Output Templates
+
+When implementing TypeScript features, provide:
+1. Type definitions (interfaces, types, generics)
+2. Implementation with type guards
+3. tsconfig configuration if needed
+4. Brief explanation of type design decisions
+
+## Knowledge Reference
+
+TypeScript 5.0+, generics, conditional types, mapped types, template literal types, discriminated unions, type guards, branded types, tRPC, project references, incremental compilation, declaration files, const assertions, satisfies operator