Timer

/**
 * Creates a standalone timer instance
 * @param parameters - Optional timer configuration parameters
 * @returns Timer instance with playback controls
 */
function createTimer(parameters?: TimerParams): Timer;

import { createTimer } from "animejs/timer";

const timer = createTimer({
  duration: 5000,
  loop: 3,
  onUpdate: (t) => {
    console.log(`Progress: ${(t.progress * 100).toFixed(2)}%`);
  },
  onComplete: () => console.log("Timer finished!"),
});

timer.play();

/**
 * Timer class for time-based operations
 * Extends Clock for precise timing control
 */
class Timer extends Clock {
  // ===== Properties =====

  /** Unique timer identifier */
  id: string | number;

  /** Parent timeline if timer is added to one */
  parent: Timeline | null;

  /** Total duration including all iterations and delays (readonly) */
  duration: number;

  /** Whether timer direction is backwards */
  backwards: boolean;

  /** Whether timer is currently paused */
  paused: boolean;

  /** Whether timer has begun playback */
  began: boolean;

  /** Whether timer has completed all iterations */
  completed: boolean;

  /** Duration of a single iteration (readonly) */
  iterationDuration: number;

  /** Total number of iterations (readonly) */
  iterationCount: number;

  // ===== Getters/Setters =====

  /**
   * Current playback time in milliseconds
   * @settable Set to seek to specific time
   */
  currentTime: number;

  /**
   * Current time within the current iteration
   * @settable Set to seek within current iteration
   */
  iterationCurrentTime: number;

  /**
   * Overall progress from 0 to 1 across all iterations
   * @settable Set to seek to percentage of total duration
   */
  progress: number;

  /**
   * Progress within current iteration from 0 to 1
   * @settable Set to seek within iteration
   */
  iterationProgress: number;

  /**
   * Current iteration number (0-indexed)
   * @settable Set to jump to specific iteration
   */
  currentIteration: number;

  /**
   * Whether timer is playing in reverse direction
   * @settable Set to change direction
   */
  reversed: boolean;

  /**
   * Whether timer has been cancelled
   * @settable Set to cancel timer
   */
  cancelled: boolean;

  // ===== Callback Properties =====

  /**
   * Called when timer begins (first update after play)
   * @param timer - Timer instance
   */
  onBegin: Callback<Timer>;

  /**
   * Called before each update tick
   * @param timer - Timer instance
   */
  onBeforeUpdate: Callback<Timer>;

  /**
   * Called on each update tick
   * @param timer - Timer instance
   */
  onUpdate: Callback<Timer>;

  /**
   * Called when timer loops to next iteration
   * @param timer - Timer instance
   */
  onLoop: Callback<Timer>;

  /**
   * Called when timer is paused
   * @param timer - Timer instance
   */
  onPause: Callback<Timer>;

  /**
   * Called when timer completes all iterations
   * @param timer - Timer instance
   */
  onComplete: Callback<Timer>;

  // ===== Methods =====

  /**
   * Reset timer to initial state
   * @param softReset - If true, keeps some internal state
   * @returns Timer instance for chaining
   */
  reset(softReset?: boolean): Timer;

  /**
   * Initialize timer (internal method)
   * @param internalRender - Internal render flag
   * @returns Timer instance for chaining
   */
  init(internalRender?: boolean): Timer;

  /**
   * Reset time to zero without resetting state
   * @returns Timer instance for chaining
   */
  resetTime(): Timer;

  /**
   * Pause timer playback
   * @returns Timer instance for chaining
   */
  pause(): Timer;

  /**
   * Resume paused timer
   * @returns Timer instance for chaining
   */
  resume(): Timer;

  /**
   * Restart timer from beginning
   * @returns Timer instance for chaining
   */
  restart(): Timer;

  /**
   * Seek to specific time position
   * @param time - Time in milliseconds
   * @param muteCallbacks - If true or number, suppress callbacks during seek
   * @param internalRender - Internal render flag
   * @returns Timer instance for chaining
   */
  seek(
    time: number,
    muteCallbacks?: boolean | number,
    internalRender?: boolean | number
  ): Timer;

  /**
   * Alternate playback direction
   * @returns Timer instance for chaining
   */
  alternate(): Timer;

  /**
   * Play timer forward
   * @returns Timer instance for chaining
   */
  play(): Timer;

  /**
   * Reverse playback direction
   * @returns Timer instance for chaining
   */
  reverse(): Timer;

  /**
   * Cancel timer and stop playback
   * @returns Timer instance for chaining
   */
  cancel(): Timer;

  /**
   * Stretch timer duration, adjusting all child timings proportionally
   * @param newDuration - New duration in milliseconds
   * @returns Timer instance for chaining
   */
  stretch(newDuration: number): Timer;

  /**
   * Revert timer to initial state
   * @returns Timer instance for chaining
   */
  revert(): Timer;

  /**
   * Complete timer immediately, jumping to end
   * @returns Timer instance for chaining
   */
  complete(): Timer;

  /**
   * Promise-like interface for timer completion
   * @param callback - Function to call when timer completes
   * @returns Timer instance for chaining
   */
  then(callback: (timer: Timer) => void): Timer;
}

import { createTimer } from "animejs/timer";

// Basic timer with callbacks
const timer = createTimer({
  duration: 3000,
  onBegin: (t) => console.log("Started"),
  onUpdate: (t) => console.log(`Time: ${t.currentTime}ms`),
  onComplete: (t) => console.log("Finished"),
});

timer.play();

// Timer with looping
const loopTimer = createTimer({
  duration: 1000,
  loop: 5,
  direction: "alternate",
  onLoop: (t) => console.log(`Loop ${t.currentIteration + 1}`),
});

// Playback control
timer.pause();
timer.resume();
timer.restart();
timer.reverse();

// Seeking
timer.seek(1500); // Seek to 1.5 seconds
timer.seek("50%"); // Seek to halfway point
timer.progress = 0.75; // Set progress to 75%

// Promise-like completion
timer.then((t) => {
  console.log("Timer completed!");
  // Start another timer
});

const timer = createTimer({
  // Duration and timing
  duration: 2000, // Total iteration duration
  delay: 500, // Delay before start
  endDelay: 300, // Delay after each iteration

  // Looping
  loop: 3, // Number of loops (true for infinite)
  loopDelay: 200, // Delay between loops
  alternate: true, // Alternate direction on each loop

  // Direction
  direction: "reverse", // 'normal', 'reverse', 'alternate'
  reversed: false, // Start reversed

  // Playback
  autoplay: true, // Start immediately
  speed: 1, // Playback speed multiplier

  // Callbacks
  onBegin: (timer) => {},
  onBeforeUpdate: (timer) => {},
  onUpdate: (timer) => {},
  onLoop: (timer) => {},
  onPause: (timer) => {},
  onComplete: (timer) => {},
});

const timer = createTimer({ duration: 5000, autoplay: false });

// Start and stop
timer.play(); // Start playback
timer.pause(); // Pause playback
timer.resume(); // Resume from pause
timer.restart(); // Restart from beginning
timer.cancel(); // Cancel and stop

// Direction control
timer.reverse(); // Play in reverse
timer.alternate(); // Switch direction

// Complete immediately
timer.complete(); // Jump to end

const timer = createTimer({ duration: 5000 });

// Seek by time
timer.seek(2500); // Seek to 2.5 seconds
timer.currentTime = 1000; // Set current time directly

// Seek by progress
timer.seek("75%"); // Seek to 75% of duration
timer.progress = 0.5; // Set to halfway point

// Iteration control
timer.currentIteration = 2; // Jump to iteration 3 (0-indexed)
timer.iterationProgress = 0.25; // Seek within current iteration

// Get current position
console.log(timer.currentTime); // Current time in ms
console.log(timer.progress); // 0-1 overall progress
console.log(timer.iterationProgress); // 0-1 iteration progress
console.log(timer.currentIteration); // Current iteration number

const timer = createTimer({ duration: 2000, loop: 3 });

console.log(timer.began); // Has timer begun?
console.log(timer.completed); // Has timer completed?
console.log(timer.paused); // Is timer paused?
console.log(timer.reversed); // Is timer reversed?
console.log(timer.cancelled); // Has timer been cancelled?
console.log(timer.backwards); // Is playing backwards?

// Duration information
console.log(timer.iterationDuration); // Single iteration duration
console.log(timer.iterationCount); // Total iterations
console.log(timer.duration); // Total duration including all iterations

const timer = createTimer({
  duration: 1000,
  delay: 500, // Wait 500ms before starting
  endDelay: 300, // Wait 300ms after each iteration
  loop: 3,
  loopDelay: 200, // Wait 200ms between loops
  onBegin: () => console.log("Starting after delay"),
  onLoop: () => console.log("Looping with delay"),
});

// Total time calculation:
// (delay) + (duration + endDelay) * loops + loopDelay * (loops - 1)
// 500 + (1000 + 300) * 3 + 200 * 2 = 500 + 3900 + 400 = 4800ms
console.log(timer.duration); // 4800

const timer = createTimer({
  duration: 2000,
  delay: 500,
  loop: 2,
});

console.log(timer.duration); // Original total duration

// Stretch to new duration
timer.stretch(6000);

// All timings scale proportionally
// duration, delay, endDelay, loopDelay all adjusted

createTimer({ duration: 1000 })
  .then((t) => {
    console.log("First timer done");
    return createTimer({ duration: 2000 });
  })
  .then((t) => {
    console.log("Second timer done");
  });

/**
 * Timer configuration parameters
 */
interface TimerParams {
  /** Timer identifier */
  id?: string | number;

  /** Iteration duration in milliseconds */
  duration?: number;

  /** Delay before starting in milliseconds */
  delay?: number;

  /** Number of iterations (true for infinite) */
  loop?: number | boolean;

  /** Delay between loop iterations in milliseconds */
  loopDelay?: number;

  /** Alternate direction on each loop */
  alternate?: boolean;

  /** Start in reversed state */
  reversed?: boolean;

  /** Start playback immediately or link to scroll observer */
  autoplay?: boolean | ScrollObserver;

  /** Maximum frame rate in frames per second */
  frameRate?: number;

  /** Playback speed multiplier */
  playbackRate?: number;

  /** Called when timer begins */
  onBegin?: Callback<Timer>;

  /** Called before each update */
  onBeforeUpdate?: Callback<Timer>;

  /** Called on each update */
  onUpdate?: Callback<Timer>;

  /** Called on each loop */
  onLoop?: Callback<Timer>;

  /** Called when paused */
  onPause?: Callback<Timer>;

  /** Called when completed */
  onComplete?: Callback<Timer>;
}

/**
 * Callback function type
 */
type Callback<T> = (instance: T) => void;