Documentation misleading on void encompassing null?

[aseemk]

TypeScript Version: 2.0.3

Code

With --strictNullChecks:

let x: string | void = 'hello';
let y: string | void = undefined;
let z: string | void = null;

Expected behavior: compiles, since the documentation states:

However, when using the --strictNullChecks flag, null and undefined are only assignable to void and their respective types.

https://www.typescriptlang.org/docs/handbook/basic-types.html#null-and-undefined

Actual behavior: the last line fails to compile:

[eval].ts (3,1): Type 'null' is not assignable to type 'string | void'. (2322)

Rationale: is there a less verbose way, with --strictNullChecks, to specify a type like string | null | undefined? i.e. Is there a type that covers both null and undefined?

[mhegazy]

is there a less verbose way, with --strictNullChecks, to specify a type like string | null | undefined? i.e. Is there a type that covers both null and undefined?

no. We could not find a way to do that that is not confusing to some users. see #7426.

if you really want to define something like this, i would recomend adding

type Optional<T> = T | null | undefined;

[aseemk]

Thanks for the quick answer and link!

So consider this issue just an issue to clarify the documentation then.

[donaldpipowitch]

Just stumbled over this. I always thought that void would be a union type of null and undefined and wondered why this throws with --strictNullChecks:

interface Foo {
  bar: void;
}

// Type 'null' is not assignable to type 'void'. 
const f: Foo = {
  bar: null
};

So what is void exactly for --strictNullChecks? Just an alias to undefined?

if you really want to define something like this, i would recommend adding

type Optional<T> = T | null | undefined;

Any idea to add something like this to the lib.*.d.ts files? Or as:

type Optional<T> = {
    [P in keyof T]?: T[P] | null | undefined;
};

Or a real common union type for null and undefined? type voidlike = null | undefined;?

[aluanhaddad]

I think that an issue here is that while technically JavaScript doesn't have any notion of void functions, having void in the type system is actually useful catching certain logic errors.

That said, returning null from a void function absolutely needs to be a type error. Returning undefined and returning without a value result in the same runtime behavior. The caller gets undefined.

[KaelWD]

Just an alias to undefined?
Returning undefined and returning without a value result in the same runtime behavior

Yet void cannot be assigned to undefined

declare function returnsUndefined(): undefined
declare function returnsVoid(): void

const nothing: void = returnsUndefined() // works
const nothing2: undefined = returnsVoid() // Type 'void' is not assignable to type 'undefined'.

Looks like there's more on this over at #20006

[karlhorky]

Just found a similar issue #16075, will do a PR to fix the docs.

Edit: PR open: microsoft/TypeScript-Handbook#1053