1.2.0

CHANGELOG.md

@@ -18,3 +18,7 @@
 - assertIsDefined
 - renamed isNullOrUndefined to isNullish
 - renamed assertIsNullOrUndefined to assertIsNullish
+
+## 1.2.0
+
+- added support for custom error messages in type assertions

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tool-belt/type-predicates",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "Collection of performant type-guard utilities",
     "repository": {
         "type": "git",
@@ -43,24 +43,24 @@
     },
     "devDependencies": {
         "@rollup/plugin-typescript": "^8.2.5",
-        "@sprylab/eslint-config": "^1.5.4",
+        "@sprylab/eslint-config": "^1.5.6",
         "@types/jest": "^27.0.1",
         "all-contributors-cli": "^6.20.0",
         "eslint": "^7.32.0",
         "eslint-plugin-tsdoc": "^0.2.14",
         "expect-type": "^0.12.0",
         "husky": ">=7",
-        "jest": "^27.0.6",
+        "jest": "^27.1.0",
         "lint-staged": ">=11",
         "prettier": "^2.3.2",
-        "prettier-plugin-jsdoc": "^0.3.23",
+        "prettier-plugin-jsdoc": "^0.3.24",
         "rimraf": "^3.0.2",
-        "rollup": "^2.56.2",
+        "rollup": "^2.56.3",
         "rollup-plugin-terser": "^7.0.2",
-        "ts-jest": "^27.0.4",
-        "ts-node": "^10.2.0",
-        "typedoc": "^0.21.5",
-        "typescript": "^4.3.5"
+        "ts-jest": "^27.0.5",
+        "ts-node": "^10.2.1",
+        "typedoc": "^0.21.9",
+        "typescript": "^4.4.2"
     },
     "lint-staged": {
         "*.ts": "eslint --fix",

src/assertions/assertIsArray.ts

@@ -1,4 +1,4 @@
-import { ValueValidator } from '../types';
+import { ErrorMessage, ValueValidator } from '../types';
 import { createTypeAssertion } from '../utils';
 import { isArray } from '../guards/isArray';
 
@@ -20,16 +20,24 @@ import { isArray } from '../guards/isArray';
  * @throws TypeError
  */
 export function assertIsArray(input: unknown): asserts input is any[];
+export function assertIsArray(
+    input: unknown,
+    options?: ErrorMessage,
+): asserts input is any[];
 export function assertIsArray<T>(
     input: unknown,
     options: ValueValidator,
 ): asserts input is T[];
 export function assertIsArray<T>(
     input: unknown,
-    options?: ValueValidator,
+    options: ValueValidator & ErrorMessage,
+): asserts input is T[];
+export function assertIsArray<T>(
+    input: unknown,
+    options?: Partial<ValueValidator & ErrorMessage>,
 ): asserts input is T[] {
-    return createTypeAssertion<T[], ValueValidator | undefined>(isArray)(
-        input,
-        options,
-    );
+    return createTypeAssertion<
+        T[],
+        Partial<ValueValidator & ErrorMessage> | undefined
+    >(isArray)(input, options);
 }

src/assertions/assertIsAsyncFunction.ts

@@ -1,4 +1,5 @@
 import { AsyncFunction, isAsyncFunction } from '../guards/isAsyncFunction';
+import { ErrorMessage } from '../types';
 import { createTypeAssertion } from '../utils';
 
 /**
@@ -9,6 +10,10 @@ import { createTypeAssertion } from '../utils';
  */
 export function assertIsAsyncFunction<T = unknown>(
     input: unknown,
+    options?: ErrorMessage,
 ): asserts input is AsyncFunction<T> {
-    return createTypeAssertion<AsyncFunction<T>>(isAsyncFunction)(input);
+    return createTypeAssertion<AsyncFunction<T>>(isAsyncFunction)(
+        input,
+        options,
+    );
 }

src/assertions/assertIsAsyncGenerator.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import { createTypeAssertion } from '../utils';
 import { isAsyncGenerator } from '../guards/isAsyncGenerator';
 
@@ -9,8 +10,10 @@ import { isAsyncGenerator } from '../guards/isAsyncGenerator';
  */
 export function assertIsAsyncGenerator<Y = unknown, R = unknown, N = unknown>(
     input: unknown,
+    options?: ErrorMessage,
 ): asserts input is AsyncGenerator<Y, R, N> {
     return createTypeAssertion<AsyncGenerator<Y, R, N>>(isAsyncGenerator)(
         input,
+        options,
     );
 }

src/assertions/assertIsAsyncGeneratorFunction.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import {
     TypedAsyncGeneratorFunction,
     isAsyncGeneratorFunction,
@@ -12,8 +13,11 @@ export function assertIsAsyncGeneratorFunction<
     Y = unknown,
     R = unknown,
     N = unknown,
->(input: unknown): asserts input is TypedAsyncGeneratorFunction<Y, R, N> {
+>(
+    input: unknown,
+    options?: ErrorMessage,
+): asserts input is TypedAsyncGeneratorFunction<Y, R, N> {
     return createTypeAssertion<TypedAsyncGeneratorFunction<Y, R, N>>(
         isAsyncGeneratorFunction,
-    )(input);
+    )(input, options);
 }

src/assertions/assertIsAsyncIterable.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import { createTypeAssertion } from '../utils';
 import { isAsyncIterable } from '../guards/isAsyncIterable';
 
@@ -10,6 +11,10 @@ import { isAsyncIterable } from '../guards/isAsyncIterable';
  */
 export function assertIsAsyncIterable<T = unknown>(
     input: unknown,
+    options?: ErrorMessage,
 ): asserts input is AsyncIterable<T> {
-    return createTypeAssertion<AsyncIterable<T>>(isAsyncIterable)(input);
+    return createTypeAssertion<AsyncIterable<T>>(isAsyncIterable)(
+        input,
+        options,
+    );
 }

src/assertions/assertIsDefined.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import { isUndefined } from '../guards/isUndefined';
 
 /**
@@ -7,8 +8,11 @@ import { isUndefined } from '../guards/isUndefined';
  * @category Type Assertion
  * @throws TypeError
  */
-export function assertIsDefined<T>(input: T | undefined): asserts input is T {
+export function assertIsDefined<T>(
+    input: T | undefined,
+    options?: ErrorMessage,
+): asserts input is T {
     if (isUndefined(input)) {
-        throw TypeError();
+        throw TypeError(options?.message);
     }
 }

src/assertions/assertIsError.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import { createTypeAssertion } from '../utils';
 import { isError } from '../guards/isError';
 
@@ -23,6 +24,7 @@ import { isError } from '../guards/isError';
  */
 export function assertIsError<T extends Error = Error>(
     input: unknown,
+    options?: ErrorMessage,
 ): asserts input is T {
-    return createTypeAssertion<T>(isError)(input);
+    return createTypeAssertion<T>(isError)(input, options);
 }

src/assertions/assertIsFunction.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import { createTypeAssertion } from '../utils';
 import { isFunction } from '../guards/isFunction';
 
@@ -31,6 +32,7 @@ import { isFunction } from '../guards/isFunction';
  */
 export function assertIsFunction<T extends Function = Function>(
     input: unknown,
+    options?: ErrorMessage,
 ): asserts input is T {
-    return createTypeAssertion<T>(isFunction)(input);
+    return createTypeAssertion<T>(isFunction)(input, options);
 }

src/assertions/assertIsGenerator.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import { createTypeAssertion } from '../utils';
 import { isGenerator } from '../guards/isGenerator';
 
@@ -9,6 +10,7 @@ import { isGenerator } from '../guards/isGenerator';
  */
 export function assertIsGenerator<Y = unknown, R = unknown, N = unknown>(
     input: unknown,
+    options?: ErrorMessage,
 ): asserts input is Generator<Y, R, N> {
-    return createTypeAssertion<Generator<Y, R, N>>(isGenerator)(input);
+    return createTypeAssertion<Generator<Y, R, N>>(isGenerator)(input, options);
 }

src/assertions/assertIsGeneratorFunction.ts

@@ -1,4 +1,4 @@
-import { TypedGeneratorFunction } from '../types';
+import { ErrorMessage, TypedGeneratorFunction } from '../types';
 import { createTypeAssertion } from '../utils';
 import { isGeneratorFunction } from '../guards/isGeneratorFunction';
 
@@ -12,8 +12,11 @@ export function assertIsGeneratorFunction<
     Y = unknown,
     R = unknown,
     N = unknown,
->(input: unknown): asserts input is TypedGeneratorFunction<Y, R, N> {
+>(
+    input: unknown,
+    options?: ErrorMessage,
+): asserts input is TypedGeneratorFunction<Y, R, N> {
     return createTypeAssertion<TypedGeneratorFunction<Y, R, N>>(
         isGeneratorFunction,
-    )(input);
+    )(input, options);
 }

src/assertions/assertIsIterable.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import { createTypeAssertion } from '../utils';
 import { isIterable } from '../guards/isIterable';
 
@@ -11,6 +12,7 @@ import { isIterable } from '../guards/isIterable';
  */
 export function assertIsIterable<T = unknown>(
     input: unknown,
+    options?: ErrorMessage,
 ): asserts input is Iterable<T> {
-    return createTypeAssertion<Iterable<T>>(isIterable)(input);
+    return createTypeAssertion<Iterable<T>>(isIterable)(input, options);
 }

src/assertions/assertIsIterator.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import { createTypeAssertion } from '../utils';
 import { isIterator } from '../guards/isIterator';
 
@@ -9,6 +10,7 @@ import { isIterator } from '../guards/isIterator';
  */
 export function assertIsIterator<Y = unknown, R = unknown, N = unknown>(
     input: unknown,
+    options?: ErrorMessage,
 ): asserts input is Iterator<Y, R, N> {
-    return createTypeAssertion<Iterator<Y, R, N>>(isIterator)(input);
+    return createTypeAssertion<Iterator<Y, R, N>>(isIterator)(input, options);
 }

src/assertions/assertIsMap.ts

@@ -1,4 +1,4 @@
-import { KeyValidator, ValueValidator } from '../types';
+import { ErrorMessage, KeyValidator, ValueValidator } from '../types';
 import { createTypeAssertion } from '../utils';
 import { isMap } from '../guards/isMap';
 
@@ -28,24 +28,40 @@ import { isMap } from '../guards/isMap';
 export function assertIsMap(
     input: unknown,
 ): asserts input is Map<unknown, unknown>;
+export function assertIsMap(
+    input: unknown,
+    options?: ErrorMessage,
+): asserts input is Map<unknown, unknown>;
 export function assertIsMap<K>(
     input: unknown,
     options: KeyValidator,
 ): asserts input is Map<K, unknown>;
+export function assertIsMap<K>(
+    input: unknown,
+    options: KeyValidator & ErrorMessage,
+): asserts input is Map<K, unknown>;
 export function assertIsMap<V>(
     input: unknown,
     options: ValueValidator,
 ): asserts input is Map<string, V>;
+export function assertIsMap<V>(
+    input: unknown,
+    options: ValueValidator & ErrorMessage,
+): asserts input is Map<string, V>;
 export function assertIsMap<K, V>(
     input: unknown,
     options: ValueValidator & KeyValidator,
 ): asserts input is Map<K, V>;
 export function assertIsMap<K, V>(
     input: unknown,
-    options?: Partial<ValueValidator & KeyValidator>,
+    options: ValueValidator & KeyValidator & ErrorMessage,
+): asserts input is Map<K, V>;
+export function assertIsMap<K, V>(
+    input: unknown,
+    options?: Partial<ValueValidator & KeyValidator & ErrorMessage>,
 ): asserts input is Map<K, V> {
     return createTypeAssertion<
         Map<K, V>,
-        undefined | Partial<ValueValidator & KeyValidator>
+        Partial<ValueValidator & KeyValidator & ErrorMessage> | undefined
     >(isMap)(input, options);
 }

src/assertions/assertIsNotNull.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import { isNull } from '../guards/isNull';
 
 /**
@@ -7,8 +8,11 @@ import { isNull } from '../guards/isNull';
  * @category Type Assertion
  * @throws TypeError
  */
-export function assertIsNotNull<T>(input: T | null): asserts input is T {
+export function assertIsNotNull<T>(
+    input: T | null,
+    options?: ErrorMessage,
+): asserts input is T {
     if (isNull(input)) {
-        throw TypeError();
+        throw TypeError(options?.message);
     }
 }

src/assertions/assertIsNotNullish.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import { isNull } from '../guards/isNull';
 import { isUndefined } from '../guards/isUndefined';
 
@@ -9,8 +10,9 @@ import { isUndefined } from '../guards/isUndefined';
  */
 export function assertIsNotNullish<T>(
     input: T | undefined | null,
+    options?: ErrorMessage,
 ): asserts input is T {
     if (isUndefined(input) || isNull(input)) {
-        throw TypeError();
+        throw TypeError(options?.message);
     }
 }

src/assertions/assertIsPromise.ts

@@ -1,3 +1,4 @@
+import { ErrorMessage } from '../types';
 import { createTypeAssertion } from '../utils';
 import { isPromise } from '../guards/isPromise';
 
@@ -9,6 +10,7 @@ import { isPromise } from '../guards/isPromise';
  */
 export function assertIsPromise<T = unknown>(
     input: unknown,
+    options?: ErrorMessage,
 ): asserts input is Promise<T> {
-    return createTypeAssertion<Promise<T>>(isPromise)(input);
+    return createTypeAssertion<Promise<T>>(isPromise)(input, options);
 }