Skip to content

Commit a390122

Browse files
sideshowbarkerdomenic
sideshowbarker
authored and
domenic
committed
Add domintro blocks for “Web storage” interfaces
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.
1 parent ff81553 commit a390122

File tree

1 file changed

+146
-27
lines changed

1 file changed

+146
-27
lines changed

‎source

Lines changed: 146 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3060,6 +3060,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
30603060
<li>The <dfn data-x-href="https://tc39.github.io/ecma262/#sec-eval-x"><code>eval()</code></dfn> function</li>
30613061
<li>The <dfn data-x-href="https://tc39.github.io/ecma262/#sec-IsHTMLDDA-internal-slot">[[IsHTMLDDA]]</dfn> internal slot</li>
30623062
<li>The <dfn data-x="js-typeof" data-x-href="https://tc39.github.io/ecma262/#sec-typeof-operator"><code>typeof</code></dfn> operator</li>
3063+
<li>The <dfn data-x-href="https://tc39.github.io/ecma262/#sec-delete-operator"><code>delete</code></dfn> operator</li>
30633064
<li><dfn data-x-href="https://tc39.github.io/ecma262/#table-49">The <var>TypedArray</var> Constructors</dfn> table</li>
30643065
</ul>
30653066

@@ -98192,7 +98193,7 @@ interface <dfn>WorkerLocation</dfn> {
9819298193
-->
9819398194

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

@@ -98260,6 +98261,53 @@ interface <dfn>Storage</dfn> {
9826098261
implementing the <code>Storage</code> interface can all be associated with the same list of
9826198262
key/value pairs simultaneously.</p>
9826298263

98264+
<dl class="domintro">
98265+
98266+
<dt><var>storage</var> . <code subdfn data-x="dom-Storage-length">length</code></dt>
98267+
<dd>
98268+
<p>Returns the number of key/value pairs currently present in the list associated with the
98269+
object.</p>
98270+
<dd>
98271+
98272+
<dt><var>storage</var> . <code subdfn data-x="dom-Storage-key">key</code> ( <var>n</var> )</dt>
98273+
<dd>
98274+
<p>Returns the name of the <var>n</var>th key in the list, or null if <var>n</var> is greater
98275+
than or equal to the number of key/value pairs in the object.</p>
98276+
<dd>
98277+
98278+
<dt><var>value</var> = <var>storage</var> . <code subdfn data-x="dom-Storage-getItem">getItem</code> ( <var>key</var> )</dt>
98279+
<dt><var>value</var> = <var>storage</var>[<var>key</var>]</dt>
98280+
<dd>
98281+
<p>Returns the current value associated with the given <var>key</var>, or null if the given
98282+
<var>key</var> does not exist in the list associated with the object.</p>
98283+
<dd>
98284+
98285+
<dt><var>storage</var> . <code subdfn data-x="dom-Storage-setItem">setItem</code> ( <var>key</var>, <var>value</var> )</dt>
98286+
<dt><var>storage</var>[<var>key</var>] = <var>value</var></dt>
98287+
<dd>
98288+
<p>Sets the value of the pair identified by <var>key</var> to <var>value</var>, creating a new
98289+
key/value pair if none existed for <var>key</var> previously.</p>
98290+
98291+
<p>Throws a <span>"<code>QuotaExceededError</code>"</span> <code>DOMException</code> exception
98292+
if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage
98293+
for the site, or if the quota has been exceeded.)</p>
98294+
98295+
<dt><var>storage</var> . <code subdfn data-x="dom-Storage-removeItem">removeItem</code> ( <var>key</var> )</dt>
98296+
<dt><code>delete</code> <var>storage</var>[<var>key</var>]</dt>
98297+
<dd>
98298+
<p>Removes the key/value pair with the given <var>key</var> from the list associated with the
98299+
object, if a key/value pair with the given <var>key</var> exists.</p>
98300+
</dd>
98301+
98302+
<dt><var>storage</var> . <code subdfn data-x="dom-Storage-clear">clear</code>()</dt>
98303+
<dd>
98304+
<p>Empties the list associated with the object of all key/value pairs, if there are any.</p>
98305+
</dd>
98306+
98307+
</dl>
98308+
98309+
<div w-nodev>
98310+
9826398311
<p>The <dfn><code data-x="dom-Storage-length">length</code></dfn> attribute must return the number
9826498312
of key/value pairs currently present in the list associated with the object.</p>
9826598313

@@ -98291,8 +98339,7 @@ interface <dfn>Storage</dfn> {
9829198339
the method must do nothing.</p>
9829298340

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

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

98358+
</div>
98359+
9831198360
<p class="note">When the <code data-x="dom-Storage-setItem">setItem()</code>, <code
9831298361
data-x="dom-Storage-removeItem">removeItem()</code>, and <code
9831398362
data-x="dom-Storage-clear">clear()</code> methods are invoked, events are fired on the
@@ -98334,6 +98383,14 @@ interface <dfn>WindowSessionStorage</dfn> {
9833498383
<p>The <dfn><code data-x="dom-sessionStorage">sessionStorage</code></dfn> attribute represents the
9833598384
set of storage areas specific to the current <span>top-level browsing context</span>.</p>
9833698385

98386+
<dl class="domintro">
98387+
<dt><var>window</var> . <code subdfn data-x="dom-sessionStorage">sessionStorage</code></dt>
98388+
<dd>
98389+
<p>Returns the <code>Storage</code> object associated with that origin's session storage
98390+
area.</p>
98391+
</dd>
98392+
</dl>
98393+
9833798394
<p>Each <span>top-level browsing context</span> has a unique set of session storage areas, one for
9833898395
each <span>origin</span>.</p>
9833998396

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

98405+
<div w-nodev>
98406+
9834898407
<p class="note">The lifetime of a browsing context can be unrelated to the lifetime of the actual
9834998408
user agent process itself, as the user agent can support resuming sessions after a restart.</p>
9835098409

@@ -98361,19 +98420,21 @@ interface <dfn>WindowSessionStorage</dfn> {
9836198420

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

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

98429+
</div>
98430+
9837198431
<p id="sessionStorageEvent">When the <code data-x="dom-Storage-setItem">setItem()</code>, <code
9837298432
data-x="dom-Storage-removeItem">removeItem()</code>, and <code
9837398433
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
9837498434
exception or "do nothing" as defined above, then for every <code>Document</code> object whose
9837598435
<code>Window</code> object's <code data-x="dom-sessionStorage">sessionStorage</code> attribute's
98376-
<code>Storage</code> object is associated with the same storage area, other than <var>x</var>, <span>send a storage notification</span>.</p>
98436+
<code>Storage</code> object is associated with the same storage area, other than <var>x</var>,
98437+
<span w-nohtml>user agents</span> <span>send a storage notification</span>.</p>
9837798438

9837898439

9837998440
<h4>The <code data-x="dom-localStorage">localStorage</code> attribute</h4>
@@ -98390,6 +98451,20 @@ interface <dfn>WindowLocalStorage</dfn> {
9839098451
<!--INSERT FINGERPRINT-->
9839198452
</p>
9839298453

98454+
<dl class="domintro">
98455+
<dt><var>window</var> . <code subdfn data-x="dom-localStorage">localStorage</code></dt>
98456+
<dd>
98457+
<p>Returns the <code>Storage</code> object associated with that origin's local storage
98458+
area.</p>
98459+
<p>Throws a <span>"<code>SecurityError</code>"</span> <code>DOMException</code> if the
98460+
<code>Document</code>'s <span>origin</span> is an <span data-x="concept-origin-opaque">opaque
98461+
origin</span> or if the request violates a policy decision (e.g. if the user agent is
98462+
configured to not allow the page to persist data).</p>
98463+
</dd>
98464+
</dl>
98465+
98466+
<div w-nodev>
98467+
9839398468
<p>User agents must have a set of local storage areas, one for each <span>origin</span>.</p>
9839498469

9839598470
<p>User agents should expire data from the local storage areas only for security reasons or when
@@ -98404,10 +98479,10 @@ interface <dfn>WindowLocalStorage</dfn> {
9840498479

9840598480
<ol>
9840698481

98407-
<li><p>The user agent may throw a <span>"<code>SecurityError</code>"</span>
98408-
<code>DOMException</code> instead of returning a <code>Storage</code>
98409-
object if the request violates a policy decisions (e.g. if the user agent is configured to not
98410-
allow the page to persist data).</p></li>
98482+
<li><p>If the request violates a policy decision (e.g. if the user agent is configured to not
98483+
allow the page to persist data), the user agent may throw a
98484+
<span>"<code>SecurityError</code>"</span> <code>DOMException</code> instead of returning a
98485+
<code>Storage</code> object</p></li>
9841198486

9841298487
<li><p>If the <code>Document</code>'s <span>origin</span> is an <span
9841398488
data-x="concept-origin-opaque">opaque origin</span>, then throw a
@@ -98424,12 +98499,15 @@ interface <dfn>WindowLocalStorage</dfn> {
9842498499

9842598500
</ol>
9842698501

98502+
</div>
98503+
9842798504
<p id="localStorageEvent">When the <code data-x="dom-Storage-setItem">setItem()</code>, <code
9842898505
data-x="dom-Storage-removeItem">removeItem()</code>, and <code
9842998506
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
9843098507
exception or "do nothing" as defined above, then for every <code>Document</code> object whose
9843198508
<code>Window</code> object's <code data-x="dom-localStorage">localStorage</code> attribute's
98432-
<code>Storage</code> object is associated with the same storage area, other than <var>x</var>, <span>send a storage notification</span>.
98509+
<code>Storage</code> object is associated with the same storage area, other than <var>x</var>,
98510+
<span w-nohtml>user agents</span> <span>send a storage notification</span>.
9843398511

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

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

98445-
<p>The <code data-x="event-storage">storage</code> event is fired on a <code>Document</code>'s
98446-
<code>Window</code> object when a storage area changes, as described in the previous two sections
98447-
(<a href="#sessionStorageEvent">for session storage</a>, <a href="#localStorageEvent">for local
98448-
storage</a>).</p>
98523+
<p><span subdfn data-x="send a storage notification">The <code
98524+
data-x="event-storage">storage</code> event is fired on a <code>Document</code>'s
98525+
<code>Window</code> object when a storage area changes</span>, as described in the previous two
98526+
sections (<a href="#sessionStorageEvent">for session storage</a>, <a href="#localStorageEvent">for
98527+
local storage</a>).</p>
98528+
98529+
<div w-nodev>
9844998530

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

98565+
</div>
98566+
9848498567

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

@@ -98502,21 +98585,50 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
9850298585
<span>Storage</span>? storageArea = null;
9850398586
};</pre>
9850498587

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

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

98511-
<p>The <dfn><code data-x="dom-StorageEvent-newValue">newValue</code></dfn> attribute must return
98512-
the value it was initialized to. It represents the new value of the key being changed.</p>
98592+
<dd>
98593+
<p>Returns the key of the storage item being changed.</p>
98594+
</dd>
98595+
98596+
<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-oldValue">oldValue</code></dt>
98597+
98598+
<dd>
98599+
<p>Returns the old value of the key of the storage item whose value is being changed.</p>
98600+
</dd>
9851398601

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

98517-
<p>The <dfn><code data-x="dom-StorageEvent-storageArea">storageArea</code></dfn> attribute must
98518-
return the value it was initialized to. It represents the <code>Storage</code> object that was
98519-
affected.</p>
98604+
<dd>
98605+
<p>Returns the new value of the key of the storage item whose value is being changed.</p>
98606+
</dd>
98607+
98608+
<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-url">url</code></dt>
98609+
98610+
<dd>
98611+
<p>Returns the <span>URL</span> of the document whose storage item changed.</p>
98612+
</dd>
98613+
98614+
<dt><var>event</var> . <code subdfn data-x="dom-StorageEvent-storageArea">storageArea</code></dt>
98615+
98616+
<dd>
98617+
<p>Returns the <code>Storage</code> object that was affected.</p>
98618+
</dd>
98619+
98620+
</dl>
98621+
98622+
<div w-nodev>
98623+
98624+
<p>The <dfn><code data-x="dom-StorageEvent-key">key</code></dfn>, <dfn><code
98625+
data-x="dom-StorageEvent-oldValue">oldValue</code></dfn>, <dfn><code
98626+
data-x="dom-StorageEvent-newValue">newValue</code></dfn>, <dfn><code
98627+
data-x="dom-StorageEvent-url">url</code></dfn>, and <dfn><code
98628+
data-x="dom-StorageEvent-storageArea">storageArea</code></dfn> attributes must return the values
98629+
they were initialized to.</p>
98630+
98631+
</div>
9852098632

9852198633

9852298634
<h3>Disk space</h3>
@@ -98648,6 +98760,7 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
9864898760
user-specific data (e.g. user-agent headers and configuration settings) to combine separate
9864998761
sessions into coherent user profiles.</p>
9865098762

98763+
<div w-nodev>
9865198764

9865298765
<h4>Sensitivity of data</h4>
9865398766

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

98774+
</div>
98775+
9866198776

9866298777
<!--ADD-TOPIC:Security-->
9866398778
<h3 id="security-storage">Security</h3>
@@ -98683,6 +98798,8 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
9868398798
path.</p>
9868498799

9868598800

98801+
<div w-nodev>
98802+
9868698803
<h4>Implementation risks</h4>
9868798804

9868898805
<p>The two primary risks when implementing these persistent storage features are letting hostile
@@ -98703,6 +98820,8 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
9870398820
important for user security.</p>
9870498821
<!--REMOVE-TOPIC:Security-->
9870598822

98823+
</div>
98824+
9870698825

9870798826

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

0 commit comments

Comments
 (0)