<commit_before>`npm install notice`

### Version 0.0.11

**unstable** - api changes almost certainly will occur (without deprecation warnings)

notice
======

A middleware based communications scaffold.


The Standalone Notifier
-----------------------

Implementes a MessageBus for communications confined to a single process.

### create a default notifier

```coffee

notice   = require 'notice'
notifier = notice.create 'origin name'

```
#### send an event

```coffee

notifier.event 'event name', { optional: 'payload' }

#
# Send an event and assign a callback to receive the result.
#

notifier.event 'event name', {}, (err, msg) -> 
    
    # 
    # * Middleware traversal is terminated upon the first
    #   throw or uncaught exception inside the pipeline 
    #   and the `err` is passed here.
    # 
    # * Otherwise `msg` is populated with the message as 
    #   modified by middlewares registered on the notifier.
    # 

```

#### register some middleware

```coffee

notifier.use (msg, next) -> 
    
    msg.myContribution = '∑'
    next()

    #
    # why Middleware ?
    # ----------------
    # 
    # * The combination of subscribe-ability and assembly-line
    #   creates a powerful tool.
    # 

#
# Or middleware with a Title
#

notifier.use title: 'Pie Thrower', (msg, next) -> 
    
    throw 'π'

    #
    # why a Title ? 
    # -------------
    # 
    # * The (not yet implemented) bottleneck identifiability.
    # 

```

#### use the promise instead

```coffee

notifier.event 'event name',

    sending:   'this message'
    with:      'a promise waiting'
    insteadOf: 'a node style callback waiting'
    forThe:    'finalMessage'

.then(

    (finalMessage) -> 
    (error) -> console.log error == 'π'

)

```




The Distributable Notifier
==========================


The Hub
-------

`Notice.listen(hubName, opts, callback)`

```coffee

Notice.listen 'Hub Name', 

    #
    # Configure with opts.listen
    # -------------------------- 
    # 
    #  * Using socket.io
    #  * PENDING: adaptor abstraction to enable transport plugins
    #

    listen:

        secret:   '◊'<commit_msg>create a notifier that does more than just 'event()'<commit_after>`npm install notice`

### Version 0.0.11

**unstable** - api changes almost certainly will occur (without deprecation warnings)

notice
======

A middleware based communications scaffold.


The Standalone Notifier
-----------------------

Implementes a MessageBus for communications confined to a single process.

### create an event notifier (the default)

```coffee

notice   = require 'notice'
notifier = notice.create 'origin name'

```
#### send an event
```coffee

notifier.event 'event name', { optional: 'payload' }

#
# Send an event and assign a callback to receive the result.
#

notifier.event 'event name', {}, (err, msg) -> 
    
    # 
    # * Middleware traversal is terminated upon the first
    #   throw or uncaught exception inside the pipeline 
    #   and the `err` is passed here.
    # 
    # * Otherwise `msg` is populated with the message as 
    #   modified by middlewares registered on the notifier.
    # 

```
#### register some middleware
```coffee

notifier.use (msg, next) -> 
    
    msg.myContribution = '∑'
    next()

    #
    # why Middleware ?
    # ----------------
    # 
    # * The combination of subscribe-ability and assembly-line
    #   creates a powerful tool.
    # 

#
# Or middleware with a Title
#

notifier.use title: 'Pie Thrower', (msg, next) -> 
    
    throw 'π'

    #
    # why a Title ? 
    # -------------
    # 
    # * The (not yet implemented) bottleneck identifiability.
    # 

```
#### use the promise instead
```coffee

notifier.event 'event name',

    sending:   'this message'
    with:      'a promise waiting'
    insteadOf: 'a node style callback waiting'
    forThe:    'finalMessage'

.then(

    (finalMessage) -> 
    (error) -> console.log error == 'π'

)

```


### create a notifier that does more than just 'event()'

```coffee
os         = require 'os'
notice     = require 'notice'

module.exports.MessageBus = notice
    
    messages:
        alert: 
            beforeCreate: (msg, done) -> 
                {hostname, uptime, loadavg, totalmem, freemem} = os
                msg.sourceInfo = 
                    hostname: hostname()
                    uptime: uptime()
                    loadavg: loadavg()
                    totalmem: totalmem()
                    freemem: freemem()
                done()

            afterCreate:  (msg, done) -> 

                #
                # * This fires before the message is pushed onto the
                #   middleware pipeline.
                # 
                # * It creates an opportunity to pre-store the message
                #   and therefore have the persistence id/ref/uuid
                #   already assigned before emitting into runtime.
                # 

        classify: {}
        resolve:  {}
        escalate: {}
        debrief:  {}

```
use it
```coffee

{MessageBus} = require 'the_previous_block'

notifier = MessageBus.create 'origin_app_name'
notifier.alert "darn, i thought this wouldn't happen", 
    
    says: 'the developer'
    heresWhatIKnow: """ 

        Recorded at the time of writing the code. 

    """

```


The Distributable Notifier
==========================


The Hub
-------

`Notice.listen(hubName, opts, callback)`

```coffee

Notice.listen 'Hub Name', 

    #
    # Configure with opts.listen
    # -------------------------- 
    # 
    #  * Using socket.io
    #  * PENDING: adaptor abstraction to enable transport plugins
    #

    listen:

        secret:   '◊'
{'fraction_non_alphanumeric': 0.1413446267866596, 'fraction_numerical': 0.0014116816657843657, 'mean_word_length': 2.0261612386545647, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2416385', 'n_tokens_mistral': 1767, 'n_tokens_neox': 1604, 'n_words': 528}