Jim Fisher’s blog

The migration SQL should go in the table

2025-11-18T00:00:00.000Z

So you run migrate in your dev environment, but it fails: some unknown migration add-foobar has already been applied from some other experimental branch, and the migration tool doesn’t know how to down-migrate it. To fix it, you have to hunt for the branch that created that migration, to find its down-migration SQL. Hopefully you still have that migration!

I want migrate to always get me to my desired database schema, no matter what the current migration list looks like. But no migration tools today have this property: they always need a developer in the loop to find the down-migration SQL.

Say the database has applied migrations a → b → c, but we want a → b → d. Then migrate needs to run the down-migration for c, then run the up-migration for d. This means migrate may need the down-migration SQL for any migration that has been applied. We can guarantee this by storing the down-migration in the migrations table:

id  name         down_sql
==  ===========  ====================================
0   users-table  drop table users;
1   email-col    alter table users drop column email;

All other migration tools I know of have a migrations table, but they only store a list of migration names. They assume you have the migration code checked out for the current database schema. This is a bad assumption, even for your production database! Say a bad migration gets applied to your production database. You should be able to roll back in the normal way: revert the commit and redeploy. But with standard migration tools, this can’t work: the down-migration SQL is lost in the revert!

A job queue in two lines of JS

2025-07-07T00:00:00.000Z

If you need a job queue in JS, you can do it in two lines:

type Job = () => Promise<unknown>;

let chain = Promise.resolve();
const enqueue = (job: Job) => chain = chain.then(job, job);

For example, if your app makes API requests, you may need requests to be processed in the order they were dispatched:

function setDone(id: string, done: boolean) {
  enqueue(() => fetch(`/todos/${id}`, {
    method: "POST",
    body: JSON.stringify({ done }),
  }));
}

Note that chain.then(job) is probably not what you want, because any rejection in the chain will cause the job to never run. Instead you want chain.then(job, job), which will run job when the chain either rejects or resolves.

Sticky snap: a better snapping algorithm

2025-06-29T00:00:00.000Z

The “snapping” feature in most drawing apps has a problem: you can’t place the object near snap lines, so for precise positioning, you have to disable snapping. In this post, I show sticky snap, a better algorithm. But first, try to place the green rectangle at the target using the standard snap algorithm:

You’ll soon find that it’s impossible to reach! The snap lines always pull the object out of place. Sometimes useful, but often very frustrating. To complete this task, you’ll need to disable snapping!

I call that standard algorithm magnetic snap, because the snap lines exert “action at a distance” on the thing you want to drag. Now for contrast, try out sticky snap on the same task:

With sticky snap, you can drag to the target by approaching it without touching the snap lines. Here, the snap lines are not magnetic, they’re sticky. The snap lines don’t exert action at a distance; they only exert force once you’ve stuck something to them. You get the best of both worlds: easy to snap, but also easy to avoid the snap line.

I discovered sticky snap in macOS window management: try dragging a window next to another one! Notice, unlike every other app with snapping, macOS has no “window snap off” mode. This is no coincidence: with sticky snap, you don’t need to turn it off.

Yet I haven’t seen sticky snap anywhere else. All drawing apps I’ve tried use naive magnetic snap: Figma, Google Docs, tldraw, Inkscape, Keynote, etc. As such, all these apps have to make it easy to disable snapping, or even to start with snapping off. They should all consider using sticky snap!

`window.ai` hello world

2024-06-29T00:00:00.000Z

If you’re running Chrome with the window.ai API, here’s a UI to prompt an LLM running locally in your browser:

Prompt

Top K: Temperature:

Status:

Output

I wrote these TypeScript type definitions for the API:

declare global {
  interface WindowOrWorkerGlobalScope {
    readonly ai?: {
      canCreateTextSession(): Promise<"readily" | "after-download" | "no">;
      createTextSession(
        options?: Partial<AITextSessionOptions>,
      ): Promise<AITextSession>;
      defaultTextSessionOptions(): Promise<AITextSessionOptions>;
    };
  }
}

type AITextSession = {
  prompt(input: string): Promise<string>;
  promptStreaming(input: string): AsyncIterable<string>;
  destroy(): void;
  clone(): AITextSession; // Not yet implemented!
};

type AITextSessionOptions = {
  topK: number;
  temperature: number;
};

Interactive Turing patterns in WebGPU

2024-05-29T00:00:00.000Z

Below is an interactive Turing pattern. It follows Karl Sims’ model. It’s implemented in WebGPU.

Feed Rate: 0.055

Kill Rate: 0.062

WebGPU hello world in 2024

2024-05-25T00:00:00.000Z

Below is a Game of Life simulation. It uses WebGPU.

Here’s the essential JavaScript:

const canvas = document.getElementById("example-canvas");
if (!navigator.gpu) {
  throw new Error("WebGPU not supported on this browser.");
}
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) {
  throw new Error("No appropriate GPUAdapter found.");
}
const device = await adapter.requestDevice();
const context = canvas.getContext("webgpu");
if (!context) {
  throw new Error("Canvas context not found");
}
context.configure({
  device: device,
  format: navigator.gpu.getPreferredCanvasFormat(),
});
const encoder = device.createCommandEncoder();
const pass = encoder.beginRenderPass({
  colorAttachments: [
    {
      view: context.getCurrentTexture().createView(),
      loadOp: "clear",
      clearValue: { r: 1, g: 0, b: 1, a: 1 },
      storeOp: "store",
    },
  ],
});
pass.end();
device.queue.submit([encoder.finish()]);

This is derived from this tutorial.

What is Monte Carlo integration?

2024-04-24T00:00:00.000Z

What’s the average distance that someone can jump? Let’s estimate it! I have a silly function that gives me the distance that someone can jump, based on their height h in centimeters:

function jumpDistance(h: number): number {
  return h < 0 || h > 360 ? 0 : 300 * Math.sin(h * (Math.PI / 400));
}

Next we’ll describe the heights of people in the population. To start, let’s say the population is just two people: Jane is 160 cm tall, and Peter is 180 cm tall. Then we can estimate the average jump distance:

const janeJump = jumpDistance(160);
const peterJump = jumpDistance(180);
const averageJump = (janeJump + peterJump) / 2;

With a bigger population, we can describe the population with an array of heights:

const populationHeights = [160, 180, 170, 190, 150];
let totalJump = 0;
for (const h of populationHeights) {
  totalJump += jumpDistance(h);
}
const averageJump = totalJump / populationHeights.length;

For a yet larger population, we can describe the population by keeping a tally for each height:

const populationHeights = new Map([
  [160, 23],
  [170, 45],
  [180, 32],
  [190, 12],
  [200, 8],
]);
let totalJump = 0;
let totalPeople = 0;
for (const [h, count] of populationHeights) {
  totalJump += count * jumpDistance(h);
  totalPeople += count;
}
const averageJump = totalJump / totalPeople;

For an even larger population, we can describe the population by a probability distribution, like $\text{Normal}(\mu=170, \sigma=20)$. Then the precise average jump distance is:

\[ \int_{h = -\infty}^{\infty} \text{jumpDistance}(h) \, \text{Normal}(h; \mu=170, \sigma=20) \, dh \]

Yuck! Suddenly we can’t solve the problem by just running the code, because there are infinitely many heights to consider. Our nice finite loop turned into an infinite integral. And it’s horrible to solve analytically, especially because jumpDistance is a piecewise function.

What can we do instead? If we have access to a function that gives us the population count at each height, we can do what we were doing before, but with some chosen heights:

function popCountForHeight(h: number) {
  return 1000 * Math.exp(-0.5 * ((h - 170) / 20) ** 2);
}

let totalJump = 0;
let totalPeople = 0;
for (let h = 0; h < 360; h += 1) {
  const count = popCountForHeight(h);
  totalJump += count * jumpDistance(h);
  totalPeople += count;
}
const averageJump = totalJump / totalPeople;

This approach could be called a Riemann sum. One problem with this approach is that we need to know a range of heights to consider that will cover most of the population, but not too much that we’re wasting time on heights that are very unlikely. Above, we chose to consider heights from 0 to 360 cm.

Another approach is to sample from the distribution:

const populationHeights = new NormalDistribution({ mean: 170, stdDev: 20 });

let totalJump = 0;
let totalPeople = 0;
for (let i = 0; i < 1000; i++) {
  const h = populationHeights.sample();
  totalJump += jumpDistance(h);
  totalPeople++;
}
const averageJump = totalJump / totalPeople;

Surprise, this is Monte Carlo integration!

How to escape JavaScript for a script tag

2024-04-24T00:00:00.000Z

To add JavaScript to a web page, we use a <script> tag like this:

<script>console.log("Hello!");</script>

But what if we need to add arbitrary JavaScript to our web page? Say, a valid script like this?:

if (x<!--y) { ... }

We can’t just write that in a <script> tag, because the browser will interpret the <!-- as the start of an HTML comment!

“But that’s fine,” you think. “We can just escape the string. This is how we serialize strings everywhere else in programming.”

You might reach for HTML entities, replacing < with <. After all, isn’t the JavaScript just ordinary text content? No, it’s not! Once the browser sees a <script> tag, it goes into a special JavaScript parsing mode, where HTML entities are not interpreted!

In this JavaScript parsing mode, the browser is looking for one of two strings:

</script to end the script tag
<!-- to start an HTML comment

To “escape” arbitrary JavaScript, we need to avoid those two substrings.

If we find <!-- in our JavaScript, we can’t just replace it, because its meaning is context-dependent:

// This is a comment containing <!--
let foo = x <!--y; // That's valid JS operators
const s = "This is a string containing <!--";

To “escape” the above JavaScript, we’d have to write something like:

// This is a comment containing
let foo = x < !--y; // That's valid JS operators
const s = "This is a string containing <" + "!--";

This is not a simple string replacement. To do those replacements, we need to parse the JavaScript, and handle every possible context where <!-- might appear.

Here’s the HTML spec. It’s all rather horrifying.

On that flickering blur in Chrome

2024-04-23T00:00:00.000Z

backdrop-filter: blur is a popular design for navbars. But it’s unusable in its current state, due to its flickery appearance in Chrome. Here’s an example:

A heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.

Nav with a blurred background

In Chrome, notice how even a 1px scroll can cause the color to completely change. Here’s a recording:

Your browser does not support the video tag.

Here’s the general problem: a blur operation, at the edges of the image, needs to know what the content is outside the image. The correct approach would be to give the blur filter enough of the background content to work with. But in Chrome, the blur is only given the pixels immediately behind the element. So, as a hack, the blur must guess what the content is outside the nav. Wikipedia calls this “edge handling”.

Chrome seems to take the extend strategy: it guesses that the pixels at the edge of the background image extend infinitely in all directions. This is why the blur flickers so much: a tiny scroll causes the edge pixels to change, which causes the extended pixels to completely change.

One better edge-handing strategy is mirroring. Mirroring is better because, even though it’s inaccurate, it results in smoother transitions.

Neither Firefox nor Safari have this problem, although I’m not sure which approach they take to edge handling.

What is the Metropolis algorithm?

2024-04-18T00:00:00.000Z

We could estimate Bob’s lunch tomorrow by counting the previous lunches you’ve seen him eating in the cafeteria:

Lunch	Count
Apple	2
Banana	3

Now we want to simulate Bob’s future lunches. Assume Bob randomly picks a lunch each morning, with the relative proportions you’ve observed. Then we can simulate Bob’s lunch with:

type Meal = "Apple" | "Banana";

function sample(): Meal {
  return Math.random() < 2 / 5 ? "Apple" : "Banana";
}

$\tfrac25$ of the samples will be Apple, and $\tfrac35$ will be Banana.

The Metropolis algorithm gives a different way to get samples with those correct proportions. It looks like this:

function nextMeal(currentMeal: Meal): Meal {
  if (currentMeal === "Apple") {
    return "Banana";
  } else {
    if (Math.random() < 2 / 3) {
      return "Apple";
    } else {
      return "Banana";
    }
  }
}

class Chain {
  currentMeal: Meal;

  constructor() {
    this.currentMeal = "Apple";
  }

  sample(): Meal {
    const current = this.currentMeal;
    this.currentMeal = nextMeal(current);
    return current;
  }
}

Yes: this algorithm is more complicated and performs worse! But the underlying technique can help us sample from more complex distributions. So let’s see what it’s doing here, and why it works at all.

Instead of each sample call being independent, the Metropolis algorithm initializes a Chain which maintains a “current meal”. Each call to sample sets the next meal.

Here’s one run of one chain:

const chain = new Chain();
for (let i = 0; i < 10; i++) {
  console.log(`Day ${i}: `, chain.sample());
}

Day 0:  Apple
Day 1:  Banana
Day 2:  Apple
Day 3:  Banana
Day 4:  Banana
Day 5:  Apple
Day 6:  Banana
Day 7:  Banana
Day 8:  Apple
Day 9:  Banana

Notice Bob’s first meal is always Apple. And if Bob’s current meal is Apple, the next meal is always Banana, so Bob’s second meal is always Banana. Here are two problems with the Metropolis algorithm:

The first few samples are not in the correct distribution.
Samples are dependent on the previous samples.

Let’s run $10{,}000$ chains, and then log the distribution of apples on each day:

const chains: Chain[] = [];
for (let i = 0; i < 10000; i++) chains.push(new Chain());

for (let i = 0; i < 10; i++) {
  const samples = chains.map((chain) => chain.sample());
  const numApples = samples.filter((sample) => sample === "Apple").length;
  console.log(`Num apples on day ${i}:`, numApples);
}

Num apples on day 0: 0
Num apples on day 1: 6673
Num apples on day 2: 2202
Num apples on day 3: 5186
Num apples on day 4: 3184
Num apples on day 5: 4563
Num apples on day 6: 3600
Num apples on day 7: 4255
Num apples on day 8: 3846
Num apples on day 9: 4041

By day $9$, approximately $4{,}000$ of the $10{,}000$ chains have apples. This is the correct proportion of $\tfrac25$. But the number bounces around before reaching this equilibrium.

This is called convergence. To analyze this more mathematically, we can instead simulate the distribution of chains for the current meal, and calculate the distribution for the next meal:

type MealDist = [number, number];
function nextMealDist(currentMealDist: MealDist): MealDist {
  const [numApples, numBananas] = currentMealDist;

  // Consider those eating apples today. What will they eat tomorrow?
  let a2a = numApples * 0; // None will eat apples.
  let a2b = numApples * 1; // All will eat bananas.

  // Then consider those eating bananas today. What will they eat tomorrow?
  let b2a = numBananas * (2 / 3); // Two-thirds will eat apples.
  let b2b = numBananas * (1 / 3); // The rest will eat bananas.

  const numApplesTomorrow = a2a + b2a;
  const numBananasTomorrow = a2b + b2b;

  return [numApplesTomorrow, numBananasTomorrow];
}

// To start, all 10,000 chains are eating apples.
let currentMealDist: MealDist = [10_000, 0];

for (let i = 0; i < 10; i++) {
  currentMealDist = nextMealDist(currentMealDist);
  console.log(`Num apples on day ${i}: ${currentMealDist[0].toFixed(3)}`);
}

Again, we see that by day $9$, around $\tfrac25$ of the chains are eating apples:

Num apples on day 0: 0.000
Num apples on day 1: 6666.667
Num apples on day 2: 2222.222
Num apples on day 3: 5185.185
Num apples on day 4: 3209.877
Num apples on day 5: 4526.749
Num apples on day 6: 3648.834
Num apples on day 7: 4234.111
Num apples on day 8: 3843.926
Num apples on day 9: 4104.049

Actually, we don’t need to start the distribution at [10_000, 0]. We can just start with [1, 0]. This is then a probability distribution, because the sum of the two numbers is $1$. Then the output is the probability distribution of the each meal:

let currentMealDist: MealDist = [1, 0];

for (let i = 0; i < 10; i++) {
  currentMealDist = nextMealDist(currentMealDist);
  console.log(
    `Probability of apples on day ${i}: ${currentMealDist[0].toFixed(3)}`,
  );
}

Probability of apples on day 0: 0.000
Probability of apples on day 1: 0.667
Probability of apples on day 2: 0.222
Probability of apples on day 3: 0.519
Probability of apples on day 4: 0.321
Probability of apples on day 5: 0.453
Probability of apples on day 6: 0.365
Probability of apples on day 7: 0.423
Probability of apples on day 8: 0.384
Probability of apples on day 9: 0.410

After 93 days, the probability of apples reaches a stable state, at least in 64-bit floating-point. And that stable state is the correct distribution: $\tfrac25$ apple and $\tfrac35$ banana.

Because the first samples are not in the correct distribution, it’s common to discard them. This is called burn-in.

The precise claim of the Metroplis algorithm is: the correct distribution is a stable distribution. To prove this, evaluate nextMealDist([2/5, 3/5]), and you’ll see that it’s [2/5, 3/5]. How many will eat Apple for the next meal? None of the $\tfrac25$ currently eating apples will eat apples tomorrow. Of the $\tfrac35$ currently eating bananas, $\tfrac23$ will eat apples tomorrow. for a total of $\tfrac35 \times \tfrac23 = \tfrac25$. And so the probability of $\tfrac25$ is maintained.

The example algorithm above was hard-coded to generate the stable state $\tfrac25$ and $\tfrac35$. But time passes, after which we’ve counted $3$ apple meals, and $6$ banana meals. Let’s update the algorithm to work with any counts:

// Our observed counts.
// We want to generate more meals in this proportion.
const A = 3; // Count of apples
const B = 6; // Count of bananas

function nextMeal(currentMeal: Meal): Meal {
  if (currentMeal === "Apple") {
    return "Banana";
  } else {
    if (Math.random() < A / B) {
      return "Apple";
    } else {
      return "Banana";
    }
  }
}

Let’s show that, for any counts $A$ and $B$, this converges to the correct probability distribution, $\tfrac{A}{A+B}$ and $\tfrac{B}{A+B}$.

\[ \begin{aligned} \texttt{numApples} &= \tfrac{A}{A+B} \\ \texttt{numBananas} &= \tfrac{B}{A+B} \\ \\ \texttt{a2a} &= 0 \\ \texttt{b2a} &= \texttt{numBananas} \times \tfrac{A}{B} \\ &= \tfrac{B}{A+B} \times \tfrac{A}{B} \\ &= \tfrac{BA}{(A+B)B} \\ &= \tfrac{A}{A+B} \\ \\ \texttt{numApplesTomorrow} &= \texttt{a2a} + \texttt{b2a} \\ &= 0 + \tfrac{A}{A+B} \\ &= \tfrac{A}{A+B} \\ \end{aligned} \]

So far, we’ve only observed Bob eating Apple or Banana. But then one day Bob’s in the cafeteria eating Chips! We need to handle more states. We can record our observed frequencies with a function f:

function f(meal: Meal): number {
  return {
    Apple: 3,
    Banana: 6,
    Chips: 1,
  }[meal];
}

The true Metropolis sample algorithm actually starts by proposing a new meal. Then it decides whether to change to that meal, or eat the current meal again. Here’s a proposal function that picks from possible meals with uniform probability:

function proposeMeal(): Meal {
  const meals: Meal[] = ["Apple", "Banana", "Chips"];
  const i = Math.floor(Math.random() * 3);
  return meals[i]!;
}

Then the true nextMeal function looks like:

function nextMeal(currentMeal: Meal): Meal {
  const proposedMeal = proposeMeal();

  const proposedMealFreq = f(proposedMeal);
  const currentMealFreq = f(currentMeal);

  // The key line!
  const transitionProb = Math.min(proposedMealFreq / currentMealFreq);

  if (Math.random() < transitionProb) {
    return proposedMeal;
  } else {
    return currentMeal;
  }
}

This works, but why does it work? The key point in the proof is that, for any two states $A$ and $B$ in the steady state, the probability mass transferred from $A$ to $B$ is the same as the probability mass transferred from $B$ to $A$.

Let’s prove that. If we’re in steady state, every state $S$ has mass proportional to $f(S)$. For simplicity, just say the mass at $S$ is $f(S)$. Without loss of generality, let’s assume $f(A) \leq f(B)$.

How much mass is transferred from state $A$ to $B$? With our uniform proposal function, $\tfrac1N^{th}$ of the mass at $A$ is proposed to move to $B$. The probability of accepting this proposal is $\text{min}(1,\tfrac{f(B)}{f(A)})$. Since $f(A) \leq f(B)$, this is $1$, i.e. the proposal is always accepted. So the mass moving from $A$ to $B$ is $\tfrac{f(A)}{N}$.

How much mass is transferred from state $B$ to $A$? Again, $\tfrac1N^{th}$ of the mass at $B$ is proposed to move to $A$. The probability of accepting this proposal is $\text{min}(1,\tfrac{f(A)}{f(B)})$. Since $f(A) \leq f(B)$, this is $\tfrac{f(A)}{f(B)}$. So the mass moving from $B$ to $A$ is $\tfrac{f(B)}{N} \times \tfrac{f(A)}{f(B)} = \tfrac{f(A)}{N}$.

The same amount of mass, $\tfrac{f(A)}{N}$, is transferred from $A$ to $B$ as from $B$ to $A$. This condition is called detailed balance, and it implies that we are in a steady state.

The proposeMeal function above just picks a meal uniformly at random. But we want to propose meals in proportion to their frequency. The only requirement is that the proposal function is symmetric: the probability of proposing $A$ from $B$ is the same as the probability of proposing $B$ from $A. (Try to prove that this results in detailed balance.)

So far, we’ve been using discrete states. But the Metropolis algorithm is most useful for continuous distributions. Here’s a weird distribution over the real numbers:

function sinFreq(x: number): number {
  if (0 < x && x < Math.PI * 2) {
    return Math.abs(Math.sin(x));
  }
  return 0;
}

We can sample from this distribution using the Metropolis algorithm in its full generality:

class Chain<State> {
  constructor(
    // Initial state
    private state: State,

    // Function to calculate the frequency of any state
    private f: (state: State) => number,

    // Function to propose a new state - must be symmetric
    private propose: (state: State) => State,

    // Number of initial samples to discard
    burnIn = 1000,
  ) {
    for (let i = 0; i < burnIn; i++) {
      this.sample();
    }
  }

  sample(): State {
    const current = this.state;
    const proposed = this.propose(current);
    const prob = Math.min(1, this.f(proposed) / this.f(current));
    const next = Math.random() < prob ? proposed : current;
    this.state = next;
    return current;
  }
}

function propose(currentState: number): number {
  return currentState + (Math.random() - 0.5);
}

const chain = new Chain(0.5, sinFreq, propose);

const numSamples = 1000000;

const buckets: Record<number, number> = {};
for (let i = 0; i < numSamples; i++) {
  const sample = chain.sample();
  const bucket = Math.floor(sample * 10);
  buckets[bucket] = (buckets[bucket] ?? 0) + 1;
}

for (const bucket in buckets) {
  buckets[bucket] /= numSamples;
}

for (const bucket in buckets) {
  const len = Math.floor(buckets[bucket]! * 1000);
  console.log("#".repeat(len));
}

Sure enough, here’s that weird lumpy distribution:

#
###
######
########
##########
#############
##############
################
##################
####################
######################
#######################
########################
########################
#########################
#########################
#########################
#########################
########################
#######################
######################
#####################
###################
##################
################
##############
############
#########
#######
####
##

##
#####
#######
#########
###########
##############
###############
#################
###################
#####################
######################
#######################
########################
########################
#########################
########################
########################
########################
#######################
######################
#####################
###################
#################
################
##############
############
##########
#######
#####
###