@rotyro-tools/nestjs-typeorm-validator 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rotyro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# NestJS TypeORM Validator
+
+[![Publish to npm](https://github.com/rotyro-tools/nestjs-typeorm-validator/actions/workflows/publish-to-npm.yml/badge.svg)](https://github.com/rotyro-tools/nestjs-typeorm-validator/actions/workflows/publish-to-npm.yml)
+[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
+
+Lightweight NestJS decorators for validating values against TypeORM entities.
+
+This package provides several decorators (more to come):
+
+| Decorator   | Description                                                   |
+| ----------- | ------------------------------------------------------------- |
+| `@ExistsIn` | Ensures a value exists in a specified entity/table column.    |
+| `@UniqueIn` | Ensures a value is unique in a specified entity/table column. |
+
+It integrates with TypeORM DataSource instances, enabling database-aware validation in DTOs.
+
+---
+
+## Key features
+
+- Works with TypeORM entity classes or table name strings.
+- Supports multiple (named) TypeORM DataSource registrations.
+- Supports class-validator options (for example `each` for array validation, or `message` for custom message).
+- Minimal runtime dependency surface — relies on TypeORM and class-validator as peer dependencies.
+
+---
+
+## Installation
+
+Install the package:
+
+### npm
+
+```bash
+npm install @rotyro-tools/nestjs-typeorm-validator
+```
+
+### yarn
+
+```bash
+yarn add @rotyro-tools/nestjs-typeorm-validator
+```
+
+### pnpm
+
+```bash
+pnpm add @rotyro-tools/nestjs-typeorm-validator
+```
+
+### bun
+
+```bash
+bun add @rotyro-tools/nestjs-typeorm-validator
+```
+
+## Peer dependencies
+
+This package declares the following peer dependencies that consumers must install at compatible versions:
+
+- [class-validator](https://github.com/typestack/class-validator)
+- [typeorm](https://github.com/typeorm/typeorm)
+
+Install them:
+
+### npm
+
+```bash
+npm install --save class-validator typeorm
+```
+
+### yarn
+
+```bash
+yarn add class-validator typeorm
+```
+
+### pnpm
+
+```bash
+pnpm add class-validator typeorm
+```
+
+### bun
+
+```bash
+bun add class-validator typeorm
+```
+
+---
+
+## Getting started
+
+1. Register one or more TypeORM DataSources to be used by the validators:
+
+```typescript
+import { registerDataSourceForValidation } from '@rotyro-tools/nestjs-typeorm-validator';
+import { DataSource } from 'typeorm';
+
+const dataSource = new DataSource({
+  type: 'mysql',
+  host: 'localhost',
+  port: 3306,
+  username: 'user',
+  password: 'pass',
+  database: 'db',
+  entities: [
+    /* ... */
+  ],
+  synchronize: false,
+});
+
+// If you initialize the DataSource yourself, that's fine. If you don't, registerDataSourceForValidation will attempt to initialize it for you.
+await dataSource.initialize();
+
+// Register your DataSource
+registerDataSourceForValidation(dataSource); // Registers as 'default'
+
+// Second 'replica' DataSource
+const replicaDataSource = new DataSource({
+  type: 'mysql',
+  host: 'replica-host',
+  port: 3306,
+  username: 'replica_user',
+  password: 'replica_pass',
+  database: 'db_replica',
+  entities: [
+    /* ... */
+  ],
+  synchronize: false,
+});
+
+// Optionally initialize the replica DataSource as well
+await replicaDataSource.initialize();
+
+// Register your DataSource
+registerDataSourceForValidation(replicaDataSource, 'replica');
+```
+
+2. Use decorators in your DTOs:
+
+```typescript
+import { ExistsIn, UniqueIn } from '@rotyro-tools/nestjs-typeorm-validator';
+
+import { User } from '@/modules/users/entities/user.entity';
+
+class CreatePostDto {
+  // Ensure the given authorId exists in the User entity's id column
+  // in the 'default' DataSource
+  @ExistsIn(User, 'id', null, { message: 'Author not found' })
+  authorId: number;
+
+  // Ensure the title is unique in the posts table (using a table name)
+  // in the 'replica' DataSource
+  @UniqueIn('post', 'title', 'replica', { message: 'Title already taken' })
+  title: string;
+}
+```
+
+---
+
+## Examples
+
+Checking existence (minimal setup):
+
+```typescript
+import { ExistsIn } from '@rotyro-tools/nestjs-typeorm-validator';
+
+class CreateCommentDto {
+  @ExistsIn('user', 'id')
+  userId: number;
+}
+```
+
+Unique constraint (entity usage and custom message):
+
+```typescript
+import { UniqueIn } from '@rotyro-tools/nestjs-typeorm-validator';
+
+import { User } from '@/modules/users/entities/user.entity';
+
+class RegisterUserDto {
+  @UniqueIn(User, 'email', null, { message: 'Email already in use' })
+  email: string;
+}
+```
+
+Validating arrays:
+
+```typescript
+import { ExistsIn } from '@rotyro-tools/nestjs-typeorm-validator';
+
+class BulkCreateDto {
+  @ExistsIn('tag', 'name', 'replica', {
+    each: true,
+    message: 'Tag does not exist',
+  })
+  tagNames: string[];
+}
+```
+
+---
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Build:
+
+```bash
+npm run build
+```
+
+Lint:
+
+```bash
+npm run lint
+```
+
+Format:
+
+```bash
+npm run format
+```
+
+Run tests:
+
+```bash
+npm run test
+```
+
+Commit (with Commitizen):
+
+```bash
+npm run cm
+```

package/dist/index.d.mts

@@ -0,0 +1,157 @@
+import { ValidationOptions } from 'class-validator';
+import { EntityTarget } from 'typeorm';
+
+/**
+ * Interface representing the minimal DataSource contract needed for validation.
+ * This allows compatibility with different TypeORM versions.
+ */
+interface DataSourceLike {
+    isInitialized: boolean;
+    initialize(): Promise<this>;
+    getRepository(target: string | (new (...args: unknown[]) => unknown)): unknown;
+}
+
+/**
+ * Register a DataSource instance to be used for validation.
+ * @param dataSourceInstance - TypeORM DataSource instance
+ * @param dataSourceName - Optional DataSource name (defaults to 'default'). If `null`, `undefined`, or an empty string is passed,
+ *                         the registration will use the 'default' name — the same name used when registering without specifying one.
+ * @throws {DataSourceInvalidError} if the instance is invalid
+ */
+declare function registerDataSourceForValidation(dataSourceInstance: DataSourceLike, dataSourceName?: string): void;
+
+/**
+ * Validates that the decorated property's value **exists in** a specific database column.
+ *
+ * @description
+ * The `@ExistsIn` decorator performs a database lookup (via TypeORM) to verify that the
+ * provided value **exists** in the specified table column.
+ * It supports both:
+ * - **Entity classes** (e.g., `User`, `Post`)
+ * - **Table name strings** (e.g., `'user'`, `'post'`)
+ *
+ *
+ * You can also specify which registered data source to use by passing the dataSourceName
+ * (the same name you used when calling `registerDataSourceForValidation(dataSourceInstance, 'yourName')`).
+ * If you pass `null` or `undefined` (or leave the parameter omitted), the decorator will use the
+ * 'default' data source — the same default used when registering a data source without specifying a name.
+ *
+ * The `validationOptions` parameter accepts the same ValidationOptions used by `class-validator`.
+ * Therefore options such as `each: true` (to validate array elements) and `message` (to provide a custom error message)
+ * behave exactly as they do in `class-validator`.
+ *
+ * @example
+ * **Using with an Entity class:**
+ * ```typescript
+ * class CreatePostDto {
+ *   @ExistsIn(User, 'id')
+ *   authorId: number;
+ * }
+ * ```
+ *
+ * @example
+ * **Using with a table name:**
+ * ```typescript
+ * class CreatePostDto {
+ *   @ExistsIn('user', 'id')
+ *   authorId: number;
+ * }
+ * ```
+ *
+ * @example
+ * **Using with a specific data source (registered as 'secondary'):**
+ * ```typescript
+ * class CreatePostDto {
+ *   @ExistsIn(User, 'id', 'secondary')
+ *   authorId: number;
+ * }
+ * ```
+ *
+ * @example
+ * **Using a default data source and validating arrays with custom message:**
+ * ```typescript
+ * class CreateMultiplePostsDto {
+ *   @ExistsIn('user', 'id', null, { each: true, message: 'Every authorId must exist' })
+ *   authorIds: number[];
+ * }
+ * ```
+ *
+ * @param entityOrTableName - The entity class or table name to check against.
+ * @param columnName - The column name in which to look for the value.
+ * @param dataSourceName - Optional name of the data source to use for validation (must match a registered name).
+ *                         Passing `null`/`undefined` (or omitting this argument) will use the 'default' data source.
+ * @param validationOptions - Optional validation settings from `class-validator` (use `{ each: true }` for arrays and `message` for custom text).
+ * @returns A property decorator function used by `class-validator`.
+ *
+ * @public
+ */
+declare function ExistsIn<T extends EntityTarget<unknown> | string>(entityOrTableName: T, columnName: T extends string ? string : T extends EntityTarget<infer E> ? keyof E & string : string, dataSourceName?: string, validationOptions?: ValidationOptions): PropertyDecorator;
+
+/**
+ * Validates that the decorated property's value is **unique** within a specified database column.
+ *
+ * @description
+ * The `@UniqueIn` decorator performs a database lookup (via TypeORM) to ensure that the provided
+ * value does **not already exist** in the specified table column.
+ * It supports both:
+ * - **Entity class references** (e.g., `User`, `Post`)
+ * - **Direct table name strings** (e.g., `'user'`, `'post'`)
+ *
+ *
+ * You can also specify which registered data source to use by passing the dataSourceName
+ * (the same name you used when calling `registerDataSourceForValidation(dataSourceInstance, 'yourName')`).
+ * If you pass `null` or `undefined` (or leave the parameter omitted), the decorator will use the
+ * 'default' data source — the same default used when registering a data source without specifying a name.
+ *
+ * The `validationOptions` parameter accepts the same ValidationOptions used by `class-validator`.
+ * Therefore options such as `each: true` (to validate array elements) and `message` (to provide a custom error message)
+ * behave exactly as they do in `class-validator`.
+ *
+ * @example
+ * **Using with an Entity class:**
+ * ```typescript
+ * class CreateUserDto {
+ *   @UniqueIn(User, 'email')
+ *   email: string;
+ * }
+ * ```
+ *
+ * @example
+ * **Using with a table name:**
+ * ```typescript
+ * class CreateUserDto {
+ *   @UniqueIn('user', 'email')
+ *   email: string;
+ * }
+ * ```
+ *
+ * @example
+ * **Using with a specific data source (registered as 'secondary'):**
+ * ```typescript
+ * class CreateUserDto {
+ *   @UniqueIn(User, 'email', 'secondary')
+ *   email: string;
+ * }
+ * ```
+ *
+ * @example
+ * **Using a default data source and validating arrays with custom message:**
+ * ```typescript
+ * class CreateUsersDto {
+ *   @UniqueIn('user', 'email', null, { each: true, message: 'Each user email must be unique' })
+ *   emails: string[];
+ * }
+ * ```
+ *
+ * @param entityOrTableName - The entity class or table name to check against.
+ * @param columnName - The column name to validate uniqueness in.
+ * @param dataSourceName - Optional name of the data source to use for validation (must match a registered name).
+ *                         Passing `null`/`undefined` (or omitting this argument) will use the 'default' data source.
+ * @param validationOptions - Optional validation settings from `class-validator` (use `{ each: true }` for arrays and `message` for custom text).
+ * @returns A property decorator function used by `class-validator`.
+ *
+ * @public
+ */
+declare function UniqueIn<T extends EntityTarget<unknown> | string>(entityOrTableName: T, columnName: T extends string ? string : T extends EntityTarget<infer E> ? keyof E & string : string, dataSourceName?: string, validationOptions?: ValidationOptions): PropertyDecorator;
+
+export { ExistsIn, UniqueIn, registerDataSourceForValidation };

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+import { ValidationOptions } from 'class-validator';
+import { EntityTarget } from 'typeorm';
+
+/**
+ * Interface representing the minimal DataSource contract needed for validation.
+ * This allows compatibility with different TypeORM versions.
+ */
+interface DataSourceLike {
+    isInitialized: boolean;
+    initialize(): Promise<this>;
+    getRepository(target: string | (new (...args: unknown[]) => unknown)): unknown;
+}
+
+/**
+ * Register a DataSource instance to be used for validation.
+ * @param dataSourceInstance - TypeORM DataSource instance
+ * @param dataSourceName - Optional DataSource name (defaults to 'default'). If `null`, `undefined`, or an empty string is passed,
+ *                         the registration will use the 'default' name — the same name used when registering without specifying one.
+ * @throws {DataSourceInvalidError} if the instance is invalid
+ */
+declare function registerDataSourceForValidation(dataSourceInstance: DataSourceLike, dataSourceName?: string): void;
+
+/**
+ * Validates that the decorated property's value **exists in** a specific database column.
+ *
+ * @description
+ * The `@ExistsIn` decorator performs a database lookup (via TypeORM) to verify that the
+ * provided value **exists** in the specified table column.
+ * It supports both:
+ * - **Entity classes** (e.g., `User`, `Post`)
+ * - **Table name strings** (e.g., `'user'`, `'post'`)
+ *
+ *
+ * You can also specify which registered data source to use by passing the dataSourceName
+ * (the same name you used when calling `registerDataSourceForValidation(dataSourceInstance, 'yourName')`).
+ * If you pass `null` or `undefined` (or leave the parameter omitted), the decorator will use the
+ * 'default' data source — the same default used when registering a data source without specifying a name.
+ *
+ * The `validationOptions` parameter accepts the same ValidationOptions used by `class-validator`.
+ * Therefore options such as `each: true` (to validate array elements) and `message` (to provide a custom error message)
+ * behave exactly as they do in `class-validator`.
+ *
+ * @example
+ * **Using with an Entity class:**
+ * ```typescript
+ * class CreatePostDto {
+ *   @ExistsIn(User, 'id')
+ *   authorId: number;
+ * }
+ * ```
+ *
+ * @example
+ * **Using with a table name:**
+ * ```typescript
+ * class CreatePostDto {
+ *   @ExistsIn('user', 'id')
+ *   authorId: number;
+ * }
+ * ```
+ *
+ * @example
+ * **Using with a specific data source (registered as 'secondary'):**
+ * ```typescript
+ * class CreatePostDto {
+ *   @ExistsIn(User, 'id', 'secondary')
+ *   authorId: number;
+ * }
+ * ```
+ *
+ * @example
+ * **Using a default data source and validating arrays with custom message:**
+ * ```typescript
+ * class CreateMultiplePostsDto {
+ *   @ExistsIn('user', 'id', null, { each: true, message: 'Every authorId must exist' })
+ *   authorIds: number[];
+ * }
+ * ```
+ *
+ * @param entityOrTableName - The entity class or table name to check against.
+ * @param columnName - The column name in which to look for the value.
+ * @param dataSourceName - Optional name of the data source to use for validation (must match a registered name).
+ *                         Passing `null`/`undefined` (or omitting this argument) will use the 'default' data source.
+ * @param validationOptions - Optional validation settings from `class-validator` (use `{ each: true }` for arrays and `message` for custom text).
+ * @returns A property decorator function used by `class-validator`.
+ *
+ * @public
+ */
+declare function ExistsIn<T extends EntityTarget<unknown> | string>(entityOrTableName: T, columnName: T extends string ? string : T extends EntityTarget<infer E> ? keyof E & string : string, dataSourceName?: string, validationOptions?: ValidationOptions): PropertyDecorator;
+
+/**
+ * Validates that the decorated property's value is **unique** within a specified database column.
+ *
+ * @description
+ * The `@UniqueIn` decorator performs a database lookup (via TypeORM) to ensure that the provided
+ * value does **not already exist** in the specified table column.
+ * It supports both:
+ * - **Entity class references** (e.g., `User`, `Post`)
+ * - **Direct table name strings** (e.g., `'user'`, `'post'`)
+ *
+ *
+ * You can also specify which registered data source to use by passing the dataSourceName
+ * (the same name you used when calling `registerDataSourceForValidation(dataSourceInstance, 'yourName')`).
+ * If you pass `null` or `undefined` (or leave the parameter omitted), the decorator will use the
+ * 'default' data source — the same default used when registering a data source without specifying a name.
+ *
+ * The `validationOptions` parameter accepts the same ValidationOptions used by `class-validator`.
+ * Therefore options such as `each: true` (to validate array elements) and `message` (to provide a custom error message)
+ * behave exactly as they do in `class-validator`.
+ *
+ * @example
+ * **Using with an Entity class:**
+ * ```typescript
+ * class CreateUserDto {
+ *   @UniqueIn(User, 'email')
+ *   email: string;
+ * }
+ * ```
+ *
+ * @example
+ * **Using with a table name:**
+ * ```typescript
+ * class CreateUserDto {
+ *   @UniqueIn('user', 'email')
+ *   email: string;
+ * }
+ * ```
+ *
+ * @example
+ * **Using with a specific data source (registered as 'secondary'):**
+ * ```typescript
+ * class CreateUserDto {
+ *   @UniqueIn(User, 'email', 'secondary')
+ *   email: string;
+ * }
+ * ```
+ *
+ * @example
+ * **Using a default data source and validating arrays with custom message:**
+ * ```typescript
+ * class CreateUsersDto {
+ *   @UniqueIn('user', 'email', null, { each: true, message: 'Each user email must be unique' })
+ *   emails: string[];
+ * }
+ * ```
+ *
+ * @param entityOrTableName - The entity class or table name to check against.
+ * @param columnName - The column name to validate uniqueness in.
+ * @param dataSourceName - Optional name of the data source to use for validation (must match a registered name).
+ *                         Passing `null`/`undefined` (or omitting this argument) will use the 'default' data source.
+ * @param validationOptions - Optional validation settings from `class-validator` (use `{ each: true }` for arrays and `message` for custom text).
+ * @returns A property decorator function used by `class-validator`.
+ *
+ * @public
+ */
+declare function UniqueIn<T extends EntityTarget<unknown> | string>(entityOrTableName: T, columnName: T extends string ? string : T extends EntityTarget<infer E> ? keyof E & string : string, dataSourceName?: string, validationOptions?: ValidationOptions): PropertyDecorator;
+
+export { ExistsIn, UniqueIn, registerDataSourceForValidation };