0
# Current Time Utilities
1

2
Utilities for getting current time values in various Temporal formats and time zones. The `Temporal.Now` namespace provides convenient access to current time information.
3

4
## Capabilities
5

6
### Temporal.Now Namespace
7

8
The `Temporal.Now` namespace contains functions for getting the current time in various Temporal formats.
9

10
```typescript { .api }
11
/**
12
 * Utilities for getting current time values
13
 */
14
namespace Now {
15
  /** Gets the current system time zone identifier */
16
  function timeZoneId(): string;
17

18
  /** Gets the current exact moment in time */
19
  function instant(): Instant;
20

21
  /** Gets the current date and time in the specified time zone with ISO calendar */
22
  function plainDateTimeISO(timeZone?: TimeZoneLike): PlainDateTime;
23

24
  /** Gets the current date and time with time zone information using ISO calendar */
25
  function zonedDateTimeISO(timeZone?: TimeZoneLike): ZonedDateTime;
26

27
  /** Gets the current date in the specified time zone with ISO calendar */
28
  function plainDateISO(timeZone?: TimeZoneLike): PlainDate;
29

30
  /** Gets the current time in the specified time zone with ISO calendar */
31
  function plainTimeISO(timeZone?: TimeZoneLike): PlainTime;
32
}
33
```
34

35
### Getting Current Time Zone
36

37
Retrieve the current system time zone identifier.
38

39
```typescript { .api }
40
/**
41
 * Gets the current system time zone identifier
42
 * @returns The current time zone as an IANA time zone identifier
43
 */
44
function timeZoneId(): string;
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
import { Temporal } from "temporal-polyfill";
51

52
// Get current system time zone
53
const currentTZ = Temporal.Now.timeZoneId();
54
console.log(currentTZ); // e.g., "America/New_York", "Europe/London", "UTC"
55

56
// Use in other operations
57
const nowInCurrentTZ = Temporal.Now.zonedDateTimeISO();
58
const nowInSpecificTZ = Temporal.Now.zonedDateTimeISO(currentTZ);
59

60
// Time zone aware operations
61
function getUserLocalTime(): Temporal.ZonedDateTime {
62
  return Temporal.Now.zonedDateTimeISO(Temporal.Now.timeZoneId());
63
}
64
```
65

66
### Getting Current Instant
67

68
Get the current exact moment in time as an Instant.
69

70
```typescript { .api }
71
/**
72
 * Gets the current exact moment in time
73
 * @returns The current instant (Unix timestamp)
74
 */
75
function instant(): Instant;
76
```
77

78
**Usage Examples:**
79

80
```typescript
81
import { Temporal } from "temporal-polyfill";
82

83
// Get current instant
84
const now = Temporal.Now.instant();
85
console.log(now.toString()); // ISO string like "2024-03-15T14:30:00.000Z"
86

87
// Convert to various formats
88
const epochMs = now.epochMilliseconds;
89
const epochNs = now.epochNanoseconds;
90

91
// Time measurements and logging
92
const startTime = Temporal.Now.instant();
93
// ... perform some operation ...
94
const endTime = Temporal.Now.instant();
95
const duration = startTime.until(endTime);
96
console.log(`Operation took ${duration.total('milliseconds')}ms`);
97

98
// Compare with other instants
99
const futureInstant = now.add({ hours: 1 });
100
const isNowEarlier = Temporal.Instant.compare(now, futureInstant) < 0; // true
101
```
102

103
### Getting Current Plain Date-Time
104

105
Get the current date and time without time zone information.
106

107
```typescript { .api }
108
/**
109
 * Gets the current date and time in the specified time zone with ISO calendar
110
 * @param timeZone Optional time zone (defaults to system time zone)
111
 * @returns Current date and time without time zone information
112
 */
113
function plainDateTimeISO(timeZone?: TimeZoneLike): PlainDateTime;
114
```
115

116
**Usage Examples:**
117

118
```typescript
119
import { Temporal } from "temporal-polyfill";
120

121
// Get current date-time in system time zone
122
const now = Temporal.Now.plainDateTimeISO();
123
console.log(now.toString()); // e.g., "2024-03-15T14:30:00"
124

125
// Get current date-time in specific time zone
126
const nowInNY = Temporal.Now.plainDateTimeISO('America/New_York');
127
const nowInLondon = Temporal.Now.plainDateTimeISO('Europe/London');
128
const nowInUTC = Temporal.Now.plainDateTimeISO('UTC');
129

130
// Business hours checking
131
function isBusinessHours(timeZone: string = Temporal.Now.timeZoneId()): boolean {
132
  const now = Temporal.Now.plainDateTimeISO(timeZone);
133
  const hour = now.hour;
134
  const dayOfWeek = now.dayOfWeek;
135

136
  // Monday-Friday, 9 AM - 5 PM
137
  return dayOfWeek >= 1 && dayOfWeek <= 5 && hour >= 9 && hour < 17;
138
}
139

140
// Scheduling operations
141
function scheduleForTomorrow(timeZone?: string): Temporal.PlainDateTime {
142
  const now = Temporal.Now.plainDateTimeISO(timeZone);
143
  return now.add({ days: 1 }).with({ hour: 9, minute: 0, second: 0 });
144
}
145
```
146

147
### Getting Current Zoned Date-Time
148

149
Get the current date and time with time zone information.
150

151
```typescript { .api }
152
/**
153
 * Gets the current date and time with time zone information using ISO calendar
154
 * @param timeZone Optional time zone (defaults to system time zone)
155
 * @returns Current date and time with time zone information
156
 */
157
function zonedDateTimeISO(timeZone?: TimeZoneLike): ZonedDateTime;
158
```
159

160
**Usage Examples:**
161

162
```typescript
163
import { Temporal } from "temporal-polyfill";
164

165
// Get current zoned date-time in system time zone
166
const now = Temporal.Now.zonedDateTimeISO();
167
console.log(now.toString()); // e.g., "2024-03-15T14:30:00-04:00[America/New_York]"
168

169
// Get current zoned date-time in specific time zones
170
const meetings = {
171
  newYork: Temporal.Now.zonedDateTimeISO('America/New_York'),
172
  london: Temporal.Now.zonedDateTimeISO('Europe/London'),
173
  tokyo: Temporal.Now.zonedDateTimeISO('Asia/Tokyo'),
174
};
175

176
// Global scheduling
177
function getBusinessHoursAcrossTimeZones() {
178
  const timeZones = [
179
    'America/New_York',
180
    'Europe/London',
181
    'Asia/Tokyo'
182
  ];
183

184
  return timeZones.map(tz => ({
185
    timeZone: tz,
186
    now: Temporal.Now.zonedDateTimeISO(tz),
187
    isBusinessHours: isBusinessHours(tz)
188
  }));
189
}
190

191
// Meeting coordination
192
function findOptimalMeetingTime(timeZones: string[]): Temporal.ZonedDateTime[] {
193
  const baseTime = Temporal.Now.zonedDateTimeISO('UTC').with({ hour: 15, minute: 0 });
194

195
  return timeZones.map(tz => baseTime.withTimeZone(tz));
196
}
197
```
198

199
### Getting Current Date
200

201
Get the current date without time information.
202

203
```typescript { .api }
204
/**
205
 * Gets the current date in the specified time zone with ISO calendar
206
 * @param timeZone Optional time zone (defaults to system time zone)
207
 * @returns Current date without time information
208
 */
209
function plainDateISO(timeZone?: TimeZoneLike): PlainDate;
210
```
211

212
**Usage Examples:**
213

214
```typescript
215
import { Temporal } from "temporal-polyfill";
216

217
// Get current date
218
const today = Temporal.Now.plainDateISO();
219
console.log(today.toString()); // e.g., "2024-03-15"
220

221
// Get date in specific time zones
222
const todayInNY = Temporal.Now.plainDateISO('America/New_York');
223
const todayInTokyo = Temporal.Now.plainDateISO('Asia/Tokyo');
224

225
// Note: dates can differ across time zones due to time differences
226
const isSameDate = todayInNY.equals(todayInTokyo); // might be false
227

228
// Date-based operations
229
function getDaysUntilWeekend(): number {
230
  const today = Temporal.Now.plainDateISO();
231
  const dayOfWeek = today.dayOfWeek;
232

233
  if (dayOfWeek === 6 || dayOfWeek === 7) { // Saturday or Sunday
234
    return 0;
235
  }
236
  return 6 - dayOfWeek; // Days until Saturday
237
}
238

239
function getNextBusinessDay(): Temporal.PlainDate {
240
  const today = Temporal.Now.plainDateISO();
241
  const dayOfWeek = today.dayOfWeek;
242

243
  if (dayOfWeek === 5) { // Friday
244
    return today.add({ days: 3 }); // Monday
245
  } else if (dayOfWeek === 6) { // Saturday
246
    return today.add({ days: 2 }); // Monday
247
  } else if (dayOfWeek === 7) { // Sunday
248
    return today.add({ days: 1 }); // Monday
249
  } else {
250
    return today.add({ days: 1 }); // Next weekday
251
  }
252
}
253
```
254

255
### Getting Current Time
256

257
Get the current time without date information.
258

259
```typescript { .api }
260
/**
261
 * Gets the current time in the specified time zone with ISO calendar
262
 * @param timeZone Optional time zone (defaults to system time zone)
263
 * @returns Current time without date information
264
 */
265
function plainTimeISO(timeZone?: TimeZoneLike): PlainTime;
266
```
267

268
**Usage Examples:**
269

270
```typescript
271
import { Temporal } from "temporal-polyfill";
272

273
// Get current time
274
const currentTime = Temporal.Now.plainTimeISO();
275
console.log(currentTime.toString()); // e.g., "14:30:00.123"
276

277
// Get time in specific time zones
278
const timeInNY = Temporal.Now.plainTimeISO('America/New_York');
279
const timeInLondon = Temporal.Now.plainTimeISO('Europe/London');
280
const timeInUTC = Temporal.Now.plainTimeISO('UTC');
281

282
// Time-based operations
283
function isAfterHours(): boolean {
284
  const now = Temporal.Now.plainTimeISO();
285
  const closingTime = Temporal.PlainTime.from('17:00:00');
286
  return Temporal.PlainTime.compare(now, closingTime) > 0;
287
}
288

289
function getTimeUntilMeeting(meetingTime: Temporal.PlainTime): Temporal.Duration {
290
  const now = Temporal.Now.plainTimeISO();
291
  return now.until(meetingTime);
292
}
293

294
// Alarm and scheduling
295
class DailySchedule {
296
  constructor(
297
    public readonly wakeUpTime: Temporal.PlainTime,
298
    public readonly workStartTime: Temporal.PlainTime,
299
    public readonly lunchTime: Temporal.PlainTime,
300
    public readonly workEndTime: Temporal.PlainTime,
301
    public readonly bedTime: Temporal.PlainTime
302
  ) {}
303

304
  getCurrentActivity(): string {
305
    const now = Temporal.Now.plainTimeISO();
306

307
    if (Temporal.PlainTime.compare(now, this.wakeUpTime) < 0) {
308
      return 'sleeping';
309
    } else if (Temporal.PlainTime.compare(now, this.workStartTime) < 0) {
310
      return 'morning routine';
311
    } else if (Temporal.PlainTime.compare(now, this.lunchTime) < 0) {
312
      return 'working (morning)';
313
    } else if (Temporal.PlainTime.compare(now, this.workEndTime) < 0) {
314
      return 'working (afternoon)';
315
    } else if (Temporal.PlainTime.compare(now, this.bedTime) < 0) {
316
      return 'evening activities';
317
    } else {
318
      return 'sleeping';
319
    }
320
  }
321
}
322

323
const schedule = new DailySchedule(
324
  Temporal.PlainTime.from('07:00:00'),
325
  Temporal.PlainTime.from('09:00:00'),
326
  Temporal.PlainTime.from('12:00:00'),
327
  Temporal.PlainTime.from('17:00:00'),
328
  Temporal.PlainTime.from('22:00:00')
329
);
330
```
331

332
### Time Zone Utilities
333

334
Working with time zones and current time utilities.
335

336
**Usage Examples:**
337

338
```typescript
339
import { Temporal } from "temporal-polyfill";
340

341
// Multi-timezone dashboard
342
class WorldClock {
343
  constructor(public readonly timeZones: string[]) {}
344

345
  getCurrentTimes(): Array<{timeZone: string, time: Temporal.ZonedDateTime}> {
346
    return this.timeZones.map(tz => ({
347
      timeZone: tz,
348
      time: Temporal.Now.zonedDateTimeISO(tz)
349
    }));
350
  }
351

352
  findBusinessHoursZones(): string[] {
353
    return this.timeZones.filter(tz => {
354
      const now = Temporal.Now.plainTimeISO(tz);
355
      return now.hour >= 9 && now.hour < 17;
356
    });
357
  }
358
}
359

360
// Performance monitoring
361
class PerformanceTimer {
362
  private startTime: Temporal.Instant | null = null;
363

364
  start(): void {
365
    this.startTime = Temporal.Now.instant();
366
  }
367

368
  stop(): Temporal.Duration {
369
    if (!this.startTime) {
370
      throw new Error('Timer not started');
371
    }
372
    const endTime = Temporal.Now.instant();
373
    const duration = this.startTime.until(endTime);
374
    this.startTime = null;
375
    return duration;
376
  }
377

378
  measure<T>(fn: () => T): { result: T; duration: Temporal.Duration } {
379
    this.start();
380
    const result = fn();
381
    const duration = this.stop();
382
    return { result, duration };
383
  }
384
}
385

386
// System health monitoring
387
function getSystemStatus() {
388
  const now = Temporal.Now.zonedDateTimeISO();
389
  const uptime = now.since(systemStartTime);
390

391
  return {
392
    currentTime: now.toString(),
393
    timeZone: now.timeZoneId,
394
    uptime: uptime.toString(),
395
    uptimeDays: uptime.total({ unit: 'day', relativeTo: now }),
396
    systemReady: isSystemReady(now)
397
  };
398
}
399
```
400

401
## Types
402

403
```typescript { .api }
404
// Type definitions for current time utilities
405
type TimeZoneLike = string | TimeZone;
406

407
// All Now functions return current time values in various formats
408
interface NowFunctions {
409
  timeZoneId(): string;
410
  instant(): Instant;
411
  plainDateTimeISO(timeZone?: TimeZoneLike): PlainDateTime;
412
  zonedDateTimeISO(timeZone?: TimeZoneLike): ZonedDateTime;
413
  plainDateISO(timeZone?: TimeZoneLike): PlainDate;
414
  plainTimeISO(timeZone?: TimeZoneLike): PlainTime;
415
}
416

417
// TimeZone interface (for reference)
418
interface TimeZone {
419
  readonly id: string;
420
  getOffsetNanosecondsFor(instant: Instant): number;
421
  getOffsetStringFor(instant: Instant): string;
422
  getPlainDateTimeFor(instant: Instant, calendar?: CalendarLike): PlainDateTime;
423
  getInstantFor(dateTime: PlainDateTime, options?: ToInstantOptions): Instant;
424
  getPossibleInstantsFor(dateTime: PlainDateTime): Instant[];
425
  getNextTransition(startingPoint: Instant): Instant | null;
426
  getPreviousTransition(startingPoint: Instant): Instant | null;
427
  toString(): string;
428
  toJSON(): string;
429
}
430

431
interface ToInstantOptions {
432
  disambiguation?: DisambiguationMode;
433
}
434

435
type DisambiguationMode = 'compatible' | 'earlier' | 'later' | 'reject';
436
```