📑 Table of Contents

✨ Features

🚀Lightweight - Tiny bundle size at ~11KB

import{createStore}from'substate';// Only ~11KB total

🔒Type-safe - Full TypeScript support with comprehensive type definitions

interfaceUser{id:number;name:string;email:string;}constuserStore=createStore<User>({name:'UserStore',state:{user:nullasUser|null,loading:false}});// TypeScript knows the exact shape of your stateuserStore.updateState({user:{id:1,name:'John',email:'john@example.com'}});

🔄Reactive - Built-in Pub/Sub pattern for reactive state updates

conststore=createStore({name:'ReactiveStore',state:{count:0}});// Subscribe to state changesstore.on('UPDATE_STATE',(newState)=>{console.log('State updated:',newState);// React to changes automatically});

🕰️Time Travel - Complete state history with ability to navigate between states

conststore=createStore({name:'TimeTravelStore',state:{count:0}});// Make some changesstore.updateState({count:1});store.updateState({count:2});store.updateState({count:3});// Go back in timeconsole.log(store.getState(0));// { count: 0 } - initial stateconsole.log(store.getState(1));// { count: 1 } - first updateconsole.log(store.getState(2));// { count: 2 } - second update

🏷️Tagged States - Named checkpoints for easy state restoration

constgameStore=createStore({name:'GameStore',state:{level:1,score:0}});// Create a checkpointgameStore.updateState({level:5,score:1250,$tag:'level-5-start'});// Later, jump back to that checkpointgameStore.jumpToTag('level-5-start');console.log(gameStore.getCurrentState());// { level: 5, score: 1250 }

🎯Immutable - Automatic deep cloning prevents accidental state mutations

conststore=createStore({name:'ImmutableStore',state:{user:{name:'John',settings:{theme:'dark'}}}});// State is automatically deep cloned - original object is safeconstoriginalState=store.getCurrentState();originalState.user.name='Jane';// This won't affect the storeconsole.log(store.getProp('user.name'));// Still 'John'

🔗Sync - Unidirectional data binding with middleware transformations

conststore=createStore({name:'SyncStore',state:{price:29.99}});// Sync to UI with formattingconstuiModel={formattedPrice:''};constunsync=store.sync({readerObj:uiModel,stateField:'price',readField:'formattedPrice',beforeUpdate:[(price)=>`$${price.toFixed(2)}`]});console.log(uiModel.formattedPrice);// '$29.99'

🎪Middleware - Extensible with before/after update hooks

conststore=createStore({name:'MiddlewareStore',state:{count:0},beforeUpdate:[(store,action)=>{console.log('About to update:',action);// Validation logic here}],afterUpdate:[(store,action)=>{console.log('Updated to:',store.getCurrentState());// Persistence logic here}]});

🌳Nested Props - Easy access to nested properties with optional dot notation or standard object spread

conststore=createStore({name:'NestedStore',state:{user:{profile:{name:'John',email:'john@example.com'}}}});// Dot notation (convenient)store.updateState({'user.profile.name':'Jane'});// Object spread (explicit)store.updateState({user:{    ...store.getProp('user'),profile:{      ...store.getProp('user.profile'),name:'Jane'}}});// Both approaches work equally well

📦Framework Agnostic - Works with any JavaScript framework or vanilla JS

// Vanilla JavaScriptconststore=createStore({name:'VanillaStore',state:{count:0}});// Reactimport{useEffect,useState}from'react';functionCounter(){const[count,setCount]=useState(0);useEffect(()=>{store.on('UPDATE_STATE',(state)=>setCount(state.count));},[]);}// Vue, Angular, Svelte - works with all frameworks!

📦 Installation

npm

npm install substate

yarn

yarn add substate

pnpm

pnpm add substate

Requirements

Bundle Size

CDN

<!-- UMD Build --><scriptsrc="https://cdn.jsdelivr.net/npm/substate@latest/dist/index.umd.js"></script><!-- ESM Build --><scripttype="module">import{createStore}from'https://cdn.jsdelivr.net/npm/substate@latest/dist/index.esm.js';</script>

🚀 Quick Start

Installation & Basic Usage

npm install substate

import{createStore}from'substate';// Create a simple counter storeconstcounterStore=createStore({name:'CounterStore',state:{count:0,lastUpdated:Date.now()}});// Update statecounterStore.updateState({count:1});console.log(counterStore.getCurrentState());// { count: 1, lastUpdated: 1234567890 }// Listen to changescounterStore.on('UPDATE_STATE',(newState)=>{console.log('Counter updated:',newState.count);});

Next Steps

Common Patterns

Counter with Actions

constcounterStore=createStore({name:'Counter',state:{count:0}});// Action functions (optional but recommended)functionincrement(){counterStore.updateState({count:counterStore.getProp('count')+1});}functiondecrement(){counterStore.updateState({count:counterStore.getProp('count')-1});}functionreset(){counterStore.resetState();// Back to initial state}// Subscribe to changescounterStore.on('UPDATE_STATE',(state)=>{console.log('Count changed to:',state.count);});// Use the actionsincrement();// count: 1increment();// count: 2decrement();// count: 1reset();// count: 0

Form State Management

constformStore=createStore({name:'ContactForm',state:{name:'',email:'',message:'',isSubmitting:false,errors:{}}});// Update form fieldsfunctionupdateField(field:string,value:string){formStore.updateState({[field]:value});}// Submit formasyncfunctionsubmitForm(){formStore.updateState({isSubmitting:true,errors:{}});try{awaitsubmitToAPI(formStore.getCurrentState());console.log('Form submitted successfully!');formStore.resetState();// Clear form}catch(error){formStore.updateState({isSubmitting:false,errors:{submit:error.message}});}}// Listen for form changesformStore.on('UPDATE_STATE',(state)=>{if(state.isSubmitting){console.log('Submitting form...');}});

🏷️ Tagged States

What is a Named State Checkpoint System?

Basic Usage

import{createStore}from'substate';constgameStore=createStore({name:'GameStore',state:{level:1,score:0,lives:3}});// Create tagged checkpoints with meaningful namesgameStore.updateState({level:5,score:1250,$tag:"level-5-start"});gameStore.updateState({level:10,score:5000,lives:2,$tag:"boss-fight"});// Jump back to any tagged state by namegameStore.jumpToTag("level-5-start");console.log(gameStore.getCurrentState());// { level: 5, score: 1250, lives: 3 }// Access tagged states without changing current stateconstbossState=gameStore.getTaggedState("boss-fight");console.log(bossState);// { level: 10, score: 5000, lives: 2 }// Manage your tagsconsole.log(gameStore.getAvailableTags());// ["level-5-start", "boss-fight"]gameStore.removeTag("level-5-start");

Advanced Checkpoint Patterns

Form Wizard with Step Restoration

constformStore=createStore({name:'FormWizard',state:{currentStep:1,personalInfo:{firstName:'',lastName:'',email:''},addressInfo:{street:'',city:'',zip:''},paymentInfo:{cardNumber:'',expiry:''}}});// Save progress at each completed stepfunctioncompletePersonalInfo(data){formStore.updateState({personalInfo:data,currentStep:2,$tag:"step-1-complete"});}functioncompleteAddressInfo(data){formStore.updateState({addressInfo:data,currentStep:3,$tag:"step-2-complete"});}// User can jump back to any completed stepfunctiongoToStep(stepNumber){conststepTag=`step-${stepNumber}-complete`;if(formStore.getAvailableTags().includes(stepTag)){formStore.jumpToTag(stepTag);}}// UsagegoToStep(1);// Jump back to personal info stepgoToStep(2);// Jump back to address info step

Debugging and Error Recovery

constappStore=createStore({name:'AppStore',state:{userData:null,settings:{},lastError:null}});// Tag known good states for debuggingfunctionmarkKnownGoodState(){appStore.updateState({$tag:"last-known-good"});}// When errors occur, jump back to known good statefunctionhandleError(error){console.error('Error occurred:',error);if(appStore.getAvailableTags().includes("last-known-good")){console.log('Rolling back to last known good state...');appStore.jumpToTag("last-known-good");}}// Tag states before risky operationsfunctionperformRiskyOperation(){appStore.updateState({$tag:"before-risky-operation"});// ... perform operation that might failif(operationFailed){appStore.jumpToTag("before-risky-operation");}}

Game Save System

constgameStore=createStore({name:'GameStore',state:{player:{health:100,level:1,inventory:[]},world:{currentArea:'town',discoveredAreas:[]},quests:{active:[],completed:[]}}});// Auto-save systemfunctionautoSave(){consttimestamp=newDate().toISOString();gameStore.updateState({$tag:`auto-save-${timestamp}`});}// Manual save systemfunctionmanualSave(saveName){gameStore.updateState({$tag:`save-${saveName}`});}// Load save systemfunctionloadSave(saveName){constsaveTag=`save-${saveName}`;if(gameStore.getAvailableTags().includes(saveTag)){gameStore.jumpToTag(saveTag);returntrue;}returnfalse;}// Get all available savesfunctiongetAvailableSaves(){returngameStore.getAvailableTags().filter(tag=>tag.startsWith('save-')).map(tag=>tag.replace('save-',''));}// UsagemanualSave("checkpoint-1");manualSave("before-boss-fight");loadSave("checkpoint-1");

Feature Flag and A/B Testing

constexperimentStore=createStore({name:'ExperimentStore',state:{features:{},userGroup:null,experimentResults:{}}});// Tag different experiment variantsfunctionsetupExperimentVariant(variant){experimentStore.updateState({userGroup:variant,$tag:`experiment-${variant}`});}// Jump between experiment variantsfunctionswitchToVariant(variant){constvariantTag=`experiment-${variant}`;if(experimentStore.getAvailableTags().includes(variantTag)){experimentStore.jumpToTag(variantTag);}}// UsagesetupExperimentVariant("control");setupExperimentVariant("variant-a");setupExperimentVariant("variant-b");switchToVariant("variant-a");// Switch to variant A

🎯 Common Tagging Patterns

// Form checkpointsformStore.updateState({ ...formData,$tag:"before-validation"});// API operation snapshotsstore.updateState({users:userData,$tag:"after-user-import"});// Feature flags / A-B testingstore.updateState({features:newFeatures,$tag:"experiment-variant-a"});// Debugging checkpointsstore.updateState({debugInfo:data,$tag:"issue-reproduction"});// Game savesgameStore.updateState({ saveData,$tag:`save-${Date.now()}`});// Workflow statesworkflowStore.updateState({status:"approved",$tag:"workflow-approved"});// User session statessessionStore.updateState({user:userData,$tag:"user-logged-in"});

📚 Usage Examples

1. Todo List Management

import{createStore}from'substate';interfaceTodo{id:string;text:string;completed:boolean;}consttodoStore=createStore({name:'TodoStore',state:{todos:[]asTodo[],filter:'all'as'all'|'active'|'completed'},defaultDeep:true});// Add a new todofunctionaddTodo(text:string){constcurrentTodos=todoStore.getProp('todos')asTodo[];todoStore.updateState({todos:[...currentTodos,{id:crypto.randomUUID(),      text,completed:false}]});}// Toggle todo completionfunctiontoggleTodo(id:string){consttodos=todoStore.getProp('todos')asTodo[];todoStore.updateState({todos:todos.map(todo=>todo.id===id ?{ ...todo,completed:!todo.completed} :todo)});}// Subscribe to changestodoStore.on('UPDATE_STATE',(state)=>{console.log(`${state.todos.length} todos, filter:${state.filter}`);});

2. User Authentication Store

import{createStore}from'substate';constauthStore=createStore({name:'AuthStore',state:{user:null,isAuthenticated:false,loading:false,error:null},beforeUpdate:[(store,action)=>{// Log all state changesconsole.log('Auth state changing:',action);}],afterUpdate:[(store,action)=>{// Persist authentication stateif(action.user||action.isAuthenticated!==undefined){localStorage.setItem('auth',JSON.stringify(store.getCurrentState()));}}]});// Login actionasyncfunctionlogin(email:string,password:string){authStore.updateState({loading:true,error:null});try{constuser=awaitauthenticateUser(email,password);authStore.updateState({      user,isAuthenticated:true,loading:false});}catch(error){authStore.updateState({error:error.message,loading:false,isAuthenticated:false});}}

3. Shopping Cart with Middleware

import{createStore}from'substate';constcartStore=createStore({name:'CartStore',state:{items:[],total:0,tax:0,discount:0},defaultDeep:true,afterUpdate:[// Automatically calculate totals after any update(store)=>{conststate=store.getCurrentState();constsubtotal=state.items.reduce((sum,item)=>sum+(item.price*item.quantity),0);consttax=subtotal*0.08;// 8% taxconsttotal=subtotal+tax-state.discount;// Update calculated fields without triggering infinite loopstore.stateStorage[store.currentState]={        ...state,        total,        tax};}]});functionaddToCart(product){constitems=cartStore.getProp('items');constexistingItem=items.find(item=>item.id===product.id);if(existingItem){cartStore.updateState({items:items.map(item=>item.id===product.id          ?{ ...item,quantity:item.quantity+1}          :item)});}else{cartStore.updateState({items:[...items,{ ...product,quantity:1}]});}}

4. Working with Nested Properties

constuserStore=createStore({name:'UserStore',state:{profile:{personal:{name:'John Doe',email:'john@example.com'},preferences:{theme:'dark',notifications:true}},settings:{privacy:{publicProfile:false}}},defaultDeep:true});// Update nested properties using dot notation (convenient for simple updates)userStore.updateState({'profile.personal.name':'Jane Doe'});userStore.updateState({'profile.preferences.theme':'light'});userStore.updateState({'settings.privacy.publicProfile':true});// Or update nested properties using object spread (no string notation required)userStore.updateState({profile:{     ...userStore.getProp('profile'),personal:{       ...userStore.getProp('profile.personal'),name:'Jane Doe'}}});// Both approaches work - choose what feels more natural for your use caseuserStore.updateState({'profile.preferences.theme':'light'});// Dot notationuserStore.updateState({profile:{     ...userStore.getProp('profile'),preferences:{       ...userStore.getProp('profile.preferences'),theme:'light'}}});// Object spread// Get nested propertiesconsole.log(userStore.getProp('profile.personal.name'));// 'Jane Doe'console.log(userStore.getProp('profile.preferences'));// { theme: 'light', notifications: true }

🎯 Framework Integrations

React/Preact

import{createStore,typeTState}from"substate";import{useSubstate,useSubstateActions}from"substate/react";// or "substate/preact"typeMyAppState=TState&{firstName:string;}conststore=createStore<MyAppState>({state:{firstName:"Ralph"}});functionMyApp(){const{ state}=useSubstate(store(state)=>state);//whole stateconst{ firstName}=useSubstate(store,(state)=>state.firstName);//state with seletorconst{     updateState,     resetState,     jumpToTag,     getAvailableTags,    getMemoryUsage}=useSubstateActions(store);return(<inputonChange={e=>updateState({firstName:e.target.value})}value={firstName}/>);}

Lit

import{LitElement,html}from'lit'import{customElement,property}from'lit/decorators.js'import{store}from'../../store';// store instance@customElement('counter')exportclassCounterLitElement{privatesyncedCount;constructor(){super();this.syncedCount=store.sync({readerObj:thisasMultiplier,stateField:'count',});}disconnectedCallback(){super.disconnectedCallback();this.syncedCount.unsync();}  @property({type:Number})count=0;render(){returnhtml`<div>${this.count}<buttontype="button"@click=${this._increment}+1</button></div>    `}private_increment(){store.updateState({count:this.count+1});}}declare global{interfaceHTMLElementTagNameMap{'multiplier-el':Multiplier}}```## 🔗 Sync - Unidirectional Data BindingOne of Substate's most powerful features is the `sync` method, which provides unidirectional data binding between your store and any target object (like UI models, form objects, or API payloads).### Basic Sync Example```typescriptimport{createStore}from'substate';constuserStore=createStore({name:'UserStore',state:{userName:'John',age:25}});// Target object (could be a UI model, form, etc.)constuiModel={displayName:'',userAge:0};// Sync userName from store to displayName in uiModelconstunsync=userStore.sync({readerObj:uiModel,stateField:'userName',readField:'displayName'});console.log(uiModel.displayName);// 'John' - immediately synced// When store updates, uiModel automatically updatesuserStore.updateState({userName:'Alice'});console.log(uiModel.displayName);// 'Alice'// Changes to uiModel don't affect the store (unidirectional)uiModel.displayName='Bob';console.log(userStore.getProp('userName'));// Still 'Alice'// Cleanup when no longer neededunsync();

Sync with Middleware Transformations

constproductStore=createStore({name:'ProductStore',state:{price:29.99,currency:'USD',name:'awesome widget'}});constdisplayModel={formattedPrice:'',productTitle:''};// Sync with transformation middlewareconstunsyncPrice=productStore.sync({readerObj:displayModel,stateField:'price',readField:'formattedPrice',beforeUpdate:[// Transform price to currency format(price,context)=>`$${price.toFixed(2)}`,// Add currency symbol based on store state(formattedPrice,context)=>{constcurrency=productStore.getProp('currency');returncurrency==='EUR' ?formattedPrice.replace('$','€') :formattedPrice;}],afterUpdate:[// Log the transformation(finalValue,context)=>{console.log(`Price synced:${finalValue} for field${context.readField}`);}]});constunsyncName=productStore.sync({readerObj:displayModel,stateField:'name',readField:'productTitle',beforeUpdate:[// Transform to title case(name)=>name.split(' ').map(word=>word.charAt(0).toUpperCase()+word.slice(1)).join(' ')]});console.log(displayModel.formattedPrice);// '$29.99'console.log(displayModel.productTitle);// 'Awesome Widget'// Update triggers all synced transformationsproductStore.updateState({price:39.99,name:'super awesome widget'});console.log(displayModel.formattedPrice);// '$39.99'console.log(displayModel.productTitle);// 'Super Awesome Widget'

Real-world Sync Example: Form Binding

// Form state storeconstformStore=createStore({name:'FormStore',state:{user:{firstName:'',lastName:'',email:'',birthDate:null},validation:{isValid:false,errors:[]}}});// Form UI object (could be from any UI framework)constformUI={fullName:'',emailInput:'',ageDisplay:'',submitEnabled:false};// Sync full name (combining first + last)constunsyncName=formStore.sync({readerObj:formUI,stateField:'user',readField:'fullName',beforeUpdate:[(user)=>`${user.firstName}${user.lastName}`.trim()]});// Sync email directlyconstunsyncEmail=formStore.sync({readerObj:formUI,stateField:'user.email',readField:'emailInput'});// Sync age calculation from birth dateconstunsyncAge=formStore.sync({readerObj:formUI,stateField:'user.birthDate',readField:'ageDisplay',beforeUpdate:[(birthDate)=>{if(!birthDate)return'Not provided';constage=newDate().getFullYear()-newDate(birthDate).getFullYear();return`${age} years old`;}]});// Sync form validity to submit buttonconstunsyncValid=formStore.sync({readerObj:formUI,stateField:'validation.isValid',readField:'submitEnabled'});// Update form dataformStore.updateState({'user.firstName':'John','user.lastName':'Doe','user.email':'john@example.com','user.birthDate':'1990-05-15','validation.isValid':true});console.log(formUI);// {//   fullName: 'John Doe',//   emailInput: 'john@example.com',//   ageDisplay: '34 years old',//   submitEnabled: true// }

Multiple Sync Instances

constdataStore=createStore({name:'DataStore',state:{timestamp:Date.now()}});constdashboard={lastUpdate:''};constreport={generatedAt:''};constapi={timestamp:0};// Sync to dashboard with human-readable formatconstunsync1=dataStore.sync({readerObj:dashboard,stateField:'timestamp',readField:'lastUpdate',beforeUpdate:[(ts)=>newDate(ts).toLocaleString()]});// Sync to report with ISO stringconstunsync2=dataStore.sync({readerObj:report,stateField:'timestamp',readField:'generatedAt',beforeUpdate:[(ts)=>newDate(ts).toISOString()]});// Sync to API with raw timestampconstunsync3=dataStore.sync({readerObj:api,stateField:'timestamp'// uses same field name when readField omitted});// One update triggers all syncsdataStore.updateState({timestamp:Date.now()});

TypeScript Support

import{createStore,typeISubstate,typeICreateStoreConfig}from'substate';constconfig:ICreateStoreConfig={name:'TypedStore',state:{count:0},defaultDeep:true};conststore:ISubstate=createStore(config);

📖 API Reference

createStore(config)

functioncreateStore(config:ICreateStoreConfig):ISubstate

conststore=createStore({name:'MyStore',state:{count:0},defaultDeep:true,maxHistorySize:25,// Keep only last 25 states for memory efficiencybeforeUpdate:[(store,action)=>console.log('Updating...',action)],afterUpdate:[(store,action)=>console.log('Updated!',store.getCurrentState())]});

Store Methods

updateState(action: IState): void

// Simple updatestore.updateState({count:5});// Nested property update with dot notation (optional convenience feature)store.updateState({'user.profile.name':'John'});// Or update nested properties using standard object spread (no strings required)store.updateState({user:{     ...store.getProp('user'),profile:{       ...store.getProp('user.profile'),name:'John'}}});// Force deep cloning for this updatestore.updateState({data:complexObject,$deep:true});// Update with custom type identifierstore.updateState({items:newItems,$type:'BULK_UPDATE'});// Adding a tagstore.updateState({items:importantItem,$tag:'important-item-added'});

batchUpdateState(actions: Array<Partial<TSubstateState> & IState>): void

// Instead of multiple individual updates (slower)store.updateState({counter:1});store.updateState({user:{name:"John"}});store.updateState({theme:"dark"});// Use batch update for better performancestore.batchUpdateState([{counter:1},{user:{name:"John"}},{theme:"dark"}]);// Batch updates with complex operationsstore.batchUpdateState([{'user.profile.name':'Jane'},{'user.profile.email':'jane@example.com'},{'settings.theme':'light'},{'settings.notifications':true}]);// Batch updates with metadatastore.batchUpdateState([{data:newData,$type:'DATA_IMPORT'},{lastUpdated:Date.now()},{version:'2.0.0'}]);

// Form submission with multiple fieldsfunctionsubmitForm(formData){store.batchUpdateState([{'form.isSubmitting':true},{'form.data':formData},{'form.errors':[]},{'form.lastSubmitted':Date.now()}]);}// Bulk data importfunctionimportData(items){store.batchUpdateState([{'data.items':items},{'data.totalCount':items.length},{'data.lastImport':Date.now()},{'ui.showImportSuccess':true}]);}// User profile updatefunctionupdateProfile(profileData){store.batchUpdateState([{'user.profile':profileData},{'user.lastUpdated':Date.now()},{'ui.profileUpdated':true}]);}

getCurrentState(): IState

constcurrentState=store.getCurrentState();console.log(currentState);// { count: 5, user: { name: 'John' }}

getProp(prop: string): unknown

// Get top-level propertyconstcount=store.getProp('count');// 5// Get nested propertyconstuserName=store.getProp('user.profile.name');// 'John'// Get array elementconstfirstItem=store.getProp('items.0.title');// Returns undefined for non-existent propertiesconstmissing=store.getProp('nonexistent.path');// undefined

getState(index: number): IState

// Get initial state (always at index 0)constinitialState=store.getState(0);// Get previous stateconstpreviousState=store.getState(store.currentState-1);// Get specific historical stateconstspecificState=store.getState(3);

resetState(): void

store.resetState();console.log(store.currentState);// 0console.log(store.getCurrentState());// Returns initial state

sync(config: ISyncConfig): () => void

constunsync=store.sync({readerObj:targetObject,stateField:'user.name',readField:'displayName',beforeUpdate:[(value)=>value.toUpperCase()],afterUpdate:[(value)=>console.log('Synced:',value)]});// Call to cleanup the syncunsync();

clearHistory(): void

// After many state updates...console.log(store.stateStorage.length);// 50+ statesstore.clearHistory();console.log(store.stateStorage.length);// 1 stateconsole.log(store.currentState);// 0// Current state is preservedconsole.log(store.getCurrentState());// Latest state data

limitHistory(maxSize: number): void

// Current setupstore.limitHistory(10);// Keep only last 10 states// If current history exceeds the limit, it gets trimmedconsole.log(store.stateStorage.length);// Max 10 states// Dynamic adjustment for debuggingif(debugMode){store.limitHistory(100);// More history for debugging}else{store.limitHistory(5);// Minimal history for production}

getMemoryUsage(): { stateCount: number; taggedCount: number; estimatedSizeKB: number }

constusage=store.getMemoryUsage();console.log(`States:${usage.stateCount}`);console.log(`Estimated Size:${usage.estimatedSizeKB}KB`);// Memory monitoringif(usage.estimatedSizeKB>1000){console.warn('Store using over 1MB of memory');store.clearHistory();// Clean up if needed}// Performance trackingsetInterval(()=>{const{ stateCount, estimatedSizeKB}=store.getMemoryUsage();console.log(`Memory:${estimatedSizeKB}KB (${stateCount} states)`);},10000);

getTaggedState(tag: string): IState | undefined

// Create tagged statesstore.updateState({user:userData,$tag:"user-login"});store.updateState({cart:cartData,$tag:"checkout-ready"});// Retrieve specific tagged statesconstloginState=store.getTaggedState("user-login");constcheckoutState=store.getTaggedState("checkout-ready");// Returns undefined for non-existent tagsconstmissing=store.getTaggedState("non-existent");// undefined

getAvailableTags(): string[]

store.updateState({step:1,$tag:"step-1"});store.updateState({step:2,$tag:"step-2"});console.log(store.getAvailableTags());// ["step-1", "step-2"]// Use for conditional navigationif(store.getAvailableTags().includes("last-known-good")){store.jumpToTag("last-known-good");}

jumpToTag(tag: string): void

// Create checkpointsstore.updateState({page:"home",$tag:"home-page"});store.updateState({page:"profile",user:userData,$tag:"profile-page"});store.updateState({page:"settings"});// Jump back to a checkpointstore.jumpToTag("profile-page");console.log(store.getCurrentState().page);// "profile"// Continue from the restored statestore.updateState({page:"edit-profile"});

removeTag(tag: string): boolean

store.updateState({temp:"data",$tag:"temporary"});constwasRemoved=store.removeTag("temporary");console.log(wasRemoved);// true// Tag is now goneconsole.log(store.getTaggedState("temporary"));// undefined

clearTags(): void

// After bulk operations with many tagsstore.clearTags();console.log(store.getAvailableTags());// []// State history remains intactconsole.log(store.stateStorage.length);// Still has all states

Event Methods (Inherited from PubSub)

on(event: string, callback: Function): void

// Listen to state updatesstore.on('STATE_UPDATED',(newState:IState)=>{console.log('State changed:',newState);});// Listen to tagging eventsstore.on('TAG_JUMPED',({ tag, state})=>{console.log(`Jumped to tag:${tag}`,state);});// Listen to memory management eventsstore.on('HISTORY_CLEARED',({ previousLength})=>{console.log(`Cleared${previousLength} states from history`);});// Listen to custom eventsstore.on('USER_LOGIN',(userData)=>{console.log('User logged in:',userData);});

emit(event: string, data?: unknown): void

// Emit custom eventstore.emit('USER_LOGIN',{userId:123,name:'John'});// Emit without datastore.emit('CACHE_CLEARED');

off(event: string, callback: Function): void

consthandler=(state)=>console.log(state);store.on('UPDATE_STATE',handler);store.off('UPDATE_STATE',handler);// Removes this specific handler

Store Properties

Middleware Order

🧠 Memory Management

Automatic History Management

conststore=createStore({name:'AutoManagedStore',state:{data:[]},maxHistorySize:50// Default - good for most applications});// After 100 updates, only the last 50 states are keptfor(leti=0;i<100;i++){store.updateState({data:[i]});}console.log(store.stateStorage.length);// 50 (not 100!)

Memory Optimization Strategies

For Small Applications (Default)

// Use default settings - 50 states is perfect for small appsconststore=createStore({name:'SmallApp',state:{user:null,settings:{}}// maxHistorySize: 50 (default)});

For High-Frequency Updates

// Reduce history for apps with frequent state changesconststore=createStore({name:'RealtimeApp',state:{liveData:[]},maxHistorySize:10// Keep minimal history});// Or dynamically adjustif(isRealtimeMode){store.limitHistory(5);}

For Large State Objects

// Monitor and manage memory proactivelyconststore=createStore({name:'LargeDataApp',state:{dataset:[],cache:{}},maxHistorySize:20});// Regular memory monitoringsetInterval(()=>{const{ stateCount, estimatedSizeKB}=store.getMemoryUsage();if(estimatedSizeKB>5000){// Over 5MBconsole.log('Memory usage high, clearing history...');store.clearHistory();}},30000);

For Debugging vs Production

conststore=createStore({name:'FlexibleApp',state:{app:'data'},maxHistorySize:process.env.NODE_ENV==='development' ?100 :25});// Runtime adjustmentif(debugMode){store.limitHistory(200);// More history for debugging}else{store.limitHistory(10);// Minimal for production}

Memory Monitoring

// Basic monitoringfunctionlogMemoryUsage(store:ISubstate,context:string){const{ stateCount, estimatedSizeKB}=store.getMemoryUsage();console.log(`${context}:${stateCount} states, ~${estimatedSizeKB}KB`);}// After bulk operationslogMemoryUsage(store,'After data import');// Regular health checkssetInterval(()=>logMemoryUsage(store,'Health check'),60000);

Best Practices

Performance Impact

⚡ Performance Benchmarks

🚀 Shallow State Performance

🏗️ Deep State Performance

📊 Key Performance Insights

🏃‍♂️ Real-World Performance

// ✅ Excellent for high-frequency updatesconstfastStore=createStore({name:'RealtimeStore',state:{liveData:[]},defaultDeep:false// 1.41μs per update});// ✅ Great for complex nested stateconstcomplexStore=createStore({name:'ComplexStore',state:deepNestedObject,defaultDeep:true// 428μs per deep update});// ✅ Property access is always fastconstvalue=store.getProp('deeply.nested.property');// ~1μs

🆚 Performance Comparison

🔬 Performance Comparison Benchmarks

📊 What We Compare

🎯 Measured Metrics

🚀 Running Comparison Benchmarks

# Run all comparison benchmarksnpm run test:comparison# Generate comparison reportnpm run test:comparison:report# Run individual benchmarkscd benchmark-comparisonsnpm run benchmark:substatenpm run benchmark:reduxnpm run benchmark:zustandnpm run benchmark:native

📈 Sample Results

🔬 Benchmark Methodology

📁 Results Storage

📊 Report Generation

🎯 Key Insights

📊 Use Case Recommendations

🔄 Why Choose Substate?

Comparison with Other State Management Solutions

When to Use Substate

Migration Benefits

🎯 What Makes Substate Unique

📋 TypeScript Definitions

Core Interfaces

interfaceISubstateextendsIPubSub{name:string;afterUpdate:UpdateMiddleware[];beforeUpdate:UpdateMiddleware[];currentState:number;stateStorage:IState[];defaultDeep:boolean;getState(index:number):IState;getCurrentState():IState;getProp(prop:string):unknown;resetState():void;updateState(action:IState):void;sync(config:ISyncConfig):()=>void;}interfaceICreateStoreConfig{name:string;state?:object;defaultDeep?:boolean;beforeUpdate?:UpdateMiddleware[];afterUpdate?:UpdateMiddleware[];}interfaceIState{[key:string]:unknown;$type?:string;$deep?:boolean;}interfaceISyncConfig{readerObj:Record<string,unknown>;stateField:string;readField?:string;beforeUpdate?:BeforeMiddleware[];afterUpdate?:AfterMiddleware[];}

Middleware Types