Support back-references

[chibenwa]

Simple question but it would be really nice to use back-reference to chain JMAP calls and reduce server roundtrips.

(For someone like me based in Vietnam this is actually critical!)

You could:

start with a mailbox query to retrieve the guy INBOX
Then back-reference the INBOX in the email/query
And finally back-reference the ids in the Email/get

Doing all of that with a single network roundtrip, with a single API call.

Is there planned support for back-references in jmap-client-ts?

I would advise the maintainer to implement it early, in order to avoid generating technical debt.

See https://jmap.io/spec-core.html#references-to-previous-method-results

[[ "Foo/changes", {
    "accountId": "A1",
    "sinceState": "abcdef"
}, "t0" ],
[ "Foo/get", {
    "accountId": "A1",
    "#ids": {
        "resultOf": "t0",
        "name": "Foo/changes",
        "path": "/created"
    }
}, "t1" ]]

[alagane]

I put here the document about the possibles implementations of this feature, it is limited by my knowledge about typescript so there might be better solutions and I gladly appreciate any suggestions.

Implementation of request chaining on jmap-client-ts

The library currently supports simples requests (not chained), with simple method calls returning promises:

jmapClientTs.mailbox_get(...).then(...);

According to the specs, we can chain methods to use responses of not yet sent methods as parameters of others not yet sent methods, see specs here but this is not implemented yet on the library, and that is the aim of this document.

How it could be used

jmapClientTs.mailbox_query(...).mailbox_get(...).email_get(...).send().then();

Problems

Typing is lost

Cannot guess the type of the response depending of the type of the request?

How to guess if I call methods Mailbox/get chained with Email/query, typescript would tell me the response will be of type [ Mailbox/get response type, Email/query response type ] for example.

Chaining methods

It would change the current behaviour, we would have to send the request when the chain is finished (preferred).

Or we should add a way to chain methods other than just calling it.

Cannot use current types for replaceable properties

Properties starting with # depending on the responses of previous chained requests are invalid according to the defined types.

For example:

I have my request with these properties:

interface MyRequest {
    a: string;
    b: boolean;
}

If I want to call it with properties of another method reponse, I should do

let myRequest: MyRequest = {
    a: "value of a",
    "#b": {
        resultOf: "t0",
        name: "Request/get",
        path: "/prop"
    }
}

But the object would not be of the type MyRequest.

We could use a sort of type WithReplaceableProperties<MyRequest, ReplacedProperty extends key of MyRequest> that would let put custom properties, and these properties could be replaced just before JSON.stringify.

[alagane]

So the behaviour of the methods like should be changed to add .send() to be able to create chains; But there would be some higher-level functions internally using methods and back-references (chains) and those would not need the .send().

Type precision can be lost since those higher-level functions could be typed too.

For properties using # (making back-references) we could just duplicate the structures or use "any" and manually check properties are defined.

Refining types can be improved later.

[chibenwa]

While it yield some nice enhancements, I believe this might not be functionally needed on the short run.

Let's focus our efforts on other places...