Enable literal type access to MIME types in Typescript - #339

Hi Matt, thanks for the PR.

Can you give me an example or two of how this is useful? I'm not familiar with satisfies, so I don't really understand what problems this solves.

Hi Robert,

No worries, of course.

1. The problem and what this PR fixes

As this was explicitly typed as {[key: string]: string[]}, it meant that literal types could no longer be inferred by Typescript.

Take the following example:

function checkMIMEType(file: File, type: string) {
    return file.type === type;
}

I could use this function as follows:

checkMIMEType(someFile, "text/xml");

However, it would be extremely useful if I could use a literal type for the type parameter as the following would never be true:

❌ We don't want to allow:

checkMIMEType(someFile, "some string") // ⚠️ Would always be false because the type parameter isn't a MIME type

checkMIMEType(someFile, "txt/xml") // ⚠️ Would always be false as there is a typo in the MIME type (type parameter)

✅ Instead, we want to allow:

checkMIMEType(someFile, "text/xml"); // ✅ since "text/xml" is a valid MIME type in the database

Given this library, I wouldn't want to create my own database of possible MIME types, so the solution should be:

import standardTypes from "mime/types/standard.ts";

type MIMEType = keyof typeof standardTypes; // ✅ MIMEType must be one of the keys in the database

function checkMIMEType(file: File, type: MIMEType) {  // 🎉 `type` is not just any old string anymore
    return file.type === type;
}

What this PR solves is that, where the type was set to {[key: string]: string[]}, then keyof typeof standardTypes was always a string, not explicitly one of the available MIME types, which is what we want. So to achieve this, {[key: string]: string[]} should be removed, resulting in:

Before:

After:

So now:

checkMIMEType(someFile, "some string");
// ❌ Before: Typescript would allow, because "some string" is a string
// ✅ After: Typescript will not allow, because "some string" isn't one of the MIME types

checkMIMEType(someFile, "txt/xml");
// ❌ Before: Typescript would allow, because "txt/xml" is a string
// ✅ After: Typescript will not allow, because "txt/xml" isn't one of the MIME types

checkMIMEType(someFile, "text/xml");
// ⚠️ Before: Typescript would allow, because "text/xml" **is a string**
// ✅ After: Typescript will allow because "text/xml" **is recognised as a MIME type**

This was not possible before.

2. Maintaining the type safety of the database (satisfies)

Using Typescript's satisfies retains the type constraints as applied on the original database, in spite of the fix:

❌ We don't want:

// If I remove the type specification on `types`, then I could put anything in as a value:
const types = {
    // ...
    "text/xml": 78459387453 // ⚠️ Valid when {[key: string]: string[]} isn't specified as the type
}

✅ Instead we want:

// If I remove the type specification on `types`, but add a `satisfies` constraint, then I can only put something valid in as a value:
const types = {
    // ...
    "text/xml": 78459387453 // ❌ Typescript error: 78459387453 does not satisfy type "string[]"
} satisfies {[key: string]: string[]}

I then noted that the database is made readonly by Object.freeze(), but would you believe, Typescript pays no attention to this.

❌ We don't want:

import standardTypes from "mime/types/standard.js"

standardTypes["application/json"] = ["something else"] // ⚠️ Valid in Typescript, even if it is not possible at runtime because of `Object.freeze()`

✅ Instead we want:

// /types/standard.ts

const types = {
    // ...
} as const satisfies Readonly<{[key: string]: string[]}>

&

import standardTypes from "mime/types/standard.js"

standardTypes["application/json"] = ["something else"] // ❌ Not valid in Typescript because this is a readonly field

Hence the {[key: string]: string[]} type definition was removed, and the trailing as const satisfies Readonly<{[key: string]: string[]}> definition has been added.

Hope that helps!

Matt

Great explanation, thank you.

So... next question: Is this a semver "patch", "minor", or "major" (breaking) change?

(I'm tempted to say it should be major because it changes the TS api types in a way that may break tsc compilation for users. But... it doesn't actually change the JS api.)

I would say this is a minor update per the SemVer spec. 😁

My reasoning:

• The type of the databases haven’t changed, it’s just enforced in a different way
• Therefore these types are backwards compatible, since the databases must still ”satisfy” {[key: string]: string[]}
• New functionality is enabled
• A bug (related to Object.freeze()) is patched

Published as [email protected]

Thanks for the contribution. I particularly appreciate the time you took to explain everything. 👍

You’re welcome. Happy to help and great to see it merged! 😁🎉