Refactor about express-keenio HOT 2 CLOSED

• Create notes on my own crazy code as well as how done something like this.
• Use notes from both to rethink and refactor the interfaces, as well as reading the premise and philosophy just in case you're leading to the wrong way.

from express-keenio.

In general:
"Events can be seen as an intention-reaction mapping.
Events belong in a collection together when they can be described by similar properties.
We should capture almost everything (events, environment, user identity and metadata e.g. repeat visits.)
Installation should be fast."

n. Test options parser on its own.
n. Change name of getEventCollectionMetadataForRoute().
n. Push configuration defaults into their own file.
n. Add a checkInitialised test, to clean up some of the code.
n. Put some way of sending the 'library' in.
n. Options parser is too complicated so should be altered. Configuration should be simpler, too.
Take a look at the example in segment.io discussed below.

n. handle and handleAll should not share the same generateMiddleware. That makes the code difficult to write.
n. Better names than handle and handleAll should be picked.

n. Instead of if-else this.options.defaults we should use a key-value object with functions attached to this.
n. Instead of 'defaults' use the term 'handlers'.
n. Setting up 'handlers' should be done in configure() - creation of objects which handle each of these things and own methods.

n. Unfuck up _generateHandler like so:

• take a look at the TODO and the one below it, can they happen earlier?
• move code which creates res and req proxying elsewhere. http://jsfiddle.net/rXy7f/
• move addEvent into a track() method.

n. Move sanitize body into earlier stage before later parsing as it is more fundamental than parsing.
n. categorise methods properly:
event collection names (validate + generate)
-> routes
-> request/params (intention)
-> tracking
-> identify (evironment + users)
-> response (reaction)

In express-keenio:

• helpers.js is fine.
• options-parser.js is too complicated and not tested on its own.
• routes.js seems to contain the wrong kind of stuff + some of the if-elsing is weird...
• keenio-middleware.js is just huge and embarassing. It handles:
  • configuration
  • two methods of generating the middleware
  • generate middleware
    • a way of proxying in between a response object's methods (while calling extra methods) and building a variable.
    • a way of making a request to keen.io on the finished response.
    • a way of defaulting to particular tag + event collection names, or defining them specifically.
    • a way of getting the params of a request.
    • a way of creaiting the keen event from this information.
    • logging, emitting events, etc.
    • this method is called by handle() or handleAll().
  • parsing request bodies
  • parsing response bodies
  • generating an event collection name
  • identifying users
  • each of these have fallback methods - which can be overridden.
  • a method that sanitizes data which is sent to keen.IO for some reason called sanitizeBody.
  • a check whether a route should be excluded
  • a way of getting a routes metadata
  • some of these depending on how options was set (if-elsing a lot here.)
  • a way of testing the validity of an event collection name
  • a way of testing the validiting of a property name

In analytics.js:

lib/index.js:

• Pretty much just pulls in methods from client and the event emitter, to expose it all.
• The .on stuff is sorted out here - Client knows nothing about it. SMART.
  [lies! https://github.com/segmentio/analytics-node/blob/master/lib/client.js#L30]
• Some things are exposed which do not need to be - they could be tested elsewhere.
• test/analytics.js tests these in the most basic way. The only thing of interest is use traits.

lib/triggers.js:

• Triggers related to flushing, etc.
  [Move this documentation into my own issue.
  See: https://github.com/segmentio/analytics-node/blob/master/lib/triggers.js
  How is flush implemented: https://github.com/segmentio/analytics-node/blob/master/test/client.js#L220
  https://github.com/segmentio/analytics-node/blob/master/lib/client.js#L305
  https://github.com/segmentio/analytics-node/blob/master/lib/client.js#L352]

lib/defaults.js:

• The default configuration goes here AND is documented.
  [We need to decide which of these configs we will pull into other Keen.IO library:
  https://github.com/segmentio/analytics-node/blob/master/lib/defaults.js]

lib/client.js:

• This is the meat, and it is tested in test/client.js, too.
  [Tests I might be missing:
  https://github.com/segmentio/analytics-node/blob/master/test/client.js#L41
  https://github.com/segmentio/analytics-node/blob/master/test/client.js#L76
  https://github.com/segmentio/analytics-node/blob/master/test/client.js#L86 (perhaps we can enforce for some?)]
• Simple init() is here: https://github.com/segmentio/analytics-node/blob/master/lib/client.js#L52
  I like the way that options are handled.
  And initialized is set to true.
  And an event is emitted.
• Methods are documented as private as well as underscored.
• _checkInitialized() exists + cleaner! We should do this with some other awkward commented things - req.route, etc.
• Passes across the 'library' to identify inside a context: https://github.com/segmentio/analytics-node/blob/master/lib/client.js#L129
  Returns a promise and enqueues the message (which owns that promise.)
• Track is very similar to identify.
• Enqueue and flush are very important. See: https://github.com/segmentio/analytics-node/blob/master/lib/client.js#L270
  Effectively they are code which would belong to a deeper-level Keen.IO client library.

Ignore the latter thing until we have split everything up more and remade the interface.

And remade the data model a little bit.

EventCollections:
What should I do when an event collection name is incorrect?
Can I check route paths in advance?
From this complete the issue related to this.

After doing that begin to docco comment everything.

from express-keenio.