feat(validation): change default assert strategy

to fail fast

Author: TomokiMiyauci

README.md

@@ -180,12 +180,15 @@ Throws an error in the following cases:
 
 ## assert
 
+Assert that the input passes validator.
+
 ```ts
 import {
   assert,
   number,
   object,
   string,
+  ValidationError,
 } from "https://deno.land/x/abstruct@$VERSION/mod.ts";
 import {
   assertEquals,
@@ -197,94 +200,85 @@ const Profile = object({ name: string, age: number });
 try {
   assert(Profile, { name: null, age: null });
 } catch (e) {
-  assertIsError(e, AggregateError);
-  assertEquals(e.errors.length, 2);
+  assertIsError(e, ValidationError, "<string validation message>");
 }
 ```
 
-### validation
+The default behavior of `assert` is fail fast. That is, it stops working as soon
+as it finds a validation failure.
 
-Validation error configs.
+`assert` provides flexible options, allowing the following customizations.
 
-#### error
+- Error instance
+- Fail slow mode
+  - Limit number of failures
 
-Error constructor.
+### Validation error
 
-The default is `ValidationError`.
+There is a setting for validation error under the `validation` property.
 
-The example of specify validation error as:
+The following elements of this instance can be customized:
 
-```ts
-import { assert, between } from "https://deno.land/x/abstruct@$VERSION/mod.ts";
+- Constructor
+- Error message
+- Error by cause
 
-assert(between(0, 255), 256, {
-  failFast: true,
-  validation: { error: RangeError },
-});
-```
+#### Validation error constructor
 
-#### message
+The default constructor is `ValidationError`.
 
-Error message.
+You may want to throw a web standard error. In this case, you can change the
+constructor in the `error` field.
 
 ```ts
+import { assert, between } from "https://deno.land/x/abstruct@$VERSION/mod.ts";
 import {
-  assert,
-  type Validator,
-} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
-import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
-
-declare const validator: Validator<unknown>;
-declare const input: unknown;
-declare const message: string;
+  assertEquals,
+  assertIsError,
+} from "https://deno.land/std/testing/asserts.ts";
 
 try {
-  assert(validator, input, { failFast: true, validation: { message } });
+  assert(between(0, 255), 256, { validation: { error: RangeError } });
 } catch (e) {
-  assertEquals(e.message, message);
+  assertIsError(e, RangeError);
 }
 ```
 
-#### cause
+This would be especially appropriate for libraries.
 
-Original cause of the error.
+#### Validation default error message
+
+A default error message can be specified, falling back to the default if the
+validator's failure message is empty.
+
+This is usually not necessary since the validator normally reports failure
+messages.
 
 ```ts
 import {
   assert,
+  ValidationError,
   type Validator,
 } from "https://deno.land/x/abstruct@$VERSION/mod.ts";
-import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+import {
+  assertEquals,
+  assertIsError,
+} from "https://deno.land/std/testing/asserts.ts";
 
-declare const validator: Validator<unknown>;
+declare const emptyMsgValidator: Validator;
 declare const input: unknown;
-declare const cause: ErrorConstructor;
+declare const defaultMsg: string;
 
 try {
-  assert(validator, input, { failFast: true, validation: { cause } });
+  assert(emptyMsgValidator, input, { validation: { message: defaultMsg } });
 } catch (e) {
-  assertEquals(e.cause, cause);
+  assertIsError(e, ValidationError, defaultMsg);
 }
 ```
 
-### Lazy vs Greedy
-
-Validation by assert works with lazy or greedy.
-
-Lazy terminates the evaluation as soon as it finds a validation error and
-reports only one validation error.
-
-In contrast, greedy continues validation until the specified number of
-validation errors is reached or all validations are completed.
-
-Also, validator has a lazy evaluation mechanism, so only as many validations are
-performed as needed.
-
-By default, it operates as greedy.
-
-### failFast
+#### Error by cause
 
-If `failFast` is true, it works as lazy.
+Original cause of the error.
 
 ```ts
 import {
@@ -297,103 +291,69 @@ import {
   assertIsError,
 } from "https://deno.land/std/testing/asserts.ts";
 
-declare const Profile: Validator<
-  { name: unknown; age: unknown },
-  { name: string; age: string }
->;
+declare const validator: Validator;
+declare const input: unknown;
+declare const cause: unknown;
 
-try {
-  assert(Profile, { name: null, age: null }, { failFast: true });
-} catch (e) {
-  assertIsError(e, ValidationError);
-}
+assert(validator, input, { validation: { cause } });
 ```
 
-The following fields can only be specified in greedy mode.
-
-### maxFailures option
+### Fail slow
 
-The number of validation failures can be changed with `maxFailures`. For
-details, see [maxFailures](#maxfailures)
+To execute multiple validations, specify `failSlow`. This delays throwing errors
+until the specified number of failures is reached.
 
-### aggregation
-
-Aggregation error configs.
-
-#### error
-
-Specify custom `AggregationErrorConstructor`.
-
-The default is `AggregationError`.
+The error instance will then be `AggregateError` since multiple failures may be
+found.
 
 ```ts
 import {
   assert,
-  type Validator,
+  number,
+  object,
+  string,
 } from "https://deno.land/x/abstruct@$VERSION/mod.ts";
-import { assertIsError } from "https://deno.land/std/testing/asserts.ts";
+import {
+  assertEquals,
+  assertIsError,
+} from "https://deno.land/std/testing/asserts.ts";
 
-declare const validator: Validator<unknown>;
-declare const input: unknown;
-declare const error: AggregateErrorConstructor;
+const Profile = object({ name: string, age: number });
 
 try {
-  assert(validator, input, { aggregation: { error } });
+  assert(Profile, { name: null, age: null }, { failSlow: true });
 } catch (e) {
-  assertIsError(e, error);
+  assertIsError(e, AggregateError);
+  assertEquals(e.errors.length, 2);
 }
 ```
 
-#### message
-
-Customize `AggregationError` message.
-
-```ts
-import {
-  assert,
-  type Validator,
-} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
-import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+#### maxFailures option
 
-declare const validator: Validator<unknown>;
-declare const input: unknown;
-declare const message: string;
+The number of validation failures can be changed with `maxFailures`. For
+details, see [maxFailures](#maxfailures)
 
-try {
-  assert(validator, input, { aggregation: { message } });
-} catch (e) {
-  assertEquals(e.message, message);
-}
-```
+#### aggregation
 
-#### cause
+There is a setting for `AggregateError` under the `aggregation` property.
 
-You can specify `cause` to express the cause of the `AggregationError`.
+The following element can be customized as
+[Validation error](#validation-error).
 
-```ts
-import {
-  assert,
-  type Validator,
-} from "https://deno.land/x/abstruct@$VERSION/mod.ts";
-import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+- [error](#validation-error-constructor)
+- [message](#validation-default-error-message)
+- [cause](#error-by-cause)
 
-declare const validator: Validator<unknown>;
-declare const input: unknown;
-declare const cause: Error;
+The `message` in `AggregateError` is empty by default.
 
-try {
-  assert(validator, input, { aggregation: { cause } });
-} catch (e) {
-  assertEquals(e.cause, cause);
-}
-```
+In fail slow mode, it is recommended to provide it.
 
 ### Throwing error
 
 Throws an error in the following cases:
 
-- `AggregateError`: If assertion is fail.
-- `ValidationError`: If assertion is fail and [failFast](#failfast) is true.
+- `ValidationError`: If assertion is fail.
+- `AggregateError`: If assertion is fail and [failSlow](#fail-slow) is `true`.
 - Same as [validate](#throwing-error).
 
 ## Factories

validation.ts

@@ -40,15 +40,17 @@ export interface AssertOptions {
   /** Validation error configs. */
   validation?: ValidationConfigs;
 
-  /** Whether to perform the assertion fail fast or not.
+  /** Whether to perform the assertion fail slow or not.
+   * - `true`: fail fast
+   * - `false`: fail slow
    * @default false
    */
-  failFast?: boolean;
+  failSlow?: boolean;
 }
 
 /** Lazy assert options. */
 export interface LazyAssertOptions extends AssertOptions {
-  failFast: true;
+  failSlow?: false;
 }
 
 /** Aggregation error configs. */
@@ -58,10 +60,33 @@ export interface GreedyAssertOptions extends AssertOptions, ValidateOptions {
   /** Aggregation error configs. */
   aggregation?: AggregationConfigs;
 
-  failFast?: false;
+  failSlow: true;
 }
 
-/** Assert with validator.
+/** Assert that the input passes validator.
+ *
+ * @example
+ * ```ts
+ * import {
+ *  assert,
+ *  number,
+ *  object,
+ *  string,
+ *  ValidationError,
+ * } from "https://deno.land/x/abstruct@$VERSION/mod.ts";
+ * import {
+ *  assertEquals,
+ *  assertIsError,
+ * } from "https://deno.land/std/testing/asserts.ts";
+ *
+ * const Profile = object({ name: string, age: number });
+ *
+ * try {
+ *  assert(Profile, { name: null, age: null });
+ * } catch (e) {
+ *  assertIsError(e, ValidationError, "<string validation message>");
+ * }
+ * ```
  *
  * @throws {AggregateError} If assertion is fail.
  * @throws {ValidationError} If assertion is fail and {@link options.failFast} is true.
@@ -73,29 +98,29 @@ export function assert<In = unknown, A extends In = In>(
   options: Readonly<LazyAssertOptions | GreedyAssertOptions> = {},
 ): asserts input is A {
   const {
-    failFast,
+    failSlow,
     validation = {},
   } = options;
-  const maxFailures = failFast ? 1 : options.maxFailures;
+  const maxFailures = failSlow ? options.maxFailures : 1;
   const result = validate(validator, input, { maxFailures });
 
   if (result.isOk()) return;
 
-  const ErrorCtor = validation.error ?? ValidationError;
+  const { error: VError = ValidationError } = validation;
 
-  if (failFast) {
-    const failure = result.value[0];
-    const e = failure2Error(failure);
+  if (failSlow) {
+    const errors = result.value.map(failure2Error).map(captured);
+    const { aggregation = {} } = options;
+    const ErrorsCtor = aggregation.error ?? AggregateError;
+    const e = new ErrorsCtor(errors, aggregation.message, {
+      cause: aggregation.cause,
+    });
 
     throw captured(e);
   }
 
-  const errors = result.value.map(failure2Error).map(captured);
-  const { aggregation = {} } = options;
-  const ErrorsCtor = aggregation.error ?? AggregateError;
-  const e = new ErrorsCtor(errors, aggregation.message, {
-    cause: aggregation.cause,
-  });
+  const failure = result.value[0];
+  const e = failure2Error(failure);
 
   throw captured(e);
 
@@ -105,7 +130,7 @@ export function assert<In = unknown, A extends In = In>(
     message = message || (validation.message ?? "");
     const msg = makeMsg({ message, instancePath });
 
-    return new ErrorCtor(msg, { cause: validation.cause, instancePath });
+    return new VError(msg, { cause: validation.cause, instancePath });
   }
 
   // deno-lint-ignore ban-types