@nhtio/validation 0.1.0-master-cd50e735 → 0.1.0-master-67185cae

package/package.json

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

package/private/index.d.ts

@@ -1,10 +1,12 @@
+import { default as Joi } 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 { AlternativesSchema, AnySchema, StringSchema, BinarySchema, NumberSchema, BooleanSchema, ObjectSchema, ArraySchema, DateSchema } from './schemas';
+import type { I18nCallback, SetI18nCallback } from './patches/i18n';
+import type { AnySchema, StringSchema, BinarySchema, NumberSchema, BooleanSchema, ObjectSchema, ArraySchema, DateSchema, AlternativesSchema, FunctionSchema, LinkSchema, SymbolSchema, Schema } from './schemas';
 /**
  * Extended Joi root interface that includes custom schema types for
  * additional validation scenarios.
@@ -24,7 +26,7 @@ import type { AlternativesSchema, AnySchema, StringSchema, BinarySchema, NumberS
  *
  * @public
  */
-export interface ValidationRoot extends Omit<Root, 'any' | 'string' | 'binary' | 'number' | 'boolean' | 'object' | 'array' | 'date' | 'alternatives' | 'alt'> {
+export interface ValidationRoot extends Omit<Root, 'allow' | 'alt' | 'alternatives' | 'any' | 'array' | 'binary' | 'bool' | 'boolean' | 'date' | 'disallow' | 'equal' | 'exist' | 'forbidden' | 'func' | 'function' | 'invalid' | 'link' | 'not' | 'number' | 'object' | 'optional' | 'preferences' | 'prefs' | 'required' | 'string' | 'symbol' | 'types' | 'valid' | 'when'> {
     /**
      * Generates a schema object that matches any data type.
      */
@@ -49,6 +51,14 @@ export interface ValidationRoot extends Omit<Root, 'any' | 'string' | 'binary' |
      * 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 function type.
+     */
+    func<TSchema = Function>(): FunctionSchema<TSchema>;
+    /**
+     * Generates a schema object that matches a function type.
+     */
+    function<TSchema = Function>(): FunctionSchema<TSchema>;
     /**
      * Generates a schema object that matches a number data type (as well as strings that can be converted to numbers).
      */
@@ -61,6 +71,10 @@ export interface ValidationRoot extends Omit<Root, 'any' | 'string' | 'binary' |
      * 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 schema object that matches any symbol.
+     */
+    symbol<TSchema = Symbol>(): SymbolSchema<TSchema>;
     /**
      * Generates a type that will match one of the provided alternative schemas
      */
@@ -71,6 +85,16 @@ export interface ValidationRoot extends Omit<Root, 'any' | 'string' | 'binary' |
      */
     alt<TSchema = any>(types: SchemaLike[]): AlternativesSchema<TSchema>;
     alt<TSchema = any>(...types: SchemaLike[]): AlternativesSchema<TSchema>;
+    /**
+     * Links to another schema node and reuses it for validation, typically for creative recursive schemas.
+     *
+     * @param ref - the reference to the linked schema node.
+     * Cannot reference itself or its children as well as other links.
+     * Links can be expressed in relative terms like value references (`Joi.link('...')`),
+     * in absolute terms from the schema run-time root (`Joi.link('/a')`),
+     * or using schema ids implicitly using object keys or explicitly using `any.id()` (`Joi.link('#a.b.c')`).
+     */
+    link<TSchema = any>(ref?: string): LinkSchema<TSchema>;
     /**
      * Generates a schema object that matches a BigInt data type.
      */
@@ -85,6 +109,128 @@ export interface ValidationRoot extends Omit<Root, 'any' | 'string' | 'binary' |
      * @param country - Optional country code or reference for phone validation
      */
     phone<TSchema = string>(country?: CountryOrUnknown | Reference | null): PhoneSchema<TSchema>;
+    /**
+     * Returns an object where each key is a plain joi schema type.
+     * Useful for creating type shortcuts using deconstruction.
+     * Note that the types are already formed and do not need to be called as functions (e.g. `string`, not `string()`).
+     */
+    types(): {
+        alternatives: AlternativesSchema;
+        any: AnySchema;
+        array: ArraySchema;
+        binary: BinarySchema;
+        boolean: BooleanSchema;
+        date: DateSchema;
+        function: FunctionSchema;
+        link: LinkSchema;
+        number: NumberSchema;
+        object: ObjectSchema;
+        string: StringSchema;
+        symbol: SymbolSchema;
+        bigint: BigIntSchema;
+        datetime: DatetimeSchema;
+        phone: PhoneSchema;
+    };
+    /**
+     * Whitelists a value
+     */
+    allow(...values: any[]): Schema;
+    /**
+     * Adds the provided values into the allowed whitelist and marks them as the only valid values allowed.
+     */
+    valid(...values: any[]): Schema;
+    equal(...values: any[]): Schema;
+    /**
+     * Blacklists a value
+     */
+    invalid(...values: any[]): Schema;
+    disallow(...values: any[]): Schema;
+    not(...values: any[]): Schema;
+    /**
+     * Marks a key as required which will not allow undefined as value. All keys are optional by default.
+     */
+    required(): Schema;
+    /**
+     * Alias of `required`.
+     */
+    exist(): Schema;
+    /**
+     * Marks a key as optional which will allow undefined as values. Used to annotate the schema for readability as all keys are optional by default.
+     */
+    optional(): Schema;
+    /**
+     * Marks a key as forbidden which will not allow any value except undefined. Used to explicitly forbid keys.
+     */
+    forbidden(): Schema;
+    /**
+     * Overrides the global validate() options for the current key and any sub-key.
+     */
+    preferences(options: Joi.ValidationOptions): Schema;
+    /**
+     * Overrides the global validate() options for the current key and any sub-key.
+     */
+    prefs(options: Joi.ValidationOptions): Schema;
+    /**
+     * Converts the type into an alternatives type where the conditions are merged into the type definition where:
+     */
+    when(ref: string | Reference, options: Joi.WhenOptions | Joi.WhenOptions[]): AlternativesSchema;
+    when(ref: Schema, options: Joi.WhenSchemaOptions): AlternativesSchema;
+    /**
+     * 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.
@@ -107,8 +253,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.