Rewrite how cursors as specified. Create a separate section for database operations. Fixes bugs 10058, 10088, 10430, 11094, 11187, 11246
authorJonas Sicking <jonas@sicking.cc>
Mon, 08 Nov 2010 03:30:39 -0800
changeset 778716288a4fe1
parent 76 5b9b80f969cd
child 78 792faedb3f15
Rewrite how cursors as specified. Create a separate section for database operations. Fixes bugs 10058, 10088, 10430, 11094, 11187, 11246
Overview.html
Speclet_020_IDB_API_Constructs.html
Speclet_021_IDB_API_Algorithms.html
Speclet_022_IDB_API_Synchronous_APIs.html
Speclet_023_IDB_API_Asynchronous_APIs.html
     1.1 --- a/Overview.html	Wed Nov 03 17:12:19 2010 +0100
     1.2 +++ b/Overview.html	Mon Nov 08 03:30:39 2010 -0800
     1.3 @@ -337,25 +337,123 @@
     1.4        <h2>Indexed Database API</h2>
     1.5  	        <section id="constructs" class="section">
     1.6        <h3>Constructs</h3>
     1.7 -        <p>
     1.8 -          An indexed database is made of records holding simple values
     1.9 -          and hierarchical objects. Each <dfn>record</dfn> consists of a key and a value. 
    1.10 -        </p>
    1.11 -        
    1.12 +       <section id="database-concept" class="section">
    1.13 +          <h4>Database</h4>
    1.14 +          <p>
    1.15 +            Each <a>origin</a> has an associated set of 
    1.16 +            <a title="database">databases</a>. A <dfn>database</dfn> comprises
    1.17 +            one or more <a title="object store">object stores</a> which hold the data stored
    1.18 +            in the database.
    1.19 +          </p>
    1.20 +          <p>
    1.21 +            Every <a>database</a> has a <dfn title="database name">name</dfn> which identifies it
    1.22 +            within a specific <a>origin</a>. The name can be any string value, including the empty string, and
    1.23 +            stays constant for the lifetime of the database. Each <a>database</a> also has a current
    1.24 +            <dfn>version</dfn>. When a database is first created, its <a>version</a> is the empty string.
    1.25 +          </p>
    1.26 +          <p class="note">
    1.27 +            Implementations MUST support all names. If a implementation
    1.28 +            uses a storage mechanism which can't handle arbitrary database names,
    1.29 +            the implementation must use an escaping mechanism or something similar
    1.30 +            to map the provided name to a name that it can handle.
    1.31 +          </p>
    1.32 +          <div class="note">
    1.33 +            Each <a>database</a> has one version at a time; a <a>database</a> 
    1.34 +            can't exist in multiple versions at once. The only way to change the version is using a VERSION_CHANGE
    1.35 +            <a>transaction</a>.
    1.36 +          </div>
    1.37 +          <p>
    1.38 +            The act of opening a <a>database</a> creates a <dfn>connection</dfn>. There MAY be multiple 
    1.39 +            <a>connection</a>s to a given <a>database</a> at any given time. Each connection has a
    1.40 +            <dfn>closePending</dfn> flag which initially is set to false.
    1.41 +          </p>
    1.42 +          <p>
    1.43 +            When a <a>connection</a> is initially created it is in <var>opened</var> state. The connection
    1.44 +            can be <dfn title="database close">closed</dfn> through several means. If the connection is GCed
    1.45 +            or execution context where the <a>connection</a> is created is destroyed (for example due to the
    1.46 +            user navigating away from that page), the connection is closed. The connection can also be closed
    1.47 +            explicitly using the <a>steps for closing a database connection</a>. When the connection is closed
    1.48 +            the <a>closePending</a> flag is always set to true if it hasn't already been.
    1.49 +          </p>
    1.50 +          <p>
    1.51 +            The <a><code>IDBDatabase</code></a> and <a><code>IDBDatabaseSync</code></a>
    1.52 +            interfaces represent a <a>connection</a> to a <a>database</a>. 
    1.53 +          </p>
    1.54 +        </section>  <!-- IDBDatabase -->
    1.55 +
    1.56 +        <section class="section" id="object-store-concept">  
    1.57 +          <h4>Object Store</h4>
    1.58 +          <p>
    1.59 +            An <dfn>object store</dfn> is the primary storage mechanism for storing data in a
    1.60 +            <a>database</a>.
    1.61 +          </p>
    1.62 +          <p>
    1.63 +            Each database contain a set of <a>object store</a>s. The set of <a>object store</a>s
    1.64 +            can be changed, but can only be changed using a VERSION_CHANGE transactions. When a new database is
    1.65 +            created it doesn't contain any <a>object store</a>s and has the empty string as <a>version</a>.
    1.66 +          </p>
    1.67 +          <p>
    1.68 +            The object store has a <a title="object store record list">list of records</a> which hold the
    1.69 +            data stored in the object store. Each <dfn>record</dfn> consists of a <dfn>key</dfn> and a <dfn>value</dfn>.
    1.70 +            The list is sorted according to key in ascending order. There can never be multiple records in a given object
    1.71 +            store with the same key.
    1.72 +          </p>
    1.73 +          <p>
    1.74 +            Every <a>object store</a> has a <dfn title="object store name">name</dfn>.
    1.75 +            The name is unique within the <a>database</a> to which it belongs. Every object store also optionally has a
    1.76 +            <a>key generator</a> and a optional <dfn title="object store key path">key path</dfn>.
    1.77 +            If the object store has a key path it is said to use <dfn>in-line keys</dfn>. Otherwise it is said to
    1.78 +            use <dfn>out-of-line</dfn> keys.
    1.79 +          </p>
    1.80 +          <p>
    1.81 +            The object store can derive the <a>key</a> from one of three sources. Which source is used is determined
    1.82 +            when the object store is created. The three sources are:
    1.83 +          </p>
    1.84 +          <ol>
    1.85 +            <li>
    1.86 +              A <dfn>key generator</dfn>. A key generator generates a monotonically increasing numbers every time
    1.87 +              a key is needed.
    1.88 +              <p class="issue">
    1.89 +                specify that generators are not shared between stores.
    1.90 +              </p>
    1.91 +            </li>
    1.92 +            <li>
    1.93 +              A <dfn>key path</dfn>. A key path points to a property in a given <a>value</a>. When a object store uses a
    1.94 +              <a>key path</a> to generate keys, the key is the property in the stored <a>value</a> pointed to by the
    1.95 +              <a>key path</a>.
    1.96 +              <p class="issue">
    1.97 +                Need to specify how a key path is parsed and how a "evaluated" against a value. Including the requirement
    1.98 +                that the value needs to be a object and that the property must be enumerated.
    1.99 +              </p>
   1.100 +            </li>
   1.101 +            <li>
   1.102 +              Keys can also be explicitly specified when a <a>value</a> is stored in the object store.
   1.103 +            </li>
   1.104 +          </p>
   1.105 +          <!--div class="ednote">
   1.106 +            The detached reading behavior MAY need more explanation.
   1.107 +            What is detached reading?
   1.108 +          </div-->
   1.109 +          <p>
   1.110 +            The <a><code>IDBObjectStore</code></a> and <a><code>IDBObjectStoreSync</code></a>
   1.111 +            interfaces represent a <a>object store</a>. Note however that multiple instances of those
   1.112 +            interfaces representing the same <a>object store</a> can exist.
   1.113 +          </p>
   1.114 +        </section> <!-- Object store -->
   1.115 +
   1.116          <section id="key-construct" class="section">
   1.117            <h4>Keys</h4>
   1.118 -          
   1.119            <p>
   1.120 -            In order to efficiently retrieve <a title="record">records</a> 
   1.121 -            stored in an indexed database, a user agent needs to organize each 
   1.122 -            <a>record</a> according to its key. <a>Conforming user agents</a>
   1.123 -            MUST support the use of the following types as <dfn>key value</dfn>s: IDL data types
   1.124 +            In order to efficiently retrieve <a>record</a>s stored in an indexed database,
   1.125 +            each <a>record</a> is organized according to its key. A value is said to be a <dfn>valid key</dfn>
   1.126 +            if it is one of the following types: IDL data types
   1.127              <code>DOMString</code>, <code>long</code>, and <code>float</code> [[!WEBIDL]]; the
   1.128              <code>Date</code> JavaScript object [[!ECMA-262]]; as well as the value <code>null</code>.
   1.129 -            For the particular case of <code>float</code>, the value NaN is not allowed.
   1.130 +            Additionally, if the value os of type <code>float</code>, it is only a <a>valid key</a> if it is not NaN.
   1.131 +            <a>Conforming user agents</a> MUST support all <a>valid key</a>s as keys.
   1.132            </p>
   1.133            <p class="note">
   1.134 -            Inifinite <code>float</code> values are allowed.
   1.135 +            Inifinite <code>float</code> values are <a>valid key</a>s.
   1.136            </p>
   1.137            <p>
   1.138              For purposes of comparison, all <code>DOMString</code> values are evaluated as greater than 
   1.139 @@ -377,152 +475,67 @@
   1.140          <section id="value-construct" class="section">
   1.141            <h4>Values</h4>
   1.142            <p>
   1.143 -            Values can be any data type supported by the <a>structured clone algorithm</a> 
   1.144 +            Each record is associated with a <dfn>value</dfn>. <a>Conforming user agents</a> MUST support
   1.145 +            any value supported by the <a>structured clone algorithm</a> 
   1.146              [[!HTML5]]. This includes simple types such as <code>DOMString</code>
   1.147              and <code>Date</code> as well as <code>Object</code> and <code>Array</code>
   1.148              instances.
   1.149            </p>
   1.150 -          
   1.151 -          <p>
   1.152 -            A database can derive a key from the contents of
   1.153 -            the value being stored. In such a case, only <code>Object</code> 
   1.154 -            instances MAY be stored as values. Only the direct enumerable
   1.155 -            properties of a stored <code>Object</code> instance SHOULD be 
   1.156 -            used to derive a key value.
   1.157 -          </p>
   1.158          </section>
   1.159          
   1.160 -        <section class="section" id="object-store-concept">  
   1.161 -          <h4>Object Store</h4>
   1.162 -          <p>
   1.163 -            An <dfn>object store</dfn> is a persistent storage mechanism that 
   1.164 -            holds key-value pairs, also called <a title="record">records</a> 
   1.165 -            or <dfn>stored objects</dfn>. An <a>object store</a>'s 
   1.166 -            <a title="record">records</a> are sorted by keys to enable fast 
   1.167 -            insertion and look up as well as ordered retrieval. 
   1.168 -          </p>
   1.169 -          <p>
   1.170 -            Every <a>object store</a> has a 
   1.171 -            <dfn title="object store name">name</dfn>. Within a <a>database</a>, 
   1.172 -            each <a>object store</a> MUST have a <a title="valid-name">valid</a> 
   1.173 -            and unique <a title="object store name">name</a>. 
   1.174 -          </p>          
   1.175 -          <p>
   1.176 -            If an <a>object store</a> uses keys generated from a monotonically
   1.177 -            increasing sequence, it MUST have a <dfn>key generator</dfn> that 
   1.178 -            produces unique keys for <a title="record">records</a> in that 
   1.179 -            <a>object store</a>. Alternatively, if an application provides keys, 
   1.180 -            they MAY either be identified as a part of the value being stored, 
   1.181 -            also called <dfn>in-line keys</dfn>, or be identified separately, 
   1.182 -            also called <dfn>out-of-line keys</dfn>. No two 
   1.183 -            <a title="record">records</a> in an <a>object store</a> MAY be 
   1.184 -            identified by the same key. An <a>object store</a> MUST have a 
   1.185 -            <dfn title="object store key path">key path</dfn> if it uses 
   1.186 -            <a>in-line keys</a>. The <a>key path</a> MUST be the name 
   1.187 -            of an enumerated property of all stored objects in that 
   1.188 -            <a>object store</a>.
   1.189 -          </p>
   1.190 -          <!--div class="ednote">
   1.191 -            The detached reading behavior MAY need more explanation.
   1.192 -          </div-->
   1.193 -          <p>
   1.194 -            The <a><code>IDBObjectStore</code></a> and <a><code>IDBObjectStoreSync</code></a>
   1.195 -            interfaces provide access to the metadata of an <a>object store</a>.
   1.196 -          </p>
   1.197 -        </section> <!-- Object store -->
   1.198 -        
   1.199          <section id="index-concept" class="section">
   1.200            <h4>Index</h4>
   1.201            <p>
   1.202 -            <a title="record">Records</a> in an <a>object store</a> can be 
   1.203 -            retrieved using the <a title="record">record's</a> key. However, 
   1.204 -            that MAY not always be adequate to recall 
   1.205 -            <a title="record">records</a>. An <a>index</a> is used to lookup 
   1.206 -            records in an <a>object store</a> other than through a
   1.207 -            <a>record</a> key.
   1.208 +            It is sometimes useful to retreive <a>records</a> in a <a>object store</a> through other means
   1.209 +            than their <a>key</a>. A <dfn>index</dfn> allows looking up <a>record</a>s in a <a>object store</a>
   1.210 +            using properties of the <a>value</a>s in the <a>object store</a>s <a>record</a>s.
   1.211            </p>
   1.212            <p>
   1.213 -            An <dfn>index</dfn> is a specialized persistent store that holds 
   1.214 -            key-value pairs such that each value is the key of objects in the 
   1.215 -            <dfn>referenced</dfn> <a>object store</a>. If an <a>index</a>'s 
   1.216 -            <dfn>unique</dfn> flag is set, then it MUST NOT allow duplicate 
   1.217 -            values for a key. Every <a>index</a> has a 
   1.218 -            <dfn title="index name">name</dfn>. Within an 
   1.219 -            <a>object store</a>, each <a>index</a> MUST have a
   1.220 -            <a title="valid-name">valid</a> and unique 
   1.221 -            <a title="index name">name</a>.
   1.222 +            An index is a specialized persistent key-value storage and has a <dfn>referenced</dfn> <a>object store</a>.
   1.223 +            The index has a <dfn title="index record list">list of records</dfn> which hold the
   1.224 +            data stored in the index. The records in an index are automatically populated whenever records in the
   1.225 +            <a>referenced</a> object store are inserted, updated or deleted. There can be several <a>index</a>es
   1.226 +            referencing the same <a>object store</a>, in which changes to the object store cause all such indexes
   1.227 +            to get updated.
   1.228            </p>
   1.229            <p>
   1.230 -            If an <a>index</a> is <dfn>auto-populated</dfn>, then the user agent 
   1.231 -            populates records using the values stored in the <a>referenced</a> 
   1.232 -            <a>object store</a>. An <a>auto-populated</a> <a>index</a> MUST have 
   1.233 -            a <dfn title="index key path">key path</dfn>. This <a>key path</a> 
   1.234 -            MUST be the name of an enumerated property of every object to be 
   1.235 -            stored in the <a>object store</a> <a>referenced</a> by that 
   1.236 -            <a>index</a>. The <a>auto-populated</a> <a>index</a> record 
   1.237 -            corresponding to an <a>object store</a> record MUST satisfy the 
   1.238 -            following <dfn>index maintenance conditions</dfn>:
   1.239 +            The values in the index's <a>record</a>s are always values of <a>keys</a> in the index's <a>referenced</a>
   1.240 +            object store. The keys are derived from the referenced object store's <a>value</a>s using a <dfn title="index key path"><a>key path</a></dfn>.
   1.241 +            If a given <a>record</a> with key <var>X</var> in the object store referenced by the index has the value <var>A</var>, and
   1.242 +            <a title="evaluate key path">evaluting</a> the <a title="index key path">index's key path</a> on <var>A</var> yields the result
   1.243 +            <var>Y</var>, then the index will contain a record with key <var>Y</var> and value <var>X</var>.
   1.244            </p>
   1.245 -          <ul>
   1.246 -            <li><a>index</a> record key = value of the enumerated property at 
   1.247 -            the <a title="index key path">key path</a> in the <a>object store</a> 
   1.248 -            record value</li>
   1.249 -            <li><a>index</a> record value = <a>object store</a> record key</li>
   1.250 -          </ul>
   1.251 +          <p>
   1.252 +            Records in an index are said to have a <dfn>referenced value</dfn>. This is the value of the record in the index's referenced
   1.253 +            object store which has a key equal to the index's record's value. So in the example above,
   1.254 +            the record in the index whose key is <var>Y</var> and value is <var>X</var> has a <a>referenced value</a> of <var>A</var>.
   1.255 +          </p>
   1.256 +          <p class="note">
   1.257 +            Each record in an index reference one and only one record in the index's <a>referenced</a> object store. However there can be
   1.258 +            multiple records in an index which reference the same record in the object store. And there can also be no records in an index
   1.259 +            which reference a given record in an object store.
   1.260 +          </p>
   1.261 +          <p class="issue">
   1.262 +            Some of the statements in the note are only true once we've implemented decisions made at TPAC.
   1.263 +          </p>
   1.264 +          <p>
   1.265 +            The <a>record</a>s in an index are always sorted according to the <a>record</a>s key. However unlike object stores,
   1.266 +            a given index can contain multiple records with the same key. Such records are additionally sorted according to
   1.267 +            the records value.
   1.268 +          </p>
   1.269 +          <p>
   1.270 +            A index contains a <dfn>unique</dfn> flag. When this flag is set to true, the index enforces that no two <a>record</a>s
   1.271 +            in the index has the same key. If a <a>record</a> in the index's referenced object store is attempted to be inserted or
   1.272 +            modified such that evaluating the index's key path on the records new value yields a result which already exists in the
   1.273 +            index, then the attempted modification to the object store fails.
   1.274 +          </p>
   1.275            <p>
   1.276              The <a><code>IDBIndex</code></a> and <a><code>IDBIndexSync</code></a> interfaces
   1.277 -            provide access to the metadata of an <a>index</a>.
   1.278 +            provide access to the metadata of an <a>index</a>. Note however that multiple instances of those
   1.279 +            interfaces representing the same <a>index</a> can exist.
   1.280            </p>
   1.281          </section> <!-- IDBIndex -->
   1.282          
   1.283 -       <section id="database-concept" class="section">
   1.284 -          <h4>Database</h4>
   1.285 -          <p>
   1.286 -            Each <a>origin</a> has an associated set of 
   1.287 -            <a title="database">databases</a>. A <dfn>database</dfn> comprises
   1.288 -            one or more <a title="object store">object stores</a>.
   1.289 -          </p>
   1.290 -          <p>
   1.291 -            Every <a>database</a> has a <dfn title="database name">name</dfn> which identifies it
   1.292 -            within a specific <a>origin</a>. The name can be any string value, including the empty string, and
   1.293 -            stays constant for the lifetime of the database. Each <a>database</a> also has a current
   1.294 -            <dfn>version</dfn>.
   1.295 -          </p>
   1.296 -          <p class="note">
   1.297 -            Implementations MUST support all names. If a implementation
   1.298 -            uses a storage mechanism which can't handle arbitrary database names,
   1.299 -            the implementation must use an escaping mechanism or something similar
   1.300 -            to map the provided name to a name that it can handle.
   1.301 -          </p>
   1.302 -          <div class="note">
   1.303 -            Each <a>database</a> has one version at a time; a <a>database</a> 
   1.304 -            can't exist in multiple versions at once. The only way to change the version is using a VERSION_CHANGE
   1.305 -            <a>transaction</a>.
   1.306 -          </div>
   1.307 -          <p>
   1.308 -            Each database contain a set of <a>object store</a>s. The set of <a>object store</a>s
   1.309 -            can changed, but can only be changed using VERSION_CHANGE transactions. When a new database is
   1.310 -            created it doesn't contain any <a>object store</a>s and has the empty string as <a>version</a>.
   1.311 -          </p>
   1.312 -          <p>
   1.313 -            The act of opening a <a>database</a> creates a <dfn>connection</dfn>. There MAY be multiple 
   1.314 -            <a>connection</a>s to a given <a>database</a> at any given time. Each connection has a
   1.315 -            <dfn>closePending</dfn> flag which initially is set to false.
   1.316 -          </p>
   1.317 -          <p>
   1.318 -            When a <a>connection</a> is initially created it is in <var>opened</var> state. The connection
   1.319 -            can be <dfn title="database close">closed</dfn> through several means. If the connection is GCed
   1.320 -            or execution context where the <a>connection</a> is created is destroyed (for example due to the
   1.321 -            user navigating away from that page), the connection is closed. The connection can also be closed
   1.322 -            explicitly using the <a>steps for closing a database connection</a>. When the connection is closed
   1.323 -            the <a>closePending</a> flag is always set to true if it hasn't already been.
   1.324 -          </p>
   1.325 -          <p>
   1.326 -            The <a><code>IDBDatabase</code></a> and <a><code>IDBDatabaseSync</code></a>
   1.327 -            interfaces represent a <a>connection</a> to a <a>database</a>. 
   1.328 -          </p>
   1.329 -        </section>  <!-- IDBDatabase -->
   1.330 -
   1.331          <section id="transaction-concept" class="section">
   1.332            <h4>Transaction</h4>
   1.333            <p>
   1.334 @@ -885,17 +898,49 @@
   1.335              are performed on the underlying <a>index</a> or an 
   1.336              <a>object store</a>.
   1.337            </p>
   1.338 -          
   1.339            <p>
   1.340 -            A <dfn>cursor</dfn> comprises a <dfn>range</dfn> of records in 
   1.341 -            either an <a>index</a> or an <a>object store</a>. A 
   1.342 -            <a title="cursor">cursor</a> maintains a <dfn>position</dfn> over 
   1.343 +            A <dfn>cursor</dfn> comprises a <dfn>range</dfn> of records in either an <a>index</a>
   1.344 +            or an <a>object store</a>. The cursor has a <dfn title="cursor source">source</dfn> indicating
   1.345 +            which index or object store whose records it is iterating. A <a>cursor</a> maintains a <dfn>position</dfn> over 
   1.346              this series, which moves in a <dfn>direction</dfn> that is either 
   1.347 -            monotonically increasing or decreasing order of the record keys. 
   1.348 +            monotonically increasing or decreasing order of the <a>record</a> keys. Cursors
   1.349 +            also have a <dfn title="cursor key">key</dfn> and a <dfn title="cursor value">value</dfn>
   1.350 +            which represent the <a>key</a> and the <a>value</a> of the last iterated <a>record</a>.
   1.351 +            Cursors finally have a <dfn>got value</dfn> flag. When this flag is false, the cursor is either
   1.352 +            in the process of loading the next value or it has reached the end of its <a>range</a>, when it
   1.353 +            is true, it indicates that the cursor is currently holding a value and that it is ready to iterate
   1.354 +            to the next one.
   1.355 +          </p>
   1.356 +          <p>
   1.357 +            If the <a title="cursor source">source</a> of a cursor is a <a>object store</a>, the <dfn>effective object store</dfn>
   1.358 +            of the cursor is that object store and the <dfn>effective key</dfn> of the cursor is the cursors <a>position</a>.
   1.359 +            If the <a title="cursor source">source</a> of a cursor is a <a>index</a>, the <a>effective object store</a>
   1.360 +            of the cursor is that index's <a>referenced</a> object store and the <a>effective key</a> is the cursors
   1.361 +            <a>object store position</a>.
   1.362 +          </p>
   1.363 +          <p>
   1.364 +            It is possible for the list of records which the cursor is iterating over to
   1.365 +            change before the full <a>range</a> of the cursor has been iterated. In order to
   1.366 +            handle this, cursors maintain their <a>position</a> not as an index, but rather
   1.367 +            as a <a>key</a> of the previously returned record. For a forward iterating cursor,
   1.368 +            the next time the cursor is asked to iterate to the next record it returns the
   1.369 +            record with the lowest <a>key</a> <a>greater than</a> the one previously returned. For
   1.370 +            a backwards iterating cursor, the situation is opposite and it returns the record
   1.371 +            with the highest <a>key</a> <a>less than</a> the one previously returned.
   1.372 +          </p>
   1.373 +          <p>
   1.374 +            For cursors iterating indexes the situation is a little bit more complicated since
   1.375 +            multiple records can have the same key and are therefor also sorted by <a>value</a>.
   1.376 +            When iterating indexes the <a>cursor</a>'s also has a <dfn>object store position</dfn>, which indicates
   1.377 +            the <a>value</a> of the previously found <a>record</a> in the index. Both
   1.378 +            <a>position</a> and the <a>object store position</a> is used when finding the next appropriate record.
   1.379            </p>
   1.380            <p>
   1.381              <a title="cursor">Cursor</a> objects implement the <a><code>IDBCursor</code></a> 
   1.382 -            or the <a><code>IDBCursorSync</code></a> interfaces.
   1.383 +            or the <a><code>IDBCursorSync</code></a> interfaces. There is only ever one
   1.384 +            <a><code>IDBCursor</code></a> or <a><code>IDBCursorSync</code></a> instance representing
   1.385 +            a given <a>cursor</a>. However there is no limit on how many cursors can be used at the
   1.386 +            same time.
   1.387            </p>
   1.388          </section> <!-- IDBCursor -->
   1.389  
   1.390 @@ -1370,105 +1415,142 @@
   1.391              </dd>
   1.392              <dt>IDBRequest put()</dt>
   1.393              <dd>
   1.394 -              This method returns immediately and stores the given value in this 
   1.395 -              <a>object store</a> by following the 
   1.396 -              <a>steps for storing a record into an object store</a>. If the 
   1.397 -              <a>record</a> can be successfully stored in the <a>object store</a>, then 
   1.398 -              a <a title="event-success">success event</a> is fired on this 
   1.399 -              method's returned object using the 
   1.400 -              <a><code>IDBTransactionEvent</code></a> interface with its 
   1.401 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to
   1.402 -              the key for the stored <a>record</a> and 
   1.403 -              <a class="idlType" href="#widl-IDBTransactionEvent-transaction"><code>transaction</code></a> 
   1.404 -              set to the <a>transaction</a> in which this <a>object store</a> is 
   1.405 -              opened.
   1.406 +              <p>
   1.407 +                This method throws a NOT_ALLOWED_ERR if the transaction which this IDBObjectStore belongs to is
   1.408 +                has its <a>mode</a> set to READ_ONLY. If any of the following conditions are true, this method
   1.409 +                throws a DATA_ERR exception:
   1.410 +              </p>
   1.411 +              <ul>
   1.412 +                <li>
   1.413 +                  The object store uses <a>in-line keys</a> or has a <a>key generator</a> and
   1.414 +                  the <var>key</var> parameter was provided.
   1.415 +                </li>
   1.416 +                <li>
   1.417 +                  The object store uses <a>out-of-line keys</a> and has no <a>key generator</a>
   1.418 +                  and the <var>key</var> parameter was not provided.
   1.419 +                </li>
   1.420 +                <li>
   1.421 +                  The object store uses <a>in-line keys</a> but no <a>key generator</a>
   1.422 +                  and the result of <a title="evaluate key path">evaluating</a> the 
   1.423 +                  <a title="object store key path">object store's key path</a> does not yield a
   1.424 +                  <a>valid key</a>.
   1.425 +                </li>
   1.426 +                <li>
   1.427 +                  The <var>key</var> parameter was provided but does not contain a <a>valid key</a>.
   1.428 +                </li>
   1.429 +                <li>
   1.430 +                  If there are any <a>index</a>es <a title="referenced">referencing</a> this object
   1.431 +                  store and <a title="evaluate key path">evaluating</a> their key path on the
   1.432 +                  <var>value</var> parameter yields a value and that value is not a <a>valid key</a>.
   1.433 +                </li>
   1.434 +              </ul>
   1.435 +              <p>
   1.436 +                Otherwise this method creates a <a>structured clone</a> of the <var>value</var> parameter.
   1.437 +                If this throws an exception that exception is rethrown. It then runs the <a>steps for
   1.438 +                asynchronously executing a request</a> and returns the <a>IDBRequest</a> created by these steps.
   1.439 +                The steps are run with this <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for
   1.440 +                storing a record into an object store</a> as <var>operation</var>, using this <a>IDBObjectStore</a>
   1.441 +                as <var>store</var>, the created clone as <var>value</var>, the <var>key</var> parameter as
   1.442 +                <var>key</var>, and with the <var>no-overwrite flag</var> flag set to false.
   1.443 +              </p>
   1.444                <dl class="parameters">
   1.445                  <dt>any value</dt>
   1.446                  <dd>The value to be stored in the <a>record</a></dd>
   1.447                  <dt>optional any key</dt>
   1.448 -                <dd>The key used to identify the <a>record</a>, which defaults 
   1.449 -                to <code>null</code></dd>
   1.450 +                <dd>The key used to identify the <a>record</a></dd>
   1.451                </dl>
   1.452                <dl class="exception" title="IDBDatabaseException">
   1.453 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   1.454 +                <dd>The <a>transaction</a> this <a>IDBObjectStore</a> belongs to is not <a>active</a>.</dd>
   1.455                  <dt>NOT_ALLOWED_ERR</dt>
   1.456 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
   1.457 -                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>.</dd>
   1.458 +                <dd>The <a>mode</a> of the associated <a>transaction</a> is <code>READ_ONLY</code>.</dd>
   1.459                  <dt>DATA_ERR</dt>
   1.460 -                <dd>This <a>object store</a> uses <a>out-of-line keys</a> and
   1.461 -                no <a>key generator</a> but the <var>key</var> parameter was not
   1.462 -                passed, or the <a>object store</a> uses <a>in-line keys</a> and
   1.463 -                no <a>key generator</a> but the <var>value</var> object does not
   1.464 -                have a property identified by the store's 
   1.465 -                <a title="object store key path">key path</a>.</dd>
   1.466 -                <dt>SERIAL_ERR</dt>
   1.467 -                <dd>The data being stored could not be serialized by the internal
   1.468 +                <dd>The calculated key for the insertion was not a <a>valid key</a>. Also thrown if the
   1.469 +                calculated key for any of the indexes which belong to this object store had a calculated
   1.470 +                key which was not a <a>valid key</a></dd>
   1.471 +              </dl>
   1.472 +              <dl class="exception" title="DOMException">
   1.473 +                <dt>DATA_CLONE_ERR</dt>
   1.474 +                <dd>The data being stored could not be cloned by the internal
   1.475                  structured cloning algorithm.</dd>
   1.476                </dl>
   1.477              </dd>
   1.478              <dt>IDBRequest add()</dt>
   1.479              <dd>
   1.480 -              This method returns immediately and stores the given value in this 
   1.481 -              <a>object store</a> by following the 
   1.482 -              <a>steps for storing a record into an object store</a> with the 
   1.483 -              no-overwrite flag set. If the <a>record</a> can be successfully 
   1.484 -              stored in the <a>object store</a>, then a 
   1.485 -              <a title="event-success">success event</a> is fired on this 
   1.486 -              method's returned object using the 
   1.487 -              <a><code>IDBTransactionEvent</code></a> interface with its 
   1.488 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to
   1.489 -              the key for the stored record and 
   1.490 -              <a class="idlType" href="#widl-IDBTransactionEvent-transaction"><code>transaction</code></a> 
   1.491 -              set to the <a>transaction</a> in which this <a>object store</a> is 
   1.492 -              opened. If a <a>record</a> exists in this <a>object store</a> for 
   1.493 -              the key <var>key</var> parameter, then an
   1.494 -              <a title="event-error">error event</a> is fired on this method's
   1.495 -              returned object with its 
   1.496 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   1.497 -              <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>
   1.498 +              <p>
   1.499 +                This method throws a NOT_ALLOWED_ERR if the transaction which this IDBObjectStore belongs to is
   1.500 +                has its <a>mode</a> set to READ_ONLY. If any of the following conditions are true, this method
   1.501 +                throws a DATA_ERR exception:
   1.502 +              </p>
   1.503 +              <ul>
   1.504 +                <li>
   1.505 +                  The object store uses <a>in-line keys</a> or has a <a>key generator</a> and
   1.506 +                  the <var>key</var> parameter was provided.
   1.507 +                </li>
   1.508 +                <li>
   1.509 +                  The object store uses <a>out-of-line keys</a> and has no <a>key generator</a>
   1.510 +                  and the <var>key</var> parameter was not provided.
   1.511 +                </li>
   1.512 +                <li>
   1.513 +                  The object store uses <a>in-line keys</a> but no <a>key generator</a>
   1.514 +                  and the result of <a title="evaluate key path">evaluating</a> the 
   1.515 +                  <a title="object store key path">object store's key path</a> does not yield a
   1.516 +                  <a>valid key</a>.
   1.517 +                </li>
   1.518 +                <li>
   1.519 +                  The <var>key parameter was provided but does not contain a <a>valid key</a>.
   1.520 +                </li>
   1.521 +                <li>
   1.522 +                  If there are any <a>index</a>es <a title="referenced">referencing</a> this object
   1.523 +                  store and <a title="evaluate key path">evaluating</a> their key path on the
   1.524 +                  <var>value</var> parameter yields a value and that value is not a <a>valid key</a>.
   1.525 +                </li>
   1.526 +              </ul>
   1.527 +              <p>
   1.528 +                Otherwise this method creates a <a>structured clone</a> of the <var>value</var> parameter.
   1.529 +                If this throws an exception that exception is rethrown. It then runs the <a>steps for
   1.530 +                asynchronously executing a request</a> and returns the <a>IDBRequest</a> created by these steps.
   1.531 +                The steps are run with this <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for
   1.532 +                storing a record into an object store</a> as <var>operation</var>, using this <a>IDBObjectStore</a>
   1.533 +                as <var>store</var>, the created clone as <var>value</var>, the <var>key</var> parameter as
   1.534 +                <var>key</var>, and with the <var>no-overwrite flag</var> flag set to true.
   1.535 +              </p>
   1.536                <dl class="parameters">
   1.537                  <dt>any value</dt>
   1.538                  <dd>The value to be stored in the <a>record</a></dd>
   1.539                  <dt>optional any key</dt>
   1.540 -                <dd>The key used to identify the <a>record</a>, which defaults 
   1.541 -                to <code>null</code></dd>
   1.542 +                <dd>The key used to identify the <a>record</a></dd>
   1.543                </dl>
   1.544                <dl class="exception" title="IDBDatabaseException">
   1.545 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   1.546 +                <dd>The <a>transaction</a> this <a>IDBObjectStore</a> belongs to is not <a>active</a>.</dd>
   1.547                  <dt>NOT_ALLOWED_ERR</dt>
   1.548 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
   1.549 -                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>.</dd>
   1.550 +                <dd>The <a>mode</a> of the associated <a>transaction</a> is <code>READ_ONLY</code>.</dd>
   1.551                  <dt>DATA_ERR</dt>
   1.552 -                <dd>This <a>object store</a> uses <a>out-of-line keys</a> and
   1.553 -                no <a>key generator</a> but the <var>key</var> parameter was not
   1.554 -                passed, or the <a>object store</a> uses <a>in-line keys</a> and
   1.555 -                no <a>key generator</a> but the <var>value</var> object does not
   1.556 -                have a property identified by the store's
   1.557 -                <a title="object store key path">key path</a>.</dd>
   1.558 -                <dt>SERIAL_ERR</dt>
   1.559 -                <dd>The data being stored could not be serialized by the internal
   1.560 +                <dd>The calculated key for the insertion was not a <a>valid key</a>. Also thrown if the
   1.561 +                calculated key for any of the indexes which belong to this object store had a calculated
   1.562 +                key which was not a <a>valid key</a></dd>
   1.563 +              </dl>
   1.564 +              <dl class="exception" title="DOMException">
   1.565 +                <dt>DATA_CLONE_ERR</dt>
   1.566 +                <dd>The data being stored could not be cloned by the internal
   1.567                  structured cloning algorithm.</dd>
   1.568                </dl>
   1.569              </dd>
   1.570              <dt>IDBRequest delete()</dt>
   1.571              <dd>
   1.572 -              This method returns immediately and deletes the <a>record</a> from 
   1.573 -              this <a>object store</a> by following the 
   1.574 -              <a>steps for deleting a record from an object store</a> 
   1.575 -              corresponding to the given key. If a <a>record</a> did not exist 
   1.576 -              in this <a>object store</a> for the <var>key</var> parameter, 
   1.577 -              then an <a title="event-error">error event</a> is fired on this 
   1.578 -              method's returned object with its 
   1.579 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   1.580 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
   1.581 -              and a suitable 
   1.582 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>. If the <a>record</a> can be successfully 
   1.583 -              deleted from the <a>object store</a>, then a 
   1.584 -              <a title="event-success">success event</a> is fired on this 
   1.585 -              method's returned object using the 
   1.586 -              <a><code>IDBTransactionEvent</code></a> interface with its 
   1.587 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to
   1.588 -              the value of the deleted <a>record</a> and <a class="idlType" href="#widl-IDBTransactionEvent-transaction"><code>transaction</code></a> 
   1.589 -              set to the <a>transaction</a> in which this <a>object store</a> is 
   1.590 -              opened. 
   1.591 +              <p>
   1.592 +                This method throws a NOT_ALLOWED_ERR if the transaction which this IDBObjectStore belongs to is
   1.593 +                has its <a>mode</a> set to READ_ONLY. If the <var>key</var> parameter is not a <a>valid key</var>
   1.594 +                this method throws a DATA_ERR exception.
   1.595 +              </p>
   1.596 +              <p>
   1.597 +                Otherwise this method runs the <a>steps for
   1.598 +                asynchronously executing a request</a> and returns the <a>IDBRequest</a> created by these steps.
   1.599 +                The steps are run with this <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for deleting
   1.600 +                a record from an object store</a> as <var>operation</var>, using this <a>IDBObjectStore</a>
   1.601 +                as <var>store</var> and the <var>key</var> parameter as <var>key</var>.
   1.602 +              </p>
   1.603                <dl class="parameters">
   1.604                  <dt>any key</dt>
   1.605                  <dd>Key identifying the <a>record</a> to be deleted</dd>
   1.606 @@ -1484,7 +1566,7 @@
   1.607                If the <var>key</var> parameter is not a valid <a>key value</a> or a <a>key range</a>, this method
   1.608                throws a DATA_ERR exception. Otherwise, this method runs the <a>steps for asynchronously executing
   1.609                a request</a> and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   1.610 -              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a record from an
   1.611 +              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a value from an
   1.612                object store</a> as <var>operation</var>, using this <a>IDBObjectStore</a> as <var>store</var> and the
   1.613                <var>key</var> parameter as <var>key</var>.
   1.614                <dl class="parameters">
   1.615 @@ -1502,27 +1584,24 @@
   1.616              <dt>IDBRequest openCursor()</dt>
   1.617              <dd>
   1.618                <p>
   1.619 -                This method returns immediately and creates a <a>cursor</a> over the 
   1.620 -                <a>records</a> of this <a>object store</a>.
   1.621 +                If the <var>range</var> parameter is specified but is not a valid <a>key value</a> or a <a>key range</a>,
   1.622 +                this method throws a DATA_ERR exception. Otherwise, this method creates a <a>cursor</a> with an undefined
   1.623 +                <a>position</a>, a <a>direction</a> set to the value of the <var>direction</var> parameter, false as
   1.624 +                <a>iterable</a> flag value, and undefined <a title="cursor key">key</a> and
   1.625 +                <a title="cursor value">value</a>. The <a title="cursor source">source</a> of the cursor is the
   1.626 +                <a>IDBObjectStore</a> this function was called on.
   1.627                </p>
   1.628                <p>
   1.629 -                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
   1.630 -                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
   1.631 -                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
   1.632 -                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
   1.633 -                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
   1.634 +                If the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a> is set to that
   1.635 +                range. Otherwise, if the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a>
   1.636 +                is set to <a>key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
   1.637 +                the cursor's key range is left as undefined.
   1.638                </p>
   1.639                <p>
   1.640 -                If there is even a single record that matches the <a>key range</a>, then a
   1.641 -                <a title="event-success">success event</a> is fired on this method's
   1.642 -                returned object with its 
   1.643 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   1.644 -                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   1.645 -                records match the <a>key range</a>, then an 
   1.646 -                <a title="event-success">success event</a> is fired on this method's
   1.647 -                returned object with its
   1.648 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   1.649 -                set to <code>null</code>.
   1.650 +                This method runs the <a>steps for asynchronously executing a request</a> and returns the <a>IDBRequest</a>
   1.651 +                created by these steps. The steps are run with this <a>IDBObjectStore</a> as <var>source</var> and the
   1.652 +                <a>steps for iterating a cursor</a> as <var>operation</var>,
   1.653 +                using the created cursor as <var>cursor</var> and with undefined as <var>key</var>.
   1.654                </p>
   1.655                <dl class="parameters">
   1.656                  <dt>optional any            range</dt>
   1.657 @@ -1640,28 +1719,24 @@
   1.658              <dt>IDBRequest openCursor()</dt>
   1.659              <dd>
   1.660                <p>
   1.661 -                This method returns immediately and creates a <a>cursor</a> over the 
   1.662 -                <a>records</a> of this <a>index</a>'s <a>referenced</a> <a>object store</a> 
   1.663 -                as arranged by this <a>index</a>.
   1.664 +                If the <var>range</var> parameter is specified but is not a valid <a>key value</a> or a <a>key range</a>,
   1.665 +                this method throws a DATA_ERR exception. Otherwise, this method creates a <a>cursor</a> with an undefined
   1.666 +                <a>position</a>, a <a>direction</a> set to the value of the <var>direction</var> parameter, false as
   1.667 +                <a>iterable</a> flag value, and undefined <a title="cursor key">key</a> and
   1.668 +                <a title="cursor value">value</a>. The <a title="cursor source">source</a> of the cursor is the
   1.669 +                <a>IDBIndex</a> this function was called on.
   1.670                </p>
   1.671                <p>
   1.672 -                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
   1.673 -                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
   1.674 -                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
   1.675 -                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
   1.676 -                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
   1.677 +                If the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a> is set to that
   1.678 +                range. Otherwise, if the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a>
   1.679 +                is set to <a>key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
   1.680 +                the cursor's key range is left as undefined.
   1.681                </p>
   1.682                <p>
   1.683 -                If there is even a single record that matches the <a>key range</a>, then a
   1.684 -                <a title="event-success">success event</a> is fired on this method's
   1.685 -                returned object with its 
   1.686 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   1.687 -                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   1.688 -                records match the <a>key range</a>, then an 
   1.689 -                <a title="event-success">success event</a> is fired on this method's
   1.690 -                returned object with its
   1.691 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   1.692 -                set to <code>null</code>.
   1.693 +                This method runs the <a>steps for asynchronously executing
   1.694 +                a request</a> and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   1.695 +                <a>IDBIndex</a> as <var>source</var> and the <a>steps for iterating a cursor</a> as <var>operation</var>,
   1.696 +                using the created cursor as <var>cursor</var> and with undefined as <var>key</var>
   1.697                </p>
   1.698                <dl class="parameters">
   1.699                  <dt>optional IDBKeyRange    range</dt>
   1.700 @@ -1679,27 +1754,24 @@
   1.701              <dt>IDBRequest openKeyCursor()</dt>
   1.702              <dd>
   1.703                <p>
   1.704 -                This method returns immediately and creates a <a>cursor</a> over the 
   1.705 -                <a>records</a> of this <a>index</a>.
   1.706 +                If the <var>range</var> parameter is specified but is not a valid <a>key value</a> or a <a>key range</a>,
   1.707 +                this method throws a DATA_ERR exception. Otherwise, this method creates a <a>cursor</a> with an undefined
   1.708 +                <a>position</a>, a <a>direction</a> set to the value of the <var>direction</var> parameter, false as
   1.709 +                <a>iterable</a> flag value, and undefined <a title="cursor key">key</a> and
   1.710 +                <a title="cursor value">value</a>. The <a title="cursor source">source</a> of the cursor is the
   1.711 +                <a>IDBIndex</a> this function was called on.
   1.712                </p>
   1.713                <p>
   1.714 -                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
   1.715 -                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
   1.716 -                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
   1.717 -                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
   1.718 -                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
   1.719 +                If the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a> is set to that
   1.720 +                range. Otherwise, if the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a>
   1.721 +                is set to <a>key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
   1.722 +                the cursor's key range is left as undefined.
   1.723                </p>
   1.724                <p>
   1.725 -                If there is even a single record that matches the <a>key range</a>, then a
   1.726 -                <a title="event-success">success event</a> is fired on this method's
   1.727 -                returned object with its 
   1.728 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   1.729 -                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   1.730 -                records match the <a>key range</a>, then an 
   1.731 -                <a title="event-success">success event</a> is fired on this method's
   1.732 -                returned object with its
   1.733 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   1.734 -                set to <code>null</code>.
   1.735 +                This method runs the <a>steps for asynchronously executing
   1.736 +                a request</a> and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   1.737 +                <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for iterating a cursor</a> as <var>operation</var>,
   1.738 +                using the created cursor as <var>cursor</var> and with undefined as <var>key</var>
   1.739                </p>
   1.740                <dl class="parameters">
   1.741                  <dt>optional IDBKeyRange    range</dt>
   1.742 @@ -1719,7 +1791,7 @@
   1.743                If the <var>key</var> parameter is not a valid <a>key value</a> or a <a>key range</a>, this method
   1.744                throws a DATA_ERR exception. This method runs the <a>steps for asynchronously executing a request</a>
   1.745                and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   1.746 -              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a record from an
   1.747 +              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a referenced value from an
   1.748                index</a> as <var>operation</var>, using this <a>IDBIndex</a> as <var>index</var> and the
   1.749                <var>key</var> parameter as <var>key</var>.
   1.750                <dl class="parameters">
   1.751 @@ -1798,65 +1870,107 @@
   1.752              <dd>The key for the record at the <a>cursor</a>'s <a>position</a>.</dd>
   1.753              <dt>readonly attribute any value</dt>
   1.754              <dd>The value for the record at the <a>cursor</a>'s <a>position</a>.</dd>
   1.755 -            <dt>readonly attribute unsigned long long count</dt>
   1.756 -            <dd>             
   1.757 -              On getting, provide the approximate number of objects in the cursor.
   1.758 -            </dd>
   1.759 +
   1.760              <dt>IDBRequest update(in any value)</dt>
   1.761              <dd>
   1.762 -              This method returns immediately and sets the value for the record at the
   1.763 -              <a>cursor</a>'s <a>position</a>.
   1.764 +              <p>
   1.765 +                This method throws a NOT_ALLOWED_ERR if the transaction which this IDBCursor belongs to
   1.766 +                has its <a>mode</a> set to READ_ONLY, or if this cursor's <a>got value</a> flag is false. If the
   1.767 +                <a>effective object store</a> of this cursor uses <a>in-line</a>
   1.768 +                keys and <a title="evaluate key path">evaluating</a> the <a title="object store key path">key path</a>
   1.769 +                of the <var>value</var> parameter results in a different value than the cursor's <a>effective key</a>,
   1.770 +                this method throws DATA_ERR.
   1.771 +              </p>
   1.772 +              <p>
   1.773 +                Otherwise this method creates a <a>structured clone</a> of the <var>value</var> parameter.
   1.774 +                If this throws an exception that exception is rethrown. It then runs the <a>steps for
   1.775 +                asynchronously executing a request</a> and returns the <a>IDBRequest</a> created by these steps.
   1.776 +                The steps are run with this IDBCursor as <var>source</var> and the <a>steps for
   1.777 +                storing a record into an object store</a> as <var>operation</var>, using this cursor's
   1.778 +                <a>effective object store</a> as <var>store</var>, the created clone as <var>value</var>,
   1.779 +                this cursor's <a>effective key</a> as <var>key</var>, and with the <var>no-overwrite flag</var>
   1.780 +                flag set to false.
   1.781 +              </p>
   1.782 +              <p class="issue">
   1.783 +                Should this fire an error if the record had been deleted since we iterated to it? I.e. should
   1.784 +                this never be able to create a new record?
   1.785 +              </p>
   1.786 +              <p>
   1.787 +                Otherwise this method runs the <a>steps for asynchronously executing a request</a> and returns the
   1.788 +                <a>IDBRequest</a> created by these steps. The steps are run with this <a>IDBCursor</a> as <var>source</var>
   1.789 +                and the <a>steps for deleting a record from an object store</a> as <var>operation</var>, using this cursor's
   1.790 +                <a>effective object store</a> and <a>effective key</a> as <var>store</var> and <var>key</var> respectively.
   1.791 +              </p>
   1.792                <dl class="exception" title="IDBDatabaseException">
   1.793 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   1.794 +                <dd>The <a>transaction</a> this <a>IDBCursor</a> belongs to is not <a>active</a>.</dd>
   1.795                  <dt>NOT_ALLOWED_ERR</dt>
   1.796                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
   1.797                  the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>. Also
   1.798                  thrown if cursor was created using
   1.799                  <a class="idlType" href="#widl-IDBIndex-openKeyCursor"><code>openKeyCursor</code></a>.</dd>
   1.800                  <dt>DATA_ERR</dt>
   1.801 -                <dd> The underlying <a>object store</a> uses <a>in-line keys</a> and the property at the 
   1.802 -                <a title="object store key path">key path</a> does not match the key in this <a>cursor</a>'s
   1.803 +                <dd> The underlying <a>object store</a> uses <a>in-line keys</a> and the property in <var>value</var>
   1.804 +                at the object store's <a title="object store key path">key path</a> does not match the key in this <a>cursor</a>'s
   1.805                  <a>position</a>.</dd>
   1.806 -                <dt>SERIAL_ERR</dt>
   1.807 -                <dd>The data being stored could not be serialized by the internal structured cloning
   1.808 -                algorithm.</dd>
   1.809 +              </dl>
   1.810 +              <dl class="exception" title="DOMException">
   1.811 +                <dt>DATA_CLONE_ERR</dt>
   1.812 +                <dd>The data being stored could not be cloned by the internal
   1.813 +                structured cloning algorithm.</dd>
   1.814                </dl>
   1.815              </dd>
   1.816              <dt>void    continue()</dt>
   1.817              <dd>
   1.818 -              This method returns immediately and advances the <a>cursor</a> to the next
   1.819 -              position along its <a>direction</a> to the item whose key matches the
   1.820 -              optional parameter. If no such parameter is provided, advance to the
   1.821 -              immediate next position. If the <a>cursor</a> has reached the end of its
   1.822 -              <a>range</a>, then a
   1.823 -              <a title="event-success">success event</a> is fired on the
   1.824 -              <a><code>IDBRequest</code></a> object that was returned when the cursor
   1.825 -              was opened, with its
   1.826 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   1.827 -              set to <code>null</code>. Otherwise, a
   1.828 -              <a title="event-success">success event</a> is fired on the
   1.829 -              <a><code>IDBRequest</code></a> object that was returned when the cursor
   1.830 -              was opened, with its
   1.831 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   1.832 -              set to the corresponding <a><code>IDBCursor</code></a> object.
   1.833 +              <p>
   1.834 +                If the <var>key</var> parameter is specified but is not a <a>valid key</a>,
   1.835 +                this method throws a DATA_ERR exception. If this cursor's <a>got value</a> flag is false, this method
   1.836 +                throws a NOT_ALLOWED_ERR. Otherwise this method runs the <a>steps for asynchronously executing a request</a>.
   1.837 +                However, the steps are slightly modified such that instead of creating a new IDBRequest, it reuses the
   1.838 +                <a>request</a> originally created when this cursor was created. The <a title="request done">done</a> flag
   1.839 +                on the request is set to false before the request is returned.  The steps are run with the cursor's
   1.840 +                <a title="cursor source">source</a> as <var>source</var> and the <a>steps for iterating a cursor</a> as <var>operation</var>,
   1.841 +                using the created cursor as <var>cursor</var> and the <var>key</var> parameter as <var>key</var>.
   1.842 +              </p>
   1.843 +              <p>
   1.844 +                Before this method returns, unless an exception was thrown, it sets the <a>got value</a> flag fn the cursor to false.
   1.845 +              </p>
   1.846                <dl class="parameters">
   1.847                  <dt>optional any key</dt>
   1.848                  <dd>The next key to position this <a>cursor</a> at</dd>
   1.849                </dl>
   1.850 +              <dl class="exception" title="IDBDatabaseException">
   1.851 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   1.852 +                <dd>The <a>transaction</a> this <a>IDBCursor</a> belongs to is not <a>active</a>.</dd>
   1.853 +                <dt>NOT_ALLOWED_ERR</dt>
   1.854 +                <dd>This <a>got value</a> on the cursor is set to false.</dd>
   1.855 +                <dt>DATA_ERR</dt>
   1.856 +                <dd>The <var>key</var> parameter was specified but did not contain a <a>valid key</a>.</dd>
   1.857 +              </dl>
   1.858              </dd>
   1.859              
   1.860              <dt>IDBRequest    delete()</dt>
   1.861              <dd>          
   1.862                <p>
   1.863 -                This method returns immediately and deletes the object at the 
   1.864 -                <a>cursor</a>'s <a>position</a>. The cursor's
   1.865 -                position is not changed. Any attempts to retrieve the cursor's
   1.866 -                current value will return <code>null</code>.
   1.867 +                This method throws a NOT_ALLOWED_ERR if the transaction which this IDBCursor belongs to
   1.868 +                has its <a>mode</a> set to READ_ONLY, or if this cursor's <a>got value</a> flag is false.
   1.869 +              </p>
   1.870 +              <p>
   1.871 +                Otherwise this method runs the <a>steps for asynchronously executing a request</a> and returns the
   1.872 +                <a>IDBRequest</a> created by these steps. The steps are run with this <a>IDBCursor</a> as <var>source</var>
   1.873 +                and the <a>steps for deleting a record from an object store</a> as <var>operation</var>, using this cursor's
   1.874 +                <a>effective object store</a> and <a>effective key</a> as <var>store</var> and <var>key</var> respectively.
   1.875 +              </p>
   1.876 +              <p class="issue">
   1.877 +                This method used to set this cursor's <a title="cursor value">value</a> to <code>null</code>. Do we want to
   1.878 +                keep that?
   1.879                </p>
   1.880                <dl class="exception" title="IDBDatabaseException">
   1.881 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   1.882 +                <dd>The <a>transaction</a> this <a>IDBCursor</a> belongs to is not <a>active</a>.</dd>
   1.883                  <dt>NOT_ALLOWED_ERR</dt>
   1.884 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
   1.885 -                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>. Also
   1.886 -                thrown if cursor was created using
   1.887 +                <dd>The <a>mode</a> of the <a>transaction</a> this <a>IDBCursor</a> belongs to is not <a>active</a>
   1.888 +                is <code>READ_ONLY</code>. Also thrown if cursor was created using
   1.889                  <a class="idlType" href="#widl-IDBIndex-openKeyCursor"><code>openKeyCursor</code></a>.</dd>
   1.890                </dl>
   1.891              </dd>
   1.892 @@ -2326,7 +2440,7 @@
   1.893              <dd>
   1.894                Retrieve the value from this <a>object store</a> for the record 
   1.895                corresponding to the given key by following the
   1.896 -              <a>steps for retrieving a record from an object store</a>. The
   1.897 +              <a>steps for retrieving a value from an object store</a>. The
   1.898                value returned from this method is the retrieved value.
   1.899                <dl class="parameters">
   1.900                  <dt>any key</dt>
   1.901 @@ -2538,7 +2652,7 @@
   1.902              <dd>
   1.903                Retrieve the value from this <a>index</a>'s <a>referenced</a>
   1.904                <a>object store</a> for the record corresponding to the given key
   1.905 -              by following the <a>steps for retrieving a record from an index</a>.
   1.906 +              by following the <a>steps for retrieving a referenced value from an index</a>.
   1.907                The value returned from this method is the retrieved value.
   1.908                <dl class="parameters">
   1.909                  <dt>any key</dt>
   1.910 @@ -2687,10 +2801,6 @@
   1.911                  <a>index</a> is <a>auto-populated</a>.</dd>
   1.912                </dl>
   1.913              </dd>
   1.914 -            <dt>readonly attribute unsigned long long count</dt>
   1.915 -            <dd>             
   1.916 -              On getting, provide the approximate number of objects in the cursor.
   1.917 -            </dd>
   1.918  
   1.919              <dt>boolean  continue()</dt>
   1.920              <dd>
   1.921 @@ -2818,7 +2928,8 @@
   1.922              </li>
   1.923              <li>
   1.924                If no database with the given name from the origin <var>origin</var>
   1.925 -              exists, then create the database <var>db</var> with name <var>name</var>.
   1.926 +              exists, then create the database <var>db</var> with name <var>name</var>, with the empty
   1.927 +              string as <a>version</a>, and with no <a>object store</a>s.
   1.928              </li>
   1.929              <li>
   1.930                Wait until no already existing <a>connection</a>s to <var>db</var>, have
   1.931 @@ -2833,218 +2944,10 @@
   1.932              <li>
   1.933                Create a <a>connection</a> to <var>db</var> and return it.
   1.934              </li>
   1.935 -          </ol>        
   1.936 -        </section>
   1.937 -        
   1.938 -        <section class="section">
   1.939 -          <h4>Object Store Storage steps</h4>
   1.940 -          <p>
   1.941 -            The <dfn>steps for storing a record into an object store</dfn> are as follows. 
   1.942 -            These steps MUST be run with four parameters: the <a>object store</a>,
   1.943 -            a value, an optional key, and an optional no-overwrite flag.
   1.944 -          </p>
   1.945 -          <ol>
   1.946 -            <li>
   1.947 -              Let <var>store</var> be the <a>object store</a>, <var>key</var> be
   1.948 -              the key and <var>value</var> be the value passed to these steps.
   1.949 -            </li>
   1.950 -            <li>
   1.951 -              If <var>store</var> uses <a>out-of-line keys</a> but no <a>key 
   1.952 -              generator</a>, then a key MUST be passed to these steps. If not, 
   1.953 -              terminate these steps and set error code <a class="idlType" href="#widl-IDBDatabaseException-DATA_ERR"><code>DATA_ERR</code></a>.
   1.954 -            </li>
   1.955 -            <li>
   1.956 -              If <var>store</var> uses <a>in-line keys</a>, then 
   1.957 -              let <var>key</var> be the property of <var>object</var> at  
   1.958 -              <var>store</var>'s <a title="object store key path">key path</a>.
   1.959 -            </li>
   1.960 -           <li>
   1.961 -              Produce a <a>structured clone</a> of <var>value</var> and call it
   1.962 -              <var>object</var>.
   1.963 -            </li>
   1.964 -            <li>
   1.965 -              If <var>key</var> is not defined or null, then perform the 
   1.966 -              following steps.
   1.967 -              <ol>
   1.968 -                <li>
   1.969 -                  If <var>store</var> does not have a <a>key generator</a>, then 
   1.970 -                  terminate these steps and set error code <a class="idlType" href="#widl-IDBDatabaseException-NOT_ALLOWED_ERR"><code>NOT_ALLOWED_ERR</code></a>.
   1.971 -                </li>
   1.972 -                <li>
   1.973 -                  Using <var>store</var>'s <a>key generator</a>, produce the 
   1.974 -                  next key and store it as <var>key</var>.
   1.975 -                </li>
   1.976 -                <li>
   1.977 -                  If <var>store</var> uses <a>in-line keys</a>, then store 
   1.978 -                  <var>key</var> as the property value for <var>object</var> at  
   1.979 -                  <var>store</var>'s <a title="object store key path">key path</a>.
   1.980 -                </li>
   1.981 -              </ol>
   1.982 -            </li>
   1.983 -            <li>
   1.984 -              If the no-overwrite flag was passed to these steps and is set, and 
   1.985 -              a record already exists with its key being <var>key</var>, then 
   1.986 -              terminate these steps and set error code <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>.
   1.987 -            </li>
   1.988 -            <li>
   1.989 -              <p>
   1.990 -                Store a record in <var>store</var> containing <var>key</var> as its key  
   1.991 -                and <var>object</var> as its value. If any <a title="index">indexes</a>  
   1.992 -                are <a>auto-populated</a> for <var>store</var>, then store a record
   1.993 -                in that index according to <a>index maintenance conditions</a>.
   1.994 -              </p>
   1.995 -              <div class="note">
   1.996 -                Storing would mean inserting if no record exists for that key
   1.997 -                or updating an existing record, otherwise. <a title="auto-populated">
   1.998 -                Auto populated</a> <a>index</a> record will also be respectively
   1.999 -                inserted or updated depending on what storing results in.
  1.1000 -              </div>
  1.1001 -            </li>
  1.1002 -            
  1.1003 -            <li>
  1.1004 -              Return the <var>key</var>.
  1.1005 -            </li>
  1.1006            </ol>
  1.1007          </section>
  1.1008          
  1.1009          <section class="section">
  1.1010 -          <h4>Object Store Retrieval steps</h4>
  1.1011 -          <p>
  1.1012 -            The <dfn>steps for retrieving a record from an object store</dfn> are
  1.1013 -            as follows. These steps MUST be run with two parameters - the record 
  1.1014 -            key and the <a>object store</a>.
  1.1015 -          </p>
  1.1016 -            
  1.1017 -          <ol>
  1.1018 -            <li>
  1.1019 -              Let <var>key</var> be the key and <var>store</var> be the <a>object
  1.1020 -              store</a> passed to these steps.
  1.1021 -            </li>
  1.1022 -            <li>
  1.1023 -              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
  1.1024 -              with key <var>key</var> from <var>store</var>. If <var>key</var> is a <a>key range</a>, then
  1.1025 -              retreive the first <a>record</a> from <var>store</var> whose key is <a title="in a key range">in</a> <var>key</var>.
  1.1026 -            </li>
  1.1027 -            <li>
  1.1028 -              If no record was found in the previous step,
  1.1029 -              then terminate these steps and set error code
  1.1030 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
  1.1031 -            </li>
  1.1032 -            <li>
  1.1033 -              Return the a new <a>structured clone</a> of the value in the found record.
  1.1034 -            </li>
  1.1035 -          </ol>
  1.1036 -        </section>
  1.1037 -        
  1.1038 -        <section class="section">
  1.1039 -          <h4>Index Referenced Value Retrieval steps</h4>
  1.1040 -          <p>
  1.1041 -            The <dfn>steps for retrieving a record from an index</dfn> are
  1.1042 -            as follows. These steps MUST be run with two parameters - the record 
  1.1043 -            key and the <a>index</a>.
  1.1044 -          </p>
  1.1045 -            
  1.1046 -          <ol>
  1.1047 -            <li>
  1.1048 -              Let <var>key</var> be the key and <var>index</var> be the <a>index</a>
  1.1049 -              passed to these steps.
  1.1050 -            </li>
  1.1051 -            <li>
  1.1052 -              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
  1.1053 -              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
  1.1054 -              retreive the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
  1.1055 -            </li>
  1.1056 -            <li>
  1.1057 -              If no record was found in the previous step, then the algorithm failed with a
  1.1058 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
  1.1059 -            </li>
  1.1060 -            <li>
  1.1061 -              If a record was found, let <var>value</var> be the value of the found record. The result of
  1.1062 -              this algorithm is a new <a>structured clone</a> of the value for the record with key
  1.1063 -              <var>value</val> in <var>index</var>'s <a>referenced</a> <a>object store</a>
  1.1064 -            </li>
  1.1065 -          </ol>
  1.1066 -        </section>
  1.1067 -        
  1.1068 -        <Section class="section">
  1.1069 -          <h4>Index Value Retrieval steps</h4>
  1.1070 -          <p>
  1.1071 -            The <dfn>steps for retrieving a value from an index</dfn> are
  1.1072 -            as follows. These steps MUST be run with two parameters - the record 
  1.1073 -            key and the <a>index</a>.
  1.1074 -          </p>
  1.1075 -            
  1.1076 -          <ol>
  1.1077 -            <li>
  1.1078 -              Let <var>key</var> be the key and <var>index</var> be the <a>index</a>
  1.1079 -              passed to these steps.
  1.1080 -            </li>
  1.1081 -            <li>
  1.1082 -              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
  1.1083 -              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
  1.1084 -              retreive the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
  1.1085 -            </li>
  1.1086 -            <li>
  1.1087 -              If no record was found in the previous step, then the algorithm failed with a
  1.1088 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
  1.1089 -            </li>
  1.1090 -            <li>
  1.1091 -              If a record was found, the result of this algorithm is the value of the found <a>record</a>.
  1.1092 -            </li>
  1.1093 -          </ol>
  1.1094 -        </section>
  1.1095 -        
  1.1096 -        <section class="section">
  1.1097 -          <h4>Object Store Deletion steps</h4>
  1.1098 -          <p>
  1.1099 -            The <dfn>steps for deleting a record from an object store</dfn> 
  1.1100 -            are as follows. These steps MUST be run with two parameters: the key
  1.1101 -            of the record to be deleted and the <a>object store</a>.
  1.1102 -          </p>
  1.1103 -          <ol>
  1.1104 -            <li>
  1.1105 -              Let <var>key</var> be the key and <var>store</var> be the <a>object
  1.1106 -              store</a> passed to these steps.
  1.1107 -            </li>
  1.1108 -            <li>
  1.1109 -              If no record exists with key <var>key</var> in <var>store</var>,
  1.1110 -              then terminate these steps and set error code
  1.1111 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
  1.1112 -            </li>            
  1.1113 -            <li>
  1.1114 -               If any <a title="index">indexes</a> are <a>auto-populated</a> for
  1.1115 -               <var>store</var>, then remove the record in that index according 
  1.1116 -               to <a>index maintenance conditions</a>.
  1.1117 -            </li>
  1.1118 -            
  1.1119 -            <li>
  1.1120 -              Remove the record from <var>store</var> with key <var>key</var>. 
  1.1121 -            </li>
  1.1122 -          </ol>
  1.1123 -        </section>
  1.1124 -        <section class="section">
  1.1125 -          <h4>Index Deletion steps</h4>
  1.1126 -          <p>
  1.1127 -            The <dfn>steps for deleting a record from an index</dfn> 
  1.1128 -            are as follows. These steps MUST be run with two parameters: the key
  1.1129 -            of the record to be deleted and the <a>index</a>.
  1.1130 -          </p>
  1.1131 -          <ol>
  1.1132 -            <li>
  1.1133 -              Let <var>key</var> be the key and <var>index</var> be the <a>index</a>
  1.1134 -              passed to these steps.
  1.1135 -            </li>
  1.1136 -            <li>
  1.1137 -              If no record exists with key <var>key</var> in <var>index</var>,
  1.1138 -              then terminate these steps and set error code
  1.1139 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
  1.1140 -            </li>            
  1.1141 -            <li>
  1.1142 -              Remove the records from <var>index</var> with key <var>key</var>. 
  1.1143 -            </li>
  1.1144 -          </ol>
  1.1145 -        </section>
  1.1146 -        <section class="section">
  1.1147            <h4>Transaction Creation steps</h4>
  1.1148            <p>
  1.1149              When the user agent is to <dfn>create a static <a>transaction</a></dfn>
  1.1150 @@ -3153,9 +3056,12 @@
  1.1151                the result of the operation.
  1.1152              </li>
  1.1153              <li>
  1.1154 -              If performing <var>operation</var> failed then set the <a title="request done">done</a> flag
  1.1155 -              on the <var>request</var> to true and <a>fire a error event</a> at <var>request</var> with
  1.1156 -              the code of the error from <var>operation</var>.
  1.1157 +              If performing <var>operation</var> failed then revert all changes made by <var>operation</var>,
  1.1158 +              set the <a title="request done">done</a> flag on the <var>request</var> to true and
  1.1159 +              <a>fire a error event</a> at <var>request</var> with the code of the error from <var>operation</var>.
  1.1160 +              <div class="note">
  1.1161 +                This only reverts the changes done by this request, not any other changes made by the transaction.
  1.1162 +              </div>
  1.1163              </li>
  1.1164            </ol>
  1.1165          </section>
  1.1166 @@ -3221,7 +3127,7 @@
  1.1167                  This event MUST NOT bubble or be cancelable.
  1.1168                </p>
  1.1169              </li>
  1.1170 -            <li>
  1.1171 +            <li id="VERSION_CHANGE-close-block">
  1.1172                Wait until all objects in <var>openDatabases</var> are <a title="database close">closed</a> and all of
  1.1173                their transactions are <a title="transaction finish">finished</a>.
  1.1174                <p class="issue">Should we allow <code>blocked</code> to be fired here too, if waiting takes "too long"?</p>.
  1.1175 @@ -3263,6 +3169,11 @@
  1.1176              <a title="transaction create">create</a> transactions first check the the <a>closePending</a> flag first and
  1.1177              throw an exception if it is true.
  1.1178            </p>
  1.1179 +          <p class="note">
  1.1180 +            Once the <a>connection</a> is closed, this can unblock the <a>steps for running a <code>VERSION_CHANGE</code>
  1.1181 +            transaction</a>, which <a href="#VERSION_CHANGE-close-block">wait</a> for <a>connection</a>s to a given
  1.1182 +            <a>database</a> to be closed before continuing.
  1.1183 +          </p>
  1.1184          </section>
  1.1185          <section class="section">
  1.1186            <h4>Fire a success event</h4>
  1.1187 @@ -3319,6 +3230,330 @@
  1.1188            </p>
  1.1189          </section>
  1.1190        </section>
  1.1191 +      <section class="section" id="database operations">
  1.1192 +        <h3>Database operations</h3>
  1.1193 +        <p>
  1.1194 +          This section describes various operations done on the data in <a>object store</a>s and <a>index</a>es
  1.1195 +          in a <a>database</a>. These operations are run by the <a>steps for asynchronously executing a request</a> and
  1.1196 +          the <a>steps for synchronously executing a request</a>.
  1.1197 +        </p>
  1.1198 +        <section class="section">
  1.1199 +          <h4>Object Store Storage Operation</h4>
  1.1200 +          <p>
  1.1201 +            The <dfn>steps for storing a record into an object store</dfn> are as follows. 
  1.1202 +            The algorithm run by these steps takes four parameters: a object store <var>store</var>,
  1.1203 +            a <var>value</var>, an optional <var>key</var>, and a <var>no-overwrite flag</var>.
  1.1204 +          </p>
  1.1205 +          <ol>
  1.1206 +            <li>
  1.1207 +              If <var>store</var> uses a <a>key generator</a> set and <var>key</var> is undefined, set
  1.1208 +              <var>key</var> to the next generated key. If <var>store</var> also uses <a>in-line keys</a>,
  1.1209 +              then set the property in <var>value</var> pointed to by <var>store</var>'s
  1.1210 +              <a title="object store key path">key path</a> to the new value for <var>key</var>
  1.1211 +            </li>
  1.1212 +            <li>
  1.1213 +              If <var>store</var> does not use a <a>key generator</a> but does use <a>in-line keys</a>, then set
  1.1214 +              <var>key</var> to the the result of <a title="evaluate key path">evaluting</a>
  1.1215 +              <a title="object store key path"><var>store</var>'s key path</a> on <var>value</var>.
  1.1216 +            </li>
  1.1217 +            <li>
  1.1218 +              If the no-overwrite flag was passed to these steps and is set, and 
  1.1219 +              a <a>record</a> already exists in <var>store</var> with its key <a>equal to</a> <var>key</var>, then 
  1.1220 +              terminate these steps and set error code to
  1.1221 +              <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>
  1.1222 +              and abort this algorithm without taking any further steps.
  1.1223 +            </li>
  1.1224 +            <li>
  1.1225 +              If a <a>record</a> already exists in <var>store</var> with its key <a>equal to</a> <var>key</var>, then 
  1.1226 +              remove the <a>record</a> from <a>store</a> using the <a>steps for deleting a record from an object store</a>.
  1.1227 +            </li>
  1.1228 +            <li>
  1.1229 +              Store a record in <var>store</var> containing <var>key</var> as its key and <var>object</var> as its
  1.1230 +              value. The record is stored in the the object store's <a title="objec store record list">list</a> such
  1.1231 +              that the list is sorted according key of the records in ascending order.
  1.1232 +            </li>
  1.1233 +            <li>
  1.1234 +              If there are any <a>index</a>es which <a title="referenced">reference</a> <var>store</var>, perform the
  1.1235 +              following sub steps on each such index.
  1.1236 +              <ol>
  1.1237 +                <li>
  1.1238 +                  Set <var>index</var> to the index.
  1.1239 +                </li>
  1.1240 +                <li>
  1.1241 +                  <a title="evaluate key path">Evaluate</a> <var>index</var>'s <a title="index key path">key path</a> on
  1.1242 +                  <var>value</var>. If this does not yield a value don't take any further actions for this index.
  1.1243 +                  Otherwise set the result to <var>index key</var>.
  1.1244 +                  <div class="note">
  1.1245 +                    The places invoking these steps ensures that <var>index key</var> is always a <a>valid key</a> at this
  1.1246 +                    point.
  1.1247 +                </li>
  1.1248 +                <li>
  1.1249 +                  If <var>index</var> already contains a <a>record</a> with <a>key</a> <a>equal to</a> <var>index key</var>,
  1.1250 +                  and <var>index</var> has it's <a>unique</a> flag set to true, then set error code to CONSTRAINT_ERR and
  1.1251 +                  abort this algorithm without taking any further steps.
  1.1252 +                </li>
  1.1253 +                <li>
  1.1254 +                  Store a record in <var>index</var> containig <var>index key</var> as its key and <var>key</var> as its
  1.1255 +                  value. The record is stored in <var>index</var>'s <a title="index record list">list of records</a> such
  1.1256 +                  that the list is sorted primarily on the records keys, and secondarily on the records values, in ascending
  1.1257 +                  order.
  1.1258 +                </li>
  1.1259 +              </ol>
  1.1260 +            </li>
  1.1261 +            <li>
  1.1262 +              The result of this algorithm is <var>key</var>.
  1.1263 +            </li>
  1.1264 +          </ol>
  1.1265 +        </section>
  1.1266 +        
  1.1267 +        <section class="section">
  1.1268 +          <h4>Object Store Retrieval Operation</h4>
  1.1269 +          <p>
  1.1270 +            The <dfn>steps for retrieving a value from an object store</dfn> are
  1.1271 +            as follows. These steps MUST be run with two parameters - the record 
  1.1272 +            key and the <a>object store</a>.
  1.1273 +          </p>
  1.1274 +            
  1.1275 +          <ol>
  1.1276 +            <li>
  1.1277 +              Let <var>key</var> be the key and <var>store</var> be the <a>object
  1.1278 +              store</a> passed to these steps.
  1.1279 +            </li>
  1.1280 +            <li>
  1.1281 +              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
  1.1282 +              with key <var>key</var> from <var>store</var>. If <var>key</var> is a <a>key range</a>, then
  1.1283 +              retreive the first <a>record</a> from <var>store</var> whose key is <a title="in a key range">in</a> <var>key</var>.
  1.1284 +            </li>
  1.1285 +            <li>
  1.1286 +              If no record was found in the previous step,
  1.1287 +              then terminate these steps and set error code
  1.1288 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
  1.1289 +            </li>
  1.1290 +            <li>
  1.1291 +              The result of this algorithm is a new <a>structured clone</a> of the value in the found record.
  1.1292 +            </li>
  1.1293 +          </ol>
  1.1294 +        </section>
  1.1295 +        
  1.1296 +        <section class="section">
  1.1297 +          <h4>Index Referenced Value Retrieval Operation</h4>
  1.1298 +          <p>
  1.1299 +            The <dfn>steps for retrieving a referenced value from an index</dfn> are
  1.1300 +            as follows. These steps MUST be run with two parameters - the record 
  1.1301 +            key and the <a>index</a>.
  1.1302 +          </p>
  1.1303 +            
  1.1304 +          <ol>
  1.1305 +            <li>
  1.1306 +              Let <var>key</var> be the key and <var>index</var> be the <a>index</a>
  1.1307 +              passed to these steps.
  1.1308 +            </li>
  1.1309 +            <li>
  1.1310 +              If <var>key</var> is not a <a>key range</a> then find the first <a>record</a>
  1.1311 +              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
  1.1312 +              find the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
  1.1313 +            </li>
  1.1314 +            <li>
  1.1315 +              If no record was found in the previous step, then the algorithm failed with a
  1.1316 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
  1.1317 +            </li>
  1.1318 +            <li>
  1.1319 +              Otherwise, the result of the operation is the <a>referenced value</a> of the found record.
  1.1320 +            </li>
  1.1321 +          </ol>
  1.1322 +        </section>
  1.1323 +        
  1.1324 +        <section class="section">
  1.1325 +          <h4>Index Value Retrieval Operation</h4>
  1.1326 +          <p>
  1.1327 +            The <dfn>steps for retrieving a value from an index</dfn> are
  1.1328 +            as follows. These steps MUST be run with two parameters - the record 
  1.1329 +            key and the <a>index</a>.
  1.1330 +          </p>
  1.1331 +            
  1.1332 +          <ol>
  1.1333 +            <li>
  1.1334 +              Let <var>key</var> be the key and <var>index</var> be the <a>index</a>
  1.1335 +              passed to these steps.
  1.1336 +            </li>
  1.1337 +            <li>
  1.1338 +              If <var>key</var> is not a <a>key range</a> then find the first <a>record</a>
  1.1339 +              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
  1.1340 +              find the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
  1.1341 +            </li>
  1.1342 +            <li>
  1.1343 +              If no record was found in the previous step, then the algorithm failed with a
  1.1344 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
  1.1345 +            </li>
  1.1346 +            <li>
  1.1347 +              If a record was found, the result of this algorithm is the <a>value</a> of the found <a>record</a>.
  1.1348 +            </li>
  1.1349 +          </ol>
  1.1350 +        </section>
  1.1351 +        
  1.1352 +        <section class="section">
  1.1353 +          <h4>Object Store Deletion Operation</h4>
  1.1354 +          <p>
  1.1355 +            The <dfn>steps for deleting a record from an object store</dfn> are as follows. 
  1.1356 +            The algorithm run by these steps takes two parameters: a object store <var>store</var> and
  1.1357 +            a <var>key</var>.
  1.1358 +          </p>
  1.1359 +          <ol>
  1.1360 +            <li>
  1.1361 +              If no <a>record</a> exists with key <var>key</var> in <var>store</var>,
  1.1362 +              then terminate these steps and set error code
  1.1363 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
  1.1364 +              <p class="issue">
  1.1365 +                Should we instead return a boolean indicating if a record was found or not?
  1.1366 +              </p>
  1.1367 +            </li>            
  1.1368 +            <li>
  1.1369 +               Remove the record from <var>store</var> with key <var>key</var>.
  1.1370 +            </li>
  1.1371 +            <li>
  1.1372 +              In all <a>index</a>es which <a title="referenced">reference</a> <var>store</var>, remove all
  1.1373 +              <a>records</a> with value <var>key</var>.
  1.1374 +            </li>
  1.1375 +            <li>
  1.1376 +              The result of this algorithm is <code>undefined</code>.
  1.1377 +            </li>
  1.1378 +          </ol>
  1.1379 +        </section>
  1.1380 +        <section class="section">
  1.1381 +          <h4>Cursor Iteration Operation</h4>
  1.1382 +          <p>
  1.1383 +            The <dfn>steps for iterating a cursor</dfn> are as follows. 
  1.1384 +            The algorithm run by these steps takes two parameters: a <var>cursor</var> and optional
  1.1385 +            <var>key</var> to iterate to.
  1.1386 +          </p>
  1.1387 +          <ol>
  1.1388 +            <li>
  1.1389 +              Let <var>source</var> be <var>cursor</var>'s <a title="cursor source">source</a>, let
  1.1390 +              <var>records</var> be list of <a>records</a> in <var>source</var>, let <var>direction</var>
  1.1391 +              be <var>cursor</var>'s <a>direction</a>, let <var>position</var> be <var>cursor</var>'s
  1.1392 +              <a>position</a>, let <var>object store position</var> be <var>cursor</var>'s <a>object store position</a>
  1.1393 +              and let <var>range</var> be <var>cursor</var>'s <a>range</a>.
  1.1394 +              <p class="note">
  1.1395 +                <var>source</var> is always a <a>object store</a> or a <a>index</a>.
  1.1396 +              </p>
  1.1397 +              <p class="note">
  1.1398 +                <var>records</var> is always sorted in ascending <a>key</a> order. In the case of
  1.1399 +                <var>source</var> being an <a>index</a>, <var>records</var> is secondarily sorted in ascending
  1.1400 +                <a>value</a> order.
  1.1401 +              </p>
  1.1402 +            </li>
  1.1403 +
  1.1404 +            <li>
  1.1405 +              <p>
  1.1406 +                If <var>direction</var> is NEXT, let <var>found record</var> be the first record in <var>records</var> which
  1.1407 +                satisfy all of the following requirements:
  1.1408 +              </p>
  1.1409 +              <ul>
  1.1410 +                <li>
  1.1411 +                  If <var>key</var> is defined, the record's key is <a>greater than</a> or <a>equal to</a> <var>key</var>.
  1.1412 +                </li>
  1.1413 +                <li>
  1.1414 +                  If <var>position</var> is defined, and <var>source</var> is a <a>object store</a>, the record's
  1.1415 +                  key is <a>greater than</a> <var>position</var>.
  1.1416 +                </li>
  1.1417 +                <li>
  1.1418 +                  If <var>position</var> is defined, and <var>source</var> is an <a>index</a>, the record's
  1.1419 +                  key is <a>equal to</a> <var>position</var> and the record's value is <a>greater than</a>
  1.1420 +                  <var>object store position</var> or the record's key is <a>greater than</a> <var>position</var>.
  1.1421 +                </li>
  1.1422 +                <li>
  1.1423 +                  If <var>range</var> is defined, the record's key is <a title="in a key range">in</a> <var>range</var>.
  1.1424 +                </li>
  1.1425 +              </ul>
  1.1426 +              <p>
  1.1427 +                If <var>direction</var> is NEXT_NO_DUPLICATE, let <var>found record</var> be the first record in <var>records</var> which
  1.1428 +                satisfy all of the following requirements:
  1.1429 +              </p>
  1.1430 +              <ul>
  1.1431 +                <li>
  1.1432 +                  If <var>key</var> is defined, the record's key is <a>greater than</a> or <a>equal to</a> <var>key</var>.
  1.1433 +                </li>
  1.1434 +                <li>
  1.1435 +                  If <var>position</var> is defined, the record's key is <a>greater than</a> <var>position</var>.
  1.1436 +                </li>
  1.1437 +                <li>
  1.1438 +                  If <var>range</var> is defined, the record's key is <a title="in a key range">in</a> <var>range</var>.
  1.1439 +                </li>
  1.1440 +              </ul>
  1.1441 +              <p>
  1.1442 +                If <var>direction</var> is PREV, let <var>found record</var> be the last record in <var>records</var> which
  1.1443 +                satisfy all of the following requirements:
  1.1444 +              </p>
  1.1445 +              <ul>
  1.1446 +                <li>
  1.1447 +                  If <var>key</var> is defined, the record's key is <a>less than</a> or <a>equal to</a> <var>key</var>.
  1.1448 +                </li>
  1.1449 +                <li>
  1.1450 +                  If <var>position</var> is defined, and <var>source</var> is a <a>object store</a>, the record's
  1.1451 +                  key is <a>less than</a> <var>position</var>.
  1.1452 +                </li>
  1.1453 +                <li>
  1.1454 +                  If <var>position</var> is defined, and <var>source</var> is an <a>index</a>, the record's
  1.1455 +                  key is <a>equal to</a> <var>position</var> and the record's value is <a>less than</a>
  1.1456 +                  <var>object store position</var> or the record's key is <a>less than</a> <var>position</var>.
  1.1457 +                </li>
  1.1458 +                <li>
  1.1459 +                  If <var>range</var> is defined, the record's key is <a title="in a key range">in</a> <var>range</var>.
  1.1460 +                </li>
  1.1461 +              </ul>
  1.1462 +              <p>
  1.1463 +                If <var>direction</var> is PREV_NO_DUPLICATE, let <var>temp record</var> be the last record in
  1.1464 +                <var>records</var> which satisfy all of the following requirements:
  1.1465 +              </p>
  1.1466 +              <ul>
  1.1467 +                <li>
  1.1468 +                  If <var>key</var> is defined, the record's key is <a>less than</a> or <a>equal to</a> <var>key</var>.
  1.1469 +                </li>
  1.1470 +                <li>
  1.1471 +                  If <var>position</var> is defined, the record's key is <a>less than</a> <var>position</var>.
  1.1472 +                </li>
  1.1473 +                <li>
  1.1474 +                  If <var>range</var> is defined, the record's key is <a title="in a key range">in</a> <var>range</var>.
  1.1475 +                </li>
  1.1476 +              </ul>
  1.1477 +              <p>
  1.1478 +                If <var>temp record</var> is defined, let <var>found record</var> be the first record in <var>records</var>
  1.1479 +                whose key is <a>equal to</a> <var>temp record</var>'s key.
  1.1480 +              </p>
  1.1481 +            </li>
  1.1482 +            <li>
  1.1483 +              If <var>found record</var> is not defined, the result of this algorithm is <code>undefined</code>. Abort these steps.
  1.1484 +            </li>
  1.1485 +            <li>
  1.1486 +              <p>
  1.1487 +                Set <var>cursor</var>'s <a>position</a> to <var>found record</var>'s key. If <var>source</var> is a <a>index</a>,
  1.1488 +                set <var>cursor</var>'s <a>object store position</a> to <var>found record</var>'s value.
  1.1489 +              </p>
  1.1490 +            </li>
  1.1491 +            <li>
  1.1492 +              <p>
  1.1493 +                Set <var>cursor</var>'s <a title="cursor key">key</a> to <var>found record</var>'s key.
  1.1494 +              </p>
  1.1495 +              <p>
  1.1496 +                If <var>cursor</var> was created using <a href="#widl-IDBIndex-openCursor"><code>IDBIndex.openCursor</code></a> or
  1.1497 +                <a href="#widl-IDBIndexSync-openCursor"><code>IDBIndexSync.openCursor</code></a>, then set
  1.1498 +                <var>cursor</var>'s <a title="cursor value">value</a> to <var>found record</var> <a>referenced value</a>. Otherwise, set
  1.1499 +                <var>cursor</var>'s <a title="cursor value">value</a> to the value of <var>found record</var>.
  1.1500 +              </p>
  1.1501 +            </li>
  1.1502 +            <li>
  1.1503 +              Set <var>cursor</var>'s <a>got value</a> flag to true.
  1.1504 +              <p class="issue">
  1.1505 +                This should only be done right before firing the success event. Not asynchronously before. Not sure
  1.1506 +                how/where to express that.
  1.1507 +              </p>
  1.1508 +            </li>
  1.1509 +            <li>
  1.1510 +              The result of the algorithm is <var>cursor</var>.
  1.1511 +            </li>
  1.1512 +          </ol>
  1.1513 +        </section>
  1.1514 +      </section>
  1.1515  
  1.1516    <!-- database-api -->
  1.1517  
     2.1 --- a/Speclet_020_IDB_API_Constructs.html	Wed Nov 03 17:12:19 2010 +0100
     2.2 +++ b/Speclet_020_IDB_API_Constructs.html	Mon Nov 08 03:30:39 2010 -0800
     2.3 @@ -134,25 +134,123 @@
     2.4        <!-- begin-content -->
     2.5        <section id="constructs" class="section">
     2.6        <h3>Constructs</h3>
     2.7 -        <p>
     2.8 -          An indexed database is made of records holding simple values
     2.9 -          and hierarchical objects. Each <dfn>record</dfn> consists of a key and a value. 
    2.10 -        </p>
    2.11 -        
    2.12 +       <section id="database-concept" class="section">
    2.13 +          <h4>Database</h4>
    2.14 +          <p>
    2.15 +            Each <a>origin</a> has an associated set of 
    2.16 +            <a title="database">databases</a>. A <dfn>database</dfn> comprises
    2.17 +            one or more <a title="object store">object stores</a> which hold the data stored
    2.18 +            in the database.
    2.19 +          </p>
    2.20 +          <p>
    2.21 +            Every <a>database</a> has a <dfn title="database name">name</dfn> which identifies it
    2.22 +            within a specific <a>origin</a>. The name can be any string value, including the empty string, and
    2.23 +            stays constant for the lifetime of the database. Each <a>database</a> also has a current
    2.24 +            <dfn>version</dfn>. When a database is first created, its <a>version</a> is the empty string.
    2.25 +          </p>
    2.26 +          <p class="note">
    2.27 +            Implementations MUST support all names. If a implementation
    2.28 +            uses a storage mechanism which can't handle arbitrary database names,
    2.29 +            the implementation must use an escaping mechanism or something similar
    2.30 +            to map the provided name to a name that it can handle.
    2.31 +          </p>
    2.32 +          <div class="note">
    2.33 +            Each <a>database</a> has one version at a time; a <a>database</a> 
    2.34 +            can't exist in multiple versions at once. The only way to change the version is using a VERSION_CHANGE
    2.35 +            <a>transaction</a>.
    2.36 +          </div>
    2.37 +          <p>
    2.38 +            The act of opening a <a>database</a> creates a <dfn>connection</dfn>. There MAY be multiple 
    2.39 +            <a>connection</a>s to a given <a>database</a> at any given time. Each connection has a
    2.40 +            <dfn>closePending</dfn> flag which initially is set to false.
    2.41 +          </p>
    2.42 +          <p>
    2.43 +            When a <a>connection</a> is initially created it is in <var>opened</var> state. The connection
    2.44 +            can be <dfn title="database close">closed</dfn> through several means. If the connection is GCed
    2.45 +            or execution context where the <a>connection</a> is created is destroyed (for example due to the
    2.46 +            user navigating away from that page), the connection is closed. The connection can also be closed
    2.47 +            explicitly using the <a>steps for closing a database connection</a>. When the connection is closed
    2.48 +            the <a>closePending</a> flag is always set to true if it hasn't already been.
    2.49 +          </p>
    2.50 +          <p>
    2.51 +            The <a><code>IDBDatabase</code></a> and <a><code>IDBDatabaseSync</code></a>
    2.52 +            interfaces represent a <a>connection</a> to a <a>database</a>. 
    2.53 +          </p>
    2.54 +        </section>  <!-- IDBDatabase -->
    2.55 +
    2.56 +        <section class="section" id="object-store-concept">  
    2.57 +          <h4>Object Store</h4>
    2.58 +          <p>
    2.59 +            An <dfn>object store</dfn> is the primary storage mechanism for storing data in a
    2.60 +            <a>database</a>.
    2.61 +          </p>
    2.62 +          <p>
    2.63 +            Each database contain a set of <a>object store</a>s. The set of <a>object store</a>s
    2.64 +            can be changed, but can only be changed using a VERSION_CHANGE transactions. When a new database is
    2.65 +            created it doesn't contain any <a>object store</a>s and has the empty string as <a>version</a>.
    2.66 +          </p>
    2.67 +          <p>
    2.68 +            The object store has a <a title="object store record list">list of records</a> which hold the
    2.69 +            data stored in the object store. Each <dfn>record</dfn> consists of a <dfn>key</dfn> and a <dfn>value</dfn>.
    2.70 +            The list is sorted according to key in ascending order. There can never be multiple records in a given object
    2.71 +            store with the same key.
    2.72 +          </p>
    2.73 +          <p>
    2.74 +            Every <a>object store</a> has a <dfn title="object store name">name</dfn>.
    2.75 +            The name is unique within the <a>database</a> to which it belongs. Every object store also optionally has a
    2.76 +            <a>key generator</a> and a optional <dfn title="object store key path">key path</dfn>.
    2.77 +            If the object store has a key path it is said to use <dfn>in-line keys</dfn>. Otherwise it is said to
    2.78 +            use <dfn>out-of-line</dfn> keys.
    2.79 +          </p>
    2.80 +          <p>
    2.81 +            The object store can derive the <a>key</a> from one of three sources. Which source is used is determined
    2.82 +            when the object store is created. The three sources are:
    2.83 +          </p>
    2.84 +          <ol>
    2.85 +            <li>
    2.86 +              A <dfn>key generator</dfn>. A key generator generates a monotonically increasing numbers every time
    2.87 +              a key is needed.
    2.88 +              <p class="issue">
    2.89 +                specify that generators are not shared between stores.
    2.90 +              </p>
    2.91 +            </li>
    2.92 +            <li>
    2.93 +              A <dfn>key path</dfn>. A key path points to a property in a given <a>value</a>. When a object store uses a
    2.94 +              <a>key path</a> to generate keys, the key is the property in the stored <a>value</a> pointed to by the
    2.95 +              <a>key path</a>.
    2.96 +              <p class="issue">
    2.97 +                Need to specify how a key path is parsed and how a "evaluated" against a value. Including the requirement
    2.98 +                that the value needs to be a object and that the property must be enumerated.
    2.99 +              </p>
   2.100 +            </li>
   2.101 +            <li>
   2.102 +              Keys can also be explicitly specified when a <a>value</a> is stored in the object store.
   2.103 +            </li>
   2.104 +          </p>
   2.105 +          <!--div class="ednote">
   2.106 +            The detached reading behavior MAY need more explanation.
   2.107 +            What is detached reading?
   2.108 +          </div-->
   2.109 +          <p>
   2.110 +            The <a><code>IDBObjectStore</code></a> and <a><code>IDBObjectStoreSync</code></a>
   2.111 +            interfaces represent a <a>object store</a>. Note however that multiple instances of those
   2.112 +            interfaces representing the same <a>object store</a> can exist.
   2.113 +          </p>
   2.114 +        </section> <!-- Object store -->
   2.115 +
   2.116          <section id="key-construct" class="section">
   2.117            <h4>Keys</h4>
   2.118 -          
   2.119            <p>
   2.120 -            In order to efficiently retrieve <a title="record">records</a> 
   2.121 -            stored in an indexed database, a user agent needs to organize each 
   2.122 -            <a>record</a> according to its key. <a>Conforming user agents</a>
   2.123 -            MUST support the use of the following types as <dfn>key value</dfn>s: IDL data types
   2.124 +            In order to efficiently retrieve <a>record</a>s stored in an indexed database,
   2.125 +            each <a>record</a> is organized according to its key. A value is said to be a <dfn>valid key</dfn>
   2.126 +            if it is one of the following types: IDL data types
   2.127              <code>DOMString</code>, <code>long</code>, and <code>float</code> [[!WEBIDL]]; the
   2.128              <code>Date</code> JavaScript object [[!ECMA-262]]; as well as the value <code>null</code>.
   2.129 -            For the particular case of <code>float</code>, the value NaN is not allowed.
   2.130 +            Additionally, if the value os of type <code>float</code>, it is only a <a>valid key</a> if it is not NaN.
   2.131 +            <a>Conforming user agents</a> MUST support all <a>valid key</a>s as keys.
   2.132            </p>
   2.133            <p class="note">
   2.134 -            Inifinite <code>float</code> values are allowed.
   2.135 +            Inifinite <code>float</code> values are <a>valid key</a>s.
   2.136            </p>
   2.137            <p>
   2.138              For purposes of comparison, all <code>DOMString</code> values are evaluated as greater than 
   2.139 @@ -174,152 +272,67 @@
   2.140          <section id="value-construct" class="section">
   2.141            <h4>Values</h4>
   2.142            <p>
   2.143 -            Values can be any data type supported by the <a>structured clone algorithm</a> 
   2.144 +            Each record is associated with a <dfn>value</dfn>. <a>Conforming user agents</a> MUST support
   2.145 +            any value supported by the <a>structured clone algorithm</a> 
   2.146              [[!HTML5]]. This includes simple types such as <code>DOMString</code>
   2.147              and <code>Date</code> as well as <code>Object</code> and <code>Array</code>
   2.148              instances.
   2.149            </p>
   2.150 -          
   2.151 -          <p>
   2.152 -            A database can derive a key from the contents of
   2.153 -            the value being stored. In such a case, only <code>Object</code> 
   2.154 -            instances MAY be stored as values. Only the direct enumerable
   2.155 -            properties of a stored <code>Object</code> instance SHOULD be 
   2.156 -            used to derive a key value.
   2.157 -          </p>
   2.158          </section>
   2.159          
   2.160 -        <section class="section" id="object-store-concept">  
   2.161 -          <h4>Object Store</h4>
   2.162 -          <p>
   2.163 -            An <dfn>object store</dfn> is a persistent storage mechanism that 
   2.164 -            holds key-value pairs, also called <a title="record">records</a> 
   2.165 -            or <dfn>stored objects</dfn>. An <a>object store</a>'s 
   2.166 -            <a title="record">records</a> are sorted by keys to enable fast 
   2.167 -            insertion and look up as well as ordered retrieval. 
   2.168 -          </p>
   2.169 -          <p>
   2.170 -            Every <a>object store</a> has a 
   2.171 -            <dfn title="object store name">name</dfn>. Within a <a>database</a>, 
   2.172 -            each <a>object store</a> MUST have a <a title="valid-name">valid</a> 
   2.173 -            and unique <a title="object store name">name</a>. 
   2.174 -          </p>          
   2.175 -          <p>
   2.176 -            If an <a>object store</a> uses keys generated from a monotonically
   2.177 -            increasing sequence, it MUST have a <dfn>key generator</dfn> that 
   2.178 -            produces unique keys for <a title="record">records</a> in that 
   2.179 -            <a>object store</a>. Alternatively, if an application provides keys, 
   2.180 -            they MAY either be identified as a part of the value being stored, 
   2.181 -            also called <dfn>in-line keys</dfn>, or be identified separately, 
   2.182 -            also called <dfn>out-of-line keys</dfn>. No two 
   2.183 -            <a title="record">records</a> in an <a>object store</a> MAY be 
   2.184 -            identified by the same key. An <a>object store</a> MUST have a 
   2.185 -            <dfn title="object store key path">key path</dfn> if it uses 
   2.186 -            <a>in-line keys</a>. The <a>key path</a> MUST be the name 
   2.187 -            of an enumerated property of all stored objects in that 
   2.188 -            <a>object store</a>.
   2.189 -          </p>
   2.190 -          <!--div class="ednote">
   2.191 -            The detached reading behavior MAY need more explanation.
   2.192 -          </div-->
   2.193 -          <p>
   2.194 -            The <a><code>IDBObjectStore</code></a> and <a><code>IDBObjectStoreSync</code></a>
   2.195 -            interfaces provide access to the metadata of an <a>object store</a>.
   2.196 -          </p>
   2.197 -        </section> <!-- Object store -->
   2.198 -        
   2.199          <section id="index-concept" class="section">
   2.200            <h4>Index</h4>
   2.201            <p>
   2.202 -            <a title="record">Records</a> in an <a>object store</a> can be 
   2.203 -            retrieved using the <a title="record">record's</a> key. However, 
   2.204 -            that MAY not always be adequate to recall 
   2.205 -            <a title="record">records</a>. An <a>index</a> is used to lookup 
   2.206 -            records in an <a>object store</a> other than through a
   2.207 -            <a>record</a> key.
   2.208 +            It is sometimes useful to retreive <a>records</a> in a <a>object store</a> through other means
   2.209 +            than their <a>key</a>. A <dfn>index</dfn> allows looking up <a>record</a>s in a <a>object store</a>
   2.210 +            using properties of the <a>value</a>s in the <a>object store</a>s <a>record</a>s.
   2.211            </p>
   2.212            <p>
   2.213 -            An <dfn>index</dfn> is a specialized persistent store that holds 
   2.214 -            key-value pairs such that each value is the key of objects in the 
   2.215 -            <dfn>referenced</dfn> <a>object store</a>. If an <a>index</a>'s 
   2.216 -            <dfn>unique</dfn> flag is set, then it MUST NOT allow duplicate 
   2.217 -            values for a key. Every <a>index</a> has a 
   2.218 -            <dfn title="index name">name</dfn>. Within an 
   2.219 -            <a>object store</a>, each <a>index</a> MUST have a
   2.220 -            <a title="valid-name">valid</a> and unique 
   2.221 -            <a title="index name">name</a>.
   2.222 +            An index is a specialized persistent key-value storage and has a <dfn>referenced</dfn> <a>object store</a>.
   2.223 +            The index has a <dfn title="index record list">list of records</dfn> which hold the
   2.224 +            data stored in the index. The records in an index are automatically populated whenever records in the
   2.225 +            <a>referenced</a> object store are inserted, updated or deleted. There can be several <a>index</a>es
   2.226 +            referencing the same <a>object store</a>, in which changes to the object store cause all such indexes
   2.227 +            to get updated.
   2.228            </p>
   2.229            <p>
   2.230 -            If an <a>index</a> is <dfn>auto-populated</dfn>, then the user agent 
   2.231 -            populates records using the values stored in the <a>referenced</a> 
   2.232 -            <a>object store</a>. An <a>auto-populated</a> <a>index</a> MUST have 
   2.233 -            a <dfn title="index key path">key path</dfn>. This <a>key path</a> 
   2.234 -            MUST be the name of an enumerated property of every object to be 
   2.235 -            stored in the <a>object store</a> <a>referenced</a> by that 
   2.236 -            <a>index</a>. The <a>auto-populated</a> <a>index</a> record 
   2.237 -            corresponding to an <a>object store</a> record MUST satisfy the 
   2.238 -            following <dfn>index maintenance conditions</dfn>:
   2.239 +            The values in the index's <a>record</a>s are always values of <a>keys</a> in the index's <a>referenced</a>
   2.240 +            object store. The keys are derived from the referenced object store's <a>value</a>s using a <dfn title="index key path"><a>key path</a></dfn>.
   2.241 +            If a given <a>record</a> with key <var>X</var> in the object store referenced by the index has the value <var>A</var>, and
   2.242 +            <a title="evaluate key path">evaluting</a> the <a title="index key path">index's key path</a> on <var>A</var> yields the result
   2.243 +            <var>Y</var>, then the index will contain a record with key <var>Y</var> and value <var>X</var>.
   2.244            </p>
   2.245 -          <ul>
   2.246 -            <li><a>index</a> record key = value of the enumerated property at 
   2.247 -            the <a title="index key path">key path</a> in the <a>object store</a> 
   2.248 -            record value</li>
   2.249 -            <li><a>index</a> record value = <a>object store</a> record key</li>
   2.250 -          </ul>
   2.251 +          <p>
   2.252 +            Records in an index are said to have a <dfn>referenced value</dfn>. This is the value of the record in the index's referenced
   2.253 +            object store which has a key equal to the index's record's value. So in the example above,
   2.254 +            the record in the index whose key is <var>Y</var> and value is <var>X</var> has a <a>referenced value</a> of <var>A</var>.
   2.255 +          </p>
   2.256 +          <p class="note">
   2.257 +            Each record in an index reference one and only one record in the index's <a>referenced</a> object store. However there can be
   2.258 +            multiple records in an index which reference the same record in the object store. And there can also be no records in an index
   2.259 +            which reference a given record in an object store.
   2.260 +          </p>
   2.261 +          <p class="issue">
   2.262 +            Some of the statements in the note are only true once we've implemented decisions made at TPAC.
   2.263 +          </p>
   2.264 +          <p>
   2.265 +            The <a>record</a>s in an index are always sorted according to the <a>record</a>s key. However unlike object stores,
   2.266 +            a given index can contain multiple records with the same key. Such records are additionally sorted according to
   2.267 +            the records value.
   2.268 +          </p>
   2.269 +          <p>
   2.270 +            A index contains a <dfn>unique</dfn> flag. When this flag is set to true, the index enforces that no two <a>record</a>s
   2.271 +            in the index has the same key. If a <a>record</a> in the index's referenced object store is attempted to be inserted or
   2.272 +            modified such that evaluating the index's key path on the records new value yields a result which already exists in the
   2.273 +            index, then the attempted modification to the object store fails.
   2.274 +          </p>
   2.275            <p>
   2.276              The <a><code>IDBIndex</code></a> and <a><code>IDBIndexSync</code></a> interfaces
   2.277 -            provide access to the metadata of an <a>index</a>.
   2.278 +            provide access to the metadata of an <a>index</a>. Note however that multiple instances of those
   2.279 +            interfaces representing the same <a>index</a> can exist.
   2.280            </p>
   2.281          </section> <!-- IDBIndex -->
   2.282          
   2.283 -       <section id="database-concept" class="section">
   2.284 -          <h4>Database</h4>
   2.285 -          <p>
   2.286 -            Each <a>origin</a> has an associated set of 
   2.287 -            <a title="database">databases</a>. A <dfn>database</dfn> comprises
   2.288 -            one or more <a title="object store">object stores</a>.
   2.289 -          </p>
   2.290 -          <p>
   2.291 -            Every <a>database</a> has a <dfn title="database name">name</dfn> which identifies it
   2.292 -            within a specific <a>origin</a>. The name can be any string value, including the empty string, and
   2.293 -            stays constant for the lifetime of the database. Each <a>database</a> also has a current
   2.294 -            <dfn>version</dfn>.
   2.295 -          </p>
   2.296 -          <p class="note">
   2.297 -            Implementations MUST support all names. If a implementation
   2.298 -            uses a storage mechanism which can't handle arbitrary database names,
   2.299 -            the implementation must use an escaping mechanism or something similar
   2.300 -            to map the provided name to a name that it can handle.
   2.301 -          </p>
   2.302 -          <div class="note">
   2.303 -            Each <a>database</a> has one version at a time; a <a>database</a> 
   2.304 -            can't exist in multiple versions at once. The only way to change the version is using a VERSION_CHANGE
   2.305 -            <a>transaction</a>.
   2.306 -          </div>
   2.307 -          <p>
   2.308 -            Each database contain a set of <a>object store</a>s. The set of <a>object store</a>s
   2.309 -            can changed, but can only be changed using VERSION_CHANGE transactions. When a new database is
   2.310 -            created it doesn't contain any <a>object store</a>s and has the empty string as <a>version</a>.
   2.311 -          </p>
   2.312 -          <p>
   2.313 -            The act of opening a <a>database</a> creates a <dfn>connection</dfn>. There MAY be multiple 
   2.314 -            <a>connection</a>s to a given <a>database</a> at any given time. Each connection has a
   2.315 -            <dfn>closePending</dfn> flag which initially is set to false.
   2.316 -          </p>
   2.317 -          <p>
   2.318 -            When a <a>connection</a> is initially created it is in <var>opened</var> state. The connection
   2.319 -            can be <dfn title="database close">closed</dfn> through several means. If the connection is GCed
   2.320 -            or execution context where the <a>connection</a> is created is destroyed (for example due to the
   2.321 -            user navigating away from that page), the connection is closed. The connection can also be closed
   2.322 -            explicitly using the <a>steps for closing a database connection</a>. When the connection is closed
   2.323 -            the <a>closePending</a> flag is always set to true if it hasn't already been.
   2.324 -          </p>
   2.325 -          <p>
   2.326 -            The <a><code>IDBDatabase</code></a> and <a><code>IDBDatabaseSync</code></a>
   2.327 -            interfaces represent a <a>connection</a> to a <a>database</a>. 
   2.328 -          </p>
   2.329 -        </section>  <!-- IDBDatabase -->
   2.330 -
   2.331          <section id="transaction-concept" class="section">
   2.332            <h4>Transaction</h4>
   2.333            <p>
   2.334 @@ -682,17 +695,49 @@
   2.335              are performed on the underlying <a>index</a> or an 
   2.336              <a>object store</a>.
   2.337            </p>
   2.338 -          
   2.339            <p>
   2.340 -            A <dfn>cursor</dfn> comprises a <dfn>range</dfn> of records in 
   2.341 -            either an <a>index</a> or an <a>object store</a>. A 
   2.342 -            <a title="cursor">cursor</a> maintains a <dfn>position</dfn> over 
   2.343 +            A <dfn>cursor</dfn> comprises a <dfn>range</dfn> of records in either an <a>index</a>
   2.344 +            or an <a>object store</a>. The cursor has a <dfn title="cursor source">source</dfn> indicating
   2.345 +            which index or object store whose records it is iterating. A <a>cursor</a> maintains a <dfn>position</dfn> over 
   2.346              this series, which moves in a <dfn>direction</dfn> that is either 
   2.347 -            monotonically increasing or decreasing order of the record keys. 
   2.348 +            monotonically increasing or decreasing order of the <a>record</a> keys. Cursors
   2.349 +            also have a <dfn title="cursor key">key</dfn> and a <dfn title="cursor value">value</dfn>
   2.350 +            which represent the <a>key</a> and the <a>value</a> of the last iterated <a>record</a>.
   2.351 +            Cursors finally have a <dfn>got value</dfn> flag. When this flag is false, the cursor is either
   2.352 +            in the process of loading the next value or it has reached the end of its <a>range</a>, when it
   2.353 +            is true, it indicates that the cursor is currently holding a value and that it is ready to iterate
   2.354 +            to the next one.
   2.355 +          </p>
   2.356 +          <p>
   2.357 +            If the <a title="cursor source">source</a> of a cursor is a <a>object store</a>, the <dfn>effective object store</dfn>
   2.358 +            of the cursor is that object store and the <dfn>effective key</dfn> of the cursor is the cursors <a>position</a>.
   2.359 +            If the <a title="cursor source">source</a> of a cursor is a <a>index</a>, the <a>effective object store</a>
   2.360 +            of the cursor is that index's <a>referenced</a> object store and the <a>effective key</a> is the cursors
   2.361 +            <a>object store position</a>.
   2.362 +          </p>
   2.363 +          <p>
   2.364 +            It is possible for the list of records which the cursor is iterating over to
   2.365 +            change before the full <a>range</a> of the cursor has been iterated. In order to
   2.366 +            handle this, cursors maintain their <a>position</a> not as an index, but rather
   2.367 +            as a <a>key</a> of the previously returned record. For a forward iterating cursor,
   2.368 +            the next time the cursor is asked to iterate to the next record it returns the
   2.369 +            record with the lowest <a>key</a> <a>greater than</a> the one previously returned. For
   2.370 +            a backwards iterating cursor, the situation is opposite and it returns the record
   2.371 +            with the highest <a>key</a> <a>less than</a> the one previously returned.
   2.372 +          </p>
   2.373 +          <p>
   2.374 +            For cursors iterating indexes the situation is a little bit more complicated since
   2.375 +            multiple records can have the same key and are therefor also sorted by <a>value</a>.
   2.376 +            When iterating indexes the <a>cursor</a>'s also has a <dfn>object store position</dfn>, which indicates
   2.377 +            the <a>value</a> of the previously found <a>record</a> in the index. Both
   2.378 +            <a>position</a> and the <a>object store position</a> is used when finding the next appropriate record.
   2.379            </p>
   2.380            <p>
   2.381              <a title="cursor">Cursor</a> objects implement the <a><code>IDBCursor</code></a> 
   2.382 -            or the <a><code>IDBCursorSync</code></a> interfaces.
   2.383 +            or the <a><code>IDBCursorSync</code></a> interfaces. There is only ever one
   2.384 +            <a><code>IDBCursor</code></a> or <a><code>IDBCursorSync</code></a> instance representing
   2.385 +            a given <a>cursor</a>. However there is no limit on how many cursors can be used at the
   2.386 +            same time.
   2.387            </p>
   2.388          </section> <!-- IDBCursor -->
   2.389  
     3.1 --- a/Speclet_021_IDB_API_Algorithms.html	Wed Nov 03 17:12:19 2010 +0100
     3.2 +++ b/Speclet_021_IDB_API_Algorithms.html	Mon Nov 08 03:30:39 2010 -0800
     3.3 @@ -154,7 +154,8 @@
     3.4              </li>
     3.5              <li>
     3.6                If no database with the given name from the origin <var>origin</var>
     3.7 -              exists, then create the database <var>db</var> with name <var>name</var>.
     3.8 +              exists, then create the database <var>db</var> with name <var>name</var>, with the empty
     3.9 +              string as <a>version</a>, and with no <a>object store</a>s.
    3.10              </li>
    3.11              <li>
    3.12                Wait until no already existing <a>connection</a>s to <var>db</var>, have
    3.13 @@ -169,218 +170,10 @@
    3.14              <li>
    3.15                Create a <a>connection</a> to <var>db</var> and return it.
    3.16              </li>
    3.17 -          </ol>        
    3.18 -        </section>
    3.19 -        
    3.20 -        <section class="section">
    3.21 -          <h4>Object Store Storage steps</h4>
    3.22 -          <p>
    3.23 -            The <dfn>steps for storing a record into an object store</dfn> are as follows. 
    3.24 -            These steps MUST be run with four parameters: the <a>object store</a>,
    3.25 -            a value, an optional key, and an optional no-overwrite flag.
    3.26 -          </p>
    3.27 -          <ol>
    3.28 -            <li>
    3.29 -              Let <var>store</var> be the <a>object store</a>, <var>key</var> be
    3.30 -              the key and <var>value</var> be the value passed to these steps.
    3.31 -            </li>
    3.32 -            <li>
    3.33 -              If <var>store</var> uses <a>out-of-line keys</a> but no <a>key 
    3.34 -              generator</a>, then a key MUST be passed to these steps. If not, 
    3.35 -              terminate these steps and set error code <a class="idlType" href="#widl-IDBDatabaseException-DATA_ERR"><code>DATA_ERR</code></a>.
    3.36 -            </li>
    3.37 -            <li>
    3.38 -              If <var>store</var> uses <a>in-line keys</a>, then 
    3.39 -              let <var>key</var> be the property of <var>object</var> at  
    3.40 -              <var>store</var>'s <a title="object store key path">key path</a>.
    3.41 -            </li>
    3.42 -           <li>
    3.43 -              Produce a <a>structured clone</a> of <var>value</var> and call it
    3.44 -              <var>object</var>.
    3.45 -            </li>
    3.46 -            <li>
    3.47 -              If <var>key</var> is not defined or null, then perform the 
    3.48 -              following steps.
    3.49 -              <ol>
    3.50 -                <li>
    3.51 -                  If <var>store</var> does not have a <a>key generator</a>, then 
    3.52 -                  terminate these steps and set error code <a class="idlType" href="#widl-IDBDatabaseException-NOT_ALLOWED_ERR"><code>NOT_ALLOWED_ERR</code></a>.
    3.53 -                </li>
    3.54 -                <li>
    3.55 -                  Using <var>store</var>'s <a>key generator</a>, produce the 
    3.56 -                  next key and store it as <var>key</var>.
    3.57 -                </li>
    3.58 -                <li>
    3.59 -                  If <var>store</var> uses <a>in-line keys</a>, then store 
    3.60 -                  <var>key</var> as the property value for <var>object</var> at  
    3.61 -                  <var>store</var>'s <a title="object store key path">key path</a>.
    3.62 -                </li>
    3.63 -              </ol>
    3.64 -            </li>
    3.65 -            <li>
    3.66 -              If the no-overwrite flag was passed to these steps and is set, and 
    3.67 -              a record already exists with its key being <var>key</var>, then 
    3.68 -              terminate these steps and set error code <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>.
    3.69 -            </li>
    3.70 -            <li>
    3.71 -              <p>
    3.72 -                Store a record in <var>store</var> containing <var>key</var> as its key  
    3.73 -                and <var>object</var> as its value. If any <a title="index">indexes</a>  
    3.74 -                are <a>auto-populated</a> for <var>store</var>, then store a record
    3.75 -                in that index according to <a>index maintenance conditions</a>.
    3.76 -              </p>
    3.77 -              <div class="note">
    3.78 -                Storing would mean inserting if no record exists for that key
    3.79 -                or updating an existing record, otherwise. <a title="auto-populated">
    3.80 -                Auto populated</a> <a>index</a> record will also be respectively
    3.81 -                inserted or updated depending on what storing results in.
    3.82 -              </div>
    3.83 -            </li>
    3.84 -            
    3.85 -            <li>
    3.86 -              Return the <var>key</var>.
    3.87 -            </li>
    3.88            </ol>
    3.89          </section>
    3.90          
    3.91          <section class="section">
    3.92 -          <h4>Object Store Retrieval steps</h4>
    3.93 -          <p>
    3.94 -            The <dfn>steps for retrieving a record from an object store</dfn> are
    3.95 -            as follows. These steps MUST be run with two parameters - the record 
    3.96 -            key and the <a>object store</a>.
    3.97 -          </p>
    3.98 -            
    3.99 -          <ol>
   3.100 -            <li>
   3.101 -              Let <var>key</var> be the key and <var>store</var> be the <a>object
   3.102 -              store</a> passed to these steps.
   3.103 -            </li>
   3.104 -            <li>
   3.105 -              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
   3.106 -              with key <var>key</var> from <var>store</var>. If <var>key</var> is a <a>key range</a>, then
   3.107 -              retreive the first <a>record</a> from <var>store</var> whose key is <a title="in a key range">in</a> <var>key</var>.
   3.108 -            </li>
   3.109 -            <li>
   3.110 -              If no record was found in the previous step,
   3.111 -              then terminate these steps and set error code
   3.112 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
   3.113 -            </li>
   3.114 -            <li>
   3.115 -              Return the a new <a>structured clone</a> of the value in the found record.
   3.116 -            </li>
   3.117 -          </ol>
   3.118 -        </section>
   3.119 -        
   3.120 -        <section class="section">
   3.121 -          <h4>Index Referenced Value Retrieval steps</h4>
   3.122 -          <p>
   3.123 -            The <dfn>steps for retrieving a record from an index</dfn> are
   3.124 -            as follows. These steps MUST be run with two parameters - the record 
   3.125 -            key and the <a>index</a>.
   3.126 -          </p>
   3.127 -            
   3.128 -          <ol>
   3.129 -            <li>
   3.130 -              Let <var>key</var> be the key and <var>index</var> be the <a>index</a>
   3.131 -              passed to these steps.
   3.132 -            </li>
   3.133 -            <li>
   3.134 -              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
   3.135 -              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
   3.136 -              retreive the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
   3.137 -            </li>
   3.138 -            <li>
   3.139 -              If no record was found in the previous step, then the algorithm failed with a
   3.140 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
   3.141 -            </li>
   3.142 -            <li>
   3.143 -              If a record was found, let <var>value</var> be the value of the found record. The result of
   3.144 -              this algorithm is a new <a>structured clone</a> of the value for the record with key
   3.145 -              <var>value</val> in <var>index</var>'s <a>referenced</a> <a>object store</a>
   3.146 -            </li>
   3.147 -          </ol>
   3.148 -        </section>
   3.149 -        
   3.150 -        <Section class="section">
   3.151 -          <h4>Index Value Retrieval steps</h4>
   3.152 -          <p>
   3.153 -            The <dfn>steps for retrieving a value from an index</dfn> are
   3.154 -            as follows. These steps MUST be run with two parameters - the record 
   3.155 -            key and the <a>index</a>.
   3.156 -          </p>
   3.157 -            
   3.158 -          <ol>
   3.159 -            <li>
   3.160 -              Let <var>key</var> be the key and <var>index</var> be the <a>index</a>
   3.161 -              passed to these steps.
   3.162 -            </li>
   3.163 -            <li>
   3.164 -              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
   3.165 -              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
   3.166 -              retreive the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
   3.167 -            </li>
   3.168 -            <li>
   3.169 -              If no record was found in the previous step, then the algorithm failed with a
   3.170 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
   3.171 -            </li>
   3.172 -            <li>
   3.173 -              If a record was found, the result of this algorithm is the value of the found <a>record</a>.
   3.174 -            </li>
   3.175 -          </ol>
   3.176 -        </section>
   3.177 -        
   3.178 -        <section class="section">
   3.179 -          <h4>Object Store Deletion steps</h4>
   3.180 -          <p>
   3.181 -            The <dfn>steps for deleting a record from an object store</dfn> 
   3.182 -            are as follows. These steps MUST be run with two parameters: the key
   3.183 -            of the record to be deleted and the <a>object store</a>.
   3.184 -          </p>
   3.185 -          <ol>
   3.186 -            <li>
   3.187 -              Let <var>key</var> be the key and <var>store</var> be the <a>object
   3.188 -              store</a> passed to these steps.
   3.189 -            </li>
   3.190 -            <li>
   3.191 -              If no record exists with key <var>key</var> in <var>store</var>,
   3.192 -              then terminate these steps and set error code
   3.193 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
   3.194 -            </li>            
   3.195 -            <li>
   3.196 -               If any <a title="index">indexes</a> are <a>auto-populated</a> for
   3.197 -               <var>store</var>, then remove the record in that index according 
   3.198 -               to <a>index maintenance conditions</a>.
   3.199 -            </li>
   3.200 -            
   3.201 -            <li>
   3.202 -              Remove the record from <var>store</var> with key <var>key</var>. 
   3.203 -            </li>
   3.204 -          </ol>
   3.205 -        </section>
   3.206 -        <section class="section">
   3.207 -          <h4>Index Deletion steps</h4>
   3.208 -          <p>
   3.209 -            The <dfn>steps for deleting a record from an index</dfn> 
   3.210 -            are as follows. These steps MUST be run with two parameters: the key
   3.211 -            of the record to be deleted and the <a>index</a>.
   3.212 -          </p>
   3.213 -          <ol>
   3.214 -            <li>
   3.215 -              Let <var>key</var> be the key and <var>index</var> be the <a>index</a>
   3.216 -              passed to these steps.
   3.217 -            </li>
   3.218 -            <li>
   3.219 -              If no record exists with key <var>key</var> in <var>index</var>,
   3.220 -              then terminate these steps and set error code
   3.221 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
   3.222 -            </li>            
   3.223 -            <li>
   3.224 -              Remove the records from <var>index</var> with key <var>key</var>. 
   3.225 -            </li>
   3.226 -          </ol>
   3.227 -        </section>
   3.228 -        <section class="section">
   3.229            <h4>Transaction Creation steps</h4>
   3.230            <p>
   3.231              When the user agent is to <dfn>create a static <a>transaction</a></dfn>
   3.232 @@ -489,9 +282,12 @@
   3.233                the result of the operation.
   3.234              </li>
   3.235              <li>
   3.236 -              If performing <var>operation</var> failed then set the <a title="request done">done</a> flag
   3.237 -              on the <var>request</var> to true and <a>fire a error event</a> at <var>request</var> with
   3.238 -              the code of the error from <var>operation</var>.
   3.239 +              If performing <var>operation</var> failed then revert all changes made by <var>operation</var>,
   3.240 +              set the <a title="request done">done</a> flag on the <var>request</var> to true and
   3.241 +              <a>fire a error event</a> at <var>request</var> with the code of the error from <var>operation</var>.
   3.242 +              <div class="note">
   3.243 +                This only reverts the changes done by this request, not any other changes made by the transaction.
   3.244 +              </div>
   3.245              </li>
   3.246            </ol>
   3.247          </section>
   3.248 @@ -557,7 +353,7 @@
   3.249                  This event MUST NOT bubble or be cancelable.
   3.250                </p>
   3.251              </li>
   3.252 -            <li>
   3.253 +            <li id="VERSION_CHANGE-close-block">
   3.254                Wait until all objects in <var>openDatabases</var> are <a title="database close">closed</a> and all of
   3.255                their transactions are <a title="transaction finish">finished</a>.
   3.256                <p class="issue">Should we allow <code>blocked</code> to be fired here too, if waiting takes "too long"?</p>.
   3.257 @@ -599,6 +395,11 @@
   3.258              <a title="transaction create">create</a> transactions first check the the <a>closePending</a> flag first and
   3.259              throw an exception if it is true.
   3.260            </p>
   3.261 +          <p class="note">
   3.262 +            Once the <a>connection</a> is closed, this can unblock the <a>steps for running a <code>VERSION_CHANGE</code>
   3.263 +            transaction</a>, which <a href="#VERSION_CHANGE-close-block">wait</a> for <a>connection</a>s to a given
   3.264 +            <a>database</a> to be closed before continuing.
   3.265 +          </p>
   3.266          </section>
   3.267          <section class="section">
   3.268            <h4>Fire a success event</h4>
   3.269 @@ -655,6 +456,330 @@
   3.270            </p>
   3.271          </section>
   3.272        </section>
   3.273 +      <section class="section" id="database operations">
   3.274 +        <h3>Database operations</h3>
   3.275 +        <p>
   3.276 +          This section describes various operations done on the data in <a>object store</a>s and <a>index</a>es
   3.277 +          in a <a>database</a>. These operations are run by the <a>steps for asynchronously executing a request</a> and
   3.278 +          the <a>steps for synchronously executing a request</a>.
   3.279 +        </p>
   3.280 +        <section class="section">
   3.281 +          <h4>Object Store Storage Operation</h4>
   3.282 +          <p>
   3.283 +            The <dfn>steps for storing a record into an object store</dfn> are as follows. 
   3.284 +            The algorithm run by these steps takes four parameters: a object store <var>store</var>,
   3.285 +            a <var>value</var>, an optional <var>key</var>, and a <var>no-overwrite flag</var>.
   3.286 +          </p>
   3.287 +          <ol>
   3.288 +            <li>
   3.289 +              If <var>store</var> uses a <a>key generator</a> set and <var>key</var> is undefined, set
   3.290 +              <var>key</var> to the next generated key. If <var>store</var> also uses <a>in-line keys</a>,
   3.291 +              then set the property in <var>value</var> pointed to by <var>store</var>'s
   3.292 +              <a title="object store key path">key path</a> to the new value for <var>key</var>
   3.293 +            </li>
   3.294 +            <li>
   3.295 +              If <var>store</var> does not use a <a>key generator</a> but does use <a>in-line keys</a>, then set
   3.296 +              <var>key</var> to the the result of <a title="evaluate key path">evaluting</a>
   3.297 +              <a title="object store key path"><var>store</var>'s key path</a> on <var>value</var>.
   3.298 +            </li>
   3.299 +            <li>
   3.300 +              If the no-overwrite flag was passed to these steps and is set, and 
   3.301 +              a <a>record</a> already exists in <var>store</var> with its key <a>equal to</a> <var>key</var>, then 
   3.302 +              terminate these steps and set error code to
   3.303 +              <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>
   3.304 +              and abort this algorithm without taking any further steps.
   3.305 +            </li>
   3.306 +            <li>
   3.307 +              If a <a>record</a> already exists in <var>store</var> with its key <a>equal to</a> <var>key</var>, then 
   3.308 +              remove the <a>record</a> from <a>store</a> using the <a>steps for deleting a record from an object store</a>.
   3.309 +            </li>
   3.310 +            <li>
   3.311 +              Store a record in <var>store</var> containing <var>key</var> as its key and <var>object</var> as its
   3.312 +              value. The record is stored in the the object store's <a title="objec store record list">list</a> such
   3.313 +              that the list is sorted according key of the records in ascending order.
   3.314 +            </li>
   3.315 +            <li>
   3.316 +              If there are any <a>index</a>es which <a title="referenced">reference</a> <var>store</var>, perform the
   3.317 +              following sub steps on each such index.
   3.318 +              <ol>
   3.319 +                <li>
   3.320 +                  Set <var>index</var> to the index.
   3.321 +                </li>
   3.322 +                <li>
   3.323 +                  <a title="evaluate key path">Evaluate</a> <var>index</var>'s <a title="index key path">key path</a> on
   3.324 +                  <var>value</var>. If this does not yield a value don't take any further actions for this index.
   3.325 +                  Otherwise set the result to <var>index key</var>.
   3.326 +                  <div class="note">
   3.327 +                    The places invoking these steps ensures that <var>index key</var> is always a <a>valid key</a> at this
   3.328 +                    point.
   3.329 +                </li>
   3.330 +                <li>
   3.331 +                  If <var>index</var> already contains a <a>record</a> with <a>key</a> <a>equal to</a> <var>index key</var>,
   3.332 +                  and <var>index</var> has it's <a>unique</a> flag set to true, then set error code to CONSTRAINT_ERR and
   3.333 +                  abort this algorithm without taking any further steps.
   3.334 +                </li>
   3.335 +                <li>
   3.336 +                  Store a record in <var>index</var> containig <var>index key</var> as its key and <var>key</var> as its
   3.337 +                  value. The record is stored in <var>index</var>'s <a title="index record list">list of records</a> such
   3.338 +                  that the list is sorted primarily on the records keys, and secondarily on the records values, in ascending
   3.339 +                  order.
   3.340 +                </li>
   3.341 +              </ol>
   3.342 +            </li>
   3.343 +            <li>
   3.344 +              The result of this algorithm is <var>key</var>.
   3.345 +            </li>
   3.346 +          </ol>
   3.347 +        </section>
   3.348 +        
   3.349 +        <section class="section">
   3.350 +          <h4>Object Store Retrieval Operation</h4>
   3.351 +          <p>
   3.352 +            The <dfn>steps for retrieving a value from an object store</dfn> are
   3.353 +            as follows. These steps MUST be run with two parameters - the record 
   3.354 +            key and the <a>object store</a>.
   3.355 +          </p>
   3.356 +            
   3.357 +          <ol>
   3.358 +            <li>
   3.359 +              Let <var>key</var> be the key and <var>store</var> be the <a>object
   3.360 +              store</a> passed to these steps.
   3.361 +            </li>
   3.362 +            <li>
   3.363 +              If <var>key</var> is not a <a>key range</a> then retreive the <a>record</a>
   3.364 +              with key <var>key</var> from <var>store</var>. If <var>key</var> is a <a>key range</a>, then
   3.365 +              retreive the first <a>record</a> from <var>store</var> whose key is <a title="in a key range">in</a> <var>key</var>.
   3.366 +            </li>
   3.367 +            <li>
   3.368 +              If no record was found in the previous step,
   3.369 +              then terminate these steps and set error code
   3.370 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
   3.371 +            </li>
   3.372 +            <li>
   3.373 +              The result of this algorithm is a new <a>structured clone</a> of the value in the found record.
   3.374 +            </li>
   3.375 +          </ol>
   3.376 +        </section>
   3.377 +        
   3.378 +        <section class="section">
   3.379 +          <h4>Index Referenced Value Retrieval Operation</h4>
   3.380 +          <p>
   3.381 +            The <dfn>steps for retrieving a referenced value from an index</dfn> are
   3.382 +            as follows. These steps MUST be run with two parameters - the record 
   3.383 +            key and the <a>index</a>.
   3.384 +          </p>
   3.385 +            
   3.386 +          <ol>
   3.387 +            <li>
   3.388 +              Let <var>key</var> be the key and <var>index</var> be the <a>index</a>
   3.389 +              passed to these steps.
   3.390 +            </li>
   3.391 +            <li>
   3.392 +              If <var>key</var> is not a <a>key range</a> then find the first <a>record</a>
   3.393 +              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
   3.394 +              find the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
   3.395 +            </li>
   3.396 +            <li>
   3.397 +              If no record was found in the previous step, then the algorithm failed with a
   3.398 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
   3.399 +            </li>
   3.400 +            <li>
   3.401 +              Otherwise, the result of the operation is the <a>referenced value</a> of the found record.
   3.402 +            </li>
   3.403 +          </ol>
   3.404 +        </section>
   3.405 +        
   3.406 +        <section class="section">
   3.407 +          <h4>Index Value Retrieval Operation</h4>
   3.408 +          <p>
   3.409 +            The <dfn>steps for retrieving a value from an index</dfn> are
   3.410 +            as follows. These steps MUST be run with two parameters - the record 
   3.411 +            key and the <a>index</a>.
   3.412 +          </p>
   3.413 +            
   3.414 +          <ol>
   3.415 +            <li>
   3.416 +              Let <var>key</var> be the key and <var>index</var> be the <a>index</a>
   3.417 +              passed to these steps.
   3.418 +            </li>
   3.419 +            <li>
   3.420 +              If <var>key</var> is not a <a>key range</a> then find the first <a>record</a>
   3.421 +              with key <var>key</var> from <var>index</var>. If <var>key</var> is a <a>key range</a>, then
   3.422 +              find the first <a>record</a> from <var>index</var> whose key is <a title="in a key range">in</a> <var>key</var>.
   3.423 +            </li>
   3.424 +            <li>
   3.425 +              If no record was found in the previous step, then the algorithm failed with a
   3.426 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code> error</a>.
   3.427 +            </li>
   3.428 +            <li>
   3.429 +              If a record was found, the result of this algorithm is the <a>value</a> of the found <a>record</a>.
   3.430 +            </li>
   3.431 +          </ol>
   3.432 +        </section>
   3.433 +        
   3.434 +        <section class="section">
   3.435 +          <h4>Object Store Deletion Operation</h4>
   3.436 +          <p>
   3.437 +            The <dfn>steps for deleting a record from an object store</dfn> are as follows. 
   3.438 +            The algorithm run by these steps takes two parameters: a object store <var>store</var> and
   3.439 +            a <var>key</var>.
   3.440 +          </p>
   3.441 +          <ol>
   3.442 +            <li>
   3.443 +              If no <a>record</a> exists with key <var>key</var> in <var>store</var>,
   3.444 +              then terminate these steps and set error code
   3.445 +              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>.
   3.446 +              <p class="issue">
   3.447 +                Should we instead return a boolean indicating if a record was found or not?
   3.448 +              </p>
   3.449 +            </li>            
   3.450 +            <li>
   3.451 +               Remove the record from <var>store</var> with key <var>key</var>.
   3.452 +            </li>
   3.453 +            <li>
   3.454 +              In all <a>index</a>es which <a title="referenced">reference</a> <var>store</var>, remove all
   3.455 +              <a>records</a> with value <var>key</var>.
   3.456 +            </li>
   3.457 +            <li>
   3.458 +              The result of this algorithm is <code>undefined</code>.
   3.459 +            </li>
   3.460 +          </ol>
   3.461 +        </section>
   3.462 +        <section class="section">
   3.463 +          <h4>Cursor Iteration Operation</h4>
   3.464 +          <p>
   3.465 +            The <dfn>steps for iterating a cursor</dfn> are as follows. 
   3.466 +            The algorithm run by these steps takes two parameters: a <var>cursor</var> and optional
   3.467 +            <var>key</var> to iterate to.
   3.468 +          </p>
   3.469 +          <ol>
   3.470 +            <li>
   3.471 +              Let <var>source</var> be <var>cursor</var>'s <a title="cursor source">source</a>, let
   3.472 +              <var>records</var> be list of <a>records</a> in <var>source</var>, let <var>direction</var>
   3.473 +              be <var>cursor</var>'s <a>direction</a>, let <var>position</var> be <var>cursor</var>'s
   3.474 +              <a>position</a>, let <var>object store position</var> be <var>cursor</var>'s <a>object store position</a>
   3.475 +              and let <var>range</var> be <var>cursor</var>'s <a>range</a>.
   3.476 +              <p class="note">
   3.477 +                <var>source</var> is always a <a>object store</a> or a <a>index</a>.
   3.478 +              </p>
   3.479 +              <p class="note">
   3.480 +                <var>records</var> is always sorted in ascending <a>key</a> order. In the case of
   3.481 +                <var>source</var> being an <a>index</a>, <var>records</var> is secondarily sorted in ascending
   3.482 +                <a>value</a> order.
   3.483 +              </p>
   3.484 +            </li>
   3.485 +
   3.486 +            <li>
   3.487 +              <p>
   3.488 +                If <var>direction</var> is NEXT, let <var>found record</var> be the first record in <var>records</var> which
   3.489 +                satisfy all of the following requirements:
   3.490 +              </p>
   3.491 +              <ul>
   3.492 +                <li>
   3.493 +                  If <var>key</var> is defined, the record's key is <a>greater than</a> or <a>equal to</a> <var>key</var>.
   3.494 +                </li>
   3.495 +                <li>
   3.496 +                  If <var>position</var> is defined, and <var>source</var> is a <a>object store</a>, the record's
   3.497 +                  key is <a>greater than</a> <var>position</var>.
   3.498 +                </li>
   3.499 +                <li>
   3.500 +                  If <var>position</var> is defined, and <var>source</var> is an <a>index</a>, the record's
   3.501 +                  key is <a>equal to</a> <var>position</var> and the record's value is <a>greater than</a>
   3.502 +                  <var>object store position</var> or the record's key is <a>greater than</a> <var>position</var>.
   3.503 +                </li>
   3.504 +                <li>
   3.505 +                  If <var>range</var> is defined, the record's key is <a title="in a key range">in</a> <var>range</var>.
   3.506 +                </li>
   3.507 +              </ul>
   3.508 +              <p>
   3.509 +                If <var>direction</var> is NEXT_NO_DUPLICATE, let <var>found record</var> be the first record in <var>records</var> which
   3.510 +                satisfy all of the following requirements:
   3.511 +              </p>
   3.512 +              <ul>
   3.513 +                <li>
   3.514 +                  If <var>key</var> is defined, the record's key is <a>greater than</a> or <a>equal to</a> <var>key</var>.
   3.515 +                </li>
   3.516 +                <li>
   3.517 +                  If <var>position</var> is defined, the record's key is <a>greater than</a> <var>position</var>.
   3.518 +                </li>
   3.519 +                <li>
   3.520 +                  If <var>range</var> is defined, the record's key is <a title="in a key range">in</a> <var>range</var>.
   3.521 +                </li>
   3.522 +              </ul>
   3.523 +              <p>
   3.524 +                If <var>direction</var> is PREV, let <var>found record</var> be the last record in <var>records</var> which
   3.525 +                satisfy all of the following requirements:
   3.526 +              </p>
   3.527 +              <ul>
   3.528 +                <li>
   3.529 +                  If <var>key</var> is defined, the record's key is <a>less than</a> or <a>equal to</a> <var>key</var>.
   3.530 +                </li>
   3.531 +                <li>
   3.532 +                  If <var>position</var> is defined, and <var>source</var> is a <a>object store</a>, the record's
   3.533 +                  key is <a>less than</a> <var>position</var>.
   3.534 +                </li>
   3.535 +                <li>
   3.536 +                  If <var>position</var> is defined, and <var>source</var> is an <a>index</a>, the record's
   3.537 +                  key is <a>equal to</a> <var>position</var> and the record's value is <a>less than</a>
   3.538 +                  <var>object store position</var> or the record's key is <a>less than</a> <var>position</var>.
   3.539 +                </li>
   3.540 +                <li>
   3.541 +                  If <var>range</var> is defined, the record's key is <a title="in a key range">in</a> <var>range</var>.
   3.542 +                </li>
   3.543 +              </ul>
   3.544 +              <p>
   3.545 +                If <var>direction</var> is PREV_NO_DUPLICATE, let <var>temp record</var> be the last record in
   3.546 +                <var>records</var> which satisfy all of the following requirements:
   3.547 +              </p>
   3.548 +              <ul>
   3.549 +                <li>
   3.550 +                  If <var>key</var> is defined, the record's key is <a>less than</a> or <a>equal to</a> <var>key</var>.
   3.551 +                </li>
   3.552 +                <li>
   3.553 +                  If <var>position</var> is defined, the record's key is <a>less than</a> <var>position</var>.
   3.554 +                </li>
   3.555 +                <li>
   3.556 +                  If <var>range</var> is defined, the record's key is <a title="in a key range">in</a> <var>range</var>.
   3.557 +                </li>
   3.558 +              </ul>
   3.559 +              <p>
   3.560 +                If <var>temp record</var> is defined, let <var>found record</var> be the first record in <var>records</var>
   3.561 +                whose key is <a>equal to</a> <var>temp record</var>'s key.
   3.562 +              </p>
   3.563 +            </li>
   3.564 +            <li>
   3.565 +              If <var>found record</var> is not defined, the result of this algorithm is <code>undefined</code>. Abort these steps.
   3.566 +            </li>
   3.567 +            <li>
   3.568 +              <p>
   3.569 +                Set <var>cursor</var>'s <a>position</a> to <var>found record</var>'s key. If <var>source</var> is a <a>index</a>,
   3.570 +                set <var>cursor</var>'s <a>object store position</a> to <var>found record</var>'s value.
   3.571 +              </p>
   3.572 +            </li>
   3.573 +            <li>
   3.574 +              <p>
   3.575 +                Set <var>cursor</var>'s <a title="cursor key">key</a> to <var>found record</var>'s key.
   3.576 +              </p>
   3.577 +              <p>
   3.578 +                If <var>cursor</var> was created using <a href="#widl-IDBIndex-openCursor"><code>IDBIndex.openCursor</code></a> or
   3.579 +                <a href="#widl-IDBIndexSync-openCursor"><code>IDBIndexSync.openCursor</code></a>, then set
   3.580 +                <var>cursor</var>'s <a title="cursor value">value</a> to <var>found record</var> <a>referenced value</a>. Otherwise, set
   3.581 +                <var>cursor</var>'s <a title="cursor value">value</a> to the value of <var>found record</var>.
   3.582 +              </p>
   3.583 +            </li>
   3.584 +            <li>
   3.585 +              Set <var>cursor</var>'s <a>got value</a> flag to true.
   3.586 +              <p class="issue">
   3.587 +                This should only be done right before firing the success event. Not asynchronously before. Not sure
   3.588 +                how/where to express that.
   3.589 +              </p>
   3.590 +            </li>
   3.591 +            <li>
   3.592 +              The result of the algorithm is <var>cursor</var>.
   3.593 +            </li>
   3.594 +          </ol>
   3.595 +        </section>
   3.596 +      </section>
   3.597        <!-- end-content -->
   3.598      </section>
   3.599    </body>
     4.1 --- a/Speclet_022_IDB_API_Synchronous_APIs.html	Wed Nov 03 17:12:19 2010 +0100
     4.2 +++ b/Speclet_022_IDB_API_Synchronous_APIs.html	Mon Nov 08 03:30:39 2010 -0800
     4.3 @@ -494,7 +494,7 @@
     4.4              <dd>
     4.5                Retrieve the value from this <a>object store</a> for the record 
     4.6                corresponding to the given key by following the
     4.7 -              <a>steps for retrieving a record from an object store</a>. The
     4.8 +              <a>steps for retrieving a value from an object store</a>. The
     4.9                value returned from this method is the retrieved value.
    4.10                <dl class="parameters">
    4.11                  <dt>any key</dt>
    4.12 @@ -706,7 +706,7 @@
    4.13              <dd>
    4.14                Retrieve the value from this <a>index</a>'s <a>referenced</a>
    4.15                <a>object store</a> for the record corresponding to the given key
    4.16 -              by following the <a>steps for retrieving a record from an index</a>.
    4.17 +              by following the <a>steps for retrieving a referenced value from an index</a>.
    4.18                The value returned from this method is the retrieved value.
    4.19                <dl class="parameters">
    4.20                  <dt>any key</dt>
    4.21 @@ -855,10 +855,6 @@
    4.22                  <a>index</a> is <a>auto-populated</a>.</dd>
    4.23                </dl>
    4.24              </dd>
    4.25 -            <dt>readonly attribute unsigned long long count</dt>
    4.26 -            <dd>             
    4.27 -              On getting, provide the approximate number of objects in the cursor.
    4.28 -            </dd>
    4.29  
    4.30              <dt>boolean  continue()</dt>
    4.31              <dd>
     5.1 --- a/Speclet_023_IDB_API_Asynchronous_APIs.html	Wed Nov 03 17:12:19 2010 +0100
     5.2 +++ b/Speclet_023_IDB_API_Asynchronous_APIs.html	Mon Nov 08 03:30:39 2010 -0800
     5.3 @@ -533,105 +533,142 @@
     5.4              </dd>
     5.5              <dt>IDBRequest put()</dt>
     5.6              <dd>
     5.7 -              This method returns immediately and stores the given value in this 
     5.8 -              <a>object store</a> by following the 
     5.9 -              <a>steps for storing a record into an object store</a>. If the 
    5.10 -              <a>record</a> can be successfully stored in the <a>object store</a>, then 
    5.11 -              a <a title="event-success">success event</a> is fired on this 
    5.12 -              method's returned object using the 
    5.13 -              <a><code>IDBTransactionEvent</code></a> interface with its 
    5.14 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to
    5.15 -              the key for the stored <a>record</a> and 
    5.16 -              <a class="idlType" href="#widl-IDBTransactionEvent-transaction"><code>transaction</code></a> 
    5.17 -              set to the <a>transaction</a> in which this <a>object store</a> is 
    5.18 -              opened.
    5.19 +              <p>
    5.20 +                This method throws a NOT_ALLOWED_ERR if the transaction which this IDBObjectStore belongs to is
    5.21 +                has its <a>mode</a> set to READ_ONLY. If any of the following conditions are true, this method
    5.22 +                throws a DATA_ERR exception:
    5.23 +              </p>
    5.24 +              <ul>
    5.25 +                <li>
    5.26 +                  The object store uses <a>in-line keys</a> or has a <a>key generator</a> and
    5.27 +                  the <var>key</var> parameter was provided.
    5.28 +                </li>
    5.29 +                <li>
    5.30 +                  The object store uses <a>out-of-line keys</a> and has no <a>key generator</a>
    5.31 +                  and the <var>key</var> parameter was not provided.
    5.32 +                </li>
    5.33 +                <li>
    5.34 +                  The object store uses <a>in-line keys</a> but no <a>key generator</a>
    5.35 +                  and the result of <a title="evaluate key path">evaluating</a> the 
    5.36 +                  <a title="object store key path">object store's key path</a> does not yield a
    5.37 +                  <a>valid key</a>.
    5.38 +                </li>
    5.39 +                <li>
    5.40 +                  The <var>key</var> parameter was provided but does not contain a <a>valid key</a>.
    5.41 +                </li>
    5.42 +                <li>
    5.43 +                  If there are any <a>index</a>es <a title="referenced">referencing</a> this object
    5.44 +                  store and <a title="evaluate key path">evaluating</a> their key path on the
    5.45 +                  <var>value</var> parameter yields a value and that value is not a <a>valid key</a>.
    5.46 +                </li>
    5.47 +              </ul>
    5.48 +              <p>
    5.49 +                Otherwise this method creates a <a>structured clone</a> of the <var>value</var> parameter.
    5.50 +                If this throws an exception that exception is rethrown. It then runs the <a>steps for
    5.51 +                asynchronously executing a request</a> and returns the <a>IDBRequest</a> created by these steps.
    5.52 +                The steps are run with this <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for
    5.53 +                storing a record into an object store</a> as <var>operation</var>, using this <a>IDBObjectStore</a>
    5.54 +                as <var>store</var>, the created clone as <var>value</var>, the <var>key</var> parameter as
    5.55 +                <var>key</var>, and with the <var>no-overwrite flag</var> flag set to false.
    5.56 +              </p>
    5.57                <dl class="parameters">
    5.58                  <dt>any value</dt>
    5.59                  <dd>The value to be stored in the <a>record</a></dd>
    5.60                  <dt>optional any key</dt>
    5.61 -                <dd>The key used to identify the <a>record</a>, which defaults 
    5.62 -                to <code>null</code></dd>
    5.63 +                <dd>The key used to identify the <a>record</a></dd>
    5.64                </dl>
    5.65                <dl class="exception" title="IDBDatabaseException">
    5.66 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
    5.67 +                <dd>The <a>transaction</a> this <a>IDBObjectStore</a> belongs to is not <a>active</a>.</dd>
    5.68                  <dt>NOT_ALLOWED_ERR</dt>
    5.69 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
    5.70 -                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>.</dd>
    5.71 +                <dd>The <a>mode</a> of the associated <a>transaction</a> is <code>READ_ONLY</code>.</dd>
    5.72                  <dt>DATA_ERR</dt>
    5.73 -                <dd>This <a>object store</a> uses <a>out-of-line keys</a> and
    5.74 -                no <a>key generator</a> but the <var>key</var> parameter was not
    5.75 -                passed, or the <a>object store</a> uses <a>in-line keys</a> and
    5.76 -                no <a>key generator</a> but the <var>value</var> object does not
    5.77 -                have a property identified by the store's 
    5.78 -                <a title="object store key path">key path</a>.</dd>
    5.79 -                <dt>SERIAL_ERR</dt>
    5.80 -                <dd>The data being stored could not be serialized by the internal
    5.81 +                <dd>The calculated key for the insertion was not a <a>valid key</a>. Also thrown if the
    5.82 +                calculated key for any of the indexes which belong to this object store had a calculated
    5.83 +                key which was not a <a>valid key</a></dd>
    5.84 +              </dl>
    5.85 +              <dl class="exception" title="DOMException">
    5.86 +                <dt>DATA_CLONE_ERR</dt>
    5.87 +                <dd>The data being stored could not be cloned by the internal
    5.88                  structured cloning algorithm.</dd>
    5.89                </dl>
    5.90              </dd>
    5.91              <dt>IDBRequest add()</dt>
    5.92              <dd>
    5.93 -              This method returns immediately and stores the given value in this 
    5.94 -              <a>object store</a> by following the 
    5.95 -              <a>steps for storing a record into an object store</a> with the 
    5.96 -              no-overwrite flag set. If the <a>record</a> can be successfully 
    5.97 -              stored in the <a>object store</a>, then a 
    5.98 -              <a title="event-success">success event</a> is fired on this 
    5.99 -              method's returned object using the 
   5.100 -              <a><code>IDBTransactionEvent</code></a> interface with its 
   5.101 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to
   5.102 -              the key for the stored record and 
   5.103 -              <a class="idlType" href="#widl-IDBTransactionEvent-transaction"><code>transaction</code></a> 
   5.104 -              set to the <a>transaction</a> in which this <a>object store</a> is 
   5.105 -              opened. If a <a>record</a> exists in this <a>object store</a> for 
   5.106 -              the key <var>key</var> parameter, then an
   5.107 -              <a title="event-error">error event</a> is fired on this method's
   5.108 -              returned object with its 
   5.109 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   5.110 -              <a class="idlType" href="#widl-IDBDatabaseException-CONSTRAINT_ERR"><code>CONSTRAINT_ERR</code></a>
   5.111 +              <p>
   5.112 +                This method throws a NOT_ALLOWED_ERR if the transaction which this IDBObjectStore belongs to is
   5.113 +                has its <a>mode</a> set to READ_ONLY. If any of the following conditions are true, this method
   5.114 +                throws a DATA_ERR exception:
   5.115 +              </p>
   5.116 +              <ul>
   5.117 +                <li>
   5.118 +                  The object store uses <a>in-line keys</a> or has a <a>key generator</a> and
   5.119 +                  the <var>key</var> parameter was provided.
   5.120 +                </li>
   5.121 +                <li>
   5.122 +                  The object store uses <a>out-of-line keys</a> and has no <a>key generator</a>
   5.123 +                  and the <var>key</var> parameter was not provided.
   5.124 +                </li>
   5.125 +                <li>
   5.126 +                  The object store uses <a>in-line keys</a> but no <a>key generator</a>
   5.127 +                  and the result of <a title="evaluate key path">evaluating</a> the 
   5.128 +                  <a title="object store key path">object store's key path</a> does not yield a
   5.129 +                  <a>valid key</a>.
   5.130 +                </li>
   5.131 +                <li>
   5.132 +                  The <var>key parameter was provided but does not contain a <a>valid key</a>.
   5.133 +                </li>
   5.134 +                <li>
   5.135 +                  If there are any <a>index</a>es <a title="referenced">referencing</a> this object
   5.136 +                  store and <a title="evaluate key path">evaluating</a> their key path on the
   5.137 +                  <var>value</var> parameter yields a value and that value is not a <a>valid key</a>.
   5.138 +                </li>
   5.139 +              </ul>
   5.140 +              <p>
   5.141 +                Otherwise this method creates a <a>structured clone</a> of the <var>value</var> parameter.
   5.142 +                If this throws an exception that exception is rethrown. It then runs the <a>steps for
   5.143 +                asynchronously executing a request</a> and returns the <a>IDBRequest</a> created by these steps.
   5.144 +                The steps are run with this <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for
   5.145 +                storing a record into an object store</a> as <var>operation</var>, using this <a>IDBObjectStore</a>
   5.146 +                as <var>store</var>, the created clone as <var>value</var>, the <var>key</var> parameter as
   5.147 +                <var>key</var>, and with the <var>no-overwrite flag</var> flag set to true.
   5.148 +              </p>
   5.149                <dl class="parameters">
   5.150                  <dt>any value</dt>
   5.151                  <dd>The value to be stored in the <a>record</a></dd>
   5.152                  <dt>optional any key</dt>
   5.153 -                <dd>The key used to identify the <a>record</a>, which defaults 
   5.154 -                to <code>null</code></dd>
   5.155 +                <dd>The key used to identify the <a>record</a></dd>
   5.156                </dl>
   5.157                <dl class="exception" title="IDBDatabaseException">
   5.158 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   5.159 +                <dd>The <a>transaction</a> this <a>IDBObjectStore</a> belongs to is not <a>active</a>.</dd>
   5.160                  <dt>NOT_ALLOWED_ERR</dt>
   5.161 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
   5.162 -                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>.</dd>
   5.163 +                <dd>The <a>mode</a> of the associated <a>transaction</a> is <code>READ_ONLY</code>.</dd>
   5.164                  <dt>DATA_ERR</dt>
   5.165 -                <dd>This <a>object store</a> uses <a>out-of-line keys</a> and
   5.166 -                no <a>key generator</a> but the <var>key</var> parameter was not
   5.167 -                passed, or the <a>object store</a> uses <a>in-line keys</a> and
   5.168 -                no <a>key generator</a> but the <var>value</var> object does not
   5.169 -                have a property identified by the store's
   5.170 -                <a title="object store key path">key path</a>.</dd>
   5.171 -                <dt>SERIAL_ERR</dt>
   5.172 -                <dd>The data being stored could not be serialized by the internal
   5.173 +                <dd>The calculated key for the insertion was not a <a>valid key</a>. Also thrown if the
   5.174 +                calculated key for any of the indexes which belong to this object store had a calculated
   5.175 +                key which was not a <a>valid key</a></dd>
   5.176 +              </dl>
   5.177 +              <dl class="exception" title="DOMException">
   5.178 +                <dt>DATA_CLONE_ERR</dt>
   5.179 +                <dd>The data being stored could not be cloned by the internal
   5.180                  structured cloning algorithm.</dd>
   5.181                </dl>
   5.182              </dd>
   5.183              <dt>IDBRequest delete()</dt>
   5.184              <dd>
   5.185 -              This method returns immediately and deletes the <a>record</a> from 
   5.186 -              this <a>object store</a> by following the 
   5.187 -              <a>steps for deleting a record from an object store</a> 
   5.188 -              corresponding to the given key. If a <a>record</a> did not exist 
   5.189 -              in this <a>object store</a> for the <var>key</var> parameter, 
   5.190 -              then an <a title="event-error">error event</a> is fired on this 
   5.191 -              method's returned object with its 
   5.192 -              <a class="idlType" href="#widl-IDBErrorEvent-code"><code>code</code></a> set to
   5.193 -              <a class="idlType" href="#widl-IDBDatabaseException-NOT_FOUND_ERR"><code>NOT_FOUND_ERR</code></a>
   5.194 -              and a suitable 
   5.195 -              <a class="idlType" href="#widl-IDBErrorEvent-message"><code>message</code></a>. If the <a>record</a> can be successfully 
   5.196 -              deleted from the <a>object store</a>, then a 
   5.197 -              <a title="event-success">success event</a> is fired on this 
   5.198 -              method's returned object using the 
   5.199 -              <a><code>IDBTransactionEvent</code></a> interface with its 
   5.200 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to
   5.201 -              the value of the deleted <a>record</a> and <a class="idlType" href="#widl-IDBTransactionEvent-transaction"><code>transaction</code></a> 
   5.202 -              set to the <a>transaction</a> in which this <a>object store</a> is 
   5.203 -              opened. 
   5.204 +              <p>
   5.205 +                This method throws a NOT_ALLOWED_ERR if the transaction which this IDBObjectStore belongs to is
   5.206 +                has its <a>mode</a> set to READ_ONLY. If the <var>key</var> parameter is not a <a>valid key</var>
   5.207 +                this method throws a DATA_ERR exception.
   5.208 +              </p>
   5.209 +              <p>
   5.210 +                Otherwise this method runs the <a>steps for
   5.211 +                asynchronously executing a request</a> and returns the <a>IDBRequest</a> created by these steps.
   5.212 +                The steps are run with this <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for deleting
   5.213 +                a record from an object store</a> as <var>operation</var>, using this <a>IDBObjectStore</a>
   5.214 +                as <var>store</var> and the <var>key</var> parameter as <var>key</var>.
   5.215 +              </p>
   5.216                <dl class="parameters">
   5.217                  <dt>any key</dt>
   5.218                  <dd>Key identifying the <a>record</a> to be deleted</dd>
   5.219 @@ -647,7 +684,7 @@
   5.220                If the <var>key</var> parameter is not a valid <a>key value</a> or a <a>key range</a>, this method
   5.221                throws a DATA_ERR exception. Otherwise, this method runs the <a>steps for asynchronously executing
   5.222                a request</a> and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   5.223 -              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a record from an
   5.224 +              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a value from an
   5.225                object store</a> as <var>operation</var>, using this <a>IDBObjectStore</a> as <var>store</var> and the
   5.226                <var>key</var> parameter as <var>key</var>.
   5.227                <dl class="parameters">
   5.228 @@ -665,27 +702,24 @@
   5.229              <dt>IDBRequest openCursor()</dt>
   5.230              <dd>
   5.231                <p>
   5.232 -                This method returns immediately and creates a <a>cursor</a> over the 
   5.233 -                <a>records</a> of this <a>object store</a>.
   5.234 +                If the <var>range</var> parameter is specified but is not a valid <a>key value</a> or a <a>key range</a>,
   5.235 +                this method throws a DATA_ERR exception. Otherwise, this method creates a <a>cursor</a> with an undefined
   5.236 +                <a>position</a>, a <a>direction</a> set to the value of the <var>direction</var> parameter, false as
   5.237 +                <a>iterable</a> flag value, and undefined <a title="cursor key">key</a> and
   5.238 +                <a title="cursor value">value</a>. The <a title="cursor source">source</a> of the cursor is the
   5.239 +                <a>IDBObjectStore</a> this function was called on.
   5.240                </p>
   5.241                <p>
   5.242 -                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
   5.243 -                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
   5.244 -                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
   5.245 -                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
   5.246 -                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
   5.247 +                If the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a> is set to that
   5.248 +                range. Otherwise, if the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a>
   5.249 +                is set to <a>key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
   5.250 +                the cursor's key range is left as undefined.
   5.251                </p>
   5.252                <p>
   5.253 -                If there is even a single record that matches the <a>key range</a>, then a
   5.254 -                <a title="event-success">success event</a> is fired on this method's
   5.255 -                returned object with its 
   5.256 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   5.257 -                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   5.258 -                records match the <a>key range</a>, then an 
   5.259 -                <a title="event-success">success event</a> is fired on this method's
   5.260 -                returned object with its
   5.261 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   5.262 -                set to <code>null</code>.
   5.263 +                This method runs the <a>steps for asynchronously executing a request</a> and returns the <a>IDBRequest</a>
   5.264 +                created by these steps. The steps are run with this <a>IDBObjectStore</a> as <var>source</var> and the
   5.265 +                <a>steps for iterating a cursor</a> as <var>operation</var>,
   5.266 +                using the created cursor as <var>cursor</var> and with undefined as <var>key</var>.
   5.267                </p>
   5.268                <dl class="parameters">
   5.269                  <dt>optional any            range</dt>
   5.270 @@ -803,28 +837,24 @@
   5.271              <dt>IDBRequest openCursor()</dt>
   5.272              <dd>
   5.273                <p>
   5.274 -                This method returns immediately and creates a <a>cursor</a> over the 
   5.275 -                <a>records</a> of this <a>index</a>'s <a>referenced</a> <a>object store</a> 
   5.276 -                as arranged by this <a>index</a>.
   5.277 +                If the <var>range</var> parameter is specified but is not a valid <a>key value</a> or a <a>key range</a>,
   5.278 +                this method throws a DATA_ERR exception. Otherwise, this method creates a <a>cursor</a> with an undefined
   5.279 +                <a>position</a>, a <a>direction</a> set to the value of the <var>direction</var> parameter, false as
   5.280 +                <a>iterable</a> flag value, and undefined <a title="cursor key">key</a> and
   5.281 +                <a title="cursor value">value</a>. The <a title="cursor source">source</a> of the cursor is the
   5.282 +                <a>IDBIndex</a> this function was called on.
   5.283                </p>
   5.284                <p>
   5.285 -                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
   5.286 -                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
   5.287 -                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
   5.288 -                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
   5.289 -                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
   5.290 +                If the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a> is set to that
   5.291 +                range. Otherwise, if the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a>
   5.292 +                is set to <a>key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
   5.293 +                the cursor's key range is left as undefined.
   5.294                </p>
   5.295                <p>
   5.296 -                If there is even a single record that matches the <a>key range</a>, then a
   5.297 -                <a title="event-success">success event</a> is fired on this method's
   5.298 -                returned object with its 
   5.299 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   5.300 -                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   5.301 -                records match the <a>key range</a>, then an 
   5.302 -                <a title="event-success">success event</a> is fired on this method's
   5.303 -                returned object with its
   5.304 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   5.305 -                set to <code>null</code>.
   5.306 +                This method runs the <a>steps for asynchronously executing
   5.307 +                a request</a> and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   5.308 +                <a>IDBIndex</a> as <var>source</var> and the <a>steps for iterating a cursor</a> as <var>operation</var>,
   5.309 +                using the created cursor as <var>cursor</var> and with undefined as <var>key</var>
   5.310                </p>
   5.311                <dl class="parameters">
   5.312                  <dt>optional IDBKeyRange    range</dt>
   5.313 @@ -842,27 +872,24 @@
   5.314              <dt>IDBRequest openKeyCursor()</dt>
   5.315              <dd>
   5.316                <p>
   5.317 -                This method returns immediately and creates a <a>cursor</a> over the 
   5.318 -                <a>records</a> of this <a>index</a>.
   5.319 +                If the <var>range</var> parameter is specified but is not a valid <a>key value</a> or a <a>key range</a>,
   5.320 +                this method throws a DATA_ERR exception. Otherwise, this method creates a <a>cursor</a> with an undefined
   5.321 +                <a>position</a>, a <a>direction</a> set to the value of the <var>direction</var> parameter, false as
   5.322 +                <a>iterable</a> flag value, and undefined <a title="cursor key">key</a> and
   5.323 +                <a title="cursor value">value</a>. The <a title="cursor source">source</a> of the cursor is the
   5.324 +                <a>IDBIndex</a> this function was called on.
   5.325                </p>
   5.326                <p>
   5.327 -                If the <var>range</var> parameter passed to the funciton is a <a><code>IDBKeyRange</code></a>,
   5.328 -                the <a>range</a> of this <a>cursor</a> matches that <a>key range</a>. If the <var>range</var>
   5.329 -                is a <a>key value</a> then the range matches a <a>key range</a> which includes only that
   5.330 -                value. If the <var>range</var> parameter is not specified, or is <code>null</code> then the
   5.331 -                range includes all the <a>records</a>. Otherwise, throw a DATA_ERR exception.
   5.332 +                If the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a> is set to that
   5.333 +                range. Otherwise, if the <var>range</var> parameter is a <a>key range</a> then the cursor's <a>range</a>
   5.334 +                is set to <a>key range</a> containing only that key value. If the <var>range</var> parameter is not specified,
   5.335 +                the cursor's key range is left as undefined.
   5.336                </p>
   5.337                <p>
   5.338 -                If there is even a single record that matches the <a>key range</a>, then a
   5.339 -                <a title="event-success">success event</a> is fired on this method's
   5.340 -                returned object with its 
   5.341 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a> set to the
   5.342 -                <a><code>IDBCursor</code></a> object for that <a>cursor</a>. If no
   5.343 -                records match the <a>key range</a>, then an 
   5.344 -                <a title="event-success">success event</a> is fired on this method's
   5.345 -                returned object with its
   5.346 -                <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   5.347 -                set to <code>null</code>.
   5.348 +                This method runs the <a>steps for asynchronously executing
   5.349 +                a request</a> and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   5.350 +                <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for iterating a cursor</a> as <var>operation</var>,
   5.351 +                using the created cursor as <var>cursor</var> and with undefined as <var>key</var>
   5.352                </p>
   5.353                <dl class="parameters">
   5.354                  <dt>optional IDBKeyRange    range</dt>
   5.355 @@ -882,7 +909,7 @@
   5.356                If the <var>key</var> parameter is not a valid <a>key value</a> or a <a>key range</a>, this method
   5.357                throws a DATA_ERR exception. This method runs the <a>steps for asynchronously executing a request</a>
   5.358                and returns the <a>IDBRequest</a> created by these steps. The steps are run with this
   5.359 -              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a record from an
   5.360 +              <a>IDBObjectStore</a> as <var>source</var> and the <a>steps for retrieving a referenced value from an
   5.361                index</a> as <var>operation</var>, using this <a>IDBIndex</a> as <var>index</var> and the
   5.362                <var>key</var> parameter as <var>key</var>.
   5.363                <dl class="parameters">
   5.364 @@ -961,65 +988,107 @@
   5.365              <dd>The key for the record at the <a>cursor</a>'s <a>position</a>.</dd>
   5.366              <dt>readonly attribute any value</dt>
   5.367              <dd>The value for the record at the <a>cursor</a>'s <a>position</a>.</dd>
   5.368 -            <dt>readonly attribute unsigned long long count</dt>
   5.369 -            <dd>             
   5.370 -              On getting, provide the approximate number of objects in the cursor.
   5.371 -            </dd>
   5.372 +
   5.373              <dt>IDBRequest update(in any value)</dt>
   5.374              <dd>
   5.375 -              This method returns immediately and sets the value for the record at the
   5.376 -              <a>cursor</a>'s <a>position</a>.
   5.377 +              <p>
   5.378 +                This method throws a NOT_ALLOWED_ERR if the transaction which this IDBCursor belongs to
   5.379 +                has its <a>mode</a> set to READ_ONLY, or if this cursor's <a>got value</a> flag is false. If the
   5.380 +                <a>effective object store</a> of this cursor uses <a>in-line</a>
   5.381 +                keys and <a title="evaluate key path">evaluating</a> the <a title="object store key path">key path</a>
   5.382 +                of the <var>value</var> parameter results in a different value than the cursor's <a>effective key</a>,
   5.383 +                this method throws DATA_ERR.
   5.384 +              </p>
   5.385 +              <p>
   5.386 +                Otherwise this method creates a <a>structured clone</a> of the <var>value</var> parameter.
   5.387 +                If this throws an exception that exception is rethrown. It then runs the <a>steps for
   5.388 +                asynchronously executing a request</a> and returns the <a>IDBRequest</a> created by these steps.
   5.389 +                The steps are run with this IDBCursor as <var>source</var> and the <a>steps for
   5.390 +                storing a record into an object store</a> as <var>operation</var>, using this cursor's
   5.391 +                <a>effective object store</a> as <var>store</var>, the created clone as <var>value</var>,
   5.392 +                this cursor's <a>effective key</a> as <var>key</var>, and with the <var>no-overwrite flag</var>
   5.393 +                flag set to false.
   5.394 +              </p>
   5.395 +              <p class="issue">
   5.396 +                Should this fire an error if the record had been deleted since we iterated to it? I.e. should
   5.397 +                this never be able to create a new record?
   5.398 +              </p>
   5.399 +              <p>
   5.400 +                Otherwise this method runs the <a>steps for asynchronously executing a request</a> and returns the
   5.401 +                <a>IDBRequest</a> created by these steps. The steps are run with this <a>IDBCursor</a> as <var>source</var>
   5.402 +                and the <a>steps for deleting a record from an object store</a> as <var>operation</var>, using this cursor's
   5.403 +                <a>effective object store</a> and <a>effective key</a> as <var>store</var> and <var>key</var> respectively.
   5.404 +              </p>
   5.405                <dl class="exception" title="IDBDatabaseException">
   5.406 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   5.407 +                <dd>The <a>transaction</a> this <a>IDBCursor</a> belongs to is not <a>active</a>.</dd>
   5.408                  <dt>NOT_ALLOWED_ERR</dt>
   5.409                  <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
   5.410                  the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>. Also
   5.411                  thrown if cursor was created using
   5.412                  <a class="idlType" href="#widl-IDBIndex-openKeyCursor"><code>openKeyCursor</code></a>.</dd>
   5.413                  <dt>DATA_ERR</dt>
   5.414 -                <dd> The underlying <a>object store</a> uses <a>in-line keys</a> and the property at the 
   5.415 -                <a title="object store key path">key path</a> does not match the key in this <a>cursor</a>'s
   5.416 +                <dd> The underlying <a>object store</a> uses <a>in-line keys</a> and the property in <var>value</var>
   5.417 +                at the object store's <a title="object store key path">key path</a> does not match the key in this <a>cursor</a>'s
   5.418                  <a>position</a>.</dd>
   5.419 -                <dt>SERIAL_ERR</dt>
   5.420 -                <dd>The data being stored could not be serialized by the internal structured cloning
   5.421 -                algorithm.</dd>
   5.422 +              </dl>
   5.423 +              <dl class="exception" title="DOMException">
   5.424 +                <dt>DATA_CLONE_ERR</dt>
   5.425 +                <dd>The data being stored could not be cloned by the internal
   5.426 +                structured cloning algorithm.</dd>
   5.427                </dl>
   5.428              </dd>
   5.429              <dt>void    continue()</dt>
   5.430              <dd>
   5.431 -              This method returns immediately and advances the <a>cursor</a> to the next
   5.432 -              position along its <a>direction</a> to the item whose key matches the
   5.433 -              optional parameter. If no such parameter is provided, advance to the
   5.434 -              immediate next position. If the <a>cursor</a> has reached the end of its
   5.435 -              <a>range</a>, then a
   5.436 -              <a title="event-success">success event</a> is fired on the
   5.437 -              <a><code>IDBRequest</code></a> object that was returned when the cursor
   5.438 -              was opened, with its
   5.439 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   5.440 -              set to <code>null</code>. Otherwise, a
   5.441 -              <a title="event-success">success event</a> is fired on the
   5.442 -              <a><code>IDBRequest</code></a> object that was returned when the cursor
   5.443 -              was opened, with its
   5.444 -              <a class="idlType" href="#widl-IDBSuccessEvent-result"><code>result</code></a>
   5.445 -              set to the corresponding <a><code>IDBCursor</code></a> object.
   5.446 +              <p>
   5.447 +                If the <var>key</var> parameter is specified but is not a <a>valid key</a>,
   5.448 +                this method throws a DATA_ERR exception. If this cursor's <a>got value</a> flag is false, this method
   5.449 +                throws a NOT_ALLOWED_ERR. Otherwise this method runs the <a>steps for asynchronously executing a request</a>.
   5.450 +                However, the steps are slightly modified such that instead of creating a new IDBRequest, it reuses the
   5.451 +                <a>request</a> originally created when this cursor was created. The <a title="request done">done</a> flag
   5.452 +                on the request is set to false before the request is returned.  The steps are run with the cursor's
   5.453 +                <a title="cursor source">source</a> as <var>source</var> and the <a>steps for iterating a cursor</a> as <var>operation</var>,
   5.454 +                using the created cursor as <var>cursor</var> and the <var>key</var> parameter as <var>key</var>.
   5.455 +              </p>
   5.456 +              <p>
   5.457 +                Before this method returns, unless an exception was thrown, it sets the <a>got value</a> flag fn the cursor to false.
   5.458 +              </p>
   5.459                <dl class="parameters">
   5.460                  <dt>optional any key</dt>
   5.461                  <dd>The next key to position this <a>cursor</a> at</dd>
   5.462                </dl>
   5.463 +              <dl class="exception" title="IDBDatabaseException">
   5.464 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   5.465 +                <dd>The <a>transaction</a> this <a>IDBCursor</a> belongs to is not <a>active</a>.</dd>
   5.466 +                <dt>NOT_ALLOWED_ERR</dt>
   5.467 +                <dd>This <a>got value</a> on the cursor is set to false.</dd>
   5.468 +                <dt>DATA_ERR</dt>
   5.469 +                <dd>The <var>key</var> parameter was specified but did not contain a <a>valid key</a>.</dd>
   5.470 +              </dl>
   5.471              </dd>
   5.472              
   5.473              <dt>IDBRequest    delete()</dt>
   5.474              <dd>          
   5.475                <p>
   5.476 -                This method returns immediately and deletes the object at the 
   5.477 -                <a>cursor</a>'s <a>position</a>. The cursor's
   5.478 -                position is not changed. Any attempts to retrieve the cursor's
   5.479 -                current value will return <code>null</code>.
   5.480 +                This method throws a NOT_ALLOWED_ERR if the transaction which this IDBCursor belongs to
   5.481 +                has its <a>mode</a> set to READ_ONLY, or if this cursor's <a>got value</a> flag is false.
   5.482 +              </p>
   5.483 +              <p>
   5.484 +                Otherwise this method runs the <a>steps for asynchronously executing a request</a> and returns the
   5.485 +                <a>IDBRequest</a> created by these steps. The steps are run with this <a>IDBCursor</a> as <var>source</var>
   5.486 +                and the <a>steps for deleting a record from an object store</a> as <var>operation</var>, using this cursor's
   5.487 +                <a>effective object store</a> and <a>effective key</a> as <var>store</var> and <var>key</var> respectively.
   5.488 +              </p>
   5.489 +              <p class="issue">
   5.490 +                This method used to set this cursor's <a title="cursor value">value</a> to <code>null</code>. Do we want to
   5.491 +                keep that?
   5.492                </p>
   5.493                <dl class="exception" title="IDBDatabaseException">
   5.494 +                <dt>TRANSACTION_INACTIVE_ERR</dt>
   5.495 +                <dd>The <a>transaction</a> this <a>IDBCursor</a> belongs to is not <a>active</a>.</dd>
   5.496                  <dt>NOT_ALLOWED_ERR</dt>
   5.497 -                <dd>This <a>object store</a> is not in the <a>scope</a> of any existing <a>transaction</a> or
   5.498 -                the associated <a>transaction</a> <a><code>mode</code></a> is <code>READ_ONLY</code>. Also
   5.499 -                thrown if cursor was created using
   5.500 +                <dd>The <a>mode</a> of the <a>transaction</a> this <a>IDBCursor</a> belongs to is not <a>active</a>
   5.501 +                is <code>READ_ONLY</code>. Also thrown if cursor was created using
   5.502                  <a class="idlType" href="#widl-IDBIndex-openKeyCursor"><code>openKeyCursor</code></a>.</dd>
   5.503                </dl>
   5.504              </dd>