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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Low-level Operations and Utilities

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

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

Capabilities

Raw Data Access

Direct access to the internal datum objects and file paths.

/**
 * Gets the complete datum object for a key (includes key, value, and TTL)
 * @param key - The key to get the datum for
 * @returns Promise resolving to datum object or empty object if not found
 */
function getDatum(key: string): Promise<any>;

/**
 * Gets the raw JSON string content of a storage file
 * @param key - The key to get raw data for
 * @returns Promise resolving to raw JSON string
 */
function getRawDatum(key: string): Promise<string>;

/**
 * Gets just the value from a datum object
 * @param key - The key to get the value for
 * @returns Promise resolving to the stored value or undefined
 */
async function getDatumValue(key: string): Promise<any>;

/**
 * Gets the filesystem path where a key's data is stored (synchronous)
 * @param key - The key to get the path for
 * @returns Absolute filesystem path to the storage file
 */
function getDatumPath(key: string): string;

Usage Examples:

const storage = require('node-persist');
await storage.init();

await storage.setItem('user', { name: 'Alice' }, { ttl: 60000 });

// Get complete datum with metadata
const datum = await storage.getDatum('user');
console.log(datum);
// { key: 'user', value: { name: 'Alice' }, ttl: 1640995200000 }

// Get raw JSON string
const rawData = await storage.getRawDatum('user');
console.log(rawData);
// '{"key":"user","value":{"name":"Alice"},"ttl":1640995200000}'

// Get just the value
const value = await storage.getDatumValue('user');
console.log(value); // { name: 'Alice' }

// Get file path
const filePath = storage.getDatumPath('user');
console.log(filePath);
// '/path/to/storage/abcd1234...' (SHA256 hash of key)

Manual Expiration Management

Control over the automatic TTL cleanup process.

/**
 * Manually removes all expired items from storage
 * @returns Promise resolving when cleanup is complete
 */
async function removeExpiredItems(): Promise<void>;

/**
 * Starts the automatic expired item cleanup interval
 * Uses the expiredInterval option setting
 */
function startExpiredKeysInterval(): void;

/**
 * Stops the automatic expired item cleanup interval
 */
function stopExpiredKeysInterval(): void;

Usage Examples:

// Manual cleanup
await storage.removeExpiredItems();
console.log('All expired items removed');

// Control automatic cleanup
storage.stopExpiredKeysInterval(); // Stop automatic cleanup
// ... do some work ...
storage.startExpiredKeysInterval(); // Resume automatic cleanup

// Custom cleanup schedule
storage.stopExpiredKeysInterval();
setInterval(async () => {
  console.log('Running custom cleanup...');
  await storage.removeExpiredItems();
}, 30000); // Every 30 seconds

Write Queue Management

Control over the write queue system for performance optimization.

/**
 * Starts the write queue processing interval
 * Processes pending writes at the configured interval
 */
function startWriteQueueInterval(): void;

/**
 * Stops the write queue processing interval
 * Note: This may leave pending writes unprocessed
 */
function stopWriteQueueInterval(): void;

Usage Examples:

// Temporarily disable write queue processing for bulk operations
storage.stopWriteQueueInterval();

// Perform many write operations
for (let i = 0; i < 1000; i++) {
  await storage.setItem(`item${i}`, { data: i });
}

// Resume write queue processing
storage.startWriteQueueInterval();

Configuration Updates

Dynamic configuration changes after initialization.

/**
 * Updates storage configuration options
 * @param options - New configuration options to apply
 */
function setOptions(options: StorageOptions): void;

Usage Examples:

// Change logging level
storage.setOptions({ logging: true });

// Update TTL default
storage.setOptions({ ttl: 3600000 }); // 1 hour

// Change write queue behavior
storage.setOptions({ 
  writeQueueWriteOnlyLast: false,
  writeQueueIntervalMs: 500 
});

// Update file descriptor limit
storage.setOptions({ maxFileDescriptors: 256 });

Advanced Usage Patterns

Storage File Inspection

// Inspect storage files directly
const allData = await storage.data();

for (const datum of allData) {
  const filePath = storage.getDatumPath(datum.key);
  console.log(`Key: ${datum.key}`);
  console.log(`File: ${filePath}`);
  
  if (datum.ttl) {
    const expiresAt = new Date(datum.ttl);
    const isExpired = Date.now() > datum.ttl;
    console.log(`Expires: ${expiresAt.toISOString()} (${isExpired ? 'EXPIRED' : 'valid'})`);
  }
}

Custom Cleanup Logic

// Implement custom expiration logic
async function customCleanup() {
  const allData = await storage.data();
  
  for (const datum of allData) {
    // Custom logic: remove items older than 7 days regardless of TTL
    const sevenDaysAgo = Date.now() - (7 * 24 * 60 * 60 * 1000);
    const fileStats = fs.statSync(storage.getDatumPath(datum.key));
    
    if (fileStats.mtime.getTime() < sevenDaysAgo) {
      await storage.removeItem(datum.key);
      console.log(`Removed old item: ${datum.key}`);
    }
  }
}

// Run custom cleanup
await customCleanup();

Performance Monitoring

// Monitor write queue size
const originalSetItem = storage.setItem;
storage.setItem = async function(key, value, options) {
  const startTime = Date.now();
  const result = await originalSetItem.call(this, key, value, options);
  const duration = Date.now() - startTime;
  
  if (duration > 100) {
    console.warn(`Slow write detected: ${key} took ${duration}ms`);
  }
  
  return result;
};