i45

Type-safe browser storage wrapper for localStorage and sessionStorage

A powerful, type-safe wrapper for browser storage (localStorage and sessionStorage) with built-in logging, validation, and error handling. Built with TypeScript for maximum type safety and developer experience.

Version 3.0.0-alpha.1 - Complete TypeScript rewrite with architectural refactoring (December 2025)

Features

✨ Full TypeScript support with generic types: DataContext<T>
🔒 Type-safe operations - catch errors at compile time
🏗️ Modern architecture - modular design with service orchestration
� Three storage options - localStorage, sessionStorage, and IndexedDB (~50MB+)
⏱️ Automatic timestamp tracking - transparent metadata with createdAt, updatedAt, version
🔄 Time-based patterns - sync-since-timestamp, cache freshness, conflict resolution- 🔗 Cross-tab synchronization (v3.2.0+) - automatic data sync between browser tabs- 💾 Storage quota checking - monitor capacity and usage across storage types
📦 Simple API - config object pattern or legacy constructor
🎯 Zero code duplication - 300+ lines eliminated through refactoring
✅ Comprehensive validation - centralized with ValidationUtils
🚨 6 custom error classes - specific, actionable error handling
🪵 Built-in logging via i45-jslogger
🧪 Well tested - 272 tests with excellent coverage
🎯 Zero dependencies (except i45-jslogger and i45-sample-data)
📝 Sample data included via i45-sample-data
🌳 Tree-shakeable ESM build
📖 Comprehensive type definitions (.d.ts)

Installation

npm install i45

Quick Start

TypeScript (Recommended)

import { DataContext, StorageLocations, Logger } from "i45";

// Define your data type
interface User {
  id: number;
  name: string;
  email: string;
}

// Create a type-safe context with config object (modern approach)
const context = new DataContext<User>({
  storageKey: "Users",
  storageLocation: StorageLocations.LocalStorage,
  trackTimestamps: true, // Automatic metadata (default: true)
  loggingEnabled: true,
  logger: new Logger(),
});

// Or use legacy constructor (still supported)
const legacyContext = new DataContext<User>(
  "Users",
  StorageLocations.LocalStorage
);

// Store data (fully typed!)
await context.store([
  { id: 1, name: "Alice", email: "alice@example.com" },
  { id: 2, name: "Bob", email: "bob@example.com" },
]);

// Retrieve data (returns User[])
const users = await context.retrieve();
console.log(users);

// Get metadata (timestamps, version, count)
const metadata = await context.getMetadata();
console.log(`Created: ${metadata.createdAt}, Version: ${metadata.version}`);

📖 More examples: examples.md | TypeScript Guide

JavaScript

import { DataContext, SampleData } from "i45";

// Create an instance of the datacontext
// The default storage location is localStorage
const context = new DataContext();

// Store data using sample data
await context.store(SampleData.Lists.Astronomy);

// Retrieve data
const data = await context.retrieve();
console.log("Astronomy terms:", data);

Architecture

i45 v3.0.0 features a completely refactored, modular architecture (December 2025).

📖 See also: Migration Guide - Architecture | API Reference

/src
  /core                      # Core application logic
    DataContext.ts           # Main storage context
    StorageManager.ts        # Service orchestration
  /services
    /base                    # Abstract base classes
      IStorageService.ts     # Service interface
      BaseStorageService.ts  # Shared service logic
    LocalStorageService.ts
    SessionStorageService.ts
  /errors                    # Custom error classes
    StorageKeyError.ts
    StorageLocationError.ts
    DataRetrievalError.ts
    StorageQuotaError.ts
    PersistenceServiceNotEnabled.ts
    DataServiceUnavailable.ts
  /models                    # Data models
    DataContextConfig.ts
    storageItem.ts
    storageLocations.ts
  /utils                     # Shared utilities
    ValidationUtils.ts       # Centralized validation
    ErrorHandler.ts          # Error management

Architecture Benefits

Single Responsibility: Each module has one clear purpose
Zero Duplication: 300+ lines of duplicate code eliminated
Easy Testing: Isolated modules with 92% test coverage
Type Safe: Strong typing throughout
Extensible: Add new storage services by implementing interface

Usage

TypeScript Usage
Default Storage Settings
Custom Storage Settings
Retrieving Data
Retrieving Data from Custom Data Stores
Removing Items and Clearing the Data Store
Storage Locations
Using Sample Data
Logging

TypeScript Usage

i45 v3.0 is built with TypeScript and provides full type safety.

📖 See typescript.md for comprehensive TypeScript usage guide

import { DataContext, StorageLocations, type StorageItem } from "i45";

// Generic type for your data
interface Product {
  id: string;
  name: string;
  price: number;
}

// Type-safe context
const context = new DataContext<Product>(
  "products",
  StorageLocations.SessionStorage
);

// Store - TypeScript ensures correct types
await context.store([
  { id: "1", name: "Widget", price: 9.99 },
  { id: "2", name: "Gadget", price: 19.99 },
]);

// Retrieve - returns Product[]
const products = await context.retrieve();
products.forEach((p) => console.log(`${p.name}: $${p.price}`));

Default Storage Settings

import { DataContext, SampleData } from "i45";

// Create an instance - uses localStorage by default with key "i45"
const context = new DataContext();

// Store data
await context.store(SampleData.Lists.Astronomy);

// Retrieve data
const data = await context.retrieve();
console.log(data);

Custom Storage Settings

Modern Config Object (Recommended)

import { DataContext, StorageLocations, Logger } from "i45";

// Create context with configuration object
const context = new DataContext<BookType>({
  storageKey: "Books",
  storageLocation: StorageLocations.SessionStorage,
  loggingEnabled: true,
  logger: new Logger(),
});

// Store books collection
await context.store(SampleData.JsonData.Books);

// Retrieve data
const books = await context.retrieve();
console.log(books);

Legacy Constructor (Still Supported)

import { DataContext, StorageLocations, SampleData } from "i45";

// Create context with positional parameters
const context = new DataContext("Books", StorageLocations.SessionStorage);

// Store books collection
await context.store(SampleData.JsonData.Books);

// Retrieve data
const books = await context.retrieve();
console.log(books);

Retrieving Data

import { DataContext, SampleData } from "i45";

// Create context
const context = new DataContext();

// Store data
await context.store(SampleData.JsonData.States);

// Retrieve and use
const states = await context.retrieve();
console.log("State data:", states);

Explicit Method Signatures

v3.0.0 provides clear, explicit methods (no confusing overloads):

import { DataContext, StorageLocations } from "i45";

const context = new DataContext<MyType>();

// Store with different scopes
await context.store(items); // Default key/location
await context.storeAs("customKey", items); // Custom key
await context.storeAt("key", StorageLocations.SessionStorage, items); // Full control

// Retrieve with different scopes
const data1 = await context.retrieve(); // Default
const data2 = await context.retrieveFrom("customKey"); // Custom key
const data3 = await context.retrieveAt("key", StorageLocations.SessionStorage); // Full control

// Remove with different scopes
await context.remove(); // Default
await context.removeFrom("customKey"); // Custom key
await context.removeAt("key", StorageLocations.SessionStorage); // Full control

Retrieving Data from Custom Data Stores

import { DataContext, StorageLocations, SampleData } from "i45";

// Create context with custom settings
const context = new DataContext("Questions", StorageLocations.SessionStorage);

// Store questions
await context.store(SampleData.JsonData.TriviaQuestions);

// Retrieve by key
const questions = await context.retrieve("Questions");
console.log(questions);

// Retrieve with specific location
const data = await context.retrieve("MyItems", StorageLocations.LocalStorage);

Removing Items and Clearing the Data Store

// Delete a specific data store by key
await context.remove("Questions");

// Clear all data from current storage location
await context.clear();

To clear all entries in all storage locations, call the clear() method.

Warning: Calling the clear() method will clear all entries in all storage locations.

import { DataContext } from "i45";

var dataContext = new DataContext();

// create an array of countries using sample data.
var countries = SampleData.KeyValueLists.Countries;

// save the collection
dataContext.store("Countries", countries);

// removes the item from storage.
dataContext.remove("Countries");

// removes all items from all storage locations.
// *** WARNING *** calling clear() will clears all entries.
datacontext.clear();

Storage Locations

StorageLocations is an enum of available storage options:

import { StorageLocations } from "i45";

// Available options
StorageLocations.LocalStorage; // Uses window.localStorage (default, ~5-10MB)
StorageLocations.SessionStorage; // Uses window.sessionStorage (~5-10MB)
StorageLocations.IndexedDB; // Uses IndexedDB (~50MB+, async database)

Using StorageLocations

import { DataContext, StorageLocations } from "i45";

// Specify storage location in constructor
const context = new DataContext("MyItems", StorageLocations.SessionStorage);

// Or use properties
context.storageLocation = StorageLocations.LocalStorage;

// Use IndexedDB for larger datasets
const largeDataContext = new DataContext({
  storageKey: "LargeDataset",
  storageLocation: StorageLocations.IndexedDB,
});

Using Sample Data

The i45-sample-data package provides sample datasets for development and testing:

import { SampleData } from "i45";

// Access various sample datasets
const books = SampleData.JsonData.Books;
const states = SampleData.JsonData.States;
const astronomy = SampleData.Lists.Astronomy;
const countries = SampleData.KeyValueLists.Countries;

console.log(books);

Logging

i45 integrates i45-jslogger for comprehensive logging support.

📖 See also: examples.md - Custom Logger

Built-In Logging

import { DataContext } from "i45";

const context = new DataContext();

// Enable logging
context.loggingEnabled = true;

// Operations will now be logged
await context.store([{ id: 1, name: "Test" }]);

When enabled, log messages are written to the console and stored in localStorage.

Using a Custom Logger

Add custom logging clients to receive DataContext events:

import { DataContext, Logger } from "i45";

// Create or use your existing logger
const customLogger = new Logger({
  logToConsole: true,
  logToStorage: false,
});

// Add to context
const context = new DataContext();
context.addClient(customLogger);

// Multiple loggers supported
context.addClient(fileSystemLogger);
context.addClient(apiLogger);

API Reference

📖 Complete API documentation: api.md

DataContext

Main class for managing browser storage operations.

class DataContext<T = any> {
  // Constructor - Config object (recommended)
  constructor(config?: DataContextConfig);

  // Constructor - Legacy (still supported)
  constructor(storageKey?: string, storageLocation?: StorageLocation);

  // Properties
  storageKey: string;
  storageLocation: StorageLocation;
  loggingEnabled: boolean;
  logger: Logger | null;

  // Store methods
  async store(items: T[]): Promise<DataContext<T>>;
  async storeAs(storageKey: string, items: T[]): Promise<DataContext<T>>;
  async storeAt(
    storageKey: string,
    storageLocation: StorageLocation,
    items: T[]
  ): Promise<DataContext<T>>;

  // Retrieve methods
  async retrieve(): Promise<T[]>;
  async retrieveFrom(storageKey: string): Promise<T[]>;
  async retrieveAt(
    storageKey: string,
    storageLocation: StorageLocation
  ): Promise<T[]>;

  // Remove methods
  async remove(): Promise<DataContext<T>>;
  async removeFrom(storageKey: string): Promise<DataContext<T>>;
  async removeAt(
    storageKey: string,
    storageLocation: StorageLocation
  ): Promise<DataContext<T>>;

  // Other methods
  async clear(): Promise<DataContext<T>>;
  addClient(logger: Logger): DataContext<T>;
  getCurrentSettings(): {
    storageKey: string;
    storageLocation: StorageLocation;
  };
  getData(): any[];
  printLog(): any[];
}

DataContextConfig

Configuration object for DataContext (v3.0.0+):

interface DataContextConfig {
  storageKey?: string; // Default: "Items"
  storageLocation?: StorageLocation; // Default: localStorage
  logger?: Logger | null; // Optional logger instance
  loggingEnabled?: boolean; // Default: false
}

Types

// Storage location type
export enum StorageLocations {
  SessionStorage = "sessionStorage",
  LocalStorage = "localStorage",
}
export type StorageLocation = `${StorageLocations}`;

// Storage item interface
export interface StorageItem {
  name: string;
  value: string;
}

// Database settings
export interface DatabaseSettings {
  storageKey: string;
  storageLocation: StorageLocation;
  loggingEnabled: boolean;
}

Error Types

v3.0.0 provides 6 custom error classes for specific error handling.

📖 Full error documentation: api.md - Error Classes | Examples

import {
  PersistenceServiceNotEnabled,
  DataServiceUnavailable,
  StorageKeyError,
  StorageLocationError,
  DataRetrievalError,
  StorageQuotaError, // NEW in December 2025
} from "i45";

try {
  await context.store(data);
} catch (error) {
  if (error instanceof StorageKeyError) {
    console.error("Invalid storage key:", error.key);
  } else if (error instanceof StorageQuotaError) {
    console.error("Storage full:", error.key, error.storageType);
  } else if (error instanceof DataRetrievalError) {
    console.error("Failed to retrieve:", error.key, "Cause:", error.cause);
  } else if (error instanceof StorageLocationError) {
    console.error(
      "Invalid location:",
      error.location,
      "Valid:",
      error.validLocations
    );
  }
}

Migration from v2.x

v3.0.0 includes breaking changes and major architectural improvements. See migration.md for the complete migration guide.

Key Changes

New Architecture: Modular design with service orchestration (December 2025)
Config Object Pattern: New recommended way to initialize DataContext
TypeScript First: Full TypeScript rewrite with generic types
Explicit Methods: store(), storeAs(), storeAt() instead of overloaded signatures
6 Custom Errors: Specific error classes for better error handling
Centralized Validation: ValidationUtils for consistent validation
Zero Duplication: 300+ lines of duplicate code eliminated
Property Names: StorageItem.Name → name, StorageItem.Value → value (camelCase)
Async Operations: All storage operations return Promises

Quick Migration Example

// v2.x (Old)
const context = new DataContext();
context.setStorageKey("MyData");
context.store(data); // May not be async

// v3.x (New - Config Object)
const context = new DataContext({
  storageKey: "MyData",
  loggingEnabled: true,
});
await context.store(data); // Always async

// v3.x (New - Legacy Constructor)
const context = new DataContext("MyData");
await context.store(data); // Always async

For detailed migration steps, error handling examples, and troubleshooting, see migration.md.

Browser Support

Chrome/Edge: Latest 2 versions
Firefox: Latest 2 versions
Safari: Latest 2 versions
Modern browsers with ES2015+ support

Requirements

Node.js 16+ (for development)
Modern browser with localStorage/sessionStorage support

Framework Integration

React: See examples.md - React Integration
Vue: See examples.md - Vue Integration
TypeScript: See typescript.md for type-safe integration patterns

Testing

i45 v3.0.0 includes comprehensive testing:

205 tests with Jest
91.7% statement coverage
Unit tests for all components including IndexedDBService
Type safety tests
Error handling tests
Browser storage mocking with fake-indexeddb

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode
npm run test:watch

📖 Testing examples: examples.md - Testing Examples

Documentation

Core Documentation

README.md - This file (getting started and quick reference)
api.md - Complete API reference with all methods, properties, and error classes
typescript.md - TypeScript usage guide with patterns and best practices
examples.md - 20+ comprehensive examples including React/Vue integration
offline-sync.md - Comprehensive offline sync patterns, conflict resolution, and queue management
migration.md - Complete v2.x → v3.x migration guide

Additional Resources

revisions.md - Version history and changelog
REFACTORING-SUMMARY.md - December 2025 refactoring details

License

MIT © CIS Guru

Links

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Changelog

See revisions.md for version history and release notes.

Name		Name	Last commit message	Last commit date
Latest commit History 107 Commits
coverage		coverage
docs		docs
examples		examples
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
eslint.config.js		eslint.config.js
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

xnodeoncode/i45

Folders and files

Latest commit

History

Repository files navigation

i45

Features

Installation

Quick Start

TypeScript (Recommended)

JavaScript

Architecture

Architecture Benefits

Usage

TypeScript Usage

Default Storage Settings

Custom Storage Settings

Modern Config Object (Recommended)

Legacy Constructor (Still Supported)

Retrieving Data

Explicit Method Signatures

Retrieving Data from Custom Data Stores

Removing Items and Clearing the Data Store

Storage Locations

Using StorageLocations

Using Sample Data

Logging

Built-In Logging

Using a Custom Logger

API Reference

DataContext

DataContextConfig

Types

Error Types

Migration from v2.x

Key Changes

Quick Migration Example

Browser Support

Requirements

Framework Integration

Testing

Documentation

Core Documentation

Additional Resources

License

Links

Contributing

Changelog

About

Topics

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages