From d3d312b4b52a0aa4017043c1a63cf747002349f6 Mon Sep 17 00:00:00 2001
From: Joshua Bell <jsbell@chromium.org>
Date: Mon, 1 Feb 2021 13:44:29 -0800
Subject: [PATCH] Speculative getAllEntries() spec

---
 index.bs | 226 ++++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 147 insertions(+), 79 deletions(-)

diff --git a/index.bs b/index.bs
index d93a954..e7bd007 100644
--- a/index.bs
+++ b/index.bs
@@ -2749,6 +2749,7 @@ interface IDBObjectStore {
                                 optional [EnforceRange] unsigned long count);
   [NewObject] IDBRequest getAllKeys(optional any query,
                                     optional [EnforceRange] unsigned long count);
+  [NewObject] IDBRequest getAllEntries(optional IDBGetAllEntriesOptions options = {});
   [NewObject] IDBRequest count(optional any query);
 
   [NewObject] IDBRequest openCursor(optional any query,
@@ -2768,6 +2769,12 @@ dictionary IDBIndexParameters {
   boolean unique = false;
   boolean multiEntry = false;
 };
+
+dictionary IDBGetAllEntriesOptions {
+  any query = null;
+  [EnforceRange] unsigned long count;
+  IDBCursorDirection direction = "next";
+};
 </xmp>
 
 <div class="domintro note">
@@ -3120,6 +3127,14 @@ The <dfn method for=IDBObjectStore>clear()</dfn> method steps are:
         If successful, |request|'s {{IDBRequest/result}} will
         be an [=Array=] of the [=/keys=].
 
+    : |request| = |store| . {{IDBObjectStore/getAllEntries()|getAllEntries}}(|options|)
+    ::
+        Retrieves multiple [=/keys=] and [=/values=] of [=object-store/records=].
+
+        The |query| option specifies a [=/key=] or [=key range=] to match. The |count| option limits the number or records matched. Set the |direction| option to "{{IDBCursorDirection/next}}" to retrieve the first |count| records, or "{{IDBCursorDirection/prev}}" to return the last |count| records.
+
+        If successful, |request|'s {{IDBRequest/result}} will be an [=Array=], with each member being an [=Array=] with a [=/key=] [=/value=] pair.
+
     : |request| = |store| .
           {{IDBObjectStore/count()|count}}(|query|)
     ::
@@ -3216,7 +3231,7 @@ The <dfn method for=IDBObjectStore>getAll(|query|, |count|)</dfn> method steps a
     [=/converting a value to a key range=] with |query|.
     Rethrow any exceptions.
 
-1. Let |operation| be an algorithm to run [=retrieve multiple values from an object store=] with the [=/current Realm=], |store|, |range|, and |count| if given.
+1. Let |operation| be an algorithm to run [=retrieve multiple items from an object store=] with the [=/current Realm=], |store|, |range|, "value", and |count| if given.
 
 
 1. Return the result (an {{IDBRequest}}) of running [=asynchronously execute a request=] with [=/this=] and |operation|.
@@ -3225,7 +3240,7 @@ The <dfn method for=IDBObjectStore>getAll(|query|, |count|)</dfn> method steps a
 
 <aside class=note>
 The |query| parameter can be a [=/key=] or [=/key range=] (an {{IDBKeyRange}})
-identifying the [=object-store/records=] to be retrieved. If null or not given,
+identifying the [=object-store/record=] values to be retrieved. If null or not given,
 an [=unbounded key range=] is used. If |count| is specified and
 there are more than |count| records in range, only the first |count|
 will be retrieved.
@@ -3250,7 +3265,7 @@ The <dfn method for=IDBObjectStore>getAllKeys(|query|, |count|)</dfn> method ste
     [=/converting a value to a key range=] with |query|.
     Rethrow any exceptions.
 
-1. Let |operation| be an algorithm to run [=retrieve multiple keys from an object store=] with |store|, |range|, and |count| if given.
+1. Let |operation| be an algorithm to run [=retrieve multiple items from an object store=] with the [=/current Realm=], |store|, |range|, "key", and |count| if given.
 
 1. Return the result (an {{IDBRequest}}) of running [=asynchronously execute a request=] with [=/this=] and |operation|.
 
@@ -3258,13 +3273,44 @@ The <dfn method for=IDBObjectStore>getAllKeys(|query|, |count|)</dfn> method ste
 
 <aside class=note>
 The |query| parameter can be a [=/key=] or [=/key range=] (an {{IDBKeyRange}})
-identifying the [=object-store/records=] keys to be retrieved. If null or not
+identifying the [=object-store/record=] keys to be retrieved. If null or not
 given, an [=unbounded key range=] is used. If |count| is specified
 and there are more than |count| keys in range, only the first |count|
 will be retrieved.
 </aside>
 
 
+<div algorithm>
+
+The <dfn method for=IDBObjectStore>getAllEntries(|query|, |count|)</dfn> method steps are:
+
+1. Let |transaction| be [=/this=]'s [=object-store-handle/transaction=].
+
+1. Let |store| be [=/this=]'s [=object-store-handle/object store=].
+
+1. If |store| has been deleted, then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.
+
+1. If |transaction|'s [=transaction/state=] is not [=transaction/active=], then [=exception/throw=] a "{{TransactionInactiveError}}" {{DOMException}}.
+
+1. Let |range| be the result of [=/converting a value to a key range=] with |query|. Rethrow any exceptions.
+
+1. Let |operation| be an algorithm to run [=retrieve multiple items from an object store=] with the [=/current Realm=], |store|, |range|, "key+value", and |count| if given.
+
+1. Return the result (an {{IDBRequest}}) of running [=asynchronously execute a request=] with [=/this=] and |operation|.
+
+</div>
+
+<aside class=note>
+  The |query| parameter can be a [=/key=] or [=key range=] (an {{IDBKeyRange}}) identifying the [=object-store/records=] to be retrieved. If null or not given, an [=unbounded key range=] is used. If |count| is specified and there are more than |count| keys in range, only the first |count| will be retrieved.
+</aside>
+
+<aside class=advisement>
+  &#x1F6A7;
+  The {{IDBObjectStore/getAllEntries()}} method is new in this edition.
+  &#x1F6A7;
+</aside>
+
+
 <div algorithm>
 
 The <dfn method for=IDBObjectStore>count(|query|)</dfn> method steps are:
@@ -3640,6 +3686,7 @@ interface IDBIndex {
                                 optional [EnforceRange] unsigned long count);
   [NewObject] IDBRequest getAllKeys(optional any query,
                                     optional [EnforceRange] unsigned long count);
+  [NewObject] IDBRequest getAllEntries(optional IDBGetAllEntriesOptions options = {});
   [NewObject] IDBRequest count(optional any query);
 
   [NewObject] IDBRequest openCursor(optional any query,
@@ -3788,6 +3835,13 @@ return [=/this=]'s [=index-handle/index=]'s [=index/unique flag=].
         If successful, |request|'s {{IDBRequest/result}} will be an
         [=Array=] of the [=/keys=].
 
+
+    : |request| = |index| . {{IDBIndex/getAllEntries()|getAllEntries}}(|query| [, |count|])
+    ::
+        Retrieves the [=/keys=], [=/values=], and index [=/keys=] of [=object-store/records=] matching the given [=/key=] or [=key range=] in |query| (up to |count| if given).
+
+        If successful, |request|'s {{IDBRequest/result}} will be an [=Array=], with each member being an [=Array=] with [=/key=], [=/value=], and index [=/key=].
+
     : |request| = |index| .
           {{IDBIndex/count()|count}}(|query|)
     ::
@@ -3885,7 +3939,7 @@ The <dfn method for=IDBIndex>getAll(|query|, |count|)</dfn> method steps are:
     [=/converting a value to a key range=] with |query|.
     Rethrow any exceptions.
 
-1. Let |operation| be an algorithm to run [=retrieve multiple referenced values from an index=] with the [=/current Realm=], |index|, |range|, and |count| if given.
+1. Let |operation| be an algorithm to run [=retrieve multiple items from an index=] with the [=/current Realm=], |index|, |range|, "value", and |count| if given.
 
 1. Return the result (an {{IDBRequest}}) of running [=asynchronously execute a request=] with [=/this=] and |operation|.
 
@@ -3893,7 +3947,7 @@ The <dfn method for=IDBIndex>getAll(|query|, |count|)</dfn> method steps are:
 
 <aside class=note>
 The |query| parameter can be a [=/key=] or [=/key range=] (an {{IDBKeyRange}})
-identifying the [=object-store/records=] to be retrieved. If null or not given,
+identifying the [=object-store/record=] values to be retrieved. If null or not given,
 an [=unbounded key range=] is used. If |count| is specified and
 there are more than |count| records in range, only the first |count|
 will be retrieved.
@@ -3918,7 +3972,7 @@ The <dfn method for=IDBIndex>getAllKeys(|query|, |count|)</dfn> method steps are
     [=/converting a value to a key range=] with |query|.
     Rethrow any exceptions.
 
-1. Let |operation| be an algorithm to run [=retrieve multiple values from an index=] with |index|, |range|, and |count| if given.
+1. Let |operation| be an algorithm to run [=retrieve multiple items from an index=] with the [=/current Realm=], |index|, |range|, "key", and |count| if given.
 
 1. Return the result (an {{IDBRequest}}) of running [=asynchronously execute a request=] with [=/this=] and |operation|.
 
@@ -3933,6 +3987,37 @@ will be retrieved.
 </aside>
 
 
+<div algorithm>
+
+The <dfn method for=IDBIndex>getAllEntries(|query|, |count|)</dfn> method steps are:
+
+1. Let |transaction| be [=/this=]'s [=index-handle/transaction=].
+
+1. Let |index| be [=/this=]'s [=index-handle/index=].
+
+1. If |index| or |index|'s [=/object store=] has been deleted, then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.
+
+1. If |transaction|'s [=transaction/state=] is not [=transaction/active=], then [=exception/throw=] a "{{TransactionInactiveError}}" {{DOMException}}.
+
+1. Let |range| be the result of [=/converting a value to a key range=] with |query|. Rethrow any exceptions.
+
+1. Let |operation| be an algorithm to run [=retrieve multiple items from an index=] with the [=/current Realm=], |index|, |range|, "key+value+indexKey", and |count| if given.
+
+1. Return the result (an {{IDBRequest}}) of running [=asynchronously execute a request=] with [=/this=] and |operation|.
+
+</div>
+
+<aside class=note>
+The |query| parameter can be a [=/key=] or [=key range=] (an {{IDBKeyRange}}) identifying the [=object-store/records=] to be retrieved. If null or not given, an [=unbounded key range=] is used. If |count| is specified and there are more than |count| keys in range, only the first |count| will be retrieved.
+</aside>
+
+<aside class=advisement>
+  &#x1F6A7;
+  The {{IDBIndex/getAllEntries()}} method is new in this edition.
+  &#x1F6A7;
+</aside>
+
+
 <div algorithm>
 
 The <dfn method for=IDBIndex>count(|query|)</dfn> method steps are:
@@ -5272,7 +5357,7 @@ created [=/request=] belongs to is [=transaction/aborted=] using the steps to
 
 1. [=/Assert=]: |transaction|'s [=transaction/state=] is [=transaction/active=].
 
-1. If |request| was not given, let |request| be a new [=/request=] with [=request/source=] as |source|.
+1. If |request| was not given, let |request| be a new [=/request=] with |source| as [=request/source=].
 
 1. Add |request| to the end of |transaction|'s [=transaction/request list=].
 
@@ -5741,30 +5826,6 @@ To <dfn>retrieve a value from an object store</dfn> with
 </div>
 
 
-<div algorithm>
-
-To <dfn>retrieve multiple values from an object
-store</dfn> with |targetRealm|, |store|, |range| and optional |count|, run these steps:
-
-1. If |count| is not given or is 0 (zero), let |count| be infinity.
-
-1. Let |records| be a [=/list=] containing the first |count| [=object-store/records=]
-    in |store|'s [=object-store/list of records=] whose [=/key=] is
-    [=in=] |range|.
-
-1. Let |list| be an empty [=/list=].
-
-1. [=list/For each=] |record| of |records|:
-
-    1. Let |serialized| be |record|'s [=/value=].
-    1. Let |entry| be [=!=] [$StructuredDeserialize$](|serialized|, |targetRealm|).
-    1. Append |entry| to |list|.
-
-1. Return |list| converted to a <code>[=/sequence=]&lt;{{any}}&gt;</code>.
-
-</div>
-
-
 <div algorithm>
 
 To <dfn>retrieve a key from an object store</dfn>
@@ -5784,24 +5845,38 @@ with |store| and |range|, run these steps:
 
 <div algorithm>
 
-To <dfn>retrieve multiple keys from an object store</dfn>
-with |store|, |range| and optional |count|, run these steps:
+To <dfn>retrieve multiple items from an object store</dfn> with |targetRealm|, |store|, |range|, |kind| and optional |count|, run these steps:
 
 1. If |count| is not given or is 0 (zero), let |count| be infinity.
 
-1. Let |records| be a list containing the first |count| [=object-store/records=]
-    in |store|'s [=object-store/list of records=] whose [=/key=] is
-    [=in=] |range|.
+1. Let |records| be a list containing the first |count| [=object-store/records=] in |store|'s [=object-store/list of records=] whose [=/key=] is [=in=] |range|.
 
 1. Let |list| be an empty [=/list=].
 
-1. [=list/For each=] |record| of |records|:
+1. [=list/For each=] |record| of |records|, switching on |kind|:
 
-    1. Let |entry| be the result of [=/converting a
-        key to a value=] with |record|'s key.
-    1. Append |entry| to |list|.
+    <dl class=switch>
+      : "key"
+      ::
+          1. Let |key| be the result of [=/converting a key to a value=] with |record|'s key.
+          1. [=list/Append=] |key| to |list|.
 
-1. Return |list| converted to a <code>[=/sequence=]&lt;{{any}}&gt;</code>.
+      : "value"
+      ::
+          1. Let |serialized| be |record|'s [=/value=].
+          1. Let |value| be [=!=] [$StructuredDeserialize$](|serialized|, |targetRealm|).
+          1. [=list/Append=] |value| to |list|.
+
+      : "key+value"
+      ::
+          1. Let |key| be the result of [=/converting a key to a value=] with |record|'s key.
+          1. Let |serialized| be |record|'s [=/value=].
+          1. Let |value| be [=!=] [$StructuredDeserialize$](|serialized|, |targetRealm|).
+          1. [=list/Append=] « |key|, |value| » to |list|.
+
+    </dl>
+
+1. Return |list|.
 
 </div>
 
@@ -5826,34 +5901,6 @@ with |targetRealm|, |index| and |range|, run these steps:
 
 </div>
 
-
-<div algorithm>
-
-To <dfn>retrieve multiple referenced values from an
-index</dfn> with |targetRealm|, |index|, |range| and optional |count|, run these steps:
-
-1. If |count| is not given or is 0 (zero), let |count| be infinity.
-
-1. Let |records| be a list containing the first |count| [=object-store/records=]
-    in |index|'s [=index/list of records=] whose [=index/key=] is [=in=] |range|.
-
-1. Let |list| be an empty [=/list=].
-
-1. [=list/For each=] |record| of |records|:
-
-    1. Let |serialized| be |record|'s [=index/referenced value=].
-    1. Let |entry| be [=!=] [$StructuredDeserialize$](|serialized|, |targetRealm|).
-    1. Append |entry| to |list|.
-
-1. Return |list| converted to a <code>[=/sequence=]&lt;{{any}}&gt;</code>.
-
-</div>
-
-<aside class=note>
-    The [=index/values=] of an [=index/record=] in an index are the keys of
-    [=object-store/records=] in the [=index/referenced=] object store.
-</aside>
-
 <div algorithm>
 
 To <dfn>retrieve a value from an index</dfn> with
@@ -5872,26 +5919,46 @@ To <dfn>retrieve a value from an index</dfn> with
 
 <div algorithm>
 
-To <dfn>retrieve multiple values from an index</dfn> with
-|index|, |range| and optional |count|, run these steps:
+To <dfn>retrieve multiple items from an index</dfn> with |targetRealm|, |index|, |range|, |kind| and optional |count|, run these steps:
 
 1. If |count| is not given or is 0 (zero), let |count| be infinity.
 
-1. Let |records| be a list containing the first |count| [=index/records=] in
-    |index|'s [=index/list of records=] whose [=index/key=] is [=in=] |range|.
+1. Let |records| be a list containing the first |count| [=object-store/records=] in |index|'s [=index/list of records=] whose [=index/key=] is [=in=] |range|.
 
 1. Let |list| be an empty [=/list=].
 
-1. [=list/For each=] |record| of |records|:
+1. [=list/For each=] |record| of |records|, switching on |kind|:
 
-    1. Let |entry| be the result of [=/converting a
-        key to a value=] with |record|'s value.
-    1. Append |entry| to |list|.
+    <dl class=switch>
+      : "key"
+      ::
+          1. Let |key| be the result of [=/converting a key to a value=] with |record|'s value.
+          1. [=list/Append=] |key| to |list|.
 
-1. Return |list| converted to a <code>[=/sequence=]&lt;{{any}}&gt;</code>.
+      : "value"
+      ::
+          1. Let |serialized| be |record|'s [=index/referenced value=].
+          1. Let |value| be [=!=] [$StructuredDeserialize$](|serialized|, |targetRealm|).
+          1. [=list/Append=] |value| to |list|.
+
+      : "key+value+indexKey"
+      ::
+          1. Let |key| be the result of [=/converting a key to a value=] with |record|'s value.
+          1. Let |indexKey| be the result of [=/converting a key to a value=] with |record|'s key.
+          1. Let |serialized| be |record|'s [=index/referenced value=].
+          1. Let |value| be [=!=] [$StructuredDeserialize$](|serialized|, |targetRealm|).
+          1. [=list/Append=] « |key|, |value|, |indexKey| » to |list|.
+
+    </dl>
+
+1. Return |list|.
 
 </div>
 
+<aside class=note>
+  The [=index/values=] of a [=index/record=] in an index are the keys of [=object-store/records=] in the [=index/referenced=] object store.
+</aside>
+
 
 <!-- ============================================================ -->
 ## Object store deletion operation ## {#object-store-deletion-operation}
@@ -6805,6 +6872,7 @@ For the revision history of the second edition, see [that document's Revision Hi
 * 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))
 * Added <a href="#accessibility">Accessibility considerations</a> section. ([Issue #327](https://github.com/w3c/IndexedDB/issues/327))
 * Used [[infra]]'s list sorting definition. ([Issue #346](https://github.com/w3c/IndexedDB/issues/346))
+* Added object store {{IDBObjectStore/getAllEntries()}} and index {{IDBIndex/getAllEntries()}} methods. ([Issue #206](https://github.com/w3c/IndexedDB/issues/206))
 
 <!-- ============================================================ -->
 # Acknowledgements # {#acknowledgements}