business-as-code 2.0.2 → 2.1.3

package/src/index.test.js

@@ -0,0 +1,274 @@
+/**
+ * Tests for business-as-code package
+ */
+import { describe, it, expect } from 'vitest';
+import { Business, Vision, Goals, Product, Service, Process, Workflow, kpis, okrs, financials, $, calculateGrossMargin, calculateOverallProgress, updateProgress, calculateOKRProgress, updateKeyResult, } from './index.js';
+describe('Business', () => {
+    it('should create a business entity', () => {
+        const business = Business({
+            name: 'Test Corp',
+            mission: 'Test mission',
+            values: ['Value 1', 'Value 2'],
+        });
+        expect(business.name).toBe('Test Corp');
+        expect(business.mission).toBe('Test mission');
+        expect(business.values).toEqual(['Value 1', 'Value 2']);
+    });
+    it('should throw error if name is missing', () => {
+        expect(() => Business({ name: '' })).toThrow('Business name is required');
+    });
+});
+describe('Vision', () => {
+    it('should create a vision statement', () => {
+        const vision = Vision({
+            statement: 'To be the best',
+            timeframe: '5 years',
+            successIndicators: ['Indicator 1', 'Indicator 2'],
+        });
+        expect(vision.statement).toBe('To be the best');
+        expect(vision.timeframe).toBe('5 years');
+        expect(vision.successIndicators).toHaveLength(2);
+    });
+    it('should throw error if statement is missing', () => {
+        expect(() => Vision({ statement: '' })).toThrow('Vision statement is required');
+    });
+});
+describe('Goals', () => {
+    it('should create multiple goals', () => {
+        const goals = Goals([
+            {
+                name: 'Goal 1',
+                category: 'strategic',
+                status: 'in-progress',
+                progress: 50,
+            },
+            {
+                name: 'Goal 2',
+                category: 'operational',
+                status: 'not-started',
+                progress: 0,
+            },
+        ]);
+        expect(goals).toHaveLength(2);
+        expect(goals[0].name).toBe('Goal 1');
+        expect(goals[1].name).toBe('Goal 2');
+    });
+    it('should calculate overall progress', () => {
+        const goals = Goals([
+            { name: 'Goal 1', progress: 50 },
+            { name: 'Goal 2', progress: 100 },
+        ]);
+        const progress = calculateOverallProgress(goals);
+        expect(progress).toBe(75);
+    });
+    it('should update goal progress', () => {
+        const goal = { name: 'Test', progress: 0, status: 'not-started' };
+        const updated = updateProgress(goal, 100);
+        expect(updated.progress).toBe(100);
+        expect(updated.status).toBe('completed');
+    });
+});
+describe('Product', () => {
+    it('should create a product', () => {
+        const product = Product({
+            name: 'Test Product',
+            price: 100,
+            cogs: 30,
+        });
+        expect(product.name).toBe('Test Product');
+        expect(product.price).toBe(100);
+        expect(product.cogs).toBe(30);
+    });
+    it('should calculate gross margin', () => {
+        const product = Product({
+            name: 'Test Product',
+            price: 100,
+            cogs: 30,
+        });
+        const margin = calculateGrossMargin(product);
+        expect(margin).toBe(70);
+    });
+});
+describe('Service', () => {
+    it('should create a service', () => {
+        const service = Service({
+            name: 'Test Service',
+            pricingModel: 'hourly',
+            price: 100,
+        });
+        expect(service.name).toBe('Test Service');
+        expect(service.pricingModel).toBe('hourly');
+        expect(service.price).toBe(100);
+    });
+});
+describe('Process', () => {
+    it('should create a process', () => {
+        const process = Process({
+            name: 'Test Process',
+            steps: [
+                {
+                    order: 1,
+                    name: 'Step 1',
+                    automationLevel: 'automated',
+                },
+            ],
+        });
+        expect(process.name).toBe('Test Process');
+        expect(process.steps).toHaveLength(1);
+    });
+});
+describe('Workflow', () => {
+    it('should create a workflow', () => {
+        const workflow = Workflow({
+            name: 'Test Workflow',
+            trigger: { type: 'event', event: 'test.event' },
+            actions: [
+                {
+                    order: 1,
+                    type: 'send',
+                    description: 'Send notification',
+                },
+            ],
+        });
+        expect(workflow.name).toBe('Test Workflow');
+        expect(workflow.trigger.type).toBe('event');
+        expect(workflow.actions).toHaveLength(1);
+    });
+    it('should throw error if trigger is missing', () => {
+        expect(() => Workflow({
+            name: 'Test',
+            trigger: undefined,
+        })).toThrow('Workflow trigger is required');
+    });
+});
+describe('KPIs', () => {
+    it('should create KPIs', () => {
+        const kpiList = kpis([
+            {
+                name: 'Revenue',
+                target: 100000,
+                current: 85000,
+            },
+            {
+                name: 'Churn',
+                target: 5,
+                current: 3.2,
+            },
+        ]);
+        expect(kpiList).toHaveLength(2);
+        expect(kpiList[0].name).toBe('Revenue');
+    });
+});
+describe('OKRs', () => {
+    it('should create OKRs', () => {
+        const okrList = okrs([
+            {
+                objective: 'Test Objective',
+                keyResults: [
+                    {
+                        description: 'KR 1',
+                        metric: 'test_metric',
+                        startValue: 0,
+                        targetValue: 100,
+                        currentValue: 50,
+                    },
+                ],
+            },
+        ]);
+        expect(okrList).toHaveLength(1);
+        expect(okrList[0].objective).toBe('Test Objective');
+        expect(okrList[0].keyResults).toHaveLength(1);
+    });
+    it('should calculate OKR progress', () => {
+        const okr = {
+            objective: 'Test',
+            keyResults: [
+                {
+                    description: 'KR 1',
+                    metric: 'metric',
+                    startValue: 0,
+                    targetValue: 100,
+                    currentValue: 50,
+                },
+                {
+                    description: 'KR 2',
+                    metric: 'metric',
+                    startValue: 0,
+                    targetValue: 100,
+                    currentValue: 100,
+                },
+            ],
+        };
+        const progress = calculateOKRProgress(okr);
+        expect(progress).toBe(75);
+    });
+    it('should update key result', () => {
+        const okr = {
+            objective: 'Test',
+            keyResults: [
+                {
+                    description: 'KR 1',
+                    metric: 'metric',
+                    startValue: 0,
+                    targetValue: 100,
+                    currentValue: 50,
+                },
+            ],
+        };
+        const updated = updateKeyResult(okr, 'KR 1', 75);
+        expect(updated.keyResults[0].currentValue).toBe(75);
+        expect(updated.keyResults[0].progress).toBe(75);
+    });
+});
+describe('Financials', () => {
+    it('should calculate financial metrics', () => {
+        const metrics = financials({
+            revenue: 1000000,
+            cogs: 300000,
+            operatingExpenses: 500000,
+        });
+        expect(metrics.revenue).toBe(1000000);
+        expect(metrics.grossProfit).toBe(700000);
+        expect(metrics.grossMargin).toBe(70);
+        expect(metrics.operatingIncome).toBe(200000);
+        expect(metrics.operatingMargin).toBe(20);
+    });
+});
+describe('$ Helper', () => {
+    it('should format currency', () => {
+        const formatted = $.format(1234.56);
+        expect(formatted).toMatch(/1,234\.56/);
+    });
+    it('should calculate percentage', () => {
+        const percent = $.percent(25, 100);
+        expect(percent).toBe(25);
+    });
+    it('should calculate growth', () => {
+        const growth = $.growth(120, 100);
+        expect(growth).toBe(20);
+    });
+    it('should calculate margin', () => {
+        const margin = $.margin(100, 60);
+        expect(margin).toBe(40);
+    });
+    it('should calculate ROI', () => {
+        const roi = $.roi(150, 100);
+        expect(roi).toBe(50);
+    });
+    it('should calculate LTV', () => {
+        const ltv = $.ltv(100, 12, 2);
+        expect(ltv).toBe(2400);
+    });
+    it('should calculate CAC', () => {
+        const cac = $.cac(10000, 100);
+        expect(cac).toBe(100);
+    });
+    it('should calculate burn rate', () => {
+        const burnRate = $.burnRate(100000, 70000, 3);
+        expect(burnRate).toBe(10000);
+    });
+    it('should calculate runway', () => {
+        const runway = $.runway(100000, 10000);
+        expect(runway).toBe(10);
+    });
+});

package/src/kpis.js

@@ -0,0 +1,231 @@
+/**
+ * Key Performance Indicators (KPIs) management
+ */
+/**
+ * Define Key Performance Indicators for tracking business metrics
+ *
+ * @example
+ * ```ts
+ * const businessKPIs = 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',
+ *     description: 'Percentage of customers lost per month',
+ *     category: 'customer',
+ *     unit: 'percent',
+ *     target: 5,
+ *     current: 3.2,
+ *     frequency: 'monthly',
+ *     dataSource: 'CRM',
+ *     formula: '(churned_customers / total_customers) * 100',
+ *   },
+ *   {
+ *     name: 'Net Promoter Score',
+ *     description: 'Customer satisfaction and loyalty metric',
+ *     category: 'customer',
+ *     unit: 'score',
+ *     target: 50,
+ *     current: 48,
+ *     frequency: 'quarterly',
+ *     dataSource: 'Survey Platform',
+ *   },
+ * ])
+ * ```
+ */
+export function kpis(definitions) {
+    return definitions.map(kpi => validateAndNormalizeKPI(kpi));
+}
+/**
+ * Define a single KPI
+ */
+export function kpi(definition) {
+    return validateAndNormalizeKPI(definition);
+}
+/**
+ * Validate and normalize a KPI definition
+ */
+function validateAndNormalizeKPI(kpi) {
+    if (!kpi.name) {
+        throw new Error('KPI name is required');
+    }
+    return {
+        ...kpi,
+        category: kpi.category || 'operations',
+        frequency: kpi.frequency || 'monthly',
+        metadata: kpi.metadata || {},
+    };
+}
+/**
+ * Calculate KPI achievement percentage
+ */
+export function calculateAchievement(kpi) {
+    if (kpi.target === undefined || kpi.current === undefined)
+        return 0;
+    if (kpi.target === 0)
+        return 100;
+    return (kpi.current / kpi.target) * 100;
+}
+/**
+ * Check if KPI meets target
+ */
+export function meetsTarget(kpi) {
+    if (kpi.target === undefined || kpi.current === undefined)
+        return false;
+    // For metrics where lower is better (like churn rate)
+    const lowerIsBetter = ['churn', 'cost', 'time', 'error', 'downtime'].some(term => kpi.name.toLowerCase().includes(term));
+    if (lowerIsBetter) {
+        return kpi.current <= kpi.target;
+    }
+    return kpi.current >= kpi.target;
+}
+/**
+ * Update KPI current value
+ */
+export function updateCurrent(kpi, value) {
+    return {
+        ...kpi,
+        current: value,
+    };
+}
+/**
+ * Update KPI target
+ */
+export function updateTarget(kpi, target) {
+    return {
+        ...kpi,
+        target,
+    };
+}
+/**
+ * Get KPIs by category
+ */
+export function getKPIsByCategory(kpis, category) {
+    return kpis.filter(k => k.category === category);
+}
+/**
+ * Get KPIs by frequency
+ */
+export function getKPIsByFrequency(kpis, frequency) {
+    return kpis.filter(k => k.frequency === frequency);
+}
+/**
+ * Get KPIs that meet their targets
+ */
+export function getKPIsOnTarget(kpis) {
+    return kpis.filter(meetsTarget);
+}
+/**
+ * Get KPIs that don't meet their targets
+ */
+export function getKPIsOffTarget(kpis) {
+    return kpis.filter(kpi => !meetsTarget(kpi));
+}
+/**
+ * Calculate overall KPI health score (0-100)
+ */
+export function calculateHealthScore(kpis) {
+    if (kpis.length === 0)
+        return 0;
+    const onTarget = getKPIsOnTarget(kpis).length;
+    return (onTarget / kpis.length) * 100;
+}
+/**
+ * Group KPIs by category
+ */
+export function groupByCategory(kpis) {
+    const groups = new Map();
+    for (const kpi of kpis) {
+        const category = kpi.category || 'other';
+        const existing = groups.get(category) || [];
+        groups.set(category, [...existing, kpi]);
+    }
+    return groups;
+}
+/**
+ * Calculate variance from target
+ */
+export function calculateVariance(kpi) {
+    if (kpi.target === undefined || kpi.current === undefined)
+        return 0;
+    return kpi.current - kpi.target;
+}
+/**
+ * Calculate variance percentage from target
+ */
+export function calculateVariancePercentage(kpi) {
+    if (kpi.target === undefined || kpi.current === undefined)
+        return 0;
+    if (kpi.target === 0)
+        return 0;
+    return ((kpi.current - kpi.target) / kpi.target) * 100;
+}
+/**
+ * Format KPI value with unit
+ */
+export function formatValue(kpi, value) {
+    const val = value ?? kpi.current;
+    if (val === undefined)
+        return 'N/A';
+    const formatted = val.toLocaleString(undefined, {
+        minimumFractionDigits: 0,
+        maximumFractionDigits: 2,
+    });
+    if (!kpi.unit)
+        return formatted;
+    switch (kpi.unit.toLowerCase()) {
+        case 'usd':
+        case 'eur':
+        case 'gbp':
+            return `$${formatted}`;
+        case 'percent':
+        case '%':
+            return `${formatted}%`;
+        default:
+            return `${formatted} ${kpi.unit}`;
+    }
+}
+/**
+ * Compare KPI performance over time
+ */
+export function comparePerformance(current, previous) {
+    if (current.current === undefined || previous.current === undefined) {
+        return { change: 0, changePercent: 0, improved: false };
+    }
+    const change = current.current - previous.current;
+    const changePercent = previous.current !== 0 ? (change / previous.current) * 100 : 0;
+    // Determine if change is an improvement
+    const lowerIsBetter = ['churn', 'cost', 'time', 'error', 'downtime'].some(term => current.name.toLowerCase().includes(term));
+    const improved = lowerIsBetter ? change < 0 : change > 0;
+    return { change, changePercent, improved };
+}
+/**
+ * Validate KPI definitions
+ */
+export function validateKPIs(kpis) {
+    const errors = [];
+    for (const kpi of kpis) {
+        if (!kpi.name) {
+            errors.push('KPI name is required');
+        }
+        if (kpi.target !== undefined && kpi.target < 0) {
+            errors.push(`KPI ${kpi.name} target cannot be negative`);
+        }
+        if (kpi.current !== undefined && kpi.current < 0) {
+            errors.push(`KPI ${kpi.name} current value cannot be negative`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}