light-storage

A lightweight tool for handing localStorage.

• Serialization and deserialization
• Using prefix to avoid key collisions
• Support expiration
• Support call chaining
• Observer Pattern
• 100% test coverage

Install

• NPM

  npm install --save light-storage
  # or
  yarn add light-storage

  import LightStorage from 'light-storage';

• CDN

  <script src="https://cdn.jsdelivr.net/npm/light-storage@1/dist/light-storage.umd.min.js"></script>

Basic Usage

• Get instance

  // generate an instance with prefix
  const storage = new LightStorage('PREFIX');

• Set data

  • Set the value with the given key, creating a new value if none existed.

    storage.set('key', 'example');

  • Set the value that expires 2 minutes from now.

    storage.set('key', 'example', { maxAge: 2 * 60 * 1000 });

    If you need to time again, set update to true.

    storage.set('key', 'example', { maxAge: 2 * 60 * 1000, update: true });

  • Using call chaining.

    storage
      .select('key')
      .setValue('example')
      .setMaxAge(2 * 60 * 1000);
    
    // if need to update creation time
    storage.select('key').update();

• Get data

  Note: return undefined if none existed

  • Get the current value associated with the given key.

    storage.get('key');

  • Using call chaining.

    storage.select('key').value;

• Delete data

  • Remove the data with the given key.

    storage.remove('key');

  • Using call chaining.

    storage.select('key').remove();

  • Clear all.

    storage.clear();

• Watch

  Note: since v1.1.0, based on @xunmi/event-channel.

  Warning: can't watch if you use native operations (e.g. localStorage.setItem).

  • Watch the change of a value associated with the given key.

    const observer = (value, oldValue) => {
      // do something
    };
    
    storage.watch('key', observer);

  • Unwatch that stops firing the observer.

    storage.unwatch('key', observer);

  • Using call chaining.

    // watch
    storage.select('key').watch(observer);
    
    // unwatch
    storage.select('key').unwatch(observer);

Other Usage

• Get all keys.

  storage.keys;

• Set a new prefix to replace the original prefix.

  storage.prefix = 'NEW_PREFIX';

• Get other metadata associated with the given key.

  // return the created time
  storage.getCreatedTime('key');
  // return the `maxAge`
  storage.getMaxAge('key');
  // whether it contains the key
  storage.has('key');

• Synchronize data in the localStorage, and check validity.

  Note: If you use localstorage directly and things don't work as expected, you may need to use this function.

  storage.reload();