Skip to content

Latest commit

 

History

History
278 lines (171 loc) · 8.22 KB

README.md

File metadata and controls

278 lines (171 loc) · 8.22 KB
Raw

temporal-fns

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

Installation

bun install temporal-fns
npm install temporal-fns
pnpm install temporal-fns

Functions

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).

Arguments

  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.

Returns

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

Example

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.

Arguments

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

Returns

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

Example

import { Temporal } from "@js-temporal/polyfill";
import { startOfWeek } from "temporal-fns";

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).

Arguments

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

Returns

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

Example

import { 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).

Arguments

  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.

Returns

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

Example

import { 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.

Arguments

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

Returns

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

Example

import { 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).

Arguments

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

Returns

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

Example

import { 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.

Arguments

  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).

Returns

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

Example

import { 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.

Arguments

  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).

Returns

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

Example

import { 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.

Arguments

  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).

Returns

(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.

Example

import { 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.

Arguments

  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).

Returns

(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.

Example

import { 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