What is @rbnlffl/race?

This is a tiny JavaScript utility that lets you set a time limit on waiting for something to finish. If you're asking your code to do something async—like fetch data from a server or run a database query—but you don't want to wait forever, this package handles that for you. It's a thin wrapper around a built-in JavaScript feature called Promise.race, but with a countdown timer built in.

How it works

Imagine you're racing two runners. Promise.race is the starter gun: whichever runner finishes first wins, and the race ends immediately. This package adds a third invisible runner—the timeout. If neither of your actual tasks finishes before the timer runs out, the whole thing fails with an error message saying "Not settled after 5000ms!" (or however many milliseconds you set).

You can use it in two ways. First, you can race a single task against time—useful when you want to make sure a slow operation doesn't hang your app forever. Second, you can race multiple tasks against each other and a timeout at the same time—say, fetching data from your primary server or a backup server, whichever responds first, but giving up if both are too slow.

Who would use this?

Any JavaScript developer building something that depends on external services or operations that might be slow or unreliable. A web app that calls multiple APIs and wants the fastest response wins. A Node.js backend that queries a database but needs to return a response within 2 seconds. A real-time chat application that can't let one hanging request block the entire user experience. Anywhere you'd say "I need this done, but not at any cost—if it takes too long, just fail and move on."

The package is intentionally small and focused, which means it has zero dependencies and minimal overhead. It's the kind of tool you'd grab when you need something straightforward: set a timeout on an async operation, nothing fancy, nothing heavy.