npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

lscache

v1.3.2

Published

A simple library that emulates memcache functions using HTML5 localStorage

Downloads

123,234

Readme

lscache

This is a simple library that emulates memcache functions using HTML5 localStorage, so that you can cache data on the client and associate an expiration time with each piece of data. If the localStorage limit (~5MB) is exceeded, it tries to create space by removing the items that are closest to expiring anyway. If localStorage is not available at all in the browser, the library degrades by simply not caching and all cache requests return null.

Methods

The library exposes these methods: set(), get(), remove(), flush(), flushExpired(), setBucket(), resetBucket(), setExpiryMilliseconds().


lscache.set

Stores the value in localStorage. Expires after specified number of minutes.

Arguments

  1. key (string)
  2. value (Object|string)
  3. time (number: optional)

Returns

boolean : True if the value was stored successfully.


lscache.get

Retrieves specified value from localStorage, if not expired.

Arguments

  1. key (string)

Returns

string | Object : The stored value. If no value is available, null is returned.


lscache.remove

Removes a value from localStorage.

Arguments

  1. key (string)

lscache.flush

Removes all lscache items from localStorage without affecting other data.


lscache.flushExpired

Removes all expired lscache items from localStorage without affecting other data.


lscache.setBucket

Appends CACHE_PREFIX so lscache will partition data in to different buckets.

Arguments

  1. bucket (string)

lscache.resetBucket

Removes prefix from keys so that lscache no longer stores in a particular bucket.


lscache.setExpiryMilliseconds

Sets the number of milliseconds each time unit represents in the set() function's "time" argument. Sample values:

  • 1: each time unit = 1 millisecond
  • 1000: each time unit = 1 second
  • 60000: each time unit = 1 minute (Default value)
  • 3600000: each time unit = 1 hour

Arguments

  1. milliseconds (number)

Usage

The interface should be familiar to those of you who have used memcache, and should be easy to understand for those of you who haven't.

For example, you can store a string for 2 minutes using lscache.set():

lscache.set('greeting', 'Hello World!', 2);

You can then retrieve that string with lscache.get():

alert(lscache.get('greeting'));

You can remove that string from the cache entirely with lscache.remove():

lscache.remove('greeting');

You can remove all items from the cache entirely with lscache.flush():

lscache.flush();

You can remove only expired items from the cache entirely with lscache.flushExpired():

lscache.flushExpired();

You can also check if local storage is supported in the current browser with lscache.supported():

if (!lscache.supported()) {
  alert('Local storage is unsupported in this browser');
  return;
}

You can enable console warning if set fails with lscache.enableWarnings():

// enable warnings
lscache.enableWarnings(true);

// disable warnings
lscache.enableWarnings(false);

The library also takes care of serializing objects, so you can store more complex data:

lscache.set('data', {'name': 'Pamela', 'age': 26}, 2);

And then when you retrieve it, you will get it back as an object:

alert(lscache.get('data').name);

If you have multiple instances of lscache running on the same domain, you can partition data in a certain bucket via:

lscache.set('response', '...', 2);
lscache.setBucket('lib');
lscache.set('path', '...', 2);
lscache.flush(); //only removes 'path' which was set in the lib bucket

The default unit for the set() function's "time" argument is minutes. A shorter time may be desired, for example, in unit tests. You can use lscache.setExpriryMilliseconds() to select a finer granularity of time unit:

asyncTest('Testing set() and get() with different units', function() {´
  var expiryMilliseconds = 1000;  //time units is seconds
  lscache.setExpiryMilliseconds(expiryMilliseconds);
  var key = 'thekey';
  var numExpiryUnits = 2; // expire after two seconds
  lscache.set(key, 'some value', numExpiryUnits);
  setTimeout(function() {
    equal(lscache.get(key), null, 'We expect value to be null');
    start();
  }, expiryMilliseconds*numExpiryUnits + 1);
});

For more live examples, play around with the demo here: http://pamelafox.github.com/lscache/demo.html

Real-World Usage

This library was originally developed with the use case of caching results of JSON API queries to speed up my webapps and give them better protection against flaky APIs. (More on that in this blog post)

For example, RageTube uses lscache to fetch Youtube API results for 10 minutes:

var key = 'youtube:' + query;
var json = lscache.get(key);
if (json) {
  processJSON(json);
} else {
  fetchJSON(query);
}

function processJSON(json) {
  // ..
}

function fetchJSON() {
  var searchUrl = 'http://gdata.youtube.com/feeds/api/videos';
  var params = {
   'v': '2', 'alt': 'jsonc', 'q': encodeURIComponent(query)
  }
  JSONP.get(searchUrl, params, null, function(json) {
    processJSON(json);
    lscache.set(key, json, 10);
  });
}

It does not have to be used for only expiration-based caching, however. It can also be used as just a wrapper for localStorage, as it provides the benefit of handling JS object (de-)serialization.

For example, the QuizCards Chrome extensions use lscache to store the user statistics for each user bucket, and those stats are an array of objects.

function initBuckets() {
  var bucket1 = [];
  for (var i = 0; i < CARDS_DATA.length; i++) {
    var datum = CARDS_DATA[i];
    bucket1.push({'id': datum.id, 'lastAsked': 0});
  }
  lscache.set(LS_BUCKET + 1, bucket1);
  lscache.set(LS_BUCKET + 2, []);
  lscache.set(LS_BUCKET + 3, []);
  lscache.set(LS_BUCKET + 4, []);
  lscache.set(LS_BUCKET + 5, []);
  lscache.set(LS_INIT, 'true')
}

Browser Support

The lscache library should work in all browsers where localStorage is supported. A list of those is here: http://www.quirksmode.org/dom/html5.html

Building

For contributors:

  • Run npm install to install all the dependencies.
  • Run grunt. The default task will check the files with jshint, minify them, and use browserify to generate a bundle for testing.
  • Run grunt test to run the tests.

For repo owners, after a code change:

  • Run grunt bump to tag the new release.
  • Run npm login, npm publish to release on npm.