@kollors/deep-json-server 0.4.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,38 +14,149 @@
 npm install --save-dev @kollors/deep-json-server
 ```
 
-Добавьте команду в `package.json`:
+## Быстрый старт
+
+До запуска создайте файл базы `mock/database.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"
-  }
+  "movies": [
+    { "id": "1", "title": "Тени Ардении" }
+  ]
 }
 ```
 
+Рядом с `package.json` создайте ESM-модуль `server.config.js`:
+
+```js
+export default {
+  database: {
+    path: 'mock/database.json',
+  },
+};
+```
+
 Запустите сервер:
 
 ```bash
-npm run mock
+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`. В примере ниже включены настройки всех возможностей:
+
+```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',
+    logger: true,
+    maxFileSize: 100 * 1024 * 1024,
+    maxPageSize: 1000,
+    port: 4001,
+  },
+};
 ```
 
-По умолчанию сервер доступен по адресу `http://127.0.0.1:4001`. Адрес и порт можно задать через `--host` и `--port` либо переменные окружения `HOST` и `PORT`.
+Ключи конфигурации:
+
+| Ключ | Условие | Назначение |
+| --- | --- | --- |
+| `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`.
+
+В том же конфиге все данные можно разместить в памяти. `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 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"
+  }
+}
+```
+
+Режимы CLI:
+
+| Команда | Поведение |
+| --- | --- |
+| `deep-json-server server.config.js` | Запускает CRUD-сервер без файловых маршрутов |
+| `deep-json-server --files server.config.js` | Запускает CRUD-сервер с файловыми маршрутами |
+| `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 с файловыми маршрутами и завершает работу |
+
+Флаг `--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": [] }
   ],
@@ -55,39 +166,39 @@ npm run mock
         { "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
     }
@@ -106,9 +217,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": "..." }
+```
 
 ## Пагинация и сортировка
 
@@ -116,30 +233,27 @@ 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`.
 
-Префикс `-` перед полем включает сортировку по убыванию. Неизвестные и небезопасные поля сортировки возвращают `400`.
+`_sort` принимает пути полей через запятую. Правила применяются слева направо; префикс `-` включает сортировку по убыванию. Через точку можно обратиться к полю вложенного объекта, включая поля, добавленные через `_embed`, например `GET /users?_embed=country&_sort=country.name,-id`. Неизвестные и небезопасные поля сортировки возвращают `400`.
 
 ## Фильтры
 
 Передайте JSON-объект через `_where`:
 
 ```http
-GET /movies?_where={"title":{"contains":"отец"}}
+GET /movies?_where={"title":{"contains":"тени"}}
 ```
 
 Можно фильтровать вложенные объекты и массивы на любой глубине. Условия внутри одного объекта по умолчанию объединяются через `AND`:
@@ -147,40 +261,61 @@ GET /movies?_where={"title":{"contains":"отец"}}
 ```json
 {
   "actors": { "some": { "userId": { "eq": "1" } } },
-  "title": { "contains": "отец" }
+  "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-параметры:
 
 ```http
-GET /movies?title:contains=отец
+GET /movies?title:contains=тени
 ```
 
 В простых фильтрах распознаются JSON-примитивы: числа, `true`, `false` и `null`. Значения с ведущими нулями, например `001`, остаются строками. Неизвестные операторы, некорректные логические условия и отсутствующие в непустом ресурсе пути фильтра возвращают `400`.
 
+Несколько простых 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` всегда можно фильтровать напрямую.
+
 ## Связи
 
-Используйте `_embed`, чтобы заменить ID связанными записями:
+Используйте `_embed`, чтобы добавить связанные записи в ответ:
 
 ```http
 GET /movies/1?_embed=actors.user.country&_embed=actors.genres&_embed=publishers
 ```
 
-Ответ будет содержать актёров, пользователя и жанры каждого актёра, страну пользователя и издателей. Глубина вложения не ограничена:
+Ответ будет содержать актёров, пользователя и жанры каждого актёра, страну пользователя и издателей. Исходные поля с ID остаются в ответе, а файл базы не изменяется. Сервер не устанавливает фиксированный лимит глубины, но каждый требуемый уровень должен быть явно указан в конечном пути `_embed`:
 
 ```http
 GET /movies/1?_embed=actors.user.country
@@ -189,27 +324,65 @@ 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` заменяет это свойство ответа актуальной связанной записью. Если цель одиночной связи не найдена, результатом будет `null`; отсутствующие цели связи с коллекцией не попадут в итоговый массив. Для поиска связей лениво создаются ID-индексы только используемых в текущем запросе ресурсов.
+
+## Файлы
+
+Добавьте `files.directory` и `files.metadata` в конфиг сервера, затем передайте `--files`, чтобы включить загрузку бинарных файлов:
+
+```bash
+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%2Fshadows-of-ardenia.jpg
+Content-Type: image/jpeg
+
+<binary body>
+```
+
+Успешная загрузка возвращает статус `201`, метаданные и постоянный URL:
+
+```json
+{
+  "id": "generated-id",
+  "mimeType": "image/jpeg",
+  "name": "posters/shadows-of-ardenia.jpg",
+  "size": 182340,
+  "url": "/_files/generated-id"
+}
+```
 
-Это мягкие ссылки: сервер загружает их по запросу, но не проверяет ссылочную целостность при записи данных.
+`GET /_files/:id` возвращает исходные байты со статусом `200`, а `DELETE /_files/:id` удаляет бинарное содержимое вместе с метаданными и возвращает удалённые метаданные со статусом `200`. Возвращаемый `url` задаётся относительно адреса mock-сервера. Сервер автоматически создаёт настроенные директории, хранит бинарное содержимое под сгенерированными ID без привязки к исходному имени и записывает логические имена и остальные метаданные в `files.metadata`. Изначально файл метаданных может отсутствовать: он создаётся при первой загрузке. Не редактируйте его во время работы сервера.
 
-Явное поле `...Id` или `...Ids` считается источником истины. Если в записи также сохранено устаревшее вложенное значение, `_embed` заменяет его актуальной связанной записью. Для поиска связей лениво создаются ID-индексы только используемых в текущем запросе ресурсов.
+Используется бинарное тело запроса, а не `multipart/form-data`, поэтому `XMLHttpRequest.upload.onprogress` может показывать прогресс при непосредственной отправке `File` через `xhr.send(file)`. Максимальный размер по умолчанию равен 100 МиБ и настраивается через `server.maxFileSize`. Отсутствующий или небезопасный `Content-Name` возвращает `400`, превышение лимита — `413`, а отсутствующий, некорректный или не поддерживаемый Fastify `Content-Type` — `400` либо `415` в зависимости от этапа проверки.
 
-## Генерация OpenAPI
+## Схема базы данных и генерация OpenAPI
 
-Создайте рядом с базой небольшой файл конфигурации, например `mock/database-schema.json`:
+Необязательный путь или объект в `database.schema` настраивает автоматически выведенные схемы. Это собственный формат настроек Deep JSON Server, а не стандартный документ JSON Schema: `$schema` здесь является объектом с настройками ресурсов. Например, файл `mock/database-schema.json` может содержать:
 
 ```json
 {
@@ -235,13 +408,27 @@ 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-совместимые схемы полей, объединяемые с автоматически найденными |
+
+`formats` — сокращённая запись для назначения `format` уже существующему строковому полю. `properties` позволяет полностью описать поле, в том числе его `type`, `format`, ограничения и вложенные свойства, либо добавить поле, которого нет в данных. Если одно поле получает `format` через оба механизма, значение из `formats` применяется последним.
+
+Укажите `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-only server.config.js
 ```
 
-Генератор определяет ресурсы и типы полей по всем записям базы. По умолчанию все найденные поля необязательные, а поле `id` верхнего уровня, присутствующее в итоговой схеме ресурса, всегда обязательное. Остальные обязательные поля перечисляются в `required`; для вложенных полей используются пути через точку, например `actors.userId`. Объект `formats` добавляет форматы OpenAPI, например `date` и `uri`.
+Чтобы включить в документ файловые маршруты, настройте секцию `files` и добавьте флаг `--files`: `deep-json-server --files --openapi-only server.config.js`.
+
+Генератор определяет ресурсы и типы полей по всем записям базы. По умолчанию все найденные поля необязательные, а поле `id` верхнего уровня всегда обязательное в схемах ответа и исключается из схем создания и обновления. Остальные обязательные поля перечисляются в `required`. Вложенный обязательный путь делает обязательным само вложенное свойство, но не все его родительские пути; при необходимости родителя нужно перечислить отдельно.
 
 Разные типы значений определяются независимо и объединяются через `oneOf`. Перед генерацией проверяются `$info`, имена ресурсов и схем, а также структура `properties`; пути из `required` и `formats` должны существовать в итоговой схеме.
 
@@ -261,9 +448,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`. В CLI поле `servers` формируется из `server.host` и `server.port`, затем из резервных переменных окружения `HOST` и `PORT`, а при их отсутствии используется `http://127.0.0.1:4001`. При прямом вызове `createServer()` переменные окружения автоматически не читаются: `server.openapi()` использует значения конфига или тот же адрес по умолчанию.
 
 Используйте `name`, если ресурсу нужно явно задать имя схемы вместо автоматически полученного имени в единственном числе:
 
@@ -277,24 +464,87 @@ 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` или `--openapi-only`; обычный запуск сервера файл не перезаписывает.
 
-При обычном запуске тела запросов проверяются по автоматически выведенным схемам ресурсов. Передайте `--schema mock/database-schema.json`, чтобы в runtime применялись те же явные ограничения `required`, `formats` и `properties`. Некорректные тела `POST`, `PUT` и `PATCH` возвращают `400`.
+При обычном запуске тела запросов проверяются по тем же автоматически выведенным и настроенным схемам. Для `POST` и `PUT` проверяются обязательные поля из `required`; `PATCH` проверяет только фактически переданные поля. Настройки `formats` и `properties` применяются ко всем трём методам. Не перечисленные дополнительные поля объекта остаются разрешёнными. Некорректные тела возвращают `400`.
 
 ## Программный API
 
 ```js
-import { createServer, generateOpenApi, startServer } from '@kollors/deep-json-server';
+import { createServer } from '@kollors/deep-json-server';
+
+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,
+  },
+};
+
+// Запрос без открытия сетевого порта — удобно для автоматических тестов.
+const server = await createServer(config);
+const fastify = server.fastify();
+const response = await fastify.inject({ method: 'GET', url: '/movies' });
 
-const server = await createServer({ databasePath: 'mock/database.json', logger: false, maxPageSize: 1000, schemaPath: 'mock/database-schema.json' });
+console.log(response.json());
 
-const response = await server.inject({ method: 'GET', url: '/movies' });
+// Возвращает документ и записывает его в config.openapi.path.
+const document = await server.openapi();
 
-await server.close();
+await fastify.close();
 
-await startServer({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001, schemaPath: 'mock/database-schema.json' });
+// Запуск сетевого сервера. Вызов без аргументов использует server.host и server.port.
+const runningServer = await createServer(config);
+const runningFastify = runningServer.fastify();
 
-await generateOpenApi({ databasePath: 'mock/database.json', host: '127.0.0.1', port: 4001, schemaPath: 'mock/database-schema.json', outputPath: 'mock/openapi-schema.yaml' });
+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' }],
+  },
+});
+
+const memoryFastify = memoryServer.fastify();
+const memoryResponse = await memoryFastify.inject({ method: 'GET', url: '/movies/1' });
+
+console.log(memoryResponse.json());
+
+await memoryFastify.close();
 ```
 
-`createServer()` удобен для тестов: он возвращает экземпляр Fastify, не открывая сетевой порт. Пакет содержит сгенерированные TypeScript-декларации для всех экспортируемых функций.
+`createServer()` принимает точно ту же структуру конфига, что и `server.config.js`. Функция загружает и клонирует настроенные источники, а затем возвращает фасад с двумя операциями:
+
+| Член | Назначение |
+| --- | --- | --- |
+| `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.4.0",
+  "version": "0.6.0",
   "description": "JSON mock server with deep filters and recursive relationship embedding",
   "type": "module",
   "types": "./types/index.d.ts",