@simtlix/simfinity-core 3.5.2 → 3.5.5

package/src/scalars/factory.js

@@ -1,5 +1,18 @@
 import { GraphQLScalarType, GraphQLString, GraphQLInt, GraphQLFloat, GraphQLBoolean, GraphQLID, Kind } from 'graphql';
 
+// The base each validated scalar delegates parsing to. A base exists before its scalar, so these links cannot cycle.
+const validatedBases = new WeakMap();
+
+// Follow validated-scalar chains to the scalar that defines the literal syntax. Any other scalar is the root, even
+// with a hand-set `baseScalarType` storage hint, because its own parseLiteral decides which literals it takes.
+const findRootScalar = (scalarType) => {
+  let root = scalarType;
+  while (validatedBases.has(root)) {
+    root = validatedBases.get(root);
+  }
+  return root;
+};
+
 export function createValidatedScalar(name, description, baseScalarType, validate) {
   if (!baseScalarType) {
     throw new Error('baseScalarType is required');
@@ -16,16 +29,21 @@ export function createValidatedScalar(name, description, baseScalarType, validat
     throw new Error('baseScalarType must be a standard GraphQL scalar type or a custom scalar with a valid name');
   }
 
+  // Float takes integer literals too, as GraphQLFloat does, so an integral default printed as `5` stays valid.
   const kindMap = {
-    String: Kind.STRING,
-    Int: Kind.INT,
-    Float: Kind.FLOAT,
-    Boolean: Kind.BOOLEAN,
-    ID: Kind.STRING,
+    String: [Kind.STRING],
+    Int: [Kind.INT],
+    Float: [Kind.FLOAT, Kind.INT],
+    Boolean: [Kind.BOOLEAN],
+    ID: [Kind.STRING],
   };
 
-  const baseKind = kindMap[baseScalarType.name] || Kind.STRING;
+  // Custom root scalars define their own literal kinds, so their parseLiteral decides.
+  const rootScalarType = findRootScalar(baseScalarType);
+  const baseKinds = Object.hasOwn(kindMap, rootScalarType.name) ? kindMap[rootScalarType.name] : undefined;
 
+  // Input is parsed by the base first, so validators judge the same internal value for variables and literals.
+  // An undefined result is the base rejecting the input; GraphQL reports it without running the validator.
   const scalar = new GraphQLScalarType({
     name: `${name}_${baseScalarType.name}`,
     description,
@@ -34,19 +52,21 @@ export function createValidatedScalar(name, description, baseScalarType, validat
       return baseScalarType.serialize(value);
     },
     parseValue(value) {
-      validate(value);
-      return baseScalarType.parseValue(value);
+      const parsed = baseScalarType.parseValue(value);
+      if (parsed !== undefined) validate(parsed);
+      return parsed;
     },
     parseLiteral(ast, variables) {
-      if (ast.kind !== baseKind) {
+      if (baseKinds !== undefined && !baseKinds.includes(ast.kind)) {
         throw new Error(`${name}_${baseScalarType.name} must be a ${baseScalarType.name}`);
       }
       const value = baseScalarType.parseLiteral(ast, variables);
-      validate(value);
+      if (value !== undefined) validate(value);
       return value;
     },
   });
 
   scalar.baseScalarType = baseScalarType;
+  validatedBases.set(scalar, baseScalarType);
   return scalar;
 }

package/src/scalars/pattern.js

@@ -0,0 +1,16 @@
+// A cross-realm RegExp fails `instanceof RegExp` but keeps this tag.
+const isRegExp = (value) => Object.prototype.toString.call(value) === '[object RegExp]';
+
+/** Private RegExp copy shared by `validators.pattern()` and `createPatternStringScalar()`; not a published subpath. */
+export const compilePattern = (pattern) => {
+  if (typeof pattern !== 'string' && !isRegExp(pattern)) {
+    throw new TypeError('pattern must be a RegExp or a string');
+  }
+  return new RegExp(pattern);
+};
+
+/** Tests each value from its first character, so `g` and `y` keep no state between values. */
+export const matchesPattern = (regex, value) => {
+  regex.lastIndex = 0;
+  return regex.test(value);
+};

package/src/scalars.js

@@ -3,6 +3,7 @@ import {
 } from 'graphql';
 import { createValidatedScalar } from './scalars/factory.js';
 import { isEmailFormat } from './scalars/email.js';
+import { compilePattern, matchesPattern } from './scalars/pattern.js';
 
 /**
  * Email scalar - validates email format
@@ -152,7 +153,7 @@ export const createBoundedFloatScalar = (name, min, max) => {
  * @returns {GraphQLScalarType} A scalar type with pattern validation
  */
 export const createPatternStringScalar = (name, pattern, message) => {
-  const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+  const regex = compilePattern(pattern);
   const errorMessage = message || 'Value does not match required pattern';
 
   return createValidatedScalar(
@@ -163,7 +164,7 @@ export const createPatternStringScalar = (name, pattern, message) => {
       if (typeof value !== 'string') {
         throw new Error('Value must be a string');
       }
-      if (!regex.test(value)) {
+      if (!matchesPattern(regex, value)) {
         throw new Error(errorMessage);
       }
     },

package/src/validators.js

@@ -1,5 +1,6 @@
 import SimfinityError from './errors/simfinity.error.js';
 import { isEmailFormat } from './scalars/email.js';
+import { compilePattern, matchesPattern } from './scalars/pattern.js';
 
 /**
  * Creates a validation object that works for both 'save' (CREATE) and 'update' (UPDATE) operations.
@@ -74,7 +75,7 @@ export const maxLength = (name, max) => {
 };
 
 export const pattern = (name, regex, message) => {
-  const regexObj = typeof regex === 'string' ? new RegExp(regex) : regex;
+  const regexObj = compilePattern(regex);
   const errorMessage = message || `${name} format is invalid`;
 
   return createValidator(async (typeName, fieldName, value) => {
@@ -82,7 +83,7 @@ export const pattern = (name, regex, message) => {
       throw new SimfinityError(`${name} must be a string`, 'VALIDATION_ERROR', 400);
     }
 
-    if (!regexObj.test(value)) {
+    if (!matchesPattern(regexObj, value)) {
       throw new SimfinityError(errorMessage, 'VALIDATION_ERROR', 400);
     }
   }, false); // Optional
@@ -109,8 +110,7 @@ export const url = () => {
     try {
       // Use URL constructor for better validation
       new URL(value);
-    } catch (e) {
-        console.log('Invalid URL format', e);
+    } catch {
       throw new SimfinityError('Invalid URL format', 'VALIDATION_ERROR', 400);
     }
   }, false); // Optional

package/types/index.d.ts

@@ -1,5 +1,6 @@
 import type {
   GraphQLEnumType,
+  GraphQLError,
   GraphQLInputObjectType,
   GraphQLObjectType,
   GraphQLOutputType,
@@ -43,6 +44,16 @@ export interface ModelDescription {
   }>;
 }
 export function describeModels(registrations: ModelRegistration[]): ModelDescription;
+/**
+ * Creates the scalar `${name}_${baseScalarType.name}`. `validate` throws to reject a value and
+ * receives the base scalar's internal value: the base's `parseValue` result for variables, the
+ * base's `parseLiteral` result for inline literals, and the resolver's value before serialization
+ * for output. Inline literal kinds are checked against the root of the chain of
+ * `createValidatedScalar` scalars when that root is String, ID, Int, Float or Boolean; a Float
+ * root accepts integer and float literals. Any other scalar is the root, even with a hand-set
+ * `baseScalarType` storage hint, and its own `parseLiteral` decides. `validate` is not called
+ * when the base rejects input by returning `undefined`.
+ */
 export function createValidatedScalar<TInternal, TExternal>(
   name: string,
   description: string,
@@ -55,6 +66,10 @@ export class SimfinityError extends Error {
   getCode(): string | undefined;
   getStatus(): number | undefined;
   getTimestamp(): string;
+  /** Set on errors that wrap a driver error, such as MongoDB's TRANSACTION_RETRY_EXCEEDED. */
+  cause?: unknown;
+  /** Set on errors that wrap a driver error, such as MongoDB's TRANSACTION_RETRY_EXCEEDED; returns `cause`. */
+  getCause?(): unknown;
 }
 
 export class InternalServerError extends SimfinityError {
@@ -62,7 +77,38 @@ export class InternalServerError extends SimfinityError {
   cause?: unknown;
   getCause(): unknown;
 }
-export function buildErrorFormatter(callback?: (error: SimfinityError) => Error | void): (error: Error) => Error;
+/**
+ * Creates an error formatter for a GraphQL server's error hook. A field error is a `GraphQLError`
+ * with a `path`: for the one graphql-js creates around a value raised while resolving a field, such
+ * as one a resolver threw, it classifies that value, and a raised `GraphQLError` that already had a
+ * path is classified as a field error itself. A path-less `GraphQLError` is a request error, even
+ * when it wraps a plain Error with the same message. An explicit `InternalServerError` cause,
+ * followed through GraphQLErrors only, is kept for masking; mark unexpected subscription source
+ * failures with it because a path-less wrapper cannot distinguish them from scalar input errors.
+ * Any other input, such as a syntax, validation or variable error, is classified as is:
+ * - a `SimfinityError` is kept;
+ * - a request `GraphQLError`, or one raised while resolving a field that has its own string
+ *   `extensions.code` or a `SimfinityError` cause, becomes a `SimfinityError` with its own message
+ *   and extensions (including ones the server added, such as Yoga's `http`). Its code is that of a
+ *   `SimfinityError` reached through `GraphQLError` causes only, else its string `extensions.code`
+ *   (so a code the server set, such as Yoga's `GRAPHQL_PARSE_FAILED`, is kept), else
+ *   `BAD_REQUEST`; its status is that error's, else its integer `extensions.status`, else 500 for
+ *   `INTERNAL_SERVER_ERROR` and 400 otherwise. Its `originalError` is never exposed, so input
+ *   rejected by Simfinity's validated scalars is `BAD_REQUEST` (400);
+ * - any other `GraphQLError` raised while resolving a field, including the ones graphql-js raises
+ *   when it cannot complete a resolved value (scalar or enum serialization, `isTypeOf`, abstract
+ *   type resolution, a non-iterable list), becomes `InternalServerError` with that message and the
+ *   error as its cause;
+ * - any other `Error` becomes `InternalServerError` with that error as its cause;
+ * - a non-Error value becomes `InternalServerError('Unexpected error value')` with no cause. Servers
+ *   whose executor first turns it into an `Error`, such as Yoga, pass the value's text instead.
+ *
+ * `callback` receives the classified error; check `error instanceof InternalServerError` to mask
+ * unexpected errors. A returned error replaces it, and a returned `GraphQLError` is returned
+ * unchanged. The result is a `GraphQLError` that keeps the input's locations and path, has the
+ * chosen error as `originalError`, and copies its `extensions`.
+ */
+export function buildErrorFormatter(callback?: (error: SimfinityError) => Error | void): (error: unknown) => GraphQLError;
 
 export interface EntityController<Session = any> {
   onSaving?(record: any, args: any, session: Session | undefined, context: any): void | Promise<void>;
@@ -87,6 +133,14 @@ export interface RuntimeRegistration<Model = any, Session = any> extends ModelRe
   controller?: EntityController<Session> | null;
   onModelCreated?: ((model: Model) => void) | null;
   stateMachine?: StateMachine<Session> | null;
+  /**
+   * Set by `createSchema()` before `adapter.prepare()`: true for entity types, those registered
+   * with `connect()` and the targets of non-embedded relations, whose `id` resolves to the stored
+   * `_id`, falling back to `id`. False for types this runtime uses only as embedded values. The `id`
+   * rule follows the type object, so a type that another runtime sharing it treats as an entity
+   * resolves `id` the same way here.
+   */
+  storedIdentity?: boolean;
 }
 export interface MiddlewareContext {
   args: any;
@@ -96,16 +150,86 @@ export interface MiddlewareContext {
   context?: any;
   [key: string]: any;
 }
+/** Operations that a type's `extensions.scope` can restrict. */
+export type ScopeOperation = 'find' | 'get_by_id' | 'aggregate';
+/** Argument of a scope function. Mutate `args` in place; the return value is ignored. */
+export interface ScopeParams<Model = any, Session = any> {
+  type: RuntimeRegistration<Model, Session>;
+  args: Record<string, any>;
+  operation: ScopeOperation;
+  context: any;
+}
+export type ScopeFunction<Model = any, Session = any> = (params: ScopeParams<Model, Session>) => unknown;
+/**
+ * Value of a type's `extensions.scope`: a plain object whose keys are scope operations and whose
+ * values are functions. Omit a key to leave that operation unscoped. A present key must hold a
+ * function: `{ find: undefined }` type-checks but throws `INVALID_SCOPE` (500) at startup, so
+ * leave the key out instead. Every own string key is checked, including non-enumerable ones. Any
+ * other shape throws `INVALID_SCOPE` at registration, at `createSchema()`, or on a read after it
+ * was changed.
+ */
+export type TypeScopes<Model = any, Session = any> = Partial<Record<ScopeOperation, ScopeFunction<Model, Session>>>;
+
+/**
+ * Process-wide limits for generated add, update and state-action mutations. Any other option,
+ * such as a misspelled `maxNestedOperation`, throws `INVALID_MUTATION_LIMITS` (400).
+ */
+export interface MutationLimitsOptions {
+  /**
+   * Maximum number of `added`, `updated` and `deleted` entries across every nested level of
+   * non-embedded collection fields in one generated mutation. A non-negative safe integer;
+   * `null` or omitted means unlimited (the default).
+   */
+  maxNestedOperations?: number | null;
+}
+
 export interface Runtime<Model = any, Session = any> {
   configureQueryLimits(options?: { maxPageSize?: number }): void;
+  /**
+   * Process-wide; calling it without options restores the unlimited default. Invalid options,
+   * including unknown or misspelled option keys, throw `INVALID_MUTATION_LIMITS` (400) and keep
+   * the current limit. A generated mutation over the limit fails with
+   * `NESTED_OPERATIONS_EXCEEDED` (400) before its transaction starts.
+   */
+  configureMutationLimits(options?: MutationLimitsOptions): void;
+  /**
+   * Throws `INVALID_SCOPE` (500) for an invalid `extensions.scope`, and
+   * `TYPE_BOUND_TO_OTHER_RUNTIME` (409) when another runtime bound the type by generating its
+   * relation resolvers, or reserved it because its schema reached the type with an unresolved
+   * relation field. A rejected type is not registered.
+   */
   connect(model: Model | null, type: GraphQLObjectType, singular: string, plural: string, controller?: EntityController<Session> | null, onModelCreated?: ((model: Model) => void) | null, stateMachine?: StateMachine<Session> | null): void;
+  /** Throws like `connect` for an invalid scope or a type bound to another runtime. */
   addNoEndpointType(type: GraphQLObjectType): void;
+  /**
+   * Validates every registered scope (`INVALID_SCOPE`) before building models, and rejects
+   * (`TYPE_BOUND_TO_OTHER_RUNTIME`) any reachable type that another runtime bound or reserved, or
+   * whose field was copied with `toConfig()` after another runtime generated its relation
+   * resolver, keeping the generated resolver or its extensions. A list or embedded relation to an unregistered type throws
+   * `UNREGISTERED_RELATION_TARGET` (500). A writable non-embedded list relation without a
+   * non-empty child `connectionField`, whose resolver this runtime would generate, throws
+   * `INVALID_MODEL` (400) before `adapter.prepare()`; one with an application resolver or
+   * `readOnly` only logs a `Configuration issue` warning, and its nested writes fail with
+   * `INVALID_MODEL` (500). Fields named like generated query arguments also log a warning. The
+   * first schema binds the types whose relation resolvers it generates to this runtime and
+   * reserves reachable types that still have a
+   * non-embedded relation field without a resolver, such as an unregistered custom mutation result.
+   * Every entity type resolves `id` to `_id ?? id`, whatever the allowlists include.
+   */
   createSchema(includedQueryTypes?: GraphQLObjectType[] | null, includedMutationTypes?: GraphQLObjectType[] | null, includedCustomMutations?: string[] | null): GraphQLSchema;
   getModel(type: GraphQLObjectType | { name: string }): Model | null | undefined;
   getType(name: string | { name: string }): GraphQLObjectType | null | undefined;
   /** Available after createSchema has built input types. */
   getInputType(type: GraphQLObjectType | { name: string }): GraphQLInputObjectType | undefined;
   getRegistrations(): RuntimeRegistration<Model, Session>[];
+  /**
+   * Middleware runs in registration order before the operation. Throws `INVALID_MIDDLEWARE`
+   * (500) for a non-function. The rest of the chain runs at most once and is awaited even when a
+   * middleware does not await `next()`; its errors cancel the operation, even if a middleware
+   * catches them. Call `next()` before the middleware returns or its promise settles: a later
+   * call, such as `setTimeout(next)`, does nothing. Omitting `next()` skips the remaining
+   * middleware only.
+   */
   use(middleware: (params: MiddlewareContext, next: () => Promise<void>) => void | Promise<void>): void;
   registerMutation(name: string, description: string, input: GraphQLInputObjectType | null | undefined, output: GraphQLOutputType, callback: (args: any, session: Session, context: any) => any): void;
   /** Owns the full workflow transaction unless an active caller session is supplied. */
@@ -119,12 +243,29 @@ export interface DatabaseAdapter<Model = any, Session = any> {
   validateRegistration?(registration: RuntimeRegistration<Model, Session>): void;
   prepare?(registrations: RuntimeRegistration<Model, Session>[], options: { createCollection: boolean }): void;
   createModel(type: GraphQLObjectType, callback: ((model: Model) => void) | null | undefined, options: { createCollection: boolean }): Model;
+  /**
+   * Casts a reference or batch key to the stored identifier type. Throw a `SimfinityError` with
+   * code `NOT_VALID_ID` (400) for a malformed value; never create a new identifier. A batched
+   * reference read whose ID throws or is normalized reads that ID alone with `getById`. When
+   * `getById` rejects a stored reference with that error, the generated reference field fails with
+   * an `InternalServerError` whose cause is that error, since the client did not send the value.
+   */
   castId(value: any): any;
   stateValue?(state: { name: string; value: any }): any;
   withTransaction<T>(session: Session | null | undefined, callback: (session: Session) => Promise<T> | T, model?: Model): Promise<T>;
   newRecord(model: Model, data: any, session?: Session): any;
   saveRecord(model: Model, record: any, session?: Session): any;
   toObject(record: any): any;
+  /**
+   * Optional. When defined, every nullable, singular embedded object field without a resolver
+   * passes its value through `readEmbeddedValue(value)`. The field is read as graphql's default
+   * resolver reads it: a method on the parent is called with (args, context, info), and the hook
+   * receives its result once a returned promise settles. Return null for a value that a hydrated
+   * record renders as an object although the stored value is an explicit null; return any other
+   * value unchanged. It must depend only on the value: these resolvers read no data and do not bind
+   * their types, so a runtime that reaches a shared type may read through another runtime's hook.
+   */
+  readEmbeddedValue?(value: any): any;
   getById(model: Model, id: any, session?: Session | null, options?: { projection?: Record<string, number>; plain?: boolean; lock?: boolean; requiredId?: any; context?: any }): any;
   /** Optional batch read: the records found for `ids`, in getById shape and any order. After a failure, the runtime reads each ID with getById. */
   getByIds?(model: Model, ids: any[], options?: { context?: any }): any;
@@ -151,6 +292,11 @@ export function createQueryPlan(models: ModelDescription, entityName: string, in
 export function resolveModelPath(models: ModelDescription, entityName: string, path: string | string[]): FieldDescription[];
 
 export function configureQueryLimits(options?: { maxPageSize?: number }): void;
+/**
+ * Same process-wide setting as `Runtime.configureMutationLimits`. Unknown or misspelled options
+ * throw `INVALID_MUTATION_LIMITS` (400) and keep the current limit.
+ */
+export function configureMutationLimits(options?: MutationLimitsOptions): void;
 export function paginationStages(pagination: { page: number; size: number } | null | undefined, withDefault: boolean): Array<{ $skip: number } | { $limit: number }>;
 
 /** Envelop-style schema plugin used by the shared authorization helpers. */
@@ -181,6 +327,11 @@ export interface FieldValidations {
 export const validators: {
   stringLength(name: string, min?: number, max?: number): FieldValidations;
   maxLength(name: string, max: number): FieldValidations;
+  /**
+   * Copies the pattern when the helper is created and tests each value from its first character,
+   * so `g` and `y` keep no state between values. Throws `TypeError` unless the pattern is a
+   * `RegExp` or a string.
+   */
   pattern(name: string, regex: RegExp | string, message?: string): FieldValidations;
   email(): FieldValidations;
   url(): FieldValidations;
@@ -204,6 +355,7 @@ export const scalars: {
   createBoundedStringScalar(name: string, min?: number, max?: number): GraphQLScalarType;
   createBoundedIntScalar(name: string, min?: number, max?: number): GraphQLScalarType;
   createBoundedFloatScalar(name: string, min?: number, max?: number): GraphQLScalarType;
+  /** Same pattern rules as `validators.pattern`: a private copy, tested from the first character. */
   createPatternStringScalar(name: string, pattern: RegExp | string, message?: string): GraphQLScalarType;
 };
 
@@ -248,7 +400,11 @@ declare class ForbiddenError extends SimfinityError {
 
 /** Authorization utilities (RBAC/ABAC rules, plugin factories and auth errors). */
 export const auth: {
-  /** Wraps schema resolvers in-place. Throws TypeError for invalid rules, maps, or defaultPolicy. */
+  /**
+   * Wraps schema resolvers in-place. Throws TypeError for invalid rules, maps, or defaultPolicy.
+   * `onSchemaChange` throws TypeError, before wrapping any field, when a schema type was created
+   * by another copy of the graphql module.
+   */
   createAuthPlugin(permissions: PermissionSchema, options?: AuthPluginOptions): EnvelopSchemaPlugin;
   /** @deprecated Use createAuthPlugin instead. graphql-middleware compatible middleware. */
   createAuthMiddleware(
@@ -264,24 +420,40 @@ export const auth: {
     options?: AuthPluginOptions,
   ): (resolve: any, parent: any, args: any, ctx: any, info: any) => Promise<any>;
   resolvePath(obj: any, pathOrFn: string | ((obj: any) => any)): any;
-  requireAuth(userPath?: string): AuthRuleFunction;
+  /**
+   * Paths in the helpers below are dotted strings or synchronous extractors. An `async`
+   * extractor throws TypeError when the helper is created; a path that yields a promise or other
+   * thenable denies with TypeError.
+   */
+  requireAuth(userPath?: string | ((ctx: any) => unknown)): AuthRuleFunction;
   /** Required roles must be nonempty strings; invalid configuration throws TypeError. */
-  requireRole(role: string | string[], options?: { userPath?: string; rolePath?: string }): AuthRuleFunction;
+  requireRole(
+    role: string | string[],
+    options?: { userPath?: string | ((ctx: any) => unknown); rolePath?: string | ((user: any) => unknown) },
+  ): AuthRuleFunction;
   /** Exact array membership; only a standalone '*' claim grants all permissions. */
   requirePermission(
     permission: string | string[],
-    options?: { userPath?: string; permissionsPath?: string },
+    options?: { userPath?: string | ((ctx: any) => unknown); permissionsPath?: string | ((user: any) => unknown) },
   ): AuthRuleFunction;
   /** Requires at least one rule function; throws TypeError otherwise. */
   composeRules(...rules: AuthRuleFunction[]): AuthRuleFunction;
   /** Requires at least one rule function; throws TypeError otherwise. */
   anyRule(...rules: AuthRuleFunction[]): AuthRuleFunction;
   /** Compares nonempty string, finite number, or MongoDB ObjectId identities; missing IDs deny. */
-  isOwner(ownerField?: string, userIdField?: string, options?: { userPath?: string }): AuthRuleFunction;
+  isOwner(
+    ownerField?: string | ((parent: any) => unknown),
+    userIdField?: string | ((user: any) => unknown),
+    options?: { userPath?: string | ((ctx: any) => unknown) },
+  ): AuthRuleFunction;
   createRule(predicate: AuthRuleFunction, errorMessage?: string, errorCode?: string): AuthRuleFunction;
   allow(): AuthRuleFunction;
   deny(message?: string): AuthRuleFunction;
-  /** Invalid ASTs and unresolved comparisons deny, including under negation. */
+  /**
+   * Invalid ASTs and unresolved comparisons deny, including under negation. Dates compare by
+   * time. Promise operands are always invalid; NaN and Date/non-Date comparisons are invalid
+   * except against `null`, which stays comparable with any value (the comparison is false).
+   */
   evaluateExpression(expression: unknown, context: any): boolean;
   isPolicyExpression(value: unknown): boolean;
   /** Throws TypeError for a malformed expression. */