Re: [IndexedDB] Proposal for async API changes

On Thu, May 20, 2010 at 11:55 AM, Shawn Wilsher <sdwilsh@mozilla.com> wrote:
> On 5/20/2010 11:30 AM, Andrei Popescu wrote:
>>
>> As someone new to this API, I thought the naming used in the current
>> draft is somewhat confusing. Consider the following interfaces:
>>
>> IndexedDatabase
>> IndexedDatabaseRequest,
>> IDBDatabaseRequest,
>> IDBDatabase,
>> IDBRequest
>>
>> Just by looking at this, it is pretty hard to understand what the
>> relationship between these interfaces really is and what role do they
>> play in the API. For instance, I thought that the IDBDatabaseRequest
>> is some type of Request when, in fact, it isn't a Request at all. It
>> also isn't immediately obvious what the difference between
>> IndexedDatabase and IDBDatabase really is, etc.
>
> It should be noted that we did not want to rock the boat too much with our
> proposal, so we stuck with the existing names.  I think the current spec as
> written has the same issues.

We kept the existing names specifically to avoid tying bikeshed naming
discussions to technical discussion about how these interfaces should
behave :)

>> - I know we need to keep the "IDB" prefix in order to avoid collisions
>> with other APIs. I would therefore think we should keep the IDB prefix
>> and make sure all the interfaces start with it (right now they don't).
>
> I agree with this.  We should probably file a bug about this.
>
>> - The "Request" suffix is now used to denote the asynchronous versions
>> of the API interfaces. These interfaces aren't actually Requests of
>> any kind, so I would like to suggest changing this suffix. In fact, if
>> the primary usage of this API is via its async version, we could even
>> drop this suffix altogether and just add "Sync" to the synchronous
>> versions?
>
> I agree that Request seems confusing and seems to be contrary to what other
> specs use.  We should try to follow what other specs do here.

Agreed on both accounts. There unfortunately isn't much in the way of
precedence here. There are three other specs to look at here, which
specify API for both workers and main thread.

* Web Workers spec
http://www.whatwg.org/specs/web-workers/current-work/ This spec
doesn't actually use different interfaces for workers and main thread.
* File API http://dev.w3.org/2006/webapi/FileAPI/ Specifies FileReader
and FileReaderSync. The two interfaces are separate and doesn't
inherit from a common base
* WebSQLDatabase http://dev.w3.org/html5/webdatabase/ Specifies
separate interfaces, like Database and DatabaseSync. The two
interfaces are separate and doesn't inherit from a common base.

I think we should follow the same convention as File API and
WebSQLDatabase. There really isn't anything to be gained by having a
common base interface, it just makes the spec harder to read as
functionality is distributed between the base interface and the
sync/async interface.

I additionally like the naming convention. The async interfaces is
probably the interface that people will use first. Additionally that
interface is available both to workers and to the main thread. So it
makes sense to give the async interface the simpler name.

>> - Some of the interfaces could have names that would more closely
>> reflect their roles in the API. For instance, IDBDatabase could be
>> renamed to IDBConnection, since in the spec it is described as "a
>> connection to the database".

Not really sold on this. I've always hated the "connection"
abstraction. With our suggested API IDBDatabase really just holds
metadata information about the database, and doesn't need to represent
a connection at all.

>> Likewise, IndexedDatabase could become
>> IDBFactory since it is used to create database connections or key
>> ranges.

This I agree with though.

>> In any case, I want to make it clear that the current naming works
>> once one takes the time to understand it. On the other hand, if we
>> make it easier for people to understand the API, we could hopefully
>> get feedback from more developers.
>
> Making it easier for someone to look at the method names and just know how
> to use the API seems like a good goal in my book.

Agreed. The 'Request' suffix in particular took me quite a while to get used to.

/ Jonas

Received on Thursday, 20 May 2010 19:20:46 UTC