Skip to content

Commit

Permalink
Speculative getAllEntries() spec
Browse files Browse the repository at this point in the history
  • Loading branch information
@inexorabletash
inexorabletash committed Jun 8, 2022
1 parent bb2eb85 commit d3d312b
Showing 1 changed file with 147 additions and 79 deletions.
226 changes: 147 additions & 79 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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">
Expand Down Expand Up @@ -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|)
::
Expand Down Expand Up @@ -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|.
Expand All @@ -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.
Expand All @@ -3250,21 +3265,52 @@ 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|.

</div>

<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:
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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|)
::
Expand Down Expand Up @@ -3885,15 +3939,15 @@ 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|.

</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,
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.
Expand All @@ -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|.

Expand All @@ -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:
Expand Down Expand Up @@ -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=].

Expand Down Expand Up @@ -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>
Expand All @@ -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>

Expand All @@ -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
Expand All @@ -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}
Expand Down Expand Up @@ -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}
Expand Down

0 comments on commit d3d312b

Please sign in to comment.