langaro-api 1.2.3 → 1.2.4

package/lib/cli/documentation-templates/13-utils.md

@@ -0,0 +1,281 @@
+# Utils
+
+## Role
+
+Utils are **pure utility functions** — small, reusable helpers that don't contain business logic. They handle validation, formatting, date operations, and common transformations.
+
+**What utils do:**
+- Validate input (required fields, field formats)
+- Format data (dates, currencies, strings)
+- Calculate values (taxes, discounts)
+- Provide shared helpers across controllers/services
+
+**What utils do NOT do:**
+- Access the database
+- Call external APIs
+- Contain business logic workflows
+
+---
+
+## Location & Naming
+
+```
+src/utils/
+├── index.js                       # Re-exports common packages + local utils
+├── sleep.js                       # sleep(ms) utility
+├── validate-*.js                  # Validation utilities
+├── format-*.js                    # Formatting utilities
+├── calculate-*.js                 # Calculation utilities
+├── determine-*.js                 # Decision logic
+├── get-*.js                       # Data retrieval helpers
+├── parse-*.js                     # Parsing utilities
+└── factory.js                     # Factory patterns
+```
+
+**Naming convention:** Kebab-case with verb prefix describing the function category.
+
+---
+
+## The Utils Index
+
+`src/utils/index.js` re-exports commonly used packages:
+
+```javascript
+export * from 'validate-required-fields';
+export * from 'trigger-api-error';
+export * from 'http-status-codes';
+export * from 'forbid-fields-sent';
+export * from 'validate-fields-format';
+export * from './sleep';
+```
+
+This allows single-line imports across the codebase:
+
+```javascript
+const {
+  validateRequiredFields,
+  ApiError,
+  StatusCodes,
+  validateFieldsFormat,
+  forbidFieldsSent,
+} = require('@/utils');
+```
+
+---
+
+## Core Validation Utilities
+
+### validateRequiredFields
+
+Validates that required fields are present in the data object. Throws if missing.
+
+```javascript
+const { validateRequiredFields } = require('@/utils');
+
+// Throws if name or email is missing/empty
+validateRequiredFields(data, ['name', 'email', 'company_id']);
+```
+
+From package: `validate-required-fields`
+
+### validateFieldsFormat
+
+Validates field formats (email, phone, array, etc.). Throws if invalid.
+
+```javascript
+const { validateFieldsFormat } = require('@/utils');
+
+validateFieldsFormat([
+  ['email', data.email, 'email field'],
+  ['phone', data.phone, 'phone field'],
+  ['array', data.items, 'items field'],
+  ['date', data.start_date, 'start date field'],
+  ['number', data.amount, 'amount field'],
+]);
+```
+
+From package: `validate-fields-format`
+
+### ApiError
+
+Creates a "safe" error that returns a specific HTTP status and message to the client:
+
+```javascript
+const { ApiError, StatusCodes } = require('@/utils');
+
+// 404 Not Found
+ApiError(StatusCodes.NOT_FOUND, 'User not found');
+
+// 400 Bad Request
+ApiError(StatusCodes.BAD_REQUEST, 'Invalid email format');
+
+// 409 Conflict
+ApiError(StatusCodes.CONFLICT, 'Email already registered');
+
+// 422 Unprocessable Entity
+ApiError(StatusCodes.UNPROCESSABLE_ENTITY, 'Cannot cancel a completed invoice');
+
+// With error code
+ApiError(StatusCodes.FORBIDDEN, 'Insufficient permissions', 'PERM_DENIED');
+
+// Passing to next() in middleware
+ApiError(StatusCodes.UNAUTHORIZED, 'Token expired', undefined, next);
+```
+
+From package: `trigger-api-error`
+
+### forbidFieldsSent
+
+Validates that forbidden fields are not present in the request:
+
+```javascript
+const { forbidFieldsSent } = require('@/utils');
+
+// Throws if any of these fields are in data
+forbidFieldsSent(data, ['role', 'api_key', 'password_hash']);
+```
+
+From package: `forbid-fields-sent`
+
+---
+
+## Common Utility Patterns
+
+### Filter Parsing
+
+Utility for parsing query string filters into andWhere conditions:
+
+```javascript
+// src/utils/parse-and-validate-filters.js
+function parseAndValidateFilters(query, filterOptions) {
+  const andWhere = [];
+
+  if (!filterOptions) return andWhere;
+
+  filterOptions.forEach(filter => {
+    const value = query[filter.name];
+    if (value === undefined) return;
+
+    const column = filter.column || filter.name;
+
+    switch (filter.type) {
+      case 'select_multiple':
+        if (Array.isArray(value)) {
+          andWhere.push([column, 'in', value]);
+        } else {
+          andWhere.push([column, value]);
+        }
+        break;
+      case 'date':
+        if (query[`${filter.name}_start`] && query[`${filter.name}_end`]) {
+          andWhere.push([column, 'between', [
+            query[`${filter.name}_start`],
+            query[`${filter.name}_end`],
+          ]]);
+        }
+        break;
+      case 'integer':
+        if (query[`${filter.name}_min`]) {
+          andWhere.push([column, '>=', query[`${filter.name}_min`]]);
+        }
+        if (query[`${filter.name}_max`]) {
+          andWhere.push([column, '<=', query[`${filter.name}_max`]]);
+        }
+        break;
+      case 'is_not_null':
+        if (value === 'true') andWhere.push([column, '<>', null]);
+        if (value === 'false') andWhere.push([column, null]);
+        break;
+    }
+  });
+
+  return andWhere;
+}
+```
+
+### Security Details Extraction
+
+```javascript
+// src/utils/get-request-security-details.js
+function getRequestSecurityDetails(req) {
+  return {
+    ip_address: req.clientIp,
+    device: req.headers['user-agent'],
+    os: parseOS(req.headers['user-agent']),
+    browser: parseBrowser(req.headers['user-agent']),
+    // Additional geolocation from IP if available
+  };
+}
+```
+
+### Date Utilities
+
+```javascript
+// src/utils/date-fns.js
+const { format, addMinutes, differenceInMilliseconds, parseISO } = require('date-fns');
+const { toZonedTime } = require('date-fns-tz');
+
+module.exports = {
+  format,
+  addMinutes,
+  differenceInMilliseconds,
+  parseISO,
+  toZonedTime,
+  // Re-export for single import point
+};
+```
+
+### Sleep Utility
+
+```javascript
+// src/utils/sleep.js
+exports.sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+```
+
+---
+
+## Creating from Scratch
+
+1. **Create the file:** `src/utils/{verb-noun}.js` (e.g., `validate-document.js`, `format-currency.js`)
+2. **Export the function:**
+   ```javascript
+   function validateDocument(document, type) {
+     // Validation logic
+     if (!isValid) {
+       const { ApiError, StatusCodes } = require('@/utils');
+       ApiError(StatusCodes.BAD_REQUEST, `Invalid ${type}`);
+     }
+     return true;
+   }
+
+   module.exports = { validateDocument };
+   ```
+3. **Import where needed:**
+   ```javascript
+   const { validateDocument } = require('@/utils/validate-document');
+   ```
+4. **Optionally re-export from `utils/index.js`** if the utility is used across many files
+
+---
+
+## Anti-patterns
+
+- **Do NOT put database access in utils.** Utils are pure functions.
+- **Do NOT create utils that depend on `req` or `res`.** Extract data first, then pass to the util.
+- **Do NOT create God utils** (one file with 50+ unrelated functions). Split by category.
+- **Do NOT duplicate validation** that the CRUD layer already does. Use model schemas for field validation.
+- **Do NOT create utils for one-off operations.** Inline the logic if it's only used once.
+
+---
+
+## Checklist
+
+When creating a utility:
+
+- [ ] File is in `src/utils/`
+- [ ] Filename uses kebab-case with verb prefix
+- [ ] Function is pure (no side effects, no database access)
+- [ ] Throws `ApiError` for validation failures (not generic Error)
+- [ ] Exports named functions (not default export)
+- [ ] Added to `utils/index.js` if widely reused
+- [ ] No HTTP-specific logic (`req`, `res`)

package/lib/cli/documentation-templates/14-testing.md

@@ -0,0 +1,315 @@
+# Testing
+
+## Role
+
+Tests validate that services, controllers, and business logic work correctly. The framework provides Jest configuration, test database isolation, and queue mocking out of the box.
+
+---
+
+## Configuration
+
+### Jest Config
+
+```
+Location: jest.config.js
+```
+
+```javascript
+module.exports = {
+  clearMocks: true,
+  coverageDirectory: 'coverage',
+  coverageProvider: 'v8',
+  forceExit: true,
+  globalSetup: '<rootDir>/src/config/tests/global-setup-tests.js',
+  maxWorkers: 4,
+  moduleNameMapper: { '^@/(.*)$': '<rootDir>/src/$1' },
+  setupFilesAfterEnv: ['<rootDir>/src/config/tests/setup-tests.js'],
+  slowTestThreshold: 30,
+  testEnvironment: 'node',
+  testMatch: ['**/src/**/*.spec.js'],
+  transform: { '^.+\\.js$': 'babel-jest' },
+  verbose: true,
+};
+```
+
+**Key settings:**
+- `moduleNameMapper`: Supports `@/` path alias in tests
+- `testMatch`: Test files must be `*.spec.js` inside `src/`
+- `globalSetup`: Runs once before all test suites
+- `setupFilesAfterEnv`: Runs before each test file
+- `maxWorkers: 4`: Limits parallel test runners
+
+### Global Setup
+
+```
+Location: src/config/tests/global-setup-tests.js
+```
+
+Loads `.env.test` for the test environment:
+```javascript
+require('dotenv').config({ path: '.env.test' });
+```
+
+### Test Setup
+
+```
+Location: src/config/tests/setup-tests.js
+```
+
+Adds extended matchers:
+```javascript
+const matchers = require('jest-extended');
+expect.extend(matchers);
+```
+
+---
+
+## Test Database
+
+### Configuration
+
+Create `.env.test` with a separate test database:
+
+```
+NODE_ENV="test"
+DB_HOST="127.0.0.1"
+DB_USER="root"
+DB_PASSWORD=""
+DB_NAME="my_project_tests"   # MUST end with '_tests'
+DB_PORT="3306"
+```
+
+**Critical:** The database name MUST contain `_tests`. The connection factory throws if the test environment tries to use a non-test database.
+
+### Setup
+
+1. Create the test database in MySQL
+2. Run migrations against the test database
+3. Tests use the same schema as production
+
+---
+
+## Queue Mocking
+
+In the test environment (`NODE_ENV=test`), the queue system automatically returns a mock:
+
+```javascript
+// From queues.js initializeQueues:
+if (isTestEnv) {
+  return { add: jest.fn() };
+}
+```
+
+You can assert jobs were queued without actually processing them:
+
+```javascript
+expect(Queue.add).toHaveBeenCalledWith('send-mail', expect.objectContaining({
+  templateName: 'welcome',
+}));
+```
+
+---
+
+## Test File Naming
+
+Test files live next to their source:
+
+```
+src/database/services/
+├── users.services.js
+├── users.services.spec.js    # Tests for users service
+src/controllers/users/
+├── users.controller.js
+├── users.controller.spec.js  # Tests for users controller
+```
+
+**Convention:** `{filename}.spec.js`
+
+---
+
+## Testing Services
+
+```javascript
+// src/database/services/users.services.spec.js
+const { getAppInstance, getQueue } = require('@/config/app');
+const knex = require('@/database/connection')('test');
+
+let services;
+let Queue;
+
+beforeAll(async () => {
+  const app = getAppInstance(knex);
+  await app.readyPromise;
+  Queue = await getQueue(knex);
+
+  // Access services from the app
+  // (exact access pattern depends on project setup)
+});
+
+afterAll(async () => {
+  await knex.destroy();
+});
+
+describe('UsersServices', () => {
+  it('should create a user with permissions', async () => {
+    const result = await services.UsersServices.newUserRegistered({
+      name: 'Test User',
+      email: 'test@example.com',
+      password: 'password123',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.data.id).toBeDefined();
+
+    // Verify permissions were created
+    const { data: permissions } = await services.UsersPermissionsServices.getWhere(
+      'user_id', result.data.id
+    );
+    expect(permissions.length).toBeGreaterThan(0);
+  });
+});
+```
+
+---
+
+## Testing Controllers / Routes
+
+Using supertest:
+
+```javascript
+const request = require('supertest');
+const { getAppInstance } = require('@/config/app');
+const knex = require('@/database/connection')('test');
+
+let app;
+let token;
+
+beforeAll(async () => {
+  const appInstance = getAppInstance(knex);
+  await appInstance.readyPromise;
+  app = appInstance.express;
+
+  // Get auth token
+  const loginResponse = await request(app)
+    .post('/auth/login')
+    .send({ email: 'test@example.com', password: 'password123' });
+  token = loginResponse.body.data.token;
+});
+
+afterAll(async () => {
+  await knex.destroy();
+});
+
+describe('GET /users', () => {
+  it('should return user profile', async () => {
+    const response = await request(app)
+      .get('/users')
+      .set('Authorization', `Bearer ${token}`)
+      .expect(200);
+
+    expect(response.body.data.email).toBe('test@example.com');
+  });
+
+  it('should reject unauthenticated requests', async () => {
+    await request(app)
+      .get('/users')
+      .expect(403);
+  });
+});
+```
+
+---
+
+## Test Data Management
+
+### Transaction Rollback Pattern
+
+Wrap each test in a transaction that rolls back:
+
+```javascript
+let trx;
+
+beforeEach(async () => {
+  trx = await knex.transaction();
+});
+
+afterEach(async () => {
+  await trx.rollback();
+});
+
+it('should create something', async () => {
+  // Use trx for all operations — rolled back after test
+});
+```
+
+### Truncation Pattern
+
+Clean specific tables between tests:
+
+```javascript
+afterEach(async () => {
+  await knex('users').truncate();
+  await knex('companies').truncate();
+});
+```
+
+---
+
+## Scripts
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test file
+npx jest src/database/services/users.services.spec.js
+
+# Watch mode (re-run on file changes)
+npm run test:watch
+
+# With coverage report
+npm run test:coverage
+```
+
+---
+
+## Creating from Scratch
+
+1. **Create the test file:** `{component}.spec.js` next to the component
+2. **Use the template:**
+   ```javascript
+   describe('ComponentName', () => {
+     it('should do something', async () => {
+       // Arrange
+       // Act
+       // Assert
+     });
+   });
+   ```
+3. **Set up test fixtures** (database connection, auth tokens)
+4. **Clean up** in `afterAll` / `afterEach`
+
+---
+
+## Anti-patterns
+
+- **Do NOT test against the production database.** Always use `.env.test` with a `_tests` database.
+- **Do NOT forget `forceExit: true`** — without it, Jest may hang due to open connections.
+- **Do NOT import services directly.** Use the app bootstrap to get properly initialized instances.
+- **Do NOT test CRUD methods directly** (they're tested by knex-extended-crud). Test your custom service methods and controller logic.
+- **Do NOT skip cleanup.** Leftover test data causes flaky tests.
+
+---
+
+## Checklist
+
+When writing tests:
+
+- [ ] Test file is named `{component}.spec.js`
+- [ ] Test file is next to the source file
+- [ ] Uses `.env.test` database (name contains `_tests`)
+- [ ] Database connections destroyed in `afterAll`
+- [ ] Test data cleaned up between tests
+- [ ] Auth tokens obtained via login (not hardcoded)
+- [ ] Queue interactions verified via `jest.fn()` assertions
+- [ ] Tests are independent (don't depend on execution order)