hi folks,

This was discussed at the dojo.data meeting today but it's a big change so I'm posting it to this list. Here's a proposal to dramatically simplify the dojo.data.Result object. I think this approach makes things considerably simpler both to use and to implement. It also makes dojo.data.Store.find look and behave a lot more like dojo.io.bind, improving API consistency. So here's the idea:

Store.find would look like:
find(query, kwargs)
where the kwargs can include:

sync : boolean [default if omitted: true]
onnext: callback called as each item in the result is received. Callback should expect an argument containing the item
oncompleted: callback func called, no argument (or maybe pass the result return value?)
onerror : error callback that expect an Error argument
saveResult : boolean If this is true an array (or maybe an Iterator?) will be set in the result attribute.
[default if omitted: if onnext is set, false, otherwise true]

Return value:
find() returns an object very similar to dojo.io.Request. Like dojo.io.Request it will mirror back the kwargs as attributes (i.e. have sync, onnext, etc. attributes) and will have the following addition attributes and methods:

result: if saveResult is set, will be an array (or maybe an iterator?), otherwise null. If the request is async this will be null until the request is completed but set prior to the call to oncompleted. If an error occurred it will be set to an Error object.

length: length of the result or -1 if not completed or error.

abort(): cancel the current async request.

Some examples:

The simple, synchronous use case:

var result = store.find(query);
if (result.length > -1) {
   var array = result.result;
}

Scrolling table use case (following Brian's YahooStore example):

this.result = store.find(query, { start : 0, count : this.itemsPerPage, oncompleted: this.displayPage } );

showNextPage() handler:
this.result = find(this.result.query,
   { start : this.currentItem, count : this.itemsPerPage,
     onnext: this.displayItem } );

Thoughts? I'm going to rewrite my RemoteStore to implement these changes and see how they feel...

-- adam