npmpackage.info

Gathering detailed insights and metrics for simple-runtypes

Other packages similar to simple-runtypes

@enre/pop-runtypes

1.27.1

runtypes for validating data using simple-runtypes

@enre/sounder-common

1.5.0

sounder common stuff, mainly using simple-runtypes

simple-runtypes

Small, efficient and extendable runtype library for Typescript

7.1.3

116

MIT

TypeScript

4.18 kB

597,128 2.5

Installations

npm install simple-runtypes

Developer Guide

BETA

Typescript

Yes

Module System

CommonJS

Pull Requests

Open

2

Total

83

Closed

51

Merged

30

Issues

Open

7

Total

18

Closed

11

Releases

Unable to fetch releases

Contributors

Unable to fetch Contributors

View All 5 Contributors

Languages

TypeScript

TypeScript (100%)

validate.email 🚀

Verify real, reachable, and deliverable emails with instant MX records, SMTP checks, and disposable email detection.

Developer

hoeck

Download Statistics

Total Downloads

597,128

Last Day

169

Last Week

1,070

Last Month

4,149

Last Year

137,468

GitHub Statistics

MIT License

116 Stars

218 Commits

5 Forks

3 Watchers

5 Branches

5 Contributors

Updated on Dec 21, 2024

Bundle Size

13.48 kB

Minified

4.18 kB

Minified + Gzipped

Bundlephobia

Maintainers

Package Meta Information

Latest Version

7.1.3

Package Id

simple-runtypes@7.1.3

Unpacked Size

320.70 kB

Size

84.23 kB

File Count

Published on

Feb 22, 2023

Total Downloads

Cumulative downloads

Total Downloads

597,128

Last Day

0.6%

169

Compared to previous day

Last Week

26.2%

1,070

Compared to previous week

Last Month

37.3%

4,149

Compared to previous month

Last Year

-63.5%

137,468

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dev Dependencies

@types/jest eslint-plugin-prettier markdown-toc prettier pretty-quick ts-node tsd tsdx tslib typescript

Preface

I said I want SIMPLE runtypes. Just functions that validate and return data. Combine them into complex types and TypeScript knows their structure. That's how runtypes work.

Install
Example
Why?
Benchmarks
Documentation

Install

npm install simple-runtypes or yarn add simple-runtypes

Example

Define the Runtype:

1import * as st from 'simple-runtypes'
2
3const userRuntype = st.record({
4    id: st.integer(),
5    name: st.string(),
6    email: st.optional(st.string()),
7})

now, ReturnType<typeof userRuntype> is equivalent to

1interface {
2    id: number,
3    name: string,
4    email?: string
5}

Use the runtype to validate untrusted data

1userRuntype({id: 1, name: 'matt'})
2// => {id: 1, name: 'matt'}
3
4userRuntype({id: 1, name: 'matt', isAdmin: true})
5// throws an st.RuntypeError: "invalid field 'isAdmin' in data"

Invoke a runtype with use to get a plain value back instead of throwing errors:

1st.use(userRuntype, {id: 1, name: 'matt'})
2// => {ok: true, result: {id: 1, name: 'matt'}}
3
4st.use(userRuntype, {id: 1, name: 'matt', isAdmin: true})
5// => {ok: false, error: FAIL}
6
7st.getFormattedError(FAIL)
8// => 'invalid keys in record: ["isAdmin"] at `<value>` in `{"id":1,"name": "matt", ... }`'

Not throwing errors is way more efficient and less obscure. Throwing errors and catching them outside is more convenient.

Why?

Why should I use this over the plethora of other runtype validation libraries available?

Strict: by default safe against proto injection attacks and unwanted properties
Fast: check the benchmark
Friendly: no use of eval, a small footprint and no dependencies
Flexible: optionally modify the data while it's being checked: trim strings, convert numbers, parse dates

Benchmarks

@moltar has done a great job comparing existing runtime type-checking libraries in moltar/typescript-runtime-type-benchmarks.

@pongo has benchmarked simple-runtypes against io-ts in pongo/benchmark-simple-runtypes.

Documentation

Intro

A Runtype is a function that:

receives an unknown value
returns that value or a copy if all validations pass
throws a RuntypeError when validation fails or returns ValidationResult when passed to use

1interface Runtype<T> {
2    (v: unknown) => T
3}

Runtypes are constructed by calling factory functions. For instance, string creates and returns a string runtype. Check the factory functions documentation for more details.

Usage Examples

Strict Property Checks

When using record, any properties which are not defined in the runtype will cause the runtype to fail:

1const strict = st.record({name: st.string()})
2
3strict({name: 'foo', other: 123})
4// => RuntypeError: Unknown attribute 'other'

To ignore single properties, use ignore, unknown or any:

1const strict = st.record({name: st.string(), other: st.ignore()})
2
3strict({name: 'foo', other: 123})
4// => {name: foo, other: undefined}

Use sloppyRecord to only validate known properties and remove everything else:

1const sloppy = st.sloppyRecord({name: st.string()})
2
3sloppy({name: 'foo', other: 123, bar: []})
4// => {name: foo}

Using any of record or sloppyRecord will keep you safe from any __proto__ injection or overriding attempts.

Optional Properties

Use the optional runtype to create optional properties:

1const squareConfigRuntype = st.record({
2  color: st.optional(st.string()),
3  width?: st.optional(st.number()),
4})

Nesting

Collection runtypes such as record, array, tuple take runtypes as their parameters:

1const nestedRuntype = st.record({
2  name: st.string(),
3  items: st.array(st.record({ id: st.integer, label: st.string() })),
4})
5
6nestedRuntype({
7  name: 'foo',
8  items: [{ id: 3, label: 'bar' }],
9}) // => returns the same data

Discriminating Unions

simple-runtypes supports Discriminating Unions via the union runtype.

The example found in the TypeScript Handbook translated to simple-runtypes:

1const networkLoadingState = st.record({
2  state: st.literal('loading'),
3})
4
5const networkFailedState = st.record({
6  state: st.literal('failed'),
7  code: st.number(),
8})
9
10const networkSuccessState = st.record({
11  state: st.literal('success'),
12  response: st.record({
13    title: st.string(),
14    duration: st.number(),
15    summary: st.string(),
16  })
17})
18
19const networdStateRuntype = st.union(
20  networkLoadingState,
21  networkFailedState,
22  networkSuccessState,
23)
24
25type NetworkState = ReturnType<typeof networkStateRuntype>

Finding the runtype to validate a specific discriminating union with is done efficiently with a Map.

Custom Runtypes

Write your own runtypes as plain functions, e.g. if you want to turn a string into a BigInt:

1const bigIntStringRuntype = st.string({match: /^-?[0-9]+n$/})
2
3const bigIntRuntype = st.runtype((v) => {
4    const stringCheck = st.use(bigIntStringRuntype, v)
5
6    if (!stringCheck.ok) {
7        return stringCheck.error
8    }
9
10    return BigInt(stringCheck.result.slice(0, -1))
11})
12
13bigIntRuntype("123n") // => 123n
14bigIntRuntype("2.2") // => error: "expected string to match ..."

Reference

Basic runtypes that match JavaScript/TypeScript types:

Meta runtypes:

Objects and Array Runtypes:

Combinators:

union
intersection
omit
pick
partial
TODO: get - similar to Type[key]

Shortcuts:

Roadmap / Todos

size - a meta-runtype that imposes a size limit on types, maybe via convert-to-json and .length on the value passed to it
rename stringLiteralUnion to literals or literalUnion and make it work on all types that literal accepts
rename record to object: #69
nonStrict modifier instead of sloppy: #68
improve docs:
- preface: what is a runtype and why is it useful
- why: explain or link to example that shows "strict by default"
- show that simple-runtypes is feature complete because it can
  1. express all TypeScript types
  2. is extendable with custom runtypes (add documentation)
- add small frontend and backend example projects that show how to use simple-runtypes in production
test all types with tsd
add more combinators: partial, required, get, ...
separate Runtype and InternalRuntype and type runtype internals (see this comment)

No vulnerabilities found.

10

Dangerous-Workflow

Determines if the project's GitHub Action workflows avoid dangerous patterns.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

0

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

Maintained

Determines if the project is "actively maintained".

0

Token-Permissions

Determines if the project's workflows follow the principle of least privilege.

0

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Security-Policy

Determines if the project has published a security policy.

0

Fuzzing

Determines if the project uses fuzzing.

0

Branch-Protection

Determines if the default and release branches are protected with GitHub's branch protection settings.

0

SAST

Determines if the project uses static code analysis.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Score

2.5

/10

Last Scanned on 2025-03-10

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More