@oscarpalmer/jhunal 0.25.0 → 0.27.0

package/dist/index.d.mts

@@ -1,12 +1,86 @@
 import { Constructor, GenericCallback, PlainObject, Simplify } from "@oscarpalmer/atoms/models";
 import { Result } from "@oscarpalmer/atoms/result/models";
 
+//#region src/validator.d.ts
+declare class Validator<Value> {
+  #private;
+  private readonly $validator;
+  constructor(handler: ValidationHandler, types: ValidationHandlerType[]);
+  /**
+   * Is the value valid?
+   *
+   * Will assert that the value is valid and throws an error if it does not
+   * @param value Value to validate
+   * @returns `true` if the value is valid, otherwise throws an error
+   */
+  is(value: unknown, reporting: 'throw'): asserts value is Value;
+  /**
+   * Is the value valid?
+   *
+   * Will validate that the value is valid and return a result of `true` or validation information for the first validation failure
+   * @param value Value to validate
+   * @return Result holding `true` or validation information
+   */
+  is(value: unknown, reporting: 'result'): Result<Value, ValueValidation>;
+  /**
+   * Is the value valid?
+   * @param value Value to validate
+   * @returns `true` if the value is valid, otherwise `false`
+   */
+  is(value: unknown, reporting?: 'none'): value is Value;
+}
+/**
+ * Create a validator for value types
+ * @param types Types to validate against
+ * @param validators Custom validators to use for validation
+ * @returns Validator
+ */
+declare function validator<Types extends Array<Constructor | ((value: unknown) => boolean) | ValueType>>(types: Types, validators?: Validators): Validator<InferValidatorValue<Types>>;
+/**
+ * Create a validator for a constructor
+ * @param constructor Constructor to validate against
+ * @returns Validator
+ */
+declare function validator<Instance>(constructor: Constructor<Instance>): Validator<Instance>;
+/**
+ * Create a validator for a callback
+ * @param callback Callback for validation
+ * @returns Validator
+ */
+declare function validator<Value>(callback: (value: unknown) => value is Value): Validator<Value>;
+/**
+ * Create a validator for a callback
+ * @param callback Callback for validation
+ * @returns Validator
+ */
+declare function validator<Value>(callback: (value: unknown) => boolean): Validator<Value>;
+/**
+ * Create a validator for a type
+ * @param type Type to validate against
+ * @param validators Custom validators to use for validation
+ * @returns Validator
+ */
+declare function validator<Type extends ValueType>(type: Type, validators?: ((value: Values[Type]) => boolean) | Array<(value: Values[Type]) => boolean> | Record<Type, ((value: Values[Type]) => boolean) | Array<(value: Values[Type]) => boolean>>): Validator<Values[Type]>;
+/**
+ * Create a validator for value types
+ * @param types Types to validate against
+ * @param validators Custom validators to use for validation
+ * @returns Validator
+ */
+declare function validator<Types extends ValueType[]>(types: Types, validators?: Validators): Validator<unknown>;
+/**
+ * Create a validator for an array of items
+ * @param type Type of items in the array
+ * @returns Validator
+ */
+declare function validator<Item>(type: 'array'): Validator<Item[]>;
+//#endregion
 //#region src/models/schematic.plain.model.d.ts
 /**
  * A generic schematic allowing nested schematics, {@link SchematicEntry} values, or arrays of {@link SchematicEntry} as values
  */
 type PlainSchematic = {
-  [key: string]: PlainSchematic | SchematicEntry | SchematicEntry[] | undefined;
+  [key: string]: SchematicEntry | SchematicEntry[];
 } & {
   $default?: never;
   $required?: never;
@@ -29,9 +103,9 @@ type Schematic = PlainSchematic;
 /**
  * A union of all valid types for a single schematic entry
  *
- * Can be a {@link Constructor}, {@link PlainSchematic}, {@link SchematicProperty}, {@link Schema}, {@link ValueName}, or a custom validator function
+ * Can be a {@link Constructor}, {@link PlainSchematic}, {@link SchematicProperty}, {@link Schema}, {@link ValueType}, or a custom validator function
  */
-type SchematicEntry = Constructor | PlainSchematic | Schema<unknown> | SchematicProperty | ValueName | ((value: unknown) => boolean);
+type SchematicEntry = Constructor | PlainSchematic | Schema<unknown> | SchematicProperty | Validator<unknown> | ValueType | ((value: unknown) => boolean);
 /**
  * A property definition with explicit type(s), an optional requirement flag, and optional validators
  *
@@ -58,18 +132,18 @@ type SchematicProperty = {
    */
   $type: SchemaPropertyType | SchemaPropertyType[];
   /**
-   * Optional validators keyed by {@link ValueName}, applied during validation
+   * Optional validators keyed by {@link ValueType}, applied during validation
    */
   $validators?: PropertyValidators<SchemaPropertyType | SchemaPropertyType[]>;
 };
 /**
  * A union of valid types for a {@link SchematicProperty}'s `$type` field
  *
- * Can be a {@link Constructor}, {@link PlainSchematic}, {@link Schema}, {@link ValueName} string, or a custom validator function
+ * Can be a {@link Constructor}, {@link PlainSchematic}, {@link Schema}, {@link ValueType} string, or a custom validator function
  */
-type SchemaPropertyType = Constructor | PlainSchematic | Schema<unknown> | ValueName | ((value: unknown) => boolean);
+type SchemaPropertyType = Constructor | PlainSchematic | Schema<unknown> | Validator<unknown> | ValueType | ((value: unknown) => boolean);
 /**
- * A map of optional validator functions keyed by {@link ValueName}, used to add custom validation to {@link SchemaProperty} definitions
+ * A map of optional validator functions keyed by {@link ValueType}, used to add custom validation to {@link SchemaProperty} definitions
  *
  * Each key may hold a single validator or an array of validators that receive the typed value
  *
@@ -82,7 +156,7 @@ type SchemaPropertyType = Constructor | PlainSchematic | Schema<unknown> | Value
  * };
  * ```
  */
-type PropertyValidators<Value> = { [Key in ExtractValueNames<Value>]?: ((value: Values[Key]) => boolean) | Array<(value: Values[Key]) => boolean> };
+type PropertyValidators<Value> = { [Key in ExtractValueTypes<Value>]?: ((value: Values[Key]) => boolean) | Array<(value: Values[Key]) => boolean> };
 //#endregion
 //#region src/models/misc.model.d.ts
 /**
@@ -99,17 +173,17 @@ type PropertyValidators<Value> = { [Key in ExtractValueNames<Value>]?: ((value:
  */
 type DeduplicateTuple<Value extends unknown[], Seen extends unknown[] = []> = Value extends [infer Head, ...infer Tail] ? Head extends Seen[number] ? DeduplicateTuple<Tail, Seen> : DeduplicateTuple<Tail, [...Seen, Head]> : Seen;
 /**
- * Recursively extracts {@link ValueName} strings from a type, unwrapping arrays and readonly arrays
+ * Recursively extracts {@link ValueType} strings from a type, unwrapping arrays and readonly arrays
  *
- * @template Value Type to extract value names from
+ * @template Value Type to extract value types from
  *
  * @example
  * ```ts
- * // ExtractValueNames<'string'>         => 'string'
- * // ExtractValueNames<['string', 'number']> => 'string' | 'number'
+ * // ExtractValueTypes<'string'>         => 'string'
+ * // ExtractValueTypes<['string', 'number']> => 'string' | 'number'
  * ```
  */
-type ExtractValueNames<Value> = Value extends ValueName ? Value : Value extends (infer Item)[] ? ExtractValueNames<Item> : Value extends readonly (infer Item)[] ? ExtractValueNames<Item> : never;
+type ExtractValueTypes<Value> = Value extends ValueType ? Value : Value extends (infer Item)[] ? ExtractValueTypes<Item> : Value extends readonly (infer Item)[] ? ExtractValueTypes<Item> : never;
 /**
  * Determines whether a schema entry is optional
  *
@@ -207,9 +281,9 @@ type UnwrapSingle<Value extends unknown[]> = Value extends [infer Only] ? Only :
 /**
  * A union of valid type name strings, e.g. `'string'`, `'number'`, `'date'`
  */
-type ValueName = keyof Values;
+type ValueType = keyof Values;
 /**
- * Maps {@link ValueName} strings to their TypeScript equivalents
+ * Maps {@link ValueType} strings to their TypeScript equivalents
  */
 type Values = {
   array: unknown[];
@@ -259,11 +333,9 @@ type InferPropertyType<Value> = Value extends (infer Item)[] ? InferPropertyValu
 /**
  * Maps a single `$type` definition to its TypeScript equivalent
  *
- * Resolves, in order: {@link Constructor}s, {@link Schema} instances, {@link ValueName} values, and nested {@link PlainSchematic} objects
- *
  * @template Value single type definition
  */
-type InferPropertyValue<Value> = Value extends Constructor<infer Instance> ? Instance : Value extends Schema<infer Model> ? Model : Value extends ValueName ? Values[Value & ValueName] : Value extends PlainSchematic ? Infer<Value> : never;
+type InferPropertyValue<Value> = Value extends Constructor<infer Instance> ? Instance : Value extends Schema<infer Model> ? Model : Value extends Validator<infer Type> ? Type : Value extends ValueType ? Values[Value & ValueType] : Value extends PlainSchematic ? Infer<Value> : never;
 /**
  * Extracts keys from a {@link Schematic} whose entries are required _(i.e., `$required` is not `false`)_
  *
@@ -279,11 +351,15 @@ type InferSchemaEntry<Value> = Value extends (infer Item)[] ? InferSchemaEntryVa
 /**
  * Maps a single top-level schema entry to its TypeScript type
  *
- * Resolves, in order: {@link Constructor}s, {@link Schema} instances, {@link SchemaProperty} objects, {@link PlainSchematic} objects, and {@link ValueName} values
- *
  * @template Value single schema entry
  */
-type InferSchemaEntryValue<Value> = Value extends Constructor<infer Instance> ? Instance : Value extends Schema<infer Model> ? Model : Value extends SchematicProperty ? InferPropertyType<Value['$type']> : Value extends PlainSchematic ? Infer<Value & Schematic> : Value extends ValueName ? Values[Value & ValueName] : never;
+type InferSchemaEntryValue<Value> = Value extends Constructor<infer Instance> ? Instance : Value extends Schema<infer Model> ? Model : Value extends SchematicProperty ? InferPropertyType<Value['$type']> : Value extends PlainSchematic ? Infer<Value & Schematic> : Value extends Validator<infer Type> ? Type : Value extends ValueType ? Values[Value & ValueType] : never;
+/**
+ * Infers the TypeScript type from a {@link Validator} definition
+ *
+ * @template Value Validator to infer type from
+ */
+type InferValidatorValue<Value> = Value extends (infer Item)[] ? InferValidatorValue<Item> : Value extends Constructor<infer Instance> ? Instance : Value extends ((value: unknown) => value is infer Type) ? Type : Value extends ((value: unknown) => boolean) ? 'xyz' : Value extends ValueType ? Values[Value & ValueType] : never;
 //#endregion
 //#region src/models/transform.model.d.ts
 /**
@@ -313,13 +389,13 @@ type ToSchemaPropertyType<Value> = UnwrapSingle<DeduplicateTuple<MapToSchemaProp
  */
 type ToSchemaPropertyTypeEach<Value> = Value extends PlainObject ? TypedSchematic<Value> : ToValueType<Value>;
 /**
- * Converts a TypeScript type to its {@link ValueName} representation, suitable for use as a top-level schema entry
+ * Converts a TypeScript type to its {@link ValueType} representation, suitable for use as a top-level schema entry
  *
  * @template Value Type to convert
  */
 type ToSchemaType<Value> = UnwrapSingle<DeduplicateTuple<MapToValueTypes<UnionToTuple<Value>>>>;
 /**
- * Maps a type to its {@link ValueName} string equivalent
+ * Maps a type to its {@link ValueType} string equivalent
  *
  * Resolves {@link Schema} types as-is, then performs a reverse-lookup against {@link Values} _(excluding `'object'`)_ to find a matching key. If no match is found, `object` types resolve to `'object'` or a type-guard function, and all other unrecognised types resolve to a type-guard function
  *
@@ -389,7 +465,7 @@ type TypedPropertyRequired<Value> = {
  * };
  * ```
  */
-type TypedSchematic<Model extends PlainObject> = Simplify<{ [Key in RequiredKeys<Model>]: Model[Key] extends PlainObject ? Schema<Model[Key]> : ToSchemaType<Model[Key]> | TypedPropertyRequired<Model[Key]> } & { [Key in OptionalKeys<Model>]: Exclude<Model[Key], undefined> extends PlainObject ? Schema<Exclude<Model[Key], undefined>> : TypedPropertyOptional<Model[Key]> }>;
+type TypedSchematic<Model extends PlainObject> = Simplify<{ [Key in RequiredKeys<Model>]: Model[Key] extends PlainObject ? Schema<Model[Key]> | TypedSchematic<Model[Key]> : ToSchemaType<Model[Key]> | TypedPropertyRequired<Model[Key]> } & { [Key in OptionalKeys<Model>]: Exclude<Model[Key], undefined> extends PlainObject ? TypedPropertyOptional<Model[Key]> : never }>;
 //#endregion
 //#region src/schema.d.ts
 /**
@@ -398,77 +474,77 @@ type TypedSchematic<Model extends PlainObject> = Simplify<{ [Key in RequiredKeys
 declare class Schema<Model> {
   #private;
   private readonly $schema;
-  constructor(validator: Validator);
+  constructor(validator: ValidationHandler);
   /**
    * Parse a value according to the schema
    *
-   * Returns a deeply cloned version of the value or throws an error for the first property that fails validation
+   * Returns value _(deeply cloned, by default)_ or throws an error for the first property that fails validation
    * @param value Value to parse
    * @param options Validation options
-   * @returns Deeply cloned version of the value if it matches the schema, otherwise throws an error
+   * @returns Value, if it matches the schema, otherwise throws an error
    */
   get(value: unknown, options: GetOptions<'throw'>): Model;
   /**
    * Parse a value according to the schema
    *
-   * Returns a deeply cloned version of the value or throws an error for the first property that fails validation
+   * Returns value _(deeply cloned, by default)_ or throws an error for the first property that fails validation
    * @param value Value to parse
    * @param errors Reporting type
-   * @returns Deeply cloned version of the value if it matches the schema, otherwise throws an error
+   * @returns Value, if it matches the schema, otherwise throws an error
    */
   get(value: unknown, errors: 'throw'): Model;
   /**
    * Parse a value according to the schema
    *
-   * Returns a result of a deeply cloned version of the value or all validation information for validation failures from the same depth in the value
+   * Returns value _(deeply cloned, by default)_ or all validation information for validation failures from the same depth in the value
    * @param value Value to parse
    * @param options Validation options
-   * @returns Result holding deeply cloned value or all validation information
+   * @returns Result holding value or all validation information
    */
-  get(value: unknown, options: GetOptions<'all'>): Result<Model, ValidationInformation[]>;
+  get(value: unknown, options: GetOptions<'all'>): Result<Model, PropertyValidation[]>;
   /**
    * Parse a value according to the schema
    *
-   * Returns a result of a deeply cloned version of the value or all validation information for validation failures from the same depth in the value
+   * Returns value _(deeply cloned, by default)_ or all validation information for validation failures from the same depth in the value
    * @param value Value to parse
    * @param errors Reporting type
-   * @returns Result holding deeply cloned value or all validation information
+   * @returns Result holding value or all validation information
    */
-  get(value: unknown, errors: 'all'): Result<Model, ValidationInformation[]>;
+  get(value: unknown, errors: 'all'): Result<Model, PropertyValidation[]>;
   /**
    * Parse a value according to the schema
    *
-   * Returns a deeply cloned version of the value or all validation information for the first failing property
+   * Returns value _(deeply cloned, by default)_ or all validation information for the first failing property
    * @param value Value to parse
    * @param options Validation options
-   * @returns Result holding deeply cloned value or all validation information
+   * @returns Result holding value or all validation information
    */
-  get(value: unknown, options: GetOptions<'first'>): Result<Model, ValidationInformation>;
+  get(value: unknown, options: GetOptions<'first'>): Result<Model, PropertyValidation>;
   /**
    * Parse a value according to the schema
    *
-   * Returns a deeply cloned version of the value or all validation information for the first failing property
+   * Returns value _(deeply cloned, by default)_ or all validation information for the first failing property
    * @param value Value to parse
    * @param errors Reporting type
-   * @returns Result holding deeply cloned value or all validation information
+   * @returns Result holding value or all validation information
    */
-  get(value: unknown, errors: 'first'): Result<Model, ValidationInformation>;
+  get(value: unknown, errors: 'first'): Result<Model, PropertyValidation>;
   /**
    * Parse a value according to the schema
    *
-   * Returns a deeply cloned version of the value or `undefined` if the value does not match the schema
+   * Returns value _(deeply cloned, by default)_ or `undefined` if the value does not match the schema
    * @param value Value to parse
    * @param options Validation options
-   * @returns Deeply cloned value, or `undefined` if it's invalid
+   * @returns Value, or `undefined` if it's invalid
    */
-  get(value: unknown, options: GetOptions<'none'>): Model | undefined;
+  get(value: unknown, options: Partial<GetOptions<'none'>>): Model | undefined;
   /**
    * Parse a value according to the schema
    *
-   * Returns a deeply cloned version of the value or `undefined` if the value does not match the schema
+   * Returns value _(deeply cloned, by default)_ or `undefined` if the value does not match the schema
    * @param value Value to parse
    * @param strict Validate if unknown keys are present in the object? _(defaults to `false`)_
-   * @returns Deeply cloned value, or `undefined` if it's invalid
+   * @returns Value, or `undefined` if it's invalid
    */
   get(value: unknown, strict?: true): Model | undefined;
   /**
@@ -497,7 +573,7 @@ declare class Schema<Model> {
    * @param options Validation options
    * @returns Result holding `true` or all validation information
    */
-  is(value: unknown, options: IsOptions<'all'>): Result<true, ValidationInformation[]>;
+  is(value: unknown, options: IsOptions<'all'>): Result<true, PropertyValidation[]>;
   /**
    * Does the value match the schema?
    *
@@ -506,38 +582,38 @@ declare class Schema<Model> {
    * @param errors Reporting type
    * @returns Result holding `true` or all validation information
    */
-  is(value: unknown, errors: 'all'): Result<true, ValidationInformation[]>;
+  is(value: unknown, errors: 'all'): Result<true, PropertyValidation[]>;
   /**
    * Does the value match the schema?
    *
    * Will validate that the value matches the schema and return a result of `true` or all validation information for the first failing property
    * @param value Value to validate
    * @param options Validation options
-   * @returns `true` if the value matches the schema, otherwise `false`
+   * @returns Result holding `true` or all validation information
    */
-  is(value: unknown, options: IsOptions<'first'>): Result<true, ValidationInformation>;
+  is(value: unknown, options: IsOptions<'first'>): Result<true, PropertyValidation>;
   /**
    * Does the value match the schema?
    *
    * Will validate that the value matches the schema and return a result of `true` or all validation information for the first failing property
    * @param value Value to validate
    * @param errors Reporting type
-   * @returns `true` if the value matches the schema, otherwise `false`
+   * @returns Result holding `true` or all validation information
    */
-  is(value: unknown, errors: 'first'): Result<true, ValidationInformation>;
+  is(value: unknown, errors: 'first'): Result<true, PropertyValidation>;
   /**
    * Does the value match the schema?
    *
-   * Will validate that the value matches the schema and return `true` or `false`, without any validation information for validation failures
+   * Will validate that the value matches the schema and return `true` if it's valid, or `false` if not
    * @param value Value to validate
    * @param options Validation options
    * @returns `true` if the value matches the schema, otherwise `false`
    */
-  is(value: unknown, options: IsOptions<'none'>): value is Model;
+  is(value: unknown, options: Partial<IsOptions<'none'>>): value is Model;
   /**
    * Does the value match the schema?
    *
-   * Will validate that the value matches the schema and return `true` or `false`, without any validation information for validation failures
+   * Will validate that the value matches the schema and return `true` if it's valid, or `false` if not
    * @param value Value to validate
    * @param strict Validate if unknown keys are present in the object? _(defaults to `false`)_
    * @returns `true` if the value matches the schema, otherwise `false`
@@ -569,11 +645,11 @@ type ReportingInformation = Record<ReportingType, boolean> & {
  * Controls how validation failures are reported
  *
  * - `'none'`, returns a boolean _(default)_
- * - `'first'`, returns the first failure as a `Result`
+ * - `'first'` or `'result'`, returns the first failure as a `Result`
  * - `'all'`, returns all failures as a `Result` _(from same level)_
  * - `'throw'`, throws a {@link ValidationError} on failure
  */
-type ReportingType = 'all' | 'first' | 'none' | 'throw';
+type ReportingType = 'all' | 'first' | 'none' | 'result' | 'throw';
 /**
  * Thrown when a schema definition is invalid
  */
@@ -584,25 +660,42 @@ declare class SchematicError extends Error {
  * Thrown in `'throw'` mode when one or more properties fail validation; `information` holds all failures
  */
 declare class ValidationError extends Error {
-  readonly information: ValidationInformation[];
-  constructor(information: ValidationInformation[]);
+  readonly information: PropertyValidation[];
+  constructor(information: PropertyValidation[]);
 }
 /**
- * Describes a single validation failure
+ * Describes a single property validation failure
  */
-type ValidationInformation = {
-  /** The key path of the property that failed */key: ValidationInformationKey; /** Human-readable description of the failure */
-  message: string; /** The validator function that failed, if the failure was from a `$validators` entry */
-  validator?: GenericCallback; /** The value that was provided */
+type PropertyValidation = {
+  /**
+   * The key path of the property that failed
+   */
+  key?: PropertyValidationKey;
+  /**
+   * Human-readable description of the failure
+   */
+  message: string;
+  /**
+   * The validator function that failed, if the failure was from a `$validators` entry
+   */
+  validator?: GenericCallback;
+  /**
+   * The value that was provided
+   */
   value: unknown;
 };
 /**
- *
+ * The full and short key paths of a property; `full` is the complete path from the root, while `short` is the path from the current schema
  */
-type ValidationInformationKey = {
+type PropertyValidationKey = {
   full: string;
   short: string;
 };
+type ValueValidation = {
+  message: string;
+  validator?: GenericCallback;
+  value: unknown;
+};
 type BaseOptions<Errors extends ReportingType> = {
   /**
    * How should validation failures be reported; see {@link ReportingType} _(defaults to `'none'`)_
@@ -626,14 +719,20 @@ type GetOptions<Errors extends ReportingType> = BaseOptions<Errors> & {
  * Options for validation an input value
  */
 type IsOptions<Errors extends ReportingType> = BaseOptions<Errors>;
-type Validator = (input: unknown, parameters: ValidatorParameters, get: boolean) => true | ValidationInformation[];
-type ValidatorParameters = {
+/**
+ * Object property validators
+ */
+type Validators = { [Key in ValueType]?: Array<(value: unknown) => boolean> };
+type ValidationHandler = (input: unknown, parameters: ValidationHandlerParameters, get: boolean) => true | PropertyValidation[];
+type ValidationHandlerParameters = {
   clone: boolean;
-  information?: ValidationInformation[];
+  information?: PropertyValidation[];
+  key?: string;
   output: PlainObject;
   reporting: ReportingInformation;
   strict: boolean;
 };
+type ValidationHandlerType = Function | PlainObject | Schema<unknown> | Validator<unknown> | ValueType;
 //#endregion
 //#region src/helpers/misc.helper.d.ts
 /**
@@ -644,10 +743,10 @@ type ValidatorParameters = {
  */
 declare function instanceOf<Instance>(constructor: Constructor<Instance>): (value: unknown) => value is Instance;
 /**
- * Is the value a schematic?
+ * Is the value a schema?
  * @param value Value to check
- * @returns `true` if the value is a schematic, `false` otherwise
+ * @returns `true` if the value is a schema, `false` otherwise
  */
-declare function isSchema(value: unknown): value is Schema<never>;
+declare function isSchema(value: unknown): value is Schema<unknown>;
 //#endregion
-export { type GetOptions, type IsOptions, type Schema, type Schematic, SchematicError, type TypedSchematic, ValidationError, instanceOf, isSchema, schema };
+export { type GetOptions, type IsOptions, type Schema, type Schematic, SchematicError, type TypedSchematic, ValidationError, type Validator, instanceOf, isSchema, schema, validator };