subscriptions.mrr-arr

export function mrrArr(subscriptions: readonly RecurringCharge[], currency: string): MrrArr

export type SubscriptionStatus = "active" | "past-due" | "trialing" | "paused" | "canceled";

/** One subscription's recurring charge. */
export interface RecurringCharge {
  /** charged every intervalCount intervals, after recurring discounts, before tax */
  readonly amount: Money;
  readonly interval: BillingInterval;
  /** 1 or more: month with 6 is every six months */
  readonly intervalCount: number;
  /** only active and past-due count towards MRR */
  readonly status: SubscriptionStatus;
}

/** Recurring revenue, each figure rounded once from the exact total. */
export interface MrrArr {
  readonly mrr: Money;
  readonly arr: Money;
  /** subscriptions included: active and past-due */
  readonly counted: number;
  /** subscriptions left out: trialing, paused and canceled */
  readonly excluded: number;
}

import { mrrArr } from "#fune/subscriptions.mrr-arr@^1";

import { type Rational, addRational, multiplyRational, rational, rationalToInteger } from "./math_rational.ts";  ← from math.rational ^1.0.0 · built alongside by fune
import { assertSameCurrency, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { type BillingInterval } from "./subscriptions_next_billing_date.ts";  ← from subscriptions.next-billing-date ^1.0.0 · built alongside by fune
import { type MrrArr, type RecurringCharge } from "./subscriptions_mrr_arr_types.ts";

// 1.0.0 declared its own BillingInterval, which callers imported from this
// module; it is now subscriptions.next-billing-date's, re-exported so they
// still can.
export type { BillingInterval };

const PER_YEAR = new Map<BillingInterval, number>([["day", 365], ["week", 52], ["month", 12], ["quarter", 4], ["year", 1]]);

/**
 * MRR and ARR from active and past-due subscriptions. Every charge becomes an
 * exact annual amount first, and each total is rounded once at the end, so a
 * list of annual plans does not lose a penny per plan.
 */
export function mrrArr(subscriptions: readonly RecurringCharge[], currency: string): MrrArr {
  const zero = money(0, currency);
  let annual: Rational = rational(0, 1);
  let counted = 0;
  let excluded = 0;
  for (const s of subscriptions) {
    assertSameCurrency(zero, s.amount);
    if (s.amount.minor < 0) {
      throw new RangeError(`recurring amount must not be negative, received ${s.amount.minor}`);
    }
    if (!Number.isInteger(s.intervalCount) || s.intervalCount < 1) {
      throw new RangeError(`interval count must be 1 or more, received ${s.intervalCount}`);
    }
    const perYear = PER_YEAR.get(s.interval);
    if (perYear === undefined) {
      throw new RangeError(`unknown billing interval "${s.interval}": expected day, week, month, quarter or year`);
    }
    if (s.status === "active" || s.status === "past-due") {
      counted += 1;
      annual = addRational(annual, rational(s.amount.minor * perYear, s.intervalCount));
    } else if (s.status === "trialing" || s.status === "paused" || s.status === "canceled") {
      excluded += 1;
    } else {
      throw new RangeError(`unknown subscription status "${s.status}": expected active, past-due, trialing, paused or canceled`);
    }
  }
  return {
    mrr: money(rationalToInteger(multiplyRational(annual, rational(1, 12)), "half-up"), currency),
    arr: money(rationalToInteger(annual, "half-up"), currency),
    counted,
    excluded,
  };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add subscriptions.mrr-arr

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./subscriptions.mrr-arr-1.1.0-typescript.fune, or fetch it from a terminal with fune pull subscriptions.mrr-arr@1.1.0:typescript.

The whole function, every language, is one file too: subscriptions.mrr-arr-1.1.0.fune, 20,656 bytes, sha256 00720786d3b507dce9b22f2e8966b5ec051a2a993e0df8eef8ed7f42d5596938. It installs into a project of any language.

// fune: before subscriptions.mrr-arr

// fune: after subscriptions.mrr-arr

// fune: replace math.rational in subscriptions.mrr-arr
// fune: replace money.amount in subscriptions.mrr-arr
// fune: replace subscriptions.next-billing-date in subscriptions.mrr-arr

// fune: step subscriptions.mrr-arr after <n|label>

More from the author

divided by `intervalCount` (a 6-monthly plan earns its price twice a year). ARR is the sum of those, and MRR is the same sum divided by 12. Both are rounded once, half-up to the minor unit, from the exact fraction (math.rational). Rounding each subscription's monthly share first and adding up is the naive way and it drifts: three annual plans of 100.00 are 25.00 of MRR, but 8.33 + 8.33 + 8.33 is 24.99. Because each figure is rounded separately, MRR x 12 can differ from ARR by a few minor units; both are right.

Weeks and days are conventions, not calendar facts: 52 weeks and 365 days to the year. Businesses that use 52.14 weeks or 365.25 days get slightly different figures for weekly and daily plans; monthly, quarterly and annual plans are exact under any convention.

What counts. `active` and `past-due` subscriptions count: a failed payment still in dunning has not churned yet, so it stays in MRR until it is cancelled. (Metrics tools differ on this; filter past-due out before calling if yours does.) `trialing` subscriptions are left out (no revenue yet), as are `paused` and `canceled` ones. The amount should be the recurring price after recurring discounts and before tax; one-off charges, usage and setup fees are not recurring revenue and do not belong here.

Errors: an amount in a currency other than `currency`, a negative amount, and an interval count below 1.

Since 1.1.0 the `interval` of a `RecurringCharge` is the `BillingInterval` declared by `subscriptions.next-billing-date` (the same five values, `day`, `week`, `month`, `quarter` and `year`), rather than a copy declared here, so a subscription record typed for one capability is accepted by the other. `BillingInterval` can still be imported from this capability's module in TypeScript and Python, which re-export it. The answers are the same as 1.0.0's.

Files