Postal API Ideas

postal.ideas.js

// Below are FOUR possible examples of publish method signatures for the upcoming v0.6.0 release.  
// Each one is using a simple "data" object (containing Alex's first and last name, since we were chatting as I wrote the gist)
// It's also worth bearing in mind that this is the top level API publish (where you don't have a handle to a channel already)
// you'll still be able to say var channel = postal.channel({ channel: "someChannel", topic: "someTopic" }), and then call publish off that later

// 1.) Single Payload, envelope is special member
/*
  PROS:  
    one object to publish (data/env)
    focus is on "DATA" being published - nice for consuming dev?
  
  CONS:
    potentially more difficult to extract envelope and data into separate args w/o perf hit of delete
*/
postal.publish({
    _envelope: {
        channel: "myChannel",
        topic: "my.topic",
        timeStamp: new Date() // this is provided by postal when msg is published
    }
    firstName: "Alex",
    lastName: "Robson"
});

// subscriber
postal.subscribe({ channel: "myChannel", topic: "my.topic", callback: function(data, envelope) { console.log("Got yer datumz"); } });

// 2.) Single Payload, envelope is payload, published data is under "data" prop
/*
  PROS: 
    one object to publish (data/env) 
    in-line extend for enrichment style patterns 
    easier to pull data off of envelope object to pass to subscriber with (data, envelope) signature
    probably the most performant option when it comes to code execution on the publish side
  
  CONS:
    data is a sub object on publish (subscribe has option of separate args)  
*/
postal.publish({
    channel: "myChannel",
    topic: "my.topic",
    timeStamp: new Date(), // this is provided by postal when msg is published
    data: {
        firstName: "Alex",
        lastName: "Robson"
    }
});

// subscriber
postal.subscribe({ channel: "myChannel", topic: "my.topic", callback: function(data, envelope) { console.log("Got yer datumz"); } });

// 3.) Two Arg Approach (data, env) - current v0.6.0-RC
/*
  PROS: 
    explicit separation of data and env ?
    no perf hit on separating data/env into separate args into subscriber callback
    focus is on the data being published, env is secondary
  
  CONS:
    more typing
    potentially less readable than above approaches
    the most common use case will have the second arg being just an object literal specifying topic, seems heavy  
*/
postal.publish({
        firstName: "Alex",
        lastName: "Robson"
    },
    {
        channel: "myChannel",
        topic: "my.topic",
        timeStamp: new Date(),  // this is provided by postal when msg is published
    }
);

// subscriber
postal.subscribe({ channel: "myChannel", topic: "my.topic", callback: function(data, envelope) { console.log("Got yer datumz"); } });

// 4.) Two Arg Approach (env, data) - current v0.6.0-RC
/*
  PROS: 
    explicit separation of data and env ?
    envelope data first might be more expressive in reading?
  
  CONS:
    more typing
    potentially less readable than single arg approaches 
    the most common use case will have the first arg being just an object literal specifying topic, seems heavy   
*/
postal.publish({
        channel: "myChannel",
        topic: "my.topic",
        timeStamp: new Date(),  // this is provided by postal when msg is published
    },
    {
        firstName: "Alex",
        lastName: "Robson"
    }
);

// subscriber
postal.subscribe({ channel: "myChannel", topic: "my.topic", callback: function(data, envelope) { console.log("Got yer datumz"); } });
// OR reversed subscriber callback args (to match the publish order)
postal.subscribe({ channel: "myChannel", topic: "my.topic", callback: function(envelope, data) { console.log("Got yer datumz"); } });

Personally, I'm inclined towards option 2. It feels very familiar, and mental friction is generally what I worry about most in any given API.

Gentlemen - HUGE thanks for weighing in on this! Per this thread, and several one-on-one discussions, I've pushed the latest revisions to v0.6.0RC here. The readme reflects the latest API (and the fiddle link on the readme is updated as well). For this release I will be putting together a real website (soon, at least) with full-on API docs as well.

The TL;DR is option 2 above was used for the top level postal.publish signature, but you still have the fallback to use (topic, data) or (channel, topic, data). The publish on the channel has a 1 arg signature that can either be the plain data object you want to publish, or an envelope (it inspects the object for "topic" and "data", and if they're found, it's an envelope).

The channel's subscribe call just takes the callback, but if you subscribe from the global postal object (i.e. - you didn't already have a channel handy), then you have to pass in an options hash that has channel, topic and callback defined on it).

-Jim

Awesome! I'm late to the party but I agree on all accounts.

Great job

@rauhryan - thanks for weighing in man!