search

devexperts / swagger-codegen-ts

Typesafe Swagger API generator for TypeScript
Mozilla Public License 2.0
80 stars 16 forks source link

Setup monorepo with lerna #53

Open raveclassic opened 4 years ago

raveclassic commented 4 years ago

As the codebase grows, new languages and specs are added, to better control tests and builds we need to turn the project to monorepo and split the code into several subpackages:

Suggestions are welcome.

/cc @sutarmin @scink

sutarmin commented 4 years ago

I like the overall idea, monorepo fits here very good.

But as it's called swagger-codegen-**ts** isn't it supposed to work only with typescript? 😅Moreover, we could have different types of typescript "decoders" (e.g. with io-ts and without them). For these reasons, I think the language directory should be named different.

raveclassic commented 4 years ago

isn't it supposed to work only with typescript?

-ts stands for being build on top of fp-ts

Moreover, we could have different types of typescript "decoders" (e.g. with io-ts and without them)

Not sure we need it. io-ts is our idiomatic way of serialization/deserialization/validation arbitrary structures.

For these reasons, I think the language directory should be named different.

Any suggestions? template? Personally I don't like it because it's not a "template" but a fully valid typescript function:

type Language<A> = (
  out: string,
  documents: Record<string, A>,
  resolveRef: (ref: string) => Either<unknown, unknown>,
) => Either<unknown, FSEntity>
sutarmin commented 4 years ago

-ts stands for being build on top of fp-ts

Then it's just an implementation detail and not worth mentioning in the name (IMO, of course).

io-ts is our idiomatic way of serialization

That's cool, but does this mean that we can't use our codegen tool for projects without io-ts?

raveclassic commented 4 years ago

and not worth mentioning in the name

It's a convention

does this mean that we can't use our codegen tool for projects without io-ts

io-ts is an implementation detail. I'd also move it from peerDependencies to dependencies section because peers do not guarantee that the lib will work with any version of io-ts but they say that it will work with at least io-ts@^2.0.1 which can be safely moved to dependencies and this will free end projects of dependency management burden.

sutarmin commented 4 years ago

It's convention among fp-ts ecosystem, not for every library that uses it. Did I get it right that you think that every library that used fp-ts must end with -ts? That sounds as weird for me as if every library that uses jquery would end with -jq. Naming things is hard and maybe it's not that important, but I find that confusing.

io-ts is an implementation detail

It's not the point. If the next project will not use io-ts, does this mean it can't use swagger-codegen-ts? I think we can, right? But we'll need to write a generator for that and put it next to the default one (which uses io-ts). How to distinguish them then?

btw, what do you think about the idea of naming entities (and directories as well) as generators? Because the language part is a bit misleading since it could be different generators for the same language, but what they basically do is generating file structure by the internal format of swagger-codegen.

raveclassic commented 4 years ago

Naming things is hard and maybe it's not that important, but I find that confusing.

If so should we rename @devexperts/remote-data-ts to @devexperts/remote-data then? Things should we consistent. This naming is consistent in terms of existing convention.

does this mean it can't use swagger-codegen-ts

No it does not. All you need to use codegen is to pass a codec/language pair which should not necessarily be an io-ts, it should only be structurally identical. This codegen tool ships with 2 spec decoders (swagger 2 and openapi 3) and 2 languages (typescript for swagger 2 and typescript for openapi 3). You can either choose from them or write your own.

generators

They are not "generators" but "serializers", they do not generate anything but serialize a spec.

sutarmin commented 4 years ago

If so should we rename @devexperts/remote-data-ts to @devexperts/remote-data then?

OK, I got your point. I thought that remote-data-ts is a part of the ecosystem and for swagger-codegen fp-ts is just an implementation detail. But since we are exposing API with involves fp-ts data types, then we could say that it's a part of the ecosystem as well, fine ;)

You can either choose from them or write your own.

Fine, does this mean that if we will decide to write a serializer without io-ts, we won't add it to this library, but will keep it in the end-project codebase? That's what my example is about. We could have different serializers for the same language, so it's not only about language+spec.

They are not "generators" but "serializers"

Ok, I'm good with serializers, I just don't like current languages.

raveclassic commented 4 years ago

We could have different serializers for the same language

That won't make much sense since language templates are tied to schema types and codecs and we already have working codecs for that types.

Ok, I'm good with serializers, I just don't like current languages

ok

raveclassic commented 4 years ago

Choosing names we should also think about https://github.com/devexperts/swagger-codegen-ts/issues/61 - this makes codegen spec-agnostic meaning that it's not only http/swagger/openapi only.

sutarmin commented 4 years ago

Shouldn't it be just parsers & serializers then? And the whole process goes like spec -> parser -> common internal codegen format -> serializer -> code.

raveclassic commented 4 years ago

LGTM What about package name?

raveclassic commented 4 years ago

Maybe @devexerts/codegen? What about subpackaging?

sutarmin commented 4 years ago

Actually, I just thought that the swagger part is not true about this package already cause it's been renamed :) And also maybe we can think of a shorter name? Smth like specgen-ts. We need to brainstorm it with the team 😃

raveclassic commented 4 years ago

specgen-ts says that the lib generates specs :) ok, if we're following fp-ts convention, then @devexperts/codegen-ts? Again, what about subpackaging? What names should we pick for separate parser and serializer packages? And evenmore do we really need to separate them? If yes what about repeating parts/utils?

raveclassic commented 4 years ago

What about @codegen-ts/<package>?