From f246019bbdaccf8c9f58b480960355213fbb99a2 Mon Sep 17 00:00:00 2001
From: Rafael Santos <rafael.santos@uphold.com>
Date: Wed, 2 Jul 2025 17:53:28 +0100
Subject: [PATCH] Update `Callback` type hint

- Specify the `customClass` parameter's expected format.
- Add example usage for clarity.
---
 README.md            |  8 +++++---
 src/types/index.d.ts | 13 ++++++++++++-
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 944f704..671adf3 100644
--- a/README.md
+++ b/README.md
@@ -132,8 +132,8 @@ Allows you to add custom rules by giving a callback function and a custom class.
 
 #### Arguments
 
-- `callback` (required) - the callback function.
-- `customClass` (required) - the name of the class.
+- `callback` (required) - the callback function, that must return `true` if the value is valid.
+- `customClass` (required) - the name of the class, which must match the pattern `/^[a-zA-Z\d]+$/`.
 
 ### CaZipCode
 
@@ -331,7 +331,9 @@ The following is an example for the extra IP assert:
 
 ```js
 const Validator = require('validator.js').Validator;
-const is = require('validator.js').Assert.extend(require('validator.js-asserts'));
+const is = require('validator.js').Assert.extend(
+  require('validator.js-asserts')
+);
 const validator = new Validator();
 
 // Validate IP `1.3.3.7`.
diff --git a/src/types/index.d.ts b/src/types/index.d.ts
index 73d73a2..5837cc2 100644
--- a/src/types/index.d.ts
+++ b/src/types/index.d.ts
@@ -60,7 +60,18 @@ export interface ValidatorJSAsserts {
   /** Valid Canadian ZIP code (postal code). */
   caZipCode(): AssertInstance;
 
-  /** Run a custom callback function, passing a custom class name. */
+  /**
+   * Run a custom callback function, passing a custom class name.
+   * @param fn - Callback function that receives the value to validate, which should return `true` if valid.
+   * @param customClass - Custom class name to use for the assert. Must match the pattern `/^[a-zA-Z\d]+$/`.
+   * @example
+   * ```js
+   * is.callback(
+   *   (value) => typeof value === 'string' && value.length > 0,
+   *   'NonEmptyString'
+   * );
+   * ```
+   */
   callback(fn: (value: unknown) => boolean, customClass: string): AssertInstance;
 
   /** Valid Brazilian CPF number. @requires cpf */