pubsub.publish is a bit verbose if I just want to send a simple string message?

[jgeewax]

Feels like if I just want to publish the message "Hello World" I have a lot more to know that I probably should, right?

var gcloud = require(‘gcloud’)({projectId: ‘my-project’, keyFile: ‘key.json’});
var pubsub = gcloud.pubsub();

pubsub.createTopic(‘Test’, function(err, topic) {
  console.log(‘Created topic’, topic);

  topic.publish({data: ‘Hello World!’}, function(err, messageIds) {
    console.log(‘Published message’, messageIds);
  });
});

Any chance we can simplify the string-only message?

var gcloud = require(‘gcloud’)({projectId: ‘my-project’, keyFile: ‘key.json’});
var pubsub = gcloud.pubsub();

pubsub.createTopic(‘Test’, function(err, topic) {
  console.log(‘Created topic’, topic);

  topic.publishString('Hello World!', function(err, messageId) {
    console.log('Published message', messageId);
  });
});

Or even better, just detect if someone sent us a string only...

var gcloud = require(‘gcloud’)({projectId: ‘my-project’, keyFile: ‘key.json’});
var pubsub = gcloud.pubsub();

pubsub.createTopic(‘Test’, function(err, topic) {
  console.log(‘Created topic’, topic);

  topic.publish('Hello World!', function(err, messageId) {
    console.log('Published message', messageId);
  });
});

[ryanseys]

We did this because if they publish a message as a string this way, and we want to support publishing an object with the same ease, they suddenly would need to wrap it around { data: message } which is confusing and inconsistent. Also it means that the message they receive on the other end doesn't match what they initially published.

[jgeewax]

I remember us talking about this one, can you remind me of the code that we write that brings about the key issue?

I'm thinking that this would be a "shortcut" for {data: 'Hello World'}...

[ryanseys]

Related #500. This functionality was removed when we removed support for topic#publishRaw and moved all functionality into topic#publish. I think it's do-able to bring it back. Thoughts @stephenplusplus ?

[stephenplusplus]

It should be fine to do. The downside is the magic that an all in one method would have. If it publishes strings or specially-formed objects, this might be confusing to document and have the user understand. If it publishes strings, why not a numeric counter, buffer, or object? I still think a plain JavaScript object is the most popular type to be published in a JS Pub/Sub pattern (no idea if that's true or not), and wish we could support that more easily as well.

[jgeewax]

That might be why we can offer a special method? publishString('Hello World')? or publishObject({key: 'val'})?

[stephenplusplus]

I still like the reverse... publish takes anything with type detection, publishRaw takes the raw format. Why did we axe that behavior again? Is there anyway we can make that work?

[ryanseys]

Found the reason deep in the hidden conversation of this PR (damn GitHub for hiding convos on outdated commits): #388 (comment)

[stephenplusplus]

Can you sum up the reason, I'm not sure I was able to grasp from that thread. I think if we change publishRaw to look like publish now, and publish to take any data type, we can send it to publishRaw in the data property.

[ryanseys]

I propose the following simplification that I believe is a balance between ease of use, functionality and clarity:

/**
 * @param {string|string[]|object|object[]} message - The message(s) to publish. If given as a 
 *    string, the message will be published simply as given. If an object is provided, the object
 *    must include data and attribute fields described in the parameters below. You may also 
 *    provide an array of these strings or objects to publish multiple messages. See the 
 *    provided examples for more information.
 * @param {*} message.data - The contents of the message.
 * @param {array=} message.attributes - Key/value pair of attributes to apply to
 *     the message. All values must be strings.
 * @param {function=} callback - The callback function.
 */
Topic.prototype.publish = function() { /* ... */ }

Examples:

// publish a single string message (typeof message === 'string')
topic.publish('message', callback);

// publish multiple string messages (typeof message === 'string')
topic.publish([ 'message1', 'message2' ], callback);

// publish a single raw message (typeof message === 'object') [same as existing impl.]
topic.publish({ data: x, attributes: y }, callback);

// publish multiple raw messages (typeof message === 'object') [same as existing impl.]
topic.publish([{ data: w, attributes: x }, { data: y, attributes: z }], callback);

[ryanseys]

This is where the examples are VERY IMPORTANT because the JSDoc is kinda cryptic. I think that's cool as long as we have great examples.

[stephenplusplus]

It's basically strings or "raw". I think we should support at least objects the same, or it's just weird. Developers will most often forget to box in their data as "data", and it's just an annoying step. If we force that boxing for all values like now, at least it's consistent. But, to offer magic string behavior and force boxing for all others from the same method is confusing.

I think it's most straightforward and predictable to accept any value to publish, and patch it to publishRaw (which would just do the boxing and message formatting for us).

[stephenplusplus]

This issue needs some updating. @jgeewax's original issue showed the use case for publishing a message on a brand new topic. We've found out since this issue that publishing a message to a topic without subscribers results in the message being dropped. So, we should only be considering the steps to publish a message to a topic that already exists.

var pubsub = gcloud.pubsub();
var topic = pubsub.topic('test');

topic.publish({ data: 'Hello World!' }, function(err, messageId) {
  console.log('Published message', messageId);
});

We should be able to support strings:

topic.publish('Hello World!', function(err, messageId) {/*...*/});

Another option would be to box in any data (strings, numbers, or objects) passed to publish by default (breaking change):

topic.publish({
  userId: 3,
  name: 'Stephen'
}, function(err, messageId) {/*...*/});

// The message that gets published to the API:
{
  data: {
    userId: 3,
    name: 'Stephen'
  }
}

... and allow turning off the auto-boxing if you need to use attributes:

var message = {
  data: {
    userId: 3,
    name: 'Stephen'
  },
  attributes: {
    source: 'github'
  }
};

topic.publish(message, { raw: true }, function(err, messageId) {/*...*/});

// The message that gets published to the API:
{
  userId: 3,
  name: 'Stephen',
  attributes: {
    source: 'github'
  }
}

@jgeewax @callmehiphop - wdyt?

[callmehiphop]

@stephenplusplus LGTM