@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/nestjs/testing/references/unit-testing.md

@@ -0,0 +1,179 @@
+# NestJS Unit Testing
+
+## Service Testing
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+
+describe('UsersService', () => {
+  let service: UsersService;
+  let repository: MockType<Repository<User>>;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        UsersService,
+        {
+          provide: getRepositoryToken(User),
+          useFactory: repositoryMockFactory,
+        },
+      ],
+    }).compile();
+
+    service = module.get<UsersService>(UsersService);
+    repository = module.get(getRepositoryToken(User));
+  });
+
+  describe('findOne', () => {
+    it('should return a user', async () => {
+      const user = { id: 1, name: 'John', email: 'john@test.com' };
+      repository.findOne.mockResolvedValue(user);
+
+      const result = await service.findOne(1);
+
+      expect(result).toEqual(user);
+      expect(repository.findOne).toHaveBeenCalledWith({ where: { id: 1 } });
+    });
+
+    it('should throw NotFoundException', async () => {
+      repository.findOne.mockResolvedValue(null);
+
+      await expect(service.findOne(999)).rejects.toThrow(NotFoundException);
+    });
+  });
+});
+
+// Mock factory
+const repositoryMockFactory = () => ({
+  find: jest.fn(),
+  findOne: jest.fn(),
+  save: jest.fn(),
+  create: jest.fn(),
+  update: jest.fn(),
+  delete: jest.fn(),
+});
+
+type MockType<T> = {
+  [P in keyof T]?: jest.Mock;
+};
+```
+
+## Controller Testing
+
+```typescript
+describe('UsersController', () => {
+  let controller: UsersController;
+  let service: UsersService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      controllers: [UsersController],
+      providers: [
+        {
+          provide: UsersService,
+          useValue: {
+            findAll: jest.fn(),
+            findOne: jest.fn(),
+            create: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    controller = module.get<UsersController>(UsersController);
+    service = module.get<UsersService>(UsersService);
+  });
+
+  describe('findAll', () => {
+    it('should return an array of users', async () => {
+      const users = [{ id: 1, name: 'John' }];
+      jest.spyOn(service, 'findAll').mockResolvedValue(users);
+
+      expect(await controller.findAll()).toBe(users);
+    });
+  });
+
+  describe('create', () => {
+    it('should create a user', async () => {
+      const dto = { name: 'John', email: 'john@test.com' };
+      const user = { id: 1, ...dto };
+      jest.spyOn(service, 'create').mockResolvedValue(user);
+
+      expect(await controller.create(dto)).toBe(user);
+      expect(service.create).toHaveBeenCalledWith(dto);
+    });
+  });
+});
+```
+
+## Mocking Patterns
+
+```typescript
+// Mock entire module
+jest.mock('../services/email.service');
+
+// Partial mock
+jest.mock('../services/email.service', () => ({
+  ...jest.requireActual('../services/email.service'),
+  sendEmail: jest.fn(),
+}));
+
+// Spy on method
+const spy = jest.spyOn(service, 'method');
+spy.mockResolvedValue(result);
+
+// Mock implementation
+mockService.method.mockImplementation((arg) => {
+  return arg === 'special' ? specialResult : defaultResult;
+});
+
+// Reset mocks
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+```
+
+## E2E Testing
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { INestApplication } from '@nestjs/common';
+import * as request from 'supertest';
+
+describe('UsersController (e2e)', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('/users (GET)', () => {
+    return request(app.getHttpServer())
+      .get('/users')
+      .expect(200)
+      .expect((res) => {
+        expect(Array.isArray(res.body)).toBe(true);
+      });
+  });
+
+  it('/users (POST)', () => {
+    return request(app.getHttpServer())
+      .post('/users')
+      .send({ name: 'John', email: 'john@test.com' })
+      .expect(201)
+      .expect((res) => {
+        expect(res.body).toHaveProperty('id');
+        expect(res.body.name).toBe('John');
+      });
+  });
+});
+```

package/rules/nestjs/transport/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: NestJS Microservices
+description: gRPC, RabbitMQ standards and Monorepo contracts.
+metadata:
+  labels: [nestjs, microservices, grpc, rabbitmq]
+  triggers:
+    files: ['main.ts', '**/*.controller.ts']
+    keywords: [Transport.GRPC, Transport.RMQ, MicroserviceOptions]
+---
+
+# Microservices & Transport Standards
+
+## Transport Strategies
+
+- **Synchronous (RPC)**: Use **gRPC** for low-latency, internal service-to-service calls.
+  - **Why**: 10x faster than REST/JSON, centralized `.proto` contracts.
+- **Asynchronous (Events)**: Use **RabbitMQ** or **Kafka** for decoupling domains.
+  - **Pattern**: Fire-and-forget (`emit()`) for side effects (e.g., "UserCreated" -> "SendEmail").
+
+## Monorepo Architecture
+
+- **Contracts**:
+  - **Pattern**: Store all DTOs, `.proto` files, and Interfaces in a **Shared Library** (`libs/contracts`).
+  - **Rule**: Services never import code from other services. They only import from `contracts`.
+- **Versioning**: Semantic versioning of messages is mandatory. Never change a field type; add a new field.
+
+## Exception Handling
+
+- **Propagation**: Standard `HttpException` is lost over Rpc/Tcp.
+- **Standard**: Use `RpcException` and generic Filters.
+
+  ```typescript
+  // Global RPC Filter
+  @Catch()
+  export class RpcExceptionFilter implements RpcExceptionFilter<RpcException> {
+    catch(exception: RpcException, host: ArgumentsHost): Observable<any> {
+      return throwError(() => exception.getError());
+    }
+  }
+  ```
+
+## Serialization
+
+- **Message DTOs**: Use `class-validator` just like HTTP.
+  - **Config**: Apply `useGlobalPipes(new ValidationPipe({ transform: true }))` in the `MicroserviceOptions` setup, not just HTTP app setup.

package/rules/nestjs/transport/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# NestJS Transport References
+
+## References
+
+- [**Microservices Patterns**](microservices-patterns.md) - TCP, Redis, RabbitMQ, Kafka, gRPC
+
+## Quick Checks
+
+- [ ] Choose appropriate transport for use case
+- [ ] Implement proper error handling
+- [ ] Use message patterns consistently
+- [ ] Configure retries and timeouts
+- [ ] Monitor message processing

package/rules/nestjs/transport/references/microservices-patterns.md

@@ -0,0 +1,170 @@
+# NestJS Microservices Transport Patterns
+
+## TCP Transport
+
+```typescript
+// Microservice
+import { NestFactory } from '@nestjs/core';
+import { Transport, MicroserviceOptions } from '@nestjs/microservices';
+
+async function bootstrap() {
+  const app = await NestFactory.createMicroservice<MicroserviceOptions>(
+    AppModule,
+    {
+      transport: Transport.TCP,
+      options: { host: '0.0.0.0', port: 3001 },
+    },
+  );
+  await app.listen();
+}
+
+// Handler
+@Controller()
+export class AppController {
+  @MessagePattern({ cmd: 'get_user' })
+  getUser(data: { id: string }) {
+    return this.userService.findOne(data.id);
+  }
+
+  @EventPattern('user_created')
+  handleUserCreated(data: User) {
+    console.log('User created:', data);
+  }
+}
+
+// Client
+@Injectable()
+export class ClientService {
+  constructor(
+    @Inject('USER_SERVICE') private client: ClientProxy,
+  ) {}
+
+  getUser(id: string) {
+    return this.client.send({ cmd: 'get_user' }, { id });
+  }
+
+  emitUserCreated(user: User) {
+    this.client.emit('user_created', user);
+  }
+}
+```
+
+## Redis Transport
+
+```typescript
+// Configuration
+{
+  transport: Transport.REDIS,
+  options: {
+    host: 'localhost',
+    port: 6379,
+  },
+}
+
+// Module registration
+@Module({
+  imports: [
+    ClientsModule.register([{
+      name: 'REDIS_SERVICE',
+      transport: Transport.REDIS,
+      options: { host: 'localhost', port: 6379 },
+    }]),
+  ],
+})
+```
+
+## RabbitMQ Transport
+
+```typescript
+// Configuration
+{
+  transport: Transport.RMQ,
+  options: {
+    urls: ['amqp://localhost:5672'],
+    queue: 'orders_queue',
+    queueOptions: { durable: true },
+  },
+}
+
+// Handler with acknowledgment
+@MessagePattern('process_order')
+async processOrder(@Payload() data: Order, @Ctx() context: RmqContext) {
+  const channel = context.getChannelRef();
+  const originalMsg = context.getMessage();
+
+  try {
+    await this.orderService.process(data);
+    channel.ack(originalMsg);
+  } catch (error) {
+    channel.nack(originalMsg);
+  }
+}
+```
+
+## Kafka Transport
+
+```typescript
+// Configuration
+{
+  transport: Transport.KAFKA,
+  options: {
+    client: {
+      brokers: ['localhost:9092'],
+    },
+    consumer: {
+      groupId: 'orders-consumer',
+    },
+  },
+}
+
+// Handler
+@MessagePattern('orders.created')
+handleOrderCreated(@Payload() message: Order, @Ctx() context: KafkaContext) {
+  const { offset, partition } = context.getMessage();
+  console.log(`Processing offset ${offset} from partition ${partition}`);
+  return this.orderService.process(message);
+}
+```
+
+## gRPC Transport
+
+```typescript
+// Configuration
+{
+  transport: Transport.GRPC,
+  options: {
+    package: 'hero',
+    protoPath: join(__dirname, 'hero.proto'),
+    url: 'localhost:5000',
+  },
+}
+
+// Service implementation
+@GrpcMethod('HeroService', 'FindOne')
+findOne(data: { id: number }): Hero {
+  return this.heroService.findOne(data.id);
+}
+
+// Streaming
+@GrpcStreamMethod('HeroService', 'FindMany')
+findMany(data$: Observable<HeroById>): Observable<Hero> {
+  return data$.pipe(
+    mergeMap(({ id }) => this.heroService.findOne(id)),
+  );
+}
+```
+
+## Hybrid Application
+
+```typescript
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  // HTTP
+  app.connectMicroservice({ transport: Transport.TCP, options: { port: 3001 } });
+  app.connectMicroservice({ transport: Transport.REDIS, options: { host: 'localhost' } });
+
+  await app.startAllMicroservices();
+  await app.listen(3000);
+}
+```

package/rules/nextjs/app-router/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: Next.js App Router
+description: File-system routing, Layouts, and Route Groups.
+metadata:
+  labels: [nextjs, routing, app-router]
+  triggers:
+    files: ['app/**/page.tsx', 'app/**/layout.tsx', 'app/**/loading.tsx']
+    keywords: [App Router, Layout, Route Group, parallel routes]
+---
+
+# Next.js App Router
+
+## **Priority: P0 (CRITICAL)**
+
+Use the App Router (`app/` directory) for all new projects.
+
+## File Conventions
+
+- **page.tsx**: The UI for a route.
+- **layout.tsx**: Shared UI wrapping children. Persists across navigation.
+- **template.tsx**: Similar to layout, but remounts on navigation.
+- **loading.tsx**: Suspense boundary for loading states.
+- **error.tsx**: Error boundary (Must be Client Component).
+- **not-found.tsx**: Custom 404 UI.
+- **route.ts**: Server-side API endpoint.
+
+## Structure Patterns
+
+- **Route Groups**: Use parenthesis `(auth)` to organize routes without affecting URL path.
+  - `app/(auth)/login/page.tsx` -> `/login`
+- **Private Folders**: Use underscore `_lib` to exclude folders from routing.
+- **Dynamic Routes**: Use brackets `[slug]`.
+  - `app/blog/[slug]/page.tsx` -> `/blog/abc`
+- **Catch-all**: `[...slug]` matches subsequent segments.
+
+## Navigation
+
+- **Link Component**: Use `<Link href="/dashboard">` for prefetching.
+- **Programmatic**: Use `useRouter` hook (Client Components only).
+  - `router.push('/dashboard')`
+- **Redirect**: Use `redirect('/login')` in Server Components.
+
+## Best Practices
+
+- **Colocation**: Keep component files, styles, and tests inside the route folder.
+- **Layouts**: Use Root Layout (`app/layout.tsx`) for `<html>` and `<body>` tags.

package/rules/nextjs/app-router/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# Next.js App Router References
+
+## References
+
+- [**Routing Patterns**](routing-patterns.md) - Routes, layouts, loading, error
+- [**Navigation**](navigation.md) - Link, useRouter, redirects
+
+## Quick Checks
+
+- [ ] Use folder-based routing
+- [ ] Layouts for shared UI
+- [ ] loading.tsx for suspense
+- [ ] error.tsx for error boundaries
+- [ ] Route groups for organization

package/rules/nextjs/app-router/references/routing-patterns.md

@@ -0,0 +1,182 @@
+# Next.js App Router Patterns
+
+## File Conventions
+
+```
+app/
+├── layout.tsx          # Root layout (required)
+├── page.tsx            # Home page (/)
+├── loading.tsx         # Loading UI
+├── error.tsx           # Error boundary
+├── not-found.tsx       # 404 page
+├── users/
+│   ├── page.tsx        # /users
+│   ├── [id]/
+│   │   └── page.tsx    # /users/:id
+│   └── [...slug]/
+│       └── page.tsx    # /users/* (catch-all)
+├── (marketing)/        # Route group (no URL impact)
+│   ├── about/
+│   └── contact/
+└── @modal/             # Parallel route
+    └── login/
+```
+
+## Layouts
+
+```tsx
+// app/layout.tsx - Root layout
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <Header />
+        <main>{children}</main>
+        <Footer />
+      </body>
+    </html>
+  );
+}
+
+// app/dashboard/layout.tsx - Nested layout
+export default function DashboardLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="dashboard">
+      <Sidebar />
+      <div className="content">{children}</div>
+    </div>
+  );
+}
+```
+
+## Dynamic Routes
+
+```tsx
+// app/users/[id]/page.tsx
+export default async function UserPage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = await params;
+  const user = await getUser(id);
+  return <UserProfile user={user} />;
+}
+
+// Generate static params
+export async function generateStaticParams() {
+  const users = await getUsers();
+  return users.map((user) => ({ id: user.id }));
+}
+
+// Catch-all routes
+// app/docs/[...slug]/page.tsx
+export default async function DocsPage({
+  params,
+}: {
+  params: Promise<{ slug: string[] }>;
+}) {
+  const { slug } = await params;
+  // slug = ['getting-started', 'installation']
+  // for /docs/getting-started/installation
+}
+```
+
+## Loading & Error States
+
+```tsx
+// app/users/loading.tsx
+export default function Loading() {
+  return <UsersSkeleton />;
+}
+
+// app/users/error.tsx
+'use client';
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error;
+  reset: () => void;
+}) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <button onClick={() => reset()}>Try again</button>
+    </div>
+  );
+}
+
+// app/users/not-found.tsx
+export default function NotFound() {
+  return <div>User not found</div>;
+}
+```
+
+## Route Groups
+
+```
+app/
+├── (auth)/
+│   ├── layout.tsx      # Auth layout (no header)
+│   ├── login/
+│   └── register/
+├── (main)/
+│   ├── layout.tsx      # Main layout (with header)
+│   ├── dashboard/
+│   └── settings/
+```
+
+## Parallel Routes
+
+```tsx
+// app/layout.tsx
+export default function Layout({
+  children,
+  modal,
+}: {
+  children: React.ReactNode;
+  modal: React.ReactNode;
+}) {
+  return (
+    <>
+      {children}
+      {modal}
+    </>
+  );
+}
+
+// app/@modal/login/page.tsx
+export default function LoginModal() {
+  return <Modal><LoginForm /></Modal>;
+}
+
+// app/@modal/default.tsx
+export default function Default() {
+  return null;
+}
+```
+
+## Intercepting Routes
+
+```
+app/
+├── feed/
+│   └── page.tsx
+├── photo/
+│   └── [id]/
+│       └── page.tsx      # Full page view
+├── @modal/
+│   └── (.)photo/
+│       └── [id]/
+│           └── page.tsx  # Intercepted modal view
+```

package/rules/nextjs/architecture/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: Next.js Architecture (FSD)
+description: Scalable project structure using Feature-Sliced Design (FSD).
+metadata:
+  labels: [nextjs, architecture, fsd, folder-structure]
+  triggers:
+    files: ['src/features/**', 'src/entities/**', 'src/widgets/**']
+    keywords: [FSD, Feature Sliced Design, slices, segments]
+---
+
+# Architecture (Feature-Sliced Design)
+
+## **Priority: P2 (MEDIUM)**
+
+Adopt **Feature-Sliced Design (FSD)** for scalable applications.
+**Warning**: FSD introduces boilerplate. Use it only if the project is expected to grow significantly (e.g., 20+ features). For smaller projects, a simple module-based structure is preferred.
+
+## Strategy
+
+1. **App Layer is Thin**: The `app/` directory (App Router) is **only** for Routing.
+   - _Rule_: `page.tsx` should only import Widgets/Features. No business logic (`useEffect`, `fetch`) directly in pages.
+2. **Slices over Types**: Group code by **Business Domain** (User, Product, Cart), not by File Type (Components, Hooks, Utils).
+   - _Bad_: `src/components/LoginForm.tsx`, `src/hooks/useLogin.ts`
+   - _Good_: `src/features/auth/login/` containing both.
+3. **Layer Hierarchy**: Code can only import from _layers below it_.
+   - `App` -> `Widgets` -> `Features` -> `Entities` -> `Shared`.
+4. **Avoid Excessive Entities**: Do not preemptively create Entities.
+   - _Rule_: Start logic in `Features` or `Pages`. Move to `Entities` **only** when data/logic is strictly reused across multiple differing features.
+   - _Rule_: Simple CRUD belongs in `shared/api`, not `entities`.
+5. **Standard Segments**: Use standard segment names within slices.
+   - `ui` (Components), `model` (State/actions), `api` (Data fetching), `lib` (Helpers), `config` (Constants).
+   - _Avoid_: `components`, `hooks`, `services` as segment names.
+
+## Structure Reference
+
+For the specific directory layout and layer definitions, see the reference documentation.
+
+- [**FSD Folder Structure**](references/fsd-structure.md)
+
+## Integration with Next.js Core
+
+- **Server Actions**: Place them in the `model/` folder of a Feature (e.g., `features/auth/model/actions.ts`).
+- **Data Access (DAL)**: Place logic in the `model/` folder of an Entity (e.g., `entities/user/model/dal.ts`).
+- **UI Components**: Base UI (shadcn) belongs in `shared/ui`. Feature-specific UI belongs in `features/*/ui`.