SimpleStorage

browser/simpleStorage. SimpleStorage

An abstract class allows you to build services that relay on browser storage (session/local) and simplifies the way you work it You can specify the storage type you want to use, the format in which you want to handle the data and even expiration time for it.

Constructor

(abstract) new SimpleStorage(optionsopt)

Source:
Tutorials:
Parameters:
Name Type Attributes Default Description
options Partial.<SimpleStorageOptions> <optional>
 {}

The options to customize the class.
Throws:

If instantiated without extending it.

Type
Error

Members

(protected) _data :SimpleStorageDictionary

Source:

This is the object/dictionary the class will use to sync the content of the storage. That way you won't need to write/read/parse from the storage every time you need to do something.

Type:

(protected) _options :SimpleStorageOptions

Source:

These are the options/settings the class uses in order to work the with the storage and the data.

Type:

(protected, nullable) _storage :SimpleStorageStorage

Source:

Once the class is initialized, this property will hold a reference to the SimpleStorageStorage being used.

Type:

(protected) _storageTypes :SimpleStorageStorageTypes

Source:

A dictionary with the storage types the class supports.

Type:

Methods

(protected) _addEntry(key, value, saveopt) → {Object|Promise}

Source:

Adds a new entry to the class data, and if save is used, saves it into the storage.

Parameters:
Name Type Attributes Default Description
key string

The entry key.
value Object | Promise

The entry value, or a Promise that resolves into the value.
save boolean <optional>
 true

Whether or not the class should save the data into the storage.
Returns:

If value is an Object, it will return the same object; but if value is a Promise, it will return the "promise chain".

Type
Object | Promise

(protected) _addResolvedEntry(key, value, save) → {Object}

Source:

This is the real method behind _addEntry. It Adds a new entry to the class data and, if save is used, it also saves it into the storage. The reason that there are two methods for this is, is because _addEntry can receive a Promise, and in that case, this method gets called after it gets resolved.

Parameters:
Name Type Description
key string

The entry key.
value Object

The entry value.
save boolean

Whether or not the class should save the data into the storage.
Returns:

The same data that was saved.

Type
Object

(protected) _delete(resetopt)

Source:

Deletes the class data from the storage.

Parameters:
Name Type Attributes Default Description
reset boolean <optional>
 true

Whether or not to reset the data to the initial data (_getInitialData), if entries area disabled, or to an empty object, if they are enabled.

(protected) _deleteEntry(key, saveopt) → {boolean}

Source:

Deletes an entry from the class data, and if save is used, the changes will be saved on the storage.

Parameters:
Name Type Attributes Default Description
key string

The entry key.
save boolean <optional>
 true

Whether or not the class should save the data into the storage after deleting the entry.
Returns:

Whether or not the entry was deleted.

Type
boolean

(protected) _deleteExpiredEntries(entries, expiration) → {Object}

Source:

Filters out a dictionary of entries by checking if they expired or not.

Parameters:
Name Type Description
entries Object

A dictionary of key-value, where the value is a SimpleStorageEntry.
expiration number

The amount of seconds that need to have passed in order to consider an entry expired.
Returns:

A new dictionary without the expired entries.

Type
Object

(protected) _deleteFromLocalStorage(key)

Source:

Deletes an object from the localStorage.

Parameters:
Name Type Description
key string

The object key.

(protected) _deleteFromSessionStorage(key)

Source:

Deletes an object from the sessionStorage.

Parameters:
Name Type Description
key string

The object key.

(protected) _deleteFromTempStorage(key)

Source:

Deletes an object from the "temp storage".

Parameters:
Name Type Description
key string

The object key.

(protected) _getData() → {Object}

Source:

Gets the data the class saves on the storage.

Returns:
Type
Object

(protected) _getEntry(key) → (nullable) {SimpleStorageEntry}

Source:

Gets an entry from the storage dictionary.

Parameters:
Name Type Description
key string

The entry key.
Throws:

If entries are not enabled.

Type
Error
Returns:

Whatever is on the storage, or null.

Type
SimpleStorageEntry

(protected) _getEntryValue(key) → (nullable) {SimpleStorageDictionary}

Source:

Gets the value of an entry.

Parameters:
Name Type Description
key string

The entry key.
Returns:
Type
SimpleStorageDictionary

(protected) _getFromLocalStorage(key) → (nullable) {SimpleStorageDictionary}

Source:

Gets an object from localStorage.

Parameters:
Name Type Description
key string

The key used to save the object.
Returns:
Type
SimpleStorageDictionary

(protected) _getFromSessionStorage(key) → (nullable) {SimpleStorageDictionary}

Source:

Gets an object from sessionStorage.

Parameters:
Name Type Description
key string

The key used to save the object.
Returns:
Type
SimpleStorageDictionary

(protected) _getFromTempStorage(key) → (nullable) {SimpleStorageDictionary}

Source:

Gets an object from the "temp storage".

Parameters:
Name Type Description
key string

The key used to save the object.
Returns:
Type
SimpleStorageDictionary

(protected) _getInitialData() → {SimpleStorageDictionary}

Source:

This method is called when the storage is deleted or resetted and if entries are disabled. It can be used to define the initial value of the data the class saves on the storage.

Returns:
Type
SimpleStorageDictionary

(protected) _hasEntry(key) → {boolean}

Source:

Checks whether an entry exists or not.

Parameters:
Name Type Description
key string

The entry key.
Returns:
Type
boolean

(protected) _initialize()

Source:

This method _"initializes" the class by validating custom options, loading the reference for the required storage and synchronizing the data with the storage.

(protected) _initializeStorage() → {SimpleStorageStorage}

Source:

This method checks the list of priorities from the storage.typePriority option and tries to find the first available storage.

Throws:

If none of the storage options are available.

Type
Error
Returns:
Type
SimpleStorageStorage

(protected) _initializeStorageData() → {Object}

Source:

Initializes the data on the class and if needed, on the storage. It first tries to load existing data from the storage, if there's nothing, it just sets an initial stage; but if there was something on the storage, and entries are enabled, it will try (if also enabled) to delete expired entries.

Returns:
Type
Object

(protected) _isLocalStorageAvailable(fallbackFromopt) → {boolean}

Source:

Checks whether localStorage is available or not.

Parameters:
Name Type Attributes Description
fallbackFrom string <optional>

In case it's being used as a fallback, this will be the name of the storage that wasn't available.
Returns:
Type
boolean

(protected) _isPromise(obj) → {boolean}

Source:

Checks whether an object is a Promise or not.

Parameters:
Name Type Description
obj *

The object to test.
Returns:
Type
boolean

(protected) _isSessionStorageAvailable(fallbackFromopt) → {boolean}

Source:

Checks whether sessionStorage is available or not.

Parameters:
Name Type Attributes Description
fallbackFrom string <optional>

In case it's being used as a fallback, this will be the name of the storage that wasn't available.
Returns:
Type
boolean

(protected) _isTempStorageAvailable(fallbackFromopt) → {boolean}

Source:

This method is just here to comply with the SimpleStorageStorage "interface" as the temp storage is always available.

Parameters:
Name Type Attributes Description
fallbackFrom string <optional>

In case it's being used as a fallback, this will be the name of the storage that wasn't available.
Returns:
Type
boolean

(protected) _mergeOptions(defaults, custom) → {SimpleStorageOptions}

Source:

Merges the class default options with the custom ones that can be sent to the constructor. The reason there's a method for this is because of a specific (edgy) use case: tempStorage can be a Proxy, and a Proxy without defined keys stops working after an Object.assign/spread.

Parameters:
Name Type Description
defaults SimpleStorageOptions

The class default options.
custom SimpleStorageOptions

The custom options sent to the constructor.
Returns:
Type
SimpleStorageOptions

(protected) _now() → {number}

Source:

Helper method to get the current timestamp in seconds.

Returns:
Type
number

(protected) _resetData(saveopt) → {Object}

Source:

Resets the data on the class; If entries are enabled, the data will become an empty object; otherwise, it will call this#_getInitialData.

Parameters:
Name Type Attributes Default Description
save boolean <optional>
 true

Whether or not the class should save the data into the storage.
Returns:
Type
Object

(protected) _save()

Source:

Saves the data from the class into the storage.

(protected) _setData(data, saveopt) → {Object|Promise}

Source:

Overwrites the data reference the class has and, if save is used, it also saves it into the storage.

Parameters:
Name Type Attributes Default Description
data Object | Promise

The new data, or a Promise that resolves into the new data.
save boolean <optional>
 true

Whether or not the class should save the data into the storage.
Returns:

If data is an object, it will return the same object; but if data is a Promise, it will return the "promise chain".

Type
Object | Promise

(protected) _setOnLocalStorage(key, value)

Source:

Sets an object into the localStorage.

Parameters:
Name Type Description
key string

The object key.
value Object

The object to save.

(protected) _setOnSessionStorage(key, value)

Source:

Sets an object into the sessionStorage.

Parameters:
Name Type Description
key string

The object key.
value Object

The object to save.

(protected) _setOnTempStorage(key, value)

Source:

Sets an object into the "temp storage".

Parameters:
Name Type Description
key string

The object key.
value Object

The object to save.

(protected) _setResolvedData(data, save) → {Object}

Source:

This is the real method behind _setData. It overwrites the data reference the class has and, if save is used, it also saves it into the storage. The reason that there are two methods for this is, is because _setData can receive a Promise, and in that case, this method gets called after it gets resolved.

Parameters:
Name Type Description
data Object

The new data.
save boolean

Whether or not the class should save the data into the storage.
Returns:

The same data that was saved.

Type
Object

(protected) _validateOptions()

Source:

Validates the class options before loading the storage and the data.

Throws:

  • If either storage.name or storage.key are missing from the options.

    Type
    Error

  • If the options have a custom logger but it doesn't have warn nor warning methods.

    Type
    Error

(protected) _warn(message)

Source:

Prints out a warning message. The method will first check if there's a custom logger (from the class options), otherwise, it will fallback to the console on the window option.

Parameters:
Name Type Description
message string

The message to print out.

(protected) _warnStorageFallback(from, to)

Source:

Prints out a message saying that the class is doing a fallback from a storage to another one.

Parameters:
Name Type Description
from string

The name of the storage that's not available.
to string

The name of the storage that will be used instead.