@kollors/deep-json-server 0.8.1 → 1.0.0-alpha.1

package/README.md

@@ -1,206 +1,359 @@
 # Deep JSON Server
 
-[English](README.md) | [Русский](README.ru.md)
+[Русский](README.ru.md)
 
-[GitHub](https://github.com/kollors/deep-json-server) | [npm](https://www.npmjs.com/package/@kollors/deep-json-server)
+A JSON-backed mock server with REST, GraphQL, nested queries, binary files and schema exports. Requires Node.js 22 or newer.
 
-A small REST API mock server with CRUD, pagination, nested data filtering, relation embedding through `_embed`, binary files, and OpenAPI generation. Data can be stored in JSON files or memory, and relations are inferred from field names such as `countryId`, `genreIds`, and `publisherIds`.
+**1.0.0-alpha.1 is a breaking prerelease.** The old `$schema`/`$info` model format and `_where`, `_sort`, `_embed`, `_page`, `_perPage` query parameters are no longer supported.
 
 ## Installation
 
-Node.js 20 or newer is required.
-
-```bash
-npm install --save-dev @kollors/deep-json-server
+```sh
+npm install @kollors/deep-json-server@alpha
 ```
 
+The `alpha` npm channel is separate from `latest`. Install an exact version with `@1.0.0-alpha.1`.
+
 ## Quick start
 
-Create the database file `mock/database.json` before startup:
+`server.config.js`:
+
+```js
+export default {
+  database: { path: './database.json', schema: './schema.json' },
+  graphql: { enabled: true, path: './generated/schema.graphql' },
+  openapi: { path: './generated/openapi.yaml' },
+  server: { host: '127.0.0.1', port: 4001, pageSize: 10, maxPageSize: 100 },
+};
+```
+
+```sh
+npx deep-json-server server.config.js
+npx deep-json-server --openapi-only --graphql-only server.config.js
+```
+
+The second command exports both schemas without listening on a port. Starting the server alone does not write schema files.
+
+Complete catalog examples: [database](examples/database.json), [model schema](examples/schema.json), [configuration](examples/server.config.js).
+
+## Configuration
+
+| Setting | Meaning |
+|---|---|
+| `database.path` / `database.data` | Exactly one: JSON file or in-memory collection object |
+| `database.schema` | Model object or JSON schema-file path; optional for REST |
+| `openapi.path` | YAML export destination |
+| `openapi.info` | Optional `title`, `version`, `description` |
+| `graphql.enabled` | Enable GraphQL HTTP endpoint; default `false` |
+| `graphql.endpoint` | Endpoint path; default `/graphql` |
+| `graphql.path` | GraphQL SDL export destination |
+| `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 |
+| `files.data` | In-memory binary files |
+| `files.directory`, `files.metadata` | Disk storage directory and metadata JSON file; both required |
+
+Configuration-file paths resolve relative to that file. Direct `createServer()` paths resolve relative to the working directory. In-memory input is copied.
+
+CLI flags:
+
+| Flag | Action |
+|---|---|
+| `--files` | Enable binary-file routes |
+| `--graphql` | Enable GraphQL endpoint |
+| `--openapi` | Export OpenAPI and start |
+| `--openapi-only` | Export OpenAPI without starting |
+| `--graphql-schema` | Export GraphQL SDL and start |
+| `--graphql-only` | Export GraphQL SDL without starting |
+| `--help` | Show usage |
+
+Both exporters can be combined. Any `--*-only` flag prevents startup. CLI file routes require `--files`; programmatic use enables them when `files` is configured unless overridden through the second `createServer()` argument.
+
+## Model schema
 
 ```json
 {
-  "movies": [
-    { "id": "1", "title": "Shadows of Ardenia" }
-  ]
+  "Country": {
+    "collection": "countries",
+    "api": ["openapi", "graphql"],
+    "fields": {
+      "id": { "type": "string", "primary": true, "generated": "uuid" },
+      "name": { "type": "string", "required": true },
+      "users": { "type": "User[]", "target": "countryId" }
+    }
+  },
+  "User": {
+    "collection": "users",
+    "api": ["openapi", "graphql"],
+    "fields": {
+      "id": { "type": "string", "primary": true, "generated": "uuid" },
+      "fullName": { "type": "string", "required": true },
+      "country": { "type": "Country", "source": "countryId" }
+    }
+  }
 }
 ```
 
-Create the ESM module `server.config.js` next to `package.json`:
+`api` defaults to `["openapi", "graphql"]`. `[]` excludes the model from both exports and GraphQL, while REST remains available. Related models must enable the same export format. Names must be valid identifiers and generated type/operation names must not collide. `and`, `or`, `not` are reserved filter names.
 
-```js
-export default {
-  database: {
-    path: 'mock/database.json',
-  },
-};
+| Capability | With schema | Without schema |
+|---|---|---|
+| REST CRUD | Model validation | JSON/body/identifier validation only |
+| Relations | Explicit model fields | `countryId`, `genreIds`, etc. naming conventions |
+| OpenAPI 3.0.3 export | Available | Error when requested |
+| GraphQL SDL / API | Available | Error when requested |
+
+Explicit schemas are strict: undeclared fields and collections are rejected, except storage keys inferred from relations. Existing data is validated on startup. Schemas can be exported for empty collections or an empty database object. REST without a schema retains the standard generated `id` behavior.
+
+### Fields
+
+Types: `string`, `number`, `boolean`, `object`, or a model name. Append `[]` for an array. No `integer`, `relation`, `items`, or multidimensional type strings. Nested fields use full dotted paths, for example `actors.fullName`. Objects inside arrays may contain their own arrays.
+
+| Properties | Meaning |
+|---|---|
+| `type` | Required type |
+| `description`, `example` | Documentation and example value |
+| `required`, `nullable` | Defaults `false`; presence and explicit null are separate |
+| `default` | Value when omitted on create/replace; PATCH does not insert defaults |
+| `enum` | Allowed values; for arrays, allowed element values |
+| `primary` | Root primary key; mandatory, unique, non-null and immutable |
+| `generated` | `uuid` for strings, `increment` for numbers; server supplies the value |
+| `readOnly`, `writeOnly` | Output-only or input-only; mutually exclusive |
+| `minLength`, `maxLength`, `pattern` | String constraints |
+| `format` | `date`, `date-time`, `email`, `uri`, `uuid` |
+| `minimum`, `maximum` | Inclusive numeric bounds |
+| `source`, `target`, `onDelete` | Relation metadata |
+
+String/numeric constraints on `string[]`/`number[]` apply to every element. `required`/`nullable` apply to the entire array, and `default`/`example` contain a complete array. Array elements are non-null. There are no item-count or uniqueness constraints. A required ordinary array may be empty.
+
+Primary keys can be named `username`, `code`, etc.; exactly one root string/number primary key is required. Without `generated`, the client supplies it during creation. Generated fields are root fields, absent from create/replace/update input; they cannot have `default`. Replace preserves generated and read-only root values.
+
+For example, a `LocalUser` with primary `username` and `password: {"type":"string","required":true,"writeOnly":true}` has `localUser(username: ...)` and `/localUsers/{username}`. `writeOnly` excludes passwords from responses, scope, filters and ordering. It does not implement hashing or authentication.
+
+### Relations
+
+```json
+"actors.genres": {
+  "type": "Genre[]",
+  "source": "actors.genreIds",
+  "required": true
+}
 ```
 
-Start the server:
+`Genre` produces an object; `Genre[]` produces a list. `source` defaults to the current model's primary key, `target` to the target model's primary key. Both paths are rooted at their respective records. Within `actors`, `actors.genreIds` reads the current actor's IDs. An omitted `source` still means the root model key, not `actors.id`.
 
-```bash
-npx deep-json-server server.config.js
+Storage keys remain in the database and are included among own fields. Their types can be inferred from the target key. For an undeclared source pointing to a target primary key, a list relation implies an array of keys; a single relation implies a scalar key. Declare storage fields explicitly when the mapping is ambiguous. Generation never guesses from the first database record.
+
+Reverse example: `User.movies = {"type":"Movie[]","target":"actors.userId"}`. A movie is returned once even if several actors match. A single relation resolving to multiple targets is invalid.
+
+Every supplied direct reference must resolve. `required: true` on a relation requires at least one target before response filtering/pagination. Reverse views with a primary source may be empty unless required. Missing single relations return `null`.
+
+`onDelete` describes what happens **when a target record is deleted**:
+
+- `restrict` (default): refuse deletion while a surviving owner refers to the target.
+- `cascade`: delete the referring owner. For `User.country`, deleting the country deletes its users. For `Movie.actors.user`, deleting the user removes matching actor elements and retains the movie.
+
+Deletion computes the cascade closure, handles cycles, checks restrictions and validates remaining data before committing. A failure cancels the complete operation. Policies also apply to explicitly declared reverse relation views; configure both directions deliberately when both are present.
+
+## Queries and responses
+
+Collections and lists of objects, including embedded `object[]` fields, return:
+
+```json
+{ "data": [], "total": 0 }
 ```
 
-The API is available at `http://127.0.0.1:4001` by default. For example, `GET http://127.0.0.1:4001/movies` returns this page:
+Primitive arrays remain plain arrays. Every object list accepts optional `where`, `order`, `pager`. Processing order is filter → sort → pagination. `total` is the filtered count before pagination. Page numbers start at 1; default pagination applies even when omitted. Exceeding `maxPageSize`, fractional values and nonpositive values are errors. Out-of-range pages return empty `data` with the correct `total`.
+
+`where` uses field operators `eq`, `ne`, `in`, string `contains`/`startsWith`/`endsWith`, and comparisons `gt`, `gte`, `lt`, `lte`. Logical composition uses `and`, `or`, `not`. Arrays support `some`, `every`, `none`; primitive arrays also support `contains`, `in`. String matching is case-insensitive. Field filters use operator objects, not shorthand scalar values.
 
 ```json
 {
-  "data": [{ "id": "1", "title": "Shadows of Ardenia" }],
-  "total": 1
+  "movies": {
+    "some": {
+      "actors": {
+        "some": {
+          "genres": { "some": { "id": { "in": ["2", "3"] } } }
+        }
+      }
+    }
+  }
 }
 ```
 
-## Configuration and startup
+Root filters choose parents. Filters inside a selected relation only trim that relation; they do not remove the parent. Each parent's child list is processed independently. Filtering does not require a relation to be included in the response.
 
-Create the ESM module `server.config.js`. The example below shows settings for every feature:
-
-```js
-import process from 'node:process';
+`order` is an array of `{ "field": "fullName", "direction": "ASC" }` rules. Earlier rules have priority; complete ties retain storage order. Null and missing values compare equally. REST uses dotted field paths; GraphQL uses generated enums (`profile_name` for `profile.name`). Ambiguous enum names cause a generation error. Sorting parents by a relation or an array is unsupported; sorting inside the relation is supported.
 
-export default {
-  database: {
-    path: process.env.DATABASE_PATH ?? 'mock/database.json',
-    schema: 'mock/database-schema.json',
-  },
-  files: {
-    directory: 'mock/files',
-    metadata: 'mock/files/_database.json',
-  },
-  openapi: {
-    path: 'mock/openapi-schema.yaml',
-  },
-  server: {
-    cors: true,
-    host: '127.0.0.1',
-    logger: true,
-    maxFileSize: 100 * 1024 * 1024,
-    maxPageSize: 1000,
-    port: 4001,
-  },
-};
-```
+### REST
 
-Configuration keys:
+| Method | Path | Operation |
+|---|---|---|
+| GET | `/users` | `userList` |
+| GET | `/users/{id}` | `user` |
+| POST | `/users` | `userCreate` |
+| PUT | `/users/{id}` | `userReplace` |
+| PATCH | `/users/{id}` | `userUpdate` |
+| DELETE | `/users/{id}` | `userDelete` |
 
-| Key | Condition | Purpose |
-| --- | --- | --- |
-| `database.path` | Exactly one of `path` or `data` is required | Existing JSON database file |
-| `database.data` | Exactly one of `path` or `data` is required | Database object stored in memory |
-| `database.schema` | No | Path to JSON overrides or an object with request-validation and OpenAPI settings |
-| `files.directory` | Together with `files.metadata` | Directory for binary contents on disk |
-| `files.metadata` | Together with `files.directory` | JSON file containing file metadata on disk |
-| `files.data` | Instead of the `directory` and `metadata` pair | In-memory files with `Uint8Array` contents |
-| `openapi.path` | Required by the `--openapi` and `--openapi-only` CLI flags | Generated OpenAPI YAML file; the programmatic API can return a document without this path |
-| `server.cors` | No | Enables permissive CORS headers and `OPTIONS` routes; defaults to `true` |
-| `server.host` | No | Host used by the CLI, `server.openapi()`, and argument-less `server.fastify().listen()`; defaults to `127.0.0.1` |
-| `server.logger` | No | Fastify logger settings; defaults to `true` |
-| `server.maxFileSize` | No | Maximum uploaded-file size in bytes when file routes are enabled; defaults to 100 MiB |
-| `server.maxPageSize` | No | Maximum allowed `_perPage` in the API and OpenAPI; defaults to `1000` |
-| `server.port` | No | Port used by the CLI, `server.openapi()`, and argument-less `server.fastify().listen()`; defaults to `4001` |
+The path key name follows the primary key. POST/PUT/PATCH receive raw record objects. PUT replaces the record while retaining its key and server-owned root values. PATCH shallowly merges supplied fields; supplied nested objects are full replacements. Create/replace enforce required fields. Update validates supplied values and the final record. Missing targets return 404; conflicts return 409. DELETE returns the deleted record.
 
-`server.port` must be an integer from `0` to `65535`. The value `0` lets Fastify select an available port at runtime, but cannot be used to generate an OpenAPI server URL, which requires a port from `1` to `65535`. Both `server.maxFileSize` and `server.maxPageSize` must be positive integers.
+Query parameters `where`, `order`, `pager`, `nested` contain JSON. `scope` is a selection string. Example shown before URL encoding:
 
-All relative paths are resolved from the directory containing `server.config.js`, not from the current working directory. Unknown keys, empty paths and invalid value types are rejected before startup. The config is executable JavaScript, so it can read environment variables, import other modules and calculate values before exporting the object. A `.js` config with `export default` requires an ESM project (`"type": "module"`); in a CommonJS project, use the same contents in `server.config.mjs`.
+```text
+GET /users?where={"fullName":{"contains":"Мира"}}&order=[{"field":"fullName","direction":"ASC"}]&pager={"page":1,"pageSize":20}
+```
 
-The same config may keep everything in memory. `database.path` and `database.data` are mutually exclusive; `database.schema` accepts either a path or an object. Likewise, `files.data` cannot be combined with `files.directory` or `files.metadata`:
+Construct encoded URLs with `URLSearchParams`:
 
 ```js
-export default {
-  database: {
-    data: { movies: [{ id: '1', title: 'Shadows of Ardenia' }] },
-    schema: { $info: { title: 'Movie API', version: '1.0.0' } },
-  },
-  files: {
-    data: [{ content: new Uint8Array([1, 2, 3]), directory: 'examples', mimeType: 'application/octet-stream', name: 'example.bin' }],
-  },
-};
+const params = new URLSearchParams({
+  scope: 'id,fullName,movies(id,title)',
+  nested: JSON.stringify({ movies: { order: [{ field: 'title', direction: 'ASC' }], pager: { page: 1, pageSize: 5 } } }),
+});
+const response = await fetch(`/users?${params}`);
 ```
 
-In-memory values are cloned during initialization. CRUD and file operations therefore do not mutate the exported config object, and their results disappear when the process exits.
+`scope=*,actors(user(id,fullName),genres(*))` selects own fields and explicit relations. `*` selects only own fields of the current object, including inferred storage keys and excluding `writeOnly`. It never recursively expands relations. Without scope, own fields are selected. Wrappers `data`/`total` remain present.
 
-Add the commands you need to `package.json`. Here, `mock:openapi:files` updates OpenAPI first and then keeps the server running with file routes:
+`nested` maps full response paths to list options:
 
 ```json
 {
-  "scripts": {
-    "mock": "deep-json-server server.config.js",
-    "mock:files": "deep-json-server --files server.config.js",
-    "mock:openapi:files": "deep-json-server --files --openapi server.config.js",
-    "openapi": "deep-json-server --openapi-only server.config.js",
-    "openapi:files": "deep-json-server --files --openapi-only server.config.js"
+  "actors": { "pager": { "pageSize": 5 } },
+  "actors.genres": {
+    "where": { "id": { "in": ["2", "3"] } },
+    "order": [{ "field": "name", "direction": "ASC" }]
   }
 }
 ```
 
-CLI modes:
+A nested path must be selected by scope and must address an object list. Single-record routes and mutations accept `scope` and `nested`; root list parameters only apply to collection GET. Invalid names and unsafe paths return 400.
+
+### GraphQL
+
+```graphql
+query {
+  userList(
+    order: [{ field: fullName, direction: ASC }]
+    pager: { page: 1, pageSize: 20 }
+  ) {
+    total
+    data {
+      id
+      fullName
+      movies(order: [{ field: title, direction: ASC }], pager: { pageSize: 5 }) {
+        total
+        data { id title }
+      }
+    }
+  }
+}
+```
 
-| Command | Behavior |
-| --- | --- |
-| `deep-json-server server.config.js` | Starts the CRUD server without file routes |
-| `deep-json-server --files server.config.js` | Starts the CRUD server with file routes |
-| `deep-json-server --openapi server.config.js` | Generates OpenAPI and starts the CRUD server |
-| `deep-json-server --files --openapi server.config.js` | Generates OpenAPI with file routes and starts the server with them |
-| `deep-json-server --openapi-only server.config.js` | Generates OpenAPI and exits |
-| `deep-json-server --files --openapi-only server.config.js` | Generates OpenAPI with file routes and exits |
+Single queries are `user(id: ...)`, with no `ById`; missing records yield null. Mutation names are `userCreate(data: ...)`, `userReplace(id: ..., data: ...)`, `userUpdate(id: ..., data: ...)`, `userDelete(id: ...)`. A generated-only model creates records without a `data` argument. Mutations use the same validation and storage operations as REST. Selecting relations in mutation results shapes the response only.
 
-`--files` is independent: without it, file routes are neither registered nor added to OpenAPI, even when the config contains a `files` section. The `--openapi` and `--openapi-only` flags are mutually exclusive. Run `deep-json-server --help` to print the CLI summary.
+String primary keys use GraphQL `ID`; ordinary strings use `String`, numbers use `Float`, pagination uses `Int`. Schema enums preserve valid string labels; other values receive `VALUE_0`, `VALUE_1`, etc. Schema constraints such as string length and formats are enforced by the shared runtime validator; SDL alone cannot express all constraints. Introspection and ordinary query/mutation execution are supported; this release does not add subscriptions or bulk mutations.
 
-## Example database
 
-Below is an example movie catalog with sample data. `Gangster` is linked to its parent genre, `Crime`.
+## Example database
 
 ```json
 {
   "countries": [
-    { "id": "1", "isArchived": false, "name": "Ardenia" },
-    { "id": "2", "isArchived": false, "name": "Veloria" }
+    {
+      "id": "1",
+      "isArchived": false,
+      "name": "Ардения"
+    },
+    {
+      "id": "2",
+      "isArchived": false,
+      "name": "Велория"
+    }
   ],
   "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": [] }
+    {
+      "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" }
+        {
+          "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": "The heir to a port city uncovers a conspiracy between two rival families.",
+      "description": "Наследница портового города раскрывает заговор двух соперничающих семей.",
       "id": "1",
       "isArchived": false,
       "publisherIds": ["2"],
-      "title": "Shadows of Ardenia"
+      "title": "Тени Ардении"
     },
     {
       "actors": [],
       "coverSrc": "https://example.com/covers/northern-star.jpg",
-      "description": "A night manager at an old hotel is drawn into the search for a missing painting.",
+      "description": "Ночной администратор старого отеля случайно становится участником поисков пропавшей картины.",
       "id": "2",
       "isArchived": false,
       "publisherIds": ["1"],
-      "title": "Midnight at the Northern Star"
+      "title": "Полночь в «Северной звезде»"
     }
   ],
   "publishers": [
-    { "id": "1", "isArchived": false, "name": "Northlight Studio" },
-    { "id": "2", "isArchived": false, "name": "Aurora Pictures" }
+    {
+      "id": "1",
+      "isArchived": false,
+      "name": "Northlight Studio"
+    },
+    {
+      "id": "2",
+      "isArchived": false,
+      "name": "Aurora Pictures"
+    }
   ],
   "users": [
     {
       "bornAt": "1988-03-14",
       "countryId": "1",
-      "fullName": "Mira Volkova",
+      "fullName": "Мира Волкова",
       "id": "1",
       "isArchived": false
     },
     {
       "bornAt": "1991-11-02",
       "countryId": "2",
-      "fullName": "Leon Vetrov",
+      "fullName": "Леон Ветров",
       "id": "2",
       "isArchived": false
     }
@@ -208,144 +361,6 @@ Below is an example movie catalog with sample data. `Gangster` is linked to its
 }
 ```
 
-Every top-level array becomes a REST resource:
-
-```text
-GET    /movies
-GET    /movies/:id
-POST   /movies
-PUT    /movies/:id
-PATCH  /movies/:id
-DELETE /movies/:id
-```
-
-`POST` generates a string ID. `PUT` completely replaces the selected record, while `PATCH` updates only supplied fields; both preserve the existing ID and its type. An `id` supplied in any request body cannot override the server-controlled ID. All write operations — `POST`, `PUT`, `PATCH` and `DELETE` — are serialized; disk storage persists them in JSON, while memory storage retains them until the process exits.
-
-The database file must exist before startup. Resource names may contain Latin letters, numbers, `_` and `-`, and must start with a letter. Every resource is an array of JSON objects. Every record must have a non-empty string or finite numeric `id`; IDs must be unique within a resource when compared as strings, so `1` and `"1"` cannot coexist. All nested values must be JSON-compatible: finite numbers, strings, booleans, `null`, arrays, and plain objects. The server rereads the file before every resource GET and write operation, so valid edits to existing resources become visible immediately. Resource names and routes are discovered at startup; restart the server after adding, removing, or renaming a top-level resource.
-
-Successful writes return the created, replaced, updated or deleted record. Errors use an appropriate HTTP status and this JSON shape:
-
-```json
-{ "error": "..." }
-```
-
-## Pagination and sorting
-
-```http
-GET /movies?_page=1&_perPage=10&_sort=-id,title
-```
-
-A collection GET always returns the current page data and the total number of records after filtering. `_page` defaults to `1`, and `_perPage` defaults to `10`:
-
-```json
-{
-  "data": [],
-  "total": 0
-}
-```
-
-`data` contains only the records on the requested page. `total` is the number of all records matching the filter before pagination is applied. When needed, a client can calculate the last page as `Math.max(1, Math.ceil(total / pageSize))`.
-
-Both pagination parameters must be positive integers. `_perPage` cannot exceed `1000` by default; change the limit through `server.maxPageSize` in the config passed to either the CLI or `createServer()`. Invalid values return `400` instead of being silently corrected. A page beyond the last page returns an empty `data` array while preserving the actual `total` value.
-
-`_sort` accepts comma-separated field paths. Rules are applied from left to right; prefix a field with `-` for descending order. Dot paths can address nested object fields, including fields added by `_embed`, for example `GET /users?_embed=country&_sort=country.name,-id`. Unknown or unsafe sort fields return `400`.
-
-## Filters
-
-Pass a JSON object through `_where`:
-
-```http
-GET /movies?_where={"title":{"contains":"ardenia"}}
-```
-
-Nested objects and arrays can be filtered at any depth. Conditions in one object use `AND` by default:
-
-```json
-{
-  "actors": { "some": { "userId": { "eq": "1" } } },
-  "title": { "contains": "ardenia" }
-}
-```
-
-Use `and`, `or` and `not` for explicit logical groups:
-
-```json
-{
-  "and": [
-    {
-      "or": [
-        { "title": { "contains": "ardenia" } },
-        { "actors": { "some": { "userId": { "eq": "2" } } } }
-      ]
-    },
-    { "not": { "isArchived": { "eq": true } } }
-  ]
-}
-```
-
-Field operators:
-
-| Operator | Behavior |
-| --- | --- |
-| `eq`, `ne` | Equality or inequality |
-| `contains` | Case-insensitive substring for strings, or matching member for arrays |
-| `startsWith`, `endsWith` | Case-insensitive string prefix or suffix |
-| `gt`, `gte`, `lt`, `lte` | Ordered comparison; ISO date strings can be compared lexically |
-| `in` | Matches a scalar or array member against the supplied values |
-| `some`, `every`, `none` | Applies a nested condition to array elements |
-| `not` | Negates a nested field condition |
-
-Simple query parameters are supported too:
-
-```http
-GET /movies?title:contains=ardenia
-```
-
-Simple filter values recognize JSON primitives: numbers, `true`, `false` and `null`. Values with leading zeroes, such as `001`, remain strings. Unknown operators, invalid logical conditions and filter paths that do not exist in a non-empty resource return `400`.
-
-Different simple query filters are combined with `AND`. Repeating the same equality filter selects any of its values, so `GET /movies?id=1&id=2` is equivalent to `GET /movies?id:in=1,2`. For an `in` filter, values are separated with commas. On an array field, `in` means that at least one field element matches at least one supplied value. `every` returns `true` for an empty array, while `some` returns `false`.
-
-If `_where` is present, it is the complete filter and other simple filter parameters are ignored. The examples show readable JSON; an HTTP client must URL-encode `_where` when constructing the URL manually, for example with `encodeURIComponent(JSON.stringify(where))`.
-
-Filtering is performed after `_embed`. This means a filter can address fields added by an embedded relation when the same request includes that `_embed`; stored `...Id` and `...Ids` fields can always be filtered directly.
-
-## Relationships
-
-Use `_embed` to add related records to the response:
-
-```http
-GET /movies/1?_embed=actors.user.country&_embed=actors.genres&_embed=publishers
-```
-
-The response contains actors, each actor's user and genres, the user's country, and publishers. Original ID fields remain in the response, and the database file is not modified. The server imposes no fixed depth limit, but every required level must be written explicitly in the finite `_embed` path:
-
-```http
-GET /movies/1?_embed=actors.user.country
-GET /genres/2?_embed=parents.parents
-```
-
-Unknown or malformed `_embed` paths return `400`.
-
-Pass `_embed` more than once, as above, or provide a comma-separated list in one parameter. Pagination applies only to the requested root collection; embedded related records are returned in full.
-
-Reverse relationships work as well:
-
-```http
-GET /countries/1?_embed=users
-```
-
-Relations are inferred by convention. A field named `<relation>Id` creates a single relation, while `<relation>Ids` creates a collection relation. The relation name is matched to a top-level resource directly or through its singular form. For example:
-
-- `countryId` points to `countries`;
-- `userId` points to `users` when the requested relation is `user`;
-- `genreIds` points to `genres`;
-- `publisherIds` points to `publishers`;
-- `parentIds` points back to the current resource when `_embed=parents` is requested; `_embed=children` resolves the reverse self-relation.
-
-Reverse relations use the source resource name. For example, `_embed=users` on a country finds users whose nested data contains the corresponding `countryId`. Relations are resolved when requested, but referential integrity is not enforced when data is written.
-
-Explicit `...Id` and `...Ids` fields determine relations. If a record also contains an outdated embedded value, `_embed` replaces that response property with the current related record. A missing related record becomes `null` for a single relation or is omitted from the resulting array for a collection relation. Per-request ID indexes are created only for resources used by the current relation lookup.
-
 ## Files
 
 Add `files.directory` and `files.metadata` to the server config, then pass `--files` to enable raw binary uploads:
@@ -411,172 +426,33 @@ In disk mode, the binary is stored at `<files.directory>/<directory>/<name>`. Th
 
 The upload is raw binary rather than `multipart/form-data`, so `XMLHttpRequest.upload.onprogress` can report progress while the browser sends a `File` directly with `xhr.send(file)`. 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.
 
-## Database schema and OpenAPI generation
-
-The optional path or object in `database.schema` customizes inferred schemas. This is a Deep JSON Server configuration format, not a standard JSON Schema document: `$schema` is an object containing resource settings. For example, `mock/database-schema.json` may contain:
-
-```json
-{
-  "$info": {
-    "title": "Movie Catalog API",
-    "version": "1.0.0"
-  },
-  "$schema": {
-    "movies": {
-      "required": ["actors", "actors.genreIds", "actors.userId", "publisherIds", "title"],
-      "formats": {
-        "coverSrc": "uri"
-      }
-    },
-    "users": {
-      "required": ["bornAt", "fullName"],
-      "formats": {
-        "avatarSrc": "uri",
-        "bornAt": "date"
-      }
-    }
-  }
-}
-```
-
-Schema configuration:
-
-| Key | Purpose |
-| --- | --- |
-| `$info` | OpenAPI `info`; when present, non-empty `title` and `version` are required |
-| `$schema.<resource>.name` | Explicit component name when automatic singularization is unsuitable or collides |
-| `$schema.<resource>.required` | Required field paths; nested paths use dots, such as `actors.userId` |
-| `$schema.<resource>.formats` | OpenAPI formats for inferred or explicit string fields, such as `date`, `date-time` or `uri` |
-| `$schema.<resource>.properties` | Recursive OpenAPI-compatible field schemas merged with inference |
-
-`formats` is shorthand for assigning `format` to an existing string field. `properties` can fully describe a field—including its `type`, `format`, constraints, and nested properties—or add a field that is absent from the data. If both mechanisms assign a format to the same field, the value from `formats` is applied last.
-
-Set `openapi.path` in the server config, then generate an OpenAPI 3.0.3 file and exit:
-
-```bash
-deep-json-server --openapi-only server.config.js
-```
-
-To include file routes in the document, configure the `files` section and add `--files`: `deep-json-server --files --openapi-only server.config.js`.
-
-The generator infers resources and field types from all database records. Every inferred field is optional by default, while the top-level `id` is always required in response schemas and is omitted from create and update request schemas. Add other required fields to `required`. A nested required path marks that nested property as required; it does not automatically make every parent path required, so list the parent separately when necessary.
-
-Different non-overlapping value types are inferred independently and combined through `oneOf`; mixed integers and decimal numbers are represented by one `number` schema. Configuration is validated before generation: `$info`, resource and component names, supported `properties` keywords and their value types are checked, while paths from `required` and `formats` must exist in the resulting schema. Explicit component names may contain ASCII letters, digits, dots, underscores, and hyphens.
-
-Use `properties` to describe fields that cannot be inferred, particularly for an empty resource. Explicit properties are merged with inferred properties:
-
-```json
-{
-  "$schema": {
-    "reviews": {
-      "properties": {
-        "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
-        "text": { "type": "string" }
-      },
-      "required": ["rating"]
-    }
-  }
-}
-```
-
-An empty resource still receives a required string `id` property because IDs created by the server are strings. Generation stops with an actionable error when resources produce duplicate schema names or operation IDs; use an explicit `name` to resolve schema-name collisions. The output directory is created automatically, and the configured YAML file is replaced on every generation.
-
-`$info` becomes the OpenAPI `info` object, while resource settings live under `$schema`. In the CLI, the OpenAPI `servers` entry uses `server.host` and `server.port`, then the `HOST` and `PORT` environment-variable fallbacks, and finally `http://127.0.0.1:4001`. A direct `createServer()` call does not read those environment variables automatically: `server.openapi()` uses the config values or the same default URL.
-
-Use `name` when a resource needs an explicit schema name instead of the automatically singularized name:
-
-```json
-{
-  "$schema": {
-    "equipment": {
-      "name": "Equipment"
-    }
-  }
-}
-```
-
-The generated document describes CRUD endpoints, pagination, sorting, nested data filters, `_embed`, and both direct and reverse response relations inferred from `...Id` and `...Ids` fields. When `--files` is present, it also describes raw binary upload, download and deletion endpoints for arbitrary media types. A numeric database ID is described as `integer | string`, because a later `POST` creates a string ID in the same resource. Generation rejects duplicate schema names, operation IDs, and invalid schema overrides before producing a document. The document can be used as input for tools such as RTK Query OpenAPI Codegen. OpenAPI is generated only with `--openapi` or `--openapi-only`; normal server startup does not rewrite the file.
-
-During normal startup, request bodies are validated against the same inferred and configured schemas. `POST` and `PUT` enforce configured required fields; `PATCH` validates only fields that are actually supplied. `formats` and `properties` apply to all three methods. Unlisted additional object fields remain allowed. Invalid bodies return `400`.
-
 ## Programmatic API
 
 ```js
 import { createServer } from '@kollors/deep-json-server';
+import config from './server.config.js';
+
+const facade = await createServer(config);
+const openapi = await facade.openapi();
+const sdl = await facade.graphql();
+const server = facade.fastify();
+await server.listen();
+// await server.close();
+```
 
-const config = {
-  database: {
-    path: 'mock/database.json',
-    schema: 'mock/database-schema.json',
-  },
-  files: {
-    directory: 'mock/files',
-    metadata: 'mock/files/_database.json',
-  },
-  openapi: {
-    path: 'mock/openapi-schema.yaml',
-  },
-  server: {
-    cors: true,
-    host: '127.0.0.1',
-    logger: false,
-    maxFileSize: 100 * 1024 * 1024,
-    maxPageSize: 1000,
-    port: 4001,
-  },
-};
-
-// Make a request without opening a network port—useful in automated tests.
-const server = await createServer(config);
-const fastify = server.fastify();
-const response = await fastify.inject({ method: 'GET', url: '/movies' });
-
-console.log(response.json());
-
-// Return the document and write it to config.openapi.path.
-const document = await server.openapi();
-
-await fastify.close();
+Accessors are lazy; exporting schemas does not listen or initialize disk file storage. Override runtime features with `createServer(config, { files: false, graphql: true })`.
 
-// Start a network server. With no arguments, listen uses server.host and server.port.
-const runningServer = await createServer(config);
-const runningFastify = runningServer.fastify();
+## Storage and development
 
-await runningFastify.listen();
+Updates are serialized within one server instance and validated on a draft before persistence. Use one writer 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. UUID generation uses Node's built-in crypto API.
 
-// Later, during application shutdown:
-await runningFastify.close();
+This is a mock server; there is no authentication or password hashing. File routes keep their independent storage and validation.
 
-// Keep the database, schema, and files entirely in memory.
-const memoryServer = await createServer({
-  database: {
-    data: { movies: [{ id: '1', title: 'Shadows of Ardenia' }] },
-    schema: { $info: { title: 'Movie API', version: '1.0.0' } },
-  },
-  files: {
-    data: [{ content: new Uint8Array([1, 2, 3]), directory: 'examples', mimeType: 'application/octet-stream', name: 'example.bin' }],
-  },
-});
-
-const memoryFastify = memoryServer.fastify();
-const memoryResponse = await memoryFastify.inject({ method: 'GET', url: '/movies/1' });
-
-console.log(memoryResponse.json());
-
-await memoryFastify.close();
+```sh
+npm ci
+npm run verify
 ```
 
-`createServer()` accepts exactly the same config shape as `server.config.js`. It loads and clones the database, schema, and file storage, then returns an object with two methods:
-
-| Method | Purpose |
-| --- | --- |
-| `server.fastify()` | Lazily creates and caches the real Fastify instance; every native method remains available, and argument-less `listen()` uses `server.host` and `server.port` |
-| `server.openapi()` | Returns an OpenAPI document and also writes it when `openapi.path` is configured |
-
-File routes are enabled programmatically when a `files` section is present. The second argument has the shape `{ files?: boolean }`: pass `{ files: false }` to keep a configured store disabled, or `{ files: true }` to require a `files` section and enable the routes. `server.openapi()` uses the same file-route setting as `server.fastify()`.
-
-An argument-less `server.fastify().listen()` uses `server.host` and `server.port`, falling back to `127.0.0.1:4001`. Explicit `listen(options)` values take precedence. Relative paths passed directly to `createServer()` resolve from the current working directory; paths loaded from `server.config.js` resolve from the config directory. The package includes generated TypeScript declarations for the returned object and every config variant.
-
-## Scope and security
+Verification runs type checking, lint, coverage gates and installation checks against the packed package. A new alpha version in `package.json` pushed to `main` creates its version tag and publishes through GitHub Actions trusted publishing to npm `alpha`. An existing tag skips automatic publication. Explicit version-tag pushes also publish; stable versions use `latest`. The publishing script rejects mismatched Git tags.
 
-Deep JSON Server is intended for local development and automated tests. It has no authentication or authorization, allows CORS from every origin by default, persists accepted writes when disk storage is configured and does not enforce referential integrity. Set `server.cors` to `false` to disable the built-in CORS headers and `OPTIONS` routes. Keep the default loopback host unless the surrounding environment provides its own access controls; do not expose the server or file routes to an untrusted network.
+License: MIT.