Unix timestamps in TypeScript.

Get current Unix timestamp

Same as JavaScript at runtime — TypeScript just adds compile-time guarantees.

Typed return value

const epochSec: number = Math.floor(Date.now() / 1000);
const epochMs: number = Date.now();

Branded types for safety

type Seconds = number & { __brand: "seconds" };
type Milliseconds = number & { __brand: "milliseconds" };

function nowSec(): Seconds {
  return Math.floor(Date.now() / 1000) as Seconds;
}

function nowMs(): Milliseconds {
  return Date.now() as Milliseconds;
}

// Now the compiler prevents mixing them up
const t: Seconds = nowSec();
// const wrong: Milliseconds = t; // ✗ type error

Convert epoch to Date

TypeScript's Date is identical to JavaScript's. Type the function signature for clarity.

Helper functions

function epochSecToDate(sec: number): Date {
  return new Date(sec * 1000);
}

function epochMsToDate(ms: number): Date {
  return new Date(ms);
}

function toIso(sec: number): string {
  return new Date(sec * 1000).toISOString();
}

With branded types

function secondsToDate(s: Seconds): Date {
  return new Date(s * 1000);
}

function millisecondsToDate(ms: Milliseconds): Date {
  return new Date(ms);
}

Format with Intl.DateTimeFormat

Same API as JavaScript, but TypeScript gives you autocomplete for the options.

Typed options

const options: Intl.DateTimeFormatOptions = {
  timeZone: 'Asia/Tokyo',
  year: 'numeric',
  month: 'short',
  day: '2-digit',
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit',
  hour12: false,
  timeZoneName: 'short',
};
const formatter = new Intl.DateTimeFormat('en-US', options);
formatter.format(new Date(1735689600 * 1000));

IANA timezone type

// Modern TypeScript (lib: ES2022) has supportedValuesOf typed:
const zones: string[] = Intl.supportedValuesOf('timeZone');

Defensive parsing

Build a typed wrapper that returns a discriminated union for safer error handling.

Result type

type ParseResult =
  | { ok: true; ts: number; detected: string }
  | { ok: false; error: string };

function parseTimestamp(input: string): ParseResult {
  const s = input.trim();
  if (!s) return { ok: false, error: "empty input" };

  if (/^-?\d+$/.test(s)) {
    const n = parseInt(s, 10);
    const absLen = Math.abs(n).toString().length;
    if (absLen <= 11) return { ok: true, ts: n, detected: "seconds" };
    if (absLen <= 13) return { ok: true, ts: n / 1000, detected: "milliseconds" };
  }

  const d = new Date(s);
  if (!isNaN(d.getTime())) {
    return { ok: true, ts: d.getTime() / 1000, detected: "date string" };
  }

  return { ok: false, error: "could not parse" };
}

Common gotchas

TypeScript-specific things to watch for.

Date is not immutable

// Same gotcha as JavaScript:
const d = new Date(2025, 0, 1);
d.setDate(d.getDate() + 1); // mutates d!
// Prefer creating new Date instances:
const tomorrow = new Date(d.getTime() + 86400_000);

Number doesn't distinguish s vs ms

// number is just a number. TypeScript can't prevent this:
const sec = 1735689600;
const date = new Date(sec); // ✗ 1970! (treats it as ms)
// Use branded types or always include the * 1000 explicitly.

Use the converter

Need to quickly check what a specific timestamp converts to? Use the main converter — paste any value and get every format back.

Working with many timestamps at once? Try the batch converter — paste a list, get a CSV or JSON file back.