shanahanjrs / typebuf

Dead simple way to create shared type definitions between applications

TypeBuf

---

Dead simple way to create shared type definitions between applications

• Other tools have too much setup? Too much boilerplate? Do too much "magic"? Just:
  • Define your Types in types.yaml
  • Run TypeBuf: $ typebuf compile -f types.yaml -l python -l typescript

Install

pip install typebuf

poetry add --dev typebuf

Quickstart

1. Create a file called types.yaml, it can be anywhere in your projects repo

2. Add the following lines to the newly created file:

---
typedefs:
  - typename: User
    imports:
      python:
        - 'from typing import Optional'
    fields:
      - name: first_name
        type: string
      - name: age
        type: int
        optional: true

3. Now call TypeBuf with: $ typebuf compile -l python -l typescript

4. You now have two new files, one called user.py and one called user.ts that can you use for things like data serialization/deserialization, validation, subclassing, etc

Generated Python:

"""
User type definition file generated by TypeBuf
Note: Any changes made to this file will be overwritten
      during next compilation
"""

from typing import Optional


class User:
    first_name: str
    age: Optional[int]

Generated TypeScript:

/**
 * User type definition file generated by TypeBuf
 * Note: Any changes made to this file will be overwritten
 *       during next compilation
 */

interface User {
  first_name: string;
  age?: number;
}

Note: So far only Python and TypeScript are supported. More languages coming soon!

Demo

Here's a quick demo of me using TypeBuf 0.1.1. First I show the contents of the types.yaml file then I generate Python and TypeScript source code and show the contents of the new files

Documentation

• Inside types.yaml there is an array called typedefs. This is where you add your shared type definitions

• Each type can have the following fields (required fields in bold):

  • typename: string
  • imports: map[string, array[str]]
  • fields: array[Field]
    • A Field has the following attributes:
      • name: string
      • type: string
        • a type can be any one of:
          • any
          • string
          • int
          • float
          • boolean
          • bytes
          • date
          • datetime
          • map
          • array
          • tuple
          • null
          • double
          • sint8
          • sint16
          • sint32
          • sint64
          • uint8
          • uint16
          • uint32
          • uint64
        • union types are also experimentally supported:
          • int | string
      • optional: boolean

• In a type definition you can also specify custom/required imports for any depedencies your classes may need:

  • ---
    typedefs:
      - typename: Address
        imports:
          python:
            - 'from mymodule.user import User'
            - 'from typing import Optional'
          typescript:
            - 'import { User } from "./User";'
        fields:
          - ...,