Home

time-queues

Welcome to the time-queues wiki! This documentation provides comprehensive information about the time-queues library.

Overview

time-queues is an efficient, lightweight library for organizing asynchronous multitasking and scheduled tasks in JavaScript applications. It works seamlessly in browsers and server-side environments like Node.js, Deno, and Bun.

The library provides elegant solutions for common timing and scheduling challenges, helping developers create responsive, efficient applications that follow best practices for resource management and user experience.

Key Features

• Efficient Task Scheduling: Schedule tasks to run at specific times or after delays
• Browser Performance Optimization: Execute tasks during idle periods or animation frames
• Page Lifecycle Management: Respond intelligently to page visibility and focus changes
• Resource Management: Control execution rates with throttling and debouncing
• Minimal Dependencies: Relies only on list-toolkit, a zero-dependency library

Documentation

This wiki contains detailed documentation for all components of the time-queues library:

Core Components (base classes)

• MicroTask: Base class for deferred execution
• MicroTaskQueue: Base class for task queues
• ListQueue: List-based queue implementation

Resource Management

• Scheduler: Time-based task scheduling
• Retainer: Manage resource lifecycle
• Throttler: Control execution rate based on keys
• Counter: Track the number of pending tasks asynchronously

Browser-Specific Components

• IdleQueue: Execute tasks during browser idle periods
• FrameQueue: Execute tasks during animation frames
• PageWatcher: Monitor and respond to page lifecycle changes

Utility Functions

• defer(): Execute tasks in the next tick
• sleep(): Promise-based delay function
• throttle(): Limit function execution rate
• debounce(): Delay function execution until input stabilizes
• sample(): Execute function at regular intervals
• audit(): Execute function after specified delay
• batch(): Execute asynchronous operations with controlled concurrency

Getting Started

To get started with time-queues, install it via npm:

npm install time-queues

Then import the components you need in your project:

// Import specific components
import {Scheduler, repeat} from 'time-queues/Scheduler.js';
import idleQueue from 'time-queues/IdleQueue.js';
import defer from 'time-queues/defer.js';

// Use the components in your application

For more information, see the documentation for each component in this wiki.

Browser-related notes

Internally it uses list-toolkit and leverages the following browser APIs:

• requestIdleCallback()
• requestAnimationFrame()
• queueMicrotask()
• setTimeout()
• Various events and properties.

There are many articles on the subject that detail how to leverage the APIs writing efficient applications. Some of them are:

• Background Tasks API
• Page Visibility API
• Page Lifecycle API

This package eliminates the need to write code that you'll write anyway following best practices.

Running a test web application

Don't forget to look at a test web application that uses the library. For that you should start a server:

npm start

And navigate to http://localhost:3000/tests/web/ — don't forget to open the console and play around: switch tabs, make other window active, navigate away and come back, and so on. See how queues work in tests/web/test.js.