@simtlix/simfinity-core 3.5.7 → 3.5.8

package/README.md

@@ -16,7 +16,7 @@ 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. The MongoDB adapter defines it.
 
 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()`.
 
@@ -35,3 +35,5 @@ 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 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.8",
   "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;
   }