view release on metacpan or  search on metacpan

lib/App/FargateStack/Builder/Utils.pm  view on Meta::CPAN

=pod

=head1 NAME

App::FargateStack::Builder::Utils

=head1 SYNOPSIS

 # can be used as a role with Role::Tiny or you can import methods

 with 'App::FargateStack::Builder::Utils';

 use App::FargateStack::Builder::Utils qw(choose log_die);

=head1 METHODS AND SUBROUTINES

=head2 choose

A clever little helper that makes your code look awesome. Instead of this:

 my $foo;

 if ( $bar ) {
   $foo = 'biz';
 }
 else {
   $foo = 'baz';
 }

 my $foo = choose {
   return 'biz'
     if $bar;
 
   return 'baz';
 }

The example above would probably be handled by a ternary, but imagine
more complex logic and you'll see why the assignment and declaration
sometimes get separated.  Since I hate to do that...C<choose> was born.

=head2 normalize_timestamp

=head2 fetch_*

Use the C<fetch_*> methods to retrieve an instance of one of the AWS
API classes. The fetch method caches class instances and instantiates
them if necessary by providing common arguments (like profile).

 my $ecs = $self->fetch_ecs;

=head2 normalize_time_range

  my ($from_ms, $to_ms) = normalize_time_range($start, $end);

Normalizes a human-friendly time range into Unix epoch timestamps in
**milliseconds**.

Given a required C<$start> and an optional C<$end>, this routine parses
each value into epoch seconds (using L<Date::Parse/str2time> for absolute
dates, or a compact “duration” syntax), validates the range, and returns
a two-element list: C<(start_ms, end_ms_or_undef)>.

Returns an empty list if C<$start> is false/undefined (useful for
“no time filter” cases).

=head3 Arguments

=over 4

=item C<$start> (required)

Either:

=over 4

=item * A relative duration: C</^\d+[dmh]$/i>

Examples: C<"5m"> (5 minutes), C<"2h"> (2 hours), C<"7d"> (7 days).  
Zero durations (e.g., C<"0m">) are rejected.

=item * An absolute date/time string parsed by C<str2time>.

Examples: C<"2025-08-12 08:00">, C<"2025-08-12T08:00:00Z">, RFC-822 style,
etc. If no timezone is present, parsing uses the local timezone.

=back

=item C<$end> (optional)

Same accepted formats as C<$start>. If omitted, the end of the range is
left undefined.

=back

=head3 Behavior

=over 4

=item * A single “now” is captured at the start of the call, so when both
C<$start> and C<$end> are durations (e.g., C<"15m"> and C<"5m">) they are
evaluated relative to the same instant.

=item * Validation:

=over 4

=item * C<start is in the future> if C<$start> resolves after “now”.

=item * C<end is in the future> if C<$end> resolves after “now”.

=item * C<start > end> if both are defined and C<$start> resolves after C<$end>.

=item * C<duration cannot be zero> for C<0d>, C<0h>, or C<0m>.

=item * C<unrecognized date format: [VALUE]> if C<str2time> cannot parse.

=back

=back