Forem: Omari

ECMAScript vs JavaScript vs TypeScript

Omari — Tue, 05 Mar 2024 10:43:23 +0000

While you’re reading about JavaScript and TypeScript online, you might come across references to some mystical third language — ECMAScript. Think of terms like ES6 or ES2016. ECMAScript is a specification that defines the language features of JavaScript, and therefore TypeScript. Let’s delve into the details.

JavaScript.

So if you’re here you probably already know what JavaScript is, but just in case let’s go through it. JavaScript is a high-level weakly-typed programming language, originally just used for building dynamic web pages, but now becoming increasingly common for general programming and back-end servers. It’s powering 98.8% of websites, so it’s quite popular.

ECMAScript.

ECMAScript is the standard that JavaScript implements. JavaScript did previously have a few siblings that also implemented ECMAScript, like ActionScript and JScript, but JavaScript is pretty much the only one that survived, which is why you’ll see JavaScript and ECMAScript used pretty interchangeably. The name comes from Ecma International, a nonprofit standards organisation for ICT.

ECMAScript defines the language features and syntax, but not things like I/O.

Things ECMAScript does define:

Array methods
Syntax
Operators

Things ECMAScript doesn’t define:

File system handling
DOM manipulation
Networking
Graphics

Since 2015, a new major version of ECMAScript has been published every June. This starts with ECMAScript 2015, or ES2015. You might also see it referred to as ES6, since it’s the 6th major edition of ECMAScript.

You’ll see ES6 mentioned a lot online as it was a significant improvement, adding features like the “let” and “const” keywords, arrow functions, maps and sets, and many more.

So every year a new ECMAScript edition is approved and published by the ECMA General Assembly. Before ES6 there was a new specification more sporadically, every few years. They were referred to by edition, e.g. ES4 or ES5. Following ES6 each version is referred to by the year it was published, e.g. ES6 is ES2015. There’s also ESNext, which refers to whatever the next version is.

ECMAScript features have to go through a 4 stage application process:

Stage 0 is a new proposal
Stage 1 is a proposal under consideration
Stage 2 is where a solution/design gets drafted for a proposal
Stage 3 is where a proposal feature has been tested, and is recommended to be implemented. There’s not likely to be any major changes, but there may still be some minor changes from feedback
Stage 4 is the final stage, and means a feature is complete and ready to be included in the standard

This is all public, by the way. You can follow along with ECMAScript proposals and meeting notes here if you want to take a look at new potential JavaScript features.

TypeScript.

TypeScript is a programming language developed by Microsoft to add static typing, and optional type annotations to JavaScript. It’s a superset of JavaScript, meaning all JavaScript is valid TypeScript, but not all TypeScript is valid JavaScript.

//Valid JavaScript, and valid TypeScript but it will complain about the lack of types
function add(a, b) {
    return a + b;
}
//Valid TypeScript with types, now invalid JavaScript
function add(a: number, b: number): number {
    return a + b;
}

Conclusion.

So to sum everything up:

JavaScript is based on a standard called ECMAScript. Technically JavaScript isn’t ECMAScript, but it’s the only version of it that still matters.

ECMAScript decides the baseline features JavaScript implements.

TypeScript is a superset of JavaScript that adds static typing and type annotations to JavaScript.

That’s everything! Thanks for reading — if you liked this article, feel free to share this article, or follow me on Twitter.

Originally published at https://www.omarileon.me on March 5, 2024.

Are TypeScript enums Still Bad?

Omari — Wed, 21 Feb 2024 14:42:09 +0000

If you search for TypeScript enums online, you’ll see they get a lot of hate. Have there been any improvements to enums over time, or are they still generally frowned upon?

A Quick Guide to Clamping Numbers in JavaScript

Omari — Thu, 08 Feb 2024 02:32:12 +0000

In JavaScript, there’s “Math.min()”, “Math.max()”, but unfortunately no Math.clamp(). There’s but it’s currently in the draft stages. This is fine — it’s very easy to implement clamp, and in this article, I’ll talk through doing just that.

A Quick Way

You can use the following function to clamp a number between a minimum and maximum value:

function clamp(num: number, lower: number, upper: number) {
    return Math.min(Math.max(num, lower), upper);
}

Why does this work? Let’s think it through. At first, our number is any valid JavaScript number, anything in the range -Number.MAX_VALUE <= num <= Number.MAX_VALUE

Then we have:

Math.max(num, lower);

So now our range gets updated to whatever the larger value is out of “lower” and “num”. Our range is now: lower <= num <= Number.MAX_VALUE.

I’m sure you can see where this is going — let’s break our code up:

const lowerBound = Math.max(num, lower);
const result = Math.min(num, upper);

Just like before but reversed. Our result is the lower of num or upper, so we can update our range to: lower <= num <= upper.

And just like that, our number is clamped! If it’s lower than the lower bound, we pick the lower bound. If it’s higher than the upper bound, we pick the upper bound. Otherwise, we pick the number.

Lodash

Lodash is a JavaScript utility library. You can install it with one of these commands:

npm i lodash 
pnpm add lodash 
yarn add lodash

And it works exactly the same as our function:

import { clamp } from 'lodash'; 
clamp(number, lower, upper);

Short and simple! If you’re not familiar with Lodash, it can be quite handy if you’re looking for any functions not native to JavaScript. Check it out .

Conclusion

So there’s two ways of getting the clamp math function into your JavaScript code. Which one should you use? Personally, I think since it’s such a small function, you should probably just implement this one yourself if you need it. If you’re already using Lodash though, then you may as well use their built-in function. Thanks for reading! If you liked this article, why not follow me on Twitter?

Originally published at https://www.omarileon.me.

The Best Way to Handle Promises in React

Omari — Tue, 06 Feb 2024 14:59:52 +0000

Promises are a great feature in JavaScript, used for data fetching or any asynchronous code. At first, it can be a struggle to figure out the best way to integrate Promises into the React ecosystem, so in this article we’ll go through a few options of how to do exactly that.

What is a Promise?

Promises allow you to perform asynchronous operations in JavaScript. To construct a Promise from scratch, you can use the Promise constructor. This takes a function which takes two parameters: “resolve”, a function to call when the operation completes, and “reject”, a function to call if the operation fails. You then have to call one of these functions when your operation completes.

Promises are a way of performing asynchronous operations in JavaScript. They’re a way of saying “I don’t have the value of this now, but I will at some point in the future”.

You can construct a promise from scratch using the Promise constructor. It takes two functions as parameters: “resolve”, a function to call when the operation completes successfully, and “reject”, a function to call if the operation fails. You then have to call one of these functions when your operation completes, called “settling” a promise.

JavaScript includes two ways of getting the result of a promise. Let’s take a look at both.

.then()

The first is “.then()”, a method on Promises which accepts a callback function to run when the promise resolves. Here’s what that looks like:

const myPromise = new Promise((resolve) => {
    setTimeout(() => {
        resolve('follow @marile0n');
    }, 1000); //1000ms = 1s
});
myPromise.then((val) => {
    console.log(val);
});

.then() returns another promise, which lets you chain together actions:

const healthyItems = ['apple', 'banana', 'carrot'];
function fetchShoppingBasket(): Promise<string[]> {
    //...
}
function countHealthyItems() {
    fetchShoppingBasket()
        .then((items) => items.filter((item) => healthyItems.includes(item)))
        .then((healthyItems) => healthyItems.length);
}

This works even if the next function you call in .then() isn’t asynchronous.

There are also two other related methods, .catch() and .finally(). .catch() is used for catching errors, and .finally() runs after a promise is settled, i.e. whether it completes successfully, or throws an error:

myPromise
    .then(() => console.log('Ill run first'))
    .then(() => console.log('Ill run second'))
    .then(() => {
        throw new Error('Whoops!');
    })
    .catch((e) => console.log('Ill run after an error:', e))
    .finally(() => console.log('Ill run last'));

Async/Await

The other way of handling promises in React is the async/await syntax. You can “await” a function to synchronously wait for the promise to settle:

const myPromise = new Promise((resolve) => {
    setTimeout(() => {
        resolve('follow @marile0n');
    }, 1000); //1000ms = 1s
});
const result = await myPromise;
console.log(result);

This lets you use a regular try…catch statement to handle errors. Here’s the above promise, converted to async/await

try {
    await myPromise;
    console.log('Ill run first');
    console.log('Ill run second');
    throw new Error('Whoops!');
} catch (e) {
    console.log('Ill run after an error:', e);
} finally {
    console.log('Ill run last');
}

If you use await in a function, it must be marked as asynchronous with the “async” keyword:

async function myAsyncFunction() {
    //...
}
const myLambdaAsyncFunction = async () => {
    //...
};

Now, onto the React part.

The Plain Way

You can handle a Promise in React using useEffect to call the Promise, and a useState to store the result. It’s also useful to set up some other values to track the state of the asynchronous action.

We’ll start off with our Promise. We’ll be using the handy — A great API for retrieving pictures of cats. Here’s the code for retrieving a cat:

type CatResponse = { _id: string };
async function getCat() {
    return axios
        .get<CatResponse>('https://cataas.com/cat?json=true')
        .then((res) => {
            console.log(res.data);
            return 'https://cataas.com/cat/' + res.data._id;
        });
}

Now let’s build that together in a React component. We’ll set up some state hooks:

const [cat, setCat] = useState('');
const [status, setStatus] = useState<'pending' | 'success' | 'error'>(
    'pending'
);
const [error, setError] = useState<Error>();

Three state values — one to track the returned cat, one to track the state of the promise, and one to store an error if we get one.

Then we have our useEffect:

useEffect(() => {
    setStatus('pending');
    getCat()
        .then((cat) => {
            setCat(cat);
            setStatus('success');
        })
        .catch((e) => {
            console.log(e);
            setStatus('error');
            setError(e);
        });
}, []);

To use the value of our promise, we can use a useEffect() hook with an empty dependency array. The function will get called the first time the component mounts, which changes our state and performs our API call. Then when the API call is done, our state values get updated, or if there’s an error, that gets stored.

Or we can rewrite this using async/await:

useEffect(() => {
    setStatus('pending');
    try {
        const cat = await getCat(); //'await' expressions are only allowed within async functions and at the top levels of modules.
        setCat(cat);
        setStatus('success');
    } catch (e) {
        console.log(e);
        setStatus('error');
        setError(e as Error);
    }
}, []);

Oh wait, but since we’re using await, we need to mark our function as async:

//Effect callbacks are synchronous to prevent race conditions.
useEffect(async () => {
    setStatus('pending');
    try {
        const cat = await getCat();
        setCat(cat);
        setStatus('success');
    } catch (e) {
        console.log(e);
        setStatus('error');
        setError(e as Error);
    }
}, []);

Now we run into another error — the useEffect function cannot be asynchronous.

How do we solve this? Move the code to an async function, and then call that function from your useEffect:

useEffect(() => {
    async function fetchCat() {
        setStatus('pending');
        try {
            const cat = await getCat();
            //'await' expressions are only allowed within async functions and at the top levels of modules.
            setCat(cat);
            setStatus('success');
        } catch (e) {
            console.log(e);
            setStatus('error');
            setError(e as Error);
        }
    }
    fetchCat();
}, []);

Then we can put this together with some JSX to display the results:

function Cat() {
    const [cat, setCat] = useState('');
    const [status, setStatus] = useState<'pending' | 'success' | 'error'>(
        'pending'
    );
    const [error, setError] = useState<Error>();
    useEffect(() => {
        async function fetchCat() {
            setStatus('pending');
            try {
                const cat = await getCat(); //'await' expressions are only allowed within async functions and at the top levels of modules.
                setCat(cat);
                setStatus('success');
            } catch (e) {
                console.log(e);
                setStatus('error');
                setError(e as Error);
            }
        }
        fetchCat();
    }, []);
    if (status === 'pending') return <h1>Loading...</h1>;
    if (status === 'error') return <h1>Error! {error?.message}</h1>;
    return (
        <div className="relative h-full w-96">
            {' '}
            <Image
                src={cat}
                alt="Cat"
                fill
                className="h-full w-full object-contain"
            />{' '}
        </div>
    );
}

And here’s what it all looks like:

So pretty straightforward, but a little verbose, even with just the basic functionality we’ve implemented here.

The Better Way

If you look online, you’ll see a lot of negative sentiment around using useEffect to handle promises. The main reason why is that it’s preferable to use existing libraries, rather than re-inventing the wheel. The most popular library for handling asynchronous promises in React is TanStack Query (formerly known as React Query). Let’s take a look at it by recreating our previous example with TanStack Query.

First you’ll need to install TanStack Query:

npm install @tanstack/react-query
yarn add @tanstack/react-query 
pnpm add @tanstack/react-query

Then we need to set up a QueryClient and a provider for our components to be able to access the client. I’m using the app directory in Next.js, so here’s how I’ve done it:

//Proiders.tsx
('use client');
import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
import { WithChildrenProps } from '@/types';
const queryClient = new QueryClient();
export function Providers({ children }: WithChildrenProps) {
    return (
        <QueryClientProvider client={queryClient}>
            {' '}
            {children}{' '}
        </QueryClientProvider>
    );
}

//layout.tsx
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import './globals.css';
import { Providers } from './providers';
const inter = Inter({ subsets: ['latin'] });
export const metadata: Metadata = {
    title: 'Create Next App',
    description: 'Generated by create next app',
};
export default function RootLayout({
    children,
}: Readonly<{ children: React.ReactNode }>) {
    return (
        <html lang="en">
            {' '}
            <body className={inter.className}>
                {' '}
                <Providers>{children}</Providers>{' '}
            </body>{' '}
        </html>
    );
}

Then, essentially all the extra logic we wrote before can be swapped out for React Query:

function TanCatQuery() {
    const {
        data: cat,
        isPending,
        error,
    } = useQuery({ queryKey: ['cat'], queryFn: () => getCat() });
    if (isPending) return <h1>Loading...</h1>;
    if (error) return <h1>Error! {error.message}</h1>;
    return (
        <div className="relative h-full w-96">
            {' '}
            <Image
                src={cat}
                alt="Cat"
                fill
                className="h-full w-full object-contain"
            />{' '}
        </div>
    );
}

The useQuery hook accepts an asynchronous function to call, as well as a key to be used when caching queries, and in return we get all the logic we previously had. React Query also has a lot of other benefits such as built-in caching, reduping requests, automatic retrying, etc.

Conclusion

So which one should you use? If you’re performing your promises outside of a React component, you can skip React Query, otherwise the choice is yours. Personally, I tend to reach for React Query straight away, as it greatly simplifies asynchronous code in React, but it’s all up to you — pick the best fit for your app. Check out the full code here and thanks for reading!

Originally published at https://www.omarileon.me.

Non-Null Assertions: The Forbidden Typescript Operator

Omari — Fri, 02 Feb 2024 11:47:51 +0000

The non-null assertion operator, or that weird exclamation mark you might be seeing in TypeScript is an operator that tells TypeScript that a value won’t be null or undefined. In a technical sense, it eliminates null and undefined from the type of your variable. In this article I’ll cover the operator, how to use it, and why maybe not to.

Here’s what it looks like:

function getName(): string | null {
    // ...
}
function greet(name: string) {
    console.log(`Hi ${name}`);
}
const myName = getName(); //string | null
greet(myName); //Argument of type 'string | null' is not assignable to parameter of type 'string'. 
//Type 'null' is not assignable to type 'string'. 
greet(myName!) //✅t

Add an exclamation mark onto the end of a variable, and the result is that variable with any null or undefined eliminated from its type.

Should you use it?

You should be aware of the fact that the operator isn’t doing anything to the variable itself, just forcing TypeScript to believe it will exist. Let’s take our previous example, and fill in our function.

function getName() {
    return Math.random() > 0.5 ? 'Omari' : null;
}

No need to add a return type anymore, TypeScript knows the function will always return a string or null.

The rest of the code still works:

function greet(name: string) {
    console.log(`Hi ${name}`);
}
const myName = getName(); //string | null 
greet(myName!); //✅

Even though we know something is wrong — “myName” will be null about half the time.

This is a simplified example, but the point is that you should be aware of why TypeScript thinks your variable might be null or undefined in the first place, and whether it’s worth risking the chance that it is. In this case, our code will still run, we’ll just get “Hi null”, so not too bad, but there are some alternatives.

What to use instead

The easiest solution to handle if your variable is null or undefined is to use type guards. Null and undefined are falsy, which makes it easy to check in an if statement:

if (myName) greet(myName);

This will include all falsy values, for example the empty string. In this case that’s helpful — we probably wouldn’t want to greet an empty name either, but you can also explicitly check for null or undefined with equality:

if (myName !== null) greet(myName);

Another way to check for null or undefined is to use the nullish coalescing operator (??), — introduced in TypeScript 3.7. This operator returns the left-hand side of the expression if it’s not null or undefined, and the right-hand side otherwise. It’s useful for giving variables default values in the case that they are null or undefined:

const myName = getName() ?? 'Omari'; //string | null greet(myName);

For not a lot more code, we’re back in alignment with TypeScript.

When might you use it?

One case I have seen the non-null assertion operator used is maps. Imagine if we wanted to use a map to count how many times we’ve greeted someone:

function greetWithCount(name: string) {
    greet(name);
    if (greetings.has(name)) {
        const count = greetings.get(name);
        //const count: number | undefined
        greetings.set(name, count + 1);
    }
}

You might be able to safely assume that inside the if statement, “.get()” should always return a value, since we’ve checked if that key has an entry. .get() always returns the type union “type | undefined” though. In this case, a quick non-null assertion is an easy solution. Again you could just check if “count” is undefined, but assuming the value exists isn’t the worst assumption in this case.

Conclusion

Thanks for reading! Hopefully, this article was a good introduction to that mysterious exclamation mark you’ve been seeing in TypeScript. Personally, I nearly always prefer handling null or undefined in other ways than the non-null assertion operator, but just like everything in coding, the choice is up to you!

Hey, I’m Omari! I’m a full-stack developer from the UK. I’m currently looking for graduate and freelance software engineering roles, so if you liked this article, check out my website.

Originally published at https://www.omarileon.me.

A Comprehensive Guide to Converting Between Strings, Booleans and Numbers in Typescript

Omari — Thu, 01 Feb 2024 13:13:44 +0000

With TypeScript, comes types. Things are stricter than the implicit conversion you’ll see in JavaScript. This means you’ll need to know how to safely convert between types. In this article, I’ll cover options for converting between the three primitive types you’re likely to be converting between the most often — strings, numbers and booleans.

A Quick Note on Truthiness

One important thing to discuss here is what it means to convert from something to a boolean. Converting a number to a boolean for example, if we say 0 is false and 1 is true, that makes sense right? But those aren’t the only numbers — what about 3 — true or false? Or -1, true or false? TypeScript, and JavaScript handle this with truthiness. A truthy value is anything that is considered true when treated as a boolean. It’s easier to go through the list of values that are falsy, which are:

Everything else is truthy.

So when converting values to boolean, it’s important to make a distinction between whether you want whatever your definition of true and false are for your context, and native TypeScript/JavaScript truthiness.

Strings

Strings to Numbers

There are two main ways to convert strings to numbers in TypeScript, parseFloat and the Number constructor.

Using parseFloat

“parseFloat” is a built-in function that converts a string to a number. It scans the string from left to right until it encounters a character that cannot be converted to a number. It then returns the numeric value parsed up to that point.

Here’s how you can use “parseFloat()” in TypeScript:

function stringToNumber(str: string) {
    return parseFloat(str);
}
console.log(stringToNumber('10')); //10 
console.log(stringToNumber('10 and 11')); //10 
console.log(stringToNumber('ten and 11')); //NaN 
console.log(stringToNumber('ten')); //NaN

So:

If we input a string that represents a number, we get out a number
If we input a string that starts with a number, we get just that number
If we input a string that doesn’t start with a number, we get NaN
If we input a string with no number, we get NaN

The NaN part is something to take note of. If you’re not familiar with NaN — it stands for Not A Number. It’s a special case that represents as you’d guess, anything that isn’t a number, for example 0/0, or the result of one of the number conversion functions failing.

One important thing is that NaN === NaN is false, which means this is false:

console.log(Number('ten') === Number('ten')); //false

So if your conversion silently fails and you compare the results, they will never be equal.

Using Number()

The Number() constructor in TypeScript can be used to explicitly convert a string to a number. It tries to convert the argument passed to it into a number. If the argument cannot be converted into a valid number, it returns NaN. Let’s take a look:

function stringToNumber(str: string) {
    return Number(str);
}
console.log(stringToNumber('10')); //10
console.log(stringToNumber('10 and 11')); //NaN
console.log(stringToNumber('ten and 11')); //NaN
console.log(stringToNumber('ten')); //NaN

Pretty similar to “parseFloat()”.The big difference is in the second case. “parseFloat” will scan the string from left to right and find the number 10, whereas Number will see that the whole thing is not a valid number, so it will return NaN

Strings to Booleans

There are a few ways to convert a string to a boolean, depending on what you want to consider true or false. The simplest way is just checking whether a string is truthy or not, which can be done with the Boolean() constructor:


function stringToBoolean(str: string) {
    return Boolean(str);
}

console.log(stringToBoolean('true')); //true
console.log(stringToBoolean('True')); //true 
console.log(stringToBoolean('false')); //true 
console.log(stringToBoolean('False')); //true 
console.log(stringToBoolean('')); //false 
console.log(stringToBoolean('Just a string')); //true

If the string is truthy, the string returns true. This means any string that isn’t an empty string.

This might not be useful depending on your use case. If you’re just checking if the string is empty then this works, but in other cases you might not want “false” or “False” to be considered truthy.

The simplest way is just checking if the string is equal to “true”:

function stringToBoolean(str: string) {
    return str === 'true';
}
console.log(stringToBoolean('true')); //true
console.log(stringToBoolean('True')); //false
console.log(stringToBoolean('false')); //false
console.log(stringToBoolean('False')); //false
console.log(stringToBoolean('')); //false
console.log(stringToBoolean('Just a string')); //false

Or for a case-insensitive version:

function stringToBoolean(str: string) {
    return str.toLowerCase() === 'true';
}
console.log(stringToBoolean('true')); //true
console.log(stringToBoolean('True')); //true
console.log(stringToBoolean('false')); //false
console.log(stringToBoolean('False')); //false
console.log(stringToBoolean('')); //false
console.log(stringToBoolean('Just a string')); //false

Numbers

Numbers to Strings

The easiest way to convert a number to a string in TypeScript is through the .toString() method:

function numberToString(num: number) {
    return num.toString();
}
console.log(numberToString(42)); //"42"
console.log(numberToString(-1)); //"1"
console.log(numberToString(NaN)); //"NaN"

One neat feature of this function is that it lets you choose the base/radix of the string, which lets you do things like convert a number to binary:

function numberToString(num: number) {
    return num.toString(2);
}
console.log(numberToString(42)); //"101010"
console.log(numberToString(-10)); //"-1010"
console.log(numberToString(NaN)); //"NaN"

Or convert a number to hexadecimal:

function numberToString(num: number) {
    return num.toString(16);
}
console.log(numberToString(12648243)); //"c0ff33"
console.log(numberToString(-10)); //"-a"
console.log(numberToString(NaN)); //"NaN"

That covers converting a plain number to a plain string, but if you’re dealing with something like percentages there are ways to

Numbers to Booleans

Like strings, the “Boolean()” constructor is the easiest way to convert a number to a boolean:


function numberToBoolean(num: number) {
    return Boolean(num);
}
console.log(numberToBoolean(-1)); //true
console.log(numberToBoolean(0)); //false
console.log(numberToBoolean(1)); //true
console.log(numberToBoolean(NaN)); //false

Any numbers that aren’t NaN or 0 are truthy.

Booleans

Booleans are a little more straightforward, since there are only two possible values, and they both convert easily to strings/numbers.

Booleans to Strings

Booleans contain a handy “toString()” method for converting them to strings:

function booleanToString(bool: boolean) {
    return bool.toString();
}
console.log(booleanToString(true)); //"true"
console.log(booleanToString(false)); //"false"

True to “true”, false to “false”.

Booleans to Numbers

The “Number” constructor is the easiest way to convert a boolean to a number. “parseFloat” won’t work here as it only accepts strings.

console.log(booleanToNumber(true)); //1
console.log(booleanToNumber(false)); //0

As you might expect, true gets converted to 1, and false gets converted to 0.

Conclusion

Thanks for reading! Hopefully, with this article, you were able to get a good grasp of how to convert between primitives in TypeScript. If you liked this article, why not check out more of my posts.

Originally published at https://www.omarileon.me.

Understanding “As Const” in TypeScript

Omari — Wed, 31 Jan 2024 11:19:56 +0000

TypeScript 3.4 introduced a new construct called “const assertions”. They tell TypeScript that your variable isn’t going to change, i.e., immutable, and that it should provide your type with as strict a type as possible. They affect different types in different ways, so in this article we’ll talk through how to use const assertions, and why they’re useful.

Strings/Numbers

Adding “as const” to a string/number will narrow the type to a specific value:

let foo = 'foo'; 
// let foo: string 
let foo = 'foo' as const; 
// let foo: 'foo't

Or for numbers:

let foo = 7; // let foo: number 
let foo = 7 as const; // let foo: 7;

It’s less useful for strings/numbers, since usually you could just define your variable using “const” for the same effect:

let foo = 7; // let foo: number 
const foo = 7; // const foo: 7;

With the added benefit of runtime safety.

Sometimes you might not want to define a value as a variable though and you might just want to use a string literal, e.g. for returning a value. Then, “as const” does come in use. Take a look at this example:

type Colour = 'red' | 'green' | 'blue';
type Variant = 'light' | 'dark';
function createColourVariant(colour: Colour, variant: Variant) {
    return `${variant}-${colour}`;
} //function createColourVariant(colour: Colour, variant: Variant): stringty

A simple function to create a colour variant name, imagine defining a palette for an app or something similar. The return type we get from this function is just a string.

You could create an explicit type for these colour variants:

type ColourVariant = `${Variant}-${Colour}`; //"light-red" | "light-green" | "light-blue" | "dark-red" | "dark-green" | "dark-blue" function createColourVariant(colour: Colour, variant: Variant): ColourVariant { return `${variant}-${colour}`; }

That might work fine for your use case, but we can also skip creating the type altogether with a const assertion:

function createColourVariant(colour: Colour, variant: Variant) {
    return `${variant}-${colour}` as const;
} //function createColourVariant(colour: Colour, variant: Variant): "light-red" | "light-green" | "light-blue" | "dark-red" | "dark-green" | "dark-blue"

Which is better? The first option is useful if you plan to reuse your type a lot, and also if you want the function to adhere to the type, rather than the type depending on that variable. The second option is shorter, and lets you skip the extra work of defining an extra type.

Something important to note is that you can only use “as const” with literal values:

const foo = 'foo' as const;
const bar = foo as const; //A 'const' assertions can only be applied to references to enum members, or string, number, boolean, array, or object literals.

Objects

Objects and arrays are where “as const” gets more interesting. For objects, “as const” changes all of the properties to readonly and narrows the values:

const myObject = { foo: 'bar', baz: 7 };
/* const myObject: { foo: string; baz: number; } */ 
const myObject = {
    foo: 'bar',
    baz: 7,
} as const; /* const myObject: { readonly foo: "bar"; readonly baz: 7; } */

This means you won’t be able to change the values of the properties:

const myObject = { foo: 'bar', baz: 7 } as const;
myObject.baz = 6; //Cannot assign to 'baz' because it is a read-only property

And you’ll lose access to any of the methods that mutate objects/arrays:

const me = { name: 'Omari', hobbies: ['coding', 'cooking', 'gaming'] } as const; //time to grow up :(
me.hobbies = ['coding', 'cooking']; //Cannot assign to 'hobbies' because it is a read-only property.
me.hobbies.pop(); //Property 'pop' does not exist on type 'readonly ["coding", "cooking", "gaming"]'. 
// yippee :)

Arrays

“as const” turns arrays into tuples of readonly values:

const goodLanguages = ['typescript', 'csharp']; //const goodLanguages: string[] const goodLanguages = ['typescript', 'csharp'] as const; 
//const goodLanguages: readonly ["typescript", "csharp"]

Not sure what a tuple is? Essentially it’s an ordered array of values. They’re useful for grouping variables together like an object, but a little less work.

So it’s especially useful for creating and handling tuples, because “as const” preserves the order and number of items in the array. Think of creating a custom React hook for toggling a value:

function useToggle(defaultValue = false) {
    const [active, setActive] = useState(false);
    const toggle = () => setActive((v) => !v);
    return [active, toggle];
}

The inferred return type of our function is this:

(boolean | (() => void))[]

We know our return type is a tuple where the first is the value, and the second is a function to toggle the value, but TypeScript has assumed that the value and the toggle function could be in any place, and the array could be any number of them.

So using our hook doesn’t work as you’d expect:

const [dialogOpen, toggleDialogOpen] = useToggle(); 
//const dialogOpen: boolean | (() => void) 
//const toggleDialogOpen: boolean | (() => void)

This is where the “as const” steps in:

function useToggle(defaultValue = false) {
    const [active, setActive] = useState(false);
    const toggle = () => setActive((v) => !v);
    return [active, toggle] as const;
} //function useToggle(defaultValue?: boolean): readonly [boolean, () => void]

We can then use the tuple returned by our hook as expected:

const [dialogOpen, toggleDialogOpen] = useToggle(); 
//const dialogOpen: boolean 
//const toggleDialogOpen: () => void

Const vs “As Const”

Despite how similar they sound, declaring a variable as a const variable is different to adding “as const” onto the end of a variable.

Declaring a const variable tells TypeScript that the reference your variable refers to will not change. Strings and numbers in JavaScript are immutable, so if you’re declaring a variable either way then for TypeScript, there is no difference between the two techniques. The difference lies in the fact that “const” is a JavaScript feature, whereas “as const” is a TypeScript feature.

const link = 'youtu.be/pHqC0uoatag'; 
//const link: 'youtu.be/pHqC0uoatag'; 

let link = 'youtu.be/pHqC0uoatag' as const; 
//let link: "youtu.be/pHqC0uoatag"

Running the following code with Bun, for example. This will run:

let link = 'youtu.be/pHqC0uoatag' as const; 
//const link: 'youtu.be/pHqC0uoatag'; 
link = ''; 
//Type '""' is not assignable to type '"youtu.be/pHqC0uoatag"'.

But this will not:

const link = 'youtu.be/pHqC0uoatag'; 
//const link: 'youtu.be/pHqC0uoatag'; 
link = ''; 
//Cannot assign to 'link' because it is a constant.

For objects and arrays, the difference lies in references vs values. Declaring an object/array using const tells TypeScript and JavaScript that that variable will never refer to another object/array, it does not mean that the values won’t change.

const bestNumbers = [1, 12, 24]; //great numbers 
bestNumbers = [1, 7, 8]; //won't work, this is a different array 
bestNumbers = [1, 12, 24]; //won't work, this is a different array 
//Cannot assign to 'bestNumbers' because it is a constant. 
bestNumbers.pop(); //Works fine

You can modify the values in an object/array without modifying the reference.

Compared to “as const”, where you can’t change the reference, or the values:

const bestNumbers = [1, 12, 24] as const; //great numbers 
bestNumbers = [1, 7, 8]; //won't work, this is a different array 
bestNumbers = [1, 12, 24]; //won't work, this is a different array 
//Cannot assign to 'bestNumbers' because it is a constant. 
bestNumbers.pop(); //Now this won't work either 
bestNumbers[2] = 7; //Or this

Con(st)clusion

So to sum everything up, “as const” or const assertions are a great TypeScript feature for giving your variables narrower types. They’re not always necessary, but they’re a great feature to have in your toolbelt, especially for creating tuples, and returning values with narrower types form functions. Hopefully, after this article, you now know when and where to use them. Thanks for reading!

Originally published at https://www.omarileon.me.