Events / Observables

I’d be interested in discussing how expected events on observable objects could be described. Here’s a first draft for one possibility based on my understanding of the current structural types:

new Channel({ displayName: String }) => ChannelInstance

interface ChannelInstance {
  displayName: String
}, emits: {
  messageAdded: { body: String, authorId: Number },
  memberJoined: { id: Number }
}

Thoughts?

[ericelliott]

@tomekwi One of the most important goals for me was to create a standard for documenting APIs that we can use in technical documentation.

We needed a standard, easily machine-readable way to document events, regardless of the listening API.

As for scope creep, I don’t expect early implementations to cover all the features, but event documentation was a must-have feature for me that needed to be in the MVP version. I’m already using it.

[ericelliott]

This is acceptable to me if everybody else likes it better:

emits: {
  'messageAdded': (body: String, authorId: Number),
  'memberJoined': (id: Number, { Name: String, email: String })
}

I guess that makes sense if you think of it this way:

messageAdded is the name of the callback function with the signature (body: String, authorId: Number).

This fits our existing method syntax:

emits: {
  messageAdded(body: String, authorId: Number),
  memberJoined(id: Number, { Name: String, email: String })
}

I’m not sure if we’ve documented it, but IMO, it should be perfectly legal to use quotes and colons with the method syntax, too:

interface MyCallbacks {
  'messageAdded': (body: String, authorId: Number),
  'memberJoined': (id: Number, { Name: String, email: String })
}