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

generate-ts-types

v1.1.7

Published

Make TypeScript types and proxy objects from example JSON objects. Can use proxy objects to dynamically type check JSON at runtime.

Downloads

361

Readme

MakeTypes 1.1.2

Generate TypeScript types and proxy classes from example JSON objects. Type check JSON objects at runtime!

NPM version Build Status Coverage Status

With MakeTypes, you can interact with REST endpoints and other sources of JSON with confidence that your program receives the data you expect. All you need is a file containing representative sample JSON objects.

Try the web demo!

Features:

  • Type-checked JSON.parse. Proxy classes generated with MakeTypes will parse your JSON and check that it matches the expected type during runtime.
  • Statically type-check code that interacts with JSON objects. Proxy objects generated with MakeTypes are expressed as TypeScript classes, so you can statically type check that your code is appropriately accessing fields on the JSON object.
  • Generate TypeScript interfaces to describe JSON types. Don't want the overhead of runtime type checking, and trust that your samples are representative? You can opt to generate TypeScript interfaces instead, which describe the expected structure of the JSON object and facilitate type checking.

Install

npm i -g maketypes

Build

npm install

Usage

First, write a file called samples.json that contains JSON samples for a particular object type, such as the value returned from a web service. It can either contain a single sample or an array of samples.

Then, run:

make_types -i interfaces.ts -p proxies.ts samples.json RootName

...where:

  • interfaces.ts will hold interface definitions for the JSON (optional)
  • proxies.ts will hold proxy class definitions that you can use to dynamically type check JSON objects at runtime (optional)
  • RootName specifies the name to use for the type that describes the JSON object

MakeTypes will use simple heuristics to determine the names of nested sub-types.

Using Proxies

MakeTypes generates proxy classes that dynamically check that runtime JSON objects match the expected static type. They also standardize optional/nullable fields to contain null rather than null or undefined, which simplifies your code.

Example samples.json:

[
  {
    "foo": "lalala"
  },
  {
    "foo": "hello",
    "baz": 32
  }
]

Generation command:

make_types -p proxies.ts samples.json RootName

Proxy generated from example:

export class RootNameProxy {
  public readonly foo: string;
  public readonly baz: number | null;
  public static Parse(d: string): RootNameProxy {
    return RootNameProxy.Create(JSON.parse(d));
  }
  public static Create(d: any): RootNameProxy {
    if (d === null || d === undefined) {
      throwNull2NonNull("RootName");
    } else if (typeof(d) !== 'object') {
      throwNotObject("RootName");
    } else if (Array.isArray(d)) {
      throwIsArray("RootName");
    }
    return new RootNameProxy(d);
  }
  private constructor(d: any) {
    checkString(d.foo, false);
    this.foo = d.foo;
    checkNumber(d.baz, true);
    if (d.baz === undefined) {
      d.baz = null;
    }
    this.baz = d.baz;
  }
}

Example TypeScript code using proxy class:

import {RootNameProxy} from './proxies';

// RootName.Create will throw an exception if rawJson does not match the type of RootName.
const proxyObject = RootNameProxy.Parse('{"foo": "bar"}');
// Now, you can access all of the properties of the JSON object with confidence that they
// actually exist.
let foo = proxyObject.foo; // TypeScript knows foo is a string
// If one of the properties on the proxy is optional, then it will have a null value.
let baz = proxyObject.baz; // TypeScript knows baz is number | null. In this case, it will be null.

Using Interfaces

For a lighterweighter option that provides no runtime guarantees, MakeTypes can also generate TypeScript interfaces that describe the expected structure of JSON objects. You can use these interfaces to typecheck code that interacts with JSON objects, but they cannot check if the JSON objects obey the static type at runtime.

Interfaces also succinctly express the static type that MakeTypes is inferring from your samples, so this feature can be a good debugging mechanism.

Example samples.json:

[
  {
    "foo": "lalala"
  },
  {
    "foo": "hello",
    "baz": 32
  }
]

Generation command:

make_types -i interfaces.ts samples.json RootName

Interface generated from example:

export interface RootName {
  foo: string;
  baz?: number | null;
}

Example TypeScript code using interfaces:

import {RootName} from './interfaces';

const rawJson = <RootName> JSON.parse('{"foo": "bar"}');
let foo = rawJson.foo; // TypeScript knows foo i a string
let baz = rawJson.baz; // TypeScript knows that baz is an optional field that may not be there.

Inspiration / Technique

MakeTypes uses the Common Preferred Shape Relation from Petricek et al.'s PLDI 2016 paper, "Types from Data: Making Structured Data First-Class Citizens in F#". Since JavaScript/TypeScript lacks a distinction between integer and floating point types, we merge the float and int types into a number type.