Temporal की मदद से, जगह की जानकारी से अलग डेटा और तारीखों के कुछ हिस्सों को कैप्चर करना

समय के हिसाब से डेटा रिकॉर्ड करना, जो दर्शक की जगह की जानकारी के बावजूद एक जैसा रहना चाहिए. जैसे, जन्म की तारीखें, रोज़ के अलार्म, क्रेडिट कार्ड की समयसीमा खत्म होने की तारीखें या महीने के बिलिंग साइकल. लेगसी Date ऑब्जेक्ट की वजह से, इसमें गड़बड़ी होने की संभावना ज़्यादा होती है. Date हमेशा समय के किसी खास पल को दिखाता है और इसे दर्शक के स्थानीय टाइम ज़ोन का इस्तेमाल करके दिखाया जाता है. इसलिए, "1990-01-01" जैसी तारीख सेव करने पर, यूटीसी के पश्चिम में रहने वाले उपयोगकर्ताओं को "1989-12-31" दिख सकता है. वहीं, तारीख के कुछ हिस्से (जैसे, सिर्फ़ महीने के हिसाब से कार्ड की समयसीमा खत्म होने की तारीख) को मॉडल करने पर, प्लेसहोल्डर के तौर पर मनचाहे दिन दिखते हैं. इससे ओवरफ़्लो की गड़बड़ियां होती हैं.

Temporal एपीआई, जगह की जानकारी से अलग "सामान्य" टाइप का एक फ़ैमिली उपलब्ध कराता है. इसमें कोई टाइम ज़ोन ऑफ़सेट नहीं होता. साथ ही, यह कैलेंडर की तारीखों और वॉल-क्लॉक के समय को ठीक उसी तरह दिखाता है जिस तरह कैलेंडर या घड़ी से पढ़ा जाता है:

इन्हें कैसे लागू करें

1. अपने डेटा से मैच करने वाला सबसे सटीक Temporal.Plain* टाइप चुनें:
   • कैलेंडर की पूरी तारीखों के लिए Temporal.PlainDate.from() और घड़ी के समय के लिए Temporal.PlainTime.from() का इस्तेमाल करें.
   • किसी कैलेंडर की तारीख और समय को किसी टाइम ज़ोन से जोड़े बिना, उन्हें एक साथ दिखाने के लिए Temporal.PlainDateTime.from() (या plainDate.toPlainDateTime(plainTime)) का इस्तेमाल करें.
   • साल के बिना सालाना तारीखों के लिए Temporal.PlainMonthDay.from() का इस्तेमाल करें. साथ ही, तारीख के हिसाब से हिसाब लगाने से पहले, .toPlainDate({ year }) के साथ PlainDate में बदलें.
   • साल और महीने की वैल्यू के लिए, Temporal.PlainYearMonth.from() का इस्तेमाल करें, ताकि कैलकुलेशन में दिन की कोई भी संख्या शामिल न हो.
2. प्लेन टाइप बनाते समय calendar पैरामीटर का ध्यान रखें: आईएसओ स्ट्रिंग को पार्स करते समय या PlainDate.from({ year, month, day }) के साथ बनाते समय, ISO 8601 ('iso8601') डिफ़ॉल्ट कैलेंडर होता है. प्रॉपर्टी बैग से PlainMonthDay या PlainYearMonth बनाते समय या नॉन-आईएसओ कैलेंडर के साथ काम करते समय, calendar को साफ़ तौर पर पास करें (उदाहरण के लिए, { month: 10, day: 31, calendar: 'iso8601' }).
3. .add() का इस्तेमाल overflow के साथ करें. इससे कैलेंडर में बार-बार होने वाले इवेंट के लिए, समय के अंतराल के विकल्प मिलते हैं: plainDate.add({ months: 1 }) को कॉल करने पर, डिफ़ॉल्ट रूप से { overflow: 'constrain' } का इस्तेमाल होता है. इससे महीने के आखिर की तारीखें, जैसे कि 31 जनवरी से 28/29 फ़रवरी तक की तारीखें क्लैंप हो जाती हैं. जब अमान्य टारगेट तारीखों को क्लैंप करने के बजाय RangeError दिखाना हो, तब { overflow: 'reject' } पास करें.

उदाहरण: पूरी तारीखें, वॉल-क्लॉक टाइम, और PlainDateTime

// 1. Parse a calendar date and a wall-clock time from input strings
const birthdate = Temporal.PlainDate.from('1990-01-01');
const reminderTime = Temporal.PlainTime.from('09:00');

// Combine into a location-agnostic PlainDateTime without string interpolation
const localAppointment = birthdate.toPlainDateTime(reminderTime);

// 2. Display without time zone conversion; outputs the same date in any time zone
console.log(birthdate.toLocaleString('en-GB'));
console.log(localAppointment.toString()); // "1990-01-01T09:00:00"

// 3. Read calendar fields directly from the Plain type. A PlainDate already *is*
// a calendar date, so there is no need for the formatToParts() workaround that
// legacy Date code uses to recover year/month/day from an instant.
const { year, month, day } = birthdate;

उदाहरण: तारीखों का कुछ हिस्सा (PlainMonthDay और PlainYearMonth)

// Annual recurring event (no year component)
// Include explicit calendar when constructing from an object
const annualHoliday = Temporal.PlainMonthDay.from({
  month: 10,
  day: 31,
  calendar: 'iso8601',
});

const today = Temporal.Now.plainDateISO();
const isToday = annualHoliday.equals(today.toPlainMonthDay());

// Convert PlainMonthDay to a PlainDate with a specific year before doing arithmetic,
// because month lengths (such as February) depend on whether the year is a leap year.
const occurrenceThisYear = annualHoliday.toPlainDate({ year: today.year });

// Monthly expiration (no day component, preventing day-of-month overflow bugs)
const cardExpiry = Temporal.PlainYearMonth.from({
  year: 2027,
  month: 12,
  calendar: 'iso8601',
});
const currentMonth = today.toPlainYearMonth();
const isExpired = Temporal.PlainYearMonth.compare(cardExpiry, currentMonth) < 0;

उदाहरण: हर महीने के अंतराल पर बार-बार होने वाले पेमेंट (overflow: 'constrain' बनाम 'reject')

const billingStart = Temporal.PlainDate.from('2024-01-31');

// Default overflow: 'constrain' clamps Jan 31 + 1 month to the last valid day of February
const nextBilling = billingStart.add({ months: 1 }, { overflow: 'constrain' });
console.log(nextBilling.toString()); // "2024-02-29" (2024 is a leap year)

// Use overflow: 'reject' to throw a RangeError when the target day does not exist
try {
  billingStart.add({ months: 1 }, { overflow: 'reject' });
} catch (err) {
  // RangeError: day 31 does not exist in February
}

उदाहरण: लेगसी Date के साथ इंटरऑपरेट करना

लेगसी Date एक टाइमस्टैंप (एक पल) है, न कि कैलेंडर की तारीख. "1990-01-01" को Date के तौर पर सेव करने पर, आपको कोई समय (आम तौर पर, यूटीसी के हिसाब से आधी रात) चुनना पड़ता है. साथ ही, यूटीसी के पश्चिम में मौजूद टाइम ज़ोन में इसे पढ़ने पर, "31/12/1989" मिलता है. अगर किसी लाइब्रेरी या एपीआई को अब भी Date की ज़रूरत है, तो आईएसओ स्ट्रिंग को मैन्युअल तरीके से बनाने के बजाय, Temporal.Instant का इस्तेमाल करके साफ़ तौर पर कन्वर्ट करें:

// PlainDate -> Date: attach a time zone (time of day defaults to the start of
// that day) to get an Instant, then hand the epoch milliseconds to Date.
// 'UTC' is a deliberate choice and must be documented; any zone would do,
// but the stored instant depends on it.
const instant = birthdate.toZonedDateTime('UTC').toInstant();
const legacyDate = new Date(instant.epochMilliseconds);

// Date -> PlainDate: go back through Instant (legacyDate.toTemporalInstant()
// is equivalent), then project into an explicit time zone. The result depends
// on the zone, which is exactly the drift risk.
const viewedDate = Temporal.Instant.fromEpochMilliseconds(legacyDate.getTime())
  .toZonedDateTimeISO('America/New_York')
  .toPlainDate();

// Compare Plain types with .equals() (or Temporal.PlainDate.compare), not strings.
console.log(viewedDate.equals(birthdate)); // false: the calendar date drifted to 1989-12-31

रणनीति को लागू करने के तरीके और सबसे सही तरीके

• कैलेंडर की पूरी तारीखों के लिए Temporal.PlainDate, घड़ी के समय के लिए Temporal.PlainTime, बिना ज़ोन वाली स्थानीय तारीख-समय के लिए Temporal.PlainDateTime, हर साल दोहराई जाने वाली तारीखों के लिए Temporal.PlainMonthDay, और साल-महीने की समयसीमा खत्म होने या बिलिंग अवधि के लिए Temporal.PlainYearMonth का इस्तेमाल करें.
• Temporal.PlainMonthDay पर सीधे तौर पर अंकगणित का इस्तेमाल न करें. इसे पहले .toPlainDate({ year }) की मदद से Temporal.PlainDate में बदलें, क्योंकि महीने की लंबाई साल के हिसाब से अलग-अलग होती है.
• कैलेंडर में बार-बार होने वाले इवेंट के लिए, Temporal.PlainDate पर .add() का इस्तेमाल करें. महीने के आखिर की तारीखों को क्लैंप करने के लिए, overflow: 'constrain' (डिफ़ॉल्ट) पर भरोसा करें या ऐसी तारीखों पर RangeError दिखाने के लिए overflow: 'reject' का इस्तेमाल करें जो मौजूद नहीं हैं.
• ऑब्जेक्ट से PlainMonthDay या नॉन-आईएसओ प्लेन टाइप बनाते समय, calendar (जैसे, calendar: 'iso8601') की जानकारी ज़रूर दें.
• DO NOT use Plain types if you need to represent a specific moment in physical time (an instant). लॉग, इवेंट के टाइमस्टैंप या अलग-अलग टाइमज़ोन में शेड्यूल करने के लिए, Temporal.Instant या Temporal.ZonedDateTime का इस्तेमाल करें.
• हाथ से बनाई गई आईएसओ स्ट्रिंग (जैसे, `${date}T00:00:00Z`) से Date ऑब्जेक्ट न बनाएं. Temporal.Instant या Temporal.ZonedDateTime के epochMilliseconds से Date बनाएं. साथ ही, Temporal.Instant.fromEpochMilliseconds(date.getTime()) या date.toTemporalInstant() से वापस पढ़ें, ताकि टाइम ज़ोन का अनुमान साफ़ तौर पर लगाया जा सके.
• साल, महीने या दिन की वैल्यू निकालने या उनकी तुलना करने के लिए, Intl.DateTimeFormat.prototype.formatToParts() का इस्तेमाल न करें. .year, .month, और .day को सीधे Plain टाइप से पढ़ें और .equals() से तुलना करें.
• टाइम ज़ोन की पहचान करने के लिए, आईएएनए नाम (जैसे, America/New_York) का इस्तेमाल करें. इसके लिए, कभी भी तय यूटीसी ऑफ़सेट का इस्तेमाल न करें. डेलाइट सेविंग टाइम और कानून के हिसाब से ऑफ़सेट बदलते रहते हैं. इसलिए, "UTC-5" जैसे लेबल साल के कुछ समय के लिए गलत हो जाते हैं.
• ध्यान रखें कि Temporal ऑब्जेक्ट बदले नहीं जा सकते. .add(), .subtract() या .with() जैसे तरीके, ओरिजनल ऑब्जेक्ट में बदलाव करने के बजाय, हमेशा नए रेफ़रंस के साथ नया इंस्टेंस दिखाते हैं. इससे उन्हें सीधे तौर पर रिएक्टिव यूज़र इंटरफ़ेस (यूआई) की स्थिति में सेव करना सुरक्षित हो जाता है.

फ़ॉलबैक रणनीति

Temporal के लिए फ़ॉलबैक और ब्राउज़र की सुविधा

ऐसे ब्राउज़र जो अब तक नेटिव Temporal एपीआई के साथ काम नहीं करते हैं उनके लिए, सुविधा की पहचान करने वाले टूल का इस्तेमाल करें और temporal-polyfill (~15 केबी min+gz) को डाइनैमिक तौर पर लोड करें.

ध्यान दें कि temporal-polyfill को इंपोर्ट करने से, Temporal ऑब्जेक्ट अपने-आप ग्लोबल स्कोप को असाइन नहीं होता. अगर आपका कोड globalThis.Temporal पर निर्भर करता है, तो इसे साफ़ तौर पर असाइन करें.

// Check if Temporal is supported natively
(async () => {
  if (typeof Temporal === 'undefined') {
    // Load the polyfill conditionally
    const module = await import('https://esm.sh/temporal-polyfill');
    globalThis.Temporal = module.Temporal;
    // Extend Date.prototype if needed
    Date.prototype.toTemporalInstant = module.toTemporalInstant;
  }
  initializeApp();
})();