DEV Community: Sergei Orlov

An 85 Lines of Code Static Site Generator with Bun and JSX

Sergei Orlov — Wed, 24 Jan 2024 07:57:07 +0000

In this post we'll take a brief look on how to create an SSG (static site generator) with Bun. It will take your components written in JSX and turn them into HTML pages.

This will be a three-step process.

collect all the pages that we conventionally put in a single
directory. Nesting directories will be preserved as well, transpile JSX inside the pages into JS files with functions that produce HTML,
loop over JS files, running them and saving HTML into .html files

TS config

First off, we need to drop the X in JSX. To do so, we instruct Bun to use our custom function for transpiling JSX. We'll go with a react-jsx preset. We'll also define a gutsby path, which is going to be our JSX handler. With this path in place, we set gutsby as our jsxImportSource.

// ./tsconfig.json
{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "gutsby/*": ["./gutsby/*"]
        },
        "jsx": "react-jsx",
        "jsxImportSource": "gutsby",
        "lib": ["ESNext", "DOM"],
        "allowJs": true,
        "esModuleInterop": true,
        "allowSyntheticDefaultImports": true,
        "skipLibCheck": true,
        "isolatedModules": true,
        "target": "ESNext",
        "module": "CommonJS",
        "types": ["bun-types"]
    }
}

Next we need to bun init in the root directory since TSConfig will blame us for bun-types. You need Bun installed on your machine, of course.

It also makes sense to define a few types for our convenience. I'll go global but you can export them if you like.

// ./src.types.d.ts
declare global {
    module JSX {
        interface IntrinsicElements {
            [key: string]: any
        }
    }

    /**
     * A customisable props type for our components.
     */
    export type PropsWithChildren<
        CustomProps extends Record<string, unknown> = Record<string, unknown>
    > = CustomProps & {
        children?: (Promise<string | string[]> | undefined)[]
    }
}

export {}

Now we're ready to make our dirty little gutsby.

Dealing with JSX in Bun

With a JSX preset we've picked in our tsconfig (react-jsx), Bun will wrap every JSX element into a jsxDEV function call. Since we've also instructed it that the import source is the gutsby directory, let's create our JSX handler there. To avoid errors, we need two files: jsx-runtime.ts and jsx-dev-runtime.ts but the content may be completely the same since Bun will refer to the dev in our scenario.

// ./gutsby/jsx-runtime.ts
/**
 * This function is called recursively, so, whether it's a component or an HTML
 * tag, it will eventually become an HTML string with all children nested as
 * HTML as well.
 */
export async function jsx(
    type: string | ((props: PropsWithChildren) => string),
    props: PropsWithChildren
): Promise<string> {
    // 1. Handling components
    // This is a component. Run it to get the contents.
    if (typeof type === "function") return type(props)

    // 2. Handling tags
    // If children is not an array then it must be.
    if (!Array.isArray(props.children)) props.children = [props.children]

    // Start opening tag composition.
    let line = `<${type}`
    // Get all the props that are not children.
    const notChildren = Object.keys(props).filter(key => key !== "children")

    // Loop over the props and put them as attributes in our HTML.
    // Yes, class, not className.
    for (const prop of notChildren) line += ` ${prop}="${props[prop]}"`

    // Finish opening tag composition.
    line += ">"

    // Loop over the children.
    for (const child of props.children) {
        let nested = await child

        // If children is not an array then it must be.
        if (!Array.isArray(nested)) nested = [nested as string]
        // Loop over children and put them as inner HTML.
        for (const item of nested as string[]) line += (await item) ?? ""
    }

    // Close the tag and return whatever HTML we got.
    return line.concat(`</${type}>`)
}

// ./gutsby/jsx-dev-runtime.ts
/**
 * This function is called recursively, so, whether it's a component or an HTML
 * tag, it will eventually become an HTML string with all children nested as
 * HTML as well.
 */
export async function jsxDEV(
    type: string | ((props: PropsWithChildren) => string),
    props: PropsWithChildren
): Promise<string> {
    // 1. Handling components
    // This is a component. Run it to get the contents.
    if (typeof type === "function") return type(props)

    // 2. Handling tags
    // If children is not an array then it must be.
    if (!Array.isArray(props.children)) props.children = [props.children]

    // Start opening tag composition.
    let line = `<${type}`
    // Get all the props that are not children.
    const notChildren = Object.keys(props).filter(key => key !== "children")

    // Loop over the props and put them as attributes in our HTML.
    // Yes, class, not className.
    for (const prop of notChildren) line += ` ${prop}="${props[prop]}"`

    // Finish opening tag composition.
    line += ">"

    // Loop over the children.
    for (const child of props.children) {
        let nested = await child

        // If children is not an array then it must be.
        if (!Array.isArray(nested)) nested = [nested as string]
        // Loop over children and put them as inner HTML.
        for (const item of nested as string[]) line += (await item) ?? ""
    }

    // Close the tag and return whatever HTML we got.
    return line.concat(`</${type}>`)
}

That is it, actually. Now all your elements will become strings of HTML. Our next step is to create a script that will run turn our top-level components into elements and save them as HTML. We're basically making a ReactDOM.render here, but it renders to HTML files directly.

Building pages

We need two things: a build script, and a page we'll render as a proof of concept. Let's start with the page first. I put mine in a src/pages directory to keep it separate from the build script and other stuff. A bit of Nextiness.

// ./src/pages/index.tsx
const valueOutsideComponent = "Value outside"
const asyncValueOutsideComponentP = Promise.resolve("Async value outside")

/**
 * This is our index page.
 *
 * NOTE: It must be a default export as per our build script.
 *
 * And yes, it does support
 * - extracting components
 * - children provision
 * - async behavior
 * - values in closure
 */
export default async function Index() {
    const valueViaChildren = "Value via children"

    return (
        <html lang="en">
            <head>
                <title>Bun, JSX and Orlowdev</title>
            </head>
            <body>
                <main>
                    <h1>My values</h1>
                    <MyValues valueViaProps="Value via props">{valueViaChildren}</MyValues>
                </main>
            </body>
        </html>
    )
}

type P = PropsWithChildren<{ valueViaProps: string }>
const MyValues = async ({ valueViaProps, children }: P) => {
    const valueInsideComponent = "Value inside"
    const asyncValueInsideComponent = await Promise.resolve("Async value inside")
    const asyncValueOutsideComponent = await asyncValueOutsideComponentP

    return (
        <ul>
            <li>{valueViaProps}</li>
            <li>{valueInsideComponent}</li>
            <li>{valueOutsideComponent}</li>
            <li>{asyncValueInsideComponent}</li>
            <li>{asyncValueOutsideComponent}</li>
            <li>{children}</li>
        </ul>
    )
}

Now the last part of our tour is to get HTML. We only cover build process here but you can add all sorts of things here, including CSS processing, copying assets, minifying images, and what. The script will run bun build on the files inside the pages directory and then grab the compiled files and execute them, saving to ./dist/*.html.

// ./build.ts
import { promises, existsSync, mkdirSync } from "node:fs"
import { execSync } from "node:child_process"

// Create all the directories if they do not exist.
if (!existsSync("dist")) mkdirSync("dist")
if (!existsSync("dist/js")) mkdirSync("dist/js")
if (!existsSync("dist/www")) mkdirSync("dist/www")

/**
 * Build JSX, loop over pages and save their content as HTML files with the same name.
 */
const compileHTML = async () => {
    // Bun build with a target of Bun since we are going to run those scripts later with Bun.
    execSync("bun build src/pages/* --outdir dist/js --target=bun")

    // Get all available pages.
    const pages = await promises.readdir("./dist/js")

    // Loop over pages and generate HTML files for each of them.
    for (const page of pages) {
        // Skip if a page is somehow not a JS file.
        if (!page.endsWith(".js")) continue

        // Get name of the file without file extension.
        const name = page.substring(0, page.lastIndexOf("."))

        // Import default function from the page.
        const f = await import(`dist/js/${name}`).then(p => p.default)

        // Run the function and write whatever it returns to an HTML file with the name of the page.
        Bun.write(`./dist/www/${name}.html`, await f())
    }
}

// Go!
compileHTML()

And that's it! If you now run bun run build.ts it should create you a dist/www/index.html that will look something like this:

And this wraps up our short lesson. Your optional home assignment is to add:

serving HTML files (check out Bun.serve)
watching for changes and rerunning compilation (fs.watch)
postprocessing for CSS (TailwindCSS, for example)
copying static assets for your pages
optimizing images - this is a harder one

If you have any questions, you can reach me out on X.

Images in a Notion page with gatsby-source-notion-api

Sergei Orlov — Thu, 10 Jun 2021 13:34:17 +0000

The syntax

Simply put this line as text on your Notion page and replace image alt and image source with
something that would work for you. I mean, literally, this will not work, you at least need a real
image source. 👍

![image alt](image source)

If you'd like to find out how to make code blocks (like the one above) with
gatsby-source-notion-api while Notion API still doesn't support them,
here's a rather dirty hack that will help you to do so.

The easiest way - remote images

If an image is already available somewhere online, and you have the URL, simply put it between the
braces and you're good to go.

But the image is on my computer...

In Gatsby, there is a static folder that you can create in the root directory of your project.
Whatever you declare there, will be available publicly. All you need to do is refer to the image as
if it was available at the root of your website.

For instance, if you have an image called puppy.png, you can put it to ./static inside your
Gatsby project, and then refer to it on your notion page as:

![Never lie in the alt text, it's a puppy!](/puppy.png)

Caveat

Since the images are not referenced from a Markdown file, and the path to the image is not
relative - you will need something like
gatsby-remark-images-anywhere so
that they are converted into file nodes and all the gatsby-image magic works with them properly.

How to use code snippets with gatsby-source-notion-api

Sergei Orlov — Fri, 04 Jun 2021 09:31:47 +0000

As of today, the official Notion API doesn't support code snippets. If such block exists on your Notion page, the API returns it with a type of unsupported and its contents are empty. When I was migrating my personal blog to gatsby-source-notion-api, I found two rather convenient ways to embed code.

gatsby-remark-embedder

Not sure if it will work if you use MDX, but it works perfectly with MarkdownRemark. All you need to do is to create a code snippet on CodePen or CodeSandBox and simply throw a link to the snippet onto the page.

This approach has the great benefit of having all your code snippets put together. You can reuse them in different places, you can edit them separately from the writing process, and you can share them outside your blog as well. You can also find the plugin useful in other places like embedding tweets, youtube videos, and what-not.

Plugin docs can be found here. In short - install the plugin, add it to your gatsby-config.js, create a code snippet ¹ and throw its link to the page.

Markdown syntax

If you prefer things to be right inside the page, there is a way, and it's what I personally use on my blog. You can write a code snippet in Markdown syntax and simply disallow Notion to transform it to a code block. Start a line with ``` and put a space. Notion will automatically turn it into a code block. Cmd/Ctrl + Z to undo this transformation. Put the snippet contents below. Then put ``` on a separate line again.

To specify syntax you want to use in the snippet, you can put it right after the first ```.

gatsby-source-notion-api will transform it preserve it as Markdown syntax, and MarkdownRemark or MDX will transform it into valid HTML.

CAVEAT: since it's a kind of a wallhack to make the current state of Notion API a bit more usable, it's should not be a way to go when they start to support code blocks properly. So, what you need to do to make it work is to indent the contents of the whole code snippet one level up. I.e. simply select the stuff between ``` and press Tab once. This will ensure snippet contents are rendered as snippet contents, not just as separate paragraphs.

Here's an example of what it looks like as a result:

console.log("Hello world!");

And here's what it looks like in Notion to make it work:

You probably need to sign up at CodePen or CodeSandBox to be able to use long-lasting links to your snippets. ↩

Images in "files" property with gatsby-source-notion-api

Sergei Orlov — Fri, 04 Jun 2021 09:28:58 +0000

There are many ways you can find the Notion files property useful. One of the experiments I did was using it to provide a hero image for my blog. Currently, hero images from all blog posts come for a Hero Image files property I have on my DB. In general, the process is quite straightforward. Here's an example with MarkdownRemark that pulls in images for all notion pages, assuming that the files property we need is called Hero Image:

query {
  allMarkdownRemark {
    edges {
      node {
        remoteImage {
          childImageSharp {
            gatsbyImageData(layout: FIXED)
          }
        }
      }
    }
  }
}

But there are things you need to consider.

✅ Embedding files via links

If you embed files via links, it should work out just fine with MarkdownRemark or MDX. gatsby-source-notion-api will create remote file nodes for those images. You can then use Sharp to transform them and do any other stuff you would do with images in Gatsby. All you need to do is to query for the image and put it where you need it.

💥 Uploading files

If you upload files, things get a bit trickier. The thing is that Notion API returns only the name of the asset if you upload it, not the URL where it resides. There are two ways you can bypass this

Storing attached images in the project repository

You could potentially attach images to a Notion page and then also copy them to your project folder, and then find the Notion attachment in the list of files you have in the repo, but this approach is quite funny and I didn't try it out. Maybe it could help in some cases. But, again, maintain it here and there if you do this.

Uploaded files are in fact links

After you attach a file, you can use the kebab menu (three dots) near the image and click "View original". It will open your image in a new tab. All you need to do is to copy the link and attach it to the same property. It is observed that you can remove the initial file afterward and the embedded link will still lead you to the file correctly. I don't know for how long they cache assets and if they remove them when you remove the attachment or not, but for now and for me it works.

UPD: Don't remove the file, simply move it down in the attachments, so that attachments as links are always on top.

After you have a file attached as a link, you can be sure that everything will work. 🎉

Factory arrow functions in TypeScript

Sergei Orlov — Tue, 20 Apr 2021 12:48:55 +0000

This article continues the discussion of using factory arrow functions and covers providing TypeScript type definitions for them. I highly recommend reading part I.

DISCLAIMER
The term factory arrow function is made up as I couldn't succeed in googling for a proper name for that. I avoid calling it factory function because it is an existing term that means a different thing. If you know the correct name for the concept covered in this article, please, share it in a comment - I'd be glad to find out.

It's a Series

Type Inference

What we get for free with classes in TypeScript is that objects instantiated from those classes have type definitions out of the box. We can refer to the class itself as a type.

class Rectangle {
    public constructor(public length: number, public width: number) {}

    public getArea(): number {
        return this.length * this.width
    }
}

const r: Rectangle = new Rectangle(10, 20)

On the other hand, if we use a factory arrow function, the type of the returning object is going to be sligthly more verbose.

const rectangle = (length: number, width: number) => ({
    length,
    width,
    getArea: () => length * width,
})

const r: { length: number; width: number; getArea: () => number } = rectangle(10, 20)

The first thing we can do is declare an interface for our rectangle return type:

interface IRectangle {
    length: number
    width: number
    getArea: () => number
}

const rectangle = (length: number, width: number) => ({
    length,
    width,
    getArea: () => length * width,
})

const r: IRectangle = rectangle(10, 20)

We can also set IRectangle as a return type of our rectangle factory arrow function, but it will not be easy to identify it in the code. I prefer to put it right after declaring the variable for our factory arrow function so that it is visible at a glance.

interface IRectangle {
    length: number
    width: number
    getArea: () => number
}

const rectangle: (length: number, width: number) => IRectangle = (
    length: number,
    width: number,
) => ({
    length,
    width,
    getArea: () => length * width,
})

const r = rectangle(10, 20)

Generic Factory Arrow Function Type

Now the type of our r is known and we don't need to specify it explicitly. But the type signature of our rectangle is very messy. Moreover, we'll have to use similar type for all our factory arrow functions, so we should probably simplify it. We can create a generic type that will include both the arguments of the factory arrow function, and the return type. Let's call it FAF for brevity.

type FAF<TArgs extends any[], TReturn> = (...args: TArgs) => TReturn

FAF accepts two types:

TArgs that will represent arguments of our function. It must be an array or a tuple. We'll make a small change to this type a bit later.
TReturn that will represent the return value of our FAF.

A great benefit of using this type is that we can remove the types for the arguments safely as we define them in the generic FAF type. To me, the more types are inferred, the better for the developer. In this case, the whole function has no types defined except for the FAF itself.

type FAF<TArgs extends any[], TReturn> = (...args: TArgs) => TReturn

interface IRectangle {
    length: number
    width: number
    getArea: () => number
}

const rectangle: FAF<[number, number], IRectangle> = (length, width) => ({
    length,
    width,
    getArea: () => length * width,
})

const r = rectangle(10, 20)

If we accidentally make a mistake and start accepting more arguments than what the type defines, we'll immediately see it. It doesn't save us from less arguments than we define in the tuple, but it's not much of an issue - if you don't need an argument, you can safely skip it. Another problem is that the FAF type is incovenient if we use it for zero or one arguments. We can fix it as follows:

type FAF<TArgs, TReturn> = TArgs extends any[]
    ? (...args: TArgs) => TReturn
    : (arg: TArgs) => TReturn

Instead of requiring an array or a tuple as our first type, we take the responsibility to check the provided type ourselves. If it is a tuple or an array, then we spread the type as a set of arguments. Otherwise, we refer to it as our function argument as is.

Now we don't have to care about adding the square brackets when we don't need them. If we create a FAF with no arguments at all, we can use the void keyword. In the following code snippet, rectangle has two arguments, square has one argument, and dot has no arguments, and in all cases we don't have to care about specifying argument types anywhere but the FAF type.

type FAF<TArgs, TReturn> = TArgs extends any[]
    ? (...args: TArgs) => TReturn
    : (arg: TArgs) => TReturn

interface IRectangle {
    length: number
    width: number
    getArea: () => number
}

interface ISquare {
    length: number
    getArea: () => number
}

interface IPoint {
    getArea: () => number
}

const rectangle: FAF<[number, number], IRectangle> = (length, width) => ({
    length,
    width,
    getArea: () => length * width,
})

const square: FAF<number, ISquare> = (length) => ({
    length,
    getArea: () => length ** 2,
})

const point: FAF<void, IPoint> = () => ({
    getArea: () => 1,
})

const r = rectangle(10, 20)
const s = square(10)
const p = point()

Keep in mind that we use tuples and arrays as our first type interchangeably, which means that we will have issues if we want to pass an array as our first argument, but avoid spreading. To do so, we can simply wrap it into square brackets:

type FAF<TArgs, TReturn> = TArgs extends any[]
    ? (...args: TArgs) => TReturn
    : (arg: TArgs) => TReturn

const str: FAF<[string[]], string> = (strs: string[]) => ''

The I of SOLID

Image taken from https://www.polygon.com

Interface Segregation Principle (ISP) suggests that we should prefer small interfaces to big interfaces. Apart from improved convenience of development, ISP allows us to follow the Law of Demeter (LoD), also known as principle of least knowledge. LoD suggests that pieces of our code should have only limited knowledge about things they work with.

One of the ways to follow ISP is by separating our types and building interface hierarchies. Following the knowledge term from the LoD, I prefer to name my interfaces as IKnows*X*. For quite some time I also used the I*X*Aware.

We can extract the getArea and length methods into separate interfaces. For now, we'll rely on the ability of TypeScript interfaces to extend from multiple other interfaces, and define the same types we had before as follows:

type FAF<TArgs, TReturn> = TArgs extends any[]
    ? (...args: TArgs) => TReturn
    : (arg: TArgs) => TReturn

interface IKnowsGetArea {
    getArea: () => number
}

interface IKnowsLength {
    length: number
}

interface IRectangle extends IKnowsGetArea, IKnowsLength {
    width: number
}

interface ISquare extends IKnowsGetArea, IKnowsLength {}

interface IPoint extends IKnowsGetArea {}

const rectangle: FAF<[number, number], IRectangle> = (length, width) => ({
    length,
    width,
    getArea: () => length * width,
})

const square: FAF<number, ISquare> = (length) => ({
    length,
    getArea: () => length ** 2,
})

const point: FAF<void, IPoint> = () => ({
    getArea: () => 1,
})

Nothing really changed, but we reduced a bit of repetition.

Least Knowledge and Interface Composition

Back to LoD. Although extending interfaces may be useful in some cases, we can make our types as clever as we really need.

Let's split everything to the smallest pieces. First, we introduce separate interfaces for all the properties and methods. Of course, it's not mandatory to always split to one-field objects. Then, we amend our shape types. We'll make them barebone - by default they will only require a minimal set of dimensions to be usable. But we will also make them generic so that we can define more features if we need them. Our Rectangle will be armed with getArea and getPerimeter whereas the square will remain barebone. Apart from providing us flexibility of defining objects, this approach also makes destructuring easier. Pick<Axe> no longer required!

type FAF<TArgs, TReturn> = TArgs extends any[]
    ? (...args: TArgs) => TReturn
    : (arg: TArgs) => TReturn

interface IKnowsGetArea {
    getArea: () => number
}

interface IKnowsGetPerimeter {
    getPerimeter: () => number
}

interface IKnowsLength {
    length: number
}

interface IKnowsWidth {
    width: number
}

type IRectangle<TFeatures extends Record<string, any> = {}> = IKnowsLength & IKnowsWidth & TFeatures

type ISquare<TFeatures extends Record<string, any> = {}> = IKnowsLength & TFeatures

const rectangle: FAF<[number, number], IRectangle<IKnowsGetArea & IKnowsGetPerimeter>> = (
    length,
    width,
) => ({
    length,
    width,
    getArea: () => length * width,
    getPerimeter: () => 2 * (length + width),
})

const square: FAF<number, ISquare> = (length) => ({
    length,
})

const r = rectangle(10, 20)
const s = square(10)

const getLengthOf = (x: IKnowsLength) => x.length

getLengthOf(r) // OK
getLengthOf(s) // OK

const getWidthOf = (x: IKnowsWidth) => x.width

getWidthOf(r) // OK
getWidthOf(s) // Argument of type 'ISquare<IKnowsGetArea>' is not assignable to parameter of type 'IKnowsWidth'.
// Property 'width' is missing in type 'ISquare<IKnowsGetArea>' but required in type 'IKnowsWidth'.

const getAreaOf = (x: IKnowsGetArea) => x.getArea()

getAreaOf(r) // OK
getAreaOf(s) // Argument of type 'IKnowsLength' is not assignable to parameter of type 'IKnowsGetArea'.
// Property 'getArea' is missing in type 'IKnowsLength' but required in type 'IKnowsGetArea'.

const getPerimeterOf = (x: IKnowsGetPerimeter) => x.getPerimeter()

getPerimeterOf(r) // OK
getPerimeterOf(s) // Argument of type 'IKnowsLength' is not assignable to parameter of type 'IKnowsGetPerimeter'.
// Property 'getPerimeter' is missing in type 'IKnowsLength' but required in type 'IKnowsGetPerimeter'.

It is not mandatory to make the shapes generic. We could have made the features generic instead, so that we can provide specific shapes that need those features. It is up to you to decide which approach to choose. If there are two shapes and twenty methods, it makes sense to make shapes generic. If it is vice versa... Well, you get the point. My rule of the thumb is: don't waste time on typing redundant letters. The total quantity of letters you can type throughout your life is not infinite. Here we have two shapes and four features so generalizing shapes sounds like two times less effort.

Static Methods

In TypeScript, we can define properties on a function because function is an object. Thus, we can define an interface for a function and imitate static properties and methods on our types. Even more - we can just extend the interface from our FAF type!

type FAF<TArgs, TReturn> = TArgs extends any[]
    ? (...args: TArgs) => TReturn
    : (arg: TArgs) => TReturn

interface IKnowsGetArea {
    getArea: () => number
}

interface IKnowsGetPerimeter {
    getPerimeter: () => number
}

interface ILengthAware {
    length: number
}

type ISquare<TFeatures extends Record<string, any> = {}> = ILengthAware & TFeatures

interface ISquareFAF extends FAF<number, ISquare<IKnowsGetArea & IKnowsGetPerimeter>> {
    new: ISquareFAF
}

const Square: ISquareFAF = (length) => ({
    length,
    getArea: () => length ** 2,
    getPerimeter: () => 4 * length,
})

Square.new = Square

const s = Square.new(10) // <- Looks like Rust!
Square.new.new.new.new.new.new(10) // <- Looks like Insanity!

Conclusion

In this article we covered using factory arrow functions in TypeScript. I hope you enjoyed reading it!

Factory arrow functions in JavaScript

Sergei Orlov — Mon, 14 Sep 2020 15:21:51 +0000

This article describes an alternative approach to instantiating objects from a template in JavaScript. For better comprehension, it is sometimes compared with commonly used ES6 classes.

DISCLAIMER
The term factory arrow function is made up as I couldn't succeed in googling for a proper name for that. I avoid calling it factory function because it is an existing term that means a different thing. If you know the correct name for the concept covered in this article, please, share it in a comment - I'd be glad to find out.

It's a Series

ES6 Class Recap

If you do not know what ES6 classes in JavaScript are, I suggest to read the official MDN article about classes but full understanding and experience with classes is not a required pre-requisite for this article. Here is a short recap:

Classes are a template for creating objects. They encapsulate data with code to work on that data. Classes in JS are built on prototypes but also have some syntax and semantics that are not shared with ES5 classalike semantics. © MDN
MDN

Key features of ES6 classes:

Familiar syntax for developers coming from other programming languages
They don't hoist, no matter if they are used as class expressions or class declarations
In methods declared on a class, this represents the current object instantiated from the class
The body of the class always operates in strict mode
Subclassing is possible using the extends keyword, referencing parent class is possible using the super keyword
Instance can be checked for being an instanceof a constructor (beware, dragons here)
The new keyword is used to instantiate a class

You've most probably seen classes in JavaScript as they have become a common part of our codebases these days. Here is an example of an ES6 class declaration:

class Rectangle {
    constructor(length, width) {
        this.length = length
        this.width = width
    }

    getArea() {
        return this.length * this.width
    }
}

const r = new Rectangle(10, 20)
r.getArea() // 200

Factory arrow function

Although classes have many benefits, I found myself using a different approach that I would like to share here. In JavaScript, we can create a function that accepts arguments and returns an object that has exclusive access to those arguments via closure.

Here is an example:

const rectangle = (length, width) => ({
    length,
    width,
    getArea: () => length * width,
})

const r = rectangle(10, 20)
r.getArea() // 200

This example uses a few shortcuts, so it's ok if it seems unfamiliar. Here is what it would look like if we wrote it in a more traditional way:

const rectangle = (length, width) => {
    return {
        length,
        width,
        getArea: () => length * width,
    }
}

Now I'd like to outline the cool features this approach gives us compared to ES6 class syntax.

no `this`

As we use arrow functions both for the methods and for object creation, this is undefined. JavaScript this requires a solid understanding of its behaviour and using it can be misleading for many developers. Instead of relying on this, we can benefit from using the closure over the arguments. As the object has access to the arguments, it means that they are available in its methods.

We also enable safe method extraction because of the closure.

const rectangle = (length, width) => ({
    width,
    length,
    getArea: () => length * width,
})

const theRectangle = rectangle(10, 20)

const getTheRectangleArea = theRectangle.getArea
getTheRectangleArea() // 200

NOTE: We can achieve safe method extraction with classes, for example using Function.prototype.bind, but with the factory arrow function, we no longer need to bother about losing the context.

Private properties

It is impossible to directly change the arguments passed to a function from the outside. They cannot be accessed, and they cannot be changed. You can explicitly allow access by binding the arguments to object properties. In the example below, length is available on the object externally, but width only exists inside and there is no way to access it from outside the object:

const rectangle = (length, width) => ({
    length,
    getArea: () => length * width,
})

const r = rectangle(10, 20)
r.length // 10
r.width // undefined
r.getArea() // 200

Free Bonus: even if you assign different values on the accessible object properties, the object itself will still use the arguments in its methods. Keep in mind that it only works if you don't use the properties of the object from the outside.

const rectangle = (length, width) => ({
    length,
    width,
    getTotalAreaWith: ({ length: oLength, width: oWidth }) => length * width + oLength * oWidth, // <- This is the cause
})

const r1 = rectangle(2, 5)
const r2 = rectangle(3, 6)

r1.getTotalAreaWith(r2) // 28

r1.width = 1000
r1.getTotalAreaWith(r2) // 28

r2.width = 1000
r1.getTotalAreaWith(r2) // 3010 <- This is the problem

You can avoid the issue with accidental overrides of object property values by doing all the calculations internally in the object:

const rectangle = (length, width) => ({
    length,
    width,
    getArea: () => length * width,
    getTotalAreaWith: ({ getArea }) => length * width + getArea(), // <- Now it will work
})

const r1 = rectangle(2, 5)
const r2 = rectangle(3, 6)

r1.getTotalAreaWith(r2) // 28

r1.width = 1000
r1.getTotalAreaWith(r2) // 28

r2.width = 1000
r1.getTotalAreaWith(r2) // 28

No Direct Inheritance And Internal Method Calls

If you looked at the previous example, you probably noticed that length is multiplied by width in two places: in getArea and in getTotalAreaWith. This is because we cannot use this and access getArea from inside getTotalAreaWith, which is a good example that everything has a price.

The factory arrow function also does not allow us to use inheritance which may cause code repetition as well.

But, due to the anonymous nature of our methods, we can write those separately and build up a horizontal extension of our objects and share methods between or even outside the objects.

A simple way to do so is to use partial application.

If you are not familiar with the concept of partial application, I suggest you read Kyle Shevlin's article on the topic.

In the example below, I create a multiplyThunk that is partially applied with two values. I then assign it as a getArea method on multiple different factory arrow function return objects and make it work for multiple shapes with a single function:

const multiplyThunk = (a, b) => () => a * b

const rectangle = (length, width) => ({
    length,
    width,
    getArea: multiplyThunk(length, width),
})

const square = (length) => ({
    length,
    getArea: multiplyThunk(length, length),
})

const circle = (radius) => ({
    radius,
    getArea: multiplyThunk(Math.PI, radius ** 2),
})

NOTE: Using the partial application is possible in ES6 classes, but there is a small chance you would need to do it as you would generally prefer to use this and extends.

Composition over Inheritance

Although inheritance is not available to us with factory arrow functions, we can choose composition over inheritance, which means that we can extend from multiple objects at once. This way, we can create lightweight objects with the methods and properties we really need in a specific situation.

NOTE: This is also possible with ES6 classes. This approach is called Mix-in.

const squarePerimeter = (length) => ({
    getPerimeter: () => 4 * length,
})

const squareArea = (length) => ({
    getArea: () => length ** 2,
})

const LengthyShape = (...features) => (length) => ({
    length,
    ...features.reduce(
        (acc, feature) => ({
            ...acc,
            ...feature(length),
        }),
        {},
    ),
})

const squareWithPerimeter = LengthyShape(squarePerimeter)
const square = LengthyShape(squarePerimeter, squareArea)

const sp = squareWithPerimeter(5)
sp.getArea() // Uncaught TypeError: sp.getArea() is not a function
sp.getPerimeter() // 20

const s = square(5)
s.getArea() // 25
s.getPerimeter() // 20

Static Methods

For the sake of convenience, you can imitate static methods. Static methods are methods on a class that can be called without instantiating the class itself. They are also non-callable when the class is instantiated, i.e. you cannot refer to them via this on the instance. Static methods are commonly used for utility functions in our app but they have other areas of application as well.

With factory arrow functions, we can declare properties on the functions themselves to obey both laws of static methods. We can declare static properties the same way.

const Square = (length) => ({
    length,
    getArea: () => length ** 2,
})

Square.new = Square

const s = Square.new(10) // <- Looks like Rust!
s.getArea() // 100

Conclusion

This article covered using factory arrow functions in JavaScript. In the next one, I extend the topic by covering factory arrow function usage with TypeScript.

I hope you enjoyed the read!

DEV Community: Sergei Orlov

An 85 Lines of Code Static Site Generator with Bun and JSX

TS config

Dealing with JSX in Bun

Building pages

Images in a Notion page with gatsby-source-notion-api

The syntax

The easiest way - remote images

But the image is on my computer...

Caveat

How to use code snippets with gatsby-source-notion-api

gatsby-remark-embedder

Markdown syntax

Images in "files" property with gatsby-source-notion-api

✅ Embedding files via links

💥 Uploading files

Storing attached images in the project repository

Uploaded files are in fact links

Factory arrow functions in TypeScript

It's a Series

Type Inference

Generic Factory Arrow Function Type

The I of SOLID

Least Knowledge and Interface Composition

Static Methods

Conclusion

Factory arrow functions in JavaScript

It's a Series

ES6 Class Recap

Factory arrow function

no this

Private properties

No Direct Inheritance And Internal Method Calls

Composition over Inheritance

Static Methods

Conclusion

no `this`