# NAME Promise::ES6 - ES6-style promises in Perl # SYNOPSIS $Promise::ES6::DETECT_MEMORY_LEAKS = 1; my $promise = Promise::ES6->new( sub { my ($resolve_cr, $reject_cr) = @_; # .. } ); my $promise2 = $promise->then( sub { .. }, sub { .. } ); my $promise3 = $promise->catch( sub { .. } ); my $promise4 = $promise->finally( sub { .. } ); my $resolved = Promise::ES6->resolve(5); my $rejected = Promise::ES6->reject('nono'); my $all_promise = Promise::ES6->all( \@promises ); my $race_promise = Promise::ES6->race( \@promises ); # DESCRIPTION This is a rewrite of [Promise::Tiny](https://metacpan.org/pod/Promise::Tiny) that implements fixes for certain bugs that proved hard to fix in the original code. This module also removes superfluous dependencies on [AnyEvent](https://metacpan.org/pod/AnyEvent) and [Scalar::Util](https://metacpan.org/pod/Scalar::Util). The interface is the same, except: - Promise resolutions and rejections accept exactly one argument, not a list. (This accords with the standard.) - A `finally()` method is defined. - Unhandled rejections are reported via `warn()`. (See below for details.) # COMPATIBILITY Right now this doesn’t try for interoperability with other promise classes. If that’s something you want, make a feature request. # UNHANDLED REJECTIONS As of version 0.05, unhandled rejections prompt a warning _only_ if one of the following is true: - 1) The unhandled rejection happens outside of the constructor. - 2) The unhandled rejection happens via an uncaught exception (even within the constructor). # MEMORY LEAKS It’s easy to create inadvertent memory leaks using promises in Perl. Here are a few “pointers” (heh) to bear in mind: - As of version 0.07, any Promise::ES6 instances that are created while `$Promise::ES6::DETECT_MEMORY_LEAKS` is set to a truthy value are “leak-detect-enabled”, which means that if they survive until their original process’s global destruction, a warning is triggered. - If your application needs recursive promises (e.g., to poll iteratively for completion of a task), the `current_sub` feature (i.e., `__SUB__`) may help you avoid memory leaks. - Garbage collection before Perl 5.18 seems to have been buggy. If you work with such versions and end up chasing leaks, try manually deleting as many references/closures as possible. See `t/race_success.t` for a notated example. You may also (counterintuitively, IMO) find that this: my ($resolve, $reject); my $promise = Promise::ES6->new( sub { ($resolve, $reject) = @_ } ); # … etc. … works better than: my $promise = Promise::ES6->new( sub { my ($resolve, $reject) = @_; # … etc. } ); # SEE ALSO If you’re not sure of what promises are, there are several good introductions to the topic. You might start with [this one](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises). Promise::ES6 serves much the same role as [Future](https://metacpan.org/pod/Future) but exposes a standard, cross-language API rather than a proprietary one. CPAN contains a number of other modules that implement promises. Promise::ES6’s distinguishing features are simplicity and lightness. By design, it implements **just** the standard Promise API and doesn’t assume you use, e.g., [AnyEvent](https://metacpan.org/pod/AnyEvent). # LICENSE & COPYRIGHT Copyright 2019 Gasper Software Consulting. This library is licensed under the same terms as Perl itself.