Errors, ordering, and limits
Errors
Validation and calculation throw ModelError with a stable code; path, period, and details may be present depending on where the error occurred. Callback errors are usually wrapped with the declaration name and period. Example codes include:
DECCF_INVALID_MODEL,DECCF_INVALID_TIMELINE,DECCF_INVALID_DATEDECCF_UNDECLARED_REFERENCE,DECCF_DUPLICATE_DECLARATIONDECCF_FLOW_ORDERfor missing or not-yet-calculated dependenciesDECCF_INPUT_DOMAIN,DECCF_INPUT_SHAPE,DECCF_INVALID_RUNDECCF_CURRENCY_MISMATCH,DECCF_INVALID_DISCOUNT_RATEDECCF_INVALID_BOOKING,DECCF_INVALID_BOOKING_AMOUNT,DECCF_UNBALANCED_BOOKINGDECCF_INVALID_TRIGGER,DECCF_AMBIGUOUS_TRIGGER,DECCF_UNDECLARED_TRIGGERDECCF_SCHEDULE_FINER_THAN_TIMELINE,DECCF_PHASE_OVERLAP
Use code for machine handling. The message is intended for diagnosis.
Identify the input needed by a calculation
Use new deccf.ModelError(code, message, details) when a calculation discovers an input rule that depends on its active branch. Use an input-validation code such as DECCF_INPUT_DOMAIN; ordinary calculation-error codes retain their calculation location. The optional details object defaults to {}. A known path identifies the field directly. Alternatively, inputReference identifies a declared input; for a field in an object-array card, include its unique inputRowId and inputFieldPath, an array of declared field names. The calculation resolves these to the full input path. Unknown references, duplicate row IDs and undeclared fields cannot identify a field safely.
This example requires a positive duration only for an active payout. No extra required setting is needed in the input declaration. The duration is measured in whole months. If the supplied duration is invalid, the Calculator can use the model's valid default of 120 months, retain the edited field in red, and describe the assumption in Results.
const duration = deccf.input.integer(120);
const active = deccf.input.boolean(true);
const model = deccf.defineModel({
currency: deccf.currencies.SEK,
timeline: deccf.periods.monthly({ from: "2026-01", count: 1 }),
preconditions: { duration, active },
metrics: {
payment: (ctx) => {
if (!ctx.get(active)) return 0;
const months = ctx.get(duration);
if (months <= 0) {
throw new deccf.ModelError("DECCF_INPUT_DOMAIN", "Duration must be positive.", {
inputReference: duration,
});
}
return 120000 / months;
},
},
});
return model;The error carries its stable code, message and resolved path; optional period identifies the calculation period and cause retains an underlying error. Reference details are replaced by field diagnostics before results leave the calculation. An unrelated model-code failure still appears as a calculation error.
Calculation order
Compilation verifies references, entity parents, agreement subjects, owners, schedules, action targets, and the flow dependency graph. Cycles in flow order are rejected. Per period, fields, lifecycles, and agreements are updated before events. Cashflows then run in dependency order, followed by options and period-end calculations.
Same-period reads of a cashflow require dependsOn. ctx.sum() cannot read future periods. JavaScript callbacks run synchronously.
Run scope
Run options accept inline deterministic.inputs. runScenarios() uses an input-reference Map for each scenario; curve overrides use the { series: { points, interpolation } } form. It returns one result per scenario and accepts Monte Carlo run settings for scenario batches.
The public dates, series, and built-in metrics cover count periods. Projection periods are evaluated, and custom metrics use the last calculated date.
Type declaration and runtime differences
lifecycle.onEnteris declared asAction[]in TypeScript, but runtime expects{ state, actions }entries. Runtime also readsactionson a transition, though that field is absent from the declaration.actions.setFieldaccepts money and input references when created, but runtime ultimately requires a finite number; aMoneyobject is rejected.- Distribution options expose
clipin the options type. Runtime readsclipfrom the distribution's parameter object, so place it there.
See the API overview and calculation context for the current interfaces.
Currency and numbers
Cashflows with an explicit currency must match the model reporting currency. Option payoffs enter model totals and NPV using their numeric amounts, so use the model currency for consistent valuation.
Calculations use JavaScript Number. Money values carry a currency reference; money(), scaleMoney(), and convertMoney() provide amount construction, scaling, and explicit rate-based conversion.