@nhtio/validation 1.20250814.1 → 1.20250911.1

package/package.json

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

package/private/schemas/datetime.d.ts

@@ -2,8 +2,9 @@ import { DateTime } from 'luxon';
 import { Dayjs } from 'dayjs';
 import type { Tokens } from '../types';
 import type { AnySchema } from '../schemas';
-import type { ExtensionFactory, Reference } from 'joi';
+import type { ExtensionFactory, CustomHelpers, Reference } from 'joi';
 import type { Zone, LocaleOptions, DateObjectUnits, ZoneOptions, ToISOTimeOptions, ToISODateOptions, ToSQLOptions, ToRelativeOptions } from 'luxon';
+type CallbackOrValue<T> = T | ((dt: DateTime, helpers: CustomHelpers) => T);
 export declare const messages: {
     'datetime.base': string;
     'datetime.exactly': string;
@@ -251,59 +252,90 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
     /**
      * Formats the datetime using a custom format string during validation.
      *
-     * @param format - The format string (Luxon format tokens)
+     * @param format - The format string (Luxon format tokens) or callback function
      * @returns The schema instance for method chaining
      *
-     * @example
+     * @example Static format
      * ```typescript
      * const schema = joi.datetime().toFormat('yyyy-MM-dd HH:mm:ss')
      * const result = schema.validate('2023-07-15T15:30:00Z')
      * // Returns: "2023-07-15 15:30:00"
      * ```
+     *
+     * @example Callback function (serializable)
+     * ```typescript
+     * const schema = joi.datetime().toFormat((dt, helpers) =>
+     *   dt.year > 2000 ? 'yyyy-MM-dd' : 'MM/dd/yy'
+     * )
+     * ```
      */
-    toFormat(format: Tokens): this;
+    toFormat(format: CallbackOrValue<Tokens>): this;
     /**
      * Formats the datetime using locale-specific formatting during validation.
      *
-     * @param formatOpts - Locale formatting options
+     * @param formatOpts - Locale formatting options or callback function
      * @returns The schema instance for method chaining
      *
-     * @example
+     * @example Static options
      * ```typescript
-     * const schema = joi.datetime().toLocaleString({ month: 'long', day: 'numeric' })
+     * const schema = joi.datetime().toLocalizedString({ month: 'long', day: 'numeric' })
      * const result = schema.validate('2023-07-15T15:30:00Z')
      * // Returns: "July 15" (or localized equivalent)
      * ```
+     *
+     * @example Callback function (serializable)
+     * ```typescript
+     * const schema = joi.datetime().toLocalizedString((dt, helpers) => ({
+     *   month: dt.month > 6 ? 'long' : 'short',
+     *   day: 'numeric'
+     * }))
+     * ```
      */
-    toLocalizedString(formatOpts: LocaleOptions): this;
+    toLocalizedString(formatOpts: CallbackOrValue<LocaleOptions>): this;
     /**
      * Converts the datetime to ISO 8601 string format during validation.
      *
-     * @param opts - Options for ISO string formatting
+     * @param opts - Options for ISO string formatting or callback function
      * @returns The schema instance for method chaining
      *
-     * @example
+     * @example Static options
      * ```typescript
-     * const schema = joi.datetime().toISO()
+     * const schema = joi.datetime().toISO({ suppressMilliseconds: true })
      * const result = schema.validate('July 15, 2023 3:30 PM')
-     * // Returns: "2023-07-15T15:30:00.000Z"
+     * // Returns: "2023-07-15T15:30:00Z"
+     * ```
+     *
+     * @example Callback function (serializable)
+     * ```typescript
+     * const schema = joi.datetime().toISO((dt, helpers) => ({
+     *   suppressMilliseconds: true,
+     *   extendedZone: dt.year > 1970,
+     *   precision: 'seconds'
+     * }))
      * ```
      */
-    toISO(opts?: ToISOTimeOptions): this;
+    toISO(opts?: CallbackOrValue<ToISOTimeOptions>): this;
     /**
      * Converts the datetime to ISO date format (YYYY-MM-DD) during validation.
      *
-     * @param opts - Options for ISO date formatting
+     * @param opts - Options for ISO date formatting or callback function
      * @returns The schema instance for method chaining
      *
-     * @example
+     * @example Static options
      * ```typescript
      * const schema = joi.datetime().toISODate()
      * const result = schema.validate('July 15, 2023 3:30 PM')
      * // Returns: "2023-07-15"
      * ```
+     *
+     * @example Callback function (serializable)
+     * ```typescript
+     * const schema = joi.datetime().toISODate((dt, helpers) => ({
+     *   format: dt.year > 2000 ? 'extended' : 'basic'
+     * }))
+     * ```
      */
-    toISODate(opts?: ToISODateOptions): this;
+    toISODate(opts?: CallbackOrValue<ToISODateOptions>): this;
     /**
      * Converts the datetime to ISO week date format during validation.
      *
@@ -320,17 +352,24 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
     /**
      * Converts the datetime to ISO time format during validation.
      *
-     * @param opts - Options for ISO time formatting
+     * @param opts - Options for ISO time formatting or callback function
      * @returns The schema instance for method chaining
      *
-     * @example
+     * @example Static options
      * ```typescript
-     * const schema = joi.datetime().toISOTime()
+     * const schema = joi.datetime().toISOTime({ suppressMilliseconds: true })
      * const result = schema.validate('2023-07-15T15:30:00Z')
-     * // Returns: "15:30:00.000Z"
+     * // Returns: "15:30:00Z"
+     * ```
+     *
+     * @example Callback function (serializable)
+     * ```typescript
+     * const schema = joi.datetime().toISOTime((dt, helpers) => ({
+     *   suppressMilliseconds: dt.millisecond === 0
+     * }))
      * ```
      */
-    toISOTime(opts?: ToISOTimeOptions): this;
+    toISOTime(opts?: CallbackOrValue<ToISOTimeOptions>): this;
     /**
      * Converts the datetime to RFC 2822 format during validation.
      *
@@ -373,31 +412,45 @@ 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
+     * @param opts - Options for SQL time formatting or callback function
      * @returns The schema instance for method chaining
      *
-     * @example
+     * @example Static options
      * ```typescript
-     * const schema = joi.datetime().toSQLTime()
+     * const schema = joi.datetime().toSQLTime({ includeZone: true })
      * const result = schema.validate('2023-07-15T15:30:45.123Z')
-     * // Returns: "15:30:45.123"
+     * // Returns: "15:30:45.123 Z"
+     * ```
+     *
+     * @example Callback function (serializable)
+     * ```typescript
+     * const schema = joi.datetime().toSQLTime((dt, helpers) => ({
+     *   includeZone: dt.zone.name !== 'UTC'
+     * }))
      * ```
      */
-    toSQLTime(opts?: ToSQLOptions): this;
+    toSQLTime(opts?: CallbackOrValue<ToSQLOptions>): this;
     /**
      * Converts the datetime to SQL datetime format during validation.
      *
-     * @param opts - Options for SQL formatting
+     * @param opts - Options for SQL formatting or callback function
      * @returns The schema instance for method chaining
      *
-     * @example
+     * @example Static options
      * ```typescript
-     * const schema = joi.datetime().toSQL()
+     * const schema = joi.datetime().toSQL({ includeZone: false })
      * const result = schema.validate('2023-07-15T15:30:45.123Z')
-     * // Returns: "2023-07-15 15:30:45.123 Z"
+     * // Returns: "2023-07-15 15:30:45.123"
+     * ```
+     *
+     * @example Callback function (serializable)
+     * ```typescript
+     * const schema = joi.datetime().toSQL((dt, helpers) => ({
+     *   includeZone: dt.zone.name !== 'UTC'
+     * }))
      * ```
      */
-    toSQL(opts?: ToSQLOptions): this;
+    toSQL(opts?: CallbackOrValue<ToSQLOptions>): this;
     /**
      * Converts the datetime to milliseconds since Unix epoch during validation.
      *
@@ -466,19 +519,26 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
     /**
      * Converts the datetime to a plain object representation during validation.
      *
-     * @param opts - Options for object conversion
+     * @param opts - Options for object conversion or callback function
      * @returns The schema instance for method chaining
      *
-     * @example
+     * @example Static options
      * ```typescript
-     * const schema = joi.datetime().toObject()
+     * const schema = joi.datetime().toObject({ includeConfig: true })
      * const result = schema.validate('2023-07-15T15:30:00Z')
      * // Returns: { year: 2023, month: 7, day: 15, hour: 15, minute: 30, second: 0, millisecond: 0 }
      * ```
+     *
+     * @example Callback function (serializable)
+     * ```typescript
+     * const schema = joi.datetime().toObject((dt, helpers) => ({
+     *   includeConfig: dt.year > 2000
+     * }))
+     * ```
      */
-    toObject(opts?: {
+    toObject(opts?: CallbackOrValue<{
         includeConfig?: boolean;
-    }): this;
+    }>): this;
     /**
      * Converts the datetime to a JavaScript Date object during validation.
      *
@@ -495,17 +555,24 @@ 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
+     * @param opts - Options for relative time formatting or callback function
      * @returns The schema instance for method chaining
      *
-     * @example
+     * @example Static options
      * ```typescript
-     * const schema = joi.datetime().toRelative()
+     * const schema = joi.datetime().toRelative({ base: DateTime.now() })
      * const result = schema.validate('2023-07-15T15:30:00Z')
      * // Returns: "2 hours ago" (relative to current time)
      * ```
+     *
+     * @example Callback function (serializable)
+     * ```typescript
+     * const schema = joi.datetime().toRelative((dt, helpers) => ({
+     *   base: dt.year > 2020 ? DateTime.now() : DateTime.fromISO('2020-01-01')
+     * }))
+     * ```
      */
-    toRelative(opts?: ToRelativeOptions): this;
+    toRelative(opts?: CallbackOrValue<ToRelativeOptions>): this;
     /**
      * Sets the locale for the datetime during validation.
      *
@@ -584,3 +651,4 @@ export interface DatetimeSchema<TSchema = DateTime> extends AnySchema<TSchema> {
  * ```
  */
 export declare const datetime: ExtensionFactory;
+export {};

package/private/schemas.d.ts

@@ -727,7 +727,7 @@ export interface SymbolSchema<TSchema = symbol> extends AnySchema<TSchema> {
  * A union type that includes all schema types.
  */
 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> ? NumberSchema : 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 Joi.NullableType<object> ? StrictSchemaMap<T> | ObjectSchema<T> : never;
+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[];
 };