DEV Community: SEN LLC

A Math-Expression Parser in 250 Lines of JavaScript — Recursive Descent, Right-Associative ^, and -2^2 = -4

SEN LLC — Wed, 20 May 2026 22:54:34 +0000

Every "math evaluator in N lines" article either uses shunting-yard (Dijkstra's stack-based RPN converter) or hand-waves over the hard cases (-2^2, right associativity, error positions). This one uses recursive descent because the grammar and the code map 1-to-1, which makes the whole thing easier to read and write about. ~250 lines of JS, 36 unit tests, supports functions, variables, constants, parentheses, and reports errors with a column number and a caret.

🌐 Demo: https://sen.ltd/portfolio/expression-eval/
📦 GitHub: https://github.com/sen-ltd/expression-eval

Why recursive descent (not shunting-yard)

Both work. Shunting-yard is more compact (one for loop, two stacks). But for explaining what's happening, recursive descent wins:

Grammar ↔ code is 1-to-1. You can read the BNF and the implementation in parallel and they look the same.
Stack traces show the AST shape. When you're debugging "why is -2^2 returning 4 instead of -4", the call stack literally is the parse tree.
Error positions are natural. The "current token" is always explicit, so reporting "unexpected ) at column 6" falls out for free.

The grammar:

expression     := additive
additive       := multiplicative (('+' | '-') multiplicative)*
multiplicative := unary (('*' | '/' | '%') unary)*
unary          := ('-' | '+')? power
power          := atom ('^' unary)?
atom           := number | identifier | identifier '(' args? ')' | '(' expression ')'
args           := expression (',' expression)*

Operator precedence is encoded in the nesting depth. That's the whole magic. The deeper a rule is, the tighter it binds.

Trap 1: making `^` right-associative

2^3^2 should be 2^(3^2) = 2^9 = 512, not (2^3)^2 = 64.

For left-associative operators (+ - * / %) the parser builds a left-leaning tree with a while loop:

parseAdditive() {
  let left = this.parseMultiplicative();
  while (current is '+' or '-') {
    const right = this.parseMultiplicative();
    left = { type: "binop", op, left, right };       // accumulate on the LEFT
  }
  return left;
}

For the right-associative ^, switch from loop to recursion:

parsePower() {
  const base = this.parseAtom();
  if (current is '^') {
    consume();
    const exponent = this.parseUnary();              // RECURSE
    return { type: "binop", op: "^", left: base, right: exponent };
  }
  return base;
}

Recursion (not iteration) means the AST for 2^3^2 looks like:

binop ^
  number 2
  binop ^
    number 3
    number 2

DFS evaluation walks the inner 3^2 = 9 first, then 2^9 = 512.

Pin both sides:

test("^ is right-associative", () => {
  assert.equal(evaluateExpression("2^3^2"), 512);          // not 64
});

test("parse produces right-associative AST for '2^3^2'", () => {
  const ast = parse("2^3^2");
  assert.equal(ast.op, "^");
  assert.equal(ast.left.value, 2);
  assert.equal(ast.right.op, "^");
  assert.equal(ast.right.left.value, 3);
  assert.equal(ast.right.right.value, 2);
});

Trap 2: `-2^2 = -4` (unary minus binds LOOSER than `^`)

This is where calculator implementations disagree:

Tool	`-2^2`	Convention
WolframAlpha	`-4`	`^` > unary `-`
Python (`**`)	`-4`	`**` > unary `-`
Mathematica	`-4`	`^` > unary `-`
Excel	`4`	unary `-` > `^` ⚠
Google Sheets	`4`	unary `-` > `^` ⚠
Mathematical convention	`-4`	`^` > unary `-`

The math convention is -2^2 = -(2^2) = -4. Excel is the outlier (probably for backward compatibility with VisiCalc-era spreadsheets).

To get this right, ^ must bind tighter than unary -. That's achieved by the grammar nesting:

unary  := ('-' | '+')? power      ← unary sees '-' first, then drops down to power
power  := atom ('^' unary)?       ← but power's right-hand side can recurse to unary

Walking -2^2 through the parser:

parseUnary() sees -, consumes it, calls parsePower()
parsePower() calls parseAtom(), reads 2
Next token is ^, consume, recurse to parseUnary() for the exponent
The recursion reads 2
parsePower() returns { ^, 2, 2 }
parseUnary() wraps: { unary -, { ^, 2, 2 } } → evaluates to -(2^2) = -4 ✓

The reason the right-hand side of ^ recurses to unary (instead of parsePower() or parseAtom()) is to also allow negative exponents: 2^-3 = 1/8. Both rules — -2^2 = -4 and 2^-3 = 0.125 — fall out of the same single grammar choice.

test("^ binds tighter than * but unary minus binds looser than ^", () => {
  assert.equal(evaluateExpression("-2^2"), -4);     // -(2^2)
  assert.equal(evaluateExpression("(-2)^2"), 4);    // explicit parens win
  assert.equal(evaluateExpression("2 * 3^2"), 18);  // 2 * (3^2)
});

test("^ accepts unary minus on the exponent side", () => {
  assert.equal(evaluateExpression("2^-3"), 0.125);  // 2^(-3)
});

If a user wants 4, they write (-2)^2. The parens are non-optional and that's the right design.

Trap 3: numeric literal tokenisation order matters

Numbers seem easy, but the edge cases bite:

42 — integer
3.14 — float
.5 — leading-dot float
1e3 — scientific (= 1000)
1.5e-2 — negative exponent (= 0.015)
1e — error: exponent has no digits
1e+ — error: sign with no digits

The naïve "scan while character matches [0-9.eE+-]" approach breaks on 1+2 because the + between numbers gets pulled into the first literal.

The fix is to scan state by state in fixed order:

// 1. integer part (optional if dot follows)
while (i < length && isDigit(source[i])) i++;

// 2. fractional part (optional)
if (source[i] === ".") {
  i++;
  while (i < length && isDigit(source[i])) i++;
}

// 3. exponent (optional)
if (source[i] === "e" || source[i] === "E") {
  i++;
  if (source[i] === "+" || source[i] === "-") i++;
  const expStart = i;
  while (i < length && isDigit(source[i])) i++;
  if (i === expStart) throw new ExpressionError("exponent has no digits", start);
}

The exponent can have a sign, but after the sign you need at least one digit — 1e and 1e+ are invalid literals, not "1 followed by an identifier e". Once you've committed to scanning a number, partial exponents are syntax errors:

test("tokenize rejects exponent without digits", () => {
  assert.throws(() => tokenize("1e"), ExpressionError);
  assert.throws(() => tokenize("1e+"), ExpressionError);
});

Trap 4: error positions with a caret

"Syntax error" is hostile. Give the column and a visual pointer:

export class ExpressionError extends Error {
  constructor(message, position) {
    super(message);
    this.name = "ExpressionError";
    this.position = position;       // 0-indexed column
  }
}

Inside parseAtom(), throw with the token's position:

throw new ExpressionError(`unexpected "${t.value}"`, t.position);

In the UI, render a caret:

const caret = " ".repeat(Math.max(0, position)) + "^";
els.error.textContent = `${msg}\n${source}\n${caret}`;

The user sees:

parse: unexpected ")"
1 + + )
      ^

Pin the position in tests:

test("error positions are reported", () => {
  try {
    parse("1 + + )");
  } catch (e) {
    assert.ok(e instanceof ExpressionError);
    assert.equal(e.position, 6);   // the ")" column
    return;
  }
  assert.fail("expected ExpressionError");
});

Function calls as part of `atom`

When the parser sees an identifier, it peeks at the next token. If it's (, it's a function call:

parseAtom() {
  // ...
  if (t.type === "ident") {
    this.next();
    if (peek is "(") {
      this.next();
      const args = [];
      if (peek is not ")") {
        args.push(this.parseAdditive());
        while (peek is ",") {
          this.next();
          args.push(this.parseAdditive());
        }
      }
      consume(")");
      return { type: "call", name: t.value, args };
    }
    return { type: "ident", name: t.value };
  }
  // ...
}

Variadic functions (min, max, hypot) fall out for free — the args loop already accepts any count. The evaluator just spreads:

const FUNCTIONS = {
  min: (...xs) => Math.min(...xs),
  max: (...xs) => Math.max(...xs),
  hypot: (...xs) => Math.hypot(...xs),
  // ...
};

Variables override constants

CONSTANTS = { pi, e, tau, ... } is hard-coded, but user-supplied variables win:

case "ident": {
  if (Object.prototype.hasOwnProperty.call(variables, node.name)) {
    return Number(variables[node.name]);             // variables first
  }
  if (Object.prototype.hasOwnProperty.call(CONSTANTS, node.name)) {
    return CONSTANTS[node.name];
  }
  throw new ExpressionError(`undefined identifier "${node.name}"`, 0);
}

Two design choices worth calling out:

hasOwnProperty.call(obj, key) instead of key in obj to avoid prototype pollution — without hasOwnProperty, a user variable named __proto__ would be intercepted by the prototype chain.
User variables override constants because the user's intent is more specific. e = 10 makes sense as an override (e.g., "the elasticity coefficient is named e in my problem").

test("variables override constants if same name", () => {
  assert.equal(evaluateExpression("e + 1", { e: 10 }), 11);
});

Edge cases: division by zero, sqrt of negative

I let JavaScript's defaults through:

1 / 0 → Infinity (no throw)
sqrt(-1) → NaN
min(3, 1, 2) → 1

The display layer formats them:

export function formatResult(value) {
  if (Number.isNaN(value)) return "NaN";
  if (!Number.isFinite(value)) return value > 0 ? "∞" : "−∞";
  if (Number.isInteger(value) && Math.abs(value) < 1e15) return String(value);
  return String(Number(value.toPrecision(12)));
}

Number(value.toPrecision(12)) is the trick to make 0.1 + 0.2 = 0.3 display cleanly. toPrecision(12) rounds floats to 12 significant digits then Number() strips trailing zeros — so 0.30000000000000004 shows as 0.3.

TL;DR

Recursive descent beats shunting-yard for readability. Grammar maps 1-to-1 to code.
Right-associative ^ is recursion (not loop) on the operator's RHS.
-2^2 = -4 is the math convention; it falls out naturally if ^ (power) sits a level below unary minus in the grammar.
Numeric literals need state-machine scanning (integer → fractional → exponent), not a regex.
Errors carry a column and the UI renders a caret. Pin positions in tests.
Function calls are atom-level; variadic functions work for free.
Variables override constants with hasOwnProperty.call to avoid proto pollution.

Source: https://github.com/sen-ltd/expression-eval — MIT, ~250 lines of JS + 36 unit tests, zero dependencies, no build step.

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

Computing Moon Phase in 150 Lines of JavaScript — Julian Date, Synodic Month, and SVG Terminator

SEN LLC — Tue, 19 May 2026 22:43:04 +0000

"Wait, what phase is the moon in tonight?" — that question deserves a 150-line answer, not a Google search. The math is small: convert the date to Julian Date, divide the days since a reference new moon by the synodic month (29.530588853 days), take the fractional part. The interesting bit is drawing it: the moon's terminator (the line between lit and dark) is an elliptical arc when projected to a plane, which means the whole moon glyph can be expressed as two SVG arc commands. Here's how.

🌐 Demo: https://sen.ltd/portfolio/moon-phase/
📦 GitHub: https://github.com/sen-ltd/moon-phase

Architecture: pure module + DOM glue

The whole pure-math layer is one file:

import { moonPhase, terminatorPath, nextFullMoon } from "./phase.js";

const info = moonPhase(new Date());
// → { phase: 0.1141, age: 3.4, illumination: 0.123, name: "三日月", waxing: true }

const svgPath = terminatorPath(info.phase, 100);
// → "M 0 -100 A 100 100 0 0 1 0 100 A 80.9 100 0 0 0 0 -100 Z"

No DOM access in phase.js, which means node --test can run every test without jsdom. The UI script just imports the pure functions and writes the path string into an SVG element.

Julian Date: the astronomer's serial day number

Astronomical math hates the Gregorian calendar (variable month lengths, leap years, leap seconds…). Astronomers count time by Julian Date (JD) instead: a continuous count of days starting at noon UT on January 1, 4713 BC. One day = 1.0, time-of-day is the fractional part.

Convert Unix milliseconds to JD with one constant:

export const UNIX_EPOCH_JD = 2440587.5;       // JD of 1970-01-01 00:00 UTC
export const MS_PER_DAY = 86400000;

export function dateToJulian(date) {
  if (!(date instanceof Date) || Number.isNaN(date.getTime())) return null;
  return date.getTime() / MS_PER_DAY + UNIX_EPOCH_JD;
}

Why the .5? Julian Days start at noon, not midnight (so that astronomers' single observing nights don't cross a day boundary). Midnight UT is half a day past JD noon → +0.5.

Pin it:

test("dateToJulian matches the unix epoch as JD 2440587.5", () => {
  assert.equal(dateToJulian(new Date("1970-01-01T00:00:00Z")), 2440587.5);
});

Phase = (JD − reference new moon) / synodic month mod 1

The synodic month — new moon to new moon — averages 29.530588853 days.

For a reference new moon, the convention is JD 2451550.1 (2000-01-06 14:24 UTC). NASA's ephemeris confirms a new moon at that instant.

export const SYNODIC_MONTH = 29.530588853;
export const REFERENCE_NEW_MOON_JD = 2451550.1;

export function moonPhase(date) {
  const jd = dateToJulian(date);
  const daysSinceRef = jd - REFERENCE_NEW_MOON_JD;
  let phase = (daysSinceRef / SYNODIC_MONTH) % 1;
  if (phase < 0) phase += 1;
  // ...
}

phase ∈ [0, 1) where 0 = new, 0.25 = first quarter, 0.5 = full, 0.75 = last quarter.

The negative-modulo gotcha

JavaScript's % is truncated modulo, not mathematical modulo. If the dividend is negative, the result is negative:

-3 % 10   // → -3 in JS  (Python would say 7)

For dates before the reference new moon (early 2000), daysSinceRef is negative and so is the phase. The if (phase < 0) phase += 1 normalises it. Test the round-trip both forward and backward:

test("moonPhase at the reference new moon JD gives phase ≈ 0", () => {
  const d = julianToDate(REFERENCE_NEW_MOON_JD);
  const info = moonPhase(d);
  assert.ok(info.phase < 0.001 || info.phase > 0.999);
});

test("moonPhase one synodic month after the reference is again ~new", () => {
  const d = julianToDate(REFERENCE_NEW_MOON_JD + SYNODIC_MONTH);
  const info = moonPhase(d);
  assert.ok(info.phase < 0.001 || info.phase > 0.999);
});

Illumination = (1 − cos(2π × phase)) / 2

The lit fraction of the moon as seen from Earth is a linear transform of the cosine of the phase angle:

const illumination = (1 - Math.cos(2 * Math.PI * phase)) / 2;

phase	cos(2π × phase)	illumination
0 (new)	1	0
0.25 (first quarter)	0	0.5
0.5 (full)	-1	1
0.75 (last quarter)	0	0.5

First quarter and last quarter are indistinguishable from illumination alone. The waxing flag (phase < 0.5) is the other axis.

The terminator is an elliptical arc — two SVG arcs draw the entire lit area

This is the bit I found cute. The terminator — the boundary between the lit and dark sides of the moon — is a great circle on the lunar surface. Projected onto the plane of view, it becomes an ellipse. So the lit portion of the moon disc can be decomposed as:

A half-circle outer arc (the lit edge of the moon)
A half-ellipse inner arc (the terminator)

With semi-minor axis r × |cos(2π × phase)|:

export function terminatorPath(phase, radius) {
  if (phase < 0.001 || phase > 0.999) return "";              // new moon: nothing lit
  if (Math.abs(phase - 0.5) < 0.001) return circlePath(radius); // full moon: whole disc

  const cosPhase = Math.cos(2 * Math.PI * phase);
  const minor = Math.abs(cosPhase) * radius;
  const r = radius;
  const waxing = phase < 0.5;

  const outerSweep = waxing ? 1 : 0;
  const innerSweep = cosPhase < 0 ? 1 : 0;

  return [
    `M 0 ${-r}`,
    `A ${r} ${r} 0 0 ${outerSweep} 0 ${r}`,
    `A ${minor} ${r} 0 0 ${innerSweep} 0 ${-r}`,
    "Z",
  ].join(" ");
}

SVG arc sweep flag, demystified

A rx ry x-axis-rotation large-arc-flag sweep-flag x y. The sweep flag is the gotcha:

0 — arc traced counter-clockwise from start to end
1 — arc traced clockwise from start to end

For a half-circle from (0, -r) (top) to (0, r) (bottom):

waxing (lit on the right) → clockwise → sweep flag 1
waning (lit on the left) → counter-clockwise → sweep flag 0

Why cosPhase's sign tells you the inner sweep

The inner half-ellipse needs to either bulge into the lit side (crescent — terminator carves the lit area down to a sliver) or bulge into the dark side (gibbous — terminator pushes the lit area beyond half the disc).

cos(2π × phase) flips sign at exactly the right moments:

phase ∈ (0, 0.25) — waxing crescent — cos > 0 — ellipse on the lit side
phase ∈ (0.25, 0.5) — waxing gibbous — cos < 0 — ellipse bulges into dark
phase ∈ (0.5, 0.75) — waning gibbous — cos < 0 — ellipse bulges into dark
phase ∈ (0.75, 1) — waning crescent — cos > 0 — ellipse on the lit side

So innerSweep = cosPhase < 0 ? 1 : 0 covers all four cases in one line. Pin it:

test("terminatorPath gibbous bulges into dark side (sweep flag 1 on inner arc)", () => {
  const path = terminatorPath(0.4, 100);   // waxing gibbous
  const arcs = path.match(/A [^A]+/g);
  assert.equal(arcs.length, 2);
  assert.ok(arcs[1].includes("0 0 1 0"));   // inner arc sweep flag = 1
});

Next new/full moon: closed-form, no binary search

"When's the next full moon?" — the naive solution loops day-by-day looking for |phase - 0.5| < ε. But phase is a linear function of JD, so just invert it:

phase(jd) = ((jd - REF) / S) mod 1

jd at the next phase = target:
  REF + (target + k) × S   for the smallest integer k where this > startJd

export function nextPhase(date, target) {
  const startJd = dateToJulian(date);
  const offset = (startJd - REFERENCE_NEW_MOON_JD) / SYNODIC_MONTH;
  const k = Math.ceil(offset - target);
  const jd = REFERENCE_NEW_MOON_JD + (target + k) * SYNODIC_MONTH;
  return julianToDate(jd);
}

offset is "how many synodic months past the reference, including fractional position". Math.ceil(offset - target) picks the smallest integer k such that target + k > offset, i.e., the next time the phase wraps around to target.

Verify by checking that consecutive new moons are exactly one synodic month apart:

test("consecutive new moons are ~SYNODIC_MONTH days apart", () => {
  const first = nextNewMoon(new Date("2024-01-01T00:00:00Z"));
  const second = nextNewMoon(new Date(first.getTime() + 86400000));  // skip past first
  const diff = (second - first) / 86400000;
  assert.ok(Math.abs(diff - SYNODIC_MONTH) < 0.01);
});

Phase-name binning with a 1/16 offset

Mapping phase ∈ [0, 1) to one of 8 phase names (new, waxing crescent, first quarter, …) needs each canonical phase to land in the centre of its bin, not at a bin edge. Offset by 1/16:

const idx = Math.floor((p + 1 / 16) * 8) % 8;

phase = 0 (new) → (0 + 1/16) × 8 = 0.5 → floor → 0. phase = 0.25 (first quarter) → (0.25 + 1/16) × 8 = 2.5 → 2. Etc. Bin boundaries fall at 1/16, 3/16, 5/16, ..., equidistant from the canonical phases.

test("phaseName maps canonical phases to expected labels", () => {
  assert.equal(phaseName(0),    "新月");          // new
  assert.equal(phaseName(0.25), "上弦の月");     // first quarter
  assert.equal(phaseName(0.5),  "満月");          // full
  assert.equal(phaseName(0.75), "下弦の月");     // last quarter
});

test("phaseName handles wrap-around", () => {
  assert.equal(phaseName(1.0),   "新月");
  assert.equal(phaseName(-0.25), "下弦の月");
});

On accuracy — this is mean-phase, not true-phase

SYNODIC_MONTH = 29.530588853 is a mean value. The actual lunar month varies by about ±7 hours due to Earth's elliptical orbit (faster at perihelion) and the moon's orbital perturbations.

What that means for the code:

Casual use ("what phase is the moon in tonight?") — accurate enough
Exact new/full moon times — off by up to ±12 hours
Astronomical-grade work — use ELP-2000/82 or similar (hundreds of periodic terms)

This trade-off is called out in the README. For 150 lines, ±12 hours is the right amount of accuracy.

TL;DR

Julian Date decouples astronomy from calendar arithmetic. JD = unix_ms / 86400000 + 2440587.5.
Phase = ((JD - REF_NEW_MOON_JD) / SYNODIC_MONTH) mod 1. Watch JS's negative-modulo behaviour.
Illumination = (1 - cos(2π × phase)) / 2. Symmetric around full — track waxing/waning separately.
The terminator projects to an ellipse. The whole lit disc is two SVG arcs: a half-circle + a half-ellipse, with sweep flags determined by (waxing, cosPhase sign).
Next full/new moon has a closed-form. No bisection needed since phase is linear in JD.
Mean synodic month → ±12-hour accuracy for transition times. For sub-minute precision, switch to ELP-2000.

Source: https://github.com/sen-ltd/moon-phase — MIT, ~150 lines of JS + 30 unit tests, zero runtime dependencies, no build step.

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

A Browser IPv4 CIDR Calculator — Three JavaScript Gotchas (uint32 Coercion, /0 Shift Trap, RFC 3021 /31)

SEN LLC — Mon, 18 May 2026 22:57:52 +0000

Every Kubernetes / VPC / AWS person has had the moment where they need to split a /16 into its component /24s and ipcalc isn't on the laptop. This is the 350-line browser tool for that — paste a CIDR, see the network, broadcast, usable range, mask, wildcard, and the optional subdivision. The implementation is straightforward except for three JavaScript-specific traps the article walks through: uint32 coercion via >>> 0, the << 32 shift-amount mod-32 trap on /0, and RFC 3021's /31 exception (the one most older ipcalc versions get wrong).

🌐 Demo: https://sen.ltd/portfolio/cidr-calc/
📦 GitHub: https://github.com/sen-ltd/cidr-calc

Gotcha 1: bit ops produce signed int32, coerce with `>>> 0`

JavaScript numbers are IEEE-754 doubles. Bit operators internally treat the value as int32, do the op, and convert back. The conversion to int32 keeps the sign bit as a sign bit — so the moment your top bit is set, what should be a uint32 like 0xFFFFFFFF (4,294,967,295) becomes the int32 -1:

0xFFFFFFFF                 // → 4294967295 — looks unsigned, fine
0xFFFFFFFF << 8            // → -256 — top bits got dropped, the result is int32
(0xFFFFFFFF << 8) >>> 0    // → 4294967040 — explicit uint32 coercion

The >>> 0 (unsigned right-shift by zero) is the idiom for "force this back to uint32". The whole module disciplines itself to slap >>> 0 after every bitwise operation:

export function maskFor(prefix) {
  if (prefix === 0) return 0;
  return (0xFFFFFFFF << (32 - prefix)) >>> 0;  // ←
}

export function cidrInfo(ip, prefix) {
  const mask = maskFor(prefix);
  const network = (ip & mask) >>> 0;                       // ←
  const broadcast = (network | (~mask >>> 0)) >>> 0;       // ←
  // ...
}

Without the coercion, intToIp reads the high bits as negative shifts and the dotted-quad comes out garbage.

Gotcha 2: `<< 32` is `<< 0`, special-case /0

To build a netmask for prefix length N, the obvious code is 0xFFFFFFFF << (32 - N). For N = 32 you get << 0 which is fine. For N = 0 you get << 32 — which JavaScript silently treats as << 0 because the spec says the shift amount is taken modulo 32:

0xFFFFFFFF << 32  // → -1 (i.e. 0xFFFFFFFF, the same value)

So maskFor(0) written naïvely returns the same mask as /32, which is exactly wrong (/0 should be all-zeros, the empty mask). The fix is a one-line branch:

export function maskFor(prefix) {
  if (prefix === 0) return 0;
  return (0xFFFFFFFF << (32 - prefix)) >>> 0;
}

Pinned at both ends in the test:

test("maskFor handles the boundary prefixes 0 and 32", () => {
  assert.equal(maskFor(0), 0);              // ← without the branch, this is 0xFFFFFFFF
  assert.equal(maskFor(32), 0xFFFFFFFF);
  assert.equal(maskFor(24), 0xFFFFFF00);
});

Gotcha 3: RFC 3021 says /31 has TWO usable hosts

The classical "total - 2 = usable hosts" formula reserves the network and broadcast addresses. That's correct for /30 and wider, but produces wrong answers at the small end of the spectrum:

/32 is a single-host route (loopback, 127.0.0.1/32; Kubernetes Cluster IPs). network = broadcast = first = last, usable = 1.
/31 is a point-to-point link per RFC 3021 (March 2001). Both addresses are usable; no network/broadcast reserve. This is the standard for router-to-router links nowadays. Many older ipcalc versions report usable = 0 for /31 because they predate RFC 3021.

if (prefix === 32) {
  firstUsable = network;
  lastUsable = network;
  usable = 1;
} else if (prefix === 31) {
  firstUsable = network;
  lastUsable = broadcast;
  usable = 2;
} else {
  firstUsable = (network + 1) >>> 0;
  lastUsable = (broadcast - 1) >>> 0;
  usable = total - 2;
}

Tests for both special cases:

test("cidrInfo handles /31 per RFC 3021 (no network/broadcast reserve)", () => {
  const info = cidrInfo(ipToInt("10.0.0.0"), 31);
  assert.equal(info.total, 2);
  assert.equal(info.usable, 2);          // ← not 0
  assert.equal(intToIp(info.firstUsable), "10.0.0.0");
  assert.equal(intToIp(info.lastUsable),  "10.0.0.1");
});

test("cidrInfo handles /32 as a single host", () => {
  const info = cidrInfo(ipToInt("10.0.0.5"), 32);
  assert.equal(info.usable, 1);
  assert.equal(intToIp(info.firstUsable), "10.0.0.5");
});

Bonus: non-aligned input IPs are masked, not rejected

When a user pastes 10.0.5.7/24, the most sensible interpretation isn't "error: the host bits should be zero". It's "the user means the /24 that contains this address". Mask off the host bits inside cidrInfo:

const network = (ip & mask) >>> 0;     // ← drops the 7 bits below /24

Now 10.0.5.7/24 and 10.0.5.0/24 produce the same output. Pinned:

test("cidrInfo zeros the host bits of a non-aligned input IP", () => {
  const info = cidrInfo(ipToInt("10.0.5.7"), 24);
  assert.equal(intToIp(info.network),   "10.0.5.0");
  assert.equal(intToIp(info.broadcast), "10.0.5.255");
});

Subdivide with a truncate limit

Splitting /16 into /24 gives 256 subnets — fine to render. Splitting /8 into /24 gives 65,536; into /30 it's 4,194,304. Don't generate those eagerly:

export function subdivide(ip, prefix, newPrefix, limit = 256) {
  if (newPrefix <= prefix || newPrefix > 32) {
    throw new Error("newPrefix must be greater than current prefix and ≤ 32");
  }
  const mask = maskFor(prefix);
  const network = (ip & mask) >>> 0;
  const step = newPrefix === 32 ? 1 : (1 << (32 - newPrefix));
  const count = 1 << (newPrefix - prefix);
  const take = Math.min(count, limit);
  const subnets = [];
  for (let i = 0; i < take; i++) {
    subnets.push({ ip: (network + i * step) >>> 0, prefix: newPrefix });
  }
  return { subnets, total: count, truncated: count > take };
}

The UI reads truncated: true and shows "first N of M shown" so the user knows the list isn't exhaustive. The newPrefix === 32 special-case for step avoids another instance of the 1 << 0 = 1 vs 1 << 32 = 1 ambiguity I noted earlier.

Reject malformed input loudly

ipToInt returns null on any malformation so the UI can show an error rather than computing garbage:

export function ipToInt(ip) {
  if (typeof ip !== "string") return null;
  const parts = ip.split(".");
  if (parts.length !== 4) return null;
  let n = 0;
  for (const part of parts) {
    if (!/^\d+$/.test(part)) return null;     // rejects "+5", "-1", "  10", "1.5"
    const v = Number(part);
    if (v < 0 || v > 255) return null;
    n = (n * 256) + v;
  }
  return n >>> 0;
}

The /^\d+$/ test is stricter than Number(part) alone — Number(" 10") returns 10 (silently), Number("+5") returns 5, Number("1e3") returns 1000. None of those are valid octets. The regex catches them.

test("ipToInt rejects malformed input", () => {
  assert.equal(ipToInt("10.0.0"), null);          // wrong octet count
  assert.equal(ipToInt("10.0.0.0.0"), null);
  assert.equal(ipToInt("256.0.0.0"), null);       // octet > 255
  assert.equal(ipToInt("10.0.0.a"), null);
  assert.equal(ipToInt("10.0.0.-1"), null);       // sign char
  assert.equal(ipToInt(""), null);
});

TL;DR

>>> 0 after every bitwise op or your uint32 becomes a negative int32.
Special-case /0 in maskFor — JS's << operator applies its right-hand side mod 32, so << 32 and << 0 are the same.
/31 has 2 usable addresses (RFC 3021); /32 has 1. Older ipcalc versions report 0 for /31.
Mask host bits in cidrInfo, so a user pasting 10.0.5.7/24 lands on the right network.
Cap subdivide output so /8 → /30 doesn't try to materialise 4 M items into the DOM.
Regex-check octets in ipToInt — Number() silently accepts " 10", "+5", "1e3", and other surprises.

Source: https://github.com/sen-ltd/cidr-calc — MIT, ~350 lines of JS, 22 unit tests, no build step, no dependencies.

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

A Browser-Only Diary in 350 Lines — Month-Grid Math, Code-Point Character Counts, and Streak Boundaries

SEN LLC — Sun, 17 May 2026 22:57:34 +0000

A journaling app is one of the rare cases where the server side adds nothing: only the writer reads it, search load is tiny, no images required and 5 MB of localStorage covers decades. This is the 350-line browser-only diary that ended up working — a month calendar with click-to-pick, a textarea that saves on a 280 ms debounce, and a stat row showing streak + character count. The interesting parts are the 6×7 month grid math, code-point character counting for CJK + emoji, and the boundary conditions for the "current streak" counter.

🌐 Demo: https://sen.ltd/portfolio/diary-local/
📦 GitHub: https://github.com/sen-ltd/diary-local

Month calendar math: always 6 × 7

The 6 × 7 calendar grid is the standard layout — even months that only "need" five rows (February in non-leap years, or short months starting on a Sunday) get rendered as 42 cells to keep the row count stable across navigation. The math comes down to one offset:

export function monthGrid(year, month, todayIso = null, weekStart = 0) {
  const first = new Date(Date.UTC(year, month - 1, 1));
  const firstWeekday = first.getUTCDay();              // 0..6, Sun..Sat
  const offset = (firstWeekday - weekStart + 7) % 7;   // blank cells before day 1
  const start = new Date(Date.UTC(year, month - 1, 1 - offset));
  const today = todayIso || formatDate(new Date());
  const cells = [];
  for (let i = 0; i < 42; i++) {
    const d = new Date(start.getTime() + i * 86400_000);
    const iso = formatDate(d);
    cells.push({
      iso,
      day: d.getUTCDate(),
      inMonth: d.getUTCMonth() + 1 === month && d.getUTCFullYear() === year,
      isToday: iso === today,
    });
  }
  return { year, month, cells };
}

Four design decisions worth stating:

Everything in UTC. Local-time new Date(year, month, day) is full of tz-edge bugs at midnight. A diary cell is a date, not a time, so UTC is the right unit.
(firstWeekday - weekStart + 7) % 7 handles Sunday-first vs Monday-first locales in one expression.
42 cells, always. Some months need 5 rows; rendering them as 5 rows breaks the UI layout when you flip between months. Fix the grid at 6 × 7 and tag cells as inMonth: false for the spillovers.
Adding 86400000 ms is safe here because we never cross DST in a calendar-day calculation (we're working in UTC). Walking with setUTCDate(getUTCDate() + 1) would be equivalent but less compact.

The unit test pins the cell count:

test("monthGrid produces 42 cells and marks in-month vs adjacent days", () => {
  const grid = monthGrid(2026, 5, "2026-05-18");
  assert.equal(grid.cells.length, 42);
  const inMay = grid.cells.filter((c) => c.inMonth);
  assert.equal(inMay.length, 31);   // May has 31 days
});

Character count: code-points, not UTF-16 units

"💖".length === 2 in JavaScript, because String.length returns the number of UTF-16 code units. For a diary app — where the user wants to see "how much did I write today" — counting an emoji as 2 characters is just wrong.

Use the iteration protocol, which iterates code points:

export function characterCount(text) {
  if (typeof text !== "string") return 0;
  const trimmed = text.trim();
  if (!trimmed) return 0;
  const collapsed = trimmed.replace(/\s+/g, " ");
  return [...collapsed].length;     // ← code-point iteration
}

[...string] (and Array.from(string), and for...of over a string) all use the same iterator, which yields one element per code point. So [...'日本語'] is ["日", "本", "語"] (length 3), and [...'a💖b'] is ["a", "💖", "b"] (length 3, not 4).

Trim + collapse whitespace before counting because users almost always want the "actual content" count, not the count-including-trailing-newlines. \n\nhello\n\n should read as 5 characters, not 9.

test("characterCount counts code points, not UTF-16 units", () => {
  assert.equal(characterCount("日本語"), 3);
  assert.equal(characterCount("a💖b"), 3);
});

There's still an edge case for grapheme clusters (a ZWJ-joined family emoji like 👨‍👩‍👧 is one user-perceived character but several code points). The fully correct count uses Intl.Segmenter:

const seg = new Intl.Segmenter('en', { granularity: 'grapheme' });
const n = [...seg.segment(text)].length;

For a diary tool, I left it at code-point counting. The difference between "1 grapheme cluster" and "5 code points" doesn't materially affect the "how much did I write" feel.

Streak counter, three boundary conditions

currentStreak(dates, todayIso) returns the number of consecutive days, ending at today, that have an entry. The implementation is small but the boundary cases are easy to get wrong:

export function currentStreak(dates, todayIso) {
  const set = new Set(dates);
  if (!set.has(todayIso)) return 0;
  let n = 0;
  let cur = parseDate(todayIso);
  while (set.has(formatDate(cur))) {
    n++;
    cur = new Date(cur.getTime() - 86400_000);
  }
  return n;
}

The three load-bearing decisions:

No entry today → streak is 0. This is the Duolingo-style "you have to write today to keep the streak" semantics. The alternative is "streak is the run ending at the most recent entry", which would report 30 days even when the user hasn't written today. Both are defensible; I picked the stricter one because it's the version that motivates the writer to come back.
Any missing day breaks the chain. 5/15-5/17 + 5/18 (today) but 5/16 absent → streak is 2 (today + yesterday), not 4 and not 3.
Empty input → 0. Trivial but worth pinning in a test.

Tests for each:

test("currentStreak is zero when today has no entry", () => {
  assert.equal(currentStreak(["2026-05-15", "2026-05-16", "2026-05-17"], "2026-05-18"), 0);
});

test("currentStreak breaks at the first missing day", () => {
  // 5/16 is missing.
  assert.equal(currentStreak(["2026-05-15", "2026-05-17", "2026-05-18"], "2026-05-18"), 2);
});

The companion longestStreak(dates) is independent of today — it just finds the longest run anywhere. Useful for the "personal best" stat.

Storage: 5 MB is plenty without images

localStorage is specced at 5 MB per origin (Chrome / Safari / Firefox all sit at exactly this value). Rough sizing for a diary:

A daily entry averages ~300 characters → ~600 bytes UTF-16 / ~900 bytes UTF-8.
1825 days (5 years) × 600 bytes ≈ 1.1 MB.

→ Decades of writing fits in 5 MB as long as there are no images. Image attachments at 100-500 KB per shot would blow the quota in a few weeks. The app deliberately doesn't support images for this reason; if you want them, IndexedDB-with-Blob is the right tool.

The write path is wrapped in a try/catch for the QuotaExceededError that fires when (eventually) the limit is hit:

function saveEntry(iso, text) {
  try {
    if (text.trim().length === 0) {
      localStorage.removeItem(keyForDate(iso));   // empty → delete the key
    } else {
      localStorage.setItem(keyForDate(iso), text);
    }
    flashStatus("ok", "saved");
  } catch (err) {
    flashStatus("bad", `save failed: ${err.message ?? err}`);
  }
}

Two small ergonomics in there:

Empty text deletes the key instead of storing an empty string. This means readEntries(localStorage) doesn't have to filter empties later, and the quota usage stays at the actual data size.
Status flashes on every save (auto-clears after 1.8s) so the user knows their text is persisted without having to think about it.

Key namespace: `diary:YYYY-MM-DD`

localStorage is a flat key-value store across the entire origin. Anything sharing the origin sees your keys. The standard fix is a prefix:

export function keyForDate(iso)  { return "diary:" + iso; }
export function isDiaryKey(k)    { return k.startsWith("diary:"); }
export function dateFromKey(k)   { return isDiaryKey(k) ? k.slice("diary:".length) : null; }

Three things this buys:

Collision-free: another app on the same origin can use localStorage for its own purposes without conflicting.
Easy enumeration: for (let i = 0; i < localStorage.length; i++) + isDiaryKey(localStorage.key(i)) lists only diary entries.
Targeted clear: the "delete all" button removes only diary:* keys, not anything else on the origin. localStorage.clear() would be too aggressive.

readEntries(storageLike) accepts a Storage-like object (the standard length / key(i) / getItem(k) shape), which lets node --test drive it with a fake:

const storage = {
  get length() { return items.length; },
  key(i) { return items[i][0]; },
  getItem(k) {
    const hit = items.find((p) => p[0] === k);
    return hit ? hit[1] : null;
  },
};
const out = readEntries(storage);

localStorage doesn't exist in Node — passing the test through an interface keeps the pure layer testable without polyfills.

TL;DR

Month calendar = always 6 × 7 = 42 cells. The offset before day 1 is (firstWeekday - weekStart + 7) % 7.
Use [...string].length for character counting; never trust text.length if your content might include emoji or CJK.
Streak design has multiple defensible semantics; pick the "must write today" one if you want it to motivate. Test the boundary cases first.
5 MB of localStorage is plenty for a text-only diary spanning decades. Drop empty entries to save the cleanup loop later.
Prefix every key with the app's name (diary:YYYY-MM-DD). Targeted enumeration and targeted delete are both worth the 6 characters.

Source: https://github.com/sen-ltd/diary-local — MIT, ~350 lines of JS, 20 unit tests, no build step, zero runtime dependencies.

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

Plotting 5 Years of FX in the Browser — Frankfurter API + Hand-Rolled SVG Line Chart

SEN LLC — Sat, 16 May 2026 22:49:22 +0000

The "I want a USD/JPY 5-year chart on my page, no backend, no API key" target turns out to be reachable with one stack: Frankfurter (a free, CORS-enabled wrapper around the ECB's official reference rates) for the data, and a hand-rolled SVG <path> for the chart. ~350 lines of vanilla JS, 20 unit tests, ECB data updates daily. This walks through the four pieces that aren't obvious: choosing Frankfurter over the alternatives, pivoting the response into per-symbol series, the "nice numbers" algorithm for y-axis ticks, and the SVG y-flip via inverted range.

🌐 Demo: https://sen.ltd/portfolio/forex-history/
📦 GitHub: https://github.com/sen-ltd/forex-history

Why Frankfurter and not the other FX APIs

The free FX API space is smaller than you'd think once you require "browser-only, no server, no auth, CORS":

ECB direct (www.ecb.europa.eu): XML/CSV, no CORS — needs a server proxy.
Yahoo Finance: unofficial, no CORS, occasionally blocks bots.
Alpha Vantage: free tier capped at 25 requests / day, requires an API key.
OpenExchangeRates: 1000 requests / month free, requires an API key.
Frankfurter (api.frankfurter.dev): CORS, no auth, JSON, commercial use explicitly allowed.

Frankfurter is a small open-source project that re-serves the ECB's daily reference rates with permissive CORS headers. It updates after ~3 PM CET on ECB business days. Endpoint shape:

https://api.frankfurter.dev/v1/2021-01-01..2026-01-01?base=USD&symbols=JPY,EUR,GBP

For a "USD/JPY chart on a static page" use case, this is the answer.

Pivoting the response

Frankfurter's response is keyed by date, then by currency:

{
  "base": "USD",
  "rates": {
    "2021-01-04": { "JPY": 103.55, "EUR": 0.815, "GBP": 0.731 },
    "2021-01-05": { "JPY": 103.20, "EUR": 0.812, "GBP": 0.730 }
  }
}

Charts want per-symbol time series, so pivot it:

export function parseFrankfurterResponse(json) {
  if (!json || !json.rates) return null;
  const dates = Object.keys(json.rates).sort();
  const symbols = new Set();
  for (const d of dates) for (const s of Object.keys(json.rates[d])) symbols.add(s);
  const series = {};
  for (const sym of symbols) series[sym] = [];
  for (const date of dates) {
    for (const sym of symbols) {
      const v = json.rates[date]?.[sym];
      if (typeof v === "number" && Number.isFinite(v)) {
        series[sym].push({ date, value: v });
      }
    }
  }
  return { base: json.base, symbols: [...symbols].sort(), series };
}

Three details:

Object.keys(...).sort() because JavaScript object key order isn't reliable across engines for non-integer keys. Sorting explicitly makes the chart deterministic.
Number.isFinite(v) drops null (sometimes appears for holidays Frankfurter didn't fill in) and NaN. Without this, the line chart drops to y=0 wherever a hole exists.
Symbols are collected by union, not assumed from the first row, so a series that only appears on some dates still gets a (sparse) entry.

test("parseFrankfurterResponse drops missing values inside a row", () => {
  const json = { base: "USD", rates: {
    "2021-01-04": { JPY: 103.0 },
    "2021-01-05": { JPY: null, EUR: 0.815 },
  }};
  const out = parseFrankfurterResponse(json);
  assert.equal(out.series.JPY.length, 1);   // null dropped
  assert.equal(out.series.EUR.length, 1);
});

Y-axis ticks: the Heckbert "Nice Numbers" algorithm

A line chart with y-ticks at 127.34, 137.49, 147.65 is correct but unreadable. The classic fix is rounding to 1, 2, or 5 times a power of 10:

export function niceTicks(min, max, targetCount = 5) {
  if (min === max) return [min];
  if (min > max) [min, max] = [max, min];
  const step = niceStep((max - min) / targetCount);
  const first = Math.ceil(min / step) * step;
  const out = [];
  for (let v = first; v <= max + step * 1e-9; v += step) {
    out.push(Number(v.toFixed(10)));
  }
  return out;
}

function niceStep(rough) {
  const exp = Math.floor(Math.log10(rough));
  const f = rough / Math.pow(10, exp);
  let nice;
  if (f < 1.5) nice = 1;
  else if (f < 3) nice = 2;
  else if (f < 7) nice = 5;
  else nice = 10;
  return nice * Math.pow(10, exp);
}

Two boring-but-important corrections:

+ step * 1e-9 in the loop bound. Without it, floating-point accumulation drops the last tick. With max=100, step=20, 5 * 20 should be exactly 100, but it isn't — 0 + 20 + 20 + 20 + 20 + 20 ≈ 99.99999... in binary float. The epsilon makes 100 land on the tick.
Number(v.toFixed(10)) strips trailing zero artefacts. 0.1 + 0.2 in JavaScript is 0.30000000000000004; calling .toFixed(10) then Number(...) yields the clean 0.3.

test("niceTicks chooses 1/2/5 × 10^n step sizes", () => {
  assert.deepEqual(niceTicks(0, 10, 5), [0, 2, 4, 6, 8, 10]);
  assert.deepEqual(niceTicks(0, 100, 5), [0, 20, 40, 60, 80, 100]);
});

This is the same algorithm D3 uses internally for axis.tickArguments() defaults; it's the algorithm worth memorising if you're going to draw axis ticks more than once.

SVG `<path d>` from a series

The path is one string per series. Generate it in a unit-free way by parameterising the x/y scalers:

export function buildLinePath(series, xFn, yFn) {
  if (!series.length) return "";
  if (series.length === 1) {
    const { x, y } = xyOf(series[0], xFn, yFn);
    return `M ${fmt(x)} ${fmt(y)} l 0.01 0`;   // single-point stub
  }
  const first = xyOf(series[0], xFn, yFn);
  let d = `M ${fmt(first.x)} ${fmt(first.y)}`;
  for (let i = 1; i < series.length; i++) {
    const { x, y } = xyOf(series[i], xFn, yFn);
    d += ` L ${fmt(x)} ${fmt(y)}`;
  }
  return d;
}

function fmt(n) {
  return Number(n.toFixed(3)).toString();
}

Three calls worth making:

xFn / yFn are arguments, not closed-over globals. The caller composes them with linearScale(...); the path generator stays pure.
Single-point series get a l 0.01 0 stub — a 1/100 pixel relative line, so a stroke-linecap: round dot still shows up even when the user picks a date range with only one ECB business day in it.
3-decimal rounding. Sub-pixel precision isn't visible on any realistic display, and on 1,000-point series this saves ~15% bytes in the output SVG.

Inverted-range scale for the SVG y-flip

SVG's y axis grows downward (DOM convention). Charts want y to grow upward. The simple fix is to feed the y scaler an inverted range:

// Top of plot area gets the max value; bottom gets the min.
const yFn = (v) => linearScale(v, yMin, yMax, PAD_TOP + PLOT_H, PAD_TOP);

For this to work, linearScale must not assume rangeMin < rangeMax:

export function linearScale(value, domainMin, domainMax, rangeMin, rangeMax) {
  if (domainMax === domainMin) return (rangeMin + rangeMax) / 2;
  const t = (value - domainMin) / (domainMax - domainMin);
  return rangeMin + t * (rangeMax - rangeMin);
}

test("linearScale handles inverted ranges (for y-axis flipping)", () => {
  assert.equal(linearScale(0,  0, 10, 100, 0), 100);
  assert.equal(linearScale(10, 0, 10, 100, 0), 0);
});

That's the entire y-flip. No separate invert flag, no special-case math.

The unavoidable multi-currency scale problem

Look at the screenshot: USD/JPY trends from 109 to 158, while USD/EUR sits at 0.8 and USD/GBP at 0.7. On a shared y-axis the EUR/GBP/CNY lines look almost flat — the JPY's 50-unit movement dominates the 0.1-unit movements of the others.

Two standard fixes:

Index to 100: rescale each series so its first point = 100. The chart shows percent change and every series sits in the same range.
Dual y-axes: a left axis for the dominant series, a right axis for the others. Bloomberg-style. Confuses some readers; clear once you label it.

I shipped the naive version because the article is about getting the data and drawing it; the index-to-100 option is a linearScale away if you want it.

TL;DR

Frankfurter (https://api.frankfurter.dev/) is the right free FX API for browser-only use: CORS, no auth, JSON, ECB data.
The response is date → currency → rate; pivot to currency → [{date, value}] for charting.
Drop null / non-finite values during the pivot or your line chart will dive to zero on ECB holidays.
Use Heckbert's 1/2/5 × 10^n algorithm for y-axis ticks; remember the floating-point epsilon at the loop bound and the toFixed(10) strip for clean labels.
Pass xFn / yFn into the path generator so it stays unit-free; round to 3 decimals for compact SVG.
Flip the SVG y axis by passing an inverted range to linearScale — no special-case code needed.

Source: https://github.com/sen-ltd/forex-history — MIT, ~350 lines of JS, 20 unit tests, no build step, zero runtime dependencies.

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

Reimplementing path-to-regexp in 100 Lines — Why /users/:id? Almost Never Works the Way You Expect

SEN LLC — Fri, 15 May 2026 22:57:58 +0000

app.get('/users/:id', ...) is one of those one-liners every Node developer types a hundred times before wondering what it actually does. The answer: Express hands the string to path-to-regexp, which compiles it to /^\/users\/([^/]+)$/. That whole pipeline fits in 100 lines of vanilla JS. Reimplementing it surfaces the subtle bugs you've probably hit at least once — the :id? modifier swallowing the leading slash, the regex-meta character that wasn't escaped, the inline regex with an unbalanced paren. The result is a browser-only Express route tester with 23 unit tests pinning the boundaries.

🌐 Demo: https://sen.ltd/portfolio/regex-route/
📦 GitHub: https://github.com/sen-ltd/regex-route

Why rewrite path-to-regexp

The standard answer is "you don't need to, just use Express." That's correct until the day you hit one of these:

/users/:id matches /users/42/extra in your mental model, but it actually doesn't — :id is exactly one segment.
/users/:id? doesn't match /users in your test, because you forgot that the optional ? modifier has to absorb the leading slash too.
You upgraded Express 4 → 5, which switched from path-to-regexp@6 to @7, and now /users/:id parses differently in a couple of subtle cases.

Walking through the parser by hand makes all three problems go away. And the parser is small enough to actually finish.

A 4-state direct-style parser

The supported grammar:

Syntax	Meaning
`/foo/bar`	Static segments; regex meta chars are escaped.
`/users/:id`	Named param; matches one non-slash segment.
`/users/:id?`	Named param, optional. The leading `/` is absorbed too.
`/users/:id(\d+)`	Named param constrained to an inline regex.
`/files/*`	Wildcard; captures the rest of the path.

Walking the pattern character-by-character:

while (i < pattern.length) {
  const ch = pattern[i];

  if (ch === ":") {
    // Named param: ':name', ':name(regex)', ':name?', or combinations.
    // ...
  } else if (ch === "*") {
    keys.push({ name: "wild", modifier: "*", custom: null });
    re += "(.*)";
    i++;
  } else if (REGEX_META.includes(ch)) {
    // Static text containing a regex meta char — escape it so the
    // generated regex still matches literally.
    re += "\\" + ch;
    i++;
  } else if (ch === "/") {
    re += "\\/";    // optional for engine, but makes the printed regex copy/pasteable
    i++;
  } else {
    re += ch;
    i++;
  }
}

Two points worth calling out:

Always escape regex meta chars in static text. /foo.bar without escaping the . would silently match /fooXbar. The article version of this bug usually shows up months later when an unexpected URL hits an unexpected handler.
Always write \/, not / in the generated regex. It's identical to the engine, but it lets me print the regex to the UI status line and have it be copy-pasteable into a new new RegExp(...) call.

The `:id?` optional-segment trap

The naïve implementation makes /users/:id? into ^\/users\/([^/]+)?$. That matches /users/ (with trailing slash) but not /users. Almost certainly not what the user wanted.

The fix: when you see the ? modifier, walk back and absorb the preceding \/ into the optional group:

if (modifier === "?") {
  if (re.endsWith("\\/")) {
    re = re.slice(0, -2) + `(?:\\/(${seg}))?`;
  } else {
    re += `(${seg})?`;
  }
}

Now /users/:id? becomes ^\/users(?:\/([^/]+))?$, which correctly matches both /users and /users/42. Pinned in the tests:

test("compilePath: :param? makes the segment + leading slash optional", () => {
  const c = compilePath("/users/:id?");
  assert.equal(matchPath(c, "/users").params.id, null);
  assert.equal(matchPath(c, "/users/42").params.id, "42");
});

This single mistake is responsible for a non-trivial fraction of "why isn't my optional route working" Stack Overflow questions about Express.

Inline regex with paren balance

:id(\d+) is a parameter constrained to a custom regex. Naïve indexOf(")") breaks the moment someone writes a nested group like :date((\d{4})-(\d{2})). Use a depth counter and respect backslash escapes:

export function findMatchingParen(s, start) {
  if (s[start] !== "(") return -1;
  let depth = 0;
  for (let i = start; i < s.length; i++) {
    if (s[i] === "\\") { i++; continue; }   // skip the escaped char
    if (s[i] === "(") depth++;
    else if (s[i] === ")") {
      depth--;
      if (depth === 0) return i;
    }
  }
  return -1;
}

The if (s[i] === "\\") { i++; continue; } line is the one that gets forgotten: without it, :id(\\)) would be parsed as ending at the \) instead of the real close. Tested:

test("findMatchingParen respects backslash escapes", () => {
  // (\)) — string length 4. Inner \) is escaped; the trailing ) closes.
  assert.equal(findMatchingParen("(\\))", 0), 3);
});

Stripping query and hash before matching

/users/42?include=author should match /users/:id because Express does. But path-to-regexp itself doesn't strip the query — Express does that in middleware. For a standalone tester, we have to do the stripping ourselves before running the match:

const hashPos = url.indexOf("#");
const noHash = hashPos === -1 ? url : url.slice(0, hashPos);
const qPos = noHash.indexOf("?");
const pathPart = qPos === -1 ? noHash : noHash.slice(0, qPos);
const query = qPos === -1 ? "" : noHash.slice(qPos + 1);

The stripped query goes into the result object so the UI can show "query: ?include=author" as a separate line, without affecting whether the match succeeded.

URL-decoding captured values, safely

/users/%E5%B1%B1%E7%94%B0 is the percent-encoding for /users/山田. The captured group is the raw %E5%B1%B1%E7%94%B0, and the user wants to see the kanji. Run it through decodeURIComponent — but guard against malformed input:

try {
  params[key.name] = decodeURIComponent(raw);
} catch {
  // Lone '%' or other malformed percent-encoding raises URIError.
  // Don't fail the match; surface the raw value instead.
  params[key.name] = raw;
}

decodeURIComponent throws URIError on invalid sequences. Without the catch, anyone who pastes /users/foo%bar into the URL field would see the entire results table blow up.

test("matchPath: malformed percent-encoding returns the raw value", () => {
  const c = compilePath("/users/:name");
  const r = matchPath(c, "/users/foo%bar");
  assert.ok(r !== null);
  assert.ok(typeof r.params.name === "string");
});

The full API in five exports

// route.js (~100 lines)
export class CompileError extends Error { /* with pos */ }
export function findMatchingParen(s, start) { /* depth-tracking */ }
export function compilePath(pattern) { /* → {regex, keys, source, generated} */ }
export function matchPath(compiled, url) { /* → {url, pathPart, query, params} | null */ }
export function testRoute(pattern, url) { /* compile + match shortcut, no throws */ }

script.js wires the DOM: pattern input → debounce 80 ms → compile → re-render the results table. URL textarea → split on newline → match each line. The output is a side-by-side educational table that makes the route → regex mapping obvious.

TL;DR

The static parts of route patterns need regex-meta escaping. /foo.bar matching /fooXbar is a classic silent bug.
:id? has to absorb the leading slash into the optional group, otherwise /users won't match.
Inline-regex paren balance needs a depth counter and backslash-escape handling.
Strip ?query and #fragment before matching; surface the query separately.
Always wrap decodeURIComponent in a try/catch — malformed percent-encoding throws.

Source: https://github.com/sen-ltd/regex-route — MIT, ~350 lines of JS, 23 unit tests, no build step, zero runtime dependencies.

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

Visualizing A* One Node at a Time — The Tie-Break and Corner-Cut Decisions That Decide How the Demo Looks

SEN LLC — Fri, 15 May 2026 00:38:24 +0000

A* is one of those algorithms that's 20 lines of pseudocode in any textbook and then takes a long afternoon to render nicely. Two design decisions sit between "works" and "looks good": the priority queue's tie-break order (without it the explored area is asymmetric for symmetric maps) and 8-connected corner-cut blocking (without it the path slides diagonally through wall corners). This is the 500-line browser visualization that gets both right, with 23 unit tests pinning the boundaries.

🌐 Demo: https://sen.ltd/portfolio/a-star-viz/
📦 GitHub: https://github.com/sen-ltd/a-star-viz

Rewrite A* to expose its state

A textbook A* runs an internal while loop and returns once. To animate it, you need to be able to advance one node at a time and re-render the state after each step. The shape that ended up working:

export function createState({ grid, start, end, heuristic = manhattan, allowDiagonal = false }) {
  const open = new MinHeap();
  const gScore = new Map();
  const fScore = new Map();
  const cameFrom = new Map();
  const closed = new Set();
  const sk = keyOf(start);
  gScore.set(sk, 0);
  fScore.set(sk, heuristic(start, end));
  open.push(start, fScore.get(sk));
  return {
    grid, start, end, heuristic, allowDiagonal,
    open, gScore, fScore, cameFrom, closed,
    status: "running", current: null, path: null, expansions: 0,
  };
}

export function step(state) {
  if (state.status !== "running") return state;
  let cur;
  do {
    cur = state.open.pop();
    if (!cur) { state.status = "no-path"; return state; }
  } while (state.closed.has(keyOf(cur)));

  state.current = cur;
  state.expansions++;
  if (cur.x === state.end.x && cur.y === state.end.y) {
    state.status = "done";
    state.path = reconstructPath(state.cameFrom, cur);
    return state;
  }
  state.closed.add(keyOf(cur));

  const curG = state.gScore.get(keyOf(cur)) ?? Infinity;
  for (const n of neighbors(cur, state.grid, { allowDiagonal: state.allowDiagonal })) {
    if (state.closed.has(keyOf(n))) continue;
    const tentativeG = curG + moveCost(cur, n);
    const nk = keyOf(n);
    if (tentativeG < (state.gScore.get(nk) ?? Infinity)) {
      state.cameFrom.set(nk, cur);
      state.gScore.set(nk, tentativeG);
      const f = tentativeG + state.heuristic(n, state.end);
      state.fScore.set(nk, f);
      state.open.push(n, f);
    }
  }
  return state;
}

The do { pop } while (closed.has) loop handles stale heap entries — A* without decrease-key inserts duplicate entries on improvement, and the high-priority copies eventually get popped while in the closed set. Skip them.

Tie-breaks make symmetric maps look symmetric

A* uses a min-heap on fScore. Most heap implementations leave the order of equal-priority items unspecified. On symmetric maps this is visually awful: the search prefers one side over the other for no apparent reason, the demo loses its educational appeal.

Add an insertion counter as a tie-break:

export class MinHeap {
  constructor() {
    this.data = [];
    this._counter = 0;
  }
  push(value, priority) {
    this.data.push({ value, priority, order: this._counter++ });
    this._bubbleUp(this.data.length - 1);
  }
  _cmp(i, j) {
    if (this.data[i].priority !== this.data[j].priority) {
      return this.data[i].priority - this.data[j].priority;
    }
    return this.data[i].order - this.data[j].order;  // FIFO
  }
  // ... _bubbleUp / _bubbleDown / pop / peek / size
}

Now equal-priority items pop in insertion order. The search expands the two sides of a symmetric corridor at the same rate.

test("MinHeap breaks ties FIFO via insertion counter", () => {
  const h = new MinHeap();
  h.push("first",  5);
  h.push("second", 5);
  h.push("third",  5);
  assert.equal(h.pop(), "first");
  assert.equal(h.pop(), "second");
  assert.equal(h.pop(), "third");
});

(Some demo authors take this the other direction and use a negative insertion-order tie-break, which biases toward depth-first behaviour and gets to the goal faster on open maps. Either is defensible — FIFO is more "textbook".)

8-connected corner-cut blocking

Allow diagonal moves and the obvious bug shows up: A* finds paths that squeeze diagonally through wall corners. Concretely, walls at (2,1) and (1,2) should not allow a diagonal move from (1,1) to (2,2) — but a naive 8-neighbor enumeration says yes.

   x=0  x=1  x=2
y=0 .    .    .
y=1 .    @    W   ← (1,1) is where the agent stands, (2,1) is wall
y=2 .    W    .   ← (1,2) is wall
                  ← (2,2) reachable diagonally? Only if cutCorners=true

The fix is a check at neighbor enumeration time:

export function neighbors(cell, grid, { allowDiagonal = false, cutCorners = false } = {}) {
  const out = [];
  const dirs = allowDiagonal
    ? [[1,0],[-1,0],[0,1],[0,-1], [1,1],[1,-1],[-1,1],[-1,-1]]
    : [[1,0],[-1,0],[0,1],[0,-1]];
  for (const [dx, dy] of dirs) {
    const n = { x: cell.x + dx, y: cell.y + dy };
    if (!inBounds(n, grid) || isWall(n, grid)) continue;
    if (dx !== 0 && dy !== 0 && !cutCorners) {
      const a = isWall({ x: cell.x + dx, y: cell.y }, grid);
      const b = isWall({ x: cell.x, y: cell.y + dy }, grid);
      if (a || b) continue;
    }
    out.push(n);
  }
  return out;
}

cutCorners: true opts back in, matching the lazy game-engine behaviour some people prefer. Defaulting to false matches "what humans expect when they see a wall corner".

test("neighbors blocks diagonal corner-squeezing by default", () => {
  const g = grid(3, 3, [[2, 1], [1, 2]]);
  const ns = neighbors({ x: 1, y: 1 }, g, { allowDiagonal: true });
  assert.ok(!ns.some((n) => n.x === 2 && n.y === 2));
});

The heuristic comparison sells the demo

Three heuristics, side-by-side in the demo:

Manhattan (|dx| + |dy|): optimal admissible for 4-connected, smallest expansions count.
Chebyshev (max(|dx|, |dy|)): optimal for 8-connected with uniform cost.
Euclidean (√(dx² + dy²)): always admissible but underestimates the actual grid cost, so it explores more nodes than the others would.

The demo's expansions counter changes dramatically when you flip between them. On a 5×5 grid from (0,0) to (4,4), 4-connected Manhattan gives a 9-node path; 8-connected Chebyshev gives a 5-node path — 4 diagonal moves plus the start. The test pins it:

test("A* with chebyshev + diagonals finds shorter diagonal paths", () => {
  const g = grid(5, 5);
  const sM = createState({ grid: g, start: {x:0,y:0}, end: {x:4,y:4}, heuristic: manhattan });
  runToCompletion(sM);
  assert.equal(sM.path.length, 9);

  const sC = createState({ grid: g, start: {x:0,y:0}, end: {x:4,y:4}, heuristic: chebyshev, allowDiagonal: true });
  runToCompletion(sC);
  assert.equal(sC.path.length, 5);
});

The Canvas footgun: width assignment clears the buffer

DPR-aware Canvas setup:

function fitCanvas() {
  const dpr = Math.max(1, window.devicePixelRatio || 1);
  els.canvas.width = GRID_W * CELL * dpr;
  els.canvas.height = GRID_H * CELL * dpr;
  els.canvas.style.aspectRatio = `${GRID_W * CELL} / ${GRID_H * CELL}`;
  const ctx = els.canvas.getContext("2d");
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
}

The thing the HTML spec doesn't shout about but bites every Canvas tutorial: assigning canvas.width clears the buffer to fully-transparent black. It's specced behaviour, not a bug, but it means fitCanvas() is destructive — anything previously drawn vanishes.

In my first version I wired window.addEventListener("resize", fitCanvas) and called it a day. The demo worked until the user resized the window (or until Playwright's screenshot triggered a layout pass), at which point the canvas would suddenly go blank.

Fix:

window.addEventListener("resize", () => {
  fitCanvas();
  draw();   // <-- without this, the canvas is transparent after resize
});

This isn't catchable by unit tests — it's a Canvas + browser-event interaction that only shows up in the wild. The lesson: whenever you assign canvas.width, you've thrown away the picture. Re-paint.

TL;DR

A* with externally-visible state (open / closed / gScore / cameFrom) makes a clean visualization API; render after every step().
FIFO tie-breaks in the min-heap make symmetric maps look symmetric.
8-connected neighbor enumeration should default to blocking corner cuts — that matches user expectation and most game engines.
The heuristic-swap UX is what sells the demo educationally; the expansions counter changes dramatically.
canvas.width = ... clears the buffer. Always pair fitCanvas() with draw() on resize.

Source: https://github.com/sen-ltd/a-star-viz — MIT, ~500 lines of JS, 23 unit tests, no build step, no dependencies.

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

A 350-Line GLSL Shader Playground in the Browser — WebGL Init, Line-Number-Aware Errors, and URL-Hash Sharing

SEN LLC — Thu, 14 May 2026 00:11:54 +0000

Sometimes you want to try a shader without spinning up Shadertoy, without a build step, without anything. Just a textarea, a canvas, and a refresh-while-you-type loop. This is that page: ~350 lines of vanilla JS, a fixed full-screen-quad vertex shader, and a fragment shader you edit live. Compile errors land back in the UI with line numbers; the URL hash round-trips your source so links shared on Twitter just work.

🌐 Demo: https://sen.ltd/portfolio/shader-playground/
📦 GitHub: https://github.com/sen-ltd/shader-playground

What it does

The vertex shader is fixed — a full-screen quad as two triangles.
The fragment shader is what the user edits. The page runs gl.compileShader(...) 220 ms after each keystroke (debounced) and swaps the program if compilation succeeds.
Three uniforms are auto-bound: u_resolution (drawing buffer size), u_mouse (cursor in WebGL pixel coords), u_time (seconds since page load).
Compile errors land in the UI with line numbers, parsed from the driver's info log.
The shader source round-trips through location.hash as base64url, so sharing a permalink works the same in any browser.

That's it. The rest of this post is the small list of footguns the implementation hits.

WebGL context — two flags worth setting

const gl =
  els.canvas.getContext("webgl", {
    antialias: true,
    premultipliedAlpha: false,
  }) ||
  els.canvas.getContext("experimental-webgl");

Two flags that almost always come up:

premultipliedAlpha: false is the difference between "canvas is an opaque drawing surface" and "canvas blends into the DOM behind it". If you forget this and your fragment shader writes gl_FragColor = vec4(rgb, 1.0), you'll still see the page background bleeding through on some browsers — and you'll spend ten minutes wondering why. Setting it explicitly removes the surprise.
antialias: true is the default, but make it explicit so you remember it's there. MSAA on the swapchain makes shape edges look clean without any per-fragment MSAA logic.

The experimental-webgl fallback is mostly historical at this point (Android Chrome 2014-ish, IE11). Costs one extra || to keep it, so I do.

Parsing the compile-error log

Drivers (mostly) emit lines like:

ERROR: 0:5: 'foo' : undeclared identifier
ERROR: 0:12: 'bar' : assignment to const variable
WARNING: 0:3: implicit conversion

0 is the file index, almost always zero for a single source string. 5 is the source line, and the rest is the human-readable message.

const ERROR_RE =
  /^\s*(ERROR|WARNING)\s*:\s*(\d+)\s*:\s*(\d+)\s*:\s*(.+?)\s*$/i;

export function parseShaderError(infoLog) {
  if (!infoLog) return [];
  const out = [];
  for (const rawLine of infoLog.split(/\r?\n/)) {
    const line = rawLine.trim();
    if (!line) continue;
    const m = line.match(ERROR_RE);
    if (m) {
      out.push({
        severity: m[1].toUpperCase() === "ERROR" ? "error" : "warning",
        line: Number(m[3]),
        message: m[4],
      });
    } else {
      // Mali / Adreno often prepend a free-form summary line. Don't drop it.
      out.push({ severity: "error", line: 0, message: line });
    }
  }
  return out;
}

Two small but load-bearing details:

Case-insensitive (ERROR|WARNING). Some drivers ship "Error" with a capital E only. The i flag handles both.
Catch the free-form summary lines. Some implementations prepend Fragment shader failed to compile with the following errors: ahead of the structured rows. If the regex doesn't match, we still surface the line — tagged with line: 0 so the UI shows it but doesn't pretend it points at the user's source.

The unit test pins both behaviours:

test("parseShaderError surfaces free-form lines as line-0 errors", () => {
  const log =
    "Fragment shader failed to compile with the following errors:\n" +
    "ERROR: 0:5: 'foo' : undeclared identifier\n";
  const out = parseShaderError(log);
  assert.equal(out.length, 2);
  assert.equal(out[0].line, 0);
  assert.equal(out[1].line, 5);
});

Uniform binding — guard the `null`

After a successful link, look up the uniform locations once:

state.uniformLocs = {
  u_resolution: gl.getUniformLocation(program, "u_resolution"),
  u_mouse:      gl.getUniformLocation(program, "u_mouse"),
  u_time:       gl.getUniformLocation(program, "u_time"),
};

In the rAF loop:

const { u_resolution, u_mouse, u_time } = state.uniformLocs;
if (u_resolution) gl.uniform2f(u_resolution, gl.drawingBufferWidth, gl.drawingBufferHeight);
if (u_mouse)      gl.uniform2f(u_mouse,  state.mouse[0] * gl.drawingBufferWidth, state.mouse[1] * gl.drawingBufferHeight);
if (u_time)       gl.uniform1f(u_time,   (performance.now() - state.startTime) / 1000);

The if (u_X) checks matter. getUniformLocation returns null when the named uniform doesn't exist in the linked program — which happens whenever the user deletes the corresponding uniform vec2 u_mouse; line, or whenever the compiler optimises it out for being unused. Calling gl.uniform2f(null, ...) is an INVALID_OPERATION and pollutes the console, but doesn't break anything else.

Note also gl.drawingBufferWidth / gl.drawingBufferHeight rather than the CSS pixel dimensions. The drawing buffer is what the fragment shader sees in gl_FragCoord.xy, and on retina displays the two differ by devicePixelRatio.

Mouse coords are WebGL-flipped

MouseEvent.clientY increases downward (CSS / DOM convention). gl_FragCoord.y increases upward (OpenGL / WebGL convention). Forgetting to flip leaves your radial-wave-from-the-cursor effect inverted on the vertical axis.

function onMouseMove(e) {
  const rect = els.canvas.getBoundingClientRect();
  state.mouse[0] = (e.clientX - rect.left) / rect.width;
  state.mouse[1] = 1 - (e.clientY - rect.top) / rect.height;  // flip
}

I normalise to 0..1 here and multiply by drawingBufferWidth/Height at uniform-update time, so the math doesn't have to know about the DPR.

URL-hash sharing

A shader source becomes a permalink:

export function encodeShaderToHash(source) {
  const bytes = new TextEncoder().encode(source);
  let bin = "";
  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
  return btoa(bin)
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}

export function decodeShaderFromHash(hash) {
  if (!hash) return "";
  let b64 = String(hash).replace(/-/g, "+").replace(/_/g, "/");
  while (b64.length % 4) b64 += "=";
  let bin;
  try { bin = atob(b64); } catch { return null; }
  const bytes = new Uint8Array(bin.length);
  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
  try {
    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
  } catch { return null; }
}

UTF-8 round-trip, so comments in any language survive intact:

test("encode/decode round-trips UTF-8 (comments in Japanese)", () => {
  const src = "// シェーダのコメント\nvoid main() { gl_FragColor = vec4(1.0); }";
  const hash = encodeShaderToHash(src);
  assert.equal(decodeShaderFromHash(hash), src);
});

URL safety: + / = are stripped or replaced with - _ so the hash can drop into any URL parser. The decoder restores the padding before calling atob so the original ASCII bytes come back.

I did not gzip-compress the source before encoding. The page is aimed at hand-written shaders in the 30-50-line range — 1-2 KB raw, ~1.4-2.7 KB base64. Well under the 2 MB URL limit Chrome / Firefox tolerate in practice. If you need to share bigger work, layering CompressionStream (browser-native gzip) on top of the base64 wrapper is a four-line addition; the API just becomes async.

"Did the source actually change?"

textarea's input event fires on every arrow-key navigation, every cursor blink that touches the field, every paste-and-undo. Recompiling on each event is wasteful. Fold whitespace and CRLF first:

export function shouldRecompile(prev, next) {
  if (prev === next) return false;
  const np = String(prev || "").replace(/\r\n/g, "\n").trimEnd();
  const nn = String(next || "").replace(/\r\n/g, "\n").trimEnd();
  return np !== nn;
}

CRLF → LF: pasting from a Windows editor flips line endings without the user noticing. The shader source is byte-for-byte different, but the compiler-visible source is the same. Skip.
Trim trailing whitespace: Enter at end-of-buffer adds a \n; that's a no-op for the compiler.

The 220 ms debounce on top of that is comfortable. Type, pause, watch the canvas update. The number was picked by feel — 50 ms recompiles too aggressively during long edits, 500 ms feels laggy.

TL;DR

Set premultipliedAlpha: false on the WebGL context unless you mean to blend with the DOM behind.
Parse getShaderInfoLog() with a tolerant regex (case-insensitive, free-form line fallback). Tag unrecognised lines with line: 0.
Guard null from getUniformLocation before calling gl.uniform* — it returns null for unused or removed uniforms.
Use gl.drawingBufferWidth/Height for the u_resolution uniform, not CSS dimensions.
Flip clientY to WebGL-space when feeding the mouse to u_mouse.
For URL-hash sharing, UTF-8 → base64url is enough for hand-written shaders; defer compression until size matters.
Fold whitespace before deciding to recompile; debounce around 200 ms feels best.

Source: https://github.com/sen-ltd/shader-playground — MIT, ~350 lines of JS, 17 unit tests, no build step, zero runtime dependencies.

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

A Browser Ear-Training Trainer in 350 Lines — Equal-Temperament Frequencies and Three Web Audio Footguns

SEN LLC — Wed, 13 May 2026 00:59:30 +0000

Reading a music-theory textbook is one way to drill relative pitch recognition. Loading a webpage is another. This is a 350-line ear-training trainer that plays a reference C4 then a target note (or a two-note interval pair) through Web Audio and asks the user to identify it. The interesting parts: the one-line equal-temperament frequency formula, the three Web Audio footguns I hit while building it (AudioContext.state === "suspended", missing the first note via osc.start(currentTime), and the click-on-stop without an ADSR envelope), and a small DOM-free pitch module that gets 21 tests under node --test.

🌐 Demo: https://sen.ltd/portfolio/pitch-trainer/
📦 GitHub: https://github.com/sen-ltd/pitch-trainer

Three modes:

Mode	Question	Choices
Major scale	C4 → one note in the major scale	Do / Re / Mi / Fa / Sol / La / Si
Chromatic	C4 → one of 12 pitch classes	C / C# / D / ... / B
Interval	Two distinct notes sequentially, then held together	P1 / m2 / M2 / ... / M7

The equal-temperament frequency formula is one line

12-TET anchored at A4 = 440 Hz gives:

export function semitoneToHz(semitone) {
  if (!Number.isFinite(semitone)) return 0;
  return 440 * Math.pow(2, semitone / 12);
}

semitone is the offset from A4. So:

semitoneToHz(0) = 440 (A4)
semitoneToHz(12) = 880 (A5, one octave up)
semitoneToHz(-9) = 261.63 (C4, middle C)

For users who think in MIDI, the conversion is semitone = midi - 69 because A4 is MIDI 69.

The !Number.isFinite(semitone) guard returns 0 instead of letting NaN reach OscillatorNode.frequency.value. Web Audio's response to a NaN frequency is the audio thread silently dropping the note, which is one of the harder things to debug from the JS side.

The unit test pins precision:

test("semitoneToHz computes equal-temperament semitones to within 1e-9", () => {
  const expected = 440 / Math.pow(2, 9 / 12);   // C4
  assert.ok(Math.abs(semitoneToHz(-9) - expected) < 1e-9);
});

Footgun 1: `AudioContext` ships in `suspended` state

Browsers refuse to make sound until the user has clicked or tapped at least once. That's the autoplay policy, and it's correct — but the failure mode is silent. The AudioContext starts in state: "suspended", you can createOscillator() and start() perfectly normally, and nothing comes out.

The fix is to resume() inside a user-gesture handler:

function ensureAudioContext() {
  if (!state.audioCtx) {
    state.audioCtx = new (window.AudioContext || window.webkitAudioContext)();
  }
  if (state.audioCtx.state === "suspended") {
    state.audioCtx.resume().catch(() => {});
  }
}

The "Start" click runs ensureAudioContext() before scheduling any notes. resume() returns a promise; ignore the rejection because there's nothing useful to do with it.

Backgrounded tabs are also a relevant case — Chrome and Safari both suspend() an inactive context after a while. Re-checking state before every playback session is cheap and catches that.

Footgun 2: `osc.start(currentTime)` drops the first note

Calling OscillatorNode.start(ctx.currentTime) looks correct but isn't. By the time the audio thread picks up the schedule, ctx.currentTime has already advanced past the time you told it, so the start is effectively in the past. The note either renders at quiet, or is dropped entirely.

Shift everything forward by a few milliseconds. I use a 12-ms attack ramp inside an ADSR envelope (which also fixes footgun 3, below), so the effective "earliest sound" is t0 + 0.012s rather than t0 itself.

function playNote(semitoneFromA4, startOffset = 0) {
  const ctx = state.audioCtx;
  const osc = ctx.createOscillator();
  const gain = ctx.createGain();
  osc.frequency.value = semitoneToHz(semitoneFromA4);

  const t0 = ctx.currentTime + startOffset;
  const t1 = t0 + 0.012;       // attack peak
  const t2 = t0 + 0.82;        // sustain end
  const t3 = t0 + 0.9;         // release end

  gain.gain.setValueAtTime(0, t0);
  gain.gain.linearRampToValueAtTime(0.35, t1);
  gain.gain.setValueAtTime(0.35, t2);
  gain.gain.exponentialRampToValueAtTime(0.0001, t3);

  osc.connect(gain).connect(ctx.destination);
  osc.start(t0);
  osc.stop(t3 + 0.01);
}

Sequencing the reference note and the target note is just two playNote calls with different startOffsets:

playNote(rootSemitone, 0);
playNote(targetSemitone, NOTE_DURATION_SEC + GAP_BETWEEN_NOTES_SEC);

The audio thread schedules both ahead of time. The JS event loop can be sluggish in between; the notes still come out at the right time because the schedule lives on the audio side.

Footgun 3: no ADSR → audible "tic" on start and stop

A naked oscillator goes 0 → 1 → 0 in zero time. That step is a discontinuity in the waveform, which the human ear hears as a click. The minimum viable Attack/Decay/Sustain/Release envelope above smooths the corners away:

Phase	Duration	Gain
Attack	12 ms	0 → 0.35 (linear)
Sustain	rest	0.35
Release	80 ms	0.35 → 0.0001 (exponential)

(Decay is skipped because Sustain is the same value as the end of Attack.)

Two technical gotchas:

exponentialRampToValueAtTime(0, ...) throws. The exponential curve can't reach exactly zero. Use a near-zero target like 0.0001.
Order matters. setValueAtTime followed by linearRampToValueAtTime defines a ramp from the set value. Without the explicit setValueAtTime(0, t0), the ramp would start from whatever the gain happened to be (1.0 by default), and you'd hear an instant 1.0 followed by an upward ramp, which is worse than the original click.

Recent-N exclude for non-repetitive questions

Pure Math.random() will sometimes give the user three Mis in a row, which feels broken even though it's statistically expected. The fix is to exclude the last few picks from the candidate pool:

export function pickFromScale(scaleOffsets, recent = [], excludeN = 2, rng = Math.random) {
  if (!scaleOffsets.length) return null;
  const tail = recent.slice(-excludeN);
  const tailSet = new Set(tail);
  const candidates = scaleOffsets.filter((s) => !tailSet.has(s));
  const pool = candidates.length ? candidates : scaleOffsets;
  return pool[Math.floor(rng() * pool.length)];
}

If excludeN is bigger than the scale (unusual, but possible if the scale is tiny), the candidate pool becomes empty and the function falls back to the full scale. Better to occasionally repeat than to throw.

rng is injected so the tests can pin output:

function rngFrom(values) {
  let i = 0;
  return () => values[i++ % values.length];
}

test("pickFromScale excludes the last `excludeN` recent picks", () => {
  const rng = rngFrom([0, 0, 0]);
  // Recent = [0, 2]. Major scale minus those starts at 4.
  const picked = pickFromScale(SCALES.major, [0, 2], 2, rng);
  assert.equal(picked, 4);
});

Interval labels by absolute distance

Music theory distinguishes ascending and descending intervals; software ear-training rarely cares. The trainer asks "what interval did you hear?" and the user types a label without worrying about direction. So absolute-distance modulo 12 is the right interpretation:

export function intervalName(semitones) {
  if (!Number.isFinite(semitones)) return "?";
  const folded = Math.abs(semitones) % 12;
  return INTERVAL_NAMES[folded];
}

intervalName(-7) → "P5" (descending fifth has the same quality as ascending fifth).
intervalName(13) → "m2" (compound minor ninth folds to minor second's label).

My first version used signed modulo (((semitones % 12) + 12) % 12), which silently inverted descending intervals to their octave-complement labels. The test failure (intervalName(-7) === "P4", expected "P5") caught it — that's the test paying for itself in less than a minute.

TL;DR

12-TET frequency is 440 * 2 ** (semitone / 12).
Always resume() the AudioContext inside a click handler. The "audio context is suspended and nothing plays" failure has no visible error.
Don't call osc.start(ctx.currentTime) directly. Add at least 10 ms of attack so the audio thread has head-room.
Wrap every oscillator in a GainNode with a short ADSR envelope. Use linearRampToValueAtTime for attack and exponentialRampToValueAtTime for release, and never ramp exponential to zero (use 0.0001).
For random question selection, exclude the last N picks before sampling; fall back to the full pool if everything got excluded.
For ear-training UIs, interval labels by absolute distance (mod 12) match the user's mental model better than signed semitone math.

Source: https://github.com/sen-ltd/pitch-trainer — MIT, ~350 lines of JS, 21 unit tests, no build step, zero runtime dependencies.

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

A Real-Time Earthquake Map for Japan in 300 Lines of JavaScript — USGS GeoJSON + Leaflet

SEN LLC — Tue, 12 May 2026 00:21:25 +0000

Japan's official seismic data — from the Japan Meteorological Agency — is the most authoritative catalog of domestic earthquakes. It's also un-callable from a browser: no CORS headers, XML payloads, and bulk-download endpoints that gate behind accounts. A real-time map of "what just shook near Japan" needs a different feed. USGS's FDSN event service has it: CORS-enabled, no auth, GeoJSON, 5-10 min publishing latency. This is the 300-line page that wires that feed into a Leaflet map with magnitude-sized, depth-colored epicenter circles, refreshing every 5 minutes.

🌐 Demo: https://sen.ltd/portfolio/earthquake-jp/
📦 GitHub: https://github.com/sen-ltd/earthquake-jp

Why USGS, not JMA

Japan Meteorological Agency (JMA) publishes a much more complete domestic catalog — it goes down to M2 and below, names of villages, JMA shindo intensities. None of which a browser can fetch directly:

No CORS on the JMA endpoints. Same-origin policy blocks fetch() and XMLHttpRequest.
XML, not JSON — and the schemas are pretty maximal (the same envelope for several event types).
Bulk downloads route through scientific portals (NIED J-SHIS, etc.) that gate access.

To use JMA from a browser you need a server in the middle. P2P Quake (api.p2pquake.net) is a community-maintained relay that does exactly that, and it's a fine answer when JMA-only data is required.

USGS FDSN event service (earthquake.usgs.gov/fdsnws/event/1/) doesn't have any of those problems:

Access-Control-Allow-Origin: *
No auth
GeoJSON in, no parsing gymnastics
5-10 minute latency for new events (good enough for "watch what just happened" use cases)

The trade is "only M2.5+", since USGS is the global catalog, not the JMA domestic-fine catalog. For the visualization-of-everything-recent purpose this page exists for, that's fine.

One URL with everything

The FDSN event service accepts a time window and a geographic bounding box. For Japan I use a generous box (lat 24-46, lon 122-148) that covers the archipelago plus the offshore subduction zones — most "felt in Japan" earthquakes originate on the wider plate boundaries:

export const JP_BBOX = {
  minLat: 24, maxLat: 46, minLon: 122, maxLon: 148,
};

export function buildFeedUrl(windowHours, minMag, nowMs = Date.now()) {
  const end = new Date(nowMs).toISOString();
  const start = new Date(nowMs - windowHours * 3600_000).toISOString();
  const params = new URLSearchParams({
    format: "geojson",
    starttime: start, endtime: end,
    minlatitude: String(JP_BBOX.minLat),
    maxlatitude: String(JP_BBOX.maxLat),
    minlongitude: String(JP_BBOX.minLon),
    maxlongitude: String(JP_BBOX.maxLon),
    minmagnitude: String(minMag),
    orderby: "time",
  });
  return `https://earthquake.usgs.gov/fdsnws/event/1/query?${params.toString()}`;
}

nowMs is a parameter, not Date.now() baked in, because tests pin it. Same reason most of the helper functions take an injected clock — production calls pass Date.now(), tests pass 1_700_000_000_000.

Linear-in-magnitude circle radii

Richter magnitude is the base-10 logarithm of seismic energy. M7 is ~32× the energy of M6; M5 is ~1000× M3. A naive radius = energy scaling produces a map where a single M9 swallows the visible area while M3 events vanish.

What reads naturally to the eye on a map is linear-in-magnitude radius:

export function magnitudeToRadius(mag) {
  if (mag == null || mag < 0) return 4;
  const r = 3 + (mag - 1) * 4.4;
  if (r < 3) return 3;
  if (r > 38) return 38;
  return r;
}

Magnitude	Radius
M1	3 px
M3	11.8 px
M5	20.6 px
M7	29.4 px
M9	38 px (clamped)

The clamp matters: when a great earthquake (M9) lands in the dataset, we don't want it to render at 250 px and bury its neighbours. The unit test pins both ends:

test("magnitudeToRadius clamps the upper end so M9 doesn't blow out", () => {
  assert.equal(magnitudeToRadius(9), 38);
  assert.equal(magnitudeToRadius(11), 38);
});

test("magnitudeToRadius grows linearly in magnitude", () => {
  const m3 = magnitudeToRadius(3);
  const m5 = magnitudeToRadius(5);
  const m7 = magnitudeToRadius(7);
  assert.ok(Math.abs((m5 - m3) - (m7 - m5)) < 0.5);  // equal 2-mag gaps
});

Depth-encoded color

Damage from an earthquake depends on magnitude × depth. An M5 at 10 km is a direct-overhead shock; an M5 at 500 km is a soft wide-area tremor. The map encodes that by colour:

const stops = [
  [0,   [0xef, 0x44, 0x44]], // red    — surface
  [30,  [0xf9, 0x73, 0x16]], // orange
  [70,  [0xea, 0xb3, 0x08]], // yellow
  [150, [0x10, 0xb9, 0x81]], // teal-green
  [300, [0x06, 0x6c, 0xb5]], // blue
  [700, [0x1e, 0x40, 0xaf]], // deep blue — slab depth
];

A few design choices behind this:

Stops don't wrap around the colour wheel. Once we leave yellow we keep heading to green and blue, never returning to red. This avoids the cognitive trap where the viewer can't tell whether two same-coloured dots are at the same depth or at very different depths a full hue cycle apart.
Surface is the warm side. People expect warm colours to mean "danger" and most surface-shock damage clusters at shallow depths.
Slab depths get cooler. 300-700 km events (the subducting Pacific plate) feel different and are coloured differently.

depthToColor linearly interpolates the RGB channels between adjacent stops, returning a #rrggbb string the Leaflet circleMarker can use directly.

Leaflet + CARTO Dark, no API key

Leaflet 1.9.4 is loaded from unpkg, CARTO Voyager Dark from their tile CDN — both free with attribution, both keyless. The alternative (maplibre-gl with vector tiles) is sharper but requires either an account at MapTiler / Stadia / similar, or a self-hosted tile server. Not worth it here when raster tiles render at 5 zoom levels and look fine:

const map = L.map("map", { zoomSnap: 0.5 }).setView([36.5, 138], 5);
L.tileLayer(
  "https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png",
  { attribution: '&copy; OSM &copy; CARTO', maxZoom: 9, minZoom: 3 },
).addTo(map);

maxZoom: 9 is a deliberate choice — the whole archipelago fits on screen, prefecture names are readable, and anyone who wants the deep-zoom view can click an epicenter and follow the popup link to the USGS detail page.

5-minute polling, with a visible countdown

USGS doesn't offer SSE or WebSocket for events. Polling is the only option. Every 5 minutes, the page re-issues the same FDSN query and replaces the marker layer. A second 1-second timer drives a countdown so the user can see exactly how stale the on-screen data is:

function scheduleAutoRefresh() {
  if (state.refreshTimer) clearInterval(state.refreshTimer);
  state.refreshTimer = setInterval(fetchAndRender, REFRESH_INTERVAL_MS);
  state.countdownTimer = setInterval(updateCountdown, 1000);
}

function updateCountdown() {
  if (!state.lastFetchAt) return;
  const remainingMs = state.lastFetchAt + REFRESH_INTERVAL_MS - Date.now();
  const m = Math.floor(remainingMs / 60_000);
  const s = Math.floor((remainingMs / 1000) % 60);
  els.nextRefresh.textContent = `次回更新まで ${m}:${String(s).padStart(2, "0")}`;
}

Background tabs are a known issue — Chrome and Safari throttle setInterval to 1 Hz once a tab is hidden. For a 5-minute interval that's fine; what matters is that the content matches the displayed time, and the countdown always shows the truth.

DOM-free helpers, tested in isolation

quakes.js has no DOM access, no Leaflet, no fetch. Everything testable is in there: URL building, magnitude/depth scales, feature flattening, bbox / time filters, summary stats, relative-time formatting. script.js glues those to the map and the network.

node --test exercises the pure layer against synthetic features and injected nowMs:

$ npm test
✔ buildFeedUrl carries window + bbox + minmagnitude params
✔ buildFeedUrl windows backwards from nowMs
✔ magnitudeToRadius grows linearly in magnitude
✔ magnitudeToRadius clamps the upper end so M9 doesn't blow out
✔ depthToColor returns warm hex for surface events
✔ depthToColor returns cool hex for slab-depth events
✔ depthToColor interpolates between anchor stops
✔ featureToRow flattens USGS GeoJSON to {lat, lon, depth, mag, ...}
✔ featureToRow returns null for malformed input
✔ filterToJp drops points outside the bbox
✔ filterByWindow keeps only rows newer than (now - hours*3600s)
✔ statsFromRows tracks count, max magnitude, average, most-recent time
✔ formatRelativeJa uses 分前 / 時間前 / M/D HH:mm thresholds
…
ℹ tests 17  ℹ pass 17  ℹ fail 0

The USGS API itself isn't tested — that's a contract with a third party, not our code.

Try it

The demo at https://sen.ltd/portfolio/earthquake-jp/ ships with the 7-day / M2.5 window selected by default. Drop to M2.5 / 24h to see the fine grain near the Tohoku coast, or move to 30 days / M5 to see only the bigger events on a longer canvas. Click any epicenter for magnitude, depth, place name (JMA-style), and a link to the USGS detail page.

Source: https://github.com/sen-ltd/earthquake-jp — MIT, ~300 lines of JS, 17 unit tests, no build step, no npm dependencies (Leaflet loads from CDN).

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

Searching Emojis With Casual Japanese Keywords — Why Unicode CLDR's ja Annotations Aren't Enough

SEN LLC — Mon, 11 May 2026 00:33:50 +0000

If you type "わらう" (laugh) into Slack's emoji search, you get nothing. The same is true for "ぴえん" (a sad-cute slang for crying that took over Japanese Twitter around 2020), or "ばんざい" (a celebratory "hooray"). Unicode's CLDR (Common Locale Data Repository) ships official Japanese annotations for every emoji — but they're written in the register of an accessibility caption, not a search query. I curated 107 emojis by hand with the casual Japanese tags people actually type, and wrapped them in a ~200-line browser search.

🌐 Demo: https://sen.ltd/portfolio/emoji-search-jp/
📦 GitHub: https://github.com/sen-ltd/emoji-search-jp

Why CLDR's Japanese annotations don't make a search index

Unicode ships annotations for every emoji in every CLDR locale. Each entry has a "name" plus a handful of "keywords". For Japanese, the file looks like this:

Emoji	Name	Keywords
😂	"うれしなき"	`["うれしなき", "かお", "かおえもじ"]`
🥺	"もの欲しそうな顔"	`["かお", "かおえもじ", "けんめい", "もの欲しそう"]`
🙏	"合掌した手"	`["お辞儀", "かたを下げる", "かんしゃ"]`
🎉	"クラッカー"	`["クラッカー", "ハッピー", "パーティー", "紙ふぶき"]`
🐶	"犬の顔"	`["いぬ", "おもしろい", "かお", "どうぶつ"]`

The accessibility job that produced these keywords is the right job for CLDR to do. They cover the visual content of the emoji in a formal-register, all-hiragana style that a screen reader can announce.

What they don't cover is what users actually type:

😂: missing わらう / lol / 草
🥺: missing ぴえん (the slang that defines this emoji in 2020s Japanese)
🙏: missing お願い / ありがとう / ごめん — the contexts every user uses this emoji for
🎉: missing おめでとう
🐶: missing わんこ / ワン

There's an upstream proposal to expand CLDR annotations toward search use cases, but the file as it ships today is a captioning dictionary, not a search dictionary. The two have different shapes.

What this repo ships instead

107 emojis with 5-9 hand-curated tags each, totaling about 750 tag entries. Same schema as CLDR ({char, name_ja, name_en, tags, category}) so the two can be merged if you want both registers.

{
  "char": "😂",
  "name_en": "face with tears of joy",
  "name_ja": "嬉し泣きの顔",
  "tags": ["わらう", "大爆笑", "笑い泣き", "嬉し泣き", "lol"],
  "category": "face"
},
{
  "char": "🥺",
  "name_en": "pleading face",
  "name_ja": "うるうる目の顔",
  "tags": ["ぴえん", "かわいい", "うるうる", "おねがい", "切ない"],
  "category": "face"
},
{
  "char": "🙏",
  "name_en": "folded hands",
  "name_ja": "合掌",
  "tags": ["お願い", "おねがい", "ありがとう", "祈る", "感謝", "ごめん"],
  "category": "gesture"
}

Tag-selection rules I followed while curating:

Mix kana and kanji. "ねこ" and "猫" both belong on 🐱 because the user may or may not have committed an IME conversion.
Mix register. Both the slang ("ぴえん") and the descriptive ("切ない") for 🥺.
Borrow from CLDR. Take the official annotations as a baseline and add the spoken-Japanese coverage on top.
A handful of English tags. lol / ok / love / cool — common enough in mixed-language Japanese chat that they earn their slot.

What I deliberately didn't do: shoot for "all 3700 emoji from the Unicode emoji-list". The lexicon is the product. A smaller, well-tagged set is more useful than a complete, badly-tagged one.

Weighted scoring, five tiers

Search is a linear scan with a five-tier scoring function. For each query token, against each emoji:

const SCORE = {
  TAG_EXACT:           10,  // token === a tag
  TAG_PREFIX:          7,   // token is a prefix of a tag
  TAG_SUBSTRING:       4,   // token is a substring of a tag (non-prefix)
  NAME_JA_SUBSTRING:   3,   // token in name_ja
  NAME_EN_SUBSTRING:   1,   // last-resort English fallback
};

export function scoreToken(emoji, token) {
  if (!token) return 0;
  let best = 0;
  for (const tag of emoji.tags) {
    const t = normalize(tag);
    if (t === token) return SCORE.TAG_EXACT;            // can't beat exact
    if (t.startsWith(token))    best = Math.max(best, SCORE.TAG_PREFIX);
    else if (t.includes(token)) best = Math.max(best, SCORE.TAG_SUBSTRING);
  }
  if (best > 0) return best;
  if (normalize(emoji.name_ja).includes(token)) return SCORE.NAME_JA_SUBSTRING;
  if (normalize(emoji.name_en).includes(token)) return SCORE.NAME_EN_SUBSTRING;
  return 0;
}

The non-obvious choice is the weight gap between TAG_SUBSTRING (4) and NAME_JA_SUBSTRING (3) — a substring hit on a hand-curated tag still beats a coincidental substring hit in the descriptive name. So 顔 ranks "tags containing 顔" above "emojis whose name happens to contain 顔". Without the gap, every face emoji would tie with every cat emoji because both have 顔 in their name_ja.

Multi-token AND with sum-of-scores ranking

Whitespace splits the query into tokens. The default behaviour is every token must contribute at least one point, otherwise the emoji is dropped:

export function scoreEmoji(emoji, tokens) {
  if (tokens.length === 0) return 0;
  let sum = 0;
  for (const tok of tokens) {
    const s = scoreToken(emoji, tok);
    if (s === 0) return -1;   // any miss → drop
    sum += s;
  }
  return sum;
}

So "わらう顔" keeps 😂 (10 from tag わらう + 3 from name_ja containing 顔 = 13) and drops 🐱 (3 from 顔 but no signal for わらう).

The unit tests pin this:

test("scoreEmoji returns -1 if any token fails to match", () => {
  const s = scoreEmoji(SAMPLE_FACE_WITH_TEARS, ["わらう", "車"]);
  assert.equal(s, -1);  // dropped
});

test("search drops emojis that don't satisfy ALL tokens", () => {
  const results = search(SAMPLE, "わらう 顔");
  const chars = results.map((r) => r.emoji.char);
  assert.ok(chars.includes("😂"));
  assert.ok(!chars.includes("🐱"));
});

NFKC normalization upfront

Users will type half-width and full-width letters, with stray IME spaces, and case-mixed. One normalize call handles all of it:

export function normalize(s) {
  return String(s).normalize("NFKC").toLowerCase().trim();
}

ＬＯＬ (full-width) becomes lol; わらう becomes わらう; Pien becomes pien. Everything downstream operates on the normalized form. The boundary is one line and gets tested:

test("search is case- and width-insensitive (NFKC)", () => {
  const results = search(SAMPLE, "ＬＯＬ");
  assert.equal(results[0].emoji.char, "😂");
});

Stable sort matters more than the algorithm

Array.prototype.sort has been stable since ECMA-2019, so equal-keyed elements keep their original order. But equal scores are common in this dataset — 顔 lands at NAME_JA_SUBSTRING (3) for every face emoji — so I made the tie-breaker explicit:

matches.sort((a, b) => {
  if (b.score !== a.score) return b.score - a.score;
  return a.idx - b.idx;   // tie-break by input order
});

The effect: when many emojis tie on score, the curated order (the order I wrote them into data.json) survives. I put the most-used emoji first in every category, so ties resolve to "the more-used one".

test("search is stable: equal-scoring matches keep input order", () => {
  // "顔" → 3 emojis all at NAME_JA_SUBSTRING (3).
  const results = search(SAMPLE, "顔");
  const chars = results.map((r) => r.emoji.char);
  assert.deepEqual(chars, ["😂", "🥺", "🐱"]);  // input order preserved
});

What I didn't build

Trie / inverted index — 107 entries × 7 tags is 0.1 ms of linear scan on a phone. The index only pays off past ~10,000 entries.
Fuzzy / Levenshtein matching — typo tolerance complicates the score function. Prefix + substring already cover ~80% of real misses, and the cost of adding fuzzy is a noticeable jump in false positives.
Skin-tone / gender variants — exploding the entry count by 5-10× hurts search quality. Native OS emoji pickers cover this better.
Speech-readout accessibility annotations — that's exactly what CLDR is for. This repo is the other annotation register.

Try it

The demo at https://sen.ltd/portfolio/emoji-search-jp/ has the full lexicon. Try わらう, ぴえん, ばんざい, 猫, ハート, 寿司, お願い, ありがとう. / focuses the search box. Click an emoji to copy it.

Source: https://github.com/sen-ltd/emoji-search-jp — MIT, ~200 lines of JS plus 107 entries of curated data, 18 unit tests, no build step, no runtime dependencies.

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

Reading Apple Pencil Pressure in the Browser — PointerEvent, getCoalescedEvents(), and the e.pressure Trap

SEN LLC — Sun, 10 May 2026 00:54:36 +0000

Building a sketch pad in a browser sounds like a one-evening job. Then someone tries it with an Apple Pencil and the pressure data is gone, because the code listens for mousemove. Or with a mouse and the line is half as thick as it should be, because it reads e.pressure blindly and a mouse reports 0.5. Or with a fast hand on an iPad and the line is jagged, because the browser only emits one pointermove per 60 Hz frame and the Apple Pencil samples at 240 Hz. This 300-line page solves all three.

🌐 Demo: https://sen.ltd/portfolio/canvas-notebook/
📦 GitHub: https://github.com/sen-ltd/canvas-notebook

Why drop `MouseEvent` / `TouchEvent` entirely

The web's input APIs grew in three layers:

MouseEvent (mousedown / mousemove / mouseup) — mouse only.
TouchEvent (touchstart / touchmove / touchend) — touch only, multi-finger.
PointerEvent (pointerdown / pointermove / pointerup) — the unification, plus a stylus story.

PointerEvent carries the type discriminator (e.pointerType ∈ "mouse" / "touch" / "pen") and exposes e.pressure, e.tiltX, e.tiltY, and on some hardware e.twist. One handler, all input devices. It also has setPointerCapture(pointerId), which kills the classic bug where the user drags out of the window and your mousemove handler never sees the release.

The whole input layer of canvas-notebook is three lines of binding plus a few hundred bytes of pointer-id bookkeeping:

els.canvas.addEventListener("pointerdown", onPointerDown);
els.canvas.addEventListener("pointermove", onPointerMove);
els.canvas.addEventListener("pointerup", onPointerUp);
els.canvas.addEventListener("pointercancel", onPointerUp);

`e.pressure` reports something different on every device

Reading e.pressure and using it as a stroke-width multiplier looks correct. It isn't. The behaviour matrix:

pointerType	what `e.pressure` returns
mouse	`0.5` while a button is held, `0` otherwise
touch (iOS)	`force` if the OS exposes it (3D Touch's old API is still wired internally)
touch (Android)	typically `0`
pen (Apple Pencil)	continuous 0..1, sampled at 240 Hz
pen (Surface Pen / Wacom)	continuous 0..1, 120-240 Hz depending on driver

So if you naïvely write width = baseWidth * e.pressure, mouse strokes come out at half width and Android touch strokes come out at zero (= invisible). The fix is a fallback for pressure === 0:

export function pressureToWidth(pressure, baseWidth, options = {}) {
  const { min = 0.4, max = 1.6, fallback = 0.5 } = options;
  const p = pressure > 0 ? pressure : fallback;
  // [0, 1] → [min, max], clamped, scaled by baseWidth.
  const factor = min + (max - min) * Math.max(0, Math.min(1, p));
  return baseWidth * factor;
}

Three subtleties:

Use the fallback only when pressure === 0. A real low-pressure reading like 0.001 is still real data; if you treat anything below 0.05 as the fallback, low-pressure iPad users see their stroke width jump every time they cross the boundary.
Clamp out-of-range readings. A handful of buggy drivers report pressure > 1. Don't let that crash your renderer or produce a tree-trunk-thick line.
The default band 0.4..1.6 means the stroke is between 40% and 160% of baseWidth end-to-end. The mouse case (pressure === 0 → fallback 0.5 → factor 1.0) lands neatly in the middle of that band, which is what you want.

The unit tests pin the boundaries:

test("pressureToWidth uses fallback only for pressure === 0", () => {
  // 0.001 → real reading, not fallback. Width ends up just above min*base.
  const w = pressureToWidth(0.001, 10);
  assert.ok(w < 10);
  assert.ok(w > 4);
});

test("pressureToWidth clamps out-of-range input", () => {
  assert.equal(pressureToWidth(99, 10), 16);  // capped at max
  assert.equal(pressureToWidth(-1, 10), 10);  // hits fallback path
});

`getCoalescedEvents()` — the API that exists for exactly this problem

Apple Pencil samples at 240 Hz. The browser's animation frame is 60 Hz. If you read pointermove events at face value, you see one sample per frame, throwing away three out of every four samples the OS captured. Drag fast and the resulting line is a series of long straight chords.

PointerEvent.getCoalescedEvents() gives you back the lost samples — every sub-frame sample that was coalesced into the dispatched event:

function onPointerMove(e) {
  if (state.activePointerId !== e.pointerId) return;

  // Fallback when the API isn't supported or returns an empty list (some
  // synthetic / programmatic events do this).
  let samples = [e];
  if (typeof e.getCoalescedEvents === "function") {
    const coalesced = e.getCoalescedEvents();
    if (coalesced && coalesced.length > 0) samples = coalesced;
  }

  for (const s of samples) {
    state.active.points.push(eventToPoint(s));
  }
  redraw();
}

The screen still only updates at 60 Hz, but the stored stroke data has every sample. PNG / SVG export afterwards has the full 240 Hz fidelity.

The length > 0 guard is real. Synthetic events dispatched via new PointerEvent(...) and dispatchEvent return empty from getCoalescedEvents() in Chromium. Without the fallback, the entire stroke is just the pointerdown and pointerup points and intermediate samples are silently dropped. I burned an hour on this during testing — the fix is the three-line guard.

Ramer-Douglas-Peucker to take the cost back out

240 Hz × a few seconds gives you hundreds-to-thousands of points per stroke. For straight or near-straight segments most of that is redundant. After pointerup we run RDP on the stroke to drop points that lie within tolerance pixels of the chord between their neighbours:

export function simplifyStroke(points, tolerance) {
  if (points.length < 3) return points.slice();
  const t2 = tolerance * tolerance;
  const keep = new Array(points.length).fill(false);
  keep[0] = true;
  keep[points.length - 1] = true;

  function recurse(start, end) {
    let maxDist = 0;
    let idx = -1;
    for (let i = start + 1; i < end; i++) {
      const d = perpendicularDistanceSq(points[i], points[start], points[end]);
      if (d > maxDist) { maxDist = d; idx = i; }
    }
    if (maxDist > t2 && idx !== -1) {
      keep[idx] = true;
      recurse(start, idx);
      recurse(idx, end);
    }
  }
  recurse(0, points.length - 1);
  return points.filter((_, i) => keep[i]);
}

tolerance = 0.4 px is below the resolution of the eye on every realistic display and shrinks the point count by 3-5×. SVG export sizes shrink in proportion. The pressure metadata travels with each kept point — RDP only decides which points survive, not what's on them.

Variable-width rendering, simplest version

Every segment of a stroke gets its own lineWidth, computed from the average of the two endpoint widths:

function drawStroke(stroke, ctx) {
  const pts = stroke.points;
  ctx.strokeStyle = stroke.color;
  for (let i = 1; i < pts.length; i++) {
    const a = pts[i - 1], b = pts[i];
    const wa = pressureToWidth(a.pressure, stroke.baseWidth);
    const wb = pressureToWidth(b.pressure, stroke.baseWidth);
    ctx.lineWidth = (wa + wb) / 2;
    ctx.beginPath();
    ctx.moveTo(a.x, a.y);
    ctx.lineTo(b.x, b.y);
    ctx.stroke();
  }
}

The trick is to set lineCap = "round" and lineJoin = "round" once at canvas init. Each segment ends in a circle of its own width, and adjacent segments overlap by their cap radii. The seams disappear visually.

I tried a fancier version with quadraticCurveTo for path-level smoothing while the lineWidth varied per segment. It does not work. The midpoint-Bézier path-management gets very tricky once you start a new path between every segment, and circular strokes (an "o", a smiley face) end up with gaps. Plain segments + round caps look almost identical and never break.

SVG export's compromise

PNG is one line: canvas.toDataURL("image/png"). SVG has to rebuild the strokes from data:

export function strokesToSvg(strokes, width, height, background = null) {
  const bg = background === null
    ? ""
    : `<rect x="0" y="0" width="${width}" height="${height}" fill="${escapeAttr(background)}"/>`;
  const paths = strokes.map((s) => {
    const d = pointsToSvgPath(s.points);
    const meanWidth = averageWidth(s);
    return `<path d="${d}" fill="none" stroke="${escapeAttr(s.color)}" stroke-width="${fmt(meanWidth)}" stroke-linecap="round" stroke-linejoin="round"/>`;
  }).join("");
  return `<?xml version="1.0" encoding="UTF-8"?><svg ...>${bg}${paths}</svg>`;
}

The compromise: <path stroke-width> is one value per path. There's no SVG primitive for "varying stroke width along a curve" that ships in mainstream renderers. The choices are:

Bake the width into the geometry — compute the outline of each variable-width stroke as a polygon, fill it. Faithful to the canvas. 5-10× the bytes.
One value per stroke — average the per-point widths and emit stroke-width="<mean>". Loses the within-stroke modulation but keeps file sizes sane.

canvas-notebook ships #2. The PNG export still has the full per-segment widths because Canvas can render them; the SVG is the same drawing at a slightly lower resolution of width information.

The escapeAttr is defensive and tested:

test("strokesToSvg escapes the color attribute against injection", () => {
  const svg = strokesToSvg(
    [{ color: '"><script>', baseWidth: 1, points: [pt(0, 0)] }], 10, 10,
  );
  assert.ok(!svg.includes("<script>"));
  assert.ok(svg.includes("&lt;script&gt;"));
});

The colors come from a fixed picker in the UI, but the test pins the escaping anyway — if the picker ever takes a color from a URL parameter or a saved file, the test catches the regression.

What didn't make the cut

Per-vertex stroke width in SVG. See above — would inflate file sizes 5-10× by emitting polygon outlines.
Multi-step undo. One step. A real implementation would store a redo stack of stroke-list snapshots.
Multiple pages. Single canvas only.
Background-image annotation. No way to import an image to draw over.
IndexedDB persistence. Not yet — the canvas is volatile, reload clears it.

Try it

If you have an iPad with an Apple Pencil, that's where the pressure story shows up most clearly. On a laptop trackpad or mouse the strokes are still uniform width, but PointerEvent and setPointerCapture and getCoalescedEvents still take care of all the bugs that handlers built on mousemove walk into.

MIT, ~300 lines (notebook.js 200 + script.js 100), 18 unit tests, no build step, zero runtime dependencies.

🛠 Built by SEN LLC as part of an ongoing series of small, focused developer tools. Browse the full portfolio for more.

DEV Community: SEN LLC

A Math-Expression Parser in 250 Lines of JavaScript — Recursive Descent, Right-Associative ^, and -2^2 = -4

Why recursive descent (not shunting-yard)

Trap 1: making ^ right-associative

Trap 2: -2^2 = -4 (unary minus binds LOOSER than ^)

Trap 3: numeric literal tokenisation order matters

Trap 4: error positions with a caret

Function calls as part of atom

Variables override constants

Edge cases: division by zero, sqrt of negative

TL;DR

Computing Moon Phase in 150 Lines of JavaScript — Julian Date, Synodic Month, and SVG Terminator

Architecture: pure module + DOM glue

Julian Date: the astronomer's serial day number

Phase = (JD − reference new moon) / synodic month mod 1

The negative-modulo gotcha

Illumination = (1 − cos(2π × phase)) / 2

The terminator is an elliptical arc — two SVG arcs draw the entire lit area

SVG arc sweep flag, demystified

Why cosPhase's sign tells you the inner sweep

Next new/full moon: closed-form, no binary search

Phase-name binning with a 1/16 offset

On accuracy — this is mean-phase, not true-phase

TL;DR

A Browser IPv4 CIDR Calculator — Three JavaScript Gotchas (uint32 Coercion, /0 Shift Trap, RFC 3021 /31)

Gotcha 1: bit ops produce signed int32, coerce with >>> 0

Gotcha 2: << 32 is << 0, special-case /0

Gotcha 3: RFC 3021 says /31 has TWO usable hosts

Bonus: non-aligned input IPs are masked, not rejected

Subdivide with a truncate limit

Reject malformed input loudly

TL;DR

A Browser-Only Diary in 350 Lines — Month-Grid Math, Code-Point Character Counts, and Streak Boundaries

Month calendar math: always 6 × 7

Character count: code-points, not UTF-16 units

Streak counter, three boundary conditions

Storage: 5 MB is plenty without images

Key namespace: diary:YYYY-MM-DD

TL;DR

Plotting 5 Years of FX in the Browser — Frankfurter API + Hand-Rolled SVG Line Chart

Why Frankfurter and not the other FX APIs

Pivoting the response

Y-axis ticks: the Heckbert "Nice Numbers" algorithm

SVG <path d> from a series

Inverted-range scale for the SVG y-flip

The unavoidable multi-currency scale problem

TL;DR

Reimplementing path-to-regexp in 100 Lines — Why /users/:id? Almost Never Works the Way You Expect

Why rewrite path-to-regexp

A 4-state direct-style parser

The :id? optional-segment trap

Inline regex with paren balance

Stripping query and hash before matching

URL-decoding captured values, safely

The full API in five exports

TL;DR

Visualizing A* One Node at a Time — The Tie-Break and Corner-Cut Decisions That Decide How the Demo Looks

Rewrite A* to expose its state

Tie-breaks make symmetric maps look symmetric

8-connected corner-cut blocking

The heuristic comparison sells the demo

The Canvas footgun: width assignment clears the buffer

TL;DR

A 350-Line GLSL Shader Playground in the Browser — WebGL Init, Line-Number-Aware Errors, and URL-Hash Sharing

What it does

WebGL context — two flags worth setting

Parsing the compile-error log

Uniform binding — guard the null

Mouse coords are WebGL-flipped

URL-hash sharing

"Did the source actually change?"

TL;DR

A Browser Ear-Training Trainer in 350 Lines — Equal-Temperament Frequencies and Three Web Audio Footguns

The equal-temperament frequency formula is one line

Footgun 1: AudioContext ships in suspended state

Footgun 2: osc.start(currentTime) drops the first note

Footgun 3: no ADSR → audible "tic" on start and stop

Recent-N exclude for non-repetitive questions

Interval labels by absolute distance

TL;DR

Trap 1: making `^` right-associative

Trap 2: `-2^2 = -4` (unary minus binds LOOSER than `^`)

Function calls as part of `atom`

Gotcha 1: bit ops produce signed int32, coerce with `>>> 0`

Gotcha 2: `<< 32` is `<< 0`, special-case /0

Key namespace: `diary:YYYY-MM-DD`

SVG `<path d>` from a series

The `:id?` optional-segment trap

Uniform binding — guard the `null`

Footgun 1: `AudioContext` ships in `suspended` state

Footgun 2: `osc.start(currentTime)` drops the first note

Why drop `MouseEvent` / `TouchEvent` entirely

`e.pressure` reports something different on every device

`getCoalescedEvents()` — the API that exists for exactly this problem