vsadx / overloads-for-js

Adds type-based overloads for functions.

Overloads for JS

What are overloads for?

Overloads come from other languages where the type of a variable is more obvious. Using overloads, you can write less code, yet understand its intent faster. How does it work? Overloads replace if (), else, or switch statements - if you're looking at a variable's type. We do this in JavaScript!

Notice the if, else if pair in this code sample, look at how we use the typeof keyword in JavaScript to do "type checking":

function makeInput(startingValue) {

    const element = document.createElement("input")
    
    if(typeof startingValue === "number") {
        element.type = "number"        
        element.value = startingValue
    }
    else if(typeof startingValue === "boolean") {
        element.type = "checkbox"
        element.checked = startingValue
    }
    else {
        element.placeholder = startingValue
    }
    
    return element
}

Since JavaScript doesn't have overloads built in, we have write the type checking code ourself. Type checking in JS gets more complicated because typeof doesn't work well on things like HTMLElements for example. You might have to use instanceof in some places or do prototype matching.

Getting Started

How to write an overload

Overloads are easy! If you've ever written callback functions to addEventListener, or setTimeout you've already got the basics. Here's the first line of our overload:

import { overload } from "./overloads.js"

const switchInput = overload()

What's this? Each time you run overload() you get a new empty function you define later. Let's add our cases:

switchInput.if(HTMLInputElement, String, (element, startingValue) => {
    element.placeholder = startingValue
})

It's that easy, we can add the next case like this:

switchInput.if(HTMLInputElement, Number, (element, startingValue) => {
    element.type = "number"
    element.value = startingValue
})
switchInput.if(HTMLInputElement, Boolean, (element, startingValue) => {
    element.type = "checkbox"
    element.checked = startingValue
})

How to run the overloaded function

Just like in other languages, these overloads are ran exactly like any other function.

// runs the `String` version
switchInput(myInputElementA, "First Name")

// runs the `Boolean` version
switchInput(myInputElementB, true)

Extras

Using overloads for better optional parameters

In JavaScript, we use optional parameters all the time! We might have different code run depending on how many parameters are passed to our function. Overloads work here too, here's how:

const makeFormQuestion = overload()

makeFormQuestion.if(String, (question) => {
    const input = document.createElement("input")
    input.placeholder = question
    return input
})
makeFormQuestion.if(String, Array, (question, choices) => {
    const select = document.createElement("select")
    select.append(...choices)
    return select
})

How it works

You might want to take an extra look at these examples above if you get stuck, overloads work for primitives like Number, String, Boolean - or elements like HTMLElement, HTMLDivElement - or Array - even your custom JS classes. Overloads don't use a magic list of types it uses real type checking just like what you would ordinarily write. Also, it's not locked at two parameters, you overloadable functions can have as many parameters as you want.

This library has some TypeScript support; in our example, each variety of (element, startingValue) => would know that element was an HTMLInputElement. What about startingValue, it needs to have a different type depending on the case? It is also has its type automatically declared for you.

Defining overloads using the compact method

So far, we've been writing overloads like this:

const functionName = overload()

functionName.if(Number, num => console.log(`Num: #${num}`))
functionName.if(String, str => console.log(`Text: "${num}"`))

Here's a shorter way:

const functionName = overload()
    .if(Number, num => console.log(`Num: #${num}`))
    .if(String, str => console.log(`Text: "${str}"`))

Preventing more cases from being accidentally added later .lock

const toHtml = overload()
    .if(Array, list => `<ul> </ul>`)
    .if(String, text => `<p> </p>`)
    .lock()
    // no more `.if` functions can be added.

Catch all cases .else

const multiNumber = overload()
    .if(Number, Number, (a, b) => a * b)
    .if(Number, Number, Number, (a, b, c) => a * b / c)
    .else((...args) => console.error("None of your parameters matched any of the cases:", args))
    // `.else` always matches if no other cases were a match.