@vitorluizc/persistence
TypeScript icon, indicating that this package has built-in type declarations

1.0.1 • Public • Published

@vitorluizc/persistence

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

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.

Package Sidebar

Install

npm i @vitorluizc/persistence

Weekly Downloads

1

Version

1.0.1

License

MIT

Unpacked Size

13.8 kB

Total Files

7

Last publish

Collaborators

  • vitorluizc