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

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 1.0.0-rc.2
+
+- Added root schema `api` to select REST, GraphQL, or both for database routes, and per-model `api` selection with matching formats. Authentication and file routes remain REST endpoints; OpenAPI includes only enabled REST routes.
+- GraphQL-only server configurations no longer require package metadata. OpenAPI keeps authentication and file routes when no database model enables REST.
+- Added installed-package coverage for per-model API selection and checks for code examples in both READMEs.
+
+## 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.2
+
+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.2 |
+|---|---|
+| `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; 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.
+
+## 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.6`.
+To install this release candidate, use `@1.0.0-rc.2`.
 
 ## 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` or `files` to enable those REST services. Add `graphql` to configure the GraphQL endpoint and `openapi` to serve the REST specification. `graphql: {}` and `openapi: {}` use default endpoint paths; add `target` to export a schema. GraphQL must also be enabled by root `api` in the model schema.
 
 ```js
 export default {
@@ -72,7 +74,7 @@ export default {
 | `graphql.target` | GraphQL SDL export destination |
 | `openapi.endpoint` | HTTP endpoint; default `/openapi.json` |
 | `openapi.target` | OpenAPI export destination |
-| `package.source` | Project `package.json`; required when `openapi` or `graphql` is configured |
+| `package.source` | Project `package.json`; required when `openapi` 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 |
@@ -82,6 +84,36 @@ export default {
 
 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.
 
+To expose the database only through GraphQL while keeping authentication and files as REST endpoints documented by OpenAPI, use:
+
+```js
+export default {
+  storage: 'file',
+  database: { source: './database.json', schema: './schema.json' },
+  auth: { source: './users.json' },
+  files: { source: './uploads' },
+  graphql: {},
+  openapi: {},
+  package: { source: './package.json' },
+};
+```
+
+Set the root `api` in `schema.json`:
+
+```json
+{
+  "api": ["graphql"],
+  "models": {
+    "Item": {
+      "collection": "items",
+      "fields": { "id": { "type": "string", "primary": true } }
+    }
+  }
+}
+```
+
+Use `"api": ["rest"]` with `openapi: {}` for REST and its OpenAPI description, or `["rest", "graphql"]` with both sections for both database APIs. The `graphql` section is required exactly when the schema root includes `graphql`. OpenAPI describes database routes only when REST is enabled; authentication and file routes are included whenever their sections are configured.
+
 ### CLI
 
 | Flag | Action |
@@ -101,10 +133,7 @@ Examples: [database](examples/database.json), [model schema](examples/schema.jso
 
 ```json
 {
-  "api": [
-    "openapi",
-    "graphql"
-  ],
+  "api": ["rest", "graphql"],
   "models": {
     "Country": {
       "collection": "countries",
@@ -146,7 +175,11 @@ Examples: [database](examples/database.json), [model schema](examples/schema.jso
 }
 ```
 
-Model definitions belong in `models`. The schema root can define `timestamps` and `softDelete`; a model can override each setting. The `openapi` and `graphql` configuration sections enable the corresponding API. A model's `api` array only limits these enabled formats: `[]` excludes the model from GraphQL and OpenAPI while REST remains available. If no model enables a requested format, generation fails with a clear error. Related models must allow the same format. 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, 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.
+
+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.
+
+An excluded model remains part of the database schema and its stored records are still validated. Its `api` setting controls how clients can access it.
 
 | Capability | With schema | Without schema |
 |---|---|---|
@@ -159,7 +192,7 @@ Explicit schemas are strict: undeclared fields and collections are rejected, exc
 
 Schemaless REST generates an `id` and preserves arbitrary JSON fields. Newly inferred relations are available to subsequent reads and writes without restarting the server. Filters and individual field selections use identifier-style names. `scope=[{"*":true}]` returns top-level JSON scalars; arrays and objects must be selected by name. Fields with mixed value types can be read explicitly, but filtering, ordering and paging heterogeneous lists require an explicit schema.
 
-Each model requires `collection`, the database collection and REST path name, and `fields`, its field definitions. The model name (`User`) determines GraphQL type and operation names. `api` controls format availability; `timestamps` and `softDelete` override global settings for that model.
+Each model requires `collection` (the database collection name, also used as its REST path when REST is enabled) and `fields` (field definitions). The model name (`User`) determines GraphQL type and operation names. `api` controls route availability; `timestamps` and `softDelete` override global settings for that model.
 
 ### Fields
 
@@ -225,37 +258,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": []
     }
   ],
@@ -274,20 +307,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": [
@@ -306,14 +339,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
     }
@@ -361,7 +394,7 @@ Root `where` selects records from the main collection. `where` inside a relation
 
 ### REST
 
-`GET /` returns collection names: `{ "resources": ["users", "movies"] }`. Each collection has these routes:
+When REST is enabled by root `api`, `GET /` lists only REST-enabled models: `{ "resources": ["users", "movies"] }`. A GraphQL-only server has no `GET /` database route. Each REST-enabled collection has these routes:
 
 | Method | Path | Operation |
 |---|---|---|
@@ -393,7 +426,7 @@ const scope = [
     ],
   },
   {
-    where: { fullName: { contains: 'Мира' } },
+    where: { fullName: { contains: 'Mira' } },
     order: [{ field: 'fullName', direction: 'ASC' }],
     pager: { page: 1, pageSize: 20 },
   },
@@ -468,7 +501,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.
 
@@ -489,7 +522,7 @@ mutation {
 
 ### GraphQL
 
-Set `database.schema` and add `graphql: {}` plus `package.source` to the configuration:
+Set `database.schema`, include `graphql` in the schema's root `api`, and add `graphql: {}` to the configuration:
 
 ```sh
 npx deep-json-server server.config.js
@@ -500,7 +533,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 }
   ) {
@@ -509,7 +542,7 @@ query {
       id
       fullName
       movies(
-        where: { title: { contains: "Тени" } }
+        where: { title: { contains: "Shadows" } }
         order: [{ field: title, direction: ASC }]
         pager: { pageSize: 5 }
       ) {
@@ -529,7 +562,7 @@ Errors include `extensions.code`: `INVALID_INPUT`, `INVALID_QUERY`, `NOT_FOUND`,
 
 ## OpenAPI and schema exports
 
-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.
+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`. Database paths appear only for REST-enabled models; a GraphQL-only database can still produce a document for configured auth and file routes. 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:
 
@@ -548,7 +581,7 @@ npx deep-json-server server.config.js --generate-only
 npx deep-json-server server.config.js --generate
 ```
 
-`--generate-only` exports and exits; `--generate` starts the server after exporting. Configuration sections select the formats. Each selected format requires its own `target`. Missing sections, missing targets or generation errors fail the command before server startup.
+`--generate-only` exports and exits; `--generate` starts the server after exporting. Configuration sections select the formats. Each selected format requires its own `target`. The OpenAPI HTTP endpoint returns JSON; file exports from `writeOpenapi()` and the CLI are YAML. Missing sections, missing targets or generation errors fail the command before server startup.
 
 Export does not open the database, user records or files. Every selected `target` is checked before writing and cannot overwrite the configuration, database, schema, users, counters or file metadata.
 
@@ -657,7 +690,7 @@ query {
 
 `actions` is available on root and related model records, including mutation results. It cannot be written, filtered or ordered. Plain embedded objects and auth user responses do not receive it.
 
-OpenAPI describes auth routes, optional Bearer authentication on record reads, required authentication on record changes and the `actions` response field. In Swagger UI, paste a token from login into **Authorize**. For schema exports, enable auth in the configuration and run `npx deep-json-server server.config.js --generate-only`; the users file is not read during generation. Auth methods are exposed through REST. GraphQL checks the same token when reading permissions or changing records. GraphQL and OpenAPI require `database.schema`.
+When `openapi` is configured, its document describes auth routes, optional Bearer authentication on record reads, required authentication on record changes and the `actions` response field. In Swagger UI, paste a token from login into **Authorize**. For schema exports, enable auth in the configuration and run `npx deep-json-server server.config.js --generate-only`; the users file is not read during generation. Auth methods are exposed through REST. GraphQL checks the same token when reading permissions or changing records. GraphQL and OpenAPI require `database.schema`.
 
 ## Record dates, deletion and ownership
 
@@ -721,7 +754,7 @@ REST returns 401 for an invalid or missing token and 403 for insufficient permis
 
 ## Files
 
-Files are available through REST and documented in OpenAPI. Add storage to the configuration:
+Files are available through REST and appear in the OpenAPI document when `openapi` is configured. Add storage to the configuration:
 
 ```js
 export default {
@@ -812,7 +845,9 @@ 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 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.
+`createServer(config)` takes the same configuration object as the CLI. When `openapi` is configured, `package.source` is required. The `openapi()` and `graphql()` methods require their respective sections. They return schemas without writing files.
+
+The returned Fastify instance accepts standard `listen()` options, including a Unix socket path. Calling `listen()` without options uses `server.host` and `server.port`.
 
 The root import `@kollors/deep-json-server` also provides these functions. Server adapters load when enabled. Generators can be used independently:
 
@@ -826,7 +861,7 @@ await writeOpenapi(document, './generated/openapi.yaml');
 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.
+Standalone generators accept a schema path or object without a server configuration. If root `api` is omitted, `generateOpenapi()` defaults it to REST and `generateGraphql()` to GraphQL. Explicit root and model `api` values still apply; the selected format must have an enabled model. 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()` 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`.
 
@@ -836,14 +871,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.