DEV Community: Basti Ortiz

Coding Agents as a First-Class Consideration in Project Structures

Basti Ortiz — Mon, 05 Jan 2026 13:00:34 +0000

Coding agents have arguably been the most revolutionary unlock in software engineering since... ever? (Citation needed!) Post-2023, we have lived in a world where probabilistic machines now write much of the world's software for better and worse.

But, we're not here to argue if it's for the best. The genie is already out of the bottle, and the most productive way forward is figuring out the best way to use these new tools to ship better (correct!) software faster.

Working with Context Windows as the Bottleneck

LLMs have only a limited number of tokens within its operable context window. As the context window fills up, these models tend to degrade in performance. It is therefore in our best (operational and financial) interests to optimize for token efficiency and effectivity. The last thing we want is to be billed exorbitantly just for sub-par results.

Many developers swear by the "40% Rule", where it's been found (anecdotally) that LLMs tend to considerably degrade in output quality past 40% of its context window. In my experience, it hasn't been so bad with the latest frontier models, but it never hurts to live by this principle regardless of the latest advancements.

So, how do we structure a codebase in such a way that optimizes for token efficiency?

Optimizing for Feature-Localized Context

A while back, I wrote about vertically sliced architectures. Today, we revisit the notion of a feature-driven project structure because it also happens to optimize for the way coding agents explore codebases.

(For the rest of the article, I'll assume that you've already read this.)

Basti Ortiz

May 15 '25

You're slicing your architecture wrong!

#beginners #architecture #webdev #devjournal

Comments 27

5 min read

Stepping into the shoes of a coding agent, the typical workflow involves implementing a single feature at a time (i.e., per context window). At least for now, it's strongly discouraged to do too many unrelated things within a single context window.

The ideal codebase must therefore be malleable enough such that features can be added incrementally (i.e., a new feature means mostly new code and only a few edits/deletions) and concurrently (i.e., multiple agents/humans can work on the code in isolation without much merge conflicts).

When a coding agent examines your prompt, it invokes tools that can semantically query (an index of) the codebase, search for key words, and read file contents—typically in that order, too! The result is an end-to-end codemap of the existing infrastructure that would be affected by the proposed new feature, bug fix, deprecation, etc. This is what we see in the PLAN.md.

Visually, the trace of tool calls resemble a search tree that narrows down from entire subsystems to individual files. Cool, right?

This exploration doesn't come for free, though! Each tool call dumps intermediate output tokens (e.g., MCP tools, search results, shell invocations, full file reads, etc.) into our already limited context window.

For instance, tools like Claude Code require reading the file before writing to it (for good reason!). Before you know it, you're already past the "40% Rule" with fewer tokens to spare for plan refinement—much less for implementation.

🗒️ Some LLMs (namely Claude 4+) exhibit "context awareness". These models adapt their behavior/effort based on the remaining amount of tokens in their context window. In practice, this means more shortcuts, more sloppy work, and more incomplete features without proper context management.

The usual workaround is to /compact, /summarize, or /handoff before implementing the PLAN.md; if the PLAN.md is so good, we may even get away with /clear entirely. Fancier methods utilize sub-agents for context management. Admittedly, these are often good enough thanks to recent advancements in the state of the art.

Nevertheless, in a perfect world, we shouldn't have to spend so many tokens in the planning stage alone. Codebase exploration and manipulation shouldn't be so token-hungry. To optimize the explorability of our codebases for humans and AI agents alike, we want...

Highly selective semantic queries that prune out several subsystems of the codebase right off the bat.
Highly selective keywords within subsystems that further prune out irrelevant context.
Highly cohesive and collocated modules for maximum recall within agentic ls invocations.
To read only the right files and only the absolutely bare minimum context required.

Effectively, we are maximizing the signal-to-noise ratio of the exploration stage. The easier it is for coding agents to navigate the codebase, the easier it is to plan and implement features for, and the easier it is for humans to review.

(Yes, you are still responsible for the code you generate and eventually merge into production!)

How Classical Architectures Pessimize Exploration

The opposite of what we want are the classical horizontally-sliced architectures of yester-decade. To reiterate some points from my previous article:

Horizontally sliced project structures violate the collocation principle by scattering snippets of features across separate directories of "services", "controllers", "models", etc. In practice, this means more ls tool calls by the coding agent and more directory jumping by the human.
Monolithic Service classes tend to bundle all CRUD operations in one big file even if many of them are unrelated to a particular feature exploration. Invoking the Read tool on such files thus dumps more code noise than signal into the context window.
Unless the index of the codebase knows a priori which subset of lines to Read, large "service" and "repository" files only pollute the context window with unrelated code—as if the haystack wasn't large enough already.

The situation is exasperated by unit tests and integration tests, where it's easy (and encouraged also for good reason!) to reach thousands of lines. A simple prompt to "write more unit tests" could (very likely!) mean reading the entire test file again.

Unless cleverly broken up into separate test files, monolithic modules imply even more monolithic test files. We're potentially looking at double the amount of reads. Again, that's just poor signal-to-noise ratio...

How Vertically Sliced Architectures Optimize for Selectivity

What we actually want is a malleable codebase with self-contained feature modules that cohesively implement all of its logic end-to-end. In doing so, files are collocated within a narrow slice of the project structure. Coding agents thus naturally traverse the repository in a few depth-first passes.

The serendipitous consequence is that codebase exploration becomes highly selective by construction and organization. There's no need to explore feature-a/ when the entire end-to-end logic of feature-b/ is already self-contained. File recall almost becomes trivial by virtue of collocation.

But, we don't have to stop there. Feature modules can still turn for the worse if they degrade to monolithic modules. The solution: modularize the logic (and its tests) even more. Taken to the extreme, we're looking at one function per file such that its associated test file only contains the describe suites relevant to that specific function only.

feature/
├── subsystem/
│   ├── index.ts
│   ├── index.test.ts
│   ├── schema.ts
│   ├── utils.ts
│   └── utils.test.ts
└── subfeature/
    ├── index.ts
    ├── dates.ts
    ├── dates.test.ts
    ├── strings.ts
    └── strings.test.ts

Of course I'm not advocating for this convention because it is comically harsh, but it's nevertheless illustrative of my overall point about optimizing for narrow end-to-end vertical slices in the name of token-efficient exploration (both for agents and humans alike).

Conclusion

A coding agent's behavior resembles a deepening and narrowing search tree. To accommodate coding agents as first-class citizens in our projects (alongside humans), we should structure our codebases accordingly.

The horizontally sliced codebases of yester-decade will struggle in the agentic era (compared to its vertically sliced counterpart) due to its monolithic conventions and scattered organization of end-to-end logic. Newer codebases should strive to be more feature-driven.

Narrow depth-first slices of the codebase encourage highly selective and cohesive exploration.
Self-contained modules encourage incremental features (rapid iteration!) and concurrent implementation (no merge conflicts!).
Modularized logic and collocated files improve recall by eliminating cross-cutting jumps between directories and subsystems.
Tightly scoped unit tests are more important than ever! Keep your LLMs honest with focused test suites.
Beware of monolithic Service-like classes and Repository-like classes! Avoid dumping too much "inter-feature" logic in the same file except for orchestration code.

And that's how I've been keeping my codebases in check in the agentic era.

Mastering Python's Iteration Protocol: Iterables, Iterators, and Generators

Basti Ortiz — Sun, 12 Oct 2025 21:44:46 +0000

Over the years, I've received innumerable queries from (mostly) undergraduate computer science students on the difference between iterables, iterators, and generators in programming languages like Python and JavaScript.

This article consolidates into one master reference all of the answers that I've given and scattered across various internal lecture notes, private Notion documents, Discord servers, and direct messages.

This edition has been adapted for Python idioms. The JavaScript edition, which covers the exact same concepts but with JavaScript's primitives instead, will be coming soon.

The Iterator Contract

Our story begins in the Iterator Contract: the very interface that underpins our entire discussion.

Iterables and `iter`

Mechanically and contractually, an Iterable is any object that implements the __iter__ dunder method (and can thus be passed as an argument to the builtin iter function). Semantically, it is any container- or collection-like object (e.g., lists, sets, trees, etc.) that can be "iterated" on.

The mechanics of "being iterated on" is quite simple. When we pass an object to the iter function, we expect that it returns an object called the iterator. The iterator is responsible for maintaining the current iteration state of the collection traversal.

Iterators and `next`

Mechanically and contractually, an Iterator is any object that implements the __next__ dunder method (and can thus be passed as an argument to the builtin next function). Semantically, it is an object that keeps track of the current iteration state. (Pedantically, an Iterator should also implement the Iterable interface, but this detail is sometimes omitted in practice.)

As you might expect, the next function returns the "next" item in the iteration (of all elements in an Iterable container). You can visualize the Iterator as a "stream" of objects that you can request from the Iterator by repeatedly invoking the next function. When there are no more items left in the Iterator, the underlying __next__ implementation must raise the StopIteration exception to signal that it has been exhausted.

# The `range` object is an `Iterable` container.
container = range(3)

# We can therefore obtain an `Iterator` over its elements.
iterator = iter(container)

# We can safely extract the first three items via `next`.
print(next(iterator)) # 0
print(next(iterator)) # 1
print(next(iterator)) # 2

# But the final invocation will raise an exception!
try:
    next(iterator) # StopIteration
except StopIteration:
    print('Done!')

Under the hood, this is exactly how the for loop works. The object being iterated on is first passed to the iter function to obtain an Iterator. Then, the for loop invokes next until it hits the StopIteration exception.

# This is fancy syntactic sugar for...
for i in range(3):
    print(i)

# ... a loop that invokes `next` over and over again
# until there are no more elements left.
container = range(3)
iterator = iter(container)
while True:
    try:
        print(next(iterator))
    except StopIteration:
        break

Aside: The Importance of Brand New Independent Instances

I want to emphasize why iter is typically expected to return a brand new iterator object. Naturally, when you create an iterator, you expect that the returned instance is its own self-contained iteration state that is independent from other invocations of iter.

# A `list` of `str` objects is an `Iterable` out of the box.
items = ['hello', 'world']

# These two invocations of `iter` create independent iterators
# that each maintain their own state.
first_iterator = iter(items)
other_iterator = iter(items)
assert first_iterator is not other_iterator

# Mutating the iteration state of one iterator should not leak
# into other iterators. They are their own instances!

print(next(first_iterator)) # 'hello'
print(next(other_iterator)) # 'hello'

print(next(first_iterator)) # 'world'
print(next(other_iterator)) # 'world'

There are exceptions to this rule, however, which we'll see in the worked examples of the following section.

Worked Examples

To get a feel around how the Iterator Contract is typically implemented, let's go through a few worked examples.

Infinite Counter

Let's implement an infinite counter. It takes in a start argument which determines where to start counting to infinity from.

from dataclasses import dataclass

@dataclass
class InfiniteCounter:
    ''' The starting point of the counter. '''
    start = 0

    # Implementing the `Iterable` contract
    def __iter__(self):
        # Observe that we're returning a newly constructed iterator every time.
        return _InfiniteCounterIterator(self.start)

@dataclass
class _InfiniteCounterIterator:
    '''
    Tracks where we are now in the iteration.
    This is our private `Iterator` class.
    '''
    current: int

    def __iter__(self):
        # We should clone ourselves here so that we don't give out
        # references to our iteration state. Otherwise, it would be
        # possible for multiple variables to "advance" the iterator
        # from different variables. We don't want that!
        #
        # However, it is totally legal to just return `self` here. In fact,
        # many iterators from the standard library simply `return self`
        # (likely to avoid the performance overhead of cloning). As such,
        # we will do the same. We must keep in mind the footguns, though!
        return self
        # return InfiniteCounterIterator(self.current)

    def __next__(self):
        value = self.current # take the first value
        self.current += 1    # advance the iterator
        return value

# This is an infinite loop because we never raise `StopIteration`!
container = InfiniteCounter()
for i in container:
    print(i) # 0, 1, 2, 3, ...

Singly Linked List

Now let's do the same drill for a basic linked list implementation.

from dataclasses import dataclass
from typing import Optional, Self

@dataclass
class Node[T]:
    next: Optional[Self]
    data: T

@dataclass
class LinkedList[T]:
    head: Optional[Node[T]]

    def __iter__(self):
        return _LinkedListIterator(self.head)

class _LinkedListIterator[T]:
    current: Optional[Node[T]]

    def __iter__(self):
        return self

    def __next__(self):
        if self.current is None:
            # No more data to yield!
            raise StopIteration

        data = self.current.data         # take the current value
        self.current = self.current.next # advance the iterator
        return data

Generators

Now I'm sure you're thinking that writing explicit Iterator classes are such a hassle—and you'd be right! In Pythonic code, we rarely interface with iterators at such a low level. Typically, we use generators and comprehension syntax to make our lives easier.

Syntactically, a Generator is a function that contains at least one yield keyword. Contractually, it returns an Iterator that streams the yield-ed items. Colloquially, it is a "pausable function".

# Generators are best understood by example.
def generate_hello_world():
    print('start')
    yield 'hello' # pause!
    print('middle')
    yield 'world' # pause!
    print('end')

# Generators return iterators!
iterator = generate_hello_world()

print(next(iterator))
# 'start'
# 'hello'

print(next(iterator))
# 'world'
# 'middle'

print(next(iterator))
# 'end'
# StopIteration!

There are also times when it is useful to exhaust an inner iterator first from within the generator. This is uncommon in practice, but it's handy to know it when you need it! For that, we have the yield from keyword.

def concat_iterators[T](
    first: Iterator[T],
    other: Iterator[T],
    bonus: T,
):
    # Exhaust this iterator first and forward the results.
    yield from first
    # Then we can exhaust the second iterator after.
    yield from other
    # We can even yield our own items at any point.
    yield bonus

def flatten_iterators[T](iterators: Iterator[Iterator[T]]):
    ''' A fancy way to flatten an iterator of iterators. '''
    for iterator in iterators:
        yield from iterator

The Comprehension Syntax

You may also be familiar with generators through a different syntax: list/set/dictionary comprehensions!

# Plain comprehensions are just fancy syntactic sugar over generators!
iterator = (i for i in range(10) if i % 2 == 0)
print(next(iterator)) # 0
print(next(iterator)) # 2
print(next(iterator)) # 4
print(next(iterator)) # 6
print(next(iterator)) # 8
print(next(iterator)) # StopIteration!

One common use case for generators is the ability to "aggregate" them into a result or some other collection.

# These are functionally equivalent!
items = [i for i in range(10) if i % 2 == 0]

# The `list` constructor also accepts a `Generator` argument.
# The yielded items will be streamed into the final `list`.
items = list(i for i in range(10) if i % 2 == 0)

# The same is true for sets and dictionaries!
items = { i for i in range(10) if i % 2 == 0 }
items = set(i for i in range(10) if i % 2 == 0)

Internally, you can imagine these "generator consumers" as for loops that process each element into an aggregation.

from collections.abc import Iterator

def collect_into_list[T](items: Iterator[T]):
    ''' This is effectively what the `list` constructor does. '''
    result = list[T]()
    for item in items:
        result.append(item)
    return result

def collect_into_set[T](items: Iterator[T]):
    ''' This is effectively what the `set` constructor does. '''
    result = set[T]()
    for item in items:
        result.add(item)
    return result

from collections.abc import Iterator
from math import nan

def sum_floats(numbers: Iterator[float]):
    ''' This is how the actual `sum` function works! '''
    total = 0.0
    for number in numbers:
        total += number
    return total

def avg_floats(numbers: Iterator[float]):
    ''' Now let's get fancy with arithmetic means! '''
    items = 0
    total = 0.0

    for number in numbers:
        items += 1
        total += number

    # Let's assume non-empty iterators for simplicity.
    assert items > 0

    # Alternatively, we may implement this as a running average.
    return total / items

from random import random

# Pro tip: you don't need a list comprehension here!
# You can use plain generators to avoid the unnecessary
# memory allocation for the temporary `list`.
total = sum(i for i in range(10) if i % 2 == 0)
float_total = sum_floats(random() for _ in range(10))
float_average = avg_floats(random() for _ in range(10))

Simplifying the Worked Examples

Now let's take the worked Iterator examples from the previous section and see how we can leverage generators to simplify their implementation.

from dataclasses import dataclass

@dataclass
class InfiniteCounter:
    ''' The starting point of the counter. '''
    start = 0

    def __iter__(self):
        # Now the infinite loop is more apparent...
        current = self.start
        while True:
            yield current
            current += 1

from dataclasses import dataclass
from typing import Optional, Self

@dataclass
class Node[T]:
    next: Optional[Self]
    data: T

    def __iter__(self):
        # Do you notice the parallels to
        # the explicit iterator version?
        current = self.head
        while current is not None:
            yield current.data
            current = current.next

@dataclass
class LinkedList[T]:
    head: Optional[Node[T]]

    def __iter__(self):
        # Now we can just invoke the inner generator
        # since we've moved the generator to the `Node`.
        if self.head is not None:
            yield from self.head

The Conveniences of `itertools`

Now that we've seen how we can build iterator primitives simply out of the next function and even the yield keyword, let's explore some of the builtin iterator utilities of the standard library: the itertools module.

# Infinite Iterators
import itertools as it

print(*it.count(10)) # 10 11 12 13 ...
print(*it.cycle('ABCD')) # A B C D A B C D ...
print(*it.repeat(10)) # 10 10 10 10 ...

# Iterator Combinators
import itertools as it

print(*it.accumulate(range(1, 6))) # 1 3 6 10 15
print(*it.batched('ABCDEFG', n=2)) # AB CD EF G
print(*it.chain('ABC', 'DEF')) # A B C D E F
print(*it.chain.from_iterable(['ABC', 'DEF'])) # A B C D E F
print(*it.pairwise('ABCDEFG')) # AB BC CD DE EF FG
print(*it.zip_longest('ABCD', 'ab', fillvalue='-')) # Aa Bb C- D-

# Combinatoric Iterators
import itertools as it

print(*it.product('ABCD', repeat=2))
# AA AB AC AD BA BB BC BD CA CB CC CD DA DB DC DD

print(*it.permutations('ABCD', repeat=2))
# AB AC AD BA BC BD CA CB CD DA DB DC

print(*it.combinations('ABCD', repeat=2))
# AB AC AD BC BD CD

print(*it.combinations_with_replacement('ABCD', 2))
# AA AB AC AD BB BC BD CC CD DD

Recap: what did we learn?

We've discussed a lot, so let's recap on what we learned.

An Iterable is something you can create a Iterator from via the builtin iter function.
- You can then repeatedly invoke the builtin next function with an Iterator as its argument until the StopIteration exception is raised.
- Internally, a for loop is just syntactic sugar for advancing an Iterator.
Generator functions and the yield keyword are another syntactic sugar over explicit Iterator implementations.
- Generators stream data to the caller via the yield keyword.
- Generators use the yield from keyword to exhaust internal iterators first before proceeding.
- Generators are almost like "pausable functions", but not intended for that exact purpose.
The comprehension syntax is syntactic sugar over explicit simple Generator implementations.
The itertools module is your best friend.

There's a common thread here: it's always one syntactic sugar over the other. That's what makes iterables, iterators, and generators so confusing to beginners! To best understand fancy generators, we had to go back to first principles: the Iterator Contract. Everything hinges on that basic design pattern as the primitive for composable utilities.

Now, a lot of things in computer programming (and computer science in general!) are like that. We face abstractions upon abstractions upon abstractions every day. Although it's more convenient to live in higher levels of abstraction, we must never neglect understanding how things really work at the lowest levels.

The best engineers never shy away from digging deeper.

🔥 Simulating Course Schedules 600x Faster with Web Workers in CourseCast

Basti Ortiz — Thu, 21 Aug 2025 15:43:06 +0000

This is the story of how I made a Monte Carlo simulation of student schedule assignments 600x faster with web workers.

Here is our baseline: the original prototype struggled to handle ~100 concurrent users. Each simulation request to the compute server took a whole minute (~60 seconds) to complete, which incidentally exasperated the resource limits of the deployment.

In this article, we'll discuss the steps that I took to make the application virtually infinitely scalable (i.e., no server compute bottleneck) thanks to sub-second client-side execution. That's faster than a page load! 🔥

Simulating Course Match with CourseCast

CourseCast is a course schedule simulator by Derek Gibbs for the Course Match system of the Wharton School of the University of Pennsylvania. In the actual Course Match system, each student rates desired courses on a scale from 0 (least desired) to 100 (most desired). This score is known as the "course utility".

On simulation day, the Course Match algorithm determines the "clearing price" for all offered courses based on their supply and demand. Upon completion, Course Match will have been able to assign schedules to each student (in a single round!) such that the course utilities and obtained credits are maximized given the student's respective budget constraints.

💡 You can think of Course Match as an autonomous shopper that "buys" courses on behalf of the student. The purchasing power is only limited by the student's token budget, their maximum workload/credits, and their assigned utilities. The higher the token budget, the greater the student's capability to "afford" the clearing price for a course.

Since it's impossible to know ahead of time what the actual clearing prices will be, CourseCast instead forecasts the clearing prices based on the most recent historical data of actual clearing prices in previous Course Match runs. These predicted prices (and their statistical variances) are the "weights" of the model trained on the latest course and instructor trends.

To account for forecast uncertainty, the CourseCast model assumes that the predicted clearing price is a normally distributed random variable. As such, CourseCast runs 100 Monte Carlo simulations and counts the frequency of particular courses and schedule configurations being selected. These simulation results are presented to the user as a probability.

So where was the bottleneck?

The original CourseCast 2024 was prototyped and deployed as a Streamlit application written in Python. Students would input their course utilities and submit their simulation request to the Streamlit Community Cloud where:

The Python back end on shared virtual compute resources would parse course data and load model weights from a hosted Excel spreadsheet.
The service would recompute all of the scheduling conflicts between courses (~200 in total). Example: classes with overlapping schedules, classes with overlapping sections, and other logistical constraints.
Run 100 Monte Carlo simulations sequentially. Each of which is an instance of a linear programming solver.

As CourseCast went viral among thousands of UPenn students, the scalability cracks began to show. When too many concurrent users hammered the Streamlit application, students couldn't run their simulations.

To be fair, the application was on the Streamlit free tier, but it was definitely high time for a rewrite to something more production-grade.

So how did we scale CourseCast 2025?

Now that we know where the bottlenecks are, let's tackle them one by one.

Scrapping the Python Server

My first instinct was to ask: is Python necessary at all? The Monte Carlo simulation was essentially a glorified for loop over a linear programming solver. Nothing about the core simulation logic was specific to Python. In fact, the only Python-specific implementation detail was the usage of Excel spreadsheet parser libraries and linear programming solver libraries for Python. I figured...

If there was a way to package and compress the Excel spreadsheet in a web-friendly format, then there's nothing stopping us from loading the entire dataset in the browser!¹ Sure enough, the Parquet file format was specifically designed for efficient portability.
If there was an equivalent linear programming solver library in JavaScript, then there's nothing stopping us from running simulations in the browser! Sure enough, there was the yalps library (among many other options).

At this point, I was fully convinced that we could scrap the Python server and compute the simulation entirely in the browser. This approach effectively allows us to infinitely scale our simulation capacity as we would no longer be constrained by shared cloud compute limits.

That solves our scalability problem! ✅

Precomputing Static Course Conflicts

The next bottleneck was the course conflict generation logic. Recall that each simulation request recomputes the logistical constraints on course selections (e.g., disallowing classes with overlapping schedules). This is fairly non-trivial work as there are hundreds of classes to consider.

So, naturally, the solution is to precompute these conflicts ahead of time. The precompute script takes the raw course data and appends the "conflict groups" of each course. These "conflict groups" ultimately determine the statically known logistical constraints of the linear programming solver.

📝 In computer science parlance, you can think of these "conflict groups" as equivalence classes defined by the relation of overlapping course schedules. That is to say, for all pairs of courses within an equivalence class, their schedules must have a non-empty schedule intersection. Thus, a "conflict group" is just a label for a group of pairwise-intersecting courses.

All of the course metadata, seeded random values, and conflict groups are embedded in a single compressed courses.parquet file (~90 KiB) and served to the user via a CDN for efficient delivery and caching. There is also the option of caching the file in a Service Worker, but the edge CDN already works well enough.

That solves our repeated work problem! ✅

Offloading CPU-Bound Work to a Separate Thread

The next bottleneck is the sequential execution of Monte Carlo simulation runs. There's actually no reason for us to run them sequentially because each sampled price prediction is independent from the 99 other trials. The simulation can thus be parallelized at the trial level.

Since each simulation run is primarily a linear programming solver, we know that the work is CPU-bound, not I/O-bound. The async-await model will not work here because CPU-bound work blocks the event loop. We must offload the work to another thread to keep the UI responsive.

In the browser, we only have one way to spawn multiple threads: through the Web Worker API.

// The API is a little wonky in that it accepts a URL to a script.
// This will be the entry point of the web worker.
const worker = new Worker("...", { type: "module" });

// Modern bundlers support URL imports. Prefer this approach!
const worker = new Worker(
  // NOTE: the import path is relative!
  new URL("./worker.ts", import.meta.url),
  { type: "module" },
);

We can then wrap the worker message-passing logic in a Promise interface and leverage libraries like TanStack Query for clean pending states in the UI. The example below uses React for demonstration, but this pattern is framework-agnostic.

// hooks.ts
import { useQuery } from "@tanstack/react-query";

async function sendWork(request: WorkRequest) {
  // Alternatively: receive this as an argument.
  const worker = new Worker(..., { type: "module" });
  const controller = new AbortController();
  const { promise, resolve, reject } = Promise.withResolvers();

  // Set up event listeners that clean up after themselves
  worker.addEventListener("message", event => {
    resolve(event.data);
    controller.abort();
  }, { once: true, signal: controller.signal });
  worker.addEventListener("error", event => {
    reject(event.error);
    controller.abort();
  }, { once: true, signal: controller.signal });

  // Kick off the work once all listeners are hooked up
  worker.postMessage(request);

  try {
    // Parse the incoming data with Zod or Valibot for type safety!
    const data = await promise;
    return WorkResponse.parse(data);
  } finally {
    // Make sure we don't leave any dangling workers!
    worker.terminate();
  }
}

/** Useful for sending work on mount! */
export function useSendWorkQuery(request: WorkRequest) {
  return useQuery({
    queryKey: ["worker", request] as const,
    queryFn: async ({ queryKey: [, request] }) => await sendWork(request),
    // Ensure that data is always fresh until revalidated.
    staleTime: "static",
    // Ensure simulations rerun immediately upon invalidation.
    gcTime: 0,
  });
}

// worker.ts
self.addEventListener("message", function (event) {
  // Parse with Zod for runtime safety!
  const data = RequestSchema.parse(event.data);
  // Do heavy CPU-bound work here
  const result: ResponseSchema = doHeavyWork(data);
  // Pass the results back to the UI
  this.postMessage(result);
}, { once: true }); // assumes one-shot requests

That solves our responsive UI problem! ✅

Parallelizing with Worker Thread Pools

A more advanced implementation of this one-shot request-response worker architecture leverages thread pools to send work to already initialized workers (as opposed to re-initializing them for each work request).

We can use navigator.hardwareConcurrency to determine the optimal number of worker threads to spawn in the pool. Spawning more workers than the maximum hardware concurrency is pointless because the hardware would not have enough cores to service that parallelism anyway.

⚠️ In the previous section, the worker was initialized by the sendWork function. In a worker pool, this should instead be provided as an argument to the sendWork function because sendWork is no longer the "owner" of the thread resource and thus has no say in the worker lifetime. Worker termination must be the responsibility of the thread pool, not the sendWork function.

// hooks.ts
import { chunked, ranged, zip } from "itertools";
import { useQuery } from "@tanstack/react-query";

async function doWorkInThreadPool(requests: RequestSchema[]) {
  // Yes, this is the thread pool...
  const workers = Array.from(
    { length: navigator.hardwareConcurrency },
    (_, id) => new Worker(
      new URL("./worker.ts", import.meta.url),
      { type: "module", name: `worker-${id}` },
    ),
  );
  try {
    // Distribute the work in a round-robin fashion
    const responses: Promise<ResponseSchema>[] = [];
    for (const jobs of chunked(range(requests.length), workers.length))
      for (const [worker, job] of zip(workers, jobs))
        responses.push(sendWork(worker, job));
    return await Promise.all(responses);
  } finally {
    // Clean up the thread pool when we're done!
    for (const worker of workers)
      worker.terminate();
  }
}

/** Execute a batch of work on mount! */
export function useThreadPoolWorkQuery(requests: RequestSchema[]) {
  return useQuery({
    queryKey: ["pool", ...requests],
    queryFn: async ({ queryKey: [_, ...requests] }) => await doWorkInThreadPool(requests),
    staleTime: "static",
    gcTime: 0,
  });
}

📝 Request cancellation is not implemented here for the sake of brevity, but it is fairly trivial to forward the AbortSignal from TanStack Query into the thread pool. It's only a matter of terminating the workers upon receiving the abort event.

The thread pool optimization allowed us to run 100 simulations in parallel batches across all of the device's cores. Together with the precomputed conflict groups, the Monte Carlo simulation was effectively reduced from a minute to sub-second territory! 🔥

That solves our performance problems! ✅

Conclusion

After all of these optimizations, I upgraded CourseCast from a prototype that struggled with a hundred concurrent users (with ~60 seconds per simulation request) to an infinitely scalable simulator with sub-second execution speeds (faster than a page load!).

CourseCast now guides 1000+ UPenn students to make informed decisions and (blazingly!) fast experiments about their course schedules. And we're just getting started! 🚀

Throughout this work, I had a few key takeaways:

Always leave the door open for the possibility of offloading compute to the browser. Modern Web APIs are highly capable with great browser support nowadays. Keep exploring ways to save ourselves from the infrastructure burden of bespoke Python services.
Always find opportunities to precompute static data. May it be through a precompute script like in CourseCast or a materialized view in the database, strive to do the least amount of repeated work.
Keep a sharp eye out for parallelizable work. There are many opportunities in data science and general scientific computing where data processing need not be sequential (e.g., dot products, seeded simulation runs, independent events, etc.).
Be extra mindful of the distinction between CPU-bound work and I/O-bound work when interfacing with lengthy operations in the user interface.

On a more human perspective, it's always a pleasure to have the code that I write be in service of others—especially students! As software engineers, it's easy to forget about the human users at the other end of the screen. To be reminded of the positive impact of our code on others never fails to make our work all the more worth it.

"Have been hearing tons of amazing feedback. Anecdotally, most people who ran simulations through CourseCast ended up without any surprises. Congrats on shipping a great product!"

Thanks to Derek Gibbs and the Casper Studios team for trusting me to take the lead on this project! And thanks to the Wharton School administration for their support and collaboration with us in making CourseCast as helpful as it can be for the students.

I must disclaim that our dataset is public and fairly small. For larger models with possibly proprietary weights, downloading the data in the browser is not an option. ↩

You're slicing your architecture wrong!

Basti Ortiz — Thu, 15 May 2025 13:29:45 +0000

For the longest time, the "separation of concerns" has been the ultimate guiding principle of software engineering. We thus structure our codebases accordingly:

Grouping related files by responsibility;
Partitioning logic by technical layers;
And sometimes even isolating by programming language.¹

Popular architectural patterns such as the Model-View-Controller (MVC) have applied and codified this principle to the point of dogma. Universities, bootcamps, and courses everywhere teach and perpetuate the notion that the MVC architecture is the be-all and end-all of architectural patterns.

To be fair, the MVC architecture is indeed often the correct mental model for fathoming any CRUD-heavy application (i.e., virtually 99.9% of web applications²) because it formalizes the flow of data from the source (i.e., the "model") to the interface (i.e., the "view") as well as the mutation and actuation on said data (i.e., the "controller"). It is quite literally the essence of CRUD.

But, is MVC also the correct framework for structuring codebases?

Does MVC supposedly³ being the correct mental model necessarily mean we should structure our directories as such?

In this article, we'll explore a better way to structure a codebase using a vertically sliced architecture instead of the classic models/, views/, and controllers/ layout.

Horizontally Sliced Architectures

The MVC architecture is an example of a horizontally sliced architecture. In a horizontally sliced architecture, the separation of concerns is sliced according to technical layers.

Note that the layers needn't be exclusively "models", "views", and "controllers". In a full-stack web application, you might find yourself slicing by "components", "endpoints", and "databases" instead.

models/
├── feature-a.ts
├── feature-b.ts
└── feature-c.ts
controllers/
├── feature-a.ts
├── feature-b.ts
└── feature-c.ts
views/
├── feature-a.tsx
├── feature-b.tsx
└── feature-c.tsx

So, what's wrong with this project structure?

To add a new feature, you must jump between multiple directories—namely models/feature/*, controllers/feature/*, and views/feature/*. Compounded over time, that's a lot of context-switching, mental overhead, and navigational ceremony!
It's often not immediately apparent which modules are used by a particular feature. As everything is horizontally sliced, each module can theoretically import any module from the layer below. This makes it difficult to track and assess the impact of code changes.
Consequently, modules across layers within the scope of a single feature tend to exhibit high coupling and low-to-medium cohesion.
"Uh... which files go where again?" – Probably you for the past 10 minutes, thinking about where to put new files for a feature.

Vertically Sliced Architectures

Now let's turn MVC on its side—literally! In a vertically sliced architecture, the separation of concerns is sliced according to features. The core idea being: each feature module must encapsulate only its own end-to-end logic and nothing else.

In practice, here is what a feature-driven project structure could look like:

features/
├── feature-a/
│   ├── model.ts
│   ├── controller.ts
│   └── view.tsx
├── feature-b/
│   ├── model.ts
│   ├── controller.ts
│   └── view.tsx
└── feature-c/
    ├── model.ts
    ├── controller.ts
    └── view.tsx

Shared logic across multiple features (e.g., database models, common utilities, etc.) may of course be refactored into shared modules elsewhere. What's important is that the feature-specific logic is self-contained and end-to-end.

Interestingly, though, the MVC patterns have not totally disappeared even in a vertically sliced architecture—as evidenced by the internal model.ts, controller.ts, and view.tsx files within a particular feature module. The slicing is different, yet the MVC-style separation of concerns remains in spirit.

So, what makes this better?

All the code related to a particular feature can be found within a single directory. No more back-and-forth between distant directories!⁴
The collocation of end-to-end logic lessens the cognitive load when developing features or debugging behaviors.⁵
By construction, a feature-driven architecture naturally leads to highly independent feature modules that exhibit low coupling (between vertical slices) and high cohesion (within vertical slices).

Example: React + Next.js

Nowadays, most full-stack web frameworks provide routing as a first-class feature. In Next.js, the src/app/ directory contains the entry points for each route. Specifically, the page.tsx file exports the component that should be rendered onto the page for that particular route.

Now let's imagine the page.tsx file as an orchestrator that only imports feature modules from src/features/. A natural conclusion is that a vertically sliced project structure entails partitioning the application logic as self-contained "feature components" that can be imported by any route—or any entry point in general.

src/
├── app/
│   ├── dashboard/
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── page.tsx
├── features/
│   ├── create-order/
│   │   ├── index.tsx
│   │   ├── context.ts
│   │   ├── hooks.ts
│   │   └── actions.ts
│   └── login-form/
│       ├── index.tsx
│       ├── context.ts
│       ├── hooks.ts
│       └── actions.ts
├── database/
│   ├── index.ts
│   └── schema.ts
└── components/
    ├── card.tsx
    ├── button.tsx
    └── input.tsx

Indeed, feature modules like create-order and login-form may contain feature-specific components, contexts, hooks, and server actions.

A feature-specific component may, for example, import from the shared src/components/ directory for common cards, buttons, and inputs.
Meanwhile, a feature-specific server action may invoke database queries from the shared src/database/ directory.

The key is to know when to extract shared logic (e.g., src/database/ and src/components/) and when to keep bespoke feature-specific logic isolated from the rest of the application.

Conclusion

At its core, the call to action is simple: simply turn MVC on its side.

Vertically sliced architectures set us up to write highly independent components that exhibit low coupling (between vertical slices) and high cohesion (within vertical slices). The result is a project structure that is considerably easier to read, understand, maintain, and extend.

Beware the Global Const

Basti Ortiz — Sat, 19 Apr 2025 08:33:23 +0000

It is common wisdom in the programming world to discourage the use of global variables.¹

It is bug-prone due to shared mutability across modules.
It introduces implicit dependencies within interfaces that are not syntactically communicated.
It may alter the behavior of dependents across invocations—even when provided with the same arguments.

I've recently come across a bug that humbled and reminded me about these pitfalls. Let me tell you a cautionary tale about global configuration objects.

DISCLAIMER: The following story is based on an actual bug in one of the projects that I work on, but several details have been altered and simplified.

A race condition?

The bug was initially simple. A user reported that generating a profile page in the app with ✨AI✨ in quick succession resulted in some components in the page persisting the old values from the previous ✨AI✨ generation.

"Simple," I naively thought to myself, "It's a classic case of a race condition." I hypothesized that the previous generation completed after the current one, which resulted in the old values overwriting the new ones in the database. The only problem was: I couldn't find the race condition.

Each ✨AI✨ enrichment is persisted as a single row in the database. Even if a race condition were to happen, the generated profile page should swap out the contents on a per-generation basis (i.e., one row as a whole). This was clearly not the case as the generated page interleaved new and old contents.

Sure enough, the database was intact. Each ✨AI✨ enrichment was indeed isolated from each other. No interleaving fields. No missing properties. No bad data. Nothing suspicious at all...

It's a front-end bug, then?

"Okay, surely the bug is in the front end," I thought to myself. I looked into the root component that renders the profile page starting with the props.

// A vastly simplified recreation of the page.

interface Props {
    // From the database...
    config: ProfileDetails;
}

export function Profile({ config }: Props) {
    return (
        <main>
            <HeroBanner src={config.bannerUrl} />
            <h1>{config.name}</h1>
            <p>{config.description}</p>
        </main>
    );
}

Nothing seemed off as the page component was literally just rendering what was given to it. "The bug must be in the data loading," I deduced. After some console.log debugging, I confirmed that the rows from the database were still intact. At this point, I was fairly confident that the persisted data was not at fault.

Despite my best efforts, I could not reproduce the bug. The data loaded from an enrichment row exactly matched the details rendered in the page. I mean... that's why race conditions are so difficult to debug, huh? At this point, I could only rely on my detective skills.

The dangers of default configurations

A couple hours passed when I finally raised my eyebrow at the call site of the Profile component.

// @/profile
export const DEFAULT_PROFILE_DETAILS = {
    bannerUrl: '...',
    name: '...',
    description: '...',
    // ...
};

import merge from 'lodash.merge';

import { DEFAULT_PROFILE_DETAILS } from '@/profile';
import { getProfileDetails } from '@/db';
import { getSessionAuth } from '@/auth';

export default async function Page() {
    const auth = await getSessionAuth();
    const profileDetails = await getProfileDetails(auth);
    const config = merge(DEFAULT_PROFILE_DETAILS, profileDetails);
    return <Profile config={config} />;
}

Wait a minute. Zoom in... Enhance!

const config = merge(DEFAULT_PROFILE_DETAILS, profileDetails); // 💥

And there it was: the single line of code that cost me several hours of my life.

Let me fill you in with the details. The merge utility here is Lodash's _.merge. As its name suggests, merge recursively merges one object with another. The key word is "recursive"; we can't use the spread syntax because that will only do a shallow merge.

Now, we want to merge the database-enriched profileDetails into the DEFAULT_PROFILE_DETAILS. This is because the ✨AI✨ prompt may possibly fail for some fields, so we need fallback values when that happens. Here is where the issue arises:

From the Lodash documentation: "this method mutates the object."

Because of this, it was totally possible (and documented!) that profile-specific details could leak into the DEFAULT_PROFILE_DETAILS—thereby causing subsequent requests to read leaked values. 😱 Suddenly, this innocent bug escalated into a data privacy issue!

Aside on serverless environments

This still begs the question: why hasn't the bug come up regularly enough for anyone to notice for a long time?

One important thing to note is that the app is deployed in a serverless environment. That means function invocations are typically ephemeral. JavaScript objects that are created within a request only exist within the lifetime of that request. By design, subsequent requests spin up new instances (a.k.a. isolates) of the environment.

On paper, the DEFAULT_PROFILE_DETAILS should be reconstructed for each request, which sidesteps the entire issue. However, cloud hosting providers can do clever performance optimizations like preserving the isolate across multiple requests to eliminate cold boot times.²

This is why the bug only manifests itself in "quick succession". There's a small non-deterministic window of opportunity where rendering a profile leaks details from a previous request.

Some mitigations and workarounds

The knee-jerk reaction is to axe the _.merge utility. But to be fair, there are several mitigations.

// Merging into a newly constructed object...
const config = merge({}, DEFAULT_PROFILE_DETAILS, profileDetails);

// Merging into a newly cloned object...
const config = merge(structuredClone(DEFAULT_PROFILE_DETAILS), profileDetails);

// Refactoring to use factory functions...
const createDefaultProfileDetails = () => ({ ... });
const config = merge(createDefaultProfileDetails(), profileDetails);

ASIDE: using Object.freeze doesn't really solve the issue because it prevents the mutation of the object during the merge process (which is a behavioral regression!). Also, TypeScript would not save us from the bug anyway even if it were annotated as Readonly due to the way _.merge is typed.

The common thread in all of these mitigations is avoiding mutation in global configuration objects. In the end, I committed to replacing all instances of non-primitive global const exports throughout the codebase into factory functions. In fact, banning non-primitive exports altogether was a safe bet.

Lesson learned: avoid non-primitive (e.g., objects, classes, maps, sets, regular expressions, functions, etc.) global exports if you can.

Not to be confused with "global constants", by the way. ↩
This is a good thing, by the way! ↩

The Curse of Verbosity and Indirection

Basti Ortiz — Sun, 23 Mar 2025 17:23:24 +0000

I've dealt with a wide spectrum of programming languages over the years. Some languages are object-oriented (e.g., Java, PHP, C++, and Dart); some are procedural (e.g., C and Zig); some are functional (e.g., Haskell, Coq); some are declarative (e.g., HTML and CSS); some are a mixed bag of everything (e.g., JavaScript, Python, Rust); and some are straight-up machine code (e.g., x86, ARM, MIPS, and RISC-V).

One common theme that I've observed is that object-oriented programming (OOP) patterns tend to yield the most verbose and indirect abstractions versus their non-OOP counterparts. In this article, we'll investigate why this is the case and how it arises out of necessity.

Free functions as a first-class citizen

package com.example.hello;
public class Main {
    public static void main(String[] _args) {
        System.out.println("Hello world!");
    }
}

fn main() {
    println!("Hello world!");
}

Let's compare two "hello world" programs: one from Java and another from Rust. It wouldn't be controversial to assert that the Rust version is clearly more concise than the Java version. To be fair, there is a lot more magic abstracted away: the command-line arguments being the most notable omission.

Putting that aside, this example illustrates the key limitation of "pure" OOP that makes it so verbose: classes are the only first-class citizens at the top level. Functions, on the other hand, are second-class citizens that must belong to either a class (as a static method) or an object (as an instance method).

When classes are imposed as the top-level entity, class declaration boilerplate becomes a necessary syntactic and semantic overhead. Instead of defining the entry point as a free function (as one typically would at the assembly level), a strictly OOP language introduces a class indirection right from the start.

The Zig language—at least as of writing—brilliantly compromises on that mental model by treating files as implicit structs. Top-level items in a file would be as if everything had been wrapped by an invisible struct { ... } declaration.

// example.zig
// struct {

// Not exported...
const std = @import("std");

// Exported as a static method!
pub fn hello() void {
    std.debug.print("world");
}

// }

// main.zig
// struct {

const example = @import("./example.zig");

pub fn main() void {
    // Static method!
    example.hello(); // world
}

// }

Interestingly, this is somewhat equivalent to the Java module system. The only difference is that the class boilerplate is implied, which makes things a little bit more bearable (as far as "hello world" examples go).

💡 A cute consequence of the Zig module system is that a file can also define struct instance fields at the top level!

Closures as a first-class citizen

Let's talk about "design patterns". In the software engineering world, design patterns—although generic by name—are most colloquially associated with OOP languages. Design patterns impose common terminology and implementation details in an effort to wrangle and make sense of a sea of OOP abstractions.

How did we get here? How did we end up with an entire vocabulary of jargon¹ just to fathom the levels of indirection? And most importantly, are these necessary and relevant today?

Let's first put into context that a lot of these design patterns were popularized and mainstreamed by a computer science zeitgeist constrained by the hardware and compiler capabilities of its time.

The class as a language feature was a necessarily limited compiler abstraction. Anything more complex than the core offering of fields, methods, and inheritance was an incredible feat of static analysis.² The class being a simple primitive enabled more arbitrarily complex software, but at the same time also necessitated more abstractions.

One such nicety of modern hardware and compiler theory that we now take for granted are closures (a.k.a. lambda functions). A closure is any callable (i.e., function-like) object with pre-bound arguments (i.e., doesn't need to be explicitly passed in).

const outsideVariable = 100;
const closure = (a: number) => {
    // `outsideVariable` is "captured" by the closure.
    return a + outsideVariable;
};

// No need to pass `outsideVariable` as an argument
// because the `closure` had already "pre-bound" it.
console.log(closure(200)); // 300

Let's take a closer look at how all of this works. At its core, a closure simply needs to stash some "outside variables" beforehand and provide some way to invoke it later. Kinda like this...

class Closure {
    #outsideVariable: number;

    constructor(outsideVariable: number) {
        this.#outsideVariable = outsideVariable;
    }

    call(a: number) {
        return a + this.#outsideVariable;
    }
}

const outsideVariable = 100;
const closure = new Closure(outsideVariable);
console.log(closure.call(200));

Poof! 💥 And just like that, we have reinvented the Strategy Pattern.

The point is: a lot of the verbosity of OOP design patterns come from the fact that (at the time!) there hadn't been language-level primitives for expressing closures. With limited compiler capabilities, the best way to emulate pre-bound functions was via strategy classes.

💡 Fortunately, modern Java has had closures since 2014 when Java 8 first released! The C++ folks also got theirs a few years earlier with C++11.

This is actually a recurring theme among previously "pure" OOP languages: many class-based design patterns are obsoleted by the introduction of closures.

Strategy? Write a lambda function that adheres to the same contract.
Factory? Write a lambda function with zero arguments that internally captures the necessary context.
Observers? Write a lambda function.
Adapters? Write a mapper lambda function.
And so on... (I think you get the point!)

So to answer the question more directly: yes, the verbosity of OOP design patterns and the opacity of its abstractions were necessary at the time. Nowadays, not so much. The point is: a lot of the OOP noise and boilerplate can be replaced by the niceties of modern language constructs.

Import-once modules as a first-class citizen

Speaking of design patterns, let's talk about singletons. Here is a classic textbook example of an eagerly initialized singleton class in Java:

package com.example.singleton;

public class Singleton {
    // Some private state that the singleton relies on...
    private int state = 0;

    private static Singleton instance = new Singleton();

    // Private just to make sure that nobody invokes it
    private Singleton() { }

    // NOTE: A public field also works, but having an explicit
    // getter function ensures that callers cannot reassign the
    // internal instance in any way.
    public static Singleton getInstance() {
        return instance;
    }

    public int getState() {
        return state;
    }
}

Now that is a lot of syntactic ceremony just for a single instance. We can simplify this by a little bit using the final keyword.

package com.example.singleton;

public class Singleton {
    private int state = 0;

    // This is now a `public` but `final` field.
    // It's functionally equivalent to the example
    // above as we only care about ensuring that the
    // internal instance never gets reassigned.
    public static final Singleton INSTANCE = new Singleton();

    private Singleton() { }

    public int getState() {
        return state;
    }
}

But even then, it's still a bit too verbose. We can go further by removing the constructor and the instantiation entirely. Instead, let's just inline the instance fields as static fields!

package com.example.singleton;

public class Singleton {
    // No longer `final` as this can be modified internally.
    private static int state = 0;

    // Now `static` because an instance is no longer required.
    public static int getState() {
        return state;
    }
}

Now this is much better! Here, the one true "instance" of the class is no "instance" at all; it is static. There's no need to jump through hoops with constructors, getters, and setters. Classic OOP patterns are so engrossed in classes that we sometimes forget that we don't have to over-complicate things.

⚠️ Of course, this contrived example doesn't apply if an actual object instance was required by some external library or API. In that case, we can either (1) write a trivial wrapper or (2) revert to the instance-based pattern.

This can be made even simpler if we step out of the "pure" OOP world, where classes are the only first-class top-level language items. If we allow variables and free functions into the top level (i.e., without requiring a class container), we get at the heart of what we're trying to express.

// Not exported to keep it private.
let state = 0;
export function getState() {
    return state;
}

💡 This example works in JavaScript because the ECMAScript module system requires that imported modules are loaded and evaluated only once.

Unions as a first-class citizen

Another example of a modern language construct is the union or enum.³ The lack of first-class unions (e.g., TypeScript unions and Rust enums) force OOP design patterns to resort to inheritance-based polymorphism (e.g., abstract class) for expressing disjoint use cases. This often leads to infamously opaque indirections across scattered subclasses.

// A base class for all possible "input types".
abstract class InputType { }

class TextInputType extends InputType {
    public String data;
    public TextInputType(final String input) {
        data = input;
    }
}

class IntegerInputType extends InputType {
    public int data;
    public IntegerInputType(final int input) {
        data = input;
    }
}

class BooleanInputType extends InputType {
    public boolean data;
    public BooleanInputType(final boolean input) {
        data = input;
    }
}

// In a language that supports first-class unions
// (such as TypeScript), we have a much simpler way
// to express the same idea.
type InputType = string | number | boolean;

// Even relatively low-level languages like Rust get this right!
enum InputType {
    Text(String),
    Integer(i32),
    Boolean(bool),
}

The point is: here we see yet another example of "pure" class-first OOP getting in the way of the core idea that's being expressed by the abstraction. The mandatory class boilerplate is frankly just overhead—necessarily self-imposed by the purity of class-first language design.

Conclusion

Many "pure" OOP patterns of yesteryear have poor signal-to-noise ratios. That is to say: there is more syntax and conceptual noise than there is engineering signal and clarity.

The notoriously verbose and opaque formulation boils down to its insistence on the class being the only top-level language item. This is not for no reason, though! Limited hardware and compiler capabilities during the heyday of the OOP trend necessitated the class being the building block of everything.

To manage all of this accidental complexity, OOP design patterns were codified—many of which are obsoleted by introducing not-so-pure OOP language features such as closures. Nevertheless, the (necessary!) codification of these patterns only justified what would otherwise be undesirable qualities in code.

Of course, this is not to say that OOP has no place in modern software engineering. There are certainly some abstractions where OOP is an appropriate tool in the box.⁴ At the very least, what I am saying is that the "pure" OOP of yesteryear is obsoleted by the modern OOP-functional hybrids of today.

In fact, I've always been a fan of the Java community's recent efforts in embracing functional programming patterns. Stream helpers, lambda functions, free functions, pattern matching, and monadic optional types are stellar examples of an evolving OOP language that recognizes cleaner ways of doing things.

Let's strive to write simpler code devoid of verbose abstractions and opaque indirections.⁵

Strategies, factories, builders, adapters, singletons, decorators, facades, etc. ↩
In the case of C++, it was also an incredible feat of bike-shedding over syntax and capture semantics! ↩
In the functional programming world, a stricter subset of unions is known as a "sum type", which are basically "tagged unions". ↩
Just to cite one common example in my experience, classes are an appropriate abstraction for database drivers, which are often stateful wrappers over live database connections. ↩
To give some personal context and motivation behind this article, I had recently worked on a Flutter codebase that subscribed to the so-called "Clean Code Architecture". It was not, in fact, clean code at all; it was riddled with superfluous OOP abstractions and mishandled async state. Files upon files of abstractions made the codebase difficult to navigate and extend—much to the irony of the SOLID principles that they swear by. This article summarized the general guidelines on the several opportunities for simplification that I encountered along the way. ↩

I was wrong about array methods and generators...

Basti Ortiz — Mon, 09 Sep 2024 01:17:31 +0000

For the longest time, I've always thought that JavaScript generators perform better than chained array methods in terms of execution time.

Surely, I thought that the superior memory efficiency of generators (due to lazy computation) implied better overall execution time as well.
Surely, in terms of time complexity, the single-pass $O (n)$ nature of generators were superior over the $O (kn)$ of $k$ chained array methods.

All of the heuristics that I had been taught by computer science point to generators being the undisputed champion. After many years of personal presumption ~~and dogma~~, it's finally time to put that to the test—with statistical rigor of course! So strap on your seatbelts as we finally answer the question:

Are generators actually faster than chained array methods?

The Setup

When we chain array methods, we typically perform a filter first then the map. The main idea is that it is more efficient to filter out the bad data first so that we don't have to map as many values later on. This will be our primary experiment: a basic filter + map operation.

Let's start with generating 32 KiB of random data.

// Generate 32 KiB of "cyptographically strong random values".
const bytes = crypto.getRandomValues(new Uint8Array(1 << 15));

// Then save the buffer into a file.
// Deno is just an implementation detail.
Deno.writeFileSync('random.bin', bytes);

Below is a histogram of the generated bytes. Indeed, we see a fairly uniform distribution of byte values in the random.bin file. For the sake of reproducibility and independence, we will now use this binary dump for all experiments.

The goal is to simply prune out all of the bytes greater than 127 (roughly half of random.bin) and then normalize the data so that the remaining bytes are between 0.0 and 1.0 (inclusive). Let's now discuss the four cases that we will be testing.

Case 1: `raw-for-loop`

By presumption, we consider the raw for loop construction as the baseline. Here, we iterate over all values in nums and push the mapped value into the output array.

function rawForLoop(nums: number[]) {
    const output = [] as number[];
    for (let i = 0; i < nums.length; ++i) {
        const num = nums[i];
        if (num <= 127)
            output.push(num / 127);
    }
    return output;
}

Case 2: `for-of-loop`

A slight variation of the raw-for-loop case is the for-of-loop case, which instead uses the for...of loop to iterate over nums. Everything else remains the same.

function forOfLoop(nums: number[]) {
    const output = [] as number[];
    for (const num of nums)
        if (num <= 127)
            output.push(num / 127);
    return output;
}

Case 3: `array-method`

Now we enter the territory of functional programming. Here, we implement the same logic as a two-pass filter + map chain.

function arrayMethod(nums: number[]) {
    return nums.filter(num => num <= 127).map(num => num / 127);
}

Case 4: `generator`

Finally, we implement the equivalent logic with generators.

function* _generatorImpl(nums: number[]) {
    for (const num of nums)
        if (num <= 127)
            yield num / 127;
}

function generator(nums: number[]) {
    return Array.from(_generatorImpl(nums));
}

The Experiment

Before we run the experiments, let's get the hardware specifications out of the way. Note that future work should reproduce this experiment on native Linux systems.

OS: Windows 22H2 (Build 19045.4842)
CPU: Intel® Core™ i7-10750H CPU @ 2.60GHz (12 CPUs)
RAM: 8192 MB

Now we implement a CLI for running each experiment case. Here is a high-level overview of the harness logic:

Select one of the four implementations: either raw-for-loop, for-of-loop, array-method, or generator.
Reads the 32-KiB random.bin file for the cached random bytes.
Perform 2048 warm-up iterations to allow the just-in-time compiler to optimize the code.
Finally, run the actual experiment with high-resolution sub-millisecond timing for 16384 iterations.
When the standard output is piped into a file, the result is 16384 lines of timing data.

I'll spare you the gory details of the harness implementation. For those who are interested in the argument parser, the file loader, the implementation selector, and the experiment runner, you may visit the GitHub repository. Please do leave a star while you're there!

BastiDood / js-generators-vs-array-methods

The repository for all the scripts, notebooks, results, and analyses related to my experiments on JavaScript generators and chained array methods.

JavaScript Generators vs. Array Methods

The repository for all the scripts, notebooks, results, and analyses related to my experiments on JavaScript generators and chained array methods. See the full article "I was wrong about array methods and generators..." for more details on the methodology, results, interpretations, and conclusions.

Generating Random Bytes

The first step is to generate 32 KiB of random data. There are many ways to do this, but I opted to generate them via the Crypto#getRandomValues function in JavaScript. A Deno script is already available at random/random.js.

# This will overwrite the already existing `random.bin` file!
deno run random/random.js

Running the Experiments

# Node.js
function run () { node --experimental-default-type=module benchmark/bench.node.js $1 > notebook/node/$1.csv; }
run raw-for-loop
run for-of-loop
run array-method
run generator

# Deno
function run () { deno --quiet --allow-read --allow-hrtime benchmark/bench.deno.js -- $1 > notebook/deno/$1.csv; }
run raw-for-loop

…

View on GitHub

Next, on which runtimes shall we run the experiments? I've selected the three most prominent JavaScript runtimes as of writing.

Node.js (v22.8.0) is written in C++ and powered by V8.
Deno (1.46.3) is written in Rust and powered by V8.
Bun (1.1.26) is written in Zig and powered by JavaScriptCore.

The Results

With 2048 warm-up iterations and 16384 actual samples, I believe it is fair to assume that sample sizes in the experiment are sufficiently large enough to omit the analyses of p-values. After all, with so many samples available, the observed data as a whole is hardly a fluke at that point.

Instead, the following results and discussion will focus on the pairwise effect size of the sample distributions. Given two sample distributions (e.g., raw-for-loop versus array-method), the effect size quantifies how "far apart" the mean of raw-for-loop is when compared to that of array-method.

For example, a large negative effect size implies that raw-for-loop has a significantly lower execution time (good!) than array-method. In practice, we are effectively quantifying the "impact" of the array-method on our baseline (i.e., raw-for-loop).

To keep things simple, we will use Cohen's $d$ as our metric for effect size. As a general rule of thumb, Cohen suggests (but warns against the dogmatization of) the following interpretations for $d$ :

We say that the effect size is small when $∣d∣<0.2\left| d \right| < 0.2$ .
But if $∣d∣<0.5\left| d \right| < 0.5$ , then we consider that to be a medium effect.
But if $∣d∣<0.8\left| d \right| < 0.8$ , then we have a large effect.
Otherwise, $∣d∣≥0.8\left| d \right| \geq 0.8$ is a huge effect.

Now that we're all on the same page, we can examine the results of the experiment.

Node.js Results

Right off the bat, the Node.js results demolish my long-held presumptions. Not only am I wrong, but it turns out that generators are the slowest of all the cases!

This histogram still sends shivers down my spine as I recall the countless number of times that I've written generators in my code under the presumption of optimization.

But how bad is it really? Let's take a look at the numbers.

Experiment	Mean	Mode	Standard Deviation
`raw-for-loop`	0.3309	0.2828	0.1975
`for-of-loop`	0.3368	0.2873	0.2031
`array-method`	0.4360	0.3557	0.2404
`generator`	1.1024	1.0010	0.2134

By eyeball statistics, we can see right away that the differences between raw-for-loop (baseline) and for-of-loop are insignificant. In fact, we can exactly quantify that with Cohen's $d$ . The table below summarizes how the raw-for-loop compares against the other experiment cases.

$d$	`raw-for-loop`
`for-of-loop`	-0.0296
`array-method`	-0.4778
`generator`	-3.7518

Let's take a look at some key observations here.

Comparing raw-for-loop and for-of-loop, we obtain $\approx -0.0296$ . That means raw-for-loop is only marginally faster than for-of-loop up to a very small effect—so small in fact that it is an injustice to say that there is one!
We get into the medium territory between raw-for-loop and array-method with $\approx -0.4778$ . That is to say, the raw-for-loop is faster than the for-of-loop up to a non-trivial medium effect. These results are consistent with that by various authors and blog posts over the years.
Perhaps the most shocking result is the extreme effect of generator on raw-for-loop having $\approx -3.7518$ ! Given these plots, it is fairly conclusive that generators significantly penalize execution time.

Going back to the original question, though: how badly do generators compare to chained array methods? It turns out that the effect size between array-method and generator is $\approx -2.9315$ ! Once again, we have entered extreme territory.

Deno Results

Hmm... that plot looks eerily familiar. As a matter of fact, we have already seen this plot in the previous section on Node.js!

Because Node.js and Deno both share V8 as their underlying JavaScript engine, the performance differences between the two are not statistically significant. From this point forward, we can thus refer to Node.js and Deno interchangeably as if they fall under the one umbrella of V8.

For the sake of completeness, here are the same tables shown in the Node.js section, but in the context of Deno instead.

Experiment	Mean	Mode	Standard Deviation
`raw-for-loop`	0.3267	0.2828	0.1857
`for-of-loop`	0.3440	0.2963	0.1987
`array-method`	0.4221	0.3462	0.3949
`generator`	1.0946	1.0180	0.1843

$d$	`raw-for-loop`
`for-of-loop`	-0.0898
`array-method`	-0.3092
`generator`	-4.1505

Note that the effect size between array-method and generator is $\approx -2.1824$ : yet another extreme effect on display.

Node.js and Deno: One and the Same

Let's go back to the observation earlier that Node.js and Deno exhibit the same performance characteristics. The following figure superimposes the Deno histogram over the Node.js histogram. The overlap is quite impressive to say the least.

Now let's quantify exactly how much they overlap by considering the effect sizes of corresponding experiment cases.

Experiment	$d$
`raw-for-loop`	0.0219
`for-of-loop`	-0.0356
`array-method`	0.0426
`generator`	0.0388

In all cases, there is little to no effect between Node.js and Deno. If we must draw a conclusion, though, we can see that Node.js is marginally slower than Deno except in the for-of-loop case. Nevertheless, this is already well within the realm of noise, so let's not look too deep into it.

Bun Results

As the JavaScriptCore engine enters the scene, the Bun histogram takes on a completely different shape. I can already hear the Zig fans rejoicing as their results practically blow Node.js and Deno out of the water.

A cursory inspection of the histograms already shows more stable performance characteristics in JavaScriptCore than in V8. The curves are closer together, but still exhibit the same patterns as in Node.js and Deno—albeit at a smaller magnitude. The table below summarizes the relevant statistics from the experiments.

Experiment	Mean	Mode	Standard Deviation
`raw-for-loop`	0.2786	0.2626	0.2749
`for-of-loop`	0.2789	0.2644	0.2718
`array-method`	0.3608	0.2707	0.3274
`generator`	0.4919	0.4712	0.2651

Rather than rehashing the discussion as in the Node.js and Deno sections, let's instead examine the Bun data based on its similarities and differences from the previous two runtimes.

Like Node.js and Deno, the performance degradation with respect to the raw-for-loop baseline is ordered as for-of-loop, array-method, and generator. This phenomenon where generator performs worst—much to my dismay and chagrin—is consistent with all engines.
Unlike that of Node.js and Deno, the Bun distributions are closer together—indicating more stable performance characteristics.
Bun (JavaScriptCore) optimizes the underlying state machines of the generator implementation better than Node.js and Deno (V8). By how much, you may ask? Between Node.js and Bun, the effect size is $\approx 2.5370$ . Meanwhile, between Deno and Bun, the effect size is $\approx 2.6401$ . That is to say, both Node.js and Deno perform extremely worse than Bun.

The next table summarizes the effect sizes of each experiment on the raw-for-loop baseline.

$d$	`raw-for-loop`
`for-of-loop`	-0.0012
`array-method`	-0.2722
`generator`	-0.7898

Like Node.js and Deno, the for-of-loop is practically equivalent in performance characteristics to the raw-for-loop baseline.
Like Node.js and Deno, a similarly small effect size has been observed between raw-for-loop and array-method. Indeed, the performance overhead is small but certainly non-zero.
Unlike Node.js and Deno, the overhead of the generator case only tiptoes between the medium and large effect sizes, whereas the former exhibited extreme effect sizes. This result attests to the previously discussed stability of Bun's performance characteristics.

Now how do array methods and generators compare in Bun? Between array-method and generator, the effect size is medium with $\approx -0.4399$ .

Interpretations and Conclusions

The most glaring conclusion thus far is that I was comically wrong about generators and chained array methods. In all experiments across all runtimes, the generator case consistently performed the worst. To add salt to the wound, I was not even wrong by a small margin, but by an extreme margin! Truly a hard lesson learned: measure, measure, measure.

The Importance of Spatial and Temporal Locality

I suspect that these results are due to the heavily optimized C++ implementations that underpin filter and map. Specifically, since arrays are contiguous data structures, low-level caches and memory prefetchers (in hardware and software) exploit the spatial and temporal locality of the array operations. In other words, a tight loop over 32768 integers becomes light work for hardware that can fetch and process 32 KiB in bulk without invalidating its internal caches.

Consider the alternative: generators. Generators are implicit state machines that tick forward after every yield. There is no notion of contiguity here because the values that will be processed are yet to be yielded by the generator. That alone fundamentally hampers the spatial and temporal locality of array operations. The state machine must necessarily tick one iteration at a time. This is opposed to the C++ code of filter and map that can zoom through the ready data in one fell swoop—albeit in two iterations.

In practice, this means that the $O (2 n)$ time complexity of filter + map does not tell the whole story. Although generators are single-pass $O (n)$ constructs, sacrificing spatial and temporal locality incurs an extreme overhead that more than makes up for the two-pass bulk operation of filter + map.

As we chain more array methods (which is rarely necessary), we anticipate array-method eventually surpassing generator in execution times.¹ Until then, we have shown that the overhead of generators due to (implicit state machines) proves to be too costly.

Some part of me is quite relieved that this is the case. I must admit that filter + map chains read more elegantly than generators (even with helpers from itertools). At least I can now rest assured that generator gymnastics need not apply.

V8 versus JavaScriptCore

An unexpected storyline that unraveled as I performed the experiments was the lopsided battle between V8 and JavaScriptCore. I have heard about Bun's supposedly superior performance versus Node.js and Deno, but I have only experienced it in the making of this article. The effect sizes are less impressive in the raw-for-loop, for-of-loop, and array-method cases. Where Bun really shined was with the generator case and the overall stability of its performance characteristics.

Frankly, I am quite impressed by Bun and especially JavaScriptCore. To beat the formidable V8 engine by extreme margins is no small feat. For that, I will continue to keep a close eye on Bun. I look forward to seeing how far we can push the boundaries of JavaScript.

So... when to use generators then?

Generators still have their place where lazy computation is a necessity due to memory constraints. One notable example is file streaming, where it's impractical to load an entire file or response into memory (as is typically the case in cloud environments).

More generally speaking, generators shine in environments that are bottlenecked by idle times due to I/O (e.g., file system, networks, user inputs, streams, etc.). Here, CPU performance is less relevant because the CPU would be idle waiting on I/O to respond anyway. The lazy computation keeps memory usage low while data streaming ensures that clients receive data as soon as possible.

However, there is another compelling reason to use generators: composability. Because generators are lazily executed, operations on the resulting data stream are easily composable as items are processed one at a time. The popular itertools package—which features a plethora of iteration utilities—is a testament to this fact.

In fact, the developer experience around iteration utilities is so great that there is an active Stage 3 ECMAScript proposal right now (as of writing) that aims to officially add lazy iterator helpers to the language. When this is more widely supported, expect a follow-up article to this one that investigates the would-be C++-backed helpers.

Future Work

As thorough as I have been in this research, there is still some more work to be done. Here are a few bullets that were previously mentioned in the article.

Reproduce these experiments on a native Linux machine.
Investigate whether a sufficiently long chain of array methods eventually surpass the execution time of the equivalent generator.
Compare the performance characteristics of the upcoming iterator helpers.

The repository for all the scripts, notebooks, results, and analyses is available below.

BastiDood / js-generators-vs-array-methods

The repository for all the scripts, notebooks, results, and analyses related to my experiments on JavaScript generators and chained array methods.

JavaScript Generators vs. Array Methods

Generating Random Bytes

# This will overwrite the already existing `random.bin` file!
deno run random/random.js

Running the Experiments

# Node.js
function run () { node --experimental-default-type=module benchmark/bench.node.js $1 > notebook/node/$1.csv; }
run raw-for-loop
run for-of-loop
run array-method
run generator

# Deno
function run () { deno --quiet --allow-read --allow-hrtime benchmark/bench.deno.js -- $1 > notebook/deno/$1.csv; }
run raw-for-loop

…

View on GitHub

While you're there, please don't forget to star the repository!

Star the Repository

However, this is yet to be shown experimentally as it is already beyond the scope of this article. ↩

A Compelling Case for the Comma Operator

Basti Ortiz — Fri, 06 Sep 2024 21:28:36 +0000

The comma operator is one of the lesser-known operators in C-like languages such as JavaScript and C++. Essentially, it delimits a sequence of expressions and only returns the result of the final one.

const a = 1;
const b = 2;
const c = 3;
const result = (a, b, c, 4, 5, 6, true);
console.log(result); // true

if (false, true) console.log('hello'); // hello

It's natural to ask then: when would it ever be useful to cram multiple expressions in a single line? Furthermore, even if it were useful, why would a comma-separated sequence of expressions (in a single line) be more readable and maintainable than a semicolon-separated sequence of statements (across several lines)? When should we prefer one over the other?

These are questions that I have struggled to answer over the years, but now I think I finally have an answer. In this article, I present a compelling case—perhaps the only one frankly speaking—for the comma operator.

A Motivating Example

Let's first talk about the conditional ternary operator. As seen below, if the condition is truthy, it evaluates value. Otherwise, it evaluates another. There is emphasis in the key word "evaluation" here because the branches only execute when their condition is met.

const result = condition ? value : another;

For most cases, it's neat and pretty. Where it falls apart, however, is when we need to do more complex logic in between the branches before returning the conditional value. At this point, we resort to this unfortunate perversion:

let result; // Uninitialized! Yikes!
if (condition) {
    // Do some complex stuff in between...
    doSomething();
    // ...
    result = value; // Actual Assignment
} else {
    // Do other complex stuff in between...
    doAnotherThing();
    // ...
    result = another; // Actual Assignment
}
// Hopefully we didn't forget to initialize `result`!

Now there are many issues with this formulation.

The result is uninitialized at first. This is not inherently evil, but an easy tried-and-tested way to avoid bugs due to undefined is to just always initialize variables.
The initialization of result is literally at the bottom of the branch—far detached from its declaration.
By the end of the conditional, we better hope that result is surely initialized. If not us, we better hope that our teammates equally enforce that. If not now, we better hope that future developers uphold that, too!

There is a way around this limitation if we insist on using conditional ternary expressions. We just have to refactor the code into functions. That's definitely easier said than done. This gimmick gets old real quick!

function computeWrappedValue() {
    // ...
    return value;
}

function computeWrappedAnother() {
    // ...
    return another;
}

// How cumbersome!
const result = condition ? computeWrappedValue() : computeWrappedAnother();

Expression-based programming languages (such as Rust) have a more elegant solution. By reclassifying the if statement as an if expression, each branch can be evaluated and thus return values that can later be stored in a variable.

// A conditional ternary operator thus looks like this. Each branch
// returns a value, which is captured by the `result` variable.
// We thus ensure that `result` is always initialized by construction.
let result = if condition { value } else { another };

// If we wanted to do something more complex, we use the same syntax.
let result = if condition {
    do_something();
    // In Rust, the last expression without a semicolon is the value
    // that will be "returned" by the overall `if` expression.
    result
} else {
    do_another_thing();
    another
};

Can we emulate this in C-like languages? You've likely long foreseen where I'm headed with this, but yes!

A Compelling Case

What we want is a way to arbitrarily execute statements before returning a value within the ternary branches. Well, lucky for us, this is exactly what the comma operator is for.

// Parenthesized for clarity.
const result = condition
    ? (doSomething(), value)       // evaluates to `value`
    : (doAnotherThing(), another); // evaluates to `another`

The neat thing about this formulation is the fact that the branch expressions are only evaluated when necessary. We effectively emulate the behavior of expression-based programming languages. Gone are the days of ad hoc wrapper functions!

But alas, we can only go so far with this technique. You can imagine that for some sufficiently large n, cramming n statements into a single line already begs to be refactored into its own function. Personally, I would already reconsider by the time n > 3. Anything higher than that is dubious construction in terms of readability.

// Maybe we should reconsider here?
const result = condition
    ? (x++, thing = hello(), doSomething(), value)
    : (++y, thing = world(), doAnotherThing(), another);

// Okay, stop. Definitely turn back now!
const result = condition
    ? (
        x++,
        thing = hello(),
        doSomething(),
        doMore(y),
        doEvenMore(thing),
        value,
    ) : (
        ++y,
        thing = world(),
        doAnotherThing(),
        doMore(y),
        doEvenMore(thing),
        another,
    );
// Unless, of course, you're fine with this. It kinda does
// look like a Rust `if` expression if you squint hard enough.

Conclusion

Wrapping up, we have seen a compelling case for the comma operator: complex conditional ternary operations. The comma operator shines when the branches are short and sweet, but falls out of fashion real quick after three inlined statements. At that point, one is likely better off refactoring the code.

So should you use comma operators? Honestly... yeah! Readable code is mindful of the next reader, so as long as the comma chains are never egregiously long, I would accept—and even encourage—this coding style. If we consider the alternatives (i.e., uninitialized variables and refactored micro-functions), the comma operator is not so bad after all.

In practice, I already sprinkle my own codebases with these funny-looking comma operators. Though in fairness, I rarely have a need for multi-statement ternary conditionals anyway. But when I do, I have a cool tool in my belt that concisely expresses my intent.

To that end, I rest my compelling case for the comma operator.

Bitmasks are not so esoteric and impractical after all...

Basti Ortiz — Sat, 20 Jul 2024 07:08:16 +0000

So an overly flashy title from one of my articles six years ago finally bit me in the back side... 😅

// Detect dark theme var iframe = document.getElementById('tweet-1814166076990558259-912'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1814166076990558259&theme=dark" }

Bitmasks: A very esoteric (and impractical) way of managing booleans

Basti Ortiz ・ Oct 28 '18

#computerscience #javascript

In my defense, this was written by my naive 2018 self. Six years and one computer science degree later, I have vastly changed my perspective on this. This is why we are going in the completely opposite direction. In this article, we will discuss why bitmasks are not so esoteric and impractical after all.

Parallelized Truth-Checking

Let's go back to the example used in the original article.

const config = {
    isOnline:          true,
    isFullscreen:      false,
    hasAudio:          true,
    hasPremiumAccount: false,
    canSendTelemetry:  true,
};

Now suppose that we are tasked to check if all of these flags are true. In a world without bitmasks, we may end up with the following solution:

function isAllTrue(flags: boolean[]) {
    for (const flag of flags)
        if (!flag) return false;
    return true;
    // ALTERNATE:
    // return flags.every(flag => flag);
}

isAllTrue(Object.values(config)); // false

This is great and all. Some may even consider its alternate one-line version the epitome of clean JavaScript code. After all, who could say no to the Array#every method?

But unfortunately, as we increase the number of flags in config, our O(n) solution eventually shows its cracks. Of course in practice, it is rare for a config object to scale up to a million flags. At that point, there are bigger architectural decisions that need to be reconsidered.

Nevertheless, for the sake of argument, we are left asking: is there a more efficient way to do this? Yes, as a matter of fact, there is an O(1) solution to this problem: bitmasks!

Bitmasks enable us to simultaneously query all of the bits in an integer in a single CPU instruction. Since we are interested in checking if all the bits are turned on, we simply have to apply a bitwise-AND on an all-ones bitmask (i.e., 0b1111...1111).

// ASSUME: We have a way to convert the
// `config` to its bitwise representation.
function isAllTrue(flags: number) {
    // Explicitly convert to an integer just in case.
    // https://tc39.es/ecma262/#sec-numberbitwiseop
    const bits = flags | 0;

    // Obtain a bitmask where all bits are ones.
    const BITMASK = ~0;

    // The bitwise-AND with the `BITMASK` verifies
    // whether the `bits` are all ones (i.e., all true).
    return (bits & BITMASK) === BITMASK;
}

With that optimization, we now have a constant-time checker that can simultaneously check 32 bits (a.k.a. 32 Boolean values) in a single CPU instruction. This is much better than our original linear-time solution, which went through each bit one at a time.

Now you may ask: what if we have more than 32 Boolean values? Fortunately, some languages (such as JavaScript and Python) support arbitrarily-sized integers, which effectively remove the 32-bit limit. That is to say, we can operate on any finite number of flag bits and bit masks. Specifically for JavaScript, we have the BigInt type.

For other lower-level languages that only have fixed-size integers (such as C, C++, Rust, and Zig), there is no magical way to extend this algorithm to more than the maximum number of bits that the language supports. Luckily for us, we can still at least "chunk" the input into 32-bit groups. In fact, this is how arbitrarily-sized integer operations are implemented under the hood.

Note that the algorithm would still be linear-time, but it is at least 32 times faster than iterating one bit at a time! This is not to even mention the removal of the for-loop overhead (e.g., branch instructions, jump instructions, etc.).

/**
 * @param {bigint} flags - The bit flags stored as one big integer.
 * @param {bigint} count - The actual number of bits in {@linkcode flags}.
 */
function isAllTrue_Chunked(flags: bigint, count: bigint) {
    const BITMASK = (1n << 32n) - 1n; // 32 ones
    while (count > 0) {
        // Only consider the first 32 bits for this chunk.
        const bits = flags & BITMASK;
        if (bits !== BITMASK) return false;

        // Advance the cursor.
        flags >>= 32n;
        count -= 32n;
    }
    return true;
}

Analogously, we can also apply this algorithm to the bitwise-OR operator, which now checks if at least one bit is turned on rather than checking if all bits are turned on. The point is: bitwise operations enable us to write highly parallelized Boolean queries.

Struct-Packing for Network Efficiency

Another neat use case for bitmasks is querying the bit flags in a tightly packed struct. This is especially relevant in computer networking, where data packets are typically serialized as a literal struct. For instance, one may represent the header of a Transmission Control Protocol (TCP) segment as a struct with the following fields:

#include <stdint.h>
struct tcp_header {
    uint16_t src_port;
    uint16_t dst_port;
    uint32_t seq_number;
    uint32_t ack_number;
    uint8_t data_offset: 4;
    uint8_t reserved: 4;
    uint8_t flags;
    uint16_t window_size;
    uint16_t checksum;
    uint16_t urgent_pointer;
    uint32_t options;
};

Of particular interest is the flags field, which is essentially an array of bits that indicate whether the packet is a SYN, ACK, FIN, or RST packet (among other bit flags). The specifics of the protocol is beyond the scope of this article, so we instead explore why a TCP header uses an 8-bit integer for bit flags rather than individual bool fields.

It is important to first consider that a bool in C is essentially an 8-bit integer that can only be either 0 or 1. Although a single bit is sufficient (and necessary!) to represent false and true, the C standard still requires that a bool is 8 bits wide (where 7 bits are left unused).

From the perspective of network efficiency, an array of bool is therefore terrible packet design! That is to say, an array of bool values requires 8 bits per flag. With the tcp_header.flags field containing 8 flags, we would require 64 bits just to represent them in a struct! These bandwidth inefficiencies add up at the unfathomable scale and volume of data transfers in the Internet.

The solution is struct-packing. Instead of wasting 7 bits per bool field, we should instead "pack" the eight bit flags as a single 8-bit integer. We then use bitmasking to query and extract each field of interest. And just like that, we saved ourselves from 56 unused bits.

const uint8_t CWR = 0x80; // 1000_0000
const uint8_t ECE = 0x40; // 0100_0000
const uint8_t URG = 0x20; // 0010_0000
const uint8_t ACK = 0x10; // 0001_0000
const uint8_t PSH = 0x08; // 0000_1000
const uint8_t RST = 0x04; // 0000_0100
const uint8_t SYN = 0x02; // 0000_0010
const uint8_t FIN = 0x01; // 0000_0001

// Is this a SYN packet?
tcp.flags & SYN == SYN;

// Is this an ACK packet?
tcp.flags & ACK == ACK;

// Is this a SYN-ACK packet?
const uint8_t SYN_ACK = SYN | ACK;
tcp.flags & SYN_ACK == SYN_ACK;

Caching with Bloom Filters

Following the theme of struct-packing, bitmasks once again show up in systems that require efficient caching strategies. Chief among the use cases are content delivery networks (CDNs) and database systems.

But first, let's go back to what a cache is for. When certain operations are too expensive to run frequently, a cache is responsible for intercepting inputs and checking whether a corresponding previously computed output may be returned instead.

Now let's consider a case study on web servers. Nowadays, many web servers dynamically render HTML on the fly depending on the current state of some internal database. Sometimes, this dynamic generation may be expensive. Perhaps the database query is a non-trivial aggregation over millions of rows. Perhaps an external API invocation takes a long time to process the request. Perhaps an upload is taking too long.

In any case, a cache layer may prove to yield significant performance gains on the system. But what exactly are we caching? A simple example for the sake of demonstration is a parameterized web page whose contents depend on a portion of the URL—say /user/:id. As much as possible, suppose that we would like to avoid frequently generating user profiles. Hence, the only sensible time to rerender is after the user modifies their profile. Everything is served from a CDN cache otherwise.

A naive in-memory cache in the web server could store the URLs (e.g., /user/100) of known cached pages in a set-like data structure. If a URL exists in the cache, then serve from the CDN. Otherwise, we generate the HTML page from scratch. Sadly, this design comes at the cost of higher memory usage. Imagine having to cache /user/1 all the way up to /user/1000000. Yikes!

A more memory-efficient way to cache this knowledge in-memory (without blowing up RAM) is through a Bloom filter. Instead of caching all of the known id values of cached pages, a Bloom filter caches only a subset of these id values.

We thus set up the Bloom filter in such a way that if the hash of a URL gets a cache hit, then we know that the corresponding user may have modified their profile (which should be rare in practice). Otherwise, we know for certain that no such modifications have taken place yet, so it is safe to serve from the CDN cache directly.

In theory, we may implement a Bloom filter as an array of Boolean values. The URLs must then be hashed as a valid index into that array. Alternatively, as it is the theme of this article, we may use bitmasks instead.

function bloomFilterHash(url: URL) {
    // Extract the :id from the URL.
    const index = url.pathname.lastIndexOf('/');
    if (index < 0) throw new Error(':id not found!');

    // This is a simple hash where we simply take the ID modulo 32.
    // This always gives us a valid index into a 32-bit Bloom filter.
    const id = BigInt(url.pathname.slice(index + 1));
    return { raw: id, bloom: id % 32n };
}

// Initially zeroed 32-bit Bloom filter.
let bloomFilter = 0n;

// GET handler for the /user/:id.
app.get('/user/:id', async req => {
    // Hash the URL as an index into the Bloom filter.
    const { raw, bloom } = bloomFilterHash(req.url);
    const bitmask = 1n << bloom;

    if (bloomFilter & bitmask !== bitmask) {
        // The bit is turned off. Therefore, no modifications
        // have been made before. We can use the cached profile.
        return new Response(null, { status: 302, ... });
    }

    // The bit is turned on, which means one of the (possibly many)
    // users that computed this hash has modified their profile.
    // Time to generate a brand new profile page. Ideally, we should
    // eventually clear the Bloom filter so that future requests
    // need not pay this overhead (even though it should be rare).
    const data = await fetchUserProfile(raw, ...);
    const html = await generateProfileHtml(data, ...);
    return new Response(html);
});

// POST handler for modifying user profiles.
app.post('/user/:id', async req => {
    // Hash the URL as an index into the Bloom filter.
    const { raw, bloom } = bloomFilterHash(req.url);
    const bitmask = 1n << bloom;

    // Mark the Bloom filter bit as "dirty" (i.e., modified).
    bloomFilter |= bitmask;

    await modifyUserProfile(raw, ...);
    return new Response(null, { status: 204, ... });
});

Conclusion

In the original article that started this all, I framed bitmasks as an "esoteric" and "impractical" way to "over-engineer" Boolean values that only "hardcore computer scientists" should care about. Much of that negative sentiment and gatekeeping has gone away nowadays as I've grown as a mentor, a software engineer, and a computer scientist myself. In its place is a greater appreciation for the attention to detail involved in such low-level optimizations.

"[Bitmasking] is impractical and unreadable most of the time. Constant documentation and awareness are required to make sure that the correct bits are being selected and manipulated."

Though if there's anything worth saving from the original article, I still stand by my concerns on readability and maintainability. Without clear documentation, bitmasks look like magic numbers out of thin air. The runic soup of bitwise operators doesn't make the situation better either given its seemingly arbitrary incantations of tildes and minuses.

Wherever possible (and perhaps until performance bottlenecks arise), it is wiser to keep bitmasks as a last-resort tool in our belt. The cognitive overhead necessary in deciphering bitwise logic is frankly unappealing in many cases.

"Frankly, I wouldn't recommend using [bitmasks] regularly, if at all. As clever as it is, it is just too esoteric for common use... Overall, there aren't many applications for this, especially in a high-level language like JavaScript."

Parallelized truth-checking, struct-packing, probabilistic caching, bit fields, permission bits, and pattern matching are just a few examples of the more "practical" side of bitmasks in the real world. Even in high-level languages such as JavaScript, bitmasks are in fact not just mere intellectual play among "hardcore computer scientists".

Much like design patterns, data structures, and algorithms, the humble bitmask serves as one of the many tricks that we have up our sleeves. As with most things in our practice, it's just a matter of using the right tool for the job while keeping code quality in check.

Just like last time... bitmask responsibly.

JavaScript First, Then TypeScript

Basti Ortiz — Sun, 15 Oct 2023 12:38:52 +0000

A recent trend has shaken up the JavaScript-TypeScript community: the anti-build-step movement. For over a decade now, a build step¹ has been widely considered to be a necessary best practice in modern web development. Now more than ever, this seemingly dogmatic reality of the web development experience has been challenged.

There are many reasons for this sudden change of heart.

The Fresh framework by Deno cited an improved developer experience due to tighter feedback loops.
The Svelte team followed suit but motivated by the maintainer's developer experience as they migrated the project away from TypeScript in favor of plain JSDoc comments for type annotations instead.
Most controversially, the Turbo framework dropped TypeScript support altogether after assessing that strong typing was the culprit behind poor developer experience.

One common thread ties everything together: developer experience. In this article, however, I will not argue whether TypeScript is still relevant today.² Instead, I choose to reflect on my own journey of stepping away from TypeScript—but for a completely different reason: consumer semantics!

TypeScript Need Not Apply

TypeScript prides itself as a superset of JavaScript. As a matter of fact, TypeScript owes much of its success to this key design decision. The classic migration guide for renaming .js to .ts considerably lowered the barrier to entry as teams gradually migrated their codebases. But, it is exactly this design decision that also made me realize where TypeScript isn't necessary!

With TypeScript being a superset of JavaScript, there exists a subset of the TypeScript language that's just plain old JavaScript. As it turns out in my experience, this also happens to be the subset of TypeScript that I deal with most often—especially in application code!

Consider the following example that features two TypeScript files: add.ts (simple adder library) and main.ts (application entry point).

// add.ts
export function add(x: number, y: number): number {
    return x + y;
}

// main.ts
import { add } from './add.ts';
console.log(add(1, 2)); // 3

In add.ts, the presence of type annotations makes TypeScript a necessity. On the other hand, a cursory inspection of main.ts shows us that its syntax is purely JavaScript! At its current state, main.ts need not be TypeScript; main.js is sufficient.

This central motivating example led me to re-evaluate my relationship with TypeScript. It gradually became apparent to me that TypeScript is best suited for library code while JavaScript is more appropriate for application code.

EDIT: I would like to clarify here that when I say "library code", I do not necessarily mean published NPM packages. "Library code" can refer to internally linked sub-projects in a monorepo/workspace. One may even consider imported files from the same project to be "library code". The point being: "application code" is the consumer of "library code" wherever that may be imported from (e.g., NPM, workspace, files, etc.).

Specifically, consumer code that can solely rely on type inference for type safety (i.e., no type annotations required) may thrive on JavaScript alone. This is not the case for library code which export functions that require type annotations—especially for parameters. One may even take this guideline to the extreme by removing return types from function signatures altogether in favor of return-value type inference. This is generally considered to be poor practice, though.

Nowadays, I isolate library code more aggressively. One may enforce a scheme (for example) where UI components are consumers written in JavaScript while the more complex business logic, data fetching, and data validation are imported from a TypeScript library. Of course, the libraries may be consumers themselves, in which case they may be written in plain old JavaScript as well.

Observe that such a scheme is desirable not only because it is a best practice that encourages more testable architectures, but also because it makes the separation between the JavaScript world and the TypeScript world more intentional. That is to say, I choose to write JavaScript (in consumer code) because type inference is sufficient. But, I also choose to write TypeScript everywhere else when type annotations, type aliases, and interfaces are necessary.

JavaScript First, Then TypeScript

The .js extension is no longer an indicator of antiquity, but a declaration of sufficiency in language semantics. I prefer to write plain old JavaScript because the .js extension presents itself as consumer code. The .js extension is a deliberate communication of the consumer semantics.

For more advanced cases, I upgrade from .js to .ts, but keep the TypeScript surface as minimal as possible while isolating it from the rest of the application code. Arguably, this is exactly what .d.ts declaration files are for, but I admittedly find that the developer experience for inline implementation files is more ergonomic (and less error-prone!) than duplicating function signatures in .js and .d.ts files.

Overall, I still strongly believe in TypeScript's value to the JavaScript ecosystem.³ Nowadays, I just choose to write JavaScript first wherever possible, then upgrade to TypeScript as a last resort.

This includes all sorts of transpiling, compiling, tree-shaking, code-splitting, bundling, etc. ↩
In fact, I am a huge fan of the type-safety conveniences and guarantees that TypeScript enables. ↩
Even without the TypeScript syntax, the benefits of type safety also extends to JSDoc annotations (which are powered by TypeScript analysis anyway). ↩

🤖 Svelte Reviewed: A Masterclass on Empowerment 🤖

Basti Ortiz — Mon, 11 Sep 2023 09:03:34 +0000

Cybernetically enhanced web apps.

A most interesting tagline for the Svelte framework since version 3. The Svelte team prides itself in aggressive compile-time automation and optimization—so much so that their previous tagline was actually "the magical disappearing UI framework" (literally!).

This is true enough even today, where the compiler strips away a lot of the inner mechanisms of the framework.¹ Behind this philosophy, Svelte's creator Rich Harris believes that if the framework can analyze it anyway, then the developer should not worry about it—which subtly takes a stab at the more mainstream UI frameworks that do the work of state analysis and resolution at runtime instead. Such is the philosophy of cybernetically enhanced web apps: let the tooling do the work!

But how far does Svelte take this philosophy? Does Svelte go as far as to become a zero-cost abstraction?² Putting aside all of the fancy compile-time machinery, how is the developer experience even like? In this article, we review the merits of the Svelte framework and its wider ecosystem.

Stellar Documentation

As with most things in life, first impressions also matter in the tech world. Poor examples, lengthy guides, inconvenient prerequisites, and strange syntax can easily turn off the most enthusiastic learners. As such, the classic Getting Started guide is where frameworks put their best foot forward.

In flying colors, Svelte really did put their best foot forward. The framework provides the following essential resources for onboarding:

Title	Description
Svelte	The official documentation/reference for the Svelte framework proper.
SvelteKit	The official documentation/reference for the SvelteKit meta-framework.
Examples	A repository of examples that serves as a tour of Svelte's features.
REPL	A live REPL editor/playground for trying out ideas in Svelte.
Tutorial	An interactive tutorial that features a comprehensive guide alongside a live editing environment.

Needless to say, Svelte does not lack in documentation. The guides are comprehensive enough to be complete, yet concise and straight to the point. Furthermore, the tone and language are sufficiently technical, but not so much as to come off dry and full of jargon.

The best examples come from the interactive tutorial, where the guides walk the reader through a motivating example before introducing features. The tutorial thus feels like a journey of discovering the essence of Svelte rather than a lecture on Svelte.

Meanwhile, for quick experimentation, the live examples and the REPL are the easiest ways to test the framework's behaviors. In my experience, I've found the REPL to be an invaluable tool in my belt when prototyping stateful components. The REPL also doubles as my go-to resource for demonstrating Svelte's coolest features to my peers.

Low Barrier to Entry

Personally, the best part about Svelte is its low barrier to entry. Much like the approach of TypeScript and Vue.js, the Svelte language³ strives to be a superset of the familiar trifecta of web development: HTML, CSS, and JavaScript.

As a mentor to many of my peers, it is so natural to transition to Svelte right after a discussion on fundamental web features and APIs. That is to say, Svelte truly feels more like an extension of the web platform than a replacement. All the Web APIs and the DOM APIs are the same. There is no need to learn about replacements for the <a> tag and whatnot. Background knowledge just transfers so seamlessly.

The language design of Svelte empowers beginners to prove to themselves that there is little to no magic behind UI frameworks; that everything is just built on top of the core Web APIs; and that everything is just plain old HTML, CSS, and JavaScript at the end of the day. The mental model perfectly bridges the gap between the world of components and the realities of the web platform.

SvelteKit: The Ultimate SSR, CSR, and SSG Solution

Before we proceed, let's begin by defining some terms:

Server-Side Rendering (SSR)
- The web server dynamically generates new (templated) HTML on-the-fly based on certain variables from the server, the database, the request, etc.
Client-Side Rendering (CSR)
- The web server sends an empty HTML app shell to the browser.
- The browser executes the JavaScript to populate the UI.⁴
- This usually implies extra round-trips to the server to fetch application data (typically in JSON).
Static Site Generation (SSG)
- The build system precompiles⁵ the HTML ahead of time.
- The web server thus only hosts static assets (e.g., HTML, CSS, and JS).

For many decades, the Web went back and forth between these three strategies—one trend after the next but never settling. To be fair, each has their own merits and trade-offs (as with most things in engineering).

However, what's most impressive about the Svelte ecosystem is its ability to seamlessly mix and match these strategies. This is where SvelteKit enters the picture.

Powered by Vite, SvelteKit is an officially maintained meta-framework⁵ that provides a full routing solution (client-side and server-side) on top of the Svelte framework proper. It combines the best of all worlds by empowering the developer to granularly choose which routes to render on the server (SSR), which routes to hydrate only on the client (CSR), and which routes to prerender as static HTML (SSG).

This seemingly zero-cost² flexibility is a godsend for pedants such as myself who take pride in squeezing every last byte of efficiency in the network.⁶ This is a far cry from the olden days when we were often forced to commit to only one strategy per application—lest we "eject" from prescribed project structures and implement the magic ourselves.

For example, consider a PHP app or an Express app with EJS templating just for the sake of SSR. Also consider the trendy React apps from the pre-2016 era just for the sake of CSR. Or pehaps consider a Gatsby setup just for the sake of SSG.

In all cases, we often required that these be separate applications. Back then, we just didn't have a holistic solution/framework that streamlines the notion of hybrid rendering strategies at the granularity level of routes. Now we do.⁷

In other words, SvelteKit empowers us to ask not whether we should commit to SSR exclusive-or CSR exclusive-or SSG, but to instead ask which specific routes we can use SSR inclusive-or CSR inclusive-or SSG on. It is a truly liberating experience to have everything just work™ out of the box.

Accessibility as a First-Class Citizen

One feature that is especially admirable about Svelte is its treatment of accessibility as a first-class citizen. The Svelte compiler goes as far as to enforce accessibility best practices and warn against the anti-patterns.

The interminable yellow squiggly lines may seem cumbersome at first, but one must always keep in mind that disabling them misses the entire point!

Some posit that this is one of Svelte's most annoying features. I personally disagree. As someone who is not so well versed in the intricacies of accessibility, I greatly appreciate the automated reminders to get off my high horse of privilege and immerse myself into the viewpoint of disabled folks.

However, I must admit that event delegation patterns in Svelte are a little cumbersome. Event delegation usually involves attaching event listeners to non-visible parent containers, which the compiler flags as accessibility warnings.

Indeed, it is rather strange to attach a click listener on seemingly arbitrary <div> tags—even stranger when they're nested! Typically, these warnings are resolved by applying the correct ARIA roles and attaching the corresponding keydown listeners. In these rare false positive cases, however, I am not totally against disabling the particular warning altogether.

Small Ecosystem

Yes, the Svelte ecosystem is relatively small especially when compared to that of React. At face value, this is a bad look on the ecosystem. One may even dare to say: "Svelte is dead!" But I believe there is a more satisfying reason behind the small ecosystem—there is just no need for a big one!

Recall that the Svelte language aims to be an extension of the web platform. As such, much of the framework internals use and accept (as arguments) the standard objects from Web APIs that are already built into browsers.

Consider for example fetch, Request, Response, FormData, Node, CustomEvent, etc. When most of the essentials are already built into browsers, it is rarely the case that a Svelte developer reaches out for libraries.

Easy Integration with Web-First Libraries

This is especially true when integrating with established third-party libraries (that were built for the Web rather than for a particular framework). One example that I can cite from experience is the Chart.js library, which works with plain old HTMLCanvasElement objects. In Svelte, a simple bind:this is sufficient to set things in motion without much ceremony.⁸ Of course, one may also opt to use wrapper libraries⁹ for convenience.

Nevertheless, the central point is that in the Svelte world, wrapper libraries are mainly for convenience. They are sufficient to get the job done, but not necessary as it is in other frameworks.¹⁰ It's rare for a third-party library to require some additional svelte-adapter-* package just to cleanly interface with Svelte's reactivity.

No Need for State Management Libraries

Speaking of Svelte's reactivity, one more thing that is also worth mentioning is the fact that state management libraries are unheard of in the Svelte world. This is not because the "Svelte ecosystem is dead". Rather, to reiterate the point, the Svelte ecosystem does not need one!

The built-in stores and reactive variables cover most (if not all) of the use cases. In fact, the reactive primitives and the logic blocks are so powerful together that they can elegantly express component-level state machines—zero third-party libraries required!

On the off chance that these reactive primitives aren't sufficient, then perhaps it is a sign to reconsider the architecture altogether. There is always a better way to do things...

Fine-Grained Reactivity (Sometimes!)

Thanks to the compiler, Svelte boasts a "magical[ly] disappearing UI framework" where reactivity and state dependencies are resolved and bound at compile-time. For most primitive variables (e.g., strings, numbers, Booleans, etc.), fine-grained reactivity is sufficient and works great out of the box. In fact, it is exactly this fine-grained reactivity that enables Svelte to consistently outperform all of the UI frameworks except a few. More on this later.

At the component level, the unit of reactivity is the variable while the catalyst for reactivity is reassignment. Svelte will even prevent a DOM re-render if the newly assigned state is strictly equal to its previous value. Note that for objects and arrays, this check is done recursively to reach that extra mile in fine-grained reactivity.

Despite these guard conditions, however, an unfortunately common mistake with non-primitive variables (e.g., objects) introduces a subtle pessimization on reactive side effects (which execute before the re-render guard).

Consider the example below where we have a data object with two fields: count and other. In the example, we will only modify data.count whenever we click on a <button>. Meanwhile, the data.other field will always remain untouched.

<script>
    // Recall that _only_ the `count` will be modified.
    let data = { count: 0, other: null };
    const increment = () => ++data.count;

    // Intuitively, this side effect should run per increment.
    $: console.log('updated count', data.count);

    // With that said, will this side effect ever run?
    $: console.log('updated other', data.other);
</script>

<!-- Increment `data.count` per click. -->
<button on:click={increment}>+</button>

Surprisingly, the side effect with data.other will actually run! This goes back to the fact that variables are the units of reactivity while reassignment is the catalyst for reactivity. Since data.count is inside the data variable (as a whole), then all dependents on the data object will also be notified of the change! The data.other side effect executes simply because it just happens to implicitly reference the data variable (as a whole).

The fix is frustratingly simple: normalize the primitives!

<script>
    // Same old `data` here.
    let data = { count: 0, other: null };

    // Now we "normalize" the object into its primitives.
    // Alternatively, we could have just separated the variables
    // to begin with rather than putting them in an object.
    $: ({ count, other } = data);

    // Same click handler.
    const increment = () => ++count;

    // Now only this side effect will run.
    $: console.log('updated count', count);

    // This is unreachable code because we hold no references
    // to `data` nor to the normalized `count` variable.
    $: console.log('updated other', other);
</script>

<!-- Increment `count` per click. -->
<button on:click={increment}>+</button>

Kevin Bridges (@kevinast) goes into great detail about this behavior in his article on exploring Svelte's reactivity. The main point is that Svelte lets us "fine tune the reactivity"—for better or worse...

Responsive Svelte (exploring Svelte's reactivity)

Kevin Bridges ・ Jul 17 '20

#svelte #reactivity #webdev #javascript

There are more examples out there where Svelte is not as fine-grained as I first thought. To cite another example, the {#each} block actually diffs by the provided key expression when the backing array gets modified. This should be an incredibly fast operation, but I was nevertheless disappointed to find out that there was no fancy compile-time machinery happening behind the scenes.

Returning to the framework benchmarks, perhaps it is for this reason why SolidJS consistently outperforms Svelte. Simply put, when it comes to non-primitive variables, SolidJS stores (which are essentially just recursive signals with fine-grained mutation helpers) are more fine-grained than that of Svelte.

Now if there was somehow a way to integrate (at compile-time!) the fine-grained reactivity of SolidJS signals with the expressiveness of the Svelte language, then that would be the most unstoppable framework ever! But alas, we do not live in a perfect world... yet!

UPDATE: On 20 September 2023, the Svelte team announced runes for Svelte 5. The signal-based rewrite of the framework internals implements finer-grained SolidJS-like reactivity at compile-time! Perhaps the perfect world is not so far after all... 🎉

The Exotically Magical Dollar

If there is one part of Svelte that is worth nitpicking, it is certainly the bold decision to change the semantics of a seldom-used JavaScript feature: labels. The $ syntax is simultaneously the most elegantly brilliant and also the most exotically magical feature of the Svelte language.

In the beginning of this review, I emphasized that Svelte prides itself in proving that there is no magic behind UI frameworks. This is the only exception.

As a JavaScript purist, it initially horrified me to see the $ everywhere. I could forgive (and even applaud) the $: label syntax, but the store prefix (i.e., $store) was where I drew the line.

In the beginning, I frequently found myself forgetting to prefix my stores with $ before accessing its inner value. Admittedly, this was a rather frustrating experience, especially considering the fact that it felt too magical for me. I knew that it desugared into the more verbose subscribe pattern, but my inner purist self could not help but feel icky about the non-standard semantics. I eventually grew to embrace the syntax, but the journey was nevertheless jarring.

Whenever I teach Svelte to JavaScript beginners, I always made sure to emphasize that the $ syntax is a non-standard Svelte-specific feature. As a mentor, the obligatory disclaimer that prefaces all of the lectures eventually does get old. But alas, the incessant reminders are necessary—lest we fall into the trap of becoming Svelte developers (exclusively) rather than JavaScript developers.¹¹

A Masterclass on Empowerment

For all of my major projects, Svelte has become my go-to framework. In all of my years of experience in full-stack development, no other framework comes this close to perfection (for now!).

Onboarding has a low barrier to entry (i.e., HTML, CSS, and JS are the only prerequisites).
Outstanding documentation and interactive playgrounds.
Minimal framework magic (aside from the aforementioned $ syntax).
Minimal performance overhead (aside from the aforementioned "not-granular-enough" footguns) if any.
Beautifully intuitive syntax and semantics behind the template language.
Keeps the spirit of zero-cost² abstractions (or otherwise minimal overhead) alive.
Maximal route-level flexibility in rendering strategies (with SvelteKit).
Streamlined developer workflow and plugin system (thanks to Vite).

All of these reasons are why I never hesitate to advocate for Svelte at my department. I have personally led several successful Svelte projects in the past semester alone. Many of these projects, in fact, involved onboarding complete beginners and experienced developers alike. Regardless of the team composition, Svelte never failed to produce successful projects. The same is true even for other teams that I have offered technical consultation on.¹²

The astute reader may notice a common theme in this review: empowerment. Svelte and its zero-cost² philosophy empower teams to move fast with ease and confidence.

Because Svelte does not require a degree in rocket science to understand, it also empowers individuals to believe that they are capable of building full-stack applications; that front-end development can be intuitive; that back-end development doesn't have to be so scary; and that they are more qualified than they initially thought.¹³

This is why Svelte is a masterclass on empowerment.

Needless to say, I am a huge fan of the Svelte team's work. I would like to thank them for empowering developers, keeping the spirit of innovation alive, and pushing the boundaries of full-stack web development.

Aside from the necessities, of course! Namely: hydration code, client-side routing, and effect scheduling. Note that these are actually optional if one decides to fully prerender their pages (i.e., static site generation). ↩
I mean "zero-cost" in a C++ sense that framework features are compiled and packaged into the final bundle if and only if they are actually used. Furthermore, the features that are compiled and packaged cannot possibly be written by hand any better. ↩
Yes, Svelte is a language. ↩
In Svelte parlance, this is called hydration. ↩
In Svelte parlance, this is called prerendering. ↩
Perhaps not exactly zero-cost in the sense that SvelteKit's SSR capabilities require (the overhead of) a Node.js-compatible JavaScript runtime rather than an external web server base layer written in Rust or Go for example. There are ways to work around this, of course, but that is beyond the scope of this article. ↩
Note that nowadays, SvelteKit is not the only framework that supports this level of flexibility. But then again, that is beyond the scope of this article. ↩
Yes, I'm aware that this is also possible in React with useRef, but that is not our topic for today. ↩
The svelte-chartjs library seems to be a popular option among Svelte developers. ↩
By "necessary", I mean that it is otherwise unwieldly to write the integration ourselves. That is, it is "unwieldly" in the sense that we have to consider so many footguns just to get it right: two-way data bindings, re-renders, caching, performance, etc. ↩
Such is the trap that many beginners fall into when they eagerly jump into React before learning the fundamentals of JavaScript first. ↩
Some teams built CSR Svelte apps on Electron. Others went for the traditional hybrid SSR and CSR route. On some of my projects, SvelteKit has become my go-to solution for SSG. ↩
In fact, one of my friends even went from zero full-stack knowledge to AWS-certified cloud practitioner in three months after recommending Svelte to them! ↩

Please don't write confusing conditionals

Basti Ortiz — Wed, 12 Jul 2023 14:41:30 +0000

Have you ever spent more than a few seconds staring at the same line of code? How often did you find conditionals that were tricky to parse? In this article, we discuss how confusing conditionals manifest in our code. Along the way, we also explore different refactoring techniques for improving the readability of conditional control flows.

Double Negatives

A double negative arises when we negate a variable whose name is already in a non-affirmative style. Consider the following example.

// Non-affirmative Naming Convention
const isNotReady = doSomething();
const isForbidden = doSomething();
const cannotJoinRoom = doSomething();
const hasNoPermission = doSomething();

// Negating once results in an awkward double negative situation.
console.log(!isNotReady);
console.log(!isForbidden);
console.log(!cannotJoinRoom);
console.log(!hasNoPermission);

This is opposed to the affirmative style, which requires less cognitive load to parse because one does not need to jump through the hoops of negating the variable name to extract the essence of its logic. In other words, the intent behind an affirmative variable may be read as is—no hoops required! Consider the following modifications to the previous example.

// Affirmative Naming Convention
const isReady = doSomething();
const isAllowed = doSomething();
const canJoinRoom = doSomething();
const hasPermission = doSomething();

// Negation actually makes sense here!
console.log(!isReady);
console.log(!isAllowed);
console.log(!canJoinRoom);
console.log(!hasPermission);

Unfortunately, non-affirmative naming conventions are sometimes inevitable due to standards and backwards-compatibility. Take the HTMLInputElement#disabled property of the HTML DOM APIs for example. The presence of the disabled attribute in an <input> tag tells the browser to (visually and literally) disable the element's form controls. Otherwise, its absence causes the <input> to exhibit its default behavior, which is to accept user input. This is an unfortunate side effect of the ergonomics of HTML.

<!-- Normal Checkbox (Default) -->
<input type="checkbox" />

<!-- Disabled Checkbox -->
<input type="checkbox" disabled />

Nevertheless, we should still strive for affirmative naming conventions wherever possible. They are easier to read and parse simply because there is no need to mentally negate the variable name at all times. This rule applies to both variables names and function names alike.

Non-affirmative Control Flows

The next form of a double negative is a little bit more subtle.

// Suppose that we _do_ follow affirmative naming conventions.
const isAllowed = checkSomething();
if (!isAllowed) {
    // There is something funny about this...
    doError();
} else {
    // Notice how the `else` block is practically a double negation?
    doSuccess();
}

As seen above, the non-affirmative style can also pervade conditional control flow. Recall that an else block is practically a negation of the corresponding if condition. We must therefore extend the affirmative style here. The fix is actually rather simple.

// Just invert the logic!
const isAllowed = checkSomething();
if (isAllowed) {
    doSuccess();
} else {
    doError();
}

The same rule applies to equality and inequality checks.

// ❌ Don't do this!
if (value !== 0) {
    doError();
} else {
    doSuccess();
}

// ✅ Prefer this instead.
if (value === 0) {
    doSuccess();
} else {
    doError();
}

Some may even go as far as to let a conditional block be blank just to negate a condition in affirmative style. Although I am not advocating for everyone to take it this far, I can see why this may be more readable for some people. Take the instanceof operator for example, which cannot be easily negated without parentheses.

if (obj instanceof Animal) {
    // Intentionally left blank.
} else {
    // Do actual work here (in the negation).
    doSomething();
}

Exceptions for Early Returns

As a quick aside, there are special exceptions for conditional control flows that return early. In such cases, the negation may be necessary.

if (!isAllowed) {
    // Return early here.
    doError();
    return;
}

// Otherwise, proceed with the success branch.
doSuccess();

Wherever possible, though, we should still attempt to invert the logic if it results in lesser nesting, fewer levels of indentation, and more readable affirmative styles.

// Prefer affirmative early returns.
if (isAllowed) {
    doSuccess();
    return;
}

// If we did not invert the logic, this would have been
// nested inside the `!isAllowed` conditional block.
if (!hasPermission) {
    doPermissionError();
    return;
}

// When all else fails, do something else.
doSomethingElse();
return;

Another way to express the same control flow in an affirmative style (without early returns) is as follows.

// Hooray for the affirmative style!
if (isAllowed) {
    doSuccess();
} else if (hasPermission) {
    doSomethingElse();
} else {
    doPermissionError();
}
return;

Of course, there are plenty of other ways to swap, invert, and refactor the code—the merits for each are totally subjective. Preserving the affirmative conventions thus becomes some kind of an art form. In any case, code readability will always improve as long as we uphold the general guidelines of the affirmative style.

Compound Conditions

The story gets a little bit more complicated with logical operators such as AND and OR. For instance, how do we refactor the code below in a more affirmative style?

// This is fine... but there has to be a better way,
// right? There are just too many negations here!
if (!isUser || !isGuest) {
    doSomething();
} else {
    doAnotherThing();
}

For compound conditionals, we introduce the most underrated law of Boolean algebra: De Morgan's Laws!

// Suppose that these are **any** two Boolean variables.
let a: boolean;
let b: boolean;

// The following assertions will **always** hold for any
// possible pairing of values for `a` and `b`.
!(a && b) === !a || !b;
!(a || b) === !a && !b;

Thanks to De Morgan's Laws, we now have a way to "distribute" the negation inside a condition and then "flip" its operator (from && to || and vice-versa).

Although the following examples only feature binary comparison (i.e., two elements), De Morgan's Laws are generalizable over any number of conditional variables as long as we respect operator precedence. Namely, the && operator is always evaluated first before the || operator.

// By De Morgan's Laws, we can "factor out" the negation as follows.
if (!(isUser && isGuest)) {
    doSomething();
} else {
    doAnotherThing();
}

// Then we simply invert the logic as we did in the previous section.
if (isUser && isGuest) {
    doAnotherThing();
} else {
    doSomething();
}

Now, isn't that much more readable? Using De Morgan's Laws, we can clean up conditionals that have "too many negations".

Conclusion

The overall theme should be apparent at this point. Wherever possible, we should avoid writing code that forces the reader to jump through hoops that (needlessly) necessitate extra cognitive overhead. In this article, we discussed the following techniques:

Encourage affirmative naming conventions.
- Avoid negative terms/prefixes like no, not, dis-, mal-, etc.
- Prefer the positive equivalents.
Invert conditional control flow (where possible) to accommodate for the affirmative style.
- Feel free to play around when swapping, inverting, and refactoring branches.
- Early returns may necessitate negations.
Use some tricks from Boolean algebra to invert condtionals.
- De Morgan's Laws are especially powerful tools for refactoring!

Now go forth and bless the world with cleaner conditionals!

DEV Community: Basti Ortiz

Coding Agents as a First-Class Consideration in Project Structures

Working with Context Windows as the Bottleneck

Optimizing for Feature-Localized Context

You're slicing your architecture wrong!

How Classical Architectures Pessimize Exploration

How Vertically Sliced Architectures Optimize for Selectivity

Conclusion

Mastering Python's Iteration Protocol: Iterables, Iterators, and Generators

The Iterator Contract

Iterables and __iter__

Iterators and __next__

Aside: The Importance of Brand New Independent Instances

Worked Examples

Infinite Counter

Singly Linked List

Generators

The Comprehension Syntax

Simplifying the Worked Examples

The Conveniences of itertools

Recap: what did we learn?

🔥 Simulating Course Schedules 600x Faster with Web Workers in CourseCast

Simulating Course Match with CourseCast

So where was the bottleneck?

So how did we scale CourseCast 2025?

Scrapping the Python Server

Precomputing Static Course Conflicts

Offloading CPU-Bound Work to a Separate Thread

Parallelizing with Worker Thread Pools

Conclusion

You're slicing your architecture wrong!

Horizontally Sliced Architectures

Vertically Sliced Architectures

Example: React + Next.js

Conclusion

Further Reading

Beware the Global Const

A race condition?

It's a front-end bug, then?

The dangers of default configurations

Aside on serverless environments

Some mitigations and workarounds

The Curse of Verbosity and Indirection

Free functions as a first-class citizen

Closures as a first-class citizen

Import-once modules as a first-class citizen

Unions as a first-class citizen

Conclusion

I was wrong about array methods and generators...

The Setup

Case 1: raw-for-loop

Case 2: for-of-loop

Case 3: array-method

Case 4: generator

The Experiment

BastiDood / js-generators-vs-array-methods

The repository for all the scripts, notebooks, results, and analyses related to my experiments on JavaScript generators and chained array methods.

JavaScript Generators vs. Array Methods

Generating Random Bytes

Running the Experiments

The Results

Node.js Results

Deno Results

Node.js and Deno: One and the Same

Bun Results

Interpretations and Conclusions

The Importance of Spatial and Temporal Locality

V8 versus JavaScriptCore

So... when to use generators then?

Future Work

BastiDood / js-generators-vs-array-methods

The repository for all the scripts, notebooks, results, and analyses related to my experiments on JavaScript generators and chained array methods.

JavaScript Generators vs. Array Methods

Generating Random Bytes

Running the Experiments

A Compelling Case for the Comma Operator

A Motivating Example

A Compelling Case

Conclusion

Bitmasks are not so esoteric and impractical after all...

Iterables and `iter`

Iterators and `next`

The Conveniences of `itertools`

Case 1: `raw-for-loop`

Case 2: `for-of-loop`

Case 3: `array-method`

Case 4: `generator`