@trajectonomics/tax 0.0.0-stage → 0.1.0-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,102 @@
+import { a as money, c as ValidateAmountOptions, d as StatutoryCapOptions, f as TaxSupportedCurrency, h as TaxBracket, i as Money, l as validateMonetaryAmount, m as BracketSlice, n as TaxResult, o as thb, p as BracketEvaluationResult, r as TaxSystem, s as usd, t as JurisdictionCode, u as ClampedAmount } from "./types-798sLpt6.mjs";
+/**
+ * Evaluates progressive tax brackets slice-by-slice across multiple tiers.
+ *
+ * Math: Slices taxable income across progressive tiers and sums integer tax per slice.
+ * Units: All inputs and outputs must be integer minor units (satang/cents).
+ *
+ * @param taxableAmount Taxable income in integer minor units.
+ * @param brackets Ordered progressive statutory tax brackets.
+ * @param grossIncome Optional gross income in minor units for statutory effective rate calculation.
+ * @param field Diagnostic field name.
+ * @returns Evaluated bracket result including total tax, slices, effective rate, and marginal rate.
+ * @throws {TaxValidationError} if inputs are invalid.
+ */
+export declare function evaluateBrackets(taxableAmount: number, brackets: readonly TaxBracket[], grossIncome?: number, field?: string): BracketEvaluationResult;
+/**
+ * Clamps a requested deduction, allowance, or expense against a statutory cap.
+ *
+ * @param requested Original requested amount.
+ * @param capOrOptions Numeric cap or StatutoryCapOptions specification.
+ * @param field Diagnostic field name.
+ * @returns Breakdown-ready ClampedAmount structure.
+ * @throws {TaxValidationError} if inputs are negative, NaN, or non-finite.
+ * @example clampCap(150_000, 100_000, "allowance") // { requested: 150000, allowed: 100000, cap: 100000, wasClamped: true }
+ */
+export declare function clampCap(requested: number, capOrOptions: number | StatutoryCapOptions, field?: string): ClampedAmount;
+/**
+ * Error thrown when input values violate mathematical boundaries or statutory constraints.
+ * Exposes field, raw value, and validation reason for transparency and structured error reporting.
+ */
+export declare class TaxValidationError extends Error {
+  readonly field: string;
+  readonly value: unknown;
+  readonly reason: string;
+  constructor(field: string, value: unknown, reason: string);
+}
+/**
+ * Converts a major-unit monetary amount to integer minor units (satang/cent).
+ *
+ * Math: Decimal string expansion and half-away-from-zero rounding to eliminate IEEE 754 float drift.
+ * Units: Input is major currency unit (e.g. THB, USD); output is integer minor units (e.g. Satang, Cents).
+ *
+ * @param amount Amount in major units.
+ * @param currency Supported statutory currency (THB or USD).
+ * @param field Diagnostic field name.
+ * @param options Validation options (e.g. allowNegative for refund balances).
+ * @returns Integer minor units.
+ * @throws {TaxValidationError} if amount is NaN, infinite, or results in a non-safe integer.
+ * @example toMinorUnits(1.14, "USD") // 114 (114 cents)
+ */
+export declare function toMinorUnits(amount: number, currency: TaxSupportedCurrency, field?: string, options?: ValidateAmountOptions): number;
+/**
+ * Converts an integer minor unit amount back to major currency units.
+ *
+ * @param minorUnits Integer minor units.
+ * @param currency Supported statutory currency (THB or USD).
+ * @param field Diagnostic field name.
+ * @param options Validation options (e.g. allowNegative for refund balances).
+ * @returns Amount in major units.
+ * @throws {TaxValidationError} if minorUnits is not a safe integer.
+ * @example fromMinorUnits(1055, "THB") // 10.55
+ */
+export declare function fromMinorUnits(minorUnits: number, currency: TaxSupportedCurrency, field?: string, options?: ValidateAmountOptions): number;
+/**
+ * Supported rounding modes for statutory tax computations.
+ */
+type RoundingMode = "half-up" | "floor" | "ceil";
+/**
+ * Rounds a number to the nearest integer, breaking ties away from zero (standard half-up).
+ *
+ * Math: Rounds fractional halves away from zero (e.g. 1.5 -> 2, -1.5 -> -2).
+ *
+ * @param value Floating-point value.
+ * @returns Rounded integer.
+ */
+export declare function roundHalfUp(value: number): number;
+/**
+ * Applies a statutory percentage rate to an integer minor unit amount using exact rational arithmetic.
+ *
+ * Math: Exact rational scaling via BigInt `(minorUnits * num + modeAdjust) / den`
+ * to eliminate IEEE 754 binary floating-point drift on exact statutory tax rates.
+ * Units: Input and output are integer minor units (satang/cents).
+ *
+ * @param minorUnits Integer minor units amount.
+ * @param rate Statutory rate ratio (e.g. 0.05 for 5%, 0.35 for 35%).
+ * @param rounding Rounding mode (`half-up`, `floor`, or `ceil`).
+ * @param options Validation options (e.g. allowNegative).
+ * @returns Computed tax in integer minor units.
+ * @throws {TaxValidationError} if minorUnits is not a safe integer or rate is outside [0, 1].
+ * @example applyPercentage(90, 0.35) // 32 (exact statutory satang calculation)
+ */
+export declare function applyPercentage(minorUnits: number, rate: number, rounding?: RoundingMode, options?: ValidateAmountOptions): number;
+/**
+ * Standard runner that executes tax calculation on a given TaxSystem instance.
+ *
+ * @param system TaxSystem implementation.
+ * @param input Statutory input parameters.
+ * @returns Standardized TaxResult envelope.
+ */
+export declare function calculateTax<TInput, C extends TaxSupportedCurrency, TBreakdown>(system: TaxSystem<TInput, C, TBreakdown>, input: TInput): TaxResult<C, TBreakdown>;
+export { type BracketEvaluationResult, type BracketSlice, type ClampedAmount, type JurisdictionCode, type Money, type RoundingMode, type StatutoryCapOptions, type TaxBracket, type TaxResult, type TaxSupportedCurrency, type TaxSystem, type ValidateAmountOptions, money, thb, usd, validateMonetaryAmount };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,15 @@
+import { a as usd, c as roundHalfUp, f as validateMonetaryAmount, i as thb, l as fromMinorUnits, m as TaxValidationError, n as evaluateBrackets, r as money, s as applyPercentage, t as clampCap, u as toMinorUnits } from "./clamp-Bse4u0H-.mjs";
+// src/core/system/runner.ts
+/**
+* Standard runner that executes tax calculation on a given TaxSystem instance.
+*
+* @param system TaxSystem implementation.
+* @param input Statutory input parameters.
+* @returns Standardized TaxResult envelope.
+*/
+function calculateTax(system, input) {
+	return system.calculate(input);
+}
+export { TaxValidationError, applyPercentage, calculateTax, clampCap, evaluateBrackets, fromMinorUnits, money, roundHalfUp, thb, toMinorUnits, usd, validateMonetaryAmount };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/core/system/runner.ts"],"sourcesContent":["import type { TaxSupportedCurrency } from \"../money\"\nimport type { TaxResult, TaxSystem } from \"./types\"\n\n/**\n * Standard runner that executes tax calculation on a given TaxSystem instance.\n *\n * @param system TaxSystem implementation.\n * @param input Statutory input parameters.\n * @returns Standardized TaxResult envelope.\n */\nexport function calculateTax<TInput, C extends TaxSupportedCurrency, TBreakdown>(\n\tsystem: TaxSystem<TInput, C, TBreakdown>,\n\tinput: TInput,\n): TaxResult<C, TBreakdown> {\n\treturn system.calculate(input)\n}\n"],"mappings":";;;;;;;;;AAUA,SAAgB,aACf,QACA,OAC2B;CAC3B,OAAO,OAAO,UAAU,KAAK;AAC9B"}