Calendar

Calendar

Represents a wall clock time with individual date and time components. This type is used for representing time as it appears on a wall clock in a specific timezone, without any timezone offset information.

reference/calendar/Calendar.ts
import {
	type Calendar,
	calendarToTimestamp,
	type TimeZone,
	timestampToCalendar,
} from "datezone";

// Current timestamp
const now = Date.now();

// Example timezone
const timeZone: TimeZone = "America/New_York";

// Convert timestamp to calendar
const calendar: Calendar = timestampToCalendar(now, timeZone);

console.log("Calendar representation:");
console.log(`Year: ${calendar.year}`);
console.log(`Month: ${calendar.month}`);
console.log(`Day: ${calendar.day}`);
console.log(`Hour: ${calendar.hour}`);
console.log(`Minute: ${calendar.minute}`);
console.log(`Second: ${calendar.second}`);
console.log(`Millisecond: ${calendar.millisecond}`);

// Convert back to timestamp
const backToTimestamp = calendarToTimestamp(calendar, timeZone);
console.log(`\nOriginal timestamp: ${now}`);
console.log(`Back to timestamp: ${backToTimestamp}`);
console.log(`Same? ${now === backToTimestamp}`);

// Example with specific calendar
const specificCalendar: Calendar = {
	day: 25,
	hour: 15,
	millisecond: 123,
	minute: 30,
	month: 12,
	second: 45,
	year: 2023,
};

console.log("\nSpecific calendar example:");
console.log("Calendar:", specificCalendar);
console.log(`Timestamp: ${calendarToTimestamp(specificCalendar, timeZone)}`);
console.log(
	`ISO: ${new Date(calendarToTimestamp(specificCalendar, timeZone)).toISOString()}`,
);

calendarToTimestamp

Converts a wall-clock Calendar value in a specific timezone to a UTC timestamp (milliseconds since epoch).

reference/calendar/calendarToTimestamp.ts
import { type Calendar, calendarToTimestamp } from "datezone";

// Create a calendar representation
const calendar: Calendar = {
	day: 25,
	hour: 15,
	millisecond: 123,
	minute: 30,
	month: 12,
	second: 45,
	year: 2023,
};

// Convert calendar to timestamp in different timezones
console.log("Converting calendar to timestamp:");

// UTC timezone
const utcTimestamp = calendarToTimestamp(calendar, "UTC");
console.log(`UTC: ${utcTimestamp}`);
console.log(`UTC ISO: ${new Date(utcTimestamp).toISOString()}`);

// America/New_York timezone
const nyTimestamp = calendarToTimestamp(calendar, "America/New_York");
console.log(`New York: ${nyTimestamp}`);
console.log(`New York ISO: ${new Date(nyTimestamp).toISOString()}`);

// Asia/Tokyo timezone
const tokyoTimestamp = calendarToTimestamp(calendar, "Asia/Tokyo");
console.log(`Tokyo: ${tokyoTimestamp}`);
console.log(`Tokyo ISO: ${new Date(tokyoTimestamp).toISOString()}`);

// Show the differences
console.log("\nTimestamp differences:");
console.log(`NYC - UTC: ${nyTimestamp - utcTimestamp}ms`);
console.log(`Tokyo - UTC: ${tokyoTimestamp - utcTimestamp}ms`);

// Example with different calendar
const newYear: Calendar = {
	day: 1,
	hour: 0,
	millisecond: 0,
	minute: 0,
	month: 1,
	second: 0,
	year: 2024,
};

console.log("\nNew Year example:");
console.log(
	`New Year in NYC: ${new Date(calendarToTimestamp(newYear, "America/New_York")).toISOString()}`,
);
console.log(
	`New Year in Tokyo: ${new Date(calendarToTimestamp(newYear, "Asia/Tokyo")).toISOString()}`,
);

timestampToCalendar

Converts a timestamp in UTC to a calendar in a specific timezone.

reference/calendar/timestampToCalendar.ts
import { timestampToCalendar } from "datezone";

// Current timestamp
const now = Date.now();

// Convert timestamp to calendar in different timezones
console.log("Converting timestamp to calendar:");

// UTC timezone
const utcCalendar = timestampToCalendar(now, "UTC");
console.log("UTC Calendar:");
console.log(`  Year: ${utcCalendar.year}`);
console.log(`  Month: ${utcCalendar.month}`);
console.log(`  Day: ${utcCalendar.day}`);
console.log(`  Hour: ${utcCalendar.hour}`);
console.log(`  Minute: ${utcCalendar.minute}`);
console.log(`  Second: ${utcCalendar.second}`);
console.log(`  Millisecond: ${utcCalendar.millisecond}`);

// America/New_York timezone
const nyCalendar = timestampToCalendar(now, "America/New_York");
console.log("\nNew York Calendar:");
console.log(`  Year: ${nyCalendar.year}`);
console.log(`  Month: ${nyCalendar.month}`);
console.log(`  Day: ${nyCalendar.day}`);
console.log(`  Hour: ${nyCalendar.hour}`);
console.log(`  Minute: ${nyCalendar.minute}`);
console.log(`  Second: ${nyCalendar.second}`);
console.log(`  Millisecond: ${nyCalendar.millisecond}`);

// Asia/Tokyo timezone
const tokyoCalendar = timestampToCalendar(now, "Asia/Tokyo");
console.log("\nTokyo Calendar:");
console.log(`  Year: ${tokyoCalendar.year}`);
console.log(`  Month: ${tokyoCalendar.month}`);
console.log(`  Day: ${tokyoCalendar.day}`);
console.log(`  Hour: ${tokyoCalendar.hour}`);
console.log(`  Minute: ${tokyoCalendar.minute}`);
console.log(`  Second: ${tokyoCalendar.second}`);
console.log(`  Millisecond: ${tokyoCalendar.millisecond}`);

// Show hour differences
console.log("\nHour differences:");
console.log(`UTC hour: ${utcCalendar.hour}`);
console.log(`New York hour: ${nyCalendar.hour}`);
console.log(`Tokyo hour: ${tokyoCalendar.hour}`);

// Example with specific timestamp
const specificTime = new Date("2023-12-25T12:00:00Z").getTime();
console.log(
	`\nSpecific time (noon UTC): ${new Date(specificTime).toISOString()}`,
);
console.log(
	`In New York: ${JSON.stringify(timestampToCalendar(specificTime, "America/New_York"))}`,
);
console.log(
	`In Tokyo: ${JSON.stringify(timestampToCalendar(specificTime, "Asia/Tokyo"))}`,
);

Constants

Iso

Edit on GitHub

On this page