=encoding utf8

=for comment POD_DERIVED_INDEX_GENERATED
The following documentation is automatically generated.  Please do not edit
this file, but rather the original, inline with Myriad::Role::Storage
at lib/Myriad/Role/Storage.pm
(on the system that originally ran this).
If you do edit this file, and don't want your changes to be removed, make
sure you change the first line.

=cut

=head1 NAME

Myriad::Role::Storage - microservice storage abstraction

=head1 SYNOPSIS

 my $storage = $myriad->storage;
 await $storage->get('some_key');
 await $storage->hash_add('some_key', 'hash_key', 13);

=head1 DESCRIPTION

Provides an abstraction over the Redis-based data model used by L<Myriad> services.

For more information on the API design, please see the official
L<Redis commands list|https://redis.io/commands>. This model was
used as the basis for the methods even when non-Redis backend
storage systems are used.

=head1 Implementation

Note that this is defined as a rôle, so it does not provide
a concrete implementation - instead, see classes such as:

=over 4

=item * L<Myriad::Storage::Implementation::Redis>

=item * L<Myriad::Storage::Implementation::Memory>

=back

=head1 METHODS - Write

=head2 set

Takes the following parameters:

=over 4

=item * C<$k> - the relative key in storage

=item * C<$v> - the scalar value to set

=back

Note that references are currently B<not> supported - attempts to write an arrayref, hashref
or object will fail.

Returns a L<Future> which will resolve on completion.

=head2 getset

Performs the same operation as L</set>, but additionally returns the original key value, if any.

Takes the following parameters:

=over 4

=item * C<$k> - the relative key in storage

=item * C<$v> - the scalar value to set

=back

Note that references are currently B<not> supported - attempts to write an arrayref, hashref
or object will fail.

Returns a L<Future> which will resolve on completion to the original value, or C<undef> if none.

=head2 push

Takes the following parameters:

=over 4

=item * C<$k> - the relative key in storage

=item * C<$v> - the scalar value to set

=back

Returns a L<Future>.

=head2 unshift

Takes the following parameters:

=over 4

=item *

=back

Returns a L<Future>.

=head2 pop

Returns a L<Future> which will resolve to the item removed from the list,
or C<undef> if none available.

=head2 shift

Returns a L<Future> which will resolve to the item removed from the list,
or C<undef> if none available.

=head2 hash_set

Takes the following parameters:

=over 4

=item *

=back

Returns a L<Future> which will resolve to .

=head2 hash_add

Takes the following parameters:

=over 4

=item *

=back

Returns a L<Future> indicating success or failure.

=head2 orderedset_add

Adds a member to an orderedset structure
Takes the following parameters:

=over 4

=item * C<$k> - the relative key in storage

=item * C<$s> - the scalar value of the score attached to member

=item * C<$m> - the scalar value of member

=back

Returns a L<Future>.

=head2 orderedset_remove_memeber

Removes a member from an orderedset structure
Takes the following parameters:

=over 4

=item * C<$k> - the relative key in storage

=item * C<$m> - the scalar value of member

=back

Returns a L<Future>.

=head2 orderedset_remove_byscore

Removes members that have scores within the range passed from an orderedset structure
Takes the following parameters:

=over 4

=item * C<$k> - the relative key in storage

=item * C<$min> - the value of minimum score

=item * C<$max> - the value of maximum score

=back

Returns a L<Future>.

=head1 METHODS - Read

=head2 get

Takes the following parameters:

=over 4

=item * C<$k> - the relative key in storage

=back

Returns a L<Future> which will resolve to the corresponding value, or C<undef> if none.

=head2 observe

Observe a specific key.

Returns a L<Ryu::Observable> which will emit the current and all subsequent values.

=head2 hash_get

Takes the following parameters:

=over 4

=item *

=back

Returns a L<Future> which will resolve to the scalar value for this key.

=head2 hash_keys

Takes the following parameters:

=over 4

=item *

=back

Returns a L<Future> which will resolve to a list of the keys in no defined order.

=head2 hash_values

Takes the following parameters:

=over 4

=item *

=back

Returns a L<Future> which will resolve to a list of the values in no defined order.

=head2 hash_exists

Takes the following parameters:

=over 4

=item *

=back

Returns a L<Future> which will resolve to true if the key exists in this hash.

=head2 hash_count

Takes the following parameters:

=over 4

=item *

=back

Returns a L<Future> which will resolve to the count of the keys in this hash.

=head2 hash_as_list

Takes the following parameters:

=over 4

=item *

=back

Returns a L<Future> which will resolve to a list of key/value pairs,
suitable for assigning to a hash.

=head2 orderedset_member_count

Returns the count of members that have scores within the range passed from an orderedset structure
Takes the following parameters:

=over 4

=item * C<$k> - the relative key in storage

=item * C<$min> - the value of minimum score

=item * C<$max> - the value of maximum score

=back

Returns a L<Future>.

=head2 orderedset_members

Returns the members that have scores within the range passed from an orderedset structure
Takes the following parameters:

=over 4

=item * C<$k> - the relative key in storage

=item * C<$min> - the value of minimum score

=item * C<$max> - the value of maximum score

=back

Returns a L<Future>.

=head1 INHERITED METHODS

=over 4

=item L<Object::Pad::UNIVERSAL>

L<BUILDARGS|Object::Pad::UNIVERSAL/BUILDARGS>

=back

=head1 AUTHOR

Deriv Group Services Ltd. C<DERIV@cpan.org>.

See L<Myriad/CONTRIBUTORS> for full details.

=head1 LICENSE

Copyright Deriv Group Services Ltd 2020-2022. Licensed under the same terms as Perl itself.

