Source: https://github.com/mscharley/generic-type-guard
Author: Matthew Scharley
Contributors: See contributors on GitHub
Bugs/Support: Github Issues
Copyright: 2022
License: MIT license
Status: Active
This library is an attempt to manage creating type guards in a sensible way, making them composable and reusable.
$ npm i generic-type-guard
The point of this library is to provide a suite of type guard expressions that are themselves both type safe and composable in a type safe way. To that end we define two new types which are just aliases for the built-in type guard type:
export type PartialTypeGuard<T, U extends T> = (value: T) => value is U;
export type TypeGuard<T> = PartialTypeGuard<unknown, T>;A PartialTypeGuard is a type guard which given a value of type T can prove it is
actually the specialised type U. A TypeGuard is a type guard that can prove any value
to be of type T; it is a PartialTypeGuard<unknown, T>.
What do we mean by type safety when we're talking about something that in a lot of ways is inherantly type unsafe? We simply mean that if you change the definition your interface/variable/whatever you are checking then your type guard should no longer successfully compile. Most of the type safety comes from leveraging the compiler, therefore you must define your typeguards in the following way to make them the most effective:
interface Foo {
foo: string;
bar: number;
}
// this fails.
const isBrokenFoo: tg.TypeGuard<Foo> = tg.isRecord('foo', tg.isString);
// this works.
const isFoo: tg.TypeGuard<Foo> = new tg.IsInterface()
.withProperty('foo', tg.isString)
.withProperty('bar', tg.isNumber)
.get();
// This works around the gotchas explained below but has other issues, especially with complex types.
// All guarantees are void if you use this format.
const isFoo = new tg.IsInterface().withProperty('foo', tg.isString).withProperty('bar', tg.isNumber).get();It is highly recommended to assign an explicit type to the type guards you create to let the compiler ensure that you've caught everything.
Some examples:
import * as tg from 'generic-type-guard';
export const isComplexInterface = new tg.IsInterface()
.withProperties({
str: tg.isString,
num: tg.isNumber,
b: tg.isBoolean,
maybeString: tg.isOptional(tg.isString),
nullableString: tg.isNullable(tg.isString),
})
.get();
export type ComplexInterface = tg.GuardedType<typeof isComplexInterface>;There are more detailed examples available.
generic-type-guard works with the TypeScript type system. You are guaranteed that the type guards you write are sufficient to prove
that the thing provided to it conforms in one way or another to the type that the type guard checks for. But that doesn't necessarily mean
that all valid values of that type will be allowed. Put another way, you are guaranteed to never get a false positive but you may get false
negatives. In particular, union types can be troublesome.
An example helps illustrate this:
import * as tg from 'generic-type-guard';
type FooBar = 'foo' | 'bar';
const isFooBar: tg.TypeGuard<FooBar> = tg.isSingletonString('foo');The above example checks for a single value "foo". This is a FooBar and so the type system does not complain. But if you try to pass
"bar" into this type guard then it will return false.
Perhaps more insidiously:
interface Foo {
foo?: string;
}
const isFoo: tg.TypeGuard<Foo> = tg.isRecord('foo', tg.isString);Again, checking that foo is a string is sufficient to prove that it is either a string or undefined.
If possible, you should reframe the question. Instead of creating a type to guard against, create a guard and export the type:
const isFoo = tg.isRecord('foo', tg.isOptional(tg.isString));
type Foo = tg.GuardedType<typeof isFoo>;![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "github-actions[bot]")
![greenkeeper[bot] avatar](https://avatars.githubusercontent.com/in/505?v=4 "greenkeeper[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent