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

package/README.ru.md

@@ -1,172 +1,315 @@
 # 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.1 — предварительная версия с несовместимыми изменениями.** Старые `$schema`/`$info` и параметры `_where`, `_sort`, `_embed`, `_page`, `_perPage` больше не поддерживаются.
 
 ## Установка
 
-Требуется Node.js 22 или новее.
-
-```bash
-npm install --save-dev @kollors/deep-json-server
+```sh
+npm install @kollors/deep-json-server@alpha
 ```
 
+Канал npm `alpha` отделён от `latest`. Для точной версии используйте `@1.0.0-alpha.1`.
+
 ## Быстрый старт
 
-До запуска создайте файл базы `mock/database.json`:
+`server.config.js`:
+
+```js
+export default {
+  database: { path: './database.json', schema: './schema.json' },
+  graphql: { enabled: true, path: './generated/schema.graphql' },
+  openapi: { path: './generated/openapi.yaml' },
+  server: { host: '127.0.0.1', port: 4001, pageSize: 10, maxPageSize: 100 },
+};
+```
+
+```sh
+npx deep-json-server server.config.js
+npx deep-json-server --openapi-only --graphql-only server.config.js
+```
+
+Вторая команда экспортирует обе схемы без запуска сервера. Обычный запуск не записывает файлы схем.
+
+Полные примеры каталога: [база](examples/database.json), [схема моделей](examples/schema.json), [конфигурация](examples/server.config.js).
+
+## Конфигурация
+
+| Ключ | Назначение |
+|---|---|
+| `database.path` / `database.data` | Ровно один: JSON-файл или объект коллекций в памяти |
+| `database.schema` | Объект моделей или путь к JSON-файлу; необязателен для REST |
+| `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` | Экспортировать OpenAPI и запустить сервер |
+| `--openapi-only` | Только экспортировать OpenAPI |
+| `--graphql-schema` | Экспортировать GraphQL SDL и запустить сервер |
+| `--graphql-only` | Только экспортировать GraphQL SDL |
+| `--help` | Показать справку |
+
+Экспортеры можно объединять. Любой флаг `--*-only` исключает запуск сервера. В CLI для файлов нужен `--files`; программный API включает их при наличии секции `files`, если второй аргумент `createServer()` не переопределяет это поведение.
+
+## Схема моделей
 
 ```json
 {
-  "movies": [
-    { "id": "1", "title": "Тени Ардении" }
-  ]
+  "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" }
+    }
+  }
 }
 ```
 
-Рядом с `package.json` создайте ESM-модуль `server.config.js`:
+По умолчанию `api` содержит `["openapi", "graphql"]`. Пустой массив исключает модель из экспорта и GraphQL, но REST продолжает работать. Связанные модели должны разрешать тот же формат экспорта. Имена должны быть допустимыми идентификаторами; конфликты генерируемых типов и операций вызывают ошибку. Имена `and`, `or`, `not` зарезервированы фильтрами.
 
-```js
-export default {
-  database: {
-    path: 'mock/database.json',
-  },
-};
+| Возможность | Со схемой | Без схемы |
+|---|---|---|
+| REST CRUD | Валидация модели | Только проверки JSON, тела запроса и идентификаторов |
+| Связи | Поля схемы | По ключам `countryId`, `genreIds` и аналогичным |
+| Экспорт OpenAPI 3.0.3 | Доступен | Ошибка при запросе экспорта |
+| GraphQL SDL / API | Доступен | Ошибка при запросе |
+
+При явной схеме неизвестные поля и коллекции запрещены. Исключение — хранимые ключи, выведенные из связей. Исходная база проверяется при загрузке. Схемы можно экспортировать для пустых коллекций и пустого объекта базы. REST без схемы сохраняет обычный генерируемый ключ `id`.
+
+### Поля
+
+Типы: `string`, `number`, `boolean`, `object` или имя модели. Суффикс `[]` обозначает массив. Нет `integer`, `relation`, `items` и многомерных строк типов. Вложенные поля описываются через точку: `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`. Ограничений количества и уникальности элементов нет. Обязательный обычный массив может быть пустым.
+
+У модели ровно один корневой первичный ключ типа string/number. Имя произвольное: `id`, `username`, `code`. Без `generated` значение передаёт клиент при создании. Генерируемые поля могут быть только корневыми, исключаются из входных типов и несовместимы с `default`. Replace сохраняет корневые генерируемые поля и `readOnly`.
+
+Например, `LocalUser` с первичным `username` и полем `password: {"type":"string","required":true,"writeOnly":true}` получает запрос `localUser(username: ...)` и маршрут `/localUsers/{username}`. Пароль исключён из ответов, scope, фильтров и сортировки. Это не реализует хеширование и авторизацию.
+
+### Связи
+
+```json
+"actors.genres": {
+  "type": "Genre[]",
+  "source": "actors.genreIds",
+  "required": true
+}
 ```
 
-Запустите сервер:
+`Genre` возвращает объект, `Genre[]` — список. Без `source` используем первичный ключ текущей модели, без `target` — первичный ключ целевой. Пути полные, от корня соответствующей записи. Внутри `actors` путь `actors.genreIds` читает ключи текущего актёра. Пропущенный `source` означает ключ корневой модели, а не `actors.id`.
 
-```bash
-npx deep-json-server server.config.js
+Хранимые ключи остаются в базе и входят в собственные поля. Их типы выводятся из сопоставляемых ключей. Для необъявленного source, ссылающегося на первичный ключ цели, множественная связь означает массив ключей, одиночная — одно значение. Если сопоставление неоднозначно, нужное хранимое поле следует описать явно. Генерация не зависит от первой записи базы.
+
+Обратная связь: `User.movies = {"type":"Movie[]","target":"actors.userId"}`. Фильм возвращается один раз, даже если совпало несколько актёров. Несколько совпадений для одиночной связи — ошибка.
+
+Каждая переданная прямая ссылка должна существовать. `required: true` у связи требует хотя бы одну связанную запись до фильтрации и пагинации ответа. Обратная связь с первичным source может быть пустой, если не объявлена обязательной. Отсутствующая одиночная связь возвращает `null`.
+
+`onDelete` срабатывает **при удалении целевой записи**:
+
+- `restrict` — по умолчанию: запретить удаление, пока на цель ссылается сохраняемая запись.
+- `cascade` — удалить ссылающуюся запись. Для `User.country` удаление страны удаляет пользователей. Для `Movie.actors.user` удаление пользователя удаляет соответствующие элементы actors, сохраняя фильм.
+
+Сначала вычисляется весь каскад, обрабатываются циклы и проверяются ограничения, затем сохраняется результат. Ошибка отменяет всю операцию. Политики действуют и на явно объявленные обратные связи; при описании обоих направлений учитывайте оба правила.
+
+## Запросы и ответы
+
+Коллекции и списки объектов, включая вложенные `object[]`, возвращают:
+
+```json
+{ "data": [], "total": 0 }
 ```
 
-По умолчанию API доступен по адресу `http://127.0.0.1:4001`. Например, `GET http://127.0.0.1:4001/movies` вернёт страницу:
+Массивы примитивов остаются обычными массивами. У каждого списка объектов есть необязательные `where`, `order`, `pager`. Порядок обработки: фильтрация → сортировка → пагинация. `total` считается после фильтрации, до пагинации. Страницы начинаются с 1; отсутствие pager включает пагинацию по умолчанию. Превышение максимума, дробные и неположительные значения — ошибка. За пределами списка возвращается пустой data с правильным total.
+
+Фильтры: `eq`, `ne`, `in`; для строк `contains`, `startsWith`, `endsWith`; сравнения `gt`, `gte`, `lt`, `lte`. Логика — `and`, `or`, `not`. У массивов есть `some`, `every`, `none`; у примитивных массивов также `contains`, `in`. Поиск строк не учитывает регистр. Условия полей записываются объектами операторов, без сокращения до скалярного значения.
 
 ```json
 {
-  "data": [{ "id": "1", "title": "Тени Ардении" }],
-  "total": 1
+  "movies": {
+    "some": {
+      "actors": {
+        "some": {
+          "genres": { "some": { "id": { "in": ["2", "3"] } } }
+        }
+      }
+    }
+  }
 }
 ```
 
-## Конфигурация и запуск
+Корневой where выбирает родителей. Where внутри связи фильтрует её элементы, сохраняя родителя. Каждый вложенный список обрабатывается отдельно. Для фильтра по связи не нужно раскрывать её в ответе.
 
-Создайте ESM-модуль `server.config.js`. В примере ниже показаны настройки всех возможностей:
-
-```js
-import process from 'node:process';
+`order` — массив правил `{ "field": "fullName", "direction": "ASC" }`. Первое правило приоритетнее; полные совпадения сохраняют порядок хранения. `null` и отсутствующее значение сравниваются одинаково. REST использует путь `profile.name`, GraphQL — enum `profile_name`. Неоднозначные имена enum вызывают ошибку генерации. Сортировка родителей по связям и массивам пока не поддерживается; внутри связи сортировка доступна.
 
-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,
-  },
-};
-```
+### REST
 
-Ключи конфигурации:
+| Метод | Путь | Операция |
+|---|---|---|
+| GET | `/users` | `userList` |
+| GET | `/users/{id}` | `user` |
+| POST | `/users` | `userCreate` |
+| PUT | `/users/{id}` | `userReplace` |
+| PATCH | `/users/{id}` | `userUpdate` |
+| DELETE | `/users/{id}` | `userDelete` |
 
-| Ключ | Условие | Назначение |
-| --- | --- | --- |
-| `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` |
+Имя параметра пути соответствует первичному ключу. POST/PUT/PATCH принимают обычный объект записи. PUT заменяет запись с сохранением ключа и корневых серверных полей. PATCH поверхностно объединяет поля; переданные вложенные объекты заменяются целиком. Create/replace проверяют обязательность. Update проверяет переданные значения и итоговую запись. Отсутствующая запись — 404, конфликт — 409. DELETE возвращает удалённую запись.
 
-`server.port` должен быть целым числом от `0` до `65535`. Значение `0` позволяет Fastify выбрать свободный порт при запуске, но не подходит для генерации URL в OpenAPI, где допустимы порты от `1` до `65535`. `server.maxFileSize` и `server.maxPageSize` должны быть положительными целыми числами.
+Параметры `where`, `order`, `pager`, `nested` содержат JSON; `scope` — строку выбора. Пример до URL-кодирования:
 
-Все относительные пути вычисляются от директории с `server.config.js`, а не от текущей рабочей директории. Неизвестные ключи, пустые пути и значения некорректных типов отклоняются до запуска. Конфиг является исполняемым JavaScript: в нём можно читать переменные окружения, импортировать другие модули и вычислять значения перед экспортом объекта. Для `.js`-конфига с `export default` проект должен быть ESM (`"type": "module"`); в CommonJS-проекте сохраните тот же конфиг как `server.config.mjs`.
+```text
+GET /users?where={"fullName":{"contains":"Мира"}}&order=[{"field":"fullName","direction":"ASC"}]&pager={"page":1,"pageSize":20}
+```
 
-В том же конфиге все данные можно разместить в памяти. `database.path` и `database.data` взаимоисключающие, а `database.schema` принимает путь или объект. Аналогично, `files.data` нельзя сочетать с `files.directory` или `files.metadata`:
+Кодирование через `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 и не раскрывает связи. Без scope выбираются собственные поля. Оболочки 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: ...)`, без ById; отсутствующая запись даёт 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 и т. д. Длины строк и форматы проверяет общий валидатор во время выполнения: SDL не выражает все ограничения. Доступны интроспекция, обычные query и mutation; подписки и массовые мутации не добавлены.
 
-## Пример базы данных
 
-Ниже приведён пример каталога фильмов с тестовыми данными. `Гангстер` связан с родительским жанром `Криминал`.
+## Пример базы данных
 
 ```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 +329,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,144 +359,6 @@ 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`, чтобы включить загрузку бинарных файлов:
@@ -411,172 +424,33 @@ Content-Type: application/json
 
 Используется бинарное тело запроса, а не `multipart/form-data`, поэтому `XMLHttpRequest.upload.onprogress` может показывать прогресс при непосредственной отправке `File` через `xhr.send(file)`. Максимальный размер по умолчанию равен 100 МиБ и настраивается через `server.maxFileSize`. Отсутствующие или небезопасные заголовки и пути возвращают `400`, превышение лимита — `413`, а отсутствующий, некорректный или не поддерживаемый Fastify `Content-Type` — `400` либо `415` в зависимости от этапа проверки.
 
-## Схема базы данных и генерация OpenAPI
-
-Необязательный путь или объект в `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`.
-
 ## Программный 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();
-
-await fastify.close();
+Аксессоры ленивые: экспорт не открывает порт и не инициализирует дисковое файловое хранилище. Возможности сервера можно переопределить через `createServer(config, { files: false, graphql: true })`.
 
-// Запуск сетевого сервера. Вызов без аргументов использует server.host и server.port.
-const runningServer = await createServer(config);
-const runningFastify = runningServer.fastify();
+## Хранение и разработка
 
-await runningFastify.listen();
+Изменения выполняются последовательно внутри экземпляра сервера и проверяются на копии данных до сохранения. Для одного файла базы используйте один пишущий сервер. Счётчики increment хранятся рядом с базой в `<путь базы>.counters.json`; сохраняйте этот файл вместе с базой. Номера резервируются до записи данных: сбой может оставить пропуск, но не приводит к повторной выдаче номера. UUID создаётся встроенным crypto Node.js.
 
-// Позже, при завершении приложения:
-await runningFastify.close();
+Это сервер для имитации API: авторизации и хеширования паролей нет. Файловые маршруты сохраняют отдельное хранилище и собственную валидацию.
 
-// База, схема и файлы полностью в памяти.
-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' });
-
-console.log(memoryResponse.json());
-
-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-декларации возвращаемого объекта и всех вариантов конфигурации.
-
-## Назначение и безопасность
+Проверка включает типы, линтер, пороги покрытия и установку упакованного пакета. Новая alpha-версия package.json в main создаёт свой тег и публикуется через GitHub Actions trusted publishing в канал npm alpha. Если тег уже существует, автоматическая публикация пропускается. Явная отправка тега версии также запускает публикацию; стабильные версии используют latest. Скрипт проверяет совпадение Git-тега и версии пакета.
 
-Deep JSON Server предназначен для локальной разработки и автоматических тестов. В нём нет аутентификации и авторизации, CORS по умолчанию разрешён для любого источника, при дисковом хранилище принятые изменения сохраняются в настроенные файлы, а ссылочная целостность не проверяется. Установите `server.cors: false`, чтобы отключить встроенные CORS-заголовки и маршруты `OPTIONS`. Оставляйте адрес loopback по умолчанию, если внешняя среда не предоставляет собственный контроль доступа; не открывайте сервер и файловые маршруты для недоверенной сети.
+Лицензия: MIT.