🚀 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
• 🔄 Promise Wrapper - Wraps synchronous or asynchronous functions into Promises
• 🏗️ Zero Dependencies - Lightweight and focused functionality
• 🔒 Type-Safe - Written in TypeScript with full type definitions
• 🧪 Well Tested - Comprehensive test coverage

🛠️ Installation

Node.js / Bundlers

# Using npm
npm install prutill

# Using yarn
yarn add prutill

# Using pnpm
pnpm add prutill

Deno

import {
    getLastPromise,
    getRaceWonPromise,
    DelayedPromise,
} from "https://raw.githubusercontent.com/dominikj111/prutill/refs/tags/v1.2.0/mod.js";

📦 Supported Environments

• ✅ Node.js (CommonJS)
• ✅ ES Modules
• ✅ Deno
• ✅ Browsers

💡 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 { DelayedPromise } from "prutill";

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

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

Promise Wrapper

Wrap any synchronous or asynchronous function into a Promise:

import { promiseWrapper } from "prutill";

// Wrap a synchronous function
const result1 = await promiseWrapper(() => 42);
console.log(result1); // 42

// Wrap an asynchronous function
const result2 = await promiseWrapper(async () => {
    const response = await fetch("https://api.example.com/data");
    return response.json();
});

// Error handling
try {
    await promiseWrapper(() => {
        throw new Error("Something went wrong");
    });
} catch (error) {
    console.error(error); // Error: Something went wrong
}

📚 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

DelayedPromise

• 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-2.0 © dominikj111

This library is licensed under the Apache License, Version 2.0. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0