dot-net-date-number-formatting

A TypeScript library that provides .NET-compatible date/time and numeric formatting for JavaScript/TypeScript applications. This library implements format string parsing and formatting similar to Microsoft's .NET Framework, enabling cross-platform compatibility for applications that need to maintain consistent formatting between .NET and JavaScript/TypeScript.

Overview

This library provides three main components:

• DateTime Formatting - Format dates using .NET standard and custom date/time format strings
• Numeric Formatting - Format numbers using .NET standard and custom numeric format strings
• Number Parsing - Parse numbers with configurable style requirements (hex, currency, thousands separators, etc.)

Built on top of JavaScript's Intl API for locale-aware formatting while maintaining compatibility with .NET format string syntax.

Installation

npm install @pbkware/dot-net-date-number-formatting

Quick Start

DateTime Formatting

import { DotNetDateTimeFormatter, DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';

const formatter = new DotNetDateTimeFormatter();
formatter.localeSettings = DotNetLocaleSettings.createInvariant();

// Standard format
formatter.trySetFormat('d');  // Short date
console.log(formatter.toString(new Date(2024, 6, 5)));  // "7/5/2024"

// Custom format
formatter.trySetFormat('yyyy-MM-dd HH:mm:ss');
console.log(formatter.toString(new Date(2024, 6, 5, 14, 30, 0)));  // "2024-07-05 14:30:00"

Numeric Formatting

import { DotNetFloatFormatter, DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';

const formatter = new DotNetFloatFormatter();
formatter.localeSettings = DotNetLocaleSettings.createInvariant();

// Currency format
formatter.trySetFormat('C2');
console.log(formatter.toString(1234.56));  // "$1,234.56"

// Custom format
formatter.trySetFormat('#,##0.00');
console.log(formatter.toString(1234.56));  // "1,234.56"

Number Parsing

import { DotNetFloatFormatter, DotNetNumberStyles } from '@pbkware/dot-net-date-number-formatting';

const formatter = new DotNetFloatFormatter();
formatter.styles = DotNetNumberStyles.number;

const result = formatter.tryFromString('1,234.56');
if (result.isOk()) {
  console.log(result.value);  // 1234.56
}

Documentation

Comprehensive documentation is available at library website

Use Cases

• Cross-platform applications - Maintain consistent formatting between .NET backends and JavaScript/TypeScript frontends
• Data export/import - Format data for consistent serialization across platforms
• Multi-locale applications - Support users in different regions with locale-aware formatting
• Financial applications - Format currency and numeric values with precise control
• Report generation - Create formatted reports with .NET-compatible output
• Round trip formatting/parsing - Formatting and then parsing a value with the same format string will return the same value.

Features

DateTime Formatting

• ✅ All standard date/time format strings (d, D, f, F, g, G, M, O, s, t, T, u, Y)
• ✅ Custom format strings with day, month, year, hour, minute, second specifiers
• ✅ Fractional seconds (f, F)
• ✅ AM/PM designators
• ✅ Literal text in format strings
• ⚠️ Limited time zone support

Numeric Formatting

• ✅ All standard numeric format strings (C, D, E, F, G, N, P, R, X, B)
• ✅ Custom format strings with digit placeholders (0, #)
• ✅ Section separators for positive/negative/zero values
• ✅ Thousands separators and number scaling
• ✅ Percentage and per mille formatting
• ✅ Scientific notation
• ✅ Hexadecimal and binary formats

Number Parsing

• ✅ Configurable parsing styles (whitespace, signs, parentheses, etc.)
• ✅ Currency symbol support
• ✅ Thousands separator support
• ✅ Exponential notation
• ✅ Hexadecimal parsing

Downloads

• npm package
• GitHub repository

License

See LICENSE file for details.

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Generate documentation
npm run docs:build

Support

For issues, questions, or contributions, please visit the GitHub repository.

Recent Releases

• 0.3.0
  Rename and rework DotNetNumberStyles and DotNetDateTimeStyles so that they are const objects instead of enums and better align with Dot Net equivalents.

History

This library was created by porting the relevant portions of the Delphi library TFieldedText (at SourceForge) (Note that the commit attributions are incorrect in TFieldedText - they should be attributed to Paul Klink.) The porting and documentation was carried out with AI (GitHub co-pilot).

Contributing

Contributions are welcome! Please ensure all tests pass before submitting pull requests.