Usage Examples

The precise-age library provides a high-performance solution for calculating and displaying temporal progress with millisecond accuracy. Below are the primary implementation patterns for both static data retrieval and dynamic UI updates.

Static Age Calculation

The getPreciseAge function returns a floating-point number representing the exact number of years elapsed since a given timestamp. It accounts for leap years and varying month lengths by calculating the difference in milliseconds relative to the average Gregorian year.

import { getPreciseAge } from "precise-age";

// Accepts ISO 8601 strings, Date objects, or timestamps
const birthDate = "2001-08-15T10:30:00Z";
const age = getPreciseAge(birthDate);

// Display with high decimal precision
console.log(age.toFixed(8)); 
// Output example: 22.67123456

Live Browser Ticker

The startTicker utility is designed for real-time DOM updates. It utilizes requestAnimationFrame for smooth visual transitions, making it ideal for "life progress" bars or high-precision age counters in personal dashboards.

import { startTicker } from "precise-age";

/**
 * Initializes a live update on a DOM element.
 * Returns a cleanup function to prevent memory leaks.
 */
const stop = startTicker({
  element: document.getElementById("animatedValue"),
  mode: "yearProgress", // Tracks progress through the current year
  precision: 5          // Number of decimal places to display
});

// To halt the animation (e.g., on component unmount)
// stop();

Technical Logic and Precision

The library calculates age based on the Unix epoch offset. To maintain mathematical consistency over long periods, the calculation uses the International Standard for the tropical year, which is approximately 31,556,952,000 milliseconds (365.2425 days).

Configuration Options

| Parameter | Type | Description | | :--- | :--- | :--- | | element | HTMLElement | The target DOM node where the value will be injected. | | mode | age | yearProgress | age calculates total lifespan; yearProgress calculates % of the current year elapsed. | | precision | Number | The number of digits appearing after the decimal point (Default: 7). | | refreshRate | Number | Optional override for the update frequency in milliseconds. |

Advanced Implementation: Lifecycle Management

When using precise-age within modern frontend frameworks like React or Vue, it is critical to invoke the returned stop function to ensure that the requestAnimationFrame loop is terminated when the component is destroyed.

// Example React implementation
useEffect(() => {
  const stop = startTicker({
    element: ref.current,
    mode: "age",
    precision: 9
  });
  
  return () => stop();
}, []);

Performance Considerations

• Zero Dependencies: The library is lightweight and contains no external dependencies, ensuring a minimal footprint in your production bundle.
• Frame Optimization: The ticker mode is throttled to the browser's refresh rate, ensuring that calculations only occur when the user's screen is ready to paint a new frame, which preserves CPU and battery life.
• Immutable Math: Calculations are performed using pure functions, ensuring that the original input Date objects are never mutated.