@nhtio/validation 1.20250720.0 → 1.20250813.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhtio/validation",
-  "version": "1.20250720.0",
+  "version": "1.20250813.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,9 @@
-import type { Root } from 'joi';
+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 { 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 +23,22 @@ import type { DatetimeSchema } from './schemas/datetime';
  *
  * @public
  */
-export interface ValidationRoot extends Root {
+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;
+    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;
+    alternatives<TSchema = any>(types: SchemaLike[]): AlternativesSchema<TSchema>;
+    alternatives<TSchema = any>(...types: SchemaLike[]): AlternativesSchema<TSchema>;
+    alt<TSchema = any>(types: SchemaLike[]): AlternativesSchema<TSchema>;
+    alt<TSchema = any>(...types: SchemaLike[]): AlternativesSchema<TSchema>;
 }
 /**
  * Extended Joi instance with custom schema types.
@@ -47,5 +63,6 @@ export interface ValidationRoot extends Root {
 export declare const validator: ValidationRoot;
 export type { BigIntSchema };
 export type { DatetimeSchema };
+export type { PhoneSchema };
 export type * from './schemas';
 export { encode, decode } from './utils';

package/private/patches/index.d.ts

@@ -0,0 +1,3 @@
+import type { Root } from 'joi';
+import type { ValidationRoot } from '../index';
+export declare const patch: (root: Root) => ValidationRoot;

package/private/patches/json.d.ts

@@ -0,0 +1,2 @@
+import type { Root } from 'joi';
+export declare const json: (root: Root) => Root;

package/private/schemas/datetime.d.ts

@@ -2,8 +2,8 @@ import { DateTime } from 'luxon';
 import { Dayjs } from 'dayjs';
 import type { Tokens } from '../types';
 import type { AnySchema } from '../schemas';
-import type { Zone, LocaleOptions, DateObjectUnits } from 'luxon';
 import type { ExtensionFactory, Reference } from 'joi';
+import type { Zone, LocaleOptions, DateObjectUnits, ZoneOptions, ToISOTimeOptions, ToISODateOptions, ToSQLOptions, ToRelativeOptions } from 'luxon';
 /**
  * Types that can be parsed into a DateTime object.
  *
@@ -232,7 +232,7 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
      * // Returns DateTime in Eastern timezone
      * ```
      */
-    setZone(zone: string | Zone): this;
+    setZone(zone: string | Zone, opts?: ZoneOptions): this;
     /**
      * Formats the datetime using a custom format string during validation.
      *
@@ -264,6 +264,7 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
     /**
      * Converts the datetime to ISO 8601 string format during validation.
      *
+     * @param opts - Options for ISO string formatting
      * @returns The schema instance for method chaining
      *
      * @example
@@ -273,10 +274,11 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
      * // Returns: "2023-07-15T15:30:00.000Z"
      * ```
      */
-    toISO(): this;
+    toISO(opts?: ToISOTimeOptions): this;
     /**
      * Converts the datetime to ISO date format (YYYY-MM-DD) during validation.
      *
+     * @param opts - Options for ISO date formatting
      * @returns The schema instance for method chaining
      *
      * @example
@@ -286,7 +288,7 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
      * // Returns: "2023-07-15"
      * ```
      */
-    toISODate(): this;
+    toISODate(opts?: ToISODateOptions): this;
     /**
      * Converts the datetime to ISO week date format during validation.
      *
@@ -303,6 +305,7 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
     /**
      * Converts the datetime to ISO time format during validation.
      *
+     * @param opts - Options for ISO time formatting
      * @returns The schema instance for method chaining
      *
      * @example
@@ -312,7 +315,7 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
      * // Returns: "15:30:00.000Z"
      * ```
      */
-    toISOTime(): this;
+    toISOTime(opts?: ToISOTimeOptions): this;
     /**
      * Converts the datetime to RFC 2822 format during validation.
      *
@@ -355,6 +358,7 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
     /**
      * Converts the datetime to SQL time format (HH:mm:ss.SSS) during validation.
      *
+     * @param opts - Options for SQL time formatting
      * @returns The schema instance for method chaining
      *
      * @example
@@ -364,10 +368,11 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
      * // Returns: "15:30:45.123"
      * ```
      */
-    toSQLTime(): this;
+    toSQLTime(opts?: ToSQLOptions): this;
     /**
      * Converts the datetime to SQL datetime format during validation.
      *
+     * @param opts - Options for SQL formatting
      * @returns The schema instance for method chaining
      *
      * @example
@@ -377,7 +382,7 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
      * // Returns: "2023-07-15 15:30:45.123 Z"
      * ```
      */
-    toSQL(): this;
+    toSQL(opts?: ToSQLOptions): this;
     /**
      * Converts the datetime to milliseconds since Unix epoch during validation.
      *
@@ -446,6 +451,7 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
     /**
      * Converts the datetime to a plain object representation during validation.
      *
+     * @param opts - Options for object conversion
      * @returns The schema instance for method chaining
      *
      * @example
@@ -455,7 +461,9 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
      * // Returns: { year: 2023, month: 7, day: 15, hour: 15, minute: 30, second: 0, millisecond: 0 }
      * ```
      */
-    toObject(): this;
+    toObject(opts?: {
+        includeConfig?: boolean;
+    }): this;
     /**
      * Converts the datetime to a JavaScript Date object during validation.
      *
@@ -472,6 +480,7 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
     /**
      * Converts the datetime to a relative time string during validation.
      *
+     * @param opts - Options for relative time formatting
      * @returns The schema instance for method chaining
      *
      * @example
@@ -481,7 +490,7 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
      * // Returns: "2 hours ago" (relative to current time)
      * ```
      */
-    toRelative(): this;
+    toRelative(opts?: ToRelativeOptions): this;
     /**
      * Sets the locale for the datetime during validation.
      *

package/private/schemas/phone.d.ts

@@ -0,0 +1,180 @@
+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;
+}
+/**
+ * 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;

package/private/schemas.d.ts

@@ -1,4 +1,10 @@
-import type { AnySchema as JoiAnySchema, StringSchema as JoiStringSchema, BinarySchema as JoiBinarySchema, NumberSchema as JoiNumberSchema, BooleanSchema as JoiBooleanSchema, ObjectSchema as JoiObjectSchema, ArraySchema as JoiArraySchema, DateSchema as JoiDateSchema, Reference, BasicType, CustomHelpers } 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 { AnySchema as JoiAnySchema, StringSchema as JoiStringSchema, BinarySchema as JoiBinarySchema, NumberSchema as JoiNumberSchema, BooleanSchema as JoiBooleanSchema, ObjectSchema as JoiObjectSchema, ArraySchema as JoiArraySchema, DateSchema as JoiDateSchema, AlternativesSchema as JoiAlternativesSchema, Reference, BasicType, CustomHelpers, SchemaLikeWithoutArray } from 'joi';
+export type DefaultableValue = Reference | BasicType | DateTime | bigint | ((parent: any, helpers: CustomHelpers) => Reference | BasicType | DateTime | bigint);
+export type ExtendedSchemaLikeWithoutArray = SchemaLikeWithoutArray | PhoneSchema | BigIntSchema | DatetimeSchema;
 /**
  * Base schema type for all validation schemas.
  *
@@ -24,7 +30,8 @@ export interface AnySchema<TSchema = any> extends Omit<JoiAnySchema<TSchema>, 'd
      * const schemaWithFunction = joi.number().default((parent, helpers) => parent.someOtherField * 2)
      * ```
      */
-    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+    default(value?: DefaultableValue): this;
+    cast(to: 'map' | 'number' | 'set' | 'string' | 'object'): this;
 }
 /**
  * Schema type for string validation.
@@ -42,7 +49,7 @@ export interface StringSchema<TSchema = string> extends Omit<JoiStringSchema<TSc
      *   - `parent` - A clone of the object containing the value being validated
      *   - `helpers` - Validation helper functions for custom validation logic
      */
-    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+    default(value?: DefaultableValue): this;
 }
 /**
  * Schema type for binary data validation.
@@ -60,7 +67,7 @@ export interface BinarySchema<TSchema = Buffer> extends Omit<JoiBinarySchema<TSc
      *   - `parent` - A clone of the object containing the value being validated
      *   - `helpers` - Validation helper functions for custom validation logic
      */
-    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+    default(value?: DefaultableValue): this;
 }
 /**
  * Schema type for number validation.
@@ -78,7 +85,7 @@ export interface NumberSchema<TSchema = number> extends Omit<JoiNumberSchema<TSc
      *   - `parent` - A clone of the object containing the value being validated
      *   - `helpers` - Validation helper functions for custom validation logic
      */
-    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+    default(value?: DefaultableValue): this;
 }
 /**
  * Schema type for boolean validation.
@@ -96,7 +103,7 @@ export interface BooleanSchema<TSchema = boolean> extends Omit<JoiBooleanSchema<
      *   - `parent` - A clone of the object containing the value being validated
      *   - `helpers` - Validation helper functions for custom validation logic
      */
-    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+    default(value?: DefaultableValue): this;
 }
 /**
  * Schema type for object validation.
@@ -117,7 +124,7 @@ export interface ObjectSchema<TSchema = any> extends Omit<JoiObjectSchema<TSchem
      * When called without any value on an object schema type, a default value will be
      * automatically generated based on the default values of the object keys.
      */
-    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+    default(value?: DefaultableValue): this;
 }
 /**
  * Schema type for array validation.
@@ -135,7 +142,9 @@ export interface ArraySchema<TSchema = any[]> extends Omit<JoiArraySchema<TSchem
      *   - `parent` - A clone of the object containing the value being validated
      *   - `helpers` - Validation helper functions for custom validation logic
      */
-    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+    default(value?: DefaultableValue): this;
+    items(...types: ExtendedSchemaLikeWithoutArray[]): this;
+    ordered(...types: ExtendedSchemaLikeWithoutArray[]): this;
 }
 /**
  * Schema type for date validation.
@@ -153,5 +162,14 @@ export interface DateSchema<TSchema = Date> extends Omit<JoiDateSchema<TSchema>,
      *   - `parent` - A clone of the object containing the value being validated
      *   - `helpers` - Validation helper functions for custom validation logic
      */
-    default(value?: Reference | BasicType | ((parent: any, helpers: CustomHelpers) => Reference | BasicType)): this;
+    default(value?: DefaultableValue): this;
+}
+/**
+ * Schema type for alternatives validation.
+ *
+ * @public
+ */
+export interface AlternativesSchema<TSchema = any> extends Omit<JoiAlternativesSchema<TSchema>, 'default' | 'try'> {
+    try(...types: ExtendedSchemaLikeWithoutArray[]): this;
+    default(value?: DefaultableValue): this;
 }