tson

Type Safe Object Notation & Validation

📌 Work in Progress, not ready for production...

Features

🧱 Functional
🔷 Immutable
✅ Well tested

Why?

After a contribution to the tRPC project, I wanted to understand more deeply the use of generics and inference in TypeScript. I needed a challenge so I set myself the goal of coding my own schema validation library. This library is heavily inspired by Zod (I try to provide the same API) but in order to avoid cloning it, I challenged myself to not use any classes.

Install

pnpm add @skarab/tson

yarn and npm also works

ES and CommonJS module

import { t } from "tson";

const { t } = require("tson");

Examples

import { t } from "tson";

const name = t.string();

name.parse("nyan"); // return "nyan"
name.parse(42); // throw TypeCheckError

import { t } from "tson";

const user = t.object({
  name: t.string(),
  age: t.number(),
  admin: t.boolean(),
});

user.parse({ name: "nyan", age: 42, admin: true });

type User = t.infer<typeof user>;
// { name: string, age: number, admin: boolean }

Strict mode

TypeScript

It is strongly recommended to activate the strict mode of TypeScript which will activate all checking behaviours that results in stronger guarantees of the program's correctness.

tson

By default tson parse objects in STRICT mode, this means that all undefined values in a scheme will be considered as an error. You can change this behaviour globally or locally, the procedure is documented here.

tson
- Features
- Why?
Install
- ES and CommonJS module
Examples
Strict mode
- TypeScript
- tson
Table of contents
API
Type helpers
Contributing 💜

API

First level types

Primitive types

t.string();
t.number();
t.bigint();
t.boolean();
t.symbol();
t.date();

Numbers types

t.nan();
t.finite();
t.infinity();
t.integer(); // Alias: int()
t.unsignedNumber(); // Alias: unumber()
t.unsignedInteger(); // Alias: uinteger(), uint()

Empty types

t.undefined();
t.null();
t.void();

Catch-all types

t.any();
t.unknown();

Never type

t.never();

literal(value)

const life = t.literal(42);
const love = t.literal(true);
const name = t.literal("nyan");

life.value; // type => 42

array(type)

const arr1 = t.array(t.string()); // string[]
const arr2 = t.array(t.boolean()); // boolean[]

tuple(...type)

const tpl = t.tuple(t.string(), t.number(), t.string()); // [string, number, string]

tuple(type[])

const tpl = t.tuple([t.string(), t.number(), t.string()]); // [string, number, string]

💔 The following code does not work, TypeScript can not infer array values properly. Use the as const workaround to do this.

const types = [t.string(), t.number(), t.string()];
const tpl = t.tuple(types); // [string, number, string]

tuple(type[] as const)

const types = [t.string(), t.number(), t.string()] as const;
const tpl = t.tuple(types); // [string, number, string]

object(schema)

const user = t.object({
  name: t.string(),
  age: t.number(),
  admin: t.boolean(),
});

type User = t.infer<typeof user>;
// { name: string, age: number, admin: boolean }

object(schema, mode)

By default tson parse objects in STRICT mode, but you can change the mode globally or locally.

There are three modes:

STRICT: Will raise an error if a key is not defined in the schema.
STRIP: Strips undefined keys from the result and does not raise an error.
PASSTHROUGH: Keeps undefined keys and does not raise an error.

Change the default mode globally.

t.defaultSettings.objectTypeMode = t.ObjectTypeMode.STRIP;

Change the mode locally.

const schema = { a: t.string(), b: t.string() };
const input = { a: "a", b: "b", c: "c" };

const user = t.object(schema, t.ObjectTypeMode.STRICT);
user.parse(input); // throws an TypeParseError

const user = t.object(schema, t.ObjectTypeMode.STRIP);
user.parse(input); // { a: string, b: string }

const user = t.object(schema, t.ObjectTypeMode.PASSTHROUGH);
user.parse(input); // { a: string, b: string, c: string }

object helpers

.strict()

t.object(schema).strict();
// same as
t.object(schema, t.ObjectTypeMode.STRICT);

.strip()

t.object(schema).strip();
// same as
t.object(schema, t.ObjectTypeMode.STRIP);

.passthrough()

t.object(schema).passthrough();
// same as
t.object(schema, t.ObjectTypeMode.PASSTHROUGH);

union(...type)

const uni = t.union(t.string(), t.number()); // string | number

union(type[])

const tpl = t.union([t.string(), t.number(), t.string()]); // string | number

💔 The following code does not work, TypeScript can not infer array values properly. Use the as const workaround to do this.

const types = [t.string(), t.number(), t.string()];
const tpl = t.union(types); // string | number

union(type[] as const)

const types = [t.string(), t.number(), t.string()] as const;
const tpl = t.union(types); // string | number

optional(type)

const user = t.object({
  name: t.string(),
  age: t.optional(t.number()),
});
// { name: string, age?: number }

enum(...string)

const myEnum = t.enum("UP", "DOWN", "LEFT", "RIGHT");

Access enum properties

myEnum.enum.UP; // === "UP"
myEnum.enum.PLOP; // error: PLOP does not exists
myEnum.enum.DOWN = "prout"; // error: it is read-only

(property) enum: {
  readonly UP: "UP";
  readonly DOWN: "DOWN";
  readonly LEFT: "LEFT";
  readonly RIGHT: "RIGHT";
}

Access enum values

myEnum.options[1]; // === "DOWN"

(property) options: ["UP", "DOWN", "LEFT", "RIGHT"]

Test enum values

myEnum.parse(myEnum.enum.LEFT); // => "LEFT"
myEnum.parse("LEFT"); // => "LEFT"
myEnum.parse("2"); // => "LEFT"
myEnum.parse(2); // => "LEFT"
myEnum.parse("PLOP"); // error: expected '0|1|2|3|UP|DOWN|LEFT|RIGHT' got 'string'

Infer enum type

type MyEnum = t.infer<typeof myEnum>; // => "UP" | "DOWN" | "LEFT" | "RIGHT"

function move(direction: MyEnum) {
  // direction === "DOWN"
}

move(myEnum.enum.DOWN);

enum(string[])

const myEnum = t.enum(["UP", "DOWN", "LEFT", "RIGHT"]);

💔 The following code does not work, TypeScript can not infer array values properly. Use the as const workaround to do this.

const values = ["UP", "DOWN", "LEFT", "RIGHT"];
const myEnum = t.enum(values);

enum(string[] as const)

const myEnum = t.enum(["UP", "DOWN", "LEFT", "RIGHT"] as const);

const values = ["UP", "DOWN", "LEFT", "RIGHT"] as const;
const myEnum = t.enum(values);

enum(object)

const myEnum = t.enum({ UP: "UP", DOWN: "DOWN", LEFT: 42, RIGHT: 43 });

💔 The following code does not work, TypeScript can not infer object properties properly. Use the as const workaround to do this.

const values = { UP: "UP", DOWN: "DOWN", LEFT: 42, RIGHT: 43 };
const myEnum = t.enum(values);

enum(object as const)

const values = { UP: "UP", DOWN: "DOWN", LEFT: 42, RIGHT: 43 } as const;
const myEnum = t.enum(values);

enum(enum)

enum MyEnum {
  UP = "UP",
  DOWN = "DOWN",
  LEFT = 42,
  RIGHT,
}

const myEnum = t.enum(MyEnum);

nativeEnum(enum)

Alias: enum(enum)

enum MyEnum {
  UP = "UP",
  DOWN = "DOWN",
  LEFT = 42,
  RIGHT,
}

const myEnum = t.nativeEnum(MyEnum);

instanceof(type)

class MyClass {}

const instance = new MyClass();

t.instanceof(MyClass).parse(instance); // passes
t.instanceof(MyClass).parse("nyan"); // fail

date()

t.date().parse(new Date()); // passes
t.date().parse("2022-01-12T00:00:00.000Z"); // passes
t.date().parse("not a string date"); // fail

record(type)

t.record(t.string()); // { [x: string]: string }
t.record(t.number()); // { [x: string]: number }
t.record(t.date()); // { [x: string]:  Date }

set(type)

Testing a single type on the entire set

t.set(t.string()); // Set<string>

Testing a union of types on the entire set

t.set(t.union(t.string(), t.boolean(), t.string())); // Set<string|boolean>

set(...type)

Same as tuple(...type) but test if the input is an instance of Set.

set([type, ...type])

Testing a tuple of types on the Set

t.set(t.string(), t.boolean(), t.string()); // Set<[string, boolean, string]>
t.set([t.string(), t.boolean(), t.string()]); // Set<[string, boolean, string]>

map(keyType, valueType)

t.map(t.string(), t.number()); // Map<string, number>
t.map(t.date(), t.string()); // Map<Date, string>

map(schema)

Same as object(schema) but test if the input is an instance of Map.

const map = new Map();

t.map({ name: t.string(), size: t.string() }).parse(map);

promise(type)

const promise = t.promise(t.number());

await promise.parse(Promise.resolve(42)); // resolve: 42
await promise.parse(Promise.resolve("42")); // reject: expected 'number' got 'string'
await promise.parse(42); // reject: expected 'Promise' got 'number'

function()

const func = t.function();

type Func = t.infer<typeof func>; // () => void

function(args)

const func = t.function([t.string(), t.number()]);

type Func = t.infer<typeof func>; // (arg_0: string, arg_1: number) => void

function(args, returns)

const func = t.function([t.string()], t.boolean());

type Func = t.infer<typeof func>; // (arg_0: string) => boolean

function(args, returns, implement)

const args = [t.string(), t.boolean()] as const;

const returns = t.union(t.string(), t.number());

const func = t.function(args, returns, (input, toInt) => {
  // input type is string and toInt type is boolean
  return toInt ? parseInt(input) : input.toUpperCase();
});

type Func = t.infer<typeof func>; // (arg_0: string, arg_1: boolean) => string | number

preprocess(filter, type)

If you want to modify the input before it is parsed you can use the preprocess type as follows.

const toString = t.preprocess((input) => String(input), t.string());

toString.parse("42"); // => "42"
toString.parse(42); // => "42"

postprocess(filter, type)

If you want to modify the output after it is parsed you can use the postprocess type as follows.

const postprocess = t.postprocess((input) => input + 2, t.number());

postprocess.parse(40); // => 42
postprocess.parse("42"); // throws: "expected 'number' got 'string'"

postprocess(filter, inputType, outputType)

If you want to modify the output after it is parsed you can use the postprocess type as follows.

const postprocess = t.postprocess(
  (input) => String(input),
  t.number(),
  t.string(),
);

postprocess.parse(40); // => "42"
postprocess.parse("42"); // => throws: "expected 'number' got 'string'"

Type helpers

safeParse(input)

If you want to avoid the parse method throws an error you can use the .safeParse() method instead.

t.bigint().safeParse(42n);
// => { success: true, data: 42n }

t.bigint().safeParse(42);
// => {
//   "error": [TypeParseError: expected 'bigint|undefined' got 'number'],
//   "success": false,
// }

optional()

t.bigint().optional(); // => bigint | undefined

// same as
t.optional(t.bigint());

preprocess()

t.string().preprocess((input) => String(input));

// same as
t.preprocess((input) => String(input), t.string());

postprocess()

Alias: .transform()

t.number().postprocess((input) => input + 2);

// same as
t.postprocess((input) => input + 2, t.number());

Contributing 💜

See CONTRIBUTING.md

v1.5.1(Mar 19, 2022)
1.5.1 (2022-03-19)

Bug Fixes

infer type alias (681c4f2)

Source code(tar.gz)
Source code(zip)
v1.5.0(Mar 19, 2022)
1.5.0 (2022-03-19)

Features

build with tsup (#7) (0e78519)

Source code(tar.gz)
Source code(zip)
v1.4.3(Mar 18, 2022)
1.4.3 (2022-03-18)

Bug Fixes

rebuild (d00febb)

Source code(tar.gz)
Source code(zip)
v1.4.1(Mar 14, 2022)
1.4.1 (2022-03-14)

Bug Fixes

nested object().strip() (afc47c1)

Source code(tar.gz)
Source code(zip)
v1.4.0(Mar 14, 2022)
1.4.0 (2022-03-14)

Features

object mode - strict, strip, passthrough (c53d81b)

Source code(tar.gz)
Source code(zip)
v1.3.0(Mar 13, 2022)
1.3.0 (2022-03-13)

Features

implements helpers (8edd949)

preproces/postprocess helpers (48cbb2a)

Source code(tar.gz)
Source code(zip)
v1.2.2(Mar 13, 2022)
1.2.2 (2022-03-13)

Bug Fixes

setType inferance with one argument (dcccd2b)

Source code(tar.gz)
Source code(zip)
v1.2.1(Mar 13, 2022)
1.2.1 (2022-03-13)

Bug Fixes

LengthMismatchError name (bc50442)

Source code(tar.gz)
Source code(zip)
v1.2.0(Mar 13, 2022)
1.2.0 (2022-03-13)

Features

postprocess type (db61178)

preprocess type (45fdc3d)

Source code(tar.gz)
Source code(zip)
v1.1.0(Mar 13, 2022)
1.1.0 (2022-03-13)

Features

exports all modules (63895c4)

Source code(tar.gz)
Source code(zip)
v1.0.4(Mar 12, 2022)
1.0.4 (2022-03-12)

Bug Fixes

package name (5741096)

Source code(tar.gz)
Source code(zip)

Type Safe Object Notation & Validation

Related tags

Overview

tson

Features

Why?

Install

ES and CommonJS module

Examples

Strict mode

TypeScript

tson

Table of contents

API

First level types

Primitive types

Numbers types

Empty types

Catch-all types

Never type

literal(value)

array(type)

tuple(...type)

tuple(type[])

tuple(type[] as const)

object(schema)

object(schema, mode)

object helpers

.strict()

.strip()

.passthrough()

union(...type)

union(type[])

union(type[] as const)

optional(type)

enum(...string)

Access enum properties

Access enum values

Test enum values

Infer enum type

enum(string[])

enum(string[] as const)

enum(object)

enum(object as const)

enum(enum)

nativeEnum(enum)

instanceof(type)

date()

record(type)

set(type)

set(...type)

set([type, ...type])

map(keyType, valueType)

map(schema)

promise(type)

function()

function(args)

function(args, returns)

function(args, returns, implement)

preprocess(filter, type)

postprocess(filter, type)

postprocess(filter, inputType, outputType)

Type helpers

safeParse(input)

optional()

preprocess()

postprocess()

Contributing 💜

You might also like...

Releases(v1.5.1)

v1.5.1(Mar 19, 2022)

1.5.1 (2022-03-19)

Bug Fixes

v1.5.0(Mar 19, 2022)

1.5.0 (2022-03-19)

Features

v1.4.3(Mar 18, 2022)

1.4.3 (2022-03-18)

Bug Fixes

v1.4.1(Mar 14, 2022)