jddf-codegen 0.1.1

Generate code from JDDF 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

# jddf-codegen

`jddf-codegen` is a CLI tool which generates data structures (i.e. structs,
classes, interfaces, etc.) from JDDF schemas.

## Usage

This section describes how you could use `jddf-codegen` for each language.

### TypeScript

> You can use `jddf-codegen` to automatically generate TypeScript `interface`s
> from your JDDF schemas. That way, you can write type-safe code off of the same
> source of truth as your other codebases!

To use `jddf-codegen` in a TypeScript codebase, it's recommended that you call
`jddf-codegen` from a `package.json` script. For example, let's say you have a
codebase that hooks like this:

```text
my-sweet-package        // the root of your package
├── package.json        // you'll invoke jddf-codegen in here
├── message.jddf.json   // your JDDF schema
└── src                 // where you put your TypeScript code
    ├── index.ts        // where you'll import the generated code from
    └── message         // a directory for containing generated code
        └── index.ts    // jddf-codegen will generate this file
```

In this example, your schema is in `message.jddf.json`. Let's pretend it
contains this:

```json
{
  "definitions": {
    "user": {
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" }
      }
    }
  },
  "properties": {
    "messageId": { "type": "string" },
    "timestamp": { "type": "timestamp" },
    "details": {
      "discriminator": {
        "tag": "type",
        "mapping": {
          "user_created": {
            "properties": {
              "user": { "ref": "user" }
            }
          },
          "user_deleted": {
            "properties": {
              "userId": { "type": "string" }
            }
          }
        }
      }
    }
  }
}
```

Then you invoke `jddf-codegen` from a script in your `package.json`, like this:

```json
{
  "scripts": {
    "jddf-codegen": "jddf-codegen --ts-out=src/message -- message.jddf.json"
  }
}
```

That will generate code that looks like this:

```typescript
export interface User {
  id: string;
  name: string;
}

export interface AnalyticsDetailsUserDeleted {
  type: "user_deleted";
  userId: string;
}

export interface AnalyticsDetailsUserCreated {
  type: "user_created";
  user: User;
}

export interface Analytics {
  messageId: string;
  timestamp: string;
  details: AnalyticsDetailsUserDeleted | AnalyticsDetailsUserCreated;
}
```

So from your hand-written code, you can import this as so:

```typescript
import { Analytics } from "./message";

// If you happen to know that `data` is JSON valid against a JDDF schema, then
// you can safely cast it into Analytics. And then you can enjoy type-safe and
// auto-completed code!
const data = JSON.parse(...);
const analyticsEvent = data as Analytics;

// This is type-checked now:
switch (analyticsEvent.details.type) {
  case "user_deleted":
    console.log("user deleted", analyticsEvent.details.userId);
  case "user_created":
    console.log("user created", analyticsEvent.details.user.id);
}
```