@kollors/deep-json-server 1.0.0-alpha.9 → 1.0.0-beta.2

package/README.md

@@ -4,15 +4,15 @@
 
 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.
 
-**1.0.0-alpha.9 is a prerelease.** When upgrading from the previous alpha, add `storage`, use `source` for data sources, move definitions under `models`, and move timestamps and soft deletion settings to the schema root. Configuration sections now enable modules; use `--generate` or `--generate-only` for exports. The second `createServer` argument has been removed.
+**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.
 
 ## Installation
 
 ```sh
-npm install @kollors/deep-json-server@alpha
+npm install @kollors/deep-json-server@beta
 ```
 
-To install a specific version, use `@1.0.0-alpha.9`.
+To install a specific version, use `@1.0.0-beta.2`.
 
 ## Quick start
 
@@ -44,7 +44,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: {}` use the default endpoints.
+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.
 
 ```js
 export default {
@@ -52,8 +52,8 @@ export default {
   database: { source: './database.json', schema: './schema.json' },
   auth: { source: './users.json', expiresIn: 3600 },
   files: { source: './uploads' },
-  graphql: { path: './generated/schema.graphql' },
-  openapi: { path: './generated/openapi.yaml' },
+  graphql: { target: './generated/schema.graphql' },
+  openapi: { target: './generated/openapi.yaml' },
   server: { host: '127.0.0.1', port: 4001 },
 };
 ```
@@ -66,11 +66,11 @@ export default {
 | `auth.source` | Users JSON path or user array |
 | `auth.expiresIn` | Session lifetime in seconds; default 3600 |
 | `files.source` | Files directory or initial file array |
-| `files.metadata` | For `file` only: metadata JSON path; defaults to `_database.json` inside `files.source` |
+| `files.metadata` | For `file` only: metadata JSON path; defaults to `.files.json` inside `files.source` |
 | `graphql.endpoint` | HTTP endpoint; default `/graphql` |
-| `graphql.path` | GraphQL SDL export destination |
+| `graphql.target` | GraphQL SDL export destination |
 | `openapi.endpoint` | HTTP endpoint; default `/openapi.json` |
-| `openapi.path` | OpenAPI export destination |
+| `openapi.target` | OpenAPI export destination |
 | `openapi.info` | Metadata: required `title` and `version`, optional `description` |
 | `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 |
@@ -154,7 +154,7 @@ Model definitions belong in `models`. The schema root can define `api`, `timesta
 
 Explicit schemas are strict: undeclared fields and collections are rejected, except storage keys inferred from relations. Existing data is validated on startup. Generation uses the model definitions.
 
-Schemaless REST generates an `id` and preserves arbitrary JSON fields. Filters and individual field selections use identifier-style names; other fields are returned through `scope=[{"*":true}]`. Fields with mixed value types can be read, but filtering, ordering and paging heterogeneous lists require an explicit schema.
+Schemaless REST generates an `id` and preserves arbitrary JSON fields. 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.
 
@@ -212,6 +212,110 @@ Every supplied direct relation key must point to an existing record. `required:
 
 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.
 
+## Example database
+
+```json
+{
+  "countries": [
+    {
+      "id": "1",
+      "isArchived": false,
+      "name": "Ардения"
+    },
+    {
+      "id": "2",
+      "isArchived": false,
+      "name": "Велория"
+    }
+  ],
+  "genres": [
+    {
+      "id": "1",
+      "isArchived": false,
+      "name": "Криминал",
+      "parentIds": []
+    },
+    {
+      "id": "2",
+      "isArchived": false,
+      "name": "Гангстер",
+      "parentIds": ["1"]
+    },
+    {
+      "id": "3",
+      "isArchived": false,
+      "name": "Драма",
+      "parentIds": []
+    },
+    {
+      "id": "4",
+      "isArchived": false,
+      "name": "Комедия",
+      "parentIds": []
+    }
+  ],
+  "movies": [
+    {
+      "actors": [
+        {
+          "genreIds": ["2", "3"],
+          "id": "movie-1-actor-1",
+          "userId": "1"
+        },
+        {
+          "genreIds": ["3"],
+          "id": "movie-1-actor-2",
+          "userId": "2"
+        }
+      ],
+      "coverSrc": "https://example.com/covers/shadows-of-ardenia.jpg",
+      "description": "Наследница портового города раскрывает заговор двух соперничающих семей.",
+      "id": "1",
+      "isArchived": false,
+      "publisherIds": ["2"],
+      "title": "Тени Ардении"
+    },
+    {
+      "actors": [],
+      "coverSrc": "https://example.com/covers/northern-star.jpg",
+      "description": "Ночной администратор старого отеля случайно становится участником поисков пропавшей картины.",
+      "id": "2",
+      "isArchived": false,
+      "publisherIds": ["1"],
+      "title": "Полночь в «Северной звезде»"
+    }
+  ],
+  "publishers": [
+    {
+      "id": "1",
+      "isArchived": false,
+      "name": "Northlight Studio"
+    },
+    {
+      "id": "2",
+      "isArchived": false,
+      "name": "Aurora Pictures"
+    }
+  ],
+  "users": [
+    {
+      "bornAt": "1988-03-14",
+      "countryId": "1",
+      "fullName": "Мира Волкова",
+      "id": "1",
+      "isArchived": false
+    },
+    {
+      "bornAt": "1991-11-02",
+      "countryId": "2",
+      "fullName": "Леон Ветров",
+      "id": "2",
+      "isArchived": false
+    }
+  ]
+}
+```
+
 ## Queries and responses
 
 The movie, actor and genre examples use the full [example schema](examples/schema.json). Run them with the [example configuration](examples/server.config.js):
@@ -293,7 +397,7 @@ const params = new URLSearchParams({ scope: JSON.stringify(scope) });
 const response = await fetch(`/users?${params}`);
 ```
 
-Select ordinary fields with `true` and objects or relations with their own scope arrays. Without arguments, the array contains only the fields object. `"*": true` includes own fields and stored keys, except `writeOnly` fields; select relations explicitly.
+Select scalars and primitive arrays with `true`, and objects or relations with their own scope arrays. Without arguments, the array contains only the fields object. `"*": true` includes only scalar fields of the current model that do not store relation keys. Arrays, objects, relations, their keys and `writeOnly` fields are not included by the wildcard. A relation key remains available through an explicit selection such as `{ "*": true, "countryId": true }`. Without a schema, a key is excluded from `*` only when the server can infer its relation from the name and an existing collection.
 
 For example, select a movie's own fields, its actors' users and sorted genres:
 
@@ -314,9 +418,9 @@ For example, select a movie's own fields, its actors' users and sorted genres:
 ]
 ```
 
-Omitting `scope` returns own fields, as with `[{"*":true}]`. An empty selection `[{}]` returns an object without fields. Lists retain the `{ data, total }` response structure.
+Omitting `scope` returns scalar fields, as with `[{"*":true}]`. An empty selection `[{}]` returns an object without fields. Lists retain the `{ data, total }` response structure.
 
-Arguments are available only on lists. Single-record queries and mutation responses can set arguments on their embedded lists. Parameters are validated even on empty data; an invalid response selection rolls back record changes. Invalid scopes return `400`. The JSON length limit is 10,000 characters; selection depth is limited to 32 levels.
+Arguments are available only on lists. A list can instead use `{ "union": [scope, ...] }`: each part is a normal list scope, parts run in array order, and the first record for each primary key is kept. This also works for nested lists. Single-record queries and mutation responses can set arguments on their embedded lists. Parameters are validated even on empty data; an invalid response selection rolls back record changes. Invalid scopes return `400`. The JSON length limit is 10,000 characters; selection depth is limited to 32 levels.
 
 ### Nested writes
 
@@ -350,7 +454,16 @@ The key name and type follow the target model. An object containing only a key s
 
 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 relations must remain populated.
 
-Use either the relation field or its storage key in an object, for example `genres` or `genreIds`. 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.
+Use either the relation field or its storage 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"]
+}
+```
+
+The server neither gives one field priority nor merges the values; the entire operation is rolled back. 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.
 
@@ -419,8 +532,8 @@ Set output paths to save schemas:
 export default {
   storage: 'file',
   database: { source: './database.json', schema: './schema.json' },
-  openapi: { path: './generated/openapi.yaml' },
-  graphql: { path: './generated/schema.graphql' },
+  openapi: { target: './generated/openapi.yaml' },
+  graphql: { target: './generated/schema.graphql' },
 };
 ```
 
@@ -429,9 +542,9 @@ 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 `path`. Missing sections, missing destinations 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`. Missing sections, missing targets or generation errors fail the command before server startup.
 
-Export reads only the schema. Database records, auth users and file storage are not opened; configuration values are still validated. The schema is loaded once, including when export is followed by startup. All destinations and selected schemas are checked before writing. Outputs cannot overwrite the configuration, database, schema, users, counters or file metadata. A disk write failure can leave an already saved file from another format.
+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.
 
 ## Authentication
 
@@ -487,7 +600,7 @@ export default {
 };
 ```
 
-Auth users are stored separately from database collections. With `storage: 'file'`, registration, password changes and admin changes are saved to `auth.source` through `lowdb`. With `'memory'`, changes stay in an internal copy and disappear on restart; the original array is unchanged. A file write failure leaves users and sessions unchanged. The file is read at startup; restart after manual edits.
+Auth users are stored separately from the database. In file mode, changes are saved to `auth.source`; in memory mode, they disappear on restart. The supplied user array is not modified. Restart the server after editing the file manually.
 
 | REST request | JSON body | Response |
 |---|---|---|
@@ -506,7 +619,39 @@ Only administrators can change `isAdmin`. They can grant or remove another user'
 
 Invalid or expired tokens return `401`, insufficient permissions return `403`, and an absent user for an otherwise permitted operation returns `404`. Invalid request bodies return `400`. Login, registration and password changes may return `429` when too many password computations are running; login also limits active sessions. Sessions are kept in memory and disappear on restart. Logout revokes only the supplied token.
 
-OpenAPI describes all auth routes and their Bearer token requirements. 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 changing records. GraphQL and OpenAPI require `database.schema`.
+Every model record has a virtual `actions` object when auth is enabled. It is calculated for the current user and is never stored. In REST, request it explicitly through `scope`:
+
+```json
+[
+  {
+    "id": true,
+    "actions": [{ "*": true }]
+  }
+]
+```
+
+The object contains `update`, `replace` and `delete`. An owner or administrator receives `true`; an anonymous or unrelated user receives `false`. Records without `createdById` are editable only by administrators. A missing token keeps reads public and returns false flags. A supplied invalid token returns `401` in REST or `UNAUTHENTICATED` in GraphQL.
+
+GraphQL exposes the same field and requires its normal explicit selection:
+
+```graphql
+query {
+  itemList {
+    data {
+      id
+      actions {
+        update
+        replace
+        delete
+      }
+    }
+  }
+}
+```
+
+`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`.
 
 ## Record dates, deletion and ownership
 
@@ -576,7 +721,7 @@ Files are available through REST and documented in OpenAPI. Add storage to the c
 export default {
   storage: 'file',
   database: { source: './database.json' },
-  files: { source: './uploads', metadata: './files.json' },
+  files: { source: './uploads' },
 };
 ```
 
@@ -639,7 +784,7 @@ Content-Type: application/json
 
 `PATCH` returns the updated metadata with status `200`; if a file already exists at the new path, the server returns `409`. `DELETE` returns `204` without a response body. A missing file returns `404` on every path-based operation. File paths in URLs are relative to `files.source`, and all returned URLs are relative to the server origin.
 
-In disk mode, the binary is stored at `<files.source>/<directory>/<name>`. Metadata stores `directory`, `mimeType` and `name`; the server reads the size from the file and builds its URLs. Directories and the metadata file are created when needed.
+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. Stop it before editing stored files or metadata manually. Storage paths cannot contain symbolic links. Uploads and renames cannot overwrite the database, counters, schema, auth users, loaded configuration or metadata file.
 
@@ -673,114 +818,10 @@ 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; schema and model `api` settings can restrict it. Timestamps and soft deletion come from the schema. `{ auth: true }` adds ownership 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. The selected function supplies the default format; schema and model `api` settings 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`.
 
-## Example database
-
-```json
-{
-  "countries": [
-    {
-      "id": "1",
-      "isArchived": false,
-      "name": "Ардения"
-    },
-    {
-      "id": "2",
-      "isArchived": false,
-      "name": "Велория"
-    }
-  ],
-  "genres": [
-    {
-      "id": "1",
-      "isArchived": false,
-      "name": "Криминал",
-      "parentIds": []
-    },
-    {
-      "id": "2",
-      "isArchived": false,
-      "name": "Гангстер",
-      "parentIds": ["1"]
-    },
-    {
-      "id": "3",
-      "isArchived": false,
-      "name": "Драма",
-      "parentIds": []
-    },
-    {
-      "id": "4",
-      "isArchived": false,
-      "name": "Комедия",
-      "parentIds": []
-    }
-  ],
-  "movies": [
-    {
-      "actors": [
-        {
-          "genreIds": ["2", "3"],
-          "id": "movie-1-actor-1",
-          "userId": "1"
-        },
-        {
-          "genreIds": ["3"],
-          "id": "movie-1-actor-2",
-          "userId": "2"
-        }
-      ],
-      "coverSrc": "https://example.com/covers/shadows-of-ardenia.jpg",
-      "description": "Наследница портового города раскрывает заговор двух соперничающих семей.",
-      "id": "1",
-      "isArchived": false,
-      "publisherIds": ["2"],
-      "title": "Тени Ардении"
-    },
-    {
-      "actors": [],
-      "coverSrc": "https://example.com/covers/northern-star.jpg",
-      "description": "Ночной администратор старого отеля случайно становится участником поисков пропавшей картины.",
-      "id": "2",
-      "isArchived": false,
-      "publisherIds": ["1"],
-      "title": "Полночь в «Северной звезде»"
-    }
-  ],
-  "publishers": [
-    {
-      "id": "1",
-      "isArchived": false,
-      "name": "Northlight Studio"
-    },
-    {
-      "id": "2",
-      "isArchived": false,
-      "name": "Aurora Pictures"
-    }
-  ],
-  "users": [
-    {
-      "bornAt": "1988-03-14",
-      "countryId": "1",
-      "fullName": "Мира Волкова",
-      "id": "1",
-      "isArchived": false
-    },
-    {
-      "bornAt": "1991-11-02",
-      "countryId": "2",
-      "fullName": "Леон Ветров",
-      "id": "2",
-      "isArchived": false
-    }
-  ]
-}
-```
-
 ## Data storage
 
 Updates run sequentially within one server instance and are validated on a copy of the data before saving. Use one server process per database file. `increment` counters are stored next to the database in `<database path>.counters.json`; keep that file with the database. Numbers are reserved before the data write, so a failed write can leave gaps but cannot reuse a reserved number.
@@ -796,6 +837,6 @@ npm run verify
 
 The command checks types, code style, test coverage and installation from the package archive.
 
-To publish a new alpha, update the version in `package.json`, `package-lock.json` and `src/core/constants.ts`, then push to `main`. GitHub Actions creates the version tag and publishes to npm `alpha` through trusted publishing. Already published versions are skipped. If the tag exists but publication failed, a retry uses that tag and verifies that the package files match it. Pushing a version tag also triggers publication; stable versions publish to `latest`.
+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.
 
 License: MIT.