feature: return promise from validation only if necessary and validate sync if possible

[lyeq]

Description

The validator has public methods for asynchronous validation (validate and validateOrReject) and for synchronous validation (validateSync).
Unfortunately the synchronous method ignores all async validations while the asynchronous methods always return a pending promise.
It is therefore not possible to write a function which conditionally returns synchronously if possible and a promise if necessary.

Proposed solution

Add a method validateSyncIfPossible to class Validator which returns immediately with ValidationError[] if there are no awaiting promises and otherwise returns with Promise<ValidationError[]>.

  validateSyncIfPossible(
    objectOrSchemaName: object | string,
    objectOrValidationOptions: object | ValidationOptions,
    maybeValidatorOptions?: ValidatorOptions
  ): ValidationError[] | Promise<ValidationError[]> {

    // same as coreValidate and validateSync
    const object = typeof objectOrSchemaName === 'string' ? (objectOrValidationOptions as object) : objectOrSchemaName;
    const options =
      typeof objectOrSchemaName === 'string' ? maybeValidatorOptions : (objectOrValidationOptions as ValidationOptions);
    const schema = typeof objectOrSchemaName === 'string' ? objectOrSchemaName : undefined;

    const executor = new ValidationExecutor(this, options);
    const validationErrors: ValidationError[] = [];
    executor.execute(object, schema, validationErrors);

    // return a promise only if there are awaiting promises; otherwise return synchronously
    return executor.awaitingPromises.length === 0
      ? executor.stripEmptyErrors(validationErrors)
      : Promise.all(executor.awaitingPromises).then(() => executor.stripEmptyErrors(validationErrors));
  }