DEV Community: takahiro hashito

Implementing UUID v7 by hand: time-sortable primary keys (and the same-millisecond trap)

takahiro hashito — Wed, 22 Jul 2026 23:17:02 +0000

Random UUID v4 makes a poor primary key: values land all over the index, so B-tree inserts scatter across pages and page splits go up. UUID v7 puts a millisecond timestamp in the leading bits (standardized in RFC 9562), so generation order equals sort order and you get locality back.

I needed a UUID generator that runs entirely in the browser, and while building it I implemented v7 by hand instead of pulling in a library. Here is the layout, the implementation, the trap I hit, and when each version is actually the right choice.

The v7 layout

The 128 bits break down like this:

| 48bit unix_ms | 4bit ver(=7) | 12bit rand_a | 2bit variant | 62bit rand_b |

The first 48 bits are the Unix timestamp in milliseconds, big-endian. Then the version (7) and variant bits, and everything else is random. The random part must come from a cryptographic source (crypto.getRandomValues) — not Math.random().

Implementation: putting the bits in the right place

The whole job is "pack the timestamp into the first six bytes, most significant byte first, then overwrite the version and variant nibbles."

function rnd(n){ const a = new Uint8Array(n); crypto.getRandomValues(a); return a; }
function hex(b){ let s=''; for(const x of b) s += ('0'+x.toString(16)).slice(-2); return s; }

function uuidV7() {
  const ts = Date.now();          // 48-bit millisecond timestamp
  const b = rnd(16);
  // 48-bit big-endian millisecond timestamp (top six bytes)
  b[0] = (ts / 0x10000000000) & 0xff; // ts >> 40
  b[1] = (ts / 0x100000000)   & 0xff; // ts >> 32
  b[2] = (ts / 0x1000000)     & 0xff; // ts >> 24
  b[3] = (ts / 0x10000)       & 0xff; // ts >> 16
  b[4] = (ts / 0x100)         & 0xff; // ts >> 8
  b[5] =  ts                  & 0xff;
  b[6] = (b[6] & 0x0f) | 0x70;    // version 7
  b[8] = (b[8] & 0x3f) | 0x80;    // variant (10xx)
  const h = hex(b);
  return `${h.slice(0,8)}-${h.slice(8,12)}-${h.slice(12,16)}-${h.slice(16,20)}-${h.slice(20)}`;
}

The detail worth remembering: shift the digits down with division, not with >>. ts >> 40 does not work, because JavaScript's bitwise operators coerce their operands to 32 bits and a 48-bit value gets mangled. Division followed by & 0xff is safe.

For v4, by the way, don't hand-roll anything if the platform gives you the standard API — it is both faster and safer.

function uuidV4() {
  if (crypto.randomUUID) return crypto.randomUUID(); // one call where it's supported
  const b = rnd(16); b[6] = (b[6]&0x0f)|0x40; b[8] = (b[8]&0x3f)|0x80;
  const h = hex(b);
  return `${h.slice(0,8)}-${h.slice(8,12)}-${h.slice(12,16)}-${h.slice(16,20)}-${h.slice(20)}`;
}

The trap: ordering is not guaranteed within a millisecond

If two IDs are generated in the same millisecond, their leading 48 bits are identical and everything after that is random — so their relative order is arbitrary. If you assume "generation order == strictly ascending", a burst of IDs will quietly break that assumption.

When you do need strict monotonicity, use the 12-bit rand_a field as a counter: increment it within the same millisecond, and reseed it when the millisecond changes.

let lastMs = 0, seq = 0;
function uuidV7Monotonic() {
  const ts = Date.now();
  if (ts === lastMs) seq = (seq + 1) & 0x0fff; // same ms: +1 (12 bits)
  else { lastMs = ts; seq = rnd(2)[0] & 0x0fff; } // new ms: start from random
  // ...store seq in the low 12 bits of b[6..7], overwriting version = 7...
}

If "roughly time-ordered" is good enough for your use case, plain random is fine. The design decision to make up front is simply whether you need strict monotonicity — not which implementation looks cleverer.

Checking it instead of trusting the spec

I measured the following in both Node and the browser rather than assuming the spec held:

Are the version and variant bits actually set? (u[14] === '7', and u[19] is one of 8, 9, a, b.)
Do two IDs generated across a millisecond boundary always sort ascending?
Generate 1000 IDs inside a single millisecond — does the plain implementation break ascending order, and does the counter version hold?

Reproducing the failure yourself, on purpose, is what makes the edge of the trap visible. "The spec says it should" is not the same as having seen it.

v4 vs v7 vs ULID

	Time-sortable	Locality	Standard	In one line
UUID v4	No	Low	RFC 9562	Fully random. Spreads well, hard on indexes
UUID v7	Yes (ms granularity)	High	RFC 9562	Good primary key. Drops into an existing UUID column
ULID	Yes	High	De facto	26-char Base32. Worth a look if you don't need UUID compatibility

If you are using UUIDs as primary keys, v7 is worth considering first. In practice the big win is that it fits your existing uuid / UUID column type unchanged — no migration of the column, just of the generator.

The result

I published the generator as a browser tool: it does v4 and v7, with options for count, hyphens, and uppercase. Generation happens in the page and nothing is sent to a server: https://hashitosystem.com/tools/uuidgen/

Wrap-up

v7 is the right fit for "I want roughly time-ordered keys with good locality." The implementation is just splitting the timestamp into bytes with division and overwriting the version/variant nibbles. The one caveat to internalize: ordering within a single millisecond is not guaranteed, so pair it with a counter if you need strict monotonicity. Get that one point right and it is safe to use.

This article is about my own side project. It was written with AI assistance.

Expiring Content: Put the Deadline in the Data, Not the Prose

takahiro hashito — Wed, 22 Jul 2026 23:16:55 +0000

Introduction

I run several sites that publish time-limited information: Kindle manga sales, grocery and household deals. Everything on them expires.

That creates a structural weakness. Expired deals left on the page erode trust in the whole site. A reader clicks a link labeled "through July 31" and lands on a full-price page. After that happens a couple of times, they stop coming back.

Removing expired entries by hand does not scale; the more articles you have, the worse it gets. So I moved the deadline into the data and let the build decide what to show.

Architecture

Each article carries metrics.deadline in its JSON, and build.js computes the days remaining at generation time.

articles.json
  └ metrics.deadline: "2026-07-31"
        ↓  build.js
   daysUntil(deadline, survey date)
        ↓
   ┌─ left <  0 → excluded from listings; article shows "may have ended"
   ├─ left == 0 → "today only" (emphasized)
   ├─ left <= 3 → "N days left" (emphasized)
   └─ left >  3 → "N days left"

The key design decision is that the reference date is not today but the date the article was last verified. More on that below.

The core of the implementation

Computing days remaining is all there is to it.

// Parse an ISO date (YYYY-MM-DD) as JST and return days remaining from the
// survey date. Expired is negative, same day is 0. The base is the survey
// date (the article's last verification date), not today.
function daysUntil(deadlineIso, baseIso) {
  const base = new Date((baseIso || surveyDate()) + "T00:00:00+09:00");
  const dl = new Date(deadlineIso + "T00:00:00+09:00");
  return Math.round((dl.getTime() - base.getTime()) / 864e5);
}

Spelling out +09:00 is the point. new Date("2026-07-31") parses as UTC, so running in JST shifts the result by nine hours and the date lands a day off. That surfaces as "today only" appearing a day early. If your dates carry a timezone, pin it at parse time.

The expiry check:

// A sale is ended only if it has a deadline and that deadline has passed
// relative to the survey date. Articles with no deadline data are never
// marked as ended (do not fabricate an ended state).
function isEnded(a) {
  const dl = a && a.metrics && a.metrics.deadline;
  return !!dl && daysUntil(dl) < 0;
}

As the comment says, articles without a deadline are deliberately not treated as ended. Displaying "this has ended" for something whose deadline is merely unknown would state something I have not verified. Deciding what not to render when data is missing is part of the spec for this kind of site.

Excluding them from listings is one filter.

// Ended sales: hidden from listings (top/category/tag/related/RSS/sitemap)
// but kept on the article page and in site search, so they stay reachable
// by direct URL.
function listedArticles() {
  return articles.filter((a) => !isEnded(a));
}

Note that this filters rather than deletes. The reason follows.

Rendering branches on days remaining:

const left = daysUntil(m.deadline);
let leftTxt = "", cls = "fact-until";
if (left < 0)        { leftTxt = "may have ended";   cls = "fact-until fact-expired"; }
else if (left === 0) { leftTxt = "today only";       cls = "fact-until fact-urgent";  }
else if (left <= 3)  { leftTxt = `${left} days left`; cls = "fact-until fact-urgent"; }
else                 { leftTxt = `${left} days left`; }

What bit me

Using "today" as the reference date makes the article assert things I never checked.

Initially daysUntil was based on the execution date. That looks natural, and it breaks.

Deal information is written on the day the source was verified. Suppose on July 20 I confirm "through July 31". Rendering that in August correctly says "expired". The failure is the other direction: the deadline itself may have changed at the source. If it was extended or cut short, my data still says July 20's version. Presenting "5 days left" as today's information asserts a fact I have not verified.

So the base became the survey date.

const base = new Date((baseIso || surveyDate()) + "T00:00:00+09:00");

Now days remaining means "how many days were left at the time of verification". The wording follows: "as of the source and verification date, listed as running through July 31." Anything past the deadline reads "may have ended", because whether it actually ended is something I did not check.

Second: deleting expired articles kills URLs.

An earlier version dropped expired entries from generation entirely. That was wrong for both SEO and readers. Externally linked URLs began returning 404, and search traffic had nowhere to land.

Now they are removed from listings, RSS, and the sitemap, but kept on the article page and in site search. New discovery paths no longer surface them, while existing links keep working. A page that says "this sale may have ended" serves a reader far better than a 404.

The result

One of the sites running this: https://manga.autoarticles.net

It aggregates Kindle manga sales, each article showing a days-remaining badge. Expired entries drop out of the listings automatically.

Conclusion

If you handle time-limited information, put the deadline in the data, not the prose. Text that merely says "through July 31" is unreadable to the build, so the operation falls back to human labor.

And the choice of reference date determines what you are allowed to claim. Today's date produces assertions; the verification date produces "here is what was confirmed, and when". Pick the base that matches how certain your information actually is — that was the part of this implementation I thought hardest about.

This article is about my own side project. It was written with AI assistance.

Enforcing Content Tone With a Lint That Fails the Build

takahiro hashito — Wed, 22 Jul 2026 23:16:46 +0000

Introduction

I run about twenty static sites on an automated pipeline. Article data lives in JSON, and a dependency-free build.js emits the HTML. Since updates run unattended, most of the writing is done by machines too.

That created a problem I did not anticipate: tone drifted. I had a rule that these sites use no emoji. Yet every run slipped one in somewhere. A heading here, an FAQ answer there. I would remove them, and the next day they showed up somewhere else.

Trying to hold a style rule in place through review does not scale. So I turned it into a lint that fails the build.

Architecture

The shape is simple: walk the files, report any line containing an emoji, and exit non-zero if there is even one.

update data
   ↓
emoji-lint  ← exits 1 if a single emoji is found
   ↓
build.js (generate site)
   ↓
deploy

The important part is failing via the exit code. A lint that only prints warnings does not get read. Once the following steps stop running, the rule starts to mean something.

The core of the implementation

It is one regular expression plus a loop over every line.

// Main ranges for emoji, pictographs, regional indicators, and variation selectors.
// (Arrows and similar symbols used in real content are deliberately excluded
//  to avoid false positives.)
const EMOJI_RE =
  /[\u{1F000}-\u{1FAFF}\u{2600}-\u{27BF}\u{2B00}-\u{2BFF}\u{1F1E6}-\u{1F1FF}\u{FE0F}\u{200D}\u{2049}\u{203C}\u{2122}\u{2139}]/u;

Range selection followed a deliberate policy. \u{2600}-\u{27BF} contains pictographs, but banning the whole block also catches arrows and other symbols. False positives on characters people legitimately use are how a lint ends up disabled. I optimized for zero false positives and accepted that a few cases slip through to human review.

Including \u{FE0F} (variation selector) and \u{200D} (ZWJ) matters. Emoji are not always a single code point; many are composed as "base character + FE0F" or "emoji + ZWJ + emoji". Matching on the selectors catches that whole family of compositions.

Findings are reported as JSON with line numbers.

const lines = text.split("\n");
lines.forEach((line, i) => {
  if (EMOJI_RE.test(line)) {
    findings.push({ file, line: i + 1, text: line.trim().slice(0, 200) });
  }
});

emit({ ok: findings.length === 0, count: findings.length, findings });
process.exit(findings.length === 0 ? 0 : 1);

Truncating text at 200 characters keeps a single long line from flooding the log. File and line number are enough to locate the problem.

What bit me

An extension-matching bug made the lint silently pass everything.

I added --ext to narrow the scan. path.extname() returns the extension with a leading dot, like ".html". But on the calling side you naturally want to write --ext html, without one. Compare those directly and:

// Bug: with --ext html, nothing matches ".html", so zero files are scanned
if (!exts || exts.includes(path.extname(target))) out.push(target);

exts was non-empty but matched nothing, so zero files scanned, zero findings, ok: true. The lint kept reporting success. Emoji were getting through while it said everything was fine.

The fix is to normalize the input.

const exts = args.ext
  ? String(args.ext)
      .split(",")
      .map((e) => e.trim())
      .filter(Boolean)
      .map((e) => (e.startsWith(".") ? e : `.${e}`))
  : null;

The lesson: a lint that cannot distinguish "found nothing" from "looked at nothing" is dangerous. Printing the number of files scanned alongside a pass would have surfaced the empty scan immediately. I now read the count together with the findings.

One more thing: skipping node_modules and .git is essential, or you drown in hits from dependency READMEs.

for (const name of fs.readdirSync(target)) {
  if (name === "node_modules" || name === ".git") continue;
  out.push(...listFiles(path.join(target, name), exts));
}

The result

One of the sites running on this pipeline: https://cve.autoarticles.net

It covers vulnerability information and uses no emoji at all. A serious subject deserves a serious presentation, and that presentation is now enforced mechanically.

Conclusion

Consistency in tone and style will always leak if you rely on review. If a rule can be decided mechanically, write the code that decides it and fail on violations.

But the lint itself can break and still report success. The extension bug was exactly that. Verifying that a check can detect violations matters as much as verifying that it is actually looking. After writing a lint, deliberately introduce a violation once and confirm it fails.

This article is about my own side project. It was written with AI assistance.