next-resolver (Python)

A utility to simplify the repeated unique ID + async promise pattern, built on asyncio.

Install from PyPI:

pip install next-resolver

Basic usage

from next_resolver import next_resolver

next_fn, resolve = next_resolver()

# next unique identifier and its awaitable
uid, promise = next_fn()

# pass `promise` around, keep `uid` …
# … then when the work is done:
if condition:
    resolve(uid, value)

# or reject:
if error:
    resolve(uid, None, error=ValueError("reason"))

promise is a Promise (subclass of asyncio.Future). Await it like any other future:

result = await promise

Custom ID types

The factory accepts a callable typed (default: int) that turns a running counter into an ID. Use str for string IDs, or any hashable value suitable for use as a dict key:

next_fn, resolve = next_resolver(str)

uid, promise = next_fn()
assert isinstance(uid, str)

next_fn, resolve = next_resolver(lambda n: f"job-{n}")

uid, promise = next_fn()

If the callable can still collide with an existing ID, the implementation increments and tries again until the ID is unused—so keep ID creation cheap and deterministic per counter value.

Promise

Promise extends asyncio.Future and adds chaining similar to JavaScript promises:

• then(on_fulfilled, on_rejected=None) — returns another Promise
• catch(on_rejected) — rejection-only handler

Nested Promise values can be flattened with the async helper Promise.value(promise).

Requirements

Python 3.8+

See also

The repository README documents the JavaScript package of the same name.