@ad-execute-manager/count-recorder

A flexible count recorder utility for JavaScript applications with daily tracking, expiration support, and user-specific counting.

Installation

npm install @ad-execute-manager/count-recorder

Features

• Daily Count Tracking: Track counts on a daily basis with automatic reset
• Expiration Support: Set expiration times for count data, including 'today' option
• User-specific Counting: Track counts per user with automatic userId integration
• Storage Integration: Uses @ad-execute-manager/storage for persistent storage
• Total Count Management: Set and manage total count limits
• Remaining Count Calculation: Automatically calculate remaining counts
• TypeScript Support: Includes TypeScript type definitions
• Error Handling: Built-in error handling for required parameters

Usage

Basic Usage

import { CountRecorder } from '@ad-execute-manager/count-recorder';

// Create a count recorder instance
const dailyTaskRecorder = CountRecorder.new({
  local_sign: 'daily_task_recorder',
  total: 5, // Maximum 5 times per day
  expire: 'today', // Reset daily
  userId: 'user123' // User-specific counting
});

// Check remaining counts
const remaining = dailyTaskRecorder.remain();
console.log('Remaining tasks:', remaining);

if (remaining > 0) {
  // Perform the task
  console.log('Performing task...');
  
  // Update the count
  dailyTaskRecorder.updateToday();
  
  console.log('Task performed, count updated');
} else {
  console.log('Daily limit reached');
}

Advanced Usage

import { CountRecorder } from '@ad-execute-manager/count-recorder';

// Create multiple recorders for different purposes

// Daily ad impression recorder
const adRecorder = CountRecorder.new({
  local_sign: 'ad_impression_recorder',
  total: 10, // Maximum 10 ads per day
  expire: 'today',
  userId: 'user123'
});

// Weekly feature usage recorder
const featureRecorder = CountRecorder.new({
  local_sign: 'feature_usage_recorder',
  total: 20, // Maximum 20 uses per week
  expire: 7 * 24 * 60 * 60 * 1000, // 7 days expiration
  userId: 'user123'
});

// Check and use ad impressions
function showAd() {
  const remaining = adRecorder.remain();
  
  if (remaining > 0) {
    console.log('Showing ad...');
    adRecorder.updateToday();
    console.log('Ad shown, remaining:', adRecorder.remain());
    return true;
  } else {
    console.log('Ad limit reached for today');
    return false;
  }
}

// Check and use feature
function usePremiumFeature() {
  const remaining = featureRecorder.remain();
  
  if (remaining > 0) {
    console.log('Using premium feature...');
    featureRecorder.updateToday();
    console.log('Feature used, remaining:', featureRecorder.remain());
    return true;
  } else {
    console.log('Feature usage limit reached');
    return false;
  }
}

// Usage examples
// showAd();
// usePremiumFeature();

API

Constructor

new CountRecorder(args)

• args (Object): Configuration arguments
  • local_sign (String): Local storage identifier (required)
  • total (Number): Total count limit, defaults to 0
  • expire (Number|'today'): Expiration time in milliseconds or 'today' for day-bound, defaults to 'today'
  • userId (String|Number): User ID for user-specific counting

Methods

• remain(): Get remaining count

  • returns (Number): Remaining count

• updateToday(): Update today's count

Static Methods

• CountRecorder.new(args): Create a new CountRecorder instance
  • args (Object): Same as constructor arguments
  • returns (CountRecorder): New CountRecorder instance

Examples

Example 1: Daily Login Tracker

import { CountRecorder } from '@ad-execute-manager/count-recorder';

// Create login recorder
const loginRecorder = CountRecorder.new({
  local_sign: 'daily_login_recorder',
  total: 1, // Only one login count per day
  expire: 'today',
  userId: 'user123'
});

// Check if user has already logged in today
function checkDailyLogin() {
  const remaining = loginRecorder.remain();
  
  if (remaining > 0) {
    console.log('First login today');
    // Give daily login bonus
    giveDailyBonus();
    // Update login count
    loginRecorder.updateToday();
  } else {
    console.log('Already logged in today');
  }
}

// Give daily bonus
function giveDailyBonus() {
  console.log('Giving daily login bonus...');
  // Bonus logic here
}

// Usage
// checkDailyLogin();

Example 2: Ad Impression Limiter

import { CountRecorder } from '@ad-execute-manager/count-recorder';

// Create ad impression recorder
const adRecorder = CountRecorder.new({
  local_sign: 'ad_impression_recorder',
  total: 8, // Maximum 8 ads per day
  expire: 'today',
  userId: 'user123'
});

// Check if ad can be shown
function canShowAd() {
  const remaining = adRecorder.remain();
  return remaining > 0;
}

// Show ad and update count
function showAd() {
  if (canShowAd()) {
    console.log('Showing ad...');
    // Ad showing logic here
    adRecorder.updateToday();
    console.log('Ad shown, remaining impressions:', adRecorder.remain());
    return true;
  } else {
    console.log('Ad limit reached for today');
    return false;
  }
}

// Check remaining ad impressions
function checkAdLimit() {
  const remaining = adRecorder.remain();
  console.log(`Remaining ad impressions: ${remaining}/8`);
  return remaining;
}

// Usage examples
// checkAdLimit();
// showAd();

Example 3: Feature Usage Tracker

import { CountRecorder } from '@ad-execute-manager/count-recorder';

// Create feature usage recorder
const featureRecorder = CountRecorder.new({
  local_sign: 'premium_feature_recorder',
  total: 15, // Maximum 15 uses per day
  expire: 'today',
  userId: 'user123'
});

// Use premium feature
function usePremiumFeature(featureName) {
  const remaining = featureRecorder.remain();
  
  if (remaining > 0) {
    console.log(`Using premium feature: ${featureName}`);
    // Feature usage logic here
    featureRecorder.updateToday();
    console.log(`Feature used, remaining uses: ${featureRecorder.remain()}/15`);
    return true;
  } else {
    console.log('Premium feature usage limit reached for today');
    return false;
  }
}

// Check feature usage status
function checkFeatureUsage() {
  const remaining = featureRecorder.remain();
  const used = 15 - remaining;
  console.log(`Premium feature usage: ${used}/15 today`);
  return { used, remaining, total: 15 };
}

// Usage examples
// checkFeatureUsage();
// usePremiumFeature('AI Summarizer');

Dependencies

• @ad-execute-manager/storage: For persistent storage of count data

License

MIT