index.bs

<pre class="metadata">
Title: Cookie Change Events
Shortname: cookie-change-events
Level: 1
Group: wicg
Status: ED
URL: https://patrickkettner.github.io/cookie-change-events
Editor: Patrick Kettner, Microsoft, patket@microsoft.com
Editor: Arron Eicholz, Microsoft, arronei@microsoft.com
Abstract: This specification describes an object based interface to cookies, and an API that can be used to attach events to cookie changes via javascript
Repository: patrickkettner/cookie-change-events
</pre>

<pre class=link-defaults>
spec:dom; type:interface; text:Document
</pre>

<section class="non-normative">
  <h2 id="introduction">Introduction</h2>
  <em>This section is non-normative.</em>

  Web Applications have conventionally had to poll document.cookie in order to
  know when a cookie has been modified or removed. In order to improve performance
  and reduce the use of unnecessary timers, this specification describes an API
  that allows for web developers to attach an event listener to `document.cookie`,
  and receive the relevant information about a cookie change via a callback. As a
  side effect of defining the data about the individual cookie that has changed,
  this document also creates an object based interface for getting and setting
  `document.cookie` values

</section>

<section>
  <h2 id="definitions">Definitions</h2>
  <section>
    <pre class="idl">
      dictionary CookieInit {
          USVString name;
          DOMString expires;
          long long maxAge;
          USVString domain;
          USVString path;
          boolean secure;
          required USVString value;
      };
    </pre>

    A {{CookieInit}} is a generic object that can be used to define a new cookie.
    You can set the following fields:
    <ul>
      <li><dfn for='CookieInit' dict-member>name</dfn> is the key value in the
      key value pairing for cookies. Because of backwards compatibility, it
      is not required.</li>
      <li><dfn for='CookieInit' dict-member>expires</dfn> is an optional string
      value of a <a href='https://tools.ietf.org/html/rfc1123'>RFC 1123 Date</a>, pursuant to <a href='https://tools.ietf.org/html/rfc6265#section-4.1.1'>RFC 6265§4.1.1</a></li>
      <li><dfn for='CookieInit' dict-member>maxAge</dfn> is an optional numeric
      value that, when specified, defines the number of seconds until the cookie
      expires, starting when the value is set, pursuant to <a href='https://tools.ietf.org/html/rfc6265#section-5.2.2'>RFC 6265§5.2.2</a></li>
      <li><dfn for='CookieInit' dict-member>domain</dfn> is an optional attribute
      that specifies what domain the cookie will be sent to, pursuant to
      <a href='https://tools.ietf.org/html/rfc6265#section-5.2.3'>RFC 6265§5.2.3</a>.</li>
      <li><dfn for='CookieInit' dict-member>path</dfn> is an optional attribute
      that will only give access to the cookie if the requested resource matches
      the specified path, pursuant to <a href='https://tools.ietf.org/html/rfc6265#section-5.2.4'>RFC 6265§5.2.4</a>.</li>
      <li><dfn for='CookieInit' dict-member>secure</dfn> is an optional boolean
      attribute that, when true, signals that the cookie can only be transmitted
      over "secure" protocols, as defined by the user agent. pursuant to
      <a href='https://tools.ietf.org/html/rfc6265#section-5.4'>RFC 6265§5.4</a>, subsection 1</li>
      <li><dfn for='CookieInit' dict-member>value</dfn> is the only required
      attribute. It is a string, as defined as a cookie-value in <a href='https://tools.ietf.org/html/rfc6265'>RFC 6265</a></li>
    </ul>
  </section>

  <section>
    <pre class="idl">
      [Constructor((CookieInit or USVString) cookie), Exposed=Window]
      interface Cookie {
          readonly attribute USVString name;
          attribute DOMString expires;
          attribute USVString value;
          readonly attribute USVString domain;
          readonly attribute USVString path;
          readonly attribute boolean secure;
          stringifier USVString ();
      };
    </pre>

    For backwards compatibility, the <dfn for='Cookie'>stringifier</dfn>
    for a {{Cookie}} returns the serialized version of the object in a format
    that is consistent with how a cookie is returned on the original document.cookie.
    The Cookie can be set via a {{CookieInit}} object, or via the same serialized string.
  </section>

  <section>
    <pre class="idl">
      [Exposed=Window]
      interface CookieJar : EventTarget {
          stringifier attribute USVString value;
          maplike&lt;USVString, Cookie&gt;;
          attribute EventHandler onchange;
          setter USVString ((Cookie or USVString) cookie);
      };
    </pre>

    {{CookieJar}} represents all of the current cookies set on a domain, and is
    available via `document.cookie`.
    <ul>
        <li><dfn for='CookieJar' attribute>value</dfn> is a seralized version of
        the current valid cookies, in the same format as the historical value 
        returns from `document.cookie`.</li>
        <li><dfn for='CookieJar' attribute>onchange</dfn> is an event handler to
        listen for a `change` event (see: [[#the-change-event]])</li>
    </ul>

    <pre class="idl">
      partial interface Document {
          [PutForwards=value] attribute CookieJar cookie;
      };
    </pre>

    For backwards compatibility, a {{CookieJar}}, when accessed as document.cookie,
    returns the serialized string version of a {{Cookie}}. However, a iterator
    is also defined, which returns the object form of {{Cookie}} on each iteration.

    <pre class="lang-js">
      let cookie = document.cookie
      typeof cookie === 'string' // returns true

      for (let cookie of document.cookie) {
        if (cookie.name === 'cookieIWantToDelete') {
          document.cookie.delete(cookie)
        }
      }
    </pre>
  </section>
  <section>
    <h2 id="the-change-event">the Change event</h2>
    <section>
      <pre class="idl">
        enum ChangeCause {
          "explicit",
          "evicted",
          "expired",
          "expired-overwrite",
          "overwrite",
          "created"
        };
      </pre>

      A {{ChangeCause}} is a string that represents the reason the cookie change
      event has been fired.
      <ul>
        <li><dfn for='ChangeCause' enum-value>explicit</dfn> is to be used when
        a delete() function has been called on a cookie called.</li>
        <li><dfn for='ChangeCause' enum-value>evicted</dfn> is to be used when
        when a cookie has been automatically removed due to garbage collection.</li>
        <li><dfn for='ChangeCause' enum-value>expired</dfn> is to be used when
        when a cookie's max-age value expires, or when the expires value is in the past.</li>
        <li><dfn for='ChangeCause' enum-value>expired-overwrite</dfn> is to be used when
        when a cookie's max-age value is set to 0, or when the expires value
        is overwritten with a value in the past</li>
        <li><dfn for='ChangeCause' enum-value>overwrite</dfn> is to be used when
        when a cookie's value is overwritten.</li>
        <li><dfn for='ChangeCause' enum-value>created</dfn> is to be used when
        when a cookie is created.</li>
      </ul>
    </section>

    <section>
      <pre class="idl">
        [Constructor(DOMString type, optional CookieChangeEventInit eventInitDict), Exposed=(Window)]
        interface CookieChangeEventInit : Event {
            attribute boolean removed;
            attribute ChangeCause cause;
            attribute Cookie cookie;
        };
      </pre>

      <pre class="idl">
        interface CookieChangeEvent : Event {
          readonly attribute boolean removed;
          readonly attribute ChangeCause cause;
          readonly attribute Cookie cookie;
        };
      </pre>

      A {{CookieChangeEvent}} is an event that is fired when a {{ChangeCause}}
      has been triggered.
      <ul>
        <li><dfn for='CookieChangeEvent' attribute>removed</dfn> is a boolean
          that represents whether or not a cookie has been removed from the {{CookieJar}}</li>
        <li><dfn for='CookieChangeEvent' attribute>cause</dfn> is a valid {{ChangeCause}},
        representing why a cookie the cookie in question has been modified.</li>
        <li><dfn for='CookieChangeEvent' attribute>cookie</dfn> is a valid {{Cookie}}, that
          represents the cookie that has been modified.</li>
      </ul>
    </section>
  </section>
</section>