@jdsalasc/solvejs-money 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,6 +3,8 @@
3
3
  [![npm](https://img.shields.io/npm/v/@jdsalasc/solvejs-money)](https://www.npmjs.com/package/@jdsalasc/solvejs-money)
4
4
  [![node](https://img.shields.io/node/v/@jdsalasc/solvejs-money)](https://www.npmjs.com/package/@jdsalasc/solvejs-money)
5
5
 
6
+ > **Live documentation:** [run this package's examples in your browser](https://jdsalasca.github.io/solvejs/live/#pkg-money).
7
+
6
8
  Zero-dependency money math in integer minor units: exact addition, percentages, allocation without lost cents, and currency-aware formatting. No floating-point rounding surprises in invoices, payments, or tax calculations.
7
9
 
8
10
  ## Utilities
@@ -122,8 +124,8 @@ configuration mistake, and guessing a locale would hide it. `MoneyError` covers
122
124
  ### Weights must be non-negative whole numbers
123
125
 
124
126
  `allocateAmount` refuses negative, fractional and all-zero weights, because there is no sensible way
125
- to split an amount among them. Pass a percentage as an integer like `20` for twenty percent.
126
-
127
- ## Review notes
128
-
129
- - Factors written in exponent notation, such as `1e-7`, are reduced to an exact integer ratio instead of being truncated to zero.
127
+ to split an amount among them. Pass a percentage as an integer like `20` for twenty percent.
128
+
129
+ ## Review notes
130
+
131
+ - Factors written in exponent notation, such as `1e-7`, are reduced to an exact integer ratio instead of being truncated to zero.
@@ -0,0 +1,168 @@
1
+ /** Stable money error codes. */
2
+ export type MoneyErrorCode = "MONEY_INVALID_DECIMAL" | "MONEY_INVALID_MINOR_UNITS" | "MONEY_INVALID_FACTOR" | "MONEY_INVALID_WEIGHTS" | "MONEY_INVALID_FRACTION_DIGITS";
3
+ /**
4
+ * Error thrown by the money utilities.
5
+ *
6
+ * Carries a stable machine-readable `code` and a `details` context object.
7
+ */
8
+ export declare class MoneyError extends Error {
9
+ readonly code: MoneyErrorCode;
10
+ readonly details: Record<string, unknown>;
11
+ constructor(code: MoneyErrorCode, message: string, details?: Record<string, unknown>);
12
+ }
13
+ /** Rounding behaviour for a fractional result. */
14
+ export type RoundingMode = "half-away-from-zero" | "half-up" | "floor" | "ceil" | "down";
15
+ /** Options for {@link fromDecimal}. */
16
+ export type FromDecimalOptions = {
17
+ /** Digits the currency supports. Defaults to 2. More than this is refused. */
18
+ fractionDigits?: number;
19
+ };
20
+ /** Options for {@link toDecimal}. */
21
+ export type ToDecimalOptions = {
22
+ /** Digits to render. Defaults to 2. */
23
+ fractionDigits?: number;
24
+ };
25
+ /** Options for {@link multiplyMoney}, {@link percentageOf} and {@link applyPercentage}. */
26
+ export type MultiplyOptions = {
27
+ /** How to settle a fractional minor unit. Defaults to `half-away-from-zero`. */
28
+ rounding?: RoundingMode;
29
+ };
30
+ /** Options for {@link formatMoney}. */
31
+ export type FormatMoneyOptions = {
32
+ /** ISO 4217 currency code. */
33
+ currency?: string;
34
+ /** BCP 47 locale tag. */
35
+ locale?: string;
36
+ /** Omit the currency symbol or code. */
37
+ showCurrency?: boolean;
38
+ /** Force an explicit `+` on a positive amount. */
39
+ signed?: boolean;
40
+ };
41
+ /**
42
+ * Converts a decimal amount into integer minor units.
43
+ *
44
+ * Parsing the decimal as a string keeps the conversion exact: `"2.675"` becomes `268` minor units
45
+ * for a two-digit currency rather than inheriting the float `2.674999...`.
46
+ *
47
+ * @param value - Decimal amount as a string, or a number you already trust.
48
+ * @param options - Conversion options.
49
+ * @param options.fractionDigits - Digits the currency supports. Defaults to 2.
50
+ * @returns Amount in minor units.
51
+ * @throws {MoneyError} `MONEY_INVALID_DECIMAL` or `MONEY_INVALID_FRACTION_DIGITS`.
52
+ *
53
+ * @example
54
+ * fromDecimal("19.99"); // 1999
55
+ * fromDecimal("0.07"); // 7
56
+ */
57
+ export declare function fromDecimal(value: string | number, options?: FromDecimalOptions): number;
58
+ /**
59
+ * Converts integer minor units into a decimal string.
60
+ *
61
+ * @param minorUnits - Amount in minor units.
62
+ * @param options - Conversion options.
63
+ * @param options.fractionDigits - Digits to render. Defaults to 2.
64
+ * @returns The decimal amount, with exactly `fractionDigits` digits.
65
+ * @throws {MoneyError} `MONEY_INVALID_MINOR_UNITS`.
66
+ *
67
+ * @example
68
+ * toDecimal(1999); // "19.99"
69
+ */
70
+ export declare function toDecimal(minorUnits: number, options?: ToDecimalOptions): string;
71
+ /**
72
+ * Adds two amounts in minor units.
73
+ *
74
+ * @param left - First amount.
75
+ * @param right - Second amount.
76
+ * @returns The sum.
77
+ * @throws {MoneyError} `MONEY_INVALID_MINOR_UNITS`.
78
+ */
79
+ export declare function addMoney(left: number, right: number): number;
80
+ /**
81
+ * Subtracts two amounts in minor units.
82
+ *
83
+ * @param left - Amount to subtract from.
84
+ * @param right - Amount to subtract.
85
+ * @returns The difference.
86
+ * @throws {MoneyError} `MONEY_INVALID_MINOR_UNITS`.
87
+ */
88
+ export declare function subtractMoney(left: number, right: number): number;
89
+ /**
90
+ * Adds a list of amounts in minor units.
91
+ *
92
+ * @param amounts - Amounts to add.
93
+ * @returns The sum, or `0` for an empty list.
94
+ * @throws {MoneyError} `MONEY_INVALID_MINOR_UNITS`.
95
+ */
96
+ export declare function sumMoney(amounts: readonly number[]): number;
97
+ /**
98
+ * Multiplies an amount by a factor, settling any fraction with an explicit rounding mode.
99
+ *
100
+ * @param minorUnits - Amount in minor units.
101
+ * @param factor - Multiplier.
102
+ * @param options - Rounding options.
103
+ * @param options.rounding - Rounding mode, defaults to `half-away-from-zero`.
104
+ * @returns The product in minor units.
105
+ * @throws {MoneyError} `MONEY_INVALID_MINOR_UNITS` or `MONEY_INVALID_FACTOR`.
106
+ *
107
+ * @example
108
+ * multiplyMoney(1999, 3); // 5997
109
+ */
110
+ export declare function multiplyMoney(minorUnits: number, factor: number, options?: MultiplyOptions): number;
111
+ /**
112
+ * Returns the percentage of an amount, in minor units.
113
+ *
114
+ * @param minorUnits - Amount in minor units.
115
+ * @param percent - Percentage, for example `19` for 19%.
116
+ * @param options - Rounding options.
117
+ * @returns The percentage amount.
118
+ * @throws {MoneyError} `MONEY_INVALID_MINOR_UNITS` or `MONEY_INVALID_FACTOR`.
119
+ *
120
+ * @example
121
+ * percentageOf(10000, 19); // 1900
122
+ */
123
+ export declare function percentageOf(minorUnits: number, percent: number, options?: MultiplyOptions): number;
124
+ /**
125
+ * Applies a percentage to an amount, adding it for a positive value and subtracting for a negative one.
126
+ *
127
+ * @param minorUnits - Amount in minor units.
128
+ * @param percent - Percentage. `-10` applies a 10% discount.
129
+ * @param options - Rounding options.
130
+ * @returns The adjusted amount.
131
+ * @throws {MoneyError} `MONEY_INVALID_MINOR_UNITS` or `MONEY_INVALID_FACTOR`.
132
+ *
133
+ * @example
134
+ * applyPercentage(10000, 21); // 12100
135
+ * applyPercentage(10000, -10); // 9000
136
+ */
137
+ export declare function applyPercentage(minorUnits: number, percent: number, options?: MultiplyOptions): number;
138
+ /**
139
+ * Splits an amount across weights without losing or inventing a single minor unit.
140
+ *
141
+ * Uses the largest-remainder method, so the parts always sum back to the total exactly. Each extra
142
+ * minor unit goes to the earliest parts, which keeps the result deterministic.
143
+ *
144
+ * @param total - Amount in minor units.
145
+ * @param weights - Non-negative whole-number weights, one per part.
146
+ * @returns One amount per weight, summing exactly to `total`.
147
+ * @throws {MoneyError} `MONEY_INVALID_MINOR_UNITS` or `MONEY_INVALID_WEIGHTS`.
148
+ *
149
+ * @example
150
+ * allocateAmount(1000, [1, 1, 1]); // [334, 333, 333]
151
+ */
152
+ export declare function allocateAmount(total: number, weights: readonly number[]): number[];
153
+ /**
154
+ * Formats an amount for display.
155
+ *
156
+ * @param minorUnits - Amount in minor units.
157
+ * @param options - Formatting options.
158
+ * @param options.currency - ISO 4217 code, defaults to `USD`.
159
+ * @param options.locale - BCP 47 tag, defaults to `en-US`.
160
+ * @param options.showCurrency - Omit the symbol or code, defaults to `true`.
161
+ * @param options.signed - Force an explicit `+` on a positive amount, defaults to `false`.
162
+ * @returns The formatted string.
163
+ * @throws {MoneyError} `MONEY_INVALID_MINOR_UNITS`.
164
+ *
165
+ * @example
166
+ * formatMoney(123456); // "$1,234.56"
167
+ */
168
+ export declare function formatMoney(minorUnits: number, options?: FormatMoneyOptions): string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jdsalasc/solvejs-money",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "description": "TypeScript money utilities using integer minor units for lossless arithmetic, exact percentage application, largest-remainder allocation, and formatting, with no floating point rounding.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -10,9 +10,14 @@
10
10
  "types": "./dist/esm/index.d.ts",
11
11
  "exports": {
12
12
  ".": {
13
- "types": "./dist/esm/index.d.ts",
14
- "import": "./dist/esm/index.js",
15
- "require": "./dist/cjs/index.cjs"
13
+ "import": {
14
+ "types": "./dist/esm/index.d.ts",
15
+ "default": "./dist/esm/index.js"
16
+ },
17
+ "require": {
18
+ "types": "./dist/cjs/index.d.cts",
19
+ "default": "./dist/cjs/index.cjs"
20
+ }
16
21
  }
17
22
  },
18
23
  "files": [
@@ -22,7 +27,7 @@
22
27
  "scripts": {
23
28
  "build": "npm run clean && npm run build:esm && npm run build:cjs",
24
29
  "build:esm": "tsc -p tsconfig.esm.json",
25
- "build:cjs": "tsc -p tsconfig.cjs.json && node ./scripts/rename-cjs.mjs",
30
+ "build:cjs": "tsc -p tsconfig.cjs.json && node ./scripts/rename-cjs.mjs && node ../../scripts/build-cjs-types.mjs",
26
31
  "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
27
32
  "test": "npm run build && node --test test/*.test.mjs",
28
33
  "lint": "tsc -p tsconfig.esm.json --noEmit"
@@ -31,7 +36,7 @@
31
36
  "access": "public"
32
37
  },
33
38
  "author": "jdsalasc",
34
- "homepage": "https://github.com/jdsalasca/solvejs#readme",
39
+ "homepage": "https://jdsalasca.github.io/solvejs/live/#pkg-money",
35
40
  "repository": {
36
41
  "type": "git",
37
42
  "url": "git+https://github.com/jdsalasca/solvejs.git"