Getting started · Formatting · Parsing · Diagnostics · Custom codecs · Bundle size
These measurements estimate the JavaScript added to a project after bundling, tree shaking, and minification of @neutrium/formatter and its runtime dependencies.
Use the first two size columns if your application does not already bundle @neutrium/decimal. If it already uses the full Decimal constructor from @neutrium/decimal, use the last two columns to estimate the additional cost of formatter. Adding both default formatting and parsing shares their common implementation; do not add the separate rows together.
“Already bundled” means the same Decimal dependency is retained in the application's bundle and can be shared with formatter. Merely listing Decimal in package.json does not provide that saving; duplicate dependency versions or separate bundles may also prevent sharing. The incremental columns compare a Decimal-only bundle with that same bundle plus formatter, including their other required runtime dependencies.
Measured for @neutrium/formatter 1.0.2, with @neutrium/decimal 2.3.0, @neutrium/utilities 4.0.0 and Rolldown 1.2.7. Sizes are KiB (1 KiB = 1,024 bytes).
| Functionality included | Minified, including Decimal | Gzipped, including Decimal | Added minified, Decimal already bundled | Added gzipped, Decimal already bundled |
|---|---|---|---|---|
| Default formatter (all built-ins) | 80.55 KiB | 26.70 KiB | 48.06 KiB | 15.04 KiB |
| Default parser (all built-ins) | 78.13 KiB | 26.24 KiB | 45.63 KiB | 14.68 KiB |
| Default formatting + parsing | 89.83 KiB | 29.65 KiB | 57.34 KiB | 17.99 KiB |
| Only number formatting | 69.30 KiB | 23.40 KiB | 36.80 KiB | 11.74 KiB |
| Only currency formatting | 69.30 KiB | 23.40 KiB | 36.80 KiB | 11.74 KiB |
| Only unit formatting | 69.30 KiB | 23.40 KiB | 36.80 KiB | 11.74 KiB |
| Only bytes formatting | 59.51 KiB | 20.29 KiB | 27.01 KiB | 8.67 KiB |
| Only percentage formatting | 58.60 KiB | 19.91 KiB | 26.09 KiB | 8.29 KiB |
| Only ordinal formatting | 59.93 KiB | 20.40 KiB | 27.42 KiB | 8.77 KiB |
| Only duration formatting | 51.48 KiB | 17.83 KiB | 18.97 KiB | 6.26 KiB |
| Only number parsing | 70.14 KiB | 23.67 KiB | 37.63 KiB | 12.10 KiB |
| Only bytes parsing | 59.10 KiB | 20.21 KiB | 26.59 KiB | 8.64 KiB |
| Only elapsed-duration parsing | 44.07 KiB | 15.48 KiB | 11.54 KiB | 3.99 KiB |
The "already bundled" columns above use the full Decimal constructor from @neutrium/decimal. Its baseline is 48.01 KiB minified / 17.69 KiB gzipped.
This table shows the cost of adding the default formatter to each existing Decimal tier. All scenario/tier combinations, exact byte counts, combined totals, and entry sources are also recorded in dist/bundle-sizes.json.
| Existing Decimal import | Existing minified | Existing gzipped | Formatter adds, minified | Formatter adds, gzipped |
|---|---|---|---|---|
@neutrium/decimal |
48.01 KiB | 17.69 KiB | 48.06 KiB | 15.04 KiB |
@neutrium/decimal/core |
16.89 KiB | 6.28 KiB | 63.65 KiB | 20.47 KiB |
@neutrium/decimal/arithmetic |
32.52 KiB | 11.78 KiB | 48.03 KiB | 14.87 KiB |
@neutrium/decimal/scientific |
48.01 KiB | 17.69 KiB | 48.06 KiB | 15.04 KiB |
The default formatter and parser include all their built-in domains. Using only { kind: "bytes" } with the default formatter does not remove the other registered codecs. For a smaller bundle, construct a registry with only the codecs you need:
import { Formatter, bytesCodec } from "@neutrium/formatter/extensions";
const sizes = new Formatter({ codecs: [bytesCodec] });
sizes.format(1536, { kind: "bytes" }); // "1.5 KiB"
Use selective imports from /extensions and /extensions/parse when you need only a few domains.
Parsing is optional. If your project only displays values, omit the parsing import. To accept only byte-size input:
import { Parser, bytesParser } from "@neutrium/formatter/extensions/parse";
const input = new Parser({ codecs: [bytesParser] });
input.parse("1.5 KiB", { kind: "bytes" }); // "1536"
Number, currency, and unit codecs share an implementation, including compact notation. Their individual sizes are therefore similar. Selective bytes, percentage, and ordinal codecs remove that native-domain implementation and its compact locale data. The duration formatter includes both elapsed and localized presentations; the duration parser includes elapsed parsing only. The table measures retained codec functionality, not a promise that a single method or specification can be isolated further.
These are runtime imports. Type-only imports add no JavaScript. Import runtimeCapabilities() from /diagnostics only if you need its full feature report; it is not included in these formatting/parsing scenarios.
dist/bundle-sizes.json contains exact byte counts, the tested entry sources, dependency/bundler versions, and combined totals.Treat these as comparable reference fixtures, not an exact prediction for an existing application. Its other imports, bundler, compression settings, shared chunks, and dependency versions affect the final output. Gzip deltas also reflect compression shared with the baseline and are not the size of a separately downloadable formatter file.
For library maintainers, the normal build refreshes the marked section above while preserving the hand-written explanations:
pnpm run build # Compile, measure, update this guide and dist/bundle-sizes.json
pnpm run sizes:built # Refresh from an already current dist build
pnpm run sizes:check # Re-measure without writing; fail if the guide or JSON is stale
After a source or dependency change, run the build and commit the generated guide with the change so the repository and GitHub Pages show the same measurements. dist/ is generated and ignored. Publication runs this build automatically; see maintaining bundle-size documentation for release integration.