tessl/npm-localforage

Fast and simple storage library for JavaScript with localStorage-like API that uses asynchronous storage (IndexedDB or WebSQL).

—

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

Storage Operations

Name: tessl/npm-localforage
Author: tessl

Core data storage methods that work consistently across all supported storage backends (IndexedDB, WebSQL, localStorage). These methods form the primary localStorage-like API with full async/await support and optional callback compatibility.

Capabilities

Get Item

Retrieves an item from storage by key. Returns null if the key doesn't exist.

/**
 * Retrieves an item from storage
 * @param key - The key of the item to retrieve
 * @param callback - Optional callback function
 * @returns Promise resolving to the stored value or null
 */
function getItem<T>(key: string, callback?: (err: any, value: T | null) => void): Promise<T | null>;

Usage Examples:

import localforage from 'localforage';

// Using async/await
const user = await localforage.getItem('user');
console.log(user); // { name: 'Alice', age: 25 } or null

// Using callbacks
localforage.getItem('user', (err, value) => {
  if (err) {
    console.error('Error:', err);
  } else {
    console.log('User:', value);
  }
});

// Type-safe retrieval with TypeScript
interface User {
  name: string;
  age: number;
}

const user = await localforage.getItem<User>('user');
// user is typed as User | null

Set Item

Stores an item in storage. The value can be any JavaScript type that can be serialized, including objects, arrays, Blobs, TypedArrays, etc.

/**
 * Stores an item in storage
 * @param key - The key to store the item under
 * @param value - The value to store (any serializable type)
 * @param callback - Optional callback function
 * @returns Promise resolving to the stored value
 */
function setItem<T>(key: string, value: T, callback?: (err: any, value: T) => void): Promise<T>;

Usage Examples:

import localforage from 'localforage';

// Store simple values
await localforage.setItem('username', 'alice');
await localforage.setItem('score', 1250);
await localforage.setItem('isActive', true);

// Store complex objects
const userData = {
  name: 'Alice Johnson',
  preferences: {
    theme: 'dark',
    notifications: true
  },
  tags: ['developer', 'javascript']
};
await localforage.setItem('user', userData);

// Store arrays
const items = [1, 2, 3, 4, 5];
await localforage.setItem('numbers', items);

// Store Blobs (binary data)
const blob = new Blob(['Hello, world!'], { type: 'text/plain' });
await localforage.setItem('textFile', blob);

// Using callbacks
localforage.setItem('key', 'value', (err, value) => {
  if (err) {
    console.error('Storage error:', err);
  } else {
    console.log('Stored value:', value);
  }
});

Remove Item

Removes an item from storage by key. No error is thrown if the key doesn't exist.

/**
 * Removes an item from storage
 * @param key - The key of the item to remove
 * @param callback - Optional callback function
 * @returns Promise resolving when the item is removed
 */
function removeItem(key: string, callback?: (err: any) => void): Promise<void>;

Usage Examples:

import localforage from 'localforage';

// Remove a single item
await localforage.removeItem('temporaryData');

// Remove user session data
await localforage.removeItem('authToken');

// Using callbacks
localforage.removeItem('oldData', (err) => {
  if (err) {
    console.error('Error removing item:', err);
  } else {
    console.log('Item removed successfully');
  }
});

// Safe removal (no error if key doesn't exist)
await localforage.removeItem('nonExistentKey'); // No error thrown

Clear Storage

Removes all items from the current storage instance. This only affects the current database/store, not other instances.

/**
 * Clears all items from storage
 * @param callback - Optional callback function
 * @returns Promise resolving when all items are cleared
 */
function clear(callback?: (err: any) => void): Promise<void>;

Usage Examples:

import localforage from 'localforage';

// Clear all data
await localforage.clear();
console.log('All data cleared');

// Clear with confirmation
const confirmClear = confirm('Are you sure you want to clear all data?');
if (confirmClear) {
  await localforage.clear();
}

// Using callbacks
localforage.clear((err) => {
  if (err) {
    console.error('Error clearing storage:', err);
  } else {
    console.log('Storage cleared successfully');
  }
});

// Clear specific instance only
const userStore = localforage.createInstance({ name: 'userdata' });
await userStore.clear(); // Only clears userdata store

Error Handling

All storage operations can potentially fail due to quota limits, permissions, or other storage-related issues:

try {
  await localforage.setItem('largeData', hugeBinaryData);
} catch (error) {
  if (error.name === 'QuotaExceededError') {
    console.error('Storage quota exceeded');
  } else {
    console.error('Storage error:', error);
  }
}

// With callbacks, errors are passed as the first parameter
localforage.getItem('key', (err, value) => {
  if (err) {
    console.error('Failed to retrieve item:', err);
    return;
  }
  // Process value...
});

Supported Data Types

localForage can store any data type that can be handled by the structured clone algorithm:

Primitives: string, number, boolean, null, undefined
Objects: Plain objects, arrays, dates
Binary Data: ArrayBuffer, Blob, File, TypedArrays (Uint8Array, etc.)
Complex Types: Nested objects, objects with circular references (in some cases)

// All of these work seamlessly
await localforage.setItem('string', 'Hello World');
await localforage.setItem('number', 42);
await localforage.setItem('boolean', true);
await localforage.setItem('date', new Date());
await localforage.setItem('array', [1, 2, 3]);
await localforage.setItem('object', { key: 'value' });
await localforage.setItem('blob', new Blob(['data']));
await localforage.setItem('buffer', new ArrayBuffer(8));