@kollors/deep-json-server 0.5.0 → 0.6.0

package/README.ru.md

@@ -4,7 +4,7 @@
 
 [GitHub](https://github.com/kollors/deep-json-server) | [npm](https://www.npmjs.com/package/@kollors/deep-json-server)
 
-Небольшой JSON REST mock-сервер с CRUD, пагинацией, глубокой фильтрацией и рекурсивной загрузкой связей. База данных хранится в одном читаемом JSON-файле, а мягкие связи определяются по соглашениям о нейминге ключей: `countryId`, `genreIds`, `publisherIds` и так далее.
+Небольшой моковый REST-сервер с CRUD, пагинацией, глубокими фильтрами, рекурсивной загрузкой связей, бинарными файлами и генерацией OpenAPI. Данные могут храниться в JSON-файлах или памяти, а связи определяются по соглашениям о нейминге ключей: `countryId`, `genreIds`, `publisherIds` и так далее.
 
 ## Установка
 
@@ -14,6 +14,43 @@
 npm install --save-dev @kollors/deep-json-server
 ```
 
+## Быстрый старт
+
+До запуска создайте файл базы `mock/database.json`:
+
+```json
+{
+  "movies": [
+    { "id": "1", "title": "Тени Ардении" }
+  ]
+}
+```
+
+Рядом с `package.json` создайте ESM-модуль `server.config.js`:
+
+```js
+export default {
+  database: {
+    path: 'mock/database.json',
+  },
+};
+```
+
+Запустите сервер:
+
+```bash
+npx deep-json-server server.config.js
+```
+
+По умолчанию API доступен по адресу `http://127.0.0.1:4001`. Например, `GET http://127.0.0.1:4001/movies` вернёт страницу:
+
+```json
+{
+  "data": [{ "id": "1", "title": "Тени Ардении" }],
+  "total": 1
+}
+```
+
 ## Конфигурация и запуск
 
 Создайте ESM-модуль `server.config.js`. В примере ниже включены настройки всех возможностей:
@@ -35,6 +72,9 @@ export default {
   },
   server: {
     host: '127.0.0.1',
+    logger: true,
+    maxFileSize: 100 * 1024 * 1024,
+    maxPageSize: 1000,
     port: 4001,
   },
 };
@@ -42,25 +82,51 @@ export default {
 
 Ключи конфигурации:
 
-| Ключ | Когда обязателен | Назначение |
+| Ключ | Условие | Назначение |
 | --- | --- | --- |
-| `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` |
+| `database.path` | Требуется ровно один из `path` или `data` | Существующий JSON-файл базы данных |
+| `database.data` | Требуется ровно один из `path` или `data` | Объект базы данных, хранящийся в памяти |
+| `database.schema` | Необязателен | Путь к JSON-настройкам либо объект с настройками проверки запросов и OpenAPI |
+| `files.directory` | Вместе с `files.metadata` | Директория для бинарного содержимого на диске |
+| `files.metadata` | Вместе с `files.directory` | JSON-файл с метаданными файлов на диске |
+| `files.data` | Вместо пары `directory` и `metadata` | Файлы в памяти с содержимым в `Uint8Array` |
+| `openapi.path` | Обязателен для CLI-флагов `--openapi` и `--openapi-only` | Генерируемый YAML-файл OpenAPI; программный API может вернуть документ без этого пути |
+| `server.host` | Необязателен | Адрес для CLI, `server.openapi()` и вызова `server.fastify().listen()` без аргументов; по умолчанию `127.0.0.1` |
+| `server.logger` | Необязателен | Настройки логгера Fastify; по умолчанию `true` |
+| `server.maxFileSize` | Необязателен | Максимальный размер загружаемого файла в байтах при включённых файловых маршрутах; по умолчанию 100 МиБ |
+| `server.maxPageSize` | Необязателен | Максимальное значение `_perPage` в API и OpenAPI; по умолчанию `1000` |
+| `server.port` | Необязателен | Порт для CLI, `server.openapi()` и вызова `server.fastify().listen()` без аргументов; по умолчанию `4001` |
+
+`server.port` должен быть целым числом от `0` до `65535`. Значение `0` позволяет Fastify выбрать свободный порт при запуске, но не подходит для генерации URL в OpenAPI, где допустимы порты от `1` до `65535`. `server.maxFileSize` и `server.maxPageSize` должны быть положительными целыми числами.
 
 Все относительные пути вычисляются от директории с `server.config.js`, а не от текущей рабочей директории. Неизвестные ключи, пустые пути и значения некорректных типов отклоняются до запуска. Конфиг является исполняемым JavaScript: в нём можно читать переменные окружения, импортировать другие модули и вычислять значения перед экспортом объекта. Для `.js`-конфига с `export default` проект должен быть ESM (`"type": "module"`); в CommonJS-проекте сохраните тот же конфиг как `server.config.mjs`.
 
-Добавьте нужные команды в `package.json`:
+В том же конфиге все данные можно разместить в памяти. `database.path` и `database.data` взаимоисключающие, а `database.schema` принимает путь или объект. Аналогично, `files.data` нельзя сочетать с `files.directory` или `files.metadata`:
+
+```js
+export default {
+  database: {
+    data: { movies: [{ id: '1', title: 'Тени Ардении' }] },
+    schema: { $info: { title: 'API фильмов', version: '1.0.0' } },
+  },
+  files: {
+    data: [{ content: new Uint8Array([1, 2, 3]), id: 'file-1', mimeType: 'application/octet-stream', name: 'example.bin' }],
+  },
+};
+```
+
+Значения в памяти клонируются при инициализации. Поэтому операции с CRUD и файлами не изменяют экспортированный объект конфига, а их результаты исчезают после завершения процесса.
+
+Добавьте нужные команды в `package.json`. Здесь `mock:openapi:files` сначала обновляет OpenAPI, а затем оставляет сервер запущенным с файловыми маршрутами:
 
 ```json
 {
   "scripts": {
-    "mock": "deep-json-server --files server.config.js",
-    "openapi": "deep-json-server --openapi --files server.config.js"
+    "mock": "deep-json-server server.config.js",
+    "mock:files": "deep-json-server --files server.config.js",
+    "mock:openapi:files": "deep-json-server --files --openapi server.config.js",
+    "openapi": "deep-json-server --openapi-only server.config.js",
+    "openapi:files": "deep-json-server --files --openapi-only server.config.js"
   }
 }
 ```
@@ -71,24 +137,26 @@ export default {
 | --- | --- |
 | `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 с файловыми маршрутами и завершает работу |
+| `deep-json-server --openapi server.config.js` | Генерирует OpenAPI и запускает CRUD-сервер |
+| `deep-json-server --files --openapi server.config.js` | Генерирует OpenAPI с файловыми маршрутами и запускает сервер с ними |
+| `deep-json-server --openapi-only server.config.js` | Генерирует OpenAPI и завершает работу |
+| `deep-json-server --files --openapi-only server.config.js` | Генерирует OpenAPI с файловыми маршрутами и завершает работу |
 
-`--openapi` никогда не запускает HTTP-сервер. Флаг `--files` независим: без него файловые маршруты не регистрируются и не добавляются в OpenAPI. Команда `deep-json-server --help` выводит краткую справку по CLI.
+Флаг `--files` независим: без него файловые маршруты не регистрируются и не добавляются в OpenAPI, даже если секция `files` присутствует в конфиге. Параметры `--openapi` и `--openapi-only` взаимоисключающие. Команда `deep-json-server --help` выводит краткую справку по CLI.
 
 ## Пример базы данных
 
-Пример основан на каталоге фильмов. `Гангстерский фильм` демонстрирует связь с родительским жанром.
+Ниже приведён пример каталога фильмов с тестовыми данными. `Гангстер` связан с родительским жанром `Криминал`.
 
 ```json
 {
   "countries": [
-    { "id": "1", "isArchived": false, "name": "Россия" },
-    { "id": "2", "isArchived": false, "name": "США" }
+    { "id": "1", "isArchived": false, "name": "Ардения" },
+    { "id": "2", "isArchived": false, "name": "Велория" }
   ],
   "genres": [
     { "id": "1", "isArchived": false, "name": "Криминал", "parentIds": [] },
-    { "id": "2", "isArchived": false, "name": "Гангстерский фильм", "parentIds": ["1"] },
+    { "id": "2", "isArchived": false, "name": "Гангстер", "parentIds": ["1"] },
     { "id": "3", "isArchived": false, "name": "Драма", "parentIds": [] },
     { "id": "4", "isArchived": false, "name": "Комедия", "parentIds": [] }
   ],
@@ -98,39 +166,39 @@ export default {
         { "genreIds": ["2", "3"], "id": "movie-1-actor-1", "userId": "1" },
         { "genreIds": ["3"], "id": "movie-1-actor-2", "userId": "2" }
       ],
-      "coverSrc": "https://image.tmdb.org/t/p/w500/3bhkrj58Vtu7enYsRolD1fZdja1.jpg",
-      "description": "История семьи Корлеоне и передачи власти от одного поколения другому.",
+      "coverSrc": "https://example.com/covers/shadows-of-ardenia.jpg",
+      "description": "Наследница портового города раскрывает заговор двух соперничающих семей.",
       "id": "1",
       "isArchived": false,
       "publisherIds": ["2"],
-      "title": "Крёстный отец"
+      "title": "Тени Ардении"
     },
     {
       "actors": [],
-      "coverSrc": "https://image.tmdb.org/t/p/w500/eWdyYQreja6JGCzqHWXpWHDrrPo.jpg",
-      "description": "Приключения консьержа и его юного помощника в знаменитом европейском отеле.",
+      "coverSrc": "https://example.com/covers/northern-star.jpg",
+      "description": "Ночной администратор старого отеля случайно становится участником поисков пропавшей картины.",
       "id": "2",
       "isArchived": false,
       "publisherIds": ["1"],
-      "title": "Отель «Гранд Будапешт»"
+      "title": "Полночь в «Северной звезде»"
     }
   ],
   "publishers": [
-    { "id": "1", "isArchived": false, "name": "A24" },
-    { "id": "2", "isArchived": false, "name": "Paramount Pictures" }
+    { "id": "1", "isArchived": false, "name": "Northlight Studio" },
+    { "id": "2", "isArchived": false, "name": "Aurora Pictures" }
   ],
   "users": [
     {
-      "bornAt": "1989-01-25",
+      "bornAt": "1988-03-14",
       "countryId": "1",
-      "fullName": "Александр Петров",
+      "fullName": "Мира Волкова",
       "id": "1",
       "isArchived": false
     },
     {
-      "bornAt": "1984-09-05",
-      "countryId": "1",
-      "fullName": "Юлия Пересильд",
+      "bornAt": "1991-11-02",
+      "countryId": "2",
+      "fullName": "Леон Ветров",
       "id": "2",
       "isArchived": false
     }
@@ -149,14 +217,14 @@ PATCH  /movies/:id
 DELETE /movies/:id
 ```
 
-`POST` генерирует строковый ID. `PUT` полностью заменяет выбранную запись, а `PATCH` изменяет только переданные поля; обе операции сохраняют существующий ID и его тип. Поле `id` в теле любого запроса не может переопределить ID, которым управляет сервер. Все операции записи — `POST`, `PUT`, `PATCH` и `DELETE` — выполняются последовательно и сохраняются в JSON-файле.
+`POST` генерирует строковый ID. `PUT` полностью заменяет выбранную запись, а `PATCH` изменяет только переданные поля; обе операции сохраняют существующий ID и его тип. Поле `id` в теле любого запроса не может переопределить ID, которым управляет сервер. Все операции записи — `POST`, `PUT`, `PATCH` и `DELETE` — выполняются последовательно; дисковое хранилище записывает их в JSON, а хранилище в памяти сохраняет до завершения процесса.
 
 Файл базы должен существовать до запуска. Имена ресурсов могут содержать латинские буквы, цифры, `_` и `-` и должны начинаться с буквы. Каждый ресурс является массивом JSON-объектов. У каждой записи должен быть непустой строковый или конечный числовой `id`; ID должны быть уникальны внутри ресурса при сравнении как строки, поэтому `1` и `"1"` не могут существовать одновременно. Перед каждым GET-запросом и изменением сервер заново читает файл, поэтому корректные внешние правки становятся видны без перезапуска.
 
 Успешная операция записи возвращает созданную, заменённую, обновлённую или удалённую запись. Ошибки используют подходящий HTTP-статус и следующий JSON-формат:
 
 ```json
-{ "error": "Понятное описание ошибки" }
+{ "error": "..." }
 ```
 
 ## Пагинация и сортировка
@@ -165,21 +233,18 @@ DELETE /movies/:id
 GET /movies?_page=1&_perPage=10&_sort=-id,title
 ```
 
-GET-запрос к коллекции всегда возвращает объект страницы. По умолчанию `_page` равен `1`, а `_perPage` — `10`:
+GET-запрос к коллекции всегда возвращает объект с массивом текущей страницы и общим количеством записей после фильтрации. По умолчанию `_page` равен `1`, а `_perPage` — `10`:
 
 ```json
 {
   "data": [],
-  "first": 1,
-  "items": 0,
-  "last": 1,
-  "next": null,
-  "pages": 1,
-  "prev": null
+  "total": 0
 }
 ```
 
-Оба параметра пагинации должны быть положительными целыми числами. По умолчанию `_perPage` не может превышать `1000`; лимит можно изменить программным параметром `maxPageSize`. При некорректном значении сервер возвращает `400`, а не исправляет его автоматически. Страница после последней возвращает пустой массив `data`, а `prev` указывает на последнюю доступную страницу.
+`data` содержит записи только запрошенной страницы. `total` содержит количество всех записей, соответствующих фильтру, до применения пагинации. Номер последней страницы при необходимости вычисляется на клиенте как `Math.max(1, Math.ceil(total / pageSize))`.
+
+Оба параметра пагинации должны быть положительными целыми числами. По умолчанию `_perPage` не может превышать `1000`; лимит меняется через `server.maxPageSize` в конфиге, переданном CLI или `createServer()`. При некорректном значении сервер возвращает `400`, а не исправляет его автоматически. Страница после последней возвращает пустой массив `data`, но сохраняет фактическое значение `total`.
 
 `_sort` принимает пути полей через запятую. Правила применяются слева направо; префикс `-` включает сортировку по убыванию. Через точку можно обратиться к полю вложенного объекта, включая поля, добавленные через `_embed`, например `GET /users?_embed=country&_sort=country.name,-id`. Неизвестные и небезопасные поля сортировки возвращают `400`.
 
@@ -188,7 +253,7 @@ GET-запрос к коллекции всегда возвращает объ
 Передайте JSON-объект через `_where`:
 
 ```http
-GET /movies?_where={"title":{"contains":"отец"}}
+GET /movies?_where={"title":{"contains":"тени"}}
 ```
 
 Можно фильтровать вложенные объекты и массивы на любой глубине. Условия внутри одного объекта по умолчанию объединяются через `AND`:
@@ -196,7 +261,7 @@ GET /movies?_where={"title":{"contains":"отец"}}
 ```json
 {
   "actors": { "some": { "userId": { "eq": "1" } } },
-  "title": { "contains": "отец" }
+  "title": { "contains": "тени" }
 }
 ```
 
@@ -207,7 +272,7 @@ GET /movies?_where={"title":{"contains":"отец"}}
   "and": [
     {
       "or": [
-        { "title": { "contains": "отец" } },
+        { "title": { "contains": "тени" } },
         { "actors": { "some": { "userId": { "eq": "2" } } } }
       ]
     },
@@ -231,12 +296,14 @@ GET /movies?_where={"title":{"contains":"отец"}}
 Также можно использовать простые query-параметры:
 
 ```http
-GET /movies?title:contains=отец
+GET /movies?title:contains=тени
 ```
 
 В простых фильтрах распознаются JSON-примитивы: числа, `true`, `false` и `null`. Значения с ведущими нулями, например `001`, остаются строками. Неизвестные операторы, некорректные логические условия и отсутствующие в непустом ресурсе пути фильтра возвращают `400`.
 
-Для простого фильтра `in` перечислите значения через запятую: `GET /movies?id:in=1,2`. Если передан `_where`, он становится полным фильтром, а остальные простые параметры фильтрации игнорируются. В примерах JSON оставлен читаемым; при ручном формировании URL HTTP-клиент должен закодировать значение `_where`.
+Несколько простых query-фильтров объединяются через `AND`. Для оператора `in` перечислите значения через запятую: `GET /movies?id:in=1,2`. Для поля-массива `in` означает, что хотя бы один элемент поля совпадает хотя бы с одним переданным значением. `every` для пустого массива возвращает `true`, а `some` — `false`.
+
+Если передан `_where`, он становится полным фильтром, а остальные простые параметры фильтрации игнорируются. В примерах JSON оставлен читаемым; при ручном формировании URL HTTP-клиент должен закодировать значение `_where`, например через `encodeURIComponent(JSON.stringify(where))`.
 
 Фильтрация выполняется после `_embed`. Поэтому фильтр может обращаться к полям добавленной связи, если в том же запросе указан соответствующий `_embed`; сохранённые поля `...Id` и `...Ids` всегда можно фильтровать напрямую.
 
@@ -248,7 +315,7 @@ GET /movies?title:contains=отец
 GET /movies/1?_embed=actors.user.country&_embed=actors.genres&_embed=publishers
 ```
 
-Ответ будет содержать актёров, пользователя и жанры каждого актёра, страну пользователя и издателей. Исходные поля с ID остаются в ответе, а файл базы не изменяется. Глубина вложения не ограничена:
+Ответ будет содержать актёров, пользователя и жанры каждого актёра, страну пользователя и издателей. Исходные поля с ID остаются в ответе, а файл базы не изменяется. Сервер не устанавливает фиксированный лимит глубины, но каждый требуемый уровень должен быть явно указан в конечном пути `_embed`:
 
 ```http
 GET /movies/1?_embed=actors.user.country
@@ -285,35 +352,37 @@ GET /countries/1?_embed=users
 deep-json-server --files server.config.js
 ```
 
+Для временных тестов вместо этого используйте `files.data`. Каждая начальная запись содержит `id`, `name`, `mimeType` и бинарное `content` в виде `Uint8Array`; `size` и `url` вычисляются автоматически. Загруженные файлы в таком режиме остаются в памяти до завершения процесса.
+
 Один файл отправляется непосредственно в теле запроса. Оба заголовка обязательны: `Content-Name` содержит относительное логическое имя, закодированное через `encodeURIComponent`, а `Content-Type` — MIME-тип файла:
 
 ```http
 POST /_files
-Content-Name: posters%2Fthe-godfather.jpg
+Content-Name: posters%2Fshadows-of-ardenia.jpg
 Content-Type: image/jpeg
 
 <binary body>
 ```
 
-Ответ содержит метаданные и постоянный URL:
+Успешная загрузка возвращает статус `201`, метаданные и постоянный URL:
 
 ```json
 {
   "id": "generated-id",
   "mimeType": "image/jpeg",
-  "name": "posters/the-godfather.jpg",
+  "name": "posters/shadows-of-ardenia.jpg",
   "size": 182340,
   "url": "/_files/generated-id"
 }
 ```
 
-`GET /_files/:id` возвращает исходные байты, а `DELETE /_files/:id` удаляет бинарное содержимое вместе с метаданными. Возвращаемый `url` задаётся относительно адреса mock-сервера. Сервер автоматически создаёт настроенные директории, хранит бинарное содержимое под сгенерированными ID без привязки к исходному имени и записывает логические имена и остальные метаданные в `files.metadata`. Изначально файл метаданных может отсутствовать: он создаётся при первой загрузке. Не редактируйте его во время работы сервера.
+`GET /_files/:id` возвращает исходные байты со статусом `200`, а `DELETE /_files/:id` удаляет бинарное содержимое вместе с метаданными и возвращает удалённые метаданные со статусом `200`. Возвращаемый `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`.
+Используется бинарное тело запроса, а не `multipart/form-data`, поэтому `XMLHttpRequest.upload.onprogress` может показывать прогресс при непосредственной отправке `File` через `xhr.send(file)`. Максимальный размер по умолчанию равен 100 МиБ и настраивается через `server.maxFileSize`. Отсутствующий или небезопасный `Content-Name` возвращает `400`, превышение лимита — `413`, а отсутствующий, некорректный или не поддерживаемый Fastify `Content-Type` — `400` либо `415` в зависимости от этапа проверки.
 
 ## Схема базы данных и генерация OpenAPI
 
-Необязательный JSON-файл, указанный в `database.schema`, например `mock/database-schema.json`, настраивает автоматически выведенные схемы. Он читается как при обычном запуске сервера, так и при генерации OpenAPI:
+Необязательный путь или объект в `database.schema` настраивает автоматически выведенные схемы. Это собственный формат настроек Deep JSON Server, а не стандартный документ JSON Schema: `$schema` здесь является объектом с настройками ресурсов. Например, файл `mock/database-schema.json` может содержать:
 
 ```json
 {
@@ -349,12 +418,16 @@ Content-Type: image/jpeg
 | `$schema.<resource>.formats` | Форматы OpenAPI для автоматически найденных или явно описанных строковых полей, например `date`, `date-time` или `uri` |
 | `$schema.<resource>.properties` | Рекурсивные OpenAPI-совместимые схемы полей, объединяемые с автоматически найденными |
 
+`formats` — сокращённая запись для назначения `format` уже существующему строковому полю. `properties` позволяет полностью описать поле, в том числе его `type`, `format`, ограничения и вложенные свойства, либо добавить поле, которого нет в данных. Если одно поле получает `format` через оба механизма, значение из `formats` применяется последним.
+
 Укажите `openapi.path` в конфиге сервера, затем сгенерируйте OpenAPI 3.0.3 и завершите работу:
 
 ```bash
-deep-json-server --openapi --files server.config.js
+deep-json-server --openapi-only server.config.js
 ```
 
+Чтобы включить в документ файловые маршруты, настройте секцию `files` и добавьте флаг `--files`: `deep-json-server --files --openapi-only server.config.js`.
+
 Генератор определяет ресурсы и типы полей по всем записям базы. По умолчанию все найденные поля необязательные, а поле `id` верхнего уровня всегда обязательное в схемах ответа и исключается из схем создания и обновления. Остальные обязательные поля перечисляются в `required`. Вложенный обязательный путь делает обязательным само вложенное свойство, но не все его родительские пути; при необходимости родителя нужно перечислить отдельно.
 
 Разные типы значений определяются независимо и объединяются через `oneOf`. Перед генерацией проверяются `$info`, имена ресурсов и схем, а также структура `properties`; пути из `required` и `formats` должны существовать в итоговой схеме.
@@ -377,7 +450,7 @@ deep-json-server --openapi --files server.config.js
 
 Пустой ресурс всё равно получает обязательное строковое поле `id`, поскольку сервер создаёт строковые ID. При совпадении имён схем или `operationId` генерация завершается понятной ошибкой; коллизию имён схем можно устранить с помощью явного `name`. Директория результата создаётся автоматически, а настроенный YAML-файл заменяется при каждой генерации.
 
-`$info` становится объектом `info` в OpenAPI, а настройки ресурсов находятся внутри `$schema`. Поле `servers` в OpenAPI формируется автоматически из `server.host` и `server.port`, резервных переменных окружения `HOST` и `PORT` или адреса по умолчанию `http://127.0.0.1:4001`.
+`$info` становится объектом `info` в OpenAPI, а настройки ресурсов находятся внутри `$schema`. В CLI поле `servers` формируется из `server.host` и `server.port`, затем из резервных переменных окружения `HOST` и `PORT`, а при их отсутствии используется `http://127.0.0.1:4001`. При прямом вызове `createServer()` переменные окружения автоматически не читаются: `server.openapi()` использует значения конфига или тот же адрес по умолчанию.
 
 Используйте `name`, если ресурсу нужно явно задать имя схемы вместо автоматически полученного имени в единственном числе:
 
@@ -391,73 +464,87 @@ deep-json-server --openapi --files server.config.js
 }
 ```
 
-В сгенерированном документе описаны CRUD, пагинация, сортировка, глубокие фильтры, `_embed`, а также прямые и обратные связи в ответах, определённые по полям `...Id` и `...Ids`. При наличии `--files` в него также добавляются маршруты бинарной загрузки, получения и удаления файлов. Числовой ID базы описывается как `integer | string`, поскольку последующий `POST` создаст строковый ID в том же ресурсе. Файл можно передать, например, в RTK Query OpenAPI Codegen. OpenAPI создаётся только с параметром `--openapi`; обычный запуск сервера файл не перезаписывает.
+В сгенерированном документе описаны CRUD, пагинация, сортировка, глубокие фильтры, `_embed`, а также прямые и обратные связи в ответах, определённые по полям `...Id` и `...Ids`. При наличии `--files` в него также добавляются маршруты бинарной загрузки, получения и удаления файлов. Числовой ID базы описывается как `integer | string`, поскольку последующий `POST` создаст строковый ID в том же ресурсе. Файл можно передать, например, в RTK Query OpenAPI Codegen. OpenAPI создаётся только с параметром `--openapi` или `--openapi-only`; обычный запуск сервера файл не перезаписывает.
 
 При обычном запуске тела запросов проверяются по тем же автоматически выведенным и настроенным схемам. Для `POST` и `PUT` проверяются обязательные поля из `required`; `PATCH` проверяет только фактически переданные поля. Настройки `formats` и `properties` применяются ко всем трём методам. Не перечисленные дополнительные поля объекта остаются разрешёнными. Некорректные тела возвращают `400`.
 
-## Назначение и безопасность
-
-Deep JSON Server предназначен для локальной разработки и автоматических тестов. В нём нет аутентификации и авторизации, CORS разрешён для любого источника, принятые изменения напрямую сохраняются в настроенные файлы, а ссылочная целостность не проверяется. Оставляйте адрес loopback по умолчанию, если внешняя среда не предоставляет собственный контроль доступа; не открывайте сервер и файловые маршруты для недоверенной сети.
-
 ## Программный API
 
 ```js
-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',
-});
+import { createServer } from '@kollors/deep-json-server';
 
-const response = await server.inject({ method: 'GET', url: '/movies' });
+const config = {
+  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',
+    logger: false,
+    maxFileSize: 100 * 1024 * 1024,
+    maxPageSize: 1000,
+    port: 4001,
+  },
+};
 
-await server.close();
+// Запрос без открытия сетевого порта — удобно для автоматических тестов.
+const server = await createServer(config);
+const fastify = server.fastify();
+const response = await fastify.inject({ method: 'GET', url: '/movies' });
 
-// Создание экземпляра и начало прослушивания.
-const listeningServer = await startServer({
-  databasePath: 'mock/database.json',
-  host: '127.0.0.1',
-  port: 4001,
-  schemaPath: 'mock/database-schema.json',
-});
+console.log(response.json());
+
+// Возвращает документ и записывает его в config.openapi.path.
+const document = await server.openapi();
 
-await listeningServer.close();
+await fastify.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',
+// Запуск сетевого сервера. Вызов без аргументов использует server.host и server.port.
+const runningServer = await createServer(config);
+const runningFastify = runningServer.fastify();
+
+await runningFastify.listen();
+
+// Позже, при завершении приложения:
+await runningFastify.close();
+
+// База, схема и файлы полностью в памяти.
+const memoryServer = await createServer({
+  database: {
+    data: { movies: [{ id: '1', title: 'Тени Ардении' }] },
+    schema: { $info: { title: 'API фильмов', version: '1.0.0' } },
+  },
+  files: {
+    data: [{ content: new Uint8Array([1, 2, 3]), id: 'file-1', mimeType: 'application/octet-stream', name: 'example.bin' }],
+  },
 });
 
-// Создание такого же OpenAPI-документа полностью в памяти.
-const document = createOpenApiDocument(
-  { movies: [{ id: '1', title: 'Крёстный отец' }] },
-  { $info: { title: 'API фильмов', version: '1.0.0' } },
-  { files: true, host: '127.0.0.1', port: 4001 },
-);
+const memoryFastify = memoryServer.fastify();
+const memoryResponse = await memoryFastify.inject({ method: 'GET', url: '/movies/1' });
+
+console.log(memoryResponse.json());
+
+await memoryFastify.close();
 ```
 
-Параметры программного API:
+`createServer()` принимает точно ту же структуру конфига, что и `server.config.js`. Функция загружает и клонирует настроенные источники, а затем возвращает фасад с двумя операциями:
 
-| Параметр | Где используется | Назначение |
+| Член | Назначение |
 | --- | --- | --- |
-| `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-декларации для всех экспортируемых функций.
+| `server.fastify()` | Лениво создаёт и кэширует настоящий экземпляр Fastify; все нативные методы доступны, а `listen()` без аргументов использует `server.host` и `server.port` |
+| `server.openapi()` | Возвращает документ OpenAPI и дополнительно записывает его, если настроен `openapi.path` |
+
+При программном использовании файловые маршруты включаются при наличии секции `files`. Сигнатура второго аргумента — `{ files?: boolean }`: передайте `{ files: false }`, чтобы оставить настроенное хранилище выключенным, или `{ files: true }`, чтобы потребовать секцию `files` и включить маршруты. `server.openapi()` использует то же состояние возможности, что и `server.fastify()`.
+
+Вызов `server.fastify().listen()` без аргументов использует `server.host` и `server.port`, а при их отсутствии — `127.0.0.1:4001`. Явные параметры `listen(options)` имеют приоритет. Относительные пути, переданные напрямую в `createServer()`, вычисляются от текущей рабочей директории; пути из `server.config.js` — от директории конфига. Пакет содержит сгенерированные TypeScript-декларации фасада и всех вариантов конфигурации.
+
+## Назначение и безопасность
+
+Deep JSON Server предназначен для локальной разработки и автоматических тестов. В нём нет аутентификации и авторизации, CORS разрешён для любого источника, при дисковом хранилище принятые изменения сохраняются в настроенные файлы, а ссылочная целостность не проверяется. Оставляйте адрес loopback по умолчанию, если внешняя среда не предоставляет собственный контроль доступа; не открывайте сервер и файловые маршруты для недоверенной сети.

package/index.js

@@ -1,2 +1,7 @@
-export { createOpenApiDocument, generateOpenApi } from './src/openapi/index.js';
-export { createServer, startServer } from './src/server.js';
+/** @typedef {import('./src/config.js').DeepJsonServerConfig} DeepJsonServerConfig */
+/** @typedef {import('./src/config.js').DatabaseConfig} DatabaseConfig */
+/** @typedef {import('./src/config.js').FilesConfig} FilesConfig */
+/** @typedef {import('./src/config.js').MemoryFile} MemoryFile */
+/** @typedef {import('./src/server.js').OpenapiDocument} OpenapiDocument */
+
+export { createServer } from './src/server.js';

package/package.json

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