{"id":17436198,"url":"https://github.com/devmamunur/timezone-utility","last_synced_at":"2025-08-03T16:30:49.614Z","repository":{"id":258524963,"uuid":"874485402","full_name":"devmamunur/timezone-utility","owner":"devmamunur","description":"Lightweight timezone management utility compatible with CommonJS, ES Modules (ESM), JavaScript, and TypeScript, featuring zero dependencies.","archived":false,"fork":false,"pushed_at":"2024-10-19T10:37:35.000Z","size":56,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-19T12:07:01.856Z","etag":null,"topics":["commonjs","datetime-conversion","esm","javascript","timezone-conversion","timezone-list","timezone-management","timezones","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devmamunur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-17T23:12:01.000Z","updated_at":"2024-10-19T10:37:38.000Z","dependencies_parsed_at":"2024-10-20T23:26:00.659Z","dependency_job_id":null,"html_url":"https://github.com/devmamunur/timezone-utility","commit_stats":null,"previous_names":["devmamunur/timezone-utility"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devmamunur%2Ftimezone-utility","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devmamunur%2Ftimezone-utility/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devmamunur%2Ftimezone-utility/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devmamunur%2Ftimezone-utility/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devmamunur","download_url":"https://codeload.github.com/devmamunur/timezone-utility/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228552376,"owners_count":17935803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commonjs","datetime-conversion","esm","javascript","timezone-conversion","timezone-list","timezone-management","timezones","typescript"],"created_at":"2024-10-17T10:06:33.681Z","updated_at":"2025-08-03T16:30:49.554Z","avatar_url":"https://github.com/devmamunur.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Timezone Utility\n\nA 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.\n\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Methods Overview](#methods-overview)\n- [Methods](#methods)\n  - [isISODateTime](#isISODateTime)\n  - [isValidTimeZone](#isValidTimeZone)\n  - [convertDateTime](#convertDateTime)\n  - [list](#list)\n  - [listWithOnlyValue](#listWithOnlyValue)\n  - [listWithOnlyLabel](#listWithOnlyLabel)\n  - [listByRegion](#listByRegion)\n  - [listByCountry](#listByCountry)\n  - [getDetailsUsingTimeZoneValue](#getDetailsUsingTimeZoneValue)\n  - [getRegions](#getRegions)\n  - [convertUTCToTimeZone](#convertUTCToTimeZone)\n  - [convertToUTC](#convertToUTC)\n  - [convertBetweenTimeZones](#convertBetweenTimeZones)\n  - [getCurrentTimeInTimeZone](#getCurrentTimeInTimeZone)\n  - [getTimeDifferenceBetweenTimeZones](#getTimeDifferenceBetweenTimeZones)\n  - [convertUTCToLocal](#convertUTCToLocal)\n  - [formatDateTime](#formatDateTime)\n  - [getLocalTimeZone](#getLocalTimeZone)\n- [TypeScript Support](#typescript-support)\n- [Error Handling](#error-handling)\n- [License](#license)\n- [Contributing](#contributing)\n\n## Installation\nInstall the package using npm:\n\n```bash\nnpm install timezone-utility\n```\n\n## Usage\n\n```javascript\n// For ES Module (ESM)\nimport { TimeZone } from \"timezone-utility\";\n\n// For CommonJS\nconst { TimeZone } = require(\"timezone-utility\");\n```\n\n## Methods Overview\n\n| Method Name | Description |\n|-------------|-------------|\n| `isISODateTime` | Validates if a string is a valid ISO date-time format. |\n| `isValidTimeZone` | Validates if a given string is a valid time zone. |\n| `convertDateTime` | Converts a date-time from one time zone to another. |\n| `list` | Returns a list of all available time zones. |\n| `listWithOnlyValue` | Returns a list of all time zone values. |\n| `listWithOnlyLabel` | Returns a list of all time zone labels. |\n| `listByRegion` | Lists time zones for a specific region. |\n| `listByCountry` | Lists time zones for a specific country. |\n| `getDetailsUsingTimeZoneValue` | Gets the details for a given time zone value. |\n| `getRegions` | Returns a list of all available regions. |\n| `convertUTCToTimeZone` | Converts a UTC date to a specified time zone. |\n| `convertToUTC` | Converts a date-time from a specified time zone to UTC. |\n| `convertBetweenTimeZones` | Converts a date-time between two specified time zones. |\n| `getCurrentTimeInTimeZone` | Gets the current time in a specified time zone. |\n| `getTimeDifferenceBetweenTimeZones` | Calculates the time difference between two time zones. |\n| `convertUTCToLocal` | Converts UTC date-time to Local date-time. |\n| `formatDateTime` | Format an ISO date-time string using a custom format pattern. |\n| `getLocalTimeZone` | Get the user's local timezone. |\n\n## Methods\n\n### isISODateTime\nValidates if a string is a valid ISO date-time format.\n\n```javascript\nconst isValid1 = TimeZone.isISODateTime('2023-10-10T10:00:00');\nconsole.log(isValid1); // true\n\nconst isValid2 = TimeZone.isISODateTime('invalid-date');\nconsole.log(isValid2); // false\n```\n\nParameters:\n- `dateTime: string`: The date-time string to validate.\n\nReturns:\n- `boolean`: True if the string is a valid ISO date-time, false otherwise.\n\n### isValidTimeZone\nValidates if a given string is a valid time zone.\n\n```javascript\nconst isValid1 = TimeZone.isValidTimeZone('UTC');\nconsole.log(isValid1); // true\n\nconst isValid2 = TimeZone.isValidTimeZone('Invalid/Zone');\nconsole.log(isValid2); // false\n```\n\nParameters:\n- `timeZone: string`: The time zone string to validate.\n\nReturns:\n- `boolean`: True if the time zone is valid, false otherwise.\n\n### convertDateTime\nConverts a date-time from one time zone to another.\n\n```javascript\n// Using string input\nconst converted1 = TimeZone.convertDateTime(\n  '2023-10-10T10:00:00', \n  'UTC', \n  'America/New_York', \n  true\n);\nconsole.log(converted1); // \"2023-10-10T06:00:00\"\n\n// Using Date object input\nconst dateTime = new Date('2023-10-10T10:00:00Z');\nconst converted2 = TimeZone.convertDateTime(\n  dateTime, \n  'UTC', \n  'America/New_York', \n  true\n);\nconsole.log(converted2); // \"2023-10-10T06:00:00\"\n```\n\nParameters:\n- `dateTime: Date | string`: The date-time to convert.\n- `sourceTimeZone: string`: The source time zone.\n- `targetTimeZone: string`: The target time zone.\n- `returnISO: boolean`: Whether to return ISO format (default: true).\n\nReturns:\n- `string | Error`: Converted date-time string or Error if conversion fails.\n\n### list\nReturns a list of all available time zones.\n\n```javascript\nconst timeZones = TimeZone.list();\nconsole.log(timeZones);\n/* OUTPUT:\n[\n  {\n    \"label\": \"(UTC-05:00) America/New_York\",\n    \"value\": \"America/New_York\",\n    \"country\": \"United States\",\n    \"phoneCode\": \"+1\",\n    \"utcOffset\": \"-05:00\"\n  },\n  ...\n]\n*/\n```\n\nReturns:\n- `Array\u003cTimeZoneEntry\u003e`: Array of TimeZoneEntry objects.\n\n### listWithOnlyValue\nReturns a list of all time zone values without labels.\n\n```javascript\nconst timeZoneValues = TimeZone.listWithOnlyValue();\nconsole.log(timeZoneValues);\n/* OUTPUT:\n[\"Africa/Abidjan\", \"Africa/Accra\", \"America/New_York\", \"Europe/London\", \"Asia/Tokyo\", ...]\n*/\n```\n\nReturns:\n- `Array\u003cstring\u003e`: Array of time zone values.\n\n### listWithOnlyLabel\nReturns a list of all time zone labels without values.\n\n```javascript\nconst timeZoneLabels = TimeZone.listWithOnlyLabel();\nconsole.log(timeZoneLabels);\n/* OUTPUT:\n[\"(UTC-05:00) America/New_York\", \"(UTC+00:00) London\", ...]\n*/\n```\n\nReturns:\n- `Array\u003cstring\u003e`: Array of time zone labels.\n\n### listByRegion\nLists time zones for a specific region.\n\n```javascript\nconst timeZonesInAmerica = TimeZone.listByRegion('America');\nconsole.log(timeZonesInAmerica);\n/* OUTPUT:\n[\n  {\n    \"label\": \"(UTC-05:00) America/New_York\",\n    \"value\": \"America/New_York\",\n    \"country\": \"United States\",\n    \"phoneCode\": \"+1\",\n    \"utcOffset\": \"-05:00\"\n  },\n  ...\n]\n*/\n```\n\nParameters:\n- `region: string`: The region to filter time zones.\n\nReturns:\n- `Array\u003cTimeZoneEntry\u003e`: Array of TimeZoneEntry objects for the specified region.\n\n### listByCountry\nLists time zones for a specific country.\n\n```javascript\nconst timeZonesInUS = TimeZone.listByCountry('United States');\nconsole.log(timeZonesInUS);\n/* OUTPUT:\n[\n  {\n    \"label\": \"(UTC-05:00) America/New_York\",\n    \"value\": \"America/New_York\",\n    \"country\": \"United States\",\n    \"phoneCode\": \"+1\",\n    \"utcOffset\": \"-05:00\"\n  },\n  ...\n]\n*/\n```\n\nParameters:\n- `country: string`: The country to filter time zones.\n\nReturns:\n- `Array\u003cTimeZoneEntry\u003e`: Array of TimeZoneEntry objects for the specified country.\n\n### getDetailsUsingTimeZoneValue\nGets the details for a given time zone value.\n\n```javascript\nconst tzDetails = TimeZone.getDetailsUsingTimeZoneValue('America/New_York');\nconsole.log(tzDetails);\n/* OUTPUT:\n{\n  \"label\": \"(UTC-05:00) America/New_York\",\n  \"value\": \"America/New_York\",\n  \"country\": \"United States\",\n  \"phoneCode\": \"+1\",\n  \"utcOffset\": \"-05:00\"\n}\n*/\n```\n\nParameters:\n- `value: string`: The time zone value.\n\nReturns:\n- `TimeZoneEntry | null`: The corresponding details or null if not found.\n\n### getRegions\nReturns a list of all available regions.\n\n```javascript\nconst regions = TimeZone.getRegions();\nconsole.log(regions);\n/* OUTPUT:\n[\"Africa\", \"America\", \"Asia\", \"Atlantic\", \"Australia\", \"Europe\", \"Indian\", \"Pacific\"]\n*/\n```\n\nReturns:\n- `Array\u003cstring\u003e`: Array of region strings.\n\n### convertUTCToTimeZone\nConverts a UTC date to a specified time zone.\n\n```javascript\n// Using ISO string with default options (ISO format)\nconst converted1 = TimeZone.convertUTCToTimeZone('2024-03-15T10:00:00Z', 'America/New_York');\nconsole.log(converted1); // \"2024-03-15T06:00:00\"\n\n// Using Date object with custom formatting\nconst date = new Date('2024-03-15T10:00:00Z');\nconst converted2 = TimeZone.convertUTCToTimeZone(date, 'America/New_York', {\n  returnISO: false,\n  is24Hour: false,\n  dateSeparator: '/',\n  timeSeparator: ':'\n});\nconsole.log(converted2); // \"2024/03/15 6:00:00 AM\"\n```\n\nParameters:\n- `utcDate: Date | string`: The UTC date.\n- `targetTimeZone: string`: The target time zone.\n- `options: ConvertOptions (optional)`: Object containing optional formatting options:\n  - `returnISO: boolean`: Whether to return ISO format (default `true`).\n  - `is24Hour: boolean`: Whether to use 24-hour format (default `true`).\n  - `dateSeparator: string`: The date separator (default `-`).\n  - `timeSeparator: string`: The time separator (default `:`).\n\nReturns:\n- `string | null`: ISO formatted date-time string in the target time zone or error message.\n\n### convertToUTC\nConverts a date-time from a specified time zone to UTC.\n\n```javascript\n// Using ISO string with default options (ISO format)\nconst utc1 = TimeZone.convertToUTC('2024-03-15T06:00:00', 'America/New_York');\nconsole.log(utc1); // \"2024-03-15T10:00:00.000Z\"\n\n// Using Date object with custom formatting\nconst localDate = new Date('2024-03-15T06:00:00');\nconst utc2 = TimeZone.convertToUTC(localDate, 'America/New_York', {\n  returnISO: false,\n  is24Hour: false,\n  dateSeparator: '/',\n  timeSeparator: ':'\n});\nconsole.log(utc2); // \"2024/03/15 10:00:00 AM\"\n```\n\nParameters:\n- `date: Date | string`: The date-time to convert.\n- `timeZone: string`: The source time zone.\n- `options: ConvertOptions (optional)`: Object containing optional formatting options:\n  - `returnISO: boolean`: Whether to return ISO format (default `true`).\n  - `is24Hour: boolean`: Whether to use 24-hour format (default `true`).\n  - `dateSeparator: string`: The date separator (default `-`).\n  - `timeSeparator: string`: The time separator (default `:`).\n\nReturns:\n- `string | Error`: ISO formatted UTC date-time string or error message.\n\n### convertBetweenTimeZones\nConverts a date-time between two specified time zones.\n\n```javascript\n// Using ISO format\nconst converted1 = TimeZone.convertBetweenTimeZones(\n  '2024-03-15T10:00:00',\n  'America/New_York',\n  'Asia/Tokyo',\n  { returnISO: true }\n);\nconsole.log(converted1); // \"2024-03-15T23:00:00\"\n\n// Using custom formatting\nconst converted2 = TimeZone.convertBetweenTimeZones(\n  '2024-03-15T10:00:00',\n  'America/New_York',\n  'Asia/Tokyo',\n  {\n    returnISO: false,\n    is24Hour: false,\n    dateSeparator: '/',\n    timeSeparator: ':'\n  }\n);\nconsole.log(converted2); // \"2024/03/15 11:00:00 PM\"\n```\n\nParameters:\n- `date: string`: The date-time string to convert.\n- `fromTimeZone: string`: The source timezone.\n- `toTimeZone: string`: The target timezone.\n- `options: ConvertOptions (optional)`: Object containing optional formatting options:\n  - `returnISO: boolean`: Whether to return ISO format (default `true`).\n  - `is24Hour: boolean`: Whether to use 24-hour format (default `true`).\n  - `dateSeparator: string`: The date separator (default `-`).\n  - `timeSeparator: string`: The time separator (default `:`).\n\nReturns:\n- `string | null`: ISO formatted date-time string in the target time zone or error message.\n\n### getCurrentTimeInTimeZone\nGets the current time in a specified time zone.\n\n```javascript\n// Get current time in ISO format\nconst currentTime1 = TimeZone.getCurrentTimeInTimeZone('America/New_York', { returnISO: true });\nconsole.log(currentTime1); // \"2024-03-15T06:00:00\"\n\n// Get current time with custom formatting\nconst currentTime2 = TimeZone.getCurrentTimeInTimeZone('America/New_York', {\n  returnISO: false,\n  is24Hour: false,\n  dateSeparator: '/',\n  timeSeparator: ':'\n});\nconsole.log(currentTime2); // \"2024/03/15 6:00:00 AM\"\n```\n\nParameters:\n- `targetTimeZone: string`: The target timezone.\n- `options: ConvertOptions (optional)`: Object containing optional formatting options:\n  - `returnISO: boolean`: Whether to return ISO format (default `true`).\n  - `is24Hour: boolean`: Whether to use 24-hour format (default `true`).\n  - `dateSeparator: string`: The date separator (default `-`).\n  - `timeSeparator: string`: The time separator (default `:`).\n\nReturns:\n- `string | null`: ISO formatted current date-time string in the target time zone or error message.\n\n### getTimeDifferenceBetweenTimeZones\nCalculates the time difference between two time zones for a specific date.\n\n```javascript\nconst difference = TimeZone.getTimeDifferenceBetweenTimeZones(\n  '2024-03-15T10:00:00',\n  'America/New_York',\n  'Asia/Tokyo'\n);\nconsole.log(difference); // \"+13 hours 0 minutes\"\n```\n\nParameters:\n- `date: string`: The date string to use for calculation.\n- `fromTimeZone: string`: The source time zone.\n- `toTimeZone: string`: The target time zone.\n\nReturns:\n- `string | null`: Formatted time difference string or error message.\n\n### convertUTCToLocal\nConverts UTC date-time to Local date-time and returns local ISO string.\n\n```javascript\nconst localTime = TimeZone.convertUTCToLocal('2024-03-15T10:00:00Z');\nconsole.log(localTime); // \"2024-03-15T10:00:00.000Z\" (returns ISO string)\n```\n\nParameters:\n- `dateTimeString: string`: The UTC date-time string to convert.\n\nReturns:\n- `string | null`: Local formatted date-time string or null if conversion fails.\n\n### formatDateTime\nFormat an ISO date-time string using a custom format pattern.\n\n```javascript\n// Format with default timezone (UTC)\nconst formatted1 = TimeZone.formatDateTime(\n  '2024-03-15T10:00:00Z',\n  'yyyy-MM-dd HH:mm:ss'\n);\nconsole.log(formatted1); // \"2024-03-15 10:00:00\"\n\n// Format with specific timezone\nconst formatted2 = TimeZone.formatDateTime(\n  '2024-03-15T10:00:00Z',\n  'yyyy-MM-dd HH:mm:ss',\n  'America/New_York'\n);\nconsole.log(formatted2); // \"2024-03-15 06:00:00\"\n```\n\nParameters:\n- `isoDateTimeString: string`: The ISO date-time string to format.\n- `format: string`: The format pattern using supported tokens (see below).\n- `timezone: string`: Optional timezone to convert to before formatting (default: 'UTC').\n\nReturns:\n- `string | null`: Formatted date-time string or null/error message if formatting fails.\n\n**Supported Format Tokens:**\n| Token | Example | Description |\n|-------|---------|-------------|\n| yyyy  | 2024    | Full year (4 digits) |\n| MM    | 03      | Month number (01-12) |\n| dd    | 15      | Day of month (01-31) |\n| HH    | 14      | 24-hour hour (00-23) |\n| mm    | 30      | Minute (00-59) |\n| ss    | 45      | Second (00-59) |\n\n### getLocalTimeZone\nGet the user's local timezone.\n\n```javascript\nconst localTZ = TimeZone.getLocalTimeZone();\nconsole.log(localTZ); // \"America/New_York\" (example output)\n```\n\nReturns:\n- `string`: The IANA timezone identifier string for the user's local timezone.\n\n## TypeScript Support\n\nThis package includes comprehensive TypeScript support with type definitions. The main types include:\n\n- `TimeZoneNames`: Union type of all supported timezone values\n- `TimeZoneEntry`: Interface for timezone objects with label, value, country, phoneCode, and utcOffset\n- `ConvertOptions`: Interface for formatting options used in conversion methods\n\n```typescript\nimport { TimeZone } from \"timezone-utility\";\n\n// TypeScript will provide intellisense and type checking\nconst timeZone: TimeZoneNames = 'America/New_York';\nconst isValid: boolean = TimeZone.isValidTimeZone(timeZone);\n```\n\n## Error Handling\n\nMost methods return appropriate error messages or null values when operations fail:\n\n- Invalid timezone names return error messages like \"Invalid timezone provided.\"\n- Invalid date formats return error messages like \"Invalid date format.\"\n- Failed conversions return null or Error objects\n- Validation methods return boolean values\n\nAlways check return values for error conditions:\n\n```javascript\nconst result = TimeZone.convertToUTC('invalid-date', 'America/New_York');\nif (result === 'Invalid date format.') {\n  // Handle error\n  console.error('Date conversion failed');\n}\n```\n\n## License\nThis project is licensed under the MIT License.\n\n## Contributing\nWe welcome contributions to this package! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevmamunur%2Ftimezone-utility","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevmamunur%2Ftimezone-utility","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevmamunur%2Ftimezone-utility/lists"}