Time-Based DOM Management with Timezone Support – TimestampWitchJs

TimestampWitchJs is a JavaScript library designed to deal with DOM elements that need to disappear at a specific time.

More Features

• Multiple timezone handling (UTC, local, or specific timezones)
• JavaScript and HTTP callbacks on element removal
• Pre-scheduling of removals for efficiency
• Intelligent rescanning with MutationObserver
• Lazy loading integration with IntersectionObserver
• Worker thread processing for performance
• Local storage caching for persistence between sessions
• Debug mode for development
• Batched DOM updates for smoother UI
• Throttled removals to prevent UI jank

See It In Action

Use Cases

• Expiring Promotions/Banners: Showing a sale banner that needs to vanish exactly at midnight in a specific timezone, not just the user’s local time. TimestampWitchJs handles the timezone math.
• Live Event Feeds: Displaying “Live Now” badges or countdown timers on event cards that automatically clean themselves up when the event time passes. The callback feature is great here for updating counters or related UI elements.
• Temporary Notifications: Showing alerts or messages that should only persist for a set duration (e.g., “Settings saved successfully,” disappearing after 5 seconds) using the scheduleRemoval method.
• Time-Sensitive Content Rotators: Cycling through content where items have specific display windows.

How to use it:

1. Install and import TimestampWitchJs.

# NPM
$ npm install timestamp-witch-js

// ES Module
import TimestampWitchJs from 'timestamp-witch-js';

<!-- Browser -->
<script src="/dist/timestamp-witch.min.js"></script>

2. Initialize with default settings:

const witch = new TimestampWitchJs({
  // options here
}).init();

3. Now you have two main ways to add expiry to elements:

<!-- HTML Data Attributes (Recommended for static content): -->
<div class="promo-banner"
  data-tc-expiry="2025-12-25 00:00:00"
  data-tc-timezone="Europe/London"
  data-tc-callbackFunction="handlePromoRemoval"
  data-tc-callbackUrl="/api/promo/expired?id=123"
  data-tc-callbackMethod="POST">
  Christmas Promo! Ends Midnight London Time.
</div>

// JavaScript Method (For dynamic elements or more control):
witch.addExpiryToElement(
   element,
   '2025-05-01 17:00:00', // Timestamp string
   {
     timezone: 'America/Los_Angeles',
     callbacks: {
       function: 'updateOfferCount', // Name of a global function
       url: '/api/offer/expired',
       method: 'POST',
       format: 'json' // Send data as JSON
     }
   }
 );

4. For elements that just need to disappear after a fixed duration (not a specific timestamp):

const notification = document.querySelector('.temp-alert');
witch.scheduleRemoval(notification, 10);

5. All possible configuration options:

const witch = new TimestampWitchJs({
  attributePrefix: 'data-tc-',       // Prefix for all data attributes
  expiryAttribute: 'expiry',         // Attribute containing the timestamp (will be prefixed)
  callbackFunctionAttr: 'callbackFunction', // Name of callback function (will be prefixed)
  callbackUrlAttr: 'callbackUrl',    // URL for callback (will be prefixed)
  callbackMethodAttr: 'callbackMethod', // HTTP method for callback (will be prefixed)
  callbackFormatAttr: 'callbackFormat', // Format for callback (will be prefixed)
  versionAttr: 'version',            // Version attribute for future compatibility
  timestampFormat: 'auto',           // Timestamp format: 'auto', 'iso', or 'custom'
  customTimestampRegex: /(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2})(?: UTC)?/, // Regex for custom timestamp format
  customTimestampParse: null,        // Custom parsing function for timestamps
  timezone: 'UTC',                   // Default timezone: 'UTC', 'local', or specific timezone like 'America/New_York'
  timezoneAttribute: 'timezone',     // Attribute for per-element timezone (will be prefixed)
  checkInterval: 60000,              // Check every minute by default
  removeExpired: true,               // Whether to remove expired items automatically
  onRemove: null,                    // Global callback when an item is removed
  fadeOut: false,                    // Whether to fade out elements before removing
  fadeOutDuration: 500,              // Duration of fade out in ms
  prescheduleThreshold: 3600000,     // Pre-schedule removals for elements expiring within 1 hour
  useWorker: true,                   // Use Web Worker for background processing
  lazyLoading: true,                 // Only track elements in viewport
  useLocalStorage: true,             // Use localStorage to persist expiry info
  intelligentRescanning: true,       // Use MutationObserver to detect new elements
  debugMode: false,                  // Show visual indicators for expiring elements
  throttleRemovalsTo: 5,             // Max elements to remove per second
  batchDomUpdates: true,             // Use requestAnimationFrame for smoother updates
}).init();