@nhtio/validation 1.20250814.0 → 1.20250911.0

package/package.json

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

package/private/index.d.ts

@@ -1,3 +1,4 @@
+import { default as Joi } from 'joi';
 import type { DateTime } from 'luxon';
 import type { PhoneSchema } from './schemas/phone';
 import type { BigIntSchema } from './schemas/bigint';
@@ -5,7 +6,7 @@ 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';
+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.
@@ -25,7 +26,7 @@ import type { AlternativesSchema, AnySchema, StringSchema, BinarySchema, NumberS
  *
  * @public
  */
-export interface ValidationRoot extends Omit<Root, 'any' | 'string' | 'binary' | 'number' | 'bool' | '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.
      */
@@ -50,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).
      */
@@ -62,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
      */
@@ -72,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.
      */
@@ -86,6 +109,72 @@ 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.
      *

package/private/schemas.d.ts

@@ -4,7 +4,6 @@ import type { BigIntSchema } from './schemas/bigint';
 import type { DatetimeSchema } from './schemas/datetime';
 import type { default as Joi, AnySchema as JoiAnySchema, Reference, BasicType, CustomHelpers } from 'joi';
 export type DefaultableValue = Reference | BasicType | DateTime | bigint | ((parent: any, helpers: CustomHelpers) => Reference | BasicType | DateTime | bigint);
-export type ExtendedSchemaLikeWithoutArray = string | number | boolean | null | Schema | Joi.SchemaMap | PhoneSchema | BigIntSchema | DatetimeSchema;
 /**
  * Base schema type for all validation schemas.
  *
@@ -13,7 +12,36 @@ export type ExtendedSchemaLikeWithoutArray = string | number | boolean | null |
  *
  * @public
  */
-export interface AnySchema<TSchema = any> extends Omit<JoiAnySchema<TSchema>, 'allow' | 'alter' | 'artifact' | 'bind' | 'cache' | 'cast' | 'concat' | 'custom' | 'default' | 'description' | 'disallow' | 'empty' | 'equal' | 'error' | 'example' | 'exist' | 'external' | 'failover' | 'forbidden' | 'fork' | 'id' | 'invalid' | 'keep' | 'label' | 'message' | 'messages' | 'meta' | 'not' | 'note' | 'only' | 'optional' | 'options' | 'preferences' | 'prefs' | 'presence' | 'raw' | 'required' | 'rule' | 'shared' | 'strict' | 'strip' | 'tag' | 'unit' | 'valid' | 'warn' | 'warning' | 'when'> {
+export interface AnySchema<TSchema = any> extends Omit<JoiAnySchema<TSchema>, '$_addRule' | '$_compile' | '$_modify' | '$_mutateRebuild' | '$_reach' | '$_super' | '$' | 'allow' | 'alter' | 'artifact' | 'bind' | 'cache' | 'cast' | 'concat' | 'custom' | 'default' | 'description' | 'disallow' | 'empty' | 'equal' | 'error' | 'example' | 'exist' | 'external' | 'extract' | 'failover' | 'forbidden' | 'fork' | 'id' | 'invalid' | 'keep' | 'label' | 'message' | 'messages' | 'meta' | 'not' | 'note' | 'only' | 'optional' | 'options' | 'preferences' | 'prefs' | 'presence' | 'raw' | 'required' | 'rule' | 'ruleset' | 'shared' | 'strict' | 'strip' | 'tag' | 'tailor' | 'unit' | 'valid' | 'warn' | 'warning' | 'when'> {
+    /**
+     * Parent schema object.
+     */
+    $_super: Schema;
+    /**
+     * Adds a rule to current validation schema.
+     */
+    $_addRule(rule: string | Joi.AddRuleOptions): Schema;
+    /**
+     * Internally compiles schema.
+     */
+    $_compile(schema: SchemaLike, options?: Joi.CompileOptions): Schema;
+    $_modify(options?: Joi.ModifyOptions): Schema;
+    /**
+     * Resets current schema.
+     */
+    $_mutateRebuild(): this;
+    /**
+     * Get schema at given path.
+     */
+    $_reach(path: string[]): Schema;
+    /**
+     * Starts a ruleset in order to apply multiple rule options. The set ends when `rule()`, `keep()`, `message()`, or `warn()` is called.
+     */
+    $: this;
+    /**
+     * Starts a ruleset in order to apply multiple rule options. The set ends when `rule()`, `keep()`, `message()`, or `warn()` is called.
+     */
+    ruleset: this;
     allow(...values: any[]): this;
     alter(targets: Record<string, (schema: this) => Schema>): this;
     artifact(id: any): this;
@@ -23,7 +51,7 @@ export interface AnySchema<TSchema = any> extends Omit<JoiAnySchema<TSchema>, 'a
     custom(fn: Joi.CustomValidator, description?: string): this;
     description(desc: string): this;
     disallow(...values: any[]): this;
-    empty(schema?: Joi.SchemaLike): this;
+    empty(schema?: SchemaLike): this;
     equal(...values: any[]): this;
     error(err: Error | Joi.ValidationErrorFunction): this;
     example(value: any, options?: {
@@ -31,6 +59,12 @@ export interface AnySchema<TSchema = any> extends Omit<JoiAnySchema<TSchema>, 'a
     }): this;
     exist(): this;
     external(method: Joi.ExternalValidationFunction, description?: string): this;
+    /**
+     * Returns a sub-schema based on a path of object keys or schema ids.
+     *
+     * @param path - a dot `.` separated path string or a pre-split array of path keys. The keys must match the sub-schema id or object key (if no id was explicitly set).
+     */
+    extract(path: string | string[]): Schema;
     failover(value: any): this;
     forbidden(): this;
     fork(key: string | string[] | string[][], adjuster: Joi.SchemaFunction): this;
@@ -56,6 +90,10 @@ export interface AnySchema<TSchema = any> extends Omit<JoiAnySchema<TSchema>, 'a
     strict(isStrict?: boolean): this;
     strip(enabled?: boolean): this;
     tag(...tags: string[]): this;
+    /**
+     * Applies any assigned target alterations to a copy of the schema that were applied via `any.alter()`.
+     */
+    tailor(targets: string | string[]): Schema;
     unit(name: string): this;
     valid(...values: any[]): this;
     warn(): this;
@@ -375,12 +413,12 @@ export interface ObjectSchema<TSchema = any> extends AnySchema<TSchema> {
     /**
      * Appends the allowed object keys. If schema is null, undefined, or {}, no changes will be applied.
      */
-    append(schema?: Joi.SchemaMap<TSchema>): this;
-    append<TSchemaExtended = any, T = TSchemaExtended>(schema?: Joi.SchemaMap<T>): ObjectSchema<T>;
+    append(schema?: SchemaMap<TSchema>): this;
+    append<TSchemaExtended = any, T = TSchemaExtended>(schema?: SchemaMap<T>): ObjectSchema<T>;
     /**
      * Verifies an assertion where.
      */
-    assert(ref: string | Reference, schema: Joi.SchemaLike, message?: string): this;
+    assert(ref: string | Reference, schema: SchemaLike, message?: string): this;
     /**
      * Requires the object to be an instance of a given constructor.
      *
@@ -391,7 +429,7 @@ export interface ObjectSchema<TSchema = any> extends AnySchema<TSchema> {
     /**
      * Sets or extends the allowed object keys.
      */
-    keys(schema?: Joi.SchemaMap<TSchema>): this;
+    keys(schema?: SchemaMap<TSchema>): this;
     /**
      * Specifies the exact number of keys in the object.
      */
@@ -428,7 +466,7 @@ export interface ObjectSchema<TSchema = any> extends AnySchema<TSchema> {
      * @param pattern - a pattern that can be either a regular expression or a joi schema that will be tested against the unknown key names
      * @param schema - the schema object matching keys must validate against
      */
-    pattern(pattern: RegExp | Joi.SchemaLike, schema: Joi.SchemaLike, options?: Joi.ObjectPatternOptions): this;
+    pattern(pattern: RegExp | SchemaLike, schema: SchemaLike, options?: Joi.ObjectPatternOptions): this;
     /**
      * Requires the object to be a Joi reference.
      */
@@ -444,7 +482,7 @@ export interface ObjectSchema<TSchema = any> extends AnySchema<TSchema> {
     /**
      * Requires the object to be a Joi schema instance.
      */
-    schema(type?: Joi.SchemaLike): this;
+    schema(type?: SchemaLike): this;
     /**
      * Overrides the handling of unknown keys for the scope of the current object only (does not apply to children).
      */
@@ -489,7 +527,7 @@ export interface ArraySchema<TSchema = any[]> extends AnySchema<TSchema> {
      * `schema` - the validation rules required to satisfy the assertion. If the `schema` includes references, they are resolved against
      * the array item being tested, not the value of the `ref` target.
      */
-    has(schema: Joi.SchemaLike): this;
+    has(schema: SchemaLike): this;
     /**
      * Specifies the exact number of items in the array.
      */
@@ -545,7 +583,7 @@ export interface ArraySchema<TSchema = any[]> extends AnySchema<TSchema> {
      *
      * @param type - a joi schema object to validate each array item against.
      */
-    items(...types: ExtendedSchemaLikeWithoutArray[]): this;
+    items(...types: SchemaLikeWithoutArray[]): this;
     /**
      * Lists the types in sequence order for the array values where:
      * @param type - a joi schema object to validate against each array item in sequence order. type can be multiple values passed as individual arguments.
@@ -553,7 +591,7 @@ export interface ArraySchema<TSchema = any[]> extends AnySchema<TSchema> {
      * Errors will contain the number of items that didn't match.
      * Any unmatched item having a label will be mentioned explicitly.
      */
-    ordered(...types: ExtendedSchemaLikeWithoutArray[]): this;
+    ordered(...types: SchemaLikeWithoutArray[]): this;
 }
 /**
  * Schema type for date validation.
@@ -629,7 +667,7 @@ export interface AlternativesSchema<TSchema = any> extends AnySchema<TSchema> {
     /**
      * Adds an alternative schema type for attempting to match against the validated value.
      */
-    try(...types: ExtendedSchemaLikeWithoutArray[]): this;
+    try(...types: SchemaLikeWithoutArray[]): this;
     default(value?: DefaultableValue): this;
 }
 /**
@@ -637,7 +675,7 @@ export interface AlternativesSchema<TSchema = any> extends AnySchema<TSchema> {
  *
  * @public
  */
-export interface FunctionSchema<TSchema = Function> extends AnySchema<TSchema> {
+export interface FunctionSchema<TSchema = Function> extends ObjectSchema<TSchema> {
     /**
      * Specifies the arity of the function where:
      * @param n - the arity expected.
@@ -688,4 +726,14 @@ export interface SymbolSchema<TSchema = symbol> extends AnySchema<TSchema> {
 /**
  * A union type that includes all schema types.
  */
-export type Schema = AnySchema | StringSchema | BinarySchema | NumberSchema | BooleanSchema | ObjectSchema | ArraySchema | DateSchema | AlternativesSchema | FunctionSchema | LinkSchema | SymbolSchema | BigIntSchema | DatetimeSchema | PhoneSchema;
+export type Schema<P = any> = AnySchema<P> | ArraySchema<P> | AlternativesSchema<P> | BinarySchema<P> | BooleanSchema<P> | DateSchema<P> | FunctionSchema<P> | NumberSchema<P> | ObjectSchema<P> | StringSchema<P> | LinkSchema<P> | SymbolSchema<P> | BigIntSchema<P> | DatetimeSchema<P> | PhoneSchema<P>;
+export type ObjectPropertiesSchema<T = any> = true extends Joi.IsNonPrimitiveSubsetUnion<Exclude<T, undefined | null>> ? AlternativesSchema : T extends Joi.NullableType<string> ? StringSchema : T extends Joi.NullableType<number> ? NumberSchema : T extends Joi.NullableType<bigint> ? BigIntSchema : T extends Joi.NullableType<boolean> ? BooleanSchema : T extends Joi.NullableType<Date> ? DateSchema : T extends Joi.NullableType<Buffer> ? BinarySchema : T extends Joi.NullableType<Array<any>> ? ArraySchema : T extends DateTime ? DatetimeSchema : T extends Joi.NullableType<object> ? StrictSchemaMap<T> | ObjectSchema<T> : never;
+export type PartialSchemaMap<TSchema = any> = {
+    [key in keyof TSchema]?: SchemaLike | SchemaLike[];
+};
+export type StrictSchemaMap<TSchema = any> = {
+    [key in keyof TSchema]-?: ObjectPropertiesSchema<TSchema[key]>;
+};
+export type SchemaMap<TSchema = any, IsStrict = false> = IsStrict extends true ? StrictSchemaMap<TSchema> : PartialSchemaMap<TSchema>;
+export type SchemaLikeWithoutArray = string | number | boolean | null | Schema | SchemaMap;
+export type SchemaLike = SchemaLikeWithoutArray | object;