https://github.com/polettix/memorator

Remind of events via Minion
https://github.com/polettix/memorator

Last synced: 27 days ago
JSON representation

Remind of events via Minion

• Host: GitHub
• URL: https://github.com/polettix/memorator
• Owner: polettix
• License: other
• Created: 2018-03-30T11:07:10.000Z (almost 7 years ago)
• Default Branch: master
• Last Pushed: 2018-04-04T20:52:18.000Z (almost 7 years ago)
• Last Synced: 2024-10-27T12:33:00.745Z (3 months ago)
• Language: Perl
• Size: 80.1 KB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: Changes
  • License: LICENSE

Awesome Lists containing this project

README

        
# NAME

Memorator - Remind of events via Minion

# VERSION

This document describes Memorator version {{\[ version \]}}.



    

    

    

    

    

    

    

    

    

    

    

    

    

    

    

    

    

    



# SYNOPSIS

    use Minion;

    my $minion = Minion->new(...);

    use Memorator;

    my $memorator = Memorator->create(

       alert_callback => sub {

          my $id = shift;

          print "notification for id <$id>\n";

          return;

       },

       minion => $minion,

       name => 'memorator', # this is the default

    );

    $minion->enqueue(memorator_process_update =>

       {

          id => 'id-001',       # identifier meaningful for you

          epoch => (time + 30), # when you want the alert

          attempts => 5,        # how many retries before giving up

       }

    );

# DESCRIPTION

> - _**memorātor**_

>     - imperative passive future of verb _memorāre_, can be translated like

>     _you will be reminded_ (see [https://en.wiktionary.org/wiki/memoro](https://en.wiktionary.org/wiki/memoro),

>     expand section on _Inflection_).

>     - nominative singular of _memorātor_, male third descension, can be

>     translated like _someone who mentions_ (see

>     [https://en.wiktionary.org/wiki/memorator](https://en.wiktionary.org/wiki/memorator))

This module allows you to set alerts for some events you need to be warned

of. It's as simple as asking an alarm to ring at a certain date/time.

The module leverages on [Minion](https://metacpan.org/pod/Minion) for the heavylifting. It's actually

a thin API on top of it, installing two _tasks_ which by default go under

the names `memorator_process_update` and `memorator_process_alert`

(although you can change the `memorator` part using ["name"](#name)).

The interaction model is simple:

- you create an object with an ["alert\_callback"](#alert_callback) and a `minion` object

that will do the hard work. The ["alert\_callback"](#alert_callback) is where you will

implement your logic for when the alert expires;

- you enqueue _updates_ to set new alarms or modify existing ones, based on

an _identifier_ that is meaningful for you;

- at the expiration of the alarm time, the ["alert\_callback"](#alert_callback) is called with

the specific _identifier_, so that you can figure out what has to be done

next.

To add a new reminder, or change an existing one, you use

`memorator_process_update` passing a hash reference like this:

    $minion->enqueue(memorator_process_update =>

       {

          eid => 'id-001',      # identifier meaningful for you

          epoch => (time + 30), # when you want the alert

          attempts => 5,        # how many retries before giving up

       }

    );

You can also set alerts directly, without the mediation of [Minion](https://metacpan.org/pod/Minion),

using ["set\_alert"](#set_alert):

    $memorator->set_alert(\%same_hashref_as_before);

See ["set\_alert"](#set_alert) for the allowed keys.

# METHODS

## **alert\_callback**

    my $sub_reference = $obj->alert_callback;

    $obj->alert_callback(sub {...});

accessor for the callback to be run when an alert has to be sent. It is

mandatory to set this before the first alert is sent. Can be set in the

constructor.

The callback will be invoked like follows:

    $callback->($identifier);

where `$identifier` is a meaningful identifier for your applications

(which is also the identifier passed upon creation of the event).

## **minion**

    my $minion = $obj->minion;

    $obj->minion($minion_instance);

accessor for the [Minion](https://metacpan.org/pod/Minion) used behind the scenes. Note that in callbacks

called in jobs the minion instance will be drawn from the jobs themselves,

as it might prove to be _fresher_.

## **name**

    my $name = $obj->name;

    $obj->name($new_name);

accessor for a name for generating local names of tables in the database,

as well as task names in [Minion](https://metacpan.org/pod/Minion). This allows you to have more instances

living inside the same [Minion](https://metacpan.org/pod/Minion), should you ever need to do this.

Defaults to `memorator`. Can be set in the constructor.

## **new**

    my $obj = Memorator->new(%args);

    my $obj = Memorator->new(\%args);

constructor. The recognized keys in `%args` correspond to accessors

["alert\_callback"](#alert_callback) (mandatory), ["minion"](#minion) (mandatory) and ["name"](#name)

(optional).

## **remove\_alert**

    $obj->remove_alert(\%hashref); # OR

    $obj->remove_alert($eid);

remove an alert. You can pass either a hash reference compatible with

["set\_alert"](#set_alert), or the external identifier for which you don't need the

alert any more. Returns nothing.

## **set\_alert**

    $obj->set_alert(\%hashref);

Set an alert. The following keys are supported:

- `attempts`

    how many times [Minion](https://metacpan.org/pod/Minion) will retry upon failure of your callback. In this

    case, _failure_ means _thrown exception_.

- `epoch`

    the UTC epoch at which you want the alert callback to be triggered. If

    this field is missing, the alert will be _removed_.

- `id`

    the [identifier](https://metacpan.org/pod/identifier) for your event, which can help you retrieve the details

    of your event somewhere else. It has a textual form, so you might want to

    abuse it to store more data (e.g. some JSON data); just keep in mind that

    it is treated as an _opaque identifier_, i.e. a string that is compared

    to other strings for equality.

You don't need to call this directly if you use [Minion](https://metacpan.org/pod/Minion) for enqueuing

alerts via `memorator_process_update` (or whatever name the task has,

based on ["name"](#name)).

# BUGS AND LIMITATIONS

Report bugs through GitHub (patches welcome).

# SEE ALSO

[Minion](https://metacpan.org/pod/Minion).

# AUTHOR

Flavio Poletti 

# COPYRIGHT AND LICENSE

Copyright (C) 2018 by Flavio Poletti 

This module is free software. You can redistribute it and/or modify it

under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but

without any warranty; without even the implied warranty of

merchantability or fitness for a particular purpose.