npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ts-interface-checker

v1.0.2

Published

Runtime library to validate data against TypeScript interfaces

Downloads

43,448,919

Readme

ts-interface-checker

Build Status npm version

Runtime library to validate data against TypeScript interfaces.

This package is the runtime support for validators created by ts-interface-builder. It allows validating data, such as parsed JSON objects received over the network, or parsed JSON or YAML files, to check if they satisfy a TypeScript interface, and to produce informative error messages if they do not.

Installation

npm install --save-dev ts-interface-builder
npm install --save ts-interface-checker

Usage

Suppose you have a TypeScript file defining an interface:

// foo.ts
interface Square {
  size: number;
  color?: string;
}

The first step is to generate some code for runtime checks:

`npm bin`/ts-interface-builder foo.ts

It produces a file like this:

// foo-ti.js
import * as t from "ts-interface-checker";

export const Square = t.iface([], {
  "size": "number",
  "color": t.opt("string"),
});
...

Now at runtime, to check if a value satisfies the Square interface:

import fooTI from "./foo-ti";
import {createCheckers} from "ts-interface-checker";

const {Square} = createCheckers(fooTI);

Square.check({size: 1});                  // OK
Square.check({size: 1, color: "green"});  // OK
Square.check({color: "green"});           // Fails with "value.size is missing"
Square.check({size: 4, color: 5});        // Fails with "value.color is not a string"

Note that ts-interface-builder is only needed for the build-time step, and ts-interface-checker is needed at runtime. That's why the recommendation is to npm-install the former using --save-dev flag and the latter using --save.

Checking method calls

If you have an interface with methods, you can validate method call arguments and return values:

// greet.ts
interface Greeter {
  greet(name: string): string;
}

After generating the runtime code, you can now check calls like:

import greetTI from "./greet-ti";
import {createCheckers} from "ts-interface-checker";

const {Greeter} = createCheckers(greetTI);

Greeter.methodArgs("greet").check(["Bob"]);     // OK
Greeter.methodArgs("greet").check([17]);        // Fails with "value.name is not a string"
Greeter.methodArgs("greet").check([]);          // Fails with "value.name is missing"

Greeter.methodResult("greet").check("hello");   // OK
Greeter.methodResult("greet").check(null);      // Fails with "value is not a string"

Type suites

If one type refers to a type defined in another file, you need to tell the interface checker about all type names when you call createCheckers(). E.g. given

// color.ts
export type Color = RGB | string;
export type RGB = [number, number, number];
// shape.ts
import {Color} from "./color";
export interface Square {
  size: number;
  color?: Color;
}

the produced files color-ti.ts and shape-ti.ts do not automatically refer to each other, but expect you to relate them in createCheckers() call:

import color from "./color-ti";
import shape from "./shape-ti";
import {createCheckers} from "ts-interface-checker";

const {Square} = createCheckers(shape, color);    // Pass in all required type suites.

Square.check({size: 1, color: [255,255,255]});

Strict checking

You may check that data contains no extra properties. Note that it is not generally recommended as it this prevents backward compatibility: if you add new properties to an interface, then older code with strict checks will not accept them.

Following on the example above:

Square.strictCheck({size: 1, color: [255,255,255], bg: "blue"});    // Fails with value.bg is extraneous
Square.strictCheck({size: 1, color: [255,255,255,0.5]});            // Fails with ...value.color[3] is extraneous

Type guards

Standard Checker objects do the type checking logic, but are unable to make the TypeScript compiler aware that an object of unknown type implements a certain interface.

Basic code:

const unk: unknown = {size: 1, color: "green"};
// Type is unknown, so TypeScript will not let you access the members.
console.log(unk.size); // Error: "Object is of type 'unknown'"

With a Checker available:

import fooTI from "./foo-ti";
import {createCheckers} from "ts-interface-checker";

const {Square} = createCheckers(fooTI);

const unk: unknown = {size: 1, color: "green"};

if (Square.test(unk)) {
  // unk does implement Square, but TypeScript is not aware of it.
  console.log(unk.size); // Error: "Object is of type 'unknown'"
}

To enable type guard functionality on the existing test, and strictTest functions, Checker objects should be cast to CheckerT<> using the appropriate type.

Using CheckerT<>:

import {Square} from "./foo";
import fooTI from "./foo-ti";
import {createCheckers, CheckerT} from "ts-interface-checker";

const {Square} = createCheckers(fooTI) as {Square: CheckerT<Square>};

const unk: unknown = {size: 1, color: "green"};

if (Square.test(unk)) {
  // TypeScript is now aware that unk implements Square, and allows member access.
  console.log(unk.size);
}

Type assertions

CheckerT<> will eventually support type assertions using the check and strictCheck functions, however, this feature is not yet fully working in TypeScript.