Feedback about InteractionOuput

[relu91]

I am reporting the feedback from @sebastiankb about the interaction output. Here's his comment:

Personally, I love the beauty of this one liner:

const jsonValue = await thing.readProperty("temperature");

With the new interface, this will no longer be straightforward and gets more complex:

const jsonValue = (await (await thing.readProperty("temperature")).value());

Or you have to go for a two liner for better readability:

const response = await thing.readProperty("temperature");
const jsonValue = await response.value();

I see the advantage of the new approach but I'm wondering if there is a kind of hybrid approach possible?

I think he has a point and we may need to refine a little bit the interface towards a simpler solution. I know that we discussed in depth about this interface, therefore let's try to refine it and don't start the whole discussion again.

[relu91]

Options that come to my mind:

Define an additional method

const jsonValue = await thing.readPropertyValue("temperature");

or use a new name for streaming:

const stream = await thing.readPropertyStreaming("temperature");

Pro

Fast and easy.
Same as before.

Cons

• Redundancy
• Weird name for actions and events thing.invokActionValue (?) thing.subscribeEventValue (?)
• Longer API list

Return an object that extends Promise

In practice, we'll provide value, data, etc. early in the promise object. Using TypeScript this translate to:

interface InteractionOutput {
    /* other fields omitted*/
    data:ReadableStream;
    value():Promise<DataSchemaValue>;
}

class DataSchemaValue {

}

class AsyncInteractionOutput extends Promise<InteractionOutput> {
    /* other fields omitted*/

    // Notice here we may even obtain the stream immediately
    data():Promise<ReadableStream>{
        return new Promise(()=>{});
    }
    value():Promise<DataSchemaValue>{
        return new Promise(()=>{});
    }
}

class Thing {
    readProperty(name:string):AsyncInteractionOutput {
        return new AsyncInteractionOutput(()=>{})
    }
}

let thing = new Thing()
//valid syntax
let myValue = await thing.readProperty("test").value()

// still valid
let response = await thing.readProperty("test");
myValue = await response.value();

Pro

It allows the usage of both verbose and compact forms.

Cons

• Not sure if it is a best practice to extend Promise in JS. In TS AFIK it is not an antipattern.
• More complex description of the API that may confuse implementers.
• Not as clean as const jsonValue = await thing.readProperty("temperature"); you still have to call value

Wrapper utility function

Another programming style could be to use a wrapper utility function, but is very similar to use await twice:

const jsonValue = await value(thing.readPropertyValue("temperature"));

Pro

Easy to implement and describe

Cons

• We need to define a function for each member of InteractionOutput
• May be counter-intuitive
• Not as clean as const jsonValue = await thing.readProperty("temperature"); you still have to call value

Return directly InteractionOutput

As the title says this would allow to simply call the value function directly like this:

let myValue = await thing.readProperty("test").value()

Pro

Cleanest fix

Cons

We lose slightly the control over the parallelism; see the code below:

let thing = new Thing()
// request not created
let response = await thing.readProperty("test"); // request created and sent
// do something else (i.e. send info to the user that the request was successfully sent)
myValue = await response.value(); // response read


let myValue = await thing.readProperty("test").value() //request created sent and response read  
                                                                                     // I can't inform the user if the request was sent successfully

Plus: - Not as clean as const jsonValue = await thing.readProperty("temperature"); you still have to call value

[zolkis]

IMHO there is nothing wrong with this in JavaScript, but indeed a two-liner is more readable.

const jsonValue = await await thing.readProperty("temperature")).value();

From all alternatives,

• I don't like duplicating the methods,
• the value() wrapper is worse than a value() function
• returning directly InteractionOutput might work, if we add an error event on it - but we wanted to avoid events since the Node.js vs DOM events controversy. In return, we only save one await. IMHO that's not worth it.

Let's anneal this a bit more.

[danielpeintner]

It seems we are a bit running in circles but I dare to ask some questions I seem to lack information now ...

• I read some discussion above that for InteractionOutput besides the plain JSON value we need ReadableStream. Do we still need ArrayBuffer?
• why do we actually need the promises twice. InteractionOutput is returned as a promise. Could we simplify the interface by removing the value() promise function and give right away the value as attribute?

InteractionOutput {
  ...
  attribute DataSchemaValue value;
};

[zolkis]

Do we still need ArrayBuffer?

We basically have a simplified Body mixin, from which we omitted the types that are covered by DataSchema (i.e. the value() function), leaving ArrayBuffer there. Of course, we can remove it, but it's much simpler to handle than a stream.

Could we simplify the interface by removing the value() promise function and give right away the value as attribute?

I don't understand why the double await is a problem, when otherwise functionally it is the correct solution? We can have example code for showing how to deal with the interaction, that should be good.

So, why Promise for value() - we have discussed this extensively and it would be good to maintain the possibility to report errors, so the Promise is the best choice. Otherwise we could use a property and say that undefined is returned on error, in which case the app may try the ArrayBuffer, or rather, the ReadableStream. But this is a bit nasty interface (switch on value), using a Promise is more correct.

And before it pops up, yes, we do need the stream handling because the content types that are not covered by DataSchema. This as well has been discussed extensively.

Instead of going back (in circles) with the API design in order to satisfy momentary comments, we should probably improve communication about the API rationale, usage and examples. There is a reason why the API looks like now. :)

[zolkis]

For context, let's re-read #201, with the PR #209.

[zolkis]

Basically I see the following alternatives.

1. The current API. Code examples are here.
   Based on the examples, I think promises are used consistently, use cases covered, error paths covered. This is a robust and good API.
2. Experiment with returning a modified InteractionOutput that has 1 or 2 extra properties for error handling. One error could have occured during the interaction and another error is possible during data conversion to the value property (leaving value as undefined). The drawback is that the app has to check on errors, rather than integrate code in a promise handling flow (which is more natural and recommended). With this API we cannot have a one-liner example since we cannot guarantee the semantics of the value property without checking the errors.
3. A variation of the above is when value can return a special error object that would contain the error and the stream for further analysis from the app. The app still needs to check on the type, i.e. we cannot have a one-liner example either.

Based on these, the only correct one-liner example I see is when using a value() function, not property, which allows handling failures, or success case only (with guaranteeing we are on the success branch, and not making that dependent on the value of value property. Okay, that one-liner contains 2 awaits, but that's normal.

In summary, IMHO the attempts to remove one or both awaits introduce bigger issues than the esthetic concern about using double await.

@sebastiankb please comment. :)

[zolkis]

Closed accidentally, sorry.

[relu91]

In general, I agree with @zolkis, I felt that the API could be simplified but it's difficult to handle cleanly all the use cases defined. However, I would bet on this update to sort out this issue:

Return an object that extends Promise

It goes under the principle of a fluent design pattern. There's an article that illustrates a similar update for a JS library: https://evertpot.com/await-fluent-interfaces/.

I did not receive comments on this update what do you think?

From all alternatives,

• I don't like duplicating the methods,
• the value() wrapper is worse than a value() function
• returning directly InteractionOutput might work, if we add an error event on it - but we wanted to avoid events since the Node.js vs DOM events controversy. In return, we only save one await. IMHO that's not worth it.

@zolkis in your previous comment it seems that you skipped it, notice that returning directly InteractionOutput it's different than Return an object that extends Promise .

[zolkis]

in your previous comment it seems that you skipped it, notice that returning directly InteractionOutput it's different than Return an object that extends Promise .

I have skipped that option, indeed, kind of censored it out internally, it seems :). I am not sure extending Promise is a good idea (even though we might need other awaitable control objects as well). I would seek guidance from TC39 people for that, but that would take too long and anyway before that we should try all other options IMHO :).

[danielpeintner]

Scripting Call 2021-03-01
It seems the current API is the best w.r.t. flexibility and is as complex as it needs to be (according use-cases)