unix_timestamp 1.0.0

A complete zero-dependency Dart and Flutter package for Unix timestamp operations.

unix_timestamp

A complete, zero-runtime-dependency Dart and Flutter package for Unix timestamp operations: get, convert, compare, format, humanize, validate, arithmetic, ranges, scheduling, timezone-awareness, and serialization.

Features

Category	What it covers
GET	Current seconds, milliseconds, microseconds, simulated nanoseconds, epoch
CONVERT	Unix seconds/milliseconds/microseconds/nanoseconds, DateTime, ISO 8601, HTTP dates, date-only strings
EPOCH TOOLS	Unit conversion, auto-detected summaries, flexible date input, batch conversion, hex, Year 2038 checks
TIME ZONES	Current device zone, available fixed-offset zones, common aliases, zone formatting
FORMAT	Token formatting and date/time/log/slug presets
HUMANIZE	Relative labels such as just now, yesterday, in 2 days, 3m
ARITHMETIC	Add, subtract, calendar months/years, round, floor, ceil
DIFF	Seconds through approximate years plus structured breakdowns
COMPARE	Past/future, today, week/month/year, weekend, range checks
VALIDATE	Unit detection, normalization, year-2100 bounds, leap year, DST heuristic
PERIODS	Start/end boundaries for minute through quarter
RANGE	Inclusive ranges, overlap, merge, split, list, map
SCHEDULER	Countdown, expiry, progress, TTL, session validity
SERIALIZATION	JSON, Firestore-like, Hive-like, Protobuf-like shapes
EXTENSIONS	Fluent APIs on int and DateTime

Installation

dependencies:
  unix_timestamp: ^0.1.0

import 'package:unix_timestamp/unix_timestamp.dart';

GET

final seconds = UnixTimestamp.now();
final milliseconds = UnixTimestamp.nowMs();
final microseconds = UnixTimestamp.nowUs();
final nanoseconds = UnixTimestamp.nowNano();
final epoch = UnixTimestamp.epoch(); // 0

final zone = UnixTimestamp.currentTimeZone();
final zoneName = UnixTimestamp.currentTimeZoneName();
final zoneOffset = UnixTimestamp.currentTimeZoneOffsetString(); // '+03:00'

TIME ZONES

final current = UnixTimestamp.currentTimeZone();
final currentZone = UnixTimestamp.currentUnixTimeZone();

final zones = UnixTimestamp.availableTimeZones();
final zoneNames = UnixTimestamp.availableTimeZoneNames();

UnixTimestamp.findTimeZone('Asia/Riyadh');
UnixTimestamp.requireTimeZone('Jeddah');
UnixTimestamp.isTimeZoneAvailable('Asia/Riyadh'); // true
UnixTimestamp.timeZoneOffset('Asia/Riyadh'); // Duration(hours: 3)
UnixTimestamp.timeZoneOffsetString('Asia/Riyadh'); // +03:00
UnixTimestamp.getTimeZone('Asia/Riyadh');

UnixTimestamp.toDateTimeZone(1779000216, 'Asia/Riyadh');
// 2026-05-17 09:43:36.000

UnixTimestamp.formatInTimeZone(1779000216, 'yyyy-MM-dd HH:mm:ss', 'Asia/Riyadh');
// 2026-05-17 09:43:36

1779000216.toDateTimeZone('Asia/Riyadh');
1779000216.formatInTimeZone('HH:mm:ss', 'Asia/Riyadh'); // 09:43:36

Timezone support is intentionally zero-dependency: the package provides fixed UTC offsets (UTC-12:00 through UTC+14:00) and common aliases such as Asia/Riyadh, Jeddah, UTC, GMT, and +03:00. It does not ship an IANA timezone database or historical DST rules.

CONVERT

const ts = 1704067200;

final utc = UnixTimestamp.toDateTimeUtc(ts);
final local = UnixTimestamp.toDateTimeLocal(ts);
final riyadhWallClock = UnixTimestamp.toDateTimeOffset(ts, const Duration(hours: 3));
final seconds = UnixTimestamp.fromDateTime(DateTime.utc(2024, 1, 1));
final ms = UnixTimestamp.fromDateTimeMs(DateTime.utc(2024, 1, 1));
final us = UnixTimestamp.fromDateTimeUs(DateTime.utc(2024, 1, 1));
final ns = UnixTimestamp.fromDateTimeNano(DateTime.utc(2024, 1, 1));

final fromMs = UnixTimestamp.msToDateTimeUtc(1704067200000);
final fromUs = UnixTimestamp.usToDateTimeUtc(1704067200000000);
final fromNs = UnixTimestamp.nanoToDateTimeUtc(1704067200000000000);
final iso = UnixTimestamp.toIso8601(ts);
final fromIso = UnixTimestamp.fromIso8601('2024-01-01T00:00:00.000Z');
final http = UnixTimestamp.toHttpDate(ts);
final fromHttp = UnixTimestamp.fromHttpDate('Mon, 01 Jan 2024 00:00:00 GMT');
final fromDate = UnixTimestamp.fromDateString('2024-01-01');
final fromFlexible = UnixTimestamp.fromDateInput(
  '17-05-2026 06:43:36',
  format: UnixDateInputFormat.dmy,
);

Example: 1779000216

const ts = 1779000216;

UnixTimestamp.toDateTimeUtc(ts);
// 2026-05-17 06:43:36.000Z

UnixTimestamp.toDateTimeOffset(ts, const Duration(hours: 3));
// 2026-05-17 09:43:36.000

UnixTimestamp.fromDateTime(DateTime.utc(2026, 5, 17, 6, 43, 36));
// 1779000216

UnixTimestamp.fromIso8601('2026-05-17T06:43:36Z');
// 1779000216

UnixTimestamp.fromDateString('2026-05-17');
// 1778976000, midnight UTC at the start of 2026-05-17

EPOCH CONVERSION TOOLS

UnixTimestamp.convertUnit(
  1779000216000,
  to: UnixTimestampUnit.seconds,
); // 1779000216

UnixTimestamp.convertUnit(
  1779000216,
  from: UnixTimestampUnit.seconds,
  to: UnixTimestampUnit.nanoseconds,
); // 1779000216000000000

UnixTimestamp.fromDateTimeUnit(
  DateTime.utc(2026, 5, 17, 6, 43, 36),
  UnixTimestampUnit.milliseconds,
); // 1779000216000

UnixTimestamp.toDateTimeUnit(1779000216000);
// 2026-05-17 06:43:36.000Z

UnixTimestamp.nowAs(UnixTimestampUnit.milliseconds);
UnixTimestamp.startOfTodayAs(UnixTimestampUnit.seconds);
UnixTimestamp.endOfTodayAs(UnixTimestampUnit.milliseconds);

final info = UnixTimestamp.epochInfo(1779000216000);

info['unit']; // milliseconds
info['seconds']; // 1779000216
info['milliseconds']; // 1779000216000
info['microseconds']; // 1779000216000000
info['nanoseconds']; // 1779000216000000000
info['iso']; // 2026-05-17T06:43:36.000Z
info['httpDate']; // Sun, 17 May 2026 06:43:36 GMT
info['dateTime']; // 2026-05-17 06:43:36
info['timezone']; // current device timezone details

final nanoInfo = UnixTimestamp.epochInfo(
  1779000216000000000,
  unit: UnixTimestampUnit.nanoseconds,
);

UnixTimestamp.fromDateInput('05/17/2026 06:43:36', format: UnixDateInputFormat.mdy);
UnixTimestamp.fromDateInput('17-05-2026 06:43:36', format: UnixDateInputFormat.dmy);
UnixTimestamp.fromDateInput('Sun, 17 May 2026 06:43:36 GMT');

UnixTimestamp.batchNormalizeToSeconds([1779000216, 1779000216000]);
UnixTimestamp.batchEpochInfo([1779000216, 1779000216000]);

UnixTimestamp.secondsToDurationBreakdown(90061);
// {'years': 0, 'months': 0, 'weeks': 0, 'days': 1, 'hours': 1, 'minutes': 1, 'seconds': 1}

UnixTimestamp.toHex(1779000216); // 0x6a096398
UnixTimestamp.fromHex('0x6a096398'); // 1779000216

UnixTimestamp.maxInt32Timestamp(); // 2147483647
UnixTimestamp.year2038LimitUtc(); // 2038-01-19 03:14:07.000Z
UnixTimestamp.isYear2038Safe(1779000216); // true

FORMAT

UnixTimestamp.format(1704067200, 'yyyy-MM-dd HH:mm:ss EEEE');
UnixTimestamp.format(1779000216, 'EEEE, MMM dd yyyy'); // Sunday, May 17 2026
UnixTimestamp.format(1779000216, 'EEEE, MMMM dd yyyy'); // Sunday, May 17 2026
UnixTimestamp.toDate(1704067200); // 2024-01-01
UnixTimestamp.toTime(1704067200); // 00:00:00
UnixTimestamp.toDateTimeString(1704067200); // 2024-01-01 00:00:00
UnixTimestamp.toDateTimeMs(1704067200); // 2024-01-01 00:00:00.000
UnixTimestamp.toSlug(1704067200); // 20240101-000000
UnixTimestamp.toLogFormat(1704067200); // [2024-01-01 00:00:00]

HUMANIZE

UnixTimestamp.humanize(UnixTimestamp.now() - 60); // 1 minute ago
UnixTimestamp.humanizeFrom(1704067140, 1704067200); // 1 minute ago
UnixTimestamp.humanizeShort(UnixTimestamp.now() - 180); // 3m

ARITHMETIC

final ts = 1704067200;

UnixTimestamp.addSeconds(ts, 30);
UnixTimestamp.addMinutes(ts, 5);
UnixTimestamp.addHours(ts, 2);
UnixTimestamp.addDays(ts, 7);
UnixTimestamp.addWeeks(ts, 1);
UnixTimestamp.addMonths(ts, 1);
UnixTimestamp.addYears(ts, 1);

UnixTimestamp.subtractSeconds(ts, 30);
UnixTimestamp.subtractMinutes(ts, 5);
UnixTimestamp.subtractHours(ts, 2);
UnixTimestamp.subtractDays(ts, 7);

UnixTimestamp.roundToMinute(ts + 31);
UnixTimestamp.roundToHour(ts + 1800);
UnixTimestamp.roundToDay(ts + 43200);
UnixTimestamp.floorToHour(ts + 1);
UnixTimestamp.ceilToHour(ts + 1);

DIFF

UnixTimestamp.diffSeconds(1704067260, 1704067200);
UnixTimestamp.diffMinutes(1704067260, 1704067200);
UnixTimestamp.diffHours(1704070800, 1704067200);
UnixTimestamp.diffDays(1704153600, 1704067200);
UnixTimestamp.diffWeeks(1704672000, 1704067200);
UnixTimestamp.diffMonths(1706659200, 1704067200); // approximate
UnixTimestamp.diffYears(1735689600, 1704067200); // approximate
UnixTimestamp.diffBreakdown(1704249910, 1704067200);

COMPARE

UnixTimestamp.isBefore(1, 2);
UnixTimestamp.isAfter(2, 1);
UnixTimestamp.isSame(1, 1);
UnixTimestamp.isPast(UnixTimestamp.now() - 1);
UnixTimestamp.isFuture(UnixTimestamp.now() + 1);
UnixTimestamp.isToday(UnixTimestamp.now());
UnixTimestamp.isYesterday(UnixTimestamp.now() - 86400);
UnixTimestamp.isTomorrow(UnixTimestamp.now() + 86400);
UnixTimestamp.isThisWeek(UnixTimestamp.now());
UnixTimestamp.isThisMonth(UnixTimestamp.now());
UnixTimestamp.isThisYear(UnixTimestamp.now());
UnixTimestamp.isWeekend(1704499200);
UnixTimestamp.isWeekday(1704067200);
UnixTimestamp.isRecent(UnixTimestamp.now(), withinSeconds: 5);
UnixTimestamp.isSameDay(1704067200, 1704070800);
UnixTimestamp.isSameMonth(1704067200, 1704153600);
UnixTimestamp.isSameYear(1704067200, 1735603200);
UnixTimestamp.isBetween(2, 1, 3);

VALIDATE

UnixTimestamp.isValidSeconds(1704067200);
UnixTimestamp.isValidMs(1704067200000);
UnixTimestamp.isValidUs(1704067200000000);
UnixTimestamp.isValidNs(1704067200000000000);

UnixTimestamp.detectUnit(1704067200000); // milliseconds
UnixTimestamp.detectUnit(1704067200000000000); // nanoseconds
UnixTimestamp.normalizeToSeconds(1704067200000); // 1704067200
UnixTimestamp.normalizeToSeconds(1779000216000); // 1779000216
UnixTimestamp.normalizeToMilliseconds(1704067200); // 1704067200000
UnixTimestamp.normalizeToMicroseconds(1704067200); // 1704067200000000
UnixTimestamp.normalizeToNanoseconds(1704067200); // 1704067200000000000
UnixTimestamp.isLeapYear(1704067200);
UnixTimestamp.isDST(UnixTimestamp.now()); // local timezone heuristic

PERIODS

UnixTimestamp.startOfMinute(1704067231);
UnixTimestamp.endOfMinute(1704067200);
UnixTimestamp.startOfHour(1704067500);
UnixTimestamp.endOfHour(1704067200);
UnixTimestamp.startOfDay(1704110400);
UnixTimestamp.endOfDay(1704067200);
UnixTimestamp.startOfWeek(1704067200);
UnixTimestamp.endOfWeek(1704067200);
UnixTimestamp.startOfMonth(1704067200);
UnixTimestamp.endOfMonth(1704067200);
UnixTimestamp.startOfYear(1704067200);
UnixTimestamp.endOfYear(1704067200);
UnixTimestamp.startOfQuarter(1704067200);
UnixTimestamp.endOfQuarter(1704067200);

RANGE

final today = UnixTimestampRange.today();
final thisWeek = UnixTimestampRange.thisWeek();
final thisMonth = UnixTimestampRange.thisMonth();
final thisYear = UnixTimestampRange.thisYear();
final thisQuarter = UnixTimestampRange.thisQuarter();
final lastSevenDays = UnixTimestampRange.lastNDays(7);
final nextThreeDays = UnixTimestampRange.nextNDays(3);
final last24Hours = UnixTimestampRange.lastNHours(24);
final between = UnixTimestampRange.between(DateTime.utc(2024), DateTime.utc(2024, 2));

today.contains(UnixTimestamp.now());
today.containsNow;
today.duration;
today.totalSeconds;
today.totalMinutes;
today.totalHours;
today.totalDays;
today.overlap(lastSevenDays);
today.merge(nextThreeDays);
today.splitByDays(1);
today.splitByHours(6);
today.splitInto(4);
today.toList(3600);
today.toMap();

IoT and solar energy windows

final sensorWindow = UnixTimestampRange.lastNHours(6);
final hourlyBuckets = sensorWindow.splitByHours(1);

final solarLogPeriod = UnixTimestampRange.between(
  DateTime.utc(2024, 6, 1),
  DateTime.utc(2024, 6, 30, 23, 59, 59),
);
final dailySolarBuckets = solarLogPeriod.splitByDays(1);

SCHEDULER

final target = UnixTimestamp.now() + 3600;

UnixTimestampScheduler.countdown(target);
UnixTimestampScheduler.isExpired(target);
UnixTimestampScheduler.expiresIn(target);
UnixTimestampScheduler.expiredAgo(UnixTimestamp.now() - 30);
UnixTimestampScheduler.percentElapsed(UnixTimestamp.now() - 10, UnixTimestamp.now() + 10);
UnixTimestampScheduler.ttlFromNow(300);
UnixTimestampScheduler.ttl(15); // minutes
UnixTimestampScheduler.isSessionValid(UnixTimestamp.now(), 3600);

JWT expiry and cache TTL

final issuedAt = UnixTimestamp.now();
final jwtIsValid = UnixTimestampScheduler.isSessionValid(issuedAt, 3600);

final cacheExpiresAt = UnixTimestampScheduler.ttlFromNow(300);
final cacheStillFresh = !UnixTimestampScheduler.isExpired(cacheExpiresAt);

SERIALIZATION

final json = UnixTimestampSerializer.toJson(1704067200);
// {'timestamp': 1704067200, 'iso': '2024-01-01T00:00:00.000Z', 'ms': 1704067200000}

final fromJson = UnixTimestampSerializer.fromJson(json);
final fromJsonMs = UnixTimestampSerializer.fromJson({'ms': 1704067200000});

final firestore = UnixTimestampSerializer.toFirestoreTs(1704067200);
final fromFirestore = UnixTimestampSerializer.fromFirestoreTs(firestore);

final hive = UnixTimestampSerializer.toHive(1704067200);
final fromHive = UnixTimestampSerializer.fromHive(hive);

final proto = UnixTimestampSerializer.toProto(1704067200);
final fromProto = UnixTimestampSerializer.fromProto(proto);

Firestore and JSON use case

final createdAt = UnixTimestamp.now();

final document = <String, dynamic>{
  'createdAt': UnixTimestampSerializer.toFirestoreTs(createdAt),
  'createdAtJson': UnixTimestampSerializer.toJson(createdAt),
};

final restored = UnixTimestampSerializer.fromFirestoreTs(document['createdAt'] as Map);

EXTENSIONS

final ts = 1704067200;

ts.toDateTimeUtc();
ts.toDateTimeLocal();
ts.toDateTimeOffset(const Duration(hours: 3));
ts.toDate();
ts.toTime();
ts.toDateTimeString();
ts.toIso8601();
ts.toSlug();
ts.toLogFormat();
ts.toHttpDate();
ts.humanize();
ts.humanizeShort();
ts.humanizeFrom(1704067200);
ts.isPast;
ts.isFuture;
ts.isToday;
ts.isYesterday;
ts.isTomorrow;
ts.isWeekend;
ts.isWeekday;
ts.isThisWeek;
ts.isThisMonth;
ts.isThisYear;
ts.isRecent(withinSeconds: 60);
ts.isBefore(1704067201);
ts.isAfter(1704067199);
ts.isBetween(1704060000, 1704070000);
ts.isSameDay(1704070800);
ts.addSeconds(1);
ts.addMinutes(1);
ts.addHours(1);
ts.addDays(1);
ts.addWeeks(1);
ts.addMonths(1);
ts.addYears(1);
ts.subtractDays(1);
ts.diffDays(1704153600);
ts.diffHours(1704070800);
ts.diffMinutes(1704067260);
ts.diffBreakdown(1704067261);
ts.countdown();
ts.isExpired;
ts.expiresIn;
ts.percentElapsed(1704060000);
ts.startOfDay;
ts.endOfDay;
ts.startOfWeek;
ts.endOfWeek;
ts.startOfMonth;
ts.endOfMonth;
ts.startOfYear;
ts.endOfYear;
ts.startOfQuarter;
ts.endOfQuarter;
ts.roundToHour;
ts.floorToHour;
ts.ceilToHour;
ts.unit;
ts.normalizedSeconds;
ts.normalizedMilliseconds;
ts.normalizedMicroseconds;
ts.normalizedNanoseconds;
ts.convertUnixUnit(to: UnixTimestampUnit.milliseconds);
ts.toDateTimeUnit();
ts.epochInfo();
ts.secondsDurationBreakdown;
ts.toUnixHex();
ts.isYear2038Safe;
ts.isLeapYear;
ts.toJson();
ts.toFirestoreTs();
ts.toProto();

1779000216.toDate(); // 2026-05-17
1779000216.toIso8601(); // 2026-05-17T06:43:36.000Z
1779000216.isWeekend; // true, Sunday
1779000216.startOfDay.toDate(); // 2026-05-17
1779000216.startOfWeek.toDate(); // 2026-05-11, Monday
1779000216000.normalizedSeconds; // 1779000216

final dt = DateTime.utc(2024, 1, 1);
dt.toUnixSeconds();
dt.toUnixMs();
dt.toUnixUs();
dt.toUnixNano();
dt.toUnixUnit(UnixTimestampUnit.milliseconds);
dt.humanize();
dt.humanizeShort();
dt.toUnixJson();
dt.toFirestoreTs();

Notes

• Core calculations are UTC-first unless a method explicitly says local or offset.
• toDateTimeOffset returns a shifted DateTime because Dart does not have an arbitrary-offset DateTime type.
• Timezone aliases use fixed offsets only. For full IANA timezone transitions and DST history, pair the package with a dedicated timezone database package in your app layer.
• DST detection uses the current device timezone and compares January/July offsets. It is useful as a lightweight heuristic, not as a replacement for a full timezone database.
• The package has no runtime dependencies.