DEV Community: Andi Rosca

How I made my blog with SolidStart and MDX

Andi Rosca — Thu, 21 Nov 2024 16:25:25 +0000

Blog here: https://andi.dev/blog/how-solid-start-blog

SolidStart is to SolidJs what NextJs is to React.

It's a general "full-stack" framework that lets you SSR, CSR, SSG and all the other acronyms.

It comes with docs for SSG and a with-mdx starter template that lets you get started quickly with a markdown-powered static website.

So why am I writing this then?

Because a tech blog has a few extra requirements that are not supported by default and I had to figure out myself. Hopefully it saves other people some time.

I assume you're already familiar with how SolidStart works, especially the file-based router.

If you're not, the official docs do a better job at explaining it than I could.

List all posts programmatically

The FileRoutes router is great. But it doesn't expose any of the information that it has on its routes.

Most (if not all) blogs have some kind of list of latest posts on the homepage, or an archive somewhere. Ideally, we would generate that automatically, based on the files in the posts directory.

Now, I only have 5 posts in total on here. I could very well just keep a manual list of posts in code somewhere and update it when I add a new post file.

But I'd rather spend a day figuring out how to automate it, than 5 minutes doing it manually.

The most painless way I found to set this up is using a custom vite plugin.

The vite plugin

A vite plugin is just an object that conforms to the vite plugin api.

import type { Plugin } from "vite";

export const blogPostsPlugin = (): Plugin => {
  return {
    name: "blog-posts-gen",
    async buildStart() {
      processFiles();
    },
    configureServer(server) {
      server.watcher.on("change", (filePath) => {
        if (filePath.includes("/src/routes/blog")) {
          processFiles();
        }
      });
    },
  };
};

This is the whole plugin.

It does 2 things:

Calls processFiles when the build process starts (this is when you're building the website for prod)
It hooks into vite's dev server listener, and calls processFiles when any file in the /src/routes/blog directory has changed.

Make sure to add it to your app config

export default defineConfig({
  ...
    vite: {
        plugins: [
            ...other plugins
            blogPostsPlugin(), // Add it here
        ],
    },
  ...
});

Processing the files

Your processFiles function could look very different from mine, but here's what mine does:

import { resolve, join } from "node:path";
import { readdirSync, statSync, writeFileSync } from "node:fs";

const processFiles = () => {
    const outputFile = resolve("src/data/posts.json");
    const blogDir = resolve("src/routes/blog");
    const files = readdirSync(blogDir);

    const blogPosts = files
        .filter((file) => 
        statSync(join(blogDir, file)).isFile() && file.endsWith(".mdx")
      )
        .map((file) => ({slug: file.replace(".mdx", "")}));

    writeFileSync(outputFile, JSON.stringify(blogPosts, null, 2), "utf-8");
};

It gets all files ending with .mdx in the blog directory, and maps them to a json list of type { slug: string}[].

Then writes that list out to src/data/posts.json.

If the folder structure looks like

Then the json file will look like

[
  { "slug": "post-1" },
  { "slug": "post-2" },
  { "slug": "post-3" }
]

I'm using typescript so I have an extra file that imports the JSON and adds types to it:

import JSONPosts from "./posts.json";
type Post = { slug: string };
export const posts: Post[] = JSONPosts;

Using the posts list

Now that it's available as a module export you can import it and use it anywhere in your solid component:

<For each={posts}>
  {post => <a href={`/blog/${post.slug}`}>{post.slug}<a/>}
</For>

The best part of this (to me), is that the json file gets updated whenever there's a change in the blog directory.

That will trigger vite's HMR and automatically refresh any modules depending on it while you're developing locally.

Keep a post's metadata in the same file as the content

Posts do not only have their content. They usually also have some metadata associated with them.

The ones I wanted to support were:

Title
Publishing date
List of tags

I'm picky about co-locating things under the same domain.

In this case, I wanted to keep the metadata for a post in the same mdx file as where the content is.

The usual way of adding metadata to a markdown file is using the frontmatter.

I also wanted to use this metadata from my dynamic posts list.

You might've noticed the component above was using the slug to render the post links:

<a href={`/blog/${post.slug}`}>{post.slug}<a/>

But what should actually happen is using the post's title instead

<a href={`/blog/${post.slug}`}>{post.title}<a/>

Parsing the frontmatter

I ended up modifying the processFiles function to also parse the file frontmatter, using to-vfile and vfile-matter together.

const processFiles = () => {
    const outputFile = resolve("src/data/posts.json");
    const blogDir = resolve("src/routes/blog");
    const files = readdirSync(blogDir);

    const blogPosts = files
        .filter((file) => 
        statSync(join(blogDir, file)).isFile() && file.endsWith(".mdx")
      )
        .map((file) => {

      // Turn each of the post files into vfiles
            const vfile = readSync(resolve("src/routes/blog", file));
      // Parse their frontmatter
            matter(vfile);

      return { 
        // Add the frontmatter properties to each post's metadata
                ...(f.data.matter as object),
        slug: file.replace(".mdx", "")
      }
    });

    writeFileSync(outputFile, JSON.stringify(blogPosts, null, 2), "utf-8");
};

I write the frontmatter in yaml, so when I add the following to the top of a post:

---
title: This is my first post!
date: 2024-09-04
tags:
  - solidjs
  - solid-start
---

Then the metadata json will become:

{
  "slug": "post-1",
  "title": "This is my first post!",
  "date": "2024-09-04",
  "tags": ["solidjs", "solid-start"]
}

I can then use that metadata whenever I want to, and especially when rendering lists of posts:

<a href={`/blog/${post.slug}`}>{post.title}<a/>

Important info:

You should also install remark-frontmatter and add it to the remarkPlugins in app.config

export default defineConfig({
  ...
    vite: {
        plugins: [
            mdx.withImports({})({
                remarkPlugins: [remarkFrontmatter], // Add it here
            }),
        ],
    },
  ...
});

The reason for that is that you want the frontmatter to be excluded when the solidjs mdx pipeline transforms the mdx file into static html.

If you don't do this, you'll see the frontmatter rendered as html when you navigate to a post's page.

Compile-time code highlighting

The grumpy engineers on HackerNews got to me. I wanted to support code highlighting even if someone has javascript disabled.

That means moving the highlighting process from running on the client (the browser, using js), to it running when the static HTML is being generated.

I'm using refractor for that. It's a wrapper around prismjs that lets you do highlighting on virtual files.

To hook it into the solid-mdx building process, I had to create my own custom rehype plugin:

import { visit } from "unist-util-visit";
import { toString as nodeToString } from "hast-util-to-string";
import { refractor } from "refractor";
import tsx from "refractor/lang/tsx.js";

refractor.register(tsx);

export const mdxPrism = () => {
    return (tree: any) => {
        visit(tree, "element" as any, visitor);
    };

    function visitor(node: any, index: number | undefined, parent: any) {
        if (parent.type !== "mdxJsxFlowElement") {
            return;
        }

        const attrs = parent.attributes.reduce((a: any, c: any) => {
            if (c.type === "mdxJsxAttribute") {
                a[c.name] = c.value;
            }
            return a;
        }, {});

        const lang = attrs.lang;
        if (!lang) {
            return;
        }

        const result = refractor.highlight(nodeToString(node), lang);
        node.children = result.children;
    }
};

I won't go through the details of what it does exactly. The gist of it is that it finds the code blocks from the parsed markdown and uses refractor on them.

It needs to be added to the app config as well, under rehypePlugins

export default defineConfig({
  ...
    vite: {
        plugins: [
            mdx.withImports({})({
                rehypePlugins: [mdxPrism], // Add it here
            }),
        ],
    },
  ...
});

Refractor generates the same class names as prism, so as long as you have a prism theme css file loaded, it'll show some nice highlighting.

Full code example

I'm keeping the code for this website in a public github repo.

I tried to keep this article small, so if I missed anything, feel free look over the full working implementation in there.

Print and Run: Making a shitty language from scratch. Part 1.5

Andi Rosca — Thu, 30 Nov 2023 10:52:05 +0000

Intro

Welcome back to making a shitty language from scratch.

This is a smaller installment, hence the 1.5.

We left off with our implementation allowing for addition and subtraction to be done through our custom syntax.

This post will focus on cleaning up our code and introducing a couple of utilities that will come in handy for implementing variables in the upcoming Part 2.

PS: You can read the original here

Introducing the standard library (also known as STD)

You can think of the standard library as a set of functionality that a language comes with out of the box. There's some pedantic differences between functionality that's built directly into the language, and a standard library, but let's not worry about that.

For our purposes, the STD and built-in functionality are one and the same. And right now, we only have 2 functions in our standard library: "+" and "-".

As a first step in our cleanup, let's refactor things a bit so that the standard library is more evident in the code. If you don't remember, the final code for Part 1 looked like this:

const sum = (numbers) =>
    numbers.reduce((sum, n) => sum + n, 0);

const EVALUATE = (input) => {
    if(!Array.isArray(input)) {
        return input;
    }

    const [fn, ...rawArguments] = input;
    const arguments = rawArguments.map(arg => EVALUATE(arg));


    if(fn === "+") {
        return sum(arguments);
    }
    if(fn === "-") {
        const [first, ...rest] = arguments;
        return first - sum(rest);
    }

    throw Error("Function not supported:", fn);
}

We will extract the "+", and "-" functions into a std object. This object will hold all future std functionality as well:

const sum = (numbers) =>
    numbers.reduce((sum, n) => sum + n, 0);

// A more readable standard library
const std = {
    "+": (args) => sum(args),
    "-": ([first, ...rest]) => first - sum(rest)
}

const EVALUATE = (input) => {
    if(!Array.isArray(input)) {
        return input;
    }

    const [fn, ...rawArguments] = input;
    const arguments = rawArguments.map(arg => EVALUATE(arg));

    if(std[fn]) {
        return std[fn](arguments);
    }

    throw Error("Function not supported:", fn);
}

You'll notice that in the body of the EVALUATE function, we've replaced the if statements for each individual operation with a generic if(std[fn]) statement. This will check if the function exists in the std, and if it does it will call it with the arguments array and return the result.

Now the body of the evaluator should stay slim, even if we add another 50 functions in the standard library.

Printing

I should've started this series with implementing a print function and running a "hello world" program.

It's not too late to add one now. It will be useful for debugging future programs once the language gets more complex.

First we will add a new function to the std:

const std = {
    "+": (args) => sum(args),
    "-": ([first, ...rest]) => first - sum(rest),
    "print": (arguments) => console.log(...arguments)
}

Luckily, console.log already handles printing multiple arguments so our print function is a very thin wrapper around it.

Since we already have the generic if statement in the evaluator, we don't need to add any extra code.

Running

EVALUATE(["print", "hello", "world"]);

will print "hello world" to the console.

We can also combine printing with the math operations we implemented last time:

EVALUATE(["print", ["+", 4, ["-", 3, 10]]]) // should log -3

<sub>Note<sub>

We're going to make our language have a functional programming flavor.

One of the most important features of a functional language is that **everything** is an expression. That means that anything you write in that language will result in a value.

A good explanation for statements vs expressions is the difference between if statements and the ternary operator.

You can't do `const myVar = if(x) 10 else 20;`. The if/else statement doesn't result in a value, it just runs the code inside the branch.

But you can do `const myVar = x ? 10 : 20;` because the ternary operator is an expression, and expressions always result in values.

Let's make the print function an expression and not just a statement.

It's very simple, all it has to do to be an expression is to result in a value. And how do functions result in values? By returning something.

const std = {
    ...
    "print": (arguments) => {
        console.log(...arguments);
        return arguments;
    }
}

It might seem inconsequential to do this, but if we stick with it for all of the language's functions, you'll notice the pay-off at the end for the kind of programs you can write when everything is an expression.

Ok, printing is done, let's switch gears to other improvements we can make.

Running multiple statements

Have you noticed that our evaluator only accepts one top-level function at a time? We can only evaluate either a print, +, or - function. These functions accept arguments that are other function calls, but we can't string multiple function calls at the top-level.

What if you want to run multiple unrelated instructions, like in a real language?

There are a few ways to do this, like allowing the evaluator to accept an array of statements as well as a single function call. Which would look like:

EVALUATE([
    ["print", "hi"],
    ["print", "this is another statement"],
]) // the 2 print statements are unrelated to each other

But that can introduce weird edge-cases to handle all throughout our interpreter.

Remember that we call evaluate on all of the arguments recursively. So we'll then have to implement some code to distinguish arrays made of instructions, or function calls.

Maybe it's possible to distinguish:

["print", ["+", 1, 2], ["-", 6, 8]]

From:

[["print", ["+", 1, 2]], ["print", ["-", 6, 8]]]

But do we want to have to deal with that?

The easier choice is to do what we've been doing until now: add another function to our std.

We'll call this function run, since it'll be used to run multiple instructions. Adjusting the example above, the program would look like this instead:

EVALUATE(["run",
    ["print", "hi"],
    ["print", "this is another statement"],
])

You can see that the function run is called with two arguments, the two print function calls.

But what should run return?

This is where we will take inspiration from functional languages again.

In an imperative language like JS, we have an explicit return statement. And a return statement is the last operation that happens before a function call results in a value.

In functional languages, every instruction is also an expression that results in a value. The usual convention is that rather than using an explicit return syntax, they implicitly return the last expression's value.

Think of this imaginary language's function:

function test() {
    "a string";
    someFunctionCall();
    10;
}

The last evaluated expression is the hardcoded number 10, and that's what the test function will return implicitly.

Now let's implement returning the last argument for the run function:

const std = {
    ...
    run: (args) => args[args.length - 1]
}

We could change our print function to also return only the last argument, for uniformity. We'll extract the logic for getting the last argument in a separate function as well:

const std = {
    "+": (args) => sum(args),
    "-": ([first, ...rest]) => first - sum(rest),
    last: (args) => args[args.length - 1],
    print: (args) => {
        console.log(...args);
        return std.last(args);
    },
    run: (args) => std.last(args)
}

🎉 Notice how there's still no need to change the EVALUATE function's body, even with all these std changes!

Final code

Now we're in a good place to implement variables in Part 2. Stay tuned for it.

Here is the full code up until now

const sum = (numbers) =>
    numbers.reduce((sum, n) => sum + n, 0);

const std = {
    "+": (args) => sum(args),
    "-": ([first, ...rest]) => first - sum(rest),
    last: (args) => args[args.length - 1],
    print: (args) => {
        console.log(...args);
        return std.last(args);
    },
    run: (args) => std.last(args)
}

const EVALUATE = (input) => {
    if(!Array.isArray(input)) {
        return input;
    }

    const [fn, ...rawArguments] = input;
    const arguments = rawArguments.map(arg => EVALUATE(arg));

    if(std[fn]) {
        return std[fn](arguments);
    }

    throw Error("Function not supported:", fn);
}

Syncing solid-js resources to a global store

Andi Rosca — Thu, 23 Nov 2023 22:37:50 +0000

Solid provides a createResource function that gives you a few niceties out of the box for working with async data.

Stuff like:

automatic refetching on reactivity changes
signals for checking if the data is loading
and of course, Suspense.

Suspense can't be triggered any other way, so most solid apps are going to be using resources extensively.

The drawback is that createResource pushes you into a pattern of data locality, where the data is only being used in the component that defined the resources (or it's children).

Data locality is nice until it isn't

Most complex web-apps make use of a global state, and tying data management and fetching to components makes it clunky to properly sync data between global and local.

A naive first approach for achieving this syncing might look like this:

const [data] = createResource(fetchData);
const [state, setState] = useContext(GlobalState);

createEffect(() => {
  setState("data", data());
});

The issue with this is that you can sync the data to the store, but if there's any reactive change to the data in the store, the resource data wouldn't change.

So syncing only works one way resource -> store.

The storage option

Solid resources accept a storage property that can be used to override the internal logic for holding the resource's data.

We can imagine the simplified internals of a createResource to look something like this:

const createResource = (fetchingFunction) => {
  const [data, setData] = createSignal();
  createEffect(() => {
    fetchingFunction().then(result => setData(result));
  })
}

The resource fetches the data automatically and stores the result in a reactive signal.

The storage option would let us replace that createSignal call with any other function that has the return type as a signal, which would be [Getter, Setter].

The solid docs have an example of using the storage option to store the data in a solid store instead of a signal. See createDeepSignal here.

function createDeepSignal<T>(value: T): Signal<T> {
  const [store, setStore] = createStore({ value });
  return [
    () => store.value,
    (v: T) => {
      const unwrapped = unwrap(store.value);
      typeof v === "function" && (v = v(unwrapped));
      setStore("value", reconcile(v));
      return store.value;
    }
  ] as Signal<T>;
}

In this example, using a store alongside the reconcile function for setting data is done for the purpose of having the fetched data be reactive only on the properties that have changed value instead of the whole data object triggering reactivity.

Abusing the storage option

But what if we take this example further, and instead of creating a new store for each resource, we create a custom storage function that gets and sets data to a global store?

Let's assume we have a solid store we can access through a hook like:

const [state, setState] = useGlobal();

And that the store's state is:

{
  songs: [
    {name: 'Never Gonna Give You Up', rating: 8},
    {name: 'Windows Erros Remix [10 Hours]', rating: 10}
  ]
}

What we would want is that in our component, we use a resource that fetches the songs data and manages local state for loading.

But that the resource is backed by the global state, so that if there are any changes to the songs in the global state, the changes would be reflected in the resource, and the other way around as well. Two-way binding: store <-> resource.

const storeBackedSongs = () => {
  const [state, setState] = useGlobal();

  const getter = () => state.songs;

  const setter = (value) => setState('songs', songs => {
    // setters can receive either a value, or a function
    // that returns a value for that reason we need to handle both cases
    if(typeof value === "function") return value(songs);
    return songs;
  });

    return [getter, setter];
}

// Using it in a component
const Songs = () => {
  const [songs] = createResource(fetchSongs, {storage: storeBackedSongs});

  return <Suspense fallback={<Loading />}>
    <SongsList songs={songs()} />
  </Suspense>
}

Now if somewhere else in the app someone changes the songs through the store:
setState("songs", []);

If the resource and component are still mounted, the SongsList component will update with the empty array value.

Similarly, if you change the value of the songs resource, either by refetching or with a mutate, that will update the store state and reflect the changes in all places where store.songs is used.

const [songs, {mutate, refetch}] = createResource(fetchSongs, {storage: storeBackedSongs});

// Both of these calls will update not only the resource's data, but store.songs as well
mutate([]);
refetch();

SSR

For people using solid-start, this pattern works just as well for createRouteData and the other route data functions, since they all wrap around resources and expose the storage option.

Extra info

The example above is simplified so it's easier to understand the main points.

The code does work, but it's missing types. If you were to copy the implementation and you're using typescript you will run into some weird type issues stemming from the complex generic type that storage accepts.

I have published a full working example here: link to repo.
It has proper types and also a generic createResourceStorage function that you can copy and reuse to simplify your code.

Happy coding!

Making a shitty language from scratch. Part 1

Andi Rosca — Thu, 23 Nov 2023 12:23:30 +0000

Intro

I believe the best way to learn how things work is to make your own shitty version of them from scratch.

Does creating a programming language feel like some forbidden knowledge that only the top geniuses have access to? It shouldn't.

Welcome to what I call the shitty series, where we'll be reinventing all kinds of wheels, but badly.

Wobbly Wheel, by me. NFT available for 500k

First installment: Making a shitty programming language.

PS: You can read the original here

Getting started

First of all, some constraints for the language:

Interpreter is implemented in JS.
The programs should be parsable by JSON.parse. We don't want to waste time writing a parser.
Minimum of features. It should barely pass as a programming language if you squint hard enough.
Parentheses everywhere (((((yes we're making a lisp inspired language))))).

It's ok if some of the bullet points don't make sense. Here's some extra context about language development terms.

Feel free to skip to here if you already know them.

Syntax

The structure of a program. How the instructions look.

In JS, the syntax for defining a variable is let name = value; for example.

Interpreter

An interpreter is a program that takes the text input of a program and executes the instructions. The interpreter can be implemented in any existing programming language, in our case JavaScript.

An interpreter for math would take this text input

2 + 5 - 3

and execute it so that it results in 4.

Parser

A parser is the part of the interpreter that takes the text input and translates it into a format the the implementation language can understand.

In our case, since we're using JS, instructions would be in a JSON format.

So the parser could take the text

2 + 5 - 3

and translate it to a list that the interpreter can then go over and execute

[2, "+", 5, "-", 3]

Most literature online for making languages spends a lot of time focusing on parsers. That's the first step that needs to happen before you can implement the execution of instructions.

I want this series to be focused on what makes programs tick and how a language runs code internally. That's why one of our constraints is that the syntax for our program should already be a valid JSON. That way JS can understand it without extra parsing.

Taking the math example, we'd define the program directly as a JS list, instead of a string input:

const program = [2, "+", 5, "-", 3];

Lisp

Lisp is a family of languages known for their weird syntax with a lot of parentheses.

They're a good place to draw inspiration from for toy languages because the syntax is very minimal. But you don't need to know anything about them to follow along.

Part 1

In Part 1 we'll focus on a small slice of what could be considered a programming language.

We'll define some of the syntax of the programs, and implement a simple interpreter that can perform math operations.
A calculator with extra steps.

Math, all languages can do math

We're used to the standard notation of math being chained with operators like so:

12 + 3 + 5 - 8 * 12

But remember we're trying to define our syntax in a way that we can store it in a JS object.

So let's take it step by step:

What if we considered a math operation to be a function that can be called with multiple arguments.

From

12 + 5 + 3

addition(12, 5, 3)

Pretty verbose, so let's use the operator sign instead:

+(12, 5, 3)

That's still not valid. We can't store the + in a JSON, better make it a string.

"+"(12, 5, 3)

Ok, that's closer, but the parentheses don't mean anything to JSON either, let's make the arguments a list:

"+"[12, 5, 3]

It's almost parsable now. The missing piece is the + being outside of the list and screwing things up.

We could move it into the list:

["+", 12, 5, 3]

We now have perfectly valid JSON syntax, but the function is in the same list as the arguments.

That's not an issue though, we can just decide that in our language's syntax, the first item in a list is a function to be called, and the rest of the items are it's arguments.

It's like going from addition(12, 5, 3) in JS to (addition, 12, 5, 3) and then converting that to a JSON list.

One more thing to figure out. How should multiple operations like 25 - 4 + 6 be defined?

We can just nest multiple lists:

["-", 25, ["+", 4, 6]]

Or with slightly better formatting

["-", 25,
      ["+", 4, 6]]

Yes it's ugly, but remember we're making the language version of a brutalist building:

Photo by Jens Aber on Unsplash

Baby steps

We have our basic syntax, let's throw some code together to make it work.

We should start small, with the simplest program we can make. An interpreter that takes a single addition operation, adds up all the numbers, and returns the sum.

No nesting, no other math.

We'll call the main interpreter function EVALUATE and calling it like so

EVALUATE(["+", 4, 6, 23])

Should return 33.

Here is the code to make that happen

const EVALUATE = (input) => {
    // first we destructure the input,
    // getting the first argument as the function to call
    // and the rest of the items as the arguments of the function
    const [fn, ...arguments] = input;


    // Then we handle our addition operator
    // When the function is +, we sum up all the arguments
    if(fn === "+") {
        return arguments.reduce((sum, n) => sum + n, 0);
    }

    // And finally we can throw an error
    // If we don't recognize the function
    throw Error("Function not supported:", fn);
}

console.log(EVALUATE(["+", 4, 6, 23])) // should log 33
console.log(EVALUATE(["-", 10, 12])) // will throw an error

Nice, and now for handling subtraction:

// Extracted the sum to a function
const sum = (numbers) =>
    numbers.reduce((sum, n) => sum + n, 0);

const EVALUATE = (input) => {
    const [fn, ...arguments] = input;

    if(fn === "+") {
        return sum(arguments);
    }
    if(fn === "-") {
        const [first, ...rest] = arguments;
        // we subtract all other numbers from the first one
        return first - sum(rest);
    }

    throw Error("Function not supported:", fn);
}

console.log(EVALUATE(["+", 4, 6, 23])) // should log 33
console.log(EVALUATE(["-", 10, 4, 6])) // should log 0

Nesting

As mentioned before, if we want to do multiple operations, we need to nest lists within lists:

["-", 25, ["+", 4, 6]]

How will our program know how to handle a list inside a list?

If we looked at the execution of ["-", 25, ["+", 4, 6]] step by step, this is what would happen now:

Program is on "-", enters the relevant if statement
Program gets the first argument, the number 25 and wants to subtract the rest from it
Program encounters the list ["+", 4, 6], can't subtract it, throws error

At step 3, what we want the program to actually do, is see that there is a list there, and run EVALUATE on it.

The evaluate call will spit back out a number, in this case 10, and then we can continue the subtraction to get 25 - 10.

But a list can appear as any of the arguments, and lists can be nested infinitely inside each other.

const program = ["-", ["+", 10, 5],
                      ["+", 3,
                            ["-", 12, 6]]];
// translates as (10 + 5) - 3 + (12 - 6)

Our program should be able to handle more complicated cases like these.

That means that we should be calling EVALUATE on all of the arguments of a list, just in case any of them are lists themselves.

// in the EVALUATE function
const [fn, ...rawArguments] = input;
const arguments = rawArguments.map(arg => EVALUATE(arg));

But what about when an argument is a number?

Calling EVALUATE on a number will throw an error, since the first line is us destructuring the input:

const [fn, ...arguments] = 6; // JS doesn't like that

A simple and elegant solution for that, is to add an extra case at the top of the evaluator where if the input is not a list, it should spit it back out and not try to evaluate it.

const EVALUATE = (input) => {
    if(!Array.isArray(input)) {
        return input;
    }

Now when some of the arguments are numbers and the evaluator runs this:

const arguments = rawArguments.map(arg => EVALUATE(arg));

The arguments that are not arrays will just be returned back immediately.

A nice side-effect of handling it this way is that now, a single number is also a valid program.

const result = EVALUATE(3); // works and returns 3

Full code

const sum = (numbers) =>
    numbers.reduce((sum, n) => sum + n, 0);

const EVALUATE = (input) => {
    // Handling base case of numbers being evaluated
    if(!Array.isArray(input)) {
        return input;
    }

    const [fn, ...rawArguments] = input;
    // evaluating all arguments to handle nested lists
    const arguments = rawArguments.map(arg => EVALUATE(arg));


    // handling supported functions
    if(fn === "+") {
        return sum(arguments);
    }
    if(fn === "-") {
        const [first, ...rest] = arguments;
        return first - sum(rest);
    }

    throw Error("Function not supported:", fn);
}

console.log(EVALUATE(["+", 4, ["-", 3, 10]])) // should log -3

Bonus: Our code above will actually also work with infinite nesting situations.

Since we're always calling evaluate on arguments, we're also calling evaluate on arguments of arguments, and arguments of arguments of arguments, etc.

Whenever there's a list inside a list, we call evaluate on the nested list's arguments as well, and so on.

The complicated example we had above:

["-", ["+", 10, 5],
      ["+", 3,
            ["-", 12, 6]]];

Will return 6 when evaluated.

We just accomplished recursion and we didn't even need to think about things recursively.

Recursion is hard to wrap your head around if you're not familiar with it already, I recommend placing a debugger; statement at the top of the evaluator and going step by step through it in developer console of a browser to get a more intuitive understanding of what's going on.

It's an important concept to grasp for language development, since most useful languages have syntax that is recursive in nature, i.e. you can nest things inside of things infinitely.

Part 2 coming soon

Stay tuned for Part 2, we'll implement defining variables next.

Do you think learning low-level programming concepts is important for web-devs?

Andi Rosca — Wed, 20 Apr 2022 18:28:35 +0000

How to write better reusable code

Andi Rosca — Wed, 07 Apr 2021 21:18:08 +0000

Side-note, the original article contains some interactive elements that are only images here.

Code that is easy to reuse is not very customizable, and code that is very customizable is not as easy to reuse.

Think of the difference between

<custom-button color="red">Cancel</custom-button>

and

<custom-button color="red" async="true" size="big" border="false" type="cancel">
  Cancel
</custom-button>

You can do more stuff with more code, but that comes with the cost of spending more time setting things up, i.e. boilerplate.

Just think of all the abstract factory makers you've worked with if you've ever written some Java.

How can we write code that is easy to use by other developers, without sacrificing on the ability to customize?

Abstraction

A good abstraction hides away the details that the developer doesn't care about, and only exposes the relevant bits and pieces.

It's like when you try to explain your code to a non-technical person. You gloss over a lot of the details and years of knowledge you accumulated, and use more simple language and analogies that can convey the main idea.

Think of an HTML element such as the input.

As a user of the HTML abstraction, you don't care about the inner workings of the browser that make it possible to have an interactive text-box presented to the user.

What you care about is that when you write <input type="text" /> the user can now enter some data.

But if an abstraction hides too many things, then it becomes useless in all but the most basic cases.

Imagine if the input element didn't even let you change the placeholder text.

Soon, a lot of developers would be doing:

<div class="my-input-class" contenteditable="true">
  <span>Placeholder text...</span>
</div>

Instead of

<input type="text" placeholder="Placeholder text..." />

If you think that's a stretch you can look into recommended ways of replacing browser checkboxes with custom styled ones like this one. Almost all involve hiding the original box and replacing it with an svg or html/css one you made yourself.

It's about balance ☯

So an abstraction's job is to hide things away from the user, so that they can focus on the task at hand. But also to not hide away too many things, in case the user wants to customize it to suit their needs.

If it sounds like creating a good abstraction is hard to do, that's because it is.

Your job as a developer is to navigate these complexities and walk the fine line between too complex and too simple.

Let's see a few mental models and recipes that can get you started.

Pattern 1: Sane defaults and escape hatches

This pattern is as simple as it sounds.

Imagine you're making a recipe website for the singer Pitbull, who has recently taken up cooking.
He's known as Mr. World-Wide™, so the website has to support all languages of the world.

It's a fair assumption to make that most people visiting your website from Spanish, Mexican, Colombian addresses speak Spanish, so you make your default language for those IPs, well, Spanish.

You also know that there's such a thing as expats in the world, so you provide selection box at the top of your website to change the language.

Mr. World-Wide™ is indeed happy with your services.

Setting the default language to Spanish is a sane default; a good assumption to make on how users will use your product/code/feature. You're now saving ~80% of people time from changing the language themselves.

The language selection box at the top is an escape hatch. For the rest of the users to whom the assumption doesn't apply, you offer a way for them to make changes.

The escape hatch does make some people do more steps to use your website, but it doesn't make it impossible for them to use it.

The same principle applies to writing reusable code. You want to save time for 80% of the developers using your code, but leave a way for the rest of 20% to customize it to suit their needs.

Obviously, most situations won't be as cut and dry as the example I've just provided. The hard part about applying this pattern is that you need to know what the most common use cases are, which requires insight into the users of your code before you've even started writing it.

However, it generally doesn't help if you obsess over what your potential users will try to do.

If it's not obvious what the common use case is from the beginning, try the following things:

Dogfooding 🐶

Dogfooding refers to eating your own dog food, i.e. use your own code yourself, in realistic scenarios.

The more different real-life scenarios you can come up with to test your code, the better of a picture you will have of your code's shortcomings and what you can change to accommodate your future users.

Focus on the escape hatches 🚀

If after dogfooding it's still not super clear which features of your code you should make easy by default, you can try another approach and leave the figuring out for later.

The way to do this and minimize breaking changes is to focus on building your escape hatches and making your code customizable.

The more generically customizable it is, the better the chances of you being able to make modifications in the future without causing breaking changes.

There is however the tradeoff that making things too customizable may make the internal implementation too complicated to maintain.

Example

Let's say you have made a vanilla JavaScript button library that provides the coolest button the world has ever seen:

const btn = new BestestButton("Amazing button");

From dogfooding you learn that it's very common to need to include icons, or loading spinners for buttons triggering async actions, etc.

Now you may not know exactly which case you should support and make easiest for your amazing button, but you can ignore that for now and build in escape hatches that will enable you to consolidate the library later on, without having breaking changes.

In this particular case you could add the following escape hatches for your users (and yourself):

Make the button constructor accept both strings and HTML elements for the content shown inside
Accept a second argument which will be a configuration object

const btn = new BestestButton(
  // Instead of only strings users can add their own custom html elements
  elementContainingIconAndText,
  // Generic configuration object that can be extended with
  // other accepted properties
  { animateClick: true }
);

The example I've laid out is quite simple and had possibly obvious answers, but the same principles apply to more complex scenarios.

It'll probably take longer to come up with good escape hatches but anythings possible with enough time spent.

Pattern 2: Do one thing well

I named it a pattern for the sake of title consistency but this one's more of a philosophy. You should start thinking about it before any line of code is written.

What "do one thing well" means is that you should very clearly define what your code can do, and what it won't do.

Let's say you've decided to create an HTML Canvas library for making interactive 2D shapes that you can select and drag around. You go ahead and implement a great library that many people use and like.

However, you start noticing that many users report the library rendering very slowly when there are more than 5000 shapes, and they all urge you to also provide a WebGL rendering option, for high-performance needs.

It is up to you now to decide if the one thing that your library does well is either:

Makes drawing 2D shapes on the Canvas easy
Makes drawing 2D shapes in the Browser easy

It's your choice what the scope of your library is, but it should be a conscious choice.

Don't just go with the flow 🌊

If you get pressured into implementing version 2, people might start requesting for you to add more functionality. Maybe they want special options for the WebGL. Maybe they want you to add basic 3D shapes as well.

You might wake up in a few years realizing you implemented Blender in the browser, when all you actually wanted to do was to drag some rectangles around.

Stick with what you believe is best

If you stick with your initial scope and purpose, you can spend more time to improve the features that are already there.

You could still implement that WebGL rendering option for performance gains, but this time as part of the goal of the library.
If people start requesting basic 3D shapes, you can simply say that implementing that would defeat the purpose of the library.

You can make multiple things that do one thing well

If you do think a browser based Blender is cooler and want to implement a WebGL 3D editor, there's no reason why you can't create a new library that does that one thing very well, without changing your 2D Canvas code.

Part 2 coming soon

There are more tips I would like to share with you, but I want to keep articles at a manageable length.

Stay tuned for part 2 of this post!

You can subscribe to get email notifications on the original post page (at the bottom): https://godoffrontend.com/posts/terseness-vs-control/

It's OK to break out of the Vue paradigm (sometimes)

Andi Rosca — Sat, 26 Sep 2020 17:43:28 +0000

The Vue way™ to do things is great.

The pipeline Data->Template->DOM works remarkably well.
You specify the data and the template and let Vue do the grunt work of connecting them together into the real DOM.

There are times however, when abiding by this clean paradigm can make implementing a certain feature feel like an uphill battle, maybe even impossible.

It's important to know when it makes sense to break out of the Vue loop and sidestep the issues with some plain JavaScript.

"Global" DOM behavior

The number one biggest problem you will run into that can't usually be solved the Vue way is when you need to access some type of DOM functionality that doesn't fit into Vue's component based parent/child paradigm.

Imagine the following scenario: You're implementing a panel that can have it's width resized by dragging a handle.

The "naive" way to do it is to use the Vue v-on directive to listen for mouse/touch events.

<div class="relative inline-block">
  <div :style="{ width: `${width}px` }" ref="panel"></div>
  <button
    class="handle"
    @mousedown="startDrag"
    @mousemove="drag"
    @mouseup="stopDrag"
    @touchstart.prevent="startDrag"
    @touchmove.prevent="drag"
    @touchend.prevent="stopDrag"
  />
</div>

export default {
  data() {
    return {
      width: 300,
      offset: 0,
      dragging: false,
    };
  },
  methods: {
    startDrag() {
      const { left, height } = this.$refs.panel.getBoundingClientRect();
      this.offset = left;
      this.height = height;
      this.dragging = true;
    },
    drag(e) {
      if (this.dragging) {
        if (e.touches) this.width = e.touches[0].clientX - this.offset;
        else this.width = e.clientX - this.offset;
      }
    },
    stopDrag() {
      this.dragging = false;
    },
  },
};

I say naive because with this approach, if you drag the mouse around too quickly the pointer will leave the handle and then the listeners attached to it will stop triggering.

Head onto the original post to try out the interactive component.

To combat this problem what you would need to do is to register the mousemove and mouseup events on the document itself, so that even when the pointer goes out of the handle, the listeners will still trigger. And since accessing the document object randomly from any component is not Vue's concern, you just have to do it in regular JS.

<div class="relative inline-block">
  <div :style="{ width: `${width}px` }" ref="panel"></div>
  <button
    class="handle"
    @mousedown="startDrag(true)"
    @touchstart.prevent="startDrag(false)"
    @touchmove.prevent="drag"
  />
</div>

export default {
  data() {
    return {
      width: 300,
      offset: 0,
      dragging: false,
    };
  },
  methods: {
    startDrag(mouse) {
      const { left, height } = this.$refs.panel.getBoundingClientRect();
      this.offset = left;
      this.height = height;
      if (mouse) {
        document.addEventListener("mouseup", this.drag);
        document.addEventListener("mousemove", this.stopDrag);
      }
    },
    drag(e) {
      if (e.touches) this.width = e.touches[0].clientX - this.offset;
      else this.width = e.clientX - this.offset;
    },
    stopDrag() {
      document.removeEventListener("mouseup", this.drag);
      document.removeEventListener("mousemove", this.stopDrag);
    },
  },
};

The above example might seem trivial, we're just adding some event listeners ourselves. But the point is that even in situations that are not as obvious as this, you should ask yourself if you're fighting Vue needlessly when you could just call the DOM APIs yourself.

Not only event listeners

Though the example focused on event listeners, there's other(less common) types of global DOM functionality you might run into, that will require you to side-step Vue.

If you had to make a notifications component, you would probably need to append your HTML to the end of the body tag to ensure it will always stay on top of the other content. Same goes for modals (tough with Vue 3 this case is mitigated through the use of teleport).

Working with the Canvas or WebGL will also require you to make the connection between data and rendering yourself.

And finally, wrapping third party libraries also requires you to manually connect the reactive data to the relevant properties and function calls in the library, since many packages need to have control over the rendering.

Organize your JavaScript OOP code better with this functional programming trick

Andi Rosca — Mon, 07 Sep 2020 20:52:12 +0000

Pure functions

One of the main characteristics of functional programming is the concept of pure functions.

Pure functions:

always return the same value when called with the same arguments
never change variables that are outside of their scope

This is what a pure function looks like:

function add(a, b) {
  return a + b;
}

Class methods

A class method is generally the opposite of a pure function.

The purpose of class methods is usually to operate in some way on a class instance (they can do other things of course).

class Point {
  add(point) {
    this.x += point.x;
    this.y += point.y;
    return this;
  }
}
const point = new Point(2, 3);
const point2 = point.add(new Point(3, 4));

How things can get messy

An often encountered problem when using methods in this way is that you are always working on the same class instance. This is fine when you only have one or two objects you're using.

But the more operations and objects your code needs to use, the more you need to keep track of references to instances and making sure you're not mutating objects that are also referenced by other parts of the code accidentally.

Look at this moment.js code for example:

const startedAt = moment();
const endedAt = startedAt.add(1, "year");

console.log(startedAt); // > 2020-02-09T13:39:07+01:00
console.log(endedAt); // > 2020-02-09T13:39:07+01:00

They both log the same time because you unwittingly mutate the startedAt variable as well, since the add method behaves much like the add method I defined on the above Point class.

Seems like an easy problem to spot, but imagine if you have around 15 lines of operations involving multiple objects. Time to whip out the console.logs on every other line.

A better way

With these simple examples, the answer should be clear: You should make your methods "pure".

I say "pure" because the characteristic we care most about is that they should not mutate any values.

Let's rewrite the Point's class add method:

class Point {
  add(point) {
    return new Point(this.x + point.x, this.y + point.y);
  }
}

Now instead of returning a reference to the same instance, you create a whole new instance.

You can chain methods all you want now since you don't need to worry about mutating existing variables.

const point1 = new Point(2, 3);
const point2 = new Point(3, 4);
const point3 = point1
  .add(point2)
  .add(point1)
  .add(point2);

Structuring your classes this way will also make debugging and unit testing way easier, since now you can test the output directly, instead of checking for variables getting mutated properly.

Another nice benefit is that it works nicely with the reactivity systems of libraries like Vue and React. Since creating new instances will be sure to trigger their "reactiveness".

What are you struggling with? (frontend)

Andi Rosca — Thu, 27 Aug 2020 09:37:18 +0000

Hi,

I enjoy spending my time helping people with programming stuff, so I will do my best to help you with any frontend related question or problem.

The kind of questions I will be able to best help with:

How to implement a certain feature
Code structure / design
JavaScript / Vue / CSS / HTML / WebGL related questions

What I will do my best with but can't make any promises on are questions related to configuration (webpack, modules, etc.) or problems with libraries I'm not familiar with.

A PM is also ok if you don't want to post a comment 👍.

How to handle input data conversion in Vue

Andi Rosca — Tue, 25 Aug 2020 20:18:30 +0000

Here is a piece of functionality that all of us either have or will run into when developing web apps:

You have an interactive component through which the user can change a value, but there is some discrepancy between how you store the value and how you present it to the user.

That was a mouthful, so let's understand the use-case better with a concrete example:

Let's say you want to make a slider that will control the amount of blur on an image. The value of the blur you pass to the filter on the image should be between 0 and 8 pixels, with decimal values allowed as well. For the sake of the user, you want the slider to show values between 0 and 100% instead, and take care of the conversion yourself.

(Check out the original link for the interactive version and a bonus example at the end)

The common way to tackle this would be to define a method that gets called on every change to the input, and then modify an instance variable like so:

<range-slider :value="percentageBlur" @input="sliderInput" />
<img
  src="https://placeimg.com/1000/480/arch"
  :style="`filter: blur(${blur}px)`"
/>

export default {
  data() {
    return {
      blur: 0, // Value in pixels, passed to the image blur filter
      percentageBlur: 0, // Value in percentages, passed to the slider
    };
  },
  methods: {
    sliderInput(value) {
      this.percentageBlur = parseInt(value);
      this.blur = (value / 100) * 8; // Converting from 0-100 to 0-8
    },
  },
};

While the above code is perfectly fine, and does what it's supposed to, I've personally noticed that it brings with it a few inconveniences.

First of all, when a component gets more complicated, with more methods and data properties, the part of the code that handles the "blur logic" is now scattered across the component. You have your values in the data section, and the code setting them in the methods section. It might not seem like a big deal, but later on, when you don't remember how you implemented it, you'll be jumping up and down in the file trying to track all of the places where you're handling the blurring.

And second of all, you can't use v-model on your input element. If the range-slider component was from a library you installed and it emitted a change event instead of an input event, you would need to track the documentation down and see why your code is not working, whereas v-model would automatically check the settings and wrap the right event. Plus, it just looks nicer to have a single v-model argument in the template instead of 2 separate ones.

Get/Set computed props to the rescue

The way to solve the inconveniences above is to use the alternative syntax for computed properties, get/set.

While it is mentioned in the Vue documentation, not many developers know or use this syntax, probably because the docs don't fully specify when it makes sense to use it.

If you don't already know about it, the get/set looks like this:

computed: {
  myProp: {
    get() {
      // When you try to get the value this.myProp in your component
      // you will get the return of this function.
      return this.value;
    },
    set(value) {
      // When you set the value like: this.myProp = 10
      // the prop this.value will be set to 10
      this.value = value;
    }
  }
}

The code above essentially defines a transparent wrapper around the this.value prop.

To make things more interesting, lets apply this new knowledge to the use case of the image blurring:

<range-slider v-model="percentageBlur" />
<img
  src="https://placeimg.com/1000/480/arch"
  :style="`filter: blur(${blur}px)`"
/>

export default {
  data() {
    return {
      blur: 0, // Value in pixels, passed to the image blur filter
    };
  },
  computed: {
    percentageBlur: {
      get() {
        // Converts the 0-8 blur values to percentages
        return Math.round((this.blur / 8) * 100);
      },
      set(value) {
        // Converts the percentages to 0-8 values and assigns
        // them to the original blur
        this.blur = (value / 100) * 8;
      },
    },
  },
};

Notice the difference? We can now enclose the functionality for the blurring conversion into one "unit" of code, the computed property. Doing it this way allows us to also declutter the template by using the v-model directive.