Have ideas to improve npm?Join in the discussion! »

    @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.

    Install

    npm i @vitorluizc/persistence

    DownloadsWeekly Downloads

    5

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    13.8 kB

    Total Files

    7

    Last publish

    Collaborators

    • avatar