@simtlix/simfinity-core 3.5.1 → 3.5.3

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,
@@ -62,7 +73,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>;
@@ -96,16 +138,80 @@ 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). 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.
+   */
   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. */
@@ -151,6 +257,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 +292,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 +320,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,35 +365,60 @@ 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(
     permissions: PermissionSchema,
     options?: AuthPluginOptions,
   ): (resolve: any, parent: any, args: any, ctx: any, info: any) => Promise<any>;
-  /** @deprecated Use createAuthPlugin instead. Field middleware object for graphql-middleware. */
+  /**
+   * @deprecated Use createAuthPlugin instead. The same graphql-middleware function as
+   * createAuthMiddleware, which applies wildcard rules and the default policy to every field.
+   */
   createFieldMiddleware(
     permissions: PermissionSchema,
     options?: AuthPluginOptions,
-  ): Record<string, Record<string, any>>;
+  ): (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. */