@kollors/deep-json-server 1.0.0-alpha.5 → 1.0.0-alpha.7

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.5 — предварительная версия.** REST-запросы используют `scope=[поля, аргументы?]` на всех уровнях. При обновлении измените параметры запросов по примерам ниже; для перехода с 0.x также нужна новая схема моделей.
+**1.0.0-alpha.7 — предварительная версия.** REST-запросы используют `scope=[поля, аргументы?]` на всех уровнях. При обновлении измените параметры запросов по примерам ниже; для перехода с 0.x также нужна новая схема моделей.
 
 ## Установка
 
@@ -12,7 +12,7 @@ JSON-сервер для имитации API: REST, GraphQL, вложенные
 npm install @kollors/deep-json-server@alpha
 ```
 
-Для установки конкретной версии укажите `@1.0.0-alpha.5`.
+Для установки конкретной версии укажите `@1.0.0-alpha.7`.
 
 ## Быстрый старт
 
@@ -42,12 +42,16 @@ npx deep-json-server server.config.js
 
 Список пользователей доступен по адресу `http://127.0.0.1:4001/users`.
 
+Для связей и валидации добавьте [схему моделей](#схема-моделей). Далее описаны [запросы](#запросы-и-ответы), [аутентификация](#аутентификация), [мягкое удаление](#даты-записей-удаление-и-владельцы), [файлы](#файлы) и [программный API](#программный-api).
+
 ## Конфигурация
 
 | Ключ | Назначение |
 |---|---|
-| `database.path` / `database.data` | Ровно один: JSON-файл или объект коллекций в памяти |
+| `database.path` / `database.data` | Для запуска укажите один вариант: JSON-файл или объект коллекций в памяти |
 | `database.schema` | Объект моделей или путь к JSON-файлу; необязателен для REST |
+| `database.timestamps` | Добавить даты создания и изменения; по умолчанию `false` |
+| `database.softDelete` | Сохранять удалённые записи с возможностью восстановления; по умолчанию `false` |
 | `openapi.enabled` | Включить HTTP-маршрут спецификации; по умолчанию `false` |
 | `openapi.endpoint` | Путь спецификации; по умолчанию `/openapi.json` |
 | `openapi.path` | Путь экспорта YAML |
@@ -55,6 +59,8 @@ npx deep-json-server server.config.js
 | `graphql.enabled` | Включить GraphQL HTTP API; по умолчанию `false` |
 | `graphql.endpoint` | Путь GraphQL; по умолчанию `/graphql` |
 | `graphql.path` | Путь экспорта GraphQL SDL |
+| `auth.users` | Путь к JSON-массиву учётных записей или массив в памяти |
+| `auth.expiresIn` | Срок действия сессии в секундах; по умолчанию 3600 |
 | `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 |
@@ -66,9 +72,13 @@ npx deep-json-server server.config.js
 
 Значение `server.port: 0` позволяет системе выбрать свободный порт. OpenAPI на HTTP-эндпоинте использует относительный адрес сервера.
 
+### CLI
+
 | Флаг CLI | Действие |
 |---|---|
-| `--files` | Включить файловые маршруты |
+| `--files` | Включить файловые маршруты; нужна секция `files` |
+| `--timestamps` | Включить даты записей глобально |
+| `--soft-delete` | Включить мягкое удаление глобально |
 | `--graphql` | Включить GraphQL API |
 | `--openapi` | Включить HTTP-маршрут OpenAPI |
 | `--host <host>` | Адрес сервера |
@@ -76,27 +86,7 @@ npx deep-json-server server.config.js
 | `--help`, `-h` | Справка |
 | `--version`, `-v` | Версия пакета |
 
-Приоритет настроек: CLI → конфигурация → `HOST`/`PORT` → значения по умолчанию. Файловые маршруты включаются при наличии секции `files`.
-
-Для генерации укажите формат и файл конфигурации:
-
-```sh
-npx deep-json-server generate openapi server.config.js
-npx deep-json-server generate graphql server.config.js
-npx deep-json-server generate openapi,graphql server.config.js
-```
-
-Команда читает `database.schema` и сохраняет схемы в `openapi.path` и `graphql.path`. Для генерации достаточно такой конфигурации:
-
-```js
-export default {
-  database: { schema: './schema.json' },
-  openapi: { path: './generated/openapi.yaml' },
-  graphql: { path: './generated/schema.graphql' },
-};
-```
-
-Для каждого формата нужен отдельный файл. Команда отклонит путь, который перезапишет конфигурацию, базу, схему или метаданные файлов.
+Приоритет адреса и порта: CLI → конфигурация → `HOST`/`PORT` → значения по умолчанию. Файловые маршруты включаются при наличии секции `files`, а вход и проверка прав — при наличии `auth`. Настройки модели могут переопределять глобальные `timestamps` и `softDelete`.
 
 ## Схема моделей
 
@@ -138,6 +128,8 @@ export default {
 
 REST без схемы создаёт ключ `id` и сохраняет произвольные JSON-поля. Для фильтров и выбора отдельных полей используются имена в формате идентификаторов; остальные поля возвращаются через `scope=[{"*":true}]`. Поля с разными типами значений можно читать, но фильтрация, сортировка и пагинация неоднородных списков требуют явной схемы.
 
+У модели обязательны `collection` — имя коллекции в базе и REST-пути — и `fields` — описание полей. Имя модели (`User`) задаёт имена типов и операций GraphQL. `api` управляет доступностью форматов, а `timestamps` и `softDelete` переопределяют глобальные настройки для этой модели.
+
 ### Поля
 
 Поле `type` принимает `string`, `number`, `boolean`, `object` или имя модели. Для массива добавьте суффикс `[]`: `string[]`, `object[]`, `Genre[]`. Вложенные поля описываются через точку, например `actors.fullName`.
@@ -168,10 +160,12 @@ REST без схемы создаёт ключ `id` и сохраняет про
 ### Связи
 
 ```json
-"actors.genres": {
-  "type": "Genre[]",
-  "source": "actors.genreIds",
-  "required": true
+{
+  "actors.genres": {
+    "type": "Genre[]",
+    "source": "actors.genreIds",
+    "required": true
+  }
 }
 ```
 
@@ -192,6 +186,12 @@ REST без схемы создаёт ключ `id` и сохраняет про
 
 ## Запросы и ответы
 
+Примеры с фильмами, актёрами и жанрами используют полную [схему из examples](examples/schema.json). Для их запуска используйте [конфигурацию примера](examples/server.config.js):
+
+```sh
+npx deep-json-server examples/server.config.js
+```
+
 Коллекции и списки объектов, включая вложенные `object[]`, возвращают:
 
 ```json
@@ -202,7 +202,7 @@ REST без схемы создаёт ключ `id` и сохраняет про
 
 В `pager` задаются `page` и `pageSize`. По умолчанию возвращается первая страница с размером из `server.pageSize`. Оба значения должны быть положительными целыми числами; `pageSize` ограничен `server.maxPageSize`. За пределами списка возвращается пустой `data` с общим числом найденных записей в `total`.
 
-Фильтры: `eq`, `ne`, `in`; для строк `contains`, `startsWith`, `endsWith`; сравнения `gt`, `gte`, `lt`, `lte`. Условия объединяются через `and`, `or`, `not`. У массивов есть `some`, `every`, `none`; у примитивных массивов также `contains`, `in`. Поиск строк не учитывает регистр. Условие поля задаётся объектом с оператором, например `{ "id": { "eq": "1" } }`.
+Фильтры: `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
 {
@@ -220,10 +220,12 @@ REST без схемы создаёт ключ `id` и сохраняет про
 
 Корневой `where` выбирает записи основной коллекции. `where` внутри связи фильтрует её элементы, сохраняя родительскую запись. Каждый вложенный список обрабатывается отдельно. Фильтрация по связи работает независимо от её включения в ответ.
 
-`order` — массив правил `{ "field": "fullName", "direction": "ASC" }`. Первое правило приоритетнее; при равных значениях сохраняется порядок хранения. `null` и отсутствующее значение сравниваются одинаково. REST использует путь `profile.name`, GraphQL — enum `profile_name`. Неоднозначные имена enum вызывают ошибку генерации. Сортировка доступна по скалярным полям текущего объекта, включая вложенные поля. Для связанных списков задаётся собственный `order`.
+`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` |
@@ -233,62 +235,13 @@ REST без схемы создаёт ключ `id` и сохраняет про
 | PATCH | `/users/{id}` | `userUpdate` |
 | DELETE | `/users/{id}` | `userDelete` |
 
-Имя параметра пути соответствует первичному ключу. POST, PUT и PATCH принимают JSON-объект записи. PUT заменяет запись с сохранением ключа и серверных полей. PATCH объединяет поля на верхнем уровне; переданные вложенные объекты заменяются с сохранением их полей `readOnly`. Создание и замена требуют всех обязательных полей. При обновлении проверяются переданные значения и итоговая запись. Отсутствующая запись — `404`, конфликт — `409`. DELETE возвращает удалённую запись.
-
-### Вложенная запись
-
-Поля ключей, например `genreIds: ["1"]`, только задают связь. В поля связей можно передавать записи для создания или обновления:
-
-```http
-PATCH /movies/1
-Content-Type: application/json
-
-{
-  "actors": [
-    {
-      "userId": "1",
-      "genres": [
-        "1",
-        { "id": "2", "name": "Обновлённый жанр" },
-        { "name": "Новый жанр" }
-      ]
-    }
-  ]
-}
-```
-
-| Значение в связи | Действие |
-|---|---|
-| Ключ, например `"1"` | Связать существующую запись без её изменения |
-| Объект с первичным ключом | PATCH обновляет переданные поля, PUT заменяет связанную запись |
-| Объект без первичного ключа | Создать запись со значениями по умолчанию и сгенерированным ключом |
+Имя параметра пути соответствует первичному ключу. POST, PUT и PATCH принимают JSON-объект записи. PUT заменяет запись с сохранением ключа и серверных полей. PATCH объединяет поля на верхнем уровне; переданные вложенные объекты заменяются с сохранением их полей `readOnly`. Создание и замена требуют всех обязательных полей. При обновлении проверяются переданные значения и итоговая запись. Отсутствующая запись — `404`, конфликт — `409`.
 
-Имя и тип ключа берутся из целевой модели. Объект только с ключом тоже считается обновлением: в 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 } } } }
-  }
-}
-```
+POST возвращает созданную запись со статусом `201`; PUT, PATCH и DELETE — результат со статусом `200`. Ошибки REST имеют вид `{ "error": "Описание ошибки" }`.
 
 ### Параметры REST-запросов
 
-REST принимает один query-параметр `scope` с JSON-массивом `[поля, аргументы?]`. Первый объект выбирает поля, второй задаёт `where`, `order` и `pager` для списка. Этот формат одинаков для корневого запроса, вложенных объектов и связей.
+Для запросов к записям REST принимает один параметр URL `scope` с JSON-массивом `[поля, аргументы?]`. Первый объект выбирает поля, второй задаёт `where`, `order` и `pager` для списка. Этот формат одинаков для корневого запроса, вложенных объектов и связей.
 
 Пример выбора пользователей и их фильмов с отдельной сортировкой и пагинацией:
 
@@ -340,13 +293,71 @@ const response = await fetch(`/users?${params}`);
 
 Аргументы доступны только у списков. В запросе отдельной записи и в ответе мутации их можно задать для вложенных списков. Параметры проверяются даже на пустых данных; ошибка в выборе ответа отменяет изменения записи. Некорректный `scope` возвращает `400`. Максимальная длина JSON — 10 000 символов, глубина выбора — 32 уровня.
 
-OpenAPI остаётся версии 3.0.3. В этой версии нельзя задать отдельную схему для каждой позиции массива: назначение элементов описано в документации, а их порядок строго проверяет сервер.
+### Вложенная запись
+
+Поля ключей, например `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.enabled: true` в конфигурации или запустите сервер с `--graphql`:
+
+```sh
+npx deep-json-server --graphql 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 }
   ) {
@@ -354,7 +365,11 @@ query {
     data {
       id
       fullName
-      movies(order: [{ field: title, direction: ASC }], pager: { pageSize: 5 }) {
+      movies(
+        where: { title: { contains: "Тени" } }
+        order: [{ field: title, direction: ASC }]
+        pager: { pageSize: 5 }
+      ) {
         total
         data { id title }
       }
@@ -365,7 +380,243 @@ query {
 
 Запрос `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` или `INTERNAL_ERROR`.
+Строковый первичный ключ представлен типом 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. Для `scope` назначение позиций массива описано текстом; их порядок проверяет сервер.
+
+Для получения спецификации по HTTP укажите `database.schema` и включите `openapi.enabled: true` или запустите сервер с `--openapi`. По умолчанию JSON доступен по адресу `/openapi.json`; путь задаётся в `openapi.endpoint`. Спецификацию можно открыть в отдельно установленном Swagger UI или импортировать в API-клиент.
+
+Для генерации укажите формат и файл конфигурации:
+
+```sh
+npx deep-json-server generate openapi server.config.js
+npx deep-json-server generate graphql server.config.js
+npx deep-json-server generate openapi,graphql server.config.js
+```
+
+Генерация выполняется без запуска сервера и чтения записей базы. Команда читает `database.schema` и сохраняет схемы в `openapi.path` и `graphql.path`. Флаги `enabled` управляют HTTP-маршрутами и для экспорта не требуются. Для генерации достаточно такой конфигурации:
+
+```js
+export default {
+  database: { schema: './schema.json' },
+  openapi: { path: './generated/openapi.yaml' },
+  graphql: { path: './generated/schema.graphql' },
+};
+```
+
+Для каждого формата нужен отдельный файл. Команда отклонит путь, который перезапишет конфигурацию, базу, схему, учётные записи auth или метаданные файлов.
+
+## Аутентификация
+
+Секция `auth` включает REST-вход и проверку прав на изменение записей в REST и GraphQL. Чтение и все операции с файлами остаются открытыми.
+
+Создайте учётную запись в отдельном файле с помощью `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 {
+  database: { path: './database.json' },
+  auth: { users: './auth.json', expiresIn: 3600 },
+};
+```
+
+Запустите `npx deep-json-server server.config.js`. Наличие секции `auth` включает модуль; без неё изменения записей доступны без токена. Каждой учётной записи нужны уникальный строковый `id`, уникальный `username` и `passwordHash`, созданный функцией выше. `isAdmin` по умолчанию равен `false`. Пароли хешируются через scrypt со случайной солью. Учётные записи auth хранятся отдельно от коллекций базы. Файл читается при запуске; после его изменения перезапустите сервер.
+
+| REST-запрос | Входные данные | Ответ |
+|---|---|---|
+| `POST /auth/login` | JSON `{ "username": "admin", "password": "…" }` | `{ accessToken, expiresIn, user: { id, username, isAdmin } }` |
+| `GET /auth/me` | Bearer-токен | `{ id, username, isAdmin }` |
+| `POST /auth/logout` | Bearer-токен | `{ success: true }` |
+
+Передавайте токен в заголовке `Authorization: Bearer <accessToken>`. Неверные учётные данные, недействительный или истёкший токен возвращают HTTP 401. Сессии хранятся в памяти и исчезают при перезапуске; выход отзывает переданный токен. Вход может вернуть HTTP 429 при слишком большом числе одновременных попыток или активных сессий.
+
+В OpenAPI описывается Bearer-аутентификация для изменения записей, `/auth/me` и `/auth/logout`. В Swagger UI токен из ответа на вход можно вставить в **Authorize**. Для экспорта схем включите auth в конфигурации и выполните `generate openapi server.config.js`; файл учётных записей при генерации не читается. Для GraphQL и OpenAPI нужна `database.schema`.
+
+## Даты записей, удаление и владельцы
+
+Глобальные настройки задаются в `database`:
+
+```js
+export default {
+  database: {
+    path: './database.json',
+    schema: './schema.json',
+    timestamps: true,
+    softDelete: true,
+  },
+  auth: { users: './auth.json' },
+};
+```
+
+В модели можно переопределить `timestamps` и `softDelete` рядом с `collection` и `fields`. Отсутствующее значение наследуется из глобальных настроек; `true` или `false` переопределяет его. CLI имеет приоритет над глобальным конфигом, а настройки модели — над обоими. Без схемы глобальные значения действуют на все коллекции. Например, эта модель отключает даты и сохраняет удалённые записи независимо от глобальных настроек:
+
+```json
+{
+  "Note": {
+    "collection": "notes",
+    "timestamps": false,
+    "softDelete": true,
+    "fields": {
+      "id": { "type": "string", "primary": true, "generated": "uuid" },
+      "text": { "type": "string", "required": true }
+    }
+  }
+}
+```
+
+| Поле | Когда включено | Значение |
+|---|---|---|
+| `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 и все операции с файлами остаются открытыми.
+
+## Файлы
+
+Файлы доступны через REST и описываются в OpenAPI. Добавьте хранилище в конфигурацию:
+
+```js
+export default {
+  database: { path: './database.json' },
+  files: { directory: './uploads', metadata: './files.json' },
+};
+```
+
+Запустите сервер:
+
+```bash
+npx deep-json-server server.config.js
+```
+
+Для временных тестов вместо этого используйте `files.data`. Каждая начальная запись содержит `name`, `mimeType`, бинарное `content` в виде `Uint8Array` и необязательный `directory`. Загруженные файлы в таком режиме остаются в памяти до завершения процесса.
+
+Один файл отправляется непосредственно в теле запроса. `Content-Name` содержит URI-кодированное имя файла, `Content-Type` — его MIME-тип, а необязательный `Content-Directory` — URI-кодированный относительный путь к директории:
+
+```http
+POST /_files/storage
+Content-Name: shadows-of-ardenia.jpg
+Content-Directory: posters
+Content-Type: image/jpeg
+
+<binary body>
+```
+
+Новый файл возвращает статус `201` и вычисленные метаданные:
+
+```json
+{
+  "directory": "posters",
+  "downloadUrl": "/_files/download/posters/shadows-of-ardenia.jpg",
+  "metadataUrl": "/_files/metadata/posters/shadows-of-ardenia.jpg",
+  "mimeType": "image/jpeg",
+  "name": "shadows-of-ardenia.jpg",
+  "size": 182340,
+  "url": "/_files/storage/posters/shadows-of-ardenia.jpg"
+}
+```
+
+Сочетание `directory` и `name` идентифицирует файл. Повторная загрузка по существующему пути возвращает `409`. Чтобы заменить файл, передайте `Content-Override: true`; успешная перезапись возвращает `200`. Сервер поддерживает следующие файловые маршруты:
+
+```text
+POST   /_files/storage      Загрузка или перезапись файла
+GET    /_files/storage/*    Просмотр содержимого файла
+PATCH  /_files/storage/*    Переименование или перемещение файла
+DELETE /_files/storage/*    Удаление файла
+
+GET    /_files/metadata/*   Получение метаданных в JSON
+GET    /_files/download/*   Скачивание файла
+```
+
+Для переименования, перемещения либо обеих операций отправьте JSON-объект. Нужно указать хотя бы одно поле:
+
+```http
+PATCH /_files/storage/posters/shadows-of-ardenia.jpg
+Content-Type: application/json
+
+{
+  "directory": "archive/posters",
+  "name": "ardenia-shadows.jpg"
+}
+```
+
+`PATCH` возвращает обновлённые метаданные со статусом `200`; если по новому пути уже существует файл, сервер возвращает `409`. `DELETE` отвечает статусом `204` без тела. Если файл не найден, любая операция по пути возвращает `404`. Пути в URL задаются относительно `files.directory`, а все возвращаемые URL — относительно адреса сервера.
+
+При хранении на диске бинарный файл находится по пути `<files.directory>/<directory>/<name>`. Метаданные содержат `directory`, `mimeType` и `name`; размер сервер читает из файла, а URL формирует сам. Директории и файл метаданных создаются по мере необходимости.
+
+Используйте один процесс сервера для дисковой базы и файлового хранилища. Перед ручным изменением файлов или метаданных остановите его. Пути в хранилище не могут содержать символические ссылки. Загрузка и переименование не могут перезаписать базу, счётчики, схему, учётные записи auth, загруженную конфигурацию или файл метаданных.
+
+Отправляйте файл как бинарное тело запроса. В браузере для этого можно использовать `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/server';
+import config from './server.config.js';
+
+const facade = await createServer(config);
+const server = facade.fastify();
+await server.listen();
+// await server.close();
+```
+
+Методы `openapi()` и `graphql()` возвращают схемы и требуют `database.schema`. `fastify()` возвращает экземпляр сервера для настройки и запуска. База и включённые сервисы инициализируются при `ready()`, `listen()` или первом `inject()`; ошибка инициализации останавливает запуск.
+
+Второй аргумент переопределяет подключение модулей, например `createServer(config, { files: false, graphql: true })`. Допустимы флаги `files`, `graphql`, `openapi` и `auth`. Для включения auth или файлов нужна соответствующая секция конфигурации; для GraphQL и OpenAPI — схема моделей.
+
+Эти функции доступны и через общий импорт `@kollors/deep-json-server`. Адаптеры сервера загружаются при включении. Генераторы можно использовать отдельно:
+
+```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');
+```
+
+Оба генератора принимают `timestamps`, `softDelete` и `auth` для описания полей записей. При `{ auth: true }` OpenAPI также добавляет REST-маршруты auth и требования токена для изменения записей. Функция `hashPassword()` доступна и через общий импорт пакета.
+
+`generateOpenapi()` также принимает `host`, `port`, `pageSize`, `maxPageSize` и `info`. Вместо пути можно передать объект схемы. Сервер и генераторы работают с собственной копией модели. Размеры страниц должны быть положительными целыми числами; `pageSize` не может превышать `maxPageSize`.
 
 ## Пример базы данных
 
@@ -471,106 +722,13 @@ query {
 }
 ```
 
-## Файлы
-
-Добавьте `files.directory` и `files.metadata` в конфигурацию и запустите сервер:
-
-```bash
-deep-json-server server.config.js
-```
-
-Для временных тестов вместо этого используйте `files.data`. Каждая начальная запись содержит `name`, `mimeType`, бинарное `content` в виде `Uint8Array` и необязательный `directory`. Загруженные файлы в таком режиме остаются в памяти до завершения процесса.
-
-Один файл отправляется непосредственно в теле запроса. `Content-Name` содержит URI-кодированное имя файла, `Content-Type` — его MIME-тип, а необязательный `Content-Directory` — URI-кодированный относительный путь к директории:
-
-```http
-POST /_files/storage
-Content-Name: shadows-of-ardenia.jpg
-Content-Directory: posters
-Content-Type: image/jpeg
-
-<binary body>
-```
-
-Новый файл возвращает статус `201` и вычисленные метаданные:
-
-```json
-{
-  "directory": "posters",
-  "downloadUrl": "/_files/download/posters/shadows-of-ardenia.jpg",
-  "metadataUrl": "/_files/metadata/posters/shadows-of-ardenia.jpg",
-  "mimeType": "image/jpeg",
-  "name": "shadows-of-ardenia.jpg",
-  "size": 182340,
-  "url": "/_files/storage/posters/shadows-of-ardenia.jpg"
-}
-```
-
-Сочетание `directory` и `name` идентифицирует файл. Повторная загрузка по существующему пути возвращает `409`. Чтобы заменить файл, передайте `Content-Override: true`; успешная перезапись возвращает `200`. Сервер поддерживает следующие файловые маршруты:
-
-```text
-POST   /_files/storage      Загрузка или перезапись файла
-GET    /_files/storage/*    Просмотр содержимого файла
-PATCH  /_files/storage/*    Переименование или перемещение файла
-DELETE /_files/storage/*    Удаление файла
-
-GET    /_files/metadata/*   Получение метаданных в JSON
-GET    /_files/download/*   Скачивание файла
-```
-
-Для переименования, перемещения либо обеих операций отправьте JSON-объект. Нужно указать хотя бы одно поле:
-
-```http
-PATCH /_files/storage/posters/shadows-of-ardenia.jpg
-Content-Type: application/json
-
-{
-  "directory": "archive/posters",
-  "name": "ardenia-shadows.jpg"
-}
-```
-
-`PATCH` возвращает обновлённые метаданные со статусом `200`; если по новому пути уже существует файл, сервер возвращает `409`. `DELETE` отвечает статусом `204` без тела. Если файл не найден, любая операция по пути возвращает `404`. Пути в URL задаются относительно `files.directory`, а все возвращаемые URL — относительно адреса сервера.
-
-При хранении на диске бинарный файл находится по пути `<files.directory>/<directory>/<name>`. Метаданные содержат `directory`, `mimeType` и `name`; размер сервер читает из файла, а URL формирует сам. Директории и файл метаданных создаются по мере необходимости.
-
-Используйте один процесс сервера для дисковой базы и файлового хранилища. Перед ручным изменением файлов или метаданных остановите его. Пути в хранилище не могут содержать символические ссылки. Загрузка и переименование не могут перезаписать базу, счётчики, схему, загруженную конфигурацию или файл метаданных.
-
-Отправляйте файл как бинарное тело запроса. В браузере для этого можно использовать `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/server';
-import config from './server.config.js';
-
-const facade = await createServer(config);
-const server = facade.fastify();
-await server.listen();
-// await server.close();
-```
-
-Методы `openapi()` и `graphql()` возвращают схемы и требуют `database.schema`. `fastify()` возвращает экземпляр сервера для настройки и запуска. База и включённые сервисы инициализируются при `ready()`, `listen()` или первом `inject()`; ошибка инициализации останавливает запуск. Возможности сервера можно переопределить через `createServer(config, { files: false, graphql: true, openapi: true })`.
-
-Эти функции доступны и через общий импорт `@kollors/deep-json-server`. Адаптеры сервера загружаются при включении. Генераторы можно использовать отдельно:
-
-```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');
-```
-
-`generateOpenapi()` также принимает `host`, `port`, `pageSize`, `maxPageSize` и `info`. Вместо пути можно передать объект схемы. Сервер и генераторы работают с собственной копией модели. Размеры страниц должны быть положительными целыми числами; `pageSize` не может превышать `maxPageSize`.
-
-## Хранение и разработка
+## Хранение данных
 
 Изменения выполняются последовательно внутри экземпляра сервера и проверяются на копии данных до сохранения. Для одного файла базы используйте один процесс сервера. Счётчики `increment` хранятся рядом с базой в `<путь базы>.counters.json`; сохраняйте этот файл вместе с базой. Номера резервируются до записи данных: сбой может оставить пропуск, но не приводит к повторной выдаче номера.
 
-Сервер предназначен для имитации API. Авторизацию и хеширование паролей при необходимости реализуйте в приложении.
+## Разработка
+
+Исходники разделены на `rest`, `graphql`, `openapi`, `auth`, `files`, `cli` и `server`. Общая модель, хранение, запросы и правила изменения записей находятся в `core`. Модуль `server` подключает остальные; генераторы схем загружаются независимо от HTTP-сервера.
 
 ```sh
 npm ci
@@ -579,6 +737,6 @@ npm run verify
 
 Команда проверяет типы, стиль кода, покрытие тестами и установку пакета из архива.
 
-Для публикации новой альфы обновите версию в `package.json`, `package-lock.json` и `src/constants.ts`, затем отправьте изменения в `main`. GitHub Actions создаст тег версии и опубликует пакет в канал npm `alpha` через trusted publishing. Уже опубликованная версия пропускается. Если тег создан, а публикация не завершилась, повторный запуск использует этот тег и проверяет соответствие ему файлов пакета. Отправка тега версии также запускает публикацию; стабильные версии публикуются в `latest`.
+Для публикации новой альфы обновите версию в `package.json`, `package-lock.json` и `src/core/constants.ts`, затем отправьте изменения в `main`. GitHub Actions создаст тег версии и опубликует пакет в канал npm `alpha` через trusted publishing. Уже опубликованная версия пропускается. Если тег создан, а публикация не завершилась, повторный запуск использует этот тег и проверяет соответствие ему файлов пакета. Отправка тега версии также запускает публикацию; стабильные версии публикуются в `latest`.
 
 Лицензия: MIT.