# rtti
> Runtime type validation for JavaScript and TypeScript programs
Latest version **1.1.4** (published 2022-03-07) · MIT license · 0 weekly downloads
## Install
```sh
npm install rtti
pnpm add rtti
yarn add rtti
bun add rtti
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 1.1.4 |
| Published | 2022-03-07 |
| First published | 2019-08-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 79.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Author | Troy Gerwien |
| Maintainers | yortus |
| Keywords | validation, validate, type, types, type info |
## Links
- npm: https://www.npmjs.com/package/rtti
- Repository: https://github.com/yortus/rtti
- Homepage: https://github.com/yortus/rtti#readme
- Issues: https://github.com/yortus/rtti/issues
- npm.io page: https://npm.io/package/rtti
## Alternatives
- [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads
- [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads
- [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads
- [@oridune/validator](https://npm.io/package/@oridune/validator.md) — 16 weekly downloads
## Recent versions
- 1.1.4 (latest) — 2022-03-07
- 1.0.0-alpha.0 (alpha) — 2021-08-07
- 1.1.3 — 2022-02-20
- 1.1.2 — 2022-02-20
- 1.1.1 — 2022-02-16
- 1.1.0 — 2022-02-16
- 1.0.1 — 2021-11-03
- 1.0.0 — 2021-09-08
- 0.4.0 — 2021-07-27
- 0.3.3 — 2020-06-25
- 0.3.2 — 2020-05-18
- 0.3.1 — 2020-05-18
- 0.3.0 — 2020-05-12
- 0.2.1 — 2020-04-07
- 0.2.0 — 2020-02-25
- … 13 more at https://npm.io/package/rtti/versions
## README
# rtti
**Runtime type validation for JavaScript and TypeScript programs.**
This library bring the benefits of TypeScript's type system to runtime code. By declaring types using runtime constructs, it is possible to add an extra level of runtime type safety that static checking alone cannot provide. For example:
- ensure that a parsed JSON string produces a value that conforms to an expected schema
- verify that a HTTP request body conforms to an expected schema
- ensure that a HTTP response body does not send additional properties other that those intended for the client
There is no need to declare any type twice (i.e., once for JS and once TS), since the TypeScript type can be inferred from the `example` property of any given `TypeInfo` value.
## Installation
`npm install rtti`
## Usage Example
```ts
import {t} from 'rtti';
const myType = t.union(
t.unit('foo'),
t.unit('bar')
);
// prints: "foo" | "bar"
console.log(myType.toString());
// prints: true
console.log(myType.isValid('foo'));
// prints: false
console.log(myType.isValid('baz'));
// prints: {
// isValid: false,
// errors: [
// {path: '^', message: 'The value "baz" does not conform to the union type'}
// ]
// }
console.log(myType.check('baz'));
// TypeScript only - static type inference:
type MyType = typeof myType.example; // type MyType = "foo" | "bar"
```
## API
> NOTE: The [v0.4 API](https://github.com/yortus/rtti/tree/v0-api#api) is deprecated but still supported.
---
##### `t.string`, `t.object(...)`, etc
Construct a `TypeInfo` instance that matches a particular set of runtime values.
---
##### `myType.assertValid(value: unknown): void`
Ensures the given `value` matches the given `type`, otherwise throws an error. The error object has an `errors`
property containing details about the validation error(s).
---
##### `myType.check(value: unknown): {isValid: boolean, errors: Array<{path: string, message: string}>}`
Returns a list of descriptive validation errors explaining why the given `value` does not match the given `type`.
---
##### `myType.example`
An example value that conforms to the given `TypeInfo` type. The TypeScript type can be inferred from this property.
---
##### `myType.isValid(value: unknown): boolean`
Returns `true` if the given `value` matches the given `type`, or `false` otherwise.
---
##### `myType.sanitize(value: typeof myType.example): typeof myType.example`
Returns a copy of the given `value`, but where any properties not declared in `type` have been removed.
---
##### `myType.toJsonSchema(type: TypeInfo): unknown`
Returns a JSON schema representation of the given type.
---
##### `myType.toString(): string`
Returns a descriptive string for the given `type`.
---
##### `TypeInfo`
An object used by the RTTI library to describes a set of matching runtime values. These objects may be created using the `t.` syntax. See the following table for examples.
## Supported Types
| | PRIMITIVE JAVASCRIPT TYPES | | | |
| -------------- | ------------------------------------------------------------ | -------------------------------- | ----------------------------------------- | -------------------------------------------- |
| **Datatype** | **Example RTTI Declaration** | **TS Type** | **Matching JS Values** | **Non-Matching JS Values** |
| Boolean | `t.boolean` | `boolean` | `true`, `false` | `0`, `''`, `'yes'`, `null` |
| Date | `t.date` | `Date` | `new Date()` | `'2020-01-01'` |
| Null | `t.null` | `null` | `null` | `undefined`, `0` |
| Number | `t.number` | `number` | `42`, `3.14` | `'three'`, `false` |
| String | `t.string` | `string` | `'foo'`, `'1:1'` | `42`, `{foo: 1}` |
| Undefined | `t.undefined` | `undefined` | `undefined` | `null`, `0` |
| | **COMPOUND JAVASCRIPT TYPES** | | | |
| **Datatype** | **Example RTTI Declaration** | **TS Type** | **Matching JS Values** | **Non-Matching JS Values** |
| Array | `t.array(t.number)` | `number[]` | `[1, 2, 3]` | `123`, `[1, 'a']` |
| Object | `t.object({foo: t.string, isBar: t.optional(t.boolean)})` | `{foo: string, isBar?: boolean}` | `{foo: 'foo'}`, `{foo: 'x', isBar: true}` | `{bar: 'bar'}`, `{foo: true}` |
| | **ADDITIONAL TYPESCRIPT TYPES** | | | |
| **Datatype** | **Example RTTI Declaration** | **TS Type** | **Matching JS Values** | **Non-Matching JS Values** |
| Any | `t.any` | `any` | `42`, `'foo'`, `null`, `[1, 2]`, `{}` | - |
| Branded String | `t.brandedString('usd')` | | | |
| Intersection | `t.intersection(t.object({foo: t.string}), t.object({bar: t.number}))` | `{foo: string} & {bar: number}` | `{foo: 'abc', bar: 42}` | `{bar: 42}` |
| Never | `t.never` | `never` | - | `42`, `'foo'`, `null`, `[1, 2]`, `{}` |
| Tuple | `t.tuple(t.string, t.number)` | `[string, number]` | `['foo', 42]` | `['foo']`, `['foo', 'bar']`, `['foo', 4, 2]` |
| Union | `t.union(t.object({foo: t.string}), t.object({bar: t.number}))` | `{foo: string} | {bar: number}` | `{foo: 'abc'}`, `{bar: 42}` | `{baz: 0}`, `{foo: 42}` |
| Unit Type | `t.unit('foo')` | `'foo'` | `'foo'` | `'bar'`, `'abc'`, `42` |
| Unknown | `t.unknown` | | `42`, `'foo'`, `null`, `[1, 2]`, `{}` | - |
---
_Source: https://npm.io/package/rtti · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._