iso-price 1.0.3

package/dist/domain.operations/cast/asIsoPriceWords.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asIsoPriceWords = void 0;
+const IsoPriceExponent_1 = require("../../domain.objects/IsoPriceExponent");
+const isIsoPriceWords_1 = require("../guard/isIsoPriceWords");
+const getIsoPriceExponentByCurrency_1 = require("../precision/getIsoPriceExponentByCurrency");
+const asIsoPriceShape_1 = require("./asIsoPriceShape");
+/**
+ * .what = gets the decimal places for an exponent
+ * .why = determines how to format the amount string
+ */
+const getDecimalPlaces = (exponent) => {
+    const match = exponent.match(/\^(-?\d+)$/);
+    if (!match)
+        return 2; // default to 2 decimal places
+    return Math.abs(parseInt(match[1], 10));
+};
+/**
+ * .what = formats the decimal part with underscore separators for high precision
+ * .why = improves readability of micro/nano/pico precision amounts
+ */
+const formatDecimalPart = (decPart) => {
+    // for 3+ digit decimals, add underscore separators every 3 digits from left
+    if (decPart.length > 3) {
+        const groups = [];
+        for (let i = 0; i < decPart.length; i += 3) {
+            groups.push(decPart.slice(i, i + 3));
+        }
+        return groups.join('_');
+    }
+    return decPart;
+};
+/**
+ * .what = formats a bigint amount to a decimal string with underscores
+ * .why = converts 5037n with exponent 2 to '50.37'
+ */
+const formatAmount = (amount, exponent = IsoPriceExponent_1.IsoPriceExponent.CENTI) => {
+    const decimalPlaces = getDecimalPlaces(exponent);
+    const isNegative = amount < 0n;
+    const absAmount = isNegative ? -amount : amount;
+    // handle zero decimal places (whole units like JPY)
+    if (decimalPlaces === 0) {
+        const formattedInt = absAmount
+            .toString()
+            .replace(/\B(?=(\d{3})+(?!\d))/g, '_');
+        return isNegative ? `-${formattedInt}` : formattedInt;
+    }
+    // convert to string and pad with zeros at start if needed
+    const amountStr = absAmount.toString().padStart(decimalPlaces + 1, '0');
+    // split into integer and decimal parts
+    const intPart = amountStr.slice(0, -decimalPlaces) || '0';
+    const decPart = amountStr.slice(-decimalPlaces);
+    // format integer part with underscore thousands separators
+    const formattedInt = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, '_');
+    // build the result
+    const sign = isNegative ? '-' : '';
+    // for centi (2 decimal places), trim zeros at end but keep at least .00
+    if (decimalPlaces === 2) {
+        const trimmedDec = decPart.replace(/0+$/, '');
+        if (trimmedDec.length === 0) {
+            return `${sign}${formattedInt}.00`;
+        }
+        return `${sign}${formattedInt}.${trimmedDec.padEnd(2, '0')}`;
+    }
+    // for higher precision, preserve full precision with underscore separators
+    const formattedDec = formatDecimalPart(decPart);
+    return `${sign}${formattedInt}.${formattedDec}`;
+};
+/**
+ * .what = converts any IsoPrice format to IsoPriceWords
+ * .why = enables uniform representation as words for serialization
+ *
+ * @example
+ * asIsoPriceWords({ amount: 5037n, currency: 'USD' })
+ * // => 'USD 50.37'
+ *
+ * @example
+ * asIsoPriceWords('$50.37')
+ * // => 'USD 50.37'
+ *
+ * @example
+ * asIsoPriceWords({ amount: 1000000n, currency: 'USD' })
+ * // => 'USD 10_000.00'
+ */
+const asIsoPriceWords = (input, options) => {
+    // if already words format, normalize it (replace commas with underscores)
+    if ((0, isIsoPriceWords_1.isIsoPriceWords)(input)) {
+        // re-parse to ensure consistent format
+        const shape = (0, asIsoPriceShape_1.asIsoPriceShape)(input);
+        // use currency's standard exponent when shape.exponent is not set
+        const exponent = shape.exponent ?? (0, getIsoPriceExponentByCurrency_1.getIsoPriceExponentByCurrency)(shape.currency);
+        const formatted = formatAmount(shape.amount, exponent);
+        return `${shape.currency} ${formatted}`;
+    }
+    // convert to shape first, then format
+    const shape = (0, asIsoPriceShape_1.asIsoPriceShape)(input, options);
+    // use currency's standard exponent when shape.exponent is not set
+    const exponent = shape.exponent ?? (0, getIsoPriceExponentByCurrency_1.getIsoPriceExponentByCurrency)(shape.currency);
+    const formatted = formatAmount(shape.amount, exponent);
+    return `${shape.currency} ${formatted}`;
+};
+exports.asIsoPriceWords = asIsoPriceWords;
+//# sourceMappingURL=asIsoPriceWords.js.map

package/dist/domain.operations/cast/asIsoPriceWords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asIsoPriceWords.js","sourceRoot":"","sources":["../../../src/domain.operations/cast/asIsoPriceWords.ts"],"names":[],"mappings":";;;AACA,4EAAyE;AAEzE,8DAA2D;AAC3D,8FAA2F;AAC3F,uDAAoD;AAEpD;;;GAGG;AACH,MAAM,gBAAgB,GAAG,CAAC,QAAmC,EAAU,EAAE;IACvE,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC,CAAC,8BAA8B;IACpD,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3C,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,iBAAiB,GAAG,CAAC,OAAe,EAAU,EAAE;IACpD,4EAA4E;IAC5E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3C,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,YAAY,GAAG,CACnB,MAAc,EACd,WAAsC,mCAAgB,CAAC,KAAK,EACpD,EAAE;IACV,MAAM,aAAa,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,MAAM,GAAG,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAEhD,oDAAoD;IACpD,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,YAAY,GAAG,SAAS;aAC3B,QAAQ,EAAE;aACV,OAAO,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAC;QACzC,OAAO,UAAU,CAAC,CAAC,CAAC,IAAI,YAAY,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;IACxD,CAAC;IAED,0DAA0D;IAC1D,MAAM,SAAS,GAAG,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,aAAa,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;IAExE,uCAAuC;IACvC,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC;IAC1D,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,aAAa,CAAC,CAAC;IAEhD,2DAA2D;IAC3D,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAC;IAEnE,mBAAmB;IACnB,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAEnC,wEAAwE;IACxE,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC9C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO,GAAG,IAAI,GAAG,YAAY,KAAK,CAAC;QACrC,CAAC;QACD,OAAO,GAAG,IAAI,GAAG,YAAY,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IAC/D,CAAC;IAED,2EAA2E;IAC3E,MAAM,YAAY,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAChD,OAAO,GAAG,IAAI,GAAG,YAAY,IAAI,YAAY,EAAE,CAAC;AAClD,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACI,MAAM,eAAe,GAAG,CAC7B,KAGU,EACV,OAAkC,EACR,EAAE;IAC5B,0EAA0E;IAC1E,IAAI,IAAA,iCAAe,EAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,uCAAuC;QACvC,MAAM,KAAK,GAAG,IAAA,iCAAe,EAAC,KAAK,CAAC,CAAC;QACrC,kEAAkE;QAClE,MAAM,QAAQ,GACZ,KAAK,CAAC,QAAQ,IAAI,IAAA,6DAA6B,EAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAClE,MAAM,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACvD,OAAO,GAAG,KAAK,CAAC,QAAQ,IAAI,SAAS,EAA8B,CAAC;IACtE,CAAC;IAED,sCAAsC;IACtC,MAAM,KAAK,GAAG,IAAA,iCAAe,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC9C,kEAAkE;IAClE,MAAM,QAAQ,GACZ,KAAK,CAAC,QAAQ,IAAI,IAAA,6DAA6B,EAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClE,MAAM,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACvD,OAAO,GAAG,KAAK,CAAC,QAAQ,IAAI,SAAS,EAA8B,CAAC;AACtE,CAAC,CAAC;AAzBW,QAAA,eAAe,mBAyB1B"}

package/dist/domain.operations/guard/isIsoPrice.d.ts

@@ -0,0 +1,18 @@
+import type { IsoPrice } from '../../domain.objects/IsoPrice';
+/**
+ * .what = type guard for IsoPrice union type
+ * .why = validates that a value is any of the three iso-price formats
+ *
+ * accepts:
+ * - IsoPriceWords: 'USD 50.37'
+ * - IsoPriceShape: { amount: 5037n, currency: 'USD' }
+ * - IsoPriceHuman: '$50.37'
+ */
+export declare const isIsoPrice: {
+    (value: unknown): value is IsoPrice;
+    /**
+     * .what = assertion function that throws on invalid input
+     * .why = enables fail-fast validation with helpful error messages
+     */
+    assure(value: unknown): asserts value is IsoPrice;
+};

package/dist/domain.operations/guard/isIsoPrice.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isIsoPrice = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const isIsoPriceHuman_1 = require("./isIsoPriceHuman");
+const isIsoPriceShape_1 = require("./isIsoPriceShape");
+const isIsoPriceWords_1 = require("./isIsoPriceWords");
+/**
+ * .what = type guard for IsoPrice union type
+ * .why = validates that a value is any of the three iso-price formats
+ *
+ * accepts:
+ * - IsoPriceWords: 'USD 50.37'
+ * - IsoPriceShape: { amount: 5037n, currency: 'USD' }
+ * - IsoPriceHuman: '$50.37'
+ */
+const isIsoPrice = (value) => {
+    return ((0, isIsoPriceWords_1.isIsoPriceWords)(value) || (0, isIsoPriceShape_1.isIsoPriceShape)(value) || (0, isIsoPriceHuman_1.isIsoPriceHuman)(value));
+};
+exports.isIsoPrice = isIsoPrice;
+/**
+ * .what = assertion function that throws on invalid input
+ * .why = enables fail-fast validation with helpful error messages
+ */
+exports.isIsoPrice.assure = (value) => {
+    if (!(0, exports.isIsoPrice)(value))
+        throw new helpful_errors_1.BadRequestError('value is not a valid IsoPrice', { value });
+};
+//# sourceMappingURL=isIsoPrice.js.map

package/dist/domain.operations/guard/isIsoPrice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isIsoPrice.js","sourceRoot":"","sources":["../../../src/domain.operations/guard/isIsoPrice.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AAGjD,uDAAoD;AACpD,uDAAoD;AACpD,uDAAoD;AAEpD;;;;;;;;GAQG;AACI,MAAM,UAAU,GAAG,CAAC,KAAc,EAAqB,EAAE;IAC9D,OAAO,CACL,IAAA,iCAAe,EAAC,KAAK,CAAC,IAAI,IAAA,iCAAe,EAAC,KAAK,CAAC,IAAI,IAAA,iCAAe,EAAC,KAAK,CAAC,CAC3E,CAAC;AACJ,CAAC,CAAC;AAJW,QAAA,UAAU,cAIrB;AAEF;;;GAGG;AACH,kBAAU,CAAC,MAAM,GAAG,CAAC,KAAc,EAA6B,EAAE;IAChE,IAAI,CAAC,IAAA,kBAAU,EAAC,KAAK,CAAC;QACpB,MAAM,IAAI,gCAAe,CAAC,+BAA+B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AAC1E,CAAC,CAAC"}

package/dist/domain.operations/guard/isIsoPriceHuman.d.ts

@@ -0,0 +1,24 @@
+/**
+ * .what = type guard for IsoPriceHuman format
+ * .why = validates strings match the symbol-based human-readable pattern
+ *
+ * valid examples:
+ * - '$50.37'
+ * - '€50.37'
+ * - '¥1,000'
+ * - '$1,000,000.00'
+ * - '100 €' (suffix position)
+ *
+ * invalid examples:
+ * - 'USD 50.37' (code-prefix is words format, not human)
+ * - '50.37' (no symbol)
+ * - { amount: 5037n, currency: 'USD' } (object, not string)
+ */
+export declare const isIsoPriceHuman: {
+    (value: unknown): value is string & import("domain-glossaries").OfGlossary<"iso-price-human">;
+    /**
+     * .what = assertion function that throws on invalid input
+     * .why = enables fail-fast validation with helpful error messages
+     */
+    assure(value: unknown): asserts value is string & import("domain-glossaries").OfGlossary<"iso-price-human">;
+};

package/dist/domain.operations/guard/isIsoPriceHuman.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isIsoPriceHuman = void 0;
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = common currency symbols for human-readable price formats
+ * .why = validates that the string contains a currency symbol (not a code)
+ */
+const CURRENCY_SYMBOLS = [
+    '$', // USD, CAD, AUD, etc.
+    '€', // EUR
+    '£', // GBP
+    '¥', // JPY, CNY
+    '₹', // INR
+    '₽', // RUB
+    '₩', // KRW
+    '₪', // ILS
+    '฿', // THB
+    '₫', // VND
+    'kr', // SEK, NOK, DKK
+    'R', // ZAR, BRL
+    'zł', // PLN
+    'Kč', // CZK
+    'CHF', // note: CHF is a code but used as-is in human format
+];
+/**
+ * .what = regex pattern for human-readable price format
+ * .why = matches symbol-prefix or symbol-suffix patterns with optional separators
+ *
+ * examples:
+ * - '$50.37' (symbol prefix)
+ * - '€1,000.00' (symbol prefix with commas)
+ * - '100 €' (symbol suffix, european style)
+ * - '¥1,000' (no decimals)
+ */
+const hasSymbolPrefix = (value) => {
+    return CURRENCY_SYMBOLS.some((symbol) => value.startsWith(symbol));
+};
+const hasSymbolSuffix = (value) => {
+    return CURRENCY_SYMBOLS.some((symbol) => value.endsWith(symbol) || value.endsWith(` ${symbol}`));
+};
+/**
+ * .what = type guard for IsoPriceHuman format
+ * .why = validates strings match the symbol-based human-readable pattern
+ *
+ * valid examples:
+ * - '$50.37'
+ * - '€50.37'
+ * - '¥1,000'
+ * - '$1,000,000.00'
+ * - '100 €' (suffix position)
+ *
+ * invalid examples:
+ * - 'USD 50.37' (code-prefix is words format, not human)
+ * - '50.37' (no symbol)
+ * - { amount: 5037n, currency: 'USD' } (object, not string)
+ */
+const isIsoPriceHuman = (value) => {
+    if (typeof value !== 'string')
+        return false;
+    // must not be words format (code-prefix pattern)
+    if (/^[A-Z]{3} /.test(value))
+        return false;
+    // must have a currency symbol (prefix or suffix)
+    return hasSymbolPrefix(value) || hasSymbolSuffix(value);
+};
+exports.isIsoPriceHuman = isIsoPriceHuman;
+/**
+ * .what = assertion function that throws on invalid input
+ * .why = enables fail-fast validation with helpful error messages
+ */
+exports.isIsoPriceHuman.assure = (value) => {
+    if (!(0, exports.isIsoPriceHuman)(value))
+        throw new helpful_errors_1.BadRequestError('value is not a valid IsoPriceHuman', { value });
+};
+//# sourceMappingURL=isIsoPriceHuman.js.map

package/dist/domain.operations/guard/isIsoPriceHuman.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isIsoPriceHuman.js","sourceRoot":"","sources":["../../../src/domain.operations/guard/isIsoPriceHuman.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AAIjD;;;GAGG;AACH,MAAM,gBAAgB,GAAG;IACvB,GAAG,EAAE,sBAAsB;IAC3B,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,GAAG,EAAE,MAAM;IACX,IAAI,EAAE,gBAAgB;IACtB,GAAG,EAAE,WAAW;IAChB,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,qDAAqD;CAC7D,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,eAAe,GAAG,CAAC,KAAa,EAAW,EAAE;IACjD,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AACrE,CAAC,CAAC;AAEF,MAAM,eAAe,GAAG,CAAC,KAAa,EAAW,EAAE;IACjD,OAAO,gBAAgB,CAAC,IAAI,CAC1B,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC,CACnE,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACI,MAAM,eAAe,GAAG,CAAC,KAAc,EAA0B,EAAE;IACxE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5C,iDAAiD;IACjD,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAE3C,iDAAiD;IACjD,OAAO,eAAe,CAAC,KAAK,CAAC,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC,CAAC;AARW,QAAA,eAAe,mBAQ1B;AAEF;;;GAGG;AACH,uBAAe,CAAC,MAAM,GAAG,CAAC,KAAc,EAAkC,EAAE;IAC1E,IAAI,CAAC,IAAA,uBAAe,EAAC,KAAK,CAAC;QACzB,MAAM,IAAI,gCAAe,CAAC,oCAAoC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AAC/E,CAAC,CAAC"}

package/dist/domain.operations/guard/isIsoPriceShape.d.ts

@@ -0,0 +1,29 @@
+import type { IsoPriceShape } from '../../domain.objects/IsoPriceShape';
+/**
+ * .what = type guard for IsoPriceShape format
+ * .why = validates objects have the required shape properties
+ *
+ * required:
+ * - amount: bigint
+ * - currency: string
+ *
+ * optional:
+ * - exponent: string (IsoPriceExponent value)
+ *
+ * valid examples:
+ * - { amount: 5037n, currency: 'USD' }
+ * - { amount: 3n, currency: 'USD', exponent: 'micro.x10^-6' }
+ *
+ * invalid examples:
+ * - { amount: 5037, currency: 'USD' } (number instead of bigint)
+ * - { amount: 5037n } (currency absent)
+ * - 'USD 50.37' (string instead of object)
+ */
+export declare const isIsoPriceShape: {
+    (value: unknown): value is IsoPriceShape<string, "whole.x10^0" | "centi.x10^-2" | "milli.x10^-3" | "micro.x10^-6" | "nano.x10^-9" | "pico.x10^-12" | import("../..").IsoPriceExponent>;
+    /**
+     * .what = assertion function that throws on invalid input
+     * .why = enables fail-fast validation with helpful error messages
+     */
+    assure(value: unknown): asserts value is IsoPriceShape<string, "whole.x10^0" | "centi.x10^-2" | "milli.x10^-3" | "micro.x10^-6" | "nano.x10^-9" | "pico.x10^-12" | import("../..").IsoPriceExponent>;
+};

package/dist/domain.operations/guard/isIsoPriceShape.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isIsoPriceShape = void 0;
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = type guard for IsoPriceShape format
+ * .why = validates objects have the required shape properties
+ *
+ * required:
+ * - amount: bigint
+ * - currency: string
+ *
+ * optional:
+ * - exponent: string (IsoPriceExponent value)
+ *
+ * valid examples:
+ * - { amount: 5037n, currency: 'USD' }
+ * - { amount: 3n, currency: 'USD', exponent: 'micro.x10^-6' }
+ *
+ * invalid examples:
+ * - { amount: 5037, currency: 'USD' } (number instead of bigint)
+ * - { amount: 5037n } (currency absent)
+ * - 'USD 50.37' (string instead of object)
+ */
+const isIsoPriceShape = (value) => {
+    // must be an object
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const obj = value;
+    // amount must be bigint
+    if (typeof obj.amount !== 'bigint')
+        return false;
+    // currency must be string
+    if (typeof obj.currency !== 'string')
+        return false;
+    // exponent is optional but must be string if present
+    if (obj.exponent !== undefined && typeof obj.exponent !== 'string')
+        return false;
+    return true;
+};
+exports.isIsoPriceShape = isIsoPriceShape;
+/**
+ * .what = assertion function that throws on invalid input
+ * .why = enables fail-fast validation with helpful error messages
+ */
+exports.isIsoPriceShape.assure = (value) => {
+    if (!(0, exports.isIsoPriceShape)(value))
+        throw new helpful_errors_1.BadRequestError('value is not a valid IsoPriceShape', { value });
+};
+//# sourceMappingURL=isIsoPriceShape.js.map

package/dist/domain.operations/guard/isIsoPriceShape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isIsoPriceShape.js","sourceRoot":"","sources":["../../../src/domain.operations/guard/isIsoPriceShape.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AAIjD;;;;;;;;;;;;;;;;;;;GAmBG;AACI,MAAM,eAAe,GAAG,CAAC,KAAc,EAA0B,EAAE;IACxE,oBAAoB;IACpB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAE9D,MAAM,GAAG,GAAG,KAAgC,CAAC;IAE7C,wBAAwB;IACxB,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAEjD,0BAA0B;IAC1B,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAEnD,qDAAqD;IACrD,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ;QAChE,OAAO,KAAK,CAAC;IAEf,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAjBW,QAAA,eAAe,mBAiB1B;AAEF;;;GAGG;AACH,uBAAe,CAAC,MAAM,GAAG,CAAC,KAAc,EAAkC,EAAE;IAC1E,IAAI,CAAC,IAAA,uBAAe,EAAC,KAAK,CAAC;QACzB,MAAM,IAAI,gCAAe,CAAC,oCAAoC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AAC/E,CAAC,CAAC"}

package/dist/domain.operations/guard/isIsoPriceWords.d.ts

@@ -0,0 +1,24 @@
+import type { IsoPriceWords } from '../../domain.objects/IsoPriceWords';
+/**
+ * .what = type guard for IsoPriceWords format
+ * .why = validates strings match the `{CURRENCY_CODE} {AMOUNT}` pattern
+ *
+ * valid examples:
+ * - 'USD 50.37'
+ * - 'USD 1_000_000.00'
+ * - 'USD 1,000,000.00' (commas accepted, normalized to underscores on output)
+ * - 'EUR 0.000003'
+ * - 'JPY 1000'
+ *
+ * invalid examples:
+ * - '$50.37' (symbol instead of code)
+ * - 'usd 50.37' (lowercase currency)
+ */
+export declare const isIsoPriceWords: {
+    (value: unknown): value is IsoPriceWords;
+    /**
+     * .what = assertion function that throws on invalid input
+     * .why = enables fail-fast validation with helpful error messages
+     */
+    assure(value: unknown): asserts value is IsoPriceWords;
+};

package/dist/domain.operations/guard/isIsoPriceWords.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isIsoPriceWords = void 0;
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = regex pattern for valid iso-price words format
+ * .why = validates `{CURRENCY_CODE} {AMOUNT}` pattern
+ *
+ * pattern breakdown:
+ * - `^[A-Z]{3}` — 3 uppercase letters for currency code
+ * - ` ` — single space separator
+ * - `-?` — optional negative sign
+ * - `(\d+|\d{1,3}([_,]\d{3})+)` — either plain digits OR underscore/comma-separated groups
+ * - `(\.(\d+|\d{1,3}([_,]\d{3})+))?$` — optional decimal point with underscore/comma-separated digits
+ *
+ * accepts both commas and underscores for input convenience; output uses underscores
+ */
+const WORDS_PATTERN = /^[A-Z]{3} -?(\d+|\d{1,3}([_,]\d{3})+)(\.(\d+|\d{1,3}([_,]\d{3})+))?$/;
+/**
+ * .what = type guard for IsoPriceWords format
+ * .why = validates strings match the `{CURRENCY_CODE} {AMOUNT}` pattern
+ *
+ * valid examples:
+ * - 'USD 50.37'
+ * - 'USD 1_000_000.00'
+ * - 'USD 1,000,000.00' (commas accepted, normalized to underscores on output)
+ * - 'EUR 0.000003'
+ * - 'JPY 1000'
+ *
+ * invalid examples:
+ * - '$50.37' (symbol instead of code)
+ * - 'usd 50.37' (lowercase currency)
+ */
+const isIsoPriceWords = (value) => {
+    if (typeof value !== 'string')
+        return false;
+    return WORDS_PATTERN.test(value);
+};
+exports.isIsoPriceWords = isIsoPriceWords;
+/**
+ * .what = assertion function that throws on invalid input
+ * .why = enables fail-fast validation with helpful error messages
+ */
+exports.isIsoPriceWords.assure = (value) => {
+    if (!(0, exports.isIsoPriceWords)(value))
+        throw new helpful_errors_1.BadRequestError('value is not a valid IsoPriceWords', { value });
+};
+//# sourceMappingURL=isIsoPriceWords.js.map

package/dist/domain.operations/guard/isIsoPriceWords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isIsoPriceWords.js","sourceRoot":"","sources":["../../../src/domain.operations/guard/isIsoPriceWords.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AAIjD;;;;;;;;;;;;GAYG;AACH,MAAM,aAAa,GACjB,sEAAsE,CAAC;AAEzE;;;;;;;;;;;;;;GAcG;AACI,MAAM,eAAe,GAAG,CAAC,KAAc,EAA0B,EAAE;IACxE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC,CAAC;AAHW,QAAA,eAAe,mBAG1B;AAEF;;;GAGG;AACH,uBAAe,CAAC,MAAM,GAAG,CAAC,KAAc,EAAkC,EAAE;IAC1E,IAAI,CAAC,IAAA,uBAAe,EAAC,KAAK,CAAC;QACzB,MAAM,IAAI,gCAAe,CAAC,oCAAoC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AAC/E,CAAC,CAAC"}

package/dist/domain.operations/precision/getIsoPriceExponentByCurrency.d.ts

@@ -0,0 +1,15 @@
+import { IsoPriceExponent } from '../../domain.objects/IsoPriceExponent';
+/**
+ * .what = returns the standard iso 4217 exponent for a currency
+ * .why = enables correct precision per currency standard
+ *
+ * defaults to centi.x10^-2 for unknown currencies, as >95% of currencies
+ * use 2 decimal places (cents).
+ *
+ * @example
+ * getIsoPriceExponentByCurrency('USD')  // => 'centi.x10^-2'
+ * getIsoPriceExponentByCurrency('JPY')  // => 'whole.x10^0'
+ * getIsoPriceExponentByCurrency('BHD')  // => 'milli.x10^-3'
+ * getIsoPriceExponentByCurrency('BTC')  // => 'centi.x10^-2' (default)
+ */
+export declare const getIsoPriceExponentByCurrency: (currency: string) => IsoPriceExponent;

package/dist/domain.operations/precision/getIsoPriceExponentByCurrency.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getIsoPriceExponentByCurrency = void 0;
+const IsoPriceExponent_1 = require("../../domain.objects/IsoPriceExponent");
+/**
+ * .what = currency codes that use whole units (no decimals)
+ * .why = JPY, KRW, VND, IDR have no minor units per iso 4217
+ */
+const WHOLE_UNIT_CURRENCIES = new Set([
+    'JPY',
+    'KRW',
+    'VND',
+    'IDR',
+    'CLP',
+    'PYG',
+    'UGX',
+]);
+/**
+ * .what = currency codes that use 3 decimal places
+ * .why = BHD, KWD, OMR, TND have fils/baisa (1/1000) per iso 4217
+ */
+const MILLI_UNIT_CURRENCIES = new Set(['BHD', 'KWD', 'OMR', 'TND']);
+/**
+ * .what = returns the standard iso 4217 exponent for a currency
+ * .why = enables correct precision per currency standard
+ *
+ * defaults to centi.x10^-2 for unknown currencies, as >95% of currencies
+ * use 2 decimal places (cents).
+ *
+ * @example
+ * getIsoPriceExponentByCurrency('USD')  // => 'centi.x10^-2'
+ * getIsoPriceExponentByCurrency('JPY')  // => 'whole.x10^0'
+ * getIsoPriceExponentByCurrency('BHD')  // => 'milli.x10^-3'
+ * getIsoPriceExponentByCurrency('BTC')  // => 'centi.x10^-2' (default)
+ */
+const getIsoPriceExponentByCurrency = (currency) => {
+    // check for whole unit currencies (0 decimal places)
+    if (WHOLE_UNIT_CURRENCIES.has(currency)) {
+        return IsoPriceExponent_1.IsoPriceExponent.WHOLE;
+    }
+    // check for milli unit currencies (3 decimal places)
+    if (MILLI_UNIT_CURRENCIES.has(currency)) {
+        return IsoPriceExponent_1.IsoPriceExponent.MILLI;
+    }
+    // default to centi (2 decimal places) — covers >95% of currencies
+    return IsoPriceExponent_1.IsoPriceExponent.CENTI;
+};
+exports.getIsoPriceExponentByCurrency = getIsoPriceExponentByCurrency;
+//# sourceMappingURL=getIsoPriceExponentByCurrency.js.map

package/dist/domain.operations/precision/getIsoPriceExponentByCurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getIsoPriceExponentByCurrency.js","sourceRoot":"","sources":["../../../src/domain.operations/precision/getIsoPriceExponentByCurrency.ts"],"names":[],"mappings":";;;AAAA,4EAAyE;AAEzE;;;GAGG;AACH,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC;IACpC,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;CACN,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;AAEpE;;;;;;;;;;;;GAYG;AACI,MAAM,6BAA6B,GAAG,CAC3C,QAAgB,EACE,EAAE;IACpB,qDAAqD;IACrD,IAAI,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxC,OAAO,mCAAgB,CAAC,KAAK,CAAC;IAChC,CAAC;IAED,qDAAqD;IACrD,IAAI,qBAAqB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxC,OAAO,mCAAgB,CAAC,KAAK,CAAC;IAChC,CAAC;IAED,kEAAkE;IAClE,OAAO,mCAAgB,CAAC,KAAK,CAAC;AAChC,CAAC,CAAC;AAfW,QAAA,6BAA6B,iCAexC"}

package/dist/domain.operations/precision/roundPrice.d.ts

@@ -0,0 +1,25 @@
+import type { IsoPrice } from '../../domain.objects/IsoPrice';
+import type { IsoPriceExponent } from '../../domain.objects/IsoPriceExponent';
+import type { IsoPriceRoundMode } from '../../domain.objects/IsoPriceRoundMode';
+import type { IsoPriceWords } from '../../domain.objects/IsoPriceWords';
+/**
+ * .what = rounds a price to a target precision
+ * .why = semantic alias for setPricePrecision when precision decrease is intended
+ *
+ * this is syntactic sugar for the common case of a precision reduction.
+ * use setPricePrecision directly if you need to increase precision.
+ *
+ * @example
+ * roundPrice({ of: 'USD 50.375', to: 'centi.x10^-2' })
+ * // => 'USD 50.38' (default half-up)
+ *
+ * @example
+ * roundPrice({ of: 'USD 50.375', to: 'centi.x10^-2' }, { round: 'floor' })
+ * // => 'USD 50.37'
+ */
+export declare const roundPrice: <TCurrency extends string = string>(input: {
+    of: IsoPrice<TCurrency> | string;
+    to: IsoPriceExponent | `${IsoPriceExponent}`;
+}, options?: {
+    round?: IsoPriceRoundMode;
+}) => IsoPriceWords<TCurrency>;

package/dist/domain.operations/precision/roundPrice.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.roundPrice = void 0;
+const setPricePrecision_1 = require("./setPricePrecision");
+/**
+ * .what = rounds a price to a target precision
+ * .why = semantic alias for setPricePrecision when precision decrease is intended
+ *
+ * this is syntactic sugar for the common case of a precision reduction.
+ * use setPricePrecision directly if you need to increase precision.
+ *
+ * @example
+ * roundPrice({ of: 'USD 50.375', to: 'centi.x10^-2' })
+ * // => 'USD 50.38' (default half-up)
+ *
+ * @example
+ * roundPrice({ of: 'USD 50.375', to: 'centi.x10^-2' }, { round: 'floor' })
+ * // => 'USD 50.37'
+ */
+const roundPrice = (input, options) => {
+    return (0, setPricePrecision_1.setPricePrecision)(input, options);
+};
+exports.roundPrice = roundPrice;
+//# sourceMappingURL=roundPrice.js.map

package/dist/domain.operations/precision/roundPrice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roundPrice.js","sourceRoot":"","sources":["../../../src/domain.operations/precision/roundPrice.ts"],"names":[],"mappings":";;;AAIA,2DAAwD;AAExD;;;;;;;;;;;;;;GAcG;AACI,MAAM,UAAU,GAAG,CACxB,KAGC,EACD,OAAuC,EACb,EAAE;IAC5B,OAAO,IAAA,qCAAiB,EAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC,CAAC;AARW,QAAA,UAAU,cAQrB"}

package/dist/domain.operations/precision/setPricePrecision.d.ts

@@ -0,0 +1,29 @@
+import type { IsoPrice } from '../../domain.objects/IsoPrice';
+import { IsoPriceExponent } from '../../domain.objects/IsoPriceExponent';
+import { IsoPriceRoundMode } from '../../domain.objects/IsoPriceRoundMode';
+import type { IsoPriceWords } from '../../domain.objects/IsoPriceWords';
+/**
+ * .what = changes the precision of a price to a target exponent
+ * .why = enables precision increase (lossless) and decrease (with round)
+ *
+ * @example
+ * // increase precision (lossless)
+ * setPricePrecision({ of: 'USD 50.37', to: 'micro.x10^-6' })
+ * // => 'USD 50.370000'
+ *
+ * @example
+ * // decrease precision (requires round)
+ * setPricePrecision({ of: 'USD 5.555', to: 'centi.x10^-2' })
+ * // => 'USD 5.56' (default half-up)
+ *
+ * @example
+ * // decrease precision with explicit round mode
+ * setPricePrecision({ of: 'USD 5.555', to: 'centi.x10^-2' }, { round: 'floor' })
+ * // => 'USD 5.55'
+ */
+export declare const setPricePrecision: <TCurrency extends string = string>(input: {
+    of: IsoPrice<TCurrency> | string;
+    to: IsoPriceExponent | `${IsoPriceExponent}`;
+}, options?: {
+    round?: IsoPriceRoundMode;
+}) => IsoPriceWords<TCurrency>;