@mee4dy/crud-nestjs 1.0.3

package/readme.md

@@ -0,0 +1,426 @@
+# @mee4dy/crud-nestjs
+
+Модуль для NestJS, предоставляющий декларативный и расширяемый CRUD-контроллер с минимальной конфигурацией. Позволяет быстро создавать REST API для любых моделей с поддержкой фильтрации, сортировки, пагинации, скопов и гибкой настройки.
+
+## Преимущества
+
+- Декларативный подход через декоратор `@Crud`
+- Не требует создания сервисов и наследования
+- Гибкая настройка разрешённых параметров (allowedParams)
+- Поддержка scopes (динамические параметры по каждому эндпоинту)
+- Единый формат ответа и ошибок
+- Лёгкая интеграция с клиентом (@mee4dy/crud-client)
+- Расширяемость и чистый код
+
+## Установка
+
+```bash
+npm install @mee4dy/crud-nestjs
+```
+
+## Быстрый старт
+
+1. Импортируйте пакет и используйте декоратор `@Crud` в контроллере:
+
+```typescript
+import { Controller } from '@nestjs/common';
+import { Crud } from '@mee4dy/crud-nestjs';
+import { Post } from './posts.model';
+
+@Crud({
+  repository: () => Posts,
+})
+@Controller('posts')
+export class PostsController {}
+```
+
+2. Подключите модель к SequelizeModule в модуле:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { SequelizeModule } from '@nestjs/sequelize';
+import { PostsController } from './posts.controller';
+import { Posts } from './posts.model';
+
+@Module({
+  imports: [SequelizeModule.forFeature([Posts])],
+  controllers: [PostsController],
+})
+export class PostsModule {}
+```
+
+## Структура опций для декоратора @Crud
+
+```typescript
+type CrudDecoratorConfig = {
+  /** Функция, возвращающая модель Sequelize для работы с БД */
+  repository: () => any;
+
+  /** Имя поля первичного ключа (по умолчанию 'id') */
+  pk?: string;
+
+  /** Включение/отключение CRUD-методов */
+  endpoints?: {
+    items?: boolean; // GET /items - получение списка
+    item?: boolean; // GET /items/:pk - получение одного элемента
+    create?: boolean; // POST /items - создание
+    update?: boolean; // PUT /items/:pk - обновление
+    delete?: boolean; // DELETE /items/:pk - удаление
+  };
+
+  /** Настройка разрешённых параметров из query string */
+  query?: {
+    allowedParams?: {
+      filters?: string[] | boolean; // Разрешённые поля для фильтрации
+      orders?: string[] | boolean; // Разрешённые поля для сортировки
+      groups?: string[] | boolean; // Разрешённые поля для группировки
+      limit?: boolean; // Разрешить пагинацию (limit)
+      offset?: boolean; // Разрешить пагинацию (offset)
+      fields?: string[]; // Разрешённые поля для выборки
+      fieldsExclude?: string[]; // Поля для исключения из выборки
+    };
+  };
+
+  /** Параметры по умолчанию для всех запросов */
+  params?: {
+    default?: Partial<CrudParams>;
+  };
+
+  /** Динамические параметры для каждого эндпоинта */
+  scopes?: {
+    global?: (req: any) => Partial<{ params: Partial<CrudParams> }>; // Применяется ко всем эндпоинтам
+    items?: (req: any) => Partial<{ params: Partial<CrudParams> }>; // Только для получения списка
+    item?: (req: any) => Partial<{ params: Partial<CrudParams> }>; // Только для получения одного элемента
+    create?: (req: any) => Partial<{ params: Partial<CrudParams> }>; // Только для создания
+    update?: (req: any) => Partial<{ params: Partial<CrudParams> }>; // Только для обновления
+    delete?: (req: any) => Partial<{ params: Partial<CrudParams> }>; // Только для удаления
+  };
+};
+```
+
+## Тип CrudParams
+
+`CrudParams` — это основной тип для описания параметров запроса к базе данных.
+
+```typescript
+interface CrudParams {
+  filters?: CrudParamsFilter; // Фильтры для WHERE условий
+  join?: CrudJoin[]; // Join связи
+  fields?: CrudFields; // Настройка выборки полей
+  orders?: CrudOrder[]; // Сортировка (ORDER BY)
+  groups?: string[]; // Группировка (GROUP BY)
+  limit?: number; // Лимит записей
+  offset?: number; // Смещение для пагинации
+}
+```
+
+### Фильтры (filters)
+
+```typescript
+type CrudParamsFilter = {
+  [field: string]: CrudFieldFilter;
+};
+
+type CrudFieldFilter =
+  | string // Простое равенство: { user_id: "123" }
+  | number // Простое равенство: { status: 1 }
+  | boolean // Простое равенство: { active: true }
+  | { op: 'eq'; value: string | number | boolean } // Явное равенство
+  | { op: 'like'; value: string } // LIKE поиск
+  | { op: 'range' | 'period'; from: number | string; to: number | string }; // Диапазон значений
+```
+
+**Примеры фильтров:**
+
+```typescript
+// В коде:
+const filters = {
+  user_id: 1,                                    // Простое равенство
+  title: { op: 'like', value: '%test%' },       // LIKE поиск
+  created_at: { op: 'range', from: '2024-01-01', to: '2024-12-31' }, // Диапазон дат
+  status: { op: 'eq', value: 'active' }         // Явное равенство
+};
+
+// HTTP запрос:
+GET /posts?filters[user_id]=1&filters[title][op]=like&filters[title][value]=test&filters[created_at][op]=range&filters[created_at][from]=2024-01-01&filters[created_at][to]=2024-12-31
+```
+
+### Сортировка (orders)
+
+```typescript
+type CrudOrder = [string, 'asc' | 'desc'];  // [поле, направление]
+
+// В коде:
+const orders = [
+  ['created_at', 'desc'],  // Сначала новые
+  ['title', 'asc'],        // По алфавиту
+  ['id', 'desc']           // По ID убывание
+];
+
+// HTTP запрос:
+GET /posts?orders[0][0]=created_at&orders[0][1]=desc&orders[1][0]=title&orders[1][1]=asc
+```
+
+### Группировка (groups)
+
+```typescript
+// В коде:
+const groups = ['user_id', 'status'];
+
+// HTTP запрос:
+GET /posts?groups[0]=user_id&groups[1]=status
+```
+
+### Пагинация (limit, offset)
+
+```typescript
+// В коде:
+const limit = 20;   // Количество записей на странице
+const offset = 40;  // Пропустить первые 40 записей (для 3-й страницы)
+
+// HTTP запрос:
+GET /posts?limit=20&offset=40
+```
+
+### Выборка полей (fields)
+
+```typescript
+type CrudFields = {
+  include?: [Literal, CrudField][]; // Дополнительные SQL выражения
+  exclude?: CrudField[]; // Исключаемые поля
+};
+
+// В коде:
+const fields = {
+  include: [
+    [Sequelize.literal('CONCAT(name, " (", email, ")")'), 'full_info'],
+    [Sequelize.literal('COUNT(*)'), 'total_count'],
+  ],
+  exclude: ['password', 'deleted_at'],
+};
+```
+
+### Связи (join)
+
+```typescript
+type CrudJoin = {
+  repository: () => any; // Функция, возвращающая модель Sequelize
+  attributes?: CrudFields; // Настройка полей для связанной модели
+  join?: CrudJoin[]; // Вложенные join для связанной модели
+};
+```
+
+**Примеры join связей:**
+
+```typescript
+// Простой join с пользователем
+const join = [
+  {
+    repository: () => User,
+    attributes: {
+      include: [[Sequelize.literal('CONCAT(name, " (", email, ")")'), 'full_info']],
+      exclude: ['password', 'deleted_at'],
+    },
+  },
+];
+
+// Вложенный join: посты с комментариями и пользователями комментариев
+const join = [
+  {
+    repository: () => Comment,
+    attributes: {
+      include: [[Sequelize.literal('CONCAT("[", id, "] ", text)'), 'formatted_text']],
+    },
+    join: [
+      {
+        repository: () => User,
+        attributes: {
+          exclude: ['password', 'deleted_at'],
+        },
+      },
+    ],
+  },
+];
+
+// Множественные join
+const join = [
+  {
+    repository: () => User,
+    attributes: {
+      exclude: ['password'],
+    },
+  },
+  {
+    repository: () => Category,
+    attributes: {
+      include: [[Sequelize.literal('UPPER(name)'), 'upper_name']],
+    },
+  },
+];
+```
+
+## Примеры контроллеров
+
+### Минимальный контроллер
+
+```typescript
+@Crud({ repository: () => Users })
+@Controller('users')
+export class UsersController {}
+```
+
+### Контроллер с ограничением параметров
+
+```typescript
+@Crud({
+  repository: () => Posts,
+  query: {
+    allowedParams: {
+      filters: ['id', 'user_id'],
+      orders: ['id', 'created_at'],
+      limit: true,
+      offset: true,
+    },
+  },
+})
+@Controller('posts')
+export class PostsController {}
+```
+
+### Контроллер с default params и scopes по эндпоинтам
+
+```typescript
+@Crud({
+  repository: () => Comments,
+  params: {
+    default: {
+      orders: [['id', 'desc']],
+      limit: 10,
+    },
+  },
+  scopes: {
+    global: (req) => ({
+      params: {
+        filters: {
+          deleted_at: null,
+        },
+      },
+    }),
+    items: (req) => ({
+      params: {
+        filters: {
+          user_id: req.user.id,
+        },
+      },
+    }),
+    create: (req) => ({
+      params: {
+        filters: {
+          user_id: req.user.id,
+        },
+      },
+    }),
+  },
+})
+@Controller('comments')
+export class CommentsController {}
+```
+
+### Контроллер с join связями
+
+```typescript
+@Crud({
+  repository: () => Posts,
+  params: {
+    default: {
+      join: [
+        {
+          repository: () => Users,
+          attributes: {
+            exclude: [
+              'password',
+              'deleted_at'
+            ]
+          }
+        }
+      ]
+    }
+  },
+  scopes: {
+    item: (req) => ({
+      params: {
+        join: [
+          {
+            repository: () => Comments,
+            attributes: {
+              include: [
+                [
+                  Sequelize.literal('CONCAT("[", id, "] ", text)'),
+                  'formatted_text'
+                ]
+              ]
+            },
+            join: [
+              {
+                repository: () => Users,
+                attributes: {
+                  exclude: [
+                    'password'
+                  ]
+                }
+              }
+            ]
+          }
+        ]
+      }
+    })
+  }
+})
+@Controller('posts')
+```
+
+## Формат ответа
+
+Все ответы возвращаются в едином формате:
+
+```json
+{
+  "status": true,
+  "data": {
+    "items": [ ... ],
+    "item": { ... }
+  }
+}
+```
+
+В случае ошибки:
+
+```json
+{
+  "status": false,
+  "error": {
+    "message": "...",
+    "statusCode": 400,
+    "errorType": "..."
+  }
+}
+```
+
+## Обработка ошибок
+
+- Все ошибки автоматически форматируются через фильтр `CrudExceptionFilter`
+- Для отключённых эндпоинтов выбрасывается `EndpointDisabledException`
+
+## Интеграция с клиентом
+
+Пакет полностью совместим с [@mee4dy/crud-client](../@mee4dy/crud-client) для фронтенда.
+
+## Совместимость
+
+- NestJS >= 9
+- Sequelize >= 6
+- Node.js >= 16
+
+## Лицензия
+
+MIT