Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
P

persist-js

> 编程语言
Open source

PersistJS is a JavaScript client-side persistent storage library

392 stars0 likes3 views
WebsiteGitHub

About

PersistJS is a JavaScript client-side persistent storage library

[DEPRECATED] This repository is no longer maintained

This fork is no longer maintained. It is left here for existing projects that may use it to prevent breaking dependencies.

PersistJS 0.3.1 README

Table of Contents

  1. Introduction

  2. Rationale

  3. Using PersistJS

  4. Size Limits

  5. Other Limits

  6. Extending PersistJS

  7. Where is it being used?

  8. About the Author

  9. Introduction


PersistJS is a JavaScript client-side persistent storage library.

PersistJS features include:

  • Small ( My Wonderful Page

After the DOM has loaded, you create a persistent store object:

// create new store named "My Application"
var store = new Persist.Store('My Application');

The store constructor has one required parameter: a store name. You can create as many stores as you'd like, as long as they each have a unique name. Store names should begin with a letter, and can consist of upper and lower case letters, numbers, spaces, and dashes.

As I mentioned before, you shouldn't create a persistent store until after the DOM has loaded. The easiest browser-agnostic way to do this is to set an onload handler on the body element, like this:

And the JavaScript:

// global object
var store;

function load_data() {
  // load persistent store after the DOM has loaded
  store = new Persist.Store('My Application');
}

Most popular JavaScript libraries such have their own way of adding DOM ready handlers. Here's how you do it in jQuery:

$(function() {
  // load persistent store after the DOM has loaded
  store = new Persist.Store('My Application');
});

And in YUI:

function init() {
  store = new Persist.Store('My Application');
}

// call when the DOM has loaded
YAHOO.util.Event.onDOMReady(init);

Anyway, after you have created a persistent store, you save values to the it:

// save data in store
store.set('some_key', 'this is a bunch of persistent data');

Note that the value must be a string. If you want to save structured data like arrays or hashes, you should serialize it using Array.join or JSON.

Once you have saved a value to the store, you can read it back, like this:

// get value from store and prompt user
val = store.get('some_key')

Here's an example of removing a key:

// remove key from store and prompt user
store.remove('some_key') 
// prompt user
alert('some_key was removed');

If you're in a hurry, then you can stop reading right now, because that's all you need to know!

Still here? Okay, here are some additional details. When you create a new store, you can also pass a hash of optional parameters, like so:

// create a new deferred data store with a description
var store = new Persist.Store('My Data Store', {
  about: 'This is my data store.',
  defer: true
});

These parameters allow you to pass additional information or fine-tune the behavior of the data store. Here's a complete list of the available parameters:

  • defer: Defer saving until save() is called (used by ie). See below for additional details.
  • domain: Limit store to given domain or sub-domain (used by cookie and globalstore).
  • expires: Number of days before store expires (used by cookie).
    Defaults to 2 years (730 days).
  • path: Limit store to given path (used by cookie).
  • size: Estimated size of data set (used by whatwg_db).
  • swf_path: Path to file persist.swf (used by flash). Defaults to ./persist.swf if unspecified.

Notes: The defer option exists because there is no way to load and save individual keys in the ie backend. By default, the ie backend will load all data when getting a value, and save all data when setting a value. When the defer flag is set, the store data will only be loaded when the store is created or when the load() method is called.

More importantly, data will not be saved unless the save() method is called. If you choose to use the defer flag, the easiest way to make sure save() is called is to use an unload handler, like so:

And the JavaScript:

function save_data() {
  // save store data
  store.save();
}

It's probably best not to use this feature unless you really need it.

One final note about the Flash and Gears backends: They will be disabled unless you include swfobject.js and gears_init.js, respectively. These files are available in the extras/ directory.

If you'd rather include all of these in one combined file (to enable and check for all possible backends), you can use the file extras/persist-all-min.js in place of persist-min.js. persist-all-min.js is the the following files concatenated together and minified:

  • extras/gears_init.js
  • extras/swfobject.js
  • persist-min.js

Note that persist-all-min.js is roughly 60% larger than persist-min.js.

  1. Size Limits

Each backend has a different data size limit. While you generally aren't concerned about which backend is being used, you may care about the amount of data you are able to store.

To deal with this, the attribute Persist.size is set to the approximate size limit, in bytes, of the active backend. For backends where the size limit is unlimited or unknown, Persist.size is set to -1. Here's a rough breakdown of the size limits for each backend:

  • cookie: 4 kilobytes
  • gears: unknown
  • flash: unknown (at least 100k)
  • globalstorage: 5 megabytes
  • ie: 64 kilobytes
  • localstorage: unknown

(Note that the key length is also included in the data size limit).

Rather than testing for a specific backend, it is probably better to calculate the approximate size of the data that you need to save, and then prompt the user if there is insufficient space. For example:

var lots_of_data = '...'; // value with lots of data

try {
  // check size of data
  if (Persist.size != -1 && Persist.size < lots_of_data.length)
    throw new Error('too much data');

  // try and save data
  store.set('some_key', lots_of_data);
} catch (err) {
  // display save error
  alert("Couldn't save data: " + err);
}

If you absolutely must know which backend is in use, you can do so by checking the Persist.type value. Also, if you'd like to disable a specific backend, use Persist.remove(), like this:

// disable "cookie" backend (will never be selected)
Persist.remove('cookie');
  1. Other Limits

The cookie backend is limited by the number of maximum number of cookies that can be saved by the browser. Older browsers typically limited the number of cookies to 20 per domain, although newer browsers have increased this limit to 50 cookies per domain.

You can work around this limit by serializing your data as JSON or some other format.

The cookie backend is the only backend with any practical limit on the number of keys.

  1. Extending PersistJS

PersistJS exposes one method -- Persist.add() -- for extending PersistJS and adding custom backends. This method is currently undocumented and may change in future versions.

PersistJS also includes a full copy of EasyCookie 0.2.1, which is exposed as Persist.Cookie. For documentation on the EasyCookie API, see the EasyCookie page at:

http://pablotron.org/software/easy_cookie/

  1. Where is it being used?

  • Beacon Interactive Systems (http://www.beaconinteractive.com)
  • MochaUI
  • tDash (http://tdash.org) - the only Twitter client that works in your browser, directly talking to Twitter.
  1. About the Author

Paul Duncan ([email protected]) - http://pablotron.org/

  1. Contributors

Jeremy Durham ([email protected]) - http://www.jeremydurham.com Marcus Spiegel ([email protected]) - http://marcusspiegel.de Matt Pizzimenti ([email protected]) - http://mjpizz.com Mayank Sharma ([email protected]) - http://mayanks.blogspot.com Maximilian Batz ([email protected]) - http://www.ideaday.de

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

JavaScript

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言