I need Falcor's `call` method explained; or a good example?

Question

Is there a good detailed explanation or usage example anywhere of Falcor's call method?

I'm struggling to understand Falcor's call method. I understand the first to arguments (functionPath and args), but I'm clueless on what the last two arguments are and how they are used (refSuffixes and thisPaths). I don't understand their descriptions. From Falcor's API reference:

/**
 * Invokes a function in the DataSource's JSONGraph object.
 * @name call
 * @function
 * @arg {Path} functionPath the path to the function to invoke
 * @arg {Array.<Object>} args the arguments to pass to the function
 * @arg {Array.<PathSet>} refSuffixes paths to retrieve from the targets of JSONGraph References in the function's response.
 * @arg {Array.<PathSet>} thisPaths paths to retrieve from function's this object after successful function execution
 * @returns {Observable.<JSONGraphEnvelope>} jsonGraphEnvelope the response returned from the server.
 * @memberof DataSource.prototype
 */

I haven't been able to find a good usage example either. The best I've found is from this falcor issue comment (snippet below), but there are some variable definitions missing - eg. titleRef:

var dataSource = new Router([
 {
        route: 'list.push',
        call: function(callPath, args) {

            // retrieving the title id from the reference path:            
            titleId = titleRef.value[1];
            if (parseInt(titleId, 10).toString() !== titleId.toString())
                throw new Error("invalid input");

            return myListService.
                addTitle(titleId).
                then(function(length) {
                    return [
                        {
                            path: ['myList', length - 1],
                            value: titleRef
                        },
                        {
                            path: ['myList', 'length'],
                            value: length
                        }
                    ];
                });
        }
    }
]);

In another client and server example, it shows one way to use the call method: returning an object with { paths: [...], jsonGraph: {...} } — What is the difference between returning pathValues or this object with paths and jsonGraph?

I seem to be missing something in my local implementations and I'm thinking it's because I don't understand the last two arguments to a falcor call method.

Answer 1

I think I understand thisPaths, however I'm with you, I don't quite get refPaths yet. Here's my understanding of thisPaths.

If the call path is list.push then we can think of push as the method and list as the object. In other words, when list.push() is called, figuratively speaking, this === list inside the push() function. This requires some imagination, since it isn't literally the case in terms of JS runtime semantics. Rather Falcor is maintaining a loose analogy to JavaScript, if that makes sense.

So then, in client-side code, if you pass thisPaths like this:

model.call(
  ['list','push'], // call path
  [...], // args
  [...], // refPaths
  [['length'],[0, 'foo']] // thisPaths
)

...it will concatenate the this object with those thisPaths, and the resulting paths will be automatically refreshed in the model cache when the response happens:

[['list', 'length'], ['list', 0, 'foo']]

That's nice since it gives the client some control over what gets updated as a result of a call operation, without resorting to manual cache invalidations and re-fetches, and without the implementor of the call route handler needing to anticipate in advance what clients want.

Specifically, all of that happens without the implementor of the call handler function needing to do anything. (That's what had thrown me for a loop at first.) It's just a convenience that's available to you on the client side, and is automatically built into Falcor.