@peter-present/format-number 0.0.1

package/README.md

@@ -0,0 +1,116 @@
+# format-number
+
+A lightweight, high-precision JavaScript/TypeScript library for rounding and formatting numbers. It handles everything from large financial figures and crypto balances to extremely small fractions with scientific subscripts.
+
+Designed for precision-critical applications where numbers often exceed safe integer limits.
+
+For detailed documentation and advanced usage, visit: [here](https://blog.peter-present.xyz/format-number)
+
+## Key Features
+
+- **High Precision**: Native support for `string`, `number`, and `bigint` without loss of precision.
+- **Multiple Rounding Modes**: 5 different strategies to handle rounding exactly how you need.
+- **Compact Formatting**: Automatically shorten large numbers with suffixes (K, M, B, T, Q).
+- **Small Number Notation**: Smart formatting for tiny numbers using subscript zeros (e.g., `0.0₃5`).
+- **Flexible Metadata**: Easily add prefixes and suffixes (e.g., Currency symbols, Units).
+- **Fluent API**: Chained operations for cleaner, more readable code.
+- **Zero Dependencies**: Keeps your bundle size minimal.
+
+## Installation
+
+```shell
+# npm
+npm install format-number
+
+# yarn
+yarn add format-number
+
+# bun
+bun install format-number
+```
+
+## Core Functions
+
+### Rounding: `round()`
+
+Round numbers using specific strategies and precision.
+
+```typescript
+import { round } from 'format-number';
+
+round(123.456, { precision: 2 }); // '123.46'
+round(-123.45, { mode: 'up', precision: 1 }); // '-123.4' (Towards +Infinity)
+```
+
+### Compact Formatting: `compact()`
+
+Format large numbers with readable suffixes.
+
+```typescript
+import { compact } from 'format-number';
+
+compact(1500); // '1.5K'
+compact(1200000, { precision: 1 }); // '1.2M'
+compact('1000000000000'); // '1T'
+```
+
+### Advanced Formatting: `formatNumber()`
+
+A comprehensive function combining rounding, compacting, and metadata.
+
+```typescript
+import { formatNumber } from 'format-number';
+
+// Currency formatting
+formatNumber(1234.56, { prefix: '$', precision: 1 }); // '$1234.6'
+
+// Compact with metadata
+formatNumber(1500000, { isCompact: true, suffix: ' units' }); // '1.5M units'
+
+// Small number subscript notation
+formatNumber(0.00005, { isSmall: true }); // '0.0₄5'
+```
+
+### Fluent / Chained API: `FN()`
+
+Perform multiple operations in a readable chain.
+
+```typescript
+import { FN } from 'format-number';
+
+const result = FN('1234567.89')
+  .round({ precision: 0 })
+  .format({ prefix: 'Total: ', suffix: ' tokens' });
+
+console.log(result); // 'Total: 1234568 tokens'
+
+// Compact chaining
+FN(1000000).compact({ precision: 0 }); // '1M'
+```
+
+## API Reference
+
+### Rounding Modes (`RoundingMode`)
+
+| Mode       | Description                                                          |
+| :--------- | :------------------------------------------------------------------- |
+| `half`     | Round to the nearest neighbor. If equidistant, round away from zero. |
+| `up`       | Round towards Positive Infinity.                                     |
+| `down`     | Round towards Negative Infinity.                                     |
+| `truncate` | Round towards Zero.                                                  |
+| `banker`   | Round to the nearest even neighbor (Statistical rounding).           |
+
+### Configuration Options
+
+| Option      | Type           | Description                                      |
+| :---------- | :------------- | :----------------------------------------------- |
+| `precision` | `number`       | Number of decimal places (default: `0`).         |
+| `mode`      | `RoundingMode` | Rounding strategy (default: `'half'`).           |
+| `prefix`    | `string`       | Text to prepend to the result.                   |
+| `suffix`    | `string`       | Text to append to the result.                    |
+| `isCompact` | `boolean`      | If `true`, uses K/M/B/T suffixes.                |
+| `isSmall`   | `boolean`      | If `true`, formats tiny numbers with subscripts. |
+
+## License
+
+ISC

package/dist/compact.d.ts

@@ -0,0 +1,2 @@
+import { RoundingConfigType, NumberType } from './types';
+export declare function compact(value: NumberType, options?: RoundingConfigType): string;

package/dist/format.d.ts

@@ -0,0 +1,8 @@
+import { MetadataType, NumberType, OtherMetadataType, RoundingConfigType } from './types';
+export declare function formatNumber(value: NumberType, options?: MetadataType): string;
+export declare function FN(value: NumberType): {
+    round(options?: RoundingConfigType): any;
+    compact(options?: RoundingConfigType): string;
+    format(options?: OtherMetadataType): string;
+    toString(): string;
+};

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function f(s){const r=s.startsWith("-")?"-":"",t=r?s.slice(1):s;let e=0,n=t.length-1;for(;t[e]=="0"&&e<t.length;)e++;if(s.indexOf(".")>=0)for(;t[n]=="0"&&n>=0;)n--;const u=t.slice(e,n+1);return u==""||u=="."?"0":r+u}function g(s){let r=f(s);r=(r.startsWith("-")?"-":"")?r.slice(1):r;const[e,n=""]=r.split("."),i=n.match(/^0+/)?.[0]?.length||0,u=i.toString().split("").map(o=>String.fromCharCode(8320+parseInt(o))).join(""),c=n.slice(i);return`${e}.0${u}${c}`}function l(s){let r="",t=s.length-1,e="1";for(;t>=0;){const n=s[t];let i=Number(n)+(e?1:0);i>=10?(e="1",i-=10):e="",r=i.toString()+r,t--}return{result:e+r,remaining:e}}function S(s,r=0){const[t,e=""]=s.split(".");if(r===0)return e&&Number(e[0])>=5?l(t).result:t;if(r>=e.length)return t+(e?`.${e}`:"");const n=e.slice(0,r),i=e.slice(r);if(Number(i[0])>=5){const u=l(n);return u.remaining?l(t).result:t+"."+u.result}else return t+"."+n}function d(s,r=0){const[t,e=""]=s.split(".");if(r===0)return e?l(t).result:t;if(r>=e.length)return t+"."+e;const n=l(e.slice(0,r));return n.remaining?l(t).result:t+"."+n.result}function m(s,r=0){const[t,e=""]=s.split(".");if(r===0)return t;let n=e.slice(0,r),i=n.length-1;for(;i>=0&&n[i]=="0";)i--;return n=n.slice(0,i+1),t+(n?`.${n}`:"")}function $(s,r=0){const[t,e=""]=s.split(".");if(r===0)return e&&Number(e[0])>=5?Number(t[0])/2==0?t:l(t).result:t;if(r>=e.length)return t+(e?`.${e}`:"");const n=e.slice(0,r),i=e.slice(r);if(i[0]=="5"){if(Number(n[n.length-1])%2==0)return t+"."+n;{const u=l(n);return u.remaining?l(t).result:t+"."+u.result}}else if(Number(i[0])>5){const u=l(n);return u.remaining?l(t).result:t+"."+u.result}else return t+"."+n}function a(s,r={}){const t=r.mode||"half",e=r.precision||0;let n=f(String(s)),i="";switch(n.startsWith("-")&&(n=n.slice(1),i="-"),t){case"half":return i+S(n,e);case"up":return i==""?d(n,e):"-"+m(n,e);case"down":return i==""?m(n,e):"-"+d(n,e);case"truncate":return i+m(n,e);case"banker":return i+$(n,e)}}const b=["K","M","B","T","Q"];function P(s,r={}){let t=f(String(s)),e="";t.startsWith("-")&&(t=t.slice(1),e="-");let[n,i=""]=t.split("."),u=n.length,c=-1;for(;u>3&&c<4;){const o=n.slice(0,u-3);i=n.slice(u-3)+i,n=o,u-=3,c++}return a(`${e}${n}.${i}`,r)+(c>=0?b[c]:"")}function N(s,r){let t=String(s);r.isCompact==!0?t=P(t,r):r.isSmall||(t=a(t,r));const e=r.prefix||"",n=r.suffix||"",i=r.isSmall||!1;return`${e}${i?g(t):t}${n}`}function h(s){return{round(r={}){return h(a(s,r))},compact(r={}){return P(s,r)},format(r={}){const t=r.prefix||"",e=r.suffix||"",n=r.isSmall||!1;return`${t}${n?g(String(s)):s}${e}`},toString(){return String(s)}}}exports.FN=h;exports.compact=P;exports.formatNumber=N;exports.formatSmallNum=g;exports.removeZero=f;exports.round=a;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './utils';
+export { compact } from './compact';
+export { FN, formatNumber } from './format';
+export { round } from './round';

package/dist/index.js

@@ -0,0 +1,125 @@
+function o(s) {
+  const r = s.startsWith("-") ? "-" : "", t = r ? s.slice(1) : s;
+  let e = 0, n = t.length - 1;
+  for (; t[e] == "0" && e < t.length; ) e++;
+  if (s.indexOf(".") >= 0) for (; t[n] == "0" && n >= 0; ) n--;
+  const l = t.slice(e, n + 1);
+  return l == "" || l == "." ? "0" : r + l;
+}
+function P(s) {
+  let r = o(s);
+  r = (r.startsWith("-") ? "-" : "") ? r.slice(1) : r;
+  const [e, n = ""] = r.split("."), i = n.match(/^0+/)?.[0]?.length || 0, l = i.toString().split("").map((f) => String.fromCharCode(8320 + parseInt(f))).join(""), c = n.slice(i);
+  return `${e}.0${l}${c}`;
+}
+function u(s) {
+  let r = "", t = s.length - 1, e = "1";
+  for (; t >= 0; ) {
+    const n = s[t];
+    let i = Number(n) + (e ? 1 : 0);
+    i >= 10 ? (e = "1", i -= 10) : e = "", r = i.toString() + r, t--;
+  }
+  return { result: e + r, remaining: e };
+}
+function d(s, r = 0) {
+  const [t, e = ""] = s.split(".");
+  if (r === 0)
+    return e && Number(e[0]) >= 5 ? u(t).result : t;
+  if (r >= e.length) return t + (e ? `.${e}` : "");
+  const n = e.slice(0, r), i = e.slice(r);
+  if (Number(i[0]) >= 5) {
+    const l = u(n);
+    return l.remaining ? u(t).result : t + "." + l.result;
+  } else return t + "." + n;
+}
+function g(s, r = 0) {
+  const [t, e = ""] = s.split(".");
+  if (r === 0)
+    return e ? u(t).result : t;
+  if (r >= e.length) return t + "." + e;
+  const n = u(e.slice(0, r));
+  return n.remaining ? u(t).result : t + "." + n.result;
+}
+function a(s, r = 0) {
+  const [t, e = ""] = s.split(".");
+  if (r === 0) return t;
+  let n = e.slice(0, r), i = n.length - 1;
+  for (; i >= 0 && n[i] == "0"; ) i--;
+  return n = n.slice(0, i + 1), t + (n ? `.${n}` : "");
+}
+function S(s, r = 0) {
+  const [t, e = ""] = s.split(".");
+  if (r === 0)
+    return e && Number(e[0]) >= 5 ? Number(t[0]) / 2 == 0 ? t : u(t).result : t;
+  if (r >= e.length) return t + (e ? `.${e}` : "");
+  const n = e.slice(0, r), i = e.slice(r);
+  if (i[0] == "5") {
+    if (Number(n[n.length - 1]) % 2 == 0)
+      return t + "." + n;
+    {
+      const l = u(n);
+      return l.remaining ? u(t).result : t + "." + l.result;
+    }
+  } else if (Number(i[0]) > 5) {
+    const l = u(n);
+    return l.remaining ? u(t).result : t + "." + l.result;
+  } else return t + "." + n;
+}
+function m(s, r = {}) {
+  const t = r.mode || "half", e = r.precision || 0;
+  let n = o(String(s)), i = "";
+  switch (n.startsWith("-") && (n = n.slice(1), i = "-"), t) {
+    case "half":
+      return i + d(n, e);
+    case "up":
+      return i == "" ? g(n, e) : "-" + a(n, e);
+    case "down":
+      return i == "" ? a(n, e) : "-" + g(n, e);
+    case "truncate":
+      return i + a(n, e);
+    case "banker":
+      return i + S(n, e);
+  }
+}
+const $ = ["K", "M", "B", "T", "Q"];
+function h(s, r = {}) {
+  let t = o(String(s)), e = "";
+  t.startsWith("-") && (t = t.slice(1), e = "-");
+  let [n, i = ""] = t.split("."), l = n.length, c = -1;
+  for (; l > 3 && c < 4; ) {
+    const f = n.slice(0, l - 3);
+    i = n.slice(l - 3) + i, n = f, l -= 3, c++;
+  }
+  return m(`${e}${n}.${i}`, r) + (c >= 0 ? $[c] : "");
+}
+function b(s, r) {
+  let t = String(s);
+  r.isCompact == !0 ? t = h(t, r) : r.isSmall || (t = m(t, r));
+  const e = r.prefix || "", n = r.suffix || "", i = r.isSmall || !1;
+  return `${e}${i ? P(t) : t}${n}`;
+}
+function x(s) {
+  return {
+    round(r = {}) {
+      return x(m(s, r));
+    },
+    compact(r = {}) {
+      return h(s, r);
+    },
+    format(r = {}) {
+      const t = r.prefix || "", e = r.suffix || "", n = r.isSmall || !1;
+      return `${t}${n ? P(String(s)) : s}${e}`;
+    },
+    toString() {
+      return String(s);
+    }
+  };
+}
+export {
+  x as FN,
+  h as compact,
+  b as formatNumber,
+  P as formatSmallNum,
+  o as removeZero,
+  m as round
+};

package/dist/round.d.ts

@@ -0,0 +1,3 @@
+import { NumberType, RoundingConfigType } from './types';
+export declare function roundPositiveHalf(value: string, precision?: number): string;
+export declare function round(value: NumberType, options?: RoundingConfigType): string;

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+export type NumberType = number | string | bigint;
+export type RoundingMode = 'half' | 'up' | 'down' | 'banker' | 'truncate';
+export type RoundingConfigType = Partial<{
+    mode: RoundingMode;
+    precision: number;
+}>;
+export type OtherMetadataType = Partial<{
+    prefix: string;
+    suffix: string;
+    isSmall: boolean;
+}>;
+export type MetadataType = RoundingConfigType & OtherMetadataType & Partial<{
+    isCompact: boolean;
+}>;

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function removeZero(value: string): string;
+export declare function formatSmallNum(value: string): string;

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@peter-present/format-number",
+  "version": "0.0.1",
+  "description": "Utility library for number formatting, rounding, and compact display.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run clear && tsc && vite build",
+    "preview": "vite preview",
+    "clear": "rm -rf dist",
+    "test": "vitest run",
+    "prepare": "bun run build",
+    "eslint": "eslint --config ./eslint.config.js --cache",
+    "format": "prettier --write .",
+    "prepublishOnly": "bun run clear && bun run build && bun run test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phamhongphuc1999/format-number.git"
+  },
+  "keywords": [
+  "number",
+  "format",
+  "number-format",
+  "compact"
+],
+  "author": "phamhongphuc1999",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/phamhongphuc1999/format-number/issues"
+  },
+  "homepage": "https://github.com/phamhongphuc1999/format-number#readme",
+  "devDependencies": {
+    "@eslint/js": "^9.29.0",
+    "@types/node": "^20.12.2",
+    "eslint": "^9.29.0",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.1",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "path": "^0.12.7",
+    "tslib": "^2.6.2",
+    "typescript": "5.5.3",
+    "typescript-eslint": "^8.34.1",
+    "vite": "^7.2.7",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.15"
+  },
+  "contributors": [
+    {
+      "name": "Phạm Hồng Phúc",
+      "email": "phamhongphuc12atm1@gmail.com",
+      "url": "https://github.com/phamhongphuc1999"
+    }
+  ],
+  "engines": {
+    "node": ">=16",
+    "npm": ">=7"
+  }
+}