DEV Community: HAU

ISO 8601: The Date Format Standard That Almost Everyone Gets Subtly Wrong

HAU — Tue, 31 Mar 2026 02:00:02 +0000

ISO 8601 is the international standard for representing dates and times. Every developer has heard of it. Far fewer have actually read it.

The result: code that parses 2026-03-24T08:00:00Z correctly but quietly breaks on 2026-03-24T08:00:00+00:00. Or assumes that ISO 8601 date strings are always sortable. Or mixes up T08:00:00 and T080000.

Let's close the gaps.

The Formats You Actually Need to Know

Date Only

2026-03-24        ← Extended format (with hyphens) — most common
20260324          ← Basic format (no hyphens) — valid ISO, rare in APIs
2026-W12-2        ← Week date: year-W{week}-{day-of-week} (1=Mon, 7=Sun)
2026-083          ← Ordinal date: year-{day-of-year}

Date and Time

2026-03-24T08:00:00           ← Local time (no offset — timezone unknown)
2026-03-24T08:00:00Z          ← UTC (Z = +00:00)
2026-03-24T08:00:00+05:30     ← UTC+5:30 (India)
2026-03-24T08:00:00+0530      ← Also valid: colon in offset is optional
2026-03-24T08:00:00.000Z      ← With milliseconds
2026-03-24T08:00:00.000000Z   ← With microseconds

What Many Developers Get Wrong: Z ≠ +00:00 (In Practice)

Technically, Z and +00:00 represent the same UTC offset. But in practice, parsers sometimes treat them differently:

// Chrome/V8
new Date('2026-03-24T08:00:00Z').toISOString();       // "2026-03-24T08:00:00.000Z" ✓
new Date('2026-03-24T08:00:00+00:00').toISOString();  // "2026-03-24T08:00:00.000Z" ✓

// Some older Java DateTimeFormatter configurations reject Z without explicit format
// Some older .NET code only handles one or the other
// PostgreSQL: both work. MySQL: both work. SQLite: it depends on the version.

If you control the format, always use Z. It's shorter and more widely supported.

The Sortability Trap

ISO 8601 datetime strings are lexicographically sortable — if they all use the same offset:

const dates = [
  '2026-03-24T10:00:00Z',
  '2026-03-24T08:00:00+05:30',  // same instant as 02:30 UTC
  '2026-03-24T06:00:00-02:00',  // same instant as 08:00 UTC
];

dates.sort(); // Lexicographic sort
// Result: ['2026-03-24T06:00:00-02:00', '2026-03-24T08:00:00+05:30', '2026-03-24T10:00:00Z']
// The "earliest" is actually 08:00 UTC — sorted last!

For reliable sorting: always normalize to UTC before storing or sorting. A lexicographic sort on *Z strings is correct. A lexicographic sort on mixed-offset strings is wrong.

Duration Format

ISO 8601 also defines a duration format that almost no one learns until they encounter it in an API response:

P1Y2M3DT4H5M6S  =  1 year, 2 months, 3 days, 4 hours, 5 minutes, 6 seconds
P30D             =  30 days
PT2H30M          =  2 hours 30 minutes
P1W              =  1 week

The P prefix stands for "period." The T separates date components (Y, M, D) from time components (H, M, S).

Used by: RSS/Atom feeds (<itunes:duration>), YouTube API video durations, HTML <time> element, PostgreSQL INTERVAL type.

// Parsing ISO 8601 duration in JS (no built-in support)
function parseDuration(iso) {
  const match = iso.match(/P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?/);
  return {
    years:   parseInt(match[1] || 0),
    months:  parseInt(match[2] || 0),
    days:    parseInt(match[3] || 0),
    hours:   parseInt(match[4] || 0),
    minutes: parseInt(match[5] || 0),
    seconds: parseInt(match[6] || 0),
  };
}

parseDuration('P1Y2M3DT4H5M6S');
// { years: 1, months: 2, days: 3, hours: 4, minutes: 5, seconds: 6 }

Interval Format

ISO 8601 intervals define a time range. Three forms:

2026-01-01/2026-03-24                        ← Start/End
2026-01-01/P83D                              ← Start/Duration
P83D/2026-03-24                              ← Duration/End

Not widely implemented in mainstream languages, but you'll see it in geospatial APIs (OGC standards) and some scheduling systems.

What to Actually Use in APIs

For any API you build or consume:

✓ Use:    2026-03-24T08:00:00.000Z     (UTC, milliseconds, Z suffix)
✓ Use:    2026-03-24                   (date only, no time component)
✗ Avoid:  2026-03-24T08:00:00          (ambiguous — local or UTC?)
✗ Avoid:  03/24/2026                   (US format, not ISO)
✗ Avoid:  March 24, 2026               (human-readable, not parseable)
✗ Avoid:  24-03-2026                   (looks like ISO but isn't)

JSON Schema Date Validation

If you're validating ISO dates in JSON Schema:

{
  "type": "string",
  "format": "date"          // validates YYYY-MM-DD
}
{
  "type": "string",  
  "format": "date-time"    // validates YYYY-MM-DDTHH:MM:SSZ
}

JSON Schema format validation is optional in most validators — don't rely on it for security; always validate explicitly in your application code.

Quick Sanity Check

When debugging an unfamiliar timestamp from an API, datetimecalculator.app/unix-timestamp will parse ISO 8601 strings and show you the UTC and local interpretations — useful for telling whether that +05:30 offset was applied correctly.

Summary

Extended format (hyphens/colons) is standard for APIs; basic format is valid ISO but rare
Local time strings (no Z, no offset) are ISO 8601 — but they're ambiguous in distributed systems
Always normalize to UTC for storage and sorting
Learn ISO 8601 durations — you'll encounter them sooner or later
Pair %G (ISO week-year) with %V (ISO week number), not %Y

What's the most unexpected place you've encountered ISO 8601 format requirements? I once found it buried in a hardware sensor protocol spec.

How to Calculate Age Correctly: The Edge Cases Every Developer Misses

HAU — Mon, 30 Mar 2026 02:00:03 +0000

Calculating someone's age sounds like a five-minute task:

function getAge(birthday) {
  const diff = Date.now() - new Date(birthday).getTime();
  return Math.floor(diff / (365.25 * 24 * 60 * 60 * 1000));
}

Ship it. Except this gives wrong answers on certain dates and can be off by a full year around birthdays. Let's fix it.

Why the Division Approach Fails

Dividing milliseconds by an "average year" (365.25 days) is imprecise because:

Leap years don't distribute uniformly — they cluster every 4 years
Someone born January 1, 2000 is not quite 26.25 years old on March 24, 2026
The rounding can flip in the wrong direction around the birthday

// Test: birthday Jan 1, today March 24 2026
getAge('2000-01-01'); // Should be 26, might return 25 or 26 depending on leap year timing

The Correct Calendar-Based Approach

Age in years is a calendar concept, not a duration in milliseconds. Calculate it as a calendar difference:

function getAge(birthdayStr) {
  const today = new Date();
  const birth = new Date(birthdayStr);

  let age = today.getFullYear() - birth.getFullYear();

  // Has the birthday occurred yet this year?
  const monthDiff = today.getMonth() - birth.getMonth();
  const dayDiff = today.getDate() - birth.getDate();

  if (monthDiff < 0 || (monthDiff === 0 && dayDiff < 0)) {
    age--; // Birthday hasn't happened yet this year
  }

  return age;
}

getAge('2000-01-01'); // 26 ✓ (birthday has passed)
getAge('2000-12-25'); // 25 ✓ (birthday hasn't happened yet in 2026)

The Leap Year Birthday Problem

People born on February 29 have a birthday that doesn't exist in most years. Different jurisdictions have different legal answers:

UK: Leap day birthday → legal age milestone on March 1 in non-leap years
New Zealand, Hong Kong: Legal age milestone on February 28 in non-leap years
Taiwan: March 1 in non-leap years
US: Not federally specified; varies

For an application context (not a legal one), February 28 is the safer default:

function getAge(birthdayStr) {
  const today = new Date();
  const birth = new Date(birthdayStr);

  let age = today.getFullYear() - birth.getFullYear();

  // Normalize Feb 29 to Feb 28 in non-leap years for comparison
  let birthThisYear = new Date(
    today.getFullYear(),
    birth.getMonth(),
    birth.getDate()
  );

  // If Feb 29 doesn't exist this year, setDate(29) rolled over to Mar 1
  // setDate(0) instead gets us Feb 28
  if (birth.getMonth() === 1 && birth.getDate() === 29) {
    const isLeapYear = new Date(today.getFullYear(), 1, 29).getDate() === 29;
    if (!isLeapYear) {
      birthThisYear = new Date(today.getFullYear(), 1, 28);
    }
  }

  if (today < birthThisYear) age--;

  return age;
}

getAge('2000-02-29'); // Correct in both leap and non-leap years

Displaying Age with Full Precision

For contexts like a baby's age or medical records, years alone aren't enough. A "6-month-old" is meaningfully different from a "1-year-old":

function getDetailedAge(birthdayStr) {
  const today = new Date();
  const birth = new Date(birthdayStr);

  let years = today.getFullYear() - birth.getFullYear();
  let months = today.getMonth() - birth.getMonth();
  let days = today.getDate() - birth.getDate();

  if (days < 0) {
    months--;
    // Days in the previous month
    const prevMonthEnd = new Date(today.getFullYear(), today.getMonth(), 0);
    days += prevMonthEnd.getDate();
  }

  if (months < 0) {
    years--;
    months += 12;
  }

  return { years, months, days };
}

getDetailedAge('2000-01-15');
// { years: 26, months: 2, days: 9 } on March 24, 2026

Next Birthday Calculation

function nextBirthday(birthdayStr) {
  const today = new Date();
  const birth = new Date(birthdayStr);

  let nextBday = new Date(
    today.getFullYear(),
    birth.getMonth(),
    birth.getDate()
  );

  // Handle Feb 29 in non-leap year
  if (birth.getMonth() === 1 && birth.getDate() === 29) {
    const year = nextBday.getMonth() === 2 ? today.getFullYear() + 1 : today.getFullYear();
    nextBday = new Date(year, 1, 28); // Use Feb 28 as approximation
  }

  // If birthday already passed this year, use next year
  if (nextBday <= today) {
    nextBday.setFullYear(today.getFullYear() + 1);
  }

  const daysUntil = Math.ceil((nextBday - today) / 86400000);
  return { date: nextBday, daysUntil };
}

Zodiac Signs: An Unexpected Date Edge Case

If you're building a birthday-related feature that includes zodiac signs, note that signs depend on the exact day — and the boundaries shift by a day between years due to the solar year not being exactly 365 days. Hard-coding "Aries starts March 21" will be wrong some years.

Quick Age Check Without Code

For manual verification or quick checks, datetimecalculator.app/age-calculator shows precise age in years, months, days, and even hours and seconds — plus the next birthday countdown. Useful for validating your implementation against a known-good result.

Summary

Never calculate age by dividing milliseconds — use calendar arithmetic
Check whether the birthday has occurred yet in the current year
Feb 29 birthdays need explicit handling; define your non-leap-year convention
For medical or legal applications, store the full birthdate and always recalculate age at display time — never store a cached age value

Have you ever shipped an age calculation bug? The leap birthday ones tend to stay hidden for exactly 4 years.

Timezone Conversion in JavaScript: Why getTimezoneOffset() Will Betray You

HAU — Sun, 29 Mar 2026 02:00:02 +0000

Ask any JavaScript developer how to convert between timezones and someone will say: "use getTimezoneOffset()."

Don't.

Here's why, and what to use instead.

What getTimezoneOffset() Actually Returns

const d = new Date();
console.log(d.getTimezoneOffset()); // e.g., -330 for IST, 300 for US/Eastern

Two problems with this:

1. It returns the local timezone offset, not an arbitrary one.

getTimezoneOffset() tells you the offset of the machine running the code. You cannot use it to find out what time it is in Tokyo from a server running in UTC.

2. The sign is backwards from what you'd expect.

UTC+5:30 (India) returns -330. UTC-5:00 (US East) returns 300. The value is UTC - local, not local - UTC. This trips up almost everyone the first time.

The Wrong Way to Convert Timezones

// ❌ This only works if the server happens to be in the right timezone
function toNewYorkTime(utcDate) {
  const offset = -300; // "NYC is UTC-5" hardcoded
  const localTime = new Date(utcDate.getTime() + offset * 60000);
  return localTime;
}

This breaks the moment New York observes Daylight Saving Time (UTC-4, not -5). You've just hardcoded a bug that appears twice a year.

The Right Way: Intl.DateTimeFormat

Modern JavaScript has built-in timezone support via the Intl API:

// Display a UTC timestamp in any IANA timezone
function formatInTimezone(date, timezone, locale = 'en-US') {
  return new Intl.DateTimeFormat(locale, {
    timeZone: timezone,
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
    hour: '2-digit',
    minute: '2-digit',
    second: '2-digit',
    hour12: false,
  }).format(date);
}

const now = new Date();
formatInTimezone(now, 'America/New_York');   // "03/24/2026, 08:00:00"
formatInTimezone(now, 'Asia/Tokyo');         // "03/24/2026, 21:00:00"
formatInTimezone(now, 'Europe/Paris');       // "03/24/2026, 13:00:00"

This correctly handles DST, historical timezone changes, and all the edge cases you'd never think of.

Getting the Offset for Any Timezone

Sometimes you need the numeric offset (for database storage, API calls, etc.):

function getTimezoneOffsetMinutes(timezone, date = new Date()) {
  // Format as offset string in the target timezone
  const formatter = new Intl.DateTimeFormat('en', {
    timeZone: timezone,
    timeZoneName: 'shortOffset', // 'GMT+5:30', 'GMT-4', etc.
  });

  const parts = formatter.formatToParts(date);
  const offsetStr = parts.find(p => p.type === 'timeZoneName')?.value;

  // Parse 'GMT+5:30' → +330, 'GMT-4' → -240
  const match = offsetStr?.match(/GMT([+-])(\d+)(?::(\d+))?/);
  if (!match) return 0;

  const sign = match[1] === '+' ? 1 : -1;
  const hours = parseInt(match[2], 10);
  const minutes = parseInt(match[3] || '0', 10);

  return sign * (hours * 60 + minutes);
}

getTimezoneOffsetMinutes('America/New_York');  // -240 (during EDT)
getTimezoneOffsetMinutes('Asia/Kolkata');      // +330 (IST, no DST)

IANA Timezone Names Are What You Need

Forget abbreviations like EST, PST, IST. They're ambiguous:

IST = Indian Standard Time or Irish Standard Time or Israel Standard Time
CST = Central Standard Time (US) or China Standard Time or Cuba Standard Time

Always use IANA timezone database names: America/New_York, Asia/Kolkata, Pacific/Auckland. These are unambiguous, globally consistent, and maintained with DST rule updates.

// Get user's IANA timezone
const userTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
console.log(userTimezone); // e.g., 'America/Los_Angeles'

DST Edge Cases

Spring forward (clocks skip an hour):
In US/Eastern, 2:30am on March 8 doesn't exist. new Date('2026-03-08T02:30:00') in an ET environment will silently resolve to 3:30am.

Fall back (clocks repeat an hour):
1:30am on November 1 happens twice in US/Eastern. Without an explicit UTC offset, you can't distinguish them.

The only reliable way to handle these: store all timestamps in UTC, convert to local only for display.

// Store this
const event = { startsAt: '2026-11-01T06:30:00Z' }; // UTC ✓

// Display this
formatInTimezone(new Date(event.startsAt), 'America/New_York');
// Correctly shows 1:30 AM EST (after fall-back)

The Temporal API (Coming Soon)

// Future Temporal API — clean timezone handling
const now = Temporal.Now.zonedDateTimeISO('America/New_York');
const tokyo = now.withTimeZone('Asia/Tokyo');
console.log(tokyo.toString()); // No ambiguity, no offset math

Temporal makes timezone-aware arithmetic first-class. It's Stage 3 and shipping in Node 22+ experimentally.

Quick Timezone Lookup

When working across timezones, I often need a quick sanity check on what time it is somewhere right now. For static date conversions ("what time is 3pm EST in Tokyo?"), datetimecalculator.app handles the basics without needing to spin up a REPL.

Summary

getTimezoneOffset() only returns the local machine's offset, and the sign is inverted
Use Intl.DateTimeFormat with IANA timezone names for reliable display
Never hardcode UTC offsets — they change with DST
Always store in UTC; convert to local only at the presentation layer
Avoid timezone abbreviations; use full IANA names

What's the wildest timezone bug you've shipped? The DST "gains an hour" failures seem to be a universal developer experience.

ISO Week Numbers: Why January 1st Is Sometimes in Week 53

HAU — Fri, 27 Mar 2026 02:00:02 +0000

"Week 1 of 2026 starts on December 29, 2025."

If that sentence confused you, welcome to ISO week numbers — one of the most counterintuitive corners of date arithmetic.

What Is an ISO Week Number?

ISO 8601 defines a week as Monday to Sunday. Week 1 of a year is the week containing the year's first Thursday. This means:

A year has either 52 or 53 ISO weeks
The first days of January can belong to the previous year's last week
The last days of December can belong to next year's first week

Real examples:

Date	ISO Week	ISO Week Year
December 29, 2025	Week 1	2026
December 30, 2025	Week 1	2026
January 1, 2026	Week 1	2026
December 28, 2026	Week 52	2026
December 29, 2026	Week 53	2026
January 1, 2027	Week 53	2026

Notice: January 1, 2027 belongs to ISO week 53 of 2026.

ISO Week vs US Week

The US system is different:

Property	ISO 8601	US (common)
First day of week	Monday	Sunday
Week 1 definition	Contains first Thursday	Contains January 1
Week year can differ from calendar year	Yes	No

This divergence causes real problems when you mix them. A US-style "week 1 of 2026" starts January 1. An ISO week 1 of 2026 starts December 29, 2025.

Calculating ISO Week Number in JavaScript

JavaScript's Date object has no built-in ISO week support. Here's a correct implementation:

function getISOWeek(date) {
  const d = new Date(date);
  // Move to nearest Thursday (ISO week is defined by Thursday)
  d.setDate(d.getDate() + 4 - (d.getDay() || 7));
  const yearStart = new Date(d.getFullYear(), 0, 1);
  const weekNum = Math.ceil((((d - yearStart) / 86400000) + 1) / 7);
  return { week: weekNum, year: d.getFullYear() };
}

getISOWeek(new Date('2025-12-29')); // { week: 1, year: 2026 }
getISOWeek(new Date('2026-01-01')); // { week: 1, year: 2026 }
getISOWeek(new Date('2027-01-01')); // { week: 53, year: 2026 }

Note the return includes both week and year — because the ISO week year can differ from the calendar year.

The %V vs %W Format Code Trap

If you're formatting dates server-side, be careful with strftime format codes:

Code	Meaning
`%V`	ISO week number (01-53), where week 1 has >=4 days in the new year
`%W`	Week number, where week 1 starts on the first Monday of the year
`%U`	Week number, where week 1 starts on the first Sunday of the year

import datetime

d = datetime.date(2025, 12, 29)
print(d.strftime('%V'))  # "01" (ISO week 1 of 2026)
print(d.strftime('%W'))  # "52" (52nd Monday-starting week of 2025)
print(d.strftime('%G'))  # "2026" (ISO week YEAR, not calendar year)
print(d.strftime('%Y'))  # "2025" (calendar year)

Using %Y with %V is a common mistake — they belong to different systems. Always pair %G with %V.

Practical Uses of Week Numbers

Time tracking — Many companies report weekly hours using ISO week numbers. Mismatching ISO vs US weeks causes reporting discrepancies.

Retail planning — Fiscal calendars often use ISO weeks to ensure comparable year-over-year metrics (ISO weeks are always exactly 7 days, unlike months).

Agile sprints — Sprint identifiers often reference ISO weeks. If your team uses "W01" and another uses a US-style week 1, you're talking about different date ranges.

Database queries — PostgreSQL's EXTRACT(WEEK FROM date) returns ISO week numbers. MySQL's WEEK(date) returns US-style by default. Mixing these in a BI tool produces silent errors.

-- PostgreSQL: ISO week (Monday-based)
SELECT EXTRACT(ISODOW FROM '2025-12-29'::date); -- 1 (Monday)
SELECT EXTRACT(WEEK FROM '2025-12-29'::date);   -- 1 (week 1 of 2026!)

-- MySQL: returns week of calendar year by default
SELECT WEEK('2025-12-29');     -- 52
SELECT WEEK('2025-12-29', 3); -- 1 (mode 3 = ISO)

Getting Week Boundaries

function getISOWeekBounds(date) {
  const d = new Date(date);
  const day = d.getDay() || 7; // Convert Sunday (0) to 7

  const monday = new Date(d);
  monday.setDate(d.getDate() - day + 1);
  monday.setHours(0, 0, 0, 0);

  const sunday = new Date(monday);
  sunday.setDate(monday.getDate() + 6);
  sunday.setHours(23, 59, 59, 999);

  return { start: monday, end: sunday };
}

getISOWeekBounds(new Date('2026-01-01'));
// start: Mon Dec 29, 2025
// end:   Sun Jan 4, 2026

For a quick lookup without writing code — what week number is today, and when does the current week start and end — datetimecalculator.app/week-number shows both ISO and calendar-week views.

Summary

ISO weeks run Monday–Sunday; week 1 contains the year's first Thursday
The ISO week year (%G) can differ from the calendar year (%Y) — always pair them correctly
JavaScript has no built-in ISO week support; implement it or use a library
PostgreSQL uses ISO by default; MySQL doesn't — watch out when mixing

Has a week number mismatch ever broken your analytics or reporting? The ISO vs US divergence seems to catch almost every team at least once.

The Right Way to Add Months to a Date in JavaScript (It's Not What You Think)

HAU — Thu, 26 Mar 2026 02:00:03 +0000

"What date is 1 month from today?"

For March 24, the intuitive answer is April 24. Simple. But what about January 31? Is one month later February 28? February 31? March 3?

Date arithmetic involving months is genuinely ambiguous, and the way JavaScript handles it will surprise you.

What JavaScript Actually Does

const d = new Date('2026-01-31');
d.setMonth(d.getMonth() + 1); // "Add 1 month"
console.log(d.toISOString()); // "2026-03-03T00:00:00.000Z"

You asked for February, you got March 3. What happened?

JavaScript's setMonth works by setting the month field and letting overflow cascade. February has 28 days in 2026, so "February 31" overflows to March 3. This behavior is defined in the spec — it's not a bug.

But it's almost certainly not what your users expect.

Three Different Conventions

There's no universally correct answer to "Jan 31 + 1 month." Different systems use different conventions:

Convention	Result	Used by
Overflow (JS default)	March 3	Raw JS Date math
Clamp to last day	February 28	Most calendar apps, banking
Snap to last day of target	February 28	PostgreSQL `interval`, many ORMs

For human-facing applications, clamping to the last valid day is almost always what you want.

The Correct Implementation

function addMonths(date, months) {
  const result = new Date(date);
  const targetMonth = result.getMonth() + months;

  result.setMonth(targetMonth);

  // If the month overflowed, we went too far — clamp to last day
  // of the intended month
  if (result.getMonth() !== ((targetMonth % 12) + 12) % 12) {
    result.setDate(0); // setDate(0) = last day of previous month
  }

  return result;
}

addMonths(new Date('2026-01-31'), 1);
// → February 28, 2026 ✓

addMonths(new Date('2026-01-31'), 2);
// → March 31, 2026 ✓

addMonths(new Date('2026-03-31'), -1);
// → February 28, 2026 ✓

Edge Cases That Will Find You

Leap years:

addMonths(new Date('2024-01-31'), 1);
// → February 29, 2024 ✓ (2024 is a leap year)

addMonths(new Date('2024-02-29'), 12);
// → February 28, 2025 ✓ (2025 is not a leap year)

Adding months then subtracting doesn't always round-trip:

const start = new Date('2026-01-31');
const plusOne = addMonths(start, 1);  // Feb 28
const backOne = addMonths(plusOne, -1); // Jan 28 — NOT Jan 31!

This is mathematically unavoidable. If you need round-trip consistency, you have to store the "intended" day separately.

Subscription billing example:

// Customer subscribes Jan 31
// Monthly billing dates:
// Jan 31 → Feb 28 → Mar 28 → Apr 28 ...
// Instead of: Jan 31 → Feb 28 → Mar 31 → Apr 30

For billing, many systems store the "anchor day" (31) and compute each billing date as: min(anchor_day, days_in_target_month). That way March and April get their correct end-of-month dates.

function nextBillingDate(anchorDay, fromDate) {
  const next = new Date(fromDate);
  next.setMonth(next.getMonth() + 1, 1); // move to 1st of next month
  const daysInMonth = new Date(next.getFullYear(), next.getMonth() + 1, 0).getDate();
  next.setDate(Math.min(anchorDay, daysInMonth));
  return next;
}

nextBillingDate(31, new Date('2026-01-31')); // Feb 28
nextBillingDate(31, new Date('2026-02-28')); // Mar 31
nextBillingDate(31, new Date('2026-03-31')); // Apr 30

Adding Years Has the Same Problem

const d = new Date('2024-02-29'); // leap day
d.setFullYear(d.getFullYear() + 1);
console.log(d); // March 1, 2025 — overflowed

Same fix: check for overflow after setting, clamp if needed.

When You Just Need the Answer

For quick calculations — "what's the date 3 months from now?", "when does my annual subscription renew?" — datetimecalculator.app handles the clamping correctly. Useful for sanity-checking your implementation against a known-good result.

The Takeaway

setMonth() overflows silently — never use it directly for user-facing date math
Define your overflow convention explicitly, document it, and test the edge cases
End-of-month dates + month arithmetic = you need a clamping strategy
Round-trip consistency (add then subtract) is impossible when months overflow; design around this

What date arithmetic gotcha has caused you the most grief? Month-end billing edge cases seem to be a rite of passage.

JavaScript Countdown Timers: Why setInterval Drifts and How to Fix It

HAU — Wed, 25 Mar 2026 02:00:01 +0000

Building a countdown timer feels like a two-minute task:

let seconds = 60;
const timer = setInterval(() => {
  seconds--;
  display(seconds);
  if (seconds <= 0) clearInterval(timer);
}, 1000);

Ship it. Done. Except... after a few minutes, your "60 second" timer has taken 63 seconds of wall-clock time. Users notice. This is timer drift, and every interval-based timer has it.

Why setInterval Drifts

setInterval(fn, 1000) doesn't fire exactly every 1000ms. It fires "at least 1000ms after the last call, when the event loop is free." Three sources of error compound over time:

Scheduling jitter — The browser/Node event loop fires the callback a few milliseconds late due to other tasks
Callback execution time — If your callback takes 5ms, the next interval starts 1005ms after the previous one began
Tab throttling — Browsers throttle timers in background tabs to 1 second minimum (sometimes more)

Small errors, big compounding:

Expected:  0ms  1000ms  2000ms  3000ms  4000ms ...
Actual:    0ms  1004ms  2009ms  3013ms  4018ms ...

After 5 minutes, you're 5.4 seconds behind. After an hour? 65+ seconds of drift.

The Fix: Anchor to Wall-Clock Time

Instead of counting ticks, measure elapsed time against a fixed reference point:

function createCountdown(durationMs, onTick, onComplete) {
  const endTime = Date.now() + durationMs;

  function tick() {
    const remaining = endTime - Date.now();

    if (remaining <= 0) {
      onTick(0);
      onComplete();
      return;
    }

    onTick(remaining);
    // Schedule next tick relative to how much time SHOULD have passed
    const nextTick = remaining % 1000 || 1000;
    setTimeout(tick, nextTick);
  }

  tick();
}

// Usage
createCountdown(
  60_000,
  (ms) => display(Math.ceil(ms / 1000)),
  () => console.log('Done!')
);

This approach:

Never accumulates drift, because every tick calculates remaining time fresh
Self-corrects automatically after tab throttling
Fires extra-soon when recovering from a delayed tick

Countdown to a Future Date

For "days until" counters (time until an event, product launch, etc.), use the same principle:

function countdownTo(targetDate) {
  function update() {
    const now = Date.now();
    const target = new Date(targetDate).getTime();
    const diff = target - now;

    if (diff <= 0) {
      render({ days: 0, hours: 0, minutes: 0, seconds: 0 });
      return;
    }

    render({
      days:    Math.floor(diff / 86_400_000),
      hours:   Math.floor((diff % 86_400_000) / 3_600_000),
      minutes: Math.floor((diff % 3_600_000)  / 60_000),
      seconds: Math.floor((diff % 60_000)     / 1000),
    });

    // Sync to the next whole second
    setTimeout(update, diff % 1000 || 1000);
  }

  update();
}

countdownTo('2026-12-25T00:00:00');

The key line is diff % 1000 || 1000 — this syncs the next update to fire right when the second digit changes, rather than on a fixed interval.

Handling Visibility Changes

Browsers aggressively throttle background tabs. When the user switches back, your timer might jump 30+ seconds at once. Handle it:

document.addEventListener('visibilitychange', () => {
  if (!document.hidden) {
    // Force immediate re-render when tab becomes visible
    update();
  }
});

Since update() always reads Date.now(), it will immediately show the correct remaining time — no accumulated error to correct.

Web Workers: When You Need Precision in Background Tabs

If your countdown genuinely must be accurate in background tabs (e.g., a timed exam), browsers won't throttle Web Worker timers the same way:

// worker.js
self.onmessage = ({ data: { endTime } }) => {
  const tick = () => {
    const remaining = endTime - Date.now();
    self.postMessage({ remaining });
    if (remaining > 0) setTimeout(tick, remaining % 1000 || 1000);
  };
  tick();
};

// main.js
const worker = new Worker('worker.js');
worker.postMessage({ endTime: Date.now() + 300_000 });
worker.onmessage = ({ data: { remaining } }) => render(remaining);

Quick Reference

Approach	Drift	Background accuracy	Complexity
`setInterval` counting	Accumulates	Poor	Low
`setTimeout` + `Date.now()`	None	Moderate	Medium
Web Worker	None	Good	Higher
`requestAnimationFrame`	None	Poor (pauses when hidden)	Medium

For countdowns to specific future dates, tools like datetimecalculator.app/days-until give you the static number without any drift concerns — useful for planning how long you have before you need to implement the real thing.

What's the worst timer drift bug you've shipped? Mine was a "60-second" quiz timer that gave users 68 seconds on slow laptops.

Stop Using new Date('2026-01-01') to Parse Date Strings

HAU — Tue, 24 Mar 2026 10:27:07 +0000

If you've been writing JavaScript for more than a week, you've probably written something like this:

const d = new Date('2026-01-01');
console.log(d.toISOString()); // "2026-01-01T00:00:00.000Z" ✓ (looks fine)

And it looks fine. Until it doesn't.

The Hidden Timezone Trap

Here's where it breaks:

const d = new Date('2026-01-01');
console.log(d.toLocaleDateString('en-US')); // "12/31/2025" 😱

You passed in January 1st. You got back December 31st.

This is not a bug — it's specified behavior. According to the ECMAScript spec, date-only strings in YYYY-MM-DD format are interpreted as UTC midnight. When you convert to local time in a UTC-5 timezone (US East Coast), UTC midnight becomes the previous day at 7pm.

Compare this:

// Date-only string → interpreted as UTC
const d1 = new Date('2026-01-01');
console.log(d1.toISOString()); // "2026-01-01T00:00:00.000Z"

// Date-time string (even just adding T00:00) → interpreted as LOCAL time
const d2 = new Date('2026-01-01T00:00:00');
console.log(d2.toISOString()); // "2026-01-06T05:00:00.000Z" in UTC+5

Same string, one extra T00:00:00 suffix, completely different behavior. This inconsistency is one of JavaScript's most footgun-laden design decisions.

The Full Breakdown

Input format	Interpreted as	Spec reference
`'2026-01-01'`	UTC midnight	ISO 8601 date-only → UTC
`'2026-01-01T00:00:00'`	Local midnight	ISO 8601 datetime (no offset) → local
`'2026-01-01T00:00:00Z'`	UTC midnight	Explicit UTC offset
`'2026-01-01T00:00:00+05:30'`	IST midnight	Explicit IST offset
`'January 1, 2026'`	Implementation-defined	Non-ISO → don't rely on this

That last row is important: any date string that isn't ISO 8601 compliant is implementation-defined behavior. Different JS engines may parse it differently. Chrome, Firefox, and Node may all disagree.

Real-World Failure Modes

Birthday forms — User types 1990-05-15. You parse with new Date('1990-05-15'). In UTC-N timezones, the birthday silently shifts to May 14. Age calculations go wrong.

Event scheduling — You store 2026-03-01 from a date picker. Users in UTC-8 see February 28 in their local calendar.

Analytics date filters — new Date('2026-01-01') as a range start in UTC-5 misses 5 hours of data from the actual start of the day.

The Correct Approaches

Option 1: Parse manually (most explicit)

function parseLocalDate(dateStr) {
  // dateStr: 'YYYY-MM-DD'
  const [year, month, day] = dateStr.split('-').map(Number);
  return new Date(year, month - 1, day); // local midnight, always
}

parseLocalDate('2026-01-01').toLocaleDateString('en-US'); // "1/1/2026" ✓

Option 2: Append local time explicitly

const d = new Date('2026-01-01T00:00:00'); // local midnight

Works, but fragile — easy to forget the suffix or strip it during data transformation.

Option 3: Use Temporal (the future)

The TC39 Temporal API fixes this properly. Temporal.PlainDate represents a calendar date with no time or timezone:

const d = Temporal.PlainDate.from('2026-01-01');
console.log(d.toString()); // "2026-01-01" — no timezone ambiguity

Temporal is at Stage 3 and available in Node 22+ behind a flag. Worth knowing.

Option 4: Use a library (practical now)

date-fns parseISO and Day.js both handle this more predictably than native Date.

import { parseISO, format } from 'date-fns';

const d = parseISO('2026-01-01');
format(d, 'MM/dd/yyyy'); // "01/01/2026" ✓

The Rule

If you need to represent a calendar date (no time, no timezone), never use new Date('YYYY-MM-DD'). Parse the components manually or use a library that understands the distinction.

For quick sanity checks when you need to verify what a date string actually resolves to, I find datetimecalculator.app useful — paste a timestamp or date in, see the UTC and local interpretations side by side.

Has this bitten you in production? What date string nightmare have you survived?

Date Difference Calculations: Why "How Many Days Between" Is Harder Than It Seems

HAU — Tue, 24 Mar 2026 09:44:26 +0000

"How many days between January 1 and March 24?"

Go ahead, count it in your head. Most people say 82 or 83 depending on how they're thinking about it. The correct answer is 83 — but ask ten developers to write the code, and at least three will get it wrong on the first try.

Date difference calculations are one of those things that seem trivial until you actually dig into the edge cases.

The Off-By-One Trap

Let's start with the most common mistake:

const start = new Date('2026-01-01');
const end = new Date('2026-03-24');

const diffMs = end - start;
const diffDays = diffMs / (1000 * 60 * 60 * 24);

console.log(diffDays); // 82

Is it 82 or 83? It depends on what you're actually asking:

Exclusive end (don't count the end date): 82 days
Inclusive end (count both the start and end date): 83 days

There's no universally correct answer — it depends on your context. Booking systems typically use exclusive end dates (if you check in Jan 1 and check out Jan 3, your stay is 2 nights). Age calculations typically are inclusive.

Always document which convention your code uses.

The Daylight Saving Time Ambush

This one has burned many developers:

// In a DST-observing timezone (e.g. US/Eastern)
const start = new Date('2026-03-08'); // day before DST starts
const end = new Date('2026-03-09');   // DST starts (clocks spring forward)

const diffMs = end - start;
const diffDays = diffMs / (1000 * 60 * 60 * 24);

console.log(diffDays); // 0.9583... NOT 1!

Because DST removed an hour from March 8, the day was only 23 hours long. The millisecond difference is 82800000 instead of 86400000.

The fix: use UTC dates, or round the result:

// Safe approach: parse as UTC
function daysBetween(dateStr1, dateStr2) {
  const d1 = new Date(dateStr1 + 'T00:00:00Z');
  const d2 = new Date(dateStr2 + 'T00:00:00Z');
  return Math.round((d2 - d1) / (1000 * 60 * 60 * 24));
}

daysBetween('2026-03-08', '2026-03-09'); // 1 ✓

Expressing Differences in Multiple Units

Sometimes "82 days" isn't the most useful answer. You want "2 months and 22 days" or "11 weeks and 5 days."

Here's the thing: months don't have a fixed number of days, so "2 months" from January 1 could mean different things depending on whether you count February or March. The only unambiguous representation is:

function dateDiff(start, end) {
  const s = new Date(start);
  const e = new Date(end);

  let years = e.getFullYear() - s.getFullYear();
  let months = e.getMonth() - s.getMonth();
  let days = e.getDate() - s.getDate();

  if (days < 0) {
    months -= 1;
    // Days in the previous month
    const prevMonth = new Date(e.getFullYear(), e.getMonth(), 0);
    days += prevMonth.getDate();
  }

  if (months < 0) {
    years -= 1;
    months += 12;
  }

  return { years, months, days };
}

dateDiff('2024-11-15', '2026-03-24');
// { years: 1, months: 4, days: 9 }

This is how age calculations work too — your age isn't just (today - birthday) / 365.25, it's the calendar difference accounting for full months and days.

The Leap Year Edge Case

February 29 exists only in leap years, which creates a fun problem: how old is someone born on February 29?

Most implementations handle this by using February 28 as the birthday in non-leap years. But different countries have different legal interpretations — some say February 28, some say March 1.

// Born Feb 29, 2000 — how old on March 1, 2026?
const birthday = new Date('2000-02-29');
const today = new Date('2026-03-01');

// Naive calculation
const age = today.getFullYear() - birthday.getFullYear(); // 26
// But have they had their birthday yet this year?
// Feb 29 doesn't exist in 2026...

For production code involving legal ages (alcohol, voting, retirement), consult your jurisdiction's specific rules.

When You Just Want the Answer

All of the above is important to understand — especially if you're implementing date logic in an application. But for quick day-to-day calculations ("when's my project due?", "how long until the conference?", "how many days since that outage?"), you don't want to write code every time.

I've been using datetimecalculator.app for this — the date difference calculator handles all the edge cases correctly and shows the result in multiple units simultaneously (days, weeks, months, years). There's also a separate days-until counter for event countdowns, which I find useful when tracking upcoming deadlines.

Summary of Edge Cases to Test

Whenever you write date difference logic, run it against:

Test Case	Why
Same start and end date	Should be 0
End before start	Handle gracefully (negative or absolute value?)
Across DST boundary	Use UTC internally
Across leap day (Feb 28–Mar 1 in leap year)	1 day, not 2
Across year boundary	January 1 to December 31 of same year = 364 or 365
February 29 birthday in non-leap year	Define your convention

Date math is one of those domains where a quick prototype works 95% of the time, but the remaining 5% creates hard-to-reproduce bugs that show up at 2am. The investment in understanding the edge cases upfront is worth it.

What's the nastiest date bug you've had to debug? The DST ones are usually my favorite war stories.

Unix Timestamps: The 10 vs 13 Digit Problem That Breaks More APIs Than You Think

HAU — Tue, 24 Mar 2026 09:25:34 +0000

There's a bug pattern I've seen in production more times than I can count. It goes like this:

const timestamp = Date.now(); // Returns something like 1742812800000
fetch(`/api/events?since=${timestamp}`);

The backend receives 1742812800000 and interprets it as a Unix timestamp in seconds — which translates to the year 57,212. Cue the confused "why are no events showing up" support ticket.

This is the 10-digit vs 13-digit timestamp problem, and it trips up even experienced developers.

What Is a Unix Timestamp?

A Unix timestamp counts the number of seconds (or milliseconds) elapsed since January 1, 1970, 00:00:00 UTC — also called the Unix epoch.

1742812800 — 10 digits → seconds since epoch
1742812800000 — 13 digits → milliseconds since epoch

The same moment in time, just different units. The problem is that different languages and APIs use different conventions:

Language/Platform	Default Unit
JavaScript `Date.now()`	Milliseconds
JavaScript `new Date().getTime()`	Milliseconds
Python `time.time()`	Seconds (float)
Unix/Linux `date +%s`	Seconds
Most REST APIs	Seconds
Java `System.currentTimeMillis()`	Milliseconds
Go `time.Now().Unix()`	Seconds
Go `time.Now().UnixMilli()`	Milliseconds

See the mismatch? JavaScript defaults to milliseconds, most backend systems default to seconds.

How to Detect Which One You Have

A quick sanity check:

function detectTimestampUnit(ts) {
  // Current year is ~2026, which is ~1.74 billion seconds
  // or ~1.74 trillion milliseconds from epoch
  const SECONDS_IN_2020 = 1577836800;
  const SECONDS_IN_2100 = 4102444800;

  if (ts >= SECONDS_IN_2020 && ts <= SECONDS_IN_2100) {
    return 'seconds';
  } else if (ts >= SECONDS_IN_2020 * 1000 && ts <= SECONDS_IN_2100 * 1000) {
    return 'milliseconds';
  }
  return 'unknown';
}

console.log(detectTimestampUnit(1742812800));    // "seconds"
console.log(detectTimestampUnit(1742812800000)); // "milliseconds"

Or more bluntly: 10 digits = seconds, 13 digits = milliseconds. This holds true for any timestamp between 2001 and 2286.

The Conversion You Actually Need

// Seconds → Milliseconds (for JavaScript Date)
const tsSeconds = 1742812800;
const date = new Date(tsSeconds * 1000);
console.log(date.toISOString()); // "2026-03-24T08:00:00.000Z"

// Milliseconds → Seconds (for API calls)
const tsMs = Date.now();
const tsForApi = Math.floor(tsMs / 1000);
console.log(tsForApi); // 1742812800

// Get current timestamp in seconds
const now = Math.floor(Date.now() / 1000);

The Year 2038 Problem (Still Real)

If you're working with 32-bit signed integers to store Unix timestamps (common in legacy C/C++ code and older databases), you have a hard ceiling:

Max 32-bit signed int: 2,147,483,647
That's: January 19, 2038, 03:14:07 UTC

After that, the value overflows to negative — typically interpreted as December 13, 1901. If your system will still be running in 2038 (and many legacy systems will), this needs to be addressed. The fix is migrating to 64-bit integer storage.

Common API Pain Points

GitHub API uses ISO 8601 strings, not timestamps. Don't try to send a number.

Stripe uses seconds-based Unix timestamps throughout.

Twilio uses ISO 8601 as well.

Most database created_at columns store as ISO strings or native datetime types — convert before storing.

Quick Conversion Without Code

When debugging, you often just need a quick sanity check: "does this timestamp look right?"

For that, I keep datetimecalculator.app/unix-timestamp bookmarked. Paste in a 10- or 13-digit number, it auto-detects the unit and shows you the UTC and local time. Works the other way too — pick a date and get the timestamp back. Faster than firing up a Node.js REPL.

Defensive Coding Patterns

// Always be explicit in function signatures
function setExpiry(timestampSeconds) { ... }
function setExpiryMs(timestampMilliseconds) { ... }

// Or use a type wrapper (TypeScript)
type Seconds = number & { readonly __brand: "Seconds" };
type Milliseconds = number & { readonly __brand: "Milliseconds" };

function toSeconds(ms: Milliseconds): Seconds {
  return Math.floor(ms / 1000) as Seconds;
}

Naming your variables and parameters explicitly (timestampSeconds, expiryMs) eliminates an entire class of conversion bugs.

Summary

JavaScript gives you milliseconds. Most everything else wants seconds.
10 digits = seconds, 13 digits = milliseconds — use this to sanity-check unknown timestamps.
32-bit timestamp storage has a 2038 deadline. Migrate now if it applies to you.
Name your variables explicitly to prevent silent unit mismatches.

Date and time bugs are among the hardest to reproduce in production because they're often time-dependent or timezone-dependent. Getting the fundamentals right upfront saves a lot of pain later.

Hit a timestamp bug in production that cost you hours? I'd love to hear the war story.

Business Days vs Calendar Days: The Date Math Mistake That Breaks Your Deadlines

HAU — Tue, 24 Mar 2026 09:24:29 +0000

When a project manager says "deliver in 30 days", do they mean 30 calendar days or 30 working days? It sounds like a simple question, but getting it wrong can throw off your entire schedule — and your code.

This is one of those date-math problems that catches developers off guard more often than it should.

The Hidden Trap in Date Calculations

Let's say you need to calculate a deadline that is 20 business days from today (March 24, 2026). The naive approach:

const today = new Date();
const deadline = new Date(today);
deadline.setDate(today.getDate() + 20); // ❌ Wrong! This adds 20 calendar days

This gives you April 13 — but the actual 20th business day falls on April 21, because you skipped 4 weekends (8 days). That's a full week off.

Why Business Day Calculation is Harder Than It Looks

A correct business day calculator needs to:

Skip Saturdays and Sundays
Account for months with different lengths
Handle leap years
(Optionally) account for public holidays

Here's a minimal JavaScript implementation:

function addBusinessDays(startDate, daysToAdd) {
  const date = new Date(startDate);
  let added = 0;

  while (added < daysToAdd) {
    date.setDate(date.getDate() + 1);
    const day = date.getDay();
    if (day !== 0 && day !== 6) { // 0 = Sunday, 6 = Saturday
      added++;
    }
  }

  return date;
}

// Usage
const result = addBusinessDays(new Date(), 20);
console.log(result.toDateString()); // Mon Apr 21 2026

And to count business days between two dates:

function countBusinessDays(startDate, endDate) {
  const start = new Date(startDate);
  const end = new Date(endDate);
  let count = 0;

  const current = new Date(start);
  while (current <= end) {
    const day = current.getDay();
    if (day !== 0 && day !== 6) {
      count++;
    }
    current.setDate(current.getDate() + 1);
  }

  return count;
}

Real-World Scenarios Where This Matters

Invoice payment terms — "Net 30" in most business contexts means 30 calendar days, but some contracts specify working days. Always clarify.

Software delivery estimates — When your team estimates a sprint as "10 working days", that's two calendar weeks. Mixing these up in your project tracker causes phantom deadlines.

Legal and compliance deadlines — Court filings and regulatory submissions almost always use business days. Missing by one day because you counted a Saturday is not an acceptable excuse.

SLA calculations — Response time SLAs in B2B contracts frequently exclude weekends. Your incident management system needs to know this.

The Two Modes You Actually Need

In practice, there are two distinct calculations:

Mode	Question	Example
Count	How many business days between A and B?	From contract signing to delivery
Add	What date is N business days from today?	When is this invoice due?

Both are useful in different contexts. For quick checks without writing code, I've been using datetimecalculator.app/business-days — it handles both modes and shows you the breakdown (total calendar days, weekends, business days) at a glance.

A Note on Holidays

The examples above only exclude weekends. If you need to exclude public holidays too, you're looking at a much more complex problem:

Which country/region's holidays?
What about regional holidays within a country?
Do you include optional/bank holidays?

For most internal tooling, weekend-only exclusion is sufficient. For anything customer-facing or legally binding, you'll want a proper holidays library or API.

Takeaway

Date arithmetic is deceptively tricky. The rule of thumb: always clarify whether a deadline is calendar days or business days, and if it's business days, make sure your code (and your tools) are actually counting correctly.

A 5-day discrepancy between what you calculated and what the client expected is an unpleasant conversation. One that's entirely avoidable.

What date math pitfalls have tripped you up? Drop them in the comments.

Convert CSV or Excel to JSON in Your Browser — No Upload, No Server

HAU — Tue, 24 Mar 2026 02:31:37 +0000

The Tool

JSON Buddy includes a CSV/Excel converter that runs 100% client-side. Click the CSV/Excel to JSON tab in the toolbar and you get a dedicated conversion panel. No account, no upload, no file sent anywhere.

Supported Input Formats

Format	Extension	Notes
CSV	`.csv`	Comma-separated, UTF-8
TSV	`.tsv`	Tab-separated (also works if you paste directly from Excel)
Semicolon-separated	`.csv`	Common in European locales
Pipe-separated	`.txt`	`
Excel	{% raw %}`.xlsx`, `.xls`	Upload the file directly

The delimiter is detected automatically. You can also override it manually.

How to Use

Option 1: Upload a file

Click CSV/Excel to JSON in the toolbar
Drag & drop your .csv or .xlsx file onto the upload area
The JSON output appears instantly on the right

Option 2: Paste directly

If you copied a table from Excel, Google Sheets, or Notion, just paste it into the text area. Tab-delimited content (the default clipboard format for spreadsheets) is parsed automatically.

name    age city    active
Alice   30  Berlin  true
Bob 25  Paris   false
Carol   35  Tokyo   true

Paste that and get:

[
  { "name": "Alice", "age": 30, "city": "Berlin", "active": true },
  { "name": "Bob",   "age": 25, "city": "Paris",  "active": false },
  { "name": "Carol", "age": 35, "city": "Tokyo",  "active": true }
]

Automatic Type Inference

By default, JSON Buddy infers types from cell values:

Cell value	JSON type
`42`	`number` (integer)
`3.14`	`number` (float)
`true` / `false`	`boolean`
`null` / empty	`null`
`"hello"`	`string`

So a column of ages becomes a JSON number array, not a string array — which is almost always what you want when seeding a database or writing tests.

You can toggle type inference off if you need everything as strings.

Real Examples

Seeding a database

You have a users.csv from a staging database export:

id,name,email,role,created_at
1,Alice,alice@example.com,admin,2024-01-15
2,Bob,bob@example.com,user,2024-02-20
3,Carol,carol@example.com,user,2024-03-05

Output:

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com",
    "role": "admin",
    "created_at": "2024-01-15"
  },
  ...
]

Paste this directly into your seed script or API test fixture.

Mocking an API response

You're building a front end and the back end isn't ready. Export a table from Notion, convert to JSON, drop it into your mock server or public/mock-data.json.

Data pipeline testing

A data engineer sends you a .xlsx with sample records to validate your ingestion pipeline. Upload it, get JSON, feed it to your tests — without ever writing a pandas script.

Copy the Output Back to the JSON Editor

Once your data is converted, there's a "Use in Editor" button that loads the JSON into the main formatter. From there you can:

Format and inspect it in the tree view
Run it through the Code Gen to generate typed structs for your language
Use Find & Replace to do a bulk value substitution before using it

Why Not Just Use Python?

You can, of course:

import csv, json

with open('data.csv') as f:
    rows = list(csv.DictReader(f))
print(json.dumps(rows, indent=2))

But that requires Python installed, a terminal, writing and running a script. For a quick one-off conversion during development, a browser tool is faster. And for non-developers (PMs, data analysts, QA engineers), a no-code option is often the only practical one.

Privacy Note

The file never leaves your browser. For Excel files, the parsing uses the SheetJS library running client-side. No file data is transmitted anywhere.

This matters when the spreadsheet contains:

Customer PII (GDPR-relevant)
Financial data
Internal employee records
Unreleased product information

Try It

👉 json-formatter.net — click the CSV/Excel to JSON tab

Works on desktop and mobile. Installable as a PWA for offline use.

Also in this series:

Privacy-first JSON formatting — no uploads, works offline
Generate Go structs, TypeScript interfaces, Java classes from JSON
Find and replace in JSON with wildcard support

Stop Writing Structs by Hand: Generate Go, Java, TypeScript, and 8 More from JSON

HAU — Tue, 24 Mar 2026 02:29:48 +0000

Automatic Code Generation from JSON

JSON Buddy's Code Generator converts any JSON object into a ready-to-use struct or class definition. Paste JSON, pick a language, copy the output. Done in seconds.

Supported languages: Go · Java · TypeScript · Python · Rust · C# · PHP · Ruby · C · C++ · Zig

How to Use It

Go to json-formatter.net
Paste your JSON into the editor
Click Code Gen in the toolbar
Select your target language
Click Copy

That's it. No account, no API call, no upload. The generation runs entirely in your browser.

Examples

Input JSON

{
  "id": 42,
  "username": "alice_dev",
  "email": "alice@example.com",
  "is_active": true,
  "score": 98.5,
  "address": {
    "city": "Berlin",
    "country": "DE",
    "zip": "10115"
  },
  "tags": ["admin", "beta-user"]
}

Go

package main

type Root struct {
    Id       int64   `json:"id"`
    Username string  `json:"username"`
    Email    string  `json:"email"`
    IsActive bool    `json:"is_active"`
    Score    float64 `json:"score"`
    Address  Address `json:"address"`
    Tags     []string `json:"tags"`
}

type Address struct {
    City    string `json:"city"`
    Country string `json:"country"`
    Zip     string `json:"zip"`
}

Go structs are generated with proper json:"..." tags, exported field names (PascalCase), and nested objects as separate named structs.

TypeScript

interface Root {
  id: number;
  username: string;
  email: string;
  is_active: boolean;
  score: number;
  address: Address;
  tags: string[];
}

interface Address {
  city: string;
  country: string;
  zip: string;
}

Python

from __future__ import annotations
from dataclasses import dataclass
from typing import Any, List, Optional

@dataclass
class Address:
    city: str
    country: str
    zip: str

@dataclass
class Root:
    id: int
    username: str
    email: str
    is_active: bool
    score: float
    address: Address
    tags: List[str]

Python output uses @dataclass with snake_case field names. Dependency classes are emitted before the root class.

Rust

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Address {
    pub city: String,
    pub country: String,
    pub zip: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Root {
    pub id: i64,
    pub username: String,
    pub email: String,
    #[serde(rename = "is_active")]
    pub is_active: bool,
    pub score: f64,
    pub address: Address,
    pub tags: Vec<String>,
}

Rust output includes #[derive(Serialize, Deserialize)] and #[serde(rename = "...")] attributes when field names differ from snake_case.

Java

import java.util.List;

public class Root {
    private int id;
    private String username;
    private String email;
    private boolean isActive;
    private double score;
    private Address address;
    private List<String> tags;

    public int getId() { return id; }
    public void setId(int id) { this.id = id; }
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    // ... getters/setters for all fields
}

C

using System.Collections.Generic;
using System.Text.Json.Serialization;

public class Root
{
    public int Id { get; set; }
    public string Username { get; set; }
    public string Email { get; set; }
    [JsonPropertyName("is_active")]
    public bool IsActive { get; set; }
    public double Score { get; set; }
    public Address Address { get; set; }
    public List<string> Tags { get; set; }
}

Zig

const Address = struct {
    city:    []const u8,
    country: []const u8,
    zip:     []const u8,
};

const Root = struct {
    id:        i64,
    username:  []const u8,
    email:     []const u8,
    is_active: bool,
    score:     f64,
    address:   Address,
    tags:      [][]const u8,
};

What It Handles Automatically

Nested objects → Each nested object becomes its own struct/class, named after the key.

Arrays → The element type is inferred from the first item. string[] in TypeScript, Vec<String> in Rust, []string in Go, etc.

Type inference → Integer vs float is detected from the actual value. 42 → int64/int/i64. 3.14 → float64/double/f64.

Naming conventions → Each language gets its own convention: PascalCase fields in Go and C#, camelCase in Java, snake_case in Python and Rust, original key names in TypeScript.

Null values → Typed as the language's nullable/optional type: interface{} in Go, Optional[Any] in Python, object? in C#.

Real-World Workflow

The most common use case: you're integrating a third-party API and need to model the response.

# Fetch the response, copy it
curl https://api.example.com/users/1 | pbcopy

# Paste into JSON Buddy, click Code Gen, select Go
# Copy the generated struct into your codebase

What used to take 10-20 minutes of careful typing (and probably a typo or two) now takes 30 seconds.

Try It

👉 json-formatter.net — click Code Gen after pasting your JSON.

All generation is client-side. Your JSON never leaves the browser.

Also in this series:

Privacy-first JSON formatting — no uploads, works offline
Convert CSV and Excel to JSON in your browser
Find and replace in JSON with wildcard support