@uecsio/pages-api

A reusable NestJS Pages module for content management with full CRUD operations, validation, and Swagger documentation.

⚠️ Breaking Changes in v2.0.0

Migrated to @dataui/crud

Version 2.0.0 migrates from @nestjs-library/crud to @dataui/crud.

What Changed:

• CRUD library: @nestjs-library/crud → @dataui/crud + @dataui/crud-typeorm
• Enhanced query features (better filtering, sorting, pagination)
• Improved Swagger documentation
• Tests reorganized: specs/ → tests/ with unit/ and integration/ separation

What Stayed the Same:

• All entity fields (rich schema preserved)
• Auto-URL generation from titles
• Async validators
• All API endpoints and functionality
• Database schema (no migrations needed for upgrade)

Installation:

npm install @uecsio/pages-api@^2.0.0

Usage: No code changes needed in consuming applications. The public API remains identical.

🚀 Features

• Full CRUD Operations: Create, Read, Update, Delete pages
• TypeORM Integration: Built-in database support
• Validation: Class-validator integration for DTOs
• Swagger Documentation: Auto-generated API documentation
• Flexible Configuration: Easy to customize and extend
• TypeScript Support: Full type safety

📦 Installation

npm install @uecsio/pages-api

🔧 Dependencies

This package requires the following peer dependencies in your NestJS application:

npm install @nestjs/common @nestjs/typeorm typeorm class-validator class-transformer @dataui/crud @dataui/crud-typeorm

📖 Usage

1. Import the Module

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { PagesModule } from '@uecsio/pages-api';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: 'localhost',
      port: 5432,
      username: 'postgres',
      password: 'password',
      database: 'your_database',
      entities: [__dirname + '/**/*.entity{.ts,.js}'],
      synchronize: true, // Only in development
    }),
    PagesModule,
  ],
})
export class AppModule {}

2. Use the Service

import { Injectable } from '@nestjs/common';
import { PagesService, CreatePageDto, Page } from '@uecsio/pages-api';

@Injectable()
export class YourService {
  constructor(private readonly pagesService: PagesService) {}

  async createPage(data: CreatePageDto): Promise<Page> {
    return this.pagesService.create(data);
  }

  async getAllPages(): Promise<Page[]> {
    return this.pagesService.findAll();
  }

  async getPageById(id: number): Promise<Page> {
    return this.pagesService.findOne(id);
  }
}

3. Use the Controller

The package automatically provides a REST API with the following endpoints:

• POST /pages - Create a new page
• GET /pages - Get all pages
• GET /pages/:id - Get a specific page
• PUT /pages/:id - Update a page
• DELETE /pages/:id - Delete a page

4. Database Migrations

The package includes database migrations that are automatically discovered by the consuming application. The migrations will be executed externally via your TypeORM settings.

Automatic Discovery (Recommended)

The consuming application automatically discovers all @uecsio packages and their migrations:

// No manual configuration needed - migrations are auto-discovered!
@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: 'localhost',
      port: 5432,
      username: 'postgres',
      password: 'password',
      database: 'your_database',
      // Migrations and entities are automatically discovered from @uecsio packages
      synchronize: false, // Always false for production
    }),
    PagesModule,
  ],
})
export class AppModule {}

Manual Integration (Alternative)

If you prefer manual control, you can still integrate manually:

import { PagesMigrationConfig } from '@uecsio/pages-api';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: 'localhost',
      port: 5432,
      username: 'postgres',
      password: 'password',
      database: 'your_database',
      entities: [...PagesMigrationConfig.entities],
      migrations: [...PagesMigrationConfig.migrations],
      migrationsTableName: 'migrations', // Standard migration table
      synchronize: false, // Always false for production
    }),
    PagesModule,
  ],
})
export class AppModule {}

Note: This module uses the standard migrations table name, so it will work seamlessly with other modules that also use the same migration table.

Available migrations

The package provides the following migration:

• CreatePagesTable1700000000000 - Creates the pages table with all required columns and indexes

Migration execution

Migrations will be executed automatically by TypeORM when you run:

# Generate new migrations
npm run typeorm migration:generate

# Run pending migrations
npm run typeorm migration:run

# Revert last migration
npm run typeorm migration:revert

5. Customize the Page Entity

You can extend the Page entity for your specific needs:

import { Entity } from 'typeorm';
import { Page } from '@uecsio/pages-api';

@Entity()
export class CustomPage extends Page {
  // Add your custom fields here
  @Column()
  customField: string;
}

🏗️ Architecture

src/
├── entities/
│   └── page.entity.ts      # Page database entity
├── dto/
│   ├── create-page.dto.ts  # Create page DTO
│   └── update-page.dto.ts  # Update page DTO
├── services/
│   └── pages.service.ts    # Business logic service
├── controllers/
│   └── pages.controller.ts # REST API controller
├── pages.module.ts         # NestJS module
└── index.ts               # Package exports

🔍 API Documentation

Once the module is imported, you can access the Swagger documentation at:

http://localhost:3000/api

🧪 Testing

# Run tests
npm test

# Run tests with coverage
npm run test:cov

# Run tests in watch mode
npm run test:watch

📝 Configuration

Environment Variables

The module uses the following environment variables (with defaults):

DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=password
DB_NAME=your_database

Custom Database Configuration

You can override the database configuration:

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { PagesModule } from '@uecsio/pages-api';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      // Your custom database configuration
      type: 'mysql',
      host: 'your-host',
      // ... other options
    }),
    PagesModule,
  ],
})
export class AppModule {}

🔌 Extending the Module

Custom Service Methods

import { Injectable } from '@nestjs/common';
import { PagesService } from '@uecsio/pages-api';

@Injectable()
export class CustomPagesService extends PagesService {
  async findByStatus(status: number) {
    return this.repository.find({ where: { status } });
  }
}

Custom Controller Methods

import { Controller } from '@nestjs/common';
import { PagesController } from '@uecsio/pages-api';

@Controller('custom-pages')
export class CustomPagesController extends PagesController {
  // Add your custom endpoints here
}

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

If you encounter any problems or have questions, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue

🔄 Changelog

v1.0.0

• Initial release
• Full CRUD operations
• TypeORM integration
• Swagger documentation
• Validation support