`satisfies` should work with imported / referenced values

[matthew-dean]

Suggestion

Right now, satisfies works on values and object literals right after they're declared. However, there are use cases when satisfies can't be used immediately, and the value is imported, such as JSON files.

🔍 Search Terms

JSON, typed JSON, satisfies JSON

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

In short, I'd like to be able to do this:

import book from 'book.json'

const foo = book satisfies BookResource

or, alternatively:

import book from 'book.json' with { satisfies: BookResource }

and have it work equal to:

const book = {
  // book fields
} satisifies BookResource

📃 Motivating Example

I have this structure in my book data JSON file:

{
  "data": [
    {
      "type": "book",
      "baseCode": "394b76ce-3ad9-4c83-b21d-d5eab7962249",
      "id": "394b76ce-3ad9-4c83-b21d-d5eab7962249",
      "url": "http://github.com/donec/dapibus/duis/at.jpg",
      "originalUrl": "http://qq.com/ante/ipsum/primis.json",
      "imageUrl": "http://dummyimage.com/246x100.png/5fa2dd/ffffff",
      "retailer": "Amazon",
      "title": "Dead End Drive-In",
      "author": "Vlad Cutmore"
    },
    {
      // more of the same schema
    }
  ]
}

And I have a type (interface) like:

interface BookResource {
  id?: string
  type: 'book'
  baseCode: string
  imageUrl: string
  title: string
  author: string
  originalUrl: string
  retailer: string
  url: string
}

(Note, in this scenario, the source data MUST be JSON.)

I want to make sure that if anyone modifies the JSON, they get a type error. However, doing the following results in an error:

import books from 'books.json'
// ...
const bookData = books.data satisfies BookResource[] // error - "Type {...} is not assignable to BookResource"

Now, I wasn't sure if this should be marked as a bug or feature request, because this works:

const blah = {
  type: 'book',
  baseCode: '394b76ce-3ad9-4c83-b21d-d5eab7962249',
  id: '394b76ce-3ad9-4c83-b21d-d5eab7962249',
  url: 'http://github.com/donec/dapibus/duis/at.jpg',
  originalUrl: 'http://qq.com/ante/ipsum/primis.json',
  imageUrl: 'http://dummyimage.com/246x100.png/5fa2dd/ffffff',
  retailer: 'Amazon',
  title: 'Dead End Drive-In',
  author: 'Vlad Cutmore'
} satisfies BookResource

In other words, the exact same value data, when applied with the satisfies keyword, causes an error depending on where the value is being checked, even though it's the same value.

What seems to be the case is that satisfies gently coerces the type (specifically to "book" instead of string) in the latter example, but fails to do so when the value is imported.

💻 Use Cases

Currently, I want to use this for JSON, but note that there are other cases where you might want to "check" and gently nudge the type at compile time the exact same way that happens with satisfies at assignment time.

Because, similar to the above example, this also causes an error:

const foo = {
  type: 'book',
  baseCode: '394b76ce-3ad9-4c83-b21d-d5eab7962249',
  id: '394b76ce-3ad9-4c83-b21d-d5eab7962249',
  url: 'http://github.com/donec/dapibus/duis/at.jpg',
  originalUrl: 'http://qq.com/ante/ipsum/primis.json',
  imageUrl: 'http://dummyimage.com/246x100.png/5fa2dd/ffffff',
  retailer: 'Amazon',
  title: 'Dead End Drive-In',
  author: 'Vlad Cutmore'
}
const bar = foo satisfies BookResource

In TypeScript / JavaScript terms, these should be equivalent statements, and TypeScript should be able to

1. say that the value of foo satisfies the type of BookResource
2. coerce bar to be of type: "book" vs type: string, just as it would if satisfies immediately followed the value.

1st note: obviously I could just use as BookResource instead of satisfies BookResource, but of course that bypasses the type-checker entirely, and defeats the purpose. Then, the JSON could have any data / shape whatsoever, with no errors provided.

2nd note: I can also sorta get there with satisfies Array<Omit<BookResource, 'type'> & { type: string }> but that's kind of gross, and I want to enforce that the type truly is "book" and not just a string. JSON type inference is helpful but it isn't perfect, and currently there's no way to actual tell it how to interpret string literal types.

[RyanCavanaugh]

It seems like this does what you want? What falls short here?

import book from 'book.json';
book satisfies BookResource;

I don't think we want to mix-and-match TS and ES syntax in import any more than we have to, especially when the equivalent desugared code is extremely similar.

[jcalz]

I think this is probably morally a duplicate of #32063 (to import a json module "as const")

(@RyanCavanaugh the type property needs to be the string literal type "book" in the example, but that won't happen)

[matthew-dean]

@RyanCavanaugh Here is a reduced test case: https://www.typescriptlang.org/play?#code/JYOwLgpgTgZghgYwgAgEIHt0GsAqBPABxQG8AoZZMQiALmQHIAjTLe0gX1NIXRAGcwyGJmQBeZGQpUidJizadSw9Mj5wwwPjGAQ+aFviJcgA

X satisfies Y as a statement would be great if it worked, but it doesn't.

[matthew-dean]

@jcalz

I think this is probably morally a duplicate of

It's partly the same core problem / bug / issue, I guess you could say, which is that TypeScript's type inference of object shapes is often useful and also, often wrong, and there's no real option to coerce the types, except to completely override the type into any possible invalid interpretation of the type, which doesn't solve anything.

The surprising discovery that I don't think was covered in the documentation write-ups on satisfies is that it actually changes / coerces the type, instead of being simply a type of type check assertion. Since that is part of the behavior of satisfies, then IMO it makes more sense to be able to coerce (and check) the type using satisfies on any value, rather than importing as const because that's incredibly limited.

So IMO the linked issue is talking about a very narrow part of the problem, and discussing a solution that won't actually address that problem fully.

[RyanCavanaugh]

often wrong

By "wrong" here do you just mean "is less specific than I would have like to be inferred" ? Or is there an actual "it says it's a string but it's actually a number?" instance?

[matthew-dean]

@RyanCavanaugh Well, what I mean is more that the satisfies statement:

1. says an object doesn't conform to an interface when it does, depending on where it is declared or checked
2. coerces a value into the satisfies type in some circumstances and rejects it as a mis-matched type in others

The fact that satisfies coerces the type at all was counter-intuitive to me, because I thought it was just a syntax for validating the type. But because it has that behavior, it would be useful for coercing the type of a JSON file to the expected type.

[RyanCavanaugh]

I mean, sure, but you wouldn't want it to not do that, because then a bunch of assertions that you would want to succeed would fail.

[matthew-dean]

@RyanCavanaugh Correct. I'm not suggesting changing satisfies existing behavior. I'm suggesting keeping this coercion consistent with any other value, referenced or imported, so extending satisfies to any value, not just a value at the original definition time.

[matthew-dean]

i.e. I would be overjoyed if this worked:

import book from 'book.json';
book satisfies BookResource;

If that's all it took for book to be coerced to BookResource, just as it would be inline, that would be wonderful.

[matthew-dean]

@RyanCavanaugh @jcalz We can close this if #32063 tracks this better. I just didn't want to completely derail if people are attached to the idea of as const (although I would argue that wouldn't completely solve the problem).

[RyanCavanaugh]

I think these are separable and both valuable. The scenario of a middle ground between the entire blob being const, which is often way too specific, and just getting the inferred type, which might not be as specific as you want, makes sense.

[jcalz]

If we had as const then you could import the json that way and widen to whatever type you wanted in a different variable. (Well, you would, if readonly arrays were actually subtypes of mutable arrays and not the other way around.) That might be less ergonomic than satisfies for this use case, but it would at least be possible. Right now we only have the inferred type, or something you just claim is the type from a .json.d.ts file as mentioned in #49703 (comment)

Oh, that reminds me that this could also be "morally equivalent" to #52994 (which is clunkier than this suggestion, imo).

I don't know that any of these should be closed as duplicates of each other, but I think they are all circling around the same unmet need to allow something like a type annotation for imported json. I'd hate for those who want that to split their vote among particular flavors of the feature, if it lowered the likelihood of any of them being implemented.

[matthew-dean]

I think they are all circling around the same unmet need to allow something like a type annotation for imported jso

In this case, JSON is the primary use case, yes, but there are actually a number of related TypeScript issues of wanting to narrow the type within a block scope without sending it through an assertion function, or when a type inferred through an object value satisfies two types but TypeScript insists it doesn't, because it's already set the object's inferred type in stone.

A possible solution, then, might also be simply that TypeScript:

1. Infers a set of "type candidates" which it can narrow through satisfies, and/or
2. Doesn't throw an error of a mis-matched type when it's an inferred type and not an explicit one, and/or
3. TypeScript does the above only with inferred JSON, since type annotation is (currently) impossible.

#2 is probably a little too complex and might have unexpected consequences, but it violates the Law of Least Surprise at least a little bit, when TypeScript says that an object with a string literal value cannot be assigned to a variable or passed to a function that's expecting the type of an object with that very same string literal. i.e. the concrete value can match the expected type perfectly, which should be passable, except that the inferred type does not match. So the problem is both the nature of inference, and the nature of type checks.

[matthew-dean]

Really, this issue is more fundamental than objects or JSON, as demonstrated by this playground example, in which the behavior of satisfies is (IMO) highly inconsistent (regarding whether or not it coerces types). But also the variables of first and second should be passable, because their values are statically analyzable (otherwise a type of string wouldn't have been inferred in the first place).

So, in addition to this issue, which is like a feature request, I would suggest there's also a satisfies bug, in which it sometimes coerces a type, and sometimes doesn't.

Also, can I point out that the TypeScript documentation has this to say:

The new satisfies operator lets us validate that the type of an expression matches some type, without changing the resulting type of that expression

That was how I understood satisfies, but that statement is demonstrably false. It does change the resulting type of the expression (but only sometimes!), as demonstrated in multiple examples here. So I'm not sure if the behavior of satisfies should be expanded (to all values) OR it should be "corrected" (to not coerce types) OR if the documentation should be changed. I'm really not sure what satisfies is supposed to do, because whatever it does do, it does inconsistently.