Overview
Promise utilities provide powerful tools for managing asynchronous operations in your game. The main feature is the Queue
class, which allows you to execute promises sequentially with control over their execution flow.
Promise Utility Functions
Before diving into the Queue class, let’s look at some helpful utility functions for working with promises:
wait
A function to pause execution for a specified duration:
import { wait } from ' dill-pixel ' ;
// 'wait' is an alias for delay
isPromise
A type guard function to check if a value is a Promise:
import { isPromise } from ' dill-pixel ' ;
const value1 = Promise . resolve ();
console . log ( isPromise (value1)); // true
console . log ( isPromise (value2)); // false
function processValue ( value : unknown ) {
// TypeScript now knows value is a Promise
value . then ( ( result ) => console . log (result));
Queue Class
The Queue class provides a way to manage and execute a sequence of promises with control over their execution:
import { Queue, createQueue } from ' dill-pixel ' ;
// Create a queue using the factory function
const queue = createQueue (
() => loadTexture ( ' sprite.png ' ) ,
async () => await playAnimation () ,
const queue2 = new Queue ([ fetch ( ' api/data ' ), () => loadTexture ( ' sprite.png ' )]);
Queue Control
Control the execution flow of your promises:
const queue = new Queue ([ () => fetch ( ' /api/data1 ' ), () => fetch ( ' /api/data2 ' ), () => fetch ( ' /api/data3 ' )]);
// Check progress (returns a number between 0 and 1)
console . log (queue . progress ); // e.g., 0.33 after first promise completes
Tracking Progress
The Queue class provides a progress
property that returns a number between 0 and 1, representing the completion percentage:
import { Scene, Queue } from ' dill-pixel ' ;
export default class MyScene extends Scene {
private _queueComplete = false ;
private queue = new Queue ([
await fetch ( ' /api/data1 ' );
await fetch ( ' /api/data2 ' );
await fetch ( ' /api/data3 ' );
async update ( dt : number ) {
if ( ! this . _queueComplete ) {
this . _showQueueProgress ();
if ( this . queue . progress === 1 ) {
this . _queueComplete = true ;
private _showQueueProgress () {
console . log ( ` Progress: ${ Math . round ( this . queue . progress * 100 ) } % ` );
private _onQueueComplete () {
console . log ( ' Queue complete! ' );
Accessing Results
Track the results of executed promises:
const queue = new Queue ([ () => fetchUserData (), () => fetchGameState (), () => fetchLeaderboard ()]);
const results = queue . results ; // Array of resolved values
Common Use Cases
Sequential API Calls
const queue = new Queue ([ () => fetch ( ' /api/user ' ), () => fetch ( ' /api/preferences ' ), () => fetch ( ' /api/stats ' )]);
Timed Operations
const queue = new Queue ([
console . log ( ' After 1 second ' );
console . log ( ' After 2 more seconds ' );
Data Processing
const queue = new Queue ([
async () => processChunk (data . slice ( 0 , 100 )),
async () => processChunk (data . slice ( 100 , 200 )),
async () => processChunk (data . slice ( 200 , 300 )),
Best Practices
Error Handling:
const queue = new Queue ([
const response = await fetch ( ' /api/data ' );
return await response . json ();
console . error ( ' Failed to fetch: ' , error);
Dynamic Queue Management:
const queue = new Queue ();
for ( const url of urls) {
const response = await fetch (url);
Efficient Usage
// Less efficient: Creating new queues frequently
const queue = new Queue ([task1 , task2]); // Don't do this
// More efficient: Reuse queues
private queue = new Queue ();
runTasks ( tasks : ( () => Promise < void >)[] ) {
this . queue . cancel (); // Clear previous tasks
tasks . forEach ( ( task ) => this . queue . add (task));
Tips and Tricks
Combine with other utilities:
import { Queue, wait } from ' dill-pixel ' ;
const queue = new Queue ([
Create task factories:
function createFetchTask ( url : string ) {
const response = await fetch (url);
const queue = new Queue ([ createFetchTask ( ' /api/data1 ' ), createFetchTask ( ' /api/data2 ' )]);
Handle cleanup:
const queue = new Queue ([
queue . cancel (); // Stop current execution
queue . clear (); // Remove all tasks