@kollors/deep-json-server 0.9.0 → 1.0.0-alpha.2

package/README.ru.md

@@ -1,172 +1,336 @@
 # Deep JSON Server
 
-[Русский](README.ru.md) | [English](README.md)
+[English](README.md)
 
-[GitHub](https://github.com/kollors/deep-json-server) | [npm](https://www.npmjs.com/package/@kollors/deep-json-server)
+JSON-сервер для имитации API: REST, GraphQL, вложенные запросы, бинарные файлы и экспорт схем. Требуется Node.js 22 или новее.
 
-Небольшой сервер для имитации REST API с CRUD, пагинацией, фильтрацией вложенных данных, подстановкой связанных записей через `_embed`, бинарными файлами и генерацией OpenAPI. Данные могут храниться в JSON-файлах или памяти, а связи определяются по именам полей: `countryId`, `genreIds`, `publisherIds` и так далее.
+**1.0.0-alpha.2 — предварительная версия.** При переходе с 0.x обновите схему моделей и параметры запросов по примерам ниже.
 
 ## Установка
 
-Требуется Node.js 22 или новее.
-
-```bash
-npm install --save-dev @kollors/deep-json-server
+```sh
+npm install @kollors/deep-json-server@alpha
 ```
 
+Для установки конкретной версии укажите `@1.0.0-alpha.2`.
+
 ## Быстрый старт
 
-До запуска создайте файл базы `mock/database.json`:
+Создайте два файла в одном каталоге.
+
+`database.json`:
 
 ```json
 {
-  "movies": [
-    { "id": "1", "title": "Тени Ардении" }
+  "users": [
+    { "id": "1", "fullName": "Мира Волкова" }
   ]
 }
 ```
 
-Рядом с `package.json` создайте ESM-модуль `server.config.js`:
+`server.config.js`:
 
 ```js
 export default {
-  database: {
-    path: 'mock/database.json',
-  },
+  database: { path: './database.json' },
 };
 ```
 
-Запустите сервер:
-
-```bash
+```sh
 npx deep-json-server server.config.js
 ```
 
-По умолчанию API доступен по адресу `http://127.0.0.1:4001`. Например, `GET http://127.0.0.1:4001/movies` вернёт страницу:
+Список пользователей доступен по адресу `http://127.0.0.1:4001/users`.
+
+## Конфигурация
+
+| Ключ | Назначение |
+|---|---|
+| `database.path` / `database.data` | Ровно один: JSON-файл или объект коллекций в памяти |
+| `database.schema` | Объект моделей или путь к JSON-файлу; необязателен для REST |
+| `openapi.enabled` | Включить HTTP-маршрут спецификации; по умолчанию `false` |
+| `openapi.endpoint` | Путь спецификации; по умолчанию `/openapi.json` |
+| `openapi.path` | Путь экспорта YAML |
+| `openapi.info` | Необязательные метаданные: `title`, `version`, `description` |
+| `graphql.enabled` | Включить GraphQL HTTP API; по умолчанию `false` |
+| `graphql.endpoint` | Путь GraphQL; по умолчанию `/graphql` |
+| `graphql.path` | Путь экспорта GraphQL SDL |
+| `server.host`, `server.port` | По умолчанию `127.0.0.1`, `4001`; CLI также читает `HOST`/`PORT` |
+| `server.pageSize`, `server.maxPageSize` | По умолчанию 10 и 100; размер по умолчанию ограничен максимумом |
+| `server.cors`, `server.logger` | По умолчанию `true`; logger также принимает настройки Fastify |
+| `server.maxFileSize` | По умолчанию 100 МиБ |
+| `files.data` | Бинарные файлы в памяти |
+| `files.directory`, `files.metadata` | Каталог файлов и JSON метаданных; необходимы оба |
+
+Относительные пути отсчитываются от каталога конфигурационного файла. При вызове `createServer()` с объектом конфигурации — от рабочего каталога. Сервер работает с копией переданных данных в памяти.
+
+| Флаг CLI | Действие |
+|---|---|
+| `--files` | Включить файловые маршруты |
+| `--graphql` | Включить GraphQL API |
+| `--openapi` | Включить HTTP-маршрут OpenAPI |
+| `--host <host>` | Адрес сервера |
+| `--port <port>` | Порт сервера |
+| `--help`, `-h` | Справка |
+| `--version`, `-v` | Версия пакета |
+
+Приоритет настроек: CLI → конфигурация → `HOST`/`PORT` → значения по умолчанию. Файловые маршруты включаются при наличии секции `files`.
+
+Для генерации укажите формат и файл конфигурации:
+
+```sh
+npx deep-json-server generate openapi server.config.js
+npx deep-json-server generate graphql server.config.js
+npx deep-json-server generate openapi,graphql server.config.js
+```
+
+Команда читает `database.schema` и сохраняет схемы по путям `openapi.path` и `graphql.path`. Данные базы и файловое хранилище для генерации не требуются.
+
+## Схема моделей
+
+Примеры: [база данных](examples/database.json), [схема моделей](examples/schema.json), [конфигурация](examples/server.config.js).
 
 ```json
 {
-  "data": [{ "id": "1", "title": "Тени Ардении" }],
-  "total": 1
+  "Country": {
+    "collection": "countries",
+    "api": ["openapi", "graphql"],
+    "fields": {
+      "id": { "type": "string", "primary": true, "generated": "uuid" },
+      "name": { "type": "string", "required": true },
+      "users": { "type": "User[]", "target": "countryId" }
+    }
+  },
+  "User": {
+    "collection": "users",
+    "api": ["openapi", "graphql"],
+    "fields": {
+      "id": { "type": "string", "primary": true, "generated": "uuid" },
+      "fullName": { "type": "string", "required": true },
+      "country": { "type": "Country", "source": "countryId" }
+    }
+  }
 }
 ```
 
-## Конфигурация и запуск
+По умолчанию `api` содержит `["openapi", "graphql"]`. Пустой массив исключает модель из экспорта и GraphQL, но REST продолжает работать. Связанные модели должны разрешать тот же формат экспорта. Имена должны быть допустимыми идентификаторами; конфликты генерируемых типов и операций вызывают ошибку. Имена `and`, `or`, `not` зарезервированы фильтрами.
 
-Создайте ESM-модуль `server.config.js`. В примере ниже показаны настройки всех возможностей:
+| Возможность | Со схемой | Без схемы |
+|---|---|---|
+| REST CRUD | Валидация модели | Только проверки JSON, тела запроса и идентификаторов |
+| Связи | Поля схемы | По ключам `countryId`, `genreIds` и аналогичным |
+| Экспорт OpenAPI 3.0.3 | Доступен | Ошибка при запросе экспорта |
+| GraphQL SDL / API | Доступен | Ошибка при запросе |
 
-```js
-import process from 'node:process';
+При явной схеме неизвестные поля и коллекции запрещены. Исключение — хранимые ключи, выведенные из связей. Исходная база проверяется при загрузке. Генерация использует описание моделей. REST без схемы создаёт ключ `id` и сохраняет произвольные JSON-поля. Для фильтров и выбора отдельных полей используются имена в формате идентификаторов; остальные поля возвращаются через `scope=*`.
 
-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: {
-    cors: true,
-    host: '127.0.0.1',
-    logger: true,
-    maxFileSize: 100 * 1024 * 1024,
-    maxPageSize: 1000,
-    port: 4001,
-  },
-};
+### Поля
+
+Поле `type` принимает `string`, `number`, `boolean`, `object` или имя модели. Для массива добавьте суффикс `[]`: `string[]`, `object[]`, `Genre[]`. Вложенные поля описываются через точку, например `actors.fullName`.
+
+| Свойства | Назначение |
+|---|---|
+| `type` | Обязательный тип |
+| `description`, `example` | Документация и пример |
+| `required`, `nullable` | По умолчанию `false`; наличие поля и разрешение `null` независимы |
+| `default` | Значение при пропуске в create/replace; PATCH не вставляет значения по умолчанию |
+| `enum` | Допустимые значения; у массива — значения каждого элемента |
+| `primary` | Корневой первичный ключ: обязательный, уникальный, неизменяемый, без `null` |
+| `generated` | `uuid` для строк, `increment` для чисел; значение создаёт сервер |
+| `readOnly`, `writeOnly` | Только ответ или только входные данные; взаимно исключаются |
+| `minLength`, `maxLength`, `pattern` | Ограничения строк |
+| `format` | `date`, `date-time`, `email`, `uri`, `uuid` |
+| `minimum`, `maximum` | Включительные числовые границы |
+| `source`, `target`, `onDelete` | Описание связи |
+
+Ограничения строк и чисел применяются к каждому элементу `string[]`/`number[]`. `required` и `nullable` относятся ко всему массиву; `default` и `example` содержат массив целиком. Элементы массива должны соответствовать его типу и быть отличны от `null`. `required` требует наличия поля; обычный массив при этом может быть пустым.
+
+У модели ровно один первичный ключ типа `string` или `number`, объявленный на верхнем уровне. Имя произвольное: `id`, `username`, `code`. Если `generated` не задан, значение передаёт клиент при создании. Генерируемые поля объявляются на верхнем уровне, исключаются из входных типов и несовместимы с `default`. При замене записи сохраняются генерируемые значения и поля `readOnly`, включая вложенные объекты. Для защиты полей внутри массива задайте `readOnly` всему массиву или содержащему его объекту. Объекты, состоящие из серверных полей, доступны только в ответах.
+
+Например, `LocalUser` с первичным ключом `username` и полем `password: {"type":"string","required":true,"writeOnly":true}` получает запрос `localUser(username: ...)` и маршрут `/localUsers/{username}`. Поле `writeOnly` доступно для записи и исключено из ответов, `scope`, фильтров и сортировки.
+
+### Связи
+
+```json
+"actors.genres": {
+  "type": "Genre[]",
+  "source": "actors.genreIds",
+  "required": true
+}
+```
+
+`Genre` возвращает объект, `Genre[]` — список. По умолчанию `source` указывает на первичный ключ текущей модели, `target` — целевой. Это правило действует и для вложенных связей. Пути задаются от корня соответствующей записи: в примере `actors.genreIds` содержит ключи жанров текущего актёра.
+
+Ключи связей хранятся в базе и входят в собственные поля записи. Их типы выводятся из сопоставляемых ключей. Если поле `source` ссылается на первичный ключ целевой модели, его можно не объявлять отдельно: для множественной связи создаётся описание массива ключей, для одиночной — одного значения. При неоднозначном сопоставлении опишите хранимое поле явно.
+
+Обратная связь: `User.movies = {"type":"Movie[]","target":"actors.userId"}`. Фильм возвращается один раз, даже если совпало несколько актёров. Несколько совпадений для одиночной связи — ошибка.
+
+Каждый переданный ключ прямой связи должен указывать на существующую запись. `required: true` у связи требует хотя бы одну связанную запись до фильтрации и пагинации ответа. Обратная связь с первичным ключом в `source` может быть пустой, если не объявлена обязательной. Отсутствующая одиночная связь возвращает `null`.
+
+`onDelete` срабатывает **при удалении целевой записи**:
+
+- `restrict` — по умолчанию: запретить удаление, пока на цель ссылается сохраняемая запись.
+- `cascade` — удалить ссылающуюся запись. Для `User.country` удаление страны удаляет пользователей. Для `Movie.actors.user` удаление пользователя удаляет соответствующие элементы `actors`, сохраняя фильм.
+
+Каскадное удаление выполняется целиком, включая циклические связи. Ошибка проверки отменяет всю операцию. Правила `onDelete` действуют и на явно объявленные обратные связи; при описании обоих направлений учитывайте оба правила.
+
+## Запросы и ответы
+
+Коллекции и списки объектов, включая вложенные `object[]`, возвращают:
+
+```json
+{ "data": [], "total": 0 }
 ```
 
-Ключи конфигурации:
+Массивы примитивов возвращаются обычными массивами. Каждый список объектов принимает необязательные `where`, `order` и `pager`. Порядок обработки: фильтрация → сортировка → пагинация. `total` — число записей после фильтрации, до пагинации.
+
+В `pager` задаются `page` и `pageSize`. По умолчанию возвращается первая страница с размером из `server.pageSize`. Оба значения должны быть положительными целыми числами; `pageSize` ограничен `server.maxPageSize`. За пределами списка возвращается пустой `data` с общим числом найденных записей в `total`.
+
+Фильтры: `eq`, `ne`, `in`; для строк `contains`, `startsWith`, `endsWith`; сравнения `gt`, `gte`, `lt`, `lte`. Условия объединяются через `and`, `or`, `not`. У массивов есть `some`, `every`, `none`; у примитивных массивов также `contains`, `in`. Поиск строк не учитывает регистр. Условие поля задаётся объектом с оператором, например `{ "id": { "eq": "1" } }`.
+
+```json
+{
+  "movies": {
+    "some": {
+      "actors": {
+        "some": {
+          "genres": { "some": { "id": { "in": ["2", "3"] } } }
+        }
+      }
+    }
+  }
+}
+```
+
+Корневой `where` выбирает записи основной коллекции. `where` внутри связи фильтрует её элементы, сохраняя родительскую запись. Каждый вложенный список обрабатывается отдельно. Фильтрация по связи работает независимо от её включения в ответ.
+
+`order` — массив правил `{ "field": "fullName", "direction": "ASC" }`. Первое правило приоритетнее; при равных значениях сохраняется порядок хранения. `null` и отсутствующее значение сравниваются одинаково. REST использует путь `profile.name`, GraphQL — enum `profile_name`. Неоднозначные имена enum вызывают ошибку генерации. Сортировка доступна по скалярным полям текущего объекта, включая вложенные поля. Для связанных списков задаётся собственный `order`.
 
-| Ключ | Условие | Назначение |
-| --- | --- | --- |
-| `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.cors` | Необязателен | Включает разрешающие CORS-заголовки и маршруты `OPTIONS`; по умолчанию `true` |
-| `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` |
+### REST
 
-`server.port` должен быть целым числом от `0` до `65535`. Значение `0` позволяет Fastify выбрать свободный порт при запуске, но не подходит для генерации URL в OpenAPI, где допустимы порты от `1` до `65535`. `server.maxFileSize` и `server.maxPageSize` должны быть положительными целыми числами.
+| Метод | Путь | Операция |
+|---|---|---|
+| GET | `/users` | `userList` |
+| GET | `/users/{id}` | `user` |
+| POST | `/users` | `userCreate` |
+| PUT | `/users/{id}` | `userReplace` |
+| PATCH | `/users/{id}` | `userUpdate` |
+| DELETE | `/users/{id}` | `userDelete` |
 
-Все относительные пути вычисляются от директории с `server.config.js`, а не от текущей рабочей директории. Неизвестные ключи, пустые пути и значения некорректных типов отклоняются до запуска. Конфиг является исполняемым JavaScript: в нём можно читать переменные окружения, импортировать другие модули и вычислять значения перед экспортом объекта. Для `.js`-конфига с `export default` проект должен быть ESM (`"type": "module"`); в CommonJS-проекте сохраните тот же конфиг как `server.config.mjs`.
+Имя параметра пути соответствует первичному ключу. POST, PUT и PATCH принимают JSON-объект записи. PUT заменяет запись с сохранением ключа и серверных полей. PATCH объединяет поля на верхнем уровне; переданные вложенные объекты заменяются с сохранением их полей `readOnly`. Создание и замена требуют всех обязательных полей. При обновлении проверяются переданные значения и итоговая запись. Отсутствующая запись — `404`, конфликт — `409`. DELETE возвращает удалённую запись.
 
-В том же конфиге все данные можно разместить в памяти. `database.path` и `database.data` взаимоисключающие, а `database.schema` принимает путь или объект. Аналогично, `files.data` нельзя сочетать с `files.directory` или `files.metadata`:
+Параметры `where`, `order`, `pager`, `nested` содержат JSON; `scope` — строку выбора. Пример до URL-кодирования:
+
+```text
+GET /users?where={"fullName":{"contains":"Мира"}}&order=[{"field":"fullName","direction":"ASC"}]&pager={"page":1,"pageSize":20}
+```
+
+Кодирование через `URLSearchParams`:
 
 ```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]), directory: 'examples', mimeType: 'application/octet-stream', name: 'example.bin' }],
-  },
-};
+const params = new URLSearchParams({
+  scope: 'id,fullName,movies(id,title)',
+  nested: JSON.stringify({ movies: { order: [{ field: 'title', direction: 'ASC' }], pager: { page: 1, pageSize: 5 } } }),
+});
+const response = await fetch(`/users?${params}`);
 ```
 
-Значения в памяти клонируются при инициализации. Поэтому операции с CRUD и файлами не изменяют экспортированный объект конфига, а их результаты исчезают после завершения процесса.
+`scope=*,actors(user(id,fullName),genres(*))` выбирает собственные поля и указанные связи. `*` включает собственные поля текущего объекта и хранимые ключи, кроме полей `writeOnly`. Связи перечисляются явно. По умолчанию выбираются собственные поля. Списки сохраняют структуру ответа `{ data, total }`.
 
-Добавьте нужные команды в `package.json`. Здесь `mock:openapi:files` сначала обновляет OpenAPI, а затем оставляет сервер запущенным с файловыми маршрутами:
+`nested` сопоставляет полные пути ответа и настройки списков:
 
 ```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"
+  "actors": { "pager": { "pageSize": 5 } },
+  "actors.genres": {
+    "where": { "id": { "in": ["2", "3"] } },
+    "order": [{ "field": "name", "direction": "ASC" }]
   }
 }
 ```
 
-Режимы CLI:
+Путь в `nested` должен быть выбран через `scope` и вести к списку объектов. Маршруты отдельных записей и мутации принимают `scope` и `nested`; корневые `where`, `order` и `pager` применяются к GET коллекции. Неизвестные имена и небезопасные пути возвращают `400`.
+
+### GraphQL
+
+```graphql
+query {
+  userList(
+    order: [{ field: fullName, direction: ASC }]
+    pager: { page: 1, pageSize: 20 }
+  ) {
+    total
+    data {
+      id
+      fullName
+      movies(order: [{ field: title, direction: ASC }], pager: { pageSize: 5 }) {
+        total
+        data { id title }
+      }
+    }
+  }
+}
+```
 
-| Команда | Поведение |
-| --- | --- |
-| `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 с файловыми маршрутами и завершает работу |
+Запрос `user(id: ...)` возвращает одну запись или `null`, если она отсутствует. Мутации: `userCreate(data: ...)`, `userReplace(id: ..., data: ...)`, `userUpdate(id: ..., data: ...)`, `userDelete(id: ...)`. Для модели, состоящей из генерируемых полей, мутация создания вызывается без аргумента `data`. Правила записи и валидации совпадают с REST. Связи, выбранные в результате мутации, определяют содержимое ответа.
 
-Флаг `--files` независим: без него файловые маршруты не регистрируются и не добавляются в OpenAPI, даже если секция `files` присутствует в конфиге. Параметры `--openapi` и `--openapi-only` взаимоисключающие. Команда `deep-json-server --help` выводит краткую справку по CLI.
+Строковый первичный ключ представлен типом GraphQL `ID`, обычные строки — `String`, числа — `Float`, параметры пагинации — `Int`. Enum сохраняет допустимые строковые имена; остальные значения получают имена `VALUE_0`, `VALUE_1` и т. д. Длины строк, форматы и другие ограничения модели проверяются сервером при выполнении запроса. Для просмотра схемы доступна интроспекция. Параметры выбранных списков проверяются до выполнения мутаций. Ошибки содержат `extensions.code`: `INVALID_INPUT`, `INVALID_QUERY`, `NOT_FOUND`, `CONFLICT` или `INTERNAL_ERROR`.
 
 ## Пример базы данных
 
-Ниже приведён пример каталога фильмов с тестовыми данными. `Гангстер` связан с родительским жанром `Криминал`.
-
 ```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": "3", "isArchived": false, "name": "Драма", "parentIds": [] },
-    { "id": "4", "isArchived": false, "name": "Комедия", "parentIds": [] }
+    {
+      "id": "1",
+      "isArchived": false,
+      "name": "Криминал",
+      "parentIds": []
+    },
+    {
+      "id": "2",
+      "isArchived": false,
+      "name": "Гангстер",
+      "parentIds": ["1"]
+    },
+    {
+      "id": "3",
+      "isArchived": false,
+      "name": "Драма",
+      "parentIds": []
+    },
+    {
+      "id": "4",
+      "isArchived": false,
+      "name": "Комедия",
+      "parentIds": []
+    }
   ],
   "movies": [
     {
       "actors": [
-        { "genreIds": ["2", "3"], "id": "movie-1-actor-1", "userId": "1" },
-        { "genreIds": ["3"], "id": "movie-1-actor-2", "userId": "2" }
+        {
+          "genreIds": ["2", "3"],
+          "id": "movie-1-actor-1",
+          "userId": "1"
+        },
+        {
+          "genreIds": ["3"],
+          "id": "movie-1-actor-2",
+          "userId": "2"
+        }
       ],
       "coverSrc": "https://example.com/covers/shadows-of-ardenia.jpg",
       "description": "Наследница портового города раскрывает заговор двух соперничающих семей.",
@@ -186,8 +350,16 @@ export default {
     }
   ],
   "publishers": [
-    { "id": "1", "isArchived": false, "name": "Northlight Studio" },
-    { "id": "2", "isArchived": false, "name": "Aurora Pictures" }
+    {
+      "id": "1",
+      "isArchived": false,
+      "name": "Northlight Studio"
+    },
+    {
+      "id": "2",
+      "isArchived": false,
+      "name": "Aurora Pictures"
+    }
   ],
   "users": [
     {
@@ -208,150 +380,12 @@ export default {
 }
 ```
 
-Каждый массив верхнего уровня становится REST-ресурсом:
-
-```text
-GET    /movies
-GET    /movies/:id
-POST   /movies
-PUT    /movies/:id
-PATCH  /movies/:id
-DELETE /movies/:id
-```
-
-`POST` генерирует строковый ID. `PUT` полностью заменяет выбранную запись, а `PATCH` изменяет только переданные поля; обе операции сохраняют существующий ID и его тип. Поле `id` в теле любого запроса не может переопределить ID, которым управляет сервер. Все операции записи — `POST`, `PUT`, `PATCH` и `DELETE` — выполняются последовательно; дисковое хранилище записывает их в JSON, а хранилище в памяти сохраняет до завершения процесса.
-
-Файл базы должен существовать до запуска. Имена ресурсов могут содержать латинские буквы, цифры, `_` и `-` и должны начинаться с буквы. Каждый ресурс является массивом JSON-объектов. У каждой записи должен быть непустой строковый или конечный числовой `id`; ID должны быть уникальны внутри ресурса при сравнении как строки, поэтому `1` и `"1"` не могут существовать одновременно. Все вложенные значения должны быть совместимы с JSON: конечные числа, строки, логические значения, `null`, массивы и обычные объекты. Перед каждым GET-запросом к ресурсу и изменением сервер заново читает файл, поэтому корректные правки существующих ресурсов становятся видны сразу. Имена ресурсов и маршруты определяются при запуске; после добавления, удаления или переименования массива верхнего уровня перезапустите сервер.
-
-Успешная операция записи возвращает созданную, заменённую, обновлённую или удалённую запись. Ошибки используют подходящий HTTP-статус и следующий JSON-формат:
-
-```json
-{ "error": "..." }
-```
-
-## Пагинация и сортировка
-
-```http
-GET /movies?_page=1&_perPage=10&_sort=-id,title
-```
-
-GET-запрос к коллекции всегда возвращает объект с массивом текущей страницы и общим количеством записей после фильтрации. По умолчанию `_page` равен `1`, а `_perPage` — `10`:
-
-```json
-{
-  "data": [],
-  "total": 0
-}
-```
-
-`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`.
-
-## Фильтры
-
-Передайте JSON-объект через `_where`:
-
-```http
-GET /movies?_where={"title":{"contains":"тени"}}
-```
-
-Можно фильтровать вложенные объекты и массивы на любой глубине. Условия внутри одного объекта по умолчанию объединяются через `AND`:
-
-```json
-{
-  "actors": { "some": { "userId": { "eq": "1" } } },
-  "title": { "contains": "тени" }
-}
-```
-
-Для явных логических групп используйте `and`, `or` и `not`:
-
-```json
-{
-  "and": [
-    {
-      "or": [
-        { "title": { "contains": "тени" } },
-        { "actors": { "some": { "userId": { "eq": "2" } } } }
-      ]
-    },
-    { "not": { "isArchived": { "eq": true } } }
-  ]
-}
-```
-
-Операторы полей:
-
-| Оператор | Поведение |
-| --- | --- |
-| `eq`, `ne` | Равенство или неравенство |
-| `contains` | Подстрока без учёта регистра для строк или совпадающий элемент массива |
-| `startsWith`, `endsWith` | Начало или окончание строки без учёта регистра |
-| `gt`, `gte`, `lt`, `lte` | Сравнение значений; строки дат ISO можно сравнивать лексикографически |
-| `in` | Совпадение скалярного значения или элемента массива с одним из переданных значений |
-| `some`, `every`, `none` | Применение вложенного условия к элементам массива |
-| `not` | Отрицание вложенного условия поля |
-
-Также можно использовать простые query-параметры:
-
-```http
-GET /movies?title:contains=тени
-```
-
-В простых фильтрах распознаются JSON-примитивы: числа, `true`, `false` и `null`. Значения с ведущими нулями, например `001`, остаются строками. Неизвестные операторы, некорректные логические условия и отсутствующие в непустом ресурсе пути фильтра возвращают `400`.
-
-Разные простые query-фильтры объединяются через `AND`. Повтор одного фильтра равенства выбирает любое из его значений, поэтому `GET /movies?id=1&id=2` равнозначен `GET /movies?id:in=1,2`. Для оператора `in` значения перечисляются через запятую. Для поля-массива `in` означает, что хотя бы один элемент поля совпадает хотя бы с одним переданным значением. `every` для пустого массива возвращает `true`, а `some` — `false`.
-
-Если передан `_where`, он становится полным фильтром, а остальные простые параметры фильтрации игнорируются. В примерах JSON оставлен читаемым; при ручном формировании URL HTTP-клиент должен закодировать значение `_where`, например через `encodeURIComponent(JSON.stringify(where))`.
-
-Фильтрация выполняется после `_embed`. Поэтому фильтр может обращаться к полям добавленной связи, если в том же запросе указан соответствующий `_embed`; сохранённые поля `...Id` и `...Ids` всегда можно фильтровать напрямую.
-
-## Связи
-
-Используйте `_embed`, чтобы добавить связанные записи в ответ:
-
-```http
-GET /movies/1?_embed=actors.user.country&_embed=actors.genres&_embed=publishers
-```
-
-Ответ будет содержать актёров, пользователя и жанры каждого актёра, страну пользователя и издателей. Исходные поля с ID остаются в ответе, а файл базы не изменяется. Сервер не устанавливает фиксированный лимит глубины, но каждый требуемый уровень должен быть явно указан в конечном пути `_embed`:
-
-```http
-GET /movies/1?_embed=actors.user.country
-GET /genres/2?_embed=parents.parents
-```
-
-Неизвестные и некорректные пути `_embed` возвращают `400`.
-
-Параметр `_embed` можно передать несколько раз, как в примере выше, либо перечислить пути через запятую в одном параметре. Пагинация применяется только к запрошенной корневой коллекции; вложенные связанные записи возвращаются полностью.
-
-Поддерживаются и обратные связи:
-
-```http
-GET /countries/1?_embed=users
-```
-
-Связи определяются по именам полей. Поле `<relation>Id` создаёт одиночную связь, а `<relation>Ids` — связь с коллекцией. Имя связи сопоставляется с ресурсом верхнего уровня напрямую или через его форму в единственном числе. Например:
-
-- `countryId` ссылается на `countries`;
-- `userId` ссылается на `users`, если запрошена связь `user`;
-- `genreIds` ссылается на `genres`;
-- `publisherIds` ссылается на `publishers`;
-- `parentIds` ссылается на тот же ресурс, если запрошена связь `_embed=parents`; `_embed=children` загружает обратную связь с дочерними записями.
-
-Имя обратной связи совпадает с именем исходного ресурса. Например, `_embed=users` у страны находит пользователей, во вложенных данных которых указан соответствующий `countryId`. Сервер получает связи по запросу, но не проверяет ссылочную целостность при записи данных.
-
-Явные поля `...Id` и `...Ids` определяют связи. Если в записи также сохранено устаревшее вложенное значение, `_embed` заменяет это свойство ответа актуальной связанной записью. Если связанная запись для одиночной связи не найдена, результатом будет `null`; отсутствующие связанные записи коллекции не попадут в итоговый массив. ID-индексы создаются только для ресурсов, используемых при поиске связей в текущем запросе.
-
 ## Файлы
 
-Добавьте `files.directory` и `files.metadata` в конфиг сервера, затем передайте `--files`, чтобы включить загрузку бинарных файлов:
+Добавьте `files.directory` и `files.metadata` в конфигурацию и запустите сервер:
 
 ```bash
-deep-json-server --files server.config.js
+deep-json-server server.config.js
 ```
 
 Для временных тестов вместо этого используйте `files.data`. Каждая начальная запись содержит `name`, `mimeType`, бинарное `content` в виде `Uint8Array` и необязательный `directory`. Загруженные файлы в таком режиме остаются в памяти до завершения процесса.
@@ -407,176 +441,52 @@ Content-Type: application/json
 
 `PATCH` возвращает обновлённые метаданные со статусом `200`; если по новому пути уже существует файл, сервер возвращает `409`. `DELETE` отвечает статусом `204` без тела. Если файл не найден, любая операция по пути возвращает `404`. Пути в URL задаются относительно `files.directory`, а все возвращаемые URL — относительно адреса сервера.
 
-При хранении на диске бинарный файл находится по пути `<files.directory>/<directory>/<name>`. Файл метаданных содержит только `directory`, `mimeType` и `name`; `size` считывается у фактического файла, а URL вычисляются. Используйте дисковую базу и файловое хранилище только из одного процесса сервера одновременно и не редактируйте сохранённые файлы или метаданные до его остановки. Сервер автоматически создаёт директории, пути внутри `files.directory` не могут содержать символические ссылки, а имена файлов ограничены переносимыми между поддерживаемыми операционными системами значениями. Изначально файл метаданных может отсутствовать: он создаётся при первой загрузке. Метаданные, созданные версиями до перехода на адресацию по пути, несовместимы с новым форматом.
-
-Используется бинарное тело запроса, а не `multipart/form-data`, поэтому `XMLHttpRequest.upload.onprogress` может показывать прогресс при непосредственной отправке `File` через `xhr.send(file)`. Максимальный размер по умолчанию равен 100 МиБ и настраивается через `server.maxFileSize`. Отсутствующие или небезопасные заголовки и пути возвращают `400`, превышение лимита — `413`, а отсутствующий, некорректный или не поддерживаемый Fastify `Content-Type` — `400` либо `415` в зависимости от этапа проверки.
-
-## Схема базы данных и генерация OpenAPI
+При хранении на диске бинарный файл находится по пути `<files.directory>/<directory>/<name>`. Файл метаданных содержит только `directory`, `mimeType` и `name`; `size` считывается у фактического файла, а URL вычисляются. Используйте дисковую базу и файловое хранилище только из одного процесса сервера одновременно и не редактируйте сохранённые файлы или метаданные до его остановки. Сервер автоматически создаёт директории, пути внутри `files.directory` не могут содержать символические ссылки, а имена файлов ограничены переносимыми между поддерживаемыми операционными системами значениями. Изначально файл метаданных может отсутствовать: он создаётся при первой загрузке.
 
-Необязательный путь или объект в `database.schema` настраивает автоматически выведенные схемы. Это собственный формат настроек Deep JSON Server, а не стандартный документ JSON Schema: `$schema` здесь является объектом с настройками ресурсов. Например, файл `mock/database-schema.json` может содержать:
-
-```json
-{
-  "$info": {
-    "title": "API каталога фильмов",
-    "version": "1.0.0"
-  },
-  "$schema": {
-    "movies": {
-      "required": ["actors", "actors.genreIds", "actors.userId", "publisherIds", "title"],
-      "formats": {
-        "coverSrc": "uri"
-      }
-    },
-    "users": {
-      "required": ["bornAt", "fullName"],
-      "formats": {
-        "avatarSrc": "uri",
-        "bornAt": "date"
-      }
-    }
-  }
-}
-```
-
-Настройки схемы:
-
-| Ключ | Назначение |
-| --- | --- |
-| `$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 --openapi-only server.config.js
-```
-
-Чтобы включить в документ файловые маршруты, настройте секцию `files` и добавьте флаг `--files`: `deep-json-server --files --openapi-only server.config.js`.
-
-Генератор определяет ресурсы и типы полей по всем записям базы. По умолчанию все найденные поля необязательные, а поле `id` верхнего уровня всегда обязательное в схемах ответа и исключается из схем создания и обновления. Остальные обязательные поля перечисляются в `required`. Вложенный обязательный путь делает обязательным само вложенное свойство, но не все его родительские пути; при необходимости родителя нужно перечислить отдельно.
-
-Разные непересекающиеся типы значений определяются независимо и объединяются через `oneOf`; сочетание целых и дробных чисел описывается одной схемой `number`. Перед генерацией проверяются `$info`, имена ресурсов и компонентов, поддерживаемые ключи `properties` и типы их значений; пути из `required` и `formats` должны существовать в итоговой схеме. Явные имена компонентов могут содержать латинские буквы, цифры, точки, подчёркивания и дефисы.
-
-Используйте `properties`, чтобы описать поля, которые невозможно определить автоматически, особенно у пустого ресурса. Явно заданные свойства объединяются с найденными автоматически:
-
-```json
-{
-  "$schema": {
-    "reviews": {
-      "properties": {
-        "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
-        "text": { "type": "string" }
-      },
-      "required": ["rating"]
-    }
-  }
-}
-```
-
-Пустой ресурс всё равно получает обязательное строковое поле `id`, поскольку сервер создаёт строковые ID. При совпадении имён схем или `operationId` генерация завершается понятной ошибкой; коллизию имён схем можно устранить с помощью явного `name`. Директория результата создаётся автоматически, а настроенный YAML-файл заменяется при каждой генерации.
-
-`$info` становится объектом `info` в OpenAPI, а настройки ресурсов находятся внутри `$schema`. В CLI поле `servers` формируется из `server.host` и `server.port`, затем из резервных переменных окружения `HOST` и `PORT`, а при их отсутствии используется `http://127.0.0.1:4001`. При прямом вызове `createServer()` переменные окружения автоматически не читаются: `server.openapi()` использует значения конфига или тот же адрес по умолчанию.
-
-Используйте `name`, если ресурсу нужно явно задать имя схемы вместо автоматически полученного имени в единственном числе:
-
-```json
-{
-  "$schema": {
-    "equipment": {
-      "name": "Equipment"
-    }
-  }
-}
-```
-
-В сгенерированном документе описаны CRUD-маршруты, пагинация, сортировка, фильтрация вложенных данных, `_embed`, а также прямые и обратные связи в ответах, определённые по полям `...Id` и `...Ids`. При наличии `--files` в него также добавляются маршруты бинарной загрузки, получения и удаления файлов с поддержкой произвольных MIME-типов. Числовой ID базы описывается как `integer | string`, поскольку последующий `POST` создаст строковый ID в том же ресурсе. До создания документа генератор отклоняет повторяющиеся имена схем и `operationId`, а также некорректные переопределения схем. Файл можно передать, например, в RTK Query OpenAPI Codegen. OpenAPI создаётся только с параметром `--openapi` или `--openapi-only`; обычный запуск сервера файл не перезаписывает.
-
-При обычном запуске тела запросов проверяются по тем же автоматически выведенным и настроенным схемам. Для `POST` и `PUT` проверяются обязательные поля из `required`; `PATCH` проверяет только фактически переданные поля. Настройки `formats` и `properties` применяются ко всем трём методам. Не перечисленные дополнительные поля объекта остаются разрешёнными. Некорректные тела возвращают `400`.
+Отправляйте файл как бинарное тело запроса. В браузере для этого можно использовать `xhr.send(file)`, а прогресс отслеживать через `XMLHttpRequest.upload.onprogress`. Максимальный размер по умолчанию равен 100 МиБ и настраивается через `server.maxFileSize`. Отсутствующие или небезопасные заголовки и пути возвращают `400`, превышение лимита — `413`, а отсутствующий, некорректный или не поддерживаемый Fastify `Content-Type` — `400` либо `415` в зависимости от этапа проверки.
 
 ## Программный API
 
 ```js
 import { createServer } from '@kollors/deep-json-server';
+import config from './server.config.js';
+
+const facade = await createServer(config);
+const openapi = await facade.openapi();
+const sdl = await facade.graphql();
+const server = facade.fastify();
+await server.listen();
+// await server.close();
+```
 
-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: {
-    cors: true,
-    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' });
-
-console.log(response.json());
-
-// Возвращает документ и записывает его в config.openapi.path.
-const document = await server.openapi();
+Методы `openapi()` и `graphql()` возвращают схемы. `fastify()` возвращает экземпляр сервера для настройки и запуска. База и включённые сервисы инициализируются при `ready()`, `listen()` или первом `inject()`; ошибка инициализации останавливает запуск. Возможности сервера можно переопределить через `createServer(config, { files: false, graphql: true, openapi: true })`.
 
-await fastify.close();
+Генераторы можно использовать отдельно:
 
-// Запуск сетевого сервера. Вызов без аргументов использует server.host и server.port.
-const runningServer = await createServer(config);
-const runningFastify = runningServer.fastify();
+```js
+import { generateOpenapi, generateGraphql, writeOpenapi, writeGraphql } from '@kollors/deep-json-server';
 
-await runningFastify.listen();
+const document = await generateOpenapi('./schema.json', { files: true });
+const sdl = await generateGraphql('./schema.json');
+await writeOpenapi(document, './generated/openapi.yaml');
+await writeGraphql(sdl, './generated/schema.graphql');
+```
 
-// Позже, при завершении приложения:
-await runningFastify.close();
+`generateOpenapi()` также принимает `host`, `port`, `pageSize`, `maxPageSize` и `info`. Вместо пути можно передать объект схемы. Сервер и генераторы работают с собственной копией модели.
 
-// База, схема и файлы полностью в памяти.
-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]), directory: 'examples', mimeType: 'application/octet-stream', name: 'example.bin' }],
-  },
-});
+## Хранение и разработка
 
-const memoryFastify = memoryServer.fastify();
-const memoryResponse = await memoryFastify.inject({ method: 'GET', url: '/movies/1' });
+Изменения выполняются последовательно внутри экземпляра сервера и проверяются на копии данных до сохранения. Для одного файла базы используйте один процесс сервера. Счётчики `increment` хранятся рядом с базой в `<путь базы>.counters.json`; сохраняйте этот файл вместе с базой. Номера резервируются до записи данных: сбой может оставить пропуск, но не приводит к повторной выдаче номера.
 
-console.log(memoryResponse.json());
+Сервер предназначен для имитации API. Авторизацию и хеширование паролей при необходимости реализуйте в приложении.
 
-await memoryFastify.close();
+```sh
+npm ci
+npm run verify
 ```
 
-`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-декларации возвращаемого объекта и всех вариантов конфигурации.
+Команда проверяет типы, стиль кода, покрытие тестами и установку пакета из архива.
 
-## Назначение и безопасность
+Для публикации новой альфы обновите версию в `package.json` и отправьте изменения в `main`. GitHub Actions создаст тег версии и опубликует пакет в канал npm `alpha` через trusted publishing. Уже опубликованная версия пропускается. Если тег создан, а публикация не завершилась, повторный запуск использует этот тег и проверяет соответствие ему файлов пакета. Отправка тега версии также запускает публикацию; стабильные версии публикуются в `latest`.
 
-Deep JSON Server предназначен для локальной разработки и автоматических тестов. В нём нет аутентификации и авторизации, CORS по умолчанию разрешён для любого источника, при дисковом хранилище принятые изменения сохраняются в настроенные файлы, а ссылочная целостность не проверяется. Установите `server.cors: false`, чтобы отключить встроенные CORS-заголовки и маршруты `OPTIONS`. Оставляйте адрес loopback по умолчанию, если внешняя среда не предоставляет собственный контроль доступа; не открывайте сервер и файловые маршруты для недоверенной сети.
+Лицензия: MIT.