Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sketch out IDBCursor.close() #302

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Sketch out IDBCursor.close() #302

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 58 additions & 16 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4261,6 +4261,7 @@ interface IDBCursor {
undefined advance([EnforceRange] unsigned long count);
undefined continue(optional any key);
undefined continuePrimaryKey(any key, any primaryKey);
undefined close();

[NewObject] IDBRequest update(any value);
[NewObject] IDBRequest delete();
Expand Down Expand Up @@ -4306,7 +4307,8 @@ return [=/this=]'s [=cursor/source=].

<aside class=note>
The {{IDBCursor/source}} attribute never returns null or throws an exception, even if the
cursor is currently being iterated, has iterated past its end, or its
cursor is currently being iterated, has iterated past its end,
{{IDBCursor/close()}} has been called, or its
[=/transaction=] is not [=transaction/active=].
</aside>

Expand Down Expand Up @@ -4383,6 +4385,12 @@ return [=/this=]'s [=cursor/request=].
Advances the cursor to the next [=object-store/record=] in range matching
or after |key| and |primaryKey|. Throws an "{{InvalidAccessError}}" {{DOMException}}
if the [=cursor/source=] is not an [=/index=].


: |cursor| . {{IDBCursor/close()|close}}()
::
Signals that the cursor is no longer needed, and that any associated resources can be released.

</div>


Expand All @@ -4401,9 +4409,9 @@ The <dfn method for=IDBCursor>advance(|count|)</dfn> method steps are:
1. If [=/this=]'s [=cursor/source=] or [=cursor/effective object
store=] has been deleted, [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.

1. If [=/this=]'s [=cursor/got value flag=] is false, indicating that
the cursor is being iterated or has iterated past its end,
[=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.
1. If [=/this=]'s [=cursor/got value flag=] is false
(indicating that the cursor is being iterated, has iterated past its end, or that {{IDBCursor/close()}} was called),
then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.

1. Set [=/this=]'s [=cursor/got value flag=] to false.

Expand Down Expand Up @@ -4441,9 +4449,9 @@ The <dfn method for=IDBCursor>continue(|key|)</dfn> method steps are:
[=cursor/effective object store=] has been deleted, [=exception/throw=] an
"{{InvalidStateError}}" {{DOMException}}.

1. If [=/this=]'s [=cursor/got value flag=] is false, indicating that
the cursor is being iterated or has iterated past its end,
[=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.
1. If [=/this=]'s [=cursor/got value flag=] is false
(indicating that the cursor is being iterated, has iterated past its end, or that {{IDBCursor/close()}} was called),
then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.

1. If |key| is given, then:

Expand Down Expand Up @@ -4503,9 +4511,9 @@ The <dfn method for=IDBCursor>continuePrimaryKey(|key|, |primaryKey|)</dfn> meth
1. If [=/this=]'s [=cursor/direction=] is not "{{IDBCursorDirection/next}}" or "{{IDBCursorDirection/prev}}",
[=exception/throw=] an "{{InvalidAccessError}}" {{DOMException}}.

1. If [=/this=]'s [=cursor/got value flag=] is false, indicating that
the cursor is being iterated or has iterated past its end,
[=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.
1. If [=/this=]'s [=cursor/got value flag=] is false
(indicating that the cursor is being iterated, has iterated past its end, or that {{IDBCursor/close()}} was called),
then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.

1. Let |r| be the result of [=/converting a value to
a key=] with |key|. Rethrow any exceptions.
Expand Down Expand Up @@ -4562,6 +4570,39 @@ The <dfn method for=IDBCursor>continuePrimaryKey(|key|, |primaryKey|)</dfn> meth
flag=] has been set to false.
</aside>

<div algorithm>

The <dfn method for=IDBCursor>close()</dfn> method steps are:

1. Let |transaction| be [=/this=]'s [=cursor/transaction=].

1. If |transaction|'s [=transaction/state=] is not [=transaction/active=], then [=exception/throw=] a "{{TransactionInactiveError}}" {{DOMException}}.

1. If [=/this=]'s [=cursor/source=] or [=cursor/effective object store=] has been deleted, then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.

1. If [=/this=]'s [=cursor/got value flag=] is false
(indicating that the cursor is being iterated, has iterated past its end, or that {{IDBCursor/close()}} was called),
then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.

1. Set [=/this=]'s [=cursor/got value flag=] to false.

1. Set [=/this=]'s [=cursor/key=] to undefined.

1. If [=/this=]'s [=cursor/source=] is an [=/index=], then set [=/this=]'s [=cursor/object store position=] to undefined.

1. If [=/this=]'s [=cursor/key only flag=] is false, then set [=/this=]'s [=cursor/value=] to undefined.

</div>

<aside class=note>
The {{IDBCursor/close()}} method allows web applications to hint to the user agent that the cursor will no longer be iterated, and that any state associated with the cursor can be discarded.
</aside>

<aside class=advisement>
&#x1F6A7;
The {{IDBCursor/close()}} method is new in this edition.
&#x1F6A7;
</aside>


<div class="domintro note">
Expand Down Expand Up @@ -4605,9 +4646,9 @@ The <dfn method for=IDBCursor>update(|value|)</dfn> method steps are:
1. If [=/this=]'s [=cursor/source=] or [=cursor/effective object
store=] has been deleted, [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.

1. If [=/this=]'s [=cursor/got value flag=] is false, indicating that
the cursor is being iterated or has iterated past its end,
[=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.
1. If [=/this=]'s [=cursor/got value flag=] is false
(indicating that the cursor is being iterated, has iterated past its end, or that {{IDBCursor/close()}} was called),
then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.

1. If [=/this=]'s [=cursor/key only flag=] is true, [=exception/throw=] an
"{{InvalidStateError}}" {{DOMException}}.
Expand Down Expand Up @@ -4666,9 +4707,9 @@ The <dfn method for=IDBCursor>delete()</dfn> method steps are:
1. If [=/this=]'s [=cursor/source=] or [=cursor/effective object
store=] has been deleted, [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.

1. If [=/this=]'s [=cursor/got value flag=] is false, indicating that
the cursor is being iterated or has iterated past its end,
[=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.
1. If [=/this=]'s [=cursor/got value flag=] is false
(indicating that the cursor is being iterated, has iterated past its end, or that {{IDBCursor/close()}} was called),
then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.

1. If [=/this=]'s [=cursor/key only flag=] is true, [=exception/throw=] an
"{{InvalidStateError}}" {{DOMException}}.
Expand Down Expand Up @@ -6781,6 +6822,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 {{IDBCursor/close()}} method for {{IDBCursor}}. ([Issue #185](https://github.com/w3c/IndexedDB/issues/185))

<!-- ============================================================ -->
# Acknowledgements # {#acknowledgements}
Expand Down