@nhtio/validation 1.20250813.0 → 1.20250814.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhtio/validation",
-  "version": "1.20250813.0",
+  "version": "1.20250814.0",
   "description": "A powerful schema description language and data validator",
   "keywords": [],
   "author": "Jak Giveon <jak@nht.io>",

package/private/index.d.ts

@@ -1,8 +1,10 @@
+import type { DateTime } from 'luxon';
 import type { PhoneSchema } from './schemas/phone';
 import type { BigIntSchema } from './schemas/bigint';
 import type { DatetimeSchema } from './schemas/datetime';
 import type { CountryOrUnknown } from '@nhtio/phone-object';
 import type { Root, Reference, SchemaMap, SchemaLike } from 'joi';
+import type { I18nCallback, SetI18nCallback } from './patches/i18n';
 import type { AlternativesSchema, AnySchema, StringSchema, BinarySchema, NumberSchema, BooleanSchema, ObjectSchema, ArraySchema, DateSchema } from './schemas';
 /**
  * Extended Joi root interface that includes custom schema types for
@@ -23,22 +25,123 @@ import type { AlternativesSchema, AnySchema, StringSchema, BinarySchema, NumberS
  *
  * @public
  */
-export interface ValidationRoot extends Omit<Root, 'any' | 'string' | 'binary' | 'number' | 'boolean' | 'object' | 'array' | 'date' | 'alternatives' | 'alt'> {
-    any: () => AnySchema;
-    string: () => StringSchema;
-    binary: () => BinarySchema;
-    number: () => NumberSchema;
-    boolean: () => BooleanSchema;
+export interface ValidationRoot extends Omit<Root, 'any' | 'string' | 'binary' | 'number' | 'bool' | 'boolean' | 'object' | 'array' | 'date' | 'alternatives' | 'alt'> {
+    /**
+     * Generates a schema object that matches any data type.
+     */
+    any<TSchema = any>(): AnySchema<TSchema>;
+    /**
+     * Generates a schema object that matches an array data type.
+     */
+    array<TSchema = any[]>(): ArraySchema<TSchema>;
+    /**
+     * Generates a schema object that matches a boolean data type (as well as the strings 'true', 'false', 'yes', and 'no'). Can also be called via boolean().
+     */
+    bool<TSchema = boolean>(): BooleanSchema<TSchema>;
+    /**
+     * Generates a schema object that matches a boolean data type (as well as the strings 'true', 'false', 'yes', and 'no'). Can also be called via bool().
+     */
+    boolean<TSchema = boolean>(): BooleanSchema<TSchema>;
+    /**
+     * Generates a schema object that matches a Buffer data type (as well as the strings which will be converted to Buffers).
+     */
+    binary<TSchema = Buffer>(): BinarySchema<TSchema>;
+    /**
+     * Generates a schema object that matches a date type (as well as a JavaScript date string or number of milliseconds).
+     */
+    date<TSchema = Date>(): DateSchema<TSchema>;
+    /**
+     * Generates a schema object that matches a number data type (as well as strings that can be converted to numbers).
+     */
+    number<TSchema = number>(): NumberSchema<TSchema>;
+    /**
+     * Generates a schema object that matches an object data type (as well as JSON strings that have been parsed into objects).
+     */
     object<TSchema = any, IsStrict = false, T = TSchema>(schema?: SchemaMap<T, IsStrict>): ObjectSchema<TSchema>;
-    array: () => ArraySchema;
-    date: () => DateSchema;
-    bigint(): BigIntSchema;
-    datetime(): DatetimeSchema;
-    phone(country?: CountryOrUnknown | Reference | null): PhoneSchema;
+    /**
+     * Generates a schema object that matches a string data type. Note that empty strings are not allowed by default and must be enabled with allow('').
+     */
+    string<TSchema = string>(): StringSchema<TSchema>;
+    /**
+     * Generates a type that will match one of the provided alternative schemas
+     */
     alternatives<TSchema = any>(types: SchemaLike[]): AlternativesSchema<TSchema>;
     alternatives<TSchema = any>(...types: SchemaLike[]): AlternativesSchema<TSchema>;
+    /**
+     * Alias for `alternatives`
+     */
     alt<TSchema = any>(types: SchemaLike[]): AlternativesSchema<TSchema>;
     alt<TSchema = any>(...types: SchemaLike[]): AlternativesSchema<TSchema>;
+    /**
+     * Generates a schema object that matches a BigInt data type.
+     */
+    bigint<TSchema = bigint>(): BigIntSchema<TSchema>;
+    /**
+     * Generates a schema object that matches a DateTime data type.
+     */
+    datetime<TSchema = DateTime>(): DatetimeSchema<TSchema>;
+    /**
+     * Generates a schema object that matches a phone number data type.
+     *
+     * @param country - Optional country code or reference for phone validation
+     */
+    phone<TSchema = string>(country?: CountryOrUnknown | Reference | null): PhoneSchema<TSchema>;
+    /**
+     * Sets a global internationalization callback that applies to all validator instances.
+     *
+     * This method sets a fallback translation function that will be used by the `$i18n` method
+     * when no instance-specific callback has been set via `$setI18n`. Once `$setI18n` is called
+     * on an instance, that instance will use its own callback instead of the global one.
+     *
+     * The global callback provides a convenient way to set default translations across your
+     * entire application while still allowing individual validator instances to override
+     * with their own translations when needed.
+     *
+     * @param callback - The I18nCallback function that will handle global message translation
+     * @returns The validator instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Set up global Spanish translations
+     * validator.$setGlobalI18n((term: string) => {
+     *   return spanishTranslations[term] || term
+     * })
+     *
+     * // All validators will now use Spanish by default
+     * const schema1 = validator.string().min(5)
+     * const schema2 = validator.number().positive()
+     *
+     * // But you can still override for specific instances
+     * const germanSchema = validator.string().$setI18n(germanCallback)
+     * ```
+     */
+    $setI18n: SetI18nCallback<ValidationRoot>;
+    /**
+     * Clears the global internationalization callback.
+     *
+     * This method removes any previously set global i18n callback, causing the `$i18n` method
+     * to fall back to default English messages for validator instances that haven't had their
+     * own callback set via `$setI18n`.
+     *
+     * This is useful for testing scenarios, dynamic language switching, or memory cleanup
+     * when you no longer need global translations.
+     *
+     * @returns The validator instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Set up global translations
+     * validator.$setGlobalI18n(spanishCallback)
+     *
+     * // Later, clear them to return to default English
+     * validator.$clearGlobalI18n()
+     *
+     * // Now all validators use default English messages again
+     * const schema = validator.string().min(5) // Uses English messages
+     * ```
+     */
+    $clearI18n: () => ValidationRoot;
+    $i18n: I18nCallback;
 }
 /**
  * Extended Joi instance with custom schema types.
@@ -61,8 +164,6 @@ export interface ValidationRoot extends Omit<Root, 'any' | 'string' | 'binary' |
  * @public
  */
 export declare const validator: ValidationRoot;
-export type { BigIntSchema };
-export type { DatetimeSchema };
-export type { PhoneSchema };
+export type { BigIntSchema, DatetimeSchema, PhoneSchema, SetI18nCallback, I18nCallback };
 export type * from './schemas';
 export { encode, decode } from './utils';

package/private/patches/i18n.d.ts

@@ -0,0 +1,51 @@
+import type { Root } from 'joi';
+/**
+ * Callback function type for internationalization translation.
+ *
+ * This function is responsible for translating validation message keys into
+ * localized strings. It receives a message term (like 'string.min') and should
+ * return the translated message in the appropriate language.
+ *
+ * @param term - The message key to translate (e.g., 'string.base', 'number.min')
+ * @returns The translated message string, or the original term if translation fails
+ *
+ * @example
+ * ```typescript
+ * const translateToSpanish: I18nCallback = (term: string) => {
+ *   const translations = {
+ *     'string.base': 'debe ser una cadena de texto',
+ *     'number.min': 'debe ser mayor o igual a {{#limit}}'
+ *   }
+ *   return translations[term] || term
+ * }
+ * ```
+ */
+export interface I18nCallback {
+    (term: string): string;
+}
+/**
+ * Callback function type for setting up internationalization.
+ *
+ * This function is used to configure the i18n system by providing a translation
+ * callback. Once called, it sets up the root validator instance to use the
+ * provided translation function for all validation messages.
+ *
+ * @param callback - The I18nCallback function that will handle message translation
+ *
+ * @example
+ * ```typescript
+ * // Set up Spanish translations
+ * validator.$setI18n((term: string) => {
+ *   return spanishTranslations[term] || term
+ * })
+ *
+ * // Set up with external i18n library
+ * validator.$setI18n((term: string) => {
+ *   return i18next.t(`validation.${term}`, { defaultValue: term })
+ * })
+ * ```
+ */
+export interface SetI18nCallback<T = Root> {
+    (this: T, callback: I18nCallback): T;
+}
+export declare const i18n: (toPatch: Root) => Root;

package/private/schemas/bigint.d.ts

@@ -1,5 +1,15 @@
 import type { AnySchema } from '../schemas';
 import type { ExtensionFactory, Reference } from 'joi';
+export declare const messages: {
+    'bigint.base': string;
+    'bigint.greater': string;
+    'bigint.less': string;
+    'bigint.max': string;
+    'bigint.min': string;
+    'bigint.multiple': string;
+    'bigint.negative': string;
+    'bigint.positive': string;
+};
 /**
  * A Joi extension that adds support for BigInt validation with comprehensive
  * comparison operations and type coercion.

package/private/schemas/datetime.d.ts

@@ -4,6 +4,21 @@ import type { Tokens } from '../types';
 import type { AnySchema } from '../schemas';
 import type { ExtensionFactory, Reference } from 'joi';
 import type { Zone, LocaleOptions, DateObjectUnits, ZoneOptions, ToISOTimeOptions, ToISODateOptions, ToSQLOptions, ToRelativeOptions } from 'luxon';
+export declare const messages: {
+    'datetime.base': string;
+    'datetime.exactly': string;
+    'datetime.equals': string;
+    'datetime.after': string;
+    'datetime.greater': string;
+    'datetime.before': string;
+    'datetime.less': string;
+    'datetime.afterOrEqual': string;
+    'datetime.min': string;
+    'datetime.beforeOrEqual': string;
+    'datetime.max': string;
+    'datetime.weekend': string;
+    'datetime.weekday': string;
+};
 /**
  * Types that can be parsed into a DateTime object.
  *

package/private/schemas/phone.d.ts

@@ -145,6 +145,25 @@ export interface PhoneSchema<TSchema = string> extends Omit<AnySchema<TSchema>,
     types(...types: PhoneTypes[]): this;
     cast(to: 'number' | 'string' | 'object'): this;
 }
+export declare const messages: {
+    'phone.base': string;
+    'phone.invalid': string;
+    'phone.fixedLine': string;
+    'phone.mobile': string;
+    'phone.strictFixedLine': string;
+    'phone.strictMobile': string;
+    'phone.fixedLineOrMobile': string;
+    'phone.tollFree': string;
+    'phone.premiumRate': string;
+    'phone.sharedCost': string;
+    'phone.voip': string;
+    'phone.personalNumber': string;
+    'phone.pager': string;
+    'phone.uan': string;
+    'phone.voicemail': string;
+    'phone.unknown': string;
+    'phone.types': string;
+};
 /**
  * Joi extension factory for phone number validation.
  * Creates a custom Joi schema type that validates phone numbers using the @nhtio/phone-object library.