tessl/npm-node-persist

Super-easy (and fast) persistent data structures in Node.js, modeled after HTML5 localStorage

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

node-persist

Name: tessl/npm-node-persist
Author: tessl

node-persist provides super-easy (and fast) persistent data structures in Node.js, modeled after HTML5 localStorage. It stores data as JSON documents in the file system instead of using a database, offering high performance with minimal network overhead. The library supports asynchronous operations with async/await patterns, includes TTL (time-to-live) functionality for automatic data expiration, and provides comprehensive data management capabilities.

Package Information

Package Name: node-persist
Package Type: npm
Language: JavaScript
Installation: npm install node-persist

Core Imports

const storage = require('node-persist');

Basic Usage

const storage = require('node-persist');

// Initialize storage (required before use)
await storage.init();

// Store and retrieve data
await storage.setItem('user', { name: 'Alice', age: 30 });
const user = await storage.getItem('user');
console.log(user); // { name: 'Alice', age: 30 }

// Use with TTL (time-to-live)
await storage.setItem('session', 'abc123', { ttl: 60000 }); // expires in 1 minute

Architecture

node-persist is built around several key components:

LocalStorage Class: Core storage implementation providing all persistence operations
Main Module: Factory and convenience wrapper exposing a default instance and factory methods
Method Mixin: After calling init() or initSync(), all LocalStorage methods are mixed into the main module for direct access
File-based Storage: Uses filesystem with SHA256-hashed filenames for key storage
Write Queue: Batched write operations for improved performance and data consistency
TTL Management: Automatic expiration and cleanup of time-limited data
Async/Await API: Modern promise-based interface throughout

Capabilities

Initialization and Configuration

Essential setup methods for configuring storage behavior, directory paths, serialization options, TTL defaults, and performance settings.

async function init(options?: StorageOptions): Promise<StorageOptions>;
function initSync(options?: StorageOptions): StorageOptions;
function create(options?: StorageOptions): LocalStorage;

// After init, ALL LocalStorage methods are mixed into the main module:
function setOptions(options: StorageOptions): void;

interface StorageOptions {
  dir?: string;
  stringify?: (obj: any) => string;
  parse?: (str: string) => any;
  encoding?: string;
  logging?: boolean | Function;
  ttl?: number | boolean;
  expiredInterval?: number;
  forgiveParseErrors?: boolean;
  writeQueue?: boolean;
  writeQueueIntervalMs?: number;
  writeQueueWriteOnlyLast?: boolean;
  maxFileDescriptors?: number;
}

Initialization and Configuration

Data Storage Operations

Core persistence operations for storing, retrieving, updating, and removing data with optional TTL support.

async function setItem(key: string, value: any, options?: { ttl?: number | Date }): Promise<any>;
async function getItem(key: string): Promise<any>;
async function updateItem(key: string, value: any, options?: { ttl?: number | Date }): Promise<any>;
async function removeItem(key: string): Promise<any>;
async function clear(): Promise<void>;

// Aliases
async function set(key: string, value: any, options?: { ttl?: number | Date }): Promise<any>;
async function get(key: string): Promise<any>;
async function update(key: string, value: any, options?: { ttl?: number | Date }): Promise<any>;
async function del(key: string): Promise<any>;
async function rm(key: string): Promise<any>;

Data Storage Operations

Data Query and Inspection

Methods for querying stored data, retrieving keys and values, and inspecting storage contents with filtering capabilities.

async function keys(filter?: (datum: any) => boolean): Promise<string[]>;
async function values(filter?: (datum: any) => boolean): Promise<any[]>;
async function length(filter?: (datum: any) => boolean): Promise<number>;
function valuesWithKeyMatch(match: string | RegExp): Promise<any[]>;
async function forEach(callback: (datum: { key: string, value: any }) => Promise<void>): Promise<void>;
function data(): Promise<Array<{ key: string, value: any, ttl?: number }>>;

// Low-level data access (also mixed into main module after init):
function getDatum(key: string): Promise<any>;
function getRawDatum(key: string): Promise<string>;
async function getDatumValue(key: string): Promise<any>;
function getDatumPath(key: string): string; // synchronous

// Utility methods (also mixed into main module after init):
async function removeExpiredItems(): Promise<void>;
function startExpiredKeysInterval(): void;
function stopExpiredKeysInterval(): void;
function startWriteQueueInterval(): void;
function stopWriteQueueInterval(): void;

Data Query and Inspection

Low-level Operations and Utilities

Advanced methods for direct data access, manual expiration management, and internal storage operations.

function getDatum(key: string): Promise<any>;
function getRawDatum(key: string): Promise<string>;
async function getDatumValue(key: string): Promise<any>;
function getDatumPath(key: string): string;

async function removeExpiredItems(): Promise<void>;
function startExpiredKeysInterval(): void;
function stopExpiredKeysInterval(): void;
function startWriteQueueInterval(): void;
function stopWriteQueueInterval(): void;
function setOptions(options: StorageOptions): void;

Low-level Operations and Utilities

Types

class LocalStorage {
  constructor(options?: StorageOptions);
  async init(options?: StorageOptions): Promise<StorageOptions>;
  initSync(options?: StorageOptions): StorageOptions;
  setOptions(options: StorageOptions): void;
  
  // All storage operations are available as methods
  async setItem(key: string, value: any, options?: { ttl?: number | Date }): Promise<any>;
  async getItem(key: string): Promise<any>;
  async updateItem(key: string, value: any, options?: { ttl?: number | Date }): Promise<any>;
  async removeItem(key: string): Promise<any>;
  async clear(): Promise<void>;
  
  // Query methods
  async keys(filter?: Function): Promise<string[]>;
  async values(filter?: Function): Promise<any[]>;
  async length(filter?: Function): Promise<number>;
  valuesWithKeyMatch(match: string | RegExp): Promise<any[]>;
  async forEach(callback: Function): Promise<void>;
  
  // Low-level access
  data(): Promise<any[]>;
  getDatum(key: string): Promise<any>;
  getRawDatum(key: string): Promise<string>;
  async getDatumValue(key: string): Promise<any>;
  getDatumPath(key: string): string; // synchronous
  
  // Utility methods
  async removeExpiredItems(): Promise<void>;
  startExpiredKeysInterval(): void;
  stopExpiredKeysInterval(): void;
  startWriteQueueInterval(): void;
  stopWriteQueueInterval(): void;
}

interface StorageOptions {
  dir?: string;
  stringify?: (obj: any) => string;
  parse?: (str: string) => any;
  encoding?: string;
  logging?: boolean | Function;
  ttl?: number | boolean;
  expiredInterval?: number;
  forgiveParseErrors?: boolean;
  writeQueue?: boolean;
  writeQueueIntervalMs?: number;
  writeQueueWriteOnlyLast?: boolean;
  maxFileDescriptors?: number;
}

Install with Tessl CLI

npx tessl i tessl/npm-node-persist

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:npm/node-persist@4.0.x
Publish Source: CLI
Badge