@simtlix/simfinity-core 3.5.7 → 3.5.9

package/types/index.d.ts

@@ -75,6 +75,13 @@ export class SimfinityError extends Error {
   getCause?(): unknown;
 }
 
+/**
+ * An unexpected failure: code `INTERNAL_SERVER_ERROR` and status 500 (`getStatus()` and
+ * `extensions.status`). `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.
+ */
 export class InternalServerError extends SimfinityError {
   constructor(message: string, cause?: unknown);
   cause?: unknown;
@@ -106,6 +113,8 @@ export class InternalServerError extends SimfinityError {
  * - 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.
  *
+ * Every `InternalServerError` has code `INTERNAL_SERVER_ERROR` and status 500.
+ *
  * `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
@@ -218,11 +227,30 @@ export interface Runtime<Model = any, Session = any> {
    * 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.
+   *
+   * A generated input that would have no fields is left out, with a `Configuration issue`
+   * warning: the `added` or `updated` operation of a collection whose child has no writable fields
+   * for it, an embedded field whose embedded type has none, `add<type>` for a type without
+   * writable fields, and `update<type>` and its state actions for a type without writable fields
+   * and without a writable `id`. A non-null embedded field whose embedded type has no writable
+   * fields throws `INVALID_MODEL` (400) while inputs are built when the generated mutations reach
+   * its owner's create input. When the process's first Simfinity schema has an application type
+   * named `FieldExtensionsType` or `RelationType`, Simfinity renames its `__Field.extensions`
+   * metadata types `SimfinityFieldExtensionsType` and `SimfinityRelationType` (numbered when
+   * taken) for every later schema and logs a warning; once those names are fixed, a type with one
+   * of them 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. The check before `adapter.prepare()` never reads an input object's
+   * fields, so a registered input's `fields` function may call `getInputType()`.
    */
   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. */
+  /**
+   * Available after createSchema has built input types. It has no fields for a type without
+   * writable fields; such inputs are not part of generated schemas.
+   */
   getInputType(type: GraphQLObjectType | { name: string }): GraphQLInputObjectType | undefined;
   getRegistrations(): RuntimeRegistration<Model, Session>[];
   /**
@@ -267,8 +295,31 @@ export interface DatabaseAdapter<Model = any, Session = any> {
    * 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.
+   * Simfinity then reads as null an object that holds no data when a non-null member would read as
+   * null, whatever the selection. These members do not count: `id`, readOnly members, interface and
+   * union members, members with their own resolver and referenced collections. An object whose type
+   * has no member that counts is returned untouched. Otherwise Simfinity reads the stored members
+   * (see `rawEmbeddedValue`), never calling a getter, and counts a stored `_id` as `id`; an error
+   * while reading them returns the object unchanged. Runtimes that share the type read through the
+   * same resolver, with or without the hook. On MongoDB, a create that writes an empty object for a
+   * required embedded member stores it as absent (Mongoose minimizes it), so an object that holds
+   * nothing else reads as null too, except in by-ID and reference reads and update responses where
+   * the member is a nested path, as generated models declare every embedded member except one named
+   * `type`.
    */
   readEmbeddedValue?(value: any): any;
+  /**
+   * Optional, used with `readEmbeddedValue`. Returns the stored data of a hydrated embedded value
+   * as a plain object, without running getters or virtuals, such as a document's raw data; returns
+   * any other value unchanged. Return a hydrated value unchanged when its stored data does not show
+   * what it renders, such as one whose schema supplies members through getters, virtuals, methods
+   * or aliases: a value that is not a plain object counts as data, so Simfinity keeps it as it is.
+   * Simfinity calls it on the embedded objects it checks for data, including those it finds inside
+   * the returned data, and reads only own data properties of the result; a null or undefined result
+   * has no members. Without it, a plain object is read as it is, an accessor property counts as
+   * present without being called, and a value that is not a plain object counts as data.
+   */
+  rawEmbeddedValue?(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;
@@ -326,10 +377,20 @@ export interface FieldValidations {
   update: FieldValidator[];
 }
 
-/** Built-in field validator factories. */
+/**
+ * What `validators.arrayLength()` runs on each item: a validator, a helper result such as
+ * `validators.maxLength('Tag', 20)`, whose `CREATE` rules run on every item on create and update,
+ * or an array of them. Falsy array entries are skipped, so `[flag && rule]` works.
+ */
+export type ItemValidators =
+  | FieldValidator
+  | FieldValidations
+  | ReadonlyArray<FieldValidator | FieldValidations | null | undefined | false | '' | 0>;
+
+/** Built-in field validator factories. A `null` or omitted bound means no bound. */
 export const validators: {
-  stringLength(name: string, min?: number, max?: number): FieldValidations;
-  maxLength(name: string, max: number): FieldValidations;
+  stringLength(name: string, min?: number | null, max?: number | null): FieldValidations;
+  maxLength(name: string, max: number | null): 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
@@ -338,10 +399,25 @@ export const validators: {
   pattern(name: string, regex: RegExp | string, message?: string): FieldValidations;
   email(): FieldValidations;
   url(): FieldValidations;
-  numberRange(name: string, min?: number, max?: number): FieldValidations;
+  numberRange(name: string, min?: number | null, max?: number | null): FieldValidations;
   positive(name: string): FieldValidations;
-  arrayLength(name: string, maxItems?: number, itemValidator?: FieldValidator[]): FieldValidations;
+  /**
+   * A falsy `itemValidator` adds no item checks. A single validator runs when it is a plain object or a
+   * function; a class instance with its own `validate()`, such as a Joi or yup schema, is ignored with a
+   * warning. Other unusable values log a `Configuration issue` warning when the helper is created.
+   */
+  arrayLength(
+    name: string,
+    maxItems?: number | null,
+    itemValidator?: FieldValidator | FieldValidator[] | FieldValidations | ItemValidators | null | undefined | false | '' | 0,
+  ): FieldValidations;
+  /**
+   * Values must be dates JavaScript can parse. Strings that start with an ISO date (`YYYY-MM-DD`), and
+   * slashed `MM/DD/YYYY` strings, must be real calendar dates, so `2024-02-31` and `02/31/2024` fail.
+   * Only the `'YYYY-MM-DD'` format is checked; any other format logs a warning when the helper is created.
+   */
   dateFormat(name: string, format?: string): FieldValidations;
+  /** Same date checks as `dateFormat()` without a format, plus the date must be in the future. */
   futureDate(name: string): FieldValidations;
 };
 
@@ -355,9 +431,12 @@ export const scalars: {
   URLScalar: GraphQLScalarType;
   PositiveIntScalar: GraphQLScalarType;
   PositiveFloatScalar: GraphQLScalarType;
-  createBoundedStringScalar(name: string, min?: number, max?: number): GraphQLScalarType;
-  createBoundedIntScalar(name: string, min?: number, max?: number): GraphQLScalarType;
-  createBoundedFloatScalar(name: string, min?: number, max?: number): GraphQLScalarType;
+  /** A `null` or omitted bound means no bound; the description names only the bounds that are set. */
+  createBoundedStringScalar(name: string, min?: number | null, max?: number | null): GraphQLScalarType;
+  /** A `null` or omitted bound means no bound; the description names only the bounds that are set. */
+  createBoundedIntScalar(name: string, min?: number | null, max?: number | null): GraphQLScalarType;
+  /** A `null` or omitted bound means no bound; the description names only the bounds that are set. */
+  createBoundedFloatScalar(name: string, min?: number | null, max?: number | null): GraphQLScalarType;
   /** Same pattern rules as `validators.pattern`: a private copy, tested from the first character. */
   createPatternStringScalar(name: string, pattern: RegExp | string, message?: string): GraphQLScalarType;
 };
@@ -393,11 +472,19 @@ export interface AuthPluginOptions {
   debug?: boolean;
 }
 
-declare class UnauthenticatedError extends SimfinityError {
+/**
+ * Authentication error: code `UNAUTHENTICATED`, status 401, default message `Authentication required`.
+ * The same class as `auth.UnauthenticatedError` and the `/auth` and `/auth/errors` subpath exports.
+ */
+export class UnauthenticatedError extends SimfinityError {
   constructor(message?: string);
 }
 
-declare class ForbiddenError extends SimfinityError {
+/**
+ * Authorization error: code `FORBIDDEN`, status 403, default message `Access denied`.
+ * The same class as `auth.ForbiddenError` and the `/auth` and `/auth/errors` subpath exports.
+ */
+export class ForbiddenError extends SimfinityError {
   constructor(message?: string);
 }
 
@@ -429,14 +516,20 @@ export const auth: {
    * thenable denies with TypeError.
    */
   requireAuth(userPath?: string | ((ctx: any) => unknown)): AuthRuleFunction;
-  /** Required roles must be nonempty strings; invalid configuration throws TypeError. */
+  /**
+   * Required roles must be nonempty strings; invalid configuration throws TypeError. The array,
+   * which may be readonly, is copied when the rule is created.
+   */
   requireRole(
-    role: string | string[],
+    role: string | readonly string[],
     options?: { userPath?: string | ((ctx: any) => unknown); rolePath?: string | ((user: any) => unknown) },
   ): AuthRuleFunction;
-  /** Exact array membership; only a standalone '*' claim grants all permissions. */
+  /**
+   * Exact array membership; only a standalone '*' claim grants all permissions. The array of
+   * required permissions, which may be readonly, is copied when the rule is created.
+   */
   requirePermission(
-    permission: string | string[],
+    permission: string | readonly string[],
     options?: { userPath?: string | ((ctx: any) => unknown); permissionsPath?: string | ((user: any) => unknown) },
   ): AuthRuleFunction;
   /** Requires at least one rule function; throws TypeError otherwise. */

package/types/plugins.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Declarations for `@simtlix/simfinity-core/plugins`. The default export is the root `plugins`
+ * namespace, and every named export has the type of the same member, so the two cannot drift.
+ */
+import { plugins } from './index.js';
+
+export type { AuthPluginOptions, EnvelopSchemaPlugin, PermissionSchema } from './index.js';
+// The /auth declaration itself, as the runtime re-exports that binding, so the two subpaths can be
+// re-exported together.
+export { createAuthPlugin } from './auth/index.js';
+export const apolloCountPlugin: typeof plugins.apolloCountPlugin;
+export const envelopCountPlugin: typeof plugins.envelopCountPlugin;
+
+export default plugins;

package/types/scalars.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Declarations for `@simtlix/simfinity-core/scalars`. The default export is the root `scalars`
+ * namespace, and every named export has the type of the same member, so the two cannot drift.
+ */
+import { scalars } from './index.js';
+
+export const EmailScalar: typeof scalars.EmailScalar;
+export const URLScalar: typeof scalars.URLScalar;
+export const PositiveIntScalar: typeof scalars.PositiveIntScalar;
+export const PositiveFloatScalar: typeof scalars.PositiveFloatScalar;
+export const createBoundedStringScalar: typeof scalars.createBoundedStringScalar;
+export const createBoundedIntScalar: typeof scalars.createBoundedIntScalar;
+export const createBoundedFloatScalar: typeof scalars.createBoundedFloatScalar;
+export const createPatternStringScalar: typeof scalars.createPatternStringScalar;
+
+export default scalars;

package/types/validators.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Declarations for `@simtlix/simfinity-core/validators`. The default export is the root
+ * `validators` namespace, and every named export has the type of the same member, so the two
+ * cannot drift. A root type used by these helpers belongs in the `export type` list below.
+ */
+import { validators } from './index.js';
+
+export type { FieldValidations, FieldValidator, ItemValidators } from './index.js';
+export const stringLength: typeof validators.stringLength;
+export const maxLength: typeof validators.maxLength;
+export const pattern: typeof validators.pattern;
+export const email: typeof validators.email;
+export const url: typeof validators.url;
+export const numberRange: typeof validators.numberRange;
+export const positive: typeof validators.positive;
+export const arrayLength: typeof validators.arrayLength;
+export const dateFormat: typeof validators.dateFormat;
+export const futureDate: typeof validators.futureDate;
+
+export default validators;