Feature: Remove indentation from description fields

[davewasmer]

trafficstars

The description option available on most (all?) decorators is a fantastic tool for adding documentation in a way that plays nicely with the rest of the GraphQL tooling ecosystem.

A minor frustration with this feature is the fact that some of these other tools render the description as Markdown (a perfectly reasonable feature for those tools). However, given how most people likely write out longer descriptions in their Typescript source, the result that a regular description is treated like a code block:

class Foo {

  @Field({ description: `
    Some long
    multiline description
    or perhaps haiku?
  `})
  bar: string;

// Results in description = "\n    Some long\n    multiline description ...

Because of the source code indentation, the multi-line string has four spaces before each line, which markdown treats as a code block, and renders with whitespace: nowrap, resulting in this:

from GraphQL Voyager

Describe the solution you'd like The description value passed to each decorator should have any base level indentation removed (i.e. indentation present on every line - purposeful indentation should be preserved).

Describe alternatives you've considered Don't do anything and leave this up to the user. That's my current solution, and it's certainly working. It's just a minor annoyance to remember to wrap every description field with some kind of stripIndentation call.

Or, ask tools like GraphQL Voyager to either:

• Don't render as Markdown. This is a non-started, since it's undoubtedly a useful feature
• Render as Markdown, but they do the indentation stripping. That could work, but it feels like it's slightly more the responsibility of whatever is generating the description fields to generate accurate values.

Additional context Happy to PR this, but didn't want to jump the gun if you'd rather leave it userland.

[MichalLytek]

I'm not sure about that. I don't think that TypeGraphQL should care about this details as they can be simply done using 3rd-party packages: https://github.com/declandewet/common-tags#oneline

Also, we can't turn on removing indentation by default. So we would need another field in config like stripIndentation: true which is much more verbose than simple:

import { oneLine } from "common-tags";

@ObjectType()
class Foo {
  @Field({ description: oneLine`
    Some long
    multiline description
    or perhaps haiku?
  `})
  bar: string;
}

[davewasmer]

Yep, that totally makes sense.

But I'd suggest that, while this certainly could be done by external libraries, I think there's an argument to be made that the current approach (keeping indentation) doesn't actually serve anyone's use case.

If there's no valid use case for keeping the indentation, then I would suggest the default behavior be to strip it. This would remove the need for the more verbose stripIndentation option.

All that said - I'm very aware of the "death by a thousand cuts" that can come from supporting a hundred of these small features, so understandable if you'd rather leave to users. But figured it wouldn't hurt to check!

---

And for any future Googlers out there, I'm using the dedent package for this, which strips the leading indentation while preserving line breaks.

[MichalLytek]

the current approach (keeping indentation) doesn't actually serve anyone's use case.

As you see, other tools parse indented description as a markdown, so there might be many users that use this feature.

I'm using the dedent package for this

common-tags has stripIndent too 😉

You are the first one with this issue after a year of TypeGraphQL. So if someone suffers from the same problem, please 👍 the first post to let me know if you need this feature.

[davewasmer]

As you see, other tools parse indented description as a markdown, so there might be many users that use this feature

Let me clarify - the leading indentation on every line doesn't serve a purpose. I didn't mean to suggest stripping all indentation and/or newlines - just the leading indentation that doesn't seem valuable in any use case.

You are the first one with this issue after a year of TypeGraphQL. So if someone suffers from the same problem, please 👍 the first post to let me know if you need this feature.

Sounds like it's not something you'd like to add right now. Bummer, but understandable. Thanks for hearing me out! Feel free to close the issue if you'd prefer.