@simtlix/simfinity-core 3.5.7 → 3.5.8

package/src/scalars.js

@@ -67,26 +67,56 @@ export const PositiveFloatScalar = createValidatedScalar(
   },
 );
 
+// A null or omitted bound means no bound (#97). Other values keep JavaScript's comparison, so numeric strings work.
+const hasBound = (bound) => bound !== undefined && bound !== null;
+
+// The published description names only the bounds that are set. A NaN bound, which no comparison applies, is left out
+// too. With both bounds the text is the same as in earlier versions.
+const describeBounds = (min, max, texts) => {
+  const described = (bound) => hasBound(bound) && !(typeof bound === 'number' && Number.isNaN(bound));
+  if (described(min) && described(max)) return texts.between;
+  if (described(min)) return texts.atLeast;
+  if (described(max)) return texts.atMost;
+  return texts.unbounded;
+};
+
+const checkNumberBounds = (min, max) => (value) => {
+  if (typeof value !== 'number' || isNaN(value)) {
+    throw new Error('Value must be a number');
+  }
+  if (hasBound(min) && value < min) {
+    throw new Error(`Value must be at least ${min}`);
+  }
+  if (hasBound(max) && value > max) {
+    throw new Error(`Value must be at most ${max}`);
+  }
+};
+
 /**
  * Factory function to create a bounded string scalar
  * @param {string} name - Name for the scalar
- * @param {number} min - Minimum length
- * @param {number} max - Maximum length
+ * @param {number|null} [min] - Minimum length; null or undefined means no minimum
+ * @param {number|null} [max] - Maximum length; null or undefined means no maximum
  * @returns {GraphQLScalarType} A scalar type with length validation
  */
 export const createBoundedStringScalar = (name, min, max) => {
   return createValidatedScalar(
     name,
-    `A string with length between ${min} and ${max} characters`,
+    describeBounds(min, max, {
+      between: `A string with length between ${min} and ${max} characters`,
+      atLeast: `A string with at least ${min} characters`,
+      atMost: `A string with at most ${max} characters`,
+      unbounded: 'A string',
+    }),
     GraphQLString,
     (value) => {
       if (typeof value !== 'string') {
         throw new Error('Value must be a string');
       }
-      if (min !== undefined && value.length < min) {
+      if (hasBound(min) && value.length < min) {
         throw new Error(`String must be at least ${min} characters`);
       }
-      if (max !== undefined && value.length > max) {
+      if (hasBound(max) && value.length > max) {
         throw new Error(`String must be at most ${max} characters`);
       }
     },
@@ -96,52 +126,42 @@ export const createBoundedStringScalar = (name, min, max) => {
 /**
  * Factory function to create a bounded integer scalar
  * @param {string} name - Name for the scalar
- * @param {number} min - Minimum value
- * @param {number} max - Maximum value
+ * @param {number|null} [min] - Minimum value; null or undefined means no minimum
+ * @param {number|null} [max] - Maximum value; null or undefined means no maximum
  * @returns {GraphQLScalarType} A scalar type with range validation
  */
 export const createBoundedIntScalar = (name, min, max) => {
   return createValidatedScalar(
     name,
-    `An integer between ${min} and ${max}`,
+    describeBounds(min, max, {
+      between: `An integer between ${min} and ${max}`,
+      atLeast: `An integer of at least ${min}`,
+      atMost: `An integer of at most ${max}`,
+      unbounded: 'An integer',
+    }),
     GraphQLInt,
-    (value) => {
-      if (typeof value !== 'number' || isNaN(value)) {
-        throw new Error('Value must be a number');
-      }
-      if (min !== undefined && value < min) {
-        throw new Error(`Value must be at least ${min}`);
-      }
-      if (max !== undefined && value > max) {
-        throw new Error(`Value must be at most ${max}`);
-      }
-    },
+    checkNumberBounds(min, max),
   );
 };
 
 /**
  * Factory function to create a bounded float scalar
  * @param {string} name - Name for the scalar
- * @param {number} min - Minimum value
- * @param {number} max - Maximum value
+ * @param {number|null} [min] - Minimum value; null or undefined means no minimum
+ * @param {number|null} [max] - Maximum value; null or undefined means no maximum
  * @returns {GraphQLScalarType} A scalar type with range validation
  */
 export const createBoundedFloatScalar = (name, min, max) => {
   return createValidatedScalar(
     name,
-    `A float between ${min} and ${max}`,
+    describeBounds(min, max, {
+      between: `A float between ${min} and ${max}`,
+      atLeast: `A float of at least ${min}`,
+      atMost: `A float of at most ${max}`,
+      unbounded: 'A float',
+    }),
     GraphQLFloat,
-    (value) => {
-      if (typeof value !== 'number' || isNaN(value)) {
-        throw new Error('Value must be a number');
-      }
-      if (min !== undefined && value < min) {
-        throw new Error(`Value must be at least ${min}`);
-      }
-      if (max !== undefined && value > max) {
-        throw new Error(`Value must be at most ${max}`);
-      }
-    },
+    checkNumberBounds(min, max),
   );
 };
 

package/src/validators.js

@@ -43,6 +43,9 @@ const createValidator = (validatorFn, required = false) => {
   };
 };
 
+// A null or omitted bound means no bound (#97). Other values keep JavaScript's comparison, so numeric strings work.
+const hasBound = (bound) => bound !== undefined && bound !== null;
+
 /**
  * String validators
  */
@@ -52,11 +55,11 @@ export const stringLength = (name, min, max) => {
       throw new SimfinityError(`${name} must be a string`, 'VALIDATION_ERROR', 400);
     }
 
-    if (min !== undefined && value.length < min) {
+    if (hasBound(min) && value.length < min) {
       throw new SimfinityError(`${name} must be at least ${min} characters`, 'VALIDATION_ERROR', 400);
     }
 
-    if (max !== undefined && value.length > max) {
+    if (hasBound(max) && value.length > max) {
       throw new SimfinityError(`${name} must be at most ${max} characters`, 'VALIDATION_ERROR', 400);
     }
   }, true); // Required for CREATE operations
@@ -68,7 +71,7 @@ export const maxLength = (name, max) => {
       throw new SimfinityError(`${name} must be a string`, 'VALIDATION_ERROR', 400);
     }
 
-    if (value.length > max) {
+    if (hasBound(max) && value.length > max) {
       throw new SimfinityError(`${name} must be at most ${max} characters`, 'VALIDATION_ERROR', 400);
     }
   }, false); // Optional
@@ -125,11 +128,11 @@ export const numberRange = (name, min, max) => {
       throw new SimfinityError(`${name} must be a number`, 'VALIDATION_ERROR', 400);
     }
 
-    if (min !== undefined && value < min) {
+    if (hasBound(min) && value < min) {
       throw new SimfinityError(`${name} must be at least ${min}`, 'VALIDATION_ERROR', 400);
     }
 
-    if (max !== undefined && value > max) {
+    if (hasBound(max) && value > max) {
       throw new SimfinityError(`${name} must be at most ${max}`, 'VALIDATION_ERROR', 400);
     }
   }, false); // Optional
@@ -150,22 +153,96 @@ export const positive = (name) => {
 /**
  * Array validators
  */
+
+// What arrayLength() runs on each item (#92). A validator is anything with a validate() function.
+const isFieldValidator = (candidate) => candidate !== null
+  && (typeof candidate === 'object' || typeof candidate === 'function')
+  && typeof candidate.validate === 'function';
+
+// A helper result such as validators.maxLength('Tag', 3). Items of a supplied list are always present, so they get
+// the helper's CREATE rules on create and update, like the documented validators.maxLength('Tag', 3).CREATE.
+const isFieldValidations = (candidate) => candidate !== null && typeof candidate === 'object'
+  && !Array.isArray(candidate) && Array.isArray(candidate.CREATE) && candidate.CREATE.every(isFieldValidator);
+
+// Array entries: every validator runs, as before, and a helper result runs its CREATE rules.
+const itemRulesOf = (entry) => {
+  if (isFieldValidator(entry)) return [entry];
+  if (isFieldValidations(entry)) return entry.CREATE;
+  return null;
+};
+
+// A single itemValidator was ignored before, so only shapes written for Simfinity run now: helper results, and plain
+// objects or functions with validate(). A class instance with its own validate(), such as a Joi or yup schema, takes
+// other arguments, so it stays ignored.
+const isPlainValidator = (candidate) => isFieldValidator(candidate)
+  && (typeof candidate === 'function' || [Object.prototype, null].includes(Object.getPrototypeOf(candidate)));
+
+const ITEM_VALIDATOR_SHAPES = 'a validator object with validate(), a helper result such as validators.maxLength(\'Item\', 20), or an array of them';
+
+// Resolves itemValidator once, when arrayLength() runs. No shape throws here, so every application that starts keeps
+// starting; unusable shapes log one 'Configuration issue' warning instead.
+const itemValidationOf = (name, itemValidator) => {
+  // undefined, null, false, '' and 0 add no item checks, so `flag && rules` works.
+  if (!itemValidator) return null;
+
+  if (Array.isArray(itemValidator)) {
+    // Falsy entries are skipped. Any other unusable entry keeps failing lists with items, as before.
+    const unusable = itemValidator.flatMap((entry, index) => (!entry || itemRulesOf(entry) ? [] : [`itemValidator[${index}]`]));
+    if (unusable.length > 0) {
+      console.warn(`Configuration issue: validators.arrayLength('${name}') has an unusable ${unusable.join(', ')}; `
+        + `lists with items fail with a TypeError. Pass ${ITEM_VALIDATOR_SHAPES}.`);
+    }
+    // The array is read on every validation, as before, so entries added after creation run too.
+    return async (typeName, fieldName, item, session) => {
+      for (let index = 0; index < itemValidator.length; index++) {
+        const entry = itemValidator[index];
+        if (!entry) continue;
+        const rules = itemRulesOf(entry);
+        if (!rules) {
+          throw new TypeError(`validators.arrayLength('${name}'): itemValidator[${index}] is not a validator with a validate() function`);
+        }
+        for (const rule of rules) {
+          await rule.validate(typeName, fieldName, item, session);
+        }
+      }
+    };
+  }
+
+  let rules = null;
+  if (isPlainValidator(itemValidator)) {
+    rules = [itemValidator];
+  } else if (isFieldValidations(itemValidator)) {
+    rules = itemValidator.CREATE;
+  }
+  if (!rules) {
+    const shape = isFieldValidator(itemValidator)
+      ? 'a class instance whose validate() is not a Simfinity validator (such as a Joi or yup schema)'
+      : `not ${ITEM_VALIDATOR_SHAPES}`;
+    console.warn(`Configuration issue: validators.arrayLength('${name}') ignores its itemValidator, which is ${shape}; `
+      + 'items are not validated.');
+    return null;
+  }
+  return async (typeName, fieldName, item, session) => {
+    for (const rule of rules) {
+      await rule.validate(typeName, fieldName, item, session);
+    }
+  };
+};
+
 export const arrayLength = (name, maxItems, itemValidator) => {
+  const validateItem = itemValidationOf(name, itemValidator);
   return createValidator(async (typeName, fieldName, value, session) => {
     if (!Array.isArray(value)) {
       throw new SimfinityError(`${name} must be an array`, 'VALIDATION_ERROR', 400);
     }
 
-    if (maxItems !== undefined && value.length > maxItems) {
+    if (hasBound(maxItems) && value.length > maxItems) {
       throw new SimfinityError(`${name} must have at most ${maxItems} items`, 'VALIDATION_ERROR', 400);
     }
 
-    // If itemValidator is provided, validate each item
-    if (itemValidator && Array.isArray(itemValidator)) {
+    if (validateItem) {
       for (let i = 0; i < value.length; i++) {
-        for (const validator of itemValidator) {
-          await validator.validate(typeName, fieldName, value[i], session);
-        }
+        await validateItem(typeName, fieldName, value[i], session);
       }
     }
   }, false); // Optional
@@ -174,52 +251,87 @@ export const arrayLength = (name, maxItems, itemValidator) => {
 /**
  * Date validators
  */
+
+// Calendar arithmetic (#94), independent of the process time zone.
+const isLeapYear = (year) => (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+const isCalendarDate = (year, month, day) => month >= 1 && month <= 12 && day >= 1
+  && day <= (month === 2 && isLeapYear(year) ? 29 : DAYS_IN_MONTH[month - 1]);
+
+// The only format dateFormat() checks.
+const ISO_DATE_FORMAT = 'YYYY-MM-DD';
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+// A leading ISO date, alone or followed by a time or a zone.
+const ISO_DATE_PREFIX = /^(\d{4})-(\d{2})-(\d{2})(?!\d)/;
+// JavaScript reads slashed dates month first.
+const SLASHED_DATE = /^(\d{1,2})\/(\d{1,2})\/(\d{4})$/;
+
+// Strings that JavaScript parses by rolling an impossible day into the next month, such as 2024-02-31 or 02/31/2024.
+// Only values whose stored date never matched what was sent qualify, so no correctly stored value is rejected.
+const isRolledOverDate = (value) => {
+  const iso = ISO_DATE_PREFIX.exec(value);
+  if (iso) return !isCalendarDate(Number(iso[1]), Number(iso[2]), Number(iso[3]));
+  const slashed = SLASHED_DATE.exec(value);
+  if (slashed) return !isCalendarDate(Number(slashed[3]), Number(slashed[1]), Number(slashed[2]));
+  return false;
+};
+
+// Date objects, and strings or timestamps that JavaScript can parse, as before.
+const parseDate = (name, value) => {
+  let date;
+  if (value instanceof Date) {
+    date = value;
+  } else if (typeof value === 'string' || typeof value === 'number') {
+    date = new Date(value);
+  } else {
+    throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
+  }
+
+  if (isNaN(date.getTime())) {
+    throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
+  }
+  return date;
+};
+
+// parseDate, plus the calendar check for strings that JavaScript would roll into the next month.
+const toDate = (name, value) => {
+  const date = parseDate(name, value);
+  if (typeof value === 'string' && isRolledOverDate(value)) {
+    throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
+  }
+  return date;
+};
+
 export const dateFormat = (name, format) => {
+  const checksFormat = format === ISO_DATE_FORMAT;
+  // Other formats were never checked. They keep that behavior, and the warning says so once, here.
+  if (format && !checksFormat) {
+    const label = typeof format === 'string' ? `'${format}'` : `of type ${typeof format}`;
+    console.warn(`Configuration issue: validators.dateFormat('${name}') does not check the format ${label}; `
+      + `only '${ISO_DATE_FORMAT}' is checked, so other values pass when JavaScript can parse them as a valid date.`);
+  }
+
   return createValidator(async (typeName, fieldName, value) => {
-    // Handle Date objects, ISO strings, and timestamps
-    let date;
-    if (value instanceof Date) {
-      date = value;
-    } else if (typeof value === 'string') {
-      date = new Date(value);
-    } else if (typeof value === 'number') {
-      date = new Date(value);
-    } else {
-      throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
-    }
-
-    if (isNaN(date.getTime())) {
-      throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
-    }
-
-    // If format is provided, validate format
-    if (format && typeof value === 'string') {
-      // Simple format validation - can be enhanced
-      const formatRegex = /^\d{4}-\d{2}-\d{2}$/; // YYYY-MM-DD
-      if (format === 'YYYY-MM-DD' && !formatRegex.test(value)) {
+    if (checksFormat && typeof value === 'string') {
+      // As before: an unparseable value is not a valid date, and any other shape gets the format message.
+      parseDate(name, value);
+      if (!ISO_DATE.test(value)) {
         throw new SimfinityError(`${name} must be in format ${format}`, 'VALIDATION_ERROR', 400);
       }
-      // Add more format patterns as needed
+      // A value in the format must be a calendar date.
+      if (isRolledOverDate(value)) {
+        throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
+      }
+      return;
     }
+    // Date objects, timestamps, and strings when no format is checked.
+    toDate(name, value);
   }, false); // Optional
 };
 
 export const futureDate = (name) => {
   return createValidator(async (typeName, fieldName, value) => {
-    let date;
-    if (value instanceof Date) {
-      date = value;
-    } else if (typeof value === 'string') {
-      date = new Date(value);
-    } else if (typeof value === 'number') {
-      date = new Date(value);
-    } else {
-      throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
-    }
-
-    if (isNaN(date.getTime())) {
-      throw new SimfinityError(`${name} must be a valid date`, 'VALIDATION_ERROR', 400);
-    }
+    const date = toDate(name, value);
 
     if (date <= new Date()) {
       throw new SimfinityError(`${name} must be a future date`, 'VALIDATION_ERROR', 400);

package/types/auth/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Declarations for `@simtlix/simfinity-core/auth/errors`. Every member has the type of the
+ * same member of the root `auth` namespace, so the two cannot drift.
+ */
+import { auth } from '../index.js';
+
+/** Authentication error: code `UNAUTHENTICATED`, status 401. */
+export const UnauthenticatedError: typeof auth.UnauthenticatedError;
+export type UnauthenticatedError = InstanceType<typeof auth.UnauthenticatedError>;
+/** Authorization error: code `FORBIDDEN`, status 403. */
+export const ForbiddenError: typeof auth.ForbiddenError;
+export type ForbiddenError = InstanceType<typeof auth.ForbiddenError>;
+export const createAuthError: typeof auth.createAuthError;
+
+declare const errors: Pick<typeof auth, 'UnauthenticatedError' | 'ForbiddenError' | 'createAuthError'>;
+export default errors;

package/types/auth/expressions.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Declarations for `@simtlix/simfinity-core/auth/expressions`. Every named export has the type of
+ * the same member of the root `auth` namespace, so the two cannot drift.
+ */
+import { auth } from '../index.js';
+
+export type { PolicyExpression } from '../index.js';
+export const evaluateExpression: typeof auth.evaluateExpression;
+export const isPolicyExpression: typeof auth.isPolicyExpression;
+export const createRuleFromExpression: typeof auth.createRuleFromExpression;
+
+declare const expressions: Pick<typeof auth, 'evaluateExpression' | 'isPolicyExpression' | 'createRuleFromExpression'> & {
+  /**
+   * Low-level helper kept on the default object only: reads a dotted `parent.`, `args.` or `ctx.`
+   * path from `{ parent, args, ctx }`; an invalid path gives `undefined`. Prefer
+   * `createRuleFromExpression`.
+   */
+  resolveRef(refPath: string, context: any): unknown;
+  /**
+   * Low-level helper kept on the default object only: resolves a `{ ref }` operand, or returns a
+   * literal as is.
+   */
+  resolveValue(value: unknown, context: any): unknown;
+};
+export default expressions;

package/types/auth/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Declarations for `@simtlix/simfinity-core/auth`. The default export is the root `auth`
+ * namespace, and every named export has the type of the same member, so the two cannot drift.
+ */
+import { auth } from '../index.js';
+
+export type {
+  AuthPluginOptions,
+  AuthRule,
+  AuthRuleFunction,
+  EnvelopSchemaPlugin,
+  PermissionSchema,
+  PolicyExpression,
+  TypePermissions,
+} from '../index.js';
+export { UnauthenticatedError, ForbiddenError, createAuthError } from './errors.js';
+export { evaluateExpression, isPolicyExpression, createRuleFromExpression } from './expressions.js';
+export {
+  resolvePath,
+  requireAuth,
+  requireRole,
+  requirePermission,
+  composeRules,
+  anyRule,
+  isOwner,
+  createRule,
+  allow,
+  deny,
+} from './rules.js';
+export const createAuthPlugin: typeof auth.createAuthPlugin;
+/** @deprecated Use createAuthPlugin instead. graphql-middleware compatible middleware. */
+export const createAuthMiddleware: typeof auth.createAuthMiddleware;
+/** @deprecated Use createAuthPlugin instead. The same function as createAuthMiddleware. */
+export const createFieldMiddleware: typeof auth.createFieldMiddleware;
+
+export default auth;

package/types/auth/rules.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Declarations for `@simtlix/simfinity-core/auth/rules`. Every member has the type of the same
+ * member of the root `auth` namespace, so the two cannot drift.
+ */
+import { auth } from '../index.js';
+
+export type { AuthRuleFunction } from '../index.js';
+export const resolvePath: typeof auth.resolvePath;
+export const requireAuth: typeof auth.requireAuth;
+export const requireRole: typeof auth.requireRole;
+export const requirePermission: typeof auth.requirePermission;
+export const composeRules: typeof auth.composeRules;
+export const anyRule: typeof auth.anyRule;
+export const isOwner: typeof auth.isOwner;
+export const createRule: typeof auth.createRule;
+export const allow: typeof auth.allow;
+export const deny: typeof auth.deny;
+
+declare const rules: Pick<typeof auth,
+  | 'resolvePath'
+  | 'requireAuth'
+  | 'requireRole'
+  | 'requirePermission'
+  | 'composeRules'
+  | 'anyRule'
+  | 'isOwner'
+  | 'createRule'
+  | 'allow'
+  | 'deny'>;
+export default rules;

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
@@ -326,10 +335,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 +357,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 +389,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;
 };
@@ -429,14 +466,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,12 @@
+/**
+ * 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';
+export const createAuthPlugin: typeof plugins.createAuthPlugin;
+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;