forwarder/README.md

Forwarding of messages to different objects (mostly properties of the receiver)

# forwarder for Javascript

A Forwarder (Delegator for those who are not too much purist on this question) for Javascript.

Special support for Coffeescript classes.

ForwarderJS is highly inspired by Forwarder19 for Ruby.

## Examples

### Simple Forwarding Without Translation

```coffee-script
  { forward } = require 'forwarder'
  obj =
    name: "no name so far"

  forward obj, 'split', to: 'name'
  obj.split " " # --> ['no', 'name', 'so', 'far']

```

### Simple Forwarding With Translation

```coffee-script
  forward obj, 'seperate', to: 'name', as: 'split'
  obj.seperate " " # --> ['no', 'name', 'so', 'far']
```

### Forwarding with Currying

```coffee-script
  forward obj, 'tokenize', to: 'name', as: 'split', with: [' ']
  obj.tokenize() # --> ['no', 'name', 'so', 'far']
```

### Forwarding inside Coffeescript Classes

```coffee-script
  {Forwarder} = require 'forwarder'
  
  class F extends Forwarder
    constructor: ->
      @name = "no name so far"
      @forward 'split', to: "name"
```

But when forwarding to a method it is called and the return value
of that call is used as the target (the same is valid in case of any
function property that is the target of forwarding).

```coffee-script
      # assuming a reverse function property
      @forward 'reverse', to: 'designation'

    designation: -> "Data"
    (new F).reverse() # --> "ataD"
```

Alternatively one can use forwarder on instances without extending the class of course,
we will just specify this explicitely.

```coffee-script
  { forward } = require "forwarder"

  class F
    constructor: ->
      @name = "no name so far"
      forward @, 'split', to: "name"
```

Same behavior as above


### Forwarding as [] is Property access

This is equivalent to the `to\_hash` special target in the Ruby version, it allows us to
access object properties. Currying might be particulary interesting in this context

```coffee-script
     obj =
       content:
         a: 42
         b: 43

       forward obj, "a", to: "content", as: "[]", with: "a"
       obj.a() # --> 42

       forward obj, "get", to: "content", as: "[]"
       obj.get('b') # --> 43
```

*N.B.* This might be missleading for beginners, [] is not a function in Javascript.
I am mimicking this behavior here as it is a convenient way to implement accessors
to objects.