@peter-present/format-number 0.0.1 → 0.0.11

package/README.md

@@ -1,115 +1,105 @@
 # 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.
+A lightweight, zero-dependency JavaScript/TypeScript library for precise number formatting. Designed for financial applications, crypto dashboards, and scientific data where precision is paramount.
 
-Designed for precision-critical applications where numbers often exceed safe integer limits.
+Unlike standard libraries that rely on floating-point math, **format-number** uses internal string-based arithmetic to handle numbers of any size (including `string`, `number`, and `bigint`) without losing a single decimal point.
 
-For detailed documentation and advanced usage, visit: [here](https://blog.peter-present.xyz/format-number)
+For detailed documentation, 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.
+- **Zero Precision Loss**: Uses string manipulation for rounding and formatting to avoid binary floating-point errors.
+- **Robust Input Parsing**: Handles messy strings with currency symbols ($€£¥), commas, underscores, and scientific notation automatically.
+- **Advanced Rounding**: 5 strategies (`half`, `up`, `down`, `banker`, `truncate`) with customizable decimal precision.
+- **Intelligent Notation**: Format small numbers with subscript zeros (e.g., `0.0₃5`) or standard scientific notation.
+- **Flexible Compacting**: Shorten massive numbers into readable strings like `1.5T` or `20.4B`.
+- **Fluent Chainable API**: Build complex formatting logic with a clean, readable syntax.
 
 ## Installation
 
 ```shell
 # npm
-npm install format-number
+npm install @peter-present/format-number
 
 # yarn
-yarn add format-number
+yarn add @peter-present/format-number
 
 # bun
-bun install format-number
+bun install @peter-present/format-number
 ```
 
-## Core Functions
+## Core API
 
-### Rounding: `round()`
+### `formatNumber(value, options)`
 
-Round numbers using specific strategies and precision.
+The primary entry point for one-off formatting. It combines parsing, rounding, and visualization.
 
 ```typescript
-import { round } from 'format-number';
+import { formatNumber } from '@peter-present/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.
+// Currency & Rounding
+formatNumber('$1,234.567', { prefix: '€', precision: 2 }); // '€1234.57'
 
-```typescript
-import { compact } from 'format-number';
+// Compact Notation
+formatNumber(1500000000, { isCompact: true }); // '1.5B'
 
-compact(1500); // '1.5K'
-compact(1200000, { precision: 1 }); // '1.2M'
-compact('1000000000000'); // '1T'
+// Special Notations
+formatNumber(0.00005, { notation: 'subscript' }); // '0.0₄5'
+formatNumber(12345, { notation: 'scientific' }); // '1.2345e+4'
 ```
 
-### Advanced Formatting: `formatNumber()`
+### `FN(value)` - Fluent API
 
-A comprehensive function combining rounding, compacting, and metadata.
+Best for complex, multi-step formatting requirements where readability is key.
 
 ```typescript
-import { formatNumber } from 'format-number';
+import { FN } from '@peter-present/format-number';
 
-// Currency formatting
-formatNumber(1234.56, { prefix: '$', precision: 1 }); // '$1234.6'
+const formatted = FN('1234567.89')
+  .round({ precision: 0, rounding: 'banker' })
+  .prefix('Balance: ')
+  .suffix(' USD')
+  .toNumber();
 
-// Compact with metadata
-formatNumber(1500000, { isCompact: true, suffix: ' units' }); // '1.5M units'
+console.log(formatted); // 'Balance: 1234568 USD'
 
-// Small number subscript notation
-formatNumber(0.00005, { isSmall: true }); // '0.0₄5'
+// Seamlessly combine with compact and notation
+FN(1500).compact({ precision: 1 }).prefix('$').toNumber(); // '$1.5K'
 ```
 
-### Fluent / Chained API: `FN()`
+### `round(value, options)`
 
-Perform multiple operations in a readable chain.
+Independent rounding utility with high-precision string logic.
 
 ```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'
+import { round } from '@peter-present/format-number';
 
-// Compact chaining
-FN(1000000).compact({ precision: 0 }); // '1M'
+round(1.235, { precision: 2, rounding: 'half' }); // '1.24'
+round(1.235, { precision: 2, rounding: 'down' }); // '1.23'
 ```
 
-## API Reference
+## Configuration Reference
 
-### Rounding Modes (`RoundingMode`)
+### `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).           |
+| Mode       | Description                                                            |
+| :--------- | :--------------------------------------------------------------------- |
+| `half`     | Rounds to the nearest neighbor (rounds away from zero if equidistant). |
+| `up`       | Rounds towards Positive Infinity.                                      |
+| `down`     | Rounds towards Negative Infinity.                                      |
+| `truncate` | Rounds towards Zero (trims decimals).                                  |
+| `banker`   | Rounds to the nearest even neighbor (minimizes statistical bias).      |
 
-### Configuration Options
+### `FormattingConfigType`
 
-| 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. |
+| Property    | Type                          | Default     | Description                                        |
+| :---------- | :---------------------------- | :---------- | :------------------------------------------------- |
+| `precision` | `number`                      | `0`         | Number of decimal places to maintain.              |
+| `rounding`  | `RoundingMode`                | `'half'`    | Strategy used for rounding.                        |
+| `prefix`    | `string`                      | `""`        | Text prepended to the result.                      |
+| `suffix`    | `string`                      | `""`        | Text appended to the result.                       |
+| `isCompact` | `boolean`                     | `false`     | Whether to use K/M/B/T suffixes for large numbers. |
+| `notation`  | `'subscript' \| 'scientific'` | `undefined` | Special formatting for extreme values.             |
 
 ## License
 

package/dist/compact.d.ts

@@ -1,2 +1,20 @@
-import { RoundingConfigType, NumberType } from './types';
+import { NumberType, RoundingConfigType } from './types';
+export declare function _compact(value: NumberType, options?: RoundingConfigType): {
+    value: string;
+    symbol: string;
+};
+/**
+ * Formats a number into a short, human-readable string with a suffix (e.g., K, M, B).
+ *
+ * @param value - The value to be compacted. Can be a number, string, or bigint.
+ * @param options - Configuration for rounding the compacted value.
+ * @param options.rounding - The rounding strategy to use. Default is 'half'.
+ * @param options.precision - The number of decimal places to include after compacting. Default is 0.
+ * @returns The compacted number with a suffix as a string.
+ *
+ * @example
+ * compact(1500); // '1.5K'
+ * compact(1200000, { precision: 1 }); // '1.2M'
+ * compact('1000000000000'); // '1T'
+ */
 export declare function compact(value: NumberType, options?: RoundingConfigType): string;

package/dist/format.d.ts

@@ -1,8 +1,37 @@
-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;
+import { FormattingConfigType, NotationMode, NumberType, ObjectNumberType, RoundingConfigType } from './types';
+/**
+ * Fluent API for performing multiple formatting operations in a readable chain.
+ * Wraps the input value into a formatter object that supports rounding,
+ * compacting, and metadata addition.
+ *
+ * @param value - The initial value to format.
+ * @returns A chainable formatter object.
+ *
+ * @example
+ * FN('1234567.89')
+ *   .round({ precision: 0 })
+ *   .prefix('$')
+ *   .toNumber(); // '$1234568'
+ */
+export declare function FN(value: NumberType | ObjectNumberType): {
+    round: (options?: RoundingConfigType) => any;
+    compact: (options?: RoundingConfigType) => any;
+    notation(mode?: NotationMode): any;
+    prefix(symbol: string): any;
+    suffix(symbol: string): any;
+    toNumber(): string;
+    toObject(): ObjectNumberType;
 };
+/**
+ * Comprehensive formatting function that combines rounding, compacting, and metadata.
+ * This is the quickest way to format a number with multiple options.
+ *
+ * @param value - The value to format.
+ * @param options - Formatting configuration (precision, rounding, isCompact, prefix, suffix, notation).
+ * @returns The formatted number string.
+ *
+ * @example
+ * formatNumber(1234.56, { prefix: '$', precision: 1 }); // '$1234.6'
+ * formatNumber(1500000, { isCompact: true }); // '1.5M'
+ */
+export declare function formatNumber(value: NumberType, options?: FormattingConfigType): string;

package/dist/index.cjs

@@ -1 +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;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function $(n){return n.replace(/^(-?)0+(?=\d)/,"$1").replace(/(\.\d*?)0+$/,"$1").replace(/\.$/,"")}function d(n){let t=String(n);t=t.trim();let e="";return t.startsWith("-")&&(t=t.slice(1),e="-"),{sign:e,value:$(t)}}const Z={K:3,M:6,B:9,T:12,Q:15};function E(n){if(typeof n=="number"||typeof n=="bigint")return n.toString();const t=String(n??"").trim();if(t==="")return"0";const e=t.match(/^[\s+-]*/),i=((e?e[0]:"").match(/-/g)||[]).length%2===1,s=t.replace(/[$€£¥,_\s]/g,""),c=/^([+-]?\d+)\.0([\u2080-\u2089]+)([0-9]*)$/i,u=s.match(c);if(u){const m=u[1].replace(/^[+-]/,""),j=u[2],D=u[3],R=j.split("").reduce((K,O)=>{const Q=O.charCodeAt(0)-8320;return K+Q},0),w="0".repeat(R)+D;let h=m;return(w!==""||R>0)&&(h+="."+w),h=$(h),(i?"-":"")+(h||"0")}const l=s.match(/[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?[KMBTQ]*/i);if(!l)return"0";let o=l[0].toUpperCase(),P=0;const S=o.match(/[KMBTQ]$/);S&&(P+=Z[S[0]]??0,o=o.slice(0,-1));const y=o.match(/[eE][+-]?\d+$/);if(y&&(P+=parseInt(y[0].slice(1),10),o=o.replace(/[eE][+-]?\d+$/i,"")),o=o.replace(/^[+-]/,""),!/^(?:\d+\.?\d*|\.\d+)$/.test(o))return"0";const[C="0",M=""]=o.split(".");let g=(C.replace(/^0+/,"")||"0")+M;const b=M.length-P;let p;if(b<=0)g+="0".repeat(-b),p=g.replace(/^0+(?=\d)/,"")||"0";else{const m=g.length-b;m<=0?p="0."+"0".repeat(-m)+g:p=g.slice(0,m)+"."+g.slice(m),p=$(p)}return(i?"-":"")+(p||"0")}function F(n){const t=typeof n;if(t=="string"||t=="bigint"||t=="number"){const{sign:e,value:r}=d(n);return{sign:e,value:r}}return n}function a(n){let t="",e=n.length-1,r="1";for(;e>=0;){const i=n[e];let s=Number(i)+(r?1:0);s>=10?(r="1",s-=10):r="",t=s.toString()+t,e--}return{result:r+t,remaining:r}}function I(n,t=0){const[e,r=""]=n.split(".");if(t===0)return r&&Number(r[0])>=5?a(e).result:e;if(t>=r.length)return e+(r?`.${r}`:"");const i=r.slice(0,t),s=r.slice(t);if(Number(s[0])>=5){const c=a(i);return c.remaining?a(e).result:e+"."+c.result}else return e+"."+i}function v(n,t=0){const[e,r=""]=n.split(".");if(t===0)return r?a(e).result:e;if(t>=r.length)return e+"."+r;const i=a(r.slice(0,t));return i.remaining?a(e).result:e+"."+i.result}function x(n,t=0){const[e,r=""]=n.split(".");if(t===0)return e;let i=r.slice(0,t),s=i.length-1;for(;s>=0&&i[s]=="0";)s--;return i=i.slice(0,s+1),e+(i?`.${i}`:"")}function k(n,t=0){const[e,r=""]=n.split(".");if(t===0)return r&&Number(r[0])>=5?Number(e[0])/2==0?e:a(e).result:e;if(t>=r.length)return e+(r?`.${r}`:"");const i=r.slice(0,t),s=r.slice(t);if(s[0]=="5"){if(Number(i[i.length-1])%2==0)return e+"."+i;{const c=a(i);return c.remaining?a(e).result:e+"."+c.result}}else if(Number(s[0])>5){const c=a(i);return c.remaining?a(e).result:e+"."+c.result}else return e+"."+i}function N(n,t={}){const e=t.rounding||"half",r=t.precision||0,{sign:i,value:s}=d(n);switch(e){case"half":return i+I(s,r);case"up":return i==""?v(s,r):"-"+x(s,r);case"down":return i==""?x(s,r):"-"+v(s,r);case"truncate":return i+x(s,r);case"banker":return i+k(s,r)}}const U=["K","M","B","T","Q"];function _(n,t={}){const{sign:e,value:r}=d(n);let[i,s=""]=r.split("."),c=i.length,u=-1;for(;c>3&&u<4;){const o=i.slice(0,c-3);s=i.slice(c-3)+s,i=o,c-=3,u++}const l=`${e}${i}${s.length>0?"."+s:s}`;return{value:t.precision!=null?N(l,t):l,symbol:u>=0?U[u]:""}}function V(n,t={}){const{value:e,symbol:r}=_(n,t);return e+r}function T(n){const{sign:t,value:e}=d(n),[r,i=""]=e.split("."),s=i.match(/^0+/)?.[0]?.length||0,c=s.toString().split("").map(l=>String.fromCharCode(8320+parseInt(l))).join(""),u=i.slice(s);return`${t}${r}.0${c}${u}`}function z(n){const{sign:t,value:e}=d(n);if(e=="0")return{value:"0",exponent:0};const[r,i=""]=e.split(".");if(r!=="0"){const l=r.length-1,o=r[0]+"."+(r.slice(1)+i).replace(/0+$/,"");return{value:`${t}${o}${o.length>1,""}`,exponent:l,sign:"+"}}const s=i.search(/[1-9]/);if(s===-1)return{value:"0",exponent:0};const c=-(s+1),u=i[s]+"."+i.slice(s+1).replace(/0+$/,"");return{value:`${t}${u}`,exponent:c-1,sign:""}}function B(n){const{value:t,exponent:e,sign:r}=z(n);return e!=0?`${t}e${r}${e}`:t}function f(n){return{round:t=>{const e=N(n.value,t);return f({...n,value:e})},compact:t=>{if(n.compactedSymbol)return f(n);const{value:e,symbol:r}=_(n.value,t);return f({...n,compactedSymbol:r,value:e})},notation(t="scientific"){return f({...n,notation:t})},prefix(t){return f({...n,prefix:t})},suffix(t){return f({...n,suffix:t})},toNumber(){let{value:t}=n;const{sign:e,prefix:r,suffix:i,compactedSymbol:s}=n;return n.notation=="scientific"?t=B(t):n.notation=="subscript"&&(t=T(t)),`${r||""}${e}${t}${s||""}${i||""}`},toObject(){return n}}}function A(n){return f(F(n))}exports.FN=A;exports.clearTrailingZero=$;exports.compact=V;exports.parseNum=E;exports.round=N;exports.scientific=B;exports.subscript=T;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types';
-export * from './utils';
 export { compact } from './compact';
-export { FN, formatNumber } from './format';
+export { FN } from './format';
+export { clearTrailingZero, parseNum } from './io';
+export { scientific, subscript } from './notation';
 export { round } from './round';

package/dist/index.js

@@ -1,125 +1,200 @@
-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--;
+function x(r) {
+  return r.replace(/^(-?)0+(?=\d)/, "$1").replace(/(\.\d*?)0+$/, "$1").replace(/\.$/, "");
+}
+function d(r) {
+  let t = String(r);
+  t = t.trim();
+  let e = "";
+  return t.startsWith("-") && (t = t.slice(1), e = "-"), { sign: e, value: x(t) };
+}
+const j = { K: 3, M: 6, B: 9, T: 12, Q: 15 };
+function z(r) {
+  if (typeof r == "number" || typeof r == "bigint")
+    return r.toString();
+  const t = String(r ?? "").trim();
+  if (t === "") return "0";
+  const e = t.match(/^[\s+-]*/), i = ((e ? e[0] : "").match(/-/g) || []).length % 2 === 1, s = t.replace(/[$€£¥,_\s]/g, ""), c = /^([+-]?\d+)\.0([\u2080-\u2089]+)([0-9]*)$/i, u = s.match(c);
+  if (u) {
+    const m = u[1].replace(/^[+-]/, ""), B = u[2], C = u[3], w = B.split("").reduce((D, K) => {
+      const Q = K.charCodeAt(0) - 8320;
+      return D + Q;
+    }, 0), y = "0".repeat(w) + C;
+    let h = m;
+    return (y !== "" || w > 0) && (h += "." + y), h = x(h), (i ? "-" : "") + (h || "0");
+  }
+  const l = s.match(/[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?[KMBTQ]*/i);
+  if (!l) return "0";
+  let o = l[0].toUpperCase(), $ = 0;
+  const N = o.match(/[KMBTQ]$/);
+  N && ($ += j[N[0]] ?? 0, o = o.slice(0, -1));
+  const S = o.match(/[eE][+-]?\d+$/);
+  if (S && ($ += parseInt(S[0].slice(1), 10), o = o.replace(/[eE][+-]?\d+$/i, "")), o = o.replace(/^[+-]/, ""), !/^(?:\d+\.?\d*|\.\d+)$/.test(o)) return "0";
+  const [T = "0", R = ""] = o.split(".");
+  let g = (T.replace(/^0+/, "") || "0") + R;
+  const P = R.length - $;
+  let p;
+  if (P <= 0)
+    g += "0".repeat(-P), p = g.replace(/^0+(?=\d)/, "") || "0";
+  else {
+    const m = g.length - P;
+    m <= 0 ? p = "0." + "0".repeat(-m) + g : p = g.slice(0, m) + "." + g.slice(m), p = x(p);
   }
-  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;
+  return (i ? "-" : "") + (p || "0");
+}
+function E(r) {
+  const t = typeof r;
+  if (t == "string" || t == "bigint" || t == "number") {
+    const { sign: e, value: n } = d(r);
+    return { sign: e, value: n };
+  }
+  return r;
+}
+function a(r) {
+  let t = "", e = r.length - 1, n = "1";
+  for (; e >= 0; ) {
+    const i = r[e];
+    let s = Number(i) + (n ? 1 : 0);
+    s >= 10 ? (n = "1", s -= 10) : n = "", t = s.toString() + t, e--;
+  }
+  return { result: n + t, remaining: n };
+}
+function I(r, t = 0) {
+  const [e, n = ""] = r.split(".");
+  if (t === 0)
+    return n && Number(n[0]) >= 5 ? a(e).result : e;
+  if (t >= n.length) return e + (n ? `.${n}` : "");
+  const i = n.slice(0, t), s = n.slice(t);
+  if (Number(s[0]) >= 5) {
+    const c = a(i);
+    return c.remaining ? a(e).result : e + "." + c.result;
+  } else return e + "." + i;
+}
+function M(r, t = 0) {
+  const [e, n = ""] = r.split(".");
+  if (t === 0)
+    return n ? a(e).result : e;
+  if (t >= n.length) return e + "." + n;
+  const i = a(n.slice(0, t));
+  return i.remaining ? a(e).result : e + "." + i.result;
+}
+function b(r, t = 0) {
+  const [e, n = ""] = r.split(".");
+  if (t === 0) return e;
+  let i = n.slice(0, t), s = i.length - 1;
+  for (; s >= 0 && i[s] == "0"; ) s--;
+  return i = i.slice(0, s + 1), e + (i ? `.${i}` : "");
+}
+function O(r, t = 0) {
+  const [e, n = ""] = r.split(".");
+  if (t === 0)
+    return n && Number(n[0]) >= 5 ? Number(e[0]) / 2 == 0 ? e : a(e).result : e;
+  if (t >= n.length) return e + (n ? `.${n}` : "");
+  const i = n.slice(0, t), s = n.slice(t);
+  if (s[0] == "5") {
+    if (Number(i[i.length - 1]) % 2 == 0)
+      return e + "." + i;
     {
-      const l = u(n);
-      return l.remaining ? u(t).result : t + "." + l.result;
+      const c = a(i);
+      return c.remaining ? a(e).result : e + "." + c.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) {
+  } else if (Number(s[0]) > 5) {
+    const c = a(i);
+    return c.remaining ? a(e).result : e + "." + c.result;
+  } else return e + "." + i;
+}
+function _(r, t = {}) {
+  const e = t.rounding || "half", n = t.precision || 0, { sign: i, value: s } = d(r);
+  switch (e) {
     case "half":
-      return i + d(n, e);
+      return i + I(s, n);
     case "up":
-      return i == "" ? g(n, e) : "-" + a(n, e);
+      return i == "" ? M(s, n) : "-" + b(s, n);
     case "down":
-      return i == "" ? a(n, e) : "-" + g(n, e);
+      return i == "" ? b(s, n) : "-" + M(s, n);
     case "truncate":
-      return i + a(n, e);
+      return i + b(s, n);
     case "banker":
-      return i + S(n, e);
+      return i + O(s, n);
   }
 }
-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++;
+const Z = ["K", "M", "B", "T", "Q"];
+function v(r, t = {}) {
+  const { sign: e, value: n } = d(r);
+  let [i, s = ""] = n.split("."), c = i.length, u = -1;
+  for (; c > 3 && u < 4; ) {
+    const o = i.slice(0, c - 3);
+    s = i.slice(c - 3) + s, i = o, c -= 3, u++;
   }
-  return m(`${e}${n}.${i}`, r) + (c >= 0 ? $[c] : "");
+  const l = `${e}${i}${s.length > 0 ? "." + s : s}`;
+  return {
+    value: t.precision != null ? _(l, t) : l,
+    symbol: u >= 0 ? Z[u] : ""
+  };
 }
-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 A(r, t = {}) {
+  const { value: e, symbol: n } = v(r, t);
+  return e + n;
+}
+function k(r) {
+  const { sign: t, value: e } = d(r), [n, i = ""] = e.split("."), s = i.match(/^0+/)?.[0]?.length || 0, c = s.toString().split("").map((l) => String.fromCharCode(8320 + parseInt(l))).join(""), u = i.slice(s);
+  return `${t}${n}.0${c}${u}`;
+}
+function F(r) {
+  const { sign: t, value: e } = d(r);
+  if (e == "0") return { value: "0", exponent: 0 };
+  const [n, i = ""] = e.split(".");
+  if (n !== "0") {
+    const l = n.length - 1, o = n[0] + "." + (n.slice(1) + i).replace(/0+$/, "");
+    return { value: `${t}${o}${o.length > 1, ""}`, exponent: l, sign: "+" };
+  }
+  const s = i.search(/[1-9]/);
+  if (s === -1) return { value: "0", exponent: 0 };
+  const c = -(s + 1), u = i[s] + "." + i.slice(s + 1).replace(/0+$/, "");
+  return { value: `${t}${u}`, exponent: c - 1, sign: "" };
 }
-function x(s) {
+function U(r) {
+  const { value: t, exponent: e, sign: n } = F(r);
+  return e != 0 ? `${t}e${n}${e}` : t;
+}
+function f(r) {
   return {
-    round(r = {}) {
-      return x(m(s, r));
+    round: (t) => {
+      const e = _(r.value, t);
+      return f({ ...r, value: e });
+    },
+    compact: (t) => {
+      if (r.compactedSymbol) return f(r);
+      const { value: e, symbol: n } = v(r.value, t);
+      return f({ ...r, compactedSymbol: n, value: e });
+    },
+    notation(t = "scientific") {
+      return f({ ...r, notation: t });
     },
-    compact(r = {}) {
-      return h(s, r);
+    prefix(t) {
+      return f({ ...r, prefix: t });
     },
-    format(r = {}) {
-      const t = r.prefix || "", e = r.suffix || "", n = r.isSmall || !1;
-      return `${t}${n ? P(String(s)) : s}${e}`;
+    suffix(t) {
+      return f({ ...r, suffix: t });
     },
-    toString() {
-      return String(s);
+    toNumber() {
+      let { value: t } = r;
+      const { sign: e, prefix: n, suffix: i, compactedSymbol: s } = r;
+      return r.notation == "scientific" ? t = U(t) : r.notation == "subscript" && (t = k(t)), `${n || ""}${e}${t}${s || ""}${i || ""}`;
+    },
+    toObject() {
+      return r;
     }
   };
 }
+function H(r) {
+  return f(E(r));
+}
 export {
-  x as FN,
-  h as compact,
-  b as formatNumber,
-  P as formatSmallNum,
-  o as removeZero,
-  m as round
+  H as FN,
+  x as clearTrailingZero,
+  A as compact,
+  z as parseNum,
+  _ as round,
+  U as scientific,
+  k as subscript
 };

package/dist/io.d.ts

@@ -0,0 +1,26 @@
+import { NumberType, ObjectNumberType, SignType } from './types';
+/**
+ * Removes redundant leading and trailing zeros from a number string.
+ *
+ * @param value - The number string to clean.
+ * @returns The cleaned number string.
+ */
+export declare function clearTrailingZero(value: string): string;
+export declare function getInput(value: NumberType): {
+    sign: SignType;
+    value: string;
+};
+/**
+ * Parses various input formats into a standard decimal string.
+ * Supports numbers, bigints, currencies ($€£¥), commas, underscores,
+ * scientific notation (e+), and custom subscript notation (e.g., "5.0₄6").
+ *
+ * @param value - The input value to parse.
+ * @returns A standardized decimal string.
+ *
+ * @example
+ * parseNum('$1,234.56'); // '1234.56'
+ * parseNum('5.0₄6'); // '5.00006'
+ */
+export declare function parseNum(value: NumberType): string;
+export declare function convertToObjectNumber(value: NumberType | ObjectNumberType): ObjectNumberType;

package/dist/notation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Formats the decimal part of small numbers using subscript characters
+ * to represent the number of consecutive leading zeros.
+ *
+ * @param value - The number string to format.
+ * @returns A string with subscript notation (e.g., '0.0₃5').
+ */
+export declare function subscript(value: string): string;
+export declare function _scientific(value: string): {
+    value: string;
+    exponent: number;
+    sign?: undefined;
+} | {
+    value: string;
+    exponent: number;
+    sign: string;
+};
+/**
+ * Formats a number string using standard scientific notation.
+ *
+ * @param value - The number string to format.
+ * @returns A string in scientific notation (e.g., '1.23e+5').
+ */
+export declare function scientific(value: string): string;

package/dist/round.d.ts

@@ -1,3 +1,16 @@
 import { NumberType, RoundingConfigType } from './types';
 export declare function roundPositiveHalf(value: string, precision?: number): string;
+/**
+ * Rounds a number based on the specified precision and rounding mode.
+ *
+ * @param value - The value to be rounded. Can be a number, string, or bigint.
+ * @param options - Configuration for rounding.
+ * @param options.rounding - The rounding strategy to use ('half', 'up', 'down', 'banker', 'truncate'). Default is 'half'.
+ * @param options.precision - The number of decimal places to round to. Default is 0.
+ * @returns The rounded number as a string.
+ *
+ * @example
+ * round(123.456, { precision: 2 }); // '123.46'
+ * round(123.45, { rounding: 'down', precision: 1 }); // '123.4'
+ */
 export declare function round(value: NumberType, options?: RoundingConfigType): string;

package/dist/types.d.ts

@@ -1,14 +1,37 @@
+/** Supported input types for number formatting */
 export type NumberType = number | string | bigint;
+/** Strategies for rounding numbers */
 export type RoundingMode = 'half' | 'up' | 'down' | 'banker' | 'truncate';
+/** Modes for special numerical notation */
+export type NotationMode = 'subscript' | 'scientific';
+/** Possible sign values for internal number representation */
+export type SignType = '-' | '';
+/** Configuration for rounding operations */
 export type RoundingConfigType = Partial<{
-    mode: RoundingMode;
+    /** The rounding strategy to use */
+    rounding: RoundingMode;
+    /** Number of decimal places to keep */
     precision: number;
 }>;
-export type OtherMetadataType = Partial<{
+/** Configuration for basic number display properties */
+export type NumberConfigType = Partial<{
+    /** Text to prepend to the number (e.g., '$') */
     prefix: string;
+    /** Text to append to the number (e.g., ' units') */
     suffix: string;
-    isSmall: boolean;
+    /** The notation style to apply */
+    notation: NotationMode;
 }>;
-export type MetadataType = RoundingConfigType & OtherMetadataType & Partial<{
+/** Internal object structure containing full formatting state */
+export type ObjectNumberType = {
+    sign: SignType;
+    value: string;
+} & NumberConfigType & Partial<{
+    /** The symbol used for compact notation (e.g., 'K', 'M') */
+    compactedSymbol: string;
+}>;
+/** Full configuration options for the formatNumber function */
+export type FormattingConfigType = RoundingConfigType & NumberConfigType & Partial<{
+    /** Whether to use compact notation (K, M, B, etc.) */
     isCompact: boolean;
 }>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@peter-present/format-number",
-  "version": "0.0.1",
-  "description": "Utility library for number formatting, rounding, and compact display.",
+  "version": "0.0.11",
+  "description": "A lightweight, zero-dependency JavaScript/TypeScript library for precise number formatting. Designed for financial applications, crypto dashboards, and scientific data where precision is paramount.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/dist/utils.d.ts

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