Initial sketch of manual commit

inexorabletash · inexorabletash · commit b4bb434eff2e · 2020-05-19T13:11:01.000-07:00
fix/add 'new in this edition' hints

version history

invert flag check

don't let tx go inactive

post-rebase cleanup
diff --git a/index.bs b/index.bs
@@ -934,6 +934,8 @@ following:
     instead is created automatically when an
     <a event>`upgradeneeded`</a> event is fired.
 
+A [=/transaction=] has an <dfn>manual commit flag</dfn>, which is initially false. By default, transactions commit automatically when all outstanding requests have been processed. This can be behavior can be modified by options set when creating the transaction.
+
 A [=/transaction=] has a <dfn>durability hint</dfn>. This is a hint to the user agent of whether to prioritize performance or durability when committing the transaction. The [=transaction/durability hint=] is one of the following:
 
 : {{"strict"}}
@@ -1041,10 +1043,11 @@ The <dfn>lifetime</dfn> of a
     </aside>
 
 1. When each [=/request=] associated with a transaction is [=request/processed=],
-    a <a event>`success`</a> or <a event>`error`</a> [=event=] will be
-    fired. While the event is being [=dispatched=], the transaction
+    a <a event>`success`</a> or <a event>`error`</a> [=event=] will be fired.
+    If the transaction's [=transaction/manual commit flag=] is false (the default), then
+    while the event is being [=dispatched=], the transaction
     [=transaction/state=] is set to [=transaction/active=], allowing
-    additional requests to be made against the transaction. Once the
+    additional requests to be made against the transaction; once the
     event dispatch is complete, the transaction's
     [=transaction/state=] is set to [=transaction/inactive=] again.
 
@@ -1063,11 +1066,12 @@ The <dfn>lifetime</dfn> of a
     [=/object stores=] as well as additions and removals of [=/object
     stores=] and [=/indexes=].
 
-1. The implementation must attempt to <dfn lt="commit|committed">commit</dfn>
-    a transaction when all [=/requests=] placed against the
+1. If a transaction's [=transaction/manual commit flag=] is false, then
+    the implementation must attempt to <dfn lt="commit|committed">commit</dfn>
+    it when all [=/requests=] placed against the
     transaction have completed and their returned results handled, no
     new requests have been placed against the transaction, and the
-    transaction has not been [=transaction/aborted=]
+    transaction has not been [=transaction/aborted=].
 
     An explicit call to {{IDBTransaction/commit()}} will initiate a
     [=transaction/commit=] without waiting for request results to be
@@ -1103,7 +1107,7 @@ They will return true if any transactions were cleaned up, or false otherwise.
     1. For each [=/transaction=] |transaction| with [=transaction/cleanup event loop=]
         matching the current [=/event loop=]:
 
-        1. Set |transaction|'s [=transaction/state=] to [=transaction/inactive=].
+        1. If |transaction|'s [=transaction/manual commit flag=] is false, then set |transaction|'s [=transaction/state=] to [=transaction/inactive=].
 
         1. Clear |transaction|'s [=transaction/cleanup event loop=].
 
@@ -1124,6 +1128,78 @@ a [=/transaction=] that has successfully [=transaction/committed=].
 An event with type <dfn event>`abort`</dfn> is fired at
 a [=/transaction=] that has [=transaction/aborted=].
 
+
+<aside class=example id=example-transaction-autocommit>
+
+The following example uses requests within a transaction to increment a counter value.
+Event handlers log various state changes during the request and transaction lifecycles.
+
+```js
+const transaction = connection.transaction('my_data', 'readwrite');
+const store = transaction.objectStore('my_data');
+const get_request = store.get('counter');
+get_request.onerror = e => {
+  console.warn(`get failed: ${get_request.error}`);
+};
+get_request.onsuccess = e => {
+  console.log(`get succeeded`);
+  const old_value = get_request.result;
+  const put_request = store.put(old_value + 1, 'counter');
+  put_request.onerror = e => {
+    console.warn(`get failed: ${put_request.error}`);
+  };
+  put_request.onsuccess = {
+    console.log(`put succeeded`);
+    // No more requests are made, so the transaction will autocommit.
+  };
+};
+
+transaction.onabort = e => {
+  console.warn(`transaction aborted: ${transaction.error}`);
+};
+
+transaction.oncomplete = e => {
+  console.log(`transaction committed`);
+};
+```
+</aside>
+
+<aside class=example id=example-transaction-manualcommit>
+
+The following example uses requests within a transaction to atomically
+update a record's value using an asynchronous network fetch. A manually
+committing transaction is necessary.
+
+```js
+const transaction = connection.transaction(
+  'my_records, 'readwrite', {manualCommit: true});
+
+const store = transaction.objectStore('my_records);
+store.get('key').onsuccess = async e => {
+  try {
+    const record = e.target.result;
+
+    // Make an asynchronous network request. If the transaction
+    // was not set to manual commit, it would autocommit here
+    // because there were no outstanding requests.
+    const response = await fetch(record.url);
+
+    // Update the record.
+    record.status = response.status;
+    store.put(record, 'key');
+
+    // Commit the transaction, once the request has completed.
+    // If the request fails, the transaction will abort instead.
+    transaction.commit();
+  } catch (ex) {
+    // If the fetch() fails, abort the transaction.
+    transaction.abort();
+  }
+});
+```
+</aside>
+
+
 <!-- ============================================================ -->
 ### Transaction scheduling ### {#transaction-scheduling}
 <!-- ============================================================ -->
@@ -2435,6 +2511,7 @@ interface IDBDatabase : EventTarget {
 enum IDBTransactionDurability { "default", "strict", "relaxed" };
 
 dictionary IDBTransactionOptions {
+  boolean manualCommit = false;
   IDBTransactionDurability durability = "default";
 };
 
@@ -2624,9 +2701,13 @@ instance on which it was called.
         Returns a new [=/transaction=] with the given
         |scope| (which can be a single [=/object store=] [=object-store/name=] or an array of [=object-store/names=]),
         |mode| ({{"readonly"}} or {{"readwrite"}}),
-        and additional |options| including {{IDBTransactionOptions/durability}} ({{"default"}}, {{"strict"}} or {{"relaxed"}}).
+        and additional |options| including
+        {{IDBTransactionOptions/manualCommit}} (true or false), and
+        {{IDBTransactionOptions/durability}} ({{"default"}}, {{"strict"}} or {{"relaxed"}}).
 
-        The default |mode| is {{"readonly"}} and the default {{IDBTransactionOptions/durability}} is {{"default"}}.
+        The default |mode| is {{"readonly"}}.
+        The default {{IDBTransactionOptions/manualCommit}} is false.
+        The default {{IDBTransactionOptions/durability}} is {{"default"}}.
 
     : |connection| . {{IDBDatabase/close()|close}}()
     ::
@@ -2657,7 +2738,11 @@ The <dfn method for=IDBDatabase>transaction(|storeNames|, |mode|, |options|)</df
 1. If |mode| is not {{"readonly"}} or {{"readwrite"}},
     [=throw=] a [=TypeError=].
 
-1. Let |transaction| be a newly [=transaction/created=] [=/transaction=] with |connection|, |mode|, |options|' {{IDBTransactionOptions/durability}} member, and the set of [=/object stores=] named in |scope|.
+1. Let |transaction| be a newly [=transaction/created=] [=/transaction=] with |connection|, |mode|, and the set of [=/object stores=] named in |scope|.
+
+1. Set |transaction|'s [=transaction/manual commit flag=] to |options|' {{IDBTransactionOptions/manualCommit}} member.
+
+1. Set |transaction|'s [=transaction/durability hint=] to |options|' {{IDBTransactionOptions/durability}} member.
 
 1. Set |transaction|'s [=transaction/cleanup event loop=] to the
     current [=/event loop=].
@@ -2666,6 +2751,12 @@ The <dfn method for=IDBDatabase>transaction(|storeNames|, |mode|, |options|)</df
 
 </div>
 
+<aside class=advisement>
+  &#x1F6A7;
+  The {{IDBTransactionOptions/manualCommit}} option is new in this edition.
+  &#x1F6A7;
+</aside>
+
 <aside class=advisement>
   &#x1F6A7;
   The {{IDBTransactionOptions/durability}} option is new in this edition.
@@ -4732,6 +4823,7 @@ the contents of the database.
 interface IDBTransaction : EventTarget {
   readonly attribute DOMStringList objectStoreNames;
   readonly attribute IDBTransactionMode mode;
+  readonly attribute boolean manualCommit;
   readonly attribute IDBTransactionDurability durability;
   [SameObject] readonly attribute IDBDatabase db;
   readonly attribute DOMException? error;
@@ -4766,6 +4858,10 @@ enum IDBTransactionMode {
         ({{"readonly"}} or {{"readwrite"}}), or {{"versionchange"}} for
         an [=/upgrade transaction=].
 
+    : |transaction| . {{IDBTransaction/manualCommit}}
+    ::
+        Returns true if the transaction was created with {{IDBTransactionOptions/manualCommit}}: `true` and false otherwise.
+
     : |transaction| . {{IDBTransaction/durability}}
     ::
         Returns the [=transaction/durability hint=] the transaction was created with
@@ -4806,6 +4902,14 @@ The <dfn attribute for=IDBTransaction>objectStoreNames</dfn> getter steps are:
 The <dfn attribute for=IDBTransaction>mode</dfn> getter steps are to
 return [=/this=]'s [=transaction/mode=].
 
+The <dfn attribute for=IDBTransaction>manualCommit</dfn> attribute's getter must return [=/this=]'s [=transaction/manual commit flag=].
+
+<aside class=advisement>
+  &#x1F6A7;
+  The {{IDBTransaction/manualCommit}} attribute is new in this edition.
+  &#x1F6A7;
+</aside>
+
 The <dfn attribute for=IDBTransaction>durability</dfn> getter steps are to return [=/this=]'s [=transaction/durability hint=].
 
 <aside class=advisement>
@@ -4815,7 +4919,6 @@ The <dfn attribute for=IDBTransaction>durability</dfn> getter steps are to retur
   &#x1F6A7;
 </aside>
 
-
 The <dfn attribute for=IDBTransaction>db</dfn> getter steps are to
 return [=/this=]'s [=transaction/connection=]'s associated [=/database=].
 
@@ -4853,6 +4956,9 @@ none.
         transaction to quickly finish, without waiting for pending requests to fire
         <a event>`success`</a> events before attempting to commit normally.
 
+        If the transaction was created with `manualCommit: true` then this method
+        <span class=allow-2119>must</span> be called to commit the transaction.
+
         The transaction will abort if a pending request fails, for example due to a
         constraint error. The <a event>`success`</a> events for successful requests
         will still fire, but throwing an exception in an event handler will not abort
@@ -4908,7 +5014,8 @@ The <dfn method for=IDBTransaction>abort()</dfn> method steps are:
 
 The <dfn method for=IDBTransaction>commit()</dfn> method steps are:
 
-1. If [=/this=]'s [=transaction/state=] is not [=transaction/active=],
+1. If [=/this=]'s [=transaction/manual commit flag=] is false,
+    and [=/this=]'s [=transaction/state=] is not [=transaction/active=],
     then [=throw=] an "{{InvalidStateError}}" {{DOMException}}.
 
 1. Run [=commit a transaction=] with [=/this=].
@@ -5169,7 +5276,7 @@ To <dfn>commit a transaction</dfn> with the |transaction| to commit, run these s
             <aside class=note>
               Even if an exception is thrown from one of the event handlers of
               this event, the transaction is still committed since writing the
-              database changes happens before the event takes places. Only
+              database changes happens before the event takes place. Only
               after the transaction has been successfully written is the
               <a event>`complete`</a> event fired.
             </aside>
@@ -5499,14 +5606,14 @@ To <dfn>fire a success event</dfn> at a |request|, run these steps:
 1. If |transaction|'s [=transaction/state=] is [=transaction/active=],
     then:
 
-    1. Set |transaction|'s [=transaction/state=] to [=transaction/inactive=].
+    1. If |transaction|'s [=transaction/manual commit flag=] is false, then set |transaction|'s [=transaction/state=] to [=transaction/inactive=].
 
     1. If |legacyOutputDidListenersThrowFlag| is true,
         then run [=abort a transaction=] with
         |transaction| and a newly <a for=exception>created</a>
         "{{AbortError}}" {{DOMException}}.
 
-    1. If |transaction|'s [=transaction/request list=] is empty,
+    1. If |transaction|'s [=transaction/manual commit flag=] is false and if |transaction|'s [=transaction/request list=] is empty,
         then run [=commit a transaction=] with |transaction|.
 
 </div>
@@ -5538,7 +5645,7 @@ To <dfn>fire an error event</dfn> at a |request|, run these steps:
 1. If |transaction|'s [=transaction/state=] is [=transaction/active=],
     then:
 
-    1. Set |transaction|'s [=transaction/state=] to [=transaction/inactive=].
+    1. If |transaction|'s [=transaction/manual commit flag=] is false, then set |transaction|'s [=transaction/state=] to [=transaction/inactive=].
 
     1. If |legacyOutputDidListenersThrowFlag| is true,
         then run [=abort a transaction=] with
@@ -5559,7 +5666,7 @@ To <dfn>fire an error event</dfn> at a |request|, run these steps:
         |transaction| and [=/request=]'s [=request/error=], and
         terminate these steps.
 
-    1. If |transaction|'s [=transaction/request list=] is empty,
+    1. If |transaction|'s [=transaction/manual commit flag=] is false and |transaction|'s [=transaction/request list=] is empty,
         then run [=commit a transaction=] with |transaction|.
 
 </div>
@@ -6777,6 +6884,7 @@ For the revision history of the second edition, see [that document's Revision Hi
 * Transactions are now temporarily made inactive during clone operations.
 * Added {{IDBTransactionOptions/durability}} option and {{IDBTransaction/durability}} attribute. ([Issue #50](https://github.com/w3c/IndexedDB/issues/50))
 * Specified [[#transaction-scheduling]] more precisely and disallow starting read/write transactions while read-only transactions with overlapping scope are running. ([Issue #253](https://github.com/w3c/IndexedDB/issues/253))
+* Specified [=transaction/manual commit flag=], {{IDBTransactionOptions/manualCommit}} option and {{IDBTransaction/manualCommit}} attribute. ([Issue #34](https://github.com/w3c/IndexedDB/issues/34))
 
 <!-- ============================================================ -->
 # Acknowledgements # {#acknowledgements}
