types-storage is a lightweight TypeScript library that ensures the desired type is correctly returned every time an item is retrieved from localStorage or sessionStorage, using Zod.
- Type Safety: Built for TypeScript with generic types and Zod schemas.
- Fallback values: To make sure a value of the same type is always retrieved.
- Safe Storage Access Prevents JSON parsing errors.
- Namespace: Avoid key conflicts.
- Expiration Support: Store values with a time-to-live or TTL.
- Simple API: Friendly user experience.
You can install types-storage via npm:
npm install types-storage zodCreate a TypeSafeStorage instance. You can use both localStorage and sessionStorage:
import { TypeSafeStorage } from 'types-storage';
import * as z from 'zod';
const storage = new TypeSafeStorage(localStorage);Use a namespace to prefix keys and avoid conflicts:
const storage = new TypeSafeStorage(sessionStorage, 'my-app');Save data to storage using the set method:
storage.set('theme', 'dark');
// Direct method import.
import { set as setToLocalStorage } from 'types-storage';
setToLocalStorage('theme', 'dark');Retrieve data with a fallback value and a Zod schema for type safety:
const themeSchema = z.enum(['light', 'dark']);
const theme = storage.get('theme', 'light', themeSchema);
// Returns 'light' if invalid or not foundStore and validate arrays or complex objects:
storage.set('filters', ['desc', 'price']);
const stringArraySchema = z.array(z.string());
const filters = storage.get('filters', [], stringArraySchema);
// Returns ['desc', 'price'] or [] if invalidSet values with expiration using TTL (in milliseconds):
storage.setWithExpiration('token', 'xxxx', 3600000); // Expires in 1 hour
const tokenSchema = z.string();
const token = storage.get('token', '', tokenSchema);
// Returns '' if expired or invalid-
get<T>(key: string, fallback: T, schema: ZodSchema<T>): T | null: Retrieves a value with type safety using a Zod schema. -
getStorage: Storage: Retrieves the current storage. -
set<T>(key: string, value: T): void: Stores a value in localStorage. -
setWithExpiration<T>(key: string, value: T, ttl: number): void: Stores a value that expires after ttl milliseconds. -
exists(key: string): boolean: Checks if a key exists. -
remove(key: string): void: Removes a key from storage. -
clear(): void: Clears all stored values. -
length(): numberReturns the total number of stored items.
MIT License © 2025