@nhtio/validation 1.20250804.0 → 1.20250813.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhtio/validation",
-  "version": "1.20250804.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/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;
 }