Fix ability to get multiple failures (ianstormtaylor#394) (ianstormtaylor#440)

* Test for multiple failures (with minimal changes to tests)

* Do not attempt to iterate on `Generator`s more than once, fixes ianstormtaylor#394

* Refine public types: StructError.failures & StructContext.check

* Update documentation regarding StructError.failures

* Clean up tests: Have all fixtures export `failures` instead of `error`

Co-authored-by: Ian Storm Taylor <[email protected]>

Author: zenflow

docs/reference.md

@@ -546,17 +546,17 @@ The error class that Superstruct uses for its validation errors. This is exposed
 
 Each error thrown includes the following properties:
 
-| **Property** | **Type**                  | **Example**             | **Description**                                                                                                                                                                                                        |
-| ------------ | ------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `branch`     | `Array<any>`              | `[{...}, false]`        | An array of the values being validated at every layer. The first element in the array is the root value, and the last element is the current value that failed. This allows you to inspect the entire validation tree. |
-| `path`       | `Array<string \| number>` | `['address', 'street']` | The path to the invalid value relative to the root value.                                                                                                                                                              |
-| `value`      | `any`                     | `false`                 | The invalid value.                                                                                                                                                                                                     |
-| `type`       | `string`                  | `'string'`              | The expected type of the invalid value.                                                                                                                                                                                |
-| `failures`   | `Array<StructFailure>`    | `[{...}]`               | All the validation failures that were encountered. The error object always represents the first failure, but you can write more complex logic involving other failures if you need to.                                 |
+| **Property** | **Type**                     | **Example**             | **Description**                                                                                                                                                                                                        |
+| ------------ | ---------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `branch`     | `Array<any>`                 | `[{...}, false]`        | An array of the values being validated at every layer. The first element in the array is the root value, and the last element is the current value that failed. This allows you to inspect the entire validation tree. |
+| `path`       | `Array<string \| number>`    | `['address', 'street']` | The path to the invalid value relative to the root value.                                                                                                                                                              |
+| `value`      | `any`                        | `false`                 | The invalid value.                                                                                                                                                                                                     |
+| `type`       | `string`                     | `'string'`              | The expected type of the invalid value.                                                                                                                                                                                |
+| `failures`   | `() => Array<StructFailure>` |                         | A function that returns all the validation failures that were encountered. The error object always represents the first failure, but you can write more complex logic involving other failures if you need to.         |
 
 ### Multiple Errors
 
-The error thrown by Superstruct is always the first validation failure that was encountered, because this makes for convenient and simple logic in the majority of cases. However, the `failures` property is available with a list of all of the validation failures that occurred in case you want to add support for multiple error handling.
+The error thrown by Superstruct is always the first validation failure that was encountered, because this makes for convenient and simple logic in the majority of cases. However, the `failures` method will return a list of all of the validation failures that occurred in case you want to add support for multiple error handling.
 
 ## Utilities
 

src/struct.ts

@@ -1,4 +1,4 @@
-import { toFailures } from './utils'
+import { toFailures, iteratorShift } from './utils'
 
 /**
  * `Struct` objects encapsulate the schema for a specific data type (with
@@ -47,18 +47,24 @@ export class StructError extends TypeError {
   type: string
   path: Array<number | string>
   branch: Array<any>
-  failures: () => Iterable<StructFailure>;
+  failures: () => Array<StructFailure>;
   [key: string]: any
 
-  constructor(failure: StructFailure, iterable: Iterable<StructFailure>) {
+  constructor(
+    failure: StructFailure,
+    moreFailures: IterableIterator<StructFailure>
+  ) {
     const { path, value, type, branch, ...rest } = failure
     const message = `Expected a value of type \`${type}\`${
       path.length ? ` for \`${path.join('.')}\`` : ''
     } but received \`${JSON.stringify(value)}\`.`
 
-    function* failures(): Iterable<StructFailure> {
-      yield failure
-      yield* iterable
+    let failuresResult: Array<StructFailure> | undefined
+    function failures(): Array<StructFailure> {
+      if (!failuresResult) {
+        failuresResult = [failure, ...moreFailures]
+      }
+      return failuresResult
     }
 
     super(message)
@@ -89,7 +95,7 @@ export type StructContext = {
     struct: Struct<any> | Struct<never>,
     parent?: any,
     key?: string | number
-  ) => Iterable<StructFailure>
+  ) => IterableIterator<StructFailure>
 }
 
 /**
@@ -163,11 +169,11 @@ export function validate<T>(
     value = struct.coercer(value)
   }
 
-  const iterable = check(value, struct)
-  const [failure] = iterable
+  const failures = check(value, struct)
+  const failure = iteratorShift(failures)
 
   if (failure) {
-    const error = new StructError(failure, iterable)
+    const error = new StructError(failure, failures)
     return [error, undefined]
   } else {
     return [undefined, value as T]
@@ -183,7 +189,7 @@ function* check<T>(
   struct: Struct<T>,
   path: any[] = [],
   branch: any[] = []
-): Iterable<StructFailure> {
+): IterableIterator<StructFailure> {
   const { type } = struct
   const ctx: StructContext = {
     value,
@@ -201,7 +207,7 @@ function* check<T>(
   }
 
   const failures = toFailures(struct.validator(value, ctx), ctx)
-  const [failure] = failures
+  const failure = iteratorShift(failures)
 
   if (failure) {
     yield failure

src/utils.ts

@@ -7,15 +7,25 @@ export type StructTuple<T> = { [K in keyof T]: Struct<T[K]> }
  * Convert a validation result to an iterable of failures.
  */
 
-export function toFailures(
+export function* toFailures(
   result: StructResult,
   context: StructContext
-): Iterable<StructFailure> {
+): IterableIterator<StructFailure> {
   if (result === true) {
-    return []
+    // yield nothing
   } else if (result === false) {
-    return [context.fail()]
+    yield context.fail()
   } else {
-    return result
+    yield* result
   }
 }
+
+/**
+ * Shifts (removes and returns) the first value from the `input` iterator.
+ * Like `Array.prototype.shift()` but for an `Iterator`.
+ */
+
+export function iteratorShift<T>(input: Iterator<T>): T | undefined {
+  const { done, value } = input.next()
+  return done ? undefined : value
+}

test/fixtures/array/invalid-element-property.ts

@@ -4,9 +4,11 @@ export const Struct = array(object({ id: string() }))
 
 export const data = [{ id: '1' }, { id: false }, { id: '3' }]
 
-export const error = {
-  value: false,
-  type: 'string',
-  path: [1, 'id'],
-  branch: [data, data[1], data[1].id],
-}
+export const failures = [
+  {
+    value: false,
+    type: 'string',
+    path: [1, 'id'],
+    branch: [data, data[1], data[1].id],
+  },
+]

test/fixtures/array/invalid-element.ts

@@ -4,9 +4,11 @@ export const Struct = array(number())
 
 export const data = [1, 'invalid', 3]
 
-export const error = {
-  value: 'invalid',
-  type: 'number',
-  path: [1],
-  branch: [data, data[1]],
-}
+export const failures = [
+  {
+    value: 'invalid',
+    type: 'number',
+    path: [1],
+    branch: [data, data[1]],
+  },
+]

test/fixtures/array/invalid-opaque.ts

@@ -4,9 +4,11 @@ export const Struct = array()
 
 export const data = 'invalid'
 
-export const error = {
-  value: 'invalid',
-  type: 'Array<unknown>',
-  path: [],
-  branch: [data],
-}
+export const failures = [
+  {
+    value: 'invalid',
+    type: 'Array<unknown>',
+    path: [],
+    branch: [data],
+  },
+]

test/fixtures/array/invalid.ts

@@ -4,9 +4,11 @@ export const Struct = array(number())
 
 export const data = 'invalid'
 
-export const error = {
-  value: 'invalid',
-  type: 'Array<number>',
-  path: [],
-  branch: [data],
-}
+export const failures = [
+  {
+    value: 'invalid',
+    type: 'Array<number>',
+    path: [],
+    branch: [data],
+  },
+]

test/fixtures/boolean/invalid.ts

@@ -4,9 +4,11 @@ export const Struct = boolean()
 
 export const data = 'invalid'
 
-export const error = {
-  value: 'invalid',
-  type: 'boolean',
-  path: [],
-  branch: [data],
-}
+export const failures = [
+  {
+    value: 'invalid',
+    type: 'boolean',
+    path: [],
+    branch: [data],
+  },
+]

test/fixtures/date/invalid-date.ts

@@ -4,9 +4,11 @@ export const Struct = date()
 
 export const data = new Date('invalid')
 
-export const error = {
-  value: data,
-  type: 'Date',
-  path: [],
-  branch: [data],
-}
+export const failures = [
+  {
+    value: data,
+    type: 'Date',
+    path: [],
+    branch: [data],
+  },
+]

test/fixtures/date/invalid.ts

@@ -4,9 +4,11 @@ export const Struct = date()
 
 export const data = 'invalid'
 
-export const error = {
-  value: 'invalid',
-  type: 'Date',
-  path: [],
-  branch: [data],
-}
+export const failures = [
+  {
+    value: 'invalid',
+    type: 'Date',
+    path: [],
+    branch: [data],
+  },
+]

test/fixtures/dynamic/invalid-reference.ts

@@ -29,9 +29,11 @@ export const data = {
   price: 'Only $19.99!',
 }
 
-export const error = {
-  value: 'Only $19.99!',
-  type: 'number',
-  path: ['price'],
-  branch: [data, data.price],
-}
+export const failures = [
+  {
+    value: 'Only $19.99!',
+    type: 'number',
+    path: ['price'],
+    branch: [data, data.price],
+  },
+]

test/fixtures/dynamic/invalid.ts

@@ -4,9 +4,11 @@ export const Struct = dynamic(() => string())
 
 export const data = 3
 
-export const error = {
-  value: 3,
-  type: 'string',
-  path: [],
-  branch: [data],
-}
+export const failures = [
+  {
+    value: 3,
+    type: 'string',
+    path: [],
+    branch: [data],
+  },
+]

test/fixtures/empty/invalid-array.ts

@@ -4,9 +4,11 @@ export const Struct = empty(array())
 
 export const data = ['invalid']
 
-export const error = {
-  value: ['invalid'],
-  type: 'Array<unknown> & Empty',
-  path: [],
-  branch: [data],
-}
+export const failures = [
+  {
+    value: ['invalid'],
+    type: 'Array<unknown> & Empty',
+    path: [],
+    branch: [data],
+  },
+]

test/fixtures/empty/invalid-string.ts

@@ -4,9 +4,11 @@ export const Struct = empty(string())
 
 export const data = 'invalid'
 
-export const error = {
-  value: 'invalid',
-  type: 'string & Empty',
-  path: [],
-  branch: [data],
-}
+export const failures = [
+  {
+    value: 'invalid',
+    type: 'string & Empty',
+    path: [],
+    branch: [data],
+  },
+]

test/fixtures/enums/invalid-numbers.ts

@@ -4,9 +4,11 @@ export const Struct = enums([1, 2])
 
 export const data = 'invalid'
 
-export const error = {
-  value: 'invalid',
-  type: 'Enum<1,2>',
-  path: [],
-  branch: [data],
-}
+export const failures = [
+  {
+    value: 'invalid',
+    type: 'Enum<1,2>',
+    path: [],
+    branch: [data],
+  },
+]

test/fixtures/enums/invalid-strings.ts

@@ -4,9 +4,11 @@ export const Struct = enums(['one', 'two'])
 
 export const data = 'invalid'
 
-export const error = {
-  value: 'invalid',
-  type: 'Enum<"one","two">',
-  path: [],
-  branch: [data],
-}
+export const failures = [
+  {
+    value: 'invalid',
+    type: 'Enum<"one","two">',
+    path: [],
+    branch: [data],
+  },
+]

test/fixtures/function/invalid.ts

@@ -4,9 +4,11 @@ export const Struct = func()
 
 export const data = false
 
-export const error = {
-  value: false,
-  type: 'Function',
-  path: [],
-  branch: [data],
-}
+export const failures = [
+  {
+    value: false,
+    type: 'Function',
+    path: [],
+    branch: [data],
+  },
+]