Primitives.org.ai

KPIs

Track key performance indicators

KPIs

The kpis() function creates a list of key performance indicators for tracking business health.

Basic Usage

import { kpis, kpi } from 'business-as-code'

// Create multiple KPIs
const kpiList = kpis([
  {
    name: 'Monthly Recurring Revenue',
    description: 'Total predictable revenue per month',
    category: 'financial',
    unit: 'USD',
    target: 100000,
    current: 85000,
    frequency: 'monthly',
    dataSource: 'Billing System',
    formula: 'SUM(active_subscriptions.price)',
  },
  {
    name: 'Customer Churn Rate',
    category: 'customer',
    unit: 'percent',
    target: 5,
    current: 3.2,
    frequency: 'monthly',
  },
])

// Create a single KPI
const nps = kpi({
  name: 'Net Promoter Score',
  category: 'customer',
  unit: 'score',
  target: 50,
  current: 48,
})

KPI Categories

CategoryDescription
financialRevenue, costs, margins
customerSatisfaction, retention, churn
operationsEfficiency, throughput, quality
peopleEmployee metrics, productivity
growthUser growth, market expansion

Measurement Frequency

FrequencyDescription
dailyMeasured every day
weeklyMeasured every week
monthlyMeasured every month
quarterlyMeasured every quarter
yearlyMeasured annually

Helper Functions

Achievement Calculation

import { calculateAchievement, kpiMeetsTarget, calculateVariance } from 'business-as-code'

// Calculate achievement percentage
const achievement = calculateAchievement(kpiList[0])
// 85 (85000 / 100000 * 100)

// Check if KPI meets target
const onTarget = kpiMeetsTarget(kpiList[1])
// true (3.2 <= 5 for churn - lower is better)

// Calculate variance from target
const variance = calculateVariance(kpiList[0])
// -15000 (85000 - 100000)

const variancePct = calculateVariancePercentage(kpiList[0])
// -15 (-15%)

Filtering and Grouping

import {
  getKPIsByCategory,
  getKPIsByFrequency,
  getKPIsOnTarget,
  getKPIsOffTarget,
  groupByCategory,
} from 'business-as-code'

// Filter by category
const financial = getKPIsByCategory(kpiList, 'financial')
const customer = getKPIsByCategory(kpiList, 'customer')

// Filter by frequency
const monthly = getKPIsByFrequency(kpiList, 'monthly')

// Get KPIs on/off target
const onTarget = getKPIsOnTarget(kpiList)
const offTarget = getKPIsOffTarget(kpiList)

// Group by category
const grouped = groupByCategory(kpiList)
// { financial: [...], customer: [...] }

Health Score

Calculate overall KPI health:

import { calculateHealthScore } from 'business-as-code'

const healthScore = calculateHealthScore(kpiList)
// 0-100 score based on target achievement

Updating Values

import { updateCurrent, updateTarget } from 'business-as-code'

// Update current value
const updated = updateCurrent(kpiList[0], 90000)

// Update target
const newTarget = updateTarget(kpiList[0], 120000)

Formatting

import { formatValue } from 'business-as-code'

const formatted = formatValue(kpiList[0])
// "$85,000" or "85000 USD"

Comparison

import { comparePerformance } from 'business-as-code'

const comparison = comparePerformance(currentKPIs, previousKPIs)
// { improved: [...], declined: [...], unchanged: [...] }

Validation

import { validateKPIs } from 'business-as-code'

const errors = validateKPIs(kpiList)
if (errors.length > 0) {
  console.error('Invalid KPIs:', errors)
}

Common KPIs by Category

Financial

  • Monthly Recurring Revenue (MRR)
  • Annual Recurring Revenue (ARR)
  • Gross Margin
  • Customer Acquisition Cost (CAC)
  • Customer Lifetime Value (LTV)
  • Burn Rate
  • Runway

Customer

  • Net Promoter Score (NPS)
  • Customer Satisfaction Score (CSAT)
  • Customer Effort Score (CES)
  • Churn Rate
  • Retention Rate

Operations

  • Uptime
  • Response Time
  • Error Rate
  • Throughput
  • Cycle Time

Growth

  • User Growth Rate
  • Revenue Growth Rate
  • Market Share
  • Active Users

Type Definition

interface KPIDefinition {
  name: string
  description?: string
  category?: 'financial' | 'customer' | 'operations' | 'people' | 'growth'
  unit?: string
  target?: number
  current?: number
  frequency?: TimePeriod
  dataSource?: string
  formula?: string
  metadata?: Record<string, unknown>
}
Was this page helpful?

On this page