@peter-present/format-number 0.0.11 → 0.0.12

package/README.md

@@ -9,12 +9,32 @@ For detailed documentation, visit: [here](https://blog.peter-present.xyz/format-
 ## Key Features
 
 - **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.
+- **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

package/dist/index.cjs

@@ -1 +1 @@
-"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;
+"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,6 +1,212 @@
-export * from './types';
-export { compact } from './compact';
-export { FN } from './format';
-export { clearTrailingZero, parseNum } from './io';
-export { scientific, subscript } from './notation';
-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,200 +1,223 @@
-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 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");
   }
-  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";
+  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 m = g.length - P;
-    m <= 0 ? p = "0." + "0".repeat(-m) + g : p = g.slice(0, m) + "." + g.slice(m), p = x(p);
+    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 ? "-" : "") + (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 (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 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 { 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);
   }
-  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 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 _(r, t = {}) {
-  const e = t.rounding || "half", n = t.precision || 0, { sign: i, value: s } = d(r);
-  switch (e) {
+  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 + I(s, n);
+      a = I(s, e);
+      break;
     case "up":
-      return i == "" ? M(s, n) : "-" + b(s, n);
+      a = c ? x(s, e) : M(s, e);
+      break;
     case "down":
-      return i == "" ? b(s, n) : "-" + M(s, n);
+      a = c ? M(s, e) : x(s, e);
+      break;
     case "truncate":
-      return i + b(s, n);
+      a = x(s, e);
+      break;
     case "banker":
-      return i + O(s, n);
+      a = E(s, e);
+      break;
+    default:
+      a = I(s, e);
   }
-}
-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 { sign: c, ...a };
+}
+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 l = `${e}${i}${s.length > 0 ? "." + s : s}`;
+  const s = r.precision != null ? S({ sign: n, intPart: e, fracPart: c }, r) : { intPart: e, fracPart: c };
   return {
-    value: t.precision != null ? _(l, t) : l,
-    symbol: u >= 0 ? Z[u] : ""
+    sign: n,
+    intPart: Q(s.intPart),
+    fracPart: K(s.fracPart),
+    symbol: o >= 0 ? H[o] : ""
   };
 }
-function A(r, t = {}) {
-  const { value: e, symbol: n } = v(r, t);
-  return e + n;
+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 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 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 F(r) {
-  const { sign: t, value: e } = d(r);
-  if (e == "0") return { value: "0", exponent: 0 };
-  const [n, i = ""] = e.split(".");
+function A(t) {
+  const { sign: r, intPart: n, fracPart: e } = t, c = r === "-" ? "-" : "";
   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 a = n.length - 1, f = (n[0] + "." + (n.slice(1) + e).replace(/0+$/, "")).replace(
+      /\.$/,
+      ""
+    );
+    return { value: `${c}${f}`, exponent: a, 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: "" };
+  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 U(r) {
-  const { value: t, exponent: e, sign: n } = F(r);
-  return e != 0 ? `${t}e${n}${e}` : t;
+function L(t) {
+  const { value: r, exponent: n, sign: e } = A(F(t));
+  return n !== 0 ? `${r}e${e}${n}` : r;
 }
-function f(r) {
+function u(t) {
   return {
-    round: (t) => {
-      const e = _(r.value, t);
-      return f({ ...r, value: e });
+    round: (r) => {
+      const n = S(t, r);
+      return u({ ...t, ...n });
     },
-    compact: (t) => {
-      if (r.compactedSymbol) return f(r);
-      const { value: e, symbol: n } = v(r.value, t);
-      return f({ ...r, compactedSymbol: n, value: e });
+    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(t = "scientific") {
-      return f({ ...r, notation: t });
+    notation(r = "scientific") {
+      return u({ ...t, notation: r });
     },
-    prefix(t) {
-      return f({ ...r, prefix: t });
+    prefix(r) {
+      return u({ ...t, prefix: r });
     },
-    suffix(t) {
-      return f({ ...r, suffix: t });
+    suffix(r) {
+      return u({ ...t, suffix: r });
     },
     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 || ""}`;
+      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 || ""}`;
     },
     toObject() {
-      return r;
+      return t;
     }
   };
 }
-function H(r) {
-  return f(E(r));
+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 {
-  H as FN,
-  x as clearTrailingZero,
-  A as compact,
-  z as parseNum,
-  _ as round,
-  U as scientific,
-  k as subscript
+  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.11",
+  "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,20 +0,0 @@
-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,37 +0,0 @@
-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/io.d.ts

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

@@ -1,24 +0,0 @@
-/**
- * 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,16 +0,0 @@
-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,37 +0,0 @@
-/** 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<{
-    /** The rounding strategy to use */
-    rounding: RoundingMode;
-    /** Number of decimal places to keep */
-    precision: number;
-}>;
-/** 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;
-    /** The notation style to apply */
-    notation: NotationMode;
-}>;
-/** 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;
-}>;