vitorluizc / persistence

💾 Persistence provides a pretty easy API to handle Storage's implementations.

@vitorluizc/persistence

Persistence provides a pretty easy API to handle Storage's implementations.

• ⚡ Pretty fast and smaller than 0.3KB (minified + gzipped ESM);
• 🏷️ Type definitions to TS developers and IDE/Editors autocomplete/intellisense;
• 📦 ESM, CommonJS and UMD distributions (CDN uses UMD as default);

Installation

This library is published in the NPM registry and can be installed using any compatible package manager.

npm install @vitorluizc/persistence --save

# For Yarn, use the command below.
yarn add @vitorluizc/persistence

Installation from CDN

This module has an UMD bundle available through JSDelivr and Unpkg CDNs.

<script src="https://cdn.jsdelivr.net/npm/@vitorluizc/persistence"></script>

<script>
  // module will be available through `persistence` function.

  var name = persistence('name', { placeholder: 'Unknown' });

  name.get();
  //=> 'Unknown'
</script>

Usage

It exports a factory function to create persistence. A persistence can easily set, get and delete JSON parseable values to any Storage implementation (ex. SessionStorage and LocalStorage).

import createPersistence from '@vitorluizc/persistence';

const persistence = createPersistence<string>('Name', {
  timeout: 1000 * 60 * 60 * 24, // A day in milliseconds
  storage: window.sessionStorage,
  placeholder: ''
});

// Setups field's value as a persistent state on session.
const field = document.querySelector('input[name="name"]');
field.value = persistence.get();
field.addEventListener('input', () => persistence.set(field.value));

API

• createPersistence

  The default exported factory function. It receives storage's key and, optionally, PersistenceOptions as arguments and returns a Persistence.

  import createPersistence from '@vitorluizc/persistence';
  
  const persistence = createPersistence('Storage\'s key', { placeholder: 'None' });

  TypeScript type definitions.

  
  

  declare const createPersistence: {
    <T = any, U = T> (
      name: string,
      options: PersistenceOptions & {
        placeholder: U;
      }
    ): Persistence<T, U>;
  
    <T = any, U = T | undefined> (
      name: string,
      options?: PersistenceOptions<U>
    ): Persistence<T, U>;
  };
  
  export default createPersistence;

• PersistenceOptions

  Options used as second argument on createPersistence to set timeout, storage and placeholder value to Persistence.

  import createPersistence, { PersistenceOptions } from '@vitorluizc/persistence';
  
  const options: PersistenceOptions<boolean> = {
    timeout: 1000 * 60 * 60, // 1 hour in milliseconds.
    placeholder: false
  };
  
  const persistence = createPersistence<boolean>('isSignedIn', options);

  TypeScript type definitions.

  
  

  export interface PersistenceOptions <T = any> {
    storage?: IStorage;
    timeout?: number;
    placeholder?: T;
  }

• Persistence

  An object with a pretty easy API to handle a Storage implementation.

  • get: Get value from persistent storage.

  • set: Set a value to a persistent storage.

  • delete: Delete value from persistent storage.

  import createPersistence, { Persistence } from '@vitorluizc/persistence';
  
  // ...
  
  type SignUpFormState = { nickname: string, };
  
  const state: Persistence<SignUpFormState> = createPersistence('state@name', {
    timeout: 1000 * 60 * 60 * 24, // A day in milliseconds
    placeholder: {
      nickname: ''
    },
  });
  
  
  $nickname.value = state.get().nickname;
  $nickname.on('keydown', (e) => state.set({ nickname: e.target.value }));
  
  $signUpForm.on('submit', (e) => {
    services.signUp(state.get());
  
    state.delete();
  });

  TypeScript type definitions.

  
  

  export interface Persistence <T = any, U = (T | undefined)> {
    get (): T | U;
    set (value: T): void;
    delete (): void;
  }

License

Released under MIT License.

persistence's Issues

Add has method to check if value is defined

Add .has() method to check if storage's key is defined.

Add watch method to listen window.onstorage if storage is LocalStorage

Add .listen(callback) method to listen window.onstorage event. It'll only work if storage is the localStorage, so this method can check when called and throw an error.