Skip to content
TotalFinance

Commodities · @insiderfinance/totalfinance

@insiderfinance/totalfinance/commodities

import { … } from '@insiderfinance/totalfinance/commodities'
stable-by-law (pre-1.0; not a 1.0 stability guarantee)iface 31type 1fn 14JSON ↗
iface

ImpliedStorageCostResult

#

Result of impliedStorageCost.

Signature
import type { ImpliedStorageCostResult } from '@insiderfinance/totalfinance/commodities';

/** Result of {@link impliedStorageCost}. */
export interface ImpliedStorageCostResult {
    /** `annualizedCarry − annualFinancingRate + annualConvenienceYield` — the rate the pair implies. */
    impliedAnnualStorageCostRate: number;
    assumptions: {
        compounding: InterestCompounding;
        /** The fixed inversion prose: storage = implied carry − financing + convenience. */
        inversion: string;
    };
    diagnostics: {
        warnings: string[];
    };
}
Fields, parameters and returned members (8)
Name · typeMeaning · unitRequired · default
assumptions{ compounding: InterestCompounding; inversion: string; }—unitless by nameRequiredNo @default declared
assumptions.compoundingInterestCompounding—unitless by nameRequiredNo @default declared
assumptions.compounding.periodsPerYearnumber—per year (count)RequiredNo @default declared
assumptions.compounding.type'periodic'—unitless by nameRequiredNo @default declared
assumptions.inversionstring

The fixed inversion prose: storage = implied carry − financing + convenience.

unitless by name
RequiredNo @default declared
diagnostics{ warnings: string[]; }—unitless by nameRequiredNo @default declared
diagnostics.warningsstring[]—unitless by nameRequiredNo @default declared
impliedAnnualStorageCostRatenumber

annualizedCarry − annualFinancingRate + annualConvenienceYield — the rate the pair implies.

decimal rate (0.05 = 5%)
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

RollReturnDecompositionInput

#

Input for rollReturnDecomposition.

Signature
import type { RollReturnDecompositionInput } from '@insiderfinance/totalfinance/commodities';

/** Input for {@link rollReturnDecomposition}. */
export interface RollReturnDecompositionInput {
    /** Spot price at the start of the holding period, > 0. */
    initialSpotPrice: number;
    /** Spot price at the end of the holding period (the roll instant), > 0. */
    finalSpotPrice: number;
    /** Price of the held contract at the start of the holding period, > 0. */
    initialContractPrice: number;
    /** Price of the held contract at the end of the holding period, BEFORE rolling, > 0. */
    finalContractPriceBeforeRoll: number;
    /** Price of the next contract at the roll instant, > 0. */
    nextContractPriceAtRoll: number;
}
Fields, parameters and returned members (5)
Name · typeMeaning · unitRequired · default
finalContractPriceBeforeRollnumber

Price of the held contract at the end of the holding period, BEFORE rolling, > 0.

unitless by name
RequiredNo @default declared
finalSpotPricenumber

Spot price at the end of the holding period (the roll instant), > 0.

currency amount (the field or record currency)
RequiredNo @default declared
initialContractPricenumber

Price of the held contract at the start of the holding period, > 0.

currency amount (the field or record currency)
RequiredNo @default declared
initialSpotPricenumber

Spot price at the start of the holding period, > 0.

currency amount (the field or record currency)
RequiredNo @default declared
nextContractPriceAtRollnumber

Price of the next contract at the roll instant, > 0.

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

RollReturnDecompositionResult

#

Result of rollReturnDecomposition.

Signature
import type { RollReturnDecompositionResult } from '@insiderfinance/totalfinance/commodities';

/** Result of {@link rollReturnDecomposition}. */
export interface RollReturnDecompositionResult {
    /**
     * The OBSERVED total return on the held contract over the holding period:
     * `finalContractPriceBeforeRoll / initialContractPrice − 1`.
     */
    totalHoldingReturn: number;
    /** `finalSpotPrice / initialSpotPrice − 1` — the spot move over the period. */
    spotMoveReturn: number;
    /**
     * The change in the contract's basis ratio to spot over the period:
     * `(finalContractPriceBeforeRoll / finalSpotPrice) / (initialContractPrice / initialSpotPrice) − 1`
     * — the carry/convergence earned as the contract pulls toward spot (positive for a long in
     * backwardation).
     */
    carryConvergenceReturn: number;
    /**
     * The roll leg, stated SEPARATELY: the roll is cash-neutral at execution, so its yield
     * `(finalContractPriceBeforeRoll − nextContractPriceAtRoll) / nextContractPriceAtRoll` accrues
     * over the NEXT holding period and is never added into `totalHoldingReturn`.
     */
    rollLeg: {
        rollYieldFraction: number;
        /** The fixed roll-leg prose: cash-neutral at execution, accrues next period. */
        convention: string;
    };
    assumptions: {
        /** The fixed reconciliation prose: the components compound exactly to the observed total. */
        reconciliation: string;
        declaredResidualBound: 1e-12;
    };
    diagnostics: {
        warnings: string[];
        /** `(1 + totalHoldingReturn) − (1 + spotMoveReturn) × (1 + carryConvergenceReturn)` — floating point only. */
        reconciliationResidual: number;
    };
}
Fields, parameters and returned members (12)
Name · typeMeaning · unitRequired · default
assumptions{ declaredResidualBound: 1e-12; reconciliation: string; }—unitless by nameRequiredNo @default declared
assumptions.declaredResidualBound1e-12—unitless by nameRequiredNo @default declared
assumptions.reconciliationstring

The fixed reconciliation prose: the components compound exactly to the observed total.

unitless by name
RequiredNo @default declared
carryConvergenceReturnnumber

The change in the contract's basis ratio to spot over the period: (finalContractPriceBeforeRoll / finalSpotPrice) / (initialContractPrice / initialSpotPrice) − 1 — the carry/convergence earned as the contract pulls toward spot (positive for a long in backwardation).

unitless by name
RequiredNo @default declared
diagnostics{ reconciliationResidual: number; warnings: string[]; }—unitless by nameRequiredNo @default declared
diagnostics.reconciliationResidualnumber

(1 + totalHoldingReturn) − (1 + spotMoveReturn) × (1 + carryConvergenceReturn) — floating point only.

unitless by name
RequiredNo @default declared
diagnostics.warningsstring[]—unitless by nameRequiredNo @default declared
rollLeg{ convention: string; rollYieldFraction: number; }

The roll leg, stated SEPARATELY: the roll is cash-neutral at execution, so its yield (finalContractPriceBeforeRoll − nextContractPriceAtRoll) / nextContractPriceAtRoll accrues over the NEXT holding period and is never added into totalHoldingReturn.

unitless by name
RequiredNo @default declared
rollLeg.conventionstring

The fixed roll-leg prose: cash-neutral at execution, accrues next period.

unitless by name
RequiredNo @default declared
rollLeg.rollYieldFractionnumber—decimal fraction / multipleRequiredNo @default declared
spotMoveReturnnumber

finalSpotPrice / initialSpotPrice − 1 — the spot move over the period.

unitless by name
RequiredNo @default declared
totalHoldingReturnnumber

The OBSERVED total return on the held contract over the holding period: finalContractPriceBeforeRoll / initialContractPrice − 1.

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

RollYieldInput

#

Input for rollYield.

Signature
import type { RollYieldInput } from '@insiderfinance/totalfinance/commodities';

// ---------------------------------------------------------------------------------------------------
// Roll yield and roll-return decomposition
// ---------------------------------------------------------------------------------------------------
/** Input for {@link rollYield}. */
export interface RollYieldInput {
    /** Price of the contract being rolled OUT of (the expiring one), > 0. */
    expiringContractPrice: number;
    /** Price of the contract being rolled INTO (the next one), > 0. */
    nextContractPrice: number;
    /**
     * The spot price at the roll instant, > 0 — supplied only when observed. Without it the
     * spot-relative decomposition is ABSENT with its reason, never guessed.
     */
    spotPriceAtRoll?: number;
}
Fields, parameters and returned members (3)
Name · typeMeaning · unitRequired · default
expiringContractPricenumber

Price of the contract being rolled OUT of (the expiring one), > 0.

currency amount (the field or record currency)
RequiredNo @default declared
nextContractPricenumber

Price of the contract being rolled INTO (the next one), > 0.

currency amount (the field or record currency)
RequiredNo @default declared
spotPriceAtRollnumber

The spot price at the roll instant, > 0 — supplied only when observed. Without it the spot-relative decomposition is ABSENT with its reason, never guessed.

unitless by name
OptionalNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

RollYieldResult

#

Result of rollYield.

Signature
import type { RollYieldResult } from '@insiderfinance/totalfinance/commodities';

/** Result of {@link rollYield}. */
export interface RollYieldResult {
    /**
     * `(expiringContractPrice − nextContractPrice) / nextContractPrice` — the yield a long roller
     * locks in for the next holding period under a static curve. SIGN LAW: positive in
     * backwardation (next below expiring), negative in contango.
     */
    rollYieldFraction: number;
    /**
     * Spot-relative decomposition, present exactly when `spotPriceAtRoll` was supplied. The two
     * components COMPOUND (they do not sum): with `e = expiringVersusSpotFraction` and
     * `n = nextVersusSpotFraction`, `(1 + rollYieldFraction) = (1 + e) / (1 + n)` EXACTLY — an
     * algebraic identity, since `(E/S) / (N/S) = E/N`.
     */
    decomposition?: {
        /**
         * `(expiringContractPrice − spotPriceAtRoll) / spotPriceAtRoll` — the expiring contract's
         * residual basis to spot (near zero when rolled at expiry; the carry already converged).
         */
        expiringVersusSpotFraction: number;
        /**
         * `(nextContractPrice − spotPriceAtRoll) / spotPriceAtRoll` — the curve slope out to the next
         * contract; NEGATIVE in backwardation, which is exactly where positive roll yield comes from.
         */
        nextVersusSpotFraction: number;
    };
    /** Present exactly when the decomposition is absent — the reason, never a guessed spot. */
    decompositionAbsentReason?: string;
    assumptions: {
        /** The fixed direction prose: a long roller out of the expiring contract into the next. */
        rollDirection: string;
        /** The fixed sign-law prose: positive in backwardation, negative in contango. */
        signLaw: string;
        /** The fixed decomposition prose: the spot-relative components compound exactly. */
        decompositionConvention: string;
    };
    diagnostics: {
        warnings: string[];
    };
}
Fields, parameters and returned members (11)
Name · typeMeaning · unitRequired · default
assumptions{ decompositionConvention: string; rollDirection: string; signLaw: string; }—unitless by nameRequiredNo @default declared
assumptions.decompositionConventionstring

The fixed decomposition prose: the spot-relative components compound exactly.

unitless by name
RequiredNo @default declared
assumptions.rollDirectionstring

The fixed direction prose: a long roller out of the expiring contract into the next.

unitless by name
RequiredNo @default declared
assumptions.signLawstring

The fixed sign-law prose: positive in backwardation, negative in contango.

unitless by name
RequiredNo @default declared
decomposition{ expiringVersusSpotFraction: number; nextVersusSpotFraction: number; }

Spot-relative decomposition, present exactly when spotPriceAtRoll was supplied. The two components COMPOUND (they do not sum): with e = expiringVersusSpotFraction and n = nextVersusSpotFraction, (1 + rollYieldFraction) = (1 + e) / (1 + n) EXACTLY — an algebraic identity, since (E/S) / (N/S) = E/N.

unitless by name
OptionalNo @default declared
decomposition.expiringVersusSpotFractionnumber

(expiringContractPrice − spotPriceAtRoll) / spotPriceAtRoll — the expiring contract's residual basis to spot (near zero when rolled at expiry; the carry already converged).

decimal fraction / multiple
RequiredNo @default declared
decomposition.nextVersusSpotFractionnumber

(nextContractPrice − spotPriceAtRoll) / spotPriceAtRoll — the curve slope out to the next contract; NEGATIVE in backwardation, which is exactly where positive roll yield comes from.

decimal fraction / multiple
RequiredNo @default declared
decompositionAbsentReasonstring

Present exactly when the decomposition is absent — the reason, never a guessed spot.

unitless by name
OptionalNo @default declared
diagnostics{ warnings: string[]; }—unitless by nameRequiredNo @default declared
diagnostics.warningsstring[]—unitless by nameRequiredNo @default declared
rollYieldFractionnumber

(expiringContractPrice − nextContractPrice) / nextContractPrice — the yield a long roller locks in for the next holding period under a static curve. SIGN LAW: positive in backwardation (next below expiring), negative in contango.

decimal fraction / multiple
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

SeasonalityMonthRow

#

One calendar-month row of a seasonalityProfile.

Signature
import type { SeasonalityMonthRow } from '@insiderfinance/totalfinance/commodities';

/** One calendar-month row of a {@link seasonalityProfile}. */
export interface SeasonalityMonthRow {
    /** Calendar month, 1..12. */
    month: number;
    observationCount: number;
    /** The requested statistic over the month's observations — `null` for an empty month. */
    statisticValue: number | null;
    /** Present exactly when `statisticValue` is null. */
    statisticValueAbsentReason?: string;
}
Fields, parameters and returned members (4)
Name · typeMeaning · unitRequired · default
monthnumber

Calendar month, 1..12.

unitless by name
RequiredNo @default declared
observationCountnumber—count (integer)RequiredNo @default declared
statisticValuenumber | null

The requested statistic over the month's observations — null for an empty month.

currency amount (the field or record currency)
RequiredNo @default declared
statisticValueAbsentReasonstring

Present exactly when statisticValue is null.

unitless by name
OptionalNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

SeasonalityObservation

#

One dated observation for seasonalityProfile.

Signature
import type { SeasonalityObservation } from '@insiderfinance/totalfinance/commodities';

// ---------------------------------------------------------------------------------------------------
// Seasonality
// ---------------------------------------------------------------------------------------------------
/** One dated observation for {@link seasonalityProfile}. */
export interface SeasonalityObservation {
    /** Strict `YYYY-MM-DD` calendar date. */
    observationDate: string;
    value: number;
}
Fields, parameters and returned members (2)
Name · typeMeaning · unitRequired · default
observationDatestring

Strict YYYY-MM-DD calendar date.

calendar date (YYYY-MM-DD)
RequiredNo @default declared
valuenumber—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

SeasonalityProfileInput

#

Input for seasonalityProfile.

Signature
import type { SeasonalityProfileInput } from '@insiderfinance/totalfinance/commodities';

/** Input for {@link seasonalityProfile}. */
export interface SeasonalityProfileInput {
    observations: readonly SeasonalityObservation[];
    /** The per-month statistic — explicit, never defaulted. */
    statistic: 'mean' | 'median';
}
Fields, parameters and returned members (2)
Name · typeMeaning · unitRequired · default
observationsreadonly SeasonalityObservation[]—unitless by nameRequiredNo @default declared
statistic'mean' | 'median'

The per-month statistic — explicit, never defaulted.

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

SeasonalityProfileResult

#

Result of seasonalityProfile.

Signature
import type { SeasonalityProfileResult } from '@insiderfinance/totalfinance/commodities';

/** Result of {@link seasonalityProfile}. */
export interface SeasonalityProfileResult {
    /** Twelve rows, months 1..12 in order — empty months are null WITH reason, never dropped. */
    months: SeasonalityMonthRow[];
    /** The mean over ALL observations (regardless of the per-month statistic). */
    overallMean: number;
    assumptions: {
        statistic: 'mean' | 'median';
        /** The fixed scope prose: descriptive only — no seasonality is invented. */
        scope: string;
    };
    diagnostics: {
        warnings: string[];
        /** Observation counts by calendar month, index 0 = January. */
        observationCountByMonth: number[];
    };
}
Fields, parameters and returned members (8)
Name · typeMeaning · unitRequired · default
assumptions{ scope: string; statistic: 'mean' | 'median'; }—unitless by nameRequiredNo @default declared
assumptions.scopestring

The fixed scope prose: descriptive only — no seasonality is invented.

unitless by name
RequiredNo @default declared
assumptions.statistic'mean' | 'median'—unitless by nameRequiredNo @default declared
diagnostics{ observationCountByMonth: number[]; warnings: string[]; }—unitless by nameRequiredNo @default declared
diagnostics.observationCountByMonthnumber[]

Observation counts by calendar month, index 0 = January.

unitless by name
RequiredNo @default declared
diagnostics.warningsstring[]—unitless by nameRequiredNo @default declared
monthsSeasonalityMonthRow[]

Twelve rows, months 1..12 in order — empty months are null WITH reason, never dropped.

unitless by name
RequiredNo @default declared
overallMeannumber

The mean over ALL observations (regardless of the per-month statistic).

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

type

TermStructureState

#

The four disclosed term-structure states.

Signature
import type { TermStructureState } from '@insiderfinance/totalfinance/commodities';

// ---------------------------------------------------------------------------------------------------
// Term-structure state
// ---------------------------------------------------------------------------------------------------
/** The four disclosed term-structure states. */
export type TermStructureState = 'contango' | 'backwardation' | 'flat' | 'indeterminate';

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

TermStructureStateInput

#

Input for termStructureState.

Signature
import type { TermStructureStateInput } from '@insiderfinance/totalfinance/commodities';

/** Input for {@link termStructureState}. */
export interface TermStructureStateInput {
    /** The forward curve — ≥ 2 points, strictly ascending delivery times. */
    curve: readonly CommodityCurvePoint[];
    /**
     * REQUIRED explicit tolerance (e.g. `0.001`): a pairwise price change with
     * `|forwardPrice[i+1] / forwardPrice[i] − 1| ≤ flatToleranceFraction` counts as flat. No
     * default — how much wiggle is "flat" is a judgment the caller must state.
     */
    flatToleranceFraction: number;
}
Fields, parameters and returned members (2)
Name · typeMeaning · unitRequired · default
curvereadonly CommodityCurvePoint[]

The forward curve — ≥ 2 points, strictly ascending delivery times.

unitless by name
RequiredNo @default declared
flatToleranceFractionnumber

REQUIRED explicit tolerance (e.g. 0.001): a pairwise price change with |forwardPrice[i+1] / forwardPrice[i] − 1| ≤ flatToleranceFraction counts as flat. No default — how much wiggle is "flat" is a judgment the caller must state.

decimal fraction / multiple
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

iface

TermStructureStateResult

#

Result of termStructureState.

Signature
import type { TermStructureStateResult } from '@insiderfinance/totalfinance/commodities';

/** Result of {@link termStructureState}. */
export interface TermStructureStateResult {
    state: TermStructureState;
    assumptions: {
        flatToleranceFraction: number;
        /** The fixed classification prose: pairwise slopes against the tolerance, mixes disclosed. */
        definition: string;
    };
    diagnostics: {
        warnings: string[];
        risingSegmentCount: number;
        fallingSegmentCount: number;
        flatSegmentCount: number;
    };
}
Fields, parameters and returned members (9)
Name · typeMeaning · unitRequired · default
assumptions{ definition: string; flatToleranceFraction: number; }—unitless by nameRequiredNo @default declared
assumptions.definitionstring

The fixed classification prose: pairwise slopes against the tolerance, mixes disclosed.

unitless by name
RequiredNo @default declared
assumptions.flatToleranceFractionnumber—decimal fraction / multipleRequiredNo @default declared
diagnostics{ fallingSegmentCount: number; flatSegmentCount: number; risingSegmentCount: number; warnings: string[]; }—unitless by nameRequiredNo @default declared
diagnostics.fallingSegmentCountnumber—count (integer)RequiredNo @default declared
diagnostics.flatSegmentCountnumber—count (integer)RequiredNo @default declared
diagnostics.risingSegmentCountnumber—count (integer)RequiredNo @default declared
diagnostics.warningsstring[]—unitless by nameRequiredNo @default declared
stateTermStructureState—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

calendarSpread

#

The calendar spread between two deliveries: the price spread far − near, and the annualized continuous carry the pair implies. Near must genuinely be nearer — a reversed pair is refused rather than silently sign-flipped.

Signature
import { calendarSpread } from '@insiderfinance/totalfinance/commodities';

export declare function calendarSpread(input: CalendarSpreadInput): CalendarSpreadResult;
Fields, parameters and returned members (9)
Name · typeMeaning · unitRequired · default
(input)CalendarSpreadInput—unitless by nameRequiredNo @default declared
(input).farPointCommodityCurvePoint

The farther delivery.

unitless by name
RequiredNo @default declared
(input).nearPointCommodityCurvePoint

The nearer delivery — nearPoint.timeToDeliveryYears < farPoint.timeToDeliveryYears.

unitless by name
RequiredNo @default declared
return.annualizedSpreadRatenumber

The CONTINUOUS carry between the two deliveries: ln(farPoint.forwardPrice / nearPoint.forwardPrice) / (farTime − nearTime).

decimal rate (0.05 = 5%)
RequiredNo @default declared
return.assumptions{ annualizedSpreadRateConvention: string; }—unitless by nameRequiredNo @default declared
return.assumptions.annualizedSpreadRateConventionstring

The fixed convention prose: continuous carry between the two deliveries.

unitless by name
RequiredNo @default declared
return.diagnostics{ warnings: string[]; }—unitless by nameRequiredNo @default declared
return.diagnostics.warningsstring[]—unitless by nameRequiredNo @default declared
return.spreadnumber

farPoint.forwardPrice − nearPoint.forwardPrice (price units).

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

commodityBasis

#

The basis between spot and a quoted futures price. basis (a price difference) and basisFraction (a dimensionless ratio) are DIFFERENT quantities and both deserve names — the library's naming law already blesses exactly this pair.

Signature
import { commodityBasis } from '@insiderfinance/totalfinance/commodities';

export declare function commodityBasis(input: CommodityBasisInput): CommodityBasisResult;
Fields, parameters and returned members (9)
Name · typeMeaning · unitRequired · default
(input)CommodityBasisInput—unitless by nameRequiredNo @default declared
(input).futuresPricenumber

The quoted futures price, > 0.

currency amount (the field or record currency)
RequiredNo @default declared
(input).spotPricenumber

Spot price, > 0.

currency amount (the field or record currency)
RequiredNo @default declared
return.assumptions{ definition: string; }—unitless by nameRequiredNo @default declared
return.assumptions.definitionstring

The fixed basis definition prose: price difference and fraction, both named.

unitless by name
RequiredNo @default declared
return.basisnumber

spotPrice − futuresPrice — the basis in price units.

unitless by name
RequiredNo @default declared
return.basisFractionnumber

spotPrice / futuresPrice − 1 — the basis as a fraction of the futures price.

decimal fraction / multiple
RequiredNo @default declared
return.diagnostics{ warnings: string[]; }—unitless by nameRequiredNo @default declared
return.diagnostics.warningsstring[]—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

commodityCarry

#

The annualized TOTAL carry a spot/forward pair implies, by inverting the compounding growth factor. When all three components (financing, storage, convenience) are supplied, the result also reports impliedResidual = annualizedCarryRate − (f + s − c) and warns when the residual exceeds 1e-9 — a parity-priced forward has residual zero, and a nonzero residual is the parity law made visible, never silently absorbed into a component.

Signature
import { commodityCarry } from '@insiderfinance/totalfinance/commodities';

export declare function commodityCarry(input: CommodityCarryInput): CommodityCarryResult;
Fields, parameters and returned members (19)

Loading 19 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

commodityForwardPrice

#

THEORETICAL cost-of-carry forward price: spotPrice × G(netCarryRate, timeToDeliveryYears) where netCarryRate = annualFinancingRate + annualStorageCostRate − annualConvenienceYield and G is the compounding growth factor. For 'continuous' compounding that is exactly spotPrice × e^((f + s − c) × t).

A bare-number primitive (like valuation's freeCashFlowToFirm): what carry says the forward SHOULD be, not a quoted futures price and not a contract value.

Signature
import { commodityForwardPrice } from '@insiderfinance/totalfinance/commodities';

export declare function commodityForwardPrice(input: CommodityForwardPriceInput): number;
Fields, parameters and returned members (7)
Name · typeMeaning · unitRequired · default
(input)CommodityForwardPriceInput—unitless by nameRequiredNo @default declared
(input).annualConvenienceYieldnumber

Annual convenience yield, decimal — the benefit of holding the physical commodity.

decimal rate (0.05 = 5%)
RequiredNo @default declared
(input).annualFinancingRatenumber

Annual financing (interest) rate, decimal.

decimal rate (0.05 = 5%)
RequiredNo @default declared
(input).annualStorageCostRatenumber

Annual storage cost as a PROPORTIONAL rate of the commodity's value, decimal — not a dollar amount per unit (v1 models storage as a continuous proportional drag, like a negative yield).

decimal rate (0.05 = 5%)
RequiredNo @default declared
(input).compoundingInterestCompounding

REQUIRED compounding convention — a market instrument never defaults its convention.

unitless by name
RequiredNo @default declared
(input).spotPricenumber

Spot price of the commodity, > 0, in the quote currency per unit.

currency amount (the field or record currency)
RequiredNo @default declared
(input).timeToDeliveryYearsnumber

Time to delivery in years, ≥ 0 (zero prices the forward at spot exactly).

years (decimal)
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

commodityForwardValue

#

CURRENT VALUE of an existing forward contract: ±(currentForwardPrice − contractForwardPrice) × quantity × discountFactorToDelivery, positive for 'long' and negated for 'short'.

The three quantities this module keeps distinct meet here: contractForwardPrice is the price STRUCK on the contract, currentForwardPrice is today's forward PRICE (quoted or theoretical), and the result is the contract's VALUE — zero at inception when struck at the fair forward.

Signature
import { commodityForwardValue } from '@insiderfinance/totalfinance/commodities';

export declare function commodityForwardValue(input: CommodityForwardValueInput): CommodityForwardValueResult;
Fields, parameters and returned members (13)

Loading 13 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

convertCommodityQuantity

#

Convert a commodity quantity between units with an EXPLICIT caller-supplied factor: convertedQuantity = quantity × conversionFactor. Economics are preserved exactly when the caller scales prices by the reciprocal (price-per-unit × quantity is invariant). An identity conversion (fromUnit === toUnit) with a factor ≠ 1 is a contradiction and is refused.

Signature
import { convertCommodityQuantity } from '@insiderfinance/totalfinance/commodities';

export declare function convertCommodityQuantity(input: ConvertCommodityQuantityInput): ConvertCommodityQuantityResult;
Fields, parameters and returned members (13)

Loading 13 members…

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

curveSpreadAnalytics

#

Spread analytics across a whole curve: one CurveSpreadRow per adjacent pair plus the overall front-to-back row, every rate under the disclosed continuous convention. Linear in the pillar count.

Signature
import { curveSpreadAnalytics } from '@insiderfinance/totalfinance/commodities';

export declare function curveSpreadAnalytics(input: CurveSpreadAnalyticsInput): CurveSpreadAnalyticsResult;
Fields, parameters and returned members (8)
Name · typeMeaning · unitRequired · default
(input)CurveSpreadAnalyticsInput—unitless by nameRequiredNo @default declared
(input).curvereadonly CommodityCurvePoint[]

The forward curve — ≥ 2 points, strictly ascending delivery times.

unitless by name
RequiredNo @default declared
return.adjacentSpreadsCurveSpreadRow[]

One row per adjacent pair, in curve order.

unitless by name
RequiredNo @default declared
return.assumptions{ annualizedSpreadRateConvention: string; }—unitless by nameRequiredNo @default declared
return.assumptions.annualizedSpreadRateConventionstring

The fixed convention prose: continuous carry per row.

unitless by name
RequiredNo @default declared
return.diagnostics{ warnings: string[]; }—unitless by nameRequiredNo @default declared
return.diagnostics.warningsstring[]—unitless by nameRequiredNo @default declared
return.frontToBackCurveSpreadRow

The overall figures from the first delivery to the last.

unitless by name
RequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.

fn

futuresHedgeRatio

#

Futures contracts required to hedge an exposure: exposureQuantity × betaOrHedgeEffectiveness / futuresContractSize. The count is NOT rounded — whether to round up, down, or trade the fraction via a mini contract is an execution decision that belongs to the caller, and the assumptions say so.

Signature
import { futuresHedgeRatio } from '@insiderfinance/totalfinance/commodities';

export declare function futuresHedgeRatio(input: FuturesHedgeRatioInput): FuturesHedgeRatioResult;
Fields, parameters and returned members (11)
Name · typeMeaning · unitRequired · default
(input)FuturesHedgeRatioInput—unitless by nameRequiredNo @default declared
(input).betaOrHedgeEffectivenessnumber

The minimum-variance hedge ratio (a regression beta or hedge effectiveness), default 1 — a one-to-one hedge, echoed as such in the assumptions.

unitless by name
OptionalNo @default declared
(input).exposureQuantitynumber

The exposure being hedged, in commodity units (sign carries the direction).

unitless by name
RequiredNo @default declared
(input).futuresContractSizenumber

Units of the commodity per futures contract, > 0.

count (integer)
RequiredNo @default declared
return.assumptions{ betaOrHedgeEffectiveness: number; hedgeRatioBasis: 'one-to-one' | 'caller-supplied beta or hedge effectiveness'; rounding: string; }—unitless by nameRequiredNo @default declared
return.assumptions.betaOrHedgeEffectivenessnumber—unitless by nameRequiredNo @default declared
return.assumptions.hedgeRatioBasis'one-to-one' | 'caller-supplied beta or hedge effectiveness'—unitless by nameRequiredNo @default declared
return.assumptions.roundingstring

The fixed rounding prose: the count is real-valued; rounding is the caller's decision.

unitless by name
RequiredNo @default declared
return.contractsRequirednumber

exposureQuantity × betaOrHedgeEffectiveness / futuresContractSize — a REAL number, not rounded: rounding to whole contracts is the caller's execution decision, disclosed in the assumptions rather than taken silently.

unitless by name
RequiredNo @default declared
return.diagnostics{ warnings: string[]; }—unitless by nameRequiredNo @default declared
return.diagnostics.warningsstring[]—unitless by nameRequiredNo @default declared

Stability: stable-by-law (pre-1.0; not a 1.0 stability guarantee). Units come from declared names; “unitless by name” means the name alone does not establish a unit. See conventions and errors and warnings.