Work with currency and money

A model has one reporting currency, declared in defineModel(). A caller can choose a different denomination for one run without changing the model by passing a currency in the run options.

import { cashflow, currencies, defineModel, entity, inflow, periods, run, schedule } from "deccf";

const building = entity.asset();
const rent = cashflow({ owner: building, direction: inflow, schedule: schedule.monthly(), amount: 12_000 });
const model = defineModel({
  name: "rent-denomination",
  currency: currencies.SEK,
  timeline: periods.monthly({ from: "2026-01", count: 12 }),
  entities: { building },
  flows: { rent },
});

const result = run(model, { currency: currencies.EUR });
return model;

The run option relabels amounts in the selected currency while keeping their numeric values. It does not convert between currencies. To convert an amount using an exchange rate, supply that rate explicitly.

import { addMoney, cashflow, convertMoney, currencies, defineModel, entity, inflow, money, periods, scaleMoney, schedule } from "deccf";

const rent = money(12_000, currencies.SEK);
const annualRent = scaleMoney(rent, 12);
const total = addMoney(rent, annualRent);
const converted = convertMoney(rent, currencies.USD, 0.095);
const building = entity.asset();
const payout = cashflow({ owner: building, direction: inflow, schedule: schedule.annual(), amount: converted });
const model = defineModel({
  name: "money-arithmetic",
  currency: currencies.USD,
  timeline: periods.annual({ from: "2026-01", count: 1 }),
  entities: { building },
  flows: { payout },
});
return model;

money() creates an amount, scaleMoney() multiplies it, and addMoney() / subtractMoney() require matching currencies. convertMoney(value, target, unitsOfTargetPerSource) performs an explicit conversion using the rate you supply. The engine does not fetch exchange rates.

A basic cashflow has a direction (inflow or outflow) and can have a category from category(path). A category can include a display label, which is returned in deterministic.categories. The core has no predefined categories; domain packs can provide them. In account postings, put a category on each account. Each posting row then inherits the category from its target account. See Post cashflows to accounts.

JavaScript numbers use IEEE 754 arithmetic. Money combines a number and a currency, but does not provide decimal-exact arithmetic or automatic minor-unit rounding. Apply rounding rules where your business logic requires them.

Keep the model currency, amount currency, and any conversion explicit. Compilation rejects a cashflow whose declared currency differs from the model currency. The run-level currency option changes the denomination for one execution while leaving numeric values unchanged.

Next: Describe entities, fields, and states.