DEV Community: Ritusmoi Kaushik

The Night the Clocks Go Back: The Daylight-Saving Bug in Time Card Maths

Ritusmoi Kaushik — Mon, 26 Oct 2026 07:47:27 +0000

I run a small free website, a time card calculator. You type in when you clocked in and out each day, it adds up the week, splits out the overtime, and gives you a spreadsheet to hand over. Quite a few of the people it's built for work nights: nurses, security guards, the late shift at a warehouse.

On Sunday 1 November, at 2am, clocks in most of the US go back an hour. If you work 10pm to 6am that night, you'll be on shift for nine hours. Your punches will say 10:00 PM and 6:00 AM, which looks exactly like every other night of the year.

My calculator said eight.

This is the bug, the fix (five lines, and no table of dates anywhere), and the one case it still can't get right.

The bug is a subtraction

Most time card maths looks roughly like this:

// minutes after midnight, as the clock read them
function shiftMinutes(inMin, outMin) {
  let d = outMin - inMin;
  if (d <= 0) d += 1440;   // the shift ran past midnight
  return d;
}

shiftMinutes(22 * 60, 6 * 60); // 480

There's nothing wrong with it on 363 nights a year. On the other two, it subtracts what the clock said, and the clock lied. When US clocks go back, 1:59am is followed by 1:00am again, so the hour from 1 to 2 happens twice, and anyone on shift through it works both of them. In March it goes the other way. 1:59 is followed by 3:00, and the same shift is seven hours.

An hourly worker is paid for the hours they worked. That night they worked nine. If they were already near forty for the week, the missing hour is an overtime hour too, so it's the expensive kind.

I recently went through about twenty free time card calculators. None of them adjusted for this.

The tempting fix is a table

My first thought was a list of changeover dates. Second Sunday in March, first Sunday in November, done.

It isn't done, though. That's only the US rule, and only since 2007, when the Energy Policy Act of 2005 moved the dates. Most of Arizona doesn't change its clocks at all. The UK went back on 25 October, a week before the US. Australia goes back in April, and only some of its states bother. A table means I own every one of those rules and every future change to them. I'm one person with a calculator site. I'd get one wrong eventually, and I'd find out from someone's payslip.

The browser already knows all of this. It has to, because it shows you the right local time all year round. So the real question was how to get the browser to tell me how long a shift actually lasted.

Let Date do the arithmetic

A JavaScript Date is an instant: milliseconds since 1970, in UTC. When you build one from local parts (year, month, day, hours, minutes) the browser turns your wall-clock reading into that instant using its own time zone rules. Subtract two instants and you get elapsed time. Not clock time. Elapsed time.

The second half of the trick is that the Date constructor doesn't mind minutes past 59. It rolls them over. new Date(2026, 9, 31, 0, 1800) is midnight on 31 October plus 1,800 minutes, which is 6am on 1 November. So I can describe any shift as "minutes after midnight on the day it started", including one that runs into the next morning, and let the constructor sort out the dates.

That's the whole fix, simplified a little:

// from and to: minutes after midnight on dateISO, as the clock read them.
// Returns the minutes a clock change added (+60) or took away (-60).
function clockChange(dateISO, from, to) {
  const [y, mo, d] = dateISO.split('-').map(Number);
  const real = Math.round(
    (new Date(y, mo - 1, d, 0, to) - new Date(y, mo - 1, d, 0, from)) / 60000);
  return real - (to - from);
}

clockChange('2026-10-31', 22 * 60, 30 * 60); // 60, in New York

(The real one also returns 0 when the card has no date on it. Without a date there's nothing to know.)

The card adds that to the day's total and writes a note on the line: "Clocks went back during this shift — the extra hour is counted." Honestly, the note matters as much as the number. A payroll clerk who sees nine hours next to punches of 10pm and 6am will assume the calculator is broken unless it says why.

Here's the same 10pm to 6am shift, started on the Saturday night before each change:

Time zone	Shift starts	Clock change
America/New_York	Sat 31 Oct 2026	+60
America/Phoenix	Sat 31 Oct 2026	0
Europe/London	Sat 24 Oct 2026	+60
Australia/Sydney	Sat 4 Apr 2026	+60
America/New_York	Sat 7 Mar 2026	−60

Phoenix gets zero because Arizona doesn't change its clocks. I didn't have to know that. The browser did.

Shifts with more than one punch

The calculator lets you clock in and out as many times as you like in a day. A night might be 8pm to 11pm, 11:30pm to 1am, then 1:30am to 5am after a break. Only the last pair crosses 2am, and only that pair should get the extra hour.

So every pair goes on one running timeline for the night, each read forward from where the one before it ended:

const from = pos === null ? inMin : pos + (inMin - pos % 1440 + 1440) % 1440;
pos = from + minutes;
clocks += clockChange(day.date, from, pos);

The 1:30am clock-in comes after a pair that ended at 1am, so it lands at minute 1530 of the timeline rather than minute 90, and new Date(..., 0, 1530) points at the right morning. Get this wrong and the hour goes to the wrong pair, or to nobody. It's the sort of thing you only notice when you write the test.

The case it can't get right

There's one I can't fix, and I'd rather say so than pretend.

On the night clocks go back, 1:30am happens twice. If someone clocks in at 1:30, which one was it? A paper time card doesn't say. Neither does a time typed into a box. JavaScript has to pick, and MDN describes the rule (it's the same as Temporal's "compatible" setting): if a local time happens twice, the earlier one is chosen, and if it never happened, like 2:30 on the night clocks go forward, it moves forward by the size of the gap, so 2:30 becomes 3:30.

So a shift typed as 1am to 3am on 1 November comes out as three hours. That's right if they clocked in before the change and an hour too much if they clocked in after it.

Real time clocks avoid this by recording the instant, or the UTC offset, at the moment of the punch. If you're building anything that records punches, do that. Store the instant, and keep the wall-clock text for display. Rebuilding instants from wall-clock times, which is what I'm doing, is the fallback for when wall-clock times are all you've got. For one hour a year, it's a guess.

It's the device's time zone, not the workplace's

The other limit is quieter. The browser uses its own time zone. If a payroll clerk in Phoenix checks a card for someone who works in Denver, it applies Arizona's rules and adds nothing.

I thought about a time zone dropdown and left it out, for now anyway. The site is built for people checking their own hours, on their own phone, where they work. A dropdown would be one more thing for everyone else to get wrong. Instead the card only adjusts when it has a date, and it always says on the line when it has. If the note is there and shouldn't be, a person can see it.

Testing it without moving to Arizona

The tests run in plain Node, with no dependencies. Node's Date follows the TZ environment variable, and since Node 13 on Linux and macOS (16.2 on Windows) you can change process.env.TZ partway through a script and the next Date picks it up. So one test file visits four time zones in turn:

process.env.TZ = 'America/New_York';
check('clocks go back on 1 Nov 2026: 10pm to 6am is 9 hours', () => {
  const r = e.dayMinutes(nightShift('2026-10-31'));
  assert.strictEqual(r.minutes, 540); assert.strictEqual(r.clocks, 60);
});

process.env.TZ = 'America/Phoenix';
check('1 Nov night shift stays 8 hours', () =>
  assert.strictEqual(e.dayMinutes(nightShift('2026-10-31')).minutes, 480));

Two of the tests I'd suggest to anyone doing this. The first is a shift on the change date that finishes before 2am, to prove it gets nothing. The second is the weekly total: four ordinary nights plus the change night is 41 hours, and the 41st is overtime. That's the one that costs real money if it's missing.

One thing that caught me out while writing this up. On Windows, running TZ=America/New_York node script.js from Git Bash didn't take for me, and the dates came out in my own zone, while setting process.env.TZ inside the script worked fine. If your daylight-saving tests pass suspiciously easily, print new Date().toString() once and check which zone you're really in.

And the spreadsheet

The main thing the calculator produces is an Excel file, and that's where a payroll person actually checks the hours. A number that's quietly an hour bigger than the punches will get "corrected" by somebody. So the sheet says it too. The main card writes "(clocks went back 1h)" next to the punches. The newer 24-hour card has a Clock change column that feeds each line's hours formula, so if someone edits a time in Excel, the hour is still counted.

If you've got a time card, a rota tool or anything that bills by the hour and subtracts clock times, try it with a 10pm to 6am shift starting on 31 October. It takes a minute, and there are still a few days before it matters.

The calculator is at hourstally.com. It's free and runs entirely in the browser, and clockChange is in assets/app.js if you'd like to read the real thing. If you've hit a daylight-saving bug of your own, I'd love to hear it. They're always a bit funny once they're fixed.

A Real .xlsx With Working Formulas in Plain JavaScript, No Library

Ritusmoi Kaushik — Tue, 13 Oct 2026 06:02:02 +0000

I run a small free website, a time card calculator. You type in when you clocked in and out each day, it adds up the week, splits regular hours from overtime, and gives you something to hand over. It's built for hourly workers checking their pay, and for small business owners doing payroll for a handful of staff on a Friday afternoon.

That last part, "something to hand over", is the bit that matters most. A total on a web page is nice. What the manager or the payroll person actually wants is a file they can open in Excel, check, and keep.

For its first few days the site offered a CSV download. CSV is fine for data. It's bad at being a timesheet, because Excel has to guess what every cell is. A total like 41:30 might stay text, or turn into a time, and if anyone then formats that column the usual way it reads 17:30. Nobody wants to explain to their manager why their timesheet says seventeen and a half hours.

So I wanted a proper .xlsx. Real dates, real time cells, and a total that is an actual =SUM() formula, so if you fix a typo in Tuesday's hours the week total moves with it.

The obvious answer is a library. I didn't take it. The whole site ships about 80 KB of JavaScript across five files, and I wasn't keen on a dependency several times that size for one button. What I ended up with is 177 lines and 9 KB, unminified. This is how it works, and the one bug that got through anyway.

An .xlsx is a zip you can write by hand

Rename any .xlsx to .zip and open it. Strip out everything Excel doesn't strictly need and you're left with six small files:

[Content_Types].xml          what each part is
_rels/.rels                  "the workbook is over there"
xl/workbook.xml              the list of sheets
xl/_rels/workbook.xml.rels   "sheet 1 and the styles are over there"
xl/styles.xml                number formats, bold
xl/worksheets/sheet1.xml     the actual cells

Five of those are boilerplate you write once and never touch. The interesting one is the sheet.

The zip part sounds like the scary bit. It isn't, because Excel happily opens a zip whose entries are stored (not compressed). No deflate, no compression library. You need a CRC-32 per file and two kinds of header:

const CRC_TABLE = (() => {
  const t = new Uint32Array(256);
  for (let n = 0; n < 256; n++) {
    let c = n;
    for (let k = 0; k < 8; k++) c = (c & 1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1);
    t[n] = c >>> 0;
  }
  return t;
})();

function crc32(bytes) {
  let c = 0xFFFFFFFF;
  for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]) & 0xFF] ^ (c >>> 8);
  return (c ^ 0xFFFFFFFF) >>> 0;
}

Then, for each file: a local header (signature 0x04034b50, the CRC, the size twice because compressed and uncompressed are the same, the name), the bytes, and later a central directory entry pointing back at it. One end-of-directory record closes the lot. All little-endian, which is where most of the fiddly bits live:

const u16 = n => [n & 0xFF, (n >>> 8) & 0xFF];
const u32 = n => [n & 0xFF, (n >>> 8) & 0xFF, (n >>> 16) & 0xFF, (n >>> 24) & 0xFF];

One small trick I'd recommend. Every entry gets the same fixed timestamp, 1 January 1980, which is the zero point of the old DOS date format. That means the same time card always produces a byte-identical file. You'd be surprised how much easier that makes testing.

Cells: strings, numbers, and formulas that already know their answer

A row in the sheet looks like this:

<row r="9">
  <c r="A9" s="1" t="inlineStr"><is><t>Total hours</t></is></c>
  <c r="E9" s="5"><f>SUM(E2:E8)</f><v>1.7291666666666667</v></c>
</row>

Two things worth noticing.

Strings are written inline (t="inlineStr"). The "proper" way is a shared strings table, where every distinct string is stored once and cells point at it by index. For a sheet with forty cells, honestly, that's ceremony. Inline strings are part of the spec and Excel reads them fine.

The formula cell carries both the formula and its result. The <f> is what Excel keeps and recalculates. The <v> is the cached value, and I compute it myself in JavaScript before writing the file. Excel shows it straight away, and so does anything that previews the file without calculating. Leave <v> out and those previews can show an empty total, which is exactly the thing people look at first.

The cell objects I build are tiny:

{ v: r.totalMinutes / 1440, s: STYLE.boldHm, f: 'SUM(E2:E8)' }

v is the cached value, s a style index, f the formula without its =.

Time is a fraction of a day, and h:mm lies

Excel stores a duration as a fraction of one day. Eight hours is 0.3333…, which is why the value above is minutes / 1440. So far so normal.

The catch is the number format. The everyday h:mm format wraps at 24 hours, like a clock. Put 41 hours 30 minutes in a cell formatted h:mm and Excel shows 17:30. Nothing is wrong with the number. The display is just a clock face, and a clock doesn't know about Thursday.

The fix is a custom format with square brackets:

<numFmt numFmtId="164" formatCode="[h]:mm"/>

[h] means "total hours, don't wrap". It's one character pair, and it's the difference between a time card and a broken one. Custom formats start at ID 164 because 0 to 163 are reserved for Excel's built-ins. I also keep a plain 0.00 decimal column next to it, because payroll people want 41.50, not 41:30.

Dates start in 1899, because of a bug from the 80s

An Excel date is a whole number: days since an epoch. You'd expect the epoch to be 1 January 1900. In practice the maths only works if you count from 30 December 1899:

function dateSerial(iso) {
  const [y, m, d] = iso.split('-').map(Number);
  return Math.round(Date.UTC(y, m - 1, d) / 86400000) + 25569;
}

25569 is the number of days from 1899-12-30 to the Unix epoch. The odd start date is there because Lotus 1-2-3 treated 1900 as a leap year (it wasn't), Excel copied that for compatibility, and the cheapest way to make modern dates come out right is to shift the origin back a day. Dates from March 1900 onwards are correct. Dates in January and February 1900 are off by one, and I'm fairly sure no one is filling in a time card for those.

I have two tests pinning it: 2026-09-07 is 46272, and 1900-03-01 is 61. If either ever changes, something upstream broke.

The ##### bug

Here's the part I didn't see coming.

Everything above passed my tests. The zip was valid, every CRC checked out, every formula was where it should be. Then the first real test on a real PC, in real Excel, opened the two-week sheet and the pay period dates read #####.

That isn't an error. It's Excel saying "this number doesn't fit in this column". I'd made column B six characters wide, because on most rows it only holds the weekday: "Mon", "Tue". On the summary rows the same column holds a date like "28 Sep 2026", and six characters is nowhere near enough. All three of my sheets had the same mistake. None of my tests knew how wide a date is, so none of them caught it.

The fix was boring: column B became 12 wide. The more useful change was a new test that walks every cell, and if it's a date, checks that its column is at least 11 characters wide. Whatever Excel will refuse to display, I'd rather fail on before anyone sees it.

The lesson I took from it, for what it's worth: a file format test tells you the file is valid, not that a person can read it. Open the thing in the real program, on a real machine, before calling it done.

Testing a zip without a zip library

The tests run in plain Node with no dependencies, so I couldn't just require an unzip package either. Instead the test file has a small zip reader, about twenty lines: find the end-of-directory record, walk the central directory, jump to each local header, and check every entry's CRC against the bytes.

And CRC-32 has a published check value, which is handy: the CRC of the ASCII string 123456789 must be 0xCBF43926. If your table is wrong, that test tells you in a millisecond.

When I wouldn't do this

If you need charts, several sheets with thousands of rows, or reading .xlsx files back in, use a library. Shared strings and compression start to matter at that size, and you'd be rebuilding something well-tested for no good reason.

But for "give the user a tidy spreadsheet of what they just typed", a hand-written writer is small and fast, and you understand every byte of it. Mine downloads with the week's punches, regular and overtime hours, and a total that is a live =SUM(). It's the Excel button on hourstally.com, a free time card calculator that runs entirely in the browser, and the code is just assets/xlsx.js if you want to read the whole thing.

If you've written .xlsx by hand and hit a different trap than these, I'd genuinely like to hear about it.

11 weeks of Search Console data from a new site, including the part that failed

Ritusmoi Kaushik — Thu, 23 Jul 2026 09:42:44 +0000

Most write-ups about ranking a new site come from people who already won. They tell you what worked, in order, as if it were a plan rather than a reconstruction. I want to publish the other version, with the actual numbers, while the outcome is still genuinely uncertain.

I launched a browser-based file tools site on 8 May 2026. Everything runs client-side — no uploads, no server, WebAssembly and canvas in the tab. Eleven weeks later I have 42 pages, 1,445 impressions in the last 28 days, and 2 clicks.

That number isn't the interesting part. The interesting part is what the data says about why, and how badly wrong I was for the first two months.

Part 1: two months of building the wrong thing

The launch plan was thirteen tools: image compress, resize, crop, format convert, PDF merge, split, compress, PDF to JPG, and so on. The reasoning was that these are high-volume evergreen queries, the tech is straightforward, and TinyPNG and Smallpdf have proven the model.

Here's what Search Console said after two months, 28 days to 5 July:

Page	Impressions	Avg position
/tools/resize-image/	174	86.7
/tools/crop-image/	107	80.0
"resize image online" (query)	30	90.9
"crop photo online" (query)	24	78.6
every other generic tool page	≤4 each	—

Sitewide: 5 clicks, ~550 impressions.

Position 80 to 95 is not "ranking slowly." Nobody has ever seen page nine of a search result. Those are the positions Google assigns when it has indexed your page, understood it, and concluded there are eighty better answers.

The pages weren't bad. They're fast, the schema is right, the tools actually work and don't upload your files. That's precisely what made the data useful: quality wasn't the variable. I had picked a fight with TinyPNG, iLoveIMG, Canva, Adobe and Google's own Squoosh, from a domain with no authority and no links. A better-executed version of the same page would have ranked 84 instead of 87.

But two rows in that same export looked completely different:

Page	Impressions	Avg position
/blog/heic-files-windows/	86	8.9
/blog/why-heic-not-supported/	5	8.8

Same domain. Same age. Same zero backlinks. Position 9.

The only difference was the topic. HEIC is the format Apple made default on every iPhone in 2017 that Windows still can't open properly. It's a real recurring problem, and the big converter sites treat it as one row in a format list rather than something to own.

Part 2: the pivot

On 10 July I stopped building generic converters and repositioned the entire site around what I started calling orphan formats: files one ecosystem creates that nothing else can open. HEIC from iPhones. AVIF from web pages. JFIF, which is Windows' own bizarre habit of saving JPEGs under a different extension. Apple's .numbers spreadsheets, which Excel refuses outright.

Three days of work, shipped 13 July: three new converter tools, four explainer articles, and a homepage that stopped saying "free image and PDF tools" and started saying "open the files your device can't."

The thirteen generic tools are still live and still indexed. I just stopped linking to them from anywhere on the site. Deleting them would throw away whatever long-tail Google already gives them, but a site that visibly is one thing reads as more authoritative than one padded with eleven me-too converters.

Part 3: what the data says now

28 days to 18 July:

1,445 impressions, up from ~550
Impressions per day went from 11–19 to 60–260 after the 13 July push
21 queries ranking positions 1–10

Every one of those 21 is an orphan-format or informational long-tail:

Query	Position
avif to jpg	3
numbers save as xlsx	7
is .heic safe	8
what is jfif file	8.7
jfif vs jpg	10

Pages published on 13 July were on page one within days. No backlinks pointed at them.

Meanwhile the head terms remain exactly as locked as they were:

Query	Impressions	Position
heic	40	90
heic file	25	86
.heic	17	86

That contrast is the whole lesson, and it's a sharper version of what I got wrong in May. It isn't that a new site can't rank. It's that a new site can rank immediately for questions nobody has bothered to answer well, and never for the terms everyone is fighting over. Same site, same week, positions 3 and 90.

Part 4: so why only 2 clicks?

Because the queries I can win are tiny.

Each of those page-one queries carries 1 to 6 impressions over 28 days. At position 8 with 3 impressions, expected clicks is about 0.3. Two clicks across the whole site is statistically unremarkable, not a failure signal.

I want to be careful here, because this is exactly the kind of correct math that lets you feel fine for six more months while nothing happens. So let me state the uncomfortable version too.

Run the arithmetic forward. If each new guide wins 20 to 30 of these long-tails, and each carries a handful of impressions, a guide is worth maybe 5 to 10 clicks a month at maturity. Publish two a week for six months and you have roughly 50 guides and maybe 400 sessions a month. At display-ad rates that's two to five dollars a month.

The strategy is working and the strategy's ceiling is also very low. Both are true. Coverage compounds, but it compounds from a small base, and I don't yet know whether the curve bends before I run out of patience.

Part 5: four things in the data I hadn't expected

Blogs massively outrank tool pages. My articles sit at positions 15–21. The tool pages they link to sit at 53–76. Same site, same internal linking, same technical setup. Google appears far more willing to rank an explanation than a utility. I now treat the articles as the front door and the tools as what happens after.

Search Console hides most of your queries. My HEIC article shows 358 impressions at the page level, but the named queries for it sum to about 18. The rest is anonymised low-volume long tail that GSC won't show you. If you optimise only against the queries you can see, you're optimising against a few percent of reality.

One referring domain is a hard ceiling. I have five dofollow backlinks and all five are from dev.to. Google counts referring domains, not links, so functionally I have one. Everything sitting at positions 11 to 21 is stuck there because of that, not because of the content. Directories are all nofollow or paid. AlternativeTo rejected the site for lack of notability. This is the actual constraint and I don't have a solution yet.

Google Trends corrected a bet I'd already made. Keyword Planner showed AVIF conversion volume down 90%, which I assumed was a measurement artifact after a 2024 spike. I checked properly. Against heic to jpg on a five-year normalised series, avif to jpg peaked at 8 in December 2024 and now sits at 4: down 50% from peak, down 33% year on year, still sliding, corroborated by avif file to jpg at -80% in related queries. So I was half right and it didn't matter. AVIF is now a maintenance asset, not a growth area. I'd already shipped the pages. Cheap lesson, but it should have come before the build.

What I'd tell myself in May

Competition selection dominates execution quality for a new domain. I don't mean that as a slogan. I mean that the same team, the same stack and the same content quality produced position 87 in one topic and position 9 in another, in the same month, and the only variable was who else was in the room.

If you're building anything that depends on search, look at your Search Console positions before you look at anything else. Not clicks, not impressions. Positions. If your pages sit in the eighties, no amount of writing better will fix it, because writing better was never the problem. Change the room.

I'll post the next set of numbers in a few months, including if it goes badly. I set a kill trigger before starting — under 500 sessions a month by November means I reassess, and I've written it down publicly now specifically so it's harder to quietly move.

The site is fileoholic.com if you want to look at what these numbers describe. Happy to answer questions about any of it, including the parts that aren't working.

I built a HEIC to JPG converter that never uploads your photos (WebAssembly + libheif)

Ritusmoi Kaushik — Tue, 14 Jul 2026 06:08:42 +0000

The privacy problem with "online HEIC converters", and how running libheif in the browser fixes it.

If you've ever helped a non-technical person get an iPhone photo to open on a Windows laptop, you've hit HEIC. Since iOS 11, iPhones save photos as .heic by default — roughly half the size of JPG at the same quality — and the rest of the computing world still chokes on it. Windows shows a black thumbnail, upload forms reject the extension, older apps just shrug.

The usual fix is to Google "HEIC to JPG converter", click the first result, and upload your photos to a server you know nothing about. That's the part that always bothered me. A camera roll isn't holiday snaps — it's ID scans, medical documents, kids, things people photographed because they were private. Shipping those to a stranger's box for a format conversion, then trusting an unverifiable "deleted after 1 hour" banner, is a bad trade.

So I built the converter to run entirely in the browser — no upload, no server, nothing leaves the device. Here's how it works and what tripped me up.

The core idea: decode HEIC where the file already is

HEIC is HEVC-compressed image data in a container. Browsers can't decode it natively (that's the whole problem), so you ship the decoder yourself. Under the hood that's libheif compiled to WebAssembly — I use the heic2any wrapper around it, which handles the decode-and-re-encode in one call.

The flow is entirely client-side — no fetch, no upload endpoint, no backend:

File (.heic)
  → heic2any (libheif WASM) decodes + re-encodes
  → Blob (image/jpeg or image/png)
  → URL.createObjectURL → download

You can prove it: open DevTools → Network tab, drop a file, and watch nothing happen. The page loads, then silence.

The whole conversion is a few lines. Two decisions matter: lazy-load the decoder and process files one at a time.

const MAX_INPUT_BYTES = 25 * 1024 * 1024;

async function processFiles(files: File[]) {
  // Reject oversized files up front — HEIC decode is memory-heavy (see below)
  const tooBig = files.find((f) => f.size > MAX_INPUT_BYTES);
  if (tooBig) return fail(`${tooBig.name} is over 25MB.`);

  // Dynamic import: the WASM decoder only downloads when someone actually
  // converts — it stays out of the initial page bundle entirely.
  const heic2any = (await import("heic2any")).default;

  const out = [];
  // Sequential, NOT Promise.all — a parallel batch blows the heap (see below)
  for (const file of files) {
    const blob = await heic2any({
      blob: file,
      toType: outputFormat,      // "image/jpeg" | "image/png"
      quality: quality / 100,    // slider, defaults to 0.9
    });
    const finalBlob = Array.isArray(blob) ? blob[0] : blob; // heic2any can return Blob[]
    out.push({ name: rename(file), url: URL.createObjectURL(finalBlob) });
  }
  return out;
}

Three things that tripped me up

1. The first conversion is slow — and that's fine. The libheif WASM module is chunky (over a megabyte). Because it's behind a dynamic import(), it only downloads the first time someone actually converts — it never touches the initial page load — and the browser caches it after that, so every conversion afterward feels instant. Compared to the typical converter site loading 4–6 MB of ad scripts before you can even drop a file, one lazy-loaded module is a good deal. I just made the "first HEIC takes longer (decoder loading)" state explicit in the UI so the first hit doesn't feel broken.

2. Memory, not CPU, is the real ceiling. Decoding HEIC allocates a full RGBA bitmap — width × height × 4 bytes. A 48 MP photo is ~190 MB decoded, before you've even re-encoded it. On desktop, fine. On a mobile Safari tab with a hard memory cap, big files kill the tab. So I cap input at 25 MB per file and run the batch sequentially — the for … await loop above, not Promise.all — so ten files don't allocate ten bitmaps at once.

3. Lossy → lossy needs a quality escape hatch. HEIC → JPG re-encodes already-decoded pixels into another lossy format. At quality: 0.9 it's visually identical for photos; below ~0.8 you start seeing it on smooth gradients (sky, skin). I exposed a quality slider and default it to 90, and offer PNG for anyone who wants zero loss after the decode step.

Why bother when Apple's "Most Compatible" setting exists

You can tell an iPhone to save JPG going forward (Settings → Camera → Formats → Most Compatible), and everyone should. But that does nothing for the thousands of HEICs already in the camera roll — those still need converting, and that's the job this tool does without asking anyone to upload anything.

If you want the deeper non-technical version of the HEIC-on-Windows mess — the black-thumbnail bug, the Microsoft extensions, why some files won't open even after you install everything — I wrote that up here: Why HEIC files won't open on Windows.

And the tool itself, if you want to poke at it (or watch the Network tab stay empty): HEIC to JPG converter.

Takeaway

For a whole class of "convert this file" tools, the server is a liability, not a feature. WASM builds of the underlying C libraries — libheif, libvips, mozjpeg, pdfium — are good enough now that the file never has to leave the device. Faster for the user, zero privacy surface for you, and no infra to run. That's the direction I'm taking the rest of the tools too.

What other file conversions are you still uploading to a server that could run locally? Curious what people are stuck on.

Why Your iPhone Photos Won't Open on Windows (and the 5-Second Fix)

Ritusmoi Kaushik — Fri, 10 Jul 2026 08:57:07 +0000

Your phone saves them as HEIC. Your laptop shrugs. Here's what's actually going on — and how to stop fighting it.

About once a week, someone I know forwards me the same panicked message. iPhone in one hand, Windows laptop open in front of them, and a photo called something like IMG_4821.heic that just… won't open. They double-click it. Nothing. They email it to themselves and try again. Same shrug from Windows. By the time they message me, they're half-convinced the photo is corrupted or their laptop is broken.

It's neither. The photo is fine. The laptop is fine. What you're running into is a quiet decade-old standoff between Apple and the rest of the computing world, and once you understand it, the fix takes about five seconds.

The one-sentence version of what's happening

Since 2017, iPhones save photos as HEIC instead of JPG by default. HEIC is a genuinely better format — roughly half the file size at the same visible quality — which is why your 256 GB phone lasts as long as it does. The catch: Windows, most web upload forms, older email clients, government portals, and a long tail of everyday software never fully caught up. So the moment a HEIC file leaves the Apple ecosystem, it hits a wall.

That's the whole problem. Not malware, not corruption, not your fault. Just a format your iPhone loves and your laptop doesn't recognize.

Why Windows specifically chokes on it

Windows didn't support HEIC natively until late in the Windows 10 cycle, and even then you had to go install an extension from the Microsoft Store to get it working. Windows 11 looks like it should handle HEIC out of the box — it ships with partial support — but in practice you'll still often see a black or blank thumbnail in Explorer, or the Photos app throwing an "unsupported format" error.

And here's the part that trips people up even after they fix the viewing problem: being able to view a HEIC file and being able to upload one are two completely different things. You can install every Microsoft extension there is, get gorgeous HEIC previews in Explorer, and still have a job-application form or a bank's KYC portal reject your .heic on the spot — because those forms check the file extension, not whether your operating system happens to have a decoder. For anything you need to send or upload, JPG is still the only format that works everywhere, every time.

Fix #1: Stop the bleeding at the source

If you regularly share photos with Windows users or upload to forms, the cleanest long-term fix is to tell your iPhone to just save JPG from now on:

Settings → Camera → Formats → Most Compatible.

Every new photo from that point forward saves as a standard JPG. Old photos stay as HEIC, but you stop creating new ones. You give up a little of that storage efficiency, but for most people the "it just opens anywhere" tradeoff is worth it.

Fix #2: Convert the HEIC photos you already have

The setting above only helps going forward. For the photos already sitting in your camera roll, you need to convert them — and this is where most people make a small mistake that I'd rather you avoid.

The typical move is to Google "HEIC to JPG converter," click the first result, and upload your photos to some random server for conversion. For holiday snaps, fine. But think about what's usually in a camera roll: ID scans, medical documents, kids, things you took a photo of specifically because they were private. Uploading those to a stranger's server for a format conversion, and trusting an unverifiable "deleted after one hour" promise, is a worse deal than people realize.

You don't have to. Modern browsers are fast enough to do the entire conversion locally, on your own device, without a single byte leaving your machine. I've been using Fileoholic's HEIC to JPG converter for exactly this — you drop the file in, it converts in the browser tab using a local WebAssembly decoder, and you download the JPG. No upload, no signup, no daily limit. If you're the paranoid type (healthy instinct), open your browser's DevTools, watch the Network tab, and drop a file: you'll see the page load and then silence. Your photo never goes anywhere.

The honest take

Apple made the right technical call with HEIC. They arguably made the wrong product call by flipping every iPhone to it by default in 2017, years before Windows, Android, and the web were ready. We've all been quietly cleaning up that mismatch ever since — which is why "convert HEIC to JPG" remains one of the most-searched file-format questions on the internet.

If you want the deeper version of all this — the Windows 11 quirks, the black-thumbnail bug, the Microsoft extensions, and why some HEIC files still won't open even after you install everything — I wrote a full walkthrough here: Why HEIC files won't open on Windows (and the simple fix).

But if you just need the photo to open right now: change the camera setting, convert the ones you already have in your browser, and get on with your day. It's a five-second tax for an inbox that just works.

Billing a Bulk Endpoint Where Any Row Might Be Free

Ritusmoi Kaushik — Fri, 10 Jul 2026 07:35:32 +0000

I already had per-invoice billing working: reserve a credit, do the expensive call, settle or refund. Then I added a bulk endpoint — paste a list, verify them all — and the neat single-item model fell apart, because in a batch some rows cost money and some are free, and you don't know which is which until you've done the work.

This is the metering design behind the bulk GSTIN verification tool on GSTExtract — a solo GST SaaS — and the two bugs I hit building it. The interesting part isn't the happy path. It's that "charge for a batch" quietly becomes "charge for the subset of the batch that turned out to be billable, without overselling and without spending the paid API on rows the user can't pay for."

The setup

A user pastes up to 50 GST numbers. For each, I call a paid third-party registry API and return the business name, status, and address. Each fresh API call costs me real money, so the rule is 1 credit per fresh successful lookup. But three kinds of rows are free:

Cached — I cache every result for 30 days. A repeat lookup of the same number costs me nothing, so it costs the user nothing.
Not found — the API has no record. No data delivered, no charge.
Invalid format — rejected by a regex before any call. Obviously free.

So a "50-item" request might bill for 12. And I can't know the 12 up front — cached vs fresh I can tell, but found vs not-found needs the call. That's the whole problem in one sentence.

Why the single-item model doesn't lift

My invoice path uses the classic reserve → settle → refund: reserve one credit before the vision-model call, settle the real count after, refund on failure. For a batch, the temptation is to do it once for the whole thing: read balance, fetch everyone, charge the found count at the end.

bal = current_balance(db, uid)
to_fetch = fresh[:bal]              # cap to what they can afford
results = await fetch_all(to_fetch)
found = sum(1 for r in results if r["found"])
charge(db, uid, found, allow_partial=True)   # <-- the hole

This oversells. Two concurrent requests both read bal = 10, both fetch 10, both try to charge — the first charges 10, the second charges 0 because allow_partial floors at zero, and that second user just got 10 paid API calls for free. It's the exact race the single-item path was designed to avoid, reintroduced the moment I batched it. Read-then-write is not atomic no matter how you dress it up.

Reserve per item, refund the misses

The fix is to keep the atomic reserve, but do it per GSTIN, and refund the ones that turn out free:

async def one(g):
    key = f"gstinbulk:{base}:{g}"
    # atomic reserve of 1 credit — a single conditional UPDATE, gated on rowcount,
    # so two concurrent reserves for the last credit can't both win
    if not reserve_one(uid, key):
        return g, None, "deferred"          # out of credits — don't call the API
    async with sem:                          # bound API concurrency
        r = await asyncio.to_thread(fetch, g)
    if r["found"]:
        return g, r, "charged"               # keep the reserved credit
    refund_one(uid, key)                      # not-found / failed = free
    return g, r, "free"

Each item reserves before its own paid call. A reserve failure means the balance is gone — that row is deferred, and crucially no API call is made for it, so you never burn the paid quota on a row nobody paid for. Found rows keep the reserve. Everything else refunds. The billable total is just the count of "charged", and it's correct under concurrency because the atomicity lives in the credit reserve, not in a Python-side balance read.

The reserve itself is a conditional update, not a read-modify-write:

UPDATE credit_lots SET remaining = remaining - 1
WHERE id = :lot AND remaining >= 1

Gate on rowcount: exactly one of two racing reserves for the last credit gets rowcount = 1; the other gets 0 and is told it's out of credits. SQLite serializes writers, so this holds without an explicit lock.

One more subtlety: the refund on a not-found must not feed the abuse counter. My invoice path counts a refunded failure toward a per-user daily "unreadable file" budget — a junk-upload guard. A not-found GSTIN is a perfectly normal result, not abuse, so bulk uses a plain reserve-release, not the failure-counting refund. Same primitive, different accounting.

The bug that actually cost me an hour

My first version ran the reserve inside asyncio.to_thread, alongside the fetch, thinking "offload all the blocking work." The tests immediately threw:

sqlite3.InterfaceError: bad parameter or other API misuse

The reserves were now happening on worker threads, several at once, against one SQLite connection. A SQLite connection isn't safe to share across threads like that. The fetch — an HTTP call — genuinely belongs in a thread. The DB writes do not.

The fix is a one-line conceptual rule: DB stays on the event loop; only the slow HTTP call is offloaded.

if not reserve_one(uid, key):     # sync, on the loop — fast local write
    return g, None, "deferred"
async with sem:
    r = await asyncio.to_thread(fetch, g)   # only this leaves the loop

The reserves are quick local writes; running them on the loop serializes them naturally and keeps them single-threaded, which is exactly what SQLite wants. The concurrency I actually needed was for the network calls, and those are the only thing that fans out now. This mirrors how the invoice path already worked — I'd just forgotten why it worked when I reached for to_thread on the DB.

The free tier, and one export gotcha

Anonymous users get a small daily cap of free fresh lookups (for the SEO/demo value), metered per IP; cached hits don't count, so re-checking the same list is always free. Logged-in users draw from credits as above.

And a non-billing one worth flagging: the results export to an .xlsx, and the values include names pulled from the registry plus, in the export path, client-submitted rows. A cell value starting with =, +, -, or @ is a formula-injection vector when the file is opened. Prefix those with a quote:

if s and s[0] in ("=", "+", "-", "@", "\t", "\r"):
    s = "'" + s

Cheap, and it turns a "download to Excel" feature into one that can't ship a live formula from untrusted input.

The takeaway

"Meter a batch" is three problems wearing one coat: the count is unknown until the work runs, some of the work is free, and it all happens concurrently. Reserve per item and the three collapse into one — each row gates itself, pays for itself, or refunds itself, and the total falls out correct. Keep the DB writes on the loop and let only the network fan out.

If you want to see the endpoint from the outside, it's the bulk GSTIN verification tool; the invoice-extraction engine it sits next to is open source. The billing primitives are the same ones from the earlier write-up on the single-item ledger — this is what happened when I pointed them at a batch.

Metering a Paid API Without Overselling: the Credit Ledger Behind a Solo SaaS

Ritusmoi Kaushik — Tue, 16 Jun 2026 07:10:36 +0000

I charge per invoice extracted. One upload of a five-invoice PDF should cost five credits, a failed extraction should cost nothing, and a user with one credit left must never get two. That last rule is where it got interesting.

This is the billing design behind GSTExtract — a tool that reads Indian GST invoice PDFs into Excel — and the concurrency bug a second-pass audit found in it. Writing it up because "meter a paid API correctly" is one of those problems that looks trivial until you hold it up to the light.

The shape of the problem

Each extraction calls a vision model, which costs me real money. So the user spends a credit per invoice. The catch: I don't know how many invoices are in a PDF until after the model reads it. A single page can hold three invoices; a "10-page" file might be one. I can't charge up front because I don't know the count, and I can't charge after without a window where a user with a zero balance has already burned my API budget.

The answer most billing systems land on is reserve → settle → refund:

Reserve one credit before doing the expensive work. This is the gate — if it fails, the user is out of credits and nothing runs.
Settle after success: charge the actual count minus the one already reserved.
Refund the reserve if the extraction failed, so failures are never billed.

Money and credits are integers. Every change is also written to an append-only ledger with an idempotency key, so a retry can never double-charge. Balance is derived: the sum of remaining credits across non-expired "lots" (a lot is one grant — a signup bonus, a purchase). Consumption is FIFO by soonest expiry, so credits get used before they lapse.

That part worked. The bug was in the word "atomic."

The bug: two uploads, one credit

The original charge function did the obvious thing:

# read the balance
bal = current_balance(db, user_id)
if bal < n:
    return False, 0
# ... then walk the lots and decrement in Python
for lot in lots:
    take = min(lot.remaining, remaining)
    lot.remaining -= take          # <-- writes an ABSOLUTE value

Read the balance, decide, write the new value. Single-threaded, this is fine. Now picture a user with exactly one credit firing two uploads at the same moment (a double-click, or two tabs):

Request A reads remaining = 1. Decides it's allowed.
Request B reads remaining = 1. Also decides it's allowed.
A writes remaining = 0, inserts a -1 ledger row.
B writes remaining = 0, inserts a -1 ledger row.

Both succeed. The user spent one credit and got two extractions. The idempotency key didn't save me — the two requests had different keys, because they're two genuinely different uploads. The read-then-write-absolute is the classic lost-update race.

The fix: let the database do the deciding

The cure is to stop computing the new value in Python and let the write itself be the gate — a conditional UPDATE that only fires if there's still enough left, checked under the row lock:

res = db.execute(
    update(CreditLot)
    .where(CreditLot.id == lot_id, CreditLot.remaining >= take)
    .values(remaining=CreditLot.remaining - take)
)
if res.rowcount == 1:
    taken += take      # we actually got it
# rowcount 0 → someone else took it first; move on or roll back

remaining = remaining - take instead of remaining = <number I computed>. The WHERE remaining >= take re-checks the balance at write time, and SQLite serializes writers, so the second request blocks, re-evaluates against the now-committed remaining = 0, gets rowcount = 0, and is correctly told it can't reserve. Exactly one upload wins. Balance can never go negative.

I proved it with a test that fires N concurrent reservers at a one-credit account on a real file-backed SQLite DB (WAL mode, busy timeout — same as production, because an in-memory shared-connection DB won't reproduce writer contention). Exactly one succeeds, every time.

The second bug: a retry that costs me money

There was a sneakier one, found in the same audit. The workspace retries an upload once on a dropped connection, reusing the same request_id so it doesn't double-charge. And it didn't double-charge — the ledger keys saw to that. But the idempotency cache was written after the model call, not before. So a retry that arrived while the first call was still in flight sailed past the cache check and fired a second vision-model call. No double charge, but I paid for two API calls and logged a duplicate usage event.

Fix: mark the request in-flight before the expensive call, while everything above it is still synchronous (so two requests can't both pass the check), and have a retry return 409 instead of re-running:

cached = _REQUESTS.get(rid)
if cached:
    if cached.get("in_flight"):
        return JSONResponse({"code": "in_progress"}, status_code=409)
    return JSONResponse(cached["response"])
# ... reserve the credit ...
_REQUESTS[rid] = {"in_flight": True}   # before the model call

The lesson that keeps repeating: idempotency has to cover the side effect, not just the database row. The charge was idempotent. The expensive API call wasn't.

Why an append-only ledger earns its keep

The thing that made all of this debuggable: nothing is ever updated or deleted in the transaction log. Every grant, charge, and refund is an immutable row with a signed delta. That gives you a reconciliation invariant you can assert on a schedule:

the sum of all ledger deltas for a user == the sum of remaining across all their lots

If those two numbers ever disagree, a write went wrong, and an alert fires. (I also learned to not fold a cache-freshness check into that alert — a balance cache that goes stale when a credit quietly expires is not corruption, and it had me chasing phantom "drift" emails for a day.)

Takeaways

Don't read-modify-write a balance. Make the write conditional (WHERE remaining >= n) and trust rowcount.
Reserve → settle → refund cleanly separates "can they pay" from "what did it actually cost."
Idempotency must guard the expensive side effect, not only the ledger insert.
An append-only ledger gives you a cheap, always-true invariant to reconcile against.
Write the concurrency test against a real on-disk DB, or it won't reproduce the race you're trying to kill.

The hosted tool has a free daily tier and twenty free credits on signup, with prepaid packs for heavier use — so this ledger runs on every extraction, and I'd rather it be boringly correct. If you want to see it in action, it's at gstextract.com; the extraction engine is open source, though the billing layer above is part of the hosted product.

If you've metered a paid API differently — especially how you handle the count-unknown-until-after problem — I'd genuinely like to hear it.

I Open-Sourced the Core of My GST Tool. Here's What I Kept Private.

Ritusmoi Kaushik — Tue, 21 Apr 2026 07:12:18 +0000

A few days ago I published the core extraction engine of GSTExtract on GitHub, MIT licensed. The repository is here. It's not the full product. It's a seven-week-old snapshot, and that gap is the whole strategy.

This post is about the decisions I made picking what to open-source and what to keep private. The deciding took longer than writing the code did, which surprised me. Writing it up in case anyone else is staring at the same question on their own project.

Context, Briefly

GSTExtract reads Indian GST invoice PDFs and pulls out the fields (GSTIN, invoice number, amounts, taxes) into Excel. Small businesses and accountants use it at month-end to avoid hand-typing supplier bills into Tally. The stack is Python — pdfplumber for digital PDFs, Tesseract OCR as fallback, regex + keyword-anchored extraction, openpyxl for Excel output. FastAPI wraps it for the hosted version. The hosted tool is free during early access, with a paid tier planned for high-volume users later.

So the question was: how do I open-source without giving away the commercial edge?

What Went Public

The deterministic regex plus keyword extraction pipeline. GSTIN parsing with the Luhn mod-36 checksum. Zone segmentation that splits an invoice into header and footer and routes fields by zone. Tax-line detection with keyword anchoring. Excel export. The test suite. Basically, the commoditised parsing work that anyone doing invoice extraction would eventually re-implement themselves if they cared enough.

If someone wants to understand how you pull GSTINs and invoice totals out of a messy PDF, the code is all there. Forkable, patchable, usable in their own pipelines.

What Stayed Private

The seven weeks of engine refinements since the cut point:

Multi-vendor accuracy tuning for Amazon, Flipkart, Swiggy, Zomato, BookMyShow, RedBus, and Myntra invoices (each one has a slightly different layout that breaks generic extraction)
Table-based tax extraction for borderless PDFs
Multi-invoice detection for combined bundles
Per-field confidence scoring refinements
Proprietorship invoice edge cases (handwritten-style templates that use bare "FROM" labels instead of "BILL FROM", single-digit invoice serials, and so on)

Plus the entire webapp: FastAPI layer, rate limiting, CSRF, file validation, the invoice validation gate that rejects credit notes and proforma bills, the batch upload flow, the learning-data logging. All of that stays closed.

Why the Time-Lag

This is the part I thought about most. Just publishing the latest engine would let anyone stand up a competing extraction site with the same accuracy I have. Publishing a snapshot from seven weeks ago means competitors get a working baseline, but not the current edge. The engineering work I do this month becomes public (maybe) in a few months, not immediately.

Redis, MongoDB, and Elastic have all done versions of this. The open-core pattern: community gets a real, working version of the core. Commercial version stays ahead by some time delta. Nobody feels cheated, but the pricing power stays intact.

For me, the specific cut was commit 0aa5f07 from 2 March 2026, labeled "Phase 12 production hardening" in the private repo. Engine is solid from there. Everything after is refinement.

What I Expect to Get From This

Honestly, the single biggest thing is the backlink. GitHub has domain authority 96. Having a public repo that links to gstextract.com from the README gives my young domain an authority signal it couldn't easily get any other way. On a site that's only a couple of months old and trying to rank for competitive GST queries, that one dofollow link is legitimately meaningful.

After that, in descending likelihood:

Credibility signal to technical readers who want to see how the extraction works. Some fraction of people evaluating a hosted tool will check if the code is worth trusting.
Issues and pull requests from people hitting edge cases I haven't seen. GST invoice formats are wilder than you'd think. Someone will inevitably send me a PDF from a vendor I've never heard of that breaks something.
Forks from people who need self-hosted extraction for their own use cases. Rare, but they become potential collaborators.

What I'm not expecting: hundreds of stars, viral adoption, a community forming around the repo. For a narrow Indian-GST tool, the realistic audience is small. A handful of serious users finding it and either using it or contributing is the bar, not hockey-stick open-source growth.

Honest Tradeoffs

What this might cost me:

Competitors can clone and study the extraction logic. They would eventually anyway, but I've shortened the path.
Time maintaining the public version even if nobody uses it. If I ignore it for months, it rots and becomes a bad signal.
Some fraction of potential paying customers might think "well, the core is free, I'll just self-host" and walk away. I don't think this is many people, but it's nonzero.

What I'm betting:

The moat is distribution plus the continuous-improvement time-lag, not the code itself.
Most competitors don't actually want to self-host and maintain a parser, deal with Tesseract and Poppler, manage their own uptime. Running the hosted tool is a service, not just code.
People who'll pay for the hosted version are paying for the current-version edge, the no-setup convenience, and whatever the product becomes post-launch. The snapshot on GitHub is closer to educational than competitive.

We'll see if that's right. If self-hosting forks start cutting into hosted usage in a measurable way, I'll revisit the cut-point. For now, the calculus feels fine.