calculation-breakdown 0.0.0-stage → 0.1.2

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

@@ -0,0 +1 @@
+{"version":3,"file":"calculation-breakdown-human-string.js","sourceRoot":"","sources":["../src/calculation-breakdown-human-string.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,14 @@
+/** 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);
+}
+//# sourceMappingURL=calculation-breakdown.error.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calculation-breakdown.error.d.ts","sourceRoot":"","sources":["../src/calculation-breakdown.error.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,MAAM,MAAM,8BAA8B,GACpC,kBAAkB,GAClB,iBAAiB,GACjB,kBAAkB,GAClB,uBAAuB,GACvB,kBAAkB,GAClB,kBAAkB,GAClB,uBAAuB,GACvB,oBAAoB,GACpB,2BAA2B,GAC3B,mBAAmB,GACnB,gBAAgB,CAAC;AAEvB,sFAAsF;AACtF,qBAAa,yBAA0B,SAAQ,KAAK;IAQ5C,QAAQ,CAAC,IAAI,EAAE,8BAA8B;IAPjD;;;;;OAKG;gBAEU,IAAI,EAAE,8BAA8B,EAC7C,OAAO,EAAE,MAAM;CAKtB"}

package/dist/calculation-breakdown.error.js

@@ -0,0 +1,16 @@
+/** Error thrown when a calculation breakdown contains invalid or incomplete input. */
+export 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';
+    }
+}
+//# sourceMappingURL=calculation-breakdown.error.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calculation-breakdown.error.js","sourceRoot":"","sources":["../src/calculation-breakdown.error.ts"],"names":[],"mappings":"AAcA,sFAAsF;AACtF,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAQnC;IAPb;;;;;OAKG;IACH,YACa,IAAoC,EAC7C,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,SAAI,GAAJ,IAAI,CAAgC;QAI7C,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC5C,CAAC;CACJ"}

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

@@ -0,0 +1,134 @@
+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>;
+}
+//# sourceMappingURL=calculation-breakdown.interface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calculation-breakdown.interface.d.ts","sourceRoot":"","sources":["../src/calculation-breakdown.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,iCAAiC,EACjC,8BAA8B,EAC9B,qCAAqC,EACrC,yBAAyB,EACzB,6BAA6B,EAC7B,kCAAkC,EAClC,6BAA6B,EAC7B,0BAA0B,EAC7B,MAAM,iCAAiC,CAAC;AAEzC,oDAAoD;AACpD,MAAM,WAAW,oCAAoC;IACjD,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,6BAA6B,CAAC;IACzC,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,iFAAiF;AACjF,MAAM,WAAW,+BAA+B,CAAC,QAAQ,SAAS,MAAM;IACpE,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;AAED,kEAAkE;AAClE,MAAM,WAAW,kCAAkC,CAAC,QAAQ,SAAS,MAAM,CACvE,SAAQ,oCAAoC;IAC5C,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;CACpD;AAED,8EAA8E;AAC9E,MAAM,WAAW,gCAAgC,CAAC,QAAQ,SAAS,MAAM;IACrE,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,iCAAiC,CAAC,QAAQ,SAAS,MAAM;IACtE,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED,iEAAiE;AACjE,MAAM,WAAW,kCAAkC;IAC/C,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CAC1B;AAED,8DAA8D;AAC9D,MAAM,WAAW,8BAA8B,CAAC,QAAQ,SAAS,MAAM;IACnE,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,6BAA6B,CAAC;IACjD,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,SAAS;QACxB,yBAAyB,CAAC,QAAQ,CAAC;QACnC,yBAAyB,CAAC,QAAQ,CAAC;KACtC,CAAC;CACL;AAED,wEAAwE;AACxE,MAAM,WAAW,iCAAiC,CAC9C,QAAQ,SAAS,MAAM,GAAG,MAAM;IAEhC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IACvD,sFAAsF;IACtF,QAAQ,CAAC,IAAI,CAAC,EAAE,8BAA8B,CAAC;IAC/C,8EAA8E;IAC9E,QAAQ,CAAC,WAAW,CAAC,EAAE,qCAAqC,CAAC;CAChE;AAED,2CAA2C;AAC3C,MAAM,WAAW,0BAA0B,CAAC,QAAQ,SAAS,MAAM,CAC/D,SAAQ,iCAAiC,CAAC,QAAQ,CAAC;IACnD,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC,QAAQ,CAAC,CAAC;CAC5D;AAED,yFAAyF;AACzF,MAAM,WAAW,qBAAqB,CAAC,QAAQ,SAAS,MAAM;IAC1D,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC,QAAQ,CAAC,CAAC;IACxD,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC;CACzD;AAED,uEAAuE;AACvE,MAAM,WAAW,gCAAgC,CAAC,QAAQ,SAAS,MAAM;IACrE,gCAAgC;IAChC,KAAK,CACD,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACjB,+BAA+B,CAAC,QAAQ,CAAC,CAAC;IAC7C,iEAAiE;IACjE,QAAQ,CACJ,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,iCAAiC,EACvC,OAAO,CAAC,EAAE,oCAAoC,GAC/C,kCAAkC,CAAC,QAAQ,CAAC,CAAC;IAChD,gDAAgD;IAChD,MAAM,CACF,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,GACd,gCAAgC,CAAC,QAAQ,CAAC,CAAC;IAC9C,8EAA8E;IAC9E,OAAO,CACH,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,MAAM,GACd,iCAAiC,CAAC,QAAQ,CAAC,CAAC;IAC/C,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,kCAAkC,CAAC;IAC5D,sEAAsE;IACtE,KAAK,CACD,UAAU,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EAC/C,OAAO,CAAC,EAAE,iCAAiC,CAAC,QAAQ,CAAC,GACtD,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IACxC,+DAA+D;IAC/D,QAAQ,CACJ,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,QAAQ,EAAE,kCAAkC,EAC5C,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC5C,4BAA4B;IAC5B,GAAG,CACC,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC5C,+DAA+D;IAC/D,QAAQ,CACJ,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC5C,6CAA6C;IAC7C,GAAG,CACC,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC5C,kCAAkC;IAClC,QAAQ,CACJ,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC5C,6CAA6C;IAC7C,GAAG,CACC,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC5C,2DAA2D;IAC3D,MAAM,CACF,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC5C,2CAA2C;IAC3C,GAAG,CACC,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC5C,8CAA8C;IAC9C,OAAO,CACH,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC5C,4CAA4C;IAC5C,GAAG,CACC,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC5C,6CAA6C;IAC7C,OAAO,CACH,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC5C,4CAA4C;IAC5C,GAAG,CACC,IAAI,EAAE,yBAAyB,CAAC,QAAQ,CAAC,EACzC,KAAK,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC3C,8BAA8B,CAAC,QAAQ,CAAC,CAAC;CAC/C"}

package/dist/calculation-breakdown.interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=calculation-breakdown.interface.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calculation-breakdown.interface.js","sourceRoot":"","sources":["../src/calculation-breakdown.interface.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,20 @@
+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>;
+//# sourceMappingURL=calculation-breakdown.type.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calculation-breakdown.type.d.ts","sourceRoot":"","sources":["../src/calculation-breakdown.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,kCAAkC,EAClC,kCAAkC,EAClC,0BAA0B,EAC1B,+BAA+B,EAC/B,gCAAgC,EAChC,8BAA8B,EAC9B,iCAAiC,EACpC,MAAM,sCAAsC,CAAC;AAE9C,yEAAyE;AACzE,MAAM,MAAM,6BAA6B,GACnC,KAAK,GACL,UAAU,GACV,UAAU,GACV,QAAQ,GACR,SAAS,GACT,SAAS,CAAC;AAEhB,wEAAwE;AACxE,MAAM,MAAM,kCAAkC,GACxC,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,CAAC;AAEZ,iDAAiD;AACjD,MAAM,MAAM,kCAAkC,GACxC,6BAA6B,GAC7B,kCAAkC,CAAC;AAEzC,2CAA2C;AAC3C,MAAM,MAAM,iCAAiC,GACvC,cAAc,GACd,SAAS,GACT,SAAS,GACT,OAAO,GACP,MAAM,CAAC;AAEb,yDAAyD;AACzD,MAAM,MAAM,6BAA6B,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;AAEtE,6CAA6C;AAC7C,MAAM,MAAM,8BAA8B,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElE,gEAAgE;AAChE,MAAM,MAAM,qCAAqC,GAC3C,YAAY,GACZ,UAAU,CAAC;AAEjB,yEAAyE;AACzE,MAAM,MAAM,0BAA0B,CAAC,QAAQ,SAAS,MAAM,IACxD,+BAA+B,CAAC,QAAQ,CAAC,GACzC,kCAAkC,CAAC,QAAQ,CAAC,GAC5C,gCAAgC,CAAC,QAAQ,CAAC,GAC1C,iCAAiC,CAAC,QAAQ,CAAC,CAAC;AAElD,gEAAgE;AAChE,MAAM,MAAM,yBAAyB,CAAC,QAAQ,SAAS,MAAM,IACvD,0BAA0B,CAAC,QAAQ,CAAC,GACpC,kCAAkC,GAClC,8BAA8B,CAAC,QAAQ,CAAC,GACxC,0BAA0B,CAAC,QAAQ,CAAC,CAAC"}

package/dist/calculation-breakdown.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=calculation-breakdown.type.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calculation-breakdown.type.js","sourceRoot":"","sources":["../src/calculation-breakdown.type.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,55 @@
+import { type ICalculationBreakdownHumanStringOptions } from './calculation-breakdown-human-string.js';
+import type { ICalculationBreakdown, ICalculationBreakdownNodeBuilder } from './calculation-breakdown.interface.js';
+import type { TCalculationBreakdownNode, TCalculationBreakdownValue } from './calculation-breakdown.type.js';
+/**
+ * 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 declare class CalculationBreakdownBuilder<Semantic extends string> {
+    private breakdownValue?;
+    private resultValue?;
+    private readonly nodeBuilder;
+    /**
+     * 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: (builder: ICalculationBreakdownNodeBuilder<Semantic>) => TCalculationBreakdownNode<Semantic>): 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: (builder: ICalculationBreakdownNodeBuilder<Semantic>) => TCalculationBreakdownValue<Semantic>): this;
+    /**
+     * Produces a detached, deeply frozen calculation breakdown.
+     *
+     * @throws {CalculationBreakdownError} If either the breakdown or result is missing.
+     */
+    build(): ICalculationBreakdown<Semantic>;
+    /** Builds and renders the calculation using localized semantic labels. */
+    toHumanString(options: ICalculationBreakdownHumanStringOptions<Semantic>): string;
+    private createMoney;
+    private createDuration;
+    private createNumber;
+    private createPercent;
+    private createConstant;
+    private createGroup;
+    private createOperation;
+}

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

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CalculationBreakdownBuilder = void 0;
+const calculation_breakdown_error_js_1 = require("./calculation-breakdown.error.js");
+const calculation_breakdown_human_string_js_1 = require("./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 calculation_breakdown_error_js_1.CalculationBreakdownError('INVALID_SEMANTIC', 'Semantic must be a non-empty string.');
+    }
+}
+function assertDecimal(value) {
+    if (!DECIMAL_PATTERN.test(value)) {
+        throw new calculation_breakdown_error_js_1.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 calculation_breakdown_error_js_1.CalculationBreakdownError('INVALID_ROUNDING', `Invalid rounding mode: ${String(options.rounding)}`);
+    }
+    if (hasRounding !== hasStep) {
+        throw new calculation_breakdown_error_js_1.CalculationBreakdownError('INVALID_ROUNDING_STEP', 'Rounding and step must be provided together.');
+    }
+    if (hasStep &&
+        (step === undefined || !Number.isFinite(step) || step <= 0)) {
+        throw new calculation_breakdown_error_js_1.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();
+ * ```
+ */
+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 calculation_breakdown_error_js_1.CalculationBreakdownError('MISSING_BREAKDOWN', 'A breakdown is required before building.');
+        }
+        if (!this.resultValue) {
+            throw new calculation_breakdown_error_js_1.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 (0, calculation_breakdown_human_string_js_1.toHumanString)(this.build(), options);
+    }
+    createMoney(semantic, amount, currency) {
+        assertSemantic(semantic);
+        assertDecimal(amount);
+        if (!CURRENCY_PATTERN.test(currency)) {
+            throw new calculation_breakdown_error_js_1.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 calculation_breakdown_error_js_1.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 calculation_breakdown_error_js_1.CalculationBreakdownError('INVALID_GROUP_ROLE', `Unsupported group role: ${String(options.role)}`);
+        }
+        if (options?.orientation !== undefined &&
+            !GROUP_ORIENTATIONS.has(options.orientation)) {
+            throw new calculation_breakdown_error_js_1.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 calculation_breakdown_error_js_1.CalculationBreakdownError('INVALID_OPERATOR', `Unsupported operator: ${operator}`);
+        }
+        return deepFreeze({
+            type: 'operation',
+            operator: normalizedOperator,
+            operands: [left, right],
+        });
+    }
+}
+exports.CalculationBreakdownBuilder = CalculationBreakdownBuilder;

package/dist/cjs/calculation-breakdown-human-string.d.ts

@@ -0,0 +1,23 @@
+import type { ICalculationBreakdown } from './calculation-breakdown.interface.js';
+/** Locales supported by the built-in human-readable renderer. */
+export type TCalculationBreakdownLocale = 'en' | 'cs';
+/** A semantic label with optional explanatory copy for richer UIs. */
+export interface ICalculationBreakdownDictionaryEntry {
+    readonly name: string;
+    readonly description: string;
+}
+/** A short label or a label with explanatory copy. */
+export type TCalculationBreakdownDictionaryEntry = string | ICalculationBreakdownDictionaryEntry;
+/** Semantic labels grouped by supported locale. */
+export type TCalculationBreakdownDictionary<Semantic extends string> = Partial<Record<TCalculationBreakdownLocale, Partial<Record<Semantic, TCalculationBreakdownDictionaryEntry>>>>;
+/** Options for rendering a calculation breakdown as human-readable text. */
+export interface ICalculationBreakdownHumanStringOptions<Semantic extends string> {
+    /** Language and decimal separator used by the renderer. */
+    readonly locale: TCalculationBreakdownLocale;
+    /** Localized labels for domain semantics. Missing labels use the semantic key. */
+    readonly dictionary: TCalculationBreakdownDictionary<Semantic>;
+    /** Whether semantic names are appended to values. Defaults to true. */
+    readonly includeNames?: boolean;
+}
+/** Renders a plain calculation breakdown without changing its serialized form. */
+export declare function toHumanString<Semantic extends string>(calculation: ICalculationBreakdown<Semantic>, options: ICalculationBreakdownHumanStringOptions<Semantic>): string;