Use non-nullable types in vscode.d.ts

[jrieken]

TypeScript will introduce support for strict null check and explicit handling of null and undefined - microsoft/TypeScript#7140. This is a great opportunity for us to make the API more explicit and hopefully a chance to prevent programming errors. Parts of the API can move from jsdoc comments into type annotations. For instance, the active editor is declared like this today:

/**
 * The currently active editor or `undefined`. ...
 */
export let activeTextEditor: TextEditor;

and we can move jsdoc type info back into code like so

/**
 * The currently...
 */
export let activeTextEditor: TextEditor | undefined;

[jrieken]

depends on TypeStrong/typedoc#234

[jrieken]

@egamma @dbaeumer Looking for some guidance here. Challenge is that many of the providers define method return types ala Foo | Thenable<Foo>. The current behaviour (spec'd in jsdoc) is that they are allowed to return undefined or null sync or async from with in the promise. That results in the following, very verbose, strict-null-aware signature:

// option 1a, inline
interface CodeLensProvider {
  provideCodeLenses(document: TextDocument, token: CancellationToken): CodeLens[] | undefined | null | Thenable<CodeLens[] | undefined | null>
}

// option 1b, inline but even more verbose
interface CodeLensProvider {
  provideCodeLenses(document: TextDocument, token: CancellationToken): CodeLens[] | undefined | null | Thenable<CodeLens[]> | Thenable<undefined> | Thenable<null>
}

// option 1c, one type for null or undefined
type Nully = null | undefined;

interface CodeLensProvider {
  provideCodeLenses(document: TextDocument, token: CancellationToken): CodeLens[] | Nully | Thenable<CodeLens[] | Nully>
}

// option 2, generic result-type
type Result<T> = T | undefined | null | Thenable<T | undefined | null>

interface CodeLensProvider {
  provideCodeLenses(document: TextDocument, token: CancellationToken): Result<CodeLens[]>
}

// option 3, generic nullable-type
type Nullable<T> = T | undefined | null;    

interface CodeLensProvider {
  provideCodeLenses(document: TextDocument, token: CancellationToken): Nullable<CodeLens[]> | Thenable<Nullable<CodeLens[]>>
}

Options 2 and 3 have the advantage that they can be applied to all providers and make a shorter method signature. On the downside that add another indirection and might make things harder to understand... Tho, also option 1 isn't exactly easy to read and understand. I'd prefer option 1c

[dbaeumer]

@jrieken hard call: I would actually go for 2.) and name it ProviderResult. Using Nullable makes it bound to nullable. If TS comes up with another feature we might need to change the signature again. With ProviderResult we might be able to simple change that type then.

[bpasero]

+1 for option 2 (generic result-type)

[joaomoreno]

I'd combine 2 and 3, each a different problem in itself, but composable with each other:

type Maybe<T> = T | undefined | null;
type Result<T> = Maybe<T> | Thenable<Maybe<T>>;

interface CodeLensProvider {
  provideCodeLenses(document: TextDocument, token: CancellationToken): Result<T>;
}

[aeschli]

Wanted to suggest Optional<T> but actually like Maybe<T> even better.
+1 for option 3 with Maybe<T>.
I'd rather not combine it with 2, too many types, and, especially, 'Result' is too general.

[joaomoreno]

type Eventually<T> = Maybe<T> | Thenable<Maybe<T>>;

😄