menu
SARO Lab
Docs
light_mode
languageEnglish

Infinite Unixtime

GitHubnpm

A date and timezone library that handles every range of time exactly, from BC to an unbounded future. Every object stays immutable, which keeps local mean time (LMT) from skewing old dates, and format parsing plus timezone support make it just as usable from npm as from a vanilla bundle.

1970-01-01 (Thu) 00:00:00.000 Z
unixtime · Seconds
unixtime · Millisecond
Year
Month
Day
Hour
Minute
Second
Millisecond
1970-01
Sun
Mon
Tue
Wed
Thu
Fri
Sat
Hour00
Minute00
Second00
Millisecond000
TZUTC±00:00
ISO 8601
1970-01-01T00:00:00.000Z
1970-01-01T00:00:00.000Z

API reference

Install

bash
npm install infinite-unixtime
pnpm add infinite-unixtime
yarn add infinite-unixtime
javascript
import { Unixtime } from 'infinite-unixtime';

Timezone offset

There is no timezone database. Every API takes a fixed offset in minutes, using the same sign as Date.prototype.getTimezoneOffset — so no local mean time leaks into old dates.

javascript
// UTC+09:00 -> -540, UTC -> 0, UTC-03:30 -> 210
const KST = -540;
const UTC = 0;

// The browser's own offset, same sign convention.
const local = new Date().getTimezoneOffset();

// Every API takes the offset last; omitting it uses the browser's.
Unixtime.fromUtc(2026, 3, 31, 5, 30).format('yyyy-MM-dd HH:mm', KST);
//=> '2026-03-31 14:30'

Create

javascript
Unixtime.now();
Unixtime.fromDate(new Date());

Unixtime.fromMillis(1774935005123n).toIsoStringUtc();
//=> '2026-03-31T05:30:05.123Z'

Unixtime.fromSeconds(1774935005).toIsoStringUtc();
//=> '2026-03-31T05:30:05.000Z'

// year, month, day, hour, minute, second, millisecond, timezoneOffset
Unixtime.from(2026, 3, 31, 14, 30, 0, 0, -540).toIsoStringUtc();
//=> '2026-03-31T05:30:00.000Z'

Unixtime.fromUtc(2026, 3, 31, 14, 30).toIsoStringUtc();
//=> '2026-03-31T14:30:00.000Z'
javascript
// No year limit — the value is one bigint of milliseconds.
Unixtime.fromUtc(23948923423421773421234n, 1, 31).timestamp;
//=> 755755026924596579546592556800000n

Unixtime.fromUtc(-2000, 2, 29).toIsoStringUtc();
//=> '-2000-02-29T00:00:00.000Z'

// A date that does not exist throws.
Unixtime.fromUtc(2026, 2, 29);
//=> Error: Unixtime: Invalid Date: 2026-2-29 0:0:0.0

Parse

Parsing follows the same format as formatting. A mismatch throws rather than guessing.

javascript
Unixtime.parseUtc('2026-03-31T14:30:00.000Z', 'yyyy-MM-ddTHH:mm:ss.SSSXXX').toIsoStringUtc();
//=> '2026-03-31T14:30:00.000Z'

Unixtime.parseUtc('20260331143000000', 'yyyyMMddHHmmssSSS').toIsoStringUtc();
//=> '2026-03-31T14:30:00.000Z'

Unixtime.parseUtc('2026-03-31 PM 09:30', 'yyyy-MM-dd a hh:mm').toIsoStringUtc();
//=> '2026-03-31T21:30:00.000Z'

// An offset in the text wins over the argument.
Unixtime.parse('2026-03-31T14:30:00.000+09:00', 'yyyy-MM-ddTHH:mm:ss.SSSXXX', 0).toIsoStringUtc();
//=> '2026-03-31T05:30:00.000Z'

Unixtime.parseUtc('2026-03-31 00:00 +0900', 'yyyy-MM-dd HH:mm XXX').toIsoStringUtc();
//=> '2026-03-30T15:00:00.000Z'

// Missing fields default to 1970-01-01 00:00:00.000
Unixtime.parseUtc('12:34', 'HH:mm').timestamp;
//=> 45240000n

Unixtime

The value comes back as a bigint by default; the $-prefixed getters return a number.

javascript
// 2026-03-31 14:30:05.123 +09:00
const u = Unixtime.fromUtc(2026, 3, 31, 5, 30, 5, 123);

u.timestamp;    //=> 1774935005123n   bigint, milliseconds
u.time;         //=> 1774935005n      bigint, seconds
u.$timestamp;   //=> 1774935005123    number, milliseconds
u.$time;        //=> 1774935005       number, seconds

Date-time, time

Prefer this over the individual getters when you need several fields — the carry is resolved once, which also keeps negative timestamps correct.

javascript
const u = Unixtime.fromUtc(2026, 3, 31, 5, 30, 5, 123);

u.toDateTimeDetail(-540);
//=> { leapYear: false, year: 2026n, month: 3, day: 31, week: 2,
//     hours: 14, minutes: 30, seconds: 5, milliseconds: 123,
//     timezoneOffset: -540 }

u.toTimeDetail(-540);
//=> { hours: 14, minutes: 30, seconds: 5, milliseconds: 123,
//     timezoneOffset: -540 }

Format

javascript
const u = Unixtime.fromUtc(2026, 3, 31, 5, 30, 5, 123);

u.format('yyyy-MM-dd (E) HH:mm:ss.SSS XXX', -540);
//=> '2026-03-31 (Tue) 14:30:05.123 +09:00'

u.formatUtc('yyyy-MM-dd HH:mm');
//=> '2026-03-31 05:30'

u.toString(-540);
//=> '2026-03-31 (Tue) PM 02:30 05.123 +09:00'

u.toStringUtc();
//=> '2026-03-31 (Tue) AM 05:30 05.123 Z'

u.toIsoString(-540);
//=> '2026-03-31T14:30:05.123+09:00'

u.toIsoStringUtc();
//=> '2026-03-31T05:30:05.123Z'
txt
yyyy  year, no padding limit      yy   2-digit year
MM    month 01-12                dd   day 01-31
HH    hour 00-23                 hh   hour 01-12
a     AM / PM                    mm   minute 00-59
ss    second 00-59               SSS  millisecond 000-999
E     Tue        EE  Tuesday     e    day of week 0-6
XXX   +09:00 / Z                 '..' literal text

Relative time

toRelative gives back the time relative to now.

javascript
const base = Unixtime.fromUtc(2026, 3, 31, 12, 0);
const u = base.plusMinutes(-90);

u.toRelative({ base, locale: 'en' });   //=> '1 hour ago'
u.toRelative({ base, locale: 'ko' });   //=> '1시간 전'

u.toRelativeDetail({ base });
//=> { value: -1, unit: 'hour', millis: -5400000n }

// Past the limit it returns null instead of a stale phrase.
base.plusDays(-31).toRelativeDetail({ base });
//=> null
javascript
u.toRelative({
  base: Unixtime.now(),          // what to measure against
  limit: { days: 30 },           // false to disable
  units: ['day', 'hour'],        // day | hour | minute | second
  future: 'keep',                // 'now' clamps the future to 0
  locale: 'ko',
  numeric: 'auto',               // 'always' | 'auto'
  style: 'long',                 // 'long' | 'short' | 'narrow'
});

Date

Every value takes the offset last and falls back to the browser timezone.

javascript
// 2026-03-31 14:30:05.123 +09:00
const u = Unixtime.fromUtc(2026, 3, 31, 5, 30, 5, 123);

u.getYear(-540);            //=> 2026n
u.getYearNumber(-540);      //=> 2026
u.getMonth(-540);           //=> 3
u.getDay(-540);             //=> 31
u.getLastDayOfMonth(-540);  //=> 31
u.getDayOfYear(-540);       //=> 90
u.isLeapYear(-540);         //=> false

Weekday and week

The plain week functions start on Sunday and need one day in the week; the ISO ones start on Monday and need four.

javascript
const u = Unixtime.fromUtc(2026, 3, 31, 5, 30, 5, 123);

u.getWeek(-540);        //=> 2          0 = Sunday
u.getWeekShort(-540);   //=> 'Tue'
u.getWeekLong(-540);    //=> 'Tuesday'

u.getWeekOfMonth(-540);         //=> 5
u.getLastWeekOfMonth(-540);     //=> 5
u.getWeekOfYear(-540);          //=> 14
u.getLastWeekOfYear(-540);      //=> 53

u.getIsoWeekOfMonth(-540);      //=> 5
u.getLastIsoWeekOfMonth(-540);  //=> 5
u.getIsoWeekOfYear(-540);       //=> 14
u.getLastIsoWeekOfYear(-540);   //=> 53

Time

javascript
const u = Unixtime.fromUtc(2026, 3, 31, 5, 30, 5, 123);

u.getHours(-540);         //=> 14
u.getHours12(-540);       //=> 2
u.getAmPm(-540);          //=> 'PM'
u.getMinutes(-540);       //=> 30
u.getSeconds(-540);       //=> 5
u.getMilliseconds(-540);  //=> 123

Move

Every instance is immutable — each call returns a new one. Month and year keep the day, clamping to the last of the month when it does not exist.

javascript
const u = Unixtime.fromUtc(2026, 1, 31);

u.plusMillis(500);
u.plusSeconds(-30);
u.plusMinutes(15);
u.plusHours(-8);

u.plusDays(7).toIsoStringUtc();
//=> '2026-02-07T00:00:00.000Z'

// The day is kept, then clamped to the last of the month.
u.plusMonth(1, 0).toIsoStringUtc();
//=> '2026-02-28T00:00:00.000Z'

Unixtime.fromUtc(2024, 1, 31).plusMonth(1, 0).toIsoStringUtc();
//=> '2024-02-29T00:00:00.000Z'

u.plusYear(-1, 0).toIsoStringUtc();
//=> '2025-01-31T00:00:00.000Z'

Compare

Comparisons accept anything a factory accepts, so a Date or a raw number needs no conversion.

javascript
const a = Unixtime.fromUtc(2026, 3, 31);
const b = Unixtime.fromUtc(2026, 4, 1);

a.before(b);     //=> true
a.beforeEq(b);   //=> true
a.after(b);      //=> false
a.afterEq(b);    //=> false

a.between(Unixtime.fromUtc(2026, 1, 1), b);
//=> true

// Accepts Unixtime | number | bigint | string | Date.
a.before(new Date());

// Second argument compares by seconds instead of milliseconds.
a.before(b, true);

Types

typescript
type TimeInput = Unixtime | number | bigint | string | Date;
type RelativeUnit = 'day' | 'hour' | 'minute' | 'second';

type DateTimeDetail = {
  readonly leapYear: boolean;
  readonly year: bigint;
  readonly month: number;
  readonly day: number;
  readonly hours: number;
  readonly minutes: number;
  readonly seconds: number;
  readonly milliseconds: number;
  readonly week: number;
  readonly timezoneOffset: number;
};

type RelativeDetail = {
  readonly value: number;
  readonly unit: RelativeUnit;
  readonly millis: bigint;
};