# @locale-tools/datetime

> Datetime localization tools

Latest version **0.2.0** (published 2021-11-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install @locale-tools/datetime
pnpm add @locale-tools/datetime
yarn add @locale-tools/datetime
bun add @locale-tools/datetime
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2021-11-26 |
| First published | 2021-11-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 467.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Sara Pope |
| Maintainers | gretzky |
| Keywords | date, time, timezones, tz-timezones, date-fns, date-fns-tz, tz, tz-database |

## Links

- npm: https://www.npmjs.com/package/@locale-tools/datetime
- Repository: https://github.com/gretzky/locale-tools
- Homepage: https://github.com/gretzky/locale-tools#readme
- Issues: https://github.com/gretzky/locale-tools/issues
- npm.io page: https://npm.io/package/@locale-tools/datetime

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 0.2.0 (latest) — 2021-11-26

## README

# @locale-tools/datetime

List of all currencies and a currency conversion tool.

## Installation

Install a given package with npm or yarn.

```bash
npm install @locale-tools/datetime

yarn add @locale-tools/datetime
```

## Usage

A full list of tz database timezones can be found in `src/data/timezones.json`

```ts
import { timezones } from "@locale-tools/datetime";
```

### Types

```ts
// week start day -- both strings and enum valid
enum WeekStartDays {
  FRIDAY = "friday",
  SATURDAY = "saturday",
  SUNDAY = "sunday",
  MONDAY = "monday"
}
type WeekStartDay = `${WeekStartDays}` | WeekStartDays

// hour clock -- both strings and enum valid
enum HourClocks {
  AM_PM = "12hr",
  MILITARY = "24hr",
  MIXED = "mixed"
}
type HourClock = `${HourClocks}` | HourClocks

// timezone object
type Timezone = {
  name: Timezones;
  type: "canonical" | "link";
  linkedTo: string | null;
  utcOffset: string;
  dstOffset: string;
};

// tz database timezone names
enum TZTimezones {}
TZTimezones.windhoek; // "Africa/Windhoek"
```

### Methods

#### `getDateFnsLocale(locale: IETF, { fallbackLocale }): DateFnsLocale`

Returns a [date-fns locale object](https://date-fns.org/v2.25.0/docs/Locale) to use with date-fns. If a direct match is not found, it'll try to detect the closest locale, otherwise it uses a fallback. The default fallback is `en-US`.

| Parameter      | Type   | Description                                     | Default      |
| -------------- | ------ | ----------------------------------------------- | ------------ |
| locale         | `IETF` | IETF locale to match                            | **Required** |
| fallbackLocale | `IETF` | Fallback IETF locale if no date-fns match found | `en-US`      |

```ts
import { getDateFnsLocale } from "@locale-tools/datetime";

const dateFnsLocaleDirect = getDateFnsLocale("en-AU"); // en-AU locale object

const dateFnsLocaleClosest = getDateFnsLocale("es-PY"); // es locale object (no es-PY date-fns locale object)

const dateFnsLocaleFallback = getDateFnsLocale("aay"); // there is no 'aay' locale or a closest match, so this will returns en-US locale object as a fallback

const dateFnsLocaleFallbackCustom = getDateFnsLocale("aay", {
  fallbackLocale: "en-CA"
}); // will return en-CA as a fallback
```

#### `getDatePatternForLocale(locale: IETF)`

Returns the date format pattern (e.g. 'dd-MM-yyyy') for a given IETF locale.

| Parameter | Type   | Description                        | Default      |
| --------- | ------ | ---------------------------------- | ------------ |
| locale    | `IETF` | IETF locale to get the pattern for | **Required** |

```ts
import { getDatePatternForLocale } from "@locale-tools/datetime";

const datePattern = getDatePatternForLocale("nl-AW"); // returns "dd-MM-yyyy"
```

#### `getDateTimeForTimezone({ date, dateTimeFormat, timezone, serverTimezone }): Date`

Returns a date formatted and converted to a given timezone.

| Parameter      | Type                   | Description                 | Default      |
| -------------- | ---------------------- | --------------------------- | ------------ |
| date           | `Date, string, number` | The date to format          | `Date.now()` |
| dateTimeFormat | `string`               | Date format pattern         | **Required** |
| timezone       | `TZTimezone`           | Timezone to format to       | **Required** |
| serverTimezone | `TZTimezone`           | Timezone to compare against | `UTC`        |

```ts
import { getDateTimeForTimezone } from "@locale-tools/datetime";

const dateTimeInTimezone = getDateTimeForTimezone({
  date: 1636911831222,
  dateTimeFormat: "dd-MM-yyyy HH:mm",
  timezone: "Africa/Windhoek"
});
// returns "14-11-2021 19:44"
```

---
_Source: https://npm.io/package/@locale-tools/datetime · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._