@oscarpalmer/jhunal 0.20.0 → 0.22.0

package/dist/helpers.d.mts

@@ -1,17 +1,14 @@
-import { ReportingInformation, ValidatedProperty } from "./models/validation.model.mjs";
+import { ReportingInformation, ValidatorParameters, ValidatorType } from "./models/validation.model.mjs";
 import { Schematic } from "./schematic.mjs";
 import { ValueName } from "./models/misc.model.mjs";
 import { Constructor } from "@oscarpalmer/atoms/models";
 
 //#region src/helpers.d.ts
 declare function getInvalidInputMessage(actual: unknown): string;
-declare function getInvalidMissingMessage(property: ValidatedProperty): string;
-declare function getInvalidTypeMessage(property: ValidatedProperty, actual: unknown): string;
-declare function getInvalidValidatorMessage(property: ValidatedProperty, type: ValueName, index: number, length: number): string;
-declare function getOptions(input: unknown): {
-  reporting: ReportingInformation;
-  strict: boolean;
-};
+declare function getInvalidMissingMessage(key: string, types: ValidatorType[]): string;
+declare function getInvalidTypeMessage(key: string, types: ValidatorType[], actual: unknown): string;
+declare function getInvalidValidatorMessage(key: string, type: ValueName, index: number, length: number): string;
+declare function getParameters(input?: unknown): ValidatorParameters;
 declare function getReporting(value: unknown): ReportingInformation;
 declare function getUnknownKeysMessage(keys: string[]): string;
 /**
@@ -28,4 +25,4 @@ declare function instanceOf<Instance>(constructor: Constructor<Instance>): (valu
  */
 declare function isSchematic(value: unknown): value is Schematic<never>;
 //#endregion
-export { getInvalidInputMessage, getInvalidMissingMessage, getInvalidTypeMessage, getInvalidValidatorMessage, getOptions, getReporting, getUnknownKeysMessage, instanceOf, isSchematic };
+export { getInvalidInputMessage, getInvalidMissingMessage, getInvalidTypeMessage, getInvalidValidatorMessage, getParameters, getReporting, getUnknownKeysMessage, instanceOf, isSchematic };

package/dist/helpers.mjs

@@ -4,41 +4,45 @@ import { isConstructor, isPlainObject } from "@oscarpalmer/atoms/is";
 function getInvalidInputMessage(actual) {
 	return VALIDATION_MESSAGE_INVALID_INPUT.replace("<>", getValueType(actual));
 }
-function getInvalidMissingMessage(property) {
-	let message = VALIDATION_MESSAGE_INVALID_REQUIRED.replace("<>", renderTypes(property.types));
-	message = message.replace("<>", property.key.full);
+function getInvalidMissingMessage(key, types) {
+	let message = VALIDATION_MESSAGE_INVALID_REQUIRED.replace("<>", renderTypes(types));
+	message = message.replace("<>", key);
 	return message;
 }
-function getInvalidTypeMessage(property, actual) {
-	let message = VALIDATION_MESSAGE_INVALID_TYPE.replace("<>", renderTypes(property.types));
-	message = message.replace("<>", property.key.full);
+function getInvalidTypeMessage(key, types, actual) {
+	let message = VALIDATION_MESSAGE_INVALID_TYPE.replace("<>", renderTypes(types));
+	message = message.replace("<>", key);
 	message = message.replace("<>", getValueType(actual));
 	return message;
 }
-function getInvalidValidatorMessage(property, type, index, length) {
-	let message = VALIDATION_MESSAGE_INVALID_VALUE.replace("<>", property.key.full);
+function getInvalidValidatorMessage(key, type, index, length) {
+	let message = VALIDATION_MESSAGE_INVALID_VALUE.replace("<>", key);
 	message = message.replace("<>", type);
 	if (length > 1) message += VALIDATION_MESSAGE_INVALID_VALUE_SUFFIX.replace("<>", String(index));
 	return message;
 }
-function getOptions(input) {
+function getParameters(input) {
 	if (typeof input === "boolean") return {
+		output: {},
 		reporting: getReporting(REPORTING_NONE),
 		strict: input
 	};
 	if (REPORTING_TYPES.has(input)) return {
+		output: {},
 		reporting: getReporting(input),
 		strict: false
 	};
 	const options = isPlainObject(input) ? input : {};
 	return {
+		output: {},
 		reporting: getReporting(options.errors),
 		strict: typeof options.strict === "boolean" ? options.strict : false
 	};
 }
 function getPropertyType(original) {
 	if (typeof original === "function") return "a validated value";
-	if (Array.isArray(original)) return `'${TYPE_OBJECT}'`;
+	if (Array.isArray(original)) return `'array'`;
+	if (isPlainObject(original)) return `'${TYPE_OBJECT}'`;
 	if (isSchematic(original)) return `a ${NAME_SCHEMATIC}`;
 	return `'${String(original)}'`;
 }
@@ -113,4 +117,4 @@ function renderTypes(types) {
 	return renderParts(parts, CONJUNCTION_OR, CONJUNCTION_OR_COMMA);
 }
 //#endregion
-export { getInvalidInputMessage, getInvalidMissingMessage, getInvalidTypeMessage, getInvalidValidatorMessage, getOptions, getReporting, getUnknownKeysMessage, instanceOf, isSchematic };
+export { getInvalidInputMessage, getInvalidMissingMessage, getInvalidTypeMessage, getInvalidValidatorMessage, getParameters, getReporting, getUnknownKeysMessage, instanceOf, isSchematic };

package/dist/index.d.mts

@@ -182,13 +182,16 @@ type TypedSchemaRequired<Model extends PlainObject> = {
 } & TypedSchema<Model>;
 //#endregion
 //#region src/models/validation.model.d.ts
+type ReportingInformation = Record<ReportingType, boolean> & {
+  type: ReportingType;
+};
 /**
  * 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
+ * - `'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';
 /**
@@ -197,58 +200,6 @@ type ReportingType = 'all' | 'first' | 'none' | 'throw';
 declare class SchematicError extends Error {
   constructor(message: string);
 }
-/**
- * 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] },
- * };
- * ```
- */
-type ValidatedProperty = {
-  /**
-   * The property name in the schema
-   */
-  key: ValidatedPropertyKey;
-  /**
-   * Whether the property is required
-   */
-  required: boolean;
-  /**
-   * The allowed types for this property
-   */
-  types: ValidatedPropertyType[];
-  /**
-   * Custom validators grouped by {@link ValueName}
-   */
-  validators: ValidatedPropertyValidators;
-};
-/**
- * The full and short forms of a property's key path
- *
- * For a nested property `address.street`: `full` is `'address.street'`, `short` is `'street'`
- */
-type ValidatedPropertyKey = {
-  full: string;
-  short: string;
-};
-/**
- * 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
  */
@@ -266,9 +217,12 @@ type ValidationInformation = {
   value: unknown;
 };
 /**
- * Same shape as {@link ValidatedPropertyKey}; the key path of a failed property
+ *
  */
-type ValidationInformationKey = ValidatedPropertyKey;
+type ValidationInformationKey = {
+  full: string;
+  short: string;
+};
 /**
  * Options for validation
  */
@@ -282,6 +236,13 @@ type ValidationOptions<Errors extends ReportingType> = {
    */
   strict?: boolean;
 };
+type Validator = (input: unknown, parameters: ValidatorParameters, get: boolean) => boolean | ValidationInformation[];
+type ValidatorParameters = {
+  information?: ValidationInformation[];
+  output: PlainObject;
+  reporting: ReportingInformation;
+  strict: boolean;
+};
 //#endregion
 //#region src/schematic.d.ts
 /**
@@ -290,11 +251,74 @@ type ValidationOptions<Errors extends ReportingType> = {
 declare class Schematic<Model> {
   #private;
   private readonly $schematic;
-  constructor(properties: ValidatedProperty[]);
+  constructor(validator: Validator);
+  /**
+   * 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;
+  /**
+   * 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
+   * @param value Value to parse
+   * @param options Validation options
+   * @returns Result holding deeply cloned value or all validation information
+   */
+  get(value: unknown, options: ValidationOptions<'all'>): Result<Model, ValidationInformation[]>;
+  /**
+   * 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
+   * @param value Value to parse
+   * @param errors Reporting type
+   * @returns Result holding deeply cloned value or all validation information
+   */
+  get(value: unknown, errors: 'all'): Result<Model, ValidationInformation[]>;
+  /**
+   * Parse a value according to the schema
+   *
+   * Returns a deeply cloned version of the value 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
+   */
+  get(value: unknown, options: ValidationOptions<'first'>): Result<Model, ValidationInformation>;
+  /**
+   * Parse a value according to the schema
+   *
+   * Returns a deeply cloned version of the value 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
+   */
+  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 strict Validate if unknown keys are present in the object? _(defaults to `false`)_
+   * @returns Deeply cloned value, or `undefined` if it's invalid
+   */
+  get(value: unknown, strict?: true): Model | undefined;
   /**
    * Does the value match the schema?
    *
-   * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation.
+   * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation
    * @param value Value to validate
    * @param options Validation options
    * @returns `true` if the value matches the schema, otherwise throws an error
@@ -303,7 +327,7 @@ declare class Schematic<Model> {
   /**
    * Does the value match the schema?
    *
-   * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation.
+   * Will assert that the values matches the schema and throw an error if it does not. The error will contain all validation information for the first property that fails validation
    * @param value Value to validate
    * @param errors Reporting type
    * @returns `true` if the value matches the schema, otherwise throws an error
@@ -312,25 +336,25 @@ declare class Schematic<Model> {
   /**
    * 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 validation failures from the same depth in the object.
+   * Will validate that the value matches the schema and return a result of `true` or all validation information for validation failures from the same depth in the value
    * @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: ValidationOptions<'all'>): Result<true, ValidationInformation[]>;
   /**
    * 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 validation failures from the same depth in the object.
+   * Will validate that the value matches the schema and return a result of `true` or all validation information for validation failures from the same depth in the value
    * @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: 'all'): Result<true, ValidationInformation[]>;
   /**
    * 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 failing property.
+   * 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`
@@ -339,7 +363,7 @@ declare class Schematic<Model> {
   /**
    * 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 failing property.
+   * 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`
@@ -348,7 +372,7 @@ declare class Schematic<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` or `false`, without any validation information for validation failures
    * @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`
@@ -395,19 +419,13 @@ type PlainSchema = {
  * };
  * ```
  */
-type Schema = SchemaIndex;
+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);
-/**
- * Index signature interface backing {@link Schema}, allowing string-keyed entries of {@link PlainSchema}, {@link SchemaEntry}, or arrays of {@link SchemaEntry}
- */
-interface SchemaIndex {
-  [key: string]: PlainSchema | SchemaEntry | SchemaEntry[];
-}
 /**
  * A property definition with explicit type(s), an optional requirement flag, and optional validators
  *
@@ -615,4 +633,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 Schema, type Schematic, SchematicError, type TypedSchema, ValidationError, type ValidationInformation, type ValidationOptions, instanceOf, isSchematic, schematic };