{"id":16644229,"url":"https://github.com/75lb/byte-size","last_synced_at":"2025-04-04T17:07:53.400Z","repository":{"id":17752103,"uuid":"20602823","full_name":"75lb/byte-size","owner":"75lb","description":"Isomorphic function to convert a bytes value (e.g. 3456) to a human-readable string ('3.5 kB')","archived":false,"fork":false,"pushed_at":"2023-09-21T16:01:45.000Z","size":568,"stargazers_count":70,"open_issues_count":1,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-14T05:11:06.576Z","etag":null,"topics":["byte","bytes","human-readable-units","iec-units","isomorphic","isomorphic-javascript","javascript","javascript-library","nodejs","npm-package"],"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/75lb.png","metadata":{"files":{"readme":"README.hbs","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":"2014-06-07T21:10:31.000Z","updated_at":"2024-07-20T19:40:15.642Z","dependencies_parsed_at":"2024-06-18T13:49:01.382Z","dependency_job_id":"fe3272f2-6247-4597-b996-5a13de3c53d0","html_url":"https://github.com/75lb/byte-size","commit_stats":{"total_commits":82,"total_committers":5,"mean_commits":16.4,"dds":0.07317073170731703,"last_synced_commit":"27828e48e456ac27fcc9eac5a6cc27c5c4d87628"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/75lb%2Fbyte-size","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/75lb%2Fbyte-size/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/75lb%2Fbyte-size/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/75lb%2Fbyte-size/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/75lb","download_url":"https://codeload.github.com/75lb/byte-size/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217183,"owners_count":20903009,"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":["byte","bytes","human-readable-units","iec-units","isomorphic","isomorphic-javascript","javascript","javascript-library","nodejs","npm-package"],"created_at":"2024-10-12T08:10:50.474Z","updated_at":"2025-04-04T17:07:53.379Z","avatar_url":"https://github.com/75lb.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![view on npm](https://badgen.net/npm/v/byte-size)](https://www.npmjs.org/package/byte-size)\n[![npm module downloads](https://badgen.net/npm/dt/byte-size)](https://www.npmjs.org/package/byte-size)\n[![Gihub repo dependents](https://badgen.net/github/dependents-repo/75lb/byte-size)](https://github.com/75lb/byte-size/network/dependents?dependent_type=REPOSITORY)\n[![Gihub package dependents](https://badgen.net/github/dependents-pkg/75lb/byte-size)](https://github.com/75lb/byte-size/network/dependents?dependent_type=PACKAGE)\n[![Node.js CI](https://github.com/75lb/byte-size/actions/workflows/node.js.yml/badge.svg)](https://github.com/75lb/byte-size/actions/workflows/node.js.yml)\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/feross/standard)\n\n***Upgraders, please check the [release notes](https://github.com/75lb/byte-size/releases).***\n\n# byte-size\n\nAn isomorphic, load-anywhere function to convert a bytes value (e.g. `3456`) to a human-readable string (`'3.5 kB'`). Choose between [metric or IEC units](https://en.wikipedia.org/wiki/Gigabyte) (summarised below) or specify your own custom units.\n\nValue  | Metric        | Metric (octet) |\n-----  | ------------- | -------------- |\n1000   | kB  kilobyte  | ko  kilooctet  |\n1000^2 | MB  megabyte  | Mo  megaoctet  |\n1000^3 | GB  gigabyte  | Go  gigaoctet  |\n1000^4 | TB  terabyte  | To  teraoctet  |\n1000^5 | PB  petabyte  | Po  petaoctet  |\n1000^6 | EB  exabyte   | Eo  exaoctet   |\n1000^7 | ZB  zettabyte | Zo  zettaoctet |\n1000^8 | YB  yottabyte | Yo  yottaoctet |\n\nValue  | IEC          | IEC (octet)   |\n------ | ------------ | ------------- |\n1024   | KiB kibibyte | Kio kibioctet |\n1024^2 | MiB mebibyte | Mio mebioctet |\n1024^3 | GiB gibibyte | Gio gibioctet |\n1024^4 | TiB tebibyte | Tio tebioctet |\n1024^5 | PiB pebibyte | Pio pebioctet |\n1024^6 | EiB exbibyte | Eio exbioctet |\n1024^7 | ZiB zebibyte | Zio zebioctet |\n1024^8 | YiB yobibyte | Yio yobioctet |\n\n## Synopsis\n\nBy default, `byteSize` converts the input number to a human readable string with metric units and a precision of 1.\n\n```js\n\u003e const byteSize = require('byte-size')\n\n\u003e byteSize(1580)\n{ value: '1.6', unit: 'kB', long: 'kilobytes' }\n```\n\nThe object returned by `byteSize` defines a `toString` method therefore can be used directly in string context.\n\n```js\n\u003e `Filesize: ${byteSize(12400)}`\n'Filesize: 12.4 kB'\n```\n\nOverride the default `toString` behaviour by setting [`options.toStringFn`](#bytesizebytes-options--object-).\n\n```js\n\u003e function toStringFn () {\n  return `**${this.value}${this.unit}**`\n}\n\n\u003e `Filesize: ${byteSize(12400, { toStringFn })}`\n'Filesize: **12.4kB**'\n```\n\nBeside the default of `metric`, there are three other built-in units available: `metric_octet`, `iec` and `iec_octet`.\n\n```js\n\u003e byteSize(1580, { units: 'iec' })\n{ value: '1.5', unit: 'KiB', long: 'kibibytes' }\n\n\u003e byteSize(1580, { units: 'iec_octet' })\n{ value: '1.5', unit: 'Kio', long: 'kibioctets' }\n\n\u003e byteSize(1580, { units: 'metric_octet' })\n{ value: '1.6', unit: 'ko', long: 'kilooctets' }\n```\n\nYou can adjust the `precision`.\n\n```js\n\u003e byteSize(1580, { units: 'iec', precision: 3 })\n{ value: '1.543', unit: 'KiB', long: 'kibibytes' }\n\n\u003e byteSize(1580, { units: 'iec', precision: 0 })\n{ value: '2', unit: 'KiB', long: 'kibibytes' }\n```\n\nDefine custom units by passing an object containing one or more additional conversion tables to `options.customUnits`. In `options.units`, specify the name of a property from the `customUnits` object.\n\n```js\n\u003e const customUnits = {\n  simple: [\n    { from: 0   , to: 1e3 , unit: ''  },\n    { from: 1e3 , to: 1e6 , unit: 'K', long: 'thousand' },\n    { from: 1e6 , to: 1e9 , unit: 'Mn', long: 'million' },\n    { from: 1e9 , to: 1e12, unit: 'Bn', long: 'billion' }\n  ]\n}\n\n\u003e const { value, unit } = byteSize(10000, { customUnits, units: 'simple' })\n\n\u003e `${value}${unit}`\n'10.0K'\n```\n\nOverride the built-in defaults for the duration of the process by passing an options object to `byteSize.defaultOptions()`. This results in cleaner code in cases where `byteSize` is used often with the same options.\n\n```js\n\u003e byteSize.defaultOptions({\n  units: 'simple',\n  precision: 2,\n  customUnits: {\n    simple: [\n      { from: 0, to: 1e3, unit: '' },\n      { from: 1e3, to: 1e6, unit: 'k' },\n      { from: 1e6, to: 1e9, unit: 'm' },\n      { from: 1e9, to: 1e12, unit: 'bn' },\n    ]\n  },\n  toStringFn: function () {\n    return this.value + this.unit\n  }\n})\n\n\u003e [2400, 16400, 3991200].map(byteSize).join(', ')\n'2.40k, 16.40k, 3.99m'\n```\n\n{{\u003emain}}\n\n## Load anywhere\n\nThis library is compatible with Node.js, the Web and any style of module loader. It can be loaded anywhere, natively without transpilation.\n\nNode.js (CommonJS):\n\n```js\nconst byteSize = require('byte-size')\n```\n\nNode.js (ECMAScript Module):\n\n```js\nimport byteSize from 'byte-size'\n```\n\nWithin a modern browser ECMAScript Module:\n\n```js\nimport byteSize from './node_modules/byte-size/index.js'\n```\n\nBrowser global (adds `window.byteSize`):\n\n```html\n\u003cscript src=\"./node_modules/byte-size/dist/index.js\"\u003e\u003c/script\u003e\n```\n\n* * *\n\n\u0026copy; 2014-25 [Lloyd Brookes](https://github.com/75lb) \\\u003copensource@75lb.com\\\u003e.\n\nTested by [test-runner](https://github.com/test-runner-js/test-runner). Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F75lb%2Fbyte-size","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F75lb%2Fbyte-size","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F75lb%2Fbyte-size/lists"}