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

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 1.0.0-rc.1
+
+First release candidate for the 1.0 API. This release includes schema-driven REST, GraphQL, OpenAPI export, authentication, record ownership, timestamps, soft deletion, and file storage. It also makes CLI and API error messages consistently English and checks TypeScript declarations from an installed package archive.
+
+The 1.0 configuration, CLI flags, and REST query format differ from 0.9.0. Follow the [migration guide](MIGRATION.md) before upgrading an existing project. In particular, the REST `scope` wildcard includes scalar fields only; select arrays, objects, relations, and relation keys explicitly.
+
+### Verification
+
+- TypeScript source and contract checks, lint, and coverage-gated tests.
+- Package installation smoke test for the CLI, REST, GraphQL, OpenAPI, and auth.
+- TypeScript consumer test against the installed package declarations.
+- CI matrix for Node.js 22, 24, and 26 on Linux.

package/MIGRATION.md

@@ -0,0 +1,41 @@
+# Migrating from 0.9.0 to 1.0.0-rc.1
+
+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.
+
+## Configuration
+
+Declare a storage mode and use `source` for each enabled component:
+
+| 0.9.0 | 1.0.0-rc.1 |
+|---|---|
+| `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 |
+| `openapi.path` | `openapi.target` |
+
+The `storage` mode applies to the database, schema, auth records, files, and package metadata. GraphQL and OpenAPI require a model schema and `package.source`. The schema format has changed: define models under `models`, with a `collection`, fields, and one primary key per model. 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.
+
+## CLI
+
+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.
+
+## REST queries
+
+REST now accepts a JSON `scope` query parameter. Replace `_where`, `_sort`, `_page`, `_perPage`, `_embed`, and simple field filters with `scope`. For example:
+
+```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 } },
+];
+const url = `/movies?${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 relation keys explicitly. Related lists can have their own filters, order, and pagination. Review clients that expect embedded relations or relation keys in default responses.
+
+## Records and auth
+
+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.
+
+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.

package/README.md

@@ -2,17 +2,19 @@
 
 [Русский](README.ru.md)
 
+[Release notes](CHANGELOG.md) · [Migration from 0.9.0](MIGRATION.md)
+
 A JSON mock server with REST, GraphQL, related records, file uploads and schema exports. Supports user login, owner and administrator permissions, record timestamps and soft deletion. Requires Node.js 22 or newer.
 
-**Breaking changes: 1.0.0-beta.2.** The REST `scope` wildcard selects only scalar fields that do not store relation keys. Arrays, objects, relations and their keys must be selected explicitly. With auth enabled, record permissions are available through the virtual `actions` field.
+**Breaking changes in 1.0.0.** See the [migration guide](MIGRATION.md) when upgrading from 0.9.0. The REST `scope` wildcard selects only scalar fields that do not store relation keys. Arrays, objects, relations and their keys must be selected explicitly. With auth enabled, record permissions are available through the virtual `actions` field.
 
 ## Installation
 
 ```sh
-npm install @kollors/deep-json-server@beta
+npm install @kollors/deep-json-server@rc
 ```
 
-To install a specific version, use `@1.0.0-beta.4`.
+To install this release candidate, use `@1.0.0-rc.1`.
 
 ## Quick start
 
@@ -23,7 +25,7 @@ Create two files in the same directory.
 ```json
 {
   "users": [
-    { "id": "1", "fullName": "Мира Волкова" }
+    { "id": "1", "fullName": "Mira Volkova" }
   ]
 }
 ```
@@ -44,7 +46,7 @@ Add a [model schema](#model-schema) to define relations and validation. See [que
 
 ## Configuration
 
-With `storage: 'file'`, all sources and the schema are paths. With `'memory'`, they are in-memory data. Modes cannot be mixed. The presence of `auth`, `files`, `graphql` and `openapi` enables those modules. `graphql: {}` and `openapi: {}` enable only the HTTP endpoints at their defaults; add `target` to export a schema.
+With `storage: 'file'`, provide paths for every source and the schema. With `'memory'`, provide data directly. Use the same mode throughout the configuration. Add `auth`, `files`, `graphql` or `openapi` to enable those features. `graphql: {}` and `openapi: {}` expose HTTP endpoints at their default paths; add `target` to export a schema.
 
 ```js
 export default {
@@ -54,6 +56,7 @@ export default {
   files: { source: './uploads' },
   graphql: { target: './generated/schema.graphql' },
   openapi: { target: './generated/openapi.yaml' },
+  package: { source: './package.json' },
   server: { host: '127.0.0.1', port: 4001 },
 };
 ```
@@ -71,13 +74,15 @@ export default {
 | `graphql.target` | GraphQL SDL export destination |
 | `openapi.endpoint` | HTTP endpoint; default `/openapi.json` |
 | `openapi.target` | OpenAPI export destination |
-| `openapi.info` | Metadata: required `title` and `version`, optional `description` |
+| `package.source` | Project `package.json`; required when `openapi` or `graphql` is configured |
 | `server.host`, `server.port` | Defaults `127.0.0.1`, `4001`; CLI also reads `HOST`/`PORT` |
 | `server.pageSize`, `server.maxPageSize` | Defaults 10 and 100; default size is capped by the maximum |
 | `server.cors`, `server.logger` | Default `true`; logger also accepts Fastify logger options |
 | `server.maxFileSize` | Default 100 MiB |
 
-Relative paths resolve from the configuration file directory, or from the working directory with `createServer(config)`. In-memory data, including the schema, is copied. Port `0` lets the system choose an available port.
+`package.source` follows the storage mode. With `storage: 'file'`, pass a path to `package.json`. With `storage: 'memory'`, pass its metadata directly: `{ name: 'example-api', version: '1.0.0', description: 'Example API' }`; `name` and `version` are required, while `description` is optional.
+
+Relative paths resolve from the configuration file directory, or from the working directory with `createServer(config)`. In-memory data, including the schema and package metadata, is copied. Port `0` lets the system choose an available port.
 
 ### CLI
 
@@ -222,37 +227,37 @@ Cascading deletion runs as one operation, including cyclic relations. A validati
     {
       "id": "1",
       "isArchived": false,
-      "name": "Ардения"
+      "name": "Ardenia"
     },
     {
       "id": "2",
       "isArchived": false,
-      "name": "Велория"
+      "name": "Veloria"
     }
   ],
   "genres": [
     {
       "id": "1",
       "isArchived": false,
-      "name": "Криминал",
+      "name": "Crime",
       "parentIds": []
     },
     {
       "id": "2",
       "isArchived": false,
-      "name": "Гангстер",
+      "name": "Gangster",
       "parentIds": ["1"]
     },
     {
       "id": "3",
       "isArchived": false,
-      "name": "Драма",
+      "name": "Drama",
       "parentIds": []
     },
     {
       "id": "4",
       "isArchived": false,
-      "name": "Комедия",
+      "name": "Comedy",
       "parentIds": []
     }
   ],
@@ -271,20 +276,20 @@ Cascading deletion runs as one operation, including cyclic relations. A validati
         }
       ],
       "coverSrc": "https://example.com/covers/shadows-of-ardenia.jpg",
-      "description": "Наследница портового города раскрывает заговор двух соперничающих семей.",
+      "description": "An heiress in a port city uncovers a plot involving two rival families.",
       "id": "1",
       "isArchived": false,
       "publisherIds": ["2"],
-      "title": "Тени Ардении"
+      "title": "Shadows of Ardenia"
     },
     {
       "actors": [],
       "coverSrc": "https://example.com/covers/northern-star.jpg",
-      "description": "Ночной администратор старого отеля случайно становится участником поисков пропавшей картины.",
+      "description": "A night clerk at an old hotel gets drawn into the search for a missing painting.",
       "id": "2",
       "isArchived": false,
       "publisherIds": ["1"],
-      "title": "Полночь в «Северной звезде»"
+      "title": "Midnight at the Northern Star"
     }
   ],
   "publishers": [
@@ -303,14 +308,14 @@ Cascading deletion runs as one operation, including cyclic relations. A validati
     {
       "bornAt": "1988-03-14",
       "countryId": "1",
-      "fullName": "Мира Волкова",
+      "fullName": "Mira Volkova",
       "id": "1",
       "isArchived": false
     },
     {
       "bornAt": "1991-11-02",
       "countryId": "2",
-      "fullName": "Леон Ветров",
+      "fullName": "Leon Vetrov",
       "id": "2",
       "isArchived": false
     }
@@ -390,7 +395,7 @@ const scope = [
     ],
   },
   {
-    where: { fullName: { contains: 'Мира' } },
+    where: { fullName: { contains: 'Mira' } },
     order: [{ field: 'fullName', direction: 'ASC' }],
     pager: { page: 1, pageSize: 20 },
   },
@@ -465,7 +470,7 @@ Use either the relation field or its storage key in an object, for example `genr
 }
 ```
 
-The server neither gives one field priority nor merges the values; the entire operation is rolled back. Relation fields accept objects only; use `genreIds` to change links without creating or updating related records. Reverse relations update the target key. If a target path crosses an array and the server cannot identify one element to attach, provide the array with the intended keys explicitly. Protected keys cannot be changed.
+The server rejects both fields together and rolls back the operation. Relation fields accept objects only; use `genreIds` to change links without creating or updating related records. Reverse relations update the target key. If a target path crosses an array and the server cannot identify one element to attach, provide the array with the intended keys explicitly. Protected keys cannot be changed.
 
 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.
 
@@ -486,7 +491,7 @@ mutation {
 
 ### GraphQL
 
-Set `database.schema` and add `graphql: {}` to the configuration:
+Set `database.schema` and add `graphql: {}` plus `package.source` to the configuration:
 
 ```sh
 npx deep-json-server server.config.js
@@ -497,7 +502,7 @@ Send requests to `/graphql` using POST with `Content-Type: application/json` and
 ```graphql
 query {
   userList(
-    where: { fullName: { contains: "Мира" } }
+    where: { fullName: { contains: "Mira" } }
     order: [{ field: fullName, direction: ASC }]
     pager: { page: 1, pageSize: 20 }
   ) {
@@ -506,7 +511,7 @@ query {
       id
       fullName
       movies(
-        where: { title: { contains: "Тени" } }
+        where: { title: { contains: "Shadows" } }
         order: [{ field: title, direction: ASC }]
         pager: { pageSize: 5 }
       ) {
@@ -526,7 +531,7 @@ Errors include `extensions.code`: `INVALID_INPUT`, `INVALID_QUERY`, `NOT_FOUND`,
 
 ## OpenAPI and schema exports
 
-Exports use OpenAPI 3.0.3. Add `openapi: {}` and `database.schema` to serve the specification at `/openapi.json`. Change the route with `openapi.endpoint`. Open the document in Swagger UI or import it into an API client.
+Exports use OpenAPI 3.0.3. Add `openapi: {}`, `database.schema` and `package.source` to serve the specification at `/openapi.json`. Change the route with `openapi.endpoint`. OpenAPI `info.title`, `info.version` and optional `info.description` come from the configured `package.json`. Open the document in Swagger UI or import it into an API client.
 
 Set output paths to save schemas:
 
@@ -536,6 +541,7 @@ export default {
   database: { source: './database.json', schema: './schema.json' },
   openapi: { target: './generated/openapi.yaml' },
   graphql: { target: './generated/schema.graphql' },
+  package: { source: './package.json' },
 };
 ```
 
@@ -808,7 +814,7 @@ await server.listen();
 
 The `openapi()` and `graphql()` methods return schemas and require `database.schema`. `fastify()` returns the server instance for configuration and startup. The database and enabled services initialize on `ready()`, `listen()` or the first `inject()`; initialization errors stop startup.
 
-`createServer(config)` takes one argument. Configuration sections control modules exactly as in the CLI. The `openapi()` and `graphql()` methods require their respective sections. They return schemas without writing files.
+`createServer(config)` takes the same configuration object as the CLI. When `openapi` or `graphql` is configured, `package.source` is required. The `openapi()` and `graphql()` methods require their respective sections. They return schemas without writing files.
 
 The root import `@kollors/deep-json-server` also provides these functions. Server adapters load when enabled. Generators can be used independently:
 
@@ -816,7 +822,7 @@ The root import `@kollors/deep-json-server` also provides these functions. Serve
 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 document = await generateOpenapi('./schema.json', { files: true, packagePath: './package.json' });
 const sdl = await generateGraphql('./schema.json');
 await writeOpenapi(document, './generated/openapi.yaml');
 await writeGraphql(sdl, './generated/schema.graphql');
@@ -824,7 +830,7 @@ await writeGraphql(sdl, './generated/schema.graphql');
 
 Standalone generators accept a schema path or object without a server configuration. The selected function supplies the default format; a model's `api` setting can restrict it. Timestamps and soft deletion come from the schema. `{ auth: true }` adds ownership and `actions` fields; OpenAPI also describes auth routes and token requirements. `hashPassword()` is available from the root package.
 
-`generateOpenapi()` also accepts `host`, `port`, `pageSize`, `maxPageSize` and `info`. Pass a schema object instead of a path if preferred. Servers and generators use their own copy of the model. Pagination sizes must be positive integers; `pageSize` cannot exceed `maxPageSize`.
+`generateOpenapi()` requires `packagePath` and also accepts `host`, `port`, `pageSize` and `maxPageSize`. It reads OpenAPI metadata from that package. Pass a schema object instead of a path if preferred. Servers and generators use their own copy of the model. Pagination sizes must be positive integers; `pageSize` cannot exceed `maxPageSize`.
 
 ## Data storage
 
@@ -832,14 +838,14 @@ Updates run sequentially within one server instance and are validated on a copy
 
 ## Development
 
-Source modules: `rest`, `graphql`, `openapi`, `auth`, `files`, `cli` and `server`. Shared models, storage, queries and mutation rules live in `core`. `server` connects the modules; API generators load independently of the HTTP runtime.
+The source code is organized into `rest`, `graphql`, `openapi`, `auth`, `files`, `cli` and `server`. Shared models, storage, queries and mutation rules live in `core`. The `server` module connects them; API generators load independently of the HTTP runtime.
 
 ```sh
 npm ci
 npm run verify
 ```
 
-The command checks types, code style, test coverage and installation from the package archive.
+`npm run verify` checks types, code style, test coverage and installation from the package archive.
 
 To publish a prerelease, update the version in `package.json`, `package-lock.json` and `src/core/constants.ts`, then push the commit to `main`. GitHub Actions creates its `v<version>` tag and publishes through trusted publishing to the `alpha`, `beta` or `rc` channel. Stable versions publish to `latest` from an explicitly pushed version tag.
 

package/README.ru.md

@@ -2,17 +2,19 @@
 
 [English](README.md)
 
-JSON-сервер для имитации API: REST, GraphQL, связанные записи, загрузка файлов и экспорт схем. Поддерживает вход пользователей, права владельца и администратора, даты записей и мягкое удаление. Требуется Node.js 22 или новее.
+[История выпусков](CHANGELOG.md) · [Переход с 0.9.0](MIGRATION.md)
 
-**Breaking changes: 1.0.0-beta.2.** `*` в REST `scope` выбирает только скалярные поля, которые не хранят ключи связей. Массивы, объекты, связи и их ключи указываются явно. При включённом auth права на запись доступны через виртуальное поле `actions`.
+JSON-сервер для создания тестового API с REST, GraphQL, связями между записями, загрузкой файлов и экспортом схем. Поддерживает вход пользователей, права владельца и администратора, даты записей и мягкое удаление. Требуется Node.js 22 или новее.
+
+**Изменения в 1.0.0, нарушающие совместимость.** При переходе с 0.9.0 воспользуйтесь [инструкцией по миграции](MIGRATION.md). `*` в REST `scope` выбирает только скалярные поля, которые не хранят ключи связей. Массивы, объекты, связи и их ключи нужно указывать явно. При включённой аутентификации права на запись доступны через виртуальное поле `actions`.
 
 ## Установка
 
 ```sh
-npm install @kollors/deep-json-server@beta
+npm install @kollors/deep-json-server@rc
 ```
 
-Для установки конкретной версии укажите `@1.0.0-beta.4`.
+Для установки этого релиз-кандидата укажите `@1.0.0-rc.1`.
 
 ## Быстрый старт
 
@@ -23,7 +25,7 @@ npm install @kollors/deep-json-server@beta
 ```json
 {
   "users": [
-    { "id": "1", "fullName": "Мира Волкова" }
+    { "id": "1", "fullName": "Mira Volkova" }
   ]
 }
 ```
@@ -44,7 +46,7 @@ npx deep-json-server server.config.js
 
 ## Конфигурация
 
-При `storage: 'file'` все источники и схема задаются путями, при `'memory'` — данными в памяти. Режимы нельзя смешивать. Наличие секций `auth`, `files`, `graphql` и `openapi` включает соответствующие модули. `graphql: {}` и `openapi: {}` включают только HTTP-маршруты со стандартными адресами; для экспорта добавьте `target`.
+При `storage: 'file'` задайте пути для всех источников и схемы, при `'memory'` — передайте данные напрямую. Используйте один режим во всей конфигурации. Секции `auth`, `files`, `graphql` и `openapi` включают соответствующие возможности. `graphql: {}` и `openapi: {}` открывают HTTP-маршруты по стандартным адресам; для экспорта схемы добавьте `target`.
 
 ```js
 export default {
@@ -54,6 +56,7 @@ export default {
   files: { source: './uploads' },
   graphql: { target: './generated/schema.graphql' },
   openapi: { target: './generated/openapi.yaml' },
+  package: { source: './package.json' },
   server: { host: '127.0.0.1', port: 4001 },
 };
 ```
@@ -71,13 +74,15 @@ export default {
 | `graphql.target` | Файл для экспорта GraphQL SDL |
 | `openapi.endpoint` | HTTP-маршрут; по умолчанию `/openapi.json` |
 | `openapi.target` | Файл для экспорта OpenAPI |
-| `openapi.info` | Метаданные: обязательные `title`, `version`, необязательный `description` |
+| `package.source` | `package.json` проекта; обязателен при наличии `openapi` или `graphql` |
 | `server.host`, `server.port` | По умолчанию `127.0.0.1`, `4001`; CLI также читает `HOST`/`PORT` |
 | `server.pageSize`, `server.maxPageSize` | По умолчанию 10 и 100; размер по умолчанию ограничен максимумом |
 | `server.cors`, `server.logger` | По умолчанию `true`; logger принимает также настройки Fastify |
 | `server.maxFileSize` | По умолчанию 100 МиБ |
 
-Относительные пути разрешаются от каталога файла конфигурации; при вызове `createServer(config)` — от рабочего каталога. Данные в памяти, включая схему, копируются. Порт `0` позволяет системе выбрать свободный порт.
+Формат `package.source` зависит от режима хранения. При `storage: 'file'` укажите путь к `package.json`. При `storage: 'memory'` передайте метаданные напрямую: `{ name: 'example-api', version: '1.0.0', description: 'Example API' }`; `name` и `version` обязательны, `description` необязателен.
+
+Относительные пути разрешаются от каталога файла конфигурации; при вызове `createServer(config)` — от рабочего каталога. Данные в памяти, включая схему и метаданные пакета, копируются. Порт `0` позволяет системе выбрать свободный порт.
 
 ### CLI
 
@@ -222,37 +227,37 @@ REST без схемы создаёт ключ `id` и сохраняет про
     {
       "id": "1",
       "isArchived": false,
-      "name": "Ардения"
+      "name": "Ardenia"
     },
     {
       "id": "2",
       "isArchived": false,
-      "name": "Велория"
+      "name": "Veloria"
     }
   ],
   "genres": [
     {
       "id": "1",
       "isArchived": false,
-      "name": "Криминал",
+      "name": "Crime",
       "parentIds": []
     },
     {
       "id": "2",
       "isArchived": false,
-      "name": "Гангстер",
+      "name": "Gangster",
       "parentIds": ["1"]
     },
     {
       "id": "3",
       "isArchived": false,
-      "name": "Драма",
+      "name": "Drama",
       "parentIds": []
     },
     {
       "id": "4",
       "isArchived": false,
-      "name": "Комедия",
+      "name": "Comedy",
       "parentIds": []
     }
   ],
@@ -271,20 +276,20 @@ REST без схемы создаёт ключ `id` и сохраняет про
         }
       ],
       "coverSrc": "https://example.com/covers/shadows-of-ardenia.jpg",
-      "description": "Наследница портового города раскрывает заговор двух соперничающих семей.",
+      "description": "An heiress in a port city uncovers a plot involving two rival families.",
       "id": "1",
       "isArchived": false,
       "publisherIds": ["2"],
-      "title": "Тени Ардении"
+      "title": "Shadows of Ardenia"
     },
     {
       "actors": [],
       "coverSrc": "https://example.com/covers/northern-star.jpg",
-      "description": "Ночной администратор старого отеля случайно становится участником поисков пропавшей картины.",
+      "description": "A night clerk at an old hotel gets drawn into the search for a missing painting.",
       "id": "2",
       "isArchived": false,
       "publisherIds": ["1"],
-      "title": "Полночь в «Северной звезде»"
+      "title": "Midnight at the Northern Star"
     }
   ],
   "publishers": [
@@ -303,14 +308,14 @@ REST без схемы создаёт ключ `id` и сохраняет про
     {
       "bornAt": "1988-03-14",
       "countryId": "1",
-      "fullName": "Мира Волкова",
+      "fullName": "Mira Volkova",
       "id": "1",
       "isArchived": false
     },
     {
       "bornAt": "1991-11-02",
       "countryId": "2",
-      "fullName": "Леон Ветров",
+      "fullName": "Leon Vetrov",
       "id": "2",
       "isArchived": false
     }
@@ -371,11 +376,11 @@ npx deep-json-server examples/server.config.js
 
 Имя параметра пути соответствует первичному ключу. POST, PUT и PATCH принимают JSON-объект записи. PUT заменяет запись с сохранением ключа и серверных полей. PATCH объединяет поля на верхнем уровне; переданные вложенные объекты заменяются с сохранением их полей `readOnly`. Создание и замена требуют всех обязательных полей. При обновлении проверяются переданные значения и итоговая запись. Отсутствующая запись — `404`, конфликт — `409`.
 
-POST возвращает созданную запись со статусом `201`; PUT, PATCH и DELETE — результат со статусом `200`. Ошибки REST имеют вид `{ "error": "Описание ошибки" }`.
+POST возвращает созданную запись со статусом `201`; PUT, PATCH и DELETE — результат со статусом `200`. Ошибки REST имеют вид `{ "error": "Error description" }`.
 
 ### Параметры REST-запросов
 
-Для запросов к записям REST принимает один параметр URL `scope` с JSON-массивом `[поля, аргументы?]`. Первый объект выбирает поля, второй задаёт `where`, `order` и `pager` для списка. Этот формат одинаков для корневого запроса, вложенных объектов и связей.
+Для запросов к записям REST принимает один параметр URL `scope` с JSON-массивом `[fields, arguments?]`. Первый объект выбирает поля, второй задаёт `where`, `order` и `pager` для списка. Этот формат одинаков для корневого запроса, вложенных объектов и связей.
 
 Пример выбора пользователей и их фильмов с отдельной сортировкой и пагинацией:
 
@@ -390,7 +395,7 @@ const scope = [
     ],
   },
   {
-    where: { fullName: { contains: 'Мира' } },
+    where: { fullName: { contains: 'Mira' } },
     order: [{ field: 'fullName', direction: 'ASC' }],
     pager: { page: 1, pageSize: 20 },
   },
@@ -438,8 +443,8 @@ Content-Type: application/json
       "userId": "1",
       "genres": [
         { "id": "1" },
-        { "id": "2", "name": "Обновлённый жанр" },
-        { "name": "Новый жанр" }
+        { "id": "2", "name": "Updated genre" },
+        { "name": "New genre" }
       ]
     }
   ]
@@ -476,7 +481,7 @@ mutation {
   movieUpdate(id: "1", data: {
     actors: [{
       userId: "1"
-      genres: [{ id: "2", name: "Обновлённый жанр" }, { name: "Новый жанр" }]
+      genres: [{ id: "2", name: "Updated genre" }, { name: "New genre" }]
     }]
   }) {
     actors { data { genres { data { id name } } } }
@@ -486,7 +491,7 @@ mutation {
 
 ### GraphQL
 
-Укажите `database.schema` и добавьте секцию `graphql: {}` в конфигурацию:
+Укажите `database.schema` и добавьте в конфигурацию `graphql: {}` вместе с `package.source`:
 
 ```sh
 npx deep-json-server server.config.js
@@ -497,7 +502,7 @@ npx deep-json-server server.config.js
 ```graphql
 query {
   userList(
-    where: { fullName: { contains: "Мира" } }
+    where: { fullName: { contains: "Mira" } }
     order: [{ field: fullName, direction: ASC }]
     pager: { page: 1, pageSize: 20 }
   ) {
@@ -506,7 +511,7 @@ query {
       id
       fullName
       movies(
-        where: { title: { contains: "Тени" } }
+        where: { title: { contains: "Shadows" } }
         order: [{ field: title, direction: ASC }]
         pager: { pageSize: 5 }
       ) {
@@ -526,7 +531,7 @@ query {
 
 ## OpenAPI и экспорт схем
 
-Экспорт использует OpenAPI 3.0.3. Добавьте `openapi: {}` и `database.schema`, чтобы получать спецификацию по HTTP на `/openapi.json`. Путь меняется через `openapi.endpoint`. Спецификацию можно открыть в Swagger UI или импортировать в API-клиент.
+Экспорт использует OpenAPI 3.0.3. Добавьте `openapi: {}`, `database.schema` и `package.source`, чтобы получать спецификацию по HTTP на `/openapi.json`. Путь меняется через `openapi.endpoint`. Поля OpenAPI `info.title`, `info.version` и необязательное `info.description` берутся из настроенного `package.json`. Спецификацию можно открыть в Swagger UI или импортировать в API-клиент.
 
 Для сохранения схем задайте пути экспорта:
 
@@ -536,6 +541,7 @@ export default {
   database: { source: './database.json', schema: './schema.json' },
   openapi: { target: './generated/openapi.yaml' },
   graphql: { target: './generated/schema.graphql' },
+  package: { source: './package.json' },
 };
 ```
 
@@ -713,7 +719,7 @@ OpenAPI описывает маршруты auth, необязательную B
 
 При включённом auth создавать записи может любой вошедший пользователь. Изменять, удалять и восстанавливать — владелец по `createdById` или пользователь с `isAdmin: true`. Записи без владельца изменяет только администратор. Его правки не меняют владельца. Правила действуют на вложенные записи, изменение ключей связей, каскады и восстановление. Ссылка на существующую запись без её изменения не требует владения ею. Каждая мутация атомарна: отказ сохраняет прежнее состояние всех затронутых записей.
 
-REST возвращает 401 при отсутствии действительного токена и 403 при недостатке прав. GraphQL проверяет мутации по тем же правилам и возвращает коды `UNAUTHENTICATED` или `FORBIDDEN`; токен получают через REST-вход и передают в `Authorization: Bearer <токен>`. GraphQL-запросы чтения, OPTIONS и все операции с файлами остаются открытыми.
+REST возвращает 401 при отсутствии действительного токена и 403 при недостатке прав. GraphQL проверяет мутации по тем же правилам и возвращает коды `UNAUTHENTICATED` или `FORBIDDEN`; токен получают через REST-вход и передают в `Authorization: Bearer <token>`. GraphQL-запросы чтения, OPTIONS и все операции с файлами остаются открытыми.
 
 ## Файлы
 
@@ -765,13 +771,13 @@ Content-Type: image/jpeg
 Сочетание `directory` и `name` идентифицирует файл. Повторная загрузка по существующему пути возвращает `409`. Чтобы заменить файл, передайте `Content-Override: true`; успешная перезапись возвращает `200`. Сервер поддерживает следующие файловые маршруты:
 
 ```text
-POST   /_files/storage      Загрузка или перезапись файла
-GET    /_files/storage/*    Просмотр содержимого файла
-PATCH  /_files/storage/*    Переименование или перемещение файла
-DELETE /_files/storage/*    Удаление файла
+POST   /_files/storage      Upload or replace a file
+GET    /_files/storage/*    Return file contents inline
+PATCH  /_files/storage/*    Rename or move a file
+DELETE /_files/storage/*    Delete a file
 
-GET    /_files/metadata/*   Получение метаданных в JSON
-GET    /_files/download/*   Скачивание файла
+GET    /_files/metadata/*   Return file metadata as JSON
+GET    /_files/download/*   Download a file as an attachment
 ```
 
 Для переименования, перемещения либо обеих операций отправьте JSON-объект. Нужно указать хотя бы одно поле:
@@ -808,7 +814,7 @@ await server.listen();
 
 Методы `openapi()` и `graphql()` возвращают схемы и требуют `database.schema`. `fastify()` возвращает экземпляр сервера для настройки и запуска. База и включённые сервисы инициализируются при `ready()`, `listen()` или первом `inject()`; ошибка инициализации останавливает запуск.
 
-`createServer(config)` принимает один аргумент. Наличие секций управляет модулями так же, как при запуске через CLI. Для методов `openapi()` и `graphql()` нужна соответствующая секция. Методы возвращают схему и не записывают файлы.
+`createServer(config)` принимает тот же объект конфигурации, что и CLI. При наличии `openapi` или `graphql` обязателен `package.source`. Для методов `openapi()` и `graphql()` нужна соответствующая секция. Методы возвращают схему и не записывают файлы.
 
 Эти функции доступны и через общий импорт `@kollors/deep-json-server`. Адаптеры сервера загружаются при включении. Генераторы можно использовать отдельно:
 
@@ -816,7 +822,7 @@ await server.listen();
 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 document = await generateOpenapi('./schema.json', { files: true, packagePath: './package.json' });
 const sdl = await generateGraphql('./schema.json');
 await writeOpenapi(document, './generated/openapi.yaml');
 await writeGraphql(sdl, './generated/schema.graphql');
@@ -824,11 +830,11 @@ await writeGraphql(sdl, './generated/schema.graphql');
 
 Отдельные генераторы принимают путь или объект схемы и не требуют конфигурации сервера. Выбранная функция задаёт формат по умолчанию; `api` у модели может его ограничить. `timestamps` и `softDelete` берутся из схемы. Опция `{ auth: true }` добавляет поля владельца и `actions`; OpenAPI также описывает маршруты auth и требования токена. `hashPassword()` доступна и через общий импорт пакета.
 
-`generateOpenapi()` также принимает `host`, `port`, `pageSize`, `maxPageSize` и `info`. Вместо пути можно передать объект схемы. Сервер и генераторы работают с собственной копией модели. Размеры страниц должны быть положительными целыми числами; `pageSize` не может превышать `maxPageSize`.
+Для `generateOpenapi()` обязателен `packagePath`; дополнительно доступны `host`, `port`, `pageSize` и `maxPageSize`. Метаданные OpenAPI читаются из указанного пакета. Вместо пути можно передать объект схемы. Сервер и генераторы работают с собственной копией модели. Размеры страниц должны быть положительными целыми числами; `pageSize` не может превышать `maxPageSize`.
 
 ## Хранение данных
 
-Изменения выполняются последовательно внутри экземпляра сервера и проверяются на копии данных до сохранения. Для одного файла базы используйте один процесс сервера. Счётчики `increment` хранятся рядом с базой в `<путь базы>.counters.json`; сохраняйте этот файл вместе с базой. Номера резервируются до записи данных: сбой может оставить пропуск, но не приводит к повторной выдаче номера.
+Изменения выполняются последовательно внутри экземпляра сервера и проверяются на копии данных до сохранения. Для одного файла базы используйте один процесс сервера. Счётчики `increment` хранятся рядом с базой в `<database path>.counters.json`; сохраняйте этот файл вместе с базой. Номера резервируются до записи данных: сбой может оставить пропуск, но не приводит к повторной выдаче номера.
 
 ## Разработка
 
@@ -839,8 +845,8 @@ npm ci
 npm run verify
 ```
 
-Команда проверяет типы, стиль кода, покрытие тестами и установку пакета из архива.
+`npm run verify` проверяет типы, стиль кода, покрытие тестами и установку пакета из архива.
 
-Для публикации предварительной версии обновите номер в `package.json`, `package-lock.json` и `src/core/constants.ts`, затем отправьте коммит в `main`. GitHub Actions создаст тег `v<версия>` и опубликует пакет через trusted publishing в канал `alpha`, `beta` или `rc`. Стабильные версии публикуются в `latest` из явно отправленного тега версии.
+Для публикации предварительной версии обновите номер в `package.json`, `package-lock.json` и `src/core/constants.ts`, затем отправьте коммит в `main`. GitHub Actions создаст тег `v<version>` и опубликует пакет через trusted publishing в канал `alpha`, `beta` или `rc`. Стабильные версии публикуются в `latest` из явно отправленного тега версии.
 
 Лицензия: MIT.