{"id":16816808,"url":"https://github.com/johnguan/neo-bytes","last_synced_at":"2025-04-11T02:22:00.933Z","repository":{"id":241278498,"uuid":"804763524","full_name":"JohnGuan/neo-bytes","owner":"JohnGuan","description":"Convert bytes to a human readable string: 1337 → 1.34 kB","archived":false,"fork":false,"pushed_at":"2024-05-24T05:43:25.000Z","size":13,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T23:41:31.662Z","etag":null,"topics":["bytes","filesize","human","humanized","pretty-bytes"],"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/JohnGuan.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":"2024-05-23T08:13:44.000Z","updated_at":"2024-05-28T03:17:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"5b705146-22ff-455b-998f-56dc5d773da7","html_url":"https://github.com/JohnGuan/neo-bytes","commit_stats":null,"previous_names":["johnguan/neo-bytes"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnGuan%2Fneo-bytes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnGuan%2Fneo-bytes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnGuan%2Fneo-bytes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnGuan%2Fneo-bytes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JohnGuan","download_url":"https://codeload.github.com/JohnGuan/neo-bytes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248328462,"owners_count":21085323,"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":["bytes","filesize","human","humanized","pretty-bytes"],"created_at":"2024-10-13T10:45:25.456Z","updated_at":"2025-04-11T02:22:00.918Z","avatar_url":"https://github.com/JohnGuan.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# neo-bytes\n\n\u003e Convert bytes to a human readable string: `1337` → `1.34 kB`\n\nUseful for displaying file sizes for humans.\n\n*Note that it uses base-10 (e.g. kilobyte).\n[Read about the difference between kilobyte and kibibyte.](https://web.archive.org/web/20150324153922/https://pacoup.com/2009/05/26/kb-kb-kib-whats-up-with-that/)*\n\n\u003e This project stands on the shoulders of the great **[pretty-bytes](https://github.com/sindresorhus/pretty-bytes) by [Sindre Sorhus](https://github.com/sindresorhus)**. \n\u003e\n\u003e It is a fork of the original project with additional features.\n\n## Install\n\n```sh\nnpm install neo-bytes\n```\n\n## Usage\n\n```js\nimport neoBytes from 'neo-bytes';\n\nneoBytes(1337);\n//=\u003e '1.34 kB'\n\nneoBytes(100);\n//=\u003e '100 B'\n\n// Display with units of bits\nneoBytes(1337, {bits: true});\n//=\u003e '1.34 kbit'\n\n// Display file size differences\nneoBytes(42, {signed: true});\n//=\u003e '+42 B'\n\n// Localized output using German locale\nneoBytes(1337, {locale: 'de'});\n//=\u003e '1,34 kB'\n```\n\n### Migrating from `pretty-bytes`\n\nCurrently, `neo-bytes` is fully compatible with `pretty-bytes`. \n\nIf you need the **additional features** of `neo-bytes`. \n\nYou can migrate to `neo-bytes` in the fastest way by doing the following:\n\n```js\n// Before\nimport prettyBytes from 'pretty-bytes';\n//                       ^^^^^^\n\n// After\nimport prettyBytes from 'neo-bytes';\n//                       ^^^\n\n// Or fully use the new name (recommended)\nimport neoBytes from 'neo-bytes';\n//     ^^^            ^^^\n```\n\n## Choose the Right Unit\n\n`neo-bytes`, like the original `pretty-bytes`, only does basic **human-readable** conversion.\n\nBut I found that in practice. It is really hard to understand how to choose units in different situations.\n\nHere are my suggestions based on a lot of study and practice.\n\n\u003e If there is any disagreement, please raise an [issue](https://github.com/JohnGuan/neo-bytes/issues) and we can discuss about it.\n\n### Memory / CPU Cache Size\n\n\u003e **Use `binary` and `noi`**\n\u003e \n\u003e Follow the [JEDEC memory standards](https://en.wikipedia.org/wiki/JEDEC_memory_standards), which is the most common standard for memory size.\n\n\n```js\n// A custom function to make it easier\nconst memorySize = (n) =\u003e neoBytes(n, {binary: true, noi: true});\n\n// Example\nmemorySize(67108864); // 64 * 1024 * 1024\n//=\u003e '64 MB'\n\nmemorySize(68719476736); // 64 * 1024 * 1024 * 1024\n//=\u003e '64 GB'\n```\n\n### Storage / Disk / File Size\n\n\u003e **Use nothing**\n\n```js\n// A custom function to make it easier\nconst storageSize = (n) =\u003e neoBytes(n);\n\n// Example\nstorageSize(128000000000); // 128 * 1000 * 1000 * 1000\n//=\u003e '128 GB'\n```\n\n```js\n// A custom function to make it easier\nconst diskSize = (n) =\u003e neoBytes(n);\n\ndiskSize(16000000000000); // 16 * 1000 * 1000 * 1000 * 1000\n//=\u003e '16 TB'\n```\n\n```js\n// A custom function to make it easier\nconst fileSize = (n) =\u003e neoBytes(n);\n\n// Example\nfileSize(1233445);\n//=\u003e '1.23 MB'\n```\n\n### Link Speed / Network Bandwidth\n\n\u003e **Use `bits`, `noit` and `suffix`**\n\n```js\n// A custom function to make it easier\nconst linkSpeed = (n) =\u003e neoBytes(n, {bits: true, noit: true, suffix: 'ps'});\n\n// Example\nlinkSpeed(1000000000); // 1 * 1000 * 1000 * 1000\n//=\u003e '1 Gbps'\n```\n\n### Download Speed / File Transfer Speed\n\n\u003e **Use `suffix`**\n\n```js\n// A custom function to make it easier\nconst downloadSpeed = (n) =\u003e neoBytes(n, {suffix: '/s'});\n\n// Example\ndownloadSpeed(1000000); // 1 * 1000 * 1000\n//=\u003e '1 MB/s'\n```\n\n### Reference\n- [Byte](https://en.wikipedia.org/wiki/Byte)\n- [Bit](https://en.wikipedia.org/wiki/Bit)\n- [JEDEC memory standards](https://en.wikipedia.org/wiki/JEDEC_memory_standards)\n- [Metric prefix](https://en.wikipedia.org/wiki/Metric_prefix)\n- [Binary Prefix](https://en.wikipedia.org/wiki/Binary_prefix)\n\n## API\n\n### neoBytes(number, options?)\n\n#### number\n\nType: `number`\n\nThe number to format.\n\n#### options\n\nType: `object`\n\n##### signed\n\nType: `boolean`\\\nDefault: `false`\n\nInclude plus sign for positive numbers. If the difference is exactly zero a space character will be prepended instead for better alignment.\n\n##### bits\n\nType: `boolean`\\\nDefault: `false`\n\nFormat the number as [bits](https://en.wikipedia.org/wiki/Bit) instead of [bytes](https://en.wikipedia.org/wiki/Byte). This can be useful when, for example, referring to [bit rate](https://en.wikipedia.org/wiki/Bit_rate).\n\n##### binary\n\nType: `boolean`\\\nDefault: `false`\n\nFormat the number using the [Binary Prefix](https://en.wikipedia.org/wiki/Binary_prefix) instead of the [SI Prefix](https://en.wikipedia.org/wiki/SI_prefix). This can be useful for presenting memory amounts. However, this should not be used for presenting file sizes.\n\n##### locale\n\nType: `boolean | string`\\\nDefault: `false` *(No localization)*\n\n**Important:** Only the number and decimal separator are localized. The unit title is not and will not be localized.\n\n- If `true`: Localize the output using the system/browser locale.\n- If `string`: Expects a [BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) (For example: `en`, `de`, …)\n- If `string[]`: Expects a list of [BCP 47 language tags](https://en.wikipedia.org/wiki/IETF_language_tag) (For example: `en`, `de`, …)\n\n##### minimumFractionDigits\n\nType: `number`\\\nDefault: `undefined`\n\nThe minimum number of fraction digits to display.\n\nIf neither `minimumFractionDigits` or `maximumFractionDigits` are set, the default behavior is to round to 3 significant digits.\n\n```js\nimport neoBytes from 'neo-bytes';\n\n// Show the number with at least 3 fractional digits\nneoBytes(1900, {minimumFractionDigits: 3});\n//=\u003e '1.900 kB'\n\nneoBytes(1900);\n//=\u003e '1.9 kB'\n```\n\n##### maximumFractionDigits\n\nType: `number`\\\nDefault: `undefined`\n\nThe maximum number of fraction digits to display.\n\nIf neither `minimumFractionDigits` or `maximumFractionDigits` are set, the default behavior is to round to 3 significant digits.\n\n```js\nimport neoBytes from 'neo-bytes';\n\n// Show the number with at most 1 fractional digit\nneoBytes(1920, {maximumFractionDigits: 1});\n//=\u003e '1.9 kB'\n\nneoBytes(1920);\n//=\u003e '1.92 kB'\n```\n\n##### space\n\nType: `boolean`\\\nDefault: `true`\n\nPut a space between the number and unit.\n\n```js\nimport neoBytes from 'neo-bytes';\n\nneoBytes(1920, {space: false});\n//=\u003e '1.9kB'\n\nneoBytes(1920);\n//=\u003e '1.92 kB'\n```\n\n##### noi\n\nType: `boolean`\\\nDefault: `false`\n\nRemove 'i' from the `binary` enabled formatted output.\n  \n```js\nimport neoBytes from 'neo-bytes';\n\nneoBytes(1024, {binary: true});\n//=\u003e '1 kiB'\n\nneoBytes(1024, {binary: true, noi: true});\n//=\u003e '1 kB'\n```\n\n##### noit\n\nType: `boolean`\\\nDefault: `false`\n\nRemove 'it' from the `bits` enabled formatted output.\n\n```js\nimport neoBytes from 'neo-bytes';\n\nneoBytes(1337, {bits: true});\n//=\u003e '1.34 kbit'\n\nneoBytes(1337, {bits: true, noit: true});\n//=\u003e '1.34 kb'\n```\n\n##### suffix\n\nType: `string`\\\nDefault: `undefined`\n\nSuffix to append to the formatted number.\n\n```js\nimport neoBytes from 'neo-bytes';\n\nneoBytes(1337, {suffix: '/s'});\n//=\u003e '1.34 kB/s'\n\nneoBytes(10e8, {bits: true, noit: true, suffix: 'ps'});\n//=\u003e '1 Gbps'\n\nneoBytes(10e9, {bits: true, space: false, noit: true, suffix: 'ps'})\n//=\u003e '10Gbps'\n```\n\n## Related\n\n- [pretty-bytes](https://github.com/sindresorhus/pretty-bytes) - Original module\n- [pretty-bytes-cli](https://github.com/sindresorhus/pretty-bytes-cli) - CLI for original module\n- [pretty-ms](https://github.com/sindresorhus/pretty-ms) - Convert milliseconds to a human readable string\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnguan%2Fneo-bytes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnguan%2Fneo-bytes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnguan%2Fneo-bytes/lists"}