PuruVJ / svelte-interval

Svelte Interval

A comprehensive Svelte utility package for managing intervals with reactive durations, synchronization, and advanced control features. This package provides convenient classes and functions for creating and controlling setInterval operations with full reactivity support.

Features:

• Core Interval Management: Basic reactive interval functionality with pause/resume/stop controls
• Limited Intervals: Automatically complete after a specified number of ticks
• Interval Synchronization: Sync multiple intervals to tick together at the fastest interval's pace
• Reactive Durations: Dynamically change interval timings based on Svelte's $state
• Complete Lifecycle Control: Pause, resume, stop, and restart intervals
• Tick Counting: Track how many times intervals have fired
• Immediate Start Option: Optionally create intervals immediately upon initialization
• Automatic Cleanup: Handles clearInterval when durations change or components unmount
• Lazy Initialization: Intervals only start when accessed (unless immediate: true)

Installation

npm install svelte-interval-rune

Basic Usage

Creating a Simple Interval

<script>
  import { Interval } from 'svelte-interval-rune';

  const timer = new Interval(1000);
</script>

<p>Time: {timer.current.toLocaleTimeString()}</p>
<p>Ticks: {timer.tickCount}</p>

Immediate vs Lazy Initialization

<script>
  import { Interval } from 'svelte-interval-rune';

  // Lazy (default) - starts when accessed
  const lazyTimer = new Interval(1000);

  // Immediate - starts right away
  const immediateTimer = new Interval(1000, { immediate: true });
</script>

<p>Lazy: {lazyTimer.current.toLocaleTimeString()}</p>
<p>Immediate: {immediateTimer.current.toLocaleTimeString()}</p>

Reactive Duration

<script>
  import { Interval } from 'svelte-interval-rune';

  let speed = $state(1000);
  const timer = new Interval(() => speed);
</script>

<p>Duration: {timer.duration}ms | Ticks: {timer.tickCount}</p>
<button onclick={() => speed = 500}>Fast</button>
<button onclick={() => speed = 2000}>Slow</button>

Interval Control

Pause, Resume, and Stop

<script>
  import { Interval } from 'svelte-interval-rune';

  const timer = new Interval(1000);
</script>

<p>Ticks: {timer.tickCount} | Status: {timer.isActive ? 'Running' : timer.isStopped ? 'Stopped' : 'Paused'}</p>

<button onclick={() => timer.pause()}>Pause</button>
<button onclick={() => timer.resume()}>Resume</button>
<button onclick={() => timer.resume(true)}>Resume Immediate</button>
<button onclick={() => timer.stop()}>Stop</button>

Key Differences:

• Pause: Temporarily stops ticking but keeps the interval running internally
• Stop: Completely destroys the interval and resets state
• Resume: Continues from where it was paused
• Resume(true): Immediately ticks and resets timing cycle

Limited Intervals

Use LimitedInterval when you need an interval that automatically stops after a specific number of ticks.

<script>
  import { LimitedInterval } from 'svelte-interval-rune';

  const timer = new LimitedInterval(500, 10); // 500ms interval, stops after 10 ticks
</script>

<p>Ticks: {timer.tickCount} / {timer.maxTicks}</p>
<p>Remaining: {timer.remainingTicks}</p>
<p>Completed: {timer.isCompleted}</p>

<button onclick={() => timer.reset()}>Reset</button>
<input type="number" bind:value={timer.maxTicks} min="1" />

LimitedInterval Features

• Automatic Completion: Stops automatically after reaching maxTicks
• Reset Functionality: Use reset() to continue from current tick count
• Dynamic Limits: Change maxTicks at runtime
• Remaining Ticks: Track progress with remainingTicks
• Completion State: Check isCompleted status

Interval Synchronization

The sync() function allows multiple intervals to tick together at the pace of the fastest interval.

<script>
  import { Interval, LimitedInterval, sync } from 'svelte-interval-rune';

  const timer1 = new Interval(1000);        // 1 second
  const timer2 = new Interval(500);         // 500ms (will be leader - fastest)
  const timer3 = new LimitedInterval(750, 5); // 750ms, 5 ticks max

  const controller = sync(timer1, timer2, timer3);
</script>

<p>Leader: {controller.leader.duration}ms | Sync: {controller.isSynced ? 'On' : 'Off'}</p>
<p>Timer1: {timer1.tickCount} | Timer2: {timer2.tickCount} | Timer3: {timer3.tickCount}</p>

<button onclick={() => controller.enable()}>Enable Sync</button>
<button onclick={() => controller.disable()}>Disable Sync</button>

Sync Behavior

• Leader Selection: The fastest interval (shortest duration) becomes the leader
• Synchronized Ticking: All intervals tick together at the leader's pace
• Individual State: Each interval maintains its own pause/active state
• Leader Completion: When the leader completes (if it's a LimitedInterval), sync stops
• Restoration: When sync is disabled, intervals return to their individual timing

Advanced Sync Example

<script>
  import { Interval, LimitedInterval, sync } from 'svelte-interval-rune';

  const fast = new Interval(100);           // Fast timer
  const limited = new LimitedInterval(200, 3); // Limited interval

  const controller = sync(fast, limited);
</script>

<p>Fast: {fast.tickCount} | Limited: {limited.tickCount}/{limited.maxTicks}</p>
<p>Leader: {controller.leader.duration}ms | Completed: {limited.isCompleted}</p>

<button onclick={() => controller.enable()}>Start Sync</button>
<button onclick={() => limited.reset()}>Reset Limited</button>

API Reference

Interval Class

Constructor

new Interval(duration: number | (() => number), options?: IntervalOptions)

Parameters:

• duration - Static number or reactive function returning interval duration in milliseconds
• options.immediate? - If true, starts interval immediately. Default: false

Properties

• current: Date - Gets current time and auto-starts interval
• duration: number - Gets or sets the interval duration
• isActive: boolean - Whether the interval is currently active (not paused/stopped)
• isStopped: boolean - Whether the interval has been completely stopped
• tickCount: number - Number of times the interval has fired (auto-starts interval)

Methods

• pause(): void - Pauses the interval (can be resumed)
• resume(immediate?: boolean): void - Resumes the interval, optionally with immediate tick
• stop(): void - Completely stops and cleans up the interval
• [Symbol.dispose](): void - Automatic cleanup (works with using)

LimitedInterval Class

Extends Interval with automatic completion after N ticks.

Constructor

new LimitedInterval(duration: number | (() => number), maxTicks: number, options?: IntervalOptions)

Additional Parameters:

• maxTicks - Number of ticks before auto-completion

Additional Properties

• maxTicks: number - Gets or sets the maximum tick limit
• isCompleted: boolean - Whether the interval has reached its tick limit
• remainingTicks: number - Number of ticks remaining before completion

Additional Methods

• reset(): void - Resets completion state and resumes from current tick count

sync() Function

Signature

function sync(...intervals: Interval[]): SyncController;

Parameters:

• ...intervals - One or more Interval or LimitedInterval instances to synchronize

Returns: SyncController

interface SyncController {
	enable(): void; // Start synchronization
	disable(): void; // Stop synchronization and restore individual timing
	isSynced: boolean; // Whether sync is currently active
	leader: Interval; // The fastest interval driving synchronization
}

IntervalOptions

interface IntervalOptions {
	immediate?: boolean; // Start interval immediately on construction
}

Advanced Patterns

Custom Timer with Reset

<script>
  import { Interval } from 'svelte-interval-rune';

  let duration = $state(1000);
  let timer = $state(new Interval(() => duration));

  function resetTimer() {
    timer.stop();
    timer = new Interval(() => duration);
  }
</script>

<p>Ticks: {timer.tickCount} | Duration: {duration}ms</p>
<button onclick={() => duration = 500}>Fast</button>
<button onclick={() => resetTimer()}>Reset</button>

Countdown Timer

<script>
  import { LimitedInterval } from 'svelte-interval-rune';

  let countdown = new LimitedInterval(1000, 10); // 10 second countdown
</script>

<p>{countdown.isCompleted ? 'Time\'s Up!' : `${countdown.remainingTicks}s left`}</p>
<button onclick={() => countdown.current}>Start</button>
<button onclick={() => countdown.reset()}>Reset</button>

Performance Notes

• Lazy Initialization: Intervals only start when current or tickCount is first accessed (unless immediate: true)
• Automatic Cleanup: All intervals automatically clean up when components unmount
• Memory Efficient: Stopped intervals are fully cleaned up and garbage collected
• Sync Overhead: Minimal overhead when syncing intervals - leader drives all timing

Bundle Size

• Interval: ~475B (minified + brotlied)
• LimitedInterval: ~681B (minified + brotlied)
• sync: ~289B (minified + brotlied)
• Interval + LimitedInterval: ~684B (minified + brotlied)
• Interval + sync: ~679B (minified + brotlied)
• LimitedInterval + sync: ~877B (minified + brotlied)
• Total Package: ~876B for all features