or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mddriver-development.mdindex.mdstorage-inspection.mdstorage-operations.md
tile.json

tessl/npm-localforage

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/localforage@1.10.x

To install, run

npx @tessl/cli install tessl/npm-localforage@1.10.0

index.mddocs/

localForage

localForage is a fast and simple storage library for JavaScript that improves the offline experience of web applications by using asynchronous storage (IndexedDB or WebSQL) with a simple, localStorage-like API. It automatically falls back to localStorage in browsers with no IndexedDB or WebSQL support, offering both callback and Promise-based APIs with async/await support, and can store any JavaScript type including Blobs, TypedArrays, and other objects that can be serialized to JSON.

Package Information

  • Package Name: localforage
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install localforage

Core Imports

import localforage from 'localforage';

For CommonJS:

const localforage = require('localforage');

For environments without module support:

<script src="localforage.js"></script>
<script>console.log('localforage is: ', localforage);</script>

Basic Usage

import localforage from 'localforage';

// Store data
await localforage.setItem('users', [
  { name: 'Alice', age: 25 },
  { name: 'Bob', age: 30 }
]);

// Retrieve data
const users = await localforage.getItem('users');
console.log(users); // [{ name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }]

// Remove data
await localforage.removeItem('users');

// Clear all data
await localforage.clear();

Architecture

localForage is built around several key components:

  • Driver System: Automatic selection and fallback between IndexedDB, WebSQL, and localStorage
  • Storage Interface: Unified API that works consistently across all storage backends
  • Serialization: Automatic handling of complex data types including Blobs and TypedArrays
  • Promise-based API: Modern async/await support with optional callback compatibility
  • Multi-instance Support: Ability to create multiple storage instances with different configurations

Capabilities

Core Storage Operations

Primary data storage methods that work consistently across all supported storage backends. These methods form the core localStorage-like API with full async support.

function getItem<T>(key: string, callback?: (err: any, value: T | null) => void): Promise<T | null>;

function setItem<T>(key: string, value: T, callback?: (err: any, value: T) => void): Promise<T>;

function removeItem(key: string, callback?: (err: any) => void): Promise<void>;

function clear(callback?: (err: any) => void): Promise<void>;

Storage Operations

Storage Inspection

Methods for inspecting and iterating over stored data, including key enumeration and batch processing capabilities.

function length(callback?: (err: any, numberOfKeys: number) => void): Promise<number>;

function key(keyIndex: number, callback?: (err: any, key: string) => void): Promise<string>;

function keys(callback?: (err: any, keys: string[]) => void): Promise<string[]>;

function iterate<T, U>(
  iteratee: (value: T, key: string, iterationNumber: number) => U,
  callback?: (err: any, result: U) => void
): Promise<U>;

Storage Inspection

Configuration and Driver Management

Configuration system for customizing storage behavior, driver selection, and creating multiple storage instances.

function config(options: LocalForageOptions): boolean;
function config(options: string): any;
function config(): LocalForageOptions;

function setDriver(
  driver: string | string[],
  callback?: () => void,
  errorCallback?: (error: any) => void
): Promise<void>;

function createInstance(options: LocalForageOptions): LocalForage;

function dropInstance(dbInstanceOptions?: LocalForageDbInstanceOptions, callback?: (err: any) => void): Promise<void>;

Configuration

Driver Development

Advanced functionality for defining custom storage drivers and inspecting driver capabilities.

function defineDriver(
  driver: LocalForageDriver,
  callback?: () => void,
  errorCallback?: (error: any) => void
): Promise<void>;

function driver(): string;

function getDriver(driver: string): Promise<LocalForageDriver>;

function getSerializer(callback?: (serializer: LocalForageSerializer) => void): Promise<LocalForageSerializer>;

function ready(callback?: (error: any) => void): Promise<void>;

function supports(driverName: string): boolean;

Driver Development

Driver Constants

// Available as properties on the localforage instance
const INDEXEDDB: string; // 'asyncStorage'
const WEBSQL: string;    // 'webSQLStorage'  
const LOCALSTORAGE: string; // 'localStorageWrapper'

Types

interface LocalForageOptions {
  driver?: string | string[];
  name?: string;
  storeName?: string;
  size?: number;
  version?: number;
  description?: string;
}

interface LocalForageDbInstanceOptions {
  name?: string;
  storeName?: string;
}

interface LocalForage {
  // Core storage methods
  getItem<T>(key: string, callback?: (err: any, value: T | null) => void): Promise<T | null>;
  setItem<T>(key: string, value: T, callback?: (err: any, value: T) => void): Promise<T>;
  removeItem(key: string, callback?: (err: any) => void): Promise<void>;
  clear(callback?: (err: any) => void): Promise<void>;
  
  // Storage inspection methods
  length(callback?: (err: any, numberOfKeys: number) => void): Promise<number>;
  key(keyIndex: number, callback?: (err: any, key: string) => void): Promise<string>;
  keys(callback?: (err: any, keys: string[]) => void): Promise<string[]>;
  iterate<T, U>(iteratee: (value: T, key: string, iterationNumber: number) => U, callback?: (err: any, result: U) => void): Promise<U>;
  
  // Configuration and management
  config(options: LocalForageOptions): boolean;
  config(options: string): any;
  config(): LocalForageOptions;
  createInstance(options: LocalForageOptions): LocalForage;
  setDriver(driver: string | string[], callback?: () => void, errorCallback?: (error: any) => void): Promise<void>;
  
  // Driver inspection
  driver(): string;
  getDriver(driver: string): Promise<LocalForageDriver>;
  supports(driverName: string): boolean;
  ready(callback?: (error: any) => void): Promise<void>;
  
  // Advanced features
  defineDriver(driver: LocalForageDriver, callback?: () => void, errorCallback?: (error: any) => void): Promise<void>;
  getSerializer(callback?: (serializer: LocalForageSerializer) => void): Promise<LocalForageSerializer>;
  dropInstance(dbInstanceOptions?: LocalForageDbInstanceOptions, callback?: (err: any) => void): Promise<void>;
  
  // Driver constants
  INDEXEDDB: string;
  WEBSQL: string;
  LOCALSTORAGE: string;
}

interface LocalForageDriver {
  _driver: string;
  _initStorage(options: LocalForageOptions): void;
  _support?: boolean | (() => Promise<boolean>);
  
  // Core storage methods
  getItem<T>(key: string, callback?: (err: any, value: T | null) => void): Promise<T | null>;
  setItem<T>(key: string, value: T, callback?: (err: any, value: T) => void): Promise<T>;
  removeItem(key: string, callback?: (err: any) => void): Promise<void>;
  clear(callback?: (err: any) => void): Promise<void>;
  length(callback?: (err: any, numberOfKeys: number) => void): Promise<number>;
  key(keyIndex: number, callback?: (err: any, key: string) => void): Promise<string>;
  keys(callback?: (err: any, keys: string[]) => void): Promise<string[]>;
  iterate<T, U>(iteratee: (value: T, key: string, iterationNumber: number) => U, callback?: (err: any, result: U) => void): Promise<U>;
  
  // Optional methods
  dropInstance?(dbInstanceOptions?: LocalForageDbInstanceOptions, callback?: (err: any) => void): Promise<void>;
}

interface LocalForageSerializer {
  serialize<T>(value: T | ArrayBuffer | Blob, callback: (value: string, error: any) => void): void;
  deserialize<T>(value: string): T | ArrayBuffer | Blob;  
  stringToBuffer(serializedString: string): ArrayBuffer;
  bufferToString(buffer: ArrayBuffer): string;
}