Documentation generation

[JoshuaWise]

Hi there,

First, thank you for this excellent library. It's great!

I stumbled upon superstruct when searching for a way to define both runtime validation and TypeScript types in one place, without duplication, and without pre-compilation. Superstruct seemed to be the exact answer to that problem. I'm using superstruct to define and validate the input and output of HTTP requests in a REST API. However, I also need to be able to generate API documentation based on the schemas I define.

For example, given this superstruct:

const schema = object({
    name: string(),
    age: nullable(number()),
});

I need to generate documentation like this:

{
    "name": string,
    "age": number | null,
}

I tried writing something to generate this documentation, but I ran into several problems. In general, the Struct class does not contain enough information to make this kind of introspection possible:

• All traces of nullable and optional modifiers are erased
• The structs that make up compound types such as intersection, union, record, and tuple are inaccessible

It would be fantastic if it were possible to inspect the types of a superstruct at runtime like this. The deprecated type would also be extremely useful in generating documentation.

[ianstormtaylor]

@JoshuaWise thanks for opening this. I'm definitely down for improvements to make this easier. Having that information exposed somehow on the structs schemas would be great. Would you be interested in a PR?

[JoshuaWise]

I'm glad to hear you're open to supporting this functionality. Unfortunately, I don't have to bandwidth right now to create a PR for this. Hopefully somebody else who has the time could do that. Or maybe I'll have more bandwidth in the future.

[shellscape]

I had the idea today to automatically create ORM models from a struct definition and was starting to look into the same questions. It occurs to me that really the only way to efficiently tackle this would be to build a simple AST that accompanies any struct. @ianstormtaylor I have some experience working with ASTs and could add that to the project. We're still debating whether or not to stick with a query builder or an ORM, so it's up in the air at the moment, but would an addition like that be welcome? It could open the door to using superstruct for all kinds of alternate document/object generation.

[ianstormtaylor]

@shellscape not completely sure, I'd likely need more information about what you're thinking.

I'm a little wary of trying to solve all the problems JSON schema is designed for, since it seems like a potential rabbit hole. But if there's a low-scope way to solve some of these issues I could be open to it. Having the structs expose their schemas better would be great overall.

[paambaati]

@ianstormtaylor This is something I'm interested in solving too, albeit for a slightly different use-case.

We use superstruct heavily in our backend, and use it to model our DynamoDB data. It is also used as a base for our GraphQL schema.

We're trying to come up with a system that will auto-generate test fixtures for superstruct schema, which we plan to then run tests on (especially for optional fields). This will help us detect subtle changes to the schema.

It would be fantastic if it were possible to inspect the types of a superstruct at runtime

I'm guessing this same feature would help us achieve our goal too.

I'm definitely down for improvements to make this easier. Having that information exposed somehow on the structs schemas would be great. Would you be interested in a PR?

@ianstormtaylor Would you mind helping me? Where do I start? Perhaps a small gist or a snippet might be helpful.