@uecsio/utils-api 0.0.1 → 0.0.2

package/README.md

@@ -1,24 +1,218 @@
-# @uecsio/utils
+# @uecsio/utils-api
 
-Shared TypeScript utility helpers used across UECS services.
+Shared utility helpers for UECS API services built with NestJS and TypeORM.
 
-## Scripts
+## Installation
+
+```bash
+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:**
+
+```typescript
+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
 
-- `pnpm run build` – compile TypeScript to `dist/`
-- `pnpm run lint` – run ESLint on the source
-- `pnpm run test` – execute unit tests with Jest
+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
+**Usage:**
 
-```ts
-import { compactObject } from '@uecsio/utils';
+```typescript
+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';
 
-const cleaned = compactObject({
-  id: 1,
-  name: 'Example',
-  optional: undefined,
-});
+@Injectable()
+export class PageUrlService {
+  constructor(
+    @InjectRepository(Page) private readonly repository: Repository<Page>,
+    private readonly urlGenerator: UrlGeneratorService,
+  ) {}
 
-console.log(cleaned); // { id: 1, name: 'Example' }
+  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:**
+
+```typescript
+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:**
+
+```typescript
+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:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { IsUniqueValueConstraint } from '@uecsio/utils-api';
+
+@Module({
+  providers: [IsUniqueValueConstraint],
+  // ...
+})
+export class MyModule {}
+```
+
+## Complete Example
+
+```typescript
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uecsio/utils-api",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Shared utility helpers for UECS API services.",
   "author": "Dmytro Morozov <morozovdmitry@gmail.com>",
   "license": "MIT",