Typist JSON

A simple runtime JSON type checker.

Features

Simple. No JSON Schema, No validation rules
Type-safe. Written in TypeScript
Intuitive. Familiar syntax like TypeScript interface

Typist JSON is focused on type checking, so there is no validation rules like range of numbers or length of strings.

Install

npm install typist-json

NOTE: Require TypeScript 4.1 or higher because Typist JSON uses Key Remapping and Template Literal Types.

Example

import { j } from "typist-json";

const NameJson = j.object({
  firstname: j.string,
  lastname: j.string,
});

const UserJson = j.object({
  name: NameJson,
  age: j.number,
  "nickname?": j.string, // optional property
});

const userJson = await fetch("/api/user")
    .then(res => res.json());

if (UserJson.check(userJson)) {
  // now, the userJson is narrowed to:
  // {
  //   name: {
  //     firstname: string
  //     lastname: string
  //   }
  //   age: number
  //   nickname?: string | undefined
  // }
}

Circular References

Sometimes JSON structures can form circular references.

Typist JSON can represent circular references by wrapping checkers in the arrow function.

const FileJson = j.object({
  filename: j.string,
});

const DirJson = j.object({
  dirname: j.string,
  entries: () => j.array(j.any([FileJson, DirJson])), // references itself
});

DirJson.check({
  dirname: "animals",
  entries: [
    {
      dirname: "cat",
      entries: [
        { filename: "american-shorthair.jpg" },
        { filename: "munchkin.jpg" },
        { filename: "persian.jpg" },
      ],
    },
    {
      dirname: "dog",
      entries: [
        { filename: "chihuahua.jpg" },
        { filename: "pug.jpg" },
        { filename: "shepherd.jpg" },
      ],
    },
    { filename: "turtle.jpg" },
    { filename: "shark.jpg" },
  ],
}); // true

Type checkers

Strings

j.string.check("foo"); // true
j.string.check("bar"); // true

Numbers

j.number.check(42); // true
j.number.check(12.3); // true
j.number.check("100"); // false

Booleans

j.boolean.check(true); // true
j.boolean.check(false); // true

Literals

j.literal("foo").check("foo"); // true
j.literal("foo").check("fooooo"); // false

Arrays

j.array(j.string).check(["foo", "bar"]); // true
j.array(j.string).check(["foo", 42]); // false
j.array(j.string).check([]); // true
j.array(j.number).check([]); // true

Objects

j.object({
  name: j.string,
  age: j.number,
  "nickname?": j.string,
}).check({
  name: "John",
  age: 20,
  nickname: "Johnny",
}); // true

j.object({
  name: j.string,
  age: j.number,
  "nickname?": j.string,
}).check({
  name: "Emma",
  age: 20,
}); // true, since "nickname" is optional

j.object({
  name: j.string,
  age: j.number,
  "nickname?": j.string,
}).check({
  id: "xxxx",
  type: "android",
}); // false, since "name" and "age" is required

If a property that ends with ? is not optional, you should replace all trailing ? by ??.

More details about escaping

As mentioned above, you need to escape all trailing ? as ??.

j.object({
    "foo??": j.boolean,
}).check({
    "foo?": true,
}); // true

So if you want optional property with a name "foo???", you should use "foo???????" as key.

j.object({
  "foo???????": j.boolean,
}).check({}); // true, since "foo???" is optional

Nulls

j.nil.check(null); // true
j.nil.check(undefined); // false

Nullables

j.nullable(j.string).check("foo"); // true
j.nullable(j.string).check(null); // true
j.nullable(j.string).check(undefined); // false

Unknowns

j.unknown.check("foo"); // true
j.unknown.check(123); // true
j.unknown.check(null); // true
j.unknown.check(undefined); // true
j.unknown.check([{}, 123, false, "foo"]); // true

Unions

j.any([j.string, j.boolean]).check(false); // true

j.any([
  j.literal("foo"),
  j.literal("bar"),
]).check("foo"); // true

Get JSON type of checkers

import { j, JsonTypeOf } from "typist-json";

const UserJson = j.object({
  name: j.string,
  age: j.number,
  "nickname?": j.string,
});

type UserJsonType = JsonTypeOf<typeof UserJson>;
// 
// ^ This is same as:
// 
// type UserJsonType = {
//   name: string;
//   age: number;
//   nickname?: string;
// }

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

kawmra / typist-json

Programming Languages

Labels

Projects that are alternatives of or similar to typist-json