node-global-storage

Node Global Storage 💾

Global data storage manager for Node.js. Make data accessible across your JavaScript and TypeScript files without worrying about multiple imports.

What's new in version 3.x? 🚀

This package was rewritten again from scratch. The exposed API is almost the same as 2.x but further improved for clarity and performance.

• Extended TypeScript types 💙
• ESModules support (import syntax)
• Zero dependencies
• Full JSDoc documentation for all methods with examples for inline editor docs!
• More exhaustive testing with 100% coverage!
• Refactor of some methods from 2.0

Install

# NPM
npm install --save node-global-storage

# Yarn
yarn add node-global-storage

# PNPM
pnpm add node-global-storage

Import

This package can be imported both as CommonJS or ESModule:

// CommonJS
const { getValue, setValue } = require("node-global-storage");

// ESModule with embedded TypeScript types
import { getValue, setValue } from "node-global-storage";

API Methods

Method	Return type	Description
setValue<T>(key: string, value: T, options?: SetOptions)	T	Sets the value for a given key in the global storage
getValue<T>(key: string)	T	Returns the value for the given key name
getAllValues()	Record<string, unknown>	Returns all stored values
getMetadata<T>(key: string)	StorageItem<T>	Returns the full StorageItem object of the provided key name
getAllMetadata()	Record<string, StorageItem<T>>	Returns all stored metadata
isSet(key: string)	boolean	Checks if a key has been set
isProtected(key: string)	boolean	Checks if a key is protected
unsetValue(key: string, options?: UnsetOptions)	void	Removes the value for a given key in the global storage
flush(options?: FlushOptions)	void	Removes all stored values
setDefaultOption(key: keyof DefaultOptions, value: DefaultOptions[T])	void	Sets the default option for all transactions
getDefaultOptions()	DefaultOptions	Returns the default options
resetDefaultOptions()	void	Resets the default options to the initial default values

Interfaces

StorageItem

Internal data structure for stored data. It is returned by getMetadata(key: string) and getAllMetadata().

Key	Type	Description
value	T	Stored value
protected	boolean	Protect the value from being deleted if set again
createdAt	Date	Date of creation of the key/value pair
updatedAt	Date	Date of the last update of the key/value pair
onUpdate?	<T>(key: string, newValue: T, oldValue?: T) => void	Callback to execute when the value is updated
onDelete?	<T>(key: string, value: T) => void	Callback to execute when the value is deleted

DefaultOptions

Default options for all transactions. They can be modified by setDefaultOption(key: keyofDefaultOptions, value: DefaultOptions[T]).

Key	Type	Description
silent	boolean	Do not execute the onUpdate or onDelete callback of previous data if set
force	boolean	Force the update of the value even if it is protected
protected	boolean	Protect the value from being deleted if set again
onUpdate?: StorageItem["onUpdate"]	<T>(key: string, newValue: T, oldValue?: T) => void	Callback to execute when the value is updated
onDelete?: StorageItem["onDelete"]	<T>(key: string, value: T) => void	Callback to execute when the value is deleted

SetOptions

Available options when calling setValue<T>(key: string, value: T, options?: SetOptions).

Key	Type	Description
value	T	Stored value
protected	boolean	Protect the value from being deleted if set again
silent	boolean	Do not execute the onUpdate or onDelete callback of previous data if set
force	boolean	Force the update of the value even if it is protected
onUpdate?	<T>(key: string, newValue: T, oldValue?: T) => void	Callback to execute when the value is updated
onDelete?	<T>(key: string, value: T) => void	Callback to execute when the value is deleted

UnsetOptions

Available options when calling unsetValue(key: string, options?: UnsetOptions).

Key	Type	Description
silent	boolean	Do not execute the onUpdate or onDelete callback of previous data if set

FlushOptions

Available options when calling flush().

Key	Type	Description
silent	boolean	Do not execute the onUpdate or onDelete callback of previous data if set

Usage Examples

⚠️ getMetadata and getAllMetadata both return the core package object reference. Don't edit it directly if you don't want to break anything!

Get and set values

import { getValue, setValue, getMetadata } from "node-global-storage";

setValue("hello", "Greetings!", { protected: true });
let hello = getValue("hello"); // => 'Greetings!'

const updateCallback = (key, value) =>
  console.log(`${key} was updated to ${value}`);

// Protected values cannot be overwritten...
setValue("hello", "What's up!", { onUpdate: updateCallback });
hello = getValue("hello"); // => "Greetings!"

// ...unless `options.force` is set to `true`
setValue("hello", "This is a forced value", { force: true });
// => "This is a forced value"

hello = getValue("hello"); // => "This is a forced value"

const metadata = getMetadata("hello"); // { value: "This is a forced value", createdAt: Date, updatedAt: Date, protected: false, onUpdate: updateCallback, onDelete: undefined }

List values and metadata

import { getAllValues, getMetadata, setValue } from 'node-global-storage';

setValue('one', 1, { protected: true });
setValue('two', false, { forced: true });
setValue('three', '33333', { onUpdate: someCallbackFunction });

const allValues = getAllValues();
// => {
//      one: 1,
//      two: false,
//      three: '33333'
//    }

var allMetadata = getAllMetadata();
// => {
//      one: {value: 1, protected: true, forced: false, onUpdate: null, onDelete: null, createdAt: Date, updatedAt: Date },
//      two: {value: false, protected: false, forced: true, onUpdate: null, onDelete: null, createdAt: Date, updatedAt: Date },
//      three: {value: '33333', protected: false, forced: false, onUpdate: doSomeCrazyThing, onDelete: null, createdAt: Date, updatedAt: Date }
//    }

isSet / isProtected

import { isSet, isProtected } from "node-global-storage";

set("key1", "This is a protected key", { protected: true });

const isKey1Set = isSet("key1"); // => true
const isKey2Set = isSet("key2"); // => false
const isKey1Protected = isProtected("key1"); // => true
const isKey2Protected = isProtected("key2"); // => false

Unset / flush

import { setValue, getValue, unsetValue, flush } from "node-global-storage";

const deleteCallback = (key, value) => console.log(`Key ${key} was deleted`);

setValue("key1", "This is a value");

let value = getValue("key1"); // => "This is a value"

unsetValue("key1");

value = getValue("key1"); // => undefined

Default options

getDefaultOptions(); // { protected: false, force: false, onUpdate: undefined, onDelete: undefined, silent: false }

setDefaultOption("protected", true);

getDefaultOptions(); // { protected: true, force: false, onUpdate: undefined, onDelete: undefined, silent: false }

const key1 = "myKey1";
const value1 = "myValue1";

setValue(key1, value1);

const isKey1Protected = isProtected(key1); // true

resetDefaultOptions();

const key2 = "myKey2";
const value2 = "myValue2";

setValue(key2, value2);

const isKey2Protected = isProtected(key2); // false

const defaultOptions =

resetDefaultOptions();

getDefaultOptions(); // { protected: false, force: false, onUpdate: undefined, onDelete: undefined, silent: false }