my Datetime utility, it mixes the Advanced capabilities of Temporal polyfill with the simplicity of Date
npm install datetime_globalDatetime_global is a JavaScript library that provides a Date-like interface for handling dates and times with robust
Temporal API offers advanced date-time functionality, Datetime_global provides a familiar Date-like API
Date-compatible interface.
Temporal directly.
Datetime_global is designed to behave like the native JavaScript Date object for methods with matching names
getFullYear, toISOString), except toJSON. The toJSON method can produce either a Date-like ISO string
useOldJSON = true, the default) or a Temporal.ZonedDateTime string (when useOldJSON = false).
Date object.
bash
npm install datetime-global
`
Include the Temporal polyfill for environments without native Temporal support:
Examples
first import the library
`typescript
import {Datetime_global} from "./Datetime_global.js";
// change "./Datetime_global" to the actual path
// get the current time
const now = new Datetime_global();
// display the current time to the user
console.log(now.toString()); // Mon Jun 09 2025 15:21:20 UTC+0200 (Europe/Amsterdam)
// will vary for you
// use components and UTC
const date = Datetime_global.fromComponentsUTC(
2024, // year
2, // month
1, // day of month
5, // hours
30, // minutes
50, // seconds
123, // millisecond
456_789, // nanoseconds and microseconds
); // a bigint that can be used in the Datetime_global constructor.
console.log((new Datetime_global(date)).toTimezone('Asia/Tokyo').toString()); // Fri Mar 01 2024 14:30:50 UTC+0900 (Asia/Tokyo)
// you can even call Datetime_global as a non constructor
console.log(Datetime_global(0, 'America/new_York')); // Wed Dec 31 1969 19:00:00 UTC-0500 (America/New_York)
`
Datetime_global Construction
The Datetime_global constructor accepts various inputs as the first argument and an optional timezone as the second:
Inputs:
- Temporal.ZonedDateTime: Used directly (nanoseconds, will ignore the specified timezone, convert to Temporal.Instant
to use argument 2).
- Temporal.Instant: From epoch nanoseconds.
- Date, Datetime_global: From epoch milliseconds.
- bigint: Epoch nanoseconds.
- number: Epoch milliseconds.
- string: Parsed via Date.parse (ISO 8601 recommended).
- undefined: Current time.
Timezone: A Temporal.TimeZoneLike or IANA timezone string (e.g., UTC, America/New_York). Defaults to local timezone.
When called with new, it returns a Datetime_global instance. Without new, it returns a string representation.
.methods
an overview of the public api. note that semver version 0. meaning anything can change.
the documentations are within jsdoc comments.
$3
- getFullYear(): number - Full year (e.g., 2025).
- getYear(): number - Year minus 1900.
- getMonth(): number - Month (0-11).
- getDate(): number - Day of month (1-31).
- getDay(): number - Day of week (0=Sunday, ..., 6=Saturday).
- getHours(): number, getMinutes(): number, getSeconds(): number, getMilliseconds(): number - Time components.
getNanoseconds(): bigint - Sub-millisecond components.
- getTimezoneOffset(): number - Timezone offset in minutes (positive west of UTC).
- valueOf(): number, getTime(): number - Milliseconds since epoch.
UTC Variants: Each getter (except valueOf, getTime) has a getUTC* version (e.g., getUTCFullYear).
$3
- setFullYear(year, month?, date?): number - Sets year, month, day.
- setMonth(month, date?): number - Sets month, day.
- setDate(date): number - Sets day of month.
- setHours(hours, minutes?, seconds?, milliseconds?): number - Sets time.
- setMinutes(minutes, seconds?, milliseconds?): number - Sets minutes and below.
- setSeconds(seconds, milliseconds?): number - Sets seconds and below.
- setMilliseconds(milliseconds): number - Sets milliseconds.
- setMicroseconds(microseconds: bigint, nanoseconds?: bigint): bigint - Sets microseconds, nanoseconds.
- setNanoseconds(nanoseconds: bigint, microseconds?: bigint): bigint - Sets nanoseconds, microseconds.
- setTime(timestamp: number | bigint): number - Sets timestamp (deprecated).
- setOldJSON(useOldJSON: boolean): Datetime_global: sets the useOldJSON with the value provided.
UTC Variants: setUTCFullYear, setUTCMonth, setUTCDate,
setUTCHours, setUTCMinutes, setUTCSeconds, setUTCMilliseconds.
$3
i think they are self-explanatory, otherwise the jsdocs are available in the code
- get year(): number
- get month(): number
- get day(): number
- get dayOfWeek(): number
- get hour(): number
- get minute(): number
- get second(): number
- get millisecond(): number
- get microsecond(): number
- get nanosecond(): number
- get epochMilliseconds(): number
- get epochNanoseconds(): bigint
- get minutesAfterMidnight(): number
- get timezoneId(): string
- get date(): Date
- get useOldJSON(): boolean
$3
i think they are self-explanatory, otherwise the jsdocs are available in the code
- set epochNanoseconds(value: bigint)
- set minutesAfterMidnight(value: number)
- set timezoneId(value: string)
- set date(value: Date | unknown)
- set useOldJSON(value: boolean)
$3
- toString(): string - Formats as (php): "D M d Y H:i:s \\U\\T\\CO (e)" (
e.g., Fri Apr 18 2025 00:00:00 UTC+0000 (UTC)).
- toISOString(): string - ISO 8601 in UTC (e.g., 2025-04-18T00:00:00.000Z).
- toJSON(): string - ISO 8601 with timezone (e.g., 2025-04-18T00:00:00+00:00[UTC]).
- format(pattern: string): string - PHP-like format (e.g., Y-m-d -> 2025-04-18).
- templateFormat(strings: TemplateStringsArray, ...keys: string[]): string - Template literal formatting.
- toHTMLString(): string - HTML time element with local or instance timezone.
$3
- toTimezone(timezoneId: string): Datetime_global - Converts to new timezone, preserving instant.
- toDate(): Date - Converts to Date (loses sub-millisecond precision).
- toTemporalZonedDateTime(): Temporal.ZonedDateTime - Returns internal Temporal object.
- clone(): Datetime_global - Creates a copy.
$3
- getDayName(): string, getFullDayName(): string - Abbreviated or full weekday (en-US).
- getMonthName(): string, getFullMonthName(): string - Abbreviated or full month (en-US).
- startOfDay(this: Datetime_global, timezone?: Temporal.TimeZoneLike): Datetime_global - Sets time to the start of day
in the current timezone or the timezone given, the output will be in the original timezone, use toTimezone to convert
the timezone.
$3
- fromComponentsUTC(year, month?, date?, ...): bigint - UTC timestamp from components.
- parse(dateString: string, this_parserOnly?: boolean): number - Parses string to milliseconds.
- parse_strict(string: string): Temporal.ZonedDateTime - Strict ISO 8601 parsing.
- now(): bigint - Current timestamp in nanoseconds.
- zeroms(): number - Current timestamp with sub-second set to 0 (milliseconds).
- zerons(): bigint - Current timestamp with sub-second set to 0 (nanoseconds).
- getUTCOffset(offset: number): string - Formats offset (e.g., UTC+0100).
- htmlToCurrentTime(timetags: NodeListOf - Updates time elements.
$3
`typescript
const tz = 'Europe/Berlin', time = new Datetime_global(1749476032000, tz);
console.log(String(time)); // Mon Jun 09 2025 15:33:52 UTC+0200 (Europe/Berlin)
// set the hour to 25, which corrosponds to hour 1 the next day.
console.log(Datetime_global(time.setHours(25), tz)); // Tue Jun 10 2025 01:33:52 UTC+0200 (Europe/Berlin)
// change the timezone to Asia/Riyadh
console.log(String(time.toTimezone('Asia/Riyadh'))); // Tue Jun 10 2025 02:33:52 UTC+0300 (Asia/Riyadh)
console.log(); // print an empty string to space out
// startOfDay
console.log(String(time.startOfDay())); // Tue Jun 10 2025 00:00:00 UTC+0200 (Europe/Berlin)
console.log(String(time.startOfDay('America/new_York'))); // Mon Jun 09 2025 06:00:00 UTC+0200 (Europe/Berlin)
console.log(); // print an empty string to space out
console.log(time.toHTMLString()); //
time.setUTCHours(0, 0, 0, 0); // midnight UTC
console.log(time.toHTMLString()); // Mon, 09 Jun 2025 00:00:00 UTC
console.log();
console.log(time.toTimezone('Asia/Seoul').templateFormat---\nToday is ${'"Y-M-d H:i:s" \\i\\n "e"'}
, '\n\n--');
console.log((new Datetime_global(Datetime_global.now(), 'UTC')).templateFormat
); // Datetime_global.FORMAT_OFFSET_FROM_NOW: ${Datetime_global.FORMAT_OFFSET_FROM_NOW};
// convert it to a classic Date
console.log(time.toDate());
console.log(); // print an empty string to space out
// or even an
console.log(time.toTemporalZonedDateTime());
console.log(); // print an empty string to space out
// toJSON is implicitly called here
console.log(JSON.stringify({
Date: new Date, Datetime_global: new Datetime_global,
Temporal_ZonedDateTime: new Temporal.ZonedDateTime(Datetime_global.now(), "UTC"),
}, null, 2));
/*{
"Date": "2025-06-09T14:29:37.049Z",
"Datetime_global": "2025-06-09T16:29:37.049+02:00[Europe/Amsterdam]",
"Temporal_ZonedDateTime": "2025-06-09T14:29:37.049+00:00[UTC]"
}*/
`
License
Mit Licence
Credits
thanks to generative ai to help with the documentation
aftercode
// npm: https://www.npmjs.com/package/datetime_global
// github: https://github.com/DNSCond/Datetime-local
// ListOfTimezones: Moderator Statistics | Reddit for Developers
consider inserting this into your site, and convert your site to local time
`ts
import {Datetime_global} from "./Datetime_global";
window.document.addEventListener('DOMContentLoaded', function () {
document.querySelectorAll('time.toLocalTime').forEach(function (each) {
each.innerText = ${new Date(each.dateTime)}.replace(/ GMT.+/, '');
});
document.querySelectorAll('time.toSelfTime').forEach(function (each) {
each.innerText = (new Date(each.dateTime)).toString();
});
Datetime_global.htmlToCurrentTime(document.querySelectorAll('time.toCurrentTime'));
});
``