engagement-rate

Comprehensive engagement rate calculation library for social media posts, reels, and videos with TypeScript support

Installation

npm install engagement-rate

Usage

TypeScript

import {
  calculateStaticPostEngagement,
  calculateReelEngagement,
  calculateVideoEngagement,
  calculateProfileEngagementForStaticPosts,
  calculateMedianEngagementForStaticPosts,
  type StaticPost,
  type VideoContent,
  EngagementValidationError,
  ErrorMessages,
} from "engagement-rate";

// Calculate engagement for a single static post
const postEngagement = calculateStaticPostEngagement(100, 50, 1000);
console.log(`Post engagement: ${postEngagement}%`); // 15%

// Calculate engagement for a single reel
const reelEngagement = calculateReelEngagement(200, 30, 5000);
console.log(`Reel engagement: ${reelEngagement}%`); // 4.6%

// Calculate profile engagement for multiple static posts
const posts: StaticPost[] = [
  { likes: 100, comments: 20, followers: 1000 },
  { likes: 150, comments: 30, followers: 1000 },
  { likes: 80, comments: 15, followers: 1000 },
];
const profileEngagement = calculateProfileEngagementForStaticPosts(posts, 1000);
console.log(`Profile engagement: ${profileEngagement}%`);

// Calculate median engagement for static posts
const medianEngagement = calculateMedianEngagementForStaticPosts(posts);
console.log(`Median engagement: ${medianEngagement}%`);

JavaScript (with editor autocomplete)

// @ts-check
const {
  calculateStaticPostEngagement,
  calculateReelEngagement,
  EngagementValidationError,
} = require("engagement-rate");

try {
  const engagement = calculateStaticPostEngagement(100, 25, 1000);
  console.log(`Engagement rate: ${engagement}%`); // 12.5%
} catch (error) {
  if (error instanceof EngagementValidationError) {
    console.error("Validation error:", error.message);
  }
}

CDN Usage (Browser)

<script src="https://unpkg.com/engagement-rate/dist/index.global.js"></script>
<script>
  const { calculateStaticPostEngagement, calculateReelEngagement } = window.EngagementRate;
  
  const postEngagement = calculateStaticPostEngagement(50, 10, 500);
  console.log(`Post engagement: ${postEngagement}%`); // 12%
</script>

API Reference

Single Post/Content Calculations

calculateStaticPostEngagement(likes, comments, followers)

Calculate engagement rate for a single static post.

Parameters:

• likes: number - Number of likes (must be >= 0)
• comments: number - Number of comments (must be >= 0)
• followers: number - Number of followers (must be > 0)

Returns: number - Engagement rate as a percentage

Formula: ((likes + comments) / followers) * 100

calculateReelEngagement(likes, comments, views)

Calculate engagement rate for a single reel.

Parameters:

• likes: number - Number of likes (must be >= 0)
• comments: number - Number of comments (must be >= 0)
• views: number - Number of views (must be > 0)

Returns: number - Engagement rate as a percentage

Formula: ((likes + comments) / views) * 100

calculateVideoEngagement(likes, comments, views)

Calculate engagement rate for a single video (same as reel calculation).

Profile-Level Calculations

calculateProfileEngagementForStaticPosts(posts, followers)

Calculate average engagement rate across multiple static posts.

Parameters:

• posts: StaticPost[] - Array of post data
• followers: number - Total followers count

Returns: number - Average engagement rate as a percentage

calculateMedianEngagementForStaticPosts(posts)

Calculate median engagement rate for static posts.

Parameters:

• posts: StaticPost[] - Array of post data (each post must include followers)

Returns: number - Median engagement rate as a percentage

calculateProfileEngagementForReels(reels)

Calculate overall engagement rate for multiple reels.

Parameters:

• reels: VideoContent[] - Array of reel data

Returns: number - Overall engagement rate as a percentage

calculateMedianEngagementForReels(reels)

Calculate median engagement rate for reels.

calculateProfileEngagementForVideos(videos)

Calculate overall engagement rate for multiple videos.

calculateMedianEngagementForVideos(videos)

Calculate median engagement rate for videos.

Combined Calculations

calculateCombinedMeanEngagement(content)

Calculate combined mean engagement for video content.

calculateCombinedStaticPostMeanEngagement(posts)

Calculate combined mean engagement for static posts.

Type Definitions

StaticPost

interface StaticPost {
  likes: number;
  comments: number;
  followers: number;
}

VideoContent

interface VideoContent {
  likes: number;
  comments: number;
  views: number;
}

Validation & Error Handling

The library includes comprehensive validation with custom error types:

EngagementValidationError

Custom error class for validation failures.

ErrorMessages

Available error messages:

• NEGATIVE_LIKES: "Likes cannot be negative"
• NEGATIVE_COMMENTS: "Comments cannot be negative"
• MIN_FOLLOWERS: "Followers must be greater than 0"
• MIN_VIEWS: "Views must be greater than 0"
• MIN_POSTS: "At least one post is required"
• MIN_VIDEOS: "At least one item is required"

Validation Functions

• isValidStaticPost(post) - Validates a StaticPost object
• isValidVideoContent(content) - Validates a VideoContent object
• isValidStaticPostsArray(posts) - Validates an array of StaticPost objects
• isValidVideoContentArray(content) - Validates an array of VideoContent objects

Examples

Error Handling

try {
  const engagement = calculateStaticPostEngagement(-10, 5, 1000);
} catch (error) {
  if (error instanceof EngagementValidationError) {
    console.error(error.message); // "Likes cannot be negative"
  }
}

Batch Processing

const posts: StaticPost[] = [
  { likes: 120, comments: 25, followers: 1000 },
  { likes: 95, comments: 18, followers: 1000 },
  { likes: 200, comments: 40, followers: 1000 },
];

// Calculate various metrics
const avgEngagement = calculateProfileEngagementForStaticPosts(posts, 1000);
const medianEngagement = calculateMedianEngagementForStaticPosts(posts);
const combinedEngagement = calculateCombinedStaticPostMeanEngagement(posts);

console.log(`Average: ${avgEngagement}%`);
console.log(`Median: ${medianEngagement}%`);
console.log(`Combined: ${combinedEngagement}%`);

Features

• 🎯 Type-safe: Full TypeScript support with exact types
• 🌐 Universal: Works in browser and Node.js environments
• 📦 Tree-shakeable: Import only what you need
• 🛡️ Defensive: Comprehensive input validation and error handling
• 📊 Flexible: Support for posts, reels, videos, and profile-level calculations
• 🚀 Zero dependencies: Lightweight and fast
• 📈 Multiple metrics: Average, median, and combined engagement calculations

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Clean build artifacts
npm run clean

License

MIT