localstorage-nodejs Documentation

A simple and complete implementation of the Web API, localStorage.

Overview

The localstorage-nodejs module provides a simple interface for local file-based storage in Node.js, mimicking the behavior of the web's localStorage. It supports both synchronous and asynchronous operations (to which the standard web api doesn't) and uses the file system to store key-value pairs.

Installation

You can install this module via npm or yarn:

npm install localstorage-nodejs
# or
yarn add localstorage-nodejs

Usage

To use this module, require it in your Node.js project and create an instance of the storage. You can choose between synchronous and asynchronous modes.

Creating an Instance

const storage = require('localstorage-nodejs');
// or for ESM
import storage from 'localstorage-nodejs'

// Synchronous
const syncStorage = storage('path/to/storage', false);

// Asynchronous
const asyncStorage = storage('path/to/storage', true);

API

Constructor

new Storage(store_prefix, isAsync)

• store_prefix (string): The directory path where the storage files will be kept.
• isAsync (boolean): Determines whether to use asynchronous file operations.

Methods

• clear()

  • Description: Clears all files and directories within the storage directory.
  • Async Mode: Returns a promise.
  • Sync Mode: Executes synchronously.

• removeItem(key)

  • Description: Removes the file associated with the specified key.
  • Async Mode: Returns a promise.
  • Sync Mode: Executes synchronously.

• setItem(key, value)

  • Description: Stores the value as a file with the specified key.
  • Parameters:
    • key (string): The key under which the value will be stored.
    • value (string): The value to store.
  • Async Mode: Returns a promise.
  • Sync Mode: Executes synchronously.

• getItem(key)

  • Description: Retrieves the value associated with the specified key.
  • Parameters:
    • key (string): The key for which the value is to be retrieved.
  • Returns: A promise that resolves to the value or null if not found (in async mode) or the value or null (in sync mode).

• length

  • Description: Returns the number of files (items) stored.
  • Async Mode: Returns a promise.
  • Sync Mode: Returns the number directly.

Proxy API

The module also exposes a Proxy object which allows for dynamic interaction with storage:

• Get

  • Retrieves the value associated with a key. If the key does not exist, it will return null.

• Set

  • Sets the value associated with a key. If the key does not exist, it will create a new file.

• Delete

  • Removes the value associated with a key. If the key does not exist, it will do nothing.

Example

const storage = require('localstorage-nodejs')('my_storage', true);

(async () => {
  await storage.setItem('testKey', 'testValue');
  const value = await storage.getItem('testKey');
  console.log(value); // Outputs: testValue

  const length = await storage.length;
  console.log(length); // Outputs: 1

  await storage.removeItem('testKey');
})();

Notes

• Ensure that the directory specified in store_prefix is writable by the Node.js process.
• The synchronous mode is suitable for simpler use cases where blocking operations are acceptable.