@ad-execute-manager/storage

A flexible storage utility for JavaScript applications with expiration support, user-specific storage, and customizable prefixes.

Installation

npm install @ad-execute-manager/storage

Features

• Expiration Support: Set expiration times for stored items, including 'today' option for day-bound data
• User-specific Storage: Store data per user with automatic userId prefixing
• Customizable Prefix: Add a prefix to identify the source of storage items
• Synchronous Operations: Uses synchronous storage methods for simple integration
• Error Handling: Built-in error handling for storage operations
• TypeScript Support: Includes TypeScript type definitions
• Logger Integration: Uses @ad-execute-manager/logger for logging storage operations

Usage

Basic Usage

import { Storage } from '@ad-execute-manager/storage';

// Create a storage instance
const storage = new Storage({
  prefix: 'myapp_',
  expire: null // Default expiration (null = never expire)
});

// Set data with different expiration options

// Set data that expires today
storage.setItem('dailyTask', { completed: false }, 'today');

// Set data with custom expiration (2 hours)
storage.setItem('tempData', { value: 123 }, 2 * 60 * 60 * 1000);

// Set permanent data
storage.setItem('userSettings', { theme: 'dark' });

// Get data
const dailyTask = storage.getItem('dailyTask');
const tempData = storage.getItem('tempData');
const userSettings = storage.getItem('userSettings');

console.log('Daily Task:', dailyTask);
console.log('Temp Data:', tempData);
console.log('User Settings:', userSettings);

User-specific Storage

import { Storage } from '@ad-execute-manager/storage';

// Create storage instance with userId
const userStorage = new Storage({
  prefix: 'app_',
  userId: 'user123'
});

// Set user-specific data
userStorage.setUserItem('preferences', { theme: 'light', language: 'en' });
userStorage.setUserItem('lastLogin', new Date().toISOString());

// Get user-specific data
const preferences = userStorage.getUserItem('preferences');
const lastLogin = userStorage.getUserItem('lastLogin');

console.log('User Preferences:', preferences);
console.log('Last Login:', lastLogin);

Advanced Usage

import { Storage } from '@ad-execute-manager/storage';

// Create storage instance
const storage = new Storage({
  prefix: 'app_',
  expire: 24 * 60 * 60 * 1000 // Default to 24 hours
});

// Set data
storage.setItem('session', { token: 'abc123' });

// Get all keys
const allKeys = storage.keys();
console.log('All stored keys:', allKeys);

// Remove an item
storage.removeItem('tempData');

// Clear all storage
// storage.clear(); // Uncomment to clear all storage

// Using the static new method
const anotherStorage = Storage.new({
  prefix: 'another_'
});

anotherStorage.setItem('test', { value: 'hello' });

API

Constructor

new Storage(options)

• options (Object): Configuration options
  • prefix (String): Storage key prefix, defaults to 'storage_'
  • expire (Number|null): Default expiration time in milliseconds, null for never expire, defaults to null
  • userId (String|Number): User ID for user-specific storage

Methods

Basic Storage

• setItem(key, value, expire): Set a storage item

  • key (String): Storage key
  • value (Any): Value to store (will be JSON stringified)
  • expire (Number|'today'|null): Expiration time in milliseconds, 'today' for day-bound, or null for no expiration

• getItem(key): Get a storage item

  • key (String): Storage key
  • returns (Any|null): Stored value or null if expired/non-existent

• removeItem(key): Remove a storage item

  • key (String): Storage key

• clear(): Clear all storage items

• keys(): Get all non-expired storage keys

  • returns (Array): Array of storage keys without prefix

User-specific Storage

• setUserItem(key, value, expire): Set a user-specific storage item

  • key (String): Storage key
  • value (Any): Value to store
  • expire (Number|'today'|null): Expiration time

• getUserItem(key): Get a user-specific storage item

  • key (String): Storage key
  • returns (Any|null): Stored value or null if expired/non-existent

Static Methods

• Storage.new(options): Create a new Storage instance
  • options (Object): Same as constructor options
  • returns (Storage): New Storage instance

Examples

Example 1: Daily Task Management

import { Storage } from '@ad-execute-manager/storage';

// Create storage for daily tasks
const taskStorage = new Storage({
  prefix: 'tasks_',
  expire: null
});

// Set daily task (expires today)
taskStorage.setItem('dailyTask', {
  id: 1,
  title: 'Complete tutorial',
  completed: false
}, 'today');

// Get daily task
const dailyTask = taskStorage.getItem('dailyTask');

if (dailyTask) {
  console.log('Daily task:', dailyTask);
  
  // Mark task as completed
  dailyTask.completed = true;
  taskStorage.setItem('dailyTask', dailyTask, 'today');
  
  console.log('Task marked as completed');
} else {
  console.log('No active daily task');
}

Example 2: User Preferences

import { Storage } from '@ad-execute-manager/storage';

// Create user-specific storage
const userStorage = new Storage({
  prefix: 'user_',
  userId: 'user123',
  expire: null
});

// Set user preferences
userStorage.setUserItem('preferences', {
  theme: 'dark',
  language: 'en',
  notifications: true
});

// Get user preferences
const preferences = userStorage.getUserItem('preferences');
console.log('User preferences:', preferences);

// Update preferences
if (preferences) {
  preferences.theme = 'light';
  userStorage.setUserItem('preferences', preferences);
  console.log('Preferences updated');
}

Example 3: Session Management

import { Storage } from '@ad-execute-manager/storage';

// Create session storage with 1-hour expiration
const sessionStorage = new Storage({
  prefix: 'session_',
  expire: 60 * 60 * 1000 // 1 hour
});

// Set session data
sessionStorage.setItem('session', {
  token: 'abc123xyz789',
  userId: 'user123',
  timestamp: Date.now()
});

// Check if session is valid
function checkSession() {
  const session = sessionStorage.getItem('session');
  
  if (session) {
    console.log('Session is valid:', session);
    return true;
  } else {
    console.log('Session expired or not found');
    return false;
  }
}

// Refresh session
sessionStorage.setItem('session', {
  token: 'newToken123',
  userId: 'user123',
  timestamp: Date.now()
});

console.log('Session refreshed');
checkSession();

Dependencies

• @ad-execute-manager/logger: For logging storage operations

License

MIT