@simtlix/simfinity-descriptor 3.19.0 → 3.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +65 -31
  2. package/package.json +3 -2
  3. package/src/package-info.js +1 -1
package/README.md CHANGED
@@ -1,40 +1,74 @@
1
+ [![Simfinity.js — Define once. Build beyond. GraphQL, MongoDB, PostgreSQL, and optional MCP.](https://raw.githubusercontent.com/simtlix/simfinity.js/master/.github/assets/readme-cover.png)](https://simtlix.github.io/simfinity.js/)
2
+
1
3
  # @simtlix/simfinity-descriptor
2
4
 
3
- Optional schema-owned JSON client metadata for Simfinity. Depends on the exact
4
- matching version of `@simtlix/simfinity-core`; supports both database facades.
5
- Available since 3.15.0. Install it
6
- as a direct application dependency at the version of your Simfinity runtime.
5
+ [![npm version](https://img.shields.io/npm/v/@simtlix/simfinity-descriptor.svg)](https://www.npmjs.com/package/@simtlix/simfinity-descriptor)
6
+ [![Node.js](https://img.shields.io/node/v/@simtlix/simfinity-descriptor.svg)](https://nodejs.org/)
7
+ [![License](https://img.shields.io/npm/l/@simtlix/simfinity-descriptor.svg)](https://github.com/simtlix/simfinity.js/blob/master/LICENSE)
8
+ [![Documentation](https://img.shields.io/badge/docs-simtlix.github.io-2563eb.svg)](https://simtlix.github.io/simfinity.js/)
9
+
10
+ **Client metadata for a [Simfinity.js](https://simtlix.github.io/simfinity.js/) schema, as JSON, with an explicitly authorized HTTP endpoint to serve it.** A descriptor is immutable JSON metadata for the exact schema that `createSchema()` returned. It is built without querying a database and can be served even when introspection queries are disabled. It is optional and works with both database packages.
11
+
12
+ **[Documentation](https://simtlix.github.io/simfinity.js/)** ·
13
+ **[Client descriptor reference](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html)** ·
14
+ **[JavaScript client](https://simtlix.github.io/simfinity.js/guide/client.html)** ·
15
+ **[Releases](https://github.com/simtlix/simfinity.js/releases)**
16
+
17
+ ## Install
18
+
19
+ ```sh
20
+ npm install @simtlix/simfinity-descriptor
21
+ ```
22
+
23
+ Install it as a direct dependency at the same version as your Simfinity database package. It requires Node.js 18.18 or later and `graphql@^16.11.0`.
24
+
25
+ ## Quick start
7
26
 
8
27
  ```javascript
9
28
  import { buildClientDescriptor, createClientDescriptorHandler } from '@simtlix/simfinity-descriptor';
29
+
10
30
  const descriptor = buildClientDescriptor(schema);
11
31
  app.all('/graphql-metadata', createClientDescriptorHandler(schema, { authorize: 'public' }));
12
32
  ```
13
33
 
14
- The application supplies its exact `createSchema()` result and explicitly chooses
15
- public access or an authorization function. Importing this package does not patch
16
- GraphQL introspection. See the [client descriptor guide](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html)
17
- for gated access, root input hints, early opt-out and client migration limits.
18
-
19
- `rootInputUsage` reports whether a field is required or optional in the actual
20
- generated root add/update input. Nested collection inputs can omit the inverse
21
- reference supplied by their parent. Descriptors do not serialize arbitrary
22
- validators or determine dynamic permissions. Finish declarations before the first
23
- build; create a new schema and handler for metadata changes. Clones and composed
24
- schemas do not inherit ownership.
25
-
26
- Core remains dependency-free; structural HTTP declarations need no Node ambient
27
- types. Directly importing `@simtlix/simfinity-core/introspection` requires core as
28
- a direct dependency pinned to the facade's version. The 3.x introspection default
29
- remains enabled, and clients selecting `__Field.extensions` must migrate before
30
- using the early opt-out.
31
-
32
- Since 3.16.0, a generated transaction field is described with
33
- `operation: 'transaction'` and `type: null`, with its actual arguments, result
34
- type and reachable `@oneOf` input. Format version 1 is unchanged; clients that
35
- handle operation kinds exhaustively must accept `transaction`. User-registered
36
- mutations retain `customMutation`.
37
-
38
- The descriptor also traverses the generated nullable `valuePath: String` field on `QLFilter`, `QLTypeFilter` and `QLFilterCondition` with format version 1 unchanged. This describes input shape, not adapter capabilities; `value`/`valuePath` mutual exclusion and `queryFeatures.valuePath` support are runtime validation rules.
39
-
40
- The 3.18.0 embedded-frame extension reuses those input shapes and format version 1. `$parent` is a value-path string validated against structural containment at execution. Input presence does not advertise `queryFeatures.elementFrames`, and embedded selection fields gain no arguments.
34
+ - Pass the exact schema returned by `createSchema()`. Clones and composed schemas do not inherit ownership.
35
+ - Choose access explicitly: `authorize: 'public'` or your own authorization function.
36
+ - Finish your declarations before the first build. Create a new schema and handler when the metadata changes.
37
+
38
+ Importing this package does not patch GraphQL introspection. A descriptor does not evaluate dynamic permissions or serialize arbitrary validators.
39
+
40
+ The [`@simtlix/simfinity-js-client`](https://www.npmjs.com/package/@simtlix/simfinity-js-client) package reads this endpoint through its `descriptorEndpoint` option.
41
+
42
+ ## Documentation
43
+
44
+ | I want to… | Read |
45
+ | --- | --- |
46
+ | Build a descriptor for the schema I serve | [Build for the schema you serve](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html#build-for-the-schema-you-serve) |
47
+ | Know every field of the JSON | [Format version 1](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html#format-version-1) |
48
+ | Protect the endpoint | [Mount the HTTP handler](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html#mount-the-http-handler) |
49
+ | Turn off the deprecated `__Field.extensions` introspection field | [Disable the legacy extension explicitly](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html#disable-the-legacy-extension-explicitly) |
50
+ | Migrate a client from introspection | [Client migration boundary](https://simtlix.github.io/simfinity.js/reference/client-descriptor.html#client-migration-boundary) |
51
+ | Use it from the JavaScript client | [Initialize with a descriptor](https://simtlix.github.io/simfinity.js/guide/client.html#initialize-with-a-descriptor) |
52
+
53
+ ## Packages
54
+
55
+ All Simfinity packages are released together under the same version. Keep the ones you install aligned. The ESLint plugin has its own version.
56
+
57
+ | Package | Use it for |
58
+ | --- | --- |
59
+ | [`@simtlix/simfinity-js`](https://www.npmjs.com/package/@simtlix/simfinity-js) | MongoDB/Mongoose applications |
60
+ | [`@simtlix/simfinity-postgres`](https://www.npmjs.com/package/@simtlix/simfinity-postgres) | PostgreSQL 15+ applications, with real tables and foreign keys |
61
+ | [`@simtlix/simfinity-mcp`](https://www.npmjs.com/package/@simtlix/simfinity-mcp) | MCP tools and transports for any Simfinity schema |
62
+ | [`@simtlix/simfinity-js-client`](https://www.npmjs.com/package/@simtlix/simfinity-js-client) | JavaScript client for Simfinity APIs |
63
+ | **`@simtlix/simfinity-descriptor`** | Client metadata endpoint for a schema (this package) |
64
+ | [`@simtlix/simfinity-core`](https://www.npmjs.com/package/@simtlix/simfinity-core) | Shared GraphQL runtime, installed automatically |
65
+ | [`@simtlix/simfinity-sql`](https://www.npmjs.com/package/@simtlix/simfinity-sql) | Relational runtime and database plugin contract |
66
+ | [`@simtlix/eslint-plugin-simfinity`](https://www.npmjs.com/package/@simtlix/eslint-plugin-simfinity) | Optional lint rules for Simfinity applications |
67
+
68
+ ## Contributing
69
+
70
+ Source, issues and the contribution guide live in the [simtlix/simfinity.js](https://github.com/simtlix/simfinity.js) monorepo, under `packages/descriptor`. See [Contributing](https://simtlix.github.io/simfinity.js/resources/contributing.html).
71
+
72
+ ## License
73
+
74
+ [Apache-2.0](https://github.com/simtlix/simfinity.js/blob/master/LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@simtlix/simfinity-descriptor",
3
- "version": "3.19.0",
3
+ "version": "3.19.1",
4
4
  "description": "Schema-owned client metadata and an explicitly authorized HTTP endpoint for Simfinity",
5
5
  "type": "module",
6
6
  "main": "./src/index.js",
@@ -21,13 +21,14 @@
21
21
  "node": ">=18.18.0"
22
22
  },
23
23
  "license": "Apache-2.0",
24
+ "homepage": "https://simtlix.github.io/simfinity.js/reference/client-descriptor.html",
24
25
  "repository": {
25
26
  "type": "git",
26
27
  "url": "https://github.com/simtlix/simfinity.js",
27
28
  "directory": "packages/descriptor"
28
29
  },
29
30
  "dependencies": {
30
- "@simtlix/simfinity-core": "3.19.0"
31
+ "@simtlix/simfinity-core": "3.19.1"
31
32
  },
32
33
  "peerDependencies": {
33
34
  "graphql": "^16.11.0"
package/src/package-info.js CHANGED
@@ -1,2 +1,2 @@
1
1
  // Generated by scripts/release-packages.js; keeps the descriptor builder free of Node/JSON loader dependencies.
2
- export const packageInfo = Object.freeze({ name: '@simtlix/simfinity-descriptor', version: '3.19.0' });
2
+ export const packageInfo = Object.freeze({ name: '@simtlix/simfinity-descriptor', version: '3.19.1' });