ui-formatter 0.1.0 → 0.1.2

package/README.md

@@ -1 +1,446 @@
-# ui-formatter
+# ui-formatter
+
+A lightweight, zero-dependency TypeScript utility library for formatting dates, times, numbers, and phone numbers.
+
+Designed for applications that require **high performance**, **small bundle size**, and **no external dependencies**.
+
+---
+
+## Features
+
+- 🚀 Zero dependencies
+- ⚡ High-performance implementations
+- 📅 Date formatting
+- 🕒 Time formatting
+- 🔢 Number formatting
+- ☎️ Phone/Fax formatting
+- 🧹 Phone normalization
+- 💯 TypeScript support
+- 🌍 Works in Browser and Node.js
+
+---
+
+## Installation
+
+```bash
+npm install ui-formatter
+```
+
+or
+
+```bash
+yarn add ui-formatter
+```
+
+---
+
+## Quick Example
+
+```ts
+import {
+    formatDate,
+    formatDateTime,
+    formatNumber,
+    formatInteger,
+    formatPhone
+} from "ui-formatter"
+
+const date = new Date()
+
+formatDate(date, "MM/dd/yyyy")
+// 07/02/2026
+
+formatDateTime(date, "yyyy-MM-dd")
+// 2026-07-02 14:35
+
+formatNumber(1234567.89, 2)
+// 1,234,567.89
+
+formatInteger(1000000)
+// 1,000,000
+
+formatPhone("8005551234")
+// 800 555-1234
+```
+
+---
+
+# API
+
+---
+
+## Date Utilities
+
+### getDateFormat()
+
+Returns the default date format.
+
+```ts
+const format = getDateFormat()
+
+// M/d/yyyy
+```
+
+---
+
+### addDays()
+
+Returns a new date with the specified number of days added.
+
+```ts
+const tomorrow = addDays(new Date(), 1)
+```
+
+---
+
+### formatDate()
+
+Formats a Date using a custom format.
+
+Supported tokens:
+
+| Token | Description |
+|--------|-------------|
+| yyyy | 4-digit year |
+| yy | 2-digit year |
+| MM | 2-digit month |
+| M | Month |
+| dd | 2-digit day |
+| d | Day |
+
+Example
+
+```ts
+formatDate(new Date(), "yyyy-MM-dd")
+
+// 2026-07-02
+```
+
+---
+
+### formatTime()
+
+Returns
+
+```
+HH:mm
+```
+
+Example
+
+```ts
+formatTime(new Date())
+
+// 15:30
+```
+
+---
+
+### formatLongTime()
+
+Returns
+
+```
+HH:mm:ss
+```
+
+Example
+
+```ts
+formatLongTime(new Date())
+
+// 15:30:45
+```
+
+---
+
+### formatFullTime()
+
+Returns
+
+```
+HH:mm:ss.SSS
+```
+
+Example
+
+```ts
+formatFullTime(new Date())
+
+// 15:30:45.123
+```
+
+---
+
+### formatDateTime()
+
+Formats
+
+```
+<Date> <HH:mm>
+```
+
+Example
+
+```ts
+formatDateTime(new Date(), "yyyy-MM-dd")
+
+// 2026-07-02 15:30
+```
+
+---
+
+### formatLongDateTime()
+
+Formats
+
+```
+<Date> <HH:mm:ss>
+```
+
+---
+
+### formatFullDateTime()
+
+Formats
+
+```
+<Date> <HH:mm:ss.SSS>
+```
+
+---
+
+### datetimeToString()
+
+Converts a Date into ISO-like format.
+
+```ts
+datetimeToString(new Date())
+
+// 2026-07-02T15:30:45
+```
+
+---
+
+### dateToString()
+
+Returns a compact timestamp.
+
+```ts
+dateToString(new Date())
+
+// 20260702153045
+```
+
+Milliseconds may be included.
+
+```ts
+dateToString(new Date(), true)
+
+// 20260702153045123
+```
+
+---
+
+# Number Utilities
+
+---
+
+### formatInteger()
+
+Formats an integer with thousands separators.
+
+```ts
+formatInteger(123456789)
+
+// 123,456,789
+```
+
+Custom separator
+
+```ts
+formatInteger(123456789, ".")
+
+// 123.456.789
+```
+
+---
+
+### formatNumber()
+
+Formats decimal numbers.
+
+```ts
+formatNumber(1234567.89, 2)
+
+// 1,234,567.89
+```
+
+Custom separators
+
+```ts
+formatNumber(
+    1234567.89,
+    2,
+    ",",
+    "."
+)
+
+// 1.234.567,89
+```
+
+---
+
+# Phone Utilities
+
+---
+
+### normalizePhone()
+
+Removes all characters except digits and `+`.
+
+```ts
+normalizePhone("(800) 555-1234")
+
+// 8005551234
+```
+
+---
+
+### normalizeFax()
+
+Alias of
+
+```
+normalizePhone()
+```
+
+---
+
+### formatPhone()
+
+Formats phone numbers into a readable representation.
+
+```ts
+formatPhone("8005551234")
+
+// 800 555-1234
+```
+
+Supports
+
+- US numbers
+- international numbers
+- partial numbers
+
+---
+
+### formatFax()
+
+Formats fax numbers.
+
+```ts
+formatFax("0212345678")
+
+// 02-12345678
+```
+
+---
+
+# Utility Functions
+
+---
+
+### isNotEmpty()
+
+Checks whether an array or string is not empty.
+
+```ts
+isNotEmpty([])
+
+// false
+
+isNotEmpty("hello")
+
+// true
+```
+
+---
+
+### isChecked()
+
+Utility for HTML templates.
+
+```ts
+isChecked(true)
+
+// checked
+
+isChecked(false)
+
+// ""
+```
+
+Can also compare string values.
+
+```ts
+isChecked("admin", "admin")
+
+// checked
+```
+
+---
+
+# Design Goals
+
+This library is designed with the following principles:
+
+- Zero runtime dependencies
+- High performance
+- Minimal allocations
+- Small bundle size
+- Predictable behavior
+- Browser and Node compatibility
+
+Several implementations avoid regular expressions and repeated string concatenation in favor of allocation-friendly algorithms.
+
+---
+
+# Performance
+
+The library includes optimized implementations for:
+
+- Manual date parsing
+- Number formatting
+- Integer formatting
+- Phone normalization
+
+Many functions use:
+
+- single-pass parsing
+- preallocated buffers
+- minimal temporary objects
+
+making them suitable for high-throughput applications.
+
+---
+
+# Browser Support
+
+Works in:
+
+- Chrome
+- Firefox
+- Safari
+- Edge
+- Node.js
+- Bun
+- Deno
+
+---
+
+# TypeScript
+
+Fully written in TypeScript.
+
+No additional typings are required.

package/lib/index.js

@@ -141,35 +141,88 @@ function pad3(n) {
   }
   return n < 10 ? "00" + n : "0" + n.toString();
 }
-function formatNumber(v, scale, d, g) {
-  if (v == null) {
+function formatInteger(v, groupSeparator) {
+  if (groupSeparator === void 0) { groupSeparator = ","; }
+  if (v == null || !Number.isFinite(v)) {
     return "";
   }
-  if (!d && !g) {
-    g = ",";
-    d = ".";
+  var isNegative = v < 0;
+  var n = Math.abs(Math.trunc(v));
+  if (n < 1000) {
+    return isNegative ? "-" + n : "" + n;
   }
-  else if (!g) {
-    g = d === "," ? "." : ",";
+  var buffer = new Array(32);
+  var i = buffer.length;
+  var digitCount = 0;
+  while (n > 0) {
+    if (digitCount > 0 && digitCount % 3 === 0) {
+      buffer[--i] = groupSeparator;
+    }
+    var digit = n % 10;
+    buffer[--i] = String.fromCharCode(48 + digit);
+    n = Math.floor(n / 10);
+    digitCount++;
+  }
+  if (isNegative) {
+    buffer[--i] = "-";
+  }
+  return buffer.slice(i).join("");
+}
+exports.formatInteger = formatInteger;
+function formatNumber(v, precision, decimalSeparator, groupSeparator) {
+  if (precision === void 0) { precision = 0; }
+  if (v == null || !Number.isFinite(v)) {
+    return "";
   }
-  var s = scale === 0 || scale ? v.toFixed(scale) : v.toString();
-  var x = s.split(".", 2);
-  var y = x[0];
-  var arr = [];
-  var len = y.length - 1;
-  for (var k = 0; k < len; k++) {
-    arr.push(y[len - k]);
-    if ((k + 1) % 3 === 0) {
-      arr.push(g);
+  var d = ".";
+  var g = ",";
+  if (decimalSeparator && groupSeparator) {
+    d = decimalSeparator;
+    g = groupSeparator;
+  }
+  else if (decimalSeparator && !groupSeparator) {
+    d = decimalSeparator;
+    if (d === "٫") {
+      g = "٬";
+    }
+    else {
+      g = d === "," ? "." : ",";
     }
   }
-  arr.push(y[0]);
-  if (x.length === 1) {
-    return arr.reverse().join("");
+  var negative = v < 0;
+  var s = Math.abs(v).toFixed(precision);
+  var dot = s.indexOf(".");
+  var intEnd = dot >= 0 ? dot : s.length;
+  var fracLen = dot >= 0 ? s.length - dot - 1 : 0;
+  var intLen = intEnd;
+  var groups = intLen > 3 ? ((intLen - 1) / 3) | 0 : 0;
+  var outLen = (negative ? 1 : 0) + intLen + groups * g.length + (fracLen > 0 ? d.length + fracLen : 0);
+  var out = new Array(outLen);
+  var p = 0;
+  if (negative) {
+    out[p++] = "-";
+  }
+  var firstGroup = intLen % 3;
+  if (firstGroup === 0) {
+    firstGroup = 3;
   }
-  else {
-    return arr.reverse().join("") + d + x[1];
+  for (var i = 0; i < intLen; i++) {
+    if (i > 0 && (i === firstGroup || (i > firstGroup && (i - firstGroup) % 3 === 0))) {
+      for (var j = 0; j < g.length; j++) {
+        out[p++] = g[j];
+      }
+    }
+    out[p++] = s[i];
+  }
+  if (fracLen > 0) {
+    for (var j = 0; j < d.length; j++) {
+      out[p++] = d[j];
+    }
+    for (var i = dot + 1; i < s.length; i++) {
+      out[p++] = s[i];
+    }
   }
+  return out.join("");
 }
 exports.formatNumber = formatNumber;
 var formatter = (function () {
@@ -180,7 +233,7 @@ var formatter = (function () {
       return "";
     }
     var s = phone;
-    var x = removePhoneFormat(phone);
+    var x = normalizePhone(phone);
     if (x.length === 10) {
       var USNumber = x.match(formatter.usPhone);
       if (USNumber != null) {
@@ -207,7 +260,7 @@ var formatter = (function () {
       return "";
     }
     var s = fax;
-    var x = removePhoneFormat(fax);
+    var x = normalizeFax(fax);
     var l = x.length;
     if (l <= 6) {
       s = x;
@@ -232,20 +285,30 @@ var formatter = (function () {
     }
     return s;
   };
-  formatter.fax = / |\-|\.|\(|\)/g;
-  formatter.phone = / |\-|\.|\(|\)/g;
   formatter.usPhone = /(\d{3})(\d{3})(\d{4})/;
   return formatter;
 }());
 exports.formatter = formatter;
-function removePhoneFormat(phone) {
-  return phone ? phone.replace(formatter.phone, "") : "";
+function normalizePhone(s) {
+  if (!s) {
+    return "";
+  }
+  var len = s.length;
+  var buf = new Array(len);
+  var j = 0;
+  for (var i = 0; i < len; i++) {
+    var c = s.charCodeAt(i);
+    if ((c >= 48 && c <= 57) || c === 43) {
+      buf[j++] = s[i];
+    }
+  }
+  return j === len ? buf.join("") : buf.slice(0, j).join("");
 }
-exports.removePhoneFormat = removePhoneFormat;
-function removeFaxFormat(fax) {
-  return fax ? fax.replace(formatter.fax, "") : "";
+exports.normalizePhone = normalizePhone;
+function normalizeFax(fax) {
+  return normalizePhone(fax);
 }
-exports.removeFaxFormat = removeFaxFormat;
+exports.normalizeFax = normalizeFax;
 function formatPhone(phone) {
   return formatter.formatPhone(phone);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ui-formatter",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Format web UI",
   "main": "./lib/index.js",
   "types": "./src/index.ts",

package/src/index.ts

@@ -140,40 +140,121 @@ function pad3(n: number): string {
   return n < 10 ? "00" + n : "0" + n.toString()
 }
 
-export function formatNumber(v?: number | null, scale?: number, d?: string | null, g?: string): any {
-  if (v == null) {
+export function formatInteger(v: number | null | undefined, groupSeparator: string = ","): any {
+  if (v == null || !Number.isFinite(v)) {
     return ""
   }
-  if (!d && !g) {
-    g = ","
-    d = "."
-  } else if (!g) {
-    g = d === "," ? "." : ","
+
+  const isNegative = v < 0
+  let n = Math.abs(Math.trunc(v))
+
+  // Fast path
+  if (n < 1000) {
+    return isNegative ? `-${n}` : `${n}`
   }
-  const s = scale === 0 || scale ? v.toFixed(scale) : v.toString()
-  const x = s.split(".", 2)
-  const y = x[0]
-  const arr: string[] = []
-  const len = y.length - 1
-  for (let k = 0; k < len; k++) {
-    arr.push(y[len - k])
-    if ((k + 1) % 3 === 0) {
-      arr.push(g)
+
+  // Max length:
+  // digits (up to 16 for JS safe int) + separators (~5) + sign
+  const buffer = new Array(32)
+  let i = buffer.length
+
+  let digitCount = 0
+
+  while (n > 0) {
+    // Insert separator every 3 digits
+    if (digitCount > 0 && digitCount % 3 === 0) {
+      buffer[--i] = groupSeparator
     }
+
+    const digit = n % 10
+    buffer[--i] = String.fromCharCode(48 + digit)
+
+    n = Math.floor(n / 10) // safe version
+    digitCount++
   }
-  arr.push(y[0])
-  if (x.length === 1) {
-    return arr.reverse().join("")
-  } else {
-    return arr.reverse().join("") + d + x[1]
+
+  if (isNegative) {
+    buffer[--i] = "-"
   }
+
+  // Slice only used portion and join once
+  return buffer.slice(i).join("")
+}
+export function formatNumber(v?: number | null, precision = 0, decimalSeparator?: string | null, groupSeparator?: string | null): any {
+  if (v == null || !Number.isFinite(v)) {
+    return ""
+  }
+  let d = "."
+  let g = ","
+  if (decimalSeparator && groupSeparator) {
+    d = decimalSeparator
+    g = groupSeparator
+  } else if (decimalSeparator && !groupSeparator) {
+    d = decimalSeparator
+    if (d === "٫") {
+      g = "٬"
+    } else {
+      g = d === "," ? "." : ","
+    }
+  }
+  const negative = v < 0
+
+  // unavoidable allocation
+  const s = Math.abs(v).toFixed(precision)
+
+  const dot = s.indexOf(".")
+
+  const intEnd = dot >= 0 ? dot : s.length
+  const fracLen = dot >= 0 ? s.length - dot - 1 : 0
+
+  const intLen = intEnd
+  const groups = intLen > 3 ? ((intLen - 1) / 3) | 0 : 0
+
+  const outLen = (negative ? 1 : 0) + intLen + groups * g.length + (fracLen > 0 ? d.length + fracLen : 0)
+
+  const out = new Array<string>(outLen)
+
+  let p = 0
+
+  if (negative) {
+    out[p++] = "-"
+  }
+
+  // integer part
+  let firstGroup = intLen % 3
+  if (firstGroup === 0) {
+    firstGroup = 3
+  }
+
+  for (let i = 0; i < intLen; i++) {
+    if (i > 0 && (i === firstGroup || (i > firstGroup && (i - firstGroup) % 3 === 0))) {
+      for (let j = 0; j < g.length; j++) {
+        out[p++] = g[j]
+      }
+    }
+
+    out[p++] = s[i]
+  }
+
+  // fractional part
+  if (fracLen > 0) {
+    for (let j = 0; j < d.length; j++) {
+      out[p++] = d[j]
+    }
+
+    for (let i = dot + 1; i < s.length; i++) {
+      out[p++] = s[i]
+    }
+  }
+
+  return out.join("")
 }
 
 // tslint:disable-next-line:class-name
 export class formatter {
   // private static _preg = / |\+|\-|\.|\(|\)/g;
-  static fax = / |\-|\.|\(|\)/g
-  static phone = / |\-|\.|\(|\)/g
+  // static fax = / |\-|\.|\(|\)/g
+  // static phone = / |\-|\.|\(|\)/g
   static usPhone = /(\d{3})(\d{3})(\d{4})/
   static formatPhone(phone?: string | null): string {
     if (!phone) {
@@ -182,7 +263,7 @@ export class formatter {
     // reformat phone number
     // 555 123-4567 or (+1) 555 123-4567
     let s = phone
-    const x = removePhoneFormat(phone)
+    const x = normalizePhone(phone)
     if (x.length === 10) {
       const USNumber = x.match(formatter.usPhone)
       if (USNumber != null) {
@@ -208,7 +289,7 @@ export class formatter {
     // reformat phone number
     // 035-456745 or 02-1234567
     let s = fax
-    const x = removePhoneFormat(fax)
+    const x = normalizeFax(fax)
     const l = x.length
     if (l <= 6) {
       s = x
@@ -230,11 +311,23 @@ export class formatter {
     return s
   }
 }
-export function removePhoneFormat(phone?: string): string {
-  return phone ? phone.replace(formatter.phone, "") : ""
+export function normalizePhone(s?: string | null): string {
+  if (!s) {
+    return ""
+  }
+  const len = s.length
+  const buf = new Array<string>(len)
+  let j = 0
+  for (let i = 0; i < len; i++) {
+    const c = s.charCodeAt(i)
+    if ((c >= 48 && c <= 57) || c === 43) {
+      buf[j++] = s[i]
+    }
+  }
+  return j === len ? buf.join("") : buf.slice(0, j).join("")
 }
-export function removeFaxFormat(fax?: string): string {
-  return fax ? fax.replace(formatter.fax, "") : ""
+export function normalizeFax(fax?: string): string {
+  return normalizePhone(fax)
 }
 export function formatPhone(phone?: string | null): string {
   return formatter.formatPhone(phone)