calculation-breakdown 0.0.0-stage → 0.1.2

package/dist/cjs/calculation-breakdown-human-string.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toHumanString = toHumanString;
+const INFIX_OPERATORS = {
+    add: '+',
+    subtract: '−',
+    multiply: '×',
+    divide: '÷',
+};
+function localizeDecimal(value, locale) {
+    return locale === 'cs' ? value.replace('.', ',') : value;
+}
+function decimalToPercent(value) {
+    const negative = value.startsWith('-');
+    const unsigned = negative ? value.slice(1) : value;
+    const [whole = '0', fraction = ''] = unsigned.split('.');
+    const digits = `${whole}${fraction}`;
+    const decimalIndex = whole.length + 2;
+    const padded = digits.padEnd(decimalIndex, '0');
+    const integer = padded
+        .slice(0, decimalIndex)
+        .replace(/^0+(?=\d)/, '');
+    const decimals = padded.slice(decimalIndex).replace(/0+$/, '');
+    return `${negative ? '-' : ''}${integer}${decimals ? `.${decimals}` : ''}`;
+}
+function localizeDurationUnit(amount, unit, locale) {
+    const singularUnit = unit.slice(0, -1);
+    const unitPart = new Intl.NumberFormat(locale, {
+        style: 'unit',
+        unit: singularUnit,
+        unitDisplay: 'long',
+        useGrouping: false,
+    })
+        .formatToParts(Number(amount))
+        .find((part) => part.type === 'unit');
+    if (!unitPart) {
+        throw new Error(`Unable to localize duration unit: ${unit}`);
+    }
+    return unitPart.value;
+}
+function labelValue(value, semantic, options) {
+    if (options.includeNames === false)
+        return value;
+    const entry = options.dictionary[options.locale]?.[semantic];
+    const label = typeof entry === 'string' ? entry : (entry?.name ?? semantic);
+    return `${value} ${label}`;
+}
+function renderValue(value, options) {
+    const rawDecimal = value.type === 'number' || value.type === 'percent'
+        ? value.value
+        : value.amount;
+    const decimal = localizeDecimal(rawDecimal, options.locale);
+    if (value.type === 'money') {
+        return labelValue(`${decimal} ${value.currency}`, value.semantic, options);
+    }
+    if (value.type === 'duration') {
+        return labelValue(`${decimal} ${localizeDurationUnit(value.amount, value.unit, options.locale)}`, value.semantic, options);
+    }
+    if (value.type === 'percent') {
+        return labelValue(`${localizeDecimal(decimalToPercent(value.value), options.locale)}%`, value.semantic, options);
+    }
+    return labelValue(decimal, value.semantic, options);
+}
+function renderNode(node, options, nested = false) {
+    if (node.type === 'constant') {
+        return localizeDecimal(node.value, options.locale);
+    }
+    if (node.type === 'group') {
+        const result = node.result
+            ? ` = ${renderValue(node.result, options)}`
+            : '';
+        return `(${renderNode(node.expression, options)}${result})`;
+    }
+    if (node.type !== 'operation') {
+        return renderValue(node, options);
+    }
+    const [left, right] = node.operands;
+    if (node.operator === 'minimum' || node.operator === 'maximum') {
+        const functionName = node.operator === 'minimum' ? 'min' : 'max';
+        return `${functionName}(${renderNode(left, options)}, ${renderNode(right, options)})`;
+    }
+    const rendered = `${renderNode(left, options, true)} ${INFIX_OPERATORS[node.operator]} ${renderNode(right, options, true)}`;
+    return nested ? `(${rendered})` : rendered;
+}
+/** Renders a plain calculation breakdown without changing its serialized form. */
+function toHumanString(calculation, options) {
+    return `${renderNode(calculation.breakdown, options)} = ${renderValue(calculation.result, options)}`;
+}

package/dist/cjs/calculation-breakdown.error.d.ts

@@ -0,0 +1,13 @@
+/** Machine-readable codes emitted when breakdown construction fails. */
+export type TCalculationBreakdownErrorCode = 'INVALID_SEMANTIC' | 'INVALID_DECIMAL' | 'INVALID_CURRENCY' | 'INVALID_DURATION_UNIT' | 'INVALID_OPERATOR' | 'INVALID_ROUNDING' | 'INVALID_ROUNDING_STEP' | 'INVALID_GROUP_ROLE' | 'INVALID_GROUP_ORIENTATION' | 'MISSING_BREAKDOWN' | 'MISSING_RESULT';
+/** Error thrown when a calculation breakdown contains invalid or incomplete input. */
+export declare class CalculationBreakdownError extends Error {
+    readonly code: TCalculationBreakdownErrorCode;
+    /**
+     * Creates a calculation breakdown error.
+     *
+     * @param code - Stable code suitable for programmatic error handling.
+     * @param message - Human-readable explanation of the failure.
+     */
+    constructor(code: TCalculationBreakdownErrorCode, message: string);
+}

package/dist/cjs/calculation-breakdown.error.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CalculationBreakdownError = void 0;
+/** Error thrown when a calculation breakdown contains invalid or incomplete input. */
+class CalculationBreakdownError extends Error {
+    code;
+    /**
+     * Creates a calculation breakdown error.
+     *
+     * @param code - Stable code suitable for programmatic error handling.
+     * @param message - Human-readable explanation of the failure.
+     */
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'CalculationBreakdownError';
+    }
+}
+exports.CalculationBreakdownError = CalculationBreakdownError;

package/dist/cjs/calculation-breakdown.interface.d.ts

@@ -0,0 +1,133 @@
+import type { TCalculationBreakdownDurationUnit, TCalculationBreakdownGroupRole, TCalculationBreakdownGroupOrientation, TCalculationBreakdownNode, TCalculationBreakdownOperator, TCalculationBreakdownOperatorInput, TCalculationBreakdownRounding, TCalculationBreakdownValue } from './calculation-breakdown.type.js';
+/** Optional rounding rules for a duration value. */
+export interface ICalculationBreakdownDurationOptions {
+    /** Direction in which the duration is rounded. Must be used with `step`. */
+    rounding?: TCalculationBreakdownRounding;
+    /** Positive interval to which the duration is rounded. Must be used with `rounding`. */
+    step?: number;
+}
+/** A monetary value represented by an exact decimal string and currency code. */
+export interface ICalculationBreakdownMoneyValue<Semantic extends string> {
+    /** Discriminator for a monetary value. */
+    readonly type: 'money';
+    /** Domain-specific meaning of the value. */
+    readonly semantic: Semantic;
+    /** Exact decimal amount. */
+    readonly amount: string;
+    /** Three-letter uppercase currency code, such as `USD`. */
+    readonly currency: string;
+}
+/** A duration represented by an exact decimal string and unit. */
+export interface ICalculationBreakdownDurationValue<Semantic extends string> extends ICalculationBreakdownDurationOptions {
+    /** Discriminator for a duration value. */
+    readonly type: 'duration';
+    /** Domain-specific meaning of the value. */
+    readonly semantic: Semantic;
+    /** Exact decimal duration. */
+    readonly amount: string;
+    /** Unit in which the duration is expressed. */
+    readonly unit: TCalculationBreakdownDurationUnit;
+}
+/** A dimensionless semantic number represented by an exact decimal string. */
+export interface ICalculationBreakdownNumberValue<Semantic extends string> {
+    /** Discriminator for a semantic number. */
+    readonly type: 'number';
+    /** Domain-specific meaning of the value. */
+    readonly semantic: Semantic;
+    /** Exact decimal value. */
+    readonly value: string;
+}
+/** A percentage represented as an exact fractional decimal string. */
+export interface ICalculationBreakdownPercentValue<Semantic extends string> {
+    /** Discriminator for a percentage value. */
+    readonly type: 'percent';
+    /** Domain-specific meaning of the value. */
+    readonly semantic: Semantic;
+    /** Exact fractional value, where `0.20` represents 20%. */
+    readonly value: string;
+}
+/** A dimensionless numeric literal used inside an expression. */
+export interface ICalculationBreakdownConstantValue {
+    /** Discriminator for a constant. */
+    readonly type: 'constant';
+    /** Exact decimal value. */
+    readonly value: string;
+}
+/** A binary operation recorded in a calculation breakdown. */
+export interface ICalculationBreakdownOperation<Semantic extends string> {
+    /** Discriminator for an operation. */
+    readonly type: 'operation';
+    /** Operation applied to the two operands. */
+    readonly operator: TCalculationBreakdownOperator;
+    /** Left and right operands, in evaluation order. */
+    readonly operands: readonly [
+        TCalculationBreakdownNode<Semantic>,
+        TCalculationBreakdownNode<Semantic>
+    ];
+}
+/** Optional presentation hints for an explicitly grouped expression. */
+export interface ICalculationBreakdownGroupOptions<Semantic extends string = string> {
+    /** Suggests that renderers place this group on its own visual line. */
+    readonly wrap?: boolean;
+    /** Domain-specific meaning of the grouped expression. */
+    readonly semantic?: Semantic;
+    /** Authoritative result of the grouped expression, such as a line subtotal. */
+    readonly result?: TCalculationBreakdownValue<Semantic>;
+    /** Identifies a roll-up whose authoritative result may be emphasized by renderers. */
+    readonly role?: TCalculationBreakdownGroupRole;
+    /** Preferred flow for detail values. Omitted groups default to horizontal. */
+    readonly orientation?: TCalculationBreakdownGroupOrientation;
+}
+/** An explicitly grouped subexpression. */
+export interface ICalculationBreakdownGroup<Semantic extends string> extends ICalculationBreakdownGroupOptions<Semantic> {
+    /** Discriminator for a group. */
+    readonly type: 'group';
+    /** Expression enclosed by the group. */
+    readonly expression: TCalculationBreakdownNode<Semantic>;
+}
+/** Serializable, immutable record of how an externally calculated result was derived. */
+export interface ICalculationBreakdown<Semantic extends string> {
+    /** Root node describing the operations and values in the calculation. */
+    readonly breakdown: TCalculationBreakdownNode<Semantic>;
+    /** Authoritative result supplied by the calling application. */
+    readonly result: TCalculationBreakdownValue<Semantic>;
+}
+/** Factory methods available inside breakdown and result callbacks. */
+export interface ICalculationBreakdownNodeBuilder<Semantic extends string> {
+    /** Creates a monetary value. */
+    money(semantic: Semantic, amount: string, currency: string): ICalculationBreakdownMoneyValue<Semantic>;
+    /** Creates a duration value, optionally with a rounding rule. */
+    duration(semantic: Semantic, amount: string, unit: TCalculationBreakdownDurationUnit, options?: ICalculationBreakdownDurationOptions): ICalculationBreakdownDurationValue<Semantic>;
+    /** Creates a semantic, dimensionless number. */
+    number(semantic: Semantic, value: string): ICalculationBreakdownNumberValue<Semantic>;
+    /** Creates a percentage from a fractional decimal, such as `0.20` for 20%. */
+    percent(semantic: Semantic, value: string): ICalculationBreakdownPercentValue<Semantic>;
+    /** Creates a dimensionless numeric literal. */
+    constant(value: string): ICalculationBreakdownConstantValue;
+    /** Preserves an explicit grouping and optional presentation hints. */
+    group(expression: TCalculationBreakdownNode<Semantic>, options?: ICalculationBreakdownGroupOptions<Semantic>): ICalculationBreakdownGroup<Semantic>;
+    /** Creates a binary operation using any supported operator. */
+    operator(left: TCalculationBreakdownNode<Semantic>, operator: TCalculationBreakdownOperatorInput, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+    /** Adds two expressions. */
+    add(left: TCalculationBreakdownNode<Semantic>, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+    /** Subtracts the right expression from the left expression. */
+    subtract(left: TCalculationBreakdownNode<Semantic>, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+    /** Decimal.js-style alias for `subtract`. */
+    sub(left: TCalculationBreakdownNode<Semantic>, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+    /** Multiplies two expressions. */
+    multiply(left: TCalculationBreakdownNode<Semantic>, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+    /** Decimal.js-style alias for `multiply`. */
+    mul(left: TCalculationBreakdownNode<Semantic>, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+    /** Divides the left expression by the right expression. */
+    divide(left: TCalculationBreakdownNode<Semantic>, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+    /** Decimal.js-style alias for `divide`. */
+    div(left: TCalculationBreakdownNode<Semantic>, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+    /** Selects the smaller of two expressions. */
+    minimum(left: TCalculationBreakdownNode<Semantic>, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+    /** Decimal.js-style alias for `minimum`. */
+    min(left: TCalculationBreakdownNode<Semantic>, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+    /** Selects the larger of two expressions. */
+    maximum(left: TCalculationBreakdownNode<Semantic>, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+    /** Decimal.js-style alias for `maximum`. */
+    max(left: TCalculationBreakdownNode<Semantic>, right: TCalculationBreakdownNode<Semantic>): ICalculationBreakdownOperation<Semantic>;
+}

package/dist/cjs/calculation-breakdown.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/calculation-breakdown.type.d.ts

@@ -0,0 +1,19 @@
+import type { ICalculationBreakdownConstantValue, ICalculationBreakdownDurationValue, ICalculationBreakdownGroup, ICalculationBreakdownMoneyValue, ICalculationBreakdownNumberValue, ICalculationBreakdownOperation, ICalculationBreakdownPercentValue } from './calculation-breakdown.interface.js';
+/** Binary operations that can be recorded in a calculation breakdown. */
+export type TCalculationBreakdownOperator = 'add' | 'subtract' | 'multiply' | 'divide' | 'minimum' | 'maximum';
+/** Decimal.js-style aliases accepted when constructing an operation. */
+export type TCalculationBreakdownOperatorAlias = 'sub' | 'mul' | 'div' | 'min' | 'max';
+/** Any operator name accepted by the builder. */
+export type TCalculationBreakdownOperatorInput = TCalculationBreakdownOperator | TCalculationBreakdownOperatorAlias;
+/** Units available for duration values. */
+export type TCalculationBreakdownDurationUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days';
+/** Direction used when rounding a duration to a step. */
+export type TCalculationBreakdownRounding = 'up' | 'down' | 'nearest';
+/** Semantic role of a grouped expression. */
+export type TCalculationBreakdownGroupRole = 'detail' | 'summary';
+/** Preferred flow of a detail group in structured renderers. */
+export type TCalculationBreakdownGroupOrientation = 'horizontal' | 'vertical';
+/** A semantic value that can be recorded as the authoritative result. */
+export type TCalculationBreakdownValue<Semantic extends string> = ICalculationBreakdownMoneyValue<Semantic> | ICalculationBreakdownDurationValue<Semantic> | ICalculationBreakdownNumberValue<Semantic> | ICalculationBreakdownPercentValue<Semantic>;
+/** Any node that can appear in a calculation breakdown tree. */
+export type TCalculationBreakdownNode<Semantic extends string> = TCalculationBreakdownValue<Semantic> | ICalculationBreakdownConstantValue | ICalculationBreakdownOperation<Semantic> | ICalculationBreakdownGroup<Semantic>;

package/dist/cjs/calculation-breakdown.type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/index.d.ts

@@ -0,0 +1,5 @@
+export { CalculationBreakdownBuilder } from './calculation-breakdown-builder.js';
+export { toHumanString, type ICalculationBreakdownDictionaryEntry, type ICalculationBreakdownHumanStringOptions, type TCalculationBreakdownDictionary, type TCalculationBreakdownDictionaryEntry, type TCalculationBreakdownLocale, } from './calculation-breakdown-human-string.js';
+export { CalculationBreakdownError, type TCalculationBreakdownErrorCode, } from './calculation-breakdown.error.js';
+export type { ICalculationBreakdown, ICalculationBreakdownConstantValue, ICalculationBreakdownDurationOptions, ICalculationBreakdownDurationValue, ICalculationBreakdownNodeBuilder, ICalculationBreakdownGroup, ICalculationBreakdownGroupOptions, ICalculationBreakdownMoneyValue, ICalculationBreakdownNumberValue, ICalculationBreakdownOperation, ICalculationBreakdownPercentValue, } from './calculation-breakdown.interface.js';
+export type { TCalculationBreakdownDurationUnit, TCalculationBreakdownGroupRole, TCalculationBreakdownGroupOrientation, TCalculationBreakdownNode, TCalculationBreakdownOperator, TCalculationBreakdownOperatorAlias, TCalculationBreakdownOperatorInput, TCalculationBreakdownRounding, TCalculationBreakdownValue, } from './calculation-breakdown.type.js';

package/dist/cjs/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CalculationBreakdownError = exports.toHumanString = exports.CalculationBreakdownBuilder = void 0;
+var calculation_breakdown_builder_js_1 = require("./calculation-breakdown-builder.js");
+Object.defineProperty(exports, "CalculationBreakdownBuilder", { enumerable: true, get: function () { return calculation_breakdown_builder_js_1.CalculationBreakdownBuilder; } });
+var calculation_breakdown_human_string_js_1 = require("./calculation-breakdown-human-string.js");
+Object.defineProperty(exports, "toHumanString", { enumerable: true, get: function () { return calculation_breakdown_human_string_js_1.toHumanString; } });
+var calculation_breakdown_error_js_1 = require("./calculation-breakdown.error.js");
+Object.defineProperty(exports, "CalculationBreakdownError", { enumerable: true, get: function () { return calculation_breakdown_error_js_1.CalculationBreakdownError; } });

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { CalculationBreakdownBuilder } from './calculation-breakdown-builder.js';
+export { toHumanString, type ICalculationBreakdownDictionaryEntry, type ICalculationBreakdownHumanStringOptions, type TCalculationBreakdownDictionary, type TCalculationBreakdownDictionaryEntry, type TCalculationBreakdownLocale, } from './calculation-breakdown-human-string.js';
+export { CalculationBreakdownError, type TCalculationBreakdownErrorCode, } from './calculation-breakdown.error.js';
+export type { ICalculationBreakdown, ICalculationBreakdownConstantValue, ICalculationBreakdownDurationOptions, ICalculationBreakdownDurationValue, ICalculationBreakdownNodeBuilder, ICalculationBreakdownGroup, ICalculationBreakdownGroupOptions, ICalculationBreakdownMoneyValue, ICalculationBreakdownNumberValue, ICalculationBreakdownOperation, ICalculationBreakdownPercentValue, } from './calculation-breakdown.interface.js';
+export type { TCalculationBreakdownDurationUnit, TCalculationBreakdownGroupRole, TCalculationBreakdownGroupOrientation, TCalculationBreakdownNode, TCalculationBreakdownOperator, TCalculationBreakdownOperatorAlias, TCalculationBreakdownOperatorInput, TCalculationBreakdownRounding, TCalculationBreakdownValue, } from './calculation-breakdown.type.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EACH,aAAa,EACb,KAAK,oCAAoC,EACzC,KAAK,uCAAuC,EAC5C,KAAK,+BAA+B,EACpC,KAAK,oCAAoC,EACzC,KAAK,2BAA2B,GACnC,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACH,yBAAyB,EACzB,KAAK,8BAA8B,GACtC,MAAM,kCAAkC,CAAC;AAC1C,YAAY,EACR,qBAAqB,EACrB,kCAAkC,EAClC,oCAAoC,EACpC,kCAAkC,EAClC,gCAAgC,EAChC,0BAA0B,EAC1B,iCAAiC,EACjC,+BAA+B,EAC/B,gCAAgC,EAChC,8BAA8B,EAC9B,iCAAiC,GACpC,MAAM,sCAAsC,CAAC;AAC9C,YAAY,EACR,iCAAiC,EACjC,8BAA8B,EAC9B,qCAAqC,EACrC,yBAAyB,EACzB,6BAA6B,EAC7B,kCAAkC,EAClC,kCAAkC,EAClC,6BAA6B,EAC7B,0BAA0B,GAC7B,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { CalculationBreakdownBuilder } from './calculation-breakdown-builder.js';
+export { toHumanString, } from './calculation-breakdown-human-string.js';
+export { CalculationBreakdownError, } from './calculation-breakdown.error.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EACH,aAAa,GAMhB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACH,yBAAyB,GAE5B,MAAM,kCAAkC,CAAC"}

package/docs/_config.yml

@@ -0,0 +1,19 @@
+title: calculation-breakdown
+description: Typed, serializable calculation breakdowns.
+url: https://thismeansmore.github.io
+baseurl: /calculation-breakdown
+theme: minima
+github_username: ThisMeansMore
+
+header_pages:
+  - playground/index.html
+  - changelog.md
+
+plugins:
+  - jekyll-relative-links
+
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default

package/docs/assets/calculation-breakdown/calculation-breakdown-builder.js

@@ -0,0 +1,242 @@
+import { CalculationBreakdownError } from './calculation-breakdown.error.js';
+import { toHumanString, } from './calculation-breakdown-human-string.js';
+const DECIMAL_PATTERN = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/;
+const CURRENCY_PATTERN = /^[A-Z]{3}$/;
+const DURATION_UNITS = new Set([
+    'milliseconds',
+    'seconds',
+    'minutes',
+    'hours',
+    'days',
+]);
+const ROUNDING_MODES = new Set([
+    'up',
+    'down',
+    'nearest',
+]);
+const GROUP_ROLES = new Set([
+    'detail',
+    'summary',
+]);
+const GROUP_ORIENTATIONS = new Set([
+    'horizontal',
+    'vertical',
+]);
+const OPERATORS = new Set([
+    'add',
+    'subtract',
+    'multiply',
+    'divide',
+    'minimum',
+    'maximum',
+]);
+const OPERATOR_ALIASES = {
+    sub: 'subtract',
+    mul: 'multiply',
+    div: 'divide',
+    min: 'minimum',
+    max: 'maximum',
+};
+function assertSemantic(semantic) {
+    if (semantic.trim().length === 0) {
+        throw new CalculationBreakdownError('INVALID_SEMANTIC', 'Semantic must be a non-empty string.');
+    }
+}
+function assertDecimal(value) {
+    if (!DECIMAL_PATTERN.test(value)) {
+        throw new CalculationBreakdownError('INVALID_DECIMAL', `Invalid decimal string: ${value}`);
+    }
+}
+function assertDurationOptions(options) {
+    if (!options)
+        return;
+    const hasRounding = options.rounding !== undefined;
+    const hasStep = options.step !== undefined;
+    const step = options.step;
+    if (hasRounding &&
+        !ROUNDING_MODES.has(options.rounding)) {
+        throw new CalculationBreakdownError('INVALID_ROUNDING', `Invalid rounding mode: ${String(options.rounding)}`);
+    }
+    if (hasRounding !== hasStep) {
+        throw new CalculationBreakdownError('INVALID_ROUNDING_STEP', 'Rounding and step must be provided together.');
+    }
+    if (hasStep &&
+        (step === undefined || !Number.isFinite(step) || step <= 0)) {
+        throw new CalculationBreakdownError('INVALID_ROUNDING_STEP', 'Rounding step must be a positive finite number.');
+    }
+}
+function deepFreeze(value) {
+    if (typeof value !== 'object' || value === null || Object.isFrozen(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    return value;
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Records a typed, serializable breakdown of a calculation performed elsewhere.
+ *
+ * This builder does not evaluate operations or calculate the result. The calling
+ * application supplies every value, including the authoritative result.
+ *
+ * @typeParam Semantic - String union used to label the domain meaning of values.
+ *
+ * @example
+ * ```ts
+ * const breakdown = new CalculationBreakdownBuilder<'price' | 'total'>()
+ *     .breakdown(({ money, constant, multiply }) =>
+ *         multiply(money('price', '100.00', 'USD'), constant('0.9')),
+ *     )
+ *     .result(({ money }) => money('total', '90.00', 'USD'))
+ *     .build();
+ * ```
+ */
+export class CalculationBreakdownBuilder {
+    breakdownValue;
+    resultValue;
+    nodeBuilder = {
+        money: (semantic, amount, currency) => this.createMoney(semantic, amount, currency),
+        duration: (semantic, amount, unit, options) => this.createDuration(semantic, amount, unit, options),
+        number: (semantic, value) => this.createNumber(semantic, value),
+        percent: (semantic, value) => this.createPercent(semantic, value),
+        constant: (value) => this.createConstant(value),
+        group: (expression, options) => this.createGroup(expression, options),
+        operator: (left, operator, right) => this.createOperation(left, operator, right),
+        add: (left, right) => this.createOperation(left, 'add', right),
+        subtract: (left, right) => this.createOperation(left, 'subtract', right),
+        sub: (left, right) => this.createOperation(left, 'sub', right),
+        multiply: (left, right) => this.createOperation(left, 'multiply', right),
+        mul: (left, right) => this.createOperation(left, 'mul', right),
+        divide: (left, right) => this.createOperation(left, 'divide', right),
+        div: (left, right) => this.createOperation(left, 'div', right),
+        minimum: (left, right) => this.createOperation(left, 'minimum', right),
+        min: (left, right) => this.createOperation(left, 'min', right),
+        maximum: (left, right) => this.createOperation(left, 'maximum', right),
+        max: (left, right) => this.createOperation(left, 'max', right),
+    };
+    /**
+     * Sets the root node that describes the calculation.
+     *
+     * @param create - Callback that describes the calculation using typed factories.
+     * @returns This builder for fluent chaining.
+     */
+    breakdown(create) {
+        this.breakdownValue = create(this.nodeBuilder);
+        return this;
+    }
+    /**
+     * Sets the authoritative result calculated by the calling application.
+     *
+     * @param create - Callback that constructs a money, duration, or number value.
+     * @returns This builder for fluent chaining.
+     */
+    result(create) {
+        this.resultValue = create(this.nodeBuilder);
+        return this;
+    }
+    /**
+     * Produces a detached, deeply frozen calculation breakdown.
+     *
+     * @throws {CalculationBreakdownError} If either the breakdown or result is missing.
+     */
+    build() {
+        if (!this.breakdownValue) {
+            throw new CalculationBreakdownError('MISSING_BREAKDOWN', 'A breakdown is required before building.');
+        }
+        if (!this.resultValue) {
+            throw new CalculationBreakdownError('MISSING_RESULT', 'A result is required before building.');
+        }
+        return deepFreeze(cloneJson({
+            breakdown: this.breakdownValue,
+            result: this.resultValue,
+        }));
+    }
+    /** Builds and renders the calculation using localized semantic labels. */
+    toHumanString(options) {
+        return toHumanString(this.build(), options);
+    }
+    createMoney(semantic, amount, currency) {
+        assertSemantic(semantic);
+        assertDecimal(amount);
+        if (!CURRENCY_PATTERN.test(currency)) {
+            throw new CalculationBreakdownError('INVALID_CURRENCY', `Currency must be a three-letter uppercase code: ${currency}`);
+        }
+        return deepFreeze({ type: 'money', semantic, amount, currency });
+    }
+    createDuration(semantic, amount, unit, options) {
+        assertSemantic(semantic);
+        assertDecimal(amount);
+        if (!DURATION_UNITS.has(unit)) {
+            throw new CalculationBreakdownError('INVALID_DURATION_UNIT', `Unsupported duration unit: ${unit}`);
+        }
+        assertDurationOptions(options);
+        return deepFreeze({
+            type: 'duration',
+            semantic,
+            amount,
+            unit,
+            ...(options?.rounding ? { rounding: options.rounding } : {}),
+            ...(options?.step !== undefined ? { step: options.step } : {}),
+        });
+    }
+    createNumber(semantic, value) {
+        assertSemantic(semantic);
+        assertDecimal(value);
+        return deepFreeze({ type: 'number', semantic, value });
+    }
+    createPercent(semantic, value) {
+        assertSemantic(semantic);
+        assertDecimal(value);
+        return deepFreeze({ type: 'percent', semantic, value });
+    }
+    createConstant(value) {
+        assertDecimal(value);
+        return deepFreeze({ type: 'constant', value });
+    }
+    createGroup(expression, options) {
+        if (options?.semantic !== undefined) {
+            assertSemantic(options.semantic);
+        }
+        if (options?.role !== undefined &&
+            !GROUP_ROLES.has(options.role)) {
+            throw new CalculationBreakdownError('INVALID_GROUP_ROLE', `Unsupported group role: ${String(options.role)}`);
+        }
+        if (options?.orientation !== undefined &&
+            !GROUP_ORIENTATIONS.has(options.orientation)) {
+            throw new CalculationBreakdownError('INVALID_GROUP_ORIENTATION', `Unsupported group orientation: ${String(options.orientation)}`);
+        }
+        return deepFreeze({
+            type: 'group',
+            expression,
+            ...(options?.wrap === true ? { wrap: true } : {}),
+            ...(options?.semantic !== undefined
+                ? { semantic: options.semantic }
+                : {}),
+            ...(options?.result !== undefined
+                ? { result: options.result }
+                : {}),
+            ...(options?.role !== undefined
+                ? { role: options.role }
+                : {}),
+            ...(options?.orientation !== undefined
+                ? { orientation: options.orientation }
+                : {}),
+        });
+    }
+    createOperation(left, operator, right) {
+        const normalizedOperator = OPERATOR_ALIASES[operator] ?? operator;
+        if (!OPERATORS.has(normalizedOperator)) {
+            throw new CalculationBreakdownError('INVALID_OPERATOR', `Unsupported operator: ${operator}`);
+        }
+        return deepFreeze({
+            type: 'operation',
+            operator: normalizedOperator,
+            operands: [left, right],
+        });
+    }
+}
+//# sourceMappingURL=calculation-breakdown-builder.js.map