jtd-codegen 0.1.4

Generate code from JSON Typedef schemas
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

# `jtd-codegen` + TypeScript

This README contains details of how to use `jtd-codegen` in conjunction with
TypeScript.

* For documentation on `jtd-codegen` in general, see [the top-level
  `jtd-codegen` README](../../..).

* For a more guided explanation of how you can integrate TypeScript generated by
  `jtd-codegen` into your codebase, see ["Generating TypeScript from JSON
  Typedef Schemas"][jtd-ts-codegen] in the JSON Typedef docs. This README will
  focus on specific technical documentation.

## Configuration Options

The TypeScript code generator has only one option:

* `--typescript-out` specifies the output directory that `jtd-codegen` should
  generate TypeScript into. If this flag is omitted, then `jtd-codegen` will
  assume you don't want to generate TypeScript.

## Notes on Generated Code

### Cleanliness of generated code

`jtd-codegen` will not always generate "pretty" code, but it will always
generate correct code. It's recommended that you run your code formatter on
`jtd-codegen`-generated code.

### Generating JavaDoc-style comments

`jtd-codegen` supports JavaDoc-style comments in generated TypeScript code. To
have `jtd-codegen` generate a documentation comment for a particular
`interface`, `interface` member, or `type` alias, use a `description` property
inside the `metadata` of a schema.

For example, if you have a schema like this in a file called `user.jtd.json`:

```json
{
  "metadata": {
    "description": "This is a user."
  },
  "properties": {
    "name": {
      "metadata": {
        "description": "The user's name"
      },
      "type": "string"
    },
    "favoriteNumbers": {
      "metadata": {
        "description": "The user's favorite numbers"
      },
      "elements": {
        "type": "float64"
      }
    }
  }
}
```

Then `jtd-codegen` will generate something like:

```ts
/**
 * This is a user.
 */
export interface User {
  /**
   * The user's favorite numbers
   */
  favoriteNumbers: number[];
  /**
   * The user's name
   */
  name: string;
}
```

### Inferred type names

`jtd-codegen` infers the name of the "root" type it generates from the name of
the file you generate code from. For example, if you generate code from a file
called `user.jtd.json`, the generated top-level TypeScript type will be called
`User`.

`jtd-codegen` uses the names of definitions to determine the name of types
described in a JSON Typedef definition. For example, if you have a schema like
this in a file called `example.jtd.json`:

```json
{
  "definitions": {
    "thing": {
      "properties": {
        "foo": { "type": "string" },
        "bar": { "type": "string" }
      }
    }
  },
  "properties": {
    "thing1": { "ref": "thing" },
    "thing2": { "ref": "thing" }
  }
}
```

Then `jtd-codegen` will generate something like:

```ts
export interface Thing {
  bar: string;
  foo: string;
}

export interface Example {
  thing1: Thing;
  thing2: Thing;
}
```

You can use this to your advantage. If there's a particular sub-component of a
schema that you'd like `jtd-codegen` to generate a specific name for, put that
sub-component in a definition with the name you want.

[jtd-ts-codegen]: https://jsontypedef.com/docs/javascript/code-generation