@nhtio/validation 1.20250804.0 → 1.20250814.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhtio/validation",
-  "version": "1.20250804.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,6 +1,11 @@
-import type { Root } from 'joi';
+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
  * additional validation scenarios.
@@ -20,9 +25,123 @@ import type { DatetimeSchema } from './schemas/datetime';
  *
  * @public
  */
-export interface ValidationRoot extends Root {
-    bigint(): BigIntSchema;
-    datetime(): DatetimeSchema;
+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>;
+    /**
+     * 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.
@@ -45,7 +164,6 @@ export interface ValidationRoot extends Root {
  * @public
  */
 export declare const validator: ValidationRoot;
-export type { BigIntSchema };
-export type { DatetimeSchema };
+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

@@ -0,0 +1,199 @@
+import type { AnySchema } from '../../index';
+import type { CountryOrUnknown, PhoneTypes } from '@nhtio/phone-object';
+import type { ExtensionFactory, Reference } from 'joi';
+/**
+ * Phone number validation schema interface extending AnySchema.
+ * Provides methods for validating and formatting phone numbers with various constraints.
+ *
+ * @template TSchema - The schema type, defaults to string
+ *
+ * @example
+ * ```typescript
+ * import Joi from 'joi'
+ * import { phone } from './phone'
+ *
+ * const extended = Joi.extend(phone)
+ * const schema = extended.phone().country('US').mobile()
+ *
+ * const result = schema.validate('+1234567890')
+ * ```
+ */
+export interface PhoneSchema<TSchema = string> extends Omit<AnySchema<TSchema>, 'cast'> {
+    /**
+     * Sets the country context for phone number validation.
+     *
+     * @param country - Country code (ISO 3166-1 alpha-2), country name, Joi reference, or null
+     * @returns The schema instance for chaining
+     *
+     * @example
+     * ```typescript
+     * schema.country('US')
+     * schema.country('United States')
+     * schema.country(Joi.ref('countryField'))
+     * ```
+     */
+    country(country: CountryOrUnknown | Reference | null): this;
+    /**
+     * Sets the output format for the phone number.
+     *
+     * @param as - The desired output format
+     * @returns The schema instance for chaining
+     *
+     * @example
+     * ```typescript
+     * schema.format('international') // +1 234 567 8900
+     * schema.format('national')      // (234) 567-8900
+     * schema.format('e164')          // +12345678900
+     * ```
+     */
+    format(as: 'e164' | 'international' | 'national' | 'raw' | 'timezone' | 'type' | 'country'): this;
+    /**
+     * Validates that the phone number is a fixed line or fixed line/mobile number.
+     *
+     * @returns The schema instance for chaining
+     */
+    fixedLine(): this;
+    /**
+     * Validates that the phone number is a mobile or fixed line/mobile number.
+     *
+     * @returns The schema instance for chaining
+     */
+    mobile(): this;
+    /**
+     * Validates that the phone number is strictly a fixed line number only.
+     *
+     * @returns The schema instance for chaining
+     */
+    strictFixedLine(): this;
+    /**
+     * Validates that the phone number is strictly a mobile number only.
+     *
+     * @returns The schema instance for chaining
+     */
+    strictMobile(): this;
+    /**
+     * Validates that the phone number is either a fixed line or mobile number.
+     *
+     * @returns The schema instance for chaining
+     */
+    fixedLineOrMobile(): this;
+    /**
+     * Validates that the phone number is a toll-free number.
+     *
+     * @returns The schema instance for chaining
+     */
+    tollFree(): this;
+    /**
+     * Validates that the phone number is a premium rate number.
+     *
+     * @returns The schema instance for chaining
+     */
+    premiumRate(): this;
+    /**
+     * Validates that the phone number is a shared cost number.
+     *
+     * @returns The schema instance for chaining
+     */
+    sharedCost(): this;
+    /**
+     * Validates that the phone number is a VoIP number.
+     *
+     * @returns The schema instance for chaining
+     */
+    voip(): this;
+    /**
+     * Validates that the phone number is a personal number.
+     *
+     * @returns The schema instance for chaining
+     */
+    personalNumber(): this;
+    /**
+     * Validates that the phone number is a pager number.
+     *
+     * @returns The schema instance for chaining
+     */
+    pager(): this;
+    /**
+     * Validates that the phone number is a UAN (Universal Access Number).
+     *
+     * @returns The schema instance for chaining
+     */
+    uan(): this;
+    /**
+     * Validates that the phone number is a voicemail number.
+     *
+     * @returns The schema instance for chaining
+     */
+    voicemail(): this;
+    /**
+     * Validates that the phone number is of unknown type.
+     *
+     * @returns The schema instance for chaining
+     */
+    unknown(): this;
+    /**
+     * Validates that the phone number matches one of the specified types.
+     *
+     * @param types - Array of phone types to allow
+     * @returns The schema instance for chaining
+     *
+     * @example
+     * ```typescript
+     * schema.types('MOBILE', 'FIXED_LINE')
+     * ```
+     */
+    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.
+ *
+ * @param joi - The Joi instance to extend
+ * @returns The phone schema extension definition
+ *
+ * @example
+ * ```typescript
+ * import Joi from 'joi'
+ * import { phone } from './phone'
+ *
+ * const extended = Joi.extend(phone)
+ *
+ * // Basic phone validation
+ * const schema = extended.phone()
+ * schema.validate('+1234567890') // validates any phone number
+ *
+ * // Country-specific validation
+ * const usSchema = extended.phone().country('US')
+ * usSchema.validate('(555) 123-4567')
+ *
+ * // Type-specific validation
+ * const mobileSchema = extended.phone().mobile()
+ * mobileSchema.validate('+1234567890')
+ *
+ * // Format output
+ * const formattedSchema = extended.phone().format('international')
+ * const result = formattedSchema.validate('+1234567890')
+ * // result.value would be "+1 234 567 8900"
+ * ```
+ */
+export declare const phone: ExtensionFactory;