chore: prep work for toggling coercion

Author: jquense

README.md

@@ -603,15 +603,35 @@ Overrides the key name which is used in error messages.
 Adds to a metadata object, useful for storing data with a schema, that doesn't belong
 the cast object itself.
 
-#### `Schema.describe(): SchemaDescription`
+#### `Schema.describe(options?: ResolveOptions): SchemaDescription`
 
 Collects schema details (like meta, labels, and active tests) into a serializable
 description object.
 
 ```ts
-const description = object({
+const schema = object({
   name: string().required(),
 });
+
+const description = schema.describe();
+```
+
+For schema with dynamic components (references, lazy, or conditions), describe requires
+more context to accurately return the schema description. In these cases provide `options`
+
+```ts
+import { ref, object, string, boolean } from 'yup';
+
+let schema = object({
+  isBig: boolean(),
+  count: number().when('isBig', {
+    is: true,
+    then: (schema) => schema.min(5),
+    otherwise: (schema) => schema.min(0),
+  }),
+});
+
+schema.describe({ value: { isBig: true } });
 ```
 
 And below is are the description types, which differ a bit depending on the schema type.
@@ -778,6 +798,10 @@ interface CastOptions<TContext extends {}> {
   // Remove undefined properties from objects
   stripUnknown: boolean = false;
 
+  // Throws a TypeError if casting doesn't produce a valid type
+  // note that the TS return type is inaccurate when this is `false`, use with caution
+  assert?: boolean = true;
+
   // External values that used to resolve conditions and references
   context?: TContext;
 }
@@ -988,10 +1012,12 @@ let schema = object({
   count: number()
     .when('isBig', {
       is: true, // alternatively: (val) => val == true
-      then: (schema) => schema..min(5),
-      otherwise: (schema) => schema..min(0),
+      then: (schema) => schema.min(5),
+      otherwise: (schema) => schema.min(0),
     })
-    .when('$other', ([other], schema) => (other === 4 ? schema.max(6) : schema)),
+    .when('$other', ([other], schema) =>
+      other === 4 ? schema.max(6) : schema,
+    ),
 });
 
 await schema.validate(value, { context: { other: 4 } });

src/array.ts

@@ -21,6 +21,7 @@ import {
   ToggleDefault,
   ISchema,
   UnsetFlag,
+  Concat,
 } from './util/types';
 import Schema, { SchemaInnerTypeDescription, SchemaSpec } from './schema';
 import { ResolveOptions } from './Condition';
@@ -59,15 +60,17 @@ export default class ArraySchema<
     this.innerType = type;
 
     this.withMutation(() => {
-      this.transform(function (values) {
-        if (typeof values === 'string')
+      this.transform((values, _, ctx) => {
+        if (!ctx.spec.coarce) return values;
+        if (typeof values === 'string') {
           try {
             values = JSON.parse(values);
           } catch (err) {
             values = null;
           }
+        }
 
-        return this.isType(values) ? values : null;
+        return ctx.isType(values) ? values : null;
       });
     });
   }
@@ -167,8 +170,16 @@ export default class ArraySchema<
     return next;
   }
 
-  concat<TOther extends ArraySchema<any, any, any>>(schema: TOther): TOther;
-  concat(schema: any): any;
+  concat<IT, IC, ID, IF extends Flags, IIn extends Maybe<IT[]>>(
+    schema: ArraySchema<IT, IC, ID, IF, IIn>,
+  ): ArraySchema<
+    Concat<T, IT>,
+    TContext & IC,
+    Extract<IF, 'd'> extends never ? TDefault : ID,
+    TFlags | IF,
+    Concat<TIn, IIn>
+  >;
+  concat(schema: this): this;
   concat(schema: any): any {
     let next = super.concat(schema) as this;
 
@@ -294,17 +305,6 @@ export default interface ArraySchema<
     def: Thunk<D>,
   ): ArraySchema<T, TContext, D, ToggleDefault<TFlags, D>, TIn>;
 
-  concat<IT, IC, ID, IF extends Flags, IIn extends Maybe<IT[]>>(
-    schema: ArraySchema<IT, IC, ID, IF, IIn>,
-  ): ArraySchema<
-    NonNullable<T> | IT,
-    TContext & IC,
-    Extract<IF, 'd'> extends never ? TDefault : ID,
-    TFlags | IF,
-    IIn
-  >;
-  concat(schema: this): this;
-
   defined(
     msg?: Message,
   ): ArraySchema<T, TContext, TDefault, TFlags, Defined<TIn>>;

src/boolean.ts

@@ -38,8 +38,8 @@ export default class BooleanSchema<
     });
 
     this.withMutation(() => {
-      this.transform(function (value) {
-        if (!this.isType(value)) {
+      this.transform((value, _raw, ctx) => {
+        if (ctx.spec.coarce && !ctx.isType(value)) {
           if (/^(true|1)$/i.test(String(value))) return true;
           if (/^(false|0)$/i.test(String(value))) return false;
         }

src/date.ts

@@ -46,8 +46,8 @@ export default class DateSchema<
     });
 
     this.withMutation(() => {
-      this.transform(function (value) {
-        if (this.isType(value)) return value;
+      this.transform((value, _raw, ctx) => {
+        if (!ctx.spec.coarce || ctx.isType(value)) return value;
 
         value = isoParse(value);
 

src/number.ts

@@ -42,17 +42,18 @@ export default class NumberSchema<
     });
 
     this.withMutation(() => {
-      this.transform(function (value) {
-        let parsed = value;
+      this.transform((value, _raw, ctx) => {
+        if (!ctx.spec.coarce) return value;
 
+        let parsed = value;
         if (typeof parsed === 'string') {
           parsed = parsed.replace(/\s/g, '');
           if (parsed === '') return NaN;
           // don't use parseFloat to avoid positives on alpha-numeric strings
           parsed = +parsed;
         }
 
-        if (this.isType(parsed)) return parsed;
+        if (ctx.isType(parsed)) return parsed;
 
         return parseFloat(parsed);
       });

src/object.ts

@@ -124,15 +124,15 @@ export default class ObjectSchema<
     });
 
     this.withMutation(() => {
-      this.transform(function coerce(value) {
+      this.transform((value, _raw, ctx) => {
         if (typeof value === 'string') {
           try {
             value = JSON.parse(value);
           } catch (err) {
             value = null;
           }
         }
-        if (this.isType(value)) return value;
+        if (ctx.isType(value)) return value;
         return null;
       });
 

src/schema.ts

@@ -35,6 +35,7 @@ import type { Flags, ISchema, ResolveFlags, Thunk, _ } from './util/types';
 import toArray from './util/toArray';
 
 export type SchemaSpec<TDefault> = {
+  coarce: boolean;
   nullable: boolean;
   optional: boolean;
   default?: TDefault | (() => TDefault);
@@ -157,6 +158,7 @@ export default abstract class Schema<
       recursive: true,
       nullable: false,
       optional: true,
+      coarce: true,
       ...options?.spec,
     };
 

src/string.ts

@@ -59,19 +59,21 @@ export default class StringSchema<
       type: 'string',
       check(value): value is NonNullable<TType> {
         if (value instanceof String) value = value.valueOf();
-
         return typeof value === 'string';
       },
     });
 
     this.withMutation(() => {
-      this.transform(function (value) {
-        if (this.isType(value)) return value;
+      this.transform((value, _raw, ctx) => {
+        if (!ctx.spec.coarce || ctx.isType(value)) return value;
+
+        // don't ever convert arrays
         if (Array.isArray(value)) return value;
 
         const strValue =
           value != null && value.toString ? value.toString() : value;
 
+        // no one wants plain objects converted to [Object object]
         if (strValue === objStringTag) return value;
 
         return strValue;