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

Jump to bottom

Add domintro blocks for “Web storage” interfaces #3179

Merged
merged 13 commits into from
Dec 12, 2017
Merged

Add domintro blocks for “Web storage” interfaces #3179

Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
5dc34f5
Add domintro blocks for “Web storage” interfaces
sideshowbarker Oct 30, 2017
0c1067a
Use <code>Storage</code> instead of <var>s
sideshowbarker Nov 23, 2017
a97cb5c
Add missing period
sideshowbarker Nov 23, 2017
774aa64
Streamline the domintro for Storage.setItem
sideshowbarker Nov 23, 2017
3d64cce
Restore event-firing requirements to dev edition
sideshowbarker Nov 23, 2017
7c36915
Restore data-expiration paragraph to dev edition
sideshowbarker Nov 23, 2017
44cfce5
Include Disk Space, Privacy section in dev edition
sideshowbarker Nov 23, 2017
ecd5178
Add domintro for window.localStorage
sideshowbarker Nov 23, 2017
269ac43
Reword in terms of “storage item” being changed
sideshowbarker Nov 23, 2017
0de841a
Streamline StorageEvent attributes normative text
sideshowbarker Nov 23, 2017
7932bad
Add dev-edition “send a storage notification” dfn
sideshowbarker Nov 23, 2017
f477a83
Respond to review comments
sideshowbarker Nov 29, 2017
13cde45
Some last domintro tweaks
domenic Dec 1, 2017
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
173 changes: 146 additions & 27 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3060,6 +3060,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li>The <dfn data-x-href="https://tc39.github.io/ecma262/#sec-eval-x"><code>eval()</code></dfn> function</li>
<li>The <dfn data-x-href="https://tc39.github.io/ecma262/#sec-IsHTMLDDA-internal-slot">[[IsHTMLDDA]]</dfn> internal slot</li>
<li>The <dfn data-x="js-typeof" data-x-href="https://tc39.github.io/ecma262/#sec-typeof-operator"><code>typeof</code></dfn> operator</li>
<li>The <dfn data-x-href="https://tc39.github.io/ecma262/#sec-delete-operator"><code>delete</code></dfn> operator</li>
<li><dfn data-x-href="https://tc39.github.io/ecma262/#table-49">The <var>TypedArray</var> Constructors</dfn> table</li>
</ul>

Expand Down Expand Up @@ -98129,7 +98130,7 @@ interface <dfn>WorkerLocation</dfn> {
-->

<p>The second storage mechanism is designed for storage that spans multiple windows, and lasts
beyond the current session. In particular, Web applications may wish to store megabytes of user
beyond the current session. In particular, Web applications might wish to store megabytes of user
data, such as entire user-authored documents or a user's mailbox, on the client side for
performance reasons.</p>

Expand Down Expand Up @@ -98197,6 +98198,53 @@ interface <dfn>Storage</dfn> {
implementing the <code>Storage</code> interface can all be associated with the same list of
key/value pairs simultaneously.</p>

<dl class="domintro">

<dt><var>storage</var> . <code subdfn data-x="dom-Storage-length">length</code></dt>
<dd>
<p>Returns the number of key/value pairs currently present in the list associated with the
object.</p>
<dd>

<dt><var>storage</var> . <code subdfn data-x="dom-Storage-key">key</code> ( <var>n</var> )</dt>
<dd>
<p>Returns the name of the <var>n</var>th key in the list, or null if <var>n</var> is greater
than or equal to the number of key/value pairs in the object.</p>
<dd>

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All of these operations might be clearer if phrased using https://infra.spec.whatwg.org/#maps, possibly including linking to them?

Probably that should be a follow-up for both the dev-facing docs and the normative definitions, instead of being done here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All of these operations might be clearer if phrased using https://infra.spec.whatwg.org/#maps, possibly including linking to them?

yeah, seems so

Probably that should be a follow-up for both the dev-facing docs and the normative definitions, instead of being done here.

Raised #3252

<dt><var>value</var> = <var>storage</var> . <code subdfn data-x="dom-Storage-getItem">getItem</code> ( <var>key</var> )</dt>
<dt><var>value</var> = <var>storage</var>[<var>key</var>]</dt>
<dd>
<p>Returns the current value associated with the given <var>key</var>, or null if the given
<var>key</var> does not exist in the list associated with the object.</p>
<dd>

<dt><var>storage</var> . <code subdfn data-x="dom-Storage-setItem">setItem</code> ( <var>key</var>, <var>value</var> )</dt>
<dt><var>storage</var>[<var>key</var>] = <var>value</var></dt>
<dd>
<p>Sets the value of the pair identified by <var>key</var> to <var>value</var>, creating a new
key/value pair if none existed for <var>key</var> previously.</p>

<p>Throws a <span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code> exception
if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage
for the site, or if the quota has been exceeded.)</p>

<dt><var>storage</var> . <code subdfn data-x="dom-Storage-removeItem">removeItem</code> ( <var>key</var> )</dt>
<dt><code>delete</code> <var>storage</var>[<var>key</var>]</dt>
<dd>
<p>Removes the key/value pair with the given <var>key</var> from the list associated with the
object, if a key/value pair with the given <var>key</var> exists.</p>
</dd>

<dt><var>storage</var> . <code subdfn data-x="dom-Storage-clear">clear</code>()</dt>
<dd>
<p>Empties the list associated with the object of all key/value pairs, if there are any.</p>
</dd>

</dl>

<div w-nodev>

<p>The <dfn><code data-x="dom-Storage-length">length</code></dfn> attribute must return the number
of key/value pairs currently present in the list associated with the object.</p>

Expand Down Expand Up @@ -98228,8 +98276,7 @@ interface <dfn>Storage</dfn> {
the method must do nothing.</p>

<p>If it couldn't set the new value, the method must throw a
<span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code> exception. (Setting could
fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.)</p>
<span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code> exception.</p>

<p>The <dfn><code data-x="dom-Storage-removeItem">removeItem(<var>key</var>)</code></dfn>
method must cause the key/value pair with the given <var>key</var> to be removed from the
Expand All @@ -98245,6 +98292,8 @@ interface <dfn>Storage</dfn> {
list associated with the object to be emptied of all key/value pairs, if there are any. If there
are none, then the method must do nothing.</p>

</div>

<p class="note">When the <code data-x="dom-Storage-setItem">setItem()</code>, <code
data-x="dom-Storage-removeItem">removeItem()</code>, and <code
data-x="dom-Storage-clear">clear()</code> methods are invoked, events are fired on the
Expand All @@ -98271,6 +98320,14 @@ interface <dfn>WindowSessionStorage</dfn> {
<p>The <dfn><code data-x="dom-sessionStorage">sessionStorage</code></dfn> attribute represents the
set of storage areas specific to the current <span>top-level browsing context</span>.</p>

<dl class="domintro">
<dt><var>window</var> . <code subdfn data-x="dom-sessionStorage">sessionStorage</code></dt>
<dd>
<p>Returns the <code>Storage</code> object associated with that origin's session storage
area.</p>
</dd>
</dl>

<p>Each <span>top-level browsing context</span> has a unique set of session storage areas, one for
each <span>origin</span>.</p>

Expand All @@ -98282,6 +98339,8 @@ interface <dfn>WindowSessionStorage</dfn> {
be discarded with it, as the API described in this specification provides no way for that data to
ever be subsequently retrieved.</p>

<div w-nodev>

<p class="note">The lifetime of a browsing context can be unrelated to the lifetime of the actual
user agent process itself, as the user agent can support resuming sessions after a restart.</p>

Expand All @@ -98298,19 +98357,21 @@ interface <dfn>WindowSessionStorage</dfn> {

<p>The <code data-x="dom-sessionStorage">sessionStorage</code> attribute must return a
<code>Storage</code> object associated with the <code>Document</code>'s assigned session storage
area, if any, or null if there isn't one. Each <code>Document</code> object must have a separate
object for its <code>Window</code>'s <code data-x="dom-sessionStorage">sessionStorage</code>
attribute.</p>
area. Each <code>Document</code> object must have a separate object for its <code>Window</code>'s
<code data-x="dom-sessionStorage">sessionStorage</code> attribute.</p>

<p>While <span>creating a new browsing context</span>, the session storage area <a
href="#copy-session-storage">is sometimes copied</a> over.</p>

</div>

<p id="sessionStorageEvent">When the <code data-x="dom-Storage-setItem">setItem()</code>, <code
data-x="dom-Storage-removeItem">removeItem()</code>, and <code
data-x="dom-Storage-clear">clear()</code> methods are called on a <code>Storage</code> object <var>x</var> that is associated with a session storage area, if the methods did not throw an
exception or "do nothing" as defined above, then for every <code>Document</code> object whose
<code>Window</code> object's <code data-x="dom-sessionStorage">sessionStorage</code> attribute's
<code>Storage</code> object is associated with the same storage area, other than <var>x</var>, <span>send a storage notification</span>.</p>
<code>Storage</code> object is associated with the same storage area, other than <var>x</var>,
<span w-nohtml>user agents</span> <span>send a storage notification</span>.</p>


<h4>The <code data-x="dom-localStorage">localStorage</code> attribute</h4>
Expand All @@ -98327,6 +98388,20 @@ interface <dfn>WindowLocalStorage</dfn> {
<!--INSERT FINGERPRINT-->
</p>

<dl class="domintro">
<dt><var>window</var> . <code subdfn data-x="dom-localStorage">localStorage</code></dt>
<dd>
<p>Returns the <code>Storage</code> object associated with that origin's local storage
area.</p>
<p>Throws a <span>"<code>SecurityError</code>"</span> <code>DOMException</code> if the
<code>Document</code>'s <span>origin</span> is an <span data-x="concept-origin-opaque">opaque
origin</span> or if the request violates a policy decision (e.g. if the user agent is
configured to not allow the page to persist data).</p>
</dd>
</dl>

<div w-nodev>

<p>User agents must have a set of local storage areas, one for each <span>origin</span>.</p>

<p>User agents should expire data from the local storage areas only for security reasons or when
Expand All @@ -98341,10 +98416,10 @@ interface <dfn>WindowLocalStorage</dfn> {

<ol>

<li><p>The user agent may throw a <span>"<code>SecurityError</code>"</span>
<code>DOMException</code> instead of returning a <code>Storage</code>
object if the request violates a policy decisions (e.g. if the user agent is configured to not
allow the page to persist data).</p></li>
<li><p>If the request violates a policy decision (e.g. if the user agent is configured to not
allow the page to persist data), the user agent may throw a
<span>"<code>SecurityError</code>"</span> <code>DOMException</code> instead of returning a
<code>Storage</code> object</p></li>

<li><p>If the <code>Document</code>'s <span>origin</span> is an <span
data-x="concept-origin-opaque">opaque origin</span>, then throw a
Expand All @@ -98361,12 +98436,15 @@ interface <dfn>WindowLocalStorage</dfn> {

</ol>

</div>

<p id="localStorageEvent">When the <code data-x="dom-Storage-setItem">setItem()</code>, <code
data-x="dom-Storage-removeItem">removeItem()</code>, and <code
data-x="dom-Storage-clear">clear()</code> methods are called on a <code>Storage</code> object <var>x</var> that is associated with a local storage area, if the methods did not throw an
exception or "do nothing" as defined above, then for every <code>Document</code> object whose
<code>Window</code> object's <code data-x="dom-localStorage">localStorage</code> attribute's
<code>Storage</code> object is associated with the same storage area, other than <var>x</var>, <span>send a storage notification</span>.
<code>Storage</code> object is associated with the same storage area, other than <var>x</var>,
<span w-nohtml>user agents</span> <span>send a storage notification</span>.

<p class="warning">The <code data-x="dom-localStorage">localStorage</code> attribute provides
access to shared state. This specification does not define the interaction with other browsing
Expand All @@ -98379,10 +98457,13 @@ interface <dfn>WindowLocalStorage</dfn> {

<h4>The <code data-x="event-storage">storage</code> event</h4>

<p>The <code data-x="event-storage">storage</code> event is fired on a <code>Document</code>'s
<code>Window</code> object when a storage area changes, as described in the previous two sections
(<a href="#sessionStorageEvent">for session storage</a>, <a href="#localStorageEvent">for local
storage</a>).</p>
<p><span subdfn data-x="send a storage notification">The <code
data-x="event-storage">storage</code> event is fired on a <code>Document</code>'s
<code>Window</code> object when a storage area changes</span>, as described in the previous two
sections (<a href="#sessionStorageEvent">for session storage</a>, <a href="#localStorageEvent">for
local storage</a>).</p>

<div w-nodev>

<p>When a user agent is to <dfn>send a storage notification</dfn> for a <code>Document</code>, the
user agent must <span>queue a task</span> to <span data-x="concept-event-fire">fire an
Expand Down Expand Up @@ -98418,6 +98499,8 @@ interface <dfn>WindowLocalStorage</dfn> {
<code>Document</code> that represents the same kind of <code>Storage</code> area as was affected
(i.e. session or local).</p>

</div>


<h5>The <code>StorageEvent</code> interface</h5>

Expand All @@ -98439,21 +98522,50 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
<span>Storage</span>? storageArea = null;
};</pre>

<p>The <dfn><code data-x="dom-StorageEvent-key">key</code></dfn> attribute must return the value
it was initialized to. It represents the key being changed.</p>
<dl class="domintro">

<p>The <dfn><code data-x="dom-StorageEvent-oldValue">oldValue</code></dfn> attribute must return
the value it was initialized to. It represents the old value of the key being changed.</p>
<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-key">key</code></dt>

<p>The <dfn><code data-x="dom-StorageEvent-newValue">newValue</code></dfn> attribute must return
the value it was initialized to. It represents the new value of the key being changed.</p>
<dd>
<p>Returns the key of the storage item being changed.</p>
</dd>

<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-oldValue">oldValue</code></dt>

<dd>
<p>Returns the old value of the key of the storage item whose value is being changed.</p>
</dd>

<p>The <dfn><code data-x="dom-StorageEvent-url">url</code></dfn> attribute must return the value
it was initialized to. It represents the <span>URL</span> of the document whose key changed.</p>
<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-newValue">newValue</code></dt>

<p>The <dfn><code data-x="dom-StorageEvent-storageArea">storageArea</code></dfn> attribute must
return the value it was initialized to. It represents the <code>Storage</code> object that was
affected.</p>
<dd>
<p>Returns the new value of the key of the storage item whose value is being changed.</p>
</dd>

<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-url">url</code></dt>

<dd>
<p>Returns the <span>URL</span> of the document whose storage item changed.</p>
</dd>

<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-storageArea">storageArea</code></dt>

<dd>
<p>Returns the <code>Storage</code> object that was affected.</p>
</dd>

</dl>

<div w-nodev>

<p>The <dfn><code data-x="dom-StorageEvent-key">key</code></dfn>, <dfn><code
data-x="dom-StorageEvent-oldValue">oldValue</code></dfn>, <dfn><code
data-x="dom-StorageEvent-newValue">newValue</code></dfn>, <dfn><code
data-x="dom-StorageEvent-url">url</code></dfn>, and <dfn><code
data-x="dom-StorageEvent-storageArea">storageArea</code></dfn> attributes must return the values
they were initialized to.</p>

</div>


<h3>Disk space</h3>
Expand Down Expand Up @@ -98585,6 +98697,7 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
user-specific data (e.g. user-agent headers and configuration settings) to combine separate
sessions into coherent user profiles.</p>

<div w-nodev>

<h4>Sensitivity of data</h4>

Expand All @@ -98595,6 +98708,8 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
<p>To this end, user agents should ensure that when deleting data, it is promptly deleted from the
underlying storage.</p>

</div>


<!--ADD-TOPIC:Security-->
<h3 id="security-storage">Security</h3>
Expand All @@ -98620,6 +98735,8 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
path.</p>


<div w-nodev>

<h4>Implementation risks</h4>

<p>The two primary risks when implementing these persistent storage features are letting hostile
Expand All @@ -98640,6 +98757,8 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
important for user security.</p>
<!--REMOVE-TOPIC:Security-->

</div>



<h2 split-filename="syntax" id="syntax"><dfn>The HTML syntax</dfn></h2>
Expand Down