view release on metacpan or  search on metacpan

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

}

1;

__END__

=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

=head3 Returns

A two-element list in **milliseconds since the Unix epoch**:

  ( $start_ms, $end_ms_or_undef )

B<List context is expected.> In scalar context, Perl will return the last
element of the list (which may be C<undef>); don’t rely on that.

=head3 Examples

  # Last 15 minutes, open-ended end:
  my ($from, $to) = normalize_time_range('15m');         # $to is undef

  # Absolute window (local timezone if none given):
  my ($from, $to) = normalize_time_range('2025-08-12 00:00',
                                         '2025-08-12 06:00');

  # Mixed: from 2 hours ago to 30 minutes ago:
  my ($from, $to) = normalize_time_range('2h', '30m');

=head3 Notes

=over 4

=item * The return values are in milliseconds. Some AWS APIs expect seconds;
divide by 1000 if needed.

=item * Duration units supported are days (C<d>), hours (C<h>), and minutes
(C<m>). Seconds/weeks are not accepted.

=item * Absolute parsing is delegated to L<Date::Parse/str2time>; pass a
timezone (e.g., trailing C<Z>) to avoid local-TZ assumptions.

=back

=pod

=head3 jmespath_mapping

  my $expr = jmespath_mapping($prefix, $elems, $ucfirst);

Builds a JMESPath object-projection expression by combining a prefix
(e.g., C<'tasks[]'>) with a field mapping rendered in JMESPath syntax,
such as C<{TaskArn:taskArn,StartedAt:startedAt}>. Quotes are stripped
from the JSON representation to form valid JMESPath.

=head4 Arguments

=over 4

=item * C<$prefix> (Str)

A JMESPath prefix to project over, e.g., C<'tasks[]'> or C<'events[]'>.

=item * C<$elems> (HashRef|ArrayRef)

Either a hashref mapping output keys to source field names, or a list
of source field names. When a list/arrayref is provided, keys are
auto-generated via camel-casing utilities (see C<$ucfirst> below).

Examples: