feat: added copilot instructions

Author: sethii

.github/copilot-instructions.md

@@ -0,0 +1,112 @@
+# Coding Guidelines for Node.js/TypeScript Boilerplate
+
+## Project Overview
+
+This repository is a boilerplate for building Node.js applications using TypeScript, following best practices and architectural patterns. It is designed to be a starting point for new projects, providing a solid foundation with modern development tools and methodologies.
+
+## Code Architecture
+
+### Key Patterns
+- **CQRS (Command Query Responsibility Segregation)**: Separates read and write operations for better scalability and maintainability.
+- **Dependency Injection**: Uses Awilix for managing dependencies, promoting loose coupling and easier testing.
+- **Event-driven architecture**: Utilizes an event dispatcher for handling domain events, enabling asynchronous processing and decoupling of components.
+- **Feature-based structure**: Organizes code into features, each encapsulating related functionality, making it easier to navigate and maintain.
+- **REST API**: Exposes a RESTful API for client interactions, following standard HTTP methods and status codes.
+
+### Project Structure
+```src/
+├── app/
+│   ├── features/          # Feature-based organization
+│   │   ├── [feature-name]/ # Each feature has its own directory
+│   │   │   ├── actions/          # REST endpoint handlers
+│   │   │   ├── commands/         # State-changing DTOs
+│   │   │   ├── queries/          # Data-retrieval DTOs
+│   │   │   ├── handlers/         # Command/query business logic
+│   │   │   ├── query-handlers/   # Query business logic
+│   │   │   ├── events/           # Domain events
+│   │   │   ├── subscribers/      # Event listeners
+│   │   │   ├── graphql/          # GraphQL resolvers
+│   │   │   ├── models/           # TypeORM entities
+│   │   │   └── routing.ts        # Route definitions
+│   ├── infrastructure/    # Infrastructure code (e.g., repositories implementations)
+│   ├── config/            # Configuration files
+│   ├── container/         # Dependency injection container setup
+│   ├── errors/            # Custom error classes
+│   ├── shared/            # Shared utilities and helpers
+│   ├── tests/             # Integration tests files
+│   │   └── bootstrap.ts   # Test bootstrap file
+│   └── migrations/        # TypeORM migrations
+├── src/
+│   ├── index.ts           # Application entry point
+│   ├── server.ts          # Server setup and configuration
+│   ├── container.ts       # Dependency injection container setup
+│   ├── config.ts          # Application configuration
+│   ├── logger.ts          # Logging setup
+│   ├── database.ts        # Database connection setup
+│   └── shared/            # Shared utilities and helpers
+```
+
+### Key Libraries and Functionalities
+- **TypeScript**: For static typing and modern JavaScript features.
+- **Express**: Web framework for building REST APIs.
+- **TypeORM**: ORM for database interactions.
+- **Awilix**: Dependency injection container.
+- **@tshio/command-bus**: Command bus for handling commands.
+- **@tshio/query-bus**: Query bus for handling queries.
+- **@tshio/event-dispatcher**: Event dispatcher for handling domain events.
+- `src/shared/pagination-utils`: Utility functions for request parameters to TypeORM options conversion and list endpoint responses.
+- **UUID v4**: For unique identifiers in database entities.
+- **Docker**: For containerization and consistent development environment.
+- **Jest**: For unit and integration testing.
+- **Celebrate**: For input validation in REST endpoints.
+
+### Key Development Guidelines
+
+#### Important commands
+- **Linting**: Use `npm run lint` to check code style.
+- **Fixing Lint Issues**: Use `npm run lint-fix` to automatically fix lint issues.
+- **Formatting**: Use `npm run format` to format code according to the project's style guide.
+- **Running Tests**: Use `npm run integration` for integration tests and `npm run units` for unit tests.
+- **Generating Migrations**: Use `npm run generate-migration` to create new migrations. Do not run migrations manually, they are auto-executed at application start.
+- **Running migrations**: Use `npm run migrations` to run all pending migrations.
+
+#### General Guidelines
+- Always use TypeScript for type safety and modern JavaScript features.
+- Follow the project's coding conventions and architecture patterns.
+- Use dependency injection for managing dependencies, avoiding direct instantiation of classes.
+- Never run any commands with `docker-compose` command, use npm scripts instead (e.g., `npm run lint`, `npm run lint-fix`, `npm run forma`).
+
+#### Naming Guidelines
+- Always think in terms of features, not technical layers.
+- Features names should be descriptive and reflect the bounded context (e.g., `planning`, `ordering`, `management`). Avoid naming features by connected entities (e.g., `user`, `product`).
+- Use **kebab-case** for directories, filenames and imports (e.g., `user.controller.ts`).
+- Use **camelCase** for variables and function names (e.g., `getUserById`).
+- Use **PascalCase** for class names and interfaces (e.g., `UserService`).
+- use **snake_case** for database columns and TypeORM entity properties (e.g., `first_name`, `last_name`) but use **camelCase** for variable names in TypeScript code.
+- Use suffixes like `.handler.ts`, `.command.ts`, `.query.ts`, `.event.ts`, `.subscriber.ts`, `.resolver.ts` for files in features (e.g, `create-user.command.ts`, `user.query.ts`).
+- Use suffixes like `Service`, `Repository`, `Controller` for class names (e.g., `UserService`, `UserRepository`, `UserController`).
+
+#### Database Guidelines
+- Use **TypeORM** for database interactions.
+- Use **UUID v4** for unique identifiers, avoid auto-increment IDs.
+- Use repositories for data access in handlers, not direct TypeORM queries.
+- Always generate migrations using the provided npm script (`npm run generate-migration`), do not create them manually.
+- Never add parameters to the `npm run generate-migration` command, as it will fail.
+- All migrations are auto-executed at application start, do not run them manually.
+- Migrations are stored in `src/migrations/`.
+
+#### Testing Guidelines
+- Every endpoint must have a corresponding integration test.
+- Every utility function must have a corresponding unit test.
+
+#### Security Guidelines
+- Use `helmet` for security headers in Express.
+- Use `celebrate` for input validation in REST endpoints.
+- Use global error handling middleware for catching and formatting errors.
+- Add logging for important events and errors using injected logger in handlers and actions.
+- Never expose sensitive information in error messages or responses.
+- Use environment variables for sensitive configuration (e.g., database credentials, API keys) and load them using `dotenv`.
+- Use HTTPS for secure communication, especially in production environments.
+- Implement proper authentication and authorization mechanisms for protected routes.
+- Regularly update dependencies to patch security vulnerabilities.
+- Use `cors` middleware to control cross-origin requests, allowing only trusted origins.

.github/instructions/actions.instructions.md

@@ -0,0 +1,71 @@
+---
+applyTo: "**/actions/*.action.ts"
+---
+
+- Every action must have a corresponding integration test
+- Always use `@tshio/command-bus` for command handlers and `@tshio/query-bus` for query handlers.
+- GET methods should be used for queries, and POST, PUT, DELETE methods for commands.
+- When naming actions files always use names descriptive of the action being performed, for example:
+  - `create-user.action.ts` for creating a user
+  - `delete-user.action.ts` for deleting a user
+  - `get-users.action.ts` for retrieving users
+- Use appropriate HTTP status codes for different actions (e.g., 200 for success, 201 for created, 204 for no content).
+- For errors use appropriate HTTP status codes (e.g., 400 for bad request, 404 for not found, 500 for internal server error).:
+- All errors must return a structured JSON response with an error message and code:
+```json
+{
+  "error": {
+    "message": "Error message",
+    "code": "ERROR_CODE"
+  }
+}
+```
+- Validation errors are handled by `celebrate` in `src/middleware/error-handler.ts` don't change that
+
+- Use `GET` method for list endpoints.
+- Use `src/shared/pagination-utils.ts` for creating TypeORM options for list endpoints.
+- Always return a JSON response with `meta` and `data` fields.
+- The `meta` field should contain pagination, filter, sort, and search information.
+- Example request for list endpoint with pagination, sorting, filtering, and search - `GET /users?page=1&limit=10&sort[firstName]=ASC&filter[lastName]=Nowak&search=test`
+- Example response for a list endpoint:
+```json
+{
+  "meta": {
+    "pagination": {
+      "page": 1,
+      "total": 0,
+      "limit": 10,
+      "totalPages": 0
+    },
+    "filter": {
+      "firstName": ["Ewa", "Adam"],
+      "lastName": "Nowak"
+    },
+    "sort": {
+      "firstName": "ASC"
+    },
+    "search": "test"
+  },
+  "data": [{ ... }]
+}
+```
+- Use `filter[field]=value` for filtering by field with specific value.
+  - Filters on the same field are interpreted as OR: `filter[field1]=value1&filter[field1]=value2`
+  - Filters on different fields are interpreted as AND: `filter[field1]=value1&filter[field2]=value2`
+  - Using `%` at the end of value will be interpreted as LIKE query: `filter[field]=value%`
+- Use `sort[field]=ASC|DESC` for sorting by field in specified order.
+- Use `search=term` for general text search.
+- Use `page=1&limit=10` for pagination. 
+- Use `GET` method for single item endpoints.
+- Use singular nouns for single item endpoint paths (e.g., `/users/123e4567-e89b-12d3-a456-426614174000`).
+- Always return a JSON response with the item data.
+- Example request for single item endpoint - `GET /users/123e4567-e89b-12d3-a456-426614174000`
+- Example response for a single item endpoint:
+```json
+{
+  "id": "123e4567-e89b-12d3-a456-426614174000",
+  "firstName": "Ewa",
+  "lastName": "Nowak",
+  "email": "ewa.nowak@example.com"
+}
+```

.github/instructions/handlers.instructions.md

@@ -0,0 +1,43 @@
+---
+applyTo: "**/*.handler.ts"
+---
+
+- All handlers must have a `.handler.ts` suffix.
+- Always use single parameter in constructor for dependencies. For example:
+```typescript
+import { UserService } from "../services/user.service";
+
+interface UserHandlerDependencies {
+  userService: UserService;
+}
+
+export class UserHandler {
+  constructor(private dependencies: UserHandlerDependencies) {}
+
+  async handle(request: Request, response: Response): Promise<void> {
+    const user = await this.dependencies.userService.getUserById(request.params.id);
+    response.json(user);
+  }
+}
+```
+- Never use Command Bus or Query Bus directly in handlers. Instead, dispatch events using the provider `@tshio/event-dispatcher`
+- Always inject repositories and not data sources directly into handlers:
+```typescript
+import { UserEntity } from "../models/user.entity";
+import { Repository } from "typeorm";
+
+interface UserHandlerDependencies {
+  userRepository: Repository<UserEntity>;
+}
+
+export class UserHandler {
+  constructor(private dependencies: UserHandlerDependencies) {}
+
+  async handle(request: Request, response: Response): Promise<void> {
+    const user = await this.dependencies.userRepository.findOneBy({ id: request.params.id });
+    response.json(user);
+  }
+}
+```
+- Never create tests for handlers.
+- Don't use `@CacheQuery` decorator in any handlers unless explicitly stated otherwise.

.github/instructions/models.instructions.md

@@ -0,0 +1,16 @@
+---
+applyTo: "**/+(*.entity.ts|*.repository.ts)"
+---
+
+- All entities must have a `.entity.ts` suffix.
+- Always register repository for each entity in `src/container/database.ts`.
+- When registering a repository, use this approach:
+```typescript
+userRepository: asValue(dbDataSource.getRepository(UserEntity)),
+```
+- Use **UUID v4** for unique identifiers, avoid auto-increment IDs.
+- Use `@PrimaryColumn()` for UUID columns, not `@PrimaryGeneratedColumn()`.
+- Always generate migrations using the provided npm script (`npm run generate-migration`), do not create them manually.
+- Never add parameters to the `npm run generate-migration` command, as it will fail.
+- Never create tests for entities.
+- Always validate and sanitize user input to prevent SQL injection and other attacks.

.github/instructions/routing.instructions.md

@@ -0,0 +1,44 @@
+---
+applyTo: "**/features/**/routing.ts"
+---
+
+- Register routing in `src/app/router.ts` 
+- When registering routing in `src/app/router.ts`, always register it with specific path, for example:
+```typescript
+router.use("/example", usersRouting);
+```
+- For list endpoints, use `GET` method and `/` format for path
+- For single item endpoints, use `GET` method and `/:id` format for path
+- For creating items, use `POST` method and `/` format for path
+- For updating items, use `PUT` method and `/:id` format for path
+- For deleting items, use `DELETE` method and `/:id` format for path
+- A good example of routing:
+```typescript
+export const exampleRouting = (actions: ExampleRoutingDependencies) => {
+  const router = express.Router();
+
+  router.post(
+    "/",
+    [createExampleActionValidation],
+    actions.createExampleAction.invoke.bind(actions.createExampleAction),
+  );
+  router.get(
+    "/",
+    [examplesActionValidation],
+    actions.examplesAction.invoke.bind(actions.examplesAction),
+  );
+  router.get(
+    "/:id",
+    [exampleActionValidation],
+    actions.exampleAction.invoke.bind(actions.exampleAction),
+  );
+  router.delete(
+    "/:id",
+    [deleteExampleActionValidation],
+    actions.deleteExampleAction.invoke.bind(actions.deleteExampleAction),
+  );
+  // ACTIONS_SETUP
+
+  return router;
+};
+```

.github/instructions/security.instructions.md

@@ -0,0 +1,18 @@
+---
+applyTo: "**"
+---
+
+- When implmenting authentication, use JWT tokens for stateless authentication.
+- Never store sensitive information (like passwords) in plain text, always hash them using a strong hashing algorithm (e.g., bcrypt).
+- Always implement authentication with proper session management, including token expiration and refresh mechanisms.
+- The authentication middleware should validate the JWT token and extract user information from it.
+- Use role-based access control (RBAC) to manage permissions and restrict access to resources based on user roles.
+- Always validate user input to prevent common security vulnerabilities such as SQL injection, XSS, and CSRF.
+- Authentication endpoints should return both access and refresh tokens upon successful login:
+```json
+{
+  "access_token": "your_access_token",
+  "refresh_token": "your_refresh_token"
+}
+```
+- Always implement `me` endpoint to allow users to retrieve their own profile information.

.github/instructions/tests.instructions.md

@@ -0,0 +1,27 @@
+---
+applyTo: "**/tests/*.spec.ts"
+---
+
+- All tests must have a `.spec.ts` suffix.
+- Unit tests should be placed next to the file they test
+- Integration tests must be placed in `src/tests` directory
+- Tests for each feature must be placed in a separate file, named after the feature (e.g., `users.spec.ts`, `warehouses.spec.ts`).
+- Tests for each feature must be placed in a separate directory, named after the feature (e.g., `src/tests/users`, `src/tests/warehouses`).
+- Use following pattern for integration tests:
+```typescript
+import { expect } from "chai";
+import "mocha";
+import request from "supertest";
+
+describe("/api/{{kebabCase name}} integration", () => {
+  it("test example", async () => {
+    return request(await global.container.cradle.app)
+      .get("/health")
+      .expect(200)
+  });
+});
+```
+- Test bootstrap is in `src/tests/bootstrap.ts`, which sets up the container, database connection, and clears the database before each test.
+- Use `clearDb()` function in `src/tests/bootstrap.ts` to clear the database before each test.
+- Every repository must be added to `clearDb()` function and cleared with `.delete({})` to avoid TypeORM issues.
+- Use `global.container` and `global.dbConnection` in tests for accessing the container and database connection.

src/migrations/1710240086737-AddUserEntity.ts

@@ -1,15 +1,18 @@
 import { MigrationInterface, QueryRunner } from "typeorm";
 
 export class AddUserEntity1710240086737 implements MigrationInterface {
-    name = 'AddUserEntity1710240086737'
+  name = "AddUserEntity1710240086737";
 
-    public async up(queryRunner: QueryRunner): Promise<void> {
-        await queryRunner.query(`CREATE TABLE "user" ("id" uuid NOT NULL DEFAULT uuid_generate_v4(), "first_name" character varying NOT NULL, "last_name" character varying NOT NULL, "email" character varying NOT NULL, CONSTRAINT "PK_cace4a159ff9f2512dd42373760" PRIMARY KEY ("id"))`);
-        await queryRunner.query(`INSERT INTO "user" (first_name, last_name, email) VALUES ('John', 'Doe', 'john@doe.com'), ('Mark', 'Smith', 'mark@smith.com')`);
-    }
-
-    public async down(queryRunner: QueryRunner): Promise<void> {
-        await queryRunner.query(`DROP TABLE "user"`);
-    }
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `CREATE TABLE "user" ("id" uuid NOT NULL DEFAULT uuid_generate_v4(), "first_name" character varying NOT NULL, "last_name" character varying NOT NULL, "email" character varying NOT NULL, CONSTRAINT "PK_cace4a159ff9f2512dd42373760" PRIMARY KEY ("id"))`,
+    );
+    await queryRunner.query(
+      `INSERT INTO "user" (first_name, last_name, email) VALUES ('John', 'Doe', 'john@doe.com'), ('Mark', 'Smith', 'mark@smith.com')`,
+    );
+  }
 
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE "user"`);
+  }
 }