Promise...pelining(3)

✨ Promise...pelining(3) — aka Promises::Cookbook::ChainingAndPipelining ✨

okay bestie so this is a page from the User Contributed Perl Documentation, and it's literally a cookbook. A cookbook of chaining and pipelining asynchronous operations. it's giving "I promise I'll call you back" but make it structured. 🎀

🌸 NAME 🌸

Promises::Cookbook::ChainingAndPipelining — no cap, it's just examples of chaining/pipelining of asynchronous operations. that's the whole vibe.

💜 VERSION 💜

version 1.05 — yes queen, we know exactly which one. 💅

🦋 SYNOPSIS 🦋

like, here's the whole thing in action:

my $cv = AnyEvent->condvar;

fetch_it(
    'http://rest.api.example.com/-/user/search?access_level=admin'
)->then(
    sub {
        my $admins = shift;
        collect(
            map {
                fetch_it( 'http://rest.api.example.com/-/user/' . url_encode( $_->{user_id} ) )
            } @$admins
        );
    }
)->then(
    sub { $cv->send( @_ ) },
    sub { $cv->croak( 'ERROR' ) }
);

my @all_admins = $cv->recv;

okay so like, look at that. it's a whole pipeline and it's chef's kiss. 😭✨

🌈 DESCRIPTION 🌈

so one of the real benefits of the Promise pattern — and honestly the main character benefit — is how it lets you write code that flows and reads more like synchronous code, by using the chaining nature of Promises. iykyk. 🔥

in the example above we are first fetching a list of users whose access level is 'admin'. in our fictional web-service we get back a list of JSON objects with only minimal information — just a user_id and full_name, for instance. from here we can then loop through the results and fetch the full user object for each one of these users, passing all of the promises returned by "fetch_it" into "collect", which itself returns a promise. chain chain chain, butterfly effect but make it async 🦋

so despite being completely asynchronous, this code reads much like a blocking synchronous version would read. top to bottom. no notes. 👑

my @all_admins;
try {
    my $admins = fetch_it( 'http://rest.api.example.com/-/user/search?access_level=admin' );
    @all_admins = map {
        fetch_it( 'http://rest.api.example.com/-/user/' . url_encode( $_->{user_id} ) )
    } @$admins;
} catch {
    die $_;
};
# do something with @all_admins ...

the only difference really are the "then" wrappers and the way in which we handle errors. but even that is very similar, since we are not including an error callback in the first "then" and allowing the errors to bubble till the final "then", which maps very closely to the "try/catch" block. it's the same picture, bestie. 💖

and of course the Promise version runs asynchronously and reaps all the benefits that brings. periodt. 💅

---

💀 AUTHOR 💀

Stevan Little <stevan.little@iinteractive.com> — icon, legend, the moment. 🫶

🎀 COPYRIGHT AND LICENSE 🎀

this software is copyright (c) 2025, 2017, 2014, 2012 by Infinity Interactive, Inc.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie!! this was generated by perl v5.42.0 on 2025-07-25, so if you're reading it, hi, you're in the right timeline. go forth and chain your promises responsibly ✨🦋🌸