https://github.com/devmamunur/timezone-utility

Lightweight timezone management utility compatible with CommonJS, ES Modules (ESM), JavaScript, and TypeScript, featuring zero dependencies.
https://github.com/devmamunur/timezone-utility
commonjs datetime-conversion esm javascript timezone-conversion timezone-list timezone-management timezones typescript
Last synced: 2 months ago
JSON representation
Lightweight timezone management utility compatible with CommonJS, ES Modules (ESM), JavaScript, and TypeScript, featuring zero dependencies.
Host: GitHub
URL: https://github.com/devmamunur/timezone-utility
Owner: devmamunur
Created: 2024-10-17T23:12:01.000Z (12 months ago)
Default Branch: main
Last Pushed: 2024-10-19T10:37:35.000Z (12 months ago)
Last Synced: 2024-10-19T12:07:01.856Z (12 months ago)
Topics: commonjs, datetime-conversion, esm, javascript, timezone-conversion, timezone-list, timezone-management, timezones, typescript
Language: TypeScript
Homepage:
Size: 54.7 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
Awesome Lists containing this project

README

          # Timezone Utility

A versatile timezone management package designed for CommonJS, ES Module (ESM), JavaScript, and TypeScript projects. It offers a range of features, including timezone listing, retrieving labels and values, region-based filtering, and converting between UTC and other timezones.

## Table of Contents

- [Installation](#installation)

- [Usage](#usage)

- [Methods Overview](#methods-overview)

- [Methods](#methods)

  - [isISODateTime](#isISODateTime)

  - [isValidTimeZone](#isValidTimeZone)

  - [convertDateTime](#convertDateTime)

  - [list](#list)

  - [listWithOnlyValue](#listWithOnlyValue)

  - [listWithOnlyLabel](#listWithOnlyLabel)

  - [listByRegion](#listByRegion)

  - [listByCountry](#listByCountry)

  - [getDetailsUsingTimeZoneValue](#getDetailsUsingTimeZoneValue)

  - [getRegions](#getRegions)

  - [convertUTCToTimeZone](#convertUTCToTimeZone)

  - [convertToUTC](#convertToUTC)

  - [convertBetweenTimeZones](#convertBetweenTimeZones)

  - [getCurrentTimeInTimeZone](#getCurrentTimeInTimeZone)

  - [getTimeDifferenceBetweenTimeZones](#getTimeDifferenceBetweenTimeZones)

  - [convertUTCToLocal](#convertUTCToLocal)

  - [formatDateTime](#formatDateTime)

  - [getLocalTimeZone](#getLocalTimeZone)

- [TypeScript Support](#typescript-support)

- [Error Handling](#error-handling)

- [License](#license)

- [Contributing](#contributing)

## Installation

Install the package using npm:

```bash

npm install timezone-utility

```

## Usage

```javascript

// For ES Module (ESM)

import { TimeZone } from "timezone-utility";

// For CommonJS

const { TimeZone } = require("timezone-utility");

```

## Methods Overview

| Method Name | Description |

|-------------|-------------|

| `isISODateTime` | Validates if a string is a valid ISO date-time format. |

| `isValidTimeZone` | Validates if a given string is a valid time zone. |

| `convertDateTime` | Converts a date-time from one time zone to another. |

| `list` | Returns a list of all available time zones. |

| `listWithOnlyValue` | Returns a list of all time zone values. |

| `listWithOnlyLabel` | Returns a list of all time zone labels. |

| `listByRegion` | Lists time zones for a specific region. |

| `listByCountry` | Lists time zones for a specific country. |

| `getDetailsUsingTimeZoneValue` | Gets the details for a given time zone value. |

| `getRegions` | Returns a list of all available regions. |

| `convertUTCToTimeZone` | Converts a UTC date to a specified time zone. |

| `convertToUTC` | Converts a date-time from a specified time zone to UTC. |

| `convertBetweenTimeZones` | Converts a date-time between two specified time zones. |

| `getCurrentTimeInTimeZone` | Gets the current time in a specified time zone. |

| `getTimeDifferenceBetweenTimeZones` | Calculates the time difference between two time zones. |

| `convertUTCToLocal` | Converts UTC date-time to Local date-time. |

| `formatDateTime` | Format an ISO date-time string using a custom format pattern. |

| `getLocalTimeZone` | Get the user's local timezone. |

## Methods

### isISODateTime

Validates if a string is a valid ISO date-time format.

```javascript

const isValid1 = TimeZone.isISODateTime('2023-10-10T10:00:00');

console.log(isValid1); // true

const isValid2 = TimeZone.isISODateTime('invalid-date');

console.log(isValid2); // false

```

Parameters:

- `dateTime: string`: The date-time string to validate.

Returns:

- `boolean`: True if the string is a valid ISO date-time, false otherwise.

### isValidTimeZone

Validates if a given string is a valid time zone.

```javascript

const isValid1 = TimeZone.isValidTimeZone('UTC');

console.log(isValid1); // true

const isValid2 = TimeZone.isValidTimeZone('Invalid/Zone');

console.log(isValid2); // false

```

Parameters:

- `timeZone: string`: The time zone string to validate.

Returns:

- `boolean`: True if the time zone is valid, false otherwise.

### convertDateTime

Converts a date-time from one time zone to another.

```javascript

// Using string input

const converted1 = TimeZone.convertDateTime(

  '2023-10-10T10:00:00', 

  'UTC', 

  'America/New_York', 

  true

);

console.log(converted1); // "2023-10-10T06:00:00"

// Using Date object input

const dateTime = new Date('2023-10-10T10:00:00Z');

const converted2 = TimeZone.convertDateTime(

  dateTime, 

  'UTC', 

  'America/New_York', 

  true

);

console.log(converted2); // "2023-10-10T06:00:00"

```

Parameters:

- `dateTime: Date | string`: The date-time to convert.

- `sourceTimeZone: string`: The source time zone.

- `targetTimeZone: string`: The target time zone.

- `returnISO: boolean`: Whether to return ISO format (default: true).

Returns:

- `string | Error`: Converted date-time string or Error if conversion fails.

### list

Returns a list of all available time zones.

```javascript

const timeZones = TimeZone.list();

console.log(timeZones);

/* OUTPUT:

[

  {

    "label": "(UTC-05:00) America/New_York",

    "value": "America/New_York",

    "country": "United States",

    "phoneCode": "+1",

    "utcOffset": "-05:00"

  },

  ...

]

*/

```

Returns:

- `Array`: Array of TimeZoneEntry objects.

### listWithOnlyValue

Returns a list of all time zone values without labels.

```javascript

const timeZoneValues = TimeZone.listWithOnlyValue();

console.log(timeZoneValues);

/* OUTPUT:

["Africa/Abidjan", "Africa/Accra", "America/New_York", "Europe/London", "Asia/Tokyo", ...]

*/

```

Returns:

- `Array`: Array of time zone values.

### listWithOnlyLabel

Returns a list of all time zone labels without values.

```javascript

const timeZoneLabels = TimeZone.listWithOnlyLabel();

console.log(timeZoneLabels);

/* OUTPUT:

["(UTC-05:00) America/New_York", "(UTC+00:00) London", ...]

*/

```

Returns:

- `Array`: Array of time zone labels.

### listByRegion

Lists time zones for a specific region.

```javascript

const timeZonesInAmerica = TimeZone.listByRegion('America');

console.log(timeZonesInAmerica);

/* OUTPUT:

[

  {

    "label": "(UTC-05:00) America/New_York",

    "value": "America/New_York",

    "country": "United States",

    "phoneCode": "+1",

    "utcOffset": "-05:00"

  },

  ...

]

*/

```

Parameters:

- `region: string`: The region to filter time zones.

Returns:

- `Array`: Array of TimeZoneEntry objects for the specified region.

### listByCountry

Lists time zones for a specific country.

```javascript

const timeZonesInUS = TimeZone.listByCountry('United States');

console.log(timeZonesInUS);

/* OUTPUT:

[

  {

    "label": "(UTC-05:00) America/New_York",

    "value": "America/New_York",

    "country": "United States",

    "phoneCode": "+1",

    "utcOffset": "-05:00"

  },

  ...

]

*/

```

Parameters:

- `country: string`: The country to filter time zones.

Returns:

- `Array`: Array of TimeZoneEntry objects for the specified country.

### getDetailsUsingTimeZoneValue

Gets the details for a given time zone value.

```javascript

const tzDetails = TimeZone.getDetailsUsingTimeZoneValue('America/New_York');

console.log(tzDetails);

/* OUTPUT:

{

  "label": "(UTC-05:00) America/New_York",

  "value": "America/New_York",

  "country": "United States",

  "phoneCode": "+1",

  "utcOffset": "-05:00"

}

*/

```

Parameters:

- `value: string`: The time zone value.

Returns:

- `TimeZoneEntry | null`: The corresponding details or null if not found.

### getRegions

Returns a list of all available regions.

```javascript

const regions = TimeZone.getRegions();

console.log(regions);

/* OUTPUT:

["Africa", "America", "Asia", "Atlantic", "Australia", "Europe", "Indian", "Pacific"]

*/

```

Returns:

- `Array`: Array of region strings.

### convertUTCToTimeZone

Converts a UTC date to a specified time zone.

```javascript

// Using ISO string with default options (ISO format)

const converted1 = TimeZone.convertUTCToTimeZone('2024-03-15T10:00:00Z', 'America/New_York');

console.log(converted1); // "2024-03-15T06:00:00"

// Using Date object with custom formatting

const date = new Date('2024-03-15T10:00:00Z');

const converted2 = TimeZone.convertUTCToTimeZone(date, 'America/New_York', {

  returnISO: false,

  is24Hour: false,

  dateSeparator: '/',

  timeSeparator: ':'

});

console.log(converted2); // "2024/03/15 6:00:00 AM"

```

Parameters:

- `utcDate: Date | string`: The UTC date.

- `targetTimeZone: string`: The target time zone.

- `options: ConvertOptions (optional)`: Object containing optional formatting options:

  - `returnISO: boolean`: Whether to return ISO format (default `true`).

  - `is24Hour: boolean`: Whether to use 24-hour format (default `true`).

  - `dateSeparator: string`: The date separator (default `-`).

  - `timeSeparator: string`: The time separator (default `:`).

Returns:

- `string | null`: ISO formatted date-time string in the target time zone or error message.

### convertToUTC

Converts a date-time from a specified time zone to UTC.

```javascript

// Using ISO string with default options (ISO format)

const utc1 = TimeZone.convertToUTC('2024-03-15T06:00:00', 'America/New_York');

console.log(utc1); // "2024-03-15T10:00:00.000Z"

// Using Date object with custom formatting

const localDate = new Date('2024-03-15T06:00:00');

const utc2 = TimeZone.convertToUTC(localDate, 'America/New_York', {

  returnISO: false,

  is24Hour: false,

  dateSeparator: '/',

  timeSeparator: ':'

});

console.log(utc2); // "2024/03/15 10:00:00 AM"

```

Parameters:

- `date: Date | string`: The date-time to convert.

- `timeZone: string`: The source time zone.

- `options: ConvertOptions (optional)`: Object containing optional formatting options:

  - `returnISO: boolean`: Whether to return ISO format (default `true`).

  - `is24Hour: boolean`: Whether to use 24-hour format (default `true`).

  - `dateSeparator: string`: The date separator (default `-`).

  - `timeSeparator: string`: The time separator (default `:`).

Returns:

- `string | Error`: ISO formatted UTC date-time string or error message.

### convertBetweenTimeZones

Converts a date-time between two specified time zones.

```javascript

// Using ISO format

const converted1 = TimeZone.convertBetweenTimeZones(

  '2024-03-15T10:00:00',

  'America/New_York',

  'Asia/Tokyo',

  { returnISO: true }

);

console.log(converted1); // "2024-03-15T23:00:00"

// Using custom formatting

const converted2 = TimeZone.convertBetweenTimeZones(

  '2024-03-15T10:00:00',

  'America/New_York',

  'Asia/Tokyo',

  {

    returnISO: false,

    is24Hour: false,

    dateSeparator: '/',

    timeSeparator: ':'

  }

);

console.log(converted2); // "2024/03/15 11:00:00 PM"

```

Parameters:

- `date: string`: The date-time string to convert.

- `fromTimeZone: string`: The source timezone.

- `toTimeZone: string`: The target timezone.

- `options: ConvertOptions (optional)`: Object containing optional formatting options:

  - `returnISO: boolean`: Whether to return ISO format (default `true`).

  - `is24Hour: boolean`: Whether to use 24-hour format (default `true`).

  - `dateSeparator: string`: The date separator (default `-`).

  - `timeSeparator: string`: The time separator (default `:`).

Returns:

- `string | null`: ISO formatted date-time string in the target time zone or error message.

### getCurrentTimeInTimeZone

Gets the current time in a specified time zone.

```javascript

// Get current time in ISO format

const currentTime1 = TimeZone.getCurrentTimeInTimeZone('America/New_York', { returnISO: true });

console.log(currentTime1); // "2024-03-15T06:00:00"

// Get current time with custom formatting

const currentTime2 = TimeZone.getCurrentTimeInTimeZone('America/New_York', {

  returnISO: false,

  is24Hour: false,

  dateSeparator: '/',

  timeSeparator: ':'

});

console.log(currentTime2); // "2024/03/15 6:00:00 AM"

```

Parameters:

- `targetTimeZone: string`: The target timezone.

- `options: ConvertOptions (optional)`: Object containing optional formatting options:

  - `returnISO: boolean`: Whether to return ISO format (default `true`).

  - `is24Hour: boolean`: Whether to use 24-hour format (default `true`).

  - `dateSeparator: string`: The date separator (default `-`).

  - `timeSeparator: string`: The time separator (default `:`).

Returns:

- `string | null`: ISO formatted current date-time string in the target time zone or error message.

### getTimeDifferenceBetweenTimeZones

Calculates the time difference between two time zones for a specific date.

```javascript

const difference = TimeZone.getTimeDifferenceBetweenTimeZones(

  '2024-03-15T10:00:00',

  'America/New_York',

  'Asia/Tokyo'

);

console.log(difference); // "+13 hours 0 minutes"

```

Parameters:

- `date: string`: The date string to use for calculation.

- `fromTimeZone: string`: The source time zone.

- `toTimeZone: string`: The target time zone.

Returns:

- `string | null`: Formatted time difference string or error message.

### convertUTCToLocal

Converts UTC date-time to Local date-time and returns local ISO string.

```javascript

const localTime = TimeZone.convertUTCToLocal('2024-03-15T10:00:00Z');

console.log(localTime); // "2024-03-15T10:00:00.000Z" (returns ISO string)

```

Parameters:

- `dateTimeString: string`: The UTC date-time string to convert.

Returns:

- `string | null`: Local formatted date-time string or null if conversion fails.

### formatDateTime

Format an ISO date-time string using a custom format pattern.

```javascript

// Format with default timezone (UTC)

const formatted1 = TimeZone.formatDateTime(

  '2024-03-15T10:00:00Z',

  'yyyy-MM-dd HH:mm:ss'

);

console.log(formatted1); // "2024-03-15 10:00:00"

// Format with specific timezone

const formatted2 = TimeZone.formatDateTime(

  '2024-03-15T10:00:00Z',

  'yyyy-MM-dd HH:mm:ss',

  'America/New_York'

);

console.log(formatted2); // "2024-03-15 06:00:00"

```

Parameters:

- `isoDateTimeString: string`: The ISO date-time string to format.

- `format: string`: The format pattern using supported tokens (see below).

- `timezone: string`: Optional timezone to convert to before formatting (default: 'UTC').

Returns:

- `string | null`: Formatted date-time string or null/error message if formatting fails.

**Supported Format Tokens:**

| Token | Example | Description |

|-------|---------|-------------|

| yyyy  | 2024    | Full year (4 digits) |

| MM    | 03      | Month number (01-12) |

| dd    | 15      | Day of month (01-31) |

| HH    | 14      | 24-hour hour (00-23) |

| mm    | 30      | Minute (00-59) |

| ss    | 45      | Second (00-59) |

### getLocalTimeZone

Get the user's local timezone.

```javascript

const localTZ = TimeZone.getLocalTimeZone();

console.log(localTZ); // "America/New_York" (example output)

```

Returns:

- `string`: The IANA timezone identifier string for the user's local timezone.

## TypeScript Support

This package includes comprehensive TypeScript support with type definitions. The main types include:

- `TimeZoneNames`: Union type of all supported timezone values

- `TimeZoneEntry`: Interface for timezone objects with label, value, country, phoneCode, and utcOffset

- `ConvertOptions`: Interface for formatting options used in conversion methods

```typescript

import { TimeZone } from "timezone-utility";

// TypeScript will provide intellisense and type checking

const timeZone: TimeZoneNames = 'America/New_York';

const isValid: boolean = TimeZone.isValidTimeZone(timeZone);

```

## Error Handling

Most methods return appropriate error messages or null values when operations fail:

- Invalid timezone names return error messages like "Invalid timezone provided."

- Invalid date formats return error messages like "Invalid date format."

- Failed conversions return null or Error objects

- Validation methods return boolean values

Always check return values for error conditions:

```javascript

const result = TimeZone.convertToUTC('invalid-date', 'America/New_York');

if (result === 'Invalid date format.') {

  // Handle error

  console.error('Date conversion failed');

}

```

## License

This project is licensed under the MIT License.

## Contributing

We welcome contributions to this package! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/devmamunur/timezone-utility

Awesome Lists containing this project

README
