push.rocks/smartformat
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(package): modernize package configuration, tooling, and documentation

Browse Source
This commit is contained in:
Jürgen Kunz
2026-05-01 22:21:02 +00:00
parent 6efab60a6f
commit 0b1c20386d
13 changed files with 7883 additions and 4282 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.smartconfig.json
+39
View File
@@ -0,0 +1,39 @@
{
"@ship.zone/szci": {
"npmGlobalTools": [],
"npmRegistryUrl": "registry.npmjs.org"
},
"@git.zone/cli": {
"projectType": "npm",
"module": {
"githost": "code.foss.global",
"gitscope": "push.rocks",
"gitrepo": "smartformat",
"shortDescription": "Human-readable byte and duration formatting",
"description": "A module that formats bytes and milliseconds into human-readable strings.",
"npmPackagename": "@push.rocks/smartformat",
"license": "MIT",
"keywords": [
"formatting",
"bytes to string",
"milliseconds to string",
"human-readable",
"pretty print",
"time",
"data size",
"typescript",
"npm package"
]
},
"release": {
"registries": [
"https://verdaccio.lossless.digital",
"https://registry.npmjs.org"
],
"accessLevel": "public"
}
},
"@git.zone/tsdoc": {
"legal": "\n## License and Legal Information\n\nThis repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.\n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.\n\nUse of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District Court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
}
}
changelog.md
+21
View File
@@ -0,0 +1,21 @@
# Changelog
## 2026-05-01 - 1.1.0 - feat(package)
modernize package configuration, tooling, and documentation
- add package exports and include smartconfig and license files in published package
- upgrade build, test, and type tooling along with pretty-bytes and pretty-ms dependencies
- replace placeholder test with runtime formatting assertions for bytes and milliseconds
- rewrite the README with installation, usage examples, API notes, and development guidance
## 2024-05-29 - 1.0.3 - metadata
Minor project metadata updates across 1.0.3 without functional changes.
- Updated project description
- Includes version tagging and release housekeeping for 1.0.3
## 2024-04-23 - 1.0.2 - core
Core maintenance updates in the 1.0.1–1.0.2 range.
- Applied core update fixes
- Summarizes repeated trivial fix commits and release version bumps for 1.0.1 and 1.0.2
license
+1 -4
View File
@@ -1,6 +1,4 @@
The MIT License (MIT) Copyright (c) 2026 Task Venture Capital GmbH <hello@task.vc>
Copyright (c) 2014 Task Venture Capital GmbH
Permission is hereby granted, free of charge, to any person obtaining a copy Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal of this software and associated documentation files (the "Software"), to deal
@@ -19,4 +17,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. SOFTWARE.
npmextra.json
+16 -9
View File
@@ -1,14 +1,18 @@
{ {
"gitzone": { "@ship.zone/szci": {
"npmGlobalTools": [],
"npmRegistryUrl": "registry.npmjs.org"
},
"@git.zone/cli": {
"projectType": "npm", "projectType": "npm",
"module": { "module": {
"githost": "code.foss.global", "githost": "code.foss.global",
"gitscope": "push.rocks", "gitscope": "push.rocks",
"gitrepo": "smartformat", "gitrepo": "smartformat",
"shortDescription": "Human-readable byte and duration formatting",
"description": "A module that formats bytes and milliseconds into human-readable strings.", "description": "A module that formats bytes and milliseconds into human-readable strings.",
"npmPackagename": "@push.rocks/smartformat", "npmPackagename": "@push.rocks/smartformat",
"license": "MIT", "license": "MIT",
"projectDomain": "push.rocks",
"keywords": [ "keywords": [
"formatting", "formatting",
"bytes to string", "bytes to string",
@@ -20,13 +24,16 @@
"typescript", "typescript",
"npm package" "npm package"
] ]
},
"release": {
"registries": [
"https://verdaccio.lossless.digital",
"https://registry.npmjs.org"
],
"accessLevel": "public"
} }
}, },
"npmci": { "@git.zone/tsdoc": {
"npmGlobalTools": [], "legal": "\n## License and Legal Information\n\nThis repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.\n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.\n\nUse of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District Court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
"npmAccessLevel": "public"
},
"tsdoc": {
"legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
} }
} }
package.json
+16 -13
View File
@@ -3,27 +3,28 @@
"version": "1.0.3", "version": "1.0.3",
"private": false, "private": false,
"description": "A module that formats bytes and milliseconds into human-readable strings.", "description": "A module that formats bytes and milliseconds into human-readable strings.",
"exports": {
".": "./dist_ts/index.js"
},
"main": "dist_ts/index.js", "main": "dist_ts/index.js",
"typings": "dist_ts/index.d.ts", "typings": "dist_ts/index.d.ts",
"type": "module", "type": "module",
"author": "Task Venture Capital GmbH", "author": "Task Venture Capital GmbH <hello@task.vc>",
"license": "MIT", "license": "MIT",
"scripts": { "scripts": {
"test": "(tstest test/ --web)", "test": "tstest test/",
"build": "(tsbuild --web --allowimplicitany)", "build": "tsbuild --web",
"buildDocs": "(tsdoc)" "buildDocs": "tsdoc"
}, },
"devDependencies": { "devDependencies": {
"@git.zone/tsbuild": "^2.1.25", "@git.zone/tsbuild": "^4.4.0",
"@git.zone/tsbundle": "^2.0.5", "@git.zone/tsdoc": "^2.0.3",
"@git.zone/tsrun": "^1.2.46", "@git.zone/tstest": "^3.6.3",
"@git.zone/tstest": "^1.0.44", "@types/node": "^25.6.0"
"@push.rocks/tapbundle": "^5.0.15",
"@types/node": "^20.8.7"
}, },
"dependencies": { "dependencies": {
"pretty-bytes": "^6.1.1", "pretty-bytes": "^7.1.0",
"pretty-ms": "^9.0.0" "pretty-ms": "^9.3.0"
}, },
"repository": { "repository": {
"type": "git", "type": "git",
@@ -45,6 +46,8 @@
"dist_ts_web/**/*", "dist_ts_web/**/*",
"assets/**/*", "assets/**/*",
"cli.js", "cli.js",
".smartconfig.json",
"license",
"npmextra.json", "npmextra.json",
"readme.md" "readme.md"
], ],
@@ -59,4 +62,4 @@
"typescript", "typescript",
"npm package" "npm package"
] ]
} }
pnpm-lock.yaml
Generated
+7626 -4192
View File
File diff suppressed because it is too large Load Diff
readme.md
+144 -50
View File
@@ -1,103 +1,197 @@
# @push.rocks/smartformat # @push.rocks/smartformat
format things Format machine values into strings humans can scan instantly. `@push.rocks/smartformat` is a small ESM TypeScript package that exports the proven `pretty-bytes` and `pretty-ms` formatters from one Push Rocks namespace.
## Install Use it when logs, dashboards, CLIs, progress views, test output, or API responses need readable file sizes and durations without custom formatting code.
To install `@push.rocks/smartformat`, use npm (or yarn, or pnpm) by running the following command in your terminal: ## Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
## Installation
```bash ```bash
npm install @push.rocks/smartformat --save pnpm add @push.rocks/smartformat
``` ```
This will add `@push.rocks/smartformat` to your project dependencies, allowing you to use it in your project. ## What You Get
## Usage - `prettyBytes(number, options?)` converts bytes or bits into SI or binary-prefixed strings.
- `prettyMs(milliseconds, options?)` converts durations into compact, verbose, colon-style, or precision-focused strings.
- Native ESM and TypeScript declarations via the published `dist_ts` build.
- Browser and Node.js compatibility through the package's web build pipeline.
`@push.rocks/smartformat` is a TypeScript module designed to help with formatting things, specifically bytes and milliseconds into a more human-friendly format. It leverages the power of `pretty-bytes` and `pretty-ms` packages to do so. This guide will help you get started with `@push.rocks/smartformat` by providing a series of examples and use cases. ## Quick Start
### Importing in TypeScript
Firstly, ensure that your project is set up to support TypeScript and ES modules. Then, you can import `@push.rocks/smartformat` into your project as follows:
```typescript
import * as smartformat from '@push.rocks/smartformat';
```
Alternatively, if you only need specific functionalities, you can import them directly:
```typescript ```typescript
import { prettyBytes, prettyMs } from '@push.rocks/smartformat'; import { prettyBytes, prettyMs } from '@push.rocks/smartformat';
const downloaded = prettyBytes(1337);
// '1.34 kB'
const duration = prettyMs(1337);
// '1.3s'
console.log(`Downloaded ${downloaded} in ${duration}`);
// Downloaded 1.34 kB in 1.3s
``` ```
### Formatting Bytes You can also import the namespace when that reads better in your codebase:
When working with file sizes or data amounts, it can be helpful to present these figures in a format that is easier for humans to understand. This is where `prettyBytes` comes into play.
#### Basic Usage
```typescript ```typescript
// Convert bytes to a human-readable string: import * as smartformat from '@push.rocks/smartformat';
const fileSize = smartformat.prettyBytes(132480239);
console.log(fileSize); // Outputs: "132.5 MB" smartformat.prettyBytes(42, { signed: true });
// '+42 B'
smartformat.prettyMs(95_500, { colonNotation: true });
// '1:35.5'
``` ```
#### Handling Negative Values ## Formatting Bytes
`prettyBytes` also gracefully handles negative values, which can be useful in certain contexts like showing the difference between file sizes. `prettyBytes` is ideal for file sizes, payload sizes, storage usage, upload/download progress, and byte deltas.
```typescript ```typescript
const sizeDifference = smartformat.prettyBytes(-827391); import { prettyBytes } from '@push.rocks/smartformat';
console.log(sizeDifference); // Outputs: "-827.4 kB"
prettyBytes(100);
// '100 B'
prettyBytes(1_337);
// '1.34 kB'
prettyBytes(1_024, { binary: true });
// '1 KiB'
prettyBytes(1_337, { bits: true });
// '1.34 kbit'
prettyBytes(42, { signed: true });
// '+42 B'
prettyBytes(1_337, { locale: 'de' });
// '1,34 kB'
``` ```
### Formatting Milliseconds Useful `prettyBytes` options include:
In many applications, representing time durations in a human-friendly manner is essential. `prettyMs` simplifies this task. - `bits`: format values as bits instead of bytes.
- `binary`: use binary prefixes like `KiB` instead of SI prefixes like `kB`.
- `signed`: include a plus sign for positive values, useful for diffs.
- `locale`: localize number formatting while keeping the unit label stable.
- `minimumFractionDigits` and `maximumFractionDigits`: control decimal precision.
- `space` and `nonBreakingSpace`: control spacing between value and unit.
- `fixedWidth`: right-align output for tables, progress bars, and terminal output.
#### Basic Usage ## Formatting Durations
`prettyMs` is built for elapsed time, latency, countdowns, retries, benchmark output, and job runtimes.
```typescript ```typescript
// Convert milliseconds to a human-readable string: import { prettyMs } from '@push.rocks/smartformat';
const duration = smartformat.prettyMs(65799000);
console.log(duration); // Outputs: "18h 19m 59s" prettyMs(133);
// '133ms'
prettyMs(1_337);
// '1.3s'
prettyMs(1_337_000_000);
// '15d 11h 23m 20s'
prettyMs(1_335_669_000, { verbose: true });
// '15 days 11 hours 1 minute 9 seconds'
prettyMs(95_500, { colonNotation: true });
// '1:35.5'
prettyMs(100.400080, { formatSubMilliseconds: true });
// '100ms 400µs 80ns'
``` ```
#### More Options Useful `prettyMs` options include:
`prettyMs` offers several options to customize the output. For example, you can include milliseconds in the output or opt for a compact representation. - `compact`: show only the first unit.
- `unitCount`: limit how many units appear.
- `verbose`: use full unit names.
- `colonNotation`: format durations like a digital timer.
- `secondsDecimalDigits` and `millisecondsDecimalDigits`: control precision.
- `separateMilliseconds`: show milliseconds as their own unit.
- `formatSubMilliseconds`: include microseconds and nanoseconds.
- `hideYear`, `hideYearAndDays`, and `hideSeconds`: tune which units appear.
- `subSecondsAsDecimals`: present sub-second values as decimal seconds.
## Practical Examples
### CLI Output
```typescript ```typescript
// Including milliseconds in the output: import { prettyBytes, prettyMs } from '@push.rocks/smartformat';
const preciseDuration = smartformat.prettyMs(65799450, { verbose: true });
console.log(preciseDuration); // Outputs: "18 hours 19 minutes 59.5 seconds"
// Compact representation: const transferredBytes = 48_203_991;
const compactDuration = smartformat.prettyMs(12345678, { compact: true }); const elapsedMs = 8_451;
console.log(compactDuration); // Outputs: "3h 25m"
console.log(`Synced ${prettyBytes(transferredBytes)} in ${prettyMs(elapsedMs)}`);
// Synced 48.2 MB in 8.5s
``` ```
### Conclusion ### Aligned Tables
Using `@push.rocks/smartformat`, you've seen how to format bytes and milliseconds into more readable strings. These examples just scratch the surface of what's possible. Both `prettyBytes` and `prettyMs` come with additional options and capabilities worth exploring. Remember, formatting data effectively can significantly improve the user experience of your applications. ```typescript
import { prettyBytes } from '@push.rocks/smartformat';
Note: The given examples use the ES Module (ESM) syntax and TypeScript, ensuring you're working with the latest standards for JavaScript development. const rows = [1_000, 10_000, 100_000].map((bytes) => prettyBytes(bytes, { fixedWidth: 8 }));
// [' 1 kB', ' 10 kB', ' 100 kB']
```
### Human-Friendly Timers
```typescript
import { prettyMs } from '@push.rocks/smartformat';
const startedAt = Date.now();
// later...
prettyMs(Date.now() - startedAt, { compact: true });
// e.g. '3s'
```
## API
```typescript
export { prettyBytes, prettyMs };
```
The exported functions are direct re-exports from `pretty-bytes` and `pretty-ms`, so their option objects and runtime behavior match those upstream packages.
## Development
```bash
pnpm install
pnpm test
pnpm run build
```
The test suite imports the TypeScript sources directly and verifies the package in the configured `@git.zone/tstest` environment.
## License and Legal Information ## License and Legal Information
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
### Trademarks ### Trademarks
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH. This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
### Company Information ### Company Information
Task Venture Capital GmbH Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc. For any legal inquiries or further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works. By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
test/test.node+chromium.ts
+12
View File
@@ -0,0 +1,12 @@
import { expect, tap } from '@git.zone/tstest/tapbundle';
import * as smartformat from '../ts/index.js';
tap.test('should format bytes', async () => {
expect(smartformat.prettyBytes(1337)).toEqual('1.34 kB');
});
tap.test('should format milliseconds', async () => {
expect(smartformat.prettyMs(1337)).toEqual('1.3s');
});
export default tap.start();
test/test.ts
-8
View File
@@ -1,8 +0,0 @@
import { expect, expectAsync, tap } from '@push.rocks/tapbundle';
import * as smartformat from '../ts/index.js'
tap.test('first test', async () => {
console.log(smartformat)
})
tap.start()
ts/00_commitinfo_data.ts
+2 -2
View File
@@ -1,8 +1,8 @@
/** /**
* autocreated commitinfo by @pushrocks/commitinfo * autocreated commitinfo by @push.rocks/commitinfo
*/ */
export const commitinfo = { export const commitinfo = {
name: '@push.rocks/smartformat', name: '@push.rocks/smartformat',
version: '1.0.3', version: '1.1.0',
description: 'A module that formats bytes and milliseconds into human-readable strings.' description: 'A module that formats bytes and milliseconds into human-readable strings.'
} }
ts/index.ts
+1 -1
View File
@@ -6,4 +6,4 @@ import {
export { export {
prettyBytes, prettyBytes,
prettyMs, prettyMs,
} };
ts/smartformat.plugins.ts
+2 -2
View File
@@ -3,6 +3,6 @@ import prettyBytes from 'pretty-bytes';
import prettyMs from 'pretty-ms'; import prettyMs from 'pretty-ms';
export { export {
prettyBytes, prettyBytes,
prettyMs prettyMs,
}; };
tsconfig.json
+3 -1
View File
@@ -5,8 +5,10 @@
"target": "ES2022", "target": "ES2022",
"module": "NodeNext", "module": "NodeNext",
"moduleResolution": "NodeNext", "moduleResolution": "NodeNext",
"noImplicitAny": true,
"esModuleInterop": true, "esModuleInterop": true,
"verbatimModuleSyntax": true "verbatimModuleSyntax": true,
"types": ["node"]
}, },
"exclude": [ "exclude": [
"dist_*/**/*.d.ts" "dist_*/**/*.d.ts"