@simtlix/simfinity-core 3.5.7 → 3.5.9

package/README.md

@@ -16,13 +16,13 @@ For relational storage, `@simtlix/simfinity-sql` builds on core and delegates ph
 - `preventCreatingCollection` to pass validation-only storage setup to an adapter;
 - `configureQueryLimits` and `configureMutationLimits` for the process-wide page-size and nested-operation limits.
 
-The adapter supplies model creation, identifiers, transactions, record reads and writes, queries, counts, aggregations, and inverse collection reads. `DatabaseAdapter`, `Runtime`, controller, middleware, registration, and state-machine interfaces are exported in the TypeScript declarations. A runtime binds one adapter; create another runtime to use another database or configuration. An adapter can also define `getByIds(model, ids, { context })`, which returns the records it finds in `getById` shape and any order; the runtime then batches generated single-reference reads per request and type, matching records by `castId`, splitting batches at `maxPageSize`, and reading an ID with `getById` when a batch read fails or when `castId` would normalize or reject it. `castId` should throw a `NOT_VALID_ID` (400) `SimfinityError` for a malformed value and must not create a new identifier. When `getById` rejects a stored reference value that way, including one that `castId` rejected first, the generated reference field fails with an `InternalServerError`, since the client did not send the value. An adapter that hydrates records can define `readEmbeddedValue(value)`: every nullable, singular embedded object field without a resolver then passes its value through it, so an explicitly stored `null` reads as `null`. The field is read as graphql's default resolver reads it, so a method on the parent is called and a promise it returns is awaited before the hook receives the value. The MongoDB adapter defines it.
+The adapter supplies model creation, identifiers, transactions, record reads and writes, queries, counts, aggregations, and inverse collection reads. `DatabaseAdapter`, `Runtime`, controller, middleware, registration, and state-machine interfaces are exported in the TypeScript declarations. A runtime binds one adapter; create another runtime to use another database or configuration. An adapter can also define `getByIds(model, ids, { context })`, which returns the records it finds in `getById` shape and any order; the runtime then batches generated single-reference reads per request and type, matching records by `castId`, splitting batches at `maxPageSize`, and reading an ID with `getById` when a batch read fails or when `castId` would normalize or reject it. `castId` should throw a `NOT_VALID_ID` (400) `SimfinityError` for a malformed value and must not create a new identifier. When `getById` rejects a stored reference value that way, including one that `castId` rejected first, the generated reference field fails with an `InternalServerError` (500), since the client did not send the value. `update()` resolves to the updated record as stored, or null; nested collection children of that record are linked to and checked against its `_id`, else `id`, else the requested ID. An adapter that hydrates records can define `readEmbeddedValue(value)`: every nullable, singular embedded object field without a resolver then passes its value through it, so an explicitly stored `null` reads as `null`. The field is read as graphql's default resolver reads it, so a method on the parent is called and a promise it returns is awaited before the hook receives the value. Simfinity then reads as `null` an object that holds no data when a required member would read as `null`, not counting `id`, `readOnly`, interface and union members, members with an application resolver and referenced collections; runtimes that share the type read the same. It reads the stored members, never calling a getter, and counts a stored `_id` as `id`; it reads nothing from objects whose type has no member that counts, and an error while reading returns the object unchanged. An adapter whose hydrated records render members through getters can also define `rawEmbeddedValue(value)`, which returns a record's stored data as a plain object, or the record unchanged when that data does not show what it renders; a value that is not a plain object counts as data. The MongoDB adapter defines both.
 
 Entity types, those registered with `connect()` and the targets of non-embedded relations, resolve `id` to `_id`, falling back to `id`, whatever the `createSchema()` allowlists include; types used only as embedded values keep their declared `id`. Embedded copies of an entity type resolve the same way, so they return their declared `id` unless the adapter stores an `_id` for them, as MongoDB does for embedded list items. The resolver is set on the type object, so it applies in every runtime that shares the type. `createSchema()` marks these registrations with `storedIdentity: true` before calling `adapter.prepare()`.
 
 When a runtime first creates a schema, it binds each GraphQL object type whose non-embedded relation fields receive its generated resolvers. It also reserves each reachable object type that still has a non-embedded relation field without a resolver, such as an unregistered custom mutation result. Registering a bound or reserved type in another runtime, or building another runtime's schema that reaches it through fields, interfaces, union members or custom mutation results, throws `TYPE_BOUND_TO_OTHER_RUNTIME` (409). `createSchema()` also rejects a type with a relation field copied, by `toConfig()` or a field spread, after another runtime generated that field's resolver. Create type objects once per runtime, for example with a factory function. Types without non-embedded relation fields, and types whose relation fields all have application resolvers, can be shared, and another runtime can use a `toConfig()` copy made before the first runtime built its schema. A shared custom mutation result type with an unresolved relation field is rejected.
 
-Registration and `createSchema()` validate `extensions.scope` (`INVALID_SCOPE`) and reject list or embedded relations to unregistered types (`UNREGISTERED_RELATION_TARGET`); `use()` rejects non-functions (`INVALID_MIDDLEWARE`). Before `adapter.prepare()`, `createSchema()` rejects a writable non-embedded list relation without a non-empty child `connectionField` whose resolver it would generate (`INVALID_MODEL`, 400). A collection without `connectionField` that has an application resolver, or is `readOnly`, only logs a `Configuration issue` warning, unless it is both, and nested writes through it fail with `INVALID_MODEL` (500) before anything is written; adapters that describe the whole model, such as PostgreSQL and transactional MongoDB, still reject it in `prepare()`. Fields named like generated query arguments (`sort`, `pagination`, `AND`, `OR`, and `aggregation` on aggregate endpoints) also log a warning once per runtime.
+Registration and `createSchema()` validate `extensions.scope` (`INVALID_SCOPE`) and reject list or embedded relations to unregistered types (`UNREGISTERED_RELATION_TARGET`); `use()` rejects non-functions (`INVALID_MIDDLEWARE`). Before `adapter.prepare()`, `createSchema()` rejects a writable non-embedded list relation without a non-empty child `connectionField` whose resolver it would generate (`INVALID_MODEL`, 400). A collection without `connectionField` that has an application resolver, or is `readOnly`, only logs a `Configuration issue` warning, unless it is both, and nested writes through it fail with `INVALID_MODEL` (500) before anything is written; adapters that describe the whole model, such as PostgreSQL and transactional MongoDB, still reject it in `prepare()`. Fields named like generated query arguments (`sort`, `pagination`, `AND`, `OR`, and `aggregation` on aggregate endpoints) also log a warning once per runtime. Generated inputs that would have no fields are left out with a `Configuration issue` warning, with the collection operations, embedded fields and mutations that would take them; a non-null embedded field whose embedded type has no writable fields throws `INVALID_MODEL` (400) when generated mutations reach its owner. An application type named `FieldExtensionsType` or `RelationType` makes Simfinity rename its introspection metadata types to `SimfinityFieldExtensionsType` and `SimfinityRelationType` when it is in the process's first Simfinity schema. That schema fixes the names: in a later `createSchema()`, an application type with one of the current names, the original ones or the fallback names after a rename, throws `RESERVED_TYPE_NAME` (500), before `adapter.prepare()` when it is an included endpoint type, a registered mutation's input or output type, an output type they reach or a field argument's type, and when the schema is constructed otherwise, such as for a type inside an input object's fields.
 
 Generated and custom mutations run through `adapter.withTransaction`. Retried attempts receive fresh clones of GraphQL input objects, lists, and dates while enum values keep their identity. An adapter can define `stateValue` when its persisted enum representation differs from GraphQL enum names.
 
@@ -34,4 +34,6 @@ Importing the runtime installs Simfinity's `__Field.extensions` introspection fi
 
 `createQueryPlan` and `resolveModelPath` turn Simfinity filter, sort, pagination, and aggregation inputs into a driver-neutral plan resolved against that metadata.
 
-The package also exports the `auth`, `validators`, `scalars`, and `plugins` helper namespaces alongside `createValidatedScalar`, `SimfinityError`, `InternalServerError`, `buildErrorFormatter`, `configureQueryLimits`, `configureMutationLimits`, `QLOperator`, `QLSort`, and `QLValue`. `buildErrorFormatter` returns a `GraphQLError` whose `originalError` is the classified Simfinity error. Database packages reuse these exports so helpers, errors, and globally named GraphQL types retain one identity.
+The package also exports the `auth`, `validators`, `scalars`, and `plugins` helper namespaces alongside `createValidatedScalar`, `SimfinityError`, `InternalServerError`, `UnauthenticatedError` and `ForbiddenError` (the same classes as `auth.UnauthenticatedError` and `auth.ForbiddenError`), `buildErrorFormatter`, `configureQueryLimits`, `configureMutationLimits`, `QLOperator`, `QLSort`, and `QLValue`. `buildErrorFormatter` returns a `GraphQLError` whose `originalError` is the classified Simfinity error. Database packages reuse these exports so helpers, errors, and globally named GraphQL types retain one identity.
+
+The same helpers are available from the `@simtlix/simfinity-core/auth`, `/auth/errors`, `/auth/expressions`, `/auth/rules`, `/plugins`, `/scalars` and `/validators` subpaths, each with TypeScript declarations whose types match the root namespaces. `moduleResolution` `node16`, `nodenext` and `bundler` read them through the export map, and `node10` through `typesVersions`. The `internal/*` subpaths are not public API and have no declarations.

package/package.json

@@ -1,24 +1,70 @@
 {
   "name": "@simtlix/simfinity-core",
-  "version": "3.5.7",
+  "version": "3.5.9",
   "description": "Driver-free GraphQL runtime and model metadata for Simfinity",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "auth": [
+        "types/auth/index.d.ts"
+      ],
+      "auth/errors": [
+        "types/auth/errors.d.ts"
+      ],
+      "auth/expressions": [
+        "types/auth/expressions.d.ts"
+      ],
+      "auth/rules": [
+        "types/auth/rules.d.ts"
+      ],
+      "plugins": [
+        "types/plugins.d.ts"
+      ],
+      "scalars": [
+        "types/scalars.d.ts"
+      ],
+      "validators": [
+        "types/validators.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
       "default": "./src/index.js"
     },
-    "./auth": "./src/auth/index.js",
-    "./auth/errors": "./src/auth/errors.js",
-    "./auth/expressions": "./src/auth/expressions.js",
-    "./auth/rules": "./src/auth/rules.js",
+    "./auth": {
+      "types": "./types/auth/index.d.ts",
+      "default": "./src/auth/index.js"
+    },
+    "./auth/errors": {
+      "types": "./types/auth/errors.d.ts",
+      "default": "./src/auth/errors.js"
+    },
+    "./auth/expressions": {
+      "types": "./types/auth/expressions.d.ts",
+      "default": "./src/auth/expressions.js"
+    },
+    "./auth/rules": {
+      "types": "./types/auth/rules.d.ts",
+      "default": "./src/auth/rules.js"
+    },
     "./internal/object-id": "./src/auth/object-id.js",
     "./internal/relation-storage": "./src/relation-storage.js",
-    "./plugins": "./src/plugins.js",
-    "./scalars": "./src/scalars.js",
-    "./validators": "./src/validators.js"
+    "./plugins": {
+      "types": "./types/plugins.d.ts",
+      "default": "./src/plugins.js"
+    },
+    "./scalars": {
+      "types": "./types/scalars.d.ts",
+      "default": "./src/scalars.js"
+    },
+    "./validators": {
+      "types": "./types/validators.d.ts",
+      "default": "./src/validators.js"
+    }
   },
   "files": [
     "src",

package/src/const/QLValue.js

@@ -3,19 +3,27 @@ import SimfinityError from '../errors/simfinity.error.js';
 
 const parseQLValue = (value) => value;
 
-const parseLiteral = (ast) => {
+// graphql-js resolves a variable that is the whole value itself, but passes a list literal such as
+// [$from, $to] here with the operation's variables (undefined during validation). A variable item
+// the operation leaves unset reads as null, as graphql-js reads list items of other types. An enum
+// literal reads as its name, like the quoted name of an enum filter value.
+const parseLiteral = (ast, variables) => {
   switch (ast.kind) {
     case Kind.INT: return parseInt(ast.value, 10);
     case Kind.FLOAT: return parseFloat(ast.value);
     case Kind.BOOLEAN: return ast.value === true || ast.value === 'true';
-    case Kind.STRING: return ast.value;
+    case Kind.STRING:
+    case Kind.ENUM: return ast.value;
     case Kind.NULL: return null;
+    case Kind.VARIABLE:
+      // Object.hasOwn: a variable named like an Object.prototype member is not inherited.
+      return variables != null && Object.hasOwn(variables, ast.name.value) ? variables[ast.name.value] : null;
     case Kind.LIST:
       return ast.values.map((item) => {
         if (item.kind === Kind.LIST) {
           throw new SimfinityError('Nested filter value lists are not supported', 'INVALID_FILTER_VALUE', 400);
         }
-        return parseLiteral(item);
+        return parseLiteral(item, variables);
       });
     default:
       throw new SimfinityError('Filter values must be scalars or flat scalar lists', 'INVALID_FILTER_VALUE', 400);

package/src/errors/internal-server.error.js

@@ -1,8 +1,12 @@
 import SimfinityError from './simfinity.error.js';
 
+// An unexpected failure: code INTERNAL_SERVER_ERROR and status 500. `cause` keeps the original error.
+// The cause is never included in GraphQL responses, or in the errors that buildErrorFormatter returns
+// when they are serialized. It is an enumerable own property of this error, so JSON.stringify(error),
+// or a logger that copies enumerable properties, includes it.
 class InternalServerError extends SimfinityError {
   constructor(message, cause) {
-    super(message, 'INTERNAL_SERVER_ERROR');
+    super(message, 'INTERNAL_SERVER_ERROR', 500);
     this.cause = cause;
     this.getCause = () => this.cause;
   }

package/src/index.js

@@ -13,6 +13,9 @@ export { default as QLValue } from './const/QLValue.js';
 export { configureQueryLimits, paginationStages } from './query-limits.js';
 export { configureMutationLimits } from './mutation-limits.js';
 export { default as auth } from './auth/index.js';
+// The same classes as auth.UnauthenticatedError and auth.ForbiddenError; types/index.d.ts has
+// always declared them as root exports.
+export { UnauthenticatedError, ForbiddenError } from './auth/errors.js';
 export { default as plugins } from './plugins.js';
 export { default as scalars } from './scalars.js';
 export { default as validators } from './validators.js';

package/src/introspection.js

@@ -5,12 +5,11 @@ import {
   __Field,
 } from 'graphql';
 
-// getFields() supports both lazy and already materialized introspection fields.
-// Reuse the shared field on repeated module evaluation to preserve type identity.
-const introspectionFields = __Field.getFields();
-if (!introspectionFields.extensions) {
+// The object types of `__Field.extensions`: FieldExtensionsType and the RelationType of its
+// `relation` field, under the given names.
+const createFieldMetadataType = (extensionsName, relationName) => {
   const RelationType = new GraphQLObjectType({
-    name: 'RelationType',
+    name: relationName,
     fields: () => ({
       embedded: { type: GraphQLBoolean },
       connectionField: { type: GraphQLString },
@@ -18,20 +17,55 @@ if (!introspectionFields.extensions) {
     }),
   });
 
-  const FieldExtensionsType = new GraphQLObjectType({
-    name: 'FieldExtensionsType',
+  return new GraphQLObjectType({
+    name: extensionsName,
     fields: () => ({
       relation: { type: RelationType },
       stateMachine: { type: GraphQLBoolean },
       readOnly: { type: GraphQLBoolean },
     }),
   });
+};
 
+// getFields() supports both lazy and already materialized introspection fields.
+// Reuse the shared field on repeated module evaluation to preserve type identity.
+const introspectionFields = __Field.getFields();
+if (!introspectionFields.extensions) {
   introspectionFields.extensions = {
-    type: FieldExtensionsType,
+    type: createFieldMetadataType('FieldExtensionsType', 'RelationType'),
     name: 'extensions',
     resolve: (obj) => obj.extensions,
     args: [],
     isDeprecated: false,
   };
 }
+
+// Set on the shared extensions field, by any evaluation of this module, once a Simfinity schema
+// contains the metadata types; their names do not change after that.
+const NAMES_FIXED = Symbol.for('simfinity.fieldMetadataNamesFixed');
+const extensionsField = () => __Field.getFields().extensions;
+
+/** The metadata types `__Field.extensions` returns now: [FieldExtensionsType, RelationType]. */
+export const fieldMetadataTypes = () => {
+  const extensionsType = extensionsField().type;
+  return [extensionsType, extensionsType.getFields().relation.type];
+};
+
+export const fieldMetadataNamesFixed = () => extensionsField()[NAMES_FIXED] === true;
+
+export const fixFieldMetadataNames = () => {
+  extensionsField()[NAMES_FIXED] = true;
+};
+
+// Every schema constructed afterwards, in the whole process, contains the metadata types under the
+// new names. The extensions field object keeps its identity, so other evaluations of this module and
+// the auth plugin, which read its type when they need it, follow the change. Returns a function that
+// puts the previous type objects back, for a schema whose construction fails.
+export const renameFieldMetadataTypes = (extensionsName, relationName) => {
+  const field = extensionsField();
+  const previous = field.type;
+  field.type = createFieldMetadataType(extensionsName, relationName);
+  return () => {
+    field.type = previous;
+  };
+};