@f-o-t/money 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -0,0 +1,258 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.1] - 2026-02-02
+
+### Fixed
+
+- Fixed TypeScript declaration generation OOM (exit code 134) by decoupling operators from comparison module
+- Root cause: duplicate Zod installations caused exponential type expansion during structural compatibility checks
+
+### Changed
+
+- Moved condition-evaluator operators from `operations/comparison.ts` to `plugins/operators/`
+- Made `@f-o-t/condition-evaluator` an optional peer dependency
+- Main library no longer imports from `@f-o-t/condition-evaluator`
+- Removed `isolatedDeclarations` and `maxMemory` workaround from build config
+
+## [1.2.0] - 2026-02-01
+
+### Changed
+
+- **Internal refactor**: Migrated to `@f-o-t/bigint` ^1.0.0 for bigint operations
+  - `parseDecimalToMinorUnits` now uses `parseToBigInt` from @f-o-t/bigint
+  - `minorUnitsToDecimal` now uses `formatFromBigInt` from @f-o-t/bigint
+  - `bankersRound` now imported from @f-o-t/bigint
+  - `roundToScale` now uses `convertScale` from @f-o-t/bigint
+- **Note**: This is an internal refactor with no breaking changes to public APIs
+- **Benefit**: Standardized bigint operations across all FOT libraries
+
+### Dependencies
+
+- Added `@f-o-t/bigint` ^1.0.0
+
+## [1.1.1] - 2026-01-25
+
+### Changed
+
+- Updated dependencies to latest versions
+
+## [1.1.0] - 2025-12-25
+
+### Added
+
+#### Rounding Mode Support
+- `ofRounded()` - New factory function that rounds excess decimal places using banker's rounding
+- `RoundingMode` type - `"truncate" | "round"` for controlling decimal handling
+- Optional third parameter for `of()` to specify rounding mode: `of("10.999", "USD", "round")`
+
+#### Precision-Safe Conversion
+- `toMajorUnitsString()` - Convert Money to major units as a string without precision loss
+- Safe formatting for very large amounts (>15 significant digits) that would lose precision with float conversion
+
+#### Scale Validation
+- `ScaleMismatchError` - New error thrown when operating on Money values with inconsistent scales
+- `assertSameCurrency()` now validates both currency AND scale consistency
+- `assertAllSameCurrency()` now validates scale consistency across all values
+
+### Changed
+
+#### Banker's Rounding Fix
+- Fixed banker's rounding algorithm for odd divisors
+- Previously used truncated half comparison which could produce incorrect results
+- Now uses `remainder * 2 === divisor` for accurate halfway detection
+
+#### Allocation Precision
+- Improved ratio precision in `allocate()` by using string-based parsing instead of `Math.round`
+- Eliminates floating-point errors for extreme ratio values (very small or very large)
+
+#### Parse Validation
+- `parse()` now throws `InvalidAmountError` on malformed input with multiple decimal separators
+- Previously would silently accept invalid formats like "1.234.56"
+
+#### Input Precision Warnings
+- `of()` now warns when passed a number with likely floating-point precision issues
+- Detects patterns like `0.1 + 0.2` that produce imprecise results
+- Encourages use of string amounts for precision-critical values
+
+### Deprecated
+
+- `toMajorUnits()` - Use `toMajorUnitsString()` for precision-safe conversion
+  - Still works but logs a warning for amounts exceeding safe integer range
+
+### Fixed
+
+- Banker's rounding for odd divisors now correctly rounds to even
+- Large amount formatting no longer loses precision due to float conversion
+- Allocation with extreme ratios now preserves full precision
+
+---
+
+## [1.0.0] - 2024-12-24
+
+### Added
+
+#### Core Features
+- BigInt-based money representation for exact precision arithmetic
+- Immutable `Money` type with `amount` (BigInt), `currency` (string), and `scale` (number) properties
+- Support for all ISO 4217 currencies with correct decimal places
+- Type-safe operations with full TypeScript support
+
+#### Factory Functions
+- `of()` - Create Money from major units (dollars, euros, etc.) as string or number
+- `fromMajorUnits()` - Alias for `of()` for semantic clarity
+- `fromMinorUnits()` - Create Money from minor units (cents, pence, etc.)
+- `zero()` - Create zero-value Money for a given currency
+
+#### Arithmetic Operations
+- `add()` - Add two Money values (throws on currency mismatch)
+- `subtract()` - Subtract Money values
+- `multiply()` - Multiply Money by scalar (number or string for precision)
+- `divide()` - Divide Money by scalar using banker's rounding
+- `percentage()` - Calculate percentage of Money value
+- `negate()` - Negate Money value
+- `absolute()` - Get absolute value of Money
+
+#### Comparison Operations
+- `equals()` - Check equality
+- `greaterThan()`, `greaterThanOrEqual()` - Greater than comparisons
+- `lessThan()`, `lessThanOrEqual()` - Less than comparisons
+- `isPositive()`, `isNegative()`, `isZero()` - Value state checks
+- `compare()` - Three-way comparison (-1, 0, 1)
+
+#### Allocation
+- `allocate()` - Distribute Money by ratios using largest remainder method
+- `split()` - Split Money evenly into N parts with fair remainder distribution
+- Guarantees sum of allocated parts equals original amount
+
+#### Aggregation
+- `sum()` - Sum array of Money values
+- `sumOrZero()` - Sum with safe handling of empty arrays
+- `min()`, `max()` - Find minimum/maximum values
+- `average()` - Calculate average with banker's rounding
+- `median()` - Calculate median value
+
+#### Formatting
+- `format()` - Format Money with locale support (Intl.NumberFormat)
+- `formatCompact()` - Format with compact notation for large amounts
+- `formatAmount()` - Format amount only without currency symbol
+- `toDecimal()` - Convert to plain decimal string
+- Support for locale-specific formatting (en-US, pt-BR, ja-JP, etc.)
+- Configurable format options (notation, sign display, currency display, etc.)
+
+#### Parsing
+- `parse()` - Parse formatted strings to Money values
+- Support for multiple locale formats
+- Handle negative amounts (both parentheses and minus sign notation)
+- Automatic removal of currency symbols and thousands separators
+
+#### Serialization
+- `toJSON()`, `fromJSON()` - JSON serialization with `{ amount: string, currency: string }` format
+- `toDatabase()`, `fromDatabase()` - Database storage (alias for JSON methods)
+- `serialize()`, `deserialize()` - String serialization with "amount currency" format
+- `toMinorUnits()` - Convert to number (throws on overflow)
+- `toMinorUnitsBigInt()` - Convert to BigInt
+- `toMajorUnits()` - Convert to decimal number
+- `toMinorUnitsString()` - Convert to string representation
+
+#### Currency Registry
+- `getCurrency()` - Get currency metadata (symbol, decimal places, name)
+- `hasCurrency()` - Check if currency exists
+- `registerCurrency()` - Register custom currencies
+- `getAllCurrencies()` - Get all registered currencies
+- `clearCustomCurrencies()` - Clear custom currencies (useful for testing)
+- `ISO_4217_CURRENCIES` - Complete ISO 4217 currency data
+- Case-insensitive currency code handling
+
+#### Validation
+- Zod schemas for all types:
+  - `MoneySchema` - JSON representation validation
+  - `MoneyInputSchema` - User input validation (accepts string or number)
+  - `MoneyInternalSchema` - Internal Money representation
+  - `CurrencyCodeSchema` - ISO 4217 currency code validation
+  - `CurrencySchema` - Currency definition validation
+  - `DatabaseMoneySchema` - Database storage validation
+  - `AllocationRatiosSchema` - Allocation ratios validation
+  - `FormatOptionsSchema` - Format options validation
+
+#### Error Handling
+- `MoneyError` - Base error class
+- `CurrencyMismatchError` - Thrown when operating on different currencies
+- `InvalidAmountError` - Thrown for invalid amount values
+- `DivisionByZeroError` - Thrown when dividing by zero
+- `UnknownCurrencyError` - Thrown for unregistered currencies
+- `OverflowError` - Thrown when converting BigInt to unsafe number
+
+#### Condition Evaluator Integration
+- `@f-o-t/money/operators` export for condition evaluator integration
+- Money operators:
+  - `money_eq`, `money_neq` - Equality checks
+  - `money_gt`, `money_gte`, `money_lt`, `money_lte` - Comparisons
+  - `money_between` - Range checks
+  - `money_positive`, `money_negative`, `money_zero` - State checks
+- Seamless integration with `@f-o-t/condition-evaluator` package
+
+#### Low-Level Utilities
+- `bankersRound()` - Banker's rounding (round half to even)
+- `createMoney()` - Direct Money creation (bypasses validation)
+- `parseDecimalToMinorUnits()` - Parse decimal string to BigInt
+- `minorUnitsToDecimal()` - Convert BigInt to decimal string
+- `assertSameCurrency()` - Assert two Money values have same currency
+- `assertAllSameCurrency()` - Assert all Money values in array have same currency
+- Constants: `EXTENDED_PRECISION`, `PRECISION_FACTOR`
+
+#### Developer Experience
+- Zero runtime dependencies (only Zod for validation)
+- Full TypeScript type safety
+- Immutable data structures (frozen objects)
+- Comprehensive test suite with 100% coverage
+- Performance benchmarks included
+- JSDoc comments for all public APIs
+
+### Technical Details
+
+#### Precision
+- Uses BigInt for all internal calculations
+- Extended precision for intermediate calculations (6 decimal places)
+- Banker's rounding (IEEE 754) for division and averaging
+- Guarantees exact results for all arithmetic operations
+
+#### Currency Handling
+- Automatic decimal place handling based on ISO 4217
+- Support for 0-decimal currencies (JPY, KRW)
+- Support for 3-decimal currencies (KWD, BHD, OMR)
+- Support for 4-decimal currencies (CLF)
+- Case-insensitive currency code input (normalized to uppercase)
+
+#### Performance
+- Optimized for high-frequency operations
+- Formatter caching for repeated format operations
+- Minimal object allocations
+- Benchmarks included in test suite:
+  - 10,000 Money creations: < 500ms
+  - 10,000 additions: < 200ms
+  - 10,000 comparisons: < 100ms
+
+#### Package Exports
+- Main export: `@f-o-t/money` - All core functionality
+- Operators export: `@f-o-t/money/operators` - Condition evaluator operators
+- Package.json export: `@f-o-t/money/package.json`
+
+### Dependencies
+
+- `zod` (^4.1.13) - Schema validation
+- `@f-o-t/condition-evaluator` (workspace) - Operator integration
+
+### Peer Dependencies
+
+- `typescript` (>=4.5.0) - Optional for type checking
+
+[1.2.1]: https://github.com/F-O-T/libraries/releases/tag/@f-o-t/money@1.2.1
+[1.2.0]: https://github.com/F-O-T/libraries/releases/tag/@f-o-t/money@1.2.0
+[1.1.1]: https://github.com/F-O-T/libraries/releases/tag/@f-o-t/money@1.1.1
+[1.1.0]: https://github.com/F-O-T/libraries/releases/tag/@f-o-t/money@1.1.0
+[1.0.0]: https://github.com/F-O-T/libraries/releases/tag/@f-o-t/money@1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FOT (F-O-T)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -482,6 +482,153 @@ const result = evaluator.evaluate(
 // - money_positive, money_negative, money_zero
 ```
 
+### Rules Engine Integration
+
+Use money operators with `@f-o-t/rules-engine` to build complex financial business rules:
+
+```typescript
+import { createEngine } from "@f-o-t/rules-engine";
+import { moneyOperators } from "@f-o-t/money/plugins/operators";
+import { z } from "zod";
+
+// Define consequence types for your rules
+const TransactionConsequences = {
+  approve: z.object({ approved: z.boolean() }),
+  require_review: z.object({ reason: z.string() }),
+  reject: z.object({ reason: z.string() }),
+  apply_fee: z.object({ amount: z.string(), currency: z.string() }),
+};
+
+// Create engine with money operators
+const engine = createEngine({
+  operators: moneyOperators,
+  consequences: TransactionConsequences,
+});
+
+// Add rules for high-value transactions
+engine.addRule({
+  name: "high-value-transaction-review",
+  priority: 100,
+  conditions: {
+    id: "g1",
+    operator: "AND",
+    conditions: [
+      {
+        id: "c1",
+        type: "custom",
+        field: "amount",
+        operator: "money_gt",
+        value: { amount: "10000.00", currency: "BRL" },
+      },
+    ],
+  },
+  consequences: [
+    {
+      type: "require_review",
+      payload: { reason: "High value transaction requires approval" },
+    },
+  ],
+});
+
+// Add rules for transaction fees
+engine.addRule({
+  name: "pix-fee-waiver",
+  priority: 50,
+  conditions: {
+    id: "g2",
+    operator: "AND",
+    conditions: [
+      {
+        id: "c1",
+        type: "string",
+        field: "paymentMethod",
+        operator: "eq",
+        value: "pix",
+      },
+      {
+        id: "c2",
+        type: "custom",
+        field: "amount",
+        operator: "money_lt",
+        value: { amount: "100.00", currency: "BRL" },
+      },
+    ],
+  },
+  consequences: [
+    {
+      type: "apply_fee",
+      payload: { amount: "0.00", currency: "BRL" },
+    },
+  ],
+});
+
+// Evaluate rules
+const result = await engine.evaluate({
+  amount: { amount: "15000.00", currency: "BRL" },
+  paymentMethod: "pix",
+});
+
+console.log(result.matchedRules);    // Rules that matched
+console.log(result.consequences);    // Actions to take
+```
+
+**Complex multi-condition rules:**
+
+```typescript
+// Discount eligibility with money conditions
+engine.addRule({
+  name: "volume-discount",
+  conditions: {
+    id: "g1",
+    operator: "AND",
+    conditions: [
+      {
+        id: "c1",
+        type: "custom",
+        field: "cartTotal",
+        operator: "money_between",
+        value: [
+          { amount: "500.00", currency: "BRL" },
+          { amount: "2000.00", currency: "BRL" },
+        ],
+      },
+      {
+        id: "c2",
+        type: "custom",
+        field: "customerLifetimeValue",
+        operator: "money_gt",
+        value: { amount: "5000.00", currency: "BRL" },
+      },
+      {
+        id: "c3",
+        type: "boolean",
+        field: "isPremiumMember",
+        operator: "eq",
+        value: true,
+      },
+    ],
+  },
+  consequences: [
+    {
+      type: "apply_discount",
+      payload: { percentage: 15 },
+    },
+  ],
+});
+```
+
+**Available money operators for rules:**
+- `money_eq` - Equal to
+- `money_neq` - Not equal to  
+- `money_gt` - Greater than
+- `money_gte` - Greater than or equal
+- `money_lt` - Less than
+- `money_lte` - Less than or equal
+- `money_between` - Between two values (inclusive)
+- `money_positive` - Is positive (> 0)
+- `money_negative` - Is negative (< 0)
+- `money_zero` - Is zero
+
 ### Custom Currencies
 
 Register currencies not in ISO 4217: