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

nibelung

v0.5.0

Published

Caching library backed by browser local storage.

Downloads

8

Readme

Nibelung Circle CI

A library for caching things locally in websites or mobile apps.

Adds the following features to HTML localStorage and sessionStorage

  • Time-to-live (TTL).
  • Namespacing.
  • The ability to cap the number of records (uses an LRU strategy).
  • A simpler event API.
  • Basic version change detection.

Creating a Hoard:

You can create a name-spaced cache as follows:

var myCache = new nibelung.Hoard({ namespace: 'fooCache' });

The following options are supported:

{
  // Used to disambiguate records belonging to different cache instances.
  namespace: 'my-cache-name',

  // Default: false.  If true, data persists across browser sessions. If false,
  // data is discarded when the browser is closed.
  persistent: true,

  // If set to a positive integer, records will be retained for that number of
  // milliseconds only.  Otherwise, records will be retained indefinitely.
  ttlMilliseconds: 3600000, // One hour.

  // If set to a positive integer, the number of cache records will be capped
  // at that number.  Records will be dropped using a least-recently-used
  // strategy based on last write time.  If omitted, no cap will be enforced.
  maxRecords: 100,

  // Used to generate timestamps for records. Can be any object with a .now()
  // function that returns strings strictly ordered in time. If omitted,
  // Date.now() is used instead.
  clock: { now: function () { ... } }

  // Used to protect event handlers against reentrancy.  Reentrancy can happen
  // when an event handler makes changes to the cache, resulting in more events
  // happening within the callstack of the first event. Can be any object with
  // a .protect() function that executes its argument. If omitted,
  // window.setTimeout(handler, 0) is used instead.  
  reentrancyProtector: { protect: function (fn) { ... } }

  // Used to log warnings and errors that happen within the library.  Can be
  // any function that accepts a string argument. If omitted, no logs will be
  // generated.
  logger: function (message) { ... }

  // Most useful with persistent === true. Checks the given version string
  // against the current format of any previously saved records. If they don't
  // match, the versionChangeHandler.onVersionChange() will be called.
  version: '1',

  // Most useful with persistent === true. If the given version differs from
  // the version of previously-saved data, onVersionChange will be called with
  // the new and old versions respectively.  Returning true from
  // onVersionChange will cause the Hoard to be stamped with the new version;
  // returning false leaves it unchanged.  This gives you the ability to
  // react to version changes and handle them (e.g. by clearing the cache, or
  // upgrading existing records to the new schema).
  //
  // As a convenience, we also provide nibelung.ClearingVersionChangeHandler in
  // case you want to 'upgrade' by just deleting old data.
  versionChangeHandler: { onVersionChange: function (expectedVersion, actualVersion )}
}

Basic Operations:

Adding, fetching, and removing a single value is straightforward:

myCache.putOne('1', { id: 1, foo: 'bar'});

var myFoo = myCache.getOne('1');

myCache.deleteOne('1');

Batch Operations:

You can also use batch versions of these operations:

// Adds a bunch of objects as records, using the id property as the cache
// key.
myCache.put([
  { id: 1, foo: 'bar'},
  { id: 2, foo: 'baaaar', quux: 'foo'}],
  'id');

// Gets all objects matching the given keys, in the same order.
// Returns undefined
var myStuff = myCache.get([1, 2]);

// Deletes values for keys 1 and 2, ignored key 3.
myCache.remove([1, 2, 3]);

Events:

A Hoard instance can notify you about changes to its data. Use the on and off methods to register event handlers.


var myHandler = function(key, value) {
  console.log(key + 'was added with value ' + value);
}

// Start listening for events on this cache.
myCache.on('PUT', myHandler);

// Stop listenting for events on this cache.
myCache.off('PUT', myHandler);

The following events are supported:

  • PUT - fired when a value is added or updated.
  • REMOVE - fired when a value is explicitly removed, or discarded by the LRU or TTL logic.
  • CLEAR - fired when the hoard is cleared. Note that clear() will not also fire individual REMOVE events for each record.