feat: move autoCast getters to separate functions

Every type used to have a `.autoCast` and `.autoCastAll` getter that returns a clone of the type with autocast parsers added. This PR changes that to be separate functions with the same name. This helps with future changes, because maintaining getters that return the `this` types is becoming increasingly hard.

BREAKING CHANGE: The getters `.autoCast` and `.autoCastAll` are removed and moved to separately exported functions.

Author: pavadeli

src/autocast.test.ts

@@ -1,21 +1,22 @@
+import { autoCast } from './autocast';
 import { int, number, string } from './types';
 
 test('autoCast should not override existing parsers', () => {
     const HourOfDay = int.withConstraint('HourOfDay', n => 0 <= n && n < 24).withParser(number.andThen(n => n % 24));
 
     const hour = HourOfDay(34);
-    const afterAutoCast = HourOfDay.autoCast(34);
+    const afterAutoCast = autoCast(HourOfDay)(34);
 
     expect(hour).toBe(10);
     expect(afterAutoCast).toBe(10);
 
     // Currently, types with parsers get no benefit from autoCast, because we don't know whether to apply the autoCast before or after the
     // custom parser.
     expect(() => HourOfDay('34')).toThrow('error in parser precondition of [HourOfDay]: expected a number, got a string ("34")');
-    expect(() => HourOfDay.autoCast('34')).toThrow('error in parser precondition of [HourOfDay]: expected a number, got a string ("34")');
+    expect(() => autoCast(HourOfDay)('34')).toThrow('error in parser precondition of [HourOfDay]: expected a number, got a string ("34")');
 });
 
 test('autoCast instances should not leak', () => {
     const SmallString = string.withConstraint('SmallString', s => s.length < 10);
-    expect(string.autoCast).not.toBe(SmallString.autoCast);
+    expect(autoCast(string)).not.toBe(autoCast(SmallString));
 });

src/autocast.ts

@@ -0,0 +1,46 @@
+import { BaseTypeImpl, createType } from './base-type';
+import { autoCastFailure } from './symbols';
+import { bracketsIfNeeded, printValue } from './utils';
+
+/**
+ * Returns the same type, but with an auto-casting default parser installed.
+ *
+ * @remarks
+ * Each type implementation provides its own auto-cast rules. See builtin types for examples of auto-cast rules.
+ */
+export function autoCast<T extends BaseTypeImpl<unknown>>(type: T): T {
+    const autoCaster = type['autoCaster'];
+    const typeParser = type['typeParser'];
+    if (!autoCaster || typeParser) return type;
+    return (type['_instanceCache'].autoCast ??= createType(type, {
+        name: { configurable: true, value: `AutoCast<${bracketsIfNeeded(type.name, '&', '|')}>` },
+        typeParser: { configurable: true, value: createAutoCastParser(autoCaster) },
+    })) as T;
+}
+
+/**
+ * Create a recursive autocasting version of the given type.
+ *
+ * @remarks
+ * This will replace any parser in the nested structure with the appropriate autocaster when applicable.
+ */
+export function autoCastAll<T extends BaseTypeImpl<unknown>>(type: T): T {
+    return (type['_instanceCache'].autoCastAll ??= type['createAutoCastAllType']()) as T;
+}
+
+function createAutoCastParser<ResultType, TypeConfig>(
+    autoCaster: (this: BaseTypeImpl<ResultType, TypeConfig>, value: unknown) => unknown,
+): BaseTypeImpl<ResultType, TypeConfig>['typeParser'] {
+    return function (this: BaseTypeImpl<ResultType, TypeConfig>, input) {
+        const autoCastResult = autoCaster.call(this, input);
+        return this.createResult(
+            input,
+            autoCastResult,
+            autoCastResult !== autoCastFailure || {
+                kind: 'custom message',
+                message: `could not autocast value: ${printValue(input)}`,
+                omitInput: true,
+            },
+        );
+    };
+}

src/base-type.ts

@@ -1,3 +1,4 @@
+import { autoCast } from './autocast';
 import type {
     BasicType,
     Branded,
@@ -23,18 +24,16 @@ import type {
     Validator,
     Visitor,
 } from './interfaces';
-import { autoCastFailure, designType } from './symbols';
+import { designType } from './symbols';
 import {
     addParserInputToResult,
     an,
     basicType,
-    bracketsIfNeeded,
     castArray,
     decodeOptionalOptions,
     defaultStringify,
     isOneOrMore,
     prependContextToDetails,
-    printValue,
 } from './utils';
 import { ValidationError } from './validation-error';
 
@@ -122,34 +121,8 @@ export abstract class BaseTypeImpl<ResultType, TypeConfig = unknown> implements
         boundIs?: BaseTypeImpl<ResultType, TypeConfig>['is'];
     } = {};
 
-    /**
-     * The same type, but with an auto-casting default parser installed.
-     *
-     * @remarks
-     * Each type implementation provides its own auto-cast rules. See builtin types for examples of auto-cast rules.
-     */
-    get autoCast(): this {
-        // eslint-disable-next-line @typescript-eslint/unbound-method
-        const { autoCaster, typeParser } = this;
-        if (!autoCaster || typeParser) return this;
-        return (this._instanceCache.autoCast ??= createType(this, {
-            name: { configurable: true, value: `${bracketsIfNeeded(this.name)}.autoCast` },
-            typeParser: { configurable: true, value: createAutoCastParser(autoCaster) },
-        })) as this;
-    }
-
-    /**
-     * Create a recursive autocasting version of the current type.
-     *
-     * @remarks
-     * This will replace any parser in the nested structure with the appropriate autocaster when applicable.
-     */
-    get autoCastAll(): this {
-        return (this._instanceCache.autoCastAll ??= this.createAutoCastAllType()) as this;
-    }
-
-    protected createAutoCastAllType(): this {
-        return this.autoCast;
+    protected createAutoCastAllType(): Type<ResultType> {
+        return autoCast(this as unknown as Type<ResultType>);
     }
 
     /**
@@ -611,20 +584,3 @@ function getVisitedMap<ResultType>(me: BaseTypeImpl<ResultType, any>, options: V
     }
     return valueMap as Map<unknown, Result<ResultType>>;
 }
-
-function createAutoCastParser<ResultType, TypeConfig>(
-    autoCaster: (this: BaseTypeImpl<ResultType, TypeConfig>, value: unknown) => unknown,
-): BaseTypeImpl<ResultType, TypeConfig>['typeParser'] {
-    return function (this: BaseTypeImpl<ResultType, TypeConfig>, input) {
-        const autoCastResult = autoCaster.call(this, input);
-        return this.createResult(
-            input,
-            autoCastResult,
-            autoCastResult !== autoCastFailure || {
-                kind: 'custom message',
-                message: `could not autocast value: ${printValue(input)}`,
-                omitInput: true,
-            },
-        );
-    };
-}

src/index.ts

@@ -1,3 +1,4 @@
+export * from './autocast';
 export * from './base-type';
 export * from './error-reporter';
 export * from './interfaces';

src/simple-type.test.ts

@@ -1,3 +1,4 @@
+import { autoCast } from './autocast';
 import type { The } from './interfaces';
 import { SimpleType } from './simple-type';
 import { createExample } from './testutils';
@@ -37,7 +38,7 @@ describe(SimpleType, () => {
         expect(BufferType(buffer)).toBe(buffer);
         expect(() => BufferType([])).toThrow(`expected a [Buffer], got: []`);
         expect(() => BufferType(Uint8Array.of(1, 2, 3))).toThrow(`expected a [Buffer], got: "1,2,3"`);
-        expect(BufferType.autoCast(Uint8Array.of(1, 2, 3))).toEqual(Buffer.of(1, 2, 3));
+        expect(autoCast(BufferType)(Uint8Array.of(1, 2, 3))).toEqual(Buffer.of(1, 2, 3));
     });
 
     test('has basic support for stringify', () => {

src/types.test.ts

@@ -1,4 +1,5 @@
 /* eslint-disable @typescript-eslint/no-unsafe-return */
+import { autoCast } from './autocast';
 import type { DeepUnbranded, MessageDetails, ObjectType, The, Type, Unbranded, Writable } from './interfaces';
 import {
     assignableTo,
@@ -103,24 +104,24 @@ testTypeImpl({
 });
 
 testTypeImpl({
-    name: 'Age.autoCast',
-    type: Age.autoCast,
+    name: 'AutoCast<Age>',
+    type: autoCast(Age),
     basicType: 'number',
     validValues: [0, 1, Age.MAX],
     invalidValues: [
-        [-1, 'error in [Age.autoCast]: the unborn miracle, got: -1'],
-        [Age.MAX + 1, 'error in [Age.autoCast]: wow, that is really old, got: 200'],
-        [-1.5, ['errors in [Age.autoCast]:', '', '- the unborn miracle, got: -1.5', '', '- expected a whole number, got: -1.5']],
-        [1.5, 'error in [Age.autoCast]: expected a whole number, got: 1.5'],
-        ...defaultUsualSuspects(Age.autoCast),
+        [-1, 'error in [AutoCast<Age>]: the unborn miracle, got: -1'],
+        [Age.MAX + 1, 'error in [AutoCast<Age>]: wow, that is really old, got: 200'],
+        [-1.5, ['errors in [AutoCast<Age>]:', '', '- the unborn miracle, got: -1.5', '', '- expected a whole number, got: -1.5']],
+        [1.5, 'error in [AutoCast<Age>]: expected a whole number, got: 1.5'],
+        ...defaultUsualSuspects(autoCast(Age)),
     ],
     validConversions: [
         [`${Age.MAX}`, Age.MAX],
         ['0', 0],
     ],
     invalidConversions: [
-        ['abc', 'error in parser of [Age.autoCast]: could not autocast value: "abc"'],
-        ['-1', 'error in [Age.autoCast]: the unborn miracle, got: -1, parsed from: "-1"'],
+        ['abc', 'error in parser of [AutoCast<Age>]: could not autocast value: "abc"'],
+        ['-1', 'error in [AutoCast<Age>]: the unborn miracle, got: -1, parsed from: "-1"'],
     ],
 });
 
@@ -589,7 +590,7 @@ testTypeImpl({
 });
 
 const NestedParsers = object('NestedParsers', {
-    outer: object({ inner: object({ value: number.autoCast }) }).withParser(inner => ({ inner })),
+    outer: object({ inner: object({ value: autoCast(number) }) }).withParser(inner => ({ inner })),
 }).withParser(outer => ({ outer }));
 
 testTypeImpl({
@@ -606,7 +607,7 @@ testTypeImpl({
                 // and especially how they are related without bloating the error report.
                 '(got: { outer: {} }, parsed from: {})',
                 '',
-                '- at <outer.inner>: missing property <value> [number.autoCast], got: {}',
+                '- at <outer.inner>: missing property <value> [AutoCast<number>], got: {}',
             ],
         ],
         [
@@ -624,7 +625,7 @@ testTypeImpl({
 });
 
 type ReplacedAutocastParser = The<typeof ReplacedAutocastParser>;
-const ReplacedAutocastParser = number.autoCast.withParser({ name: 'ReplacedAutocastParser', chain: false }, input => input);
+const ReplacedAutocastParser = autoCast(number).withParser({ name: 'ReplacedAutocastParser', chain: false }, input => input);
 
 testTypeImpl({
     name: 'ReplacedAutocastParser',
@@ -635,7 +636,7 @@ testTypeImpl({
 });
 
 type ChainedAutocastParser = The<typeof ChainedAutocastParser>;
-const ChainedAutocastParser = number.autoCast.withParser({ name: 'ChainedAutocastParser', chain: true }, input => input);
+const ChainedAutocastParser = autoCast(number).withParser({ name: 'ChainedAutocastParser', chain: true }, input => input);
 
 testTypeImpl({
     name: 'ChainedAutocastParser',

src/types/array.test.ts

@@ -1,3 +1,4 @@
+import { autoCast, autoCastAll } from '../autocast';
 import type { The } from '../interfaces';
 import { assignableTo, createExample, defaultUsualSuspects, testTypeImpl, testTypes } from '../testutils';
 import { array } from './array';
@@ -32,18 +33,18 @@ testTypeImpl({
 });
 
 testTypeImpl({
-    name: 'string[].autoCast',
-    type: array(string).autoCast,
+    name: 'AutoCast<string[]>',
+    type: autoCast(array(string)),
     basicType: 'array',
     // wrap arrays inside extra array because of the use of jest.each in testTypeImpl
     validValues: [[['a', 'b', 'bla']], [[]]],
     invalidValues: [
-        ['a', 'error in [string[].autoCast]: expected an array, got a string ("a")'],
-        [{ 0: 'a', length: 1 }, 'error in [string[].autoCast]: expected an array, got an object ({ "0": "a", length: 1 })'],
+        ['a', 'error in [AutoCast<string[]>]: expected an array, got a string ("a")'],
+        [{ 0: 'a', length: 1 }, 'error in [AutoCast<string[]>]: expected an array, got an object ({ "0": "a", length: 1 })'],
         [
             [1, 2, 3],
             [
-                'errors in [string[].autoCast]:',
+                'errors in [AutoCast<string[]>]:',
                 '',
                 '- at <[0]>: expected a string, got a number (1)',
                 '',
@@ -58,43 +59,43 @@ testTypeImpl({
         ['str', ['str']],
     ],
     invalidConversions: [
-        [1, ['errors in [string[].autoCast]:', '(got: [1], parsed from: 1)', '', '- at <[0]>: expected a string, got a number (1)']],
+        [1, ['errors in [AutoCast<string[]>]:', '(got: [1], parsed from: 1)', '', '- at <[0]>: expected a string, got a number (1)']],
     ],
 });
 
 testTypeImpl({
-    name: 'Array<number.autoCast>',
-    type: array(number.autoCast),
+    name: 'Array<AutoCast<number>>',
+    type: array(autoCast(number)),
     basicType: 'array',
     // wrap arrays inside extra array because of the use of jest.each in testTypeImpl
     validValues: [[[1, 2, 3]], [[]]],
     invalidValues: [
-        [1, 'error in [Array<number.autoCast>]: expected an array, got a number (1)'],
-        [{ 0: 0 }, 'error in [Array<number.autoCast>]: expected an array, got an object ({ "0": 0 })'],
-        [['1'], 'error in [Array<number.autoCast>] at <[0]>: expected a number, got a string ("1")'],
-        ...defaultUsualSuspects(array(number.autoCast)),
+        [1, 'error in [Array<AutoCast<number>>]: expected an array, got a number (1)'],
+        [{ 0: 0 }, 'error in [Array<AutoCast<number>>]: expected an array, got an object ({ "0": 0 })'],
+        [['1'], 'error in [Array<AutoCast<number>>] at <[0]>: expected a number, got a string ("1")'],
+        ...defaultUsualSuspects(array(autoCast(number))),
     ],
     validConversions: [
         [
             ['1', '2', '3'],
             [1, 2, 3],
         ],
     ],
-    invalidConversions: [[1, 'error in [Array<number.autoCast>]: expected an array, got a number (1)']],
+    invalidConversions: [[1, 'error in [Array<AutoCast<number>>]: expected an array, got a number (1)']],
 });
 
 testTypeImpl({
-    name: 'Array<number.autoCast>.autoCast',
-    type: array(number).autoCastAll,
+    name: 'AutoCast<Array<AutoCast<number>>>',
+    type: autoCastAll(array(number)),
     basicType: 'array',
     // wrap arrays inside extra array because of the use of jest.each in testTypeImpl
     validValues: [[[1, 2, 3]], [[]]],
     validConversions: [['1', [1]]],
 });
 
 testTypeImpl({
-    name: '(custom name).autoCast',
-    type: array('custom name', number).autoCastAll,
+    name: 'AutoCast<(custom name)>',
+    type: autoCastAll(array('custom name', number)),
 });
 
 type SmallArray = The<typeof SmallArray>;

src/types/array.ts

@@ -1,3 +1,4 @@
+import { autoCast, autoCastAll } from '../autocast';
 import { BaseTypeImpl, createType } from '../base-type';
 import type { ArrayTypeConfig, Result, TypeImpl, TypeOf, ValidationOptions, Visitor } from '../interfaces';
 import {
@@ -90,7 +91,7 @@ define(ArrayType, 'basicType', 'array');
 // Defined outside class definition, because TypeScript somehow ends up in a wild-typings-goose-chase that takes
 // up to a minute or more. We have to make sure consuming libs don't have to pay this penalty ever.
 define(ArrayType, 'createAutoCastAllType', function (this: ArrayType<BaseTypeImpl<any>, any, any[]>) {
-    return createType(new ArrayType(this.elementType.autoCastAll, this.typeConfig, this.isDefaultName ? undefined : this.name).autoCast);
+    return createType(autoCast(new ArrayType(autoCastAll(this.elementType), this.typeConfig, this.isDefaultName ? undefined : this.name)));
 });
 
 /**

src/types/boolean.test.ts

@@ -1,3 +1,4 @@
+import { autoCast, autoCastAll } from '../autocast';
 import { basicTypeMessage, testTypeImpl } from '../testutils';
 import { boolean } from './boolean';
 
@@ -19,17 +20,17 @@ testTypeImpl({
 });
 
 testTypeImpl({
-    name: 'boolean.autoCast',
-    type: boolean.autoCast,
+    name: 'AutoCast<boolean>',
+    type: autoCast(boolean),
     basicType: 'boolean',
     validValues: [true, false],
     invalidValues: [
-        ['false', basicTypeMessage(boolean.autoCast, 'false')],
-        [NaN, basicTypeMessage(boolean.autoCast, NaN)],
-        [null, basicTypeMessage(boolean.autoCast, null)],
-        [undefined, basicTypeMessage(boolean.autoCast, undefined)],
-        [0, basicTypeMessage(boolean.autoCast, 0)],
-        [1, basicTypeMessage(boolean.autoCast, 1)],
+        ['false', basicTypeMessage(autoCast(boolean), 'false')],
+        [NaN, basicTypeMessage(autoCast(boolean), NaN)],
+        [null, basicTypeMessage(autoCast(boolean), null)],
+        [undefined, basicTypeMessage(autoCast(boolean), undefined)],
+        [0, basicTypeMessage(autoCast(boolean), 0)],
+        [1, basicTypeMessage(autoCast(boolean), 1)],
     ],
     validConversions: [
         ['false', false],
@@ -40,12 +41,12 @@ testTypeImpl({
         [1, true],
     ],
     invalidConversions: [
-        [NaN, 'error in parser of [boolean.autoCast]: could not autocast value: NaN'],
-        [null, 'error in parser of [boolean.autoCast]: could not autocast value: null'],
-        [undefined, 'error in parser of [boolean.autoCast]: could not autocast value: undefined'],
+        [NaN, 'error in parser of [AutoCast<boolean>]: could not autocast value: NaN'],
+        [null, 'error in parser of [AutoCast<boolean>]: could not autocast value: null'],
+        [undefined, 'error in parser of [AutoCast<boolean>]: could not autocast value: undefined'],
     ],
 });
 
 test('no autoCastAll', () => {
-    expect(boolean.autoCastAll).toBe(boolean.autoCast);
+    expect(autoCastAll(boolean)).toBe(autoCast(boolean));
 });