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

package/README.ru.md

@@ -2,9 +2,9 @@
 
 [English](README.md)
 
-JSON-сервер для имитации API: REST, GraphQL, вложенные запросы, бинарные файлы и экспорт схем. Требуется Node.js 22 или новее.
+JSON-сервер для имитации API: REST, GraphQL, связанные записи, загрузка файлов и экспорт схем. Поддерживает вход пользователей, права владельца и администратора, даты записей и мягкое удаление. Требуется Node.js 22 или новее.
 
-**1.0.0-alpha.1 — предварительная версия с несовместимыми изменениями.** Старые `$schema`/`$info` и параметры `_where`, `_sort`, `_embed`, `_page`, `_perPage` больше не поддерживаются.
+**Breaking changes: 1.0.0-alpha.10.** Изменились форматы конфигурации и схемы. Актуальные примеры — в разделах «Конфигурация» и «Схема моделей».
 
 ## Установка
 
@@ -12,88 +12,138 @@ JSON-сервер для имитации API: REST, GraphQL, вложенные
 npm install @kollors/deep-json-server@alpha
 ```
 
-Канал npm `alpha` отделён от `latest`. Для точной версии используйте `@1.0.0-alpha.1`.
+Для установки конкретной версии укажите `@1.0.0-alpha.11`.
 
 ## Быстрый старт
 
+Создайте два файла в одном каталоге.
+
+`database.json`:
+
+```json
+{
+  "users": [
+    { "id": "1", "fullName": "Мира Волкова" }
+  ]
+}
+```
+
 `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 },
-};
+export default { storage: 'file', database: { source: './database.json' } };
 ```
 
 ```sh
 npx deep-json-server server.config.js
-npx deep-json-server --openapi-only --graphql-only server.config.js
 ```
 
-Вторая команда экспортирует обе схемы без запуска сервера. Обычный запуск не записывает файлы схем.
+Список пользователей доступен по адресу `http://127.0.0.1:4001/users`.
 
-Полные примеры каталога: [база](examples/database.json), [схема моделей](examples/schema.json), [конфигурация](examples/server.config.js).
+Для связей и валидации добавьте [схему моделей](#схема-моделей). Далее описаны [запросы](#запросы-и-ответы), [аутентификация](#аутентификация), [мягкое удаление](#даты-записей-удаление-и-владельцы), [файлы](#файлы) и [программный API](#программный-api).
 
 ## Конфигурация
 
-| Ключ | Назначение |
+При `storage: 'file'` все источники и схема задаются путями, при `'memory'` — данными в памяти. Режимы нельзя смешивать. Наличие секций `auth`, `files`, `graphql` и `openapi` включает соответствующие модули. `graphql: {}` и `openapi: {}` включают только HTTP-маршруты со стандартными адресами; для экспорта добавьте `target`.
+
+```js
+export default {
+  storage: 'file',
+  database: { source: './database.json', schema: './schema.json' },
+  auth: { source: './users.json', expiresIn: 3600 },
+  files: { source: './uploads' },
+  graphql: { target: './generated/schema.graphql' },
+  openapi: { target: './generated/openapi.yaml' },
+  server: { host: '127.0.0.1', port: 4001 },
+};
+```
+
+| Настройка | Назначение |
 |---|---|
-| `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 |
+| `storage` | Обязательный режим: `file` или `memory`; общий для всех источников и схемы |
+| `database.source` | Путь к JSON базы или объект коллекций |
+| `database.schema` | Путь к JSON схемы или объект схемы; необязателен для REST |
+| `auth.source` | Путь к JSON пользователей или массив пользователей |
+| `auth.expiresIn` | Срок сессии в секундах; по умолчанию 3600 |
+| `files.source` | Каталог файлов или массив начальных файлов |
+| `files.metadata` | Только для `file`: путь JSON метаданных; по умолчанию `.files.json` внутри `files.source` |
+| `graphql.endpoint` | HTTP-маршрут; по умолчанию `/graphql` |
+| `graphql.target` | Файл для экспорта GraphQL SDL |
+| `openapi.endpoint` | HTTP-маршрут; по умолчанию `/openapi.json` |
+| `openapi.target` | Файл для экспорта OpenAPI |
+| `openapi.info` | Метаданные: обязательные `title`, `version`, необязательный `description` |
 | `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.cors`, `server.logger` | По умолчанию `true`; logger принимает также настройки Fastify |
 | `server.maxFileSize` | По умолчанию 100 МиБ |
-| `files.data` | Бинарные файлы в памяти |
-| `files.directory`, `files.metadata` | Каталог файлов и JSON метаданных; необходимы оба |
 
-Пути конфигурационного файла разрешаются относительно него. При прямом `createServer()` — относительно рабочего каталога. Переданные данные в памяти копируются.
+Относительные пути разрешаются от каталога файла конфигурации; при вызове `createServer(config)` — от рабочего каталога. Данные в памяти, включая схему, копируются. Порт `0` позволяет системе выбрать свободный порт.
+
+### CLI
 
-| Флаг CLI | Действие |
+| Флаг | Действие |
 |---|---|
-| `--files` | Включить файловые маршруты |
-| `--graphql` | Включить GraphQL API |
-| `--openapi` | Экспортировать OpenAPI и запустить сервер |
-| `--openapi-only` | Только экспортировать OpenAPI |
-| `--graphql-schema` | Экспортировать GraphQL SDL и запустить сервер |
-| `--graphql-only` | Только экспортировать GraphQL SDL |
-| `--help` | Показать справку |
+| `--generate` | Экспортировать схемы и запустить сервер |
+| `--generate-only` | Экспортировать схемы и завершить работу |
+| `--host <host>` | Адрес сервера |
+| `--port <port>` | Порт сервера |
+| `--help, -h` | Справка |
+| `--version, -v` | Версия пакета |
 
-Экспортеры можно объединять. Любой флаг `--*-only` исключает запуск сервера. В CLI для файлов нужен `--files`; программный API включает их при наличии секции `files`, если второй аргумент `createServer()` не переопределяет это поведение.
+Приоритет адреса и порта: CLI → конфигурация → `HOST`/`PORT` → значения по умолчанию. Без флагов генерации запускается только сервер. `--generate` и `--generate-only` нельзя передавать вместе.
 
 ## Схема моделей
 
+Примеры: [база данных](examples/database.json), [схема моделей](examples/schema.json), [конфигурация](examples/server.config.js).
+
 ```json
 {
-  "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"
+  ],
+  "models": {
+    "Country": {
+      "collection": "countries",
+      "fields": {
+        "id": {
+          "type": "string",
+          "primary": true,
+          "generated": "uuid"
+        },
+        "name": {
+          "type": "string",
+          "required": true
+        },
+        "users": {
+          "type": "User[]",
+          "target": "countryId"
+        }
+      }
+    },
+    "User": {
+      "collection": "users",
+      "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` зарезервированы фильтрами.
+Модели находятся в `models`. В корне схемы можно задать `api`, `timestamps` и `softDelete`; у модели эти параметры переопределяют общие значения. Для `api` приоритет такой: модель → корень схемы → секции конфигурации. Массив заменяется целиком; `[]` исключает модель из GraphQL и OpenAPI, но REST продолжает работать. Явный список не включает отсутствующий модуль. Связанные модели должны разрешать тот же формат. Имена моделей должны быть допустимыми идентификаторами; конфликты типов и операций вызывают ошибку. Имена `and`, `or`, `not` зарезервированы фильтрами.
 
 | Возможность | Со схемой | Без схемы |
 |---|---|---|
@@ -102,11 +152,15 @@ npx deep-json-server --openapi-only --graphql-only server.config.js
 | Экспорт OpenAPI 3.0.3 | Доступен | Ошибка при запросе экспорта |
 | GraphQL SDL / API | Доступен | Ошибка при запросе |
 
-При явной схеме неизвестные поля и коллекции запрещены. Исключение — хранимые ключи, выведенные из связей. Исходная база проверяется при загрузке. Схемы можно экспортировать для пустых коллекций и пустого объекта базы. REST без схемы сохраняет обычный генерируемый ключ `id`.
+При явной схеме неизвестные поля и коллекции запрещены. Исключение — хранимые ключи, выведенные из связей. Исходная база проверяется при загрузке. Генерация использует описание моделей.
+
+REST без схемы создаёт ключ `id` и сохраняет произвольные JSON-поля. Для фильтров и выбора отдельных полей используются имена в формате идентификаторов; остальные поля возвращаются через `scope=[{"*":true}]`. Поля с разными типами значений можно читать, но фильтрация, сортировка и пагинация неоднородных списков требуют явной схемы.
+
+У модели обязательны `collection` — имя коллекции в базе и REST-пути — и `fields` — описание полей. Имя модели (`User`) задаёт имена типов и операций GraphQL. `api` управляет доступностью форматов, а `timestamps` и `softDelete` переопределяют глобальные настройки для этой модели.
 
 ### Поля
 
-Типы: `string`, `number`, `boolean`, `object` или имя модели. Суффикс `[]` обозначает массив. Нет `integer`, `relation`, `items` и многомерных строк типов. Вложенные поля описываются через точку: `actors.fullName`. Объект внутри массива может содержать собственные массивы.
+Поле `type` принимает `string`, `number`, `boolean`, `object` или имя модели. Для массива добавьте суффикс `[]`: `string[]`, `object[]`, `Genre[]`. Вложенные поля описываются через точку, например `actors.fullName`.
 
 | Свойства | Назначение |
 |---|---|
@@ -114,7 +168,7 @@ npx deep-json-server --openapi-only --graphql-only server.config.js
 | `description`, `example` | Документация и пример |
 | `required`, `nullable` | По умолчанию `false`; наличие поля и разрешение `null` независимы |
 | `default` | Значение при пропуске в create/replace; PATCH не вставляет значения по умолчанию |
-| `enum` | Допустимые значения; у массива — значения каждого элемента |
+| `enum` | Допустимые строки, числа или логические значения; у массива — значения каждого элемента |
 | `primary` | Корневой первичный ключ: обязательный, уникальный, неизменяемый, без `null` |
 | `generated` | `uuid` для строк, `increment` для чисел; значение создаёт сервер |
 | `readOnly`, `writeOnly` | Только ответ или только входные данные; взаимно исключаются |
@@ -123,137 +177,40 @@ npx deep-json-server --openapi-only --graphql-only server.config.js
 | `minimum`, `maximum` | Включительные числовые границы |
 | `source`, `target`, `onDelete` | Описание связи |
 
-Ограничения строк и чисел применяются к каждому элементу `string[]`/`number[]`. `required`/`nullable` относятся ко всему массиву; `default`/`example` содержат массив целиком. Элементы массива не допускают `null`. Ограничений количества и уникальности элементов нет. Обязательный обычный массив может быть пустым.
+Ограничения строк и чисел применяются к каждому элементу `string[]`/`number[]`. `required` и `nullable` относятся ко всему массиву; `default` и `example` содержат массив целиком. Элементы массива должны соответствовать его типу и быть отличны от `null`. `required` требует наличия поля; обычный массив при этом может быть пустым.
 
-У модели ровно один корневой первичный ключ типа string/number. Имя произвольное: `id`, `username`, `code`. Без `generated` значение передаёт клиент при создании. Генерируемые поля могут быть только корневыми, исключаются из входных типов и несовместимы с `default`. Replace сохраняет корневые генерируемые поля и `readOnly`.
+У модели ровно один первичный ключ типа `string` или `number`, объявленный на верхнем уровне. Имя произвольное: `id`, `username`, `code`. Если `generated` не задан, значение передаёт клиент при создании. Генерируемые поля объявляются на верхнем уровне, исключаются из входных типов и несовместимы с `default`. При замене записи сохраняются генерируемые значения и поля `readOnly`, включая вложенные объекты. Для защиты полей внутри массива задайте `readOnly` всему массиву или содержащему его объекту. Объекты, состоящие из серверных полей, доступны только в ответах.
 
-Например, `LocalUser` с первичным `username` и полем `password: {"type":"string","required":true,"writeOnly":true}` получает запрос `localUser(username: ...)` и маршрут `/localUsers/{username}`. Пароль исключён из ответов, scope, фильтров и сортировки. Это не реализует хеширование и авторизацию.
+Например, `LocalUser` с первичным ключом `username` и полем `password: {"type":"string","required":true,"writeOnly":true}` получает запрос `localUser(username: ...)` и маршрут `/localUsers/{username}`. Поле `writeOnly` доступно для записи и исключено из ответов, `scope`, фильтров и сортировки.
+
+Объекты в GraphQL должны содержать хотя бы одно поле, доступное в ответе; REST допускает и пустые объекты.
 
 ### Связи
 
 ```json
-"actors.genres": {
-  "type": "Genre[]",
-  "source": "actors.genreIds",
-  "required": true
+{
+  "actors.genres": {
+    "type": "Genre[]",
+    "source": "actors.genreIds",
+    "required": true
+  }
 }
 ```
 
-`Genre` возвращает объект, `Genre[]` — список. Без `source` используем первичный ключ текущей модели, без `target` — первичный ключ целевой. Пути полные, от корня соответствующей записи. Внутри `actors` путь `actors.genreIds` читает ключи текущего актёра. Пропущенный `source` означает ключ корневой модели, а не `actors.id`.
+`Genre` возвращает объект, `Genre[]` — список. По умолчанию `source` указывает на первичный ключ текущей модели, `target` — целевой. Это правило действует и для вложенных связей. Пути задаются от корня соответствующей записи: в примере `actors.genreIds` содержит ключи жанров текущего актёра.
 
-Хранимые ключи остаются в базе и входят в собственные поля. Их типы выводятся из сопоставляемых ключей. Для необъявленного source, ссылающегося на первичный ключ цели, множественная связь означает массив ключей, одиночная — одно значение. Если сопоставление неоднозначно, нужное хранимое поле следует описать явно. Генерация не зависит от первой записи базы.
+Ключи связей хранятся в базе и входят в собственные поля записи. Их типы выводятся из сопоставляемых ключей. Если поле `source` ссылается на первичный ключ целевой модели, его можно не объявлять отдельно: для множественной связи создаётся описание массива ключей, для одиночной — одного значения. При неоднозначном сопоставлении опишите хранимое поле явно.
 
 Обратная связь: `User.movies = {"type":"Movie[]","target":"actors.userId"}`. Фильм возвращается один раз, даже если совпало несколько актёров. Несколько совпадений для одиночной связи — ошибка.
 
-Каждая переданная прямая ссылка должна существовать. `required: true` у связи требует хотя бы одну связанную запись до фильтрации и пагинации ответа. Обратная связь с первичным source может быть пустой, если не объявлена обязательной. Отсутствующая одиночная связь возвращает `null`.
+Каждый переданный ключ прямой связи должен указывать на существующую запись. `required: true` у связи требует хотя бы одну связанную запись до фильтрации и пагинации ответа. Обратная связь с первичным ключом в `source` может быть пустой, если не объявлена обязательной. Отсутствующая одиночная связь возвращает `null`.
 
 `onDelete` срабатывает **при удалении целевой записи**:
 
 - `restrict` — по умолчанию: запретить удаление, пока на цель ссылается сохраняемая запись.
-- `cascade` — удалить ссылающуюся запись. Для `User.country` удаление страны удаляет пользователей. Для `Movie.actors.user` удаление пользователя удаляет соответствующие элементы actors, сохраняя фильм.
-
-Сначала вычисляется весь каскад, обрабатываются циклы и проверяются ограничения, затем сохраняется результат. Ошибка отменяет всю операцию. Политики действуют и на явно объявленные обратные связи; при описании обоих направлений учитывайте оба правила.
-
-## Запросы и ответы
-
-Коллекции и списки объектов, включая вложенные `object[]`, возвращают:
-
-```json
-{ "data": [], "total": 0 }
-```
-
-Массивы примитивов остаются обычными массивами. У каждого списка объектов есть необязательные `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
-{
-  "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 вызывают ошибку генерации. Сортировка родителей по связям и массивам пока не поддерживается; внутри связи сортировка доступна.
-
-### REST
-
-| Метод | Путь | Операция |
-|---|---|---|
-| GET | `/users` | `userList` |
-| GET | `/users/{id}` | `user` |
-| POST | `/users` | `userCreate` |
-| PUT | `/users/{id}` | `userReplace` |
-| PATCH | `/users/{id}` | `userUpdate` |
-| DELETE | `/users/{id}` | `userDelete` |
-
-Имя параметра пути соответствует первичному ключу. POST/PUT/PATCH принимают обычный объект записи. PUT заменяет запись с сохранением ключа и корневых серверных полей. PATCH поверхностно объединяет поля; переданные вложенные объекты заменяются целиком. Create/replace проверяют обязательность. Update проверяет переданные значения и итоговую запись. Отсутствующая запись — 404, конфликт — 409. DELETE возвращает удалённую запись.
-
-Параметры `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
-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}`);
-```
-
-`scope=*,actors(user(id,fullName),genres(*))` выбирает собственные поля и явные связи. `*` включает собственные поля текущего объекта и хранимые ключи, исключает writeOnly и не раскрывает связи. Без scope выбираются собственные поля. Оболочки data/total сохраняются.
-
-`nested` сопоставляет полные пути ответа и настройки списков:
-
-```json
-{
-  "actors": { "pager": { "pageSize": 5 } },
-  "actors.genres": {
-    "where": { "id": { "in": ["2", "3"] } },
-    "order": [{ "field": "name", "direction": "ASC" }]
-  }
-}
-```
-
-Путь 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 }
-      }
-    }
-  }
-}
-```
-
-Одиночный запрос — `user(id: ...)`, без ById; отсутствующая запись даёт null. Мутации: `userCreate(data: ...)`, `userReplace(id: ..., data: ...)`, `userUpdate(id: ..., data: ...)`, `userDelete(id: ...)`. Если модель содержит только генерируемые поля, создание не имеет аргумента data. Используются те же операции хранения и проверки, что в REST. Выбор связей в результате мутации управляет только ответом.
-
-Строковый первичный ключ представлен GraphQL ID, обычные строки — String, числа — Float, пагинация — Int. Enum сохраняет допустимые строковые имена; остальные значения получают имена VALUE_0, VALUE_1 и т. д. Длины строк и форматы проверяет общий валидатор во время выполнения: SDL не выражает все ограничения. Доступны интроспекция, обычные query и mutation; подписки и массовые мутации не добавлены.
+- `cascade` — удалить ссылающуюся запись. Для `User.country` удаление страны удаляет пользователей. Для `Movie.actors.user` удаление пользователя удаляет соответствующие элементы `actors`, сохраняя фильм.
 
+Каскадное удаление выполняется целиком, включая циклические связи. Ошибка проверки отменяет всю операцию. Правила `onDelete` действуют и на явно объявленные обратные связи; при описании обоих направлений учитывайте оба правила.
 
 ## Пример базы данных
 
@@ -359,15 +316,381 @@ query {
 }
 ```
 
+## Запросы и ответы
+
+Примеры с фильмами, актёрами и жанрами используют полную [схему из examples](examples/schema.json). Для их запуска используйте [конфигурацию примера](examples/server.config.js):
+
+```sh
+npx deep-json-server examples/server.config.js
+```
+
+Коллекции и списки объектов, включая вложенные `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` — одно условие; `not` также можно использовать внутри фильтра поля. У массивов есть `some`, `every`, `none`; у примитивных массивов также `contains`, `in`. `contains`, `startsWith` и `endsWith` для строк не учитывают регистр; `eq`, `ne` и `in` сравнивают точные значения. Условие поля задаётся объектом с оператором, например `{ "id": { "eq": "1" } }`.
+
+```json
+{
+  "movies": {
+    "some": {
+      "actors": {
+        "some": {
+          "genres": { "some": { "id": { "in": ["2", "3"] } } }
+        }
+      }
+    }
+  }
+}
+```
+
+Корневой `where` выбирает записи основной коллекции. `where` внутри связи фильтрует её элементы, сохраняя родительскую запись. Каждый вложенный список обрабатывается отдельно. Фильтрация по связи работает независимо от её включения в ответ.
+
+`order` — массив правил `{ "field": "fullName", "direction": "ASC" }`. `ASC` сортирует по возрастанию, `DESC` — по убыванию. Первое правило приоритетнее; при равных значениях сохраняется порядок хранения. `null` и отсутствующее значение сравниваются одинаково. REST использует путь `profile.name`, GraphQL — enum `profile_name`. Неоднозначные имена enum вызывают ошибку генерации. Сортировка доступна по скалярным полям текущего объекта, включая вложенные поля. Для связанных списков задаётся собственный `order`.
+
+### REST
+
+`GET /` возвращает имена коллекций: `{ "resources": ["users", "movies"] }`. Для каждой коллекции доступны следующие маршруты:
+
+| Метод | Путь | Операция |
+|---|---|---|
+| GET | `/users` | `userList` |
+| GET | `/users/{id}` | `user` |
+| POST | `/users` | `userCreate` |
+| PUT | `/users/{id}` | `userReplace` |
+| PATCH | `/users/{id}` | `userUpdate` |
+| DELETE | `/users/{id}` | `userDelete` |
+
+Имя параметра пути соответствует первичному ключу. POST, PUT и PATCH принимают JSON-объект записи. PUT заменяет запись с сохранением ключа и серверных полей. PATCH объединяет поля на верхнем уровне; переданные вложенные объекты заменяются с сохранением их полей `readOnly`. Создание и замена требуют всех обязательных полей. При обновлении проверяются переданные значения и итоговая запись. Отсутствующая запись — `404`, конфликт — `409`.
+
+POST возвращает созданную запись со статусом `201`; PUT, PATCH и DELETE — результат со статусом `200`. Ошибки REST имеют вид `{ "error": "Описание ошибки" }`.
+
+### Параметры REST-запросов
+
+Для запросов к записям REST принимает один параметр URL `scope` с JSON-массивом `[поля, аргументы?]`. Первый объект выбирает поля, второй задаёт `where`, `order` и `pager` для списка. Этот формат одинаков для корневого запроса, вложенных объектов и связей.
+
+Пример выбора пользователей и их фильмов с отдельной сортировкой и пагинацией:
+
+```js
+const scope = [
+  {
+    id: true,
+    fullName: true,
+    movies: [
+      { id: true, title: true },
+      { order: [{ field: 'title', direction: 'ASC' }], pager: { page: 1, pageSize: 5 } },
+    ],
+  },
+  {
+    where: { fullName: { contains: 'Мира' } },
+    order: [{ field: 'fullName', direction: 'ASC' }],
+    pager: { page: 1, pageSize: 20 },
+  },
+];
+const params = new URLSearchParams({ scope: JSON.stringify(scope) });
+const response = await fetch(`/users?${params}`);
+```
+
+Обычные поля выбираются через `true`, объекты и связи — через свой массив `scope`. Если аргументы не нужны, в массиве остаётся только объект полей. `"*": true` включает собственные поля и хранимые ключи, кроме `writeOnly`; связи выбираются явно.
+
+Например, собственные поля фильма, пользователи актёров и отсортированные жанры:
+
+```json
+[
+  {
+    "*": true,
+    "actors": [
+      {
+        "user": [{ "id": true, "fullName": true }],
+        "genres": [
+          { "*": true },
+          { "order": [{ "field": "name", "direction": "ASC" }] }
+        ]
+      }
+    ]
+  }
+]
+```
+
+Без `scope` возвращаются собственные поля, как при `[{"*":true}]`. Пустой выбор `[{}]` возвращает объект без полей. Списки сохраняют структуру `{ data, total }`.
+
+Аргументы доступны только у списков. В запросе отдельной записи и в ответе мутации их можно задать для вложенных списков. Параметры проверяются даже на пустых данных; ошибка в выборе ответа отменяет изменения записи. Некорректный `scope` возвращает `400`. Максимальная длина JSON — 10 000 символов, глубина выбора — 32 уровня.
+
+### Вложенная запись
+
+Поля ключей, например `genreIds: ["1"]`, только задают связь. В поля связей можно передавать записи для создания или обновления:
+
+```http
+PATCH /movies/1
+Content-Type: application/json
+
+{
+  "actors": [
+    {
+      "userId": "1",
+      "genres": [
+        "1",
+        { "id": "2", "name": "Обновлённый жанр" },
+        { "name": "Новый жанр" }
+      ]
+    }
+  ]
+}
+```
+
+| Значение в связи | Действие |
+|---|---|
+| Ключ, например `"1"` | Связать существующую запись без её изменения |
+| Объект с первичным ключом | PATCH обновляет переданные поля, PUT заменяет связанную запись |
+| Объект без первичного ключа | Создать запись со значениями по умолчанию и сгенерированным ключом |
+
+Имя и тип ключа берутся из целевой модели. Объект только с ключом тоже считается обновлением: в PUT он должен содержать обязательные поля модели. При замене сохраняются первичный ключ, генерируемые значения и поля `readOnly`. В POST вложенные объекты с существующими ключами обновляются частично. Если запись по ключу не найдена, операция завершится ошибкой. Для создания вложенной записи без ключа нужна его автоматическая генерация.
+
+Переданный список заменяет состав связи. PATCH сохраняет пропущенные связи, PUT очищает пропущенные связи, ключи которых доступны для записи. `[]` очищает список, `null` — одиночную связь с разрешённым `nullable`. Разрыв связи не удаляет связанную запись. Обязательные связи должны оставаться заполненными.
+
+В одном объекте указывайте либо связь, либо её хранимый ключ: например, `genres` или `genreIds`. Для обратной связи сервер меняет целевой ключ. Если путь проходит через массив и нельзя однозначно выбрать элемент для связи, передайте массив с нужными ключами явно. Защищённые ключи изменять нельзя.
+
+Все вложенные изменения входят в транзакцию основной записи. Ошибка проверки, отсутствующая запись или неверный выбор полей ответа отменяет всю операцию. Изменения общей записи видны всем, кто с ней связан.
+
+GraphQL принимает в полях связей типизированные объекты. Чтобы при замене изменить только связи, используйте поля ключей, например `genreIds`. Пример:
+
+```graphql
+mutation {
+  movieUpdate(id: "1", data: {
+    actors: [{
+      userId: "1"
+      genres: [{ id: "2", name: "Обновлённый жанр" }, { name: "Новый жанр" }]
+    }]
+  }) {
+    actors { data { genres { data { id name } } } }
+  }
+}
+```
+
+### GraphQL
+
+Укажите `database.schema` и добавьте секцию `graphql: {}` в конфигурацию:
+
+```sh
+npx deep-json-server server.config.js
+```
+
+Отправляйте запросы на `/graphql` методом POST с `Content-Type: application/json` и телом `{ "query": "…", "variables": {} }`. Путь можно изменить через `graphql.endpoint`.
+
+```graphql
+query {
+  userList(
+    where: { fullName: { contains: "Мира" } }
+    order: [{ field: fullName, direction: ASC }]
+    pager: { page: 1, pageSize: 20 }
+  ) {
+    total
+    data {
+      id
+      fullName
+      movies(
+        where: { title: { contains: "Тени" } }
+        order: [{ field: title, direction: ASC }]
+        pager: { pageSize: 5 }
+      ) {
+        total
+        data { id title }
+      }
+    }
+  }
+}
+```
+
+Запрос `user(id: ...)` возвращает одну запись или `null`, если она отсутствует. Мутации: `userCreate(data: ...)`, `userReplace(id: ..., data: ...)`, `userUpdate(id: ..., data: ...)`, `userDelete(id: ...)`. Для модели, состоящей из генерируемых полей, мутация создания вызывается без аргумента `data`. Правила записи и валидации совпадают с REST. Связи, выбранные в результате мутации, определяют содержимое ответа.
+
+Строковый первичный ключ представлен типом GraphQL `ID`, обычные строки — `String`, числа — `Float`, параметры пагинации — `Int`. Enum сохраняет допустимые строковые имена; остальные значения получают имена `VALUE_0`, `VALUE_1` и т. д. Длины строк, форматы и другие ограничения модели проверяются сервером при выполнении запроса. Для просмотра схемы доступна интроспекция. Параметры выбранных списков проверяются до выполнения мутаций.
+
+Ошибки содержат `extensions.code`: `INVALID_INPUT`, `INVALID_QUERY`, `NOT_FOUND`, `CONFLICT`, `UNAUTHENTICATED`, `FORBIDDEN` или `INTERNAL_ERROR`. Ошибки синтаксиса и типов GraphQL возвращаются в стандартном массиве `errors`. Максимальная глубина запроса — 32 уровня.
+
+## OpenAPI и экспорт схем
+
+Экспорт использует OpenAPI 3.0.3. Добавьте `openapi: {}` и `database.schema`, чтобы получать спецификацию по HTTP на `/openapi.json`. Путь меняется через `openapi.endpoint`. Спецификацию можно открыть в Swagger UI или импортировать в API-клиент.
+
+Для сохранения схем задайте пути экспорта:
+
+```js
+export default {
+  storage: 'file',
+  database: { source: './database.json', schema: './schema.json' },
+  openapi: { target: './generated/openapi.yaml' },
+  graphql: { target: './generated/schema.graphql' },
+};
+```
+
+```bash
+npx deep-json-server server.config.js --generate-only
+npx deep-json-server server.config.js --generate
+```
+
+`--generate-only` экспортирует и завершает работу, `--generate` после экспорта запускает сервер. Форматы определяются наличием секций. Для каждого выбранного формата обязателен свой `target`. Если секций нет, отсутствует `target` или генерация завершилась ошибкой, команда возвращает ошибку и сервер не запускается.
+
+Экспорт не открывает базу, учётные записи и файлы. Перед записью проверяются все выбранные `target`; они не могут совпадать с конфигурацией, базой, схемой, пользователями, счётчиками или метаданными файлов.
+
+## Аутентификация
+
+Секция `auth` включает регистрацию, вход и проверку прав на изменение записей в REST и GraphQL. Чтение и все операции с файлами остаются открытыми.
+
+Первого администратора задайте в исходных данных. Например, создайте `auth.json` с помощью `setup-auth.mjs`:
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { hashPassword } from '@kollors/deep-json-server/auth';
+
+const password = process.env.DJS_PASSWORD;
+if (!password) throw new Error('Set DJS_PASSWORD');
+await writeFile(
+  './auth.json',
+  JSON.stringify(
+    [{ id: '1', username: 'admin', passwordHash: await hashPassword(password), isAdmin: true }],
+    null,
+    2,
+  ),
+  { flag: 'wx', mode: 0o600 },
+);
+```
+
+Задайте `DJS_PASSWORD` и выполните `node setup-auth.mjs`. Добавьте файл в конфигурацию сервера:
+
+```js
+export default {
+  storage: 'file',
+  database: { source: './database.json' },
+  auth: { source: './auth.json', expiresIn: 3600 },
+};
+```
+
+Запустите `npx deep-json-server server.config.js`. Каждой исходной учётной записи нужны уникальный строковый `id`, уникальный `username` и `passwordHash`, созданный функцией выше. `isAdmin` по умолчанию равен `false`. Пароли хешируются через scrypt со случайной солью.
+
+При `storage: 'memory'` передайте массив в `auth.source`:
+
+```js
+import { hashPassword } from '@kollors/deep-json-server/auth';
+
+const password = process.env.DJS_PASSWORD;
+if (!password) throw new Error('Set DJS_PASSWORD');
+
+export default {
+  storage: 'memory',
+  database: { source: { items: [] } },
+  auth: {
+    source: [
+      { id: '1', username: 'admin', passwordHash: await hashPassword(password), isAdmin: true },
+    ],
+  },
+};
+```
+
+Учётные записи auth хранятся отдельно от базы. В файловом режиме изменения сохраняются в `auth.source`; в режиме памяти они исчезают после перезапуска. Переданный массив пользователей не изменяется. После ручного изменения файла перезапустите сервер.
+
+| REST-запрос | JSON тела | Ответ |
+|---|---|---|
+| `POST /auth/register` | `{ "username": "anna", "password": "…" }` | `201`: `{ id, username, isAdmin: false }` |
+| `POST /auth/login` | `{ "username": "anna", "password": "…" }` | `{ accessToken, expiresIn, user: { id, username, isAdmin } }` |
+| `GET /auth/me` | — | `{ id, username, isAdmin }` |
+| `POST /auth/logout` | — | `{ success: true }` |
+| `PATCH /auth/users/:id/password` | `{ "currentPassword": "…", "newPassword": "…" }` | `{ success: true }` |
+| `PATCH /auth/users/:id/admin` | `{ "isAdmin": true }` | `{ id, username, isAdmin }` |
+
+Регистрация и вход доступны без токена. Для остальных методов передавайте `Authorization: Bearer <accessToken>`. Регистрация создаёт обычного пользователя с новым `id`; поля `id`, `passwordHash` и `isAdmin` в запросе запрещены. `username` уникален с учётом регистра, повтор возвращает `409`. Имя должно содержать хотя бы один непробельный символ и не более 256 символов, пароль — от 1 до 1024 символов. Значения не обрезаются. Регистрация не открывает сессию: после неё выполните вход.
+
+Пользователь меняет только свой пароль, передавая `currentPassword` и `newPassword`. Для администратора при смене своего пароля действует то же правило. Администратор может сменить пароль обычному пользователю, передав только `newPassword`. Изменение пароля другого администратора возвращает `403`. После успешной смены завершаются все сессии этого пользователя, включая текущую при смене своего пароля; требуется новый вход. Неверный текущий пароль возвращает `401` без изменения сессий.
+
+Статус `isAdmin` меняет только администратор. Можно назначать других администраторов и снимать с них статус. Снять статус с себя можно, только если остаётся другой администратор; иначе возвращается `409`. Проверка учитывает параллельные запросы. Новые права действуют с прежними токенами сразу после сохранения, в том числе для мутаций GraphQL. Администратор может снять статус с другого администратора, а затем сменить ему пароль как обычному пользователю.
+
+Недействительный или истёкший токен возвращает `401`, недостаток прав — `403`, отсутствующий пользователь при разрешённой операции — `404`. Ошибки тела запроса возвращают `400`. Вход, регистрация и смена пароля могут вернуть `429` при превышении числа одновременных вычислений паролей; вход также ограничивает число активных сессий. Сессии хранятся в памяти и исчезают после перезапуска. Выход завершает только сессию переданного токена.
+
+OpenAPI описывает все маршруты auth и требования Bearer-токена. В Swagger UI токен из ответа на вход можно вставить в **Authorize**. Для экспорта схем включите auth в конфигурации и выполните `npx deep-json-server server.config.js --generate-only`; файл учётных записей при генерации не читается. Методы auth доступны через REST. В GraphQL тот же токен проверяется при изменении записей. Для GraphQL и OpenAPI нужна `database.schema`.
+
+## Даты записей, удаление и владельцы
+
+Общие настройки задаются в корне схемы. В этом примере модель `Note` наследует мягкое удаление и отключает даты:
+
+```json
+{
+  "timestamps": true,
+  "softDelete": true,
+  "models": {
+    "Note": {
+      "collection": "notes",
+      "timestamps": false,
+      "fields": {
+        "id": {
+          "type": "string",
+          "primary": true,
+          "generated": "uuid"
+        },
+        "text": {
+          "type": "string",
+          "required": true
+        }
+      }
+    }
+  }
+}
+```
+
+Приоритет: модель → корень схемы → `false`. Явное `false` отключает унаследованную настройку. Без схемы даты и мягкое удаление выключены.
+
+| Поле | Когда включено | Значение |
+|---|---|---|
+| `createdAt`, `updatedAt` | `timestamps` | Даты создания и последнего изменения |
+| `deletedAt` | `softDelete` | Дата удаления или `null` для активной записи |
+| `createdById`, `updatedById` | `auth` | Создатель/владелец и последний редактор |
+| `deletedById` | `auth` + `softDelete` | Пользователь, удаливший запись, или `null` |
+
+Даты — строки ISO 8601 в UTC. При создании даты создания и изменения совпадают, а при включённом auth создателем и редактором становится текущий пользователь. PUT/PATCH сохраняют создателя и дату создания. DELETE обновляет поля удаления и включённые поля последнего изменения. Для старых записей с неизвестными датами или авторами возвращается `null`. Эти поля доступны только для чтения в REST и GraphQL; обычные вложенные объекты собственных полей авторства и дат не получают. При отключении функции уже сохранённые значения её полей сохраняются.
+
+При мягком удалении DELETE оставляет запись в базе. Повторный DELETE уже удалённой записи сохраняет прежние сведения об удалении. Получение по первичному ключу возвращает и удалённые записи. Успешный PUT/PATCH восстанавливает запись, обнуляя `deletedAt` и `deletedById`. Пустой PATCH восстанавливает без замены остальных полей; для PUT нужно передать все обязательные поля.
+
+Списки по умолчанию возвращают активные записи. Для получения удалённых задайте условие по `deletedAt`:
+
+```json
+[
+  { "id": true, "deletedAt": true },
+  { "where": { "deletedAt": { "ne": null } } }
+]
+```
+
+`eq: null` выбирает активные записи, `ne: null` — удалённые, объединение обоих условий через `or` — все записи. Те же фильтры работают в GraphQL. Явное условие по `deletedAt`, в том числе внутри `and`, `or` или `not`, заменяет автоматическую фильтрацию на этом уровне. Фильтры связей и списки связей применяют правило независимо. Одиночные связи скрывают удалённые цели; запрос по первичному ключу позволяет получить их напрямую.
+
+Каскадное удаление учитывает `onDelete` и настройку `softDelete` каждой затронутой модели. Восстановление записи, начавшей каскад, возвращает записи, удалённые той же операцией, не затрагивая удалённые ранее. Физически удалённые записи восстановить нельзя. Если каскад удалил вложенный объект, восстановление возможно, пока соответствующее поле объекта не менялось после удаления. Конфликт или отсутствие обязательной связи отменяет всю операцию.
+
+Служебные сведения восстановления хранятся вместе с записями и переживают перезапуск; сохраняйте их при резервном копировании базы. Внутреннее поле `djsDeletion` зарезервировано и не выдаётся через API.
+
+При включённом auth создавать записи может любой вошедший пользователь. Изменять, удалять и восстанавливать — владелец по `createdById` или пользователь с `isAdmin: true`. Записи без владельца изменяет только администратор. Его правки не меняют владельца. Правила действуют на вложенные записи, изменение ключей связей, каскады и восстановление. Ссылка на существующую запись без её изменения не требует владения ею. Каждая мутация атомарна: отказ сохраняет прежнее состояние всех затронутых записей.
+
+REST возвращает 401 при отсутствии действительного токена и 403 при недостатке прав. GraphQL проверяет мутации по тем же правилам и возвращает коды `UNAUTHENTICATED` или `FORBIDDEN`; токен получают через REST-вход и передают в `Authorization: Bearer <токен>`. GraphQL-запросы чтения, OPTIONS и все операции с файлами остаются открытыми.
+
 ## Файлы
 
-Добавьте `files.directory` и `files.metadata` в конфиг сервера, затем передайте `--files`, чтобы включить загрузку бинарных файлов:
+Файлы доступны через REST и описываются в OpenAPI. Добавьте хранилище в конфигурацию:
+
+```js
+export default {
+  storage: 'file',
+  database: { source: './database.json' },
+  files: { source: './uploads' },
+};
+```
+
+Запустите сервер:
 
 ```bash
-deep-json-server --files server.config.js
+npx deep-json-server server.config.js
 ```
 
-Для временных тестов вместо этого используйте `files.data`. Каждая начальная запись содержит `name`, `mimeType`, бинарное `content` в виде `Uint8Array` и необязательный `directory`. Загруженные файлы в таком режиме остаются в памяти до завершения процесса.
+Для временных тестов выберите `storage: 'memory'` и передайте массив в `files.source`. Каждая начальная запись содержит `name`, `mimeType`, бинарное `content` в виде `Uint8Array` и необязательный `directory`. Загруженные файлы в таком режиме остаются в памяти до завершения процесса.
 
 Один файл отправляется непосредственно в теле запроса. `Content-Name` содержит URI-кодированное имя файла, `Content-Type` — его MIME-тип, а необязательный `Content-Directory` — URI-кодированный относительный путь к директории:
 
@@ -418,39 +741,61 @@ Content-Type: application/json
 }
 ```
 
-`PATCH` возвращает обновлённые метаданные со статусом `200`; если по новому пути уже существует файл, сервер возвращает `409`. `DELETE` отвечает статусом `204` без тела. Если файл не найден, любая операция по пути возвращает `404`. Пути в URL задаются относительно `files.directory`, а все возвращаемые URL — относительно адреса сервера.
+`PATCH` возвращает обновлённые метаданные со статусом `200`; если по новому пути уже существует файл, сервер возвращает `409`. `DELETE` отвечает статусом `204` без тела. Если файл не найден, любая операция по пути возвращает `404`. Пути в URL задаются относительно `files.source`, а все возвращаемые URL — относительно адреса сервера.
+
+При хранении на диске бинарный файл находится по пути `<files.source>/<directory>/<name>`. Метаданные по умолчанию хранятся в `<files.source>/.files.json`; другой путь можно задать через `files.metadata`. Директории и файл метаданных создаются по мере необходимости.
 
-При хранении на диске бинарный файл находится по пути `<files.directory>/<directory>/<name>`. Файл метаданных содержит только `directory`, `mimeType` и `name`; `size` считывается у фактического файла, а URL вычисляются. Используйте дисковую базу и файловое хранилище только из одного процесса сервера одновременно и не редактируйте сохранённые файлы или метаданные до его остановки. Сервер автоматически создаёт директории, пути внутри `files.directory` не могут содержать символические ссылки, а имена файлов ограничены переносимыми между поддерживаемыми операционными системами значениями. Изначально файл метаданных может отсутствовать: он создаётся при первой загрузке. Метаданные, созданные версиями до перехода на адресацию по пути, несовместимы с новым форматом.
+Используйте один процесс сервера для дисковой базы и файлового хранилища. Перед ручным изменением файлов или метаданных остановите его. Пути в хранилище не могут содержать символические ссылки. Загрузка и переименование не могут перезаписать базу, счётчики, схему, учётные записи auth, загруженную конфигурацию или файл метаданных.
 
-Используется бинарное тело запроса, а не `multipart/form-data`, поэтому `XMLHttpRequest.upload.onprogress` может показывать прогресс при непосредственной отправке `File` через `xhr.send(file)`. Максимальный размер по умолчанию равен 100 МиБ и настраивается через `server.maxFileSize`. Отсутствующие или небезопасные заголовки и пути возвращают `400`, превышение лимита — `413`, а отсутствующий, некорректный или не поддерживаемый Fastify `Content-Type` — `400` либо `415` в зависимости от этапа проверки.
+Отправляйте файл как бинарное тело запроса. В браузере для этого можно использовать `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 { createServer } from '@kollors/deep-json-server/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();
 ```
 
-Аксессоры ленивые: экспорт не открывает порт и не инициализирует дисковое файловое хранилище. Возможности сервера можно переопределить через `createServer(config, { files: false, graphql: true })`.
+Методы `openapi()` и `graphql()` возвращают схемы и требуют `database.schema`. `fastify()` возвращает экземпляр сервера для настройки и запуска. База и включённые сервисы инициализируются при `ready()`, `listen()` или первом `inject()`; ошибка инициализации останавливает запуск.
 
-## Хранение и разработка
+`createServer(config)` принимает один аргумент. Наличие секций управляет модулями так же, как при запуске через CLI. Для методов `openapi()` и `graphql()` нужна соответствующая секция. Методы возвращают схему и не записывают файлы.
 
-Изменения выполняются последовательно внутри экземпляра сервера и проверяются на копии данных до сохранения. Для одного файла базы используйте один пишущий сервер. Счётчики increment хранятся рядом с базой в `<путь базы>.counters.json`; сохраняйте этот файл вместе с базой. Номера резервируются до записи данных: сбой может оставить пропуск, но не приводит к повторной выдаче номера. UUID создаётся встроенным crypto Node.js.
+Эти функции доступны и через общий импорт `@kollors/deep-json-server`. Адаптеры сервера загружаются при включении. Генераторы можно использовать отдельно:
 
-Это сервер для имитации API: авторизации и хеширования паролей нет. Файловые маршруты сохраняют отдельное хранилище и собственную валидацию.
+```js
+import { generateOpenapi, writeOpenapi } from '@kollors/deep-json-server/openapi';
+import { generateGraphql, writeGraphql } from '@kollors/deep-json-server/graphql';
+
+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');
+```
+
+Отдельные генераторы принимают путь или объект схемы и не требуют конфигурации сервера. Выбранная функция задаёт формат по умолчанию; `api` в схеме и моделях может его ограничить. `timestamps` и `softDelete` берутся из схемы. Опция `{ auth: true }` добавляет поля владельца; OpenAPI также описывает маршруты auth и требования токена. `hashPassword()` доступна и через общий импорт пакета.
+
+`generateOpenapi()` также принимает `host`, `port`, `pageSize`, `maxPageSize` и `info`. Вместо пути можно передать объект схемы. Сервер и генераторы работают с собственной копией модели. Размеры страниц должны быть положительными целыми числами; `pageSize` не может превышать `maxPageSize`.
+
+## Хранение данных
+
+Изменения выполняются последовательно внутри экземпляра сервера и проверяются на копии данных до сохранения. Для одного файла базы используйте один процесс сервера. Счётчики `increment` хранятся рядом с базой в `<путь базы>.counters.json`; сохраняйте этот файл вместе с базой. Номера резервируются до записи данных: сбой может оставить пропуск, но не приводит к повторной выдаче номера.
+
+## Разработка
+
+Исходники разделены на `rest`, `graphql`, `openapi`, `auth`, `files`, `cli` и `server`. Общая модель, хранение, запросы и правила изменения записей находятся в `core`. Модуль `server` подключает остальные; генераторы схем загружаются независимо от HTTP-сервера.
 
 ```sh
 npm ci
 npm run verify
 ```
 
-Проверка включает типы, линтер, пороги покрытия и установку упакованного пакета. Новая alpha-версия package.json в main создаёт свой тег и публикуется через GitHub Actions trusted publishing в канал npm alpha. Если тег уже существует, автоматическая публикация пропускается. Явная отправка тега версии также запускает публикацию; стабильные версии используют latest. Скрипт проверяет совпадение Git-тега и версии пакета.
+Команда проверяет типы, стиль кода, покрытие тестами и установку пакета из архива.
+
+Для публикации новой альфы обновите версию в `package.json`, `package-lock.json` и `src/core/constants.ts`, затем отправьте изменения в `main`. GitHub Actions создаст тег версии и опубликует пакет в канал npm `alpha` через trusted publishing. Уже опубликованная версия пропускается. Если тег создан, а публикация не завершилась, повторный запуск использует этот тег и проверяет соответствие ему файлов пакета. Отправка тега версии также запускает публикацию; стабильные версии публикуются в `latest`.
 
 Лицензия: MIT.