Class: LocalStorage

jrt.LocalStorage(dataKey, propertiesopt, nullable, compressedopt)

Class for storing string and object items in local storage, optionally compressed with LZW. Objects are serialized as a JSON string. Set and Map properties are supported transparently.

Items can be stored as "important". Important items are not removed when making room for a new item when storage is full (see setItem, setObject and save).

Note that important items are implemented internally by prepending "!" to their key, so you should not use "!" as the first character of your item's keys.

Constructor

new LocalStorage(dataKey, propertiesopt, nullable, compressedopt)

Creates an object which own properties can be stored in local storage under a single key.

Parameters:
Name Type Attributes Default Description
dataKey string

The stored object's key.
properties Object <optional>
<nullable>
 null

Object to copy properties from (optional).
compressed boolean <optional>
 true

True if the value is to be stored as a compressed UTF16 string.

Extends

Members

(protected, non-null) app :jrt.App

Reference to the app instance.

Type:
Overrides:

compressed :boolean

Indicates if the object is stored compressed or not.

Type:
  • boolean

dataKey :string

The stored object's key.

Type:
  • string

Methods

(static) clear(keepImportantopt)

Removes all items from local storage. It silently fails if local storage is not supported.

Parameters:
Name Type Attributes Default Description
keepImportant boolean <optional>
 false

If true, important items are not removed.

(static) getItem(key, decompressopt) → (nullable) {string}

Retrieves an item from local storage.

Parameters:
Name Type Attributes Default Description
key string

The item's key.
decompress boolean <optional>
 false

True if the value is stored as a compressed UTF16 string.
Returns:

Returns null if the item is not found or local storage is not supported.

Type
string

(static) getObject(key, decompressopt) → (nullable) {Object}

Retrieves an object from local storage. The object must have been previously stored as a JSON string with setObject.

Parameters:
Name Type Attributes Default Description
key string

The item's key.
decompress boolean <optional>
 true

True if the value is stored as a compressed UTF16 string.
Returns:

Returns null if the object is not found, it's not valid JSON, or local storage is not supported.

Type
Object

(static) keys(importantopt) → (non-null) {Array.<string>}

Returns the keys currently set in local storage.

Parameters:
Name Type Attributes Description
important boolean <optional>

If set to true/false, only important/unimportant keys are returned.
Returns:

Returns an empty array if local storage is not supported.

Type
Array.<string>

(static) removeItem(key)

Removes an item from local storage. It silently fails if local storage is not supported.

Parameters:
Name Type Description
key string

The item's key.

(static) setItem(key, value, importantopt, compressopt, makeRoomopt) → {boolean}

Stores a string in local storage.

Parameters:
Name Type Attributes Default Description
key string

The item's key.
value string

The string to store.
important boolean <optional>
 false

If false, the item is elligible for removal when storage is full.
compress boolean <optional>
 false

True if the value is to be stored as a compressed UTF16 string.
makeRoom boolean <optional>
 true

When true, if storage is full, room will be made by deleting non-important keys.
Returns:

True on success. False if local storage is not supported or storage is full.

Type
boolean

(static) setObject(key, objnon-null, importantopt, compressopt, makeRoomopt) → {boolean}

Stores an object in local storage as a JSON string.

Parameters:
Name Type Attributes Default Description
key string

The item's key.
obj Object

The object to store.
important boolean <optional>
 false

If false, the item is elligible for removal when storage is full.
compress boolean <optional>
 true

True if the value is to be stored as a compressed UTF16 string.
makeRoom boolean <optional>
 true

When true, if storage is full, room will be made by deleting other keys.
Returns:

True on success. False if local storage is not supported o storage is full.

Type
boolean

(protected) export() → (nullable) {Object}

Converts this object's properties to the serialized object's properties. The default implementation just returns a copy of this object's properties.

Returns:

An object as it must be serialized. If null, the object is removed.

Type
Object

getProperties() → (non-null) {Object}

Returns a new object containing this object's serializable properties.

Overrides:
Returns:
Type
Object

(protected) import(storedDatanon-null) → {boolean}

Converts the serialized object's properties to the properties required by this object. This implementation just copies in the serialized object's properties and returns true.

Parameters:
Name Type Description
storedData Object

Object with the serialized object's properties.
Returns:

False if the object cannot be imported.

Type
boolean

isEmpty() → {boolean}

Tells whether the object is empty or not. The default implementation returns true if all serializable properties have a null or undefined value.

Returns:
Type
boolean

load() → {boolean}

Sets this object's properties from the local storage object (stored as JSON). If the object key is not present in local storage, the object not modified. If the stored object's representation differs from this object's representation, then the import method must be implemented to make the conversion. If the object cannot be imported then local storage is deleted and the object is reset.

Returns:

True if the stored object exists and can be imported. False otherwise.

Type
boolean

remove()

Removes this object from local storage and resets its properties.

reset()

Resets the serializable properties in this object. The default implementation assigns null to every property. A reset object should always result in the isEmpty method returning true.

save(importantopt)

Saves the object's own properties in local storage as JSON. If the stored object's properties differ from this object's properties, then export must be implemented to make the conversion. Note that the object will not be saved but instead will be removed if jrt.Serializable#isEmpty returns true or export returns null.

If there is not enough local storage left, this method it will try to make room for the object by deleting non-important items (in an unspecified order).

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

If false, the item is elligible for removal when storage is full.

setProperties(propertiesnon-null)

Copies the specified object's enumerable properties to this object.

Parameters:
Name Type Description
properties Object
Overrides: