TypeScript: Add a --strictNaNChecks option, and a NaN / integer / float type to avoid runtime NaN errors

It would actually be great to have integer type. As discussed in #195 and #4639, it might help to force developers to do strict conversions and checks when you expect to get an integer value, eg. with math operations (as far as under the hood of JS engines, an internal conversion to integers and back takes place):

let x: integer = 1; // you expect its value to always be an integer
x = 5 / 2; // compile error
x = Math.floor(5 / 2); // ok

It will be great also suggest replace x === NaN to Number.isNaN(x) or isNaN(x) during diagnostics because x === NaN always false and 100% mistake.

n.b. Integer types have already been decided as out of scope (especially now that BigInt is a thing), so what follows only refers to NaN typing. We discussed this at length and couldn’t come up with any plausible design where the complexity introduced here would provide sufficient value in most use cases.

The only reasonably common way to get a NaN with “normal” inputs is to divide by zero; programs that do standard arithmetic should be on guard for this and add appropriate checks the same way you would for handling file existence, lack of network connectivity, etc (i.e. things that are common errors but not enforced by a type system). Once a well-formed program correctly guards its division, any NaN checking that follows is mostly going to be noise. For example, if you write Math.log(arr.length), this can never return NaN, but we only know this because arr.length can’t be negative. Many other functions work in a similar way - to provide these NaNs in useful places we’d have to encode a large amount of data about possible values for numbers (integers, positive, nonnegative, less than 2^32, etc) all over the type system, which is a ton of work that everyone would have to reason about from that point forward for the sake of the relatively small number of programs that encounter unexpected NaNs due to logic errors.

Shouldn’t the terminology be double and not float? I believe JS numbers are actually double precision.

Nitpick aside, an integer type that is backed by number and not bigint would have proven immensely useful for my use case.

My use case is outlined in the below link, https://github.com/AnyhowStep/tsql/blob/adbfcf666ef71be4b6c03567a8d14a88ab699d7c/doc/00-getting-started/01-data-types.md#signed-integer

Basically, SQL has SMALLINT,INT,BIGINT types that correspond to 2,4,8 byte signed integers.

The 2 and 4 byte signed integers could have been represented by an integer type backed by number.

However, I wanted to eliminate a large class of errors where floating-point values are used instead of integer values.

So, I had no choice but to also represent 2 and 4 byte signed integers with bigint.

Also, the LIMIT and OFFSET clauses would have benefited from an integer type, so I can guarantee that numbers with fractional parts are not passed as arguments (during compile-time, anyway)

This could have been solved with branding.

However, I’m strongly of the opinion that branding should be a last resort. Which is why I like this proposal and the range-type proposals so much. Being able to express what we want with only built-in types reduces dependencies on external libraries for complex branding.

If a brand is used, it increases the chance of downstream users having to use multiple differing brands that mean the same thing. (Library A might use {int : void} as the integer brand, library B might use {integer : void} as the integer brand, etc)

I like the idea of having an integer type backed by number but I disagree with how the OP wants the type to be defined.

I would prefer,

//Infinity is now a literal type
declare const inf : Infinity;

//-Infinity is now a literal type
declare const negInf : -Infinity;

//NaN is now a literal type
declare const nan : NaN;

//No change to this type
type number;

type finiteNumber = number & (not (Infinity|-Infinity|NaN));

type integer; //All **finite numbers** where Math.floor(x) === x

I do not like the idea of Infinity, -Infinity, and NaN being part of the integer type. It is very unintuitive and usually not what I (and I assume others) would want.

If someone wants the original proposal, they can just create their own type alias,

type PotentiallyNonFiniteInteger = integer|Infinity|-Infinity|NaN;

With my proposal, number would be the same as finiteNumber|Infinity|-Infinity|NaN.

We would get the following type guards,

• isFinite(x) : x is finiteNumber
• isNaN(x) : x is NaN
• Number.isInteger(x) : x is integer

Also, another reason to prefer my proposed definition for integer is that it follows the Number.isInteger() convention, https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isInteger#Polyfill

Number.isInteger = Number.isInteger || function(value) {
  return typeof value === 'number' && 
    isFinite(value) && 
    Math.floor(value) === value;
};

[UPDATE] I wrote an update earlier on but it got lost to the void because GitHub error’d. Ugh. I am retyping my update below.

Anyway, I re-read the OP and realized I had misunderstood parts of it. The integer proposal I disagree with would only be applied if strictNanChecks is turned off.

I am against the new flag being introduced.

New flags should only be introduced when intentionally breaking changes are introduced. These new types would not break the current behaviour of the number type.

If anyone uses integer,finiteNumber,Infinity,-Infinity,NaN (new types), they should be forced to acknowledge the possibility of Inifinity,-Infinity,NaN,etc. values creeping in to their code and handle it accordingly (with type guards, run-time errors, etc.)

If they do not want to have the compiler warn them about potentially undesirable values, they can stick to using number and live blissfully unaware of impending doom.

Another point that doesn’t seem to have been brought up yet is that allowing NaN as a type literal allows for type narrowing when checking for falsy values:

declare let x: number;

if (!x) {
    // x should be `0 | NaN`, but since `NaN` currently isn't a valid type, x is `number` instead
}

I may have missed something but I don’t see how having “bigint” helps in any way in differentiating integers vs floating point numbers? 🤷‍♂️ As far as I know, bigint is for (very) large numbers (MDN: “represent whole numbers larger than 2^53 - 1”). Bigint values are fully incompatible with both numbers and Math functions, cannot be included in JSON, and probably more caveats that I don’t know of.

Appart from that, Number.isInteger has been part of the language since … I don’t know, but quite some time now. It seems fair that typescript would be able to tell the difference between a number and an integer.

I understand that it may be a lot of work, but integers are a thing. How can people even be ok with the idea of using “number” to type durations, quantities, indexes, or any whole number. 😕

Claiming that developers can handle the thing themselves (but without typescript) sounds wrong to me.

[I will be very incisive here, not because I like to, but because I believe it is unfortunately necessary.]

@c-dinkel there are two important things to respond to the “no compelling scenario” argument / decision method:

1. It is fundamentally a bug-promoting mentality. Waiting for a compelling scenario to appear before trying to get a fundamental aspect of the language right… flies in the face of the sanity of the language. It’s exactly saying “let’s wait for unfinished foundations to cause the practical problems they were bound to, before we consider taking action”. It is, technically, willful ignorance of how much practical benefit ensues from mathematical elegance. For these reasons, I call its past users to please reconsider before using that argument / decision method.

2. I am most confused that the lead architect of TypeScript either:

• could not think of division by zero (even considering such a thing is bordering on insulting) and the ensuing NaN propagation, or
• thinks it’s not an issue in practice (unsurprisingly, it is), or
• thinks TS is fine as a linter, as in: it doesn’t necessarily need to (have the ability to) limit itself to accepting programs that can’t crash at run time. (in this case, in hard-to-debug ways)

And, yes, “compelling scenarios” have been provided. But my point is that it’s crazy that any of that should be needed: the mere idea of unchecked division by zero should suffice.

Has this issue been picked up by the maintainers? It’s surprising to me that a type-checking compiler for JavaScript wouldn’t try to prevent one of the most notorious type issues prevented by nearly every other language, dividing by zero (not sure if TS would need zero and non-zero subtypes in order to be able to typeguard a valid division).

EDIT: I guess I should add that other languages don’t necessarily prevent this at compile time, but they throw errors when it happens. JavaScript fails silently, so it would be great for TypeScript to be able to be able to detect this. But I understand that it requires some significant modifications to the type system.

Is this anywhere close to being fixed?

Nope, after lots of time and many issues this is apparently not considered an actual issue by the maintainers. If you absolutely need this fixed, consider forking TypeScript.

Regardless of whether an integer type is added, I don’t think this form of NaN checking, where two operands known to not be NaN produces a non-NaN number, would be perfect. For example, adding two integers doesn’t necessarily produce another integer:

const int: number = 1e308
if (Number.isInteger(int)) { // This is true
  // int: integer
  const sum: integer = int + int // At runtime, Infinity
  const difference: integer = sum - sum // At runtime, NaN
}

I think it’s not a big enough deal though since TypeScript is already unsound—['a'][1].length has no type errors but throws a TypeError because having undefined checks for array access is annoying—and the type systems of most other languages such as Rust don’t check for integer overflows, so there’s not really a need to require checks on the programmer’s side for large floating point integers

Also, using the name float or double to mean “not NaN nor an Infinity” might be misleading because NaN and the Infinities are valid floating point values in other programming languages. I’m not really sure what values would be a realNumber but not a float, but I think using realNumber/real or finite would probably be a better name for a such a set of numbers

While I don’t think it is good to implement such fundamental language features on an as-needed basis[1], the question @CrimsonCodes0 asks does deserve a proper answer, which was not given in the reply above.

1. It is useful to be able to prove that a function does not return NaN. I think that needs no justification but here it is for completeness: this would allow, compile-time, to avoid hard-to-debug runtime crashes that are due to a division by zero (or other) that produces NaN, and causes a confusing error very far away from the code that creates this NaN value initially.

2. It is useful to be able to tell the compiler we do want a function that can return NaN, exactly when we want to handle it later, not here, in a function whose type is exactly one that disallows NaN as a return value.

Errare humanum est. Without strict checks, Murphy’s law reigns!

[1] This is because all code written before the availability of basic features in the language will have to use workarounds or be unsafe, and will need to be rewritten when the language fixes that flaw, which it now needs to do with some amount of backwards compatibility with the workarounds in question. All that code working around missing language features will not be refactored using the new feature right away, or at all, because that has a cost. All in all, introducing language features as the need arises creates technical debt orders of magnitude higher, as well as “good practices” that will be obsoleted by introducing the language features proper.

We need this in order to specify a function that has to return NaN on purpose in specific cases. If we returned another number, like 0, we could declare it as:

function example(): string | 0 {
...

but sadly we can currently not declare the function as returning:

function example(): string | NaN {
...

so we have to fall back to the very loose definition

function example(): string | number {
...

It would be greate to see this new rule in TypeScript 4.0

Having to use 1.0 for floats is an idiom from some other programming languages that shouldn’t be forced onto TypeScript users for no good reason.

The “good reason” is allowing users to take advantage of a type system.

A frequent problem I’m running into is that, with WASM, there’s no way to signal to consumers in JS whether an interface accepts signed/unsigned integers, floats, etc. Users have to read the source or guess and check as TS can’t provide any useful info beyond “it’s a number of some sort”, which is a shame. Being able to specify, precisely, what kind of number is allowed is really important as TS branches out to describe interfaces beyond plain JS.

// x should be `0 | NaN`

And also -0 should be there 😆

The only thing that distiguishes -0 from 0 (i.e. +0) is SameValue equality, which is leveraged only in Object.is, so I’m actually not sure it can be supported in TS (or worth it), but then we can’t say it’s completely “strict” number type checking if we don’t support -0.

I can’t believe this has not been implemented yet. NaN is one of the most runtime-error-prone thing in JS, which could (and must) be avoided by static typing. That’s the very purpose of TypeScript, isn’t that?

@c-dinkel Are there any particular reasons that you’re using NaN for that value? Could you elaborate on what your function actually does, and in what case it is returning NaN? Is it your function or just a type definition for an arbitrary JS function? Would you be willing to consider string | null instead, or throwing an exception?

While in this particular case a value is needed that compares falsely to itself, there are other cases where NaN is necessary for other reasons. Imagine, for example, a numeric calculation that returns 0 | 1 | 2 | 3 | NaN , I’d really want to be able to express that.

And no, I’m not willing to consider changing the runtime semantics of the program just to make tsc happy at compile time. Also, what if I’m trying to add types to an external library I don’t control?

Since there is a function called Number.isFinite(), I suggest use finite instead of realNumber as the name of the type for real numbers.

I just want to be able when I write 1.0 and its not suppossed to be float to get an error in typescript and i want if the type is float to have to make it 1.0. Is that not possible?

It’s idiomatic in JavaScript to just use 1 instead of 1.0 even in cases where it’s used as a real number rather than an integer (e.g. setting image quality, media volume, canvas shapes, etc). Having to use 1.0 for floats is an idiom from some other programming languages that shouldn’t be forced onto TypeScript users for no good reason. We already have special syntax for bigints, anyways

@anematode well there are two objectives; I’ll concentrate on avoiding runtime type errors caused by NaN. Checking every operation is necessary, and this is exactly what TypeScript does by construction: operations (operators) are functions, and TS checks that function signatures match their calls. That’s actually already the main selling point of TS.

Thankfully, new compiler features like range analysis can remain out of the picture to do this.

This can be implemented only by introducing a more stringent number type or compiler option and adding a few signatures, which will in turn make TS reject programs that lack the proper guard conditions before potentially dividing by zero and so on.

The only reason I can imagine TS maintainers getting cold feet at the idea, is that at first glance they might think it will result in several operation modes and break backwards compatibility, but with new types it doesn’t have to!

I believe this would help solve #47347 / #15135.

@yuhr also, 1 / -0 !== 1 / 0. -0 exists in JS, it’s a thing.

@yuhr perhaps the typescript developers need help with this because it’s too hard to do? Or financial support if microsoft doesn’t provide enough?

More realistically, most likely it’s precisely because corporate priorities are orthogonal to software quality that this is not on the roadmap. Many such projects (this includes Rust) tend to forget/tone down their initial goals like this: instead of failing the compile if the program isn’t provably safe, which was the initial objective, TS is becoming more of a linter which catches what it can and lets potential errors fly when it doesn’t know.

While we would want it to (at least have an option to) never accept programs that may crash, it is out of ignorance that more novice developers do not care, and simply relay what management asks for: do dangerous things and deal with the consequences later.

Of course, wise developers would rather make sure, at compile time, that no errors are ever possible.
Novice developers, managers and the former under the influence of the latter think that a compromise is possible to reap a lot of benefits with minimum risk; and that’s why modern technology is plagued with bugs.

Well, it’s an all-or-therewillalwaysbeshenanigans choice. I was hoping TS might aim for complete correctness by doing all of the above; perhaps the answer is “not now”, then?

Easy comes with complications; simple comes with complexity.

I think dividing number into integer and float is enough, while dealing with NaN and Infinity you need to look into the values for operators like /, while dealing with integer-float, you need only types.

You can actually do even more than that: there’s int32 which is closed on &, |, ~, ^, <<, and >>, and uint32 which is closed on <<< and >>>. These are totally NaN- and Infinity-safe: NaN << NaN is 0 and 1 << Infinity is 1.

I think this is unsolvable, as a+a is infinity and (a+a)-(a+a) is NaN when a = Number.MAX_VALUE (which is an integer). So NaNs and infinities can creep up into any ordinary integer-only code. You couldn’t call a function passing an arithmetic expression to an integer parameter without casting, so you’d have to do things like f((i+1) as integer), which kinda defeats the purpose of types.

Alternatively, you could define types of arithmetic operations to be unsound (i.e. return integer for integers and ignore overflows), but I don’t think Typescript needs any more unsoundness.

The only things that could be safely done are:

• a type named NotFraction, which would contain integers, infinities and NaNs – preserved by +, -, ++, --, *, |, &, ^, ~,
• a type named NonnegativeNumber, which would contain nonnegative finite numbers (including -0) and positive infinity – preserved by + and ++ (in particular, not preserved by *, / or **, as 0*Infinity, 0/0 and 1**Infinity are NaN),
• analogous NonpositiveNumber (including +0), preserved by + and --,
• a type named PositiveNumber, which would contain positive finite numbers (excluding +0) and positive infinity – preserved by +, ++ and * (in particular, not preserved by **, as 1**Infinity is NaN),
• analogous NegativeNumber (excluding -0), preserved by + and --, and with NegativeNumber * NegativeNumber = PositiveNumber,
• NonnegativeNotFraction = NotFraction & NonnegativeNumber, etc.
• a type named NaN containing NaN, just so Falsy could be defined.

Note there’s no way to guarantee lack of infinity, and no way to have subtraction, division or modulo without NaNs. Also, I don’t think those types should ever be inferred.

Of course I could have made some mistakes above, this is not a serious proposal, as I don’t think those types would be very useful.

@SheepTester made an excellent point above… there’s no sound way to have an integer type or finite type without checking nearly every operation and/or doing sophisticated range analysis. The four main binary floating-point operations can over- or underflow; the only practicable operations to check are those which cast to signed 32-bit.

Despite this limitation, I would really like to see NaN as a type literal, just as an annotation. NaNs are quite useful signaling tools in numeric code.

At the very least, NaN, Infinity and -Infinity should be valid and correctly handled in type positions, since TypeScript can and will emit Infinity and ‑Infinity in type positions: https://github.com/microsoft/TypeScript/issues/42905.

This would also make it possible for TypeScript to produce an error for code like the following:

declare var foo: number;

// @ts-expect-error
if (foo === NaN) {
	// ...
}

Then TypeScript warns that === NaN will always return false and !== NaN will always return true.

Similarly, Number.isNaN could then be defined as:

interface NumberConstructor {
	isNaN(number: unknown): number is NaN;
}

There’s also real world code that relies on returning NaN in a catch clause: https://github.com/engine262/engine262/blob/ab4baf1b1faeae35da022aea6c60a6a824822167/src/abstract-ops/type-conversion.mjs#L404-L415, because the error is handled elsewhere: https://github.com/engine262/engine262/blob/ab4baf1b1faeae35da022aea6c60a6a824822167/src/abstract-ops/type-conversion.mjs#L386-L394.