prutill

A lightweight, environment-agnostic, production-ready Promise utility library for managing concurrent Promise executions and their side effects.

Features

• Last Promise Resolution - Ensures only the most recent Promise affects your application state
• Race Promise Resolution - Acts on the first resolved Promise while managing others
• Timed Promises - Create Promises that resolve after a specified timeout
• Environment Agnostic - Works in Node.js, Deno, browsers, and bundlers
• Zero Dependencies - Lightweight and focused functionality
• Type Safe - Written in TypeScript with full type definitions

Installation

Node.js / Bundlers

# Using npm
npm install prutill

# Using yarn
yarn add prutill

# Using pnpm
pnpm add prutill

Deno

import {
    getLastPromise,
    getRaceWonPromise,
    TimedPromise,
} from "https://raw.githubusercontent.com/dominikj111/prutill/main/index-deno.ts";

Usage

Last Promise Resolution

Useful for scenarios where you only want to act on the most recent Promise, like in React's useEffect:

import { getLastPromise } from "prutill";

// React example
useEffect(() => {
    getLastPromise("data-fetch", fetchData()).then(data => {
        // Only the latest fetch will update the state
        setState(data);
    });
}, [dependency1, dependency2]);

Race Promise Resolution

When you want to act on the first resolved Promise:

import { getRaceWonPromise } from "prutill";

// Multiple API endpoints example
getRaceWonPromise("fastest-api", fetch("api1")).then(data => {
    // First resolved API response wins
    processData(data);
});
getRaceWonPromise("fastest-api", fetch("api2"));

Timed Promise

Create Promises that resolve after a specific duration:

import { TimedPromise } from "prutill";

// Resolve after 500ms
new TimedPromise(500).then(() => {
    console.log("500ms passed");
});

// Resolve with value after 1000ms
new TimedPromise(1000, "Hello").then(value => {
    console.log(value); // Outputs: "Hello"
});

API Documentation

getLastPromise(key: string, promise: Promise, resolveAllPrevious = true): Promise

• key: Unique identifier for the promise stack
• promise: Promise to add to the stack
• resolveAllPrevious: If true, resolves all previous promises with the latest value

getRaceWonPromise(key: string, promise: Promise, resolveAllOthers = true): Promise

• key: Unique identifier for the promise race
• promise: Promise to add to the race
• resolveAllOthers: If true, resolves all other promises with the winning value

TimedPromise

• constructor(timeout: number, passThrough?: T)
• timeout: Time in milliseconds before the promise resolves
• passThrough: Optional value to resolve with

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

Apache License 2.0 - see LICENSE for details.

Status

• Production Ready
• Full Test Coverage
• TypeScript Support
• Cross-Platform Support