asarazan / martok Goto Github PK

Home Page: https://www.npmjs.com/package/martok

TypeScript 59.54% JavaScript 1.88% Kotlin 38.58%

martok's Introduction

Martok - Glory To Your Schema!

Martok is built for one thing and one thing only: converting Typescript schemas into kotlinx.serialization schemas. It's the brutal and chaotic rival to Dukat.

Why Kotlin? Why Typescript?

We've always been big believers in Kotlin Multiplatform for Mobile -- but also recognize the (well-earned) dominance of Node on the backend. Martok creates an automated schema pipeline from the Typescript in your backend codebase to the Kotlin data layer in your Android & iOS apps.

Why Not QuickType?

QuickType has gotten quite old and difficult to develop. The PRs have mostly stagnated, we currently cannot find a way to successfully build the project, so we've moved on.

Can I see some example output?

Sure! Check out the comparison files we use for our automated tests HERE.

For a quick example:

export type Unions = {
  foo: { bar: string } | { baz: string };
};

Would translate to

@Serializable
data class Unions(
    val foo: Foo
) {
    @Serializable
    data class Foo(
        val bar: String? = null,
        val baz: String? = null
    )
}

Installation

npm install -g martok

Usage

# Martok works with single files, directories, and always infers the right thing to do.
martok ./someFile.d.ts -o Schema.kt --package example
martok ./someDirectory -o BigSchema.kt
martok ./someDirectory -o ./outputDirectory # produce lots of little files.

SUPPORTS

Multiple source files
Output to multiple files or a single mega-file
Interfaces + Inheritance
Type Aliases + Intersections + Unions
string, number, boolean, Arrays, any
Anonymous types
Cross-references to other types
kotlinx.serializable
kotlinx.datetime (When annotated with @Date or @DateTime. See HERE for examples)
Custom package name
Enums
optional fields
Typescript "Utility" types (e.g. Omit and Pick)
Configurable numeric precision via the @precision jsdoc tag

TODO

Zod (this is so hard - PRs accepted!)
Fully discriminated/disagreeing unions
documentation
Intended for .d.ts files. Work on safer execution for .ts

martok's People

Contributors

Stargazers

Watchers

martok's Issues

Import generator doesn't properly follow type aliases

🤦

generated files should say they're generated in docs

Do an overhaul on newline formatting logic

It ugly

Need to escape numbers inside string literals

eg foo: "1" | "2" will end up creating invalid enum member names.

Add underscores to enum member names

Tagged unions can generate confusing "duplicate" classes.

The tagged union generator creates a great sealed class cluster, but if the types it's referencing are declared/named elsewhere in the codebase, it does not delete those types from the output, causing some very confusing and similarly named classes, which are ripe for user error. You can see the failing tests in the https://github.com/asarazan/martok/tree/fix/vestigial_code branch.

Some possible approaches:

Delete the node from input as soon as we know it'll be in a tagged union

This is tricky because A) It's order-dependent and our compiler is single-pass, and B) it doesn't guarantee that other sections of the code aren't doing weird things with that reference in their own right. We could try walking all references and swapping them for the tagged version, but that might not be provably correct in all cases.

Delete the kotlin class from the output

It might actually be simpler to let the compiler do its magic and then erase/postprocess the undesired classes out of existence before returning. It shares some drawbacks with above, and has an added complication of "not all paths return klasses, some return strings (we kludged out on things like typedef).

Just do the multiple-pass upgrade already

Please no 😭

Just let folks know that if they don't want extraneous output, they should declare the unioned types anonymously

I fully admit that this kinda sucks, and becomes an overly prescriptive constraint on how backend organizes their code. I don't like it much either.

Enable custom date logic via jsdoc rather than name regexes.

This should follow a similar pattern as the @precision feature.

it'd be nice to have generated enums instead of string literals when disambiguating union types

When union types share a property of type string that's used to disambiguate them, it'd be nice if enums were automatically created.

Here, a union type is used to generate a sealed class, and the property actionType is used to disambiguate them:

The generated file looks like this:

It'd be great if there was a nested enum class called ActionType. That way we could create simple switch statements to go through the different possible types. And also when checking for the actionType, we wouldn't need to compare strings which would be brittle and prone to refactoring errors.

Seeing random `__type` show up in various places.

That's the keyword for type literals so I'm just not guarding against it in some single spot

Update to latest kotlinx serialization

Research what happens with `Omit<Foo, "bar">`

Who knows!

Sanitize dirnam hyphens in resultant package names

eg if a file is in a directory foo-bar it will create a subpackage like com.example.foo-bar which is invalid in kotlin.

Figure out why there are slashes in the package imports.

e.g. import net.sarazan.martok.Users/asarazan/foo/bar/src/types.Baz

Look into problems with Top Level array item types

I believe there have been a couple cases of it failing to properly generate the items for an array at top-level

TaggedUnionGenerator doesn't properly create imports

Research alternatives to default Kotlin name-mangling for collisions in ObjC

Kotlin's current strategy is to simply add a bunch of underscores. See here: JetBrains/kotlin-native#2467

We may want to implement our own collision algorithm, or some command line switch, or maybe we just need to advise folks to be careful in their typescript. Who knows!

Compiler error if you have a data class with empty constructor

This is newly risen thanks to the recent tagged union changes. It's probably not a super useful class, but we at least don't want it to throw errors.

typedef for simple types fails

Repro: export type Float = number;

Nested array types should probably be called `FooItem` instead of `Foo`

Convey comments/jsdoc into kotlin declarations

Still some weird formatting

https://github.com/asarazan/Tangent-Mobile/blob/main/shared/src/commonMain/kotlin/social/tangent/mobile/api/entities/Preferences.kt

Can't properly translate string | string[]

generated kotlin sealed classes from typescript unions allow multiple types for a property when only one is valid

If a sealed class is generated from type unions, sometimes the property can only have one valid type (like a specific case in an enum), but that's not reflected in the generated class.

For example, this typescript file for type SketchyUpdate will generate the kotlin sealed class SketchyUpdate with an inner type SketchyUpdateLifecycleEvent:

SketchyUpdateLifecycleEvent.actionType can only be ActionType.LIFECYCLE_EVENT, but that's not reflected in the generated class, and it is possible to initialize the class with the wrong ActionType.