@peter-present/format-number 0.0.1 → 0.0.12

package/README.md

@@ -1,115 +1,125 @@
 # 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**: Centralized parsing handles messy strings with currency symbols ($€£¥), commas, underscores, and scientific notation.
+- **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.
+
+## Robust Parsing & Error Handling
+
+The library follows a **Single-Gate Parsing** philosophy. High-level entry points (`FN`, `formatNumber`, and `parseNum`) are designed to be robust and will attempt to clean and normalize nearly any "number-like" string.
+
+> [!IMPORTANT]
+> **Internal functions** (like `round`, `compact`, `scientific`, etc.) are optimized for performance and **assume valid numeric strings**. Passing completely invalid non-numeric data (e.g., `"abc"`) directly to these utilities may result in fallback values or undefined behavior.
+
+For manual parsing with custom error handling, use `parseNum`:
+
+```typescript
+import { parseNum } from '@peter-present/format-number';
+
+// Default fallback is '--'
+parseNum('invalid'); // '--'
+
+// Custom fallback for your own error boundaries
+parseNum('not-a-number', { fallback: 'NaN' }); // 'NaN'
+parseNum('null', { fallback: '0' }); // '0'
+```
 
 ## 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';
-
-round(123.456, { precision: 2 }); // '123.46'
-round(-123.45, { mode: 'up', precision: 1 }); // '-123.4' (Towards +Infinity)
-```
+import { formatNumber } from '@peter-present/format-number';
 
-### Compact Formatting: `compact()`
+// Currency & Rounding
+formatNumber('$1,234.567', { prefix: '€', precision: 2 }); // '€1234.57'
 
-Format large numbers with readable suffixes.
+// Compact Notation
+formatNumber(1500000000, { isCompact: true }); // '1.5B'
 
-```typescript
-import { compact } from 'format-number';
-
-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/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"});const Z=t=>t.replace(/0+$/,""),B=t=>t.replace(/^0+(?!$)/,"");function p(t){return t.replace(/^(-?)0+(?=\d)/,"$1").replace(/(\.\d*?)0+$/,"$1").replace(/\.$/,"")}function z(t,r={}){const{fallback:n="--"}=r;if(typeof t=="number"||typeof t=="bigint")return t.toString();const e=String(t??"").trim();if(!e)return"0";const c=e.match(/^[\s+-]*/),i=(c&&c[0].match(/-/g)||[]).length%2===1,o=e.replace(/[$€£¥,_\s]/g,""),s=o.match(/^([+-]?\d+)\.0([\u2080-\u2089]+)([0-9]*)$/i);if(s){const[,l,K,Q]=s,V=K.split("").reduce((H,L)=>H+(L.charCodeAt(0)-8320),0),E=p(l.replace(/^[+-]/,"")+"."+"0".repeat(V)+Q);return(i?"-":"")+(E||"0")}const a=o.match(/[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?[KMBTQ]*/i);if(!a)return n;let f=a[0].toUpperCase(),b=0;const U=f.slice(-1),S="KMBTQ".indexOf(U);S!==-1&&(b=(S+1)*3,f=f.slice(0,-1));const h=f.match(/[E]([+-]?\d+)$/);if(h&&(b+=parseInt(h[1],10),f=f.slice(0,h.index)),f=f.replace(/^[+-]/,""),!/^(?:\d+\.?\d*|\.\d+)$/.test(f))return"0";const[D="0",F=""]=f.split("."),d=(D.replace(/^0+/,"")||"0")+F,x=F.length-b;let P;if(x<=0)P=(d+"0".repeat(-x)).replace(/^0+(?=\d)/,"")||"0";else{const l=d.length-x;P=l<=0?"0."+"0".repeat(-l)+d:d.slice(0,l)+"."+d.slice(l),P=p(P)}return(i?"-":"")+(P||"0")}function m(t){let r=String(t).trim();const n=r.startsWith("-")?"-":"";n&&(r=r.slice(1));const[e,c=""]=p(r).split(".");return{sign:n,intPart:e,fracPart:c}}const I=t=>t.fracPart?`${t.sign}${t.intPart}.${t.fracPart}`:`${t.sign}${t.intPart}`;function A(t){return typeof t=="object"&&t!==null&&"intPart"in t?t:m(t)}function $(t){if(!t)return{result:"",carry:!0};const n=(BigInt(t)+1n).toString();return n.length>t.length?{result:n.slice(1),carry:!0}:{result:n.padStart(t.length,"0"),carry:!1}}function g({intPart:t}){const{result:r,carry:n}=$(t);return{intPart:n?"1"+r:r,fracPart:""}}function k(t,r=0){const{intPart:n,fracPart:e}=t;if(!e||r>=e.length)return t;if(parseInt(e[r],10)>=5){if(r===0)return g(t);const i=e.slice(0,r),{result:o,carry:s}=$(i);return s?g(t):{intPart:n,fracPart:o}}return{intPart:n,fracPart:e.slice(0,r)}}function M(t,r=0){const{intPart:n,fracPart:e}=t;if(!e||r>=e.length)return t;if(r===0)return g(t);const c=e.slice(0,r),{result:i,carry:o}=$(c);return o?g(t):{intPart:n,fracPart:i}}function y(t,r=0){const{intPart:n,fracPart:e}=t;if(!e||r>=e.length)return t;const c=e.slice(0,r);return{intPart:n,fracPart:c.replace(/0+$/,"")}}function W(t,r=0){const{intPart:n,fracPart:e}=t;if(!e||r>=e.length)return t;const c=parseInt(e[r],10),i=e.slice(r+1).replace(/0+$/,""),o=c===5&&i==="";let s=!1;if(c>5||c===5&&i!=="")s=!0;else if(o){const a=r===0?n[n.length-1]:e[r-1];parseInt(a,10)%2!==0&&(s=!0)}if(s){if(r===0)return g(t);const{result:a,carry:f}=$(e.slice(0,r));return f?g(t):{intPart:n,fracPart:a}}return{intPart:n,fracPart:e.slice(0,r)}}function N(t,r={}){const n=r.rounding||"half",e=r.precision||0,{sign:c,intPart:i,fracPart:o}=t,s={intPart:i,fracPart:o};let a;switch(n){case"half":a=k(s,e);break;case"up":a=c?y(s,e):M(s,e);break;case"down":a=c?M(s,e):y(s,e);break;case"truncate":a=y(s,e);break;case"banker":a=W(s,e);break;default:a=k(s,e)}return{sign:c,...a}}function q(t,r={}){const n=N(m(t),r);return I(n)}const G=["K","M","B","T","Q"];function T(t,r={}){let{sign:n,intPart:e,fracPart:c}=t,i=e.length,o=-1;for(;i>3&&o<4;){const a=e.slice(0,i-3);c=e.slice(i-3)+c,e=a,i-=3,o++}const s=r.precision!=null?N({sign:n,intPart:e,fracPart:c},r):{intPart:e,fracPart:c};return{sign:n,intPart:B(s.intPart),fracPart:Z(s.fracPart),symbol:o>=0?G[o]:""}}function J(t,r={}){const{sign:n,intPart:e,fracPart:c,symbol:i}=T(m(t),r);return I({sign:n,intPart:e,fracPart:c})+i}function _(t){return typeof t=="object"&&"intPart"in t?t:m(t)}function j(t){const{sign:r,intPart:n,fracPart:e}=_(t),c=e.match(/^0+/)?.[0]?.length||0,i=c.toString().split("").reduce((o,s)=>o+String.fromCharCode(8320+Number(s)),"");return`${r}${n}.0${i}${e.slice(c)}`}function R(t){const{sign:r,intPart:n,fracPart:e}=t,c=r==="-"?"-":"";if(n!=="0"){const a=n.length-1,f=(n[0]+"."+(n.slice(1)+e).replace(/0+$/,"")).replace(/\.$/,"");return{value:`${c}${f}`,exponent:a,sign:"+"}}const i=e.search(/[1-9]/);if(i===-1)return{value:"0",exponent:0};const o=-(i+1),s=(e[i]+"."+e.slice(i+1).replace(/0+$/,"")).replace(/\.$/,"");return{value:`${c}${s}`,exponent:o,sign:""}}function O(t){const{value:r,exponent:n,sign:e}=R(_(t));return n!==0?`${r}e${e}${n}`:r}function u(t){return{round:r=>{const n=N(t,r);return u({...t,...n})},compact:r=>{if(t.compactedSymbol)return u(t);const n=T(t,r);return u({...t,intPart:n.intPart,fracPart:n.fracPart,compactedSymbol:n.symbol})},notation(r="scientific"){return u({...t,notation:r})},prefix(r){return u({...t,prefix:r})},suffix(r){return u({...t,suffix:r})},toNumber(){const{sign:r,intPart:n,fracPart:e,prefix:c,suffix:i,compactedSymbol:o,notation:s}=t;let a=e.length>0?`${n}.${e}`:n;return s==="scientific"?a=O({sign:"",intPart:n,fracPart:e}):s==="subscript"&&(a=j({sign:"",intPart:n,fracPart:e})),`${c||""}${r}${a}${o||""}${i||""}`},toObject(){return t}}}function w(t){return u(A(t))}function C(t,r={}){let n=w(t).round(r);return r.isCompact&&(n=n.compact(r)),r.notation&&(n=n.notation(r.notation)),r.prefix&&(n=n.prefix(r.prefix)),r.suffix&&(n=n.suffix(r.suffix)),n.toNumber()}function X(t={}){return r=>C(r,t)}exports.FN=w;exports.clearLeadingZero=B;exports.clearTrailingZero=Z;exports.clearUnnecessaryZero=p;exports.compact=J;exports.createFormatFunction=X;exports.formatNumber=C;exports.getBaseNumberNumber=m;exports.parseNum=z;exports.round=q;exports.scientific=O;exports.subscript=j;

package/dist/index.d.ts

@@ -1,5 +1,212 @@
-export * from './types';
-export * from './utils';
-export { compact } from './compact';
-export { FN, formatNumber } from './format';
-export { round } from './round';
+export declare type BaseObjectNumberType = {
+    sign: SignType;
+} & BasePositiveNumberType;
+
+export declare type BasePositiveNumberType = {
+    intPart: string;
+    fracPart: string;
+};
+
+/**
+ * Removes leading zeros from a string (e.g., '005' -> '5').
+ */
+export declare const clearLeadingZero: (value: string) => string;
+
+/**
+ * Removes trailing zeros from a decimal string (e.g., '1.500' -> '1.5').
+ */
+export declare const clearTrailingZero: (value: string) => string;
+
+/**
+ * Removes redundant leading and trailing zeros from a number string.
+ */
+export declare function clearUnnecessaryZero(value: string): 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;
+
+/**
+ * Creates a reusable formatting function with predefined options.
+ * Useful for applying consistent formatting across multiple numbers.
+ *
+ * @param options - Configuration options for the formatter.
+ * @returns A function that accepts a value and returns the formatted string.
+ *
+ * @example
+ * const formatCurrency = createFormatFunction({ prefix: '$', precision: 2 });
+ * formatCurrency(1234.56); // '$1234.56'
+ * formatCurrency(100); // '$100.00'
+ */
+export declare function createFormatFunction(options?: FormattingConfigType): (value: NumberType) => string;
+
+/**
+ * Fluent API for performing multiple formatting operations in a readable chain.
+ * Wraps the input value into a formatter object that supports rounding,
+ * compacting, notation, prefixes, and suffixes.
+ *
+ * @param value - The initial value to format, can be a number, string, or bigint.
+ * @returns A chainable `FNType` object.
+ *
+ * @example
+ * FN('1234567.89')
+ *   .round({ precision: 0 })
+ *   .prefix('$')
+ *   .toNumber(); // '$1234568'
+ *
+ * @example
+ * FN(1000000)
+ *   .compact()
+ *   .suffix(' total')
+ *   .toNumber(); // '1M total'
+ */
+export declare function FN(value: NumberType | ObjectNumberType): FNType;
+
+/**
+ * Fluent API interface for chainable number formatting operations.
+ */
+export declare type FNType = {
+    /**
+     * Rounds the number based on the provided precision and strategy.
+     * @param options - Rounding configuration (precision, rounding strategy).
+     * @returns The same FNType instance for further chaining.
+     */
+    round(options?: RoundingConfigType): FNType;
+    /**
+     * Converts the number to a compact representation (e.g., 1K, 1M, 1B).
+     * @param options - Optional rounding configuration to apply during compaction.
+     * @returns The same FNType instance for further chaining.
+     */
+    compact(options?: RoundingConfigType): FNType;
+    /**
+     * Sets the notation style for the number (e.g., scientific, subscript).
+     * @param mode - The notation mode to use. Defaults to 'scientific'.
+     * @returns The same FNType instance for further chaining.
+     */
+    notation(mode?: NotationMode): FNType;
+    /**
+     * Adds a prefix to the formatted number string.
+     * @param symbol - The string to prepend.
+     * @returns The same FNType instance for further chaining.
+     */
+    prefix(symbol: string): FNType;
+    /**
+     * Adds a suffix to the formatted number string.
+     * @param symbol - The string to append.
+     * @returns The same FNType instance for further chaining.
+     */
+    suffix(symbol: string): FNType;
+    /**
+     * Finalizes the chain and returns the formatted number as a string.
+     * @returns The final formatted number string.
+     */
+    toNumber(): string;
+    /**
+     * Returns the internal state of the number as an ObjectNumberType.
+     * @returns The internal object representation.
+     */
+    toObject(): ObjectNumberType;
+};
+
+/**
+ * Comprehensive formatting function that combines rounding, compacting, and metadata.
+ * This is the quickest way to format a number with multiple options in a single call.
+ *
+ * @param value - The value to format (number, string, or bigint).
+ * @param options - Formatting configuration (precision, rounding strategy, compact mode, prefix, suffix, and notation style).
+ * @returns The final formatted number string.
+ *
+ * @example
+ * formatNumber(1234.56, { prefix: '$', precision: 1 }); // '$1234.6'
+ *
+ * @example
+ * formatNumber(1500000, { isCompact: true, notation: 'scientific' }); // '1.5M' (compacted before potential notation)
+ */
+export declare function formatNumber(value: NumberType, options?: FormattingConfigType): string;
+
+/** Full configuration options for the formatNumber function */
+export declare type FormattingConfigType = RoundingConfigType & NumberConfigType & Partial<{
+    /** Whether to use compact notation (K, M, B, etc.) */
+    isCompact: boolean;
+}>;
+
+export declare function getBaseNumberNumber(value: NumberType): BaseObjectNumberType;
+
+/** Modes for special numerical notation */
+export declare type NotationMode = 'subscript' | 'scientific';
+
+/** Configuration for basic number display properties */
+export declare type NumberConfigType = Partial<{
+    /** Text to prepend to the number (e.g., '$') */
+    prefix: string;
+    /** Text to append to the number (e.g., ' units') */
+    suffix: string;
+    /** The notation style to apply */
+    notation: NotationMode;
+}>;
+
+/** Supported input types for number formatting */
+export declare type NumberType = number | string | bigint;
+
+/** Internal object structure containing full formatting state */
+export declare type ObjectNumberType = BaseObjectNumberType & NumberConfigType & Partial<{
+    /** The symbol used for compact notation (e.g., 'K', 'M') */
+    compactedSymbol: string;
+}>;
+
+/**
+ * Parses various input formats into a standard decimal string.
+ */
+export declare function parseNum(value: NumberType, options?: ParseNumberParamsType): string;
+
+/** Configuration for input parsing */
+export declare type ParseNumberParamsType = Partial<{
+    /** Value to return if parsing fails. Default is '--' */
+    fallback: string;
+}>;
+
+export declare function round(value: NumberType, options?: RoundingConfigType): string;
+
+/** Configuration for rounding operations */
+export declare type RoundingConfigType = Partial<{
+    /** The rounding strategy to use */
+    rounding: RoundingMode;
+    /** Number of decimal places to keep */
+    precision: number;
+}>;
+
+/** Strategies for rounding numbers */
+export declare type RoundingMode = 'half' | 'up' | 'down' | 'banker' | 'truncate';
+
+/**
+ * Formats a number string using standard scientific notation.
+ */
+export declare function scientific(value: NumberType | BaseObjectNumberType): string;
+
+export declare type ScientificReturnType = {
+    value: string;
+    exponent: number;
+    sign?: string;
+};
+
+/** Possible sign values for internal number representation */
+export declare type SignType = '-' | '';
+
+/**
+ * Formats the decimal part of small numbers using subscript characters.
+ */
+export declare function subscript(value: NumberType | BaseObjectNumberType): string;
+
+export { }

package/dist/index.js

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

package/package.json

@@ -1,16 +1,24 @@
 {
   "name": "@peter-present/format-number",
-  "version": "0.0.1",
-  "description": "Utility library for number formatting, rounding, and compact display.",
+  "version": "0.0.12",
+  "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",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "bun run clear && tsc && vite build",
+    "build": "bun run clear && vite build",
     "preview": "vite preview",
     "clear": "rm -rf dist",
     "test": "vitest run",

package/dist/compact.d.ts

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

package/dist/format.d.ts

@@ -1,8 +0,0 @@
-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/round.d.ts

@@ -1,3 +0,0 @@
-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

@@ -1,14 +0,0 @@
-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

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