@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/javascript/best-practices/references/REFERENCE.md

@@ -0,0 +1,91 @@
+# JavaScript Best Practices Reference
+
+Module patterns and project organization.
+
+## References
+
+- [**Module Patterns**](module-patterns.md) - ES6 modules and organization.
+- [**Project Structure**](project-structure.md) - Directory organization.
+
+## Module Patterns
+
+```javascript
+// Public API with index.js
+// src/users/index.js
+export { UserService } from './user-service.js';
+export { UserRepository } from './user-repository.js';
+export { createUser, updateUser } from './user-operations.js';
+
+// Private implementation
+// src/users/user-service.js
+import { UserRepository } from './user-repository.js';
+import { validateUser } from './validators.js';
+
+export class UserService {
+  constructor(repository = new UserRepository()) {
+    this.repository = repository;
+  }
+
+  async createUser(data) {
+    validateUser(data);
+    return this.repository.save(data);
+  }
+}
+
+// Singleton pattern
+// src/utils/logger.js
+class Logger {
+  #instance;
+
+  constructor() {
+    if (Logger.#instance) {
+      return Logger.#instance;
+    }
+    Logger.#instance = this;
+  }
+
+  log(message) {
+    console.log(`[${new Date().toISOString()}] ${message}`);
+  }
+}
+
+export const logger = new Logger();
+```
+
+## Project Structure
+
+```
+src/
+├── domain/           # Business logic
+│   └── user/
+│       ├── user.js
+│       └── user-repository.js
+├── services/         # Application services
+│   └── user-service.js
+├── utils/            # Utilities
+│   ├── logger.js
+│   └── validation.js
+├── config/           # Configuration
+│   └── database.js
+└── index.js          # Entry point
+```
+
+## Configuration Management
+
+```javascript
+// config/index.js
+const config = {
+  development: {
+    apiUrl: 'http://localhost:3000',
+    logLevel: 'debug',
+  },
+  production: {
+    apiUrl: process.env.API_URL,
+    logLevel: 'error',
+  },
+};
+
+const env = process.env.NODE_ENV || 'development';
+
+export default config[env];
+```

package/rules/javascript/language/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: JavaScript Language Patterns
+description: Modern JavaScript (ES2022+) patterns for clean, maintainable code.
+metadata:
+  labels: [javascript, language, es6, modern-js]
+  triggers:
+    files: ['**/*.js', '**/*.mjs', '**/*.cjs']
+    keywords:
+      [const, let, arrow, async, await, promise, destructuring, spread, class]
+---
+
+# JavaScript Language Patterns
+
+## **Priority: P0 (CRITICAL)**
+
+Modern JavaScript standards for clean, maintainable code.
+
+## Implementation Guidelines
+
+- **Variables**: `const` default. `let` if needed. No `var`.
+- **Functions**: Arrows for callbacks. Declarations for top-level.
+- **Async**: `async/await` + `try/catch`.
+- **Objects**: Destructuring, Spread `...`, Optional Chain `?.`, Nullish `??`.
+- **Strings**: Template literals `${}`.
+- **Arrays**: `map`, `filter`, `reduce`. No loops.
+- **Modules**: ESM `import`/`export`.
+- **Classes**: Use `#private` fields.
+
+## Anti-Patterns
+
+- **No `var`**: Block scope only.
+- **No `==`**: Strict `===`.
+- **No `new Object()`**: Use literals `{}`.
+- **No Callbacks**: Promisify everything.
+- **No Mutation**: Immutability first.
+
+## Code
+
+```javascript
+// Modern Syntax
+const [x, ...rest] = items;
+const name = user?.profile?.name ?? 'Guest';
+
+// Async
+async function getUser(id) {
+  try {
+    const res = await fetch(`/api/${id}`);
+    return res.json();
+  } catch (err) {
+    console.error(err);
+    throw err;
+  }
+}
+
+// Class + Private
+class Service {
+  #key;
+  constructor(k) {
+    this.#key = k;
+  }
+}
+```
+
+## Reference & Examples
+
+For advanced patterns and functional programming:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+best-practices | tooling

package/rules/javascript/language/references/REFERENCE.md

@@ -0,0 +1,106 @@
+# JavaScript Language Patterns Reference
+
+Advanced patterns and functional programming techniques.
+
+## References
+
+- [**Functional Programming**](functional-programming.md) - Immutability and pure functions.
+- [**Promises & Async**](promises-async.md) - Advanced async patterns.
+
+## Functional Programming Patterns
+
+```javascript
+// Pure functions
+const add = (a, b) => a + b;
+const multiply = (a, b) => a * b;
+
+// Function composition
+const compose = (...fns) => x => fns.reduceRight((v, f) => f(v), x);
+const pipe = (...fns) => x => fns.reduce((v, f) => f(v), x);
+
+// Example usage
+const addOne = x => x + 1;
+const double = x => x * 2;
+const addOneThenDouble = pipe(addOne, double);
+console.log(addOneThenDouble(3)); // 8
+
+// Immutable data updates
+const updateUser = (user, updates) => ({
+  ...user,
+  ...updates,
+  updatedAt: new Date(),
+});
+
+// Deep cloning
+const deepClone = obj => structuredClone(obj);
+
+// Currying
+const curry = (fn) => {
+  return function curried(...args) {
+    if (args.length >= fn.length) {
+      return fn.apply(this, args);
+    }
+    return (...args2) => curried.apply(this, args.concat(args2));
+  };
+};
+
+const add3 = curry((a, b, c) => a + b + c);
+console.log(add3(1)(2)(3)); // 6
+console.log(add3(1, 2)(3)); // 6
+```
+
+## Advanced Async Patterns
+
+```javascript
+// Promise.all for parallel execution
+async function fetchAllUsers(ids) {
+  const promises = ids.map(id => fetch(`/api/users/${id}`));
+  const responses = await Promise.all(promises);
+  return Promise.all(responses.map(r => r.json()));
+}
+
+// Promise.allSettled for handling partial failures
+async function fetchWithFallback(urls) {
+  const results = await Promise.allSettled(
+    urls.map(url => fetch(url))
+  );
+  
+  return results
+    .filter(result => result.status === 'fulfilled')
+    .map(result => result.value);
+}
+
+// Retry with exponential backoff
+async function retryWithBackoff(fn, maxRetries = 3, baseDelay = 1000) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (i === maxRetries - 1) throw error;
+      const delay = baseDelay * Math.pow(2, i);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+}
+
+// Debounce
+function debounce(fn, delay) {
+  let timeoutId;
+  return (...args) => {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => fn(...args), delay);
+  };
+}
+
+// Throttle
+function throttle(fn, limit) {
+  let inThrottle;
+  return (...args) => {
+    if (!inThrottle) {
+      fn(...args);
+      inThrottle = true;
+      setTimeout(() => inThrottle = false, limit);
+    }
+  };
+}
+```

package/rules/javascript/tooling/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: JavaScript Tooling
+description: Development tools, linting, and testing for JavaScript projects.
+metadata:
+  labels: [tooling, javascript, eslint, prettier, testing]
+  triggers:
+    files: ['.eslintrc.*', 'jest.config.*', 'package.json']
+    keywords: [eslint, prettier, jest, test, lint, build]
+---
+
+# JavaScript Tooling
+
+## **Priority: P1 (OPERATIONAL)**
+
+Essential tooling for JavaScript development.
+
+## Implementation Guidelines
+
+- **Linting**: ESLint (Rec + Prettier). Fix on save.
+- **Formatting**: Prettier. Run on save/commit.
+- **Testing**: Jest/Vitest. Co-locate tests. >80% cov.
+- **Build**: Vite (Apps), Rollup (Libs).
+- **Pkg Manager**: Sync versions (`npm`/`yarn`/`pnpm`).
+
+## Anti-Patterns
+
+- **No Formatting Wars**: Prettier rules.
+- **No Untested Code**: TDD/Post-code tests.
+- **No Dirty Commits**: Lint before push.
+
+## Configuration
+
+```javascript
+// .eslintrc.js
+module.exports = {
+  extends: ['eslint:recommended', 'prettier'],
+  rules: { 'no-console': 'warn', 'prefer-const': 'error' },
+};
+```
+
+```json
+// .prettierrc
+{ "semi": true, "singleQuote": true, "printWidth": 80 }
+```
+
+```javascript
+// jest.config.js
+export default {
+  coverageThreshold: { global: { lines: 80 } },
+};
+```
+
+## Reference & Examples
+
+For testing patterns and CI/CD:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+best-practices | language

package/rules/javascript/tooling/references/REFERENCE.md

@@ -0,0 +1,107 @@
+# JavaScript Tooling Reference
+
+Testing patterns and CI/CD configuration.
+
+## References
+
+- [**Testing Patterns**](testing-patterns.md) - Unit and integration testing.
+- [**CI/CD**](ci-cd.md) - Continuous integration setup.
+
+## Jest Testing Patterns
+
+```javascript
+// user-service.test.js
+import { UserService } from './user-service.js';
+
+describe('UserService', () => {
+  let service;
+  let mockRepository;
+
+  beforeEach(() => {
+    mockRepository = {
+      findById: jest.fn(),
+      save: jest.fn(),
+    };
+    service = new UserService(mockRepository);
+  });
+
+  describe('createUser', () => {
+    it('should create a user with valid data', async () => {
+      const userData = { name: 'John', email: 'john@example.com' };
+      mockRepository.save.mockResolvedValue({ id: '1', ...userData });
+
+      const result = await service.createUser(userData);
+
+      expect(result).toEqual({ id: '1', ...userData });
+      expect(mockRepository.save).toHaveBeenCalledWith(userData);
+    });
+
+    it('should throw error for invalid data', async () => {
+      const invalidData = { name: '' };
+
+      await expect(service.createUser(invalidData))
+        .rejects
+        .toThrow('Name is required');
+    });
+  });
+});
+```
+
+## Integration Testing
+
+```javascript
+// api.integration.test.js
+import request from 'supertest';
+import { app } from '../app.js';
+
+describe('User API', () => {
+  it('GET /api/users/:id returns user', async () => {
+    const response = await request(app)
+      .get('/api/users/1')
+      .expect(200);
+
+    expect(response.body).toHaveProperty('id', '1');
+    expect(response.body).toHaveProperty('name');
+  });
+
+  it('POST /api/users creates user', async () => {
+    const newUser = { name: 'Jane', email: 'jane@example.com' };
+
+    const response = await request(app)
+      .post('/api/users')
+      .send(newUser)
+      .expect(201);
+
+    expect(response.body).toHaveProperty('id');
+    expect(response.body.name).toBe(newUser.name);
+  });
+});
+```
+
+## GitHub Actions CI
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    strategy:
+      matrix:
+        node-version: [18, 20]
+    
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test -- --coverage
+      - run: npm run build
+```

package/rules/metadata.json

@@ -0,0 +1,54 @@
+{
+  "global": {
+    "author": "Minh",
+    "repository": "https://github.com/ngxtm/ags"
+  },
+  "categories": {
+    "flutter": {
+      "version": "1.1.0",
+      "last_updated": "2026-01-19",
+      "tag_prefix": "flutter-v"
+    },
+    "dart": {
+      "version": "1.0.1",
+      "last_updated": "2026-01-17",
+      "tag_prefix": "dart-v"
+    },
+    "typescript": {
+      "version": "1.0.0",
+      "last_updated": "2026-01-17",
+      "tag_prefix": "typescript-v"
+    },
+    "javascript": {
+      "version": "1.0.0",
+      "last_updated": "2026-01-17",
+      "tag_prefix": "javascript-v"
+    },
+    "react": {
+      "version": "1.0.0",
+      "last_updated": "2026-01-17",
+      "tag_prefix": "react-v"
+    },
+    "nestjs": {
+      "version": "1.0.0",
+      "last_updated": "2026-01-17",
+      "tag_prefix": "nestjs-v"
+    },
+    "rust": {
+      "version": "1.1.0",
+      "last_updated": "2026-01-20",
+      "tag_prefix": "rust-v"
+    },
+    "golang": {
+      "version": "1.1.0",
+      "last_updated": "2026-01-20",
+      "tag_prefix": "golang-v"
+    },
+    "nextjs": {
+      "version": "1.0.0",
+      "last_updated": "2026-01-18",
+      "tag_prefix": "nextjs-v"
+    },
+    "angular": {}
+  }
+}

package/rules/nestjs/api-standards/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: NestJS API Standards
+description: Response wrapping, pagination, and error standardization.
+metadata:
+  labels: [nestjs, api, pagination, response]
+  triggers:
+    files: ['**/*.controller.ts', '**/*.dto.ts']
+    keywords: [ApiResponse, Pagination, TransformInterceptor]
+---
+
+# NestJS API Standards & Common Patterns
+
+## Generic Response Wrapper
+
+- **Concept**: Standardize all successful API responses.
+- **Implementation**: Use `TransformInterceptor` to wrap data in `{ statusCode, data, meta }`.
+
+## Pagination Standards (Pro)
+
+- **DTOs**: Use strict `PageOptionsDto` (page/take/order) and `PageDto<T>` (data/meta).
+- **Swagger Logic**: Generics require `ApiExtraModels` and schema path resolution.
+- **Reference**: See [Pagination Wrapper Implementation](references/pagination-wrapper.md) for the complete `ApiPaginatedResponse` decorator code.
+
+## Custom Error Response
+
+- **Standard Error Object**:
+
+  ```typescript
+  export class ApiErrorResponse {
+    @ApiProperty()
+    statusCode: number;
+
+    @ApiProperty()
+    message: string;
+
+    @ApiProperty()
+    error: string;
+
+    @ApiProperty()
+    timestamp: string;
+
+    @ApiProperty()
+    path: string;
+  }
+  ```
+
+- **Docs**: Apply `@ApiBadRequestResponse({ type: ApiErrorResponse })` globally or per controller.

package/rules/nestjs/api-standards/references/pagination-wrapper.md

@@ -0,0 +1,87 @@
+# NestJS API Standards Patterns
+
+## Generic Response & Pagination
+
+This reference implements the standard `PageDto`, `PageMetaDto`, and the `ApiPaginatedResponse` decorator for Swagger.
+
+### Page Options DTO
+
+Standard query parameters for list endpoints.
+
+```typescript
+// dtos/page-options.dto.ts
+export class PageOptionsDto {
+  @ApiPropertyOptional({ enum: Order, default: Order.ASC })
+  @IsEnum(Order)
+  @IsOptional()
+  readonly order?: Order = Order.ASC;
+
+  @ApiPropertyOptional({ minimum: 1, default: 1 })
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  readonly page?: number = 1;
+
+  @ApiPropertyOptional({ minimum: 1, maximum: 50, default: 10 })
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(50)
+  readonly take?: number = 10;
+
+  get skip(): number {
+    return (this.page - 1) * this.take;
+  }
+}
+```
+
+### Page DTO
+
+Generic wrapper for paginated data.
+
+```typescript
+// dtos/page.dto.ts
+export class PageDto<T> {
+  @ApiProperty({ isArray: true })
+  readonly data: T[];
+
+  @ApiProperty({ type: () => PageMetaDto })
+  readonly meta: PageMetaDto;
+
+  constructor(data: T[], meta: PageMetaDto) {
+    this.data = data;
+    this.meta = meta;
+  }
+}
+```
+
+### Swagger Decorator
+
+Magical decorator to expose `PageDto<UserDto>` correctly in Swagger UI.
+
+```typescript
+// decorators/api-paginated-response.decorator.ts
+export const ApiPaginatedResponse = <TModel extends Type<any>>(
+  model: TModel,
+) => {
+  return applyDecorators(
+    ApiExtraModels(PageDto, model),
+    ApiOkResponse({
+      description: 'Successfully received model list',
+      schema: {
+        allOf: [
+          { $ref: getSchemaPath(PageDto) },
+          {
+            properties: {
+              data: {
+                type: 'array',
+                items: { $ref: getSchemaPath(model) },
+              },
+            },
+          },
+        ],
+      },
+    }),
+  );
+};
+```

package/rules/nestjs/architecture/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: NestJS Architecture
+description: Module organization, Dependency Injection patterns, and Project Structure.
+metadata:
+  labels: [nestjs, architecture, modularity]
+  triggers:
+    files: ['**/*.module.ts', 'main.ts']
+    keywords: [Module, forRoot, forFeature, Dependency Injection]
+---
+
+# NestJS Architecture Standards
+
+## Core Principles
+
+1. **Modularity**: Every feature **must** be encapsulated in its own `@Module`.
+   - **Do**: `users.module.ts`, `auth.module.ts`.
+   - **Don't**: Everything in `app.module.ts`.
+2. **Dependency Injection (DI)**: Invert control. Never manually instantiate classes (e.g., `new Service()`).
+   - **Use**: Constructor injection `constructor(private readonly service: Service)`.
+3. **Scalability**: Use **Feature Modules** for domain logic and **Core/Shared Modules** for reusable utilities.
+
+## Module Configuration
+
+### Dynamic Modules
+
+- **Modern Pattern**: Use `ConfigurableModuleBuilder` class to auto-generate `forRoot`/`register` methods properly.
+- **Reference**: See [Dynamic Module Builder Implementation](references/dynamic-module.md) for the boilerplate code.
+  - **Conventions**:
+    - `forRoot`: Global configurations (Db, Config).
+    - `register`: Per-instance configurations.
+    - `forFeature`: Extending a module with specific providers/entities.
+
+### Circular Dependencies
+
+- **Avoid**: Re-architect to move shared logic to a common module.
+- **Constraint**: If unavoidable, use `forwardRef(() => ModuleName)` on **both** sides of the import.
+
+## Advanced Providers
+
+- **Factory Providers**: Use `useFactory` heavily for providers dependent on configuration or async operations.
+- **Aliasing**: Use `useExisting` to provide backward compatibility or abstract different implementations.
+
+## Scopes & Lifecycle
+
+- **Default**: **Singleton**. Best performance.
+- **Request Scope**: Use `Scope.REQUEST` sparingly.
+  - **Performance Warning**: Request scope **bubbles up**. If a Service is request-scoped, every controller injecting it becomes request-scoped, triggering re-instantiation per request (~5-10% latency overhead).
+- **Multi-tenancy**: If request-scope is needed (e.g. Tenant ID header), use **Durable Providers** (`durable: true`) with `ContextIdFactory` to reuse DI sub-trees.
+- **Shutdown**: `SIGTERM` doesn't trigger cleanup by default.
+  - **Mandatory**: Call `app.enableShutdownHooks()` in `main.ts`.
+
+## Structure & Organization
+
+- **Feature Modules**: Domain logic (`ShopModule`, `AuthModule`). Encapsulated.
+- **Shared Module**: Reusable providers (`DateService`, `MathService`) exported to other modules. **Stateless**.
+- **Core Module**:
+  - **Role**: Global infrastructure setup ONE TIME (Interceptors, Filters, Loggers).
+  - **Rule**: Import `CoreModule` **only** in `AppModule`.
+  - **Contents**: `APP_INTERCEPTOR`, `APP_FILTER`, `APP_GUARD` providers.
+
+## Reliability & Observability
+
+- **Health Checks**: Mandatory for K8s/Docker.
+  - **Tool**: Use `@nestjs/terminus`. Expose `/health` endpoint checking DB, Cache (Redis), and Memory.
+- **Structured Logging**:
+  - **Warning**: Default NestJS logger is unstructured text.
+  - **Standard**: Use `nestjs-pino` for JSON-formatted logs with automatic `req-id` correlation and request duration tracking.
+  - **Context**: Inject `Logger` into services to keep traces connected.