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

package/README.md

@@ -14,7 +14,7 @@ A JSON mock server with REST, GraphQL, related records, file uploads and schema
 npm install @kollors/deep-json-server@rc
 ```
 
-To install this release candidate, use `@1.0.0-rc.5`.
+To install this release candidate, use `@1.0.0-rc.7`.
 
 ## Quick start
 
@@ -151,7 +151,7 @@ Examples: [database](examples/database.json), [model schema](examples/schema.jso
         },
         "users": {
           "type": "User[]",
-          "target": "countryId"
+          "keyOn": "related"
         }
       }
     },
@@ -169,7 +169,7 @@ Examples: [database](examples/database.json), [model schema](examples/schema.jso
         },
         "country": {
           "type": "Country",
-          "source": "countryId"
+          "keyOn": "current"
         }
       }
     }
@@ -177,7 +177,20 @@ Examples: [database](examples/database.json), [model schema](examples/schema.jso
 }
 ```
 
-Model definitions belong in `models`. The schema root accepts `models`, `api`, `timestamps` and `softDelete`. Root `api` selects database routes. When omitted, it defaults to REST and also GraphQL if the server config has a `graphql` section. A model can override the global timestamp and soft-deletion settings. A model's optional `api` array can narrow access to `['rest']`, `['graphql']`, both, or `[]` to hide it from both. A model cannot enable an API absent from root `api`. OpenAPI includes models with REST enabled. GraphQL generation needs at least one GraphQL model; REST OpenAPI generation needs at least one REST model. On a GraphQL-only server, OpenAPI can still describe configured auth and file routes. Related models must allow the same API. Model names must be valid identifiers; type and operation collisions cause errors. `and`, `or` and `not` are reserved filter names.
+Model definitions belong in `models`. The schema root accepts `models`, `api`, `timestamps` and `softDelete`. Root `api` selects database routes. When omitted, its default depends on how the schema is used:
+
+| Context | Default root `api` |
+|---|---|
+| Server without a `graphql` section | `['rest']` |
+| Server with a `graphql` section | `['rest', 'graphql']` |
+| Standalone `generateOpenapi()` | `['rest']` |
+| Standalone `generateGraphql()` | `['graphql']` |
+
+Explicit `['rest']` enables database REST routes; `['graphql']` enables GraphQL operations; `['rest', 'graphql']` enables both. OpenAPI describes REST routes when `openapi` is configured. Root `api: []` is invalid; `[]` is allowed only at the model level.
+
+A model without its own `api` inherits the root value. A model can override it with `['rest']`, `['graphql']`, both, or `[]` to hide it from both. A model cannot enable an API absent from root `api`. OpenAPI includes models with REST enabled. GraphQL generation needs at least one GraphQL model; REST OpenAPI generation needs at least one REST model. On a GraphQL-only server, OpenAPI can still describe configured auth and file routes. Related models must allow the same API. Model names must be valid identifiers; type and operation collisions cause errors. `and`, `or` and `not` are reserved filter names.
+
+Thus an explicit root `"api": ["rest", "graphql"]` enables both APIs for models that inherit the root setting. The array order does not matter.
 
 For example, with root `api: ['rest', 'graphql']`, a model set to `api: ['rest']` has REST routes and OpenAPI paths but no GraphQL operations; a model set to `api: ['graphql']` has GraphQL operations but no REST routes or OpenAPI paths.
 
@@ -213,7 +226,7 @@ The `type` property accepts `string`, `number`, `boolean`, `object`, or a model
 | `minLength`, `maxLength`, `pattern` | String constraints |
 | `format` | `date`, `date-time`, `email`, `uri`, `uuid` |
 | `minimum`, `maximum` | Inclusive numeric bounds |
-| `source`, `target`, `onDelete` | Relation metadata |
+| `keyOn`, `source`, `target`, `onDelete` | Relation metadata |
 
 String and numeric constraints on `string[]`/`number[]` apply to every element. `required` and `nullable` apply to the entire array; `default` and `example` contain a complete array. Elements must match the array's type and be non-null. `required` requires a stored array field to be present but does not require any elements.
 
@@ -231,26 +244,35 @@ Objects used in GraphQL must have at least one field visible in responses; REST
 {
   "actors.genres": {
     "type": "Genre[]",
+    "keyOn": "current",
     "source": "actors.genreIds",
     "required": true
   }
 }
 ```
 
-`Genre` returns an object; `Genre[]` returns a list. `source` defaults to the current model's primary key, `target` to the target model's primary key. These defaults also apply to nested relations. Paths start at the root of their respective records: in this example, `actors.genreIds` contains the current actor's genre keys.
+`Genre` returns an object; `Genre[]` returns a list. Every explicit relation needs a matching declaration on the other model. Both declarations require `keyOn`: `current` marks the side that stores the key, and `related` marks its inverse. The pair must contain one of each. For this example, add `Genre.movies = {"type":"Movie[]","keyOn":"related","target":"actors.genreIds"}`.
+
+On the `current` side, `target` defaults to the related model's primary key. `source` defaults to the relation field name plus that target key: `User.country` → `User.countryId`; a list uses the singular field name and a plural key: `Genre.parents` → `Genre.parentIds`. Thus `Genre.parents = {"type":"Genre[]","keyOn":"current"}` and `Genre.children = {"type":"Genre[]","keyOn":"related"}` share `Genre.parentIds`. Nested relations keep their parent path: `Movie.actors.genres` → `Movie.actors.genreIds`. A custom primary key also changes the suffix: `Movie.publishers` targeting `Publisher.ref` → `Movie.publisherRefs`.
 
-Relation keys remain in the database even when they are absent from `fields`. A `source` field pointing to a target primary key can be omitted: the server infers an array of keys for a list relation or a scalar key for a single relation. An inferred key is internal: REST and GraphQL cannot read, select, filter, sort or write it directly, and OpenAPI does not describe it. The relation itself remains available. Declare the key in `fields`, for example `"countryId": { "type": "string" }`, to expose it in the APIs. An ambiguous mapping also requires an explicit declaration.
+`source` is always a path in the current model, and `target` is always a path in the model named by `type`. For an inverse relation, the paths are swapped: `Country.users` has `source: "id"` and `target: "countryId"`. Specify a path when the stored key has a custom name. If multiple relations connect the same models, disambiguate the inverse declarations, for example `Country.birthUsers = {"type":"User[]","keyOn":"related","target":"birthCountryId"}` and `Country.residenceUsers = {"type":"User[]","keyOn":"related","target":"residenceCountryId"}`. Missing, inconsistent, or ambiguous pairs fail when the schema loads.
 
-Reverse example: `User.movies = {"type":"Movie[]","target":"actors.userId"}`. A movie is returned once even if several actors match. A single relation that matches multiple records causes an error.
+Relation keys remain in the database even when they are absent from `fields`. On the `current` side, a `source` field can be omitted when the target key type is known: the server infers an array of keys for a list relation or a scalar key for a single relation. This applies to primary and non-primary target fields. An inferred key is internal: REST and GraphQL cannot read, select, filter, sort or write it directly, and OpenAPI does not describe it. The relation itself remains available. Declare the key in `fields`, for example `"countryId": { "type": "string" }`, to expose it in the APIs. An ambiguous mapping also requires an explicit declaration.
+
+For example, `publishers: { "type": "Publisher[]", "keyOn": "current", "target": "code" }` infers `publisherCodes: { "type": "string[]" }` when `Publisher.code` is a string, even if the primary key is `Publisher.id`. Explicitly declared storage key types are preserved.
+
+Reverse example: `User.movies = {"type":"Movie[]","keyOn":"related","target":"actors.userId"}` pairs with `Movie.actors.user = {"type":"User","keyOn":"current","source":"actors.userId"}`. A movie is returned once even if several actors match. A single relation that matches multiple records causes an error.
 
 Every directly supplied, explicitly declared relation key must point to an existing record. `required: true` on a single relation requires a target. On a list relation backed by its own array of source keys, it requires that array to be present, but `[]` is valid. A list computed without its own source-key array, including a reverse relation, is always available and may be empty even with `required: true`. Missing single relations return `null`.
 
+Omitting a `related` relation from `PUT` leaves its existing links unchanged, because those keys live in other records. Supply the relation explicitly to replace its links; for example, `"users": []` removes every user from that country's inverse list.
+
 `onDelete` describes what happens **when a target record is deleted**:
 
 - `restrict` (default): refuse deletion while a retained record refers to the target.
 - `cascade`: delete the referring record. For `User.country`, deleting the country deletes its users. For `Movie.actors.user`, deleting the user removes matching actor elements and retains the movie.
 
-Cascading deletion runs as one operation, including cyclic relations. A validation failure cancels the entire operation. `onDelete` rules also apply to explicitly declared reverse relations; account for both rules when defining both directions.
+Cascading deletion runs as one operation, including cyclic relations. A validation failure cancels the entire operation. A `related` inverse without `onDelete` does not restrict deletion merely because the other side stores a key; set `onDelete` on that inverse to define an additional rule.
 
 ## Example database
 
@@ -259,37 +281,31 @@ Cascading deletion runs as one operation, including cyclic relations. A validati
   "countries": [
     {
       "id": "1",
-      "isArchived": false,
       "name": "Ardenia"
     },
     {
       "id": "2",
-      "isArchived": false,
       "name": "Veloria"
     }
   ],
   "genres": [
     {
       "id": "1",
-      "isArchived": false,
       "name": "Crime",
       "parentIds": []
     },
     {
       "id": "2",
-      "isArchived": false,
       "name": "Gangster",
       "parentIds": ["1"]
     },
     {
       "id": "3",
-      "isArchived": false,
       "name": "Drama",
       "parentIds": []
     },
     {
       "id": "4",
-      "isArchived": false,
       "name": "Comedy",
       "parentIds": []
     }
@@ -311,7 +327,6 @@ Cascading deletion runs as one operation, including cyclic relations. A validati
       "coverSrc": "https://example.com/covers/shadows-of-ardenia.jpg",
       "description": "An heiress in a port city uncovers a plot involving two rival families.",
       "id": "1",
-      "isArchived": false,
       "publisherIds": ["2"],
       "title": "Shadows of Ardenia"
     },
@@ -320,7 +335,6 @@ Cascading deletion runs as one operation, including cyclic relations. A validati
       "coverSrc": "https://example.com/covers/northern-star.jpg",
       "description": "A night clerk at an old hotel gets drawn into the search for a missing painting.",
       "id": "2",
-      "isArchived": false,
       "publisherIds": ["1"],
       "title": "Midnight at the Northern Star"
     }
@@ -328,12 +342,10 @@ Cascading deletion runs as one operation, including cyclic relations. A validati
   "publishers": [
     {
       "id": "1",
-      "isArchived": false,
       "name": "Northlight Studio"
     },
     {
       "id": "2",
-      "isArchived": false,
       "name": "Aurora Pictures"
     }
   ],
@@ -342,15 +354,13 @@ Cascading deletion runs as one operation, including cyclic relations. A validati
       "bornAt": "1988-03-14",
       "countryId": "1",
       "fullName": "Mira Volkova",
-      "id": "1",
-      "isArchived": false
+      "id": "1"
     },
     {
       "bornAt": "1991-11-02",
       "countryId": "2",
       "fullName": "Leon Vetrov",
-      "id": "2",
-      "isArchived": false
+      "id": "2"
     }
   ]
 }
@@ -488,20 +498,20 @@ Content-Type: application/json
 
 | Relation value | Behavior |
 |---|---|
-| An object containing only a primary key | Link an existing record without changing it |
+| An object containing only a primary key | Link an existing record without updating its fields or audit values |
 | An object with a primary key and other fields | PATCH updates supplied fields; PUT replaces the related record |
 | An object without a primary key | Create a related record with defaults and a generated key |
 
-The key name and type follow the target model. An object containing only a key still counts as an update: in PUT it must include the model's required fields. Replacement preserves primary keys, generated values and `readOnly` fields. In POST, nested objects with existing keys receive partial updates. A missing target is an error; creating a nested record without a key requires an autogenerated primary key.
+The key name and type follow the target model. An object containing only that key is a reference in POST, PUT and PATCH; it does not require the target's other mandatory fields. Adding other fields makes it an update: PUT requires all mandatory fields and removes omitted optional fields or resets them to defaults; POST/PATCH update supplied fields. Replacement preserves primary keys, generated values and `readOnly` fields. A missing target is an error; creating a nested record without a key requires an autogenerated primary key. Declared storage keys, for example `countryId`, can also change links directly.
 
-A supplied list replaces the relation's membership. PATCH preserves omitted relations; PUT clears omitted writable links. `[]` clears a list and `null` clears a nullable single relation. Removing a link does not delete the related record. Required single relations must remain linked; required list relations may be empty.
+A supplied list replaces the relation's membership. PATCH preserves omitted relations. PUT replaces the current record's writable fields, including its own relation keys, but preserves omitted `keyOn: "related"` links whose keys live in other records. `[]` clears a list and `null` clears a nullable single relation. Removing a link does not delete the related record. Required single relations must remain linked; required list relations may be empty.
 
 When the storage key is declared in `fields`, use either the relation field or its key in an object, for example `genres` or `genreIds`. Supplying both fields returns `400 INVALID_INPUT`, even when their key sets match:
 
 ```json
 {
   "genreIds": ["1", "2"],
-  "genres": ["1", "2"]
+  "genres": [{ "id": "1" }, { "id": "2" }]
 }
 ```
 
@@ -509,7 +519,7 @@ The server rejects both fields together and rolls back the operation. Relation f
 
 All nested changes belong to the main record's transaction. A validation error, missing record or invalid response selection rolls back the entire operation. Updating a shared record affects every record linked to it.
 
-GraphQL accepts typed objects in relation fields. To change only the links in a replace mutation, use a declared storage key such as `genreIds`. For example:
+GraphQL accepts typed objects in relation fields. To change only links, including in a replace mutation, pass objects containing only primary keys or use a declared storage key such as `genreIds`. Required fields for nested creation or replacement with additional fields are checked at runtime. For example:
 
 ```graphql
 mutation {
@@ -753,7 +763,7 @@ Cascade deletion follows `onDelete` and each affected model's `softDelete`. Rest
 
 Restoration metadata is stored with the records and survives restarts; include it when backing up the database. The internal `djsDeletion` field is reserved and is not exposed by either API.
 
-With auth, any authenticated user can create records. Updating, deleting and restoring require ownership through `createdById` or `isAdmin: true`. Only administrators can change unowned records. Administrator edits preserve the original owner. The rules cover nested writes, changes to relation storage keys, cascades and restoration. Linking an existing record without changing it does not require owning it. Each mutation is atomic: denied changes leave all affected records unchanged.
+With auth, any authenticated user can create records. Updating, deleting and restoring require ownership through `createdById` or `isAdmin: true`. Only administrators can change unowned records. Administrator edits preserve the original owner. The rules cover nested writes, changes to relation storage keys, cascades and restoration. Linking a record through a primary-key-only object or a declared storage key does not require owning the unchanged target. A nested object with additional fields requires permission to update it. Changing inverse links still requires permission for every record whose stored key changes. Each mutation is atomic: denied changes leave all affected records unchanged.
 
 REST returns 401 for an invalid or missing token and 403 for insufficient permissions. GraphQL applies the same rules to mutations and returns `UNAUTHENTICATED` or `FORBIDDEN`; obtain the token through REST login and send `Authorization: Bearer <token>`. GraphQL reads remain public, as do OPTIONS requests and every file operation.
 
@@ -832,7 +842,7 @@ Content-Type: application/json
 
 In disk mode, the binary is stored at `<files.source>/<directory>/<name>`. Metadata defaults to `<files.source>/.files.json`; set `files.metadata` for another location. Directories and the metadata file are created when needed.
 
-Use one server process per disk database and file store. A second server using the same database file fails at startup; closing the first server releases its lock, and a lock left by a crashed process is recovered on the next start. Stop the server before editing stored files or metadata manually. Storage paths cannot contain symbolic links. Uploads and renames cannot overwrite the database, its lock, counters, schema, auth users, loaded configuration or metadata file.
+Use one server process per disk database and file store. A second server using the same database file fails at startup; closing the first server releases its lock, and a lock left by a crashed process is recovered on the next start. Stop the server before editing stored files or metadata manually. Paths inside the file storage directory cannot contain symbolic links. Uploads and renames cannot overwrite the database, its lock, counters, schema, auth users, loaded configuration or metadata file.
 
 Send the file as a binary request body. In a browser, use `xhr.send(file)` and track progress through `XMLHttpRequest.upload.onprogress`. The default maximum size is 100 MiB and can be changed through `server.maxFileSize`. Missing or unsafe headers and paths return `400`, an exceeded limit returns `413`, and a missing, malformed, or Fastify-unsupported `Content-Type` returns `400` or `415`, depending on which validation stage rejects it.
 

package/README.ru.md

@@ -2,11 +2,11 @@
 
 [English](README.md)
 
-[История выпусков](CHANGELOG.md) · [Переход с 0.9.0](MIGRATION.md)
+[История выпусков](CHANGELOG.md) · [Переход с 0.9.0](MIGRATION.ru.md)
 
 JSON-сервер для создания тестового API с REST, GraphQL, связями между записями, загрузкой файлов и экспортом схем. Поддерживает вход пользователей, права владельца и администратора, даты записей и мягкое удаление. Требуется Node.js 22 или новее.
 
-**Изменения в 1.0.0, нарушающие совместимость.** При переходе с 0.9.0 воспользуйтесь [инструкцией по миграции](MIGRATION.md). `*` в REST `scope` выбирает только скалярные поля, которые не хранят ключи связей. Массивы, объекты, связи и явно объявленные ключи связей нужно указывать в выборе полей. При включённой аутентификации права на запись доступны через виртуальное поле `actions`.
+**Изменения в 1.0.0, нарушающие совместимость.** При переходе с 0.9.0 воспользуйтесь [инструкцией по миграции](MIGRATION.ru.md). `*` в REST `scope` выбирает только скалярные поля, которые не хранят ключи связей. Массивы, объекты, связи и явно объявленные ключи связей нужно указывать в выборе полей. При включённой аутентификации права на запись доступны через виртуальное поле `actions`.
 
 ## Установка
 
@@ -14,7 +14,7 @@ JSON-сервер для создания тестового API с REST, GraphQ
 npm install @kollors/deep-json-server@rc
 ```
 
-Для установки этого релиз-кандидата укажите `@1.0.0-rc.5`.
+Для установки этого релиз-кандидата укажите `@1.0.0-rc.7`.
 
 ## Быстрый старт
 
@@ -151,7 +151,7 @@ export default {
         },
         "users": {
           "type": "User[]",
-          "target": "countryId"
+          "keyOn": "related"
         }
       }
     },
@@ -169,7 +169,7 @@ export default {
         },
         "country": {
           "type": "Country",
-          "source": "countryId"
+          "keyOn": "current"
         }
       }
     }
@@ -177,7 +177,20 @@ export default {
 }
 ```
 
-Модели задаются в `models`. Корень схемы принимает `models`, `api`, `timestamps` и `softDelete`. Корневой `api` выбирает маршруты базы. Если его нет, по умолчанию включён REST и дополнительно GraphQL при наличии секции `graphql` в конфигурации сервера. У модели настройки дат и мягкого удаления могут переопределять общие значения. Необязательный массив `api` у модели может сузить доступ до `['rest']`, `['graphql']`, обоих вариантов или `[]`, чтобы скрыть модель полностью. Модель не может включить API, отсутствующий в корневом `api`. OpenAPI включает модели, доступные через REST. Для генерации GraphQL нужна хотя бы одна GraphQL-модель; для генерации OpenAPI с маршрутами базы — хотя бы одна REST-модель. Если база доступна только через GraphQL, OpenAPI всё равно может описывать настроенные маршруты auth и файлов. Связанные модели должны разрешать тот же API. Имена моделей должны быть допустимыми идентификаторами; конфликты типов и операций вызывают ошибку. Имена `and`, `or`, `not` зарезервированы фильтрами.
+Модели задаются в `models`. Корень схемы принимает `models`, `api`, `timestamps` и `softDelete`. Корневой `api` выбирает маршруты базы. Если он не задан, значение по умолчанию зависит от способа использования схемы:
+
+| Контекст | Корневой `api` по умолчанию |
+|---|---|
+| Сервер без секции `graphql` | `['rest']` |
+| Сервер с секцией `graphql` | `['rest', 'graphql']` |
+| Отдельный вызов `generateOpenapi()` | `['rest']` |
+| Отдельный вызов `generateGraphql()` | `['graphql']` |
+
+Явный `['rest']` включает REST-маршруты базы; `['graphql']` — операции GraphQL; `['rest', 'graphql']` — оба API. OpenAPI описывает REST-маршруты при наличии секции `openapi`. Корневой `api: []` недопустим; `[]` разрешён только на уровне модели.
+
+Модель без собственного `api` наследует значение из корня. Указанный у модели массив может содержать `['rest']`, `['graphql']`, оба варианта или `[]`. Модель не может включить API, отсутствующий в корневом `api`. OpenAPI включает модели, доступные через REST. Для генерации GraphQL нужна хотя бы одна GraphQL-модель; для генерации OpenAPI с маршрутами базы — хотя бы одна REST-модель. Если база доступна только через GraphQL, OpenAPI всё равно может описывать настроенные маршруты auth и файлов. Связанные модели должны разрешать тот же API. Имена моделей должны быть допустимыми идентификаторами; конфликты типов и операций вызывают ошибку. Имена `and`, `or`, `not` зарезервированы фильтрами.
+
+Таким образом, явный корневой `"api": ["rest", "graphql"]` включает оба API у моделей, наследующих настройку из корня. Порядок элементов массива не важен.
 
 Например, при корневом `api: ['rest', 'graphql']` модель с `api: ['rest']` получает REST-маршруты и пути в OpenAPI без операций GraphQL, а модель с `api: ['graphql']` — операции GraphQL без REST-маршрутов и путей в OpenAPI.
 
@@ -213,7 +226,7 @@ REST без схемы создаёт ключ `id` и сохраняет про
 | `minLength`, `maxLength`, `pattern` | Ограничения строк |
 | `format` | `date`, `date-time`, `email`, `uri`, `uuid` |
 | `minimum`, `maximum` | Включительные числовые границы |
-| `source`, `target`, `onDelete` | Описание связи |
+| `keyOn`, `source`, `target`, `onDelete` | Описание связи |
 
 Ограничения строк и чисел применяются к каждому элементу `string[]`/`number[]`. `required` и `nullable` относятся ко всему массиву; `default` и `example` содержат массив целиком. Элементы массива должны соответствовать его типу и быть отличны от `null`. `required` требует наличия хранимого поля массива, но не требует элементов в нём.
 
@@ -231,26 +244,35 @@ REST без схемы создаёт ключ `id` и сохраняет про
 {
   "actors.genres": {
     "type": "Genre[]",
+    "keyOn": "current",
     "source": "actors.genreIds",
     "required": true
   }
 }
 ```
 
-`Genre` возвращает объект, `Genre[]` — список. По умолчанию `source` указывает на первичный ключ текущей модели, `target` — целевой. Это правило действует и для вложенных связей. Пути задаются от корня соответствующей записи: в примере `actors.genreIds` содержит ключи жанров текущего актёра.
+`Genre` возвращает объект, `Genre[]` — список. Каждую явную связь нужно объявить с обеих сторон. В обоих полях обязателен `keyOn`: `current` обозначает сторону, где хранится ключ, `related` — обратную. В паре должно быть по одному полю каждого вида. Для примера выше добавьте `Genre.movies = {"type":"Movie[]","keyOn":"related","target":"actors.genreIds"}`.
+
+На стороне `current` поле `target` по умолчанию равно первичному ключу связанной модели. `source` выводится из имени поля связи и этого ключа: `User.country` → `User.countryId`; для списка берётся единственное число имени связи и множественное число ключа: `Genre.parents` → `Genre.parentIds`. Поэтому `Genre.parents = {"type":"Genre[]","keyOn":"current"}` и `Genre.children = {"type":"Genre[]","keyOn":"related"}` используют один `Genre.parentIds`. Вложенные поля сохраняют родительский путь: `Movie.actors.genres` → `Movie.actors.genreIds`. Нестандартный первичный ключ меняет суффикс: `Movie.publishers` при ключе `Publisher.ref` → `Movie.publisherRefs`.
 
-Ключи связей остаются в базе, даже если их нет в `fields`. Если поле `source` ссылается на первичный ключ целевой модели, его можно не объявлять отдельно: сервер выведет массив ключей для множественной связи или одно значение для одиночной. Такой ключ остаётся внутренним: REST и GraphQL не позволяют читать, выбирать, фильтровать, сортировать или записывать его напрямую, а OpenAPI его не описывает. Сама связь при этом доступна. Чтобы открыть ключ в API, объявите его в `fields`, например `"countryId": { "type": "string" }`. Неоднозначное сопоставление тоже требует явного объявления.
+`source` всегда указывает на поле текущей модели, а `target` — на поле модели из `type`. Для обратной связи пути меняются местами: у `Country.users` это `source: "id"` и `target: "countryId"`. Если ключ хранится под нестандартным именем, задайте путь явно. Когда между двумя моделями несколько связей, уточните обратные поля: например, `Country.birthUsers = {"type":"User[]","keyOn":"related","target":"birthCountryId"}` и `Country.residenceUsers = {"type":"User[]","keyOn":"related","target":"residenceCountryId"}`. Отсутствующая, противоречивая или неоднозначная пара вызывает ошибку при загрузке схемы.
 
-Обратная связь: `User.movies = {"type":"Movie[]","target":"actors.userId"}`. Фильм возвращается один раз, даже если совпало несколько актёров. Несколько совпадений для одиночной связи — ошибка.
+Ключи связей остаются в базе, даже если их нет в `fields`. На стороне `current` поле `source` можно не объявлять отдельно, если известен тип целевого ключа: сервер выведет массив для множественной связи или одно значение для одиночной. Это действует и для первичного, и для непервичного целевого поля. Такой ключ остаётся внутренним: REST и GraphQL не позволяют читать, выбирать, фильтровать, сортировать или записывать его напрямую, а OpenAPI его не описывает. Сама связь при этом доступна. Чтобы открыть ключ в API, объявите его в `fields`, например `"countryId": { "type": "string" }`. Неоднозначное сопоставление тоже требует явного объявления.
+
+Например, `publishers: { "type": "Publisher[]", "keyOn": "current", "target": "code" }` выводит `publisherCodes: { "type": "string[]" }`, если `Publisher.code` — строка, даже при первичном ключе `Publisher.id`. Типы явно объявленных хранимых ключей сохраняются.
+
+Обратная связь: `User.movies = {"type":"Movie[]","keyOn":"related","target":"actors.userId"}` соответствует `Movie.actors.user = {"type":"User","keyOn":"current","source":"actors.userId"}`. Фильм возвращается один раз, даже если совпало несколько актёров. Несколько совпадений для одиночной связи — ошибка.
 
 Каждый переданный напрямую и явно объявленный ключ связи должен указывать на существующую запись. `required: true` у одиночной связи требует целевую запись. У связи-списка с собственным массивом ключей `source` оно требует наличия этого массива, но `[]` допустим. Список без собственного массива ключей, включая обратную связь, вычисляется всегда и может быть пустым даже при `required: true`. Отсутствующая одиночная связь возвращает `null`.
 
+Если не передать связь `related` в `PUT`, существующие связи сохранятся: их ключи хранятся в других записях. Чтобы заменить состав связи, передайте её явно; например, `"users": []` удалит всех пользователей из обратного списка страны.
+
 `onDelete` срабатывает **при удалении целевой записи**:
 
 - `restrict` — по умолчанию: запретить удаление, пока на цель ссылается сохраняемая запись.
 - `cascade` — удалить ссылающуюся запись. Для `User.country` удаление страны удаляет пользователей. Для `Movie.actors.user` удаление пользователя удаляет соответствующие элементы `actors`, сохраняя фильм.
 
-Каскадное удаление выполняется целиком, включая циклические связи. Ошибка проверки отменяет всю операцию. Правила `onDelete` действуют и на явно объявленные обратные связи; при описании обоих направлений учитывайте оба правила.
+Каскадное удаление выполняется целиком, включая циклические связи. Ошибка проверки отменяет всю операцию. Обратная связь `related` без `onDelete` сама по себе не запрещает удаление записи из-за ключа на другой стороне; задайте `onDelete`, если для неё нужно дополнительное правило.
 
 ## Пример базы данных
 
@@ -259,37 +281,31 @@ REST без схемы создаёт ключ `id` и сохраняет про
   "countries": [
     {
       "id": "1",
-      "isArchived": false,
       "name": "Ardenia"
     },
     {
       "id": "2",
-      "isArchived": false,
       "name": "Veloria"
     }
   ],
   "genres": [
     {
       "id": "1",
-      "isArchived": false,
       "name": "Crime",
       "parentIds": []
     },
     {
       "id": "2",
-      "isArchived": false,
       "name": "Gangster",
       "parentIds": ["1"]
     },
     {
       "id": "3",
-      "isArchived": false,
       "name": "Drama",
       "parentIds": []
     },
     {
       "id": "4",
-      "isArchived": false,
       "name": "Comedy",
       "parentIds": []
     }
@@ -311,7 +327,6 @@ REST без схемы создаёт ключ `id` и сохраняет про
       "coverSrc": "https://example.com/covers/shadows-of-ardenia.jpg",
       "description": "An heiress in a port city uncovers a plot involving two rival families.",
       "id": "1",
-      "isArchived": false,
       "publisherIds": ["2"],
       "title": "Shadows of Ardenia"
     },
@@ -320,7 +335,6 @@ REST без схемы создаёт ключ `id` и сохраняет про
       "coverSrc": "https://example.com/covers/northern-star.jpg",
       "description": "A night clerk at an old hotel gets drawn into the search for a missing painting.",
       "id": "2",
-      "isArchived": false,
       "publisherIds": ["1"],
       "title": "Midnight at the Northern Star"
     }
@@ -328,12 +342,10 @@ REST без схемы создаёт ключ `id` и сохраняет про
   "publishers": [
     {
       "id": "1",
-      "isArchived": false,
       "name": "Northlight Studio"
     },
     {
       "id": "2",
-      "isArchived": false,
       "name": "Aurora Pictures"
     }
   ],
@@ -342,15 +354,13 @@ REST без схемы создаёт ключ `id` и сохраняет про
       "bornAt": "1988-03-14",
       "countryId": "1",
       "fullName": "Mira Volkova",
-      "id": "1",
-      "isArchived": false
+      "id": "1"
     },
     {
       "bornAt": "1991-11-02",
       "countryId": "2",
       "fullName": "Leon Vetrov",
-      "id": "2",
-      "isArchived": false
+      "id": "2"
     }
   ]
 }
@@ -488,20 +498,20 @@ Content-Type: application/json
 
 | Значение в связи | Действие |
 |---|---|
-| Объект только с первичным ключом | Связать существующую запись без её изменения |
+| Объект только с первичным ключом | Связать существующую запись без обновления её полей, дат и авторства |
 | Объект с первичным ключом и другими полями | PATCH обновляет переданные поля, PUT заменяет связанную запись |
 | Объект без первичного ключа | Создать запись со значениями по умолчанию и сгенерированным ключом |
 
-Имя и тип ключа берутся из целевой модели. Объект только с ключом тоже считается обновлением: в PUT он должен содержать обязательные поля модели. При замене сохраняются первичный ключ, генерируемые значения и поля `readOnly`. В POST вложенные объекты с существующими ключами обновляются частично. Если запись по ключу не найдена, операция завершится ошибкой. Для создания вложенной записи без ключа нужна его автоматическая генерация.
+Имя и тип ключа берутся из целевой модели. Объект только с этим ключом считается ссылкой в POST, PUT и PATCH; остальные обязательные поля целевой модели ему не нужны. Если добавить другие поля, это уже обновление: PUT требует все обязательные поля, удаляет пропущенные необязательные или задаёт им значения по умолчанию; POST/PATCH обновляют переданные поля. При замене сохраняются первичный ключ, генерируемые значения и поля `readOnly`. Если запись по ключу не найдена, операция завершится ошибкой. Для создания вложенной записи без ключа нужна его автоматическая генерация. Объявленные хранимые ключи, например `countryId`, тоже позволяют менять ссылки напрямую.
 
-Переданный список заменяет состав связи. PATCH сохраняет пропущенные связи, PUT очищает пропущенные связи, ключи которых доступны для записи. `[]` очищает список, `null` — одиночную связь с разрешённым `nullable`. Разрыв связи не удаляет связанную запись. Обязательная одиночная связь должна сохраняться; обязательная связь-список может быть пустой.
+Переданный список заменяет состав связи. PATCH сохраняет пропущенные связи. PUT заменяет доступные для записи поля текущей записи, включая её собственные ключи связей, но сохраняет пропущенные связи `keyOn: "related"`, чьи ключи хранятся в других записях. `[]` очищает список, `null` — одиночную связь с разрешённым `nullable`. Разрыв связи не удаляет связанную запись. Обязательная одиночная связь должна сохраняться; обязательная связь-список может быть пустой.
 
 Если хранимый ключ объявлен в `fields`, в одном объекте указывайте либо связь, либо её ключ: например, `genres` или `genreIds`. Одновременная передача обоих полей возвращает `400 INVALID_INPUT`, даже если наборы ключей совпадают:
 
 ```json
 {
   "genreIds": ["1", "2"],
-  "genres": ["1", "2"]
+  "genres": [{ "id": "1" }, { "id": "2" }]
 }
 ```
 
@@ -509,7 +519,7 @@ Content-Type: application/json
 
 Все вложенные изменения входят в транзакцию основной записи. Ошибка проверки, отсутствующая запись или неверный выбор полей ответа отменяет всю операцию. Изменения общей записи видны всем, кто с ней связан.
 
-GraphQL принимает в полях связей типизированные объекты. Чтобы при замене изменить только связи, используйте объявленные поля ключей, например `genreIds`. Пример:
+GraphQL принимает в полях связей типизированные объекты. Чтобы изменить только ссылки, в том числе при замене, передайте объекты только с первичными ключами либо объявленные поля ключей, например `genreIds`. Обязательные поля вложенного создания или замены с дополнительными полями проверяются при выполнении. Пример:
 
 ```graphql
 mutation {
@@ -753,7 +763,7 @@ query {
 
 Служебные сведения восстановления хранятся вместе с записями и переживают перезапуск; сохраняйте их при резервном копировании базы. Внутреннее поле `djsDeletion` зарезервировано и не выдаётся через API.
 
-При включённом auth создавать записи может любой вошедший пользователь. Изменять, удалять и восстанавливать — владелец по `createdById` или пользователь с `isAdmin: true`. Записи без владельца изменяет только администратор. Его правки не меняют владельца. Правила действуют на вложенные записи, изменение ключей связей, каскады и восстановление. Ссылка на существующую запись без её изменения не требует владения ею. Каждая мутация атомарна: отказ сохраняет прежнее состояние всех затронутых записей.
+При включённом auth создавать записи может любой вошедший пользователь. Изменять, удалять и восстанавливать — владелец по `createdById` или пользователь с `isAdmin: true`. Записи без владельца изменяет только администратор. Его правки не меняют владельца. Правила действуют на вложенные записи, изменение ключей связей, каскады и восстановление. Ссылка через объект только с первичным ключом или объявленный хранимый ключ не требует владения неизменяемой целевой записью. Вложенный объект с дополнительными полями требует права изменять её. При изменении обратных связей нужны права на каждую запись, чей хранимый ключ меняется. Каждая мутация атомарна: отказ сохраняет прежнее состояние всех затронутых записей.
 
 REST возвращает 401 при отсутствии действительного токена и 403 при недостатке прав. GraphQL проверяет мутации по тем же правилам и возвращает коды `UNAUTHENTICATED` или `FORBIDDEN`; токен получают через REST-вход и передают в `Authorization: Bearer <token>`. GraphQL-запросы чтения, OPTIONS и все операции с файлами остаются открытыми.
 
@@ -832,7 +842,7 @@ Content-Type: application/json
 
 При хранении на диске бинарный файл находится по пути `<files.source>/<directory>/<name>`. Метаданные по умолчанию хранятся в `<files.source>/.files.json`; другой путь можно задать через `files.metadata`. Директории и файл метаданных создаются по мере необходимости.
 
-Используйте один процесс сервера для дисковой базы и файлового хранилища. Второй сервер с тем же файлом базы не запустится; закрытие первого освобождает блокировку, а после аварийного завершения она снимается при следующем запуске. Перед ручным изменением файлов или метаданных остановите сервер. Пути в хранилище не могут содержать символические ссылки. Загрузка и переименование не могут перезаписать базу, её блокировку, счётчики, схему, учётные записи auth, загруженную конфигурацию или файл метаданных.
+Используйте один процесс сервера для дисковой базы и файлового хранилища. Второй сервер с тем же файлом базы не запустится; закрытие первого освобождает блокировку, а после аварийного завершения она снимается при следующем запуске. Перед ручным изменением файлов или метаданных остановите сервер. Пути внутри каталога файлового хранилища не могут содержать символические ссылки. Загрузка и переименование не могут перезаписать базу, её блокировку, счётчики, схему, учётные записи auth, загруженную конфигурацию или файл метаданных.
 
 Отправляйте файл как бинарное тело запроса. В браузере для этого можно использовать `xhr.send(file)`, а прогресс отслеживать через `XMLHttpRequest.upload.onprogress`. Максимальный размер по умолчанию равен 100 МиБ и настраивается через `server.maxFileSize`. Отсутствующие или небезопасные заголовки и пути возвращают `400`, превышение лимита — `413`, а отсутствующий, некорректный или не поддерживаемый Fastify `Content-Type` — `400` либо `415` в зависимости от этапа проверки.
 

package/dist/src/core/constants.d.ts

@@ -3,4 +3,4 @@ export declare const DEFAULT_MAX_FILE_SIZE: number;
 export declare const DEFAULT_MAX_PAGE_SIZE = 100;
 export declare const DEFAULT_PAGE_SIZE = 10;
 export declare const DEFAULT_PORT = 4001;
-export declare const VERSION = "1.0.0-rc.5";
+export declare const VERSION = "1.0.0-rc.6";

package/dist/src/core/constants.js

@@ -3,5 +3,5 @@ export const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024;
 export const DEFAULT_MAX_PAGE_SIZE = 100;
 export const DEFAULT_PAGE_SIZE = 10;
 export const DEFAULT_PORT = 4001;
-export const VERSION = '1.0.0-rc.5';
+export const VERSION = '1.0.0-rc.6';
 //# sourceMappingURL=constants.js.map

package/dist/src/core/engine.js

@@ -200,6 +200,10 @@ export class Engine {
                 if (node.virtual)
                     continue;
                 if (node.relation) {
+                    // A paired inverse view does not own a storage key. Its default must not block
+                    // deletion of a record that merely appears in that view.
+                    if (node.keyOn === 'related' && node.onDelete === undefined)
+                        continue;
                     const owner = { ref, node, targets: related(ref, node) };
                     owners.push(owner);
                     for (const target of owner.targets) {