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

json2struct

v0.4.4

Published

Easily translate JSON into type definitions

Downloads

32

Readme

json2struct

json2struct is a tool that translates JSON into type definitions. It currently supports translating to TypeScript, Python, Julia and Rust.

The goal is for the definitions to be used as a starting point for the user, and not as a single source of truth.

Installation

The tool can either be run using npx

$ npx json2struct <REQUIRED_INPUT_FILE>

or be installed globally

$ npm i -g json2struct
$ json2struct <REQUIRED_INPUT_FILE>

Usage

To use the program pass the path to the json file $ json2struct example.json.

By default the structure will be printed to stdout.

# example.json
{
    "number_key": 1,
    "string_key": "json2struct",
    "boolean_key": true,
    "array_key": [42],
    "map_key": { "key": "value" }
}

$ npx json2struct example.json

json2struct: Converting example.json to typescript:
type GeneratedStruct = { array_key: Array<number>; boolean_key: boolean; map_key: { key: string }; number_key: number; string_key: string }

Writing struct to file

To write the structure to a file pass use the output option $ npx json2struct <REQUIRED_INPUT_FILE> --output <OUTPUT_FILE>.

# example.json
{
    "number_key": 1,
    "string_key": "json2struct",
    "boolean_key": true,
    "array_key": [42],
    "map_key": { "key": "value" }
}

$ npx json2struct example.json --output example.d.ts

Writes the following to the output file:

// example.d.ts
type GeneratedStruct = {
    array_key: Array<number>;
    boolean_key: boolean;
    map_key: { key: string };
    number_key: number;
    string_key: string;
};

The default behavior is to append to the output file. This behavior can be overwritten by passing the option --overwrite.

Changing language

json2struct currently supports outputting to either TypeScript or Python. By default the conversion will be to TypeScript.

To use another language pass the --language option.

Python

# example.json
{
    "number_key": 1,
    "string_key": "json2struct",
    "boolean_key": true,
    "array_key": [42],
    "map_key": { "key": "value" }
}

$ npx json2struct example.json --output example.py --language python

Writes the following to the output file:

# example.py
from typing import List, TypedDict


class SubStruct1(TypedDict):
    key: str


class GeneratedStruct(TypedDict):
    array_key: List[int]
    boolean_key: bool
    map_key: SubStruct1
    number_key: int
    string_key: str

Julia

# example.json
{
    "number_key": 1,
    "string_key": "json2struct",
    "boolean_key": true,
    "array_key": [42],
    "map_key": { "key": "value" }
}

$ npx json2struct example.json --output example.jl --language julia

Writes the following to the output file:

# example.jl
struct SubStruct1
    key::String
end

struct GeneratedStruct
    array_key::Array{Int64}
    boolean_key::Bool
    map_key::SubStruct1
    number_key::Int64
    string_key::String
end

Unknown values

If json2struct isn't able to determine the type of a given element, it tries to convert it to the closest type possible. In most languages this will be the Any type of the language.

For some languages, like Rust, this mean that the generated type definitions might not always be valid.

Empty arrays

By default empty arrays will be converted to:

TypeScript

Array<unknown>;

Python

List[Any]

Julia

Array{Any}

Empty hashmaps

Hashmaps without keys will be converted to:

TypeScript

Record<string, unknown>;

Python

Dict[Any, Any]

Julia

Dict{Any,Any}

Examples

Examples of type definitions generated using json2struct can be found in the examples folder.

Notes

As said earlier the aim of this tool is to be used as a helper when writing type definitions, for that reason json2struct tries not to augment the output in any way.

One such example is not flattening the values of maps. In some cases it might make sense to flatten [{ "a": 1 }, { "b": 1 }] into type GeneratedStruct = [{ a?: number; b?: number }];. But in most cases flattening of maps requires having preexisting knowledge about the data that should be expected. For that reason json2struct prefers to let the user augment the type definition after, instead of imposing it's views on the user.

For the same reason json2struct does not take into account whether a key is actually valid in the given language.

Since this project is mostly meant to be a way for me to familiarize myself with different languages, the types might not be the most optimal.