resources/src/mediawiki.storage/index.js

   1 /**
   2  * A safe interface to HTML5 `localStorage` and `sessionStorage`.
   3  *
   4  * This normalises differences across browsers and silences any and all
   5  * exceptions that may occur.
   6  *
   7  * **Note**: Storage keys are not automatically prefixed in relation to
   8  * MediaWiki and/or the current wiki. Always **prefix your keys** with "mw" to
   9  * avoid conflicts with gadgets, JavaScript libraries, browser extensions,
  10  * internal CDN or webserver cookies, and third-party applications that may
  11  * be embedded on the page.
  12  *
  13  * **Warning**: This API has limited storage space and does not use an expiry
  14  * by default. This means unused **keys are stored forever**, unless you
  15  * opt-in to the `expiry` parameter or otherwise make sure that your code
  16  * can rediscover and delete keys you created in the past.
  17  *
  18  * If you don't use the `expiry` parameter, avoid keys with variable
  19  * components as this leads to untracked keys that your code has no way
  20  * to know about and delete when the data is no longer needed. Instead,
  21  * store dynamic values in an object under a single constant key that you
  22  * manage or replace over time.
  23  * See also T121646.
  24  *
  25  * @example mw.storage.set( key, value, expiry );
  26  * mw.storage.set( key, value ); // stored indefinitely
  27  * mw.storage.get( key );
  28  *
  29  * @example var local = require( 'mediawiki.storage' ).local;
  30  * local.set( key, value, expiry );
  31  * local.get( key );
  32  *
  33  * @example mw.storage.session.set( key, value );
  34  * mw.storage.session.get( key );
  35  *
  36  * @example var session = require( 'mediawiki.storage' ).session;
  37  * session.set( key, value );
  38  * session.get( key );
  39  *
  40  * @module mediawiki.storage
  41  */
  42 'use strict';
  43
  44 // Catch exceptions to avoid fatal in Chrome's "Block data storage" mode
  45 // which throws when accessing the localStorage property itself, as opposed
  46 // to the standard behaviour of throwing on getItem/setItem. (T148998)
  47 const
  48         localStorage = ( function () {
  49                 try {
  50                         return window.localStorage;
  51                 } catch ( e ) {}
  52         }() ),
  53         sessionStorage = ( function () {
  54                 try {
  55                         return window.sessionStorage;
  56                 } catch ( e ) {}
  57         }() );
  58
  59 const SafeStorage = require( './SafeStorage.js' );
  60
  61 /**
  62  * Alias for {@link module:mediawiki.storage.local}.
  63  *
  64  * @type {SafeStorage}
  65  * @memberof mw
  66  * @property {SafeStorage} session Alias for {@link module:mediawiki.storage.session}.
  67  */
  68 mw.storage = new SafeStorage( localStorage );
  69 mw.storage.session = new SafeStorage( sessionStorage );
  70
  71 module.exports = {
  72         /**
  73          * A safe interface to HTML5 `localStorage`.
  74          *
  75          * @type {SafeStorage}
  76          */
  77         local: mw.storage,
  78
  79         /**
  80          * A safe interface to HTML5 `sessionStorage`.
  81          *
  82          * **Note**: Data persisted via `sessionStorage` will persist for the lifetime
  83          * of the browser *tab*, not the browser *window*.
  84          * For longer-lasting persistence across tabs, refer to mw.storage or mw.cookie instead.
  85          *
  86          * @type {SafeStorage}
  87          */
  88         session: mw.storage.session
  89 };