{"_id":"persist-js","_rev":"3-7b6201c4f0ff95187e2dc56443526f09","name":"persist-js","description":"client-side persistent storage library","dist-tags":{"latest":"0.3.1"},"versions":{"0.3.1":{"name":"persist-js","version":"0.3.1","description":"client-side persistent storage library","main":"src/persist.js","repository":{"type":"git","url":"git+https://github.com/nl0/persist-js.git"},"keywords":["browser","persistance","localStorage"],"author":{"name":"Jeremy Durham","email":"jeremydurham@gmail.com"},"license":"ISC","bugs":{"url":"https://github.com/nl0/persist-js/issues"},"homepage":"https://github.com/nl0/persist-js#readme","gitHead":"07bab20d365b87291266a63ca5d8811f242e4d7f","_id":"persist-js@0.3.1","scripts":{},"_shasum":"69bc06128560f82029aed5217da27f2045eee8e9","_from":".","_npmVersion":"2.10.0","_nodeVersion":"0.12.3","_npmUser":{"name":"nl","email":"nl.imbecile@gmail.com"},"dist":{"shasum":"69bc06128560f82029aed5217da27f2045eee8e9","tarball":"https://registry.npmjs.org/persist-js/-/persist-js-0.3.1.tgz","integrity":"sha512-+TJO3g4OcgCX47Rv1Yidb3pr/79n49QblKMtlZD5eofodyj1F/pJaihhZdT717V54We9f7Uk5/dXktapBohhqQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQDRmyRQWPflRJdCq6HpOHjjpHJJN6t94Sq7l/IXG53z2QIhAOFFWkLZDDfIRDEF9V45MDqXxChcK9AHA2aahD7tfmR8"}]},"maintainers":[{"name":"nl","email":"nl.imbecile@gmail.com"}]}},"readme":"PersistJS 0.3.1 README\n======================\n\nTable of Contents\n-----------------\n  1. Introduction\n  2. Rationale\n  3. Using PersistJS\n  4. Size Limits\n  5. Other Limits\n  6. Extending PersistJS\n  7. Where is it being used?\n  8. About the Author\n\n1. Introduction\n---------------\nPersistJS is a JavaScript client-side persistent storage library.\n\nPersistJS features include:\n\n  * Small (<10k minified, 3k gzipped)\n  * Standalone: Does not need any additional browser plugins or\n    JavaScript libraries to work on the vast majority of current\n    browsers.\n  * Consistent: Provides a consistent, opaque API, regardless of\n    the browser.\n  * Extensible: Custom backends can be added easily.\n  * Backwards Compatible: Can fall back to flash or cookies if no\n    client-side storage solution for the given browser is available.\n  * Forwards Compatible: Supports the upcoming versions of Internet\n    Explorer, Firefox, Chrome, and Safari (Opera too, if you have Flash).\n  * Unobtrusive: Capability testing rather than browser detection, so\n    newer standards-conformant browsers will automatically be supported.\n\nThe latest version of PersistJS is always available online at the\nfollowing URL:\n\n    http://github.com/jeremydurham/persist-js\n\n2. Rationale\n------------\nWhy use PersistJS?  What's the problem with using cookies directly or\nsimply requiring Flash?\n\nCurrently the only reliable cross-platform and cross-browser mechanism\nfor storing data on the client side are cookies.  Unfortunately, using\ncookies to store persistent data has several problems:\n\n  * Size: Cookies are limited to about 4 kilobytes in size.\n  * Bandwidth: Cookies are sent along with every HTTP transaction.\n  * Complexity: Cookies are difficult to manipulate correctly.\n\nModern web browsers have addressed these issues by adding non-Cookie\nmechanisms for saving client-side persistent data.  Each of these\nsolutions are simpler to use than cookies, can store far more data, and\nare not transmitted along with HTTP requests.  Unfortunately, each\nbrowser has addressed the problem in a different and incompatible way.\nThere are currently 5 different client side persistent data solutions:\n\n  * globalStorage: Firefox 2.0+, Internet Explorer 8\n  * localStorage: development WebKit (Safari, iPhone, etc)\n  * openDatabase: Safari 3.1+\n  * userdata behavior: Internet Explorer 5.5+\n  * Google Gears: Chrome\n\nSome developers have attempted to address the client side storage\nissue with the following browser plugins:\n\n  * Adobe Flash\n  * Google Gears\n\nThe problem with relying on plugins, of course, is that users without\nthe plugin installed miss out on the feature in question, and your\napplication is dependent on software from a particular vendor.  Google\nGears, for example, is not widely deployed.  Flash is, but it has\nproblems of its own:\n\n  * Many users block Flash or require a click in order to enable\n    flash content; this makes Flash unsuitable as a transparent,\n    client-side data store.\n  * Flash is notoriously unreliable on newer 64-bit machines.\n  * Some businesses block Flash content as a security measure.\n\nAnyway, if we include Gears and Flash, that means there are no less than\n6 incompatible solutions for storing client-side persistent data.  \n\nThe most notable attempt at addressing this problem is probably Dojo\nStorage.  Unfortunately, Dojo Storage does not support Internet Explorer\nwithout Flash, and it does not support Safari or other WebKit-based\nbrowsers at all (at least, not without Flash).  Also, Dojo Storage is\nnot standalone; it requires a several other Dojo components in order to\noperate.\n\nPersistJS addresses all of the issues above.  It currently supports\npersistent client-side storage through the following backends:\n\n   * flash:         Flash 8 persistent storage.\n   * gears:         Google Gears-based persistent storage.\n   * localstorage:  HTML5 draft storage.\n   * globalstorage: HTML5 draft storage (old spec).\n   * ie:            Internet Explorer userdata behaviors.\n   * cookie:        Cookie-based persistent storage.\n\nEach backend is wrapped by PersistJS and exploses the exact same\ninterface, which means you don't have to know or care which backend is\nbeing used.  The next section explains how to use the PersistJS API.\n\n3. Using PersistJS\n------------------\nUsing PersistJS is fairly straightforward.  First, you include\n`persist-min.js` in your web site:\n\n    <head>\n      <title>My Wonderful Page</title>\n      <script type='text/javascript' src='persist-min.js'></script>\n    </head>\n\nAfter the DOM has loaded, you create a persistent store object:\n\n    // create new store named \"My Application\"\n    var store = new Persist.Store('My Application');\n\nThe store constructor has one required parameter: a store name.  You can\ncreate as many stores as you'd like, as long as they each have a unique\nname.  Store names should begin with a letter, and can consist of upper\nand lower case letters, numbers, spaces, and dashes.  \n\nAs I mentioned before, you shouldn't create a persistent store until\nafter the DOM has loaded.  The easiest browser-agnostic way to do this\nis to set an `onload` handler on the `body` element, like this:\n\n    <body onload='load_data();'>\n\nAnd the JavaScript:\n\n    // global object\n    var store;\n\n    function load_data() {\n      // load persistent store after the DOM has loaded\n      store = new Persist.Store('My Application');\n    }\n\nMost popular JavaScript libraries such have their own way of adding DOM\nready handlers.  Here's how you do it in jQuery:\n\n    $(function() {\n      // load persistent store after the DOM has loaded\n      store = new Persist.Store('My Application');\n    });\n\nAnd in YUI:\n\n    function init() {\n      store = new Persist.Store('My Application');\n    }\n\n    // call when the DOM has loaded\n    YAHOO.util.Event.onDOMReady(init);\n\nAnyway, after you have created a persistent store, you save values to\nthe it:\n\n    // save data in store\n    store.set('some_key', 'this is a bunch of persistent data');\n\nNote that the value must be a string.  If you want to save structured\ndata like arrays or hashes, you should serialize it using Array.join or\nJSON.\n\nOnce you have saved a value to the store, you can read it back, \nlike this:\n\n    // get value from store and prompt user\n    val = store.get('some_key')\n\nHere's an example of removing a key:\n\n    // remove key from store and prompt user\n    store.remove('some_key') \n    // prompt user\n    alert('some_key was removed');\n\nIf you're in a hurry, then you can stop reading right now, because\nthat's all you need to know!\n\nStill here?  Okay, here are some additional details.  When you create a\nnew store, you can also pass a hash of optional parameters, like so:\n\n    // create a new deferred data store with a description\n    var store = new Persist.Store('My Data Store', {\n      about: 'This is my data store.',\n      defer: true\n    });\n\nThese parameters allow you to pass additional information or fine-tune\nthe behavior of the data store.  Here's a complete list of the available\nparameters:\n\n  * defer:    Defer saving until `save()` is called (used by `ie`).  See\n              below for additional details.\n  * domain:   Limit store to given domain or sub-domain (used by `cookie`\n              and `globalstore`).\n  * expires:  Number of days before store expires (used by `cookie`).  \n              Defaults to 2 years (730 days).\n  * path:     Limit store to given path (used by `cookie`).\n  * size:     Estimated size of data set (used by `whatwg_db`).\n  * swf_path: Path to file `persist.swf` (used by `flash`).  Defaults to\n              `./persist.swf` if unspecified.\n\nNotes: The `defer` option exists because there is no way to load and\nsave individual keys in the `ie` backend.  By default, the `ie` backend\nwill load all data when getting a value, and save all data when setting\na value.  When the `defer` flag is set, the store data will only be\nloaded when the store is created or when the `load()` method is called.  \n\nMore importantly, data will _not_ be saved unless the `save()` method is\ncalled.  If you choose to use the `defer` flag, the easiest way to make\nsure `save()` is called is to use an unload handler, like so:\n\n    <body unload='save_data();'>\n\nAnd the JavaScript:\n\n    function save_data() {\n      // save store data\n      store.save();\n    }\n\nIt's probably best not to use this feature unless you really need it.\n\nOne final note about the Flash and Gears backends: They will be disabled\nunless you include swfobject.js and gears_init.js, respectively.  These\nfiles are available in the extras/ directory.\n\nIf you'd rather include all of these in one combined file (to enable and\ncheck for all possible backends), you can use the file\n`extras/persist-all-min.js` in place of `persist-min.js`.\n`persist-all-min.js` is the the following files concatenated together\nand minified:\n  \n  * extras/gears_init.js\n  * extras/swfobject.js\n  * persist-min.js\n\nNote that `persist-all-min.js` is roughly 60% larger than\n`persist-min.js`.\n\n4. Size Limits\n--------------\nEach backend has a different data size limit.  While you generally\naren't concerned about _which_ backend is being used, you may care about\nthe amount of data you are able to store.  \n\nTo deal with this, the attribute `Persist.size` is set to the\n_approximate_ size limit, in bytes, of the active backend.  For backends\nwhere the size limit is unlimited or unknown, `Persist.size` is set to\n`-1`.  Here's a rough breakdown of the size limits for each backend:\n\n  * cookie:         4 kilobytes\n  * gears:          unknown\n  * flash:          unknown (at least 100k)\n  * globalstorage:  5 megabytes\n  * ie:             64 kilobytes\n  * localstorage:   unknown \n\n(Note that the key length is also included in the data size limit).\n\nRather than testing for a specific backend, it is probably better to\ncalculate the approximate size of the data that you need to save, and\nthen prompt the user if there is insufficient space.  For example:\n\n    var lots_of_data = '...'; // value with lots of data\n\n    try {\n      // check size of data\n      if (Persist.size != -1 && Persist.size < lots_of_data.length)\n        throw new Error('too much data');\n\n      // try and save data\n      store.set('some_key', lots_of_data);\n    } catch (err) {\n      // display save error\n      alert(\"Couldn't save data: \" + err);\n    }\n\nIf you absolutely _must_ know which backend is in use, you can do so by\nchecking the `Persist.type` value.  Also, if you'd like to disable a\nspecific backend, use `Persist.remove()`, like this:\n\n    // disable \"cookie\" backend (will never be selected)\n    Persist.remove('cookie');\n\n5. Other Limits\n---------------\nThe `cookie` backend is limited by the number of maximum number of\ncookies that can be saved by the browser.  Older browsers typically\nlimited the number of cookies to 20 per domain, although newer browsers\nhave increased this limit to 50 cookies per domain.  \n\nYou can work around this limit by serializing your data as JSON or\nsome other format.\n\nThe `cookie` backend is the only backend with any practical limit on the\nnumber of keys.\n\n6. Extending PersistJS\n----------------------\nPersistJS exposes one method -- `Persist.add()` -- for extending\nPersistJS and adding custom backends.  This method is currently\nundocumented and may change in future versions.\n\nPersistJS also includes a full copy of EasyCookie 0.2.1, which is\nexposed as Persist.Cookie.  For documentation on the EasyCookie API, see \nthe EasyCookie page at:\n\n  http://pablotron.org/software/easy_cookie/\n\n7. Where is it being used?\n-------------------------\n* Beacon Interactive Systems (http://www.beaconinteractive.com)\n* MochaUI\n* tDash (http://tdash.org) - the only Twitter client that works in your\n    browser, directly talking to Twitter.\n\n8. About the Author\n-------------------\nPaul Duncan (pabs@pablotron.org) - http://pablotron.org/\n\n9. Contributors\n---------------\nJeremy Durham (jeremydurham@gmail.com) - http://www.jeremydurham.com\nMarcus Spiegel (marcus.spiegel@gmail.com) - http://marcusspiegel.de\nMatt Pizzimenti (mjpizz+github@gmail.com) - http://mjpizz.com\nMayank Sharma (mayanks@gmail.com) - http://mayanks.blogspot.com\nMaximilian Batz (m.batz@ideaday.de) - http://www.ideaday.de","maintainers":[{"name":"nl","email":"nl.imbecile@gmail.com"}],"time":{"modified":"2022-06-23T18:51:48.192Z","created":"2015-05-20T17:33:03.690Z","0.3.1":"2015-05-20T17:33:03.690Z"},"homepage":"https://github.com/nl0/persist-js#readme","keywords":["browser","persistance","localStorage"],"repository":{"type":"git","url":"git+https://github.com/nl0/persist-js.git"},"author":{"name":"Jeremy Durham","email":"jeremydurham@gmail.com"},"bugs":{"url":"https://github.com/nl0/persist-js/issues"},"license":"ISC","readmeFilename":"README.md"}