Temporal (#1895)

Author: thisisjofrank

examples/scripts/temporal.ts

@@ -2,36 +2,36 @@
  * @title Temporal API
  * @difficulty beginner
  * @tags cli
- * @run <url>
+ * @run --unstable-temporal <url>
  * @resource {https://docs.deno.com/api/web/~/Temporal} Temporal API reference documentation
  * @resource {https://tc39.es/proposal-temporal/docs} Temporal API proposal documentation
  * @group Unstable APIs
  */
 
 // Get the current date
-const date = Temporal.Now.plainDateISO(); // 2025-01-31
+const date = Temporal.Now.plainDateISO();
 
-// Return the date in ISO 8601 date format
-const dateAsString = date.toString(); // "2025-01-31"
+// Return the date in ISO 8601 date format (eg "2025-01-31")
+const dateAsString = date.toString();
 console.log(`Temporal date as string: ${dateAsString}`);
 
-// Get current date and time in ISO 8601 format
-const plainDateTimeIsoString = Temporal.Now.plainDateTimeISO().toString(); // "2025-01-31T10:51:40.269979904"
+// Get current date and time in ISO 8601 format (eg "2025-01-31T10:51:40.269979904")
+const plainDateTimeIsoString = Temporal.Now.plainDateTimeISO().toString();
 console.log(`Temporal plainDateTimeISO as string: ${plainDateTimeIsoString}`);
 
-// Get Unix timestamp
-const timeStamp = Temporal.Now.instant(); // 2025-01-31T18:51:59.093355008Z
+// Get Unix timestamp (eg 2025-01-31T18:51:59.093355008Z)
+const timeStamp = Temporal.Now.instant();
 console.log(`Temporal timestamp as string: ${timeStamp}`);
 
-// Return timestamp in milliseconds
-const epochMilliseconds = timeStamp.epochMilliseconds; // 1738349519093
+// Return timestamp in milliseconds (eg 1738349519093)
+const epochMilliseconds = timeStamp.epochMilliseconds;
 console.log(`Temporal timestamp epoch milliseconds: ${epochMilliseconds}`);
 
-// Get date and time in ISO 8601 format from milliseconds
-const futureTime = Temporal.Instant.fromEpochMilliseconds(1851222399924); // 2028-08-30T04:26:39.924Z
+// Get date and time in ISO 8601 format from milliseconds (eg "2025-01-31T18:51:59.093Z")
+const futureTime = Temporal.Instant.fromEpochMilliseconds(1851222399924);
 console.log(`Temporal future time: ${futureTime}`);
 
 // Measure difference in hours from now.
 const now = Temporal.Now.instant();
-const differenceInHours = now.until(futureTime, { smallestUnit: "hour" }); // PT31600H
+const differenceInHours = now.until(futureTime, { smallestUnit: "hour" });
 console.log(`Temporal difference in hours: ${differenceInHours}`);

runtime/reference/cli/unstable_flags.md

@@ -241,3 +241,43 @@ deno run --unstable your_script.ts
 
 It is recommended that you use the granular unstable flags instead of this, the
 `--unstable` flag is now deprecated and will be removed in Deno 2.
+
+## `--unstable-temporal`
+
+Enable the experimental [Temporal API](https://tc39.es/proposal-temporal/docs/)
+in the global scope. The Temporal API is a modern date and time API that is
+being developed as a replacement for the legacy `Date` object in JavaScript. It
+provides better support for time zones, calendars, and more precise date/time
+calculations.
+
+To use the Temporal API in your Deno program, run it with the flag:
+
+```sh
+deno run --unstable-temporal your_script.ts
+```
+
+Or configure it in your `deno.json`:
+
+```json title="deno.json"
+{
+  "unstable": ["temporal"]
+}
+```
+
+```ts title="example.ts"
+// Example using Temporal API
+const now = Temporal.Now.plainDateTimeISO();
+console.log(`Current date and time: ${now}`);
+
+const date = Temporal.PlainDate.from("2025-07-10");
+const nextWeek = date.add({ days: 7 });
+console.log(`Next week: ${nextWeek}`);
+
+// Working with time zones
+const zonedDateTime = Temporal.Now.zonedDateTimeISO("America/New_York");
+console.log(`Time in New York: ${zonedDateTime}`);
+```
+
+Note that the Temporal API is still experimental and the specification may
+change before it becomes stable. Use this flag only for testing and
+experimentation.