node_modules/coffea/package.json

{
  "name": "coffea",
  "version": "1.0.0-beta9",
  "description": "an extensible library built to handle multiple chat protocols",
  "main": "./lib/index.js",
  "author": {
    "name": "Caffeinery Developers",
    "email": "daniel.bugl@touchlay.com"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/caffeinery/coffea.git"
  },
  "keywords": [
    "library",
    "extensible",
    "plugins",
    "protocols",
    "modular",
    "core",
    "es6"
  ],
  "bugs": {
    "url": "https://github.com/caffeinery/coffea/issues"
  },
  "dependencies": {
    "debug": "^2.2.0",
    "debug-dude": "^1.0.3"
  },
  "engine": "node >= 4.0.0",
  "license": "BSD-2-Clause",
  "devDependencies": {
    "babel-core": "^6.5.1",
    "babel-eslint": "^4.1.8",
    "babel-plugin-transform-object-rest-spread": "^6.5.0",
    "babel-preset-es2015": "^6.5.0",
    "babel-register": "^6.5.2",
    "chai": "^3.5.0",
    "eslint": "^2.0.0",
    "eslint-config-standard": "^5.1.0",
    "eslint-plugin-promise": "^1.0.8",
    "eslint-plugin-standard": "^1.3.2",
    "isparta": "^4.0.0",
    "mocha": "^2.4.5",
    "rimraf": "^2.5.2"
  },
  "scripts": {
    "clean": "./node_modules/.bin/rimraf lib",
    "compile": "./node_modules/.bin/babel --presets es2015 -d lib/ src/",
    "lint": "./node_modules/.bin/eslint src test",
    "test": "./node_modules/.bin/mocha --compilers js:babel-register --recursive",
    "test:cov": "./node_modules/.bin/babel-node ./node_modules/.bin/isparta cover ./node_modules/.bin/_mocha -- --recursive",
    "prepublish": "npm run lint && npm run test && npm run clean && npm run compile"
  },
  "readme": "# coffea\n\n[![NPM version (>=0.4)](https://img.shields.io/npm/v/coffea.svg?style=flat-square)](https://www.npmjs.com/package/coffea) [![Build Status](https://img.shields.io/travis/caffeinery/coffea/master.svg?style=flat-square)](https://travis-ci.org/caffeinery/coffea) [![Dependencies](https://img.shields.io/david/caffeinery/coffea.svg?style=flat-square)](https://david-dm.org/caffeinery/coffea) [![Documentation Status](https://readthedocs.org/projects/coffea/badge/?style=flat-square&version=latest)](https://readthedocs.org/projects/coffea/?badge=latest) [![Code Climate](https://img.shields.io/codeclimate/github/caffeinery/coffea.svg?style=flat-square)](https://codeclimate.com/github/caffeinery/coffea) [![Coverage](https://img.shields.io/coveralls/caffeinery/coffea.svg?style=flat-square)](https://coveralls.io/r/caffeinery/coffea)\n\n_coffea lays the foundations you need to painlessly and effortlessly connect to multiple chat protocols_\n\n**Table of contents:**\n\n * [Connecting](#connecting) (connecting to multiple networks on various protocols)\n * [Events](#events)\n   * [Listening on events](#listening-on-events)\n   * [Event helpers](#event-helpers) (creating events)\n   * [Sending events](#sending-events)\n * [Example: Reverse bot](#example-reverse-bot) (quickstart example)\n * [Protocols](#protocols) (implementing a new protocol)\n\n\n## Try it out!\n\nYou can install the latest coffea version like this:\n\n```\nnpm install --save coffea@beta\n```\n\nAs for protocols, we're working on [coffea-irc](https://github.com/caffeinery/coffea-irc), [coffea-slack](https://github.com/caffeinery/coffea-slack) and [coffea-telegram](https://github.com/caffeinery/coffea-telegram). Feel free to [build your own](#protocols) if you want to play around with coffea.\n\n\n## Connecting\n\nThe coffea core exposes a `connect` function (along with other functions, which are explained later). It can be imported like this:\n\n```js\nimport { connect } from 'coffea'\n```\n\nThis function loads the required protocols (via `node_modules`) and returns an instance container, which has the `on` and `send` functions.\n\n```js\n// create an instance container for one irc instance\n// Note: options get passed to the protocol, which handles them (e.g. autojoin channels on irc)\n//       please refer to the protocol documentation for more information about these options\n//       (usually available at https://npmjs.com/package/coffea-PROTOCOLNAME)\nconst networks = connect([\n  {\n    protocol: 'irc',\n    network: '...',\n    channels: ['#foo', '#bar']\n  }\n])\n\n// the instance container exposes the `on` and `send` functions:\nnetworks.send({...}) // we'll learn about sending events later\nnetworks.on('message', (msg, reply) => {...}) // we'll learn about listening to events later\n```\n\n**Note:** You need to install `coffea-PROTOCOLNAME` to use that protocol, e.g. `npm install coffea-slack`\n\nYou can now use this function to connect to networks and create instance containers! :tada:\n\n\n\n## Events\n\nEvents are *the* central concept in coffea. They have a certain structure (object with a `type` key):\n\n```js\n{\n  type: 'EVENT_NAME',\n  ...\n}\n```\n\nFor a message, it could look like this (imagine a git bot):\n\n```js\n{\n  type: 'message',\n  channel: '#dev',\n  text: 'New commit!'\n}\n```\n\n**Note:** In coffea, outgoing and ingoing events are always consistent - they look the same. That way you don't need to memorize two separate structures for sending/receiving events - awesome! (might even save some code)\n\n\n### Listening on events\n\ncoffea's `connect` function transforms the passed configuration array into an instance container, which is an enhanced array. This means you can use normal array functions, like `map` and `filter`. e.g. you could filter networks and only listen to `slack` networks, or you could use `map` to send a message to all networks. You could even combine them!\n\n```js\n// only listen to `slack` networks:\nnetworks.filter(network => network.protocol === 'slack')\n\n// `map` and `filter` combined\nnetworks\n  .filter(network => network.protocol === 'slack')\n  .map(network => console.log(network))\n```\n\nThe array is enhanced with an `on` function (and a `send` function, more on that later), which allows you to listen to events on the instance container:\n\n```js\nnetworks.on('event', (event, reply) => { ... })\n\nnetworks\n  .filter(network => network.protocol === 'slack')\n  .on('message', msg => console.log(msg.text))\n\n// sending events will be explained more later\nconst parrot = (msg, reply) => reply(message(msg.channel, msg.text))\nnetworks.on('message', parrot)\n```\n\n\n### Event helpers\n\nYou probably don't want to deal with raw event objects all the time - you write a lot of boilerplate and it's prone to error. That's why coffea (and the protocols) provide helper functions that create events, they can be imported like this:\n\n```js\n// `message` is a core event helper (it works on all protocols)\nimport { message } from 'coffea'\n\n// `attachment` is a protocol specific event helper (it only works on certain protocols)\nimport { attachment } from 'coffea-slack'\n```\n\n**Note:** Protocols should try to keep similar functionality consistent (e.g. if two protocols support attachments, keep the api consistent so you can use either helper function and it will work for both protocols).\n\nNow you can create an event like this:\n\n```js\nmessage('#dev', 'New commit!')\n```\n\nThe structure for event helpers is:\n\n```js\neventName(requiredArgs, { optionalArgs })\n```\n\n(`eventName` should always equal the `type` of the event that is returned to avoid confusion!)\n\nMultiple protocols can expose the same helper functions, but with enhanced functionality. e.g. for Slack you could do:\n\n```js\nimport { message, attachment } from 'coffea-slack'\nmessage(channel, text, { attachment: attachment('test.png') })\n```\n\n**Note:** coffea core's `message` helper function (if you import with `import { message } from 'coffea'`) does not implement the `attachment` option!\n\n\n### Sending events\n\nNow that you know how to create events, let's send them to the networks.\n\nThe instance container is also enhanced with a `send` function, which allows you to send *calling events* to the networks. e.g. sending a calling `message` event will send a message to the network.\n\n**Note:** As mentioned before, in coffea *calling events* and *receiving events* always look the same.\n\nYou can use the `message` helper function to send an event to all networks:\n\n```js\nimport { message } from 'coffea'\n\n// send to all networks:\nnetworks.send(message('#dev', 'Commit!'))\n\n// send to slack networks only:\nnetworks\n  .filter(network => network.protocol === 'slack')\n  .send(message('#random', 'Secret slack-only stuff.'))\n```\n\n#### `send` in combination with `on`\n\nIf you're sending events as a response to another event, you should use the `reply` function that gets passed as an argument to the listener. It will automatically figure out where to send the message instead of sending it to all networks (like `networks.send` does):\n\n```js\nimport { message } from 'coffea'\nnetworks.on('message', (msg, reply) => reply(message(msg.channel, msg.text)))\n```\n\nYou may want to keep the function definitions (`const parrot = ...`) separate from the `on` statement (`networks.on(...)`). This allows for easy unit tests:\n\n```js\n// somefile.js\nimport { message } from 'coffea'\nexport const parrot = (msg, reply) => reply(message(msg.channel, msg.text))\nexport const reverse = (msg, reply) => {\n  const reversedText = msg.text.split('').reverse().join('')\n  const message = message(msg.channel, reversedText)\n\n  reply(message)\n}\n\n// unittests.js\nimport { assert } from 'my-favorite-testing-library'\nimport { parrot, reverse } from './somefile'\nparrot('test', msg => assert(msg.text === 'test'))\nreverse('test', msg => assert(msg.text === 'tset'))\n\n// main.js\nimport connect from 'coffea'\nimport { parrot, reverse } from './somefile'\nconst networks = connect([...]) // put network config here\nnetworks.on('message', reverse)\n// or...\nnetworks.on('message', parrot)\n```\n\n\n\n## Example: Reverse bot\n\n```js\nimport { connect, message } from 'coffea'\n\nconst networks = connect([\n  {\n    protocol: 'irc',\n    network: '...',\n    channels: ['#foo', '#bar']\n  },\n  {\n    protocol: 'telegram',\n    token: '...'\n  },\n  {\n    protocol: 'slack',\n    token: '...'\n  }\n])\n\nconst reverse = (msg, reply) => {\n  const reversedText = msg.text.split('').reverse().join('')\n  const message = message(msg.channel, reversedText)\n\n  reply(message)\n}\n\nnetworks.on('message', reverse)\n```\n\n\n\n## Protocols\n\nThis is a guide on how to implement a new protocol with coffea.\n\nProtocols are functions that take `config`, a network configuration, and a `dispatch` function as arguments. They return a function that will handle all *calling events* sent to the protocol later.\n\nA simple protocol could look like this:\n\n```js\nexport default const dummyProtocol = (config, dispatch) => {\n  // mock connect event\n  dispatch({\n    type: 'connect',\n    network: config.network\n  })\n\n  return event => {\n    switch (event.type) {\n      case 'message':\n        dispatch({\n          type: 'message',\n          text: event.text\n        })\n        break\n      default:\n        dispatch({\n          type: 'error',\n          text: 'Unknown event'\n        })\n        break\n    }\n  }\n}\n```\n\nTo use this protocol, you have to pass the protocol function to `connect`:\n\n```js\nimport { connect, message } from 'coffea'\nimport dummyProtocol from './dummy'\n\nconst networks = connect([\n  {\n    protocol: dummyProtocol,\n    network: 'test'\n  }\n])\n\nconst logListener = msg => console.log(msg)\nnetworks.on('message', logListener)\n\nnetworks.send(message('hello world!'))\n```\n\n`dummyProtocol`'s event handler will then receive the following as the `event` argument:\n\n```js\n{\n  type: 'message',\n  text: 'hello world!'\n}\n```\n\nWhich means it will dispatch the `message` event, which results in the `on('message', listener)` listeners getting called with the same `event` argument.\n\nFinally, the `logListener` function will get called, which results in the following output on the console:\n\n```\n{\n  type: 'message',\n  text: 'hello world!'\n}\n```\n\n### `forward` helper\n\n```js\nforward({\n  eventName: function,\n  ...\n})\n```\n\nYou probably don't want to use `switch` statements to parse the events, which is why coffea provides a `forward` helper function. It forwards the events (depending on their type) to the specific handler function and can be used like this:\n\n```js\nimport { forward } from 'coffea'\n\nexport default const dummyProtocol = (config, dispatch) => {\n  // mock connect event\n  dispatch({\n    type: 'connect',\n    network: config.network\n  })\n\n  return forward({\n    'message': event => dispatch({\n        type: 'message',\n        text: event.text\n      }),\n\n    'default': event => dispatch({\n        type: 'error',\n        text: 'Unknown event'\n      })\n  })\n}\n```\n\n**Note:** `'default'` will be called if the event doesn't match any of the other defined types.\n\nThis helper also allows you to separate your event handlers from the protocol logic:\n\n```js\nimport { forward } from 'coffea'\n\nconst messageHandler = dispatch => event =>\n  dispatch({\n    type: 'message',\n    text: event.text\n  })\n\nconst defaultHandler = dispatch => event =>\n  dispatch({\n    type: 'error',\n    text: 'Unknown event'\n  })\n\nexport default const dummyProtocol = (config, dispatch) => {\n  // mock connect event\n  dispatch({\n    type: 'connect',\n    network: config.network\n  })\n\n  return forward({\n    'message': messageHandler(dispatch),\n    'default': defaultHandler(dispatch)\n  })\n}\n```\n",
  "readmeFilename": "README.md",
  "_id": "coffea@1.0.0-beta9",
  "dist": {
    "shasum": "aff089f1c584deea20a2d56eef9bba1087a40e53"
  },
  "_from": "coffea@^1.0.0-beta16",
  "_resolved": "https://registry.npmjs.org/coffea/-/coffea-1.0.0-beta9.tgz"
}