@kollors/deep-json-server 0.3.2 → 0.5.0

package/README.ru.md

@@ -14,24 +14,67 @@
 npm install --save-dev @kollors/deep-json-server
 ```
 
-Добавьте команду в `package.json`:
+## Конфигурация и запуск
+
+Создайте ESM-модуль `server.config.js`. В примере ниже включены настройки всех возможностей:
+
+```js
+import process from 'node:process';
+
+export default {
+  database: {
+    path: process.env.DATABASE_PATH ?? 'mock/database.json',
+    schema: 'mock/database-schema.json',
+  },
+  files: {
+    directory: 'mock/files',
+    metadata: 'mock/files/_database.json',
+  },
+  openapi: {
+    path: 'mock/openapi-schema.yaml',
+  },
+  server: {
+    host: '127.0.0.1',
+    port: 4001,
+  },
+};
+```
+
+Ключи конфигурации:
+
+| Ключ | Когда обязателен | Назначение |
+| --- | --- | --- |
+| `database.path` | Всегда | Существующий JSON-файл базы данных |
+| `database.schema` | Необязателен | JSON-настройки проверки запросов и OpenAPI-схем |
+| `files.directory` | С `--files` | Директория для бинарного содержимого |
+| `files.metadata` | С `--files` | JSON-файл с метаданными загруженных файлов |
+| `openapi.path` | С `--openapi` | Генерируемый YAML-файл OpenAPI |
+| `server.host` | Необязателен | Адрес прослушивания; затем используются `HOST` и `127.0.0.1` |
+| `server.port` | Необязателен | Порт; затем используются `PORT` и `4001` |
+
+Все относительные пути вычисляются от директории с `server.config.js`, а не от текущей рабочей директории. Неизвестные ключи, пустые пути и значения некорректных типов отклоняются до запуска. Конфиг является исполняемым JavaScript: в нём можно читать переменные окружения, импортировать другие модули и вычислять значения перед экспортом объекта. Для `.js`-конфига с `export default` проект должен быть ESM (`"type": "module"`); в CommonJS-проекте сохраните тот же конфиг как `server.config.mjs`.
+
+Добавьте нужные команды в `package.json`:
 
 ```json
 {
   "scripts": {
-    "mock": "deep-json-server mock/database.json --port 4001",
-    "openapi": "deep-json-server mock/database.json --generate mock/database-schema.json mock/openapi-schema.yaml"
+    "mock": "deep-json-server --files server.config.js",
+    "openapi": "deep-json-server --openapi --files server.config.js"
   }
 }
 ```
 
-Запустите сервер:
+Режимы CLI:
 
-```bash
-npm run mock
-```
+| Команда | Поведение |
+| --- | --- |
+| `deep-json-server server.config.js` | Запускает CRUD-сервер без файловых маршрутов |
+| `deep-json-server --files server.config.js` | Запускает CRUD-сервер с файловыми маршрутами |
+| `deep-json-server --openapi server.config.js` | Генерирует OpenAPI и завершает работу |
+| `deep-json-server --openapi --files server.config.js` | Генерирует OpenAPI с файловыми маршрутами и завершает работу |
 
-По умолчанию сервер доступен по адресу `http://127.0.0.1:4001`. Адрес и порт можно задать через `--host` и `--port` либо переменные окружения `HOST` и `PORT`.
+`--openapi` никогда не запускает HTTP-сервер. Флаг `--files` независим: без него файловые маршруты не регистрируются и не добавляются в OpenAPI. Команда `deep-json-server --help` выводит краткую справку по CLI.
 
 ## Пример базы данных
 
@@ -106,7 +149,15 @@ PATCH  /movies/:id
 DELETE /movies/:id
 ```
 
-`POST` генерирует строковый ID, а `PUT` и `PATCH` сохраняют исходный тип ID. Все операции записи — `POST`, `PUT`, `PATCH` и `DELETE` — сохраняют изменения в JSON-файле. Файл базы должен существовать до запуска и содержать JSON-объект, каждое свойство верхнего уровня которого является массивом записей отдельного ресурса.
+`POST` генерирует строковый ID. `PUT` полностью заменяет выбранную запись, а `PATCH` изменяет только переданные поля; обе операции сохраняют существующий ID и его тип. Поле `id` в теле любого запроса не может переопределить ID, которым управляет сервер. Все операции записи — `POST`, `PUT`, `PATCH` и `DELETE` — выполняются последовательно и сохраняются в JSON-файле.
+
+Файл базы должен существовать до запуска. Имена ресурсов могут содержать латинские буквы, цифры, `_` и `-` и должны начинаться с буквы. Каждый ресурс является массивом JSON-объектов. У каждой записи должен быть непустой строковый или конечный числовой `id`; ID должны быть уникальны внутри ресурса при сравнении как строки, поэтому `1` и `"1"` не могут существовать одновременно. Перед каждым GET-запросом и изменением сервер заново читает файл, поэтому корректные внешние правки становятся видны без перезапуска.
+
+Успешная операция записи возвращает созданную, заменённую, обновлённую или удалённую запись. Ошибки используют подходящий HTTP-статус и следующий JSON-формат:
+
+```json
+{ "error": "Понятное описание ошибки" }
+```
 
 ## Пагинация и сортировка
 
@@ -128,9 +179,9 @@ GET-запрос к коллекции всегда возвращает объ
 }
 ```
 
-Оба параметра пагинации должны быть положительными целыми числами. При некорректном значении сервер возвращает `400`, а не исправляет его автоматически.
+Оба параметра пагинации должны быть положительными целыми числами. По умолчанию `_perPage` не может превышать `1000`; лимит можно изменить программным параметром `maxPageSize`. При некорректном значении сервер возвращает `400`, а не исправляет его автоматически. Страница после последней возвращает пустой массив `data`, а `prev` указывает на последнюю доступную страницу.
 
-Префикс `-` перед полем включает сортировку по убыванию.
+`_sort` принимает пути полей через запятую. Правила применяются слева направо; префикс `-` включает сортировку по убыванию. Через точку можно обратиться к полю вложенного объекта, включая поля, добавленные через `_embed`, например `GET /users?_embed=country&_sort=country.name,-id`. Неизвестные и небезопасные поля сортировки возвращают `400`.
 
 ## Фильтры
 
@@ -149,18 +200,33 @@ GET /movies?_where={"title":{"contains":"отец"}}
 }
 ```
 
-Доступны логические операторы:
+Для явных логических групп используйте `and`, `or` и `not`:
 
 ```json
 {
-  "or": [
-    { "title": { "contains": "отец" } },
-    { "actors": { "some": { "userId": { "eq": "2" } } } }
+  "and": [
+    {
+      "or": [
+        { "title": { "contains": "отец" } },
+        { "actors": { "some": { "userId": { "eq": "2" } } } }
+      ]
+    },
+    { "not": { "isArchived": { "eq": true } } }
   ]
 }
 ```
 
-Поддерживаются операторы полей: `contains`, `endsWith`, `eq`, `every`, `gt`, `gte`, `in`, `lt`, `lte`, `ne`, `none`, `not`, `some` и `startsWith`.
+Операторы полей:
+
+| Оператор | Поведение |
+| --- | --- |
+| `eq`, `ne` | Равенство или неравенство |
+| `contains` | Подстрока без учёта регистра для строк или совпадающий элемент массива |
+| `startsWith`, `endsWith` | Начало или окончание строки без учёта регистра |
+| `gt`, `gte`, `lt`, `lte` | Сравнение значений; строки дат ISO можно сравнивать лексикографически |
+| `in` | Совпадение скалярного значения или элемента массива с одним из переданных значений |
+| `some`, `every`, `none` | Применение вложенного условия к элементам массива |
+| `not` | Отрицание вложенного условия поля |
 
 Также можно использовать простые query-параметры:
 
@@ -170,42 +236,84 @@ GET /movies?title:contains=отец
 
 В простых фильтрах распознаются JSON-примитивы: числа, `true`, `false` и `null`. Значения с ведущими нулями, например `001`, остаются строками. Неизвестные операторы, некорректные логические условия и отсутствующие в непустом ресурсе пути фильтра возвращают `400`.
 
+Для простого фильтра `in` перечислите значения через запятую: `GET /movies?id:in=1,2`. Если передан `_where`, он становится полным фильтром, а остальные простые параметры фильтрации игнорируются. В примерах JSON оставлен читаемым; при ручном формировании URL HTTP-клиент должен закодировать значение `_where`.
+
+Фильтрация выполняется после `_embed`. Поэтому фильтр может обращаться к полям добавленной связи, если в том же запросе указан соответствующий `_embed`; сохранённые поля `...Id` и `...Ids` всегда можно фильтровать напрямую.
+
 ## Связи
 
-Используйте `_embed`, чтобы заменить ID связанными записями:
+Используйте `_embed`, чтобы добавить связанные записи в ответ:
 
 ```http
 GET /movies/1?_embed=actors.user.country&_embed=actors.genres&_embed=publishers
 ```
 
-Ответ будет содержать актёров, пользователя и жанры каждого актёра, страну пользователя и издателей. Глубина вложения не ограничена:
+Ответ будет содержать актёров, пользователя и жанры каждого актёра, страну пользователя и издателей. Исходные поля с ID остаются в ответе, а файл базы не изменяется. Глубина вложения не ограничена:
 
 ```http
 GET /movies/1?_embed=actors.user.country
 GET /genres/2?_embed=parents.parents
 ```
 
+Неизвестные и некорректные пути `_embed` возвращают `400`.
+
+Параметр `_embed` можно передать несколько раз, как в примере выше, либо перечислить пути через запятую в одном параметре. Пагинация применяется только к запрошенной корневой коллекции; вложенные связанные записи возвращаются полностью.
+
 Поддерживаются и обратные связи:
 
 ```http
 GET /countries/1?_embed=users
 ```
 
-Связи определяются по неймингу:
+Связи определяются по неймингу. Поле `<relation>Id` создаёт одиночную связь, а `<relation>Ids` — связь с коллекцией. Имя связи сопоставляется с ресурсом верхнего уровня напрямую или через его форму в единственном числе. Например:
 
 - `countryId` ссылается на `countries`;
 - `userId` ссылается на `users`, если запрошена связь `user`;
 - `genreIds` ссылается на `genres`;
 - `publisherIds` ссылается на `publishers`;
-- `parentIds` ссылается на тот же ресурс, если запрошена связь `_embed=parents`.
+- `parentIds` ссылается на тот же ресурс, если запрошена связь `_embed=parents`; `_embed=children` загружает обратную связь с дочерними записями.
 
-Это мягкие ссылки: сервер загружает их по запросу, но не проверяет ссылочную целостность при записи данных.
+Имя обратной связи совпадает с именем исходного ресурса. Например, `_embed=users` у страны находит пользователей, во вложенных данных которых указан соответствующий `countryId`. Это мягкие ссылки: сервер загружает их по запросу, но не проверяет ссылочную целостность при записи данных.
 
-Явное поле `...Id` или `...Ids` считается источником истины. Если в записи также сохранено устаревшее вложенное значение, `_embed` заменяет его актуальной связанной записью. Для поиска связей лениво создаются ID-индексы только используемых в текущем запросе ресурсов.
+Явное поле `...Id` или `...Ids` считается источником истины. Если в записи также сохранено устаревшее вложенное значение, `_embed` заменяет это свойство ответа актуальной связанной записью. Если цель одиночной связи не найдена, результатом будет `null`; отсутствующие цели связи с коллекцией не попадут в итоговый массив. Для поиска связей лениво создаются ID-индексы только используемых в текущем запросе ресурсов.
 
-## Генерация OpenAPI
+## Файлы
 
-Создайте рядом с базой небольшой файл конфигурации, например `mock/database-schema.json`:
+Добавьте `files.directory` и `files.metadata` в конфиг сервера, затем передайте `--files`, чтобы включить загрузку бинарных файлов:
+
+```bash
+deep-json-server --files server.config.js
+```
+
+Один файл отправляется непосредственно в теле запроса. Оба заголовка обязательны: `Content-Name` содержит относительное логическое имя, закодированное через `encodeURIComponent`, а `Content-Type` — MIME-тип файла:
+
+```http
+POST /_files
+Content-Name: posters%2Fthe-godfather.jpg
+Content-Type: image/jpeg
+
+<binary body>
+```
+
+Ответ содержит метаданные и постоянный URL:
+
+```json
+{
+  "id": "generated-id",
+  "mimeType": "image/jpeg",
+  "name": "posters/the-godfather.jpg",
+  "size": 182340,
+  "url": "/_files/generated-id"
+}
+```
+
+`GET /_files/:id` возвращает исходные байты, а `DELETE /_files/:id` удаляет бинарное содержимое вместе с метаданными. Возвращаемый `url` задаётся относительно адреса mock-сервера. Сервер автоматически создаёт настроенные директории, хранит бинарное содержимое под сгенерированными ID без привязки к исходному имени и записывает логические имена и остальные метаданные в `files.metadata`. Изначально файл метаданных может отсутствовать: он создаётся при первой загрузке. Не редактируйте его во время работы сервера.
+
+Используется бинарное тело запроса, а не `multipart/form-data`, поэтому `XMLHttpRequest.upload.onprogress` может показывать прогресс при непосредственной отправке `File` через `xhr.send(file)`. Максимальный размер по умолчанию равен 100 МиБ и настраивается программным параметром `maxFileSize`. Небезопасный или абсолютный путь в `Content-Name` возвращает `400`, превышение лимита — `413`, а некорректный или неподдерживаемый `Content-Type` — `400` или `415`.
+
+## Схема базы данных и генерация OpenAPI
+
+Необязательный JSON-файл, указанный в `database.schema`, например `mock/database-schema.json`, настраивает автоматически выведенные схемы. Он читается как при обычном запуске сервера, так и при генерации OpenAPI:
 
 ```json
 {
@@ -231,13 +339,23 @@ GET /countries/1?_embed=users
 }
 ```
 
-Сгенерируйте OpenAPI 3.0.3 и завершите работу:
+Настройки схемы:
+
+| Ключ | Назначение |
+| --- | --- |
+| `$info` | Объект `info` в OpenAPI; если он указан, обязательны непустые `title` и `version` |
+| `$schema.<resource>.name` | Явное имя компонента, если автоматическое образование единственного числа не подходит или создаёт коллизию |
+| `$schema.<resource>.required` | Пути обязательных полей; вложенные пути записываются через точку, например `actors.userId` |
+| `$schema.<resource>.formats` | Форматы OpenAPI для автоматически найденных или явно описанных строковых полей, например `date`, `date-time` или `uri` |
+| `$schema.<resource>.properties` | Рекурсивные OpenAPI-совместимые схемы полей, объединяемые с автоматически найденными |
+
+Укажите `openapi.path` в конфиге сервера, затем сгенерируйте OpenAPI 3.0.3 и завершите работу:
 
 ```bash
-deep-json-server mock/database.json --generate mock/database-schema.json mock/openapi-schema.yaml --host 127.0.0.1 --port 4001
+deep-json-server --openapi --files server.config.js
 ```
 
-Генератор определяет ресурсы и типы полей по всем записям базы. По умолчанию все найденные поля необязательные, а поле `id` верхнего уровня, присутствующее в итоговой схеме ресурса, всегда обязательное. Остальные обязательные поля перечисляются в `required`; для вложенных полей используются пути через точку, например `actors.userId`. Объект `formats` добавляет форматы OpenAPI, например `date` и `uri`.
+Генератор определяет ресурсы и типы полей по всем записям базы. По умолчанию все найденные поля необязательные, а поле `id` верхнего уровня всегда обязательное в схемах ответа и исключается из схем создания и обновления. Остальные обязательные поля перечисляются в `required`. Вложенный обязательный путь делает обязательным само вложенное свойство, но не все его родительские пути; при необходимости родителя нужно перечислить отдельно.
 
 Разные типы значений определяются независимо и объединяются через `oneOf`. Перед генерацией проверяются `$info`, имена ресурсов и схем, а также структура `properties`; пути из `required` и `formats` должны существовать в итоговой схеме.
 
@@ -257,9 +375,9 @@ deep-json-server mock/database.json --generate mock/database-schema.json mock/op
 }
 ```
 
-Пустой ресурс всё равно получает обязательное строковое поле `id`, поскольку сервер создаёт строковые ID. При совпадении имён схем или `operationId` генерация завершается понятной ошибкой; коллизию имён схем можно устранить с помощью явного `name`.
+Пустой ресурс всё равно получает обязательное строковое поле `id`, поскольку сервер создаёт строковые ID. При совпадении имён схем или `operationId` генерация завершается понятной ошибкой; коллизию имён схем можно устранить с помощью явного `name`. Директория результата создаётся автоматически, а настроенный YAML-файл заменяется при каждой генерации.
 
-`$info` становится объектом `info` в OpenAPI, а настройки ресурсов находятся внутри `$schema`. Поле `servers` в OpenAPI формируется автоматически из параметров `--host` и `--port`, соответствующих переменных окружения `HOST` и `PORT` или адреса по умолчанию `http://127.0.0.1:4001`.
+`$info` становится объектом `info` в OpenAPI, а настройки ресурсов находятся внутри `$schema`. Поле `servers` в OpenAPI формируется автоматически из `server.host` и `server.port`, резервных переменных окружения `HOST` и `PORT` или адреса по умолчанию `http://127.0.0.1:4001`.
 
 Используйте `name`, если ресурсу нужно явно задать имя схемы вместо автоматически полученного имени в единственном числе:
 
@@ -273,22 +391,73 @@ deep-json-server mock/database.json --generate mock/database-schema.json mock/op
 }
 ```
 
-В сгенерированном документе описаны CRUD, пагинация, сортировка, глубокие фильтры, `_embed` и связи в ответах, определённые по полям `...Id` и `...Ids`. Файл можно передать, например, в RTK Query OpenAPI Codegen. OpenAPI создаётся только с параметром `--generate`; обычный запуск сервера файл не перезаписывает.
+В сгенерированном документе описаны CRUD, пагинация, сортировка, глубокие фильтры, `_embed`, а также прямые и обратные связи в ответах, определённые по полям `...Id` и `...Ids`. При наличии `--files` в него также добавляются маршруты бинарной загрузки, получения и удаления файлов. Числовой ID базы описывается как `integer | string`, поскольку последующий `POST` создаст строковый ID в том же ресурсе. Файл можно передать, например, в RTK Query OpenAPI Codegen. OpenAPI создаётся только с параметром `--openapi`; обычный запуск сервера файл не перезаписывает.
+
+При обычном запуске тела запросов проверяются по тем же автоматически выведенным и настроенным схемам. Для `POST` и `PUT` проверяются обязательные поля из `required`; `PATCH` проверяет только фактически переданные поля. Настройки `formats` и `properties` применяются ко всем трём методам. Не перечисленные дополнительные поля объекта остаются разрешёнными. Некорректные тела возвращают `400`.
+
+## Назначение и безопасность
+
+Deep JSON Server предназначен для локальной разработки и автоматических тестов. В нём нет аутентификации и авторизации, CORS разрешён для любого источника, принятые изменения напрямую сохраняются в настроенные файлы, а ссылочная целостность не проверяется. Оставляйте адрес loopback по умолчанию, если внешняя среда не предоставляет собственный контроль доступа; не открывайте сервер и файловые маршруты для недоверенной сети.
 
 ## Программный API
 
 ```js
-import { createServer, generateOpenApi, startServer } from '@kollors/deep-json-server';
-
-const server = await createServer({ databasePath: 'mock/database.json', logger: false });
+import { createOpenApiDocument, createServer, generateOpenApi, startServer } from '@kollors/deep-json-server';
+
+// Создание экземпляра без открытия порта, например для тестов.
+const server = await createServer({
+  databasePath: 'mock/database.json',
+  filesDirectoryPath: 'mock/files',
+  filesMetadataPath: 'mock/files/_database.json',
+  logger: false,
+  maxFileSize: 100 * 1024 * 1024,
+  maxPageSize: 1000,
+  schemaPath: 'mock/database-schema.json',
+});
 
 const response = await server.inject({ method: 'GET', url: '/movies' });
 
 await server.close();
 
-await startServer({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001 });
-
-await generateOpenApi({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001, schemaPath: 'mock/database-schema.json', outputPath: 'mock/openapi-schema.yaml' });
+// Создание экземпляра и начало прослушивания.
+const listeningServer = await startServer({
+  databasePath: 'mock/database.json',
+  host: '127.0.0.1',
+  port: 4001,
+  schemaPath: 'mock/database-schema.json',
+});
+
+await listeningServer.close();
+
+// Чтение файлов базы и схемы с последующей записью OpenAPI YAML.
+await generateOpenApi({
+  databasePath: 'mock/database.json',
+  files: true,
+  host: '127.0.0.1',
+  outputPath: 'mock/openapi-schema.yaml',
+  port: 4001,
+  schemaPath: 'mock/database-schema.json',
+});
+
+// Создание такого же OpenAPI-документа полностью в памяти.
+const document = createOpenApiDocument(
+  { movies: [{ id: '1', title: 'Крёстный отец' }] },
+  { $info: { title: 'API фильмов', version: '1.0.0' } },
+  { files: true, host: '127.0.0.1', port: 4001 },
+);
 ```
 
-`createServer()` удобен для тестов: он возвращает экземпляр Fastify, не открывая сетевой порт.
+Параметры программного API:
+
+| Параметр | Где используется | Назначение |
+| --- | --- | --- |
+| `databasePath` | `createServer`, `startServer`, `generateOpenApi` | Обязательный путь к JSON-базе |
+| `schemaPath` | Те же три функции | Необязательный путь к схеме базы |
+| `filesDirectoryPath`, `filesMetadataPath` | `createServer`, `startServer` | Необязательная пара, включающая файловые маршруты |
+| `files` | `generateOpenApi`, `createOpenApiDocument` | Нужно ли добавлять файловые маршруты в OpenAPI |
+| `host`, `port` | `startServer`, `generateOpenApi`, `createOpenApiDocument` | Адрес прослушивания или URL в поле `servers` |
+| `logger` | `createServer`, `startServer` | Настройки логгера Fastify; значение по умолчанию — `true` |
+| `maxPageSize`, `maxFileSize` | `createServer`, `startServer` | Ограничения сервера; по умолчанию 1000 записей и 100 МиБ |
+| `outputPath` | `generateOpenApi` | Обязательный путь к генерируемому YAML-файлу |
+
+`createServer()` возвращает экземпляр Fastify без открытия сетевого порта, поэтому удобен вместе с `server.inject()` в тестах. `startServer()` дополнительно начинает прослушивание. `generateOpenApi()` читает файлы и записывает YAML, а `createOpenApiDocument()` работает с объектами базы и схемы в памяти и ничего не записывает. Эти функции не читают `server.config.js`: параметры нужно передавать явно. Пакет содержит сгенерированные TypeScript-декларации для всех экспортируемых функций.

package/bin/deep-json-server.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import { runCli } from '../src/cli.js';
+
+try {
+  await runCli();
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/index.js

@@ -1,12 +1,2 @@
-#!/usr/bin/env node
-
-import process from 'node:process';
-import { runCli } from './src/cli.js';
-import { isMainModule } from './src/utils.js';
-
-export { createOpenApiDocument, generateOpenApi } from './src/openapi.js';
+export { createOpenApiDocument, generateOpenApi } from './src/openapi/index.js';
 export { createServer, startServer } from './src/server.js';
-
-if (isMainModule(process.argv[1], import.meta.url)) {
-  await runCli();
-}

package/package.json

@@ -1,24 +1,37 @@
 {
   "name": "@kollors/deep-json-server",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "JSON mock server with deep filters and recursive relationship embedding",
   "type": "module",
+  "types": "./types/index.d.ts",
   "bin": {
-    "deep-json-server": "index.js"
+    "deep-json-server": "bin/deep-json-server.js"
   },
   "exports": {
-    ".": "./index.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./index.js"
+    }
   },
   "files": [
+    "bin",
     "index.js",
     "src",
+    "types",
     "LICENSE",
     "README.md",
     "README.ru.md"
   ],
   "scripts": {
-    "check": "node --check index.js && node --check src/*.js",
-    "test": "node --test"
+    "check": "node --check index.js && node --check bin/deep-json-server.js && node --check src/*.js && node --check src/openapi/*.js && node --check src/query/*.js",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "prepack": "npm run types",
+    "prepublishOnly": "npm run verify",
+    "test": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-lines=90 --test-coverage-branches=80 --test-coverage-functions=90",
+    "types": "tsc -p tsconfig.types.json",
+    "verify": "npm run check && npm run lint && npm run test:coverage && npm run types"
   },
   "engines": {
     "node": ">=20"
@@ -49,5 +62,9 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.11",
+    "typescript": "^7.0.2"
   }
 }

package/src/cli.js

@@ -1,74 +1,90 @@
 import process from 'node:process';
-import { generateOpenApi } from './openapi.js';
+import { readServerConfig } from './config.js';
+import { DEFAULT_HOST, DEFAULT_PORT } from './constants.js';
+import { generateOpenApi } from './openapi/index.js';
 import { startServer } from './server.js';
 
-const HELP = `Deep JSON Server
+const HELP_TEXT = `Deep JSON Server
 
 Использование:
-  deep-json-server <database.json> [--host <host>] [--port <port>]
-  deep-json-server <database.json> --generate <database-schema.json> <openapi-schema.yaml> [--host <host>] [--port <port>]
+  deep-json-server [--openapi] [--files] <server.config.js>
 
 Параметры:
-  --generate  Сгенерировать OpenAPI и завершить работу
-  --host, -h  Адрес сервера (по умолчанию 127.0.0.1)
-  --port, -p  Порт сервера (по умолчанию 4001)
-  --help      Показать справку`;
-
-const parseServerOptions = (args) => {
-  const options = {};
-
-  for (let index = 1; index < args.length; index += 2) {
-    const option = args[index];
-    const value = args[index + 1];
-
-    if (!['--host', '-h', '--port', '-p'].includes(option)) {
-      throw new Error(`Неизвестный параметр: ${option}`);
-    }
-
-    if (value == null || value.startsWith('-')) {
-      throw new Error(`Не указано значение параметра ${option}`);
+  --openapi  Сгенерировать OpenAPI и завершить работу
+  --files    Добавить файловые маршруты в сервер или OpenAPI
+  --help     Показать справку`;
+
+const parseArguments = (args) => {
+  const flags = { files: false, openapi: false };
+  let configPath;
+
+  args.forEach((argument) => {
+    if (argument === '--files') {
+      flags.files = true;
+    } else if (argument === '--openapi') {
+      flags.openapi = true;
+    } else if (argument.startsWith('-')) {
+      throw new Error(`Неизвестный параметр: ${argument}`);
+    } else if (configPath == null) {
+      configPath = argument;
+    } else {
+      throw new Error('Можно указать только один файл конфигурации');
     }
+  });
 
-    options[['--host', '-h'].includes(option) ? 'host' : 'port'] = value;
+  if (configPath == null) {
+    throw new Error('Укажите путь к файлу конфигурации');
   }
 
-  return options;
+  return { configPath, ...flags };
 };
 
-export async function runCli(args = process.argv.slice(2)) {
-  if (args.includes('--help')) {
-    process.stdout.write(`${HELP}\n`);
-    return;
+const validateModeConfig = (config, { files, openapi }) => {
+  if (openapi && config.openapiPath == null) {
+    throw new Error('Для --openapi укажите ключ config.openapi.path');
   }
 
-  const [databasePath] = args;
-
-  if (databasePath == null || databasePath.startsWith('-')) {
-    throw new Error('Укажите путь к JSON-базе данных');
+  if (files && config.filesDirectoryPath == null) {
+    throw new Error('Для --files укажите ключ config.files.directory');
   }
 
-  const generateIndex = args.indexOf('--generate');
-
-  if (generateIndex !== -1) {
-    const schemaPath = args[generateIndex + 1];
-    const outputPath = args[generateIndex + 2];
-
-    if (generateIndex !== 1 || schemaPath == null || outputPath == null) {
-      throw new Error('Используйте: deep-json-server <database.json> --generate <database-schema.json> <openapi-schema.yaml> [--host <host>] [--port <port>]');
-    }
-
-    const options = parseServerOptions([databasePath, ...args.slice(4)]);
-    const host = options.host ?? process.env.HOST ?? '127.0.0.1';
-    const port = Number(options.port ?? process.env.PORT ?? 4001);
+  if (files && config.filesMetadataPath == null) {
+    throw new Error('Для --files укажите ключ config.files.metadata');
+  }
+};
 
-    await generateOpenApi({ databasePath, host, outputPath, port, schemaPath });
-    process.stdout.write(`OpenAPI-схема сохранена в ${outputPath}\n`);
+export async function runCli(args = process.argv.slice(2), services = { generateOpenApi, startServer }) {
+  if (args.includes('--help')) {
+    process.stdout.write(`${HELP_TEXT}\n`);
     return;
   }
 
-  const options = parseServerOptions(args);
-  const host = options.host ?? process.env.HOST ?? '127.0.0.1';
-  const port = Number(options.port ?? process.env.PORT ?? 4001);
+  const { configPath, files, openapi } = parseArguments(args);
+  const config = await readServerConfig(configPath);
+  const host = config.host ?? process.env.HOST ?? DEFAULT_HOST;
+  const port = config.port ?? Number(process.env.PORT ?? DEFAULT_PORT);
+
+  validateModeConfig(config, { files, openapi });
+
+  if (openapi) {
+    await services.generateOpenApi({
+      databasePath: config.databasePath,
+      files,
+      host,
+      outputPath: config.openapiPath,
+      port,
+      schemaPath: config.schemaPath,
+    });
+    process.stdout.write(`OpenAPI-схема сохранена в ${config.openapiPath}\n`);
+    return;
+  }
 
-  await startServer({ databasePath, host, port });
+  await services.startServer({
+    databasePath: config.databasePath,
+    filesDirectoryPath: files ? config.filesDirectoryPath : undefined,
+    filesMetadataPath: files ? config.filesMetadataPath : undefined,
+    host,
+    port,
+    schemaPath: config.schemaPath,
+  });
 }