https://github.com/matthieubosquet/ts-guards
A collection of basic type guards.
https://github.com/matthieubosquet/ts-guards
asserts runtime-validation type-guards typescript
Last synced: 30 days ago
JSON representation
A collection of basic type guards.
- Host: GitHub
- URL: https://github.com/matthieubosquet/ts-guards
- Owner: matthieubosquet
- License: mit
- Created: 2020-11-15T15:14:31.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2021-10-18T12:30:40.000Z (over 3 years ago)
- Last Synced: 2024-10-07T13:49:50.623Z (8 months ago)
- Topics: asserts, runtime-validation, type-guards, typescript
- Language: TypeScript
- Homepage:
- Size: 182 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Type Guards
[](https://github.com/matthieubosquet/ts-guards/actions/workflows/test.yml?query=workflow%3Atest+branch%3Amain)
[](https://www.npmjs.com/package/ts-guards)
A collection of generic type guards to check runtime variables in TypeScript.
## How-to?
- Install the [npm package ts-guards](https://www.npmjs.com/package/ts-guards)
```bash
npm i ts-guards
```
- Use the package
```javascript
import { asserts, primitiveType } from 'ts-guards';
let x = "a string";
// Type of x inferred inside the if statement as: let x: string
if(primitiveType.isString(x)) { console.log(x); }
// Type of x inferred after the call as:
// Throws an error if type doesn't match
asserts.isString(x);
// Properties of object inferred (if object does not have an x and a y property, it throws an error)
asserts.areObjectPropertiesOf({ x: "y", y: "x" }, ["x", "y"]);
// Type of x inferred inside the if statement as: let x: string
if(isLiteral(x, "x" as const)) { x }
// Type of x inferred inside the if statement as: let x: "x" | 1 | "y" | "z"
if(isLiteralType(x, new Set([ "x", 1, "y", "z" ] as const))) { x }
```
## Why?
TypeScript helps only with compile time validation, you need to check anything coming from IO at runtime. TypeScript runtime validation relies upon [type guards](https://www.typescriptlang.org/docs/handbook/advanced-types.html#type-guards-and-differentiating-types).
Type guards take a parameter `x as unknown`, denoting [variables whose type we do not know](https://www.typescriptlang.org/docs/handbook/basic-types.html#unknown).
There are two styles of validation: one relying on `x is T`; another relying on `asserts x is T`.
The former can be used in conditional cases (returns a boolean), the latter for input validation (throws an error).
One might consider that functions given a wrong parameter can’t answer the question they’re supposed to, hence they should throw an error, hence the `asserts x is T` style (error throwing).
All of `asserts x is T` style functions rely upon and have a `x is T` counterpart. Both validation styles trigger TypeScript type inference.
In some cases, type guards may take a parameter `x: T` to catter for output type inference.