@kollors/deep-json-server 0.4.0 → 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 --schema mock/database-schema.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,9 +149,15 @@ PATCH  /movies/:id
 DELETE /movies/:id
 ```
 
-`POST` генерирует строковый ID, а `PUT` и `PATCH` сохраняют исходный тип ID. Все операции записи — `POST`, `PUT`, `PATCH` и `DELETE` — сохраняют изменения в JSON-файле.
+`POST` генерирует строковый ID. `PUT` полностью заменяет выбранную запись, а `PATCH` изменяет только переданные поля; обе операции сохраняют существующий ID и его тип. Поле `id` в теле любого запроса не может переопределить ID, которым управляет сервер. Все операции записи — `POST`, `PUT`, `PATCH` и `DELETE` — выполняются последовательно и сохраняются в JSON-файле.
 
-Файл базы должен существовать до запуска. Имена ресурсов могут содержать латинские буквы, цифры, `_` и `-` и должны начинаться с буквы. Каждый ресурс является массивом JSON-объектов. У каждой записи должен быть непустой строковый или конечный числовой `id`; ID должны быть уникальны внутри ресурса при сравнении как строки, поэтому `1` и `"1"` не могут существовать одновременно.
+Файл базы должен существовать до запуска. Имена ресурсов могут содержать латинские буквы, цифры, `_` и `-` и должны начинаться с буквы. Каждый ресурс является массивом JSON-объектов. У каждой записи должен быть непустой строковый или конечный числовой `id`; ID должны быть уникальны внутри ресурса при сравнении как строки, поэтому `1` и `"1"` не могут существовать одновременно. Перед каждым GET-запросом и изменением сервер заново читает файл, поэтому корректные внешние правки становятся видны без перезапуска.
+
+Успешная операция записи возвращает созданную, заменённую, обновлённую или удалённую запись. Ошибки используют подходящий HTTP-статус и следующий JSON-формат:
+
+```json
+{ "error": "Понятное описание ошибки" }
+```
 
 ## Пагинация и сортировка
 
@@ -132,7 +181,7 @@ GET-запрос к коллекции всегда возвращает объ
 
 Оба параметра пагинации должны быть положительными целыми числами. По умолчанию `_perPage` не может превышать `1000`; лимит можно изменить программным параметром `maxPageSize`. При некорректном значении сервер возвращает `400`, а не исправляет его автоматически. Страница после последней возвращает пустой массив `data`, а `prev` указывает на последнюю доступную страницу.
 
-Префикс `-` перед полем включает сортировку по убыванию. Неизвестные и небезопасные поля сортировки возвращают `400`.
+`_sort` принимает пути полей через запятую. Правила применяются слева направо; префикс `-` включает сортировку по убыванию. Через точку можно обратиться к полю вложенного объекта, включая поля, добавленные через `_embed`, например `GET /users?_embed=country&_sort=country.name,-id`. Неизвестные и небезопасные поля сортировки возвращают `400`.
 
 ## Фильтры
 
@@ -151,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-параметры:
 
@@ -172,15 +236,19 @@ 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
@@ -189,27 +257,63 @@ 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
 {
@@ -235,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` должны существовать в итоговой схеме.
 
@@ -261,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`, если ресурсу нужно явно задать имя схемы вместо автоматически полученного имени в единственном числе:
 
@@ -277,24 +391,73 @@ deep-json-server mock/database.json --generate mock/database-schema.json mock/op
 }
 ```
 
-В сгенерированном документе описаны CRUD, пагинация, сортировка, глубокие фильтры, `_embed`, а также прямые и обратные связи в ответах, определённые по полям `...Id` и `...Ids`. Числовой ID базы описывается как `integer | string`, поскольку последующий `POST` создаст строковый ID в том же ресурсе. Файл можно передать, например, в RTK Query OpenAPI Codegen. OpenAPI создаётся только с параметром `--generate`; обычный запуск сервера файл не перезаписывает.
+В сгенерированном документе описаны CRUD, пагинация, сортировка, глубокие фильтры, `_embed`, а также прямые и обратные связи в ответах, определённые по полям `...Id` и `...Ids`. При наличии `--files` в него также добавляются маршруты бинарной загрузки, получения и удаления файлов. Числовой ID базы описывается как `integer | string`, поскольку последующий `POST` создаст строковый ID в том же ресурсе. Файл можно передать, например, в RTK Query OpenAPI Codegen. OpenAPI создаётся только с параметром `--openapi`; обычный запуск сервера файл не перезаписывает.
 
-При обычном запуске тела запросов проверяются по автоматически выведенным схемам ресурсов. Передайте `--schema mock/database-schema.json`, чтобы в runtime применялись те же явные ограничения `required`, `formats` и `properties`. Некорректные тела `POST`, `PUT` и `PATCH` возвращают `400`.
+При обычном запуске тела запросов проверяются по тем же автоматически выведенным и настроенным схемам. Для `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, maxPageSize: 1000, schemaPath: 'mock/database-schema.json' });
+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, schemaPath: 'mock/database-schema.json' });
-
-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, не открывая сетевой порт. Пакет содержит сгенерированные TypeScript-декларации для всех экспортируемых функций.
+Параметры программного 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kollors/deep-json-server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "JSON mock server with deep filters and recursive relationship embedding",
   "type": "module",
   "types": "./types/index.d.ts",

package/src/cli.js

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

package/src/config.js

@@ -0,0 +1,97 @@
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isObject } from './utils.js';
+
+const CONFIG_KEYS = new Set(['database', 'files', 'openapi', 'server']);
+const DATABASE_KEYS = new Set(['path', 'schema']);
+const FILES_KEYS = new Set(['directory', 'metadata']);
+const OPENAPI_KEYS = new Set(['path']);
+const SERVER_KEYS = new Set(['host', 'port']);
+let configImportIndex = 0;
+
+const assertKnownKeys = (value, keys, path) => {
+  const unknownKey = Object.keys(value).find((key) => !keys.has(key));
+
+  if (unknownKey != null) {
+    throw new Error(`Неизвестный ключ ${path}.${unknownKey}`);
+  }
+};
+
+const getObject = (value, path) => {
+  if (value == null) {
+    return {};
+  }
+
+  if (!isObject(value)) {
+    throw new Error(`Ключ ${path} должен быть JSON-объектом`);
+  }
+
+  return value;
+};
+
+const getString = (value, path, required = false) => {
+  if (value == null && !required) {
+    return undefined;
+  }
+
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`Ключ ${path} должен содержать непустую строку`);
+  }
+
+  return value;
+};
+
+const resolveConfigPath = (value, directoryPath) => (value == null ? undefined : resolve(directoryPath, value));
+
+export async function readServerConfig(configPath) {
+  const resolvedConfigPath = resolve(getString(configPath, 'config', true));
+  let config;
+
+  try {
+    const configUrl = pathToFileURL(resolvedConfigPath);
+
+    configUrl.searchParams.set('deep-json-server-import', String(configImportIndex++));
+    config = (await import(configUrl.href)).default;
+  } catch (error) {
+    throw new Error(`Не удалось загрузить конфигурацию ${resolvedConfigPath}: ${error.message}`, { cause: error });
+  }
+
+  if (!isObject(config)) {
+    throw new Error('Конфигурация сервера должна экспортировать JSON-объект через export default');
+  }
+
+  assertKnownKeys(config, CONFIG_KEYS, 'config');
+
+  const database = getObject(config.database, 'config.database');
+  const files = getObject(config.files, 'config.files');
+  const openapi = getObject(config.openapi, 'config.openapi');
+  const server = getObject(config.server, 'config.server');
+
+  assertKnownKeys(database, DATABASE_KEYS, 'config.database');
+  assertKnownKeys(files, FILES_KEYS, 'config.files');
+  assertKnownKeys(openapi, OPENAPI_KEYS, 'config.openapi');
+  assertKnownKeys(server, SERVER_KEYS, 'config.server');
+
+  const directoryPath = dirname(resolvedConfigPath);
+  const databasePath = getString(database.path, 'config.database.path', true);
+  const schemaPath = getString(database.schema, 'config.database.schema');
+  const openapiPath = getString(openapi.path, 'config.openapi.path');
+  const filesDirectory = getString(files.directory, 'config.files.directory');
+  const filesMetadata = getString(files.metadata, 'config.files.metadata');
+  const host = getString(server.host, 'config.server.host');
+
+  if (server.port != null && (!Number.isInteger(server.port) || server.port < 0 || server.port > 65_535)) {
+    throw new Error('Ключ config.server.port должен быть целым числом от 0 до 65535');
+  }
+
+  return {
+    configPath: resolvedConfigPath,
+    databasePath: resolveConfigPath(databasePath, directoryPath),
+    filesDirectoryPath: resolveConfigPath(filesDirectory, directoryPath),
+    filesMetadataPath: resolveConfigPath(filesMetadata, directoryPath),
+    host,
+    openapiPath: resolveConfigPath(openapiPath, directoryPath),
+    port: server.port,
+    schemaPath: resolveConfigPath(schemaPath, directoryPath),
+  };
+}

package/src/constants.js

@@ -1,4 +1,5 @@
 export const DEFAULT_HOST = '127.0.0.1';
+export const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024;
 export const DEFAULT_PAGE_SIZE = 10;
 export const DEFAULT_PORT = 4001;
 export const MAX_PAGE_SIZE = 1000;