@oscarpalmer/jhunal 0.21.0 → 0.23.0

package/dist/index.d.mts

@@ -1,6 +1,228 @@
 import { Constructor, GenericCallback, PlainObject, Simplify } from "@oscarpalmer/atoms/models";
 import { Result } from "@oscarpalmer/atoms/result/models";
 
+//#region src/models/schema.plain.model.d.ts
+/**
+ * A generic schema allowing nested schemas, {@link SchemaEntry} values, or arrays of {@link SchemaEntry} as values
+ */
+type PlainSchema = {
+  [key: string]: PlainSchema | SchemaEntry | SchemaEntry[] | undefined;
+} & {
+  $required?: never;
+  $type?: never;
+  $validators?: never;
+};
+/**
+ * A schema for validating objects
+ *
+ * @example
+ * ```ts
+ * const schema: Schema = {
+ *   name: 'string',
+ *   age: 'number',
+ *   tags: ['string', 'number'],
+ * };
+ * ```
+ */
+type Schema = PlainSchema;
+/**
+ * A union of all valid types for a single schema entry
+ *
+ * Can be a {@link Constructor}, {@link PlainSchema}, {@link SchemaProperty}, {@link Schematic}, {@link ValueName} string, or a custom validator function
+ */
+type SchemaEntry = Constructor | PlainSchema | SchemaProperty | Schematic<unknown> | ValueName | ((value: unknown) => boolean);
+/**
+ * A property definition with explicit type(s), an optional requirement flag, and optional validators
+ *
+ * @example
+ * ```ts
+ * const prop: SchemaProperty = {
+ *   $required: false,
+ *   $type: ['string', 'number'],
+ *   $validators: {
+ *     string: (v) => v.length > 0,
+ *     number: (v) => v > 0,
+ *   },
+ * };
+ * ```
+ */
+type SchemaProperty = {
+  /**
+   * Whether the property is required _(defaults to `true`)_
+   */
+  $required?: boolean;
+  /**
+   * The type(s) the property value must match; a single {@link SchemaPropertyType} or an array
+   */
+  $type: SchemaPropertyType | SchemaPropertyType[];
+  /**
+   * Optional validators keyed by {@link ValueName}, applied during validation
+   */
+  $validators?: PropertyValidators<SchemaPropertyType | SchemaPropertyType[]>;
+};
+/**
+ * A union of valid types for a {@link SchemaProperty}'s `$type` field
+ *
+ * Can be a {@link Constructor}, {@link PlainSchema}, {@link Schematic}, {@link ValueName} string, or a custom validator function
+ */
+type SchemaPropertyType = Constructor | PlainSchema | Schematic<unknown> | ValueName | ((value: unknown) => boolean);
+/**
+ * A map of optional validator functions keyed by {@link ValueName}, 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
+ *
+ * @template Value `$type` value(s) to derive validator keys from
+ *
+ * @example
+ * ```ts
+ * const validators: PropertyValidators<'string'> = {
+ *   string: (value) => value.length > 0,
+ * };
+ * ```
+ */
+type PropertyValidators<Value> = { [Key in ExtractValueNames<Value>]?: ((value: Values[Key]) => boolean) | Array<(value: Values[Key]) => boolean> };
+//#endregion
+//#region src/models/misc.model.d.ts
+/**
+ * Removes duplicate types from a tuple, preserving first occurrence order
+ *
+ * @template Value Tuple to deduplicate
+ * @template Seen Accumulator for already-seen types _(internal)_
+ *
+ * @example
+ * ```ts
+ * // DeduplicateTuple<['string', 'number', 'string']>
+ * // => ['string', 'number']
+ * ```
+ */
+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
+ *
+ * @template Value Type to extract value names from
+ *
+ * @example
+ * ```ts
+ * // ExtractValueNames<'string'>         => 'string'
+ * // ExtractValueNames<['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;
+/**
+ * Determines whether a schema entry is optional
+ *
+ * Returns `true` if the entry is a {@link SchemaProperty} with `$required` set to `false`; otherwise returns `false`
+ *
+ * @template Value Schema entry to check
+ */
+type IsOptionalProperty<Value> = Value extends SchemaProperty ? Value['$required'] extends false ? true : false : false;
+/**
+ * Extracts the last member from a union type by leveraging contravariance of function parameter types
+ *
+ * @template Value Union type
+ */
+type LastOfUnion<Value> = UnionToIntersection<Value extends unknown ? () => Value : never> extends (() => infer Item) ? Item : never;
+/**
+ * Extracts keys from an object type that are optional
+ *
+ * @template Value Object type to inspect
+ */
+type OptionalKeys<Value> = { [Key in keyof Value]-?: {} extends Pick<Value, Key> ? Key : never }[keyof Value];
+/**
+ * Extracts keys from an object type that are required _(i.e., not optional)_
+ *
+ * @template Value Object type to inspect
+ */
+type RequiredKeys<Value> = Exclude<keyof Value, OptionalKeys<Value>>;
+/**
+ * Generates all permutations of a tuple type
+ *
+ * Used by {@link UnwrapSingle} to allow schema types in any order for small tuples _(length ≤ 5)_
+ *
+ * @template Tuple Tuple to permute
+ * @template Elput Accumulator for the current permutation _(internal; name is Tuple backwards)_
+ *
+ * @example
+ * ```ts
+ * // TuplePermutations<['string', 'number']>
+ * // => ['string', 'number'] | ['number', 'string']
+ * ```
+ */
+type TuplePermutations<Tuple extends unknown[], Elput extends unknown[] = []> = Tuple['length'] extends 0 ? Elput : { [Key in keyof Tuple]: TuplePermutations<TupleRemoveAt<Tuple, Key & `${number}`>, [...Elput, Tuple[Key]]> }[keyof Tuple & `${number}`];
+/**
+ * Removes the element at a given index from a tuple
+ *
+ * Used internally by {@link TuplePermutations}
+ *
+ * @template Items Tuple to remove from
+ * @template Item Index as a string literal
+ * @template Prefix Accumulator for elements before the target _(internal)_
+ */
+type TupleRemoveAt<Items extends unknown[], Item extends string, Prefix extends unknown[] = []> = Items extends [infer Head, ...infer Tail] ? `${Prefix['length']}` extends Item ? [...Prefix, ...Tail] : TupleRemoveAt<Tail, Item, [...Prefix, Head]> : Prefix;
+/**
+ * Converts a union type into an intersection
+ *
+ * Uses the contravariance of function parameter types to collapse a union into an intersection
+ *
+ * @template Value Union type to convert
+ *
+ * @example
+ * ```ts
+ * // UnionToIntersection<{ a: 1 } | { b: 2 }>
+ * // => { a: 1 } & { b: 2 }
+ * ```
+ */
+type UnionToIntersection<Value> = (Value extends unknown ? (value: Value) => void : never) extends ((value: infer Item) => void) ? Item : never;
+/**
+ * Converts a union type into an ordered tuple
+ *
+ * Repeatedly extracts the {@link LastOfUnion} member and prepends it to the accumulator
+ *
+ * @template Value Union type to convert
+ * @template Items Accumulator for the resulting tuple _(internal)_
+ *
+ * @example
+ * ```ts
+ * // UnionToTuple<'a' | 'b' | 'c'>
+ * // => ['a', 'b', 'c']
+ * ```
+ */
+type UnionToTuple<Value, Items extends unknown[] = []> = [Value] extends [never] ? Items : UnionToTuple<Exclude<Value, LastOfUnion<Value>>, [LastOfUnion<Value>, ...Items]>;
+/**
+ * Unwraps a single-element tuple to its inner type
+ *
+ * For tuples of length 2–5, returns all {@link TuplePermutations} to allow types in any order. Longer tuples are returned as-is
+ *
+ * @template Value Tuple to potentially unwrap
+ *
+ * @example
+ * ```ts
+ * // UnwrapSingle<['string']>            => 'string'
+ * // UnwrapSingle<['string', 'number']>  => ['string', 'number'] | ['number', 'string']
+ * ```
+ */
+type UnwrapSingle<Value extends unknown[]> = Value extends [infer Only] ? Only : Value['length'] extends 1 | 2 | 3 | 4 | 5 ? TuplePermutations<Value> : Value;
+/**
+ * A union of valid type name strings, e.g. `'string'`, `'number'`, `'date'`
+ */
+type ValueName = keyof Values;
+/**
+ * Maps {@link ValueName} strings to their TypeScript equivalents
+ */
+type Values = {
+  array: unknown[];
+  bigint: bigint;
+  boolean: boolean;
+  date: Date;
+  function: Function;
+  null: null;
+  number: number;
+  object: object;
+  string: string;
+  symbol: symbol;
+  undefined: undefined;
+};
+//#endregion
 //#region src/models/infer.model.d.ts
 /**
  * Infers the TypeScript type from a {@link Schema} definition
@@ -181,128 +403,32 @@ type TypedSchemaRequired<Model extends PlainObject> = {
   $required?: true;
 } & TypedSchema<Model>;
 //#endregion
-//#region src/models/validation.model.d.ts
-/**
- * Controls how validation failures are reported
- *
- * - `'none'` — returns a boolean _(default)_
- * - `'first'` — 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';
-/**
- * Thrown when a schema definition is invalid
- */
-declare class SchematicError extends Error {
-  constructor(message: string);
-}
+//#region src/schematic.d.ts
 /**
- * The runtime representation of a parsed schema property, used internally during validation
- *
- * @example
- * ```ts
- * const parsed: ValidatedProperty = {
- *   key: 'age',
- *   required: true,
- *   types: ['number'],
- *   validators: { number: [(v) => v > 0] },
- * };
- * ```
+ * A schematic for validating objects
  */
-type ValidatedProperty = {
+declare class Schematic<Model> {
+  #private;
+  private readonly $schematic;
+  constructor(validator: Validator);
   /**
-   * The property name in the schema
+   * 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
+   * @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
    */
-  key: string;
+  get(value: unknown, options: GetOptions<'throw'>): Model;
   /**
-   * Whether the property is required
+   * 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
+   * @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
    */
-  required: boolean;
-  /**
-   * The allowed types for this property
-   */
-  types: ValidatedPropertyType[];
-  /**
-   * Custom validators grouped by {@link ValueName}
-   */
-  validators: ValidatedPropertyValidators;
-};
-/**
- * A union of valid types for a {@link ValidatedProperty}'s `types` array
- *
- * Can be a callback _(custom validator)_, a {@link Schematic}, a nested {@link ValidatedProperty}, or a {@link ValueName} string
- */
-type ValidatedPropertyType = GenericCallback | ValidatedProperty[] | Schematic<unknown> | ValueName;
-/**
- * A map of validator functions keyed by {@link ValueName}, used at runtime in {@link ValidatedProperty}
- *
- * Each key holds an array of validator functions that receive an `unknown` value and return a `boolean`
- */
-type ValidatedPropertyValidators = { [Key in ValueName]?: Array<(value: unknown) => boolean> };
-/**
- * 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[]);
-}
-/**
- * Describes a single 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 */
-  value: unknown;
-};
-/**
- *
- */
-type ValidationInformationKey = {
-  full: string;
-  short: string;
-};
-/**
- * Options for validation
- */
-type ValidationOptions<Errors extends ReportingType> = {
-  /**
-   * How should validation failures be reported; see {@link ReportingType} _(defaults to `'none'`)_
-   */
-  errors?: Errors;
-  /**
-   * Validate if unknown keys are present in the object? _(defaults to `false`)_
-   */
-  strict?: boolean;
-};
-//#endregion
-//#region src/schematic.d.ts
-/**
- * A schematic for validating objects
- */
-declare class Schematic<Model> {
-  #private;
-  private readonly $schematic;
-  constructor(properties: ValidatedProperty[]);
-  /**
-   * 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
-   * @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
-   */
-  get(value: unknown, options: ValidationOptions<'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
-   * @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
-   */
-  get(value: unknown, errors: 'throw'): Model;
+  get(value: unknown, errors: 'throw'): Model;
   /**
    * Parse a value according to the schema
    *
@@ -311,7 +437,7 @@ declare class Schematic<Model> {
    * @param options Validation options
    * @returns Result holding deeply cloned value or all validation information
    */
-  get(value: unknown, options: ValidationOptions<'all'>): Result<Model, ValidationInformation[]>;
+  get(value: unknown, options: GetOptions<'all'>): Result<Model, ValidationInformation[]>;
   /**
    * Parse a value according to the schema
    *
@@ -329,7 +455,7 @@ declare class Schematic<Model> {
    * @param options Validation options
    * @returns Result holding deeply cloned value or all validation information
    */
-  get(value: unknown, options: ValidationOptions<'first'>): Result<Model, ValidationInformation>;
+  get(value: unknown, options: GetOptions<'first'>): Result<Model, ValidationInformation>;
   /**
    * Parse a value according to the schema
    *
@@ -339,6 +465,15 @@ declare class Schematic<Model> {
    * @returns Result holding deeply cloned value or all validation information
    */
   get(value: unknown, errors: 'first'): Result<Model, ValidationInformation>;
+  /**
+   * 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
+   * @param value Value to parse
+   * @param options Validation options
+   * @returns Deeply cloned value, or `undefined` if it's invalid
+   */
+  get(value: unknown, options: GetOptions<'none'>): Model | undefined;
   /**
    * Parse a value according to the schema
    *
@@ -356,7 +491,7 @@ declare class Schematic<Model> {
    * @param options Validation options
    * @returns `true` if the value matches the schema, otherwise throws an error
    */
-  is(value: unknown, options: ValidationOptions<'throw'>): asserts value is Model;
+  is(value: unknown, options: IsOptions<'throw'>): asserts value is Model;
   /**
    * Does the value match the schema?
    *
@@ -374,7 +509,7 @@ declare class Schematic<Model> {
    * @param options Validation options
    * @returns Result holding `true` or all validation information
    */
-  is(value: unknown, options: ValidationOptions<'all'>): Result<true, ValidationInformation[]>;
+  is(value: unknown, options: IsOptions<'all'>): Result<true, ValidationInformation[]>;
   /**
    * Does the value match the schema?
    *
@@ -392,7 +527,7 @@ declare class Schematic<Model> {
    * @param options Validation options
    * @returns `true` if the value matches the schema, otherwise `false`
    */
-  is(value: unknown, options: ValidationOptions<'first'>): Result<true, ValidationInformation>;
+  is(value: unknown, options: IsOptions<'first'>): Result<true, ValidationInformation>;
   /**
    * Does the value match the schema?
    *
@@ -402,6 +537,15 @@ declare class Schematic<Model> {
    * @returns `true` if the value matches the schema, otherwise `false`
    */
   is(value: unknown, errors: 'first'): Result<true, ValidationInformation>;
+  /**
+   * 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
+   * @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;
   /**
    * Does the value match the schema?
    *
@@ -429,235 +573,81 @@ declare function schematic<Model extends Schema>(schema: Model): Schematic<Infer
  */
 declare function schematic<Model extends PlainObject>(schema: TypedSchema<Model>): Schematic<Model>;
 //#endregion
-//#region src/models/schema.plain.model.d.ts
-/**
- * A generic schema allowing nested schemas, {@link SchemaEntry} values, or arrays of {@link SchemaEntry} as values
- */
-type PlainSchema = {
-  [key: string]: PlainSchema | SchemaEntry | SchemaEntry[] | undefined;
-} & {
-  $required?: never;
-  $type?: never;
-  $validators?: never;
+//#region src/models/validation.model.d.ts
+type ReportingInformation = Record<ReportingType, boolean> & {
+  type: ReportingType;
 };
 /**
- * A schema for validating objects
+ * Controls how validation failures are reported
  *
- * @example
- * ```ts
- * const schema: Schema = {
- *   name: 'string',
- *   age: 'number',
- *   tags: ['string', 'number'],
- * };
- * ```
+ * - `'none'`, returns a boolean _(default)_
+ * - `'first'`, 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 Schema = SchemaIndex;
+type ReportingType = 'all' | 'first' | 'none' | 'throw';
 /**
- * A union of all valid types for a single schema entry
- *
- * Can be a {@link Constructor}, {@link PlainSchema}, {@link SchemaProperty}, {@link Schematic}, {@link ValueName} string, or a custom validator function
+ * Thrown when a schema definition is invalid
  */
-type SchemaEntry = Constructor | PlainSchema | SchemaProperty | Schematic<unknown> | ValueName | ((value: unknown) => boolean);
+declare class SchematicError extends Error {
+  constructor(message: string);
+}
 /**
- * Index signature interface backing {@link Schema}, allowing string-keyed entries of {@link PlainSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry}
+ * Thrown in `'throw'` mode when one or more properties fail validation; `information` holds all failures
  */
-interface SchemaIndex {
-  [key: string]: PlainSchema | SchemaEntry | SchemaEntry[];
+declare class ValidationError extends Error {
+  readonly information: ValidationInformation[];
+  constructor(information: ValidationInformation[]);
 }
 /**
- * A property definition with explicit type(s), an optional requirement flag, and optional validators
+ * Describes a single 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 */
+  value: unknown;
+};
+/**
  *
- * @example
- * ```ts
- * const prop: SchemaProperty = {
- *   $required: false,
- *   $type: ['string', 'number'],
- *   $validators: {
- *     string: (v) => v.length > 0,
- *     number: (v) => v > 0,
- *   },
- * };
- * ```
  */
-type SchemaProperty = {
-  /**
-   * Whether the property is required _(defaults to `true`)_
-   */
-  $required?: boolean;
+type ValidationInformationKey = {
+  full: string;
+  short: string;
+};
+type BaseOptions<Errors extends ReportingType> = {
   /**
-   * The type(s) the property value must match; a single {@link SchemaPropertyType} or an array
+   * How should validation failures be reported; see {@link ReportingType} _(defaults to `'none'`)_
    */
-  $type: SchemaPropertyType | SchemaPropertyType[];
+  errors: Errors;
   /**
-   * Optional validators keyed by {@link ValueName}, applied during validation
+   * Validate if unknown keys are present in the object? _(defaults to `false`)_
    */
-  $validators?: PropertyValidators<SchemaPropertyType | SchemaPropertyType[]>;
+  strict?: boolean;
 };
 /**
- * A union of valid types for a {@link SchemaProperty}'s `$type` field
- *
- * Can be a {@link Constructor}, {@link PlainSchema}, {@link Schematic}, {@link ValueName} string, or a custom validator function
- */
-type SchemaPropertyType = Constructor | PlainSchema | Schematic<unknown> | ValueName | ((value: unknown) => boolean);
-/**
- * A map of optional validator functions keyed by {@link ValueName}, 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
- *
- * @template Value `$type` value(s) to derive validator keys from
- *
- * @example
- * ```ts
- * const validators: PropertyValidators<'string'> = {
- *   string: (value) => value.length > 0,
- * };
- * ```
- */
-type PropertyValidators<Value> = { [Key in ExtractValueNames<Value>]?: ((value: Values[Key]) => boolean) | Array<(value: Values[Key]) => boolean> };
-//#endregion
-//#region src/models/misc.model.d.ts
-/**
- * Removes duplicate types from a tuple, preserving first occurrence order
- *
- * @template Value Tuple to deduplicate
- * @template Seen Accumulator for already-seen types _(internal)_
- *
- * @example
- * ```ts
- * // DeduplicateTuple<['string', 'number', 'string']>
- * // => ['string', 'number']
- * ```
- */
-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
- *
- * @template Value Type to extract value names from
- *
- * @example
- * ```ts
- * // ExtractValueNames<'string'>         => 'string'
- * // ExtractValueNames<['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;
-/**
- * Determines whether a schema entry is optional
- *
- * Returns `true` if the entry is a {@link SchemaProperty} with `$required` set to `false`; otherwise returns `false`
- *
- * @template Value Schema entry to check
- */
-type IsOptionalProperty<Value> = Value extends SchemaProperty ? Value['$required'] extends false ? true : false : false;
-/**
- * Extracts the last member from a union type by leveraging contravariance of function parameter types
- *
- * @template Value Union type
- */
-type LastOfUnion<Value> = UnionToIntersection<Value extends unknown ? () => Value : never> extends (() => infer Item) ? Item : never;
-/**
- * Extracts keys from an object type that are optional
- *
- * @template Value Object type to inspect
- */
-type OptionalKeys<Value> = { [Key in keyof Value]-?: {} extends Pick<Value, Key> ? Key : never }[keyof Value];
-/**
- * Extracts keys from an object type that are required _(i.e., not optional)_
- *
- * @template Value Object type to inspect
- */
-type RequiredKeys<Value> = Exclude<keyof Value, OptionalKeys<Value>>;
-/**
- * Generates all permutations of a tuple type
- *
- * Used by {@link UnwrapSingle} to allow schema types in any order for small tuples _(length ≤ 5)_
- *
- * @template Tuple Tuple to permute
- * @template Elput Accumulator for the current permutation _(internal; name is Tuple backwards)_
- *
- * @example
- * ```ts
- * // TuplePermutations<['string', 'number']>
- * // => ['string', 'number'] | ['number', 'string']
- * ```
- */
-type TuplePermutations<Tuple extends unknown[], Elput extends unknown[] = []> = Tuple['length'] extends 0 ? Elput : { [Key in keyof Tuple]: TuplePermutations<TupleRemoveAt<Tuple, Key & `${number}`>, [...Elput, Tuple[Key]]> }[keyof Tuple & `${number}`];
-/**
- * Removes the element at a given index from a tuple
- *
- * Used internally by {@link TuplePermutations}
- *
- * @template Items Tuple to remove from
- * @template Item Index as a string literal
- * @template Prefix Accumulator for elements before the target _(internal)_
- */
-type TupleRemoveAt<Items extends unknown[], Item extends string, Prefix extends unknown[] = []> = Items extends [infer Head, ...infer Tail] ? `${Prefix['length']}` extends Item ? [...Prefix, ...Tail] : TupleRemoveAt<Tail, Item, [...Prefix, Head]> : Prefix;
-/**
- * Converts a union type into an intersection
- *
- * Uses the contravariance of function parameter types to collapse a union into an intersection
- *
- * @template Value Union type to convert
- *
- * @example
- * ```ts
- * // UnionToIntersection<{ a: 1 } | { b: 2 }>
- * // => { a: 1 } & { b: 2 }
- * ```
+ * Options for validating and getting a value from an input
  */
-type UnionToIntersection<Value> = (Value extends unknown ? (value: Value) => void : never) extends ((value: infer Item) => void) ? Item : never;
-/**
- * Converts a union type into an ordered tuple
- *
- * Repeatedly extracts the {@link LastOfUnion} member and prepends it to the accumulator
- *
- * @template Value Union type to convert
- * @template Items Accumulator for the resulting tuple _(internal)_
- *
- * @example
- * ```ts
- * // UnionToTuple<'a' | 'b' | 'c'>
- * // => ['a', 'b', 'c']
- * ```
- */
-type UnionToTuple<Value, Items extends unknown[] = []> = [Value] extends [never] ? Items : UnionToTuple<Exclude<Value, LastOfUnion<Value>>, [LastOfUnion<Value>, ...Items]>;
-/**
- * Unwraps a single-element tuple to its inner type
- *
- * For tuples of length 2–5, returns all {@link TuplePermutations} to allow types in any order. Longer tuples are returned as-is
- *
- * @template Value Tuple to potentially unwrap
- *
- * @example
- * ```ts
- * // UnwrapSingle<['string']>            => 'string'
- * // UnwrapSingle<['string', 'number']>  => ['string', 'number'] | ['number', 'string']
- * ```
- */
-type UnwrapSingle<Value extends unknown[]> = Value extends [infer Only] ? Only : Value['length'] extends 1 | 2 | 3 | 4 | 5 ? TuplePermutations<Value> : Value;
-/**
- * A union of valid type name strings, e.g. `'string'`, `'number'`, `'date'`
- */
-type ValueName = keyof Values;
+type GetOptions<Errors extends ReportingType> = BaseOptions<Errors> & {
+  /**
+   * Get a deeply cloned version of the input? _(defaults to `true`)_
+   */
+  clone?: boolean;
+};
 /**
- * Maps {@link ValueName} strings to their TypeScript equivalents
+ * Options for validation an input value
  */
-type Values = {
-  array: unknown[];
-  bigint: bigint;
-  boolean: boolean;
-  date: Date;
-  function: Function;
-  null: null;
-  number: number;
-  object: object;
-  string: string;
-  symbol: symbol;
-  undefined: undefined;
+type IsOptions<Errors extends ReportingType> = BaseOptions<Errors>;
+type Validator = (input: unknown, parameters: ValidatorParameters, get: boolean) => true | ValidationInformation[];
+type ValidatorParameters = {
+  clone: boolean;
+  information?: ValidationInformation[];
+  output: PlainObject;
+  reporting: ReportingInformation;
+  strict: boolean;
 };
 //#endregion
-//#region src/helpers.d.ts
+//#region src/helpers/misc.helper.d.ts
 /**
  * Creates a validator function for a given constructor
  * @param constructor - Constructor to check against
@@ -672,4 +662,4 @@ declare function instanceOf<Instance>(constructor: Constructor<Instance>): (valu
  */
 declare function isSchematic(value: unknown): value is Schematic<never>;
 //#endregion
-export { type Schema, type Schematic, SchematicError, type TypedSchema, ValidationError, instanceOf, isSchematic, schematic };
+export { type GetOptions, type IsOptions, type Schema, type Schematic, SchematicError, type TypedSchema, ValidationError, instanceOf, isSchematic, schematic };