{"id":26057931,"url":"https://github.com/onix-systems/formatters","last_synced_at":"2025-04-11T05:08:13.332Z","repository":{"id":57240483,"uuid":"399095640","full_name":"Onix-Systems/formatters","owner":"Onix-Systems","description":"A javascript library for formatting and manipulating.","archived":false,"fork":false,"pushed_at":"2021-08-26T06:10:38.000Z","size":204,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"dev","last_synced_at":"2025-04-11T05:08:03.217Z","etag":null,"topics":["currency","date-format","format-converter","formatt","formatter","list-format","number-format","percentage","round"],"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/Onix-Systems.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}},"created_at":"2021-08-23T12:28:57.000Z","updated_at":"2022-05-17T05:35:26.000Z","dependencies_parsed_at":"2022-08-29T22:21:34.292Z","dependency_job_id":null,"html_url":"https://github.com/Onix-Systems/formatters","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Onix-Systems%2Fformatters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Onix-Systems%2Fformatters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Onix-Systems%2Fformatters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Onix-Systems%2Fformatters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Onix-Systems","download_url":"https://codeload.github.com/Onix-Systems/formatters/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248345266,"owners_count":21088244,"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":["currency","date-format","format-converter","formatt","formatter","list-format","number-format","percentage","round"],"created_at":"2025-03-08T11:59:45.886Z","updated_at":"2025-04-11T05:08:13.288Z","avatar_url":"https://github.com/Onix-Systems.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Formatters\n\n---\n**NOTE**\n\nFor people who don't like read documentation ;)\n\n---\n\n## Installation\n\n```bash\n\u003e npm i formatters\n```\n\n## Import\n\n```javascript\n// es6\nimport { NumberFormat, ListFormat, DateTimeFormat } from 'formatters';\n\n// es5\nconst {\n    NumberFormat,\n    ListFormat,\n    DateTimeFormat\n} = require('formatters');\n```\n\n## NumberFormat\n\nThe NumberFormat object enables language-sensitive number formatting.\n\n```javascript\nconst { NumberFormat } = require('formatters');\n\nconst number = 123456.789;\n\nconsole.log(NumberFormat('en-US', { style: 'currency', currency: 'EUR' }).format(10000));\n// expected output: \"€123,456.79\"\n\n// the Japanese yen doesn't use a minor unit\nconsole.log(new NumberFormat('ja-JP', { style: 'currency', currency: 'JPY' }).format(number));\n// expected output: \"￥123,457\"\n\n// limit to three significant digits\nconsole.log(new NumberFormat('en-IN', { maximumSignificantDigits: 3 }).format(number));\n// expected output: \"1,23,000\"\n```\n\n## Instance methods\n\n### ```format();```\n\nThe format getter function formats a number into a string according to the locale and formatting options of this NumberFormat object.\n\nExample:\n\n```javascript\nconst amount = 654321.987;\n\nconst options1 = { style: 'currency', currency: 'RUB' };\nconst numberFormat1 = new NumberFormat('ru-RU', options1);\n\nconsole.log(numberFormat1.format(amount));\n// expected output: \"654 321,99 ₽\"\n\nconst options2 = { style: 'currency', currency: 'USD' };\nconst numberFormat2 = new NumberFormat('en-US', options2);\n\nconsole.log(numberFormat2.format(amount));\n// expected output: \"$654,321.99\"\n```\n\n#### Parameters\n\n##### locales Optional\nA string with a BCP 47 language tag, or an array of such strings.\n\n##### options Optional\nAn object with some or all of the following properties:\n\n```compactDisplay```\nOnly used when notation is **\"compact\"**. Takes either **\"short\"** (default) or **\"long\"**.\n\n```currency```\nThe currency to use in currency formatting. Possible values are the ISO 4217 currency codes, such as \"USD\" for the US dollar, \"EUR\" for the euro, or \"CNY\" for the Chinese RMB — see the Current currency \u0026 funds code list. There is no default value; if the style is \"currency\", the currency property must be provided.\n\n```currencyDisplay```\nHow to display the currency in currency formatting. Possible values are:\n\n**\"symbol\"** to use a localized currency symbol such as €, this is the default value,\n**\"narrowSymbol\"** to use a narrow format symbol (\"$100\" rather than \"US$100\"),\n**\"code\"** to use the ISO currency code,\n**\"name\"** to use a localized currency name such as **\"dollar\"**,\ncurrencySign\nIn many locales, accounting format means to wrap the number with parentheses instead of appending a minus sign. You can enable this formatting by setting the currencySign option to **\"accounting\"**. The default value is **\"standard\"**.\n\n```localeMatcher```\nThe locale matching algorithm to use. Possible values are \"lookup\" and \"best fit\"; the default is \"best fit\". For information about this option, see the Intl page.\n\n```notation```\nThe formatting that should be displayed for the number, the defaults is \"standard\"\n\n**\"standard\"** plain number formatting\n**\"scientific\"** return the order-of-magnitude for formatted number.\n**\"engineering\"** return the exponent of ten when divisible by three\n**\"compact\"** string representing exponent, defaults is using the **\"short\"** form.\nnumberingSystem\nNumbering System. Possible values include: **\"arab\", \"arabext\", \" bali\", \"beng\", \"deva\", \"fullwide\", \" gujr\", \"guru\", \"hanidec\", \"khmr\", \" knda\", \"laoo\", \"latn\", \"limb\", \"mlym\", \" mong\", \"mymr\", \"orya\", \"tamldec\", \" telu\", \"thai\", \"tibt\"**.\n\n```signDisplay```\nWhen to display the sign for the number; defaults to \"auto\"\n\n**\"auto\"** sign display for negative numbers only\n**\"never\"** never display sign\n**\"always\"** always display sign\n**\"exceptZero\"** sign display for positive and negative numbers, but not zero\n```style```\nThe formatting style to use , the default is **\"decimal\"**.\n\n**\"decimal\"** for plain number formatting.\n**\"currency\"** for currency formatting.\n**\"percent\"** for percent formatting\n**\"unit\"** for unit formatting\n\n```javascript\nlet amount = 3500;\n\nnew NumberFormat('en-US', {style: 'decimal'}).format(amount);\n// → '3,500'\nnew NumberFormat('en-US', {style: 'percent'}).format(amount);\n// → '350,000%'\n```\n\n```unit```\nThe unit to use in unit formatting, Possible values are core unit identifiers, defined in UTS #35, Part 2, Section 6. A subset of units from the full list was selected for use in ECMAScript. Pairs of simple units can be concatenated with \"-per-\" to make a compound unit. There is no default value; if the style is \"unit\", the unit property must be provided.\n\n```unitDisplay```\nThe unit formatting style to use in unit formatting, the defaults is **\"short\"**.\n\n**\"long\"** (e.g., 16 litres)\n**\"short\"** (e.g., 16 l)\n**\"narrow\"** (e.g., 16l)\nuseGrouping\nWhether to use grouping separators, such as thousands separators or thousand/lakh/crore separators. Possible values are true and false; the default is true.\n\nThe following properties fall into two groups: ```minimumIntegerDigits, minimumFractionDigits, and maximumFractionDigits``` in one group, ```minimumSignificantDigits and maximumSignificantDigits``` in the other. If at least one property from the second group is defined, then the first group is ignored.\n\n```minimumIntegerDigits```\nThe minimum number of integer digits to use. Possible values are from 1 to 21; the default is 1.\n\n```minimumFractionDigits```\nThe minimum number of fraction digits to use. Possible values are from 0 to 20; the default for plain number and percent formatting is 0; the default for currency formatting is the number of minor unit digits provided by the ISO 4217 currency code list (2 if the list doesn't provide that information).\n\n```maximumFractionDigits```\nThe maximum number of fraction digits to use. Possible values are from 0 to 20; the default for plain number formatting is the larger of minimumFractionDigits and 3; the default for currency formatting is the larger of minimumFractionDigits and the number of minor unit digits provided by the ISO 4217 currency code list (2 if the list doesn't provide that information); the default for percent formatting is the larger of minimumFractionDigits and 0.\n\n```minimumSignificantDigits```\nThe minimum number of significant digits to use. Possible values are from 1 to 21; the default is 1.\n\n```maximumSignificantDigits```\nThe maximum number of significant digits to use. Possible values are from 1 to 21; the default is 21.\n\n### ```formatToParts();```\n\nThe formatToParts() method is useful for custom formatting of number strings. It returns an Array of objects containing the locale-specific tokens from which it possible to build custom strings while preserving the locale-specific parts. The structure the formatToParts() method returns example:\n\n```javascript\nconst number = 3500;\n\nconst formatter = new NumberFormat('de-DE', {\n  style: 'currency',\n  currency: 'EUR'\n});\n\nformatter.formatToParts(number);\n\n\n// return value:\n[\n  { type: \"integer\",  value: \"3\"   },\n  { type: \"group\",    value: \".\"   },\n  { type: \"integer\",  value: \"500\" },\n  { type: \"decimal\",  value: \",\"   },\n  { type: \"fraction\", value: \"00\"  },\n  { type: \"literal\",  value: \" \"   },\n  { type: \"currency\", value: \"€\"   }\n]\n```\n\n### ```resolvedOptions();```\n\nThe NumberFormat.prototype.resolvedOptions() method returns a new object with properties reflecting the locale and number formatting options computed during initialization of this\n\nExample:\n\n```javascript\nconst numberFormat1 = new NumberFormat('de-DE');\nconst options1 = numberFormat1.resolvedOptions();\n\nconsole.log(options1.locale);\n// expected output (Firefox / Safari): \"de-DE\"\n// expected output (Chrome): \"de\"\n\nconsole.log(options1.numberingSystem);\n// expected output: \"latn\"\n\nconsole.log(options1.style);\n// expected output: \"decimal\"\n```\n\nThe resulting object has the following properties:\n\n```locale```\nThe BCP 47 language tag for the locale actually used. If any Unicode extension values were requested in the input BCP 47 language tag that led to this locale, the key-value pairs that were requested and are supported for this locale are included in locale.\n\n```numberingSystem```\nThe value provided for this properties in the options argument, if present, or the value requested using the Unicode extension key \"nu\" or filled in as a default.\n\n```notation```\nThe value provided for this property in the options argument, if present, or \"standard\" filled in as a default.\n\n```compactDisplay```\nThe value provided for this property in the options argument, or \"short\" filled in as a default.  This property is only present if the notation is set to \"compact\".\n\n```signDisplay```\nThe value provided for this property in the options argument, or \"auto\" filled in as a default.\n\n```useGrouping```\nThe values provided for these properties in the options argument or filled in as defaults.\n\n```currency, currencyDisplay```\nThe values provided for these properties in the options argument or filled in as defaults. These properties are only present if style is \"currency\".\n\nOnly one of the following two groups of properties is included:\n\n```minimumIntegerDigits, minimumFractionDigits, maximumFractionDigits```\nThe values provided for these properties in the options argument or filled in as defaults. These properties are present only if neither minimumSignificantDigits nor maximumSignificantDigits was provided in the options argument.\n\n```minimumSignificantDigits, maximumSignificantDigits```\nThe values provided for these properties in the options argument or filled in as defaults. These properties are present only if at least one of them was provided in the options argument.\n\n## ListFormat\n\nThe ListFormat object enables language-sensitive list formatting.\n\n```javascript\nconst vehicles = ['Motorcycle', 'Bus', 'Car'];\n\nconst formatter = new ListFormat('en', { style: 'long', type: 'conjunction' });\nconsole.log(formatter.format(vehicles));\n// expected output: \"Motorcycle, Bus, and Car\"\n\nconst formatter2 = new ListFormat('de', { style: 'short', type: 'disjunction' });\nconsole.log(formatter2.format(vehicles));\n// expected output: \"Motorcycle, Bus oder Car\"\n\nconst formatter3 = new ListFormat('en', { style: 'narrow', type: 'unit' });\nconsole.log(formatter3.format(vehicles));\n// expected output: \"Motorcycle Bus Car\"\n```\n\n## Instance methods\n\n### ```format();```\n\nThe format() method returns a string that has been formatted based on parameters provided in the ListFormat object. The locales and options parameters customize the behavior of format() and let applications specify the language conventions that should be used to format the list.\n\nExample:\n\n```javascript\nconst list = ['Motorcycle', 'Bus', 'Car'];\n\n console.log(new ListFormat('en-GB', { style: 'long', type: 'conjunction' }).format(list));\n// \u003e Motorcycle, Bus and Car\n\n console.log(new ListFormat('en-GB', { style: 'short', type: 'disjunction' }).format(list));\n// \u003e Motorcycle, Bus or Car\n\n console.log(new ListFormat('en-GB', { style: 'narrow', type: 'unit' }).format(list));\n// \u003e Motorcycle Bus Car\n```\n\n### ```formatToParts();```\n\nWhereas ListFormat.prototype.format() returns a string being the formatted version of the list (according to the given locale and style options), formatToParts() returns an array of the different components of the formatted string.\n\nEach element of the resulting array has two properties: type and value. The type property may be either \"element\", which refers to a value from the list, or \"literal\" which refers to a linguistic construct. The value property gives the content, as a string, of the token.\n\nThe locale and style options used for formatting are given when constructing the ListFormat instance.\n\nExample:\n\n```javascript\nconst fruits = ['Apple', 'Orange', 'Pineapple'];\nconst myListFormat = new ListFormat('en-GB', { style: 'long', type: 'conjunction' });\n\nconsole.table(myListFormat.formatToParts(fruits));\n// [\n//  { \"type\": \"element\", \"value\": \"Apple\" },\n//  { \"type\": \"literal\", \"value\": \", \" },\n//  { \"type\": \"element\", \"value\": \"Orange\" },\n//  { \"type\": \"literal\", \"value\": \", and \" },\n//  { \"type\": \"element\", \"value\": \"Pineapple\" }\n// ]\n```\n\n## DateTimeFormat\n\nThe DateTimeFormat object enables language-sensitive date and time formatting.\n\n```javascript\nconst date = new Date(Date.UTC(2020, 11, 20, 3, 23, 16, 738));\n// Results below assume UTC timezone - your results may vary\n\n// Specify default date formatting for language (locale)\nconsole.log(new DateTimeFormat('en-US').format(date));\n// expected output: \"12/20/2020\"\n\n// Specify default date formatting for language with a fallback language (in this case Indonesian)\nconsole.log(new DateTimeFormat(['ban', 'id']).format(date));\n// expected output: \"20/12/2020\"\n\n// Specify date and time format using \"style\" options (i.e. full, long, medium, short)\nconsole.log(new DateTimeFormat('en-GB', { dateStyle: 'full', timeStyle: 'long' }).format(date));\n// Expected output \"Sunday, 20 December 2020 at 14:23:16 GMT+11\"\n```\n\n## Instance methods\n\n### ```format();```\n\nThe format getter formats a date into a string according to the locale and formatting options of this DateTimeFormat object.\n\nExample:\n\n```javascript\nconst options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };\nconst dateTimeFormat = new DateTimeFormat('sr-RS', options);\n\nconsole.log(dateTimeFormat.format(new Date()));\n```\n\n### ```formatRange();```\n\nThe DateTimeFormat.prototype.formatRange() formats a date range in the most concise way based on the locale and options provided when instantiating DateTimeFormat object.\n\nExample:\n\n```javascript\nconst options1 = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };\nconst options2 = { year: '2-digit', month: 'numeric', day: 'numeric' };\n\nconst startDate = new Date(Date.UTC(2007, 0, 10, 10, 0, 0));\nconst endDate = new Date(Date.UTC(2008, 0, 10, 11, 0, 0));\n\nconst dateTimeFormat = new DateTimeFormat('en', options1);\nconsole.log(dateTimeFormat.formatRange(startDate, endDate));\n// expected output: Wednesday, January 10, 2007 – Thursday, January 10, 2008\n\nconst dateTimeFormat2 = new DateTimeFormat('en', options2);\nconsole.log(dateTimeFormat2.formatRange(startDate, endDate));\n// expected output: 1/10/07 – 1/10/08\n\n```\n\n```javascript\nlet date1 = new Date(Date.UTC(2007, 0, 10, 10, 0, 0));\nlet date2 = new Date(Date.UTC(2007, 0, 10, 11, 0, 0));\nlet date3 = new Date(Date.UTC(2007, 0, 20, 10, 0, 0));\n// \u003e 'Wed, 10 Jan 2007 10:00:00 GMT'\n// \u003e 'Wed, 10 Jan 2007 11:00:00 GMT'\n// \u003e 'Sat, 20 Jan 2007 10:00:00 GMT'\n\nlet fmt1 = new DateTimeFormat(\"en\", {\n    year: '2-digit',\n    month: 'numeric',\n    day: 'numeric',\n    hour: 'numeric',\n    minute: 'numeric'\n});\nconsole.log(fmt1.format(date1));\nconsole.log(fmt1.formatRange(date1, date2));\nconsole.log(fmt1.formatRange(date1, date3));\n// \u003e '1/10/07, 10:00 AM'\n// \u003e '1/10/07, 10:00 – 11:00 AM'\n// \u003e '1/10/07, 10:00 AM – 1/20/07, 10:00 AM'\n\nlet fmt2 = new DateTimeFormat(\"en\", {\n    year: 'numeric',\n    month: 'short',\n    day: 'numeric'\n});\nconsole.log(fmt2.format(date1));\nconsole.log(fmt2.formatRange(date1, date2));\nconsole.log(fmt2.formatRange(date1, date3));\n// \u003e 'Jan 10, 2007'\n// \u003e 'Jan 10, 2007'\n// \u003e 'Jan 10 – 20, 2007'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonix-systems%2Fformatters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonix-systems%2Fformatters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonix-systems%2Fformatters/lists"}