chore: bump version to 0.3.1-alpha.0 and update formatCurrency default currency to USD

Ivanmw97 · Ivanmw97 · commit c8152d3f8ad3 · 2026-02-21T20:15:16.000Z
- Change formatCurrency default currency from EUR to USD across all platforms (TypeScript, Kotlin, Dart)
- Add validation to throw on NaN/Infinity amounts in formatCurrency (RangeError in TypeScript, IllegalArgumentException in Kotlin, ArgumentError in Dart)
- Update all version references from 0.3.0-alpha to 0.3.1-alpha.0 across README, docs, package files, and SECURITY.md
- Update formatCurrency examples
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # KompKit
 
-[![Version](https://img.shields.io/badge/version-0.3.0--alpha.0-orange.svg)](https://github.com/Kompkit/KompKit/releases)
+[![Version](https://img.shields.io/badge/version-0.3.1--alpha.0-orange.svg)](https://github.com/Kompkit/KompKit/releases)
 [![Web CI](https://github.com/Kompkit/KompKit/actions/workflows/web.yml/badge.svg?branch=develop)](https://github.com/Kompkit/KompKit/actions/workflows/web.yml)
 [![Kotlin CI](https://github.com/Kompkit/KompKit/actions/workflows/android.yml/badge.svg?branch=develop)](https://github.com/Kompkit/KompKit/actions/workflows/android.yml)
 [![Flutter CI](https://github.com/Kompkit/KompKit/actions/workflows/flutter.yml/badge.svg?branch=develop)](https://github.com/Kompkit/KompKit/actions/workflows/flutter.yml)
@@ -95,7 +95,7 @@ Add to your `pubspec.yaml`:
 
 ```yaml
 dependencies:
-  kompkit_core: ^0.3.0-alpha.1
+  kompkit_core: ^0.3.1-alpha.0
 ```
 
 Then run:
@@ -211,7 +211,7 @@ KompKit/
 
 ## Version Information
 
-- **Current Version**: `0.3.0-alpha`
+- **Current Version**: `0.3.1-alpha`
 - **Minimum Requirements**:
   - Node.js 20+ (Web)
   - JDK 17+ (Android)
@@ -225,7 +225,7 @@ KompKit/
 KompKit is currently in **alpha**. This means:
 
 - **APIs may change** between alpha versions without a deprecation period.
-- **Pin to exact versions** in production: `"kompkit-core": "0.3.0-alpha.1"` / `kompkit_core: 0.3.0-alpha.1`.
+- **Pin to exact versions** in production: `"kompkit-core": "0.3.1-alpha.0"` / `kompkit_core: 0.3.1-alpha.0`.
 - **Breaking changes** will be documented in [CHANGELOG.md](./docs/CHANGELOG.md) with migration notes.
 - Once `1.0.0` is released, the project will follow strict [Semantic Versioning](https://semver.org/): breaking changes only in major versions.
 
diff --git a/SECURITY.md b/SECURITY.md
@@ -4,7 +4,8 @@
 
 | Version         | Supported              |
 | --------------- | ---------------------- |
-| `0.3.0-alpha.1` | ✅ Current             |
+| `0.3.1-alpha.0` | ✅ Current             |
+| `0.3.0-alpha.1` | ❌ No longer supported |
 | `0.2.0-alpha.0` | ❌ No longer supported |
 | `0.1.0-alpha`   | ❌ No longer supported |
 
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1-alpha.0] - 2026-02-20
+
+### Changed
+
+- **`formatCurrency` default currency**: Changed from `EUR` to `USD` across all platforms (TypeScript, Kotlin, Dart)
+- **`formatCurrency` finite validation**: Added validation that throws on `NaN` and `Infinity` amounts across all platforms
+  - TypeScript: throws `RangeError`
+  - Kotlin: throws `IllegalArgumentException`
+  - Dart: throws `ArgumentError`
+- **Documentation**: Corrected `formatCurrency` examples to reflect `USD` default
+- **Documentation**: Added Platform Differences section to npm README documenting Dart single-argument debounce limitation and other divergences
+- **Packaging**: Clarified that `kompkit-core` ships both ESM and CommonJS builds (not ESM-only)
+
+### Fixed
+
+- Documentation inconsistency where examples showed `USD` but default was `EUR`
+
 ## [0.3.0-alpha] - 2026-02-09
 
 ### Changed
diff --git a/docs/android.md b/docs/android.md
@@ -2,7 +2,7 @@
 
 KompKit Core provides small utilities for Android applications written in Kotlin.
 
-Status: `V0.3.0-alpha`.
+Status: `V0.3.1-alpha`.
 
 ## Installation
 
diff --git a/docs/flutter.md b/docs/flutter.md
@@ -2,7 +2,7 @@
 
 This guide covers using KompKit Core utilities in Flutter and Dart applications.
 
-Status: `V0.3.0-alpha`.
+Status: `V0.3.1-alpha`.
 
 ## Installation
 
@@ -12,7 +12,7 @@ Add KompKit Core to your `pubspec.yaml`:
 
 ```yaml
 dependencies:
-  kompkit_core: ^0.3.0-alpha.1
+  kompkit_core: ^0.3.1-alpha.0
 ```
 
 Then run:
@@ -29,7 +29,7 @@ For server-side Dart projects, add to your `pubspec.yaml`:
 
 ```yaml
 dependencies:
-  kompkit_core: ^0.3.0-alpha.1
+  kompkit_core: ^0.3.1-alpha.0
 ```
 
 Then run:
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -2,7 +2,7 @@
 
 KompKit Core is a small cross-platform utility library for Web (TypeScript), Android (Kotlin), and Flutter (Dart).
 
-Status: `V0.3.0-alpha`.
+Status: `V0.3.1-alpha`.
 
 ## Install
 
@@ -20,7 +20,7 @@ Add to your `pubspec.yaml`:
 
 ```yaml
 dependencies:
-  kompkit_core: ^0.3.0-alpha.1
+  kompkit_core: ^0.3.1-alpha.0
 ```
 
 Then run:
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -1,6 +1,6 @@
 # Roadmap
 
-## Current State — `0.3.0-alpha.1`
+## Current State — `0.3.1-alpha.0`
 
 KompKit Core is in early alpha. The current release includes:
 
@@ -10,7 +10,7 @@ KompKit Core is in early alpha. The current release includes:
 - **Full CI/CD** with path-based workflow optimization
 - **Cancel support** on `debounce` across all platforms
 
-## Next: `0.3.0-alpha`
+## Next: `0.3.1-alpha`
 
 Focus: utility expansion and Android publishing.
 
diff --git a/docs/web.md b/docs/web.md
@@ -2,7 +2,7 @@
 
 KompKit Core provides small, framework-agnostic utilities for web applications written in TypeScript.
 
-Status: `V0.3.0-alpha`.
+Status: `V0.3.1-alpha`.
 
 ## Installation
 
diff --git a/lerna.json b/lerna.json
@@ -1,5 +1,5 @@
 {
-  "version": "0.3.0-alpha.1",
+  "version": "0.3.1-alpha.0",
   "npmClient": "npm",
   "packages": ["packages/core/web"],
   "command": {
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "kompkit",
-  "version": "0.3.0-alpha",
+  "version": "0.3.1-alpha",
   "description": "A lightweight cross-platform utility kit for Web (TypeScript), Android (Kotlin), and Flutter (Dart): debounce, isEmail, formatCurrency",
   "private": true,
   "workspaces": [
diff --git a/packages/core/android/src/main/kotlin/com/kompkit/core/Format.kt b/packages/core/android/src/main/kotlin/com/kompkit/core/Format.kt
@@ -11,28 +11,32 @@ import java.util.Locale
  * to a [Locale] as required by the JVM — callers do not need to construct [Locale] objects
  * directly.
  *
- * Throws [IllegalArgumentException] if [currency] is not a valid ISO 4217 code. Locale strings are
- * parsed leniently by the JVM; an unrecognized locale falls back to the root locale rather than
- * throwing.
+ * Throws [IllegalArgumentException] if [amount] is not finite (NaN or Infinity), or if [currency]
+ * is not a valid ISO 4217 code. Locale strings are parsed leniently by the JVM; an unrecognized
+ * locale falls back to the root locale rather than throwing.
  *
- * @param amount The numeric amount to format.
- * @param currency ISO 4217 currency code (e.g., "USD", "EUR", "JPY"). Defaults to "EUR".
+ * @param amount The numeric amount to format. Must be finite.
+ * @param currency ISO 4217 currency code (e.g., "USD", "EUR", "JPY"). Defaults to "USD".
  * @param locale BCP 47 locale string (e.g., "en-US", "es-ES"). Defaults to "en-US".
  * @return A formatted currency string.
- * @throws IllegalArgumentException if [currency] is not a valid ISO 4217 code.
+ * @throws IllegalArgumentException if [amount] is NaN or Infinity, or if [currency] is not a valid
+ * ISO 4217 code.
  *
  * @sample
  * ```kotlin
- * formatCurrency(1234.56)                        // "$1,234.56" (en-US default)
+ * formatCurrency(1234.56)                        // "$1,234.56" (en-US / USD default)
  * formatCurrency(1234.56, "EUR", "es-ES")        // "1.234,56 €"
  * formatCurrency(1000.0, "JPY", "ja-JP")         // "¥1,000"
  * ```
  */
 fun formatCurrency(
         amount: Double,
-        currency: String = "EUR",
+        currency: String = "USD",
         locale: String = "en-US",
 ): String {
+        if (!amount.isFinite()) {
+                throw IllegalArgumentException("Invalid amount: $amount. Must be a finite number.")
+        }
         val jvmLocale = Locale.forLanguageTag(locale)
         val currencyInstance =
                 runCatching { Currency.getInstance(currency) }.getOrElse {
diff --git a/packages/core/android/src/test/kotlin/com/kompkit/core/CoreTests.kt b/packages/core/android/src/test/kotlin/com/kompkit/core/CoreTests.kt
@@ -42,7 +42,7 @@ class FormatCurrencyTests {
   fun defaultLocaleIsEnUs() {
     val result = formatCurrency(1234.56)
     assertTrue(result.contains("1,234.56"), "Expected en-US formatted number, got: $result")
-    assertTrue(result.contains("€"), "Expected EUR symbol, got: $result")
+    assertTrue(result.contains("$"), "Expected USD symbol, got: $result")
   }
 
   @Test
@@ -82,6 +82,17 @@ class FormatCurrencyTests {
     assertFailsWith<IllegalArgumentException> { formatCurrency(100.0, "INVALID", "en-US") }
   }
 
+  @Test
+  fun throwsForNaNAmount() {
+    assertFailsWith<IllegalArgumentException> { formatCurrency(Double.NaN) }
+  }
+
+  @Test
+  fun throwsForInfinityAmount() {
+    assertFailsWith<IllegalArgumentException> { formatCurrency(Double.POSITIVE_INFINITY) }
+    assertFailsWith<IllegalArgumentException> { formatCurrency(Double.NEGATIVE_INFINITY) }
+  }
+
   @Test
   fun unrecognizedLocaleFallsBackGracefully() {
     // JVM Locale.forLanguageTag is lenient — unknown locales fall back to root locale.
diff --git a/packages/core/flutter/CHANGELOG.md b/packages/core/flutter/CHANGELOG.md
@@ -1,6 +1,6 @@
 # Changelog
 
-## 0.3.0-alpha.1
+## 0.3.1-alpha.0
 
 - Initial alpha release of `kompkit_core` for Flutter/Dart
 - **debounce** — Delay function execution with cancellation (`debounce<T>`, `debounceVoid`)
diff --git a/packages/core/flutter/README.md b/packages/core/flutter/README.md
@@ -8,7 +8,7 @@ Add to your `pubspec.yaml`:
 
 ```yaml
 dependencies:
-  kompkit_core: ^0.3.0-alpha.1
+  kompkit_core: ^0.3.1-alpha.0
 ```
 
 > Published on [pub.dev/packages/kompkit_core](https://pub.dev/packages/kompkit_core)
diff --git a/packages/core/flutter/lib/src/format.dart b/packages/core/flutter/lib/src/format.dart
@@ -6,33 +6,36 @@ import 'package:intl/intl.dart';
 /// The `intl` package uses underscore-separated locale identifiers internally;
 /// hyphens are converted automatically.
 ///
-/// Throws [ArgumentError] if [currency] is not a valid ISO 4217 code or
-/// [locale] is not a recognized locale — consistent with TypeScript and Kotlin behavior.
+/// Throws [ArgumentError] if [amount] is not finite (NaN or Infinity), [currency] is not a valid
+/// ISO 4217 code, or [locale] is not a recognized locale — consistent with TypeScript and Kotlin.
 ///
 /// **Parameters:**
-/// - [amount] - The numeric amount to format (supports both int and double)
-/// - [currency] - ISO 4217 currency code (e.g., "USD", "EUR", "JPY"). Defaults to "EUR"
+/// - [amount] - The numeric amount to format (supports both int and double). Must be finite.
+/// - [currency] - ISO 4217 currency code (e.g., "USD", "EUR", "JPY"). Defaults to "USD"
 /// - [locale] - BCP 47 locale string (e.g., "en-US", "es-ES", "ja-JP"). Defaults to "en-US"
 ///
 /// **Returns:** A formatted currency string according to the specified locale
-/// @throws [ArgumentError] if [currency] or [locale] is invalid.
+/// @throws [ArgumentError] if [amount] is NaN or Infinity, or if [currency] or [locale] is invalid.
 ///
 /// **Example:**
 /// ```dart
-/// formatCurrency(1234.56);                                    // "$1,234.56" (en-US default)
+/// formatCurrency(1234.56);                                    // "$1,234.56" (en-US / USD default)
 /// formatCurrency(1234.56, currency: "EUR", locale: "es-ES"); // "1.234,56 €"
 /// formatCurrency(1000, currency: "JPY", locale: "ja-JP");    // "¥1,000"
 /// formatCurrency(999.99, currency: "GBP", locale: "en-GB");  // "£999.99"
-/// formatCurrency(-50.25, currency: "USD", locale: "en-US");  // "-$50.25"
+/// formatCurrency(double.nan);                                 // throws ArgumentError
 /// ```
 /// ISO 4217 currency codes are exactly 3 uppercase ASCII letters.
 final _currencyCodeRe = RegExp(r'^[A-Z]{3}$');
 
 String formatCurrency(
   num amount, {
-  String currency = "EUR",
+  String currency = "USD",
   String locale = "en-US",
 }) {
+  if (amount is double && !amount.isFinite) {
+    throw ArgumentError('Invalid amount: $amount. Must be a finite number.');
+  }
   if (!_currencyCodeRe.hasMatch(currency)) {
     throw ArgumentError('Invalid currency code: "$currency". Expected a 3-letter ISO 4217 code.');
   }
diff --git a/packages/core/flutter/pubspec.yaml b/packages/core/flutter/pubspec.yaml
@@ -1,6 +1,6 @@
 name: kompkit_core
 description: Cross-platform utility functions for Flutter and Dart applications. Part of the KompKit ecosystem.
-version: 0.3.0-alpha.1
+version: 0.3.1-alpha.0
 homepage: https://github.com/Kompkit/KompKit
 repository: https://github.com/Kompkit/KompKit
 issue_tracker: https://github.com/Kompkit/KompKit/issues
diff --git a/packages/core/flutter/test/format_test.dart b/packages/core/flutter/test/format_test.dart
@@ -3,10 +3,10 @@ import '../lib/src/format.dart';
 
 void main() {
   group('formatCurrency', () {
-    test('default locale is en-US with EUR', () {
+    test('default locale is en-US with USD', () {
       final result = formatCurrency(1234.56);
       expect(result, contains('1,234.56'));
-      expect(result, contains('EUR'));
+      expect(result, contains('USD'));
     });
 
     test('formats USD with en-US locale using BCP 47 string', () {
@@ -55,6 +55,24 @@ void main() {
       );
     });
 
+    test('throws ArgumentError for NaN amount', () {
+      expect(
+        () => formatCurrency(double.nan),
+        throwsArgumentError,
+      );
+    });
+
+    test('throws ArgumentError for Infinity amount', () {
+      expect(
+        () => formatCurrency(double.infinity),
+        throwsArgumentError,
+      );
+      expect(
+        () => formatCurrency(double.negativeInfinity),
+        throwsArgumentError,
+      );
+    });
+
     test('throws ArgumentError for invalid locale', () {
       // intl's NumberFormat throws on unrecognized locales via verifiedLocale().
       // This is caught and re-thrown as ArgumentError.
diff --git a/packages/core/web/README.md b/packages/core/web/README.md
diff --git a/packages/core/web/package.json b/packages/core/web/package.json
diff --git a/packages/core/web/src/format.ts b/packages/core/web/src/format.ts
diff --git a/packages/core/web/tests/core.test.ts b/packages/core/web/tests/core.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "version": "0.3.0-alpha.1",`
	`2`	`+ "version": "0.3.1-alpha.0",`
`3`	`3`	`"npmClient": "npm",`
`4`	`4`	`"packages": ["packages/core/web"],`
`5`	`5`	`"command": {`