@simtlix/simfinity-core 3.5.7 → 3.5.9

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,12 @@
+/**
+ * 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';
+
+// The root classes themselves, which `auth.UnauthenticatedError` and `auth.ForbiddenError` also are.
+export { UnauthenticatedError, ForbiddenError } from '../index.js';
+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;