{"id":21090084,"url":"https://github.com/vintl-dev/compact-number","last_synced_at":"2025-05-16T13:31:12.260Z","repository":{"id":65925305,"uuid":"602562193","full_name":"vintl-dev/compact-number","owner":"vintl-dev","description":"Pluralisable compact notation numbers using @formatjs/intl","archived":false,"fork":false,"pushed_at":"2024-11-16T13:35:07.000Z","size":232,"stargazers_count":0,"open_issues_count":5,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-16T14:28:01.889Z","etag":null,"topics":["i18n","intl","javascript","number-format"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/vintl-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-02-16T13:29:26.000Z","updated_at":"2024-10-31T14:35:50.000Z","dependencies_parsed_at":"2024-01-22T09:31:29.866Z","dependency_job_id":"f8d4f45a-965b-4755-84da-b053a49e48c5","html_url":"https://github.com/vintl-dev/compact-number","commit_stats":{"total_commits":36,"total_committers":2,"mean_commits":18.0,"dds":"0.38888888888888884","last_synced_commit":"7827cfae39a0190e29eef136130112d1737f7690"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintl-dev%2Fcompact-number","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintl-dev%2Fcompact-number/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintl-dev%2Fcompact-number/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vintl-dev%2Fcompact-number/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vintl-dev","download_url":"https://codeload.github.com/vintl-dev/compact-number/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225432127,"owners_count":17473472,"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":["i18n","intl","javascript","number-format"],"created_at":"2024-11-19T21:34:18.302Z","updated_at":"2024-11-19T21:34:19.007Z","avatar_url":"https://github.com/vintl-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @vintl/compact-number\n\n\u003e Pluralisable compact notation numbers using `@formatjs/intl`.\n\n[![Supports: ESM only](https://img.shields.io/static/v1?label=Format\u0026message=ESM%20only\u0026color=blue\u0026style=flat-square)](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) [![Depends on @formatjs/intl](https://img.shields.io/static/v1?label=Requires\u0026message=%40formatjs%2Fintl\u0026color=lightgray\u0026style=flat-square)](https://npm.im/@formatjs/intl)\n\n## **Prehistory**\n\nThere has been a long-standing issue with the `Intl.NumberFormat` API that it does not provide any means to use a formatted number to choose the correct plural form. In contrast, this is possible in Java implementation of ICU4J. Unfortunately, this issue has not seen much progress for a long time, so something had to be done.\n\n### **Issue**\n\nMany people mistakenly assume that they can simply take the original number and pluralise it. However, this is not correct in languages with complex pluralisation rules, as the declension of the following noun depends on the compact unit rather than the number.\n\nFor example, in Ukrainian:\n\nIf you have 1,452 cats, you may want to display it in compact notation (e.g. 1.4K in English). Using `Intl.NumberFormat`, you get 1,4 тис. If you then pluralise it using the original number (1,452), you get ‘1,4 тис. коти’, which is incorrect. The correct result should be ‘1,4 тис. котів’.\n\nThis is because you are pluralising the wrong thing — the original number, without compact notation. The correct pluralisation for ‘1,452 коти’ is ‘1,452 котів’, but when you use compact notation, you need to select a plural form based on the unit (thousands in this case).\n\n### **Mitigation**\n\nThis module attempts to address this issue by doing ‘smart rounding’. Using CLDR data, it calculates the exponent, the same one that is used to format the number, and then rounds the original number using it. The result is a number that roughly represents the rounded number. Using this number for pluralisation seems to work with most languages (however, additional testing from native speakers would be appreciated).\n\n## **Installation**\n\nWith your package manager of choice:\n\n**npm**\n\n```sh\nnpm i @vintl/compact-number\n```\n\n**pnpm**\n\n```sh\npnpm add @vintl/compact-number\n```\n\n**yarn**\n\n```sh\nyarn add @vintl/compact-number\n```\n\n## **Example**\n\n```jsx\nimport { createFormatter } from '@vintl/compact-number'\nimport { createIntl } from '@formatjs/intl'\nimport '@vintl/compact-number/locale-data/en'\n\nconst intl = createIntl({ locale: 'en-US' })\n\nconst formatCompactNumber = createFormatter(intl)\n\nconst compactNumber = formatCompactNumber(1_456)\n\nconsole.log(String(compactNumber))\n// =\u003e \"1.4K\"\n\nconsole.log(Number(compactNumber))\n// =\u003e 1400\n```\n\n## **API**\n\n### **`createFormatter`**\n\nA function that accepts an `IntlShape` object as an argument and returns a function that can be used to create the `CompactNumber` objects.\n\n```ts\nconst formatCompactNumber = createFormatter(intl)\n```\n\n### **`normalize`**\n\nA function that accepts a `string`, a `CompactNumber` object, an element of `T` type, or an array of those. It then converts all `CompactNumber` objects in the provided value to strings.\n\nIf the provided value is an array and contains elements that are either strings or `CompactNumber` objects, the strings are joined together into a single string.\n\nLikewise, when only a `CompactNumber` is given, the return value is equivalent to `String(value)`.\n\nThis function can be useful for filtering out invalid objects in React projects.\n\n```ts\nnormalize([formatCompactNumber(1_350), { value: 'Hello' }])\n// =\u003e ['1.3K', { value: 'Hello' }]\n\nnormalize([formatCompactNumber(1_350), ' cats'])\n// =\u003e '1.3K cats'\n```\n\n### **`wrapFormatMessage`**\n\nA function that accepts an `IntlShape` object as an argument and returns a wrapping function over the `formatMessage` method of the given `IntlShape` object. This wrapper calls the original `formatMessage` method and then normalizes all output using `normalize`.\n\n```ts\nconst formatMessage = wrapFormatMessage(intl)\nformatMessage(messages.greeting, {\n  letters: formatCompactNumber(12_522),\n})\n// =\u003e 'Hello! You have 12.5K unread mail.'\n```\n\n### **`supportedLocalesOf`**\n\nAccepts a locale or an array of BCP 47 language tags and returns an array of language tags that are supported for generating a pluralisable rounded number.\n\n```ts\nif (supportedLocalesOf(['en-US']).length \u003c 1) {\n  console.log('Missing locale data for English')\n}\n```\n\n### **`addLocaleData`**\n\nA function that accepts BCP 47 language tag and locale data object to store for use.\n\n```ts\nimport data from '@vintl/compact-number/locale-data/en.data'\naddLocaleData('en', enData)\nsupportedLocalesOf(['en-US'])\n// =\u003e ['en']\n```\n\n### **`CompactNumber`**\n\nDescribes an object that holds the original number value as well as formatting options. This object has `toString`, `valueOf` and `toParts` methods that can be used to convert this object into a useful value.\n\nConverting this object to a string (using `toString` or `String()`) will invoke number formatter and return the formatted string.\n\nConverting it to a number (using `valueOf` or `Number()`) will invoke calculation of pluralisable number.\n\nCalling `toParts` method will invoke the number formatter and return the formatted parts.\n\nReturn values of all methods are cached for a lifetime of the `CompactNumber` object.\n\n## **Locale data**\n\nIn order to accurately round the numbers, CLDR locale data is required.\n\nThis module is built with of a subset of locale data provided by the `cldr-numbers-modern` module.\n\nYou can auto-add this data using `@vintl/compact-number/locale-data/[tag]`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvintl-dev%2Fcompact-number","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvintl-dev%2Fcompact-number","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvintl-dev%2Fcompact-number/lists"}