Build Status License Library minified size Library minified + gzipped size

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);

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

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>

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));

• 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;
  }

Released under MIT License.