@magentagrid/datetime

Standardized, framework-agnostic cross-platform date and time library for MagentaGrid web applications.

Features

• Standardized UTC Contract: Standardizes API inputs and outputs into standard ISO-8601 UTC strings.
• Strict IANA Timezones: Full support for IANA timezone identifiers (e.g. Asia/Kolkata, America/New_York). Rejects ambiguous offsets (+05:30, IST).
• No Dependencies: Powered entirely by the high-performance native Intl.DateTimeFormat engine. Zero runtime bundle bloat.
• Framework Independent: Works natively with React, Next.js, Vite, Vue, Svelte, or vanilla TypeScript/JavaScript.
• Configurable Environment: Separation of concerns—the package never reads .env directly; the consuming app configures it.
• DST & Leap Year Ready: Accurate handling of Daylight Saving Time transitions, leap years, and midnight boundaries.
• Strong Typing: Comprehensive TypeScript types, interfaces, and typed error classes.

Installation

npm install @magentagrid/datetime

or with pnpm / yarn:

pnpm add @magentagrid/datetime
# or
yarn add @magentagrid/datetime

Quick Start

1. Application Configuration

Configure the package once at your application bootstrap (e.g. main.tsx, index.ts, _app.tsx):

import { configureDateTime } from "@magentagrid/datetime";

// Vite example:
configureDateTime({
  timeZone: import.meta.env.VITE_APP_TIMEZONE || "Asia/Kolkata",
  locale: "en-IN",
  emptyValue: "-",
  timezoneMode: "application",
});

// Next.js example:
configureDateTime({
  timeZone: process.env.NEXT_PUBLIC_APP_TIMEZONE || "Asia/Kolkata",
  locale: "en-IN",
});

2. Rendering API Dates in UI

Convert incoming UTC API timestamps into formatted local strings:

import { formatDateTime, formatDate, formatTime } from "@magentagrid/datetime";

// API response: { createdAt: "2026-08-25T01:54:32.000Z" }
const displayDateTime = formatDateTime(apiData.createdAt);
// Output: "25 Aug 2026, 07:24:32"

const displayDate = formatDate(apiData.createdAt);
// Output: "25 Aug 2026"

const displayTime = formatTime(apiData.createdAt);
// Output: "07:24:32"

// Null or undefined gracefully fallback to emptyValue ("-")
const emptyDisplay = formatDateTime(null);
// Output: "-"

Formatting Options

formatDateTime(apiData.createdAt, {
  timeZone: "America/New_York", // Explicit timezone override
  locale: "en-US",
  hour12: true,                 // 12h clock
  showSeconds: false,           // Hide seconds
});
// Output: "08/24/2026, 09:54 PM"

3. Converting User Input to UTC for API Payloads

Convert dates selected in pickers or forms back into ISO-8601 UTC before sending requests:

import { toUtc } from "@magentagrid/datetime";

const payload = {
  orderId: "ORD-12345",
  scheduledAt: toUtc(selectedPickerDate), // Date object, timestamp number, or ISO string
};
// Payload: { "orderId": "ORD-12345", "scheduledAt": "2026-08-25T01:54:00.000Z" }

await api.createSchedule(payload);

4. Handling Explicit Zoned Inputs

When receiving timezone-less strings (e.g. from an offline form or legacy input) that are known to belong to a specific timezone:

import { toUtcFromZonedTime } from "@magentagrid/datetime";

const utcString = toUtcFromZonedTime("2026-08-25 07:24:32", "Asia/Kolkata");
// Output: "2026-08-25T01:54:32.000Z"

API Reference

Configuration Functions

• configureDateTime(config: Partial<DateTimeConfig>): void
• getConfig(): Readonly<DateTimeConfig>
• resetConfig(): void
• getConfiguredTimeZone(): string

Timezone Utilities

• getBrowserTimeZone(): string
• isValidTimeZone(timeZone: string): boolean
• resolveTimeZone(explicitTimeZone?: string): string

Formatting Functions

• formatDateTime(date: string | number | Date | null | undefined, options?: FormatOptions): string
• formatDate(date: string | number | Date | null | undefined, options?: FormatOptions): string
• formatTime(date: string | number | Date | null | undefined, options?: FormatOptions): string

UTC Conversion Functions

• toUtc(date: string | number | Date | null | undefined): string | null | undefined
• toUtcFromZonedTime(dateStr: string, timeZone: string): string

Errors

• MgDateTimeError: Base class.
• InvalidDateTimeError: Thrown on unparseable date values.
• InvalidTimeZoneError: Thrown on invalid or non-IANA timezone strings.
• AmbiguousDateTimeError: Thrown on timezone-less strings passed to instant converters without explicit timezone.

License

MIT © MagentaGrid