TypeScript: `unknown`: less-permissive alternative to `any`

I like the idea of differentiating “trust me, I know what I’m doing” from “I don’t know what this is, but I still want to be safe”. That distinction is helpful in localizing unsafe work.

Conditional types are making a true top type more necessary. Some offline discussion summary.

Can unknown be narrowed? If so, by what?

function fn(x: unknown) {
    if (Array.isArray(x)) {
        // OK, or no?
        const arr: any[] = x;
    }
}

Yes, this is half of the entire point of the feature. Particulars:

• The primitive guards typeof x === "string" should narrow x to string
• User-defined type guards like Array.isArray(x) should work as well
• The instanceof operator narrows to the instance type of the RHS
• if ("p" in x) { narrows x to { p: unknown }

Openish questions?

• Does x > 0 imply any narrowing?
• Do we need to do anything with x === y ? Presumably you would just use y at that point?
• What does if (x) { do?
• What does if (!x) { do?
• Would (x === "foo") || (x === "bar") to narrow x to the union type "foo" | "bar" ? What are the practical limits of this kind of narrowing?

Can you access properties of an unknown and/or call it?

No. Allowing “chained” unknown bad because it implies you could unsafely write x.y.z.

What does { [s: string]: unknown } mean?

We currently have special behavior around { [s: string]: any }; unknown gets the same behavior: Anything is assignable to { [s: string]: unknown }.

Is unknown assignable to any?

Yes, necessarily - type guards are presumably written accepting any.

Is unknown assignable to {} in non-SNC mode?

Yes.

Is unknown assignable to anything else?

No.

Is everything assignable to unknown?

Yes.

What is the meaning of unknown & T ?

T

What is the meaning of unknown | T ?

unknown

What’s the type of x! ?

object | string | number | boolean ?

For anyone interested, there’s a good deal of related discussion about the pros/cons of any and {} in #9999. The desire for a distinct unknown type is mentioned there, but I really like the way @seanmiddleditch has presented it here. I think this captures it brilliantly:

Where any is the escape hatch out of the type system, unknown is the well-guarded and regulated entrance into the type system.

Being able to express a clear distinction between trusted (any) and untrusted (unknown) data I think could lead to safer coding and clearer intent. I’d certainly use this.

Have not seen it mentioned here, but this proposal looks quite similar to the mixed type in Flow.

I’m closing #23838 and posting my thoughts in here. Proper top would only be useful if:

• Everything is assignable to unknown
• unknown can be assigned to nothing unknown & T = T unknown | T = unknown unknown extends T ? true : false = false (in other words, follow assignability rules)

This agrees exactly with Ryan’s post.

No matter what fringe use cases, these kinds of types are used often inside of very complex mapped conditionals, etc, and every special case needs to be checked, so it’s important that the type acts very “purely mathematical”. There’s some weird behavior with never that doesn’t fit the name at times, but the reason it’s usable, is because it’s pure. I use never more than any other type because of that reason.

@Conaclos

function f <T> (x: T): x is ComplexType & T {
    // Check for ComplexType.
}

This code is equivalent to yours. No need for unknown, except as a hint to the programmer that there might be more to the type. That small hint is not worth making the type useless as a top type.

I think a huge improvement would already to make it possible to narrow any with type guards. @ahejlsberg this for example does not work:

const json = await resp.json()
if (Array.isArray(json.errors) && json.errors.length > 0) {
  throw Object.assign(new Error(json.errors.map(e => e.message)), { errors: json.errors })
}

json.errors is still any after the Array.isArray() check, instead of any[]. So I could mistype .length, I don’t get autocompletion for json.errors.map() etc.

I think the request here is for unknown to be { } | null | undefined, but be allowed to “evolve” as you assert/assign into it.

Beyond simply adding an alias for unknown, it’d be really nice if core APIs were modified to return unknown where appropriate: e.g. JSON.parse returning unknown and Array.isArray(x) would be a type guard for x is unknown[]. (Rather than x is any[])

Obviously, those would be breaking changes, but perhaps that can be avoided by putting this can be put behind a strict-mode flag? If the flag was off, unknown would be treated as any, which would maintain backwards compatibility.

Without a flag, I think this’ll be a nice “best-practice” utility to use in application code, but won’t get much traction in libraries, which will likely not want to introduce a major backwards-compatibility break.

I just followed @marcind 's link above, and I think it’s a nice and simple write-up of the case for unknown (called mixed there), and the different case for any, which many mistake for the top type. It also mentions refinements as simply being what typescript calls type guards.

mixed types

mixed will accept any type of value. Strings, numbers, objects, functions– anything will work. […] When you try to use a value of a mixed type you must first figure out what the actual type is [with a type guard] or you’ll end up with an error.

any types

If you want a way to opt-out of using the type checker, any is the way to do it. Using any is completely unsafe, and should be avoided whenever possible.

By this definition, unknown is equivalent to {} | undefined | null, but that’s fine with me if we can have a single named and documented top type that is not unsafe like any.

I just want a proper top type. DefinitelyTyped is full of examples where any is used as a top type, but that’s obviously wrong because libraries should not be in a position to turn off type checking in client code, which is what any does in output positions.

I’m not sure if this is what @RyanCavanaugh was referring to with the SBS comment ‘Would hopefully remove a lot of confusion from DefinitelyTyped’.

If there was a simple top type unknown, then that would be the obvious type to use in many scenarios that currently use any, the difference being that it doesn’t disable type-checking.

Additionally, if you can’t trust the type, how are you supposed to know it’s even callable

I’m not sure I follow your example or reasoning.

An example use of {[key: any]: unknown} would be the Request.body object in Express, assuming a suitable body parser.

I know the body objects exists and I know it has properties. Its typing today however is just any and that suffers from all the problems outlined by the sea of discussion above: it’s easy to write code that just assumes that a body parameter exists or is of a given type. That is, the followoing compiles without warning: const foo: string = req.body['foo']. However, correct code would need to use some kind of validation function that ensures that key foo exists and is of the correct type.

It’s safe to assume that body is trusted (it is provided by the application/library) but not safe to assume that the contents of body are trusted (they are user-provided).

Suggestion: drop unknown keyword, and apply “the ability to evolve” feature to {} itself.

That would limit cognitive load and proliferation of ‘exception’ types like never, unknown, any, void etc. But also it would force people to spell null-ability when it comes to the alien data.

Evolvability

The currently existing {} type, and intersection with it will get an extra feature, being “evolvable”.

Evolvable means you can probe its properties liberally without casting. Probing means accessing property in special known positions:

var bla: {};
if (bla.price) console.log("It's priced!");   // GOOD, we **probed** price
console.log(bla.price);                       // BAD, we're **using** price, which isn't safe
if (bla.price) console.log(bla.price);        // GOOD, we **probed**,  then we can use

Probing works very similar to type assertions, and in a conventional JS coding style too. After a property is probed, the type of the expression changes to {} & { property: any; }, allowing immediate use of the property as in the last line of the example above.

I suggest these three supported ways of probing:

// non-null probing,      asserts {} & { property: any; }
if (bla.price) console.log("priced!");

// property probing,     asserts {} & { property: any | null | undefined }
if ('price' in bla) console.log("priced!");undefined; }

// typed probing,         asserts {} & { property: type; }
if (typeof bla.price==='number') console.log("priced!");}

// custom assert probing, asserts {} & { property: type; }
if (isFinite(bla.price)) console.log("priced!");

Intersection

It’s crucial to allow “evolability” to more than just one selected type, but intersections too. Consider multi-property asserts that naturally come out of it:

if (bla.price && bla.articleId && bla.completed)
  acknowledgeOrder(bla);

No unknowns please

Lastly I want to highlight the real danger of unknown keyword:

unknown undefined

Those two are way too similar, and be confused in all sorts of situations. Mere typos would be a big problem in itself. But factor in genuine long-term misconceptions this similarity would inevitably breed.

Picking another, less similar keyword might help, but going straight for an existing syntax is much better.

The point of {} in the first place is to mark values we don’t know properties of. It’s not for objects without properties, it’s objects with unknown properties. Nobody really uses empty objects except in some weirdo cases.

So this extra sugar added on {} would most of the time be a welcome useful addition right where it’s helpful. If you deal with unknown-properties case, you get that probing/assertion evolvability intuitive and ready. Neat?

UPDATE: replaced unions with intersections up across the text, my mistake using wrong one.*

The idea of introducing a property in the refined type after offering proof of its existence and type in a type guard is definitely interesting. Since you didn’t mention it I wanted to point out that you can do it through user-defined type guards, but it obviously takes more typing than your last example:

interface AccountData {
  id: number;
}

function isAccountData(obj: any): obj is AccountData {
    return typeof obj.id === "number";
}

declare function reifyAccount(data: AccountData): void;

declare function readUserInput(): Object;

const data = readUserInput();  // data is Object
if (isAccountData(data)) {
    reifyAccount(data);  // data is AccountData
}

The advantage to this approach is that you can have any sort of logic you want in the user-defined type guard. Often such code only checks for a few properties and then takes it as proof that the type conforms to a larger interface.

No matter what fringe use cases, these kinds of types are used often inside of very complex mapped conditionals, etc, and every special case needs to be checked, so it’s important that the type acts very “purely mathematical”.

This.

@neoncom

I want a compiler option to make me aware of any “any” occurances that I may be unknowingly using.

This tslint rule might help: https://palantir.github.io/tslint/rules/no-unsafe-any/

Ack, so I disappear for a little while and this exploded. 😃

Having now read (cough skimmed) the bazillion comments, I do think that Flow’s mixed is exactly what I’m after. I don’t use or know Flow but the documentation indicates the behavior I’m seeking.

I agree that the subscripting behavior I originally spelled out is a bad idea as it’s too permissive and defeats the purpose. For the use cases that involve an object with open subscripting, specifying a type of {[key: any]: unknown} would work just fine; likewise for arrays of unknown type, {[index: number]: unknown}.

If type unknown = {} | undefined | null would work, that’s totally fine by me. I’ll give it a go from Type Zoo when I get a chance and see if it handles the various use cases I have handy. I can’t think of any reasons right now why it wouldn’t work and it’s definitely the simple solution. 😃

Assuming it works (and I think it will), adding some type aliases to the core library along the lines of unknown would suffice for me. Maybe also adding in aliases for {[key: any]: unknown} and {[index: number]: unknown} too. 😃

@saschanaz Flow’s mixed is basically this proposal’s unknown (or what it evolved to be in the comments, at least). The only difference is the name.

I think the idea from OP is this:

declare function foo(input: number): void;
declare var bar: number;

function processUnknown() {
  var o: unknown; // we don't know its type...
  o.baz // okay, but please be careful...
  o.baz() // okay, use `o` like `any` in your *local* area.

  foo(o); // NOOO you don't know the type of `o` so please please do not pass it!
  bar = o; // No, DO NOT SPREAD the type unsafety

  if (typeof o === "number") {
    foo(o); // Yes!
  }
}

Summary: Play with your unknown toy in your room, not in the entire house.

I really don’t like this. It removes a level of type safety in the language, and it would especially show up when you have large numbers of boolean flags on an object. If you change the name of one, you might miss one and TypeScript wouldn’t tell you that you did, because it’s just assuming you’re trying to narrow the type instead.

On Wed, Oct 26, 2016, 08:52 mihailik notifications@github.com wrote:

Suggestion: drop unknown keyword, and apply “the ability to evolve” feature to {} itself.

That would limit cognitive load and proliferation of ‘exception’ types like never, unknown, any, void etc. But also it would force people to spell null-ability when it comes to the alien data. Evolvability

The currently existing {} type, and union with it will get an extra feature, being “evolvable”.

Evolvable means you can probe its properties liberally without casting. Probing means accessing property in special known positions:

var bla: {};if (bla.price) console.log(“It’s priced!”); // GOOD, we probed price console.log(bla.price); // BAD, we’re using price, which isn’t safeif (bla.price) console.log(bla.price); // GOOD, we probed, then we can use

Probing works very similar to type assertions, and in a conventional JS coding style too. After a property is probed, the type of the expression changes to {} | { property: any; }, allowing immediate use of the property as in the last line of the example above.

I suggest these three supported ways of probing:

// non-null probing, asserts {} | { property: any; }if (bla.price) console.log(“priced!”);if (‘price’ in bla) console.log(“priced!”); // property probing, asserts {} | { property: any | null | undefined; }if (typeof bla.price===‘number’) console.log(“priced!”); // typed probing, asserts {} { property: type; }if (isFinite(bla.price)) console.log(“priced!”); // custom assert probing, asserts {} { property: type; }

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/Microsoft/TypeScript/issues/10715#issuecomment-256337526, or mute the thread https://github.com/notifications/unsubscribe-auth/AERrBDdp6AGkgsZTHdn8g0pzWMBdS1-gks5q300RgaJpZM4J1Wzb .

@SaschaNaz Your understanding matches mine, too.

declare function send(x: number)
let value: unknown

send(value) // error
send(value as any) // ok
if (typeof value === "number") {
  send(value) // ok
}

On Wed, Sep 28, 2016, 19:11 Kagami Sascha Rosylight < notifications@github.com> wrote:

@RyanCavanaugh https://github.com/RyanCavanaugh

If I understand correctly:

let x;declare function sendNumber(num: number);

sendNumber(x); // legal in any sendNumber(x); // illegal in unknown and {} if (typeof x.num === “number”) { sendNumber(x.num); // legal in any and unknown, illegal in {} }

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/Microsoft/TypeScript/issues/10715#issuecomment-250327981, or mute the thread https://github.com/notifications/unsubscribe-auth/AERrBO-yD4Qdc605NubmW6yKrBXH5ZFTks5quvQUgaJpZM4J1Wzb .

@isiahmeadows any is universally assignable both to and from all other types, which in the usual type parlance would make it both a top type and a bottom type. But if we think of a type as holding a set of values, and assignability only being allowed from subsets to supersets, then any is an impossible beast.

I prefer to think of any more like a compiler directive that can appear in a type position that just means ‘escape hatch - don’t type check here’. If we think of any in terms of it’s type-theory qualities, it just leads to contradictions. any is a type only by definition, in the sense that the spec says it is a type, and says that it is assignable to/from all other types.

Do we need to do anything with x === y

~I think this should be an error when one is unknown and the other is T, for some type-variable.~

No it should have the same behaviour as x == y, when one is {} | undefined | null, and the other is T. I forgot that there are different cases for when the concrete type contains {}, instead of just being number | boolean, for example.

In my head those cases should be the same but they aren’t, hence my initial incorrect comment.

In this example:

function fn(x: unknown) {
    if (Array.isArray(x)) {
        // OK, or no?
        const arr: any[] = x;
    }
}

Does x get narrowed to unknown[]?

What would be nice if an option in the compiler could exist that would replace any “any” type from 3rd party declarations or generelly all typescript code with this new “unknown” type. Often some “any” types just slip in and you have no way of knowing, ever – until a bug comes up. Any one with me on this? Yes I want a compiler option to make me aware of any “any” occurances that I may be unknowingly using.

Using any is completely unsafe, and should be avoided whenever possible.

I like this 👍

Sounds better to file a new issue for mixed?

An author can at least be sure that any unsafe object is not being passed around.

A bug is a bug is a bug 🤷‍♂️ The value of that half measure is not at all clear to me. Meanwhile the cost seems high: yet another magical non-type like any and void with its own peculiar semantics, a complexity multiplier on the type system. And after all that we still wouldn’t have a true top type!

Why is the first any better than the second though?

An author can be sure that any unsafe object is not being passed around.

We already have type guards/predicates for the purpose of evolvability… that seems to me an orthogonal concern from having a standardized strict top type, which is what I want from unknown.

A top type like this unknown would be immensely useful for type safety reasons. It gets old typing {} | void each time.

Also note that {} naturally fits with strictNullChecks story — and with my suggestions it continues to do so neatly. Meaning it follows stricter checks when option is enabled, and gets relaxed when it isn’t.

Not necessary the case with unknown:

var x: unknown;
x = null    // is it an error?   you would struggle to guess, i.e. it impedes readability

var x: {};
x = null;    // here the rules are well-known

This could use clarification with some more examples – it’s not clear from the example what the difference between this type and any are. For example, what’s legal to do with any that would be illegal to do with unknown?

With {}, any, {} | null | undefined, the proposed but unimplemented object, and never, most use cases seem to be well-covered already. A proposal should outline what those use cases are and how the existing types fail to meet the needs of those cases.