# ts-guards

> A collection of basic type guards.

Latest version **0.5.1** (published 2020-11-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install ts-guards
pnpm add ts-guards
yarn add ts-guards
bun add ts-guards
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.1 |
| Published | 2020-11-17 |
| First published | 2020-11-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 20.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Matthieu Bosquet |
| Maintainers | matthieubosquet |
| Keywords | Type Guards, Asserts, Runtime Validation, TypeScript |

## Links

- npm: https://www.npmjs.com/package/ts-guards
- Repository: https://github.com/matthieubosquet/ts-guards
- Homepage: https://github.com/matthieubosquet/ts-guards#readme
- Issues: https://github.com/matthieubosquet/ts-guards/issues
- npm.io page: https://npm.io/package/ts-guards

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 0.5.1 (latest) — 2020-11-17
- 0.5.0 — 2020-11-17
- 0.4.4 — 2020-11-17
- 0.4.3 — 2020-11-17
- 0.4.2 — 2020-11-17
- 0.4.1 — 2020-11-17
- 0.4.0 — 2020-11-16
- 0.3.0 — 2020-11-16
- 0.2.0 — 2020-11-15
- 0.1.0 — 2020-11-15

## README

# Type 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.

---
_Source: https://npm.io/package/ts-guards · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._