@insiderfinance/totalfinance/options/black-scholes

interface

BlackScholesEvaluateFacade

`blackScholes.evaluate` — a selected calculation with its `.explain` companion. An empty selection is refused at run time (`input.out_of_range`).

/**
 * `blackScholes.evaluate` — a selected calculation with its `.explain` companion. An empty
 * selection is refused at run time (`input.out_of_range`).
 */
export interface BlackScholesEvaluateFacade {
    <const O extends BlackScholesOutputSelection>(input: BlackScholesEvaluateInput<O>): BlackScholesEvaluation<O>;
    explain<const O extends BlackScholesOutputSelection>(input: BlackScholesEvaluateInput<O>): Computed<BlackScholesEvaluation<O>>;
}

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

BlackScholesEvaluateInput

Input for {@link blackScholes}.evaluate: the typed Black–Scholes input plus the outputs to compute. `outputs` is required, nonempty, dense and duplicate-free.

/**
 * Input for {@link blackScholes}.evaluate: the typed Black–Scholes input plus the outputs to compute.
 * `outputs` is required, nonempty, dense and duplicate-free.
 */
export interface BlackScholesEvaluateInput<O extends BlackScholesOutputSelection = BlackScholesOutputSelection> extends BlackScholesTypedInput {
    /** The outputs to compute, e.g. `['price', 'delta', 'gamma']`. Only these appear in the result. */
    outputs: O;
}

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

type

BlackScholesEvaluation

The result of a selected evaluation. The outputs the selection is certain to contain are required numbers; any other output it might contain is optional ({@link GuaranteedSelection}). So a literal `['price', 'gamma']` gives exactly those two required, while a dynamic selection (`BlackScholesOutput[]`), a conditional (`c ? ['gamma'] : ['delta']`) or a union-valued element gives optional properties: the type never claims a value exists that was not requested.

/**
 * The result of a selected evaluation. The outputs the selection is certain to contain are required
 * numbers; any other output it might contain is optional ({@link GuaranteedSelection}). So a
 * literal `['price', 'gamma']` gives exactly those two required, while a dynamic selection
 * (`BlackScholesOutput[]`), a conditional (`c ? ['gamma'] : ['delta']`) or a union-valued element
 * gives optional properties: the type never claims a value exists that was not requested.
 */
export type BlackScholesEvaluation<O extends BlackScholesOutputSelection> = {
    [K in GuaranteedSelection<O>]: number;
} & {
    [K in Exclude<O[number], GuaranteedSelection<O>>]?: number;
};

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

BlackScholesImpliedVolatilityKernelInput

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface BlackScholesImpliedVolatilityKernelInput extends BlackScholesPriceBoundsInput, BlackScholesImpliedVolatilityOptions {
    price: number;
}

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

BlackScholesImpliedVolatilityOptions

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface BlackScholesImpliedVolatilityOptions {
    /** Lower σ bracket (default `1e-7`). */
    lowerVolatilityBound?: number;
    /** Upper σ bracket before expansion (default `5`). */
    upperVolatilityBound?: number;
}

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

BlackScholesImpliedVolatilityResult

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface BlackScholesImpliedVolatilityResult {
    value: number;
    converged: boolean;
    iterations: number;
    error?: number;
    reason?: ImpliedVolatilityReason;
    /** Explanatory detail when a usable numeric pricing bracket cannot be established. */
    message?: string;
}

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

BlackScholesKernelInput

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface BlackScholesKernelInput extends BlackScholesPriceBoundsInput {
    volatility: number;
}

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

type

BlackScholesOutput

A Black–Scholes output a selective call can request. First-order Greeks use the library's display units (theta per calendar day, vega and rho per 1%); higher-order Greeks use the raw units documented on `blackScholesExtendedGreeks`.

/**
 * A Black–Scholes output a selective call can request. First-order Greeks use the library's display
 * units (theta per calendar day, vega and rho per 1%); higher-order Greeks use the raw units
 * documented on `blackScholesExtendedGreeks`.
 */
export type BlackScholesOutput = (typeof BLACK_SCHOLES_OUTPUTS)[number];

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

type

BlackScholesOutputSelection

A selection of outputs, as an array or (inferred from a literal) a tuple.

/** A selection of outputs, as an array or (inferred from a literal) a tuple. */
export type BlackScholesOutputSelection = readonly BlackScholesOutput[];

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

interface

BlackScholesPriceBoundsInput

Public declaration. Read the signature and parameter/member contracts below; no additional behavior is inferred.

export interface BlackScholesPriceBoundsInput {
    type: OptionType;
    spot: number;
    strike: number;
    timeToExpiryYears: number;
    riskFreeRate: number;
    dividendYield: number;
}

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

value

blackScholes

The Black–Scholes facade namespace. Flat object arguments in, plain values out; `.explain()` on each function returns the assumptions/diagnostics envelope.

export declare const blackScholes: { call: Facade<BlackScholesInput, number>; put: Facade<BlackScholesInput, number>; price: Facade<BlackScholesTypedInput, number>; delta: Facade<BlackScholesTypedInput, number>; gamma: Facade<BlackScholesTypedInput, number>; theta: Facade<BlackScholesTypedInput, number>; vega: Facade<BlackScholesTypedInput, number>; rho: Facade<BlackScholesTypedInput, number>; greeks: Facade<BlackScholesTypedInput, Greeks>; extendedGreeks: Facade<BlackScholesTypedInput, ExtendedGreeks>; evaluate: BlackScholesEvaluateFacade; impliedVolatility: Facade<BlackScholesImpliedVolatilityInput, number, Record<never, never>, number | null>; };

import { blackScholes } from '@insiderfinance/totalfinance/options';

blackScholes.price({ spot: 100, strike: 105, timeToExpiryYears: 30 / 365, riskFreeRate: 0.045, volatility: 0.22, type: 'call' });
// → 0.898…  (plain number)

const { value, assumptions, diagnostics } = blackScholes.greeks.explain({
  spot: 100, strike: 105, timeToExpiryYears: 30 / 365, riskFreeRate: 0.045, volatility: 0.22, type: 'call',
});
// value.delta, value.theta (per day), … — with every assumption disclosed

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

blackScholesExtendedGreeks

Higher-order Greeks under BSM (spec §9.4), analytic and exact. First-order fields (`delta`…`rho`) carry the same default units as {@link blackScholesGreeks}; the second/third-order fields are in raw units: - `vanna` = ∂Δ/∂σ = ∂²V/∂S∂σ (per 1.00 σ, per $), - `vomma` = ∂(vega)/∂σ = ∂²V/∂σ² (per 1.00 σ²; vega here is per 1.00 σ), - `charm` = ∂Δ/∂T (delta drift per added year of time-to-expiry), - `speed` = ∂Γ/∂S = ∂³V/∂S³, - `color` = ∂Γ/∂T (gamma drift per added year of time-to-expiry), - `phi` = ε = ∂V/∂q (dividend rho, per 1% dividend yield — scaled like rho), - `zomma` = ∂Γ/∂σ = ∂³V/∂S²∂σ, - `veta` = ∂vega/∂T (per year of time-to-expiry; the ∂/∂T sibling of vega), - `vera` = ∂rho/∂σ = ∂²V/∂r∂σ, - `ultima`= ∂vomma/∂σ = ∂³V/∂σ³, - `lambda`= Δ·S/V (elasticity / effective leverage, dimensionless). All are validated against finite differences of the first-order Greeks / the price.

export declare function blackScholesExtendedGreeks(input: BlackScholesKernelInput): ExtendedGreeks;

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

blackScholesGreeks

First-order Greeks in TotalFinance default units (theta/day, vega/1%, rho/1%).

export declare function blackScholesGreeks(input: BlackScholesKernelInput): Greeks;

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

blackScholesImpliedVolatility

Solve implied volatility from a price using Brent with no-arbitrage bound checks. Returns `converged: false` with a machine-readable `reason` on failure — never a fabricated value (design law #4). Three ways there is no answer, reported apart: the price violates the intrinsic floor (`below_intrinsic`), it sits at or above the upper no-arbitrage bound, which is a SUPREMUM attained only as σ→∞ (`above_max_bound`), or it is below the model price at the lowest σ in the bracket (`price_below_resolvable`).

export declare function blackScholesImpliedVolatility(input: BlackScholesImpliedVolatilityKernelInput): BlackScholesImpliedVolatilityResult;

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

blackScholesPrice

Black–Scholes–Merton price for a European call/put with continuous dividend yield `q`. This is the seed defect Phase 3B was opened on. It validated the object and the `type` enum, then destructured six numeric fields and checked none of them: omitting `volatility` made `sigma` `undefined`, `d1` `NaN`, and the returned PRICE `NaN` — handed back as a success, through a declaration that said the field was required. A pricing function that answers `NaN` is worse than one that throws, because every layer above it treats the answer as a number.

export declare function blackScholesPrice(input: BlackScholesKernelInput): number;

stable-by-law (pre-1.0; not a 1.0 stability guarantee)

function

blackScholesPriceBounds

No-arbitrage price bounds for a vanilla under BSM (forward intrinsic ≤ price ≤ discounted spot/strike).

export declare function blackScholesPriceBounds(input: BlackScholesPriceBoundsInput): { lower: number; upper: number; };

stable-by-law (pre-1.0; not a 1.0 stability guarantee)