{"id":22423307,"url":"https://github.com/prantlf/date-and-time-formatter","last_synced_at":"2025-07-03T02:05:43.625Z","repository":{"id":144719628,"uuid":"616140769","full_name":"prantlf/date-and-time-formatter","owner":"prantlf","description":"Formats a date/time value to a localised string using a pattern consisting of Unicode LDML tokens.","archived":false,"fork":false,"pushed_at":"2023-12-10T18:33:27.000Z","size":87,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-11T05:05:51.490Z","etag":null,"topics":["date","date-time","datetime","format","ldml","locale","pattern","time","unicode"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prantlf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","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":"2023-03-19T18:15:14.000Z","updated_at":"2024-09-09T14:04:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"11970e77-d0c0-43f1-8bda-5bb4fc5f9b03","html_url":"https://github.com/prantlf/date-and-time-formatter","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/prantlf/date-and-time-formatter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fdate-and-time-formatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fdate-and-time-formatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fdate-and-time-formatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fdate-and-time-formatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prantlf","download_url":"https://codeload.github.com/prantlf/date-and-time-formatter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fdate-and-time-formatter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261233247,"owners_count":23128199,"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":["date","date-time","datetime","format","ldml","locale","pattern","time","unicode"],"created_at":"2024-12-05T18:09:57.756Z","updated_at":"2025-07-03T02:05:43.583Z","avatar_url":"https://github.com/prantlf.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DateTime Formatter\n\n[![Latest version](https://img.shields.io/npm/v/date-and-time-formatter)\n ![Dependency status](https://img.shields.io/librariesio/release/npm/date-and-time-formatter)\n](https://www.npmjs.com/package/date-and-time-formatter)\n[![Coverage](https://codecov.io/gh/prantlf/date-and-time-formatter/branch/master/graph/badge.svg)](https://codecov.io/gh/prantlf/date-and-time-formatter)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/9f1034029c0747a980cd49f64f16338b)](https://www.codacy.com/app/prantlf/date-and-time-formatter?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=prantlf/date-and-time-formatter\u0026amp;utm_campaign=Badge_Grade)\n\nFormats a date/time value to a localised string using a pattern consisting of [Unicode LDML] tokens.\n\n| Locale | Pattern             | Example                     |\n|:-------|:--------------------|:----------------------------|\n| en     | M/d/yy, h:mm a      | 2/3/01, 4:05 AM             |\n| cs     | d. MMMM y H:mm:ss z | 3. února 1901 4:05:06 GMT+1 |\n\n```js\nconst result = formatDateTime(new Date(), 'd.M.yy') // 3.2.01\n```\n\n* ES, CJS and UMD module exports.\n* TypeScript type declarations (typings).\n* No other dependencies.\n* Output translated to the requested locale by [`Intl.DateTimeFormat`].\n* Custom translations of the textual date/time parts possible.\n* Tiny code base - 7.21 kB minified, 2.23 kB gzipped, 2.01 kB brotlied.\n* [Extremely fast](perf/README.md).\n\nRelated projects:\n\n* [datetime-placeholder] - simplifies a date/time-formatting pattern using [Unicode LDML] tokens to a pattern usable in date/time pickers.\n* [datetime-locale-patterns] - provides localized date/time format patterns for styles `full`, `long`, `medium` and `short` using [Unicode CLDR], compliant with [Unicode LDML].\n* [intl-datetimeformat-options] - provides localized date/time format patterns for styles `full`, `long`, `medium` and `short`, using [`Intl.DateTimeFormat`].\n* [intl-datetimeformat-pattern] - creates a valid [`Intl.DateTimeFormat`] options object from a [Unicode CLDR] skeleton or token pattern.\n\n## Installation\n\nThis module can be installed in your project using [NPM], [PNPM] or [Yarn]. Make sure, that you use [Node.js] version 16.14 or newer.\n\n```sh\n$ npm i date-and-time-formatter\n$ pnpm i date-and-time-formatter\n$ yarn add date-and-time-formatter\n```\n\nFunctions are exposed as named exports from ES and CJS modules, for example:\n\n```js\nimport { formatDateTime } from 'date-and-time-formatter'\n```\n\n```js\nconst { formatDateTime } = require('date-and-time-formatter')\n```\n\nA UMD module can be loaded to the browser either directly:\n\n```html\n\u003cscript src=\"https://unpkg.com/date-and-time-formatter@1.0.0/lib/index.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const { formatDateTime } = window.dateAndTimeFormatter\n\u003c/script\u003e\n```\n\nOr using an AMD module loader:\n\n```html\n\u003cscript\u003e\n  require([\n    'https://unpkg.com/date-and-time-formatter@1.0.0/lib/index.min.js'\n  ], ({ formatDateTime }) =\u003e {\n    ...\n  })\n\u003c/script\u003e\n```\n\n## API\n\n### formatDateTime(date, pattern, locale?, utc?) : string\n\nFormats a date/time value to a string using a pattern of Unicode LDML tokens. If no `locale` is specified, English (\"en-US\") will be used by default. If `true` is not passed for `utc`, the date/time value will be considered in the local time zone and formatted accordingly.\n\nIf you format many date/time values using the same pattern or if the performance of the formatting is important, consider compiling the pattern with `compileDateTimePattern`.\n\n* **date** - a date/time value (an instance of `Date`)\n* **pattern** - a date/time pattern consisting of [Unicode LDML] tokens\n* **locale** - target locale identifier according to [BCP 47] or an object with translated texts to be used as date/time parts\n* **utc** - format the date/time value converted to UTC\n\n```js\nimport { formatDateTime } from 'date-and-time-formatter'\n\nconst result = formatDateTime(new Date(), 'M/d/yy')\nconsole.log(result) // prints '3/19/23'\n```\n\n### formatDateTimeToParts(date, pattern, locale?, utc?) : []\n\nFormats a date/time value to an array of parts, which values are supposed to be concatenated together, using a pattern of Unicode LDML tokens. If no `locale` is specified, English (\"en-US\") will be used by default. If `true` is not passed for `utc`, the date/time value will be considered in the local time zone and formatted accordingly.\n\nIf you format many date/time values using the same pattern or if the performance of the formatting is important, consider compiling the pattern with `compileDateTimePattern`.\n\n* **date** - a date/time value (an instance of `Date`)\n* **pattern** - a date/time pattern consisting of [Unicode LDML] tokens\n* **locale** - target locale identifier according to [BCP 47] or an object with translated texts to be used as date/time parts\n* **utc** - format the date/time value converted to UTC\n\n```js\nimport { formatDateTime } from 'date-and-time-formatter'\n\nconst result = formatDateTime(new Date(), 'M/d/yy')\nconsole.log(result) // prints the following:\n// [{ type: 'month', value: 3,\n//    type: 'literal', value: '/',\n//    type; 'day', value: 19,\n//    type: 'literal', value: '/',\n//    type: 'year': value: 23 }]\n```\n\n### compileDateTimePattern(pattern) : Function\n\nCompiles a date/time pattern to a formatting function. The function can be called to format multiple date/time values to a string.\n\nThe returned function carries another function as a property `formatToParts`. This function can be called to return an array of parts, which values are supposed to be concatenated together, instead of the final string.\n\n* **pattern** - a date/time pattern consisting of [Unicode LDML] tokens\n\n```js\nimport { compileDateTimePattern } from 'date-and-time-formatter'\n\nconst format = compileDateTimePattern('M/d/yy')\nconsole.log(format(new Date())) // prints '3/19/23'\nconsole.log(format.formatToParts(new Date())) // prints the following:\n// [{ type: 'month', value: 3,\n//    type: 'literal', value: '/',\n//    type; 'day', value: 19,\n//    type: 'literal', value: '/',\n//    type: 'year': value: 23 }]\n```\n\n## Formatting Pattern\n\nThe characters wrapped between two single quotes characters (`'`) are escaped.\nTwo single quotes in a row, whether inside or outside a quoted sequence,\nrepresent a \"real\" single quote. (see the last example)\n\nFormat of the string is based on [Unicode Technical Standard #35].\nOnly those tokens are supported, which can appear in patterns for formatting\ninstances of `Date` by [`Intl.DateTimeFormat`]. For example, only the \"formatting\"\nvariant of a token (M, E) is supported, not the \"stand-alone\" one (L, i).\n(\"Formatting\" means declined according to the rules of the language\n in the context of a date. \"Stand-alone\" means always nominative singular.)\n\nAccepted patterns:\n\n| Unit                         | Pattern | Result examples                   |\n|------------------------------|---------|-----------------------------------|\n| Era                          | G..GGG  | AD, BC                            |\n|                              | GGGG    | Anno Domini, Before Christ        |\n|                              | GGGGG   | A, B                              |\n| Calendar year                | y       | 44, 1, 1900, 2017                 |\n|                              | yy      | 44, 01, 00, 17                    |\n|                              | yyy     | 044, 001, 1900, 2017              |\n|                              | yyyy    | 0044, 0001, 1900, 2017            |\n|                              | yyyyy   | ...                               |\n| Month                        | M       | 1, 2, ..., 12                     |\n|                              | MM      | 01, 02, ..., 12                   |\n|                              | MMM     | Jan, Feb, ..., Dec                |\n|                              | MMMM    | January, February, ..., December  |\n|                              | MMMMM   | J, F, ..., D                      |\n| Day of month                 | d       | 1, 2, ..., 31                     |\n|                              | dd      | 01, 02, ..., 31                   |\n| Day of week                  | E..EEE  | Mon, Tue, Wed, ..., Sun           |\n|                              | EEEE    | Monday, Tuesday, ..., Sunday      |\n|                              | EEEEE   | M, T, W, T, F, S, S               |\n| AM, PM                       | a..aa   | AM, PM                            |\n|                              | aaa     | am, pm                            |\n|                              | aaaa    | a.m., p.m.                        |\n|                              | aaaaa   | a, p                              |\n| AM, PM, noon, midnight       | b..bb   | AM, PM, noon, midnight            |\n|                              | bbb     | am, pm, noon, midnight            |\n|                              | bbbb    | a.m., p.m., noon, midnight        |\n|                              | bbbbb   | a, p, n, mi                       |\n| Flexible day period          | B..BBB  | at night, in the morning, ...     |\n|                              | BBBB    | at night, in the morning, ...     |\n|                              | BBBBB   | at night, in the morning, ...     |\n| Hour [1-12]                  | h       | 1, 2, ..., 11, 12                 |\n|                              | hh      | 01, 02, ..., 11, 12               |\n| Hour [0-23]                  | H       | 0, 1, 2, ..., 23                  |\n|                              | HH      | 00, 01, 02, ..., 23               |\n| Hour [0-11]                  | K       | 1, 2, ..., 11, 0                  |\n|                              | KK      | 01, 02, ..., 11, 00               |\n| Hour [1-24]                  | k       | 24, 1, 2, ..., 23                 |\n|                              | kk      | 24, 01, 02, ..., 23               |\n| Minute                       | m       | 0, 1, ..., 59                     |\n|                              | mm      | 00, 01, ..., 59                   |\n| Second                       | s       | 0, 1, ..., 59                     |\n|                              | ss      | 00, 01, ..., 59                   |\n| Fraction of second           | S       | 0, 1, ..., 9                      |\n|                              | SS      | 00, 01, ..., 99                   |\n|                              | SSS     | 000, 001, ..., 999                |\n|                              | SSSS    | ...                               |\n| Timezone (ISO-8601 w/ Z)     | X       | -08, +0530, Z                     |\n|                              | XX      | -0800, +0530, Z                   |\n|                              | XXX     | -08:00, +05:30, Z                 |\n|                              | XXXX    | -0800, +0530, Z, +123456          |\n|                              | XXXXX   | -08:00, +05:30, Z, +12:34:56      |\n| Timezone (ISO-8601 w/o Z)    | x       | -08, +0530, +00                   |\n|                              | xx      | -0800, +0530, +0000               |\n|                              | xxx     | -08:00, +05:30, +00:00            |\n|                              | xxxx    | -0800, +0530, +0000, +123456      |\n|                              | xxxxx   | -08:00, +05:30, +00:00, +12:34:56 |\n| Timezone (GMT)               | O       | GMT-8, GMT+5:30, GMT+0            |\n|                              | OOOO    | GMT-08:00, GMT+05:30, GMT+00:00   |\n| Timezone (specific non-loc.) | z...zzz | GMT-8, GMT+5:30, GMT+0            |\n|                              | zzzz    | GMT-08:00, GMT+05:30, GMT+00:00   |\n\nAny sequence of the identical letters is a pattern, unless it is escaped by\nthe single quote characters (see below). Tokens for textual formatted parts\nare usually available in three styles:\n\n```js\nformat(new Date(2017, 10, 6), 'MMM')   // short  =\u003e 'Nov'\nformat(new Date(2017, 10, 6), 'MMMM')  // long   =\u003e 'November'\nformat(new Date(2017, 10, 6), 'MMMMM') // narrow =\u003e 'N'\n```\n\nSpecific non-location time zones are currently unavailable,\nso right now these tokens fall back to GMT time zones.\n\n### Examples\n\n```js\n// Represent 11 February 2014 in middle-endian format\nformatDateAndTime(new Date(2014, 1, 11), 'MM/dd/yyyy')\n//=\u003e '02/11/2014'\n```\n\n```js\n// Escape string by single quote characters\nformatDateAndTimeToParts(new Date(2014, 6, 2, 15), \"h 'o''clock'\")\n//=\u003e [{ type: 'hour', value: 3 },\n//    { type: 'literal', value: \" o'clock\" }]\n```\n\n## Custom Translations\n\nPatterns may need to be customised, if you need them to differ from the CLDR standard, or if you need to support only a subset of locales, formats or styles to reduce the size of the data loaded by your application.\n\nThe default data including all locales, formats and pattern styles are exposed as the `date-and-time-formatter/data/all` module. Smaller data including all locales and formats for the short pattern style are exposed as the `date-and-time-formatter/data/short` module. Other data (list of localized date/time format patterns) can be generated using the `create-date-and-time-formatter` script and enabled using the `setLocalePatterns` function.\n\n### Creating Custom Data\n\nFormat of the data is JSON:\n\n    {\n      formats: [...], // a subset of date, time, dateTime\n      styles: [...],  // a subset of full, long, medium, short\n      patterns: {\n        // locale to array of formats; a format is an array of styles\n        [locale]: [[date], [time], [date-time]],\n        ...\n      }\n    }\n\nFor example, for supporting only `en` and `cs` locales and `short` and `long` styles, the following command line will create the following file content:\n\n    create-date-and-time-formatter -l en,cs -s short,long\n\n```json\n{\n  \"formats\": [\"date\", \"time\", \"dateTime\"],\n  \"styles\": [\"short\", \"long\"],\n  \"patterns\": {\n    \"en\": [[\"M/d/yy\", \"MMMM d, y\"], [\"h:mm a\", \"h:mm:ss a z\"], [\"{1}, {0}\", \"{1}, {0}\"]],\n    \"cs\": [[\"dd.MM.yy\", \"d. MMMM y\"], [\"H:mm\", \"H:mm:ss z\"], [\"{1} {0}\", \"{1} {0}\"]]\n  }\n}\n```\n\nThe command-line script `create-date-and-time-formatter` is installed to the `bin` directory in `node_modules`:\n\n    Usage: create-date-and-time-formatter [options]\n\n    Options:\n      -l|--locales \u003c\u003e  list of locales to include (default: all)\n      -f|--formats \u003c\u003e  list of format patterns (default: date,time,dateTime)\n      -s|--styles \u003c\u003e   list of format styles (default: short,medium,long,full)\n      -o|--output \u003c\u003e   output file (default: console)\n      -p|--pretty      prettify the JSON output (default: minified)\n      -V|--version     print version number\n      -h|--help        print usage instructions\n\n    Examples:\n      $ create-date-and-time-formatter -s short,long -o patterns.json\n      $ create-date-and-time-formatter -l en,en-GB,cs,de,de-AT -f date -p\n\n### Loading Custom Data\n\nIf you want to use the limited data from the `date-and-time-formatter/data/short` module or your custom data, do not import functions from the default `date-and-time-formatter` module, but from the `date-and-time-formatter/code` module, which will not load the default data automatically. Once you do it, you will have to supply the custom data to the `setLocalePatterns` function before you call any other function from this library:\n\n```js\nimport { setLocalePatterns, formatDateTime } from 'date-and-time-formatter/code'\nimport patterns from './patterns.json' assert { type: 'json' }\n\nsetLocalePatterns(patterns)\nconst pattern = formatDateTime('cs', 'short', 'short')\n```\n\n## Contributing\n\nIn lieu of a formal styleguide, take care to maintain the existing coding style.  Add unit tests for any new or changed functionality. Lint and test your code using Grunt.\n\n## License\n\nCopyright (c) 2023 Ferdinand Prantl\n\nLicensed under the MIT license.\n\n[Node.js]: http://nodejs.org/\n[NPM]: https://www.npmjs.com/\n[PNPM]: https://pnpm.io/\n[Yarn]: https://yarnpkg.com/\n[date-and-time]: https://github.com/knowledgecode/date-and-time\n[date-fns]: https://github.com/date-fns/date-fns\n[luxon]: https://moment.github.io/luxon/\n[ICU]: https://icu.unicode.org/\n[CLDR data]: https://www.npmjs.com/package/cldr-dates-full\n[Unicode LDML]: https://unicode.org/reports/tr35/\n[Unicode CLDR]: https://cldr.unicode.org/\n[BCP 47]: https://www.ietf.org/rfc/bcp/bcp47.html\n[`Intl.DateTimeFormat`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat\n[`Intl.DateTimeFomat` options]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options\n[8. Date Format Patterns]: http://unicode.org/reports/tr35/tr35-dates.html#8-date-format-patterns\n[Unicode Technical Standard #35]: https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table\n[datetime-placeholder]: https://github.com/prantlf/datetime-placeholder\n[datetime-locale-patterns]: https://github.com/prantlf/datetime-locale-patterns\n[intl-datetimeformat-pattern]: https://github.com/caridy/intl-datetimeformat-pattern\n[intl-datetimeformat-options]: https://github.com/prantlf/intl-datetimeformat-options\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fdate-and-time-formatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprantlf%2Fdate-and-time-formatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fdate-and-time-formatter/lists"}