✅ topgun-typed

Fast, tiny and type-safe runtime validation library for TopGun

Install

npm install topgun-typed

Usage

1import * as t from "topgun-typed";
2
3const post = t.object({
4  id: t.number(),
5  title: t.string(),
6});
7
8const postList = t.array(post);
9
10// Get the actual type of the postList
11type PostList = t.Infer<typeof postList>;
12
13// Some json data from somewhere
14const data = {} as any;
15
16const result = postList(data);
17
18if (result.ok) {
19  // Do something with the data
20  result.data;
21} else {
22  // Handle the error
23  result.error;
24}
25
26// Or you can just unwrap the value directly. It will throw if the data is invalid.
27const parsed = t.unwrap(result);
28
29// Or if you don't want it to throw, you can use `unwrapOr`
30const parsed = t.unwrapOr(result, {
31  /* a default value */
32});

Fetch example

Validate data from a remote API.

1import * as t from "topgun-typed";
2
3const post = t.object({
4  id: t.number(),
5  title: t.string(),
6});
7
8const postList = t.array(post);
9
10// If everything goes ok, posts will be correctly typed as `Post[]`.
11// If not, an error will be thrown.
12const posts = await fetch("https://jsonplaceholder.typicode.com/posts")
13  .then((res) => res.json())
14  .then(postList)
15  .then(t.unwrap);

Custom Types

There's a chance you'll want to define more complex types to deal with your data. You can do this in a few ways:

• Using the map function.
• Using the chain function.
• Creating a struct from scratch.

Using the map function

The map function allows you to convert one "base" type into another. It always starts from a base type.

1import * as t from "topgun-typed";
2
3// Suppose we have this geolocation struct.
4const latLng = t.object({
5  lat: t.number(),
6  lng: t.number(),
7});
8
9// `asNumber` means we can pass a string and it will be converted to a number.
10const latLngPair = t.tuple([t.asNumber(), t.asNumber()]);
11
12// And we'd like to have a type that takes a string a returns a `LatLng`.
13const asLatLng = t.map(t.string(), (str) => {
14  // Here `str` is guaranteed to be a string.
15
16  // Here we validate our splited string against a tuple of two numbers.
17  const result = latLngPair(str.split(","));
18
19  // If it succeeds we return a `LatLng` struct. If not, forwards the error.
20  return t.isOk(result) ? latLng(result.data) : result;
21});
22
23// Now we can use `asLatLng` to validate a string.
24const str = "42.123,42.123";
25
26const result = asLatLng(str); // `result` will be a `LatLng` struct.

Using the chain function

The chain function is useful when you don't want to change the type of your data, but further process it.

For example, if you have a string that you want to trim and lowercase it, then chain is the function you want to use.

1import * as t from "topgun-typed";
2
3const trim = (value: string) => value.trim();
4const lower = (value: string) => value.toLowerCase();
5
6const trimLower = t.chain(
7  t.string(),
8  trim,
9  lower /* whatever else function you want as longs as it at takes the same type and returns the same type */,
10);
11
12const result = trimLower("  Hello World  "); // { ok: true, value: "hello world" }

Creating a struct from scratch

A struct is nothing more than a function that takes whatever input and returns a Result. The convention in topgun-typed is to have factory functions that return a struct just to be able to customize error messages. This was not the case in previous versions of typed, but it is now.

1import * as t from "topgun-typed";
2
3const regex =
4  (regex: RegExp, msg = "Expecting value to match regex"): t.Struct<string> =>
5  (input) => {
6    if (typeof input !== "string" || !regex.test(input)) {
7      return t.err(new t.StructError(msg, { input }));
8    }
9    return t.ok(input);
10  };

You can browse the topgun-typed source code to see how structs are implemented if you're curious.

Notes

topgun-typed will deep clone non primitive values as it validates them. So if you pass an object or array to a struct, it will be cloned. This is to say that topgun-typed will get rid of any extra properties on your data, so it'll exactly match the shape you defined.

Reference

The code in this repository is based on typed (https://github.com/brielov/typed).

License

MIT