Skip to content

Commit

Permalink
Add domintro blocks for “Web storage” interfaces
Browse files Browse the repository at this point in the history 
This change adds domintro blocks in the “Web storage” section and adds
markup to cause more implementer-specific parts of that section of the
spec to be suppressed in the developer edition.

While here, removed some bogus spec text that implied you could return
null for window.sessionStorage, contradicting the IDL and also the
sentence after it that said that such a storage area must always exist.
  • Loading branch information
@sideshowbarker @domenic
sideshowbarker authored and domenic committed Dec 12, 2017
1 parent ff81553 commit a390122
Showing 1 changed file with 146 additions and 27 deletions.
173 changes: 146 additions & 27 deletions source
View file
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 @@ -98192,7 +98193,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 @@ -98260,6 +98261,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>

<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 @@ -98291,8 +98339,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 @@ -98308,6 +98355,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 @@ -98334,6 +98383,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 @@ -98345,6 +98402,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 @@ -98361,19 +98420,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 @@ -98390,6 +98451,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 @@ -98404,10 +98479,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 @@ -98424,12 +98499,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 @@ -98442,10 +98520,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 @@ -98481,6 +98562,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 @@ -98502,21 +98585,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 @@ -98648,6 +98760,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 @@ -98658,6 +98771,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 @@ -98683,6 +98798,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 @@ -98703,6 +98820,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

0 comments on commit a390122

Please sign in to comment.