localstorage-language

A better way to interact and store data in a localstorage container.

Table of content

• Installation

• Usage (see API structure here)

  • Functions
    • get([options])
    • set(newLanguage[, options])
  • Types
    • GetOptions
    • SetOptions
  • Errors

• API structure

• Contributing

• License

• Credits to dependencies

Installation

A better way to store and retrieve clients' favorite language for your web apps!

npm i localstorage-localstorage

Usage

This module allows to get and set client's using language is its local storage.

get([options])

Get the i18n tag stored in the local storage.

Returns

• string - i18n tag stored in the local storage.
• undefined - No i18n tag is stored in the local storage.

Parameters

| Name | Type | Facultative | Description | | :-------: | :-------------------------: | :----------------: | ---------------- | | options | GetOptions | :white_check_mark: | Getter's options |

Throw

• CannotParse - The loaded value cannot be parsed.
• I18nNotString - The loaded i18n tag is not a string.
• InvalidI18n - The loaded i18n tag isn't valid (according to i18n-locales).

Examples

// { language: "en" }
get(); // "en"

// { language: "en" }
get({ key: "locale" }); // undefined

// { locale: "en" }
get({ key: "locale" }); // "en"

set(newLanguage[, options])

Set a i18n tag in the localstorage.

Returns

• void.

Parameters

| Name | Type | Facultative | Description | | :-----------: | :-----------------------: | :----------------: | --------------------- | | newLanguage | string | :x: | New i18n tag to store | | options | SetOptions | :white_check_mark: | Getter's options |

Throw

• MissingI18n - The i18n tag is not provided (undefined, null, empty string, ...).
• I18nNotString - The i18n tag is not a string.
• InvalidI18n - The i18n tag doesn't exist (according to i18n-locales).

Examples

// {}
set("en");
// { language: "en" }

// {}
set("en", { key: "locale" });
// { locale: "en" }

GetOptions

get() options.

Content

| Name | Type | Facultative | Description | | :----------------: | :-----: | :----------------: | -------------------------------------------------------------------------------------------------- | | destroy | boolean | :white_check_mark: | If strictly true, will destroy the entry after calling this function (even if an error occurred) | | destroyOnInvalid | boolean | :white_check_mark: | If strictly true, will destroy the entry only if an error occurred | | key | string | :white_check_mark: | Custom entry's key (default: language). Must be a non-empty string (or will be undefined) |

SetOptions

set() options.

Content

| Name | Type | Facultative | Description | | :---: | :----: | :----------------: | ------------------------------------------------------------------------------------------- | | key | string | :white_check_mark: | Custom entry's key (default: language). Must be a non-empty string (or will be undefined) |

Errors

| Name | Description | | :--------------: | ------------------------------------------- | | CannotParse | Cannot parse language's local storage entry | | KeyNotString | The local storage key is not a string | | InvalidI18n | The i18n tag doesn't exists | | I18nNotString | The i18n tag is not a string | | MissingI18nTag | Missing i18n tag |

API structure

localstorage-language
  |
  |- get([options])
  |- set(newLanguage[, options])
  |
  |- GetOptions
  |- SetOptions
  |
  \- errors
      |
      |- CannotParse
      |- KeyNotString
      |- InvalidI18n
      |- I18nNotString
      \- MissingI18nTag

Contributing

Feel free to open an issue if you want to report bugs or discuss about suggestions!

License

This package is published under the MIT license.

Credits to dependencies

Using multiple modules:

• dependencies:
  • improved-localstorage - Interactions with client's localstorage
• Development dependencies:
  • chai - Assertions (tests)
  • glob - Multiple files selection (build)
  • gulp - Tasks runner (build)
  • gulp-minify - Gulp plugin for files minifying (build)
  • gulp-rename - Gulp plugin for files renaming (build)
  • gulp-typescript - Gulp plugin for Typescript compilation (build)
  • merge2 - Combine streams (build)
  • node-localstorage - Localstorage simulation on Node.js (tests)
  • ts-mocha - Typescript version of Mocha (tests)
  • tsconfig-paths - Loader for tsconfig.json paths (tests)