diff --git a/datetime/constants.ts b/datetime/constants.ts index 96b6cba831c4..c5b606488673 100644 --- a/datetime/constants.ts +++ b/datetime/constants.ts @@ -10,6 +10,21 @@ * * SECOND; // 1_000 * ``` + * + * @example Migration to Temporal + * ```ts + * import { SECOND } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(30 * SECOND, 30_000); + * + * // After + * assertEquals(Temporal.Duration.from({ seconds: 30 }).total("milliseconds"), 30_000); + * ``` + * + * @deprecated Use {@linkcode Temporal.Duration} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const SECOND = 1e3; /** @@ -21,6 +36,21 @@ export const SECOND = 1e3; * * MINUTE; // 60_000 * ``` + * + * @example Migration to Temporal + * ```ts + * import { MINUTE } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(5 * MINUTE, 300_000); + * + * // After + * assertEquals(Temporal.Duration.from({ minutes: 5 }).total("milliseconds"), 300_000); + * ``` + * + * @deprecated Use {@linkcode Temporal.Duration} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const MINUTE: number = SECOND * 60; /** @@ -32,6 +62,21 @@ export const MINUTE: number = SECOND * 60; * * HOUR; // 3_600_000 * ``` + * + * @example Migration to Temporal + * ```ts + * import { HOUR } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(2 * HOUR, 7_200_000); + * + * // After + * assertEquals(Temporal.Duration.from({ hours: 2 }).total("milliseconds"), 7_200_000); + * ``` + * + * @deprecated Use {@linkcode Temporal.Duration} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const HOUR: number = MINUTE * 60; /** @@ -43,6 +88,21 @@ export const HOUR: number = MINUTE * 60; * * DAY; // 86_400_000 * ``` + * + * @example Migration to Temporal + * ```ts + * import { DAY } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(3 * DAY, 259_200_000); + * + * // After + * assertEquals(Temporal.Duration.from({ days: 3 }).total("milliseconds"), 259_200_000); + * ``` + * + * @deprecated Use {@linkcode Temporal.Duration} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const DAY: number = HOUR * 24; /** @@ -54,6 +114,25 @@ export const DAY: number = HOUR * 24; * * WEEK; // 604_800_000 * ``` + * + * @example Migration to Temporal + * ```ts + * import { WEEK } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(2 * WEEK, 1_209_600_000); + * + * // After + * assertEquals( + * Temporal.Duration.from({ weeks: 2 }) + * .total({ unit: "milliseconds", relativeTo: "2025-01-01" }), + * 1_209_600_000, + * ); + * ``` + * + * @deprecated Use {@linkcode Temporal.Duration} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const WEEK: number = DAY * 7; /** @@ -65,6 +144,21 @@ export const WEEK: number = DAY * 7; * * new Date(2025, JANUARY, 1); // 2025-01-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { JANUARY } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, JANUARY, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 1, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `1` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const JANUARY = 0; /** @@ -76,6 +170,21 @@ export const JANUARY = 0; * * new Date(2025, FEBRUARY, 1); // 2025-02-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { FEBRUARY } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, FEBRUARY, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 2, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `2` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const FEBRUARY = 1; /** @@ -87,6 +196,21 @@ export const FEBRUARY = 1; * * new Date(2025, MARCH, 1); // 2025-03-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { MARCH } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, MARCH, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 3, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `3` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const MARCH = 2; /** @@ -98,6 +222,21 @@ export const MARCH = 2; * * new Date(2025, APRIL, 1); // 2025-04-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { APRIL } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, APRIL, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 4, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `4` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const APRIL = 3; /** @@ -109,6 +248,21 @@ export const APRIL = 3; * * new Date(2025, MAY, 1); // 2025-05-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { MAY } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, MAY, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 5, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `5` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const MAY = 4; /** @@ -120,6 +274,21 @@ export const MAY = 4; * * new Date(2025, JUNE, 1); // 2025-06-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { JUNE } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, JUNE, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 6, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `6` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const JUNE = 5; /** @@ -131,6 +300,21 @@ export const JUNE = 5; * * new Date(2025, JULY, 1); // 2025-07-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { JULY } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, JULY, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 7, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `7` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const JULY = 6; /** @@ -142,6 +326,21 @@ export const JULY = 6; * * new Date(2025, AUGUST, 1); // 2025-08-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { AUGUST } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, AUGUST, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 8, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `8` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const AUGUST = 7; /** @@ -153,6 +352,21 @@ export const AUGUST = 7; * * new Date(2025, SEPTEMBER, 1); // 2025-09-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { SEPTEMBER } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, SEPTEMBER, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 9, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `9` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const SEPTEMBER = 8; /** @@ -164,6 +378,21 @@ export const SEPTEMBER = 8; * * new Date(2025, OCTOBER, 1); // 2025-10-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { OCTOBER } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, OCTOBER, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 10, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `10` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const OCTOBER = 9; /** @@ -175,6 +404,21 @@ export const OCTOBER = 9; * * new Date(2025, NOVEMBER, 1); // 2025-11-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { NOVEMBER } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, NOVEMBER, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 11, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `11` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const NOVEMBER = 10; /** @@ -186,6 +430,21 @@ export const NOVEMBER = 10; * * new Date(2025, DECEMBER, 1); // 2025-12-01 * ``` + * + * @example Migration to Temporal + * ```ts no-assert + * import { DECEMBER } from "@std/datetime/constants"; + * + * // Before + * new Date(2025, DECEMBER, 1); + * + * // After (Temporal months are 1-based) + * Temporal.PlainDate.from({ year: 2025, month: 12, day: 1 }); + * ``` + * + * @deprecated Use the 1-based month number `12` with + * {@linkcode Temporal.PlainDate} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const DECEMBER = 11; /** @@ -197,6 +456,22 @@ export const DECEMBER = 11; * * new Date(2025, JANUARY, 5).getDay() === SUNDAY; // true * ``` + * + * @example Migration to Temporal + * ```ts + * import { SUNDAY } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(new Date("2025-01-05T00:00").getDay(), SUNDAY); + * + * // After (ISO 8601: Monday is 1, Sunday is 7) + * assertEquals(Temporal.PlainDate.from("2025-01-05").dayOfWeek, 7); + * ``` + * + * @deprecated Use the day-of-week number `7` with + * {@linkcode Temporal.PlainDate.prototype.dayOfWeek} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const SUNDAY = 0; /** @@ -208,6 +483,22 @@ export const SUNDAY = 0; * * new Date(2025, JANUARY, 6).getDay() === MONDAY; // true * ``` + * + * @example Migration to Temporal + * ```ts + * import { MONDAY } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(new Date("2025-01-06T00:00").getDay(), MONDAY); + * + * // After (ISO 8601: Monday is 1, Sunday is 7) + * assertEquals(Temporal.PlainDate.from("2025-01-06").dayOfWeek, 1); + * ``` + * + * @deprecated Use the day-of-week number `1` with + * {@linkcode Temporal.PlainDate.prototype.dayOfWeek} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const MONDAY = 1; /** @@ -219,6 +510,22 @@ export const MONDAY = 1; * * new Date(2025, JANUARY, 7).getDay() === TUESDAY; // true * ``` + * + * @example Migration to Temporal + * ```ts + * import { TUESDAY } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(new Date("2025-01-07T00:00").getDay(), TUESDAY); + * + * // After (ISO 8601: Monday is 1, Sunday is 7) + * assertEquals(Temporal.PlainDate.from("2025-01-07").dayOfWeek, 2); + * ``` + * + * @deprecated Use the day-of-week number `2` with + * {@linkcode Temporal.PlainDate.prototype.dayOfWeek} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const TUESDAY = 2; /** @@ -230,6 +537,22 @@ export const TUESDAY = 2; * * new Date(2025, JANUARY, 1).getDay() === WEDNESDAY; // true * ``` + * + * @example Migration to Temporal + * ```ts + * import { WEDNESDAY } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(new Date("2025-01-01T00:00").getDay(), WEDNESDAY); + * + * // After (ISO 8601: Monday is 1, Sunday is 7) + * assertEquals(Temporal.PlainDate.from("2025-01-01").dayOfWeek, 3); + * ``` + * + * @deprecated Use the day-of-week number `3` with + * {@linkcode Temporal.PlainDate.prototype.dayOfWeek} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const WEDNESDAY = 3; /** @@ -241,6 +564,22 @@ export const WEDNESDAY = 3; * * new Date(2025, JANUARY, 2).getDay() === THURSDAY; // true * ``` + * + * @example Migration to Temporal + * ```ts + * import { THURSDAY } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(new Date("2025-01-02T00:00").getDay(), THURSDAY); + * + * // After (ISO 8601: Monday is 1, Sunday is 7) + * assertEquals(Temporal.PlainDate.from("2025-01-02").dayOfWeek, 4); + * ``` + * + * @deprecated Use the day-of-week number `4` with + * {@linkcode Temporal.PlainDate.prototype.dayOfWeek} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const THURSDAY = 4; /** @@ -252,6 +591,22 @@ export const THURSDAY = 4; * * new Date(2025, JANUARY, 3).getDay() === FRIDAY; // true * ``` + * + * @example Migration to Temporal + * ```ts + * import { FRIDAY } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(new Date("2025-01-03T00:00").getDay(), FRIDAY); + * + * // After (ISO 8601: Monday is 1, Sunday is 7) + * assertEquals(Temporal.PlainDate.from("2025-01-03").dayOfWeek, 5); + * ``` + * + * @deprecated Use the day-of-week number `5` with + * {@linkcode Temporal.PlainDate.prototype.dayOfWeek} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const FRIDAY = 5; /** @@ -263,5 +618,21 @@ export const FRIDAY = 5; * * new Date(2025, JANUARY, 4).getDay() === SATURDAY; // true * ``` + * + * @example Migration to Temporal + * ```ts + * import { SATURDAY } from "@std/datetime/constants"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(new Date("2025-01-04T00:00").getDay(), SATURDAY); + * + * // After (ISO 8601: Monday is 1, Sunday is 7) + * assertEquals(Temporal.PlainDate.from("2025-01-04").dayOfWeek, 6); + * ``` + * + * @deprecated Use the day-of-week number `6` with + * {@linkcode Temporal.PlainDate.prototype.dayOfWeek} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export const SATURDAY = 6; diff --git a/datetime/day_of_year.ts b/datetime/day_of_year.ts index 85914f65ba98..9ad1754a8725 100644 --- a/datetime/day_of_year.ts +++ b/datetime/day_of_year.ts @@ -16,6 +16,21 @@ import { DAY } from "./constants.ts"; * * assertEquals(dayOfYear(new Date("2019-03-11T03:24:00")), 70); * ``` + * + * @example Migration to Temporal + * ```ts + * import { dayOfYear } from "@std/datetime/day-of-year"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(dayOfYear(new Date("2019-03-11T03:24:00")), 70); + * + * // After + * assertEquals(Temporal.PlainDate.from("2019-03-11").dayOfYear, 70); + * ``` + * + * @deprecated Use {@linkcode Temporal.PlainDate.prototype.dayOfYear} instead. + * See https://github.com/denoland/std/issues/7262 for details. */ export function dayOfYear(date: Date): number { // Values from 0 to 99 map to the years 1900 to 1999. All other values are the actual year. (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date) @@ -43,6 +58,24 @@ export function dayOfYear(date: Date): number { * * assertEquals(dayOfYearUtc(new Date("2019-03-11T03:24:00.000Z")), 70); * ``` + * + * @example Migration to Temporal + * ```ts + * import { dayOfYearUtc } from "@std/datetime/day-of-year"; + * import { assertEquals } from "@std/assert"; + * + * const date = new Date("2019-03-11T03:24:00.000Z"); + * + * // Before + * assertEquals(dayOfYearUtc(date), 70); + * + * // After + * assertEquals(date.toTemporalInstant().toZonedDateTimeISO("UTC").dayOfYear, 70); + * ``` + * + * @deprecated Use {@linkcode Date.prototype.toTemporalInstant} and + * {@linkcode Temporal.ZonedDateTime.prototype.dayOfYear} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export function dayOfYearUtc(date: Date): number { // Values from 0 to 99 map to the years 1900 to 1999. All other values are the actual year. (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date) diff --git a/datetime/difference.ts b/datetime/difference.ts index 7dfd98b6b088..ec23fd0449fb 100644 --- a/datetime/difference.ts +++ b/datetime/difference.ts @@ -6,6 +6,9 @@ import { DAY, HOUR, MINUTE, SECOND, WEEK } from "./constants.ts"; /** * Duration units for {@linkcode DifferenceFormat} and * {@linkcode DifferenceOptions}. + * + * @deprecated Use {@linkcode Temporal.Duration} unit strings instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export type Unit = | "milliseconds" @@ -18,10 +21,20 @@ export type Unit = | "quarters" | "years"; -/** Return type for {@linkcode difference}. */ +/** + * Return type for {@linkcode difference}. + * + * @deprecated Use {@linkcode Temporal.Duration} instead. See + * https://github.com/denoland/std/issues/7262 for details. + */ export type DifferenceFormat = Partial>; -/** Options for {@linkcode difference}. */ +/** + * Options for {@linkcode difference}. + * + * @deprecated Use the options of {@linkcode Temporal.PlainDate.prototype.until} + * instead. See https://github.com/denoland/std/issues/7262 for details. + */ export type DifferenceOptions = { /** * Units to calculate difference in. Defaults to all units. @@ -87,6 +100,27 @@ function calculateMonthsDifference(from: Date, to: Date): number { * years: 1 * }); * ``` + * + * @example Migration to Temporal + * ```ts + * import { difference } from "@std/datetime/difference"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * const date0 = new Date("2018-05-14"); + * const date1 = new Date("2020-05-13"); + * assertEquals(difference(date0, date1).years, 1); + * + * // After + * const start = Temporal.PlainDate.from("2018-05-14"); + * const end = Temporal.PlainDate.from("2020-05-13"); + * assertEquals(start.until(end, { largestUnit: "years" }).years, 1); + * assertEquals(start.until(end, { largestUnit: "days" }).days, 730); + * ``` + * + * @deprecated Use {@linkcode Temporal.PlainDate.prototype.until} or + * {@linkcode Temporal.PlainDate.prototype.since} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export function difference( from: Date, diff --git a/datetime/format.ts b/datetime/format.ts index f8b69d0715b1..324a508f8255 100644 --- a/datetime/format.ts +++ b/datetime/format.ts @@ -3,7 +3,12 @@ import { DateTimeFormatter } from "./_date_time_formatter.ts"; -/** Options for {@linkcode format}. */ +/** + * Options for {@linkcode format}. + * + * @deprecated Use {@linkcode Intl.DateTimeFormat} instead. See + * https://github.com/denoland/std/issues/7262 for details. + */ export interface FormatOptions { /** * The timezone the formatted date should be in. @@ -71,6 +76,28 @@ export interface FormatOptions { * * assertEquals(format(date, "yyyy-MM-dd HH:mm:ss", { timeZone: "UTC" }), "2019-01-20 05:34:23"); * ``` + * + * @example Migration to Temporal + * + * For ISO 8601 output, use the `toString()` methods of the Temporal classes. + * For locale-aware output, use {@linkcode Intl.DateTimeFormat}. + * + * ```ts + * import { format } from "@std/datetime/format"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(format(new Date(2019, 0, 20), "yyyy-MM-dd"), "2019-01-20"); + * + * // After + * const date = Temporal.PlainDate.from({ year: 2019, month: 1, day: 20 }); + * assertEquals(date.toString(), "2019-01-20"); + * assertEquals(new Intl.DateTimeFormat("en-US").format(new Date(2019, 0, 20)), "1/20/2019"); + * ``` + * + * @deprecated Use {@linkcode Intl.DateTimeFormat} or the `toString()` and + * `toLocaleString()` methods of the Temporal classes instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export function format( date: Date, diff --git a/datetime/is_leap.ts b/datetime/is_leap.ts index b3030dba11f9..d17fe91d7eb4 100644 --- a/datetime/is_leap.ts +++ b/datetime/is_leap.ts @@ -44,6 +44,21 @@ function isYearNumberALeapYear(yearNumber: number): boolean { * isLeap(2000); * * ``` + * + * @example Migration to Temporal + * ```ts + * import { isLeap } from "@std/datetime/is-leap"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(isLeap(1972), true); + * + * // After + * assertEquals(Temporal.PlainDate.from({ year: 1972, month: 1, day: 1 }).inLeapYear, true); + * ``` + * + * @deprecated Use {@linkcode Temporal.PlainDate.prototype.inLeapYear} instead. + * See https://github.com/denoland/std/issues/7262 for details. */ export function isLeap(year: Date | number): boolean { const yearNumber = year instanceof Date ? year.getFullYear() : year; @@ -73,6 +88,24 @@ export function isLeap(year: Date | number): boolean { * * assertEquals(isUtcLeap(1999), false); * ``` + * + * @example Migration to Temporal + * ```ts + * import { isUtcLeap } from "@std/datetime/is-leap"; + * import { assertEquals } from "@std/assert"; + * + * const date = new Date("2000-01-01"); + * + * // Before + * assertEquals(isUtcLeap(date), true); + * + * // After + * assertEquals(date.toTemporalInstant().toZonedDateTimeISO("UTC").inLeapYear, true); + * ``` + * + * @deprecated Use {@linkcode Date.prototype.toTemporalInstant} and + * {@linkcode Temporal.ZonedDateTime.prototype.inLeapYear} instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export function isUtcLeap(year: Date | number): boolean { const yearNumber = year instanceof Date ? year.getUTCFullYear() : year; diff --git a/datetime/parse.ts b/datetime/parse.ts index cfa6f03b076f..46bc5362da15 100644 --- a/datetime/parse.ts +++ b/datetime/parse.ts @@ -43,6 +43,27 @@ import { DateTimeFormatter } from "./_date_time_formatter.ts"; * * assertEquals(parse("01-03-2019 16:33:23.123", "MM-dd-yyyy HH:mm:ss.SSS"), new Date(2019, 0, 3, 16, 33, 23, 123)); * ``` + * + * @example Migration to Temporal + * + * Temporal parses ISO 8601 strings only. For other formats, parse the parts + * manually or use a userland library. + * + * ```ts + * import { parse } from "@std/datetime/parse"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(parse("01-03-2019 16:30", "MM-dd-yyyy HH:mm"), new Date(2019, 0, 3, 16, 30)); + * + * // After (ISO 8601 input) + * const dateTime = Temporal.PlainDateTime.from("2019-01-03T16:30"); + * assertEquals(dateTime.toString(), "2019-01-03T16:30:00"); + * ``` + * + * @deprecated Use {@linkcode Temporal.PlainDateTime.from} or + * {@linkcode Temporal.Instant.from} for ISO 8601 strings instead. See + * https://github.com/denoland/std/issues/7262 for details. */ export function parse(dateString: string, formatString: string): Date { const formatter = new DateTimeFormatter(formatString); diff --git a/datetime/week_of_year.ts b/datetime/week_of_year.ts index 716cd105e47a..0af41fa07dbb 100644 --- a/datetime/week_of_year.ts +++ b/datetime/week_of_year.ts @@ -30,6 +30,21 @@ const Day = { * * assertEquals(weekOfYear(new Date("2020-07-10T03:24:00")), 28); * ``` + * + * @example Migration to Temporal + * ```ts + * import { weekOfYear } from "@std/datetime/week-of-year"; + * import { assertEquals } from "@std/assert"; + * + * // Before + * assertEquals(weekOfYear(new Date("2020-12-28T03:24:00")), 53); + * + * // After + * assertEquals(Temporal.PlainDate.from("2020-12-28").weekOfYear, 53); + * ``` + * + * @deprecated Use {@linkcode Temporal.PlainDate.prototype.weekOfYear} instead. + * See https://github.com/denoland/std/issues/7262 for details. */ export function weekOfYear(date: Date): number { const workingDate = new Date(