Netflix Falcor - When to return pathValues versus jsonGraph from the data source?

Question

In implementing a Falcor data source I am confused as to why sometimes you may return collections of path values:

[{path, value}, {path, value}]

And sometimes you must supply the return value as a jsonGraph envelope:

{jsonGraph: {something: {here: value}}}

I understand how the entire framework works within the context of jsonGraph, but sometimes collections of path values just work, and sometimes they don't. Maybe I'm just not representing more complicated jsonGraph shapes properly in path value collections.

My naive understanding is that collections of path values are parsed to jsonGraph by falcor. But I can't find any documentation on this.

If anyone can clarify when to use the respective return types, or what exactly collections of path values represent as return types it would be very much appreciated.

Follow Up

I believe my problem is simply not expressing JSONGraph in pathValue form correctly. For example, how is this arbitrary JSONGraph structure expressed with pathValues?

{jsonGraph: {tasksById: {0: "taskA",
                         1: "taskB",
                         2: "taskC"}}}

I thought that this would simply be a flat collection of 3 path values with the full path for each "task", but for some reason it keeps throwing.

[{path: ['tasksById', 0], value: "taskA"}, ...]

Is this the valid pathValue equivalent?

Answer 1

Handlers for get, set, and call should all accept either jsonGraph or an array of pathValues (or promises or observables wrapping either of those). There's a reported bug with using jsonGraph to invalidate paths (haven't tested to see if it's still an issue), but besides that, the two should be equivalent. I've found pathValues easier to express, so haven't worked much w/ jsonGraph.

As you noted, what is ultimately returned from the datasource is always a jsonGraphEnvelope wrapping jsonGraph, regardless of what your handlers return, so yes, if your handler returns pathValues, the datasource handles the transformation to jsonGraph.

sometimes collections of path values just work, and sometimes they don't

Can you give an example? Might be a bug, or might be malformed pathValues.

Edit

An example implementation of a get handler that nearly matches your example could look like:

const RootRouter = Router.createClass([
  {
    route: 'tasksById[{integers:indices}]',
    get: ({ indices }) => {
      return indices.map((index) => ({
        path: ['tasksById', index],
        value: `task #${index}`,
      }));
    }
  }
]);

const router = new RootRouter()

router.get([['tasksById', [0, 2]]])
  .subscribe((data) => console.log(data));

// {"jsonGraph":{"tasksById":{"0":"task #0","2":"task #2"}}}