Chain API

The chain API provides a fluent, method-chaining style for multi-step calculations.

Design Principles

1. c-prefix to start: chains begin with cadd, cmul, etc.
2. No prefix to continue: subsequent methods drop the c prefix: .add(), .mul()
3. Function returns function: the chain returns a callable — call it to get the result
4. Any number of arguments: each method accepts multiple arguments
5. Nesting supported: arguments can be other chain objects for complex expressions

Basic Syntax

import { cadd, cmul, csub, cdiv } from "a-calc";

cadd(1, 2, 3)(); // "6"
cmul(2, 3, 4)(); // "24"

cadd(1, 2).mul(3)(); // "9"
cmul(10, 10).sub(1)(); // "99"
csub(100, 20, 10).div(2)(); // "35"

Nested Chains

Chain arguments can be other chain objects, enabling complex nested expressions:

cadd(1, cadd(2, 3))(); // 1 + (2 + 3) = "6"
cmul(cadd(1, 2), cadd(3, 4))(); // (1 + 2) * (3 + 4) = "21"

// Multi-level nesting
cadd(
  cmul(cadd(1, 2), 3), // (1 + 2) * 3 = 9
  cmul(cadd(4, 5), 2), // (4 + 5) * 2 = 18
)(); // 9 + 18 = "27"

Starter Methods

Method	Description	Behavior
cadd(...nums)	Start with addition	Sum all arguments
csub(...nums)	Start with subtraction	First minus rest
cmul(...nums)	Start with multiplication	Multiply all
cdiv(...nums)	Start with division	First divided by rest
cmod(...nums)	Start with modulo	Sequential modulo
cpow(...nums)	Start with power	Sequential power
cidiv(...nums)	Start with integer division	Sequential idiv

cadd(1, 2, 3)(); // "6"
csub(100, 20, 10)(); // "70"
cmul(2, 3, 4)(); // "24"
cdiv(100, 2, 5)(); // "10"
cmod(17, 5)(); // "2"
cpow(2, 3)(); // "8"
cidiv(17, 5)(); // "3"

Chain Methods

Methods on the chain (no c prefix):

Method	Description
.add(...nums)	Add all arguments
.sub(...nums)	Subtract all arguments
.mul(...nums)	Multiply by all arguments
.div(...nums)	Divide by all arguments
.mod(...nums)	Modulo by all arguments
.pow(...nums)	Power by all arguments
.idiv(...nums)	Integer divide by all arguments

cadd(10)
  .add(5, 3) // 10 + 5 + 3 = 18
  .mul(2) // 18 * 2 = 36
  .sub(6)(); // 36 - 6 = 30 // "30"

Formatting Output

Pass a format string to the final call:

cmul(100, 1.1)(); // "110"
cmul(100, 1.1)("=2"); // "110.00"
cdiv(100, 3)("=4"); // "33.3333"
cadd(1000, 234, 567)("=2,"); // "1,801.00"
cmul(0.5, 0.8)("%=2"); // "40.00%"

Error Propagation

Errors propagate automatically through the chain:

cadd(10).div(0).add(100)(); // "-" (error propagates)

Real-World Examples

Shopping Cart

const total = cadd(99.9, 199, 49.5) // item prices
  .mul(0.9) // 10% discount
  .sub(20) // coupon
  .mul(1.06)(
  // tax
  "=2",
); // "296.33"

Compound Interest

const amount = cmul(10000) // principal
  .mul(1.05) // year 1
  .mul(1.05) // year 2
  .mul(1.05)(
  // year 3
  "=2,",
); // "11,576.25"

Complex Nested Calculation

// Multiple items with discounts
const item1 = cmul(cadd(99.9, 199), 0.9);
const item2 = cmul(cadd(49.5, 50.5), 0.8);
const total = cadd(item1, item2);
total("=2,"); // "349.01"