@svnrnns/typed-storage

A lightweight TypeScript library for managing localStorage and sessionStorage with type safety and optional Zod validation.

Features

• Type Safety: Built for TypeScript with generic types
• Optional Zod Validation: Add schema validation when you need it
• Fallback Values: Ensure a value of the expected type is always retrieved
• Safe Storage Access: Handles JSON parsing errors gracefully
• Namespace Support: Avoid key conflicts with prefixed keys
• Expiration Support: Store values with a time-to-live (TTL)

Installation

npm install @svnrnns/typed-storage zod

Quick Start

Basic Usage

Create a TypedStorage instance with localStorage or sessionStorage:

import { TypedStorage } from '@svnrnns/typed-storage';

const storage = new TypedStorage(localStorage);

// Set a value
storage.setItem('theme', 'dark');
storage.setItem('user', { id: 1, name: 'John' });

// Get a value (returns null if not found)
const theme = storage.getItem('theme'); // 'dark' | null
const user = storage.getItem<{ id: number; name: string }>('user');

// Get with fallback (returns fallback if not found)
const locale = storage.getItem('locale', 'en'); // 'en' if not found

// Remove a value
storage.removeItem('theme');

// Clear all values
storage.clear();

// Check if key exists
storage.itemExists('theme'); // boolean

// Get storage length
storage.length(); // number

With Namespace

Use a namespace to prefix keys and avoid conflicts:

import { TypedStorage } from '@svnrnns/typed-storage';

const storage = new TypedStorage(localStorage, 'my-app');

storage.setItem('theme', 'dark');
// Stored as 'my-app:theme' in localStorage

With Zod Validation

Add a Zod schema as the third parameter for type-safe validation:

import { TypedStorage } from '@svnrnns/typed-storage';
import { z } from 'zod';

const storage = new TypedStorage(localStorage);

// Get with Zod validation (returns fallback if not found or invalid)
const themeSchema = z.enum(['light', 'dark']);
const theme = storage.getItem('theme', 'light', themeSchema);
// Returns 'light' if key 'theme' is not found or fails validation

With Expiration

Set values with a time-to-live (TTL) in milliseconds:

import { TypedStorage } from '@svnrnns/typed-storage';

const storage = new TypedStorage(localStorage);

// Expires in 1 hour
storage.setItemWithExpiration('token', 'xxxx', 3600000);

Standalone Functions

You can also import standalone functions (uses localStorage by default):

import { getItem, setItem, setItemWithExpiration, itemExists, removeItem, clear, length } from '@svnrnns/typed-storage';

Examples

Store arrays or complex objects with Zod validation:

import { TypedStorage } from '@svnrnns/typed-storage';
import { z } from 'zod';

const storage = new TypedStorage(localStorage);

storage.setItem('filters', ['desc', 'price']);

const schema = z.array(z.string());
const filters = storage.getItem('filters', [], schema);
// Returns ['desc', 'price'] or [] if invalid

API Reference

TypedStorage

| Method | Signature | Description | | ----------------------- | ------------------------------------------------------------- | --------------------------------------------- | | setItem | setItem<T>(key: string, value: T): void | Stores a value in storage. | | setItemWithExpiration | setItemWithExpiration<T>(key: string, value: T, ttl): void | Stores a value that expires after ttl ms. | | getItem | getItem<T>(key: string): T \| null | Retrieves a value. Returns null if not found. | | getItem | getItem<T>(key: string, fallback: T): T | Retrieves a value with fallback. | | getItem | getItem<T>(key: string, fallback: T, schema: ZodType<T>): T | Retrieves a value with Zod validation. | | removeItem | removeItem(key: string): void | Removes a key from storage. | | clear | clear(): void | Clears all stored values. | | itemExists | itemExists(key: string): boolean | Checks if a key exists. | | length | length(): number | Returns the total number of stored items. | | getStorage | getStorage(): globalThis.Storage | Returns the underlying storage instance. | | getNamespace | getNamespace(): string \| undefined | Gets the current namespace. | | setNamespace | setNamespace(namespace: string): void | Sets a new namespace. | | static isAvailable | isAvailable(): boolean | Checks if storage is available. |

MIT License © 2025