decorators.ts

import { NoTransformConfigurationError } from "./transformers/NoTransformConfigurationError";

import { IValidation } from "./IValidation";
import { TypeGuardError } from "./TypeGuardError";

/* ===========================================================
  DECORATORS
    - ASSERT
    - IS
    - VALIDATE
==============================================================
  ASSERT
----------------------------------------------------------- */
/**
 * Asserts a method with its parameters.
 *
 * Asserts a method, by wrapping the method and checking its parameters through
 * {@link assert} function. If some parameter does not match the expected type, it
 * throws an {@link TypeGuardError} or a custom error generated by the *errorFactory*
 * parameter.
 *
 * For reference, {@link TypeGuardError.path} would be a little bit different with
 * individual {@link assert} function. If the {@link TypeGuardError} occurs from
 * some parameter, the path would start from `$input.parameters[number]`.
 *
 * This decorator is equivalent to using {@link functional.assertParameters} but
 * works as a TypeScript method decorator for class methods.
 *
 * @param errorFactory Custom error factory. Default is `TypeGuardError`
 * @returns Method decorator
 * @throws A {@link TypeGuardError} or a custom error generated by *errorFactory*
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export function assert(
  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
): MethodDecorator;

/**
 * @internal
 */
export function assert(): never {
  NoTransformConfigurationError("decorators.assert");
}

/**
 * Asserts a method with strict equality of its parameters.
 *
 * Asserts a method, by wrapping the method and checking its parameters through
 * {@link assertEquals} function. If some parameter does not match the expected type,
 * it throws an {@link TypeGuardError} or a custom error generated by the *errorFactory*
 * parameter.
 *
 * For reference, {@link TypeGuardError.path} would be a little bit different with
 * individual {@link assertEquals} function. If the {@link TypeGuardError} occurs from
 * some parameter, the path would start from `$input.parameters[number]`.
 *
 * This decorator is equivalent to using {@link functional.assertEqualsParameters} but
 * works as a TypeScript method decorator for class methods.
 *
 * On the other hand, if you want to allow superfluous properties that are not enrolled
 * to the parameter types, you can use {@link assert} decorator instead.
 *
 * @param errorFactory Custom error factory. Default is `TypeGuardError`
 * @returns Method decorator
 * @throws A {@link TypeGuardError} or a custom error generated by *errorFactory*
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export function assertEquals(
  errorFactory?: undefined | ((props: TypeGuardError.IProps) => Error),
): MethodDecorator;

/**
 * @internal
 */
export function assertEquals(): never {
  NoTransformConfigurationError("decorators.assertEquals");
}

/* -----------------------------------------------------------
  IS
----------------------------------------------------------- */
/**
 * Tests a method's parameters.
 *
 * Tests a method, by wrapping the method and checking its parameters through
 * {@link is} function. If some parameter does not match the expected type, it
 * returns `null`. Otherwise there's no type error, it returns the result of the
 * method.
 *
 * This decorator is equivalent to using {@link functional.isParameters} but
 * works as a TypeScript method decorator for class methods.
 *
 * By the way, if you want is not just testing type checking, but also finding
 * detailed type error reason(s), then use {@link assert} or {@link validate}
 * decorators instead.
 *
 * On the other hand, if you don't want to allow any superfluous properties,
 * utilize {@link equals} decorator instead.
 *
 * @returns Method decorator
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export function is(): MethodDecorator;

/**
 * @internal
 */
export function is(): never {
  NoTransformConfigurationError("decorators.is");
}

/**
 * Tests a method's parameters with strict equality.
 *
 * Tests a method, by wrapping the method and checking its parameters through
 * {@link equals} function. If some parameter does not match the expected type, it
 * returns `null`. Otherwise there's no type error, it returns the result of the
 * method.
 *
 * This decorator is equivalent to using {@link functional.equalsParameters} but
 * works as a TypeScript method decorator for class methods.
 *
 * By the way, if you want is not just testing type checking, but also finding
 * detailed type error reason(s), then use {@link assertEquals} or {@link validateEquals}
 * decorators instead.
 *
 * On the other hand, if you want to allow superfluous properties that are not enrolled
 * to the parameter types, you can use {@link is} decorator instead.
 *
 * @returns Method decorator
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export function equals(): MethodDecorator;

/**
 * @internal
 */
export function equals(): never {
  NoTransformConfigurationError("decorators.equals");
}

/* -----------------------------------------------------------
  VALIDATE
----------------------------------------------------------- */
/**
 * Validates a method's parameters.
 *
 * Validates a method, by wrapping the method and checking its parameters through
 * {@link validate} function. If some parameter does not match the expected type, it
 * returns {@link IValidation.IError} typed object. Otherwise there's no type error, it
 * returns {@link IValidation.ISuccess} typed object instead.
 *
 * For reference, {@link IValidation.IError.path} would be a little bit different with
 * individual {@link validate} function. If the {@link IValidation.IError} occurs from
 * some parameter, the path would start from `$input.parameters[number]`.
 *
 * This decorator is equivalent to using {@link functional.validateParameters} but
 * works as a TypeScript method decorator for class methods.
 *
 * By the way, if what you want is not finding every type errors, but just finding
 * the 1st type error, then use {@link assert} decorator instead. Otherwise, if you
 * just want to know whether the parameters are matched with their types, {@link is}
 * decorator is the way to go.
 *
 * On the other hand, if you don't want to allow any superfluous properties, utilize
 * {@link validateEquals} decorator instead.
 *
 * @returns Method decorator
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export function validate(): MethodDecorator;

/**
 * @internal
 */
export function validate(): never {
  NoTransformConfigurationError("decorators.validate");
}

/**
 * Validates a method's parameters with strict equality.
 *
 * Validates a method, by wrapping the method and checking its parameters through
 * {@link validateEquals} function. If some parameter does not match the expected type, it
 * returns {@link IValidation.IError} typed object. Otherwise there's no type error, it
 * returns {@link IValidation.ISuccess} typed object instead.
 *
 * For reference, {@link IValidation.IError.path} would be a little bit different with
 * individual {@link validateEquals} function. If the {@link IValidation.IError} occurs from
 * some parameter, the path would start from `$input.parameters[number]`.
 *
 * This decorator is equivalent to using {@link functional.validateEqualsParameters} but
 * works as a TypeScript method decorator for class methods.
 *
 * By the way, if what you want is not finding every type errors, but just finding
 * the 1st type error, then use {@link assertEquals} decorator instead. Otherwise, if you
 * just want to know whether the parameters are matched with their types, {@link equals}
 * decorator is the way to go.
 *
 * On the other hand, if you want to allow superfluous properties that are not enrolled
 * to the parameter types, you can use {@link validate} decorator instead.
 *
 * @returns Method decorator
 *
 * @author Jeongho Nam - https://github.com/samchon
 */
export function validateEquals(): MethodDecorator;

/**
 * @internal
 */
export function validateEquals(): never {
  NoTransformConfigurationError("decorators.validateEquals");
}