Below is an example of a Markdown documentation file for the Category Module:

Category Module Documentation

This module provides functionality to manage categories, including creating categories, retrieving categories and their associated posts, updating category details, updating the category tree structure, and deleting categories.

Note: This module is built on top of Express and leverages custom use cases for business logic. Custom errors such as ValidationError and NotFoundError are thrown when appropriate.

Installation

Install the module via npm (if published as a package):

npm install cca-category-module

Then, import the module into your project:

import { createCategoryContainer, CategoryController } from 'cca-category-module';

Usage Example

Below is an example on how to integrate the CategoryController with your Express application:

import express from 'express';
import { createCategoryContainer, CategoryController } from 'cca-category-module';

const app = express();
app.use(express.json());

// Create a container and resolve the CategoryController
const container = createCategoryContainer();
const categoryController: CategoryController = container.resolve(CategoryController);

// Routes for categories
app.post('/categories', categoryController.createCategory);
app.get('/categories', categoryController.getAllCategories);
app.get('/categories/:id', categoryController.getCategory);
app.get('/categories/:id/posts', categoryController.getAllCategoryPosts);
app.put('/categories/:id', categoryController.updateCategory);
app.put('/categories/tree', categoryController.updateCategoryTree);
app.delete('/categories/:id', categoryController.deleteCategory);

// Error handling middleware
app.use((err, req, res, next) => {
  res.status(500).json({ error: err.message });
});

app.listen(3000, () => console.log('Server is running on port 3000'));

Endpoints

1. Create a Category

• URL: /categories
• Method: POST
• Description: Create a new category.
• Body Parameters:
  • name (string, required): The category name.
  • description (string, optional): Description of the category.
  • Other optional category data as required.
• Success Response:
  • Code: 201 Created
  • Content: JSON object containing the created category details.
• Errors:
  • Throws ValidationError if the required field name is missing.

2. Get All Categories

• URL: /categories
• Method: GET
• Description: Retrieve all categories.
• Success Response:
  • Code: 200 OK
  • Content: JSON array of categories.

3. Get a Single Category

• URL: /categories/:id
• Method: GET
• Description: Retrieve a single category by its ID.
• Parameters:
  • id (string): The category identifier.
• Success Response:
  • Code: 200 OK
  • Content: JSON object with category details.
• Errors:
  • Throws ValidationError if no ID is provided.
  • Throws NotFoundError if the category is not found.

4. Get All Posts for a Category

• URL: /categories/:id/posts
• Method: GET
• Description: Retrieve posts associated with a specific category, with pagination support.
• Parameters:
  • id (string): The category identifier.
• Query Parameters:
  • page (number, optional): The page number (default: 1).
  • limit (number, optional): Number of posts per page (default: 10).
  • orderBy (string, optional): Field to order by (default: "createdAt").
  • order (string, optional): Order direction (ASC or DESC, default: "DESC").
• Success Response:
  • Code: 200 OK
  • Content: JSON with paginated posts for the category.
• Errors:
  • Throws ValidationError if no category ID is provided.

5. Update a Category

• URL: /categories/:id
• Method: PUT
• Description: Update an existing category by its ID.
• Parameters:
  • id (string): The category identifier.
• Body Parameters:
  • JSON object with fields to update.
• Success Response:
  • Code: 200 OK
  • Content: JSON object with the updated category details.
• Errors:
  • Throws ValidationError if no category ID is provided.

6. Update Category Tree

• URL: /categories/tree
• Method: PUT
• Description: Update the category tree structure. This endpoint expects an array representing the moves/changes in the category hierarchy.
• Body Parameters:
  • An array of moves describing the new category tree structure.
• Success Response:
  • Code: 204 No Content
• Errors:
  • Throws ValidationError if the request body is not an array.

7. Delete a Category

• URL: /categories/:id
• Method: DELETE
• Description: Delete a category by its ID.
• Parameters:
  • id (string): The category identifier.
• Success Response:
  • Code: 204 No Content
• Errors:
  • Throws ValidationError if no category ID is provided.

Error Handling

Ensure your application has a proper error-handling middleware to catch and return errors:

app.use((err, req, res, next) => {
  res.status(500).json({ error: err.message });
});

License

This module is released under the MIT License.

This documentation provides an overview of the available endpoints and their usage. For more detailed information on the business logic and error handling, please refer to the source code and inline comments.