Type Guard Utils -- WIP -- Use at your own risk

Just some operators and decorators to check return types at runtime. Mostly useful for doing sanity checks at the edges of your apps.

This is still a work in progress any input/contributions are welcome.

---

Rxjs Operators

typeGuardCheckOperator

An an operator to use with rxjs observables. Could be used to check the type on any state of an observable.

The best use case for this would be on the edges of your application such as request to external APIs. This would help with both verifying that the you defined the correct types for the returned values. This would also help to catch if the data type returned from an API changes.

typeGuardMapOperator

Same as typeGuardCheckOperator expect that the observable gets emitted to the return value from either the invalidTypeCallback or the validTypeCallback. If either callback is omitted the stream is re-emitted when that callback is called.

---

Typescript Method Decorators

checkWithTypeGuard(typeChecker, expectArray, invalidTypeCallback, validTypeCallback, mapInsteadOfCheck)

A method decorator to check return type.

For Observables: Wraps the typeGuardMapOperator.

For Promises and non-async values: Wraps internal handleTypeGuardValidation function.

Can handle () => ReturnType | <Promise> | <Observable>

---

Utility functions/factories

validatorFactory(typeChecker, expectArray, invalidTypeCallback, validTypeCallback)

The validatorFactory returns a validator function that can be used to do runtime type checks for a certain type.

The invalidTypeCallback and validTypeCallbacks null/undefined or a some value. If null/undefined the original value is returned from the validator function, if any other value is return that value is also returned by the validator.

Example: let cars = 0; const logInvalidType = (car) => { postToSomeLoggingService(car) } const incrementCarCount = () => { cars++ }

const carsValidator = validatorFactory(isCar, true, logInvalidCar, incrementCarCount)

In cases where invalidTypeCallback or validTypeCallback don't return anything we can use this to check a value and also a return value.

To check an existing value: const car = {...} carValidator(car)

To check a return value, you can just use the validator as a higher order function:

const car = carValidator(getNextCar())

typeGuardOperatorFactory(operator)

Mostly for internal use but exposing incase anyone wants to do anything other than the predefined operators.

---

Detailed function descriptions

---

typeGuardCheckOperator

An an operator to use with rxjs observables. Could be used to check the type on any state of an observable.

The best use case for this would be on the edges of your application such as request to external APIs. This would help with both verifying that the you defined the correct types for the returned values. This would also help to catch if the data type returned from an API changes.

Kind: global variable

Param	Description
typeChecker	A function that acts as a type guard. Accepts the item in and returns a boolean for if its valid
expectArray	Apply the typeChecker to an array of items instead of individual item.
invalidTypeCallback	Callback for if typeChecker(item) returns false
validTypeCallback	Callback for if typeChecker(item) returns true

typeGuardMapOperator

Same as typeGuardCheckOperator expect that the observable gets emitted to the return value from either the invalidTypeCallback or the validTypeCallback. If either callback is omitted the stream is re-emitted when that callback is called.

Kind: global variable

checkWithTypeGuard(typeChecker, expectArray, invalidTypeCallback, validTypeCallback, mapInsteadOfCheck)

A method decorator to check return type.

For Observables: Wraps the typeGuardMapOperator.

For Promises and non-async values: Wraps internal handleTypeGuardValidation function.

Can handle () => ReturnType | <Promise> | <Observable>

Kind: global function

Param	Default	Description
typeChecker		A function that acts as a type guard. Accepts the item in and returns a boolean for if its valid
expectArray	false	Apply the typeChecker to an array of items instead of individual item
invalidTypeCallback		Callback for if typeChecker(item) returns false
validTypeCallback		Callback for if typeChecker(item) returns true
mapInsteadOfCheck	false	If true the return type gets mapped to the return from either the invalidTypeCallback or validTypeCallback. Default is that the return value is unchanged.

validatorFactory(typeChecker, expectArray, invalidTypeCallback, validTypeCallback)

The validatorFactory returns a validator function that can be used to do runtime type checks for a certain type.

The invalidTypeCallback and validTypeCallbacks null/undefined or a some value. If null/undefined the original value is returned from the validator function, if any other value is return that value is also returned by the validator.

Example: let cars = 0; const logInvalidType = (car) => { postToSomeLoggingService(car) } const incrementCarCount = () => { cars++ }

const carsValidator = validatorFactory(isCar, true, logInvalidCar, incrementCarCount)

In cases where invalidTypeCallback or validTypeCallback don't return anything we can use this to check a value and also a return value.

To check an existing value: const car = {...} carValidator(car)

To check a return value, you can just use the validator as a higher order function:

const car = carValidator(getNextCar())

Kind: global function

Param	Description
typeChecker	A function that acts as a type guard. Accepts the item in and returns a boolean for if its valid
expectArray	Apply the typeChecker to an array of items instead of individual item.
invalidTypeCallback	Callback for if typeChecker(item) returns false
validTypeCallback	Callback for if typeChecker(item) returns true

typeGuardOperatorFactory(operator)

Mostly for internal use but exposing incase anyone wants to do anything other than the predefined operators.

Kind: global function

Param	Description
operator	Accepts an rxjs operator