Implement new util pattern

[josephjclark]

I'm keen to start implementing this pattern:

• All exported functions from an adaptor are OPERATIONS (take state, return state)
• Any non-operation functions are exported onto the util (or utils? I think it should be singular) object.

Typically util functions will be in a util.js file but this is less important. What's important is that the main adaptor object includes a utils object.

When using non-operation functions in job code, you always do util.whatever, like util.fetch or util.jsonPath(state, path).

Doing this helps make it clear to job writers what is an operation (and needs state passing) and what is just a function. Because it's pretty confusing right now!

[SOLVED] Difficulty #1

The hardest thing about this pattern is the docs!

How do document an exported namespace?

We don't handle this well at the moment. There are no docs on the common/http helpers.

There is a commented out bit in the docs template for interfaces, I think. Maybe we just restore this, but it may not be very readable.

Basically for each adaptor we need to list Functions (actually, Operations); and Utils, with the note that utils are available on the utils object.

Difficulty #2

What do we do about common, which right now has http and util namespaces?

Also common.http is actually old stuff.

I think the answer, as in #507 , is just to add the http helpers to the util object (even though they're in the http namespace). It's fine :)

Difficulty #3

When every adaptor adopts this pattern we are living in utopia, nirvana, shangra-la.

But while migrating, we're basically just introducing even more inconsistency to the design :( It reduces predictability.

This just means we should migrate the top 10 adaptors quickly, but maybe even do a push on the next 20.

[josephjclark]

I will spike something here

[josephjclark]

As of right now, the doc site supports namespacing. So if we were to add a utils. namespace, the docsite can easily handle it. Hurrah!

[josephjclark]

I think this is in-hand and all technical issue are resolved. common right now has several namespaces and salesforce 5.0 uses the util namespace for non-operations