Update type declarations including validator.js-asserts

- Update `validator.js-asserts@9.0.0`
- Refactors the type declarations in line with what's done on `validator.js-asserts`, including their exported types

Author: risantos

index.d.ts

@@ -1,7 +1,50 @@
 import type { Assert as BaseAssert, Constraint as BaseConstraint } from 'validator.js';
+import type { ValidatorJSAsserts } from 'validator.js-asserts';
 
 /**
- * Valid values for constraint mapping
+ * The instance‐side of an Assert (no static factory methods).
+ * All core “is.X()” methods and custom asserts produce this.
+ */
+interface AssertInstance {
+  /** Returns `true` if the value passes, otherwise returns a Violation/object. */
+  check(value: unknown, group?: string | string[], context?: unknown): true | any;
+  /** Throws on failure; returns `true` if the value passes. */
+  validate(value: unknown, group?: string | string[], context?: unknown): true;
+  /** Does this assert apply to the given validation group(s)? */
+  requiresValidation(group?: string | string[]): boolean;
+  /** Is this assert assigned to the given group? */
+  hasGroup(group: string | string[]): boolean;
+  /** Is this assert in any of the provided groups? */
+  hasOneOf(groups: string[]): boolean;
+  /** Does this assert belong to at least one group? */
+  hasGroups(): boolean;
+}
+
+/**
+ * The instance‐side of a Constraint (no static/constructor methods).
+ * Mirrors the Assert API but for Constraint objects.
+ */
+interface ConstraintInstance extends BaseConstraint {
+  /** Check if value matches the constraint */
+  check(value: unknown, group?: string | string[], context?: unknown): true | any;
+  /** Validate the value against the constraint */
+  validate(value: unknown, group?: string | string[], context?: unknown): true;
+  /** Check if the constraint requires validation */
+  requiresValidation(group?: string | string[]): boolean;
+  /** Check if the constraint belongs to a specific group */
+  hasGroup(group: string | string[]): boolean;
+  /** Check `hasGroup` over the specified groups */
+  hasOneOf(groups: string[]): boolean;
+  /** Check if the constraint has any groups */
+  hasGroups(): boolean;
+}
+
+/**
+ * Valid types that can appear in a constraint mapping:
+ * - an Assert instance
+ * - a Constraint instance
+ * - a nested object mapping
+ * - an array of any of the above
  */
 type ConstraintValue =
   | BaseAssert
@@ -14,187 +57,228 @@ type ConstraintValue =
  * All core `validator.js` assert factories.
  */
 interface CoreAssertsMap {
-  /** An object must have the given property. */
-  haveProperty(node: string): ConstraintValue;
+  /** Object must have the given property. */
+  haveProperty(node: string): AssertInstance;
 
   /** Alias for `haveProperty`. */
-  propertyDefined(node: string): ConstraintValue;
+  propertyDefined(node: string): AssertInstance;
 
-  /** A string must be empty or only whitespace. */
-  blank(): ConstraintValue;
+  /** String must be empty or only whitespace. */
+  blank(): AssertInstance;
 
-  /** Run a custom callback that returns true on success. */
-  callback(fn: (value: unknown, ...args: unknown[]) => boolean, ...args: unknown[]): ConstraintValue;
+  /** Run a custom function that returns true on success. */
+  callback(fn: (value: unknown, ...args: unknown[]) => boolean, ...args: unknown[]): AssertInstance;
 
-  /** Value must be one of the provided list. */
-  choice(list: unknown[] | (() => unknown[])): ConstraintValue;
+  /** Value must be one of the supplied list. */
+  choice(list: unknown[] | (() => unknown[])): AssertInstance;
 
-  /** Validate each element of an array. */
-  collection(assertOrConstraint: ConstraintValue | BaseConstraint | object): ConstraintValue;
+  /** Each element of an array must match the given Assert/Constraint. */
+  collection(assertOrConstraint: ConstraintValue | ConstraintInstance | object): AssertInstance;
 
-  /** Array must have exactly N items. */
-  count(count: number | ((arr: unknown[]) => number)): ConstraintValue;
+  /** Array must have exactly N items (or N computed from a function). */
+  count(count: number | ((arr: unknown[]) => number)): AssertInstance;
 
   /** Valid email address. */
-  email(): ConstraintValue;
+  email(): AssertInstance;
 
-  /** Value must equal reference or match function. */
-  equalTo(reference: unknown | ((value: unknown) => unknown)): ConstraintValue;
+  /** Value must equal the reference or match the provided function. */
+  equalTo(reference: unknown | ((value: unknown) => unknown)): AssertInstance;
 
   /** Numeric value must be > threshold. */
-  greaterThan(threshold: number): ConstraintValue;
+  greaterThan(threshold: number): AssertInstance;
 
   /** Numeric value must be ≥ threshold. */
-  greaterThanOrEqual(threshold: number): ConstraintValue;
+  greaterThanOrEqual(threshold: number): AssertInstance;
 
-  /** Value must be `instanceof` the given class. */
-  instanceOf(classRef: new (...args: unknown[]) => unknown): ConstraintValue;
+  /** Value must be `instanceof` the specified class. */
+  instanceOf(classRef: new (...args: unknown[]) => unknown): AssertInstance;
 
   /** Value must be a string. */
-  string(): ConstraintValue;
+  string(): AssertInstance;
 
   /** String/array length must be within `[min, max]`. */
-  length(boundaries: { min?: number; max?: number }): ConstraintValue;
+  length(boundaries: { min?: number; max?: number }): AssertInstance;
 
   /** Alias for `length()`. */
-  ofLength(boundaries: { min?: number; max?: number }): ConstraintValue;
+  ofLength(boundaries: { min?: number; max?: number }): AssertInstance;
 
   /** Numeric value must be < threshold. */
-  lessThan(threshold: number): ConstraintValue;
+  lessThan(threshold: number): AssertInstance;
 
   /** Numeric value must be ≤ threshold. */
-  lessThanOrEqual(threshold: number): ConstraintValue;
+  lessThanOrEqual(threshold: number): AssertInstance;
 
   /** Value must not be null or undefined. */
-  notNull(): ConstraintValue;
+  notNull(): AssertInstance;
 
-  /** String must contain ≥1 non-whitespace character. */
-  notBlank(): ConstraintValue;
+  /** String must contain at least one non-whitespace character. */
+  notBlank(): AssertInstance;
 
-  /** Value must not equal reference or match fn. */
-  notEqualTo(reference: unknown | ((value: unknown) => unknown)): ConstraintValue;
+  /** Value must not equal the reference or match the provided function. */
+  notEqualTo(reference: unknown | ((value: unknown) => unknown)): AssertInstance;
 
   /** Value must be exactly null. */
-  null(): ConstraintValue;
+  null(): AssertInstance;
 
-  /** `Number`/`String`/`Array` must fall within `[min, max]`. */
-  range(min: number, max: number): ConstraintValue;
+  /** `Number`/`String`/`Array` must lie within `[min, max]`. */
+  range(min: number, max: number): AssertInstance;
 
   /** `String` must match the given `RegExp`. */
-  regexp(regexp: string | RegExp, flag?: string): ConstraintValue;
+  regexp(regexp: string | RegExp, flag?: string): AssertInstance;
 
   /** Value must be defined (not `undefined`). */
-  required(): ConstraintValue;
+  required(): AssertInstance;
 
-  /** Array items must be unique (by `key` if given). */
-  unique(opts?: { key: string }): ConstraintValue;
+  /** Array items must be unique (optionally by `key`). */
+  unique(opts?: { key: string }): AssertInstance;
 
-  /** If `context[ref]` passes `is`, run `then` else `otherwise`. */
+  /**
+   * If `context[ref]` satisfies `options.is`, run `options.then`; otherwise `options.otherwise`.
+   */
   when(
     ref: string,
     options: {
       is: ConstraintValue | object;
       then?: ConstraintValue | object;
       otherwise?: ConstraintValue | object;
     }
-  ): ConstraintValue;
+  ): AssertInstance;
 }
 
-type ExtraAssertType = {
-  [key: string]: ConstraintValue;
-};
-
 /**
- * Map runtime‐passed `extraAsserts` into uncapitalized methods.
- * This can include both built‐ins *and* entirely custom keys.
+ * If the user passes an object of `extraAsserts` (e.g. `{ MyFoo: () => new FooAssert() }`),
+ * this type will expose each key as a lowercase method returning `AssertInstance`.
  */
-type ExtraAsserts<EA extends ExtraAssertType> = {
-  [K in keyof EA as Uncapitalize<string & K>]: EA[K];
-};
+type ExtraAsserts<EA> = EA extends Record<string, any>
+  ? {
+      [K in keyof EA as Uncapitalize<string & K>]: () => AssertInstance;
+    }
+  : {};
 
-/** Callable/newable `Assert` constructor. */
+/** Callable/newable `Assert` constructor function itself. */
 interface BaseAssertStatic {
-  new (group?: string | string[]): BaseAssert;
-  (group?: string | string[]): BaseAssert;
+  new (group?: string | string[]): AssertInstance;
+  (group?: string | string[]): AssertInstance;
 }
 
 /**
- * The full `is` API:
- *  - BaseAssert constructor.
- *  - core `validator.js` asserts.
- *  - all `validator.js-asserts` (camelCased).
- *  - any `extraAsserts` passed at runtime.
+ * Everything available under `is`:
+ * - The base‐factory (`new is()` or `is()`).
+ * - All core `validator.js` methods (`haveProperty`, `blank`, `email`, …).
+ * - All built‐in `validator.js-asserts` (via `ValidatorJSAsserts`).
+ * - Any user‐passed `extraAsserts` (lowercased).
  */
-type AssertStatic<EA extends ExtraAssertType> = BaseAssertStatic & CoreAssertsMap & ExtraAsserts<EA> & ExtraAssertType;
+type AssertStatic<EA> = BaseAssertStatic & CoreAssertsMap & ValidatorJSAsserts & ExtraAsserts<EA>;
 
-/** Map a data type to `validator.js` constraints. */
+/**
+ * Given a type `T`, map each key to either:
+ * - a single `ConstraintValue`, or
+ * - an array of `ConstraintValue`.
+ *
+ * @example `{ foo: is.string(), bar: [is.required(), is.email()] }`
+ */
 type ConstraintMapping<T> =
   | { [P in keyof T]?: ConstraintValue | ConstraintValue[] }
   | Record<string, ConstraintValue | ConstraintValue[]>;
 
-/** `validate`/`assert` function signature. */
+/** Signature of `assert(data, constraints)` or `validate(data, constraints)`. */
 type ValidateFunction = <T>(data: T, constraints: ConstraintMapping<T> | Record<string, ConstraintValue>) => T;
 
-/** Type of `Error` to pass to `AssertionError`/`ValidationError`. */
+/** Custom Error type for `AssertionError`/`ValidationError`. */
 type ValidatorErrorType = new (...args: any[]) => Error;
 
-/** Options for creating a validator. */
-interface ValidatorOptions<EA extends ExtraAssertType = ExtraAssertType> {
-  AssertionError?: ValidatorErrorType;
-  ValidationError?: ValidatorErrorType;
-  extraAsserts?: EA;
-  logger?: (errors: any) => void;
-  obfuscator?: (input: { errors: any }) => { errors: any };
-  mask?: boolean;
-}
-
-/**
- * Base exports with just `is`.
- */
-interface BaseValidatorExports<EA extends ExtraAssertType = ExtraAssertType> {
+/** You always get an `{ is: AssertStatic<EA> }` back. */
+interface BaseValidatorExports<EA = any> {
   is: AssertStatic<EA>;
 }
 
-/**
- * Exports with `assert` added when `AssertionError` is provided.
- */
-interface ValidatorExportsWithAssert<EA extends ExtraAssertType = ExtraAssertType> extends BaseValidatorExports<EA> {
+/** If `AssertionError` was passed, you also get `assert(data, …)`. */
+interface ValidatorExportsWithAssert<EA = any> extends BaseValidatorExports<EA> {
   assert: ValidateFunction;
 }
 
-/**
- * Exports with `validate` added when `ValidationError` is provided.
- */
-interface ValidatorExportsWithValidate<EA extends ExtraAssertType = ExtraAssertType> extends BaseValidatorExports<EA> {
+/** If `ValidationError` was passed, you also get `validate(data, …)`. */
+interface ValidatorExportsWithValidate<EA = any> extends BaseValidatorExports<EA> {
   validate: ValidateFunction;
 }
 
-/**
- * Exports with both `assert` and `validate` when both errors are provided.
- */
-interface ValidatorExportsWithBoth<EA extends ExtraAssertType = ExtraAssertType> extends BaseValidatorExports<EA> {
+/** If both errors were passed, you get both `assert` and `validate`. */
+interface ValidatorExportsWithBoth<EA = any> extends BaseValidatorExports<EA> {
   assert: ValidateFunction;
   validate: ValidateFunction;
 }
 
 /**
- * Factory function to create a `validator` instance.
+ * Create a new validator instance.
+ * TypeScript will infer `EA` from the shape of `options.extraAsserts`.
+ *
+ * - If you supply both `AssertionError` and `ValidationError`, you get: `{ is, assert, validate }`
+ * - If you supply only one of them, you get exactly that method plus `is`.
+ * - If you supply neither, you get only `{ is }`.
  */
-declare function validator<EA extends ExtraAssertType = ExtraAssertType>(
-  options: ValidatorOptions<EA> & { AssertionError: ValidatorErrorType; ValidationError: ValidatorErrorType }
-): ValidatorExportsWithBoth<EA>;
+declare function validator<EA extends Record<string, any>>(options: {
+  AssertionError: ValidatorErrorType;
+  ValidationError: ValidatorErrorType;
+  extraAsserts: EA;
+  logger?: (errors: any) => void;
+  obfuscator?: (input: { errors: any }) => { errors: any };
+  mask?: boolean;
+}): ValidatorExportsWithBoth<EA>;
+
+declare function validator(options: {
+  AssertionError: ValidatorErrorType;
+  ValidationError: ValidatorErrorType;
+  extraAsserts?: undefined;
+  logger?: (errors: any) => void;
+  obfuscator?: (input: { errors: any }) => { errors: any };
+  mask?: boolean;
+}): ValidatorExportsWithBoth<{}>;
+
+declare function validator<EA extends Record<string, any>>(options: {
+  AssertionError: ValidatorErrorType;
+  extraAsserts: EA;
+  logger?: (errors: any) => void;
+  obfuscator?: (input: { errors: any }) => { errors: any };
+  mask?: boolean;
+}): ValidatorExportsWithAssert<EA>;
+
+declare function validator(options: {
+  AssertionError: ValidatorErrorType;
+  extraAsserts?: undefined;
+  logger?: (errors: any) => void;
+  obfuscator?: (input: { errors: any }) => { errors: any };
+  mask?: boolean;
+}): ValidatorExportsWithAssert<{}>;
 
-declare function validator<EA extends ExtraAssertType = ExtraAssertType>(
-  options: ValidatorOptions<EA> & { AssertionError: ValidatorErrorType }
-): ValidatorExportsWithAssert<EA>;
+declare function validator<EA extends Record<string, any>>(options: {
+  ValidationError: ValidatorErrorType;
+  extraAsserts: EA;
+  logger?: (errors: any) => void;
+  obfuscator?: (input: { errors: any }) => { errors: any };
+  mask?: boolean;
+}): ValidatorExportsWithValidate<EA>;
 
-declare function validator<EA extends ExtraAssertType = ExtraAssertType>(
-  options: ValidatorOptions<EA> & { ValidationError: ValidatorErrorType }
-): ValidatorExportsWithValidate<EA>;
+declare function validator(options: {
+  ValidationError: ValidatorErrorType;
+  extraAsserts?: undefined;
+  logger?: (errors: any) => void;
+  obfuscator?: (input: { errors: any }) => { errors: any };
+  mask?: boolean;
+}): ValidatorExportsWithValidate<{}>;
 
-declare function validator<EA extends ExtraAssertType = ExtraAssertType>(
-  options?: ValidatorOptions<EA>
-): BaseValidatorExports<EA>;
+declare function validator<EA extends Record<string, any>>(options?: {
+  extraAsserts: EA;
+  logger?: (errors: any) => void;
+  obfuscator?: (input: { errors: any }) => { errors: any };
+  mask?: boolean;
+}): BaseValidatorExports<EA>;
+
+declare function validator(options?: {
+  extraAsserts?: undefined;
+  logger?: (errors: any) => void;
+  obfuscator?: (input: { errors: any }) => { errors: any };
+  mask?: boolean;
+}): BaseValidatorExports<{}>;
 
 /**
  * Export `validator`.

package.json

@@ -23,7 +23,7 @@
     "json-mask": "^2.0.0",
     "lodash": "^4.17.21",
     "validator.js": "^2.0.3",
-    "validator.js-asserts": "^7.3.1"
+    "validator.js-asserts": "^9.0.0"
   },
   "devDependencies": {
     "@fastify/pre-commit": "^2.2.0",