Class: StorageNamespace

StorageNamespace

new StorageNamespace(name, storage)

Storage Namespace class.

This class allows us to "unflatten" and "typen" the client Storage (localStorage or sessionStorage) i.e. allows us to introduce an artificial hierarchy within the Storage.

This works by prefixing the key names with a namespace, allowing the clearing of a set of values by namespace, as well as storing values by the same name within different namespaces e.g. creating to StorageNamespace instances named "a/b" and "a/z" and setting a value on key "org.jenkins.magickey" on both would work perfectly fine as they would be stored in the underlying storage via keys "a/b:org.jenkins.magickey" and "a/z:org.jenkins.magickey".

Parameters:
Name Type Description
name string The name of the namespace. A forward slash separated value indicates sub-namespacing e.g. "a/b".
storage Storage The storage instance to use e.g. window.localStorage or window.sessionStorage.
Source:
Examples
// Store some info in a namespace.
const storage = require('@jenkins-cd/storage');
const jenkinsInstance = storage.localNamespace('jenkins-instance');
jenkinsInstance.set('currentVersion', versionString);
jenkinsInstance.set('currentPlugins', pluginsArray);
// After detecting that the Jenkins instance version has changed, or
// active plugins have changed, lets clear the "jenkins-instance"
// namespace.
const storage = require('@jenkins-cd/storage');
const jenkinsInstance = storage.localNamespace('jenkins-instance');
jenkinsInstance.clear(); // Clear all NVPs in that namespace only.

Methods

clear(clearSubspacesopt)

Clear all stored values in this namespace.
Parameters:
Name Type Attributes Description
clearSubspaces boolean <optional>
 Also clear subspace values. Default true.
Source:

count(countSubspacesopt) → {number}

Get the count of stored values in this namespace.

Note that this is not a "free" operation. This function iterates the namespace values in order to count.

Parameters:
Name Type Attributes Description
countSubspaces boolean <optional>
 Also count subspace values. Default true.
Source:
Returns:
The count of stored values in this namespace.
Type
number

get(name, optionsopt) → {string|object|boolean|number|undefined}

Get a value from the namespace.

Options controlling the get can be configured by the optional "options" object argument. Available options:

  • "checkDotParent": Flag (true/false) or an array of permitted values, indicating that if the name is (e.g.) "a.b.c" and no value is found for that name (or the found value is not permitted), then fall back and check "a.b" and then "a" etc.
Parameters:
Name Type Attributes Description
name string The name/key.
options object <optional>
 Used to configure the secondary checks that should be made should there not be a value for the initially specified key. See examples below.
Source:
Returns:
The value.
Type
string | object | boolean | number | undefined
Examples
// get a value from a namespace
const storage = require('@jenkins-cd/storage');
const jenkinsInstance = storage.localNamespace('jenkins-instance');
const lastVersion = jenkinsInstance.get('currentVersion');

if (lastVersion !== versionString) {
    // Jenkins version has changed deom the last time we ran
    // in this browser. Lets clear all old stored values.
    jenkinsInstance.clear();
}
// get a value from a namespace, with fallback
const storage = require('@jenkins-cd/storage');
const jenkinsInstance = storage.localNamespace('jenkins-instance');
const logCategories = jenkinsInstance.subspace('log-categories');
const sseLogLevel = logCategories.get('org.jenkins.blueocean.sse', {checkDotParent: true});

if (sseLogLevel) {
    // A log level for 'org.jenkins.blueocean.sse', or one of it's "dot parent"
    // ('org.jenkins.blueocean' etc) is set ... do something with with it.
    // Of course this would be wrapped up in a higher level logging API e.g.
    // in @jenkins-cd/diag.
}

iterate(callback, iterateSubspacesopt)

Iterate the key/value pairs in this namespace.

Note, values in subspaces will also be sent to the callback.

Parameters:
Name Type Attributes Description
callback function A callback that's called with the key (1st arg) value (2nd arg) pairs, as well as the namespace (3rd arg) that the value is in (which can be a subspace). this for the callback is set to "this" {StorageNamespace} instance.
iterateSubspaces boolean <optional>
 Also iterate subspace values. Default true.
Source:

remove(name)

Remove a value from the namespace.
Parameters:
Name Type Description
name string The name/key.
Source:

set(name, value)

Set a value in the namespace.
Parameters:
Name Type Description
name string The name/key.
value string | object | boolean | number The value.
Source:

subspace(name) → {StorageNamespace}

Create a sub-namespace of this namespace.

Creating a sub-space "y" from a namespace "x" will result in a new namespace named "x/y" (see example below).

Parameters:
Name Type Description
name string The name of the sub-space.
Source:
Returns:
The storage namespace.
Type
StorageNamespace
Example
const storage = require('@jenkins-cd/storage');
const x = storage.localNamespace('x'); // "x"
const y = x.subspace('y'); // "x/y"