temporal-fns

A utility library for working with Temporal dates and times, providing helper functions for common date and time manipulations.

$3

``bash
bun install temporal-fns
npm install temporal-fns
pnpm install temporal-fns
`

Functions

- startOfMonth
- startOfWeek
- startOfDay
- endOfMonth
- endOfWeek
- endOfDay
- nextDayOfWeek
- previousDayOfWeek
- firstDayOfWeekOfMonth
- lastDayOfWeekOfMonth

startOfMonth

Gets the first day of the month for the given Temporal object. Optionally, the time can be preserved instead of resetting to the start of the day (00:00:00.000000000).

$3

1. temporal _(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: The Temporal object to query.
2. [options] _(Object)_: The options object.
- preserveTime _(boolean)_: Specify whether to preserve the original time. Defaults to false.

$3

_(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: Returns the new Temporal object set to the first day of the month.

$3

`ts
import { Temporal } from "@js-temporal/polyfill";
import { startOfMonth } from "temporal-fns";

const dateTime = Temporal.PlainDateTime.from("2024-02-24T14:24:24");

startOfMonth(dateTime);
// => Temporal.PlainDateTime 2024-02-01T00:00:00

startOfMonth(dateTime, { preserveTime: true });
// => Temporal.PlainDateTime 2024-02-01T14:24:24
`

startOfWeek

Gets the first day of the week (Monday) for the given Temporal object.

$3

1. temporal _(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: The Temporal object to query.

$3

_(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: Returns the new Temporal object set to the first day of the week (Monday).

$3

`ts
import { Temporal } from "@js-temporal/polyfill";
import { setTemporalPolyfill, startOfWeek } from "temporal-fns";

setTemporalPolyfill(Temporal);

const date = Temporal.PlainDate.from("2024-02-21"); // A Wednesday

startOfWeek(date);
// => Temporal.PlainDate 2024-02-19 (Monday)
`

startOfDay

Sets the time to the start of the day (00:00:00.000000000).

$3

1. temporal _(Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: The Temporal object to modify.

$3

_(Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: Returns the new Temporal object with the time set to the start of the day.

$3

`ts
import type { Temporal } from "@js-temporal/polyfill";
import { startOfDay } from "temporal-fns";

const dateTime = Temporal.PlainDateTime.from("2024-02-24T14:24:24");

startOfDay(dateTime);
// => Temporal.PlainDateTime 2024-02-24T00:00:00
`

endOfMonth

Gets the last day of the month for the given Temporal object. Optionally, the time can be preserved instead of resetting to the end of the day (23:59:59.999999999).

$3

1. temporal _(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: The Temporal object to query.
2. [options] _(Object)_: The options object.
- preserveTime _(boolean)_: Specify whether to preserve the original time. Defaults to false.

$3

_(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: Returns the new Temporal object set to the last day of the month.

$3

`ts
import type { Temporal } from "@js-temporal/polyfill";
import { endOfMonth } from "temporal-fns";

const dateTime = Temporal.PlainDateTime.from("2024-02-24T14:24:24");

endOfMonth(dateTime);
// => Temporal.PlainDateTime 2024-02-29T23:59:59.999999999

endOfMonth(dateTime, { preserveTime: true });
// => Temporal.PlainDateTime 2024-02-29T14:24:24
`

endOfWeek

Gets the last day of the week (Sunday) for the given Temporal object.

$3

1. temporal _(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: The Temporal object to query.

$3

_(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: Returns the new Temporal object set to the last day of the week (Sunday).

$3

`ts
import type { Temporal } from "@js-temporal/polyfill";
import { endOfWeek } from "temporal-fns";

const date = Temporal.PlainDate.from("2024-02-21"); // A Wednesday

endOfWeek(date);
// => Temporal.PlainDate 2024-02-25 (Sunday)
`

endOfDay

Sets the time to the end of the day (23:59:59.999999999).

$3

1. temporal _(Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: The Temporal object to modify.

$3

_(Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: Returns the new Temporal object with the time set to the end of the day.

$3

`ts
import type { Temporal } from "@js-temporal/polyfill";
import { endOfDay } from "temporal-fns";

const dateTime = Temporal.PlainDateTime.from("2024-02-24T14:24:24");

endOfDay(dateTime);
// => Temporal.PlainDateTime 2024-02-24T23:59:59.999999999
`

nextDayOfWeek

Gets the next occurrence of a specific day of the week after the given Temporal object.

$3

1. temporal _(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: The Temporal object to query.
2. dayOfWeek _(1 | 2 | 3 | 4 | 5 | 6 | 7)_: The desired day of the week (1 = Monday, 7 = Sunday).

$3

_(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: Returns the new Temporal object set to the next occurrence of the specified day of the week.

$3

`ts
import type { Temporal } from "@js-temporal/polyfill";
import { nextDayOfWeek } from "temporal-fns";

const date = Temporal.PlainDate.from("2024-02-21");

nextDayOfWeek(date, 5); // Next Friday
// => Temporal.PlainDate 2024-02-23
`

previousDayOfWeek

Gets the previous occurrence of a specific day of the week before the given Temporal object.

$3

1. temporal _(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: The Temporal object to query.
2. dayOfWeek _(1 | 2 | 3 | 4 | 5 | 6 | 7)_: The desired day of the week (1 = Monday, 7 = Sunday).

$3

_(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: Returns the new Temporal object set to the previous occurrence of the specified day of the week.

$3

`ts
import type { Temporal } from "@js-temporal/polyfill";
import { previousDayOfWeek } from "temporal-fns";

const date = Temporal.PlainDate.from("2024-02-21");

previousDayOfWeek(date, 1); // Previous Monday
// => Temporal.PlainDate 2024-02-19
`

firstDayOfWeekOfMonth

Gets the first occurrence of a specific day of the week in the month of the given Temporal object.

$3

1. temporal _(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: The Temporal object to query.
2. dayOfWeek _(1 | 2 | 3 | 4 | 5 | 6 | 7)_: The desired day of the week (1 = Monday, 7 = Sunday).

$3

_(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: Returns the new Temporal object set to the first occurrence of the specified day of the week in the month.

$3

`ts
import type { Temporal } from "@js-temporal/polyfill";
import { firstDayOfWeekOfMonth } from "temporal-fns";

const date = Temporal.PlainDate.from("2024-02-24");

firstDayOfWeekOfMonth(date, 1); // First Monday of the month
// => Temporal.PlainDate 2024-02-05
`

lastDayOfWeekOfMonth

Gets the last occurrence of a specific day of the week in the month of the given Temporal object.

$3

1. temporal _(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: The Temporal object to query.
2. dayOfWeek _(1 | 2 | 3 | 4 | 5 | 6 | 7)_: The desired day of the week (1 = Monday, 7 = Sunday).

$3

_(Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime)_: Returns the new Temporal object set to the last occurrence of the specified day of the week in the month.

$3

`ts
import type { Temporal } from "@js-temporal/polyfill";
import { lastDayOfWeekOfMonth } from "temporal-fns";

const date = Temporal.PlainDate.from("2024-02-24");

lastDayOfWeekOfMonth(date, 1); // Last Monday of the month
// => Temporal.PlainDate 2024-02-26
``