Ginti

Ginti – smart number & unit formatter in plain JavaScript.

• Works in Node.js, modern browsers, and via CDN
• ESM + CJS + UMD (global Ginti)
• i18n via Intl for numbers, currency, and percentages
• SI units & bytes (decimal or binary/IEC)
• Human durations (milliseconds → human-readable text)
• Tiny, dependency-free, and tree-shakeable

📦 Installation

Using npm

npm install ginti

Using yarn

yarn add ginti

Using pnpm

pnpm add ginti

🌐 Browser usage

CDN: UMD (global Ginti)

<script src="https://unpkg.com/[email protected]/dist/index.umd.js"></script>
<script>
  console.log(Ginti.format(15300, { notation: "compact" })); // "15.3K"
</script>

CDN: ESM

<script type="module">
  import { format } from "https://unpkg.com/[email protected]/dist/index.mjs";
  console.log(format(0.237, { style: "percent", maxFractionDigits: 1 })); // "23.7%"
</script>

🖥 Node.js & bundlers

ESM

import Ginti, { format } from "ginti";

console.log(format(15300, { notation: "compact" })); // "15.3K"
console.log(Ginti.bytes(1_048_576, { base: 2 }));    // "1 MiB"

CommonJS

const Ginti = require("ginti");

console.log(Ginti.currency(1234.56, { currency: "EUR", locale: "de" })); // "1.234,56 €"
console.log(Ginti.si(12_300, "W"));                                      // "12.3 kW"

🚀 Quick Examples

import { format } from "ginti";

// 1) Numbers
format(15300, { notation: "compact" });             // "15.3K"
format(1234.567, { maxFractionDigits: 1 });         // "1,234.6" (locale-aware)

// 2) Currency
format(1234.56, { style: "currency", currency: "EUR", locale: "de" }); // "1.234,56 €"

// 3) Percent
format(0.237, { style: "percent", maxFractionDigits: 1 }); // "23.7%"

// 4) SI units
format(12_300, { style: "si", unit: "W" });         // "12.3 kW"
format(0.0012, { style: "si", unit: "m" });         // "1.2 mm"

// 5) Bytes (decimal or binary)
format(1_000_000, { style: "bytes", base: 10 });    // "1 MB"
format(1_048_576, { style: "bytes", base: 2 });     // "1 MiB"
format(1536, { style: "bytes", base: 2, iec: true, decimals: 0 }); // "2 KiB"

// 6) Duration (milliseconds → words)
format(90_061, { style: "duration" });              // "1 minute 30 seconds"
format(86_400_000, { style: "duration" });          // "1 day"

📜 API Reference

format(value, options?, durationOptions?)

Main formatting function.

Common options

• style: "number" | "si" | "bytes" | "currency" | "percent" | "duration" (default "number")
• locale: BCP-47 locale (e.g., "en", "de")
• notation: "standard" | "compact" (default "standard")
• decimals: fixed fraction digits (overrides minFractionDigits / maxFractionDigits)
• minFractionDigits, maxFractionDigits: set decimal places range
• signDisplay: "auto" | "never" | "always" | "exceptZero"

Currency-specific

• currency: e.g., "USD", "EUR"

SI-specific

• unit: e.g., "W", "m", "g"
• base: 10 | 2 (default 10)

Bytes-specific

• base: 10 | 2 (default 2 for bytes)
• iec: true | false (default true – use KiB/MiB symbols)

Duration-specific (durationOptions)

• maxUnits: number of units to display (default 2)
• smallestUnit: "ms" | "s" (default "ms")

Named Helpers

Instead of passing style each time, you can call:

Ginti.number(value, opts?)
Ginti.currency(value, { currency, ...opts })
Ginti.percent(value, opts?)
Ginti.si(value, unit?, opts?)
Ginti.bytes(value, opts?)
Ginti.duration(milliseconds, durationOpts?, baseOpts?)

🛠 Development

# install dependencies
npm install

# build (outputs dist: ESM, CJS, UMD)
npm run build

# run tests once
npm test

# run tests in watch mode
npm run test:watch

📄 License

MIT