cuetsy

README

Installation · Usage

cuetsy

Converting CUE objects to their TypeScript equivalent (highly experimental!)

• CUE makes defining and validating canonical data specification easy
• TypeScript is dominant in the frontend, but cannot natively benefit from this
• CUE types often have direct TypeScript equivalents, so cuetsy can bridge this gap

Example

CUE	TypeScript
DiceFaces: 1 | 2 | 3 | 4 | 5 | 6 @cuetsy(kind="type") Animal: { Name: string Sound: string } @cuetsy(kind="interface") LeggedAnimal: Animal & { Legs: int } @cuetsy(kind="interface") Pets: "Cat" | "Dog" | "Horse" @cuetsy(kind="enum")	export type DiceFaces = 1 | 2 | 3 | 4 | 5 | 6; export interface Animal { Name: string; Sound: string; } export interface LeggedAnimal extends Animal { Legs: number; } export enum Pets { Cat = "Cat", Dog = "Dog", Horse = "Horse", }

Status

Cuetsy is experimental. The following are supported:

• Types
  • Unions
  • Interfaces
  • Enums
• Default const

Installation

Cuetsy can be installed using Go 1.16+

$ go install github.com/grafana/cuetsy/cmd/cuetsy

Usage

cuetsy must be invoked on files as follows:

$ cuetsy [file.cue]

This will create a logically equivalent [file].ts

Alternatively, cuetsy can be used as a library for more customized code generation.

Union Types

CUE	TypeScript	@cuetsy(kind)
Disjunction	Union Type	type

Union types are expressed in CUE and TypeScript nearly the same way, namely a series of disjunctions (a | b | c):

CUE	TypeScript
MyUnion: 1 | 2 | 3 | 4 | 5 | 6 @cuetsy(kind="type")	export type MyUnion = 1 | 2 | 3 | 4 | 5 | 6;

Interfaces

CUE	TypeScript	@cuetsy(kind)
Struct	Interface	interface

TypeScript interfaces are expressed as regular structs in CUE.

Caveats:

• Default generation does not work correctly for optional nested structs. Issue

CUE	TypeScript
MyInterface: { Num: number Text: string List: [...number] Truth: bool } @cuetsy(kind="interface")	export interface MyInterface { List: number[]; Num: number; Text: string; Truth: boolean; }

Inheritance

Interfaces can optionally extend another interface. If a type marked for export as a kind="interface" is unified (whether by & or embedding) with another type marked for export as an interface, it will produce extend in output:

CUE	TypeScript
AInterface: { AField: string } @cuetsy(kind="interface") ByUnifying: AInterface & { BField: int } @cuetsy(kind="interface") ByEmbedding: { AInterface CField: bool } @cuetsy(kind="interface")	export interface AInterface { AField: string; } export interface ByUnifying extends AInterface { BField: number; } export interface ByEmbedding extends AInterface { CField: boolean; }

Enums

CUE	TypeScript	@cuetsy(kind)
Disjunction	String enums, String enums	enum

TypeScript's enums are union types, and are a mostly-exact mapping of what can be expressed with CUE's disjunctions. Disjunctions may contain only string or numeric values.

For string enums, the member names (keys) of the TypeScript enum are automatically inferred as the titled camel-case variant of their string value, but may be explicitly specified using the memberNames attribute. For a numeric enum, memberNames must be specified.

CUE	TypeScript
AutoCamel: "foo" | "bar" @cuetsy(kind="enum") ManualCamel: "foo" | "bar" @cuetsy(kind="enum",memberNames="Foo|Bar") Arbitrary: "foo" | "bar" @cuetsy(kind="enum",memberNames="Zip|Zap") Numeric: 0 | 1 | 2 @cuetsy(kind="enum",memberNames="Zero|One|Two")	export enum AutoCamel { Bar = 'bar', Foo = 'foo', } export enum ManualCamel { Bar = 'bar', Foo = 'foo', } export enum Arbitrary { Zap = 'bar', Zip = 'foo', } export enum Numeric { One = 1, Two = 2, Zero = 0, }

Defaults

CUE	TypeScript
Defaults	const

Cuetsy can optionally generate a const for each type that holds default values. For that, mark CUE Default Values to your type definitions:

CUE	TypeScript
MyUnion: 1 | 2 | *3 @cuetsy(kind="type") MyEnum: "foo" | *"bar" @cuetsy(kind="enum") MyInterface: { num: int | *6 txt: string | *"CUE" enm: MyDisjEnum } @cuetsy(kind="interface")	export type MyUnion = 1 | 2 | 3; export const defaultMyUnion: MyUnion = 3; export enum MyEnum { Bar = 'bar', Foo = 'foo', } export const defaultMyEnum: MyEnum = MyEnum.Bar; export interface MyInterface { enm: MyDisjEnum; num: number; txt: string; } export const defaultMyInterface: Partial<MyInterface> = { enm: MyDisjEnum.Bar, num: 6, txt: 'CUE', };

Documentation

Index

• func Generate(val cue.Value, c Config) (b []byte, err error)
• func GenerateAST(val cue.Value, c Config) (*ts.File, error)
• func NoImportMappingErr(d *ast.ImportDecl) error
• type Concreteness
• type Config
• type ImportMapper
• type KV
• type NewConfig
• type TypeMapper

Functions

func Generate

func Generate(val cue.Value, c Config) (b []byte, err error)

Generate takes a cue.Value and generates the corresponding TypeScript for all top-level members of that value that have appropriate @cuetsy attributes.

Members that are definitions, hidden fields, or optional fields are ignored.

func GenerateAST

func GenerateAST(val cue.Value, c Config) (*ts.File, error)

func NoImportMappingErr

func NoImportMappingErr(d *ast.ImportDecl) error

NoImportMappingErr returns a standard error indicating that no mapping can be made for the provided import statement.

Types

type Concreteness

type Concreteness int

Concreteness is a measure of the level of concreteness of a value, where lower values mean more concrete.

Replicated from cuelang.org/internal/core/adt

const (
	BottomLevel Concreteness = iota

	// Concrete indicates a concrete scalar value, list or struct.
	Concrete

	// Constraint indicates a non-concrete scalar value that is more specific,
	// than a top-level type.
	Constraint

	// Type indicates a top-level specific type, for instance, string,
	// bytes, number, or bool.
	Type

	// Any indicates any value, or top.
	Any
)

type Config

type Config struct {
	// ImportMapper determines how CUE imports are mapped to Typescript imports.
	// If nil, any non-stdlib import in the CUE source will result in a fatal
	// error.
	ImportMapper
}

Config governs certain variable behaviors when converting CUE to Typescript.

type ImportMapper

type ImportMapper func(*ast.ImportDecl) (string, error)

An ImportMapper takes an ImportDecl and returns a string indicating the import statement that should be used in the corresponding typescript, or an error if no mapping can be made.

type KV

type KV struct {
	K, V string
}

type NewConfig

type NewConfig struct {
	// Subpath is the path within the cue.Instance that cuetsy should treat as the
	// root object to be rendered. Optional.
	Subpath cue.Path

	// Self indicates that, rather than rendering all the attribute-annotated
	// children of provided instance, the instance itself should be rendered.
	Self bool

	// InjectCuetsyAttrs is an optional set of attribute bodies to be dynamically
	// injected onto values as they're being rendered.
	//
	// The keys will be passed to cue.ParsePath(). The value will be treated as
	// the body of a @cuetsy attribute (@cuetsy(<value>)) for values encountered at
	// that path, relative to the root.
	InjectCuetsyAttrs map[string]string
}

type TypeMapper

type TypeMapper interface {
	Value() cue.Value
	Kind() cue.Kind
	Concreteness() Concreteness
	String() string
}

TypeMapper is a general interface to describe a mapping between cue.Value and typescript kinds and types. Will necessarily need to omit expressions.