Switch from class to class-like to include all types in commander namespace

[shadowspawn]

Pull Request

Problem

TypeScript errors in some client use cases because not all types are exported. See #1037

Solution

Rework to use class-like interfaces and constructors rather than explicitly using class so all the types can be included in the commander namespace. (This is made hard by the existing default export of the global Command object so can not use multiple exports or export explicit classes.)

This is beyond my TypeScript comfort zone! We might need a TypeScript expert to confirm this is a reasonable approach.

[shadowspawn]

@alan-agius4 (#646)
@jsamr (#713)
Thanks for your past contributions to the Commander TypeScript declaration file.

In case you are interested, I have a PR in flight and would welcome any feedback from TypeScript contributors.

I have done a refactor to get the Command and Option types fully into the commander namespace to fix a reported bug. I did a lot of reading and trial and error, but I seem to have it working nicely now with a manual class-like declaration (interface + constructor).

All my attempts to use a true class failed and my understanding is declaring a class adds a value (the constructor) to the otherwise type-only namespace, which then conflicts with the export of the global command object. I expect this same problem is why Command and Option were originally outside the namespace, then moved into a separate namespace to allow aliasing the types.

[alan-agius4]

this LGTM

[shadowspawn]

Thanks @alan-agius4 !

[jsamr]

@shadowspawn I think grouping all the declarations in the same namespace is a good idea, and I was a bit skeptical with the former local namespace, and I would guess it would fix #1037 . I just wonder however why you had to get rid of class declarations in favor of instance interface + constructor interface + constant declaration? It's OK, but a bit over-engineered.

[shadowspawn]

With the single export =, adding a class to the namespace causes an error. Stripped down example:

declare namespace commander {
  class Foo {
  }
}
declare const commander: object
export = commander;

error TS2300: Duplicate identifier 'commander'.

[jsamr]

@shadowspawn This is expected :-) The namespace is a value! A POJO which fields are the names of declared values.

So you should get rid of declare const commander: object and you'll be all good.

EDIT You can read that nice page to get what I mean: Definition File Theory: A Deep Dive

Also, I can submit a PR to your fork if you don't grasp it, but I would recommend trying as it is a great exercise to grow your typing muscles 💪 .

[jsamr]

@shadowspawn see my edited answer above

[shadowspawn]

Thanks @jsamr. I did consult the TypeScript documentation, especially the Declaration Files pages, and the Deep Dive was indeed one of the most relevant pages.

My understanding is the previous and PR solution allow a single export to include both meanings of commander, the "value" which is the global program object, and the (non-value) "namespace" which includes the supporting "types". The shape of the global program object is the Command class/interface with a few additions.

I am not sure how to declare the global/default program object without exporting a "value" for it. Did you have a pattern in mind?

For example, client code could look like:

import * as commander from 'commander';
commander
   .name('global-program');
const myProgram = new commander.Command();
myProgram
   .name('local-program');

[jsamr]

@shadowspawn Now I get it. Typescript cannot merge a constant value with a namespace which has values within, such as classes. So your trick is perfectly legitimate 🙂

LGTM! 👍

[shadowspawn]

Thanks @alan-agius4 and @jsamr