@uecsio/utils-api

Shared utility helpers for UECS API services built with NestJS and TypeORM.

Installation

npm install @uecsio/utils-api

Peer Dependencies

This package requires the following peer dependencies:

• @nestjs/common: ^11.0.0
• @nestjs/typeorm: ^11.0.0
• typeorm: ^0.3.26
• class-validator: ^0.14.0
• @dataui/crud-typeorm: ^5.3.4

Services

BaseTypeOrmCrudService

A base class that extends TypeOrmCrudService from @dataui/crud-typeorm and adds a getRepository() method for direct repository access.

Usage:

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { BaseTypeOrmCrudService } from '@uecsio/utils-api';
import { Page } from './entities/page.entity';

@Injectable()
export class PagesService extends BaseTypeOrmCrudService<Page> {
  constructor(@InjectRepository(Page) repo: Repository<Page>) {
    super(repo);
  }
}

// Now you can access the repository from other services
const repository = pagesService.getRepository();

UrlGeneratorService

Generates unique URL-friendly slugs from strings with automatic collision handling. Supports transliteration for Cyrillic characters and automatically appends numeric suffixes (e.g., slug-1, slug-2) if duplicates are found.

Usage:

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { UrlGeneratorService } from '@uecsio/utils-api';
import { Page } from './entities/page.entity';

@Injectable()
export class PageUrlService {
  constructor(
    @InjectRepository(Page) private readonly repository: Repository<Page>,
    private readonly urlGenerator: UrlGeneratorService,
  ) {}

  async generateSlug(title: string): Promise<string> {
    // Generate a unique URL slug from the title
    return this.urlGenerator.generateUrl(
      'url', // Field name to check for uniqueness
      title, // Base value to convert to slug
      this.repository, // Repository to check for duplicates
      {
        excludeId: 123, // Optional: exclude this ID when updating
      }
    );
  }
}

Options:

• urlField: Field name to check for uniqueness (default: 'url')
• baseValue: String to convert to URL-friendly slug
• repository: TypeORM repository to check for duplicates
• options.excludeId: ID to exclude from uniqueness check (useful when updating)
• options.extraCondition: Additional WHERE conditions for duplicate checking
• options.maxAttempts: Maximum number of attempts before giving up (default: 100)

Validators

@IsUrlPath()

Validates that a string is a valid URL path segment (without protocol and domain). Allows alphanumeric characters, hyphens, underscores, forward slashes, and periods.

Usage:

import { IsString } from 'class-validator';
import { IsUrlPath } from '@uecsio/utils-api';

export class CreatePageDto {
  @IsString()
  @IsUrlPath()
  url: string; // Valid: "/welcome", "about-us", "products/item-1"
}

@IsUniqueValue()

Validates that a value is unique in a database table. Automatically excludes the current record's ID when updating.

Usage:

import { IsString } from 'class-validator';
import { IsUniqueValue } from '@uecsio/utils-api';
import { Page } from './entities/page.entity';

export class CreatePageDto {
  @IsString()
  @IsUniqueValue(Page, 'url')
  url: string;
}

export class UpdatePageDto {
  id: number;

  @IsString()
  @IsUniqueValue(Page, 'url') // Will exclude this.id from the check
  url: string;
}

// With custom ID field
export class UpdateUserDto {
  userId: number;

  @IsString()
  @IsUniqueValue(User, 'email', 'userId') // Use 'userId' instead of 'id'
  email: string;
}

Parameters:

• entity: The TypeORM entity class to check against
• field: The field name in the entity to check for uniqueness
• idField: Optional field name for the ID (default: 'id')
• validationOptions: Optional class-validator validation options

Note: This validator requires IsUniqueValueConstraint to be provided in your NestJS module:

import { Module } from '@nestjs/common';
import { IsUniqueValueConstraint } from '@uecsio/utils-api';

@Module({
  providers: [IsUniqueValueConstraint],
  // ...
})
export class MyModule {}

Complete Example

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { BaseTypeOrmCrudService, UrlGeneratorService, IsUniqueValueConstraint } from '@uecsio/utils-api';
import { Page } from './entities/page.entity';
import { CreatePageDto } from './dto/create-page.dto';

// Service extending base CRUD service
@Injectable()
export class PagesService extends BaseTypeOrmCrudService<Page> {
  constructor(@InjectRepository(Page) repo: Repository<Page>) {
    super(repo);
  }
}

// DTO with validators
export class CreatePageDto {
  @IsString()
  @IsUrlPath()
  @IsUniqueValue(Page, 'url')
  url: string;

  @IsString()
  title: string;
}

// Module setup
@Module({
  imports: [TypeOrmModule.forFeature([Page])],
  providers: [
    PagesService,
    UrlGeneratorService,
    IsUniqueValueConstraint, // Required for @IsUniqueValue()
  ],
  exports: [PagesService],
})
export class PagesModule {}

Scripts

• npm run build – Compile TypeScript to dist/
• npm run build:watch – Watch mode for development
• npm run lint – Run ESLint on the source
• npm run lint:fix – Fix ESLint issues automatically
• npm run test – Execute unit tests with Jest
• npm run test:watch – Watch mode for tests
• npm run test:cov – Run tests with coverage
• npm run clean – Remove the dist/ directory

License

MIT