Allow JSDoc comments to temporarily overwrite certain CLI options

[ViSaturn]

It would be nice if we could have JSDoc comments that could temporarily overwrite certain options provided by src/cli.ts for the type that the JSDoc comment is for.

Like in src/cli.ts you could have:

  {
    description: 'Path to `tsconfig.json`.',
    name: 'project',
    type: String,
    typeLabel: '{underline file}',

    JSDocCanControl: false // < here
  },
  {
    alias: 'd',
    description: 'Include debug logs in generated type guards.',
    name: 'debug',
    type: Boolean,

    JSDocCanControl: true // < here
  },

Then you could have:

/* @see {isIWantToDebugONLYThis} ts-auto-guard:debug */
interface IWantToDebugONLYThis {
  a: "awesome"
}

isIWantToDebugONLYThis({a: "actually not awesome :("})

or something similar to the above

I would be willing to open a PR for this, I'm just looking for some thoughts on this first.

[rhys-vdw]

The original idea is that the second have of ts-auto-guard:<here> is for generating a type guard or something else, but currently the project only supports type guards (and I have kind of cooled off on the idea of it supporting any other generation). Since debug mode is only for development I don't see a strong benefit for doing it per-type (since you'd just regenerate everything anyway before release).

[download13]

@ViSaturn Is there another use-case for this? The idea of being able to change options on a per-type basis sounds potentially worthwhile, but debug mode seems like an unlikely thing to use it for since you'd be turning it on and off frequently during debugging, and having it on for all types doesn't seem to have obvious downsides, so making it a file modification seems more cumbersome than helpful.

Looking through the other CLI options I don't see much in the way of good candidates to make into per-type options.

If you have an idea for how exactly an option benefits from this I'd love to hear it. My instinct is that more customizability === better but I can't quite see the utility now.

EDIT: Just saw #202. That's an interesting idea. Will comment there.

[ViSaturn]

@ViSaturn Is there another use-case for this? The idea of being able to change options on a per-type basis sounds potentially worthwhile, but debug mode seems like an unlikely thing to use it for since you'd be turning it on and off frequently during debugging, and having it on for all types doesn't seem to have obvious downsides, so making it a file modification seems more cumbersome than helpful.

Looking through the other CLI options I don't see much in the way of good candidates to make into per-type options.

If you have an idea for how exactly an option benefits from this I'd love to hear it. My instinct is that more customizability === better but I can't quite see the utility now.

EDIT: Just saw #202. That's an interesting idea. Will comment there.

Mainly just this would pair well with #202, it's also nice to have if in the future more CLI options are added.

[download13]

Sudden thought. Would the shortcircuit option be a good candidate for this?

Short-circuiting is something that it might make sense to turn on for only certain type guards.

For example, if you want to use most of your guards, but one in particular has significant performance impact and you're willing to risk it.

type SimpleType = { ... }

/**
  * @see {isSuperComplicatedType} ts-auto-guard:type-guard
  * @see {process.env.NODE_ENV === 'production'} ts-auto-guard:shortcircuit
  */
type SuperComplicatedType = {
  ...
}

The format could use some discussion. There might be a better way of providing multiple options to one type.

[rhys-vdw]

Sudden thought. Would the shortcircuit option be a good candidate for this?

Yeah, that would be.

Although the use of the @see tag doesn't really make sense there. In the case of JSDoc it links to the generated function.

Unless someone is looking for this feature I wouldn't bother, but I agree it's a candidate.