Re: [indexeddb] openCursor optional parameters issue

On Mon, Jun 27, 2011 at 11:42 AM, Israel Hilerio <israelh@microsoft.com> wrote:
> The IDBObjectStore.openCursor method is defined to have two optional parameters:
> * IDBRequest openCursor (in optional any range, in optional unsigned short direction) raises (IDBDatabaseException);
>
> Based on the examples in the spec, it seems we're envisioning the method to be used in the following ways:
> * objStore.openCursor();
> * objStore.openCursor(keyRange);
> * objStore.openCursor(keyRange, IDBCursor.PREV);
> * objStore.openCursor(IDBCursor.PREV);

No, that's not how optional parameters work in WebIDL. In order to
specify an optional parameter, you always have to specify all
preceding optional parameters. So only the following syntaxes are
valid:

* objStore.openCursor();
* objStore.openCursor(keyRange);
* objStore.openCursor(keyRange, IDBCursor.PREV);

> Having "any" for the keyRange type makes it difficult to detect the correct overloaded parameter for openCursor.

The reason the first parameter is of type 'any' is so that you can
pass either a IDBKeyRange or a value. So for example:

req = objStore.openCursor("hello");
req = index.openCursor(4);

are valid. When called with a simple value on an object store the
cursor will obviously always return 0 or 1 rows. For indexes it could
return any number of rows though.

This is actually already specified if you look at the steps for
opening a cursor. The same holds true for many other functions, such
as .get and .delete.

However it's a very subtle feature that's easy to miss. If you have
suggestions for how to make this more clear in the spec I'd love to
hear them. I've been thinking that we should add non-normative,
easy-to-understand text to explain each function, similar to what the
HTML5 spec does when defining APIs.

/ Jonas

Received on Tuesday, 28 June 2011 03:21:33 UTC