@kollors/deep-json-server 1.0.0-rc.6 → 1.0.0-rc.8

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.0.0-rc.8
+
+- Persist hashed auth sessions with users in file storage so valid tokens survive restarts, with atomic logout and password-change revocation.
+- Replace the lock directory with one readable `<source-name>-lock.json` file and native OS locking. Lock the database, auth store, upload root and file metadata; recover after crashes and reject competing writers.
+- Protect configured files and their symlink targets from upload, deletion and schema export. Reject malformed Unicode file paths before changing storage.
+- Preserve protected nested fields when a nullable ancestor is cleared, and infer relations across numeric seed IDs and generated string IDs.
+- Use `key` for the primary-key argument of GraphQL update/replace mutations when the primary field is named `data`.
+- Bound REST and GraphQL selection, expansion, query work and response size; document that GraphQL result errors do not undo committed mutations.
+- Derive the CLI version from package metadata and verify the installed CLI over HTTP, including paths with spaces and Unicode and persistence after a crash.
+- Run type checks, lint, coverage and installed-package checks on Linux, Windows and macOS with Node.js 22, 24 and 26. Publish only after the full matrix succeeds for the selected commit.
+
+When upgrading from an earlier RC, stop all old server processes before starting RC8: the lock protocol has changed. Existing auth files without `sessions` remain valid. Regenerate GraphQL clients if a model uses `data` as its primary field.
+
+## 1.0.0-rc.7
+
+- Treat nested objects containing only a primary key as references in POST, PUT and PATCH, preserving the target's fields and audit values. Actual changes, including inverse key changes, still require ownership.
+- Allow key-only references in GraphQL replace inputs and OpenAPI request schemas; validate required fields when a nested object creates or changes a record.
+- Infer array storage keys for `keyOn: "current"` list relations targeting non-primary fields, preserving explicitly declared key types.
+- Expand the migration guide from 0.9.0 in English and Russian, document API defaults, and remove the archive flag from examples.
+
 ## 1.0.0-rc.6
 
 - Require both sides of every explicit model relation and `keyOn: "current" | "related"` to identify where its key is stored.

package/MIGRATION.md

@@ -1,49 +1,211 @@
-# Migrating from 0.9.0 to 1.0.0-rc.6
+# Migrating from 0.9.0 to 1.0.0-rc.8
 
-Version 1.0 changes configuration and request syntax. Update the server configuration and client requests together. Back up any file database, auth records, and file metadata before changing the running server.
+[Русский](MIGRATION.ru.md) · [Current README](README.md)
 
-## Configuration
+This guide compares `v0.9.0` with `1.0.0-rc.8` and also covers the relation changes since RC6. Update configuration and clients together. Node.js 22 or newer is still required. Back up the database, config, schema, uploaded files and metadata before migrating.
 
-Declare a storage mode and use `source` for each enabled component:
+## 1. Choose whether you need a schema
 
-| 0.9.0 | 1.0.0-rc.6 |
+For REST without schema validation or exports, the smallest configuration change is:
+
+```js
+// 0.9.0
+export default { database: { path: './database.json' } };
+```
+
+```js
+// 1.0.0-rc.8
+export default { storage: 'file', database: { source: './database.json' } };
+```
+
+This keeps schemaless REST and relations inferred from stored `...Id` / `...Ids` names. The query and response changes below still apply. OpenAPI and GraphQL now require an explicit model schema; generators no longer infer field definitions from database records.
+
+## 2. Convert configuration
+
+| 0.9.0 | 1.0.0-rc.8 |
 |---|---|
-| `database.path` | `storage: 'file'`, `database.source` |
-| `database.data` | `storage: 'memory'`, `database.source` |
-| `files.directory` | `files.source` in file mode |
-| `files.data` | `files.source` in memory mode |
+| `database.path` | `storage: 'file'` and `database.source` |
+| `database.data` | `storage: 'memory'` and `database.source` |
+| `database.schema` with `$info` / `$schema` | Same config key, new schema format with `models` |
+| `files.directory` / `files.data` | `files.source` |
+| `files.metadata` | Keep the existing path to preserve file metadata |
 | `openapi.path` | `openapi.target` |
+| Schema `$info` | `package.source`: `name`, `version`, optional `description` |
+| Default `server.maxPageSize: 1000` | Default `100`; set `1000` explicitly to retain the old limit |
+
+`storage` is required and applies to every source, including the schema and package metadata. File mode requires paths; memory mode requires objects/arrays. Mixed file and memory components are no longer supported. Export `target` values remain file paths in either mode.
+
+A file-based configuration that exports OpenAPI becomes:
+
+```js
+export default {
+  storage: 'file',
+  database: { source: './database.json', schema: './schema.json' },
+  files: { source: './files', metadata: './files/_database.json' },
+  openapi: { target: './generated/openapi.yaml' },
+  package: { source: './package.json' },
+  server: { maxPageSize: 1000 },
+};
+```
+
+Create `schema.json` as described below. `package.source` is required when `openapi` is configured: package `name` becomes OpenAPI `info.title`, with `version` and optional `description`. Other old `$info` properties have no configuration equivalent. In memory mode, use `package: { source: { name: 'example-api', version: '1.0.0' } }`.
+
+Keep an existing `files.metadata` path explicitly. Omitting it selects `<files.source>/.files.json`, which does not import an old `_database.json`. The metadata format from 0.9.0 and the `/_files/*` routes remain compatible; raw upload headers and `DELETE` returning `204` also remain unchanged.
+
+Relative paths still resolve from the config directory in the CLI, and from the working directory in `createServer(config)`.
+
+## 3. Replace schema overrides with complete models
+
+In 0.9.0, `$schema` supplemented field types inferred from data. It was not the current model/relation format. Each collection now needs a model with `collection`, `fields`, and exactly one top-level primary key of type `string` or `number`.
+
+| Old override | New definition |
+|---|---|
+| `$schema.users.name` | Model name under `models`, for example `User` |
+| `$schema.users.required: ['fullName']` | `fields.fullName.required: true` |
+| `$schema.users.formats.bornAt: 'date'` | `fields.bornAt: { type: 'string', format: 'date' }` |
+| Recursive `properties` and `items` | Typed fields, `[]` for arrays, dotted paths for children |
+| Inferred generated string `id` | Explicit `{ type: 'string', primary: true, generated: 'uuid' }` |
+
+Define every stored field, not just former overrides. For example, declare `actors` as `object[]` and `actors.fullName` as `string`. Additional fields and collections are rejected with an explicit schema, except inferred relation storage keys. Existing records are validated when the HTTP server initializes.
+
+There is no general replacement for mixed-type `oneOf` fields or an `integer`-only field constraint. Normalize those fields to a supported type before adopting the schema, or keep schemaless REST. Model names must be identifiers; old custom component names containing dots or hyphens must change.
+
+### Complete example with a paired relation
+
+For existing users containing `id`, `fullName`, and `countryId`, and countries containing `id` and `name`:
+
+```json
+{
+  "api": ["rest"],
+  "models": {
+    "User": {
+      "collection": "users",
+      "fields": {
+        "id": { "type": "string", "primary": true, "generated": "uuid" },
+        "fullName": { "type": "string", "required": true },
+        "countryId": { "type": "string" },
+        "country": { "type": "Country", "keyOn": "current" }
+      }
+    },
+    "Country": {
+      "collection": "countries",
+      "fields": {
+        "id": { "type": "string", "primary": true, "generated": "uuid" },
+        "name": { "type": "string", "required": true },
+        "users": { "type": "User[]", "keyOn": "related" }
+      }
+    }
+  }
+}
+```
+
+Every explicit relation needs both declarations and a `keyOn` value. `current` stores the foreign key; `related` reads that key in the other model. No second copy of the key or stored `users` array is needed.
 
-The `storage` mode applies to the database, schema, auth records, files, and package metadata. GraphQL and OpenAPI require a model schema; OpenAPI also requires `package.source`. The schema format has changed: define models under `models`, with a `collection`, fields, and one primary key per model. Use root `api` to enable REST, GraphQL, or both for the database; a model's optional `api` array can narrow that choice. Start with the [current schema example](examples/schema.json), then validate your existing records against it. The [configuration example](examples/server.config.js) shows all required paths.
+- Direct `target` defaults to the related model's primary key. Direct `source` uses the relation field name and target key: `country` → `countryId`, `publishers` → `publisherIds`. A custom primary key `ref` produces `publisherRefs`.
+- Inverse paths swap the direct paths. For `Country.users`, `source` is `id` and `target` is `countryId`.
+- Self-relations pair `Genre.parents: { type: 'Genre[]', keyOn: 'current' }` with `Genre.children: { type: 'Genre[]', keyOn: 'related' }`; both use stored `Genre.parentIds`.
+- Multiple relations between the same models require disambiguation: inverse `Country.birthUsers` uses `target: 'birthCountryId'`, and `Country.residenceUsers` uses `target: 'residenceCountryId'`. Ambiguous or missing pairs fail schema loading.
+- Declare existing keys explicitly, as above, if clients read, filter, sort or write them. Inferred keys remain in storage but are hidden from both APIs and OpenAPI, even when selected by name.
+- RC7 also infers source arrays for lists targeting **non-primary** fields. For example, `publishers` with `keyOn: 'current'` and `target: 'code'` infers `publisherCodes: { type: 'string[]' }` when `Publisher.code` is a string. Explicitly declare the key if it must be exposed in the API. If RC6 stored this automatically inferred key as a scalar, convert existing values to arrays, for example `"A"` to `["A"]`, before upgrading. An explicitly declared scalar key retains its type.
 
-## Relation declarations
+Repair dangling direct references before startup. Writes now validate references; deleting a referenced target is restricted by default. Choose `onDelete: 'cascade'` deliberately where deleting a target should delete referring records. An inverse with no explicit `onDelete` does not add its own restriction.
 
-Current schemas require each explicit relation in both models and `keyOn` on each relation field. Use `current` where the stored key lives and `related` on the inverse. For example, `User.country = {"type":"Country","keyOn":"current"}` pairs with `Country.users = {"type":"User[]","keyOn":"related"}`. The server infers `User.countryId` referencing the primary key of `Country`, even if `countryId` is omitted from `fields`; existing records still keep their stored keys.
+### Preserve IDs and custom fields
 
-Previously, a relation could be declared on only one side, and `source` defaulted to the current model's primary key. Add the inverse declaration and review any relation that relied on that default. A list such as `Genre.parents` now infers `parentIds` from the relation name, while `Genre.children` with `keyOn: "related"` reads the same key. Keep explicit `source` or `target` for custom key paths. If multiple relations connect the same two models, specify the inverse `target` to pair each one unambiguously. Missing or ambiguous pairs now fail during schema loading.
+Do not regenerate IDs while converting the schema. Existing string IDs remain valid with `generated: 'uuid'`; only new values use UUIDs. If a collection mixes numeric and string IDs, normalize them and all referencing keys to one type before enabling an explicit schema.
 
-Omitting a `related` inverse field from `PUT` leaves its links unchanged, because their keys are stored in other records. Supply the inverse field explicitly when replacing those links, for example `"users": []` to detach all users from a country.
+`generated` is not implied by `primary`. Without it, clients must supply the primary key on create. With it, clients must omit generated fields; sending them is rejected instead of ignored as in 0.9.0.
 
-## CLI
+Old application fields must be declared or deliberately removed from copied data. A custom archive flag does not automatically become soft deletion. Enabling lifecycle or auth features reserves their system field names, so rename conflicting application fields first.
 
-Adding a `files`, `graphql`, or `openapi` section enables that feature. The old `--files`, `--openapi`, and `--openapi-only` flags are gone. Use `--generate` to export configured schemas and start the server, or `--generate-only` to export and exit. Each exported format needs a `target` path.
+## 4. Select APIs and update startup commands
 
-## REST queries
+If root `api` is omitted, the server uses `['rest']`, or `['rest', 'graphql']` when `graphql` is configured. To expose the database only through GraphQL, set `api: ['graphql']` and add `graphql: {}`. A model inherits root `api` or narrows it; model `api: []` hides that model. Root `api: []` is invalid. Related models must enable the same APIs.
 
-REST now accepts a JSON `scope` query parameter. Replace `_where`, `_sort`, `_page`, `_perPage`, `_embed`, and simple field filters with `scope`. For example:
+The `graphql` section and root GraphQL flag must be enabled together. Auth and files remain REST services and appear only in OpenAPI. OpenAPI can describe these services on a GraphQL-only database server.
+
+| Old CLI | New CLI |
+|---|---|
+| `--files` | Remove the flag; the `files` section enables routes |
+| `--openapi` | `--generate` |
+| `--openapi-only` | `--generate-only` |
+
+Unlike the old CLI, normal startup now enables configured file routes. Remove `files` if they should be disabled. `openapi: {}` serves `/openapi.json`; `graphql: {}` serves `/graphql`. To export files, set a `target` for **each** configured format; generation flags export all configured formats. Normal startup does not write exports.
+
+## 5. Migrate REST queries and response readers
+
+The only record query parameter is now URL-encoded JSON `scope: [fields, arguments?]`.
+
+| 0.9.0 parameter | New scope entry |
+|---|---|
+| `_where` or simple `fullName:contains=mi` | Second object: `where: { fullName: { contains: 'mi' } }` |
+| `_sort=-id,fullName` | `order: [{ field: 'id', direction: 'DESC' }, { field: 'fullName', direction: 'ASC' }]` |
+| `_page=1&_perPage=10` | `pager: { page: 1, pageSize: 10 }` |
+| `_embed=country` | First object: `country: [{ id: true, name: true }]` |
+
+Example against the paired schema above:
 
 ```js
 const scope = [
-  { id: true, title: true, publishers: [{ id: true, name: true }] },
-  { where: { title: { contains: 'Ardenia' } }, order: [{ field: 'title', direction: 'ASC' }], pager: { page: 1, pageSize: 10 } },
+  { id: true, fullName: true, countryId: true, country: [{ id: true, name: true }] },
+  {
+    where: { fullName: { contains: 'mi' } },
+    order: [{ field: 'fullName', direction: 'ASC' }],
+    pager: { page: 1, pageSize: 10 },
+  },
 ];
-const url = `/movies?${new URLSearchParams({ scope: JSON.stringify(scope) })}`;
+const url = `/users?${new URLSearchParams({ scope: JSON.stringify(scope) })}`;
 ```
 
-Without an explicit `scope`, the response contains scalar fields only. `"*": true` also selects only scalar fields that do not store relation keys. Select arrays, objects, relations, and declared relation keys explicitly. Relation keys omitted from `fields` remain in the database but are unavailable in REST, GraphQL, and OpenAPI. Related lists can have their own filters, order, and pagination. Review clients that expect embedded relations or relation keys in default responses.
+Update response readers as well:
+
+- Missing `scope` and `{ '*': true }` select only scalars that do not store relation keys. Arrays, objects, relations and declared storage keys need explicit selection. `writeOnly` fields cannot be selected.
+- Collections still return `{ data, total }`. Embedded **object and relation lists now also return `{ data, total }`**, rather than plain arrays. Primitive arrays remain arrays. A single relation returns an object or `null`.
+- Every object list is paginated, including nested lists: default page size `10`, maximum `100`. Embedded lists were previously returned in full. Give each list the necessary `pager` and load further pages when needed.
+- Relation filters work without selecting that relation. Sorting the parent by a related field, such as old `_sort=country.name`, is not supported; sort the related list with its own `order`, or store a sortable value on the parent.
+- String comparisons `gt/gte/lt/lte` now use case-insensitive, numeric-aware ordering. Review clients relying on the old lexical comparisons.
+- Scope JSON is limited to 10,000 characters and 32 selection levels. Unknown fields/operators are rejected even on empty data.
+
+## 6. Check write behavior and optional auth
+
+`PATCH` merges top-level fields; a supplied nested plain object replaces that object while preserving protected fields. `PUT` replaces writable fields, preserving primary, generated, read-only and system values. Required fields must be supplied for creation/replacement unless they have defaults.
+
+Relation values are objects, for example `country: { id: '1' }`, not scalar IDs. **Starting with RC7, an object containing only the primary key is a reference in POST, PUT and PATCH.** It preserves the target's fields, dates and author values. Adding other fields invokes an update: PUT replaces the target and requires its mandatory fields; POST/PATCH update supplied fields. Changing an inverse relation still requires permission for every record whose stored key changes. Declared storage keys, such as `countryId`, can also change links directly. Do not send the relation and its storage key in the same object.
+
+**When upgrading from RC6:** key-only objects no longer update the target, change its audit values or require ownership of an unchanged target. If an existing client intends to update or replace the target, include the fields to change. Declared storage keys remain available for link-only writes.
+
+Omitted inverse (`keyOn: 'related'`) relations survive PUT. Explicit `users: []` changes users' foreign keys to detach them; it can fail if those keys are required or the caller lacks permission. Nested changes are atomic, and modifying a shared target affects every record referring to it.
+
+Auth, timestamps and soft deletion are new, optional features. To first preserve unauthenticated writes and physical deletion, omit `auth` and leave `timestamps` / `softDelete` disabled (their defaults).
+
+If enabling auth, create a separate auth user store and migrate ownership deliberately. Old records without `createdById` can be changed only by administrators. The ownership field is server-managed through the API; prepare ownership in the copied database before startup if ordinary users must edit existing records. Auth does not close read endpoints or file operations. In RC8, file storage persists hashed sessions in the auth user file and restores unexpired sessions after a restart. Existing users without `sessions` remain valid. When manually changing a password hash, also clear that user's `sessions`.
+
+With `softDelete`, DELETE retains records, lists hide deleted records by default, direct primary-key reads can retrieve them, and successful PUT/PATCH restores them. There is no automatic conversion of an old application archive flag. See the [lifecycle rules](README.md#record-dates-deletion-and-ownership) before enabling this feature.
+
+## 7. Update programmatic consumers
+
+`createServer(config)` now takes exactly one argument. Remove the old second `{ files: false }` argument and omit `files` from the config to disable the feature.
+
+`facade.openapi()` and `facade.graphql()` return documents without writing `target`. They require their respective config sections; OpenAPI also needs package metadata and a schema. Use CLI generation flags or explicit writers:
+
+```js
+import { createServer } from '@kollors/deep-json-server';
+import { writeOpenapi } from '@kollors/deep-json-server/openapi';
+import config from './server.config.js';
+
+const facade = await createServer(config);
+await writeOpenapi(await facade.openapi(), './generated/openapi.yaml');
+const app = facade.fastify();
+await app.ready(); // Initializes and validates the database without opening a port.
+await app.close();
+```
 
-## Records and auth
+Schema generation alone does not validate existing database records. Call `ready()`, `inject()` or `listen()` to initialize HTTP and check data. Regenerate clients from the new OpenAPI/GraphQL documents after changing models and queries.
 
-Explicit models validate fields and relations more strictly than the 0.9 schemaless server. Existing records with undeclared fields or dangling direct relation keys may fail validation at startup or on write. Test the migrated database before replacing the production file.
+## 8. Validate the cutover and keep rollback data
 
-Authentication is optional and enabled by an `auth` section. When enabled, creating records requires login; changing existing records requires ownership or administrator access. Record timestamps and soft deletion are configured in the model schema. The [README](README.md) describes the current behavior and API endpoints.
+1. Pin the chosen RC version and migrate a **copy** of the 0.9.0 files. Run generation, then initialize the HTTP server to validate data too.
+2. Check representative reads: defaults, explicit foreign keys, nested lists, filters and pagination. Check create, PATCH, PUT, link changes and deletion using disposable copied records.
+3. If enabling auth, test an owner, an administrator and an ordinary non-owner against old records. Confirm uploaded files remain accessible through the retained metadata path.
+4. Stop every old server process before switching: RC8 replaces the old lock directory with native OS locks and readable `<source-name>-lock.json` files for the database, auth, upload root and file metadata. Old and new lock protocols do not coordinate. Run one process per writable store and stop it before manual edits.
+5. Keep the original package version, config, schema, data and file metadata together for rollback. Restore them together; do not point 0.9.0 at data already modified by the new server. Include new increment counters (`<database>.counters.json`) and soft-delete restoration metadata in subsequent backups when used.

package/MIGRATION.ru.md

@@ -0,0 +1,211 @@
+# Переход с 0.9.0 на 1.0.0-rc.8
+
+[English](MIGRATION.md) · [Актуальный README](README.ru.md)
+
+Руководство сравнивает релиз `v0.9.0` с `1.0.0-rc.8` и также описывает изменения связей после RC6. Конфигурацию и клиентов нужно обновлять вместе. Требование Node.js 22 или новее сохраняется. Перед переходом скопируйте базу, конфигурацию, схему, загруженные файлы и их метаданные.
+
+## 1. Выберите режим со схемой или без неё
+
+Для REST без проверки по схеме и без генерации достаточно начать с такой замены:
+
+```js
+// 0.9.0
+export default { database: { path: './database.json' } };
+```
+
+```js
+// 1.0.0-rc.8
+export default { storage: 'file', database: { source: './database.json' } };
+```
+
+REST без схемы и связи по именам хранимых полей `...Id` / `...Ids` сохраняются. Описанные ниже изменения запросов и ответов действуют и в этом режиме. Для OpenAPI и GraphQL теперь нужна явная схема моделей: генераторы больше не определяют поля по содержимому базы.
+
+## 2. Обновите конфигурацию
+
+| В 0.9.0 | В 1.0.0-rc.8 |
+|---|---|
+| `database.path` | `storage: 'file'` и `database.source` |
+| `database.data` | `storage: 'memory'` и `database.source` |
+| `database.schema` с `$info` / `$schema` | То же поле конфигурации, новый формат схемы с `models` |
+| `files.directory` / `files.data` | `files.source` |
+| `files.metadata` | Сохраните прежний путь к метаданным файлов |
+| `openapi.path` | `openapi.target` |
+| `$info` в схеме | `package.source`: `name`, `version`, необязательный `description` |
+| `server.maxPageSize` по умолчанию `1000` | Теперь `100`; для прежнего ограничения задайте `1000` явно |
+
+Обязательный `storage` действует на все источники, включая схему и метаданные пакета. В режиме `file` нужны пути, в `memory` — объекты и массивы. Смешивать дисковые источники и данные в памяти больше нельзя. Пути экспорта `target` остаются путями к файлам в обоих режимах.
+
+Пример конфигурации с дисковой базой и экспортом OpenAPI:
+
+```js
+export default {
+  storage: 'file',
+  database: { source: './database.json', schema: './schema.json' },
+  files: { source: './files', metadata: './files/_database.json' },
+  openapi: { target: './generated/openapi.yaml' },
+  package: { source: './package.json' },
+  server: { maxPageSize: 1000 },
+};
+```
+
+Создайте `schema.json` по следующему разделу. При настроенном `openapi` обязателен `package.source`: `name` пакета становится `info.title`, также используются `version` и необязательный `description`. Остальные свойства старого `$info` не имеют аналога в конфигурации. В памяти передавайте `package: { source: { name: 'example-api', version: '1.0.0' } }`.
+
+**Сохраните прежний `files.metadata` явно.** Без него сервер выберет `<files.source>/.files.json` и не импортирует старый `_database.json`. Формат метаданных из 0.9.0 и маршруты `/_files/*` совместимы; заголовки загрузки бинарного тела и ответ `204` на удаление файла сохраняются.
+
+Относительные пути по-прежнему отсчитываются от каталога конфигурации в CLI и от рабочего каталога при прямом вызове `createServer(config)`.
+
+## 3. Замените дополнения к схеме полными моделями
+
+В 0.9.0 `$schema` дополнял поля, определённые по данным. Это ещё не был нынешний формат моделей и связей. Теперь каждой коллекции нужна модель с `collection`, `fields` и одним первичным ключом верхнего уровня типа `string` или `number`.
+
+| Старое описание | Новое описание |
+|---|---|
+| `$schema.users.name` | Имя модели в `models`, например `User` |
+| `$schema.users.required: ['fullName']` | `fields.fullName.required: true` |
+| `$schema.users.formats.bornAt: 'date'` | `fields.bornAt: { type: 'string', format: 'date' }` |
+| Вложенные `properties` и `items` | Поля с типами, `[]` для массивов, пути через точку для дочерних полей |
+| Автоматический строковый `id` | Явный `{ type: 'string', primary: true, generated: 'uuid' }` |
+
+Опишите все хранимые поля, а не только прежние дополнения. Например, `actors` получает тип `object[]`, а `actors.fullName` — `string`. При явной схеме неизвестные поля и коллекции запрещены; исключение — автоматически выведенные ключи связей. Существующие записи проверяются при инициализации HTTP-сервера.
+
+У полей со смешанными типами `oneOf` и ограничения «только целые числа» через `integer` нет общего прямого аналога. Приведите данные к поддерживаемому типу или оставьте REST без схемы. Имена моделей должны быть идентификаторами: старые имена компонентов с точками и дефисами нужно заменить.
+
+### Полный пример с двусторонней связью
+
+Для пользователей с полями `id`, `fullName`, `countryId` и стран с `id`, `name`:
+
+```json
+{
+  "api": ["rest"],
+  "models": {
+    "User": {
+      "collection": "users",
+      "fields": {
+        "id": { "type": "string", "primary": true, "generated": "uuid" },
+        "fullName": { "type": "string", "required": true },
+        "countryId": { "type": "string" },
+        "country": { "type": "Country", "keyOn": "current" }
+      }
+    },
+    "Country": {
+      "collection": "countries",
+      "fields": {
+        "id": { "type": "string", "primary": true, "generated": "uuid" },
+        "name": { "type": "string", "required": true },
+        "users": { "type": "User[]", "keyOn": "related" }
+      }
+    }
+  }
+}
+```
+
+Каждая явная связь описывается с обеих сторон, везде обязателен `keyOn`. Сторона `current` хранит внешний ключ; `related` использует этот ключ в другой модели. Второй экземпляр ключа или хранимый массив `users` не нужен.
+
+- У прямой связи `target` по умолчанию равен первичному ключу целевой модели. `source` выводится из имени поля связи и целевого ключа: `country` → `countryId`, `publishers` → `publisherIds`. При первичном ключе `ref` получится `publisherRefs`.
+- У обратной связи пути меняются местами: для `Country.users` это `source: 'id'` и `target: 'countryId'`.
+- Связь модели с собой: `Genre.parents: { type: 'Genre[]', keyOn: 'current' }` и `Genre.children: { type: 'Genre[]', keyOn: 'related' }` используют один хранимый массив `Genre.parentIds`.
+- Если между моделями несколько связей, укажите, какие поля образуют пары: у обратной `Country.birthUsers` задайте `target: 'birthCountryId'`, у `Country.residenceUsers` — `target: 'residenceCountryId'`. Неоднозначные и отсутствующие пары отклоняются при загрузке.
+- Объявляйте существующие ключи в `fields`, как в примере, если клиент их читает, фильтрует, сортирует или записывает. Автоматически выведенные ключи остаются в базе, но скрыты из обоих API и OpenAPI; выбрать их даже по имени нельзя.
+- RC7 выводит массив источника и для списка с **непервичным** целевым полем. Например, `publishers` с `keyOn: 'current'` и `target: 'code'` получает `publisherCodes: { type: 'string[]' }`, если `Publisher.code` — строка. Объявите ключ явно, если его нужно открыть в API. Если RC6 сохранил такой автоматически выведенный ключ скаляром, перед обновлением преобразуйте значения в массивы, например `"A"` в `["A"]`. Явно объявленный скалярный ключ сохраняет свой тип.
+
+До запуска исправьте ссылки на отсутствующие записи. Теперь запись проверяет целостность связей, а удаление целевой записи по умолчанию запрещено, пока на неё ссылаются. Задавайте `onDelete: 'cascade'` только там, где удаление цели должно удалять ссылающиеся записи. Обратная связь без явно указанного `onDelete` не добавляет собственного запрета.
+
+### Сохраните идентификаторы и пользовательские поля
+
+Не генерируйте идентификаторы заново. Старые строковые ID допустимы с `generated: 'uuid'`; UUID получают только новые значения. Если в коллекции есть и числа, и строки в качестве ID, перед подключением явной схемы приведите их и все ссылки к одному типу.
+
+`primary` не включает `generated` автоматически. Без `generated` клиент сам передаёт ключ при создании. С `generated` клиент должен пропускать генерируемые поля: теперь их передача отклоняется, а не игнорируется, как в 0.9.0.
+
+Старые поля приложения нужно объявить или осознанно удалить из копии базы. Пользовательский флаг архивирования не превращается в мягкое удаление автоматически. При включении дат, мягкого удаления или auth соответствующие служебные имена резервируются; переименуйте конфликтующие поля приложения заранее.
+
+## 4. Выберите API и обновите команды запуска
+
+Без корневого `api` сервер использует `['rest']`, а с секцией `graphql` — `['rest', 'graphql']`. Для доступа к базе только через GraphQL задайте `api: ['graphql']` и добавьте `graphql: {}`. Модель наследует корневой выбор или сужает его; `api: []` у модели скрывает её. Корневой `api: []` недопустим. Связанные модели должны разрешать одинаковые API.
+
+Секцию `graphql` и GraphQL в корневом `api` нужно включать вместе. Auth и файлы остаются REST-сервисами и описываются только в OpenAPI. OpenAPI может описывать их и при базе, доступной только через GraphQL.
+
+| Старый флаг CLI | Замена |
+|---|---|
+| `--files` | Уберите флаг: маршруты включает секция `files` |
+| `--openapi` | `--generate` |
+| `--openapi-only` | `--generate-only` |
+
+В отличие от старого CLI, обычный запуск теперь включает настроенные файловые маршруты. Чтобы отключить их, уберите `files`. `openapi: {}` публикует `/openapi.json`, `graphql: {}` — `/graphql`. Для экспорта задайте `target` **каждому** настроенному формату: флаги генерации экспортируют все настроенные форматы. Обычный запуск файлы экспорта не записывает.
+
+## 5. Переведите запросы и обработку ответов на scope
+
+Единственный параметр запроса к записям — JSON `scope: [fields, arguments?]`, закодированный для URL.
+
+| Параметр 0.9.0 | Запись в scope |
+|---|---|
+| `_where` или `fullName:contains=mi` | Второй объект: `where: { fullName: { contains: 'mi' } }` |
+| `_sort=-id,fullName` | `order: [{ field: 'id', direction: 'DESC' }, { field: 'fullName', direction: 'ASC' }]` |
+| `_page=1&_perPage=10` | `pager: { page: 1, pageSize: 10 }` |
+| `_embed=country` | Первый объект: `country: [{ id: true, name: true }]` |
+
+Пример для схемы выше:
+
+```js
+const scope = [
+  { id: true, fullName: true, countryId: true, country: [{ id: true, name: true }] },
+  {
+    where: { fullName: { contains: 'mi' } },
+    order: [{ field: 'fullName', direction: 'ASC' }],
+    pager: { page: 1, pageSize: 10 },
+  },
+];
+const url = `/users?${new URLSearchParams({ scope: JSON.stringify(scope) })}`;
+```
+
+Обновите и чтение ответов:
+
+- Без `scope` и с `{ '*': true }` выбираются только скаляры, не хранящие ключи связей. Массивы, объекты, связи и объявленные ключи нужно выбирать явно. Поля `writeOnly` выбрать нельзя.
+- Коллекции сохраняют `{ data, total }`. **Вложенные списки объектов и связей теперь тоже имеют `{ data, total }`**, а не обычный массив. Массивы примитивов остаются массивами. Одиночная связь возвращает объект или `null`.
+- У каждого списка объектов есть пагинация, в том числе у вложенного: размер страницы по умолчанию `10`, максимум `100`. Раньше вложенные связи возвращались целиком. Задайте нужный `pager` каждому списку и загружайте следующие страницы.
+- Фильтрация по связи работает без её выбора в ответе. Сортировка родительских записей по связанной модели, как старый `_sort=country.name`, не поддерживается. Сортируйте связанный список его собственным `order` либо храните сортируемое значение в родительской записи.
+- Строковые сравнения `gt/gte/lt/lte` используют порядок без учёта регистра, с учётом числовых частей. Проверьте клиентов, полагавшихся на прежнее лексикографическое сравнение.
+- JSON scope ограничен 10 000 символов и 32 уровнями выбора. Неизвестные поля и операторы отклоняются даже на пустых данных.
+
+## 6. Проверьте запись и включение auth
+
+`PATCH` объединяет поля верхнего уровня; переданный вложенный обычный объект заменяет прежний с сохранением защищённых полей. `PUT` заменяет доступные для записи поля, сохраняя первичный ключ, генерируемые, служебные и `readOnly` значения. При создании и замене нужны все обязательные поля без значений по умолчанию.
+
+Поле связи принимает объекты, например `country: { id: '1' }`, а не скалярные ID. **Начиная с RC7 объект только с первичным ключом считается ссылкой в POST, PUT и PATCH.** Поля, даты и авторство целевой записи сохраняются. Дополнительные поля превращают его в обновление: PUT заменяет цель и требует её обязательные поля, POST/PATCH обновляют переданные поля. При изменении обратной связи нужны права на каждую запись, чей хранимый ключ меняется. Объявленные хранимые ключи, например `countryId`, тоже позволяют менять ссылки напрямую. Не передавайте одновременно связь и её хранимый ключ.
+
+**При переходе с RC6:** объект только с ключом больше не обновляет цель, не меняет её даты/авторство и не требует владения неизменяемой целевой записью. Если клиент намерен обновить или заменить цель, передавайте поля для изменения. Объявленные хранимые ключи по-прежнему позволяют менять только ссылки.
+
+Пропущенные обратные связи (`keyOn: 'related'`) сохраняются при PUT. Явное `users: []` меняет ключи пользователей, чтобы отсоединить их; операция может завершиться ошибкой при обязательных ключах или отсутствии прав. Вложенные изменения атомарны, а изменение общей целевой записи видно всем, кто на неё ссылается.
+
+Auth, даты и мягкое удаление — новые необязательные возможности. Для первого перехода с сохранением записи без входа и физического удаления не добавляйте `auth`, оставьте `timestamps` / `softDelete` выключенными — это их значения по умолчанию.
+
+Если включаете auth, создайте отдельное хранилище учётных записей и перенесите владельцев осознанно. Старые записи без `createdById` может менять только администратор. Через API владелец управляется сервером; подготовьте его в копии базы до запуска, если старые записи должны редактировать обычные пользователи. Auth не закрывает чтение и файловые операции. В RC8 дисковый режим сохраняет хеши сессий в файле пользователей и восстанавливает действующие сессии после перезапуска. Старые пользователи без `sessions` остаются допустимыми. При ручной замене хеша пароля также очистите `sessions` этого пользователя.
+
+При `softDelete` DELETE сохраняет запись, списки по умолчанию скрывают удалённые записи, чтение по первичному ключу может вернуть их, а успешный PUT/PATCH восстанавливает. Старый пользовательский флаг архивирования не преобразуется автоматически. Перед включением прочитайте [правила дат, удаления и владения](README.ru.md#даты-записей-удаление-и-владельцы).
+
+## 7. Обновите программное использование
+
+`createServer(config)` принимает ровно один аргумент. Уберите прежний второй аргумент `{ files: false }`; для отключения файлов уберите `files` из конфигурации.
+
+`facade.openapi()` и `facade.graphql()` возвращают документы без записи в `target`. Нужны соответствующие секции конфигурации; для OpenAPI — также метаданные пакета и схема. Используйте флаги генерации CLI или явную запись:
+
+```js
+import { createServer } from '@kollors/deep-json-server';
+import { writeOpenapi } from '@kollors/deep-json-server/openapi';
+import config from './server.config.js';
+
+const facade = await createServer(config);
+await writeOpenapi(await facade.openapi(), './generated/openapi.yaml');
+const app = facade.fastify();
+await app.ready(); // Инициализация и проверка базы без открытия порта.
+await app.close();
+```
+
+Одна генерация схем не проверяет существующие записи базы. Для инициализации HTTP и проверки данных вызовите `ready()`, `inject()` или `listen()`. После изменения моделей и запросов пересоздайте клиентов из новых OpenAPI/GraphQL-документов.
+
+## 8. Проверьте переход и подготовьте откат
+
+1. Зафиксируйте выбранную RC-версию и переведите **копию** файлов 0.9.0. Выполните генерацию, затем инициализацию HTTP-сервера для проверки данных.
+2. Проверьте чтение по умолчанию, явные ключи, вложенные списки, фильтры и пагинацию. На одноразовых копиях записей проверьте создание, PATCH, PUT, изменение связей и удаление.
+3. При включении auth проверьте владельца, администратора и обычного пользователя без владения на старых записях. Убедитесь, что загруженные файлы доступны через прежний путь к метаданным.
+4. Перед переключением остановите все старые процессы сервера: RC8 заменяет каталог блокировки системными блокировками и читаемыми файлами `<имя-источника>-lock.json` для базы, auth, каталога загрузок и метаданных файлов. Старый и новый протоколы блокировки не взаимодействуют. Используйте один процесс на записываемое хранилище и останавливайте его перед ручными правками.
+5. Для отката храните вместе старую версию пакета, конфигурацию, схему, базу и метаданные файлов. Восстанавливайте их вместе; не направляйте 0.9.0 на данные, уже изменённые новым сервером. В последующие резервные копии включайте новые счётчики (`<database>.counters.json`) и служебные данные восстановления мягкого удаления, если используете эти функции.