local-storage-to-object

This package contains the same functionality as window.localStorage, as it makes use of it, with the difference that everything that is stored in and fetched from window.localStorage will always be treated as an object.

Important

Note: This package is weighted to be used only on the client side, since it is necessary to use the window property of the browser.

Table of Contents

• Installation
• Basic Usage
• Methods Reference
  • setItem()
  • setItems()
  • getItem()
  • getItems()
  • removeItem()
  • getKeyName()
  • getCapacity()
• Data Types
  • SetItemsLocalStorage
  • GetItemsLocalStorage
• Resources

Installation

Using npm:

npm install --save local-storage-to-object

npm i local-storage-to-object

Basic Usage

For this example we will name it LocalStorage, but you can use anything else.

Example:

import LocalStorage from 'local-storage-to-object';

function myFuction() {
  // Do something...


  // Add values
  LocalStorage.setItem('keyLocalStorage', { isTesting: true });

  // Get values
  // Get an object stored in localStorage
  const valueLS = LocalStorage.getItem('keyLocalStorage');
  // valueLS = { isTesting: true }

  // Acceda a un valor específico del objeto almacenado en localStorage
  const _valueLS = LocalStorage.getItem('keyLocalStorage', 'isTesting');
  // _valueLS = true

  // Delete values
  // To delete a key and its value
  LocalStorage.removeItem('keyLocalStorage');

  // Multiple keys can also be deleted
  LocalStorage.removeItem(['keyLocalStorage']);

  // To completely clean the localStorage
  LocalStorage.removeItem();


  // Do something...
}

Example to store several keys at once:

import LocalStorage from 'local-storage-to-object';

function myFuction() {
  // Do something...


  LocalStorage.setItems([
    { key: 'keyLocalStorage', value: { isTesting: true } }
    { key: 'keyExample', value: { id: '123456', value: 10 } }
  ]);


  // Do something...
}

Example to get multiple keys at once. You can also access one of several values ​​of the returned object, and in case those values ​​do not exist, a default value is assigned to that value.:

import LocalStorage from 'local-storage-to-object';

function myFuction() {
  // Do something...


  LocalStorage.setItems([
    { key: 'keyLocalStorage', value: { isTesting: true } },
    { key: 'keyExample', value: { isExample: 1, data: null } }
  ]);

  const valueLS = LocalStorage.getItems([
    { key: 'keyLocalStorage' },
    { key: 'keyLocalStorage', value: 'isTesting' },
    { key: 'keyLocalStorage', value: 'isTesting.val' },
    {
      key: 'keyExample',
      value: ['isExample', 'data', 'id'],
      defaultValue: 'default'
    },
    { key: 'keyExample', value: ['isExample', 'data'] },
    { key: 'keyExample', value: 'data', defaultValue: [] },
    { key: 'keyFake' },
    { key: 'keyFake', value: 'items' }
  ]);
  /*
    valueLS = [
      { key: 'keyLocalStorage', localStorageData: { isTesting: true } },
      { key: 'keyLocalStorage', localStorageData: true },
      { key: 'keyLocalStorage', localStorageData: '*' },
      {
        key: 'keyExample',
        localStorageData: { isExample: 1, data: 'default', id: 'default' }
      },
      { key: 'keyExample', localStorageData: { isExample: 1, data: '*' } },
      { key: 'keyExample', localStorageData: [] },
      { key: 'keyFake', localStorageData: {} },
      { key: 'keyFake', localStorageData: '*' }
    ]
  */


  // Do something...
}

Example to obtain the name of a stored key, through the index:

import LocalStorage from 'local-storage-to-object';

function myFuction() {
  // Do something...


  LocalStorage.setItems([
    { key: 'keyLocalStorage', value: { isTesting: true } },
    { key: 'keyExample', value: { isExample: 1 } }
  ]);

  const valueLS = LocalStorage.getKeyName(0);
  // valueLS = 'keyLocalStorage'


  // Do something...
}

Example to count the number of stored keys:

import LocalStorage from 'local-storage-to-object';

function myFuction() {
  // Do something...


  LocalStorage.setItems([
    { key: 'keyLocalStorage', value: { isTesting: true } },
    { key: 'keyExample', value: { isExample: 1 } }
  ]);

  const valueLS = LocalStorage.getCapacity();
  // valueLS = 2


  // Do something...
}

Read the tests of each of the methods in the tests to get a clearer idea of ​​the capabilities of their use.

Methods Reference

Description of each of the methods.

• LocalStorage.setItem(key, value)

• LocalStorage.setItems(items)

• LocalStorage.getItem(key, value, defaultValue)

• LocalStorage.getItems(items)

• LocalStorage.removeItem(key)

• LocalStorage.getKeyName()

• LocalStorage.getCapacity()

setItem()

LocalStorage.setItem(key, value);

Before storing a new value in localStorage, it is validated if the 'key' exists inside localStorage, in order to be able to merge the new values ​​under the same object.

• If the 'key' already exists, it will extract from localStorage, the object that matches the 'key', and its values ​​will be merged with those of the new object, so that the new values ​​can overwrite one or several values ​​of the existing ones, in addition to add new values ​​to the object.

• If the 'key' does not exist, it will simply be added with its respective value object.

  Parameters:

  | Name | Type | Default | Description | | -----|------|---------|------------ | | key | string | N/A | Name on which the values ​​will be stored in localStorage | | value | object | N/A | Value or values ​​to store in localStorage |

  Does not return any value.

setItems()

LocalStorage.setItems(items);

It allows to store several keys with their respective objects, at the same time.

• For each element that exists in the array, first get the localStorage object that matches the 'key' of the current element and combine the existing values ​​with the new values. This new value is stored under the current 'key'.

  Parameters:

  | Name | Type | Default | Description | | -----|------|---------|------------ | | items | SetItemsLocalStorage | N/A | Array of objects to store in localStorage |

  Does not return any value.

getItem()

LocalStorage.getItem(key, value?, defaultValue?);

To get a value, look inside localStorage for the object that matches the value of 'key', and return the entire object.

• If the value is not found, an empty object will be returned.

• From the object returned from localStorage, a single value can be accessed instead of the entire object.

• You can set a default value, in case you want to access an attribute of the object returned by localStorage, and it does not exist.

• If the second argument is passed as an array, multiple objects can be requested, and those that are not found will be returned with the default value assigned.

  Parameters:

  | Name | Type | Default | Description | | -----|------|---------|------------ | | key | string | N/A | Name of values ​​stored in localStorage | | value | string \| string[] | N/A | Value or values ​​that you want to access | | defaultValue | any | * | Default value in case value does not exist |

  Return an object that matches the value of 'key' or an empty object.

getItems()

LocalStorage.getItems(items);

Allows you to get multiple keys from localStorage, as well as the object assigned to each key.

• For each element that exists in the array, it allows obtaining the value corresponding to that 'key', a single element of that 'key' or multiple elements existing in the current 'key'.

  Parameters:

  | Name | Type | Default | Description | | -----|------|---------|------------ | | items | GetItemsLocalStorage | N/A | Array of objects to get from localStorage |

  Return an array of objects matching each of the 'key' or an empty array.

removeItem()

LocalStorage.removeItem(key?);

You can completely clean localStorage or remove one or more 'keys'. Keep in mind that when removing 'keys', their assigned objects will also be removed.

• If 'key' is passed as a string, the matching 'key' will be removed, as well as its assigned object.

• If the 'key' is passed as an array, all matching 'keys' will be removed, as well as their assigned objects.

• If the 'key' is not passed, the entire localStorage will be cleaned, regardless of whether there are values ​​that were added with this functionality or not.

  Parameters:

  | Name | Type | Default | Description | | -----|------|---------|------------ | | key | string \| string[] | N/A | Name(s) on which to delete the values ​​in localStorage |

  Does not return any value.

getKeyName()

LocalStorage.getKeyName();

When passed a number n, this method returns the name of the nth key in storage.

Return the name of the index found, if it does not exist it returns an empty string.

getCapacity()

LocalStorage.getCapacity();

Get the number of 'keys' stored in localStorage.

Devuelve el número de 'claves' almacenadas en localStorage.

Data Types

SetItemsLocalStorage

This data type is an array of objects, where each object has the following structure.

Interface:

| Name | Type | Description | | -----|------|------------ | | key | string | Name on which the values ​​will be stored in localStorage | | value | object | Value or values ​​to store in localStorage |

GetItemsLocalStorage

This data type is an array of objects, where each object has the following structure.

Interface:

| Name | Type | Description | | -----|------|------------ | | key | string | Name of values ​​stored in localStorage | | value | string \| string[] | Value or values ​​that you want to access | | defaultValue | any | Default value in case value does not exist |

Resources

• Changelog
• Tests

License

MIT