Superutils

Appearance

Interface: IObjectStore<T, CacheDisabled> ​

Defined in: store/src/types/IObjectStore.ts:10

Extends ​

  • Omit<IStore<keyof T, T[keyof T], CacheDisabled>, "validate">

Type Parameters ​

T ​

T extends object = object

CacheDisabled ​

CacheDisabled extends boolean = false

Properties ​

cacheDisabled ​

readonly cacheDisabled: CacheDisabled

Defined in: store/src/types/IStore.ts:87

Disable in-memory cache and only directly read/write from storage (local storage or JSON fle)

Inherited from ​

Omit.cacheDisabled

clear ​

readonly clear: () => IStore<keyof T, T[keyof T], CacheDisabled>

Defined in: store/src/types/IStore.ts:273

Clear all items

Returns ​

IStore<keyof T, T[keyof T], CacheDisabled>

Inherited from ​

Omit.clear

delay ​

readonly delay: number

Defined in: store/src/types/IStore.ts:97

Debounce/throttle delay duration in milliseconds for writing to storage when caching is enabled.

Increasing this value can improve performance when dealing with large datasets or frequent updates by reducing the number of write operations.

Default: 300

Inherited from ​

IStore.delay

delayOptions? ​

readonly optional delayOptions?: Store_DelayOptions

Defined in: store/src/types/IStore.ts:100

Debounce and throttle related options

Inherited from ​

Omit.delayOptions

delete ​

readonly delete: (key) => IStore<keyof T, T[keyof T], CacheDisabled>

Defined in: store/src/types/IStore.ts:276

Delete one or more items by their respective keys

Parameters ​

key ​

keyof T | keyof T[]

Returns ​

IStore<keyof T, T[keyof T], CacheDisabled>

Inherited from ​

Omit.delete

entries ​

readonly entries: () => [keyof T, T[keyof T]][]

Defined in: store/src/types/IStore.ts:279

Get entries (2D Array)

Returns ​

[keyof T, T[keyof T]][]

Inherited from ​

Omit.entries

filter ​

readonly filter: <AsArray>(...args) => AsArray extends true ? Map<keyof T, T[keyof T]> : T[keyof T][]

Defined in: store/src/types/IStore.ts:282

Filter items by predicate

Type Parameters ​

AsArray ​

AsArray extends boolean = false

Parameters ​

args ​

...[FilterPredicate<keyof T, T[keyof T]>, number, AsArray, Map<keyof T, T[keyof T]>]

Returns ​

AsArray extends true ? Map<keyof T, T[keyof T]> : T[keyof T][]

Inherited from ​

Omit.filter

find ​

readonly find: <IncludeKey>(predicateOrOptions) => IncludeKey extends true ? [keyof T, T[keyof T]] : T[keyof T] | undefined

Defined in: store/src/types/IStore.ts:287

Find an item by predicate or search criteria

Type Parameters ​

IncludeKey ​

IncludeKey extends boolean = false

Parameters ​

predicateOrOptions ​

FilterPredicate<keyof T, T[keyof T]> | FindOptions<keyof T, T[keyof T], IncludeKey>

Returns ​

IncludeKey extends true ? [keyof T, T[keyof T]] : T[keyof T] | undefined

Inherited from ​

Omit.find

has ​

readonly has: (key) => boolean

Defined in: store/src/types/IStore.ts:314

Check if key exists

Parameters ​

key ​

keyof T

Returns ​

boolean

Inherited from ​

Omit.has

init ​

readonly init: (initialValue?, silent?) => boolean

Defined in: store/src/types/IStore.ts:331

Initializes storage and sets up internal subscriptions.

Manual invocation is not typically necessary, as initialization occurs automatically in one of the following scenarios:

  • During construction, if an initialValue with at least one entry is provided.
  • On the first attempt to read or write data.

Parameters ​

initialValue? ​

Map<keyof T, T[keyof T]>

(optional) An optional map to initialize the storage with if it's currently empty.

silent? ​

boolean

(optional) Whether to throw error on failure.

Default: true

Returns ​

boolean

true if initialization was successful, or false if the storage was already initialized.

Inherited from ​

Omit.init

initialized ​

readonly initialized: boolean

Defined in: store/src/types/IStore.ts:105

Indicates wherether storage has been initialized (init() function invoked).

Inherited from ​

Omit.initialized

keys ​

readonly keys: () => keyof T[]

Defined in: store/src/types/IStore.ts:334

Get all keys

Returns ​

keyof T[]

Inherited from ​

Omit.keys

map ​

readonly map: <T>(callback) => T[]

Defined in: store/src/types/IStore.ts:337

Map each item on the data to an Array

Type Parameters ​

T ​

T = unknown

Parameters ​

callback ​

(value, key, entries, index) => T

Returns ​

T[]

Inherited from ​

Omit.map

name? ​

readonly optional name?: string | null

Defined in: store/src/types/IStore.ts:113

Storage name. Filename (NodeJS) or property name (browser LocalStorage). If empty string or undefined, data will not be saved to storage and will only work in-memory.

Default: null

Inherited from ​

Omit.name

onChange? ​

optional onChange?: (this, data) => ValueOrPromise<void | Map<keyof T, T[keyof T]>>

Defined in: store/src/types/IStore.ts:182

A callback function executed whenever a data change occurs within the storage.

This hook allows for reactive side-effects. If the callback throws an error or returns a rejected Promise, the exception is caught gracefully and redirected to the onError callback with the type Store_OnErrorType.onChange.

Note: Execution of this callback is managed by internal subscriptions and will stop firing once unsubscribe is called.

Parameters ​

this ​

IStore<keyof T, T[keyof T], CacheDisabled>

data ​

Map<keyof T, T[keyof T]>

Returns ​

ValueOrPromise<void | Map<keyof T, T[keyof T]>>

Inherited from ​

Omit.onChange

onError? ​

optional onError?: (this, err, type) => ValueOrPromise<void>

Defined in: store/src/types/IStore.ts:198

A global error handler invoked whenever an internal operation fails.

It captures failures in the following areas:

  • Data parsing and serialization (JSON or custom logic).
  • Storage access (e.g., localStorage quota or permission errors).
  • Execution of user-provided callbacks like onChange.

Note: If this handler itself throws an error, the exception is ignored gracefully to prevent application crashes during storage cycles.

Parameters ​

this ​

IStore<keyof T, T[keyof T], CacheDisabled>

err ​

unknown

type ​

Store_OnErrorType

Returns ​

ValueOrPromise<void>

Inherited from ​

Omit.onError

parse? ​

optional parse?: Store_Parse<TypedMap<T>, IObjectStore<T, CacheDisabled>>

Defined in: store/src/types/IObjectStore.ts:23

A callback to customize the deserialization of data read from storage.

This allows you to transform the raw string from the underlying storage back into a Map<Key, Value>. It serves as the functional inverse of stringify.

Fallback Behavior:

  • If this function is not defined, or returns undefined or a non-map value, the system falls back to internal JSON.parse logic.
  • If the function throws an error, it will use and empty map.

Error Triggers:

Overrides ​

Omit.parse

patch ​

patch: (data, silent?) => IObjectStore<T, CacheDisabled>

Defined in: store/src/types/IObjectStore.ts:26

Sugar for setAll() without replace

Parameters ​

data ​

Partial<T>

silent? ​

boolean

Returns ​

IObjectStore<T, CacheDisabled>

read ​

readonly read: (dataStr?, silent?) => Map<keyof T, T[keyof T]>

Defined in: store/src/types/IStore.ts:362

Reads and parses data directly from the persistent storage medium.

This operation is synchronous and does not trigger reactive updates via subject$. It is useful for debugging custom parse logic or manual data retrieval.

If instance.parse function is provided and invokation fails, an empty Map will be returned.

Parameters ​

dataStr? ​

string | null

(optional) A raw string to parse. If omitted, the method fetches the current value associated with the instance name from the underlying storage.

Default: null

silent? ​

boolean

(optional) Whether to throw error on failure.

Default: false

Returns ​

Map<keyof T, T[keyof T]>

Inherited from ​

Omit.read

readonly search: <MatchExact, AsMap>(...args) => AsMap extends true ? Map<keyof T, T[keyof T]> : T[keyof T][]

Defined in: store/src/types/IStore.ts:393

Search through the stored data (Map<Key, Value>). It supports both a global search (using a string or RegExp) across all properties of an item, and a detailed, field-specific search using a query object.

Type Parameters ​

MatchExact ​

MatchExact extends boolean = false

AsMap ​

AsMap extends boolean = true

Parameters ​

args ​

...[SearchOptions<keyof T, T[keyof T], MatchExact, AsMap>]

Returns ​

AsMap extends true ? Map<keyof T, T[keyof T]> : T[keyof T][]

A Map or an Array containing the matched items, based on the asMap option.

Example ​

Search for users in a specific city ​

javascript
import { Store } from '@superutils/store'

const storage = new Store('users', {
  initialValue: new Map([
    [1, { name: 'John Doe', city: 'New York' }],
    [2, { name: 'Jane Doe', city: 'London' }],
    [3, { name: 'Peter Jones', city: 'New York' }],
  ])
})

const nyUsers = storage.search({ query: { city: 'New York' } })
console.log(nyUsers.size) // 2

Inherited from ​

Omit.search

size ​

readonly size: number

Defined in: store/src/types/IStore.ts:116

Get the number of items

Inherited from ​

Omit.size

sort ​

readonly sort: Store_Sort<keyof T, T[keyof T]>

Defined in: store/src/types/IStore.ts:462

Sort items in the storage.

Param ​

nameOrComparator

Criteria to sort by. Accepts one of the following:

  • function: A comparator function to sort the data.
  • string: A property name of the value object to sort by.
  • true: Sorts the map by its keys.

Param ​

options

(optional) Sorting options.

Param ​

options.save

(optional) Whether to save the sorted data back to storage (localStorage/file).

Returns ​

The sorted Map.

Inherited from ​

Omit.sort

spaces? ​

optional spaces?: number

Defined in: store/src/types/IStore.ts:119

Number of spaces to use when stringifying. Default: undefined

Inherited from ​

Omit.spaces

storage? ​

readonly optional storage?: Storage | StorageCompact | null

Defined in: store/src/types/IStore.ts:139

LocalStorage or equivalent storage instance to be used as the underlying storage and to read & write from.

Notes:

  • Ignored when name is falsy (in-memory only mode)
  • For NodeJS or equivalent, an instance of LocalStorage from "node-localstoarge" NPM module can be used.
  • A custom storage that implements StorageCompact interface can also be used both in browser and NodeJS.

Fallback behavior:

  • undefined: will attempt to use globalThis.localStorage, if available
  • null, will defer storage check until initialization on first read/write or when init() invoked manually.
    • If storage is undefined or null will attempt to assign globalTihs.localStorage again
    • If storage is still falsy, will throw an error.

Default:

  • browser: localStorage
  • node: undefined (in-memory mode)

Inherited from ​

Omit.storage

stringify? ​

optional stringify?: Store_Stringify<TypedMap<T>, IObjectStore<T, CacheDisabled>>

Defined in: store/src/types/IObjectStore.ts:48

A callback function to customize the serialization of data before it is written to storage.

This allows you to transform the data Map<Key, Value> into a string format suitable for the underlying storage (e.g., JSON). It serves as the functional inverse of parse.

Use this to sanitize data, remove circular references, or optimize the storage size by only persisting necessary fields.

Fallback Behavior:

  • If this function is not defined, or returns undefined or a non-string value, the system falls back to internal JSON.stringify logic.
  • If the function throws an error, it will use and empty string.

Error Triggers:

Param ​

data

a map of all values stored in this storage

Returns ​

string or undefined

Example ​

Sanitize data before saving ​

javascript
import { Store } from '@superutils/store'

const stringify = (data) => {
  // Convert Map to an array of entries, removing sensitive fields
  const entries = Array.from(data).map(([id, user]) => { // eslint-disable-line @typescript-eslint/no-unused-vars
    const { password, ...publicData } = user
    return [id, publicData]
  })
  return JSON.stringify(entries)
}
const storage = new Store('users', { stringify })

Overrides ​

Omit.stringify

subject$ ​

readonly subject$: CacheDisabled extends true ? Subject<Map<keyof T, T[keyof T]>> : BehaviorSubject<Map<keyof T, T[keyof T]>>

Defined in: store/src/types/IStore.ts:162

The underlying RxJS subject that serves as the primary reactive interface for observing data modifications.

Its implementation type is determined by the caching strategy:

  • BehaviorSubject: Used when caching is enabled. It maintains the current state and emits it immediately to new subscribers.
  • Subject: Used when caching is disabled. It acts as a pure event pipe, emitting updates only at the moment they occur without retaining an in-memory copy.

Inherited from ​

Omit.subject$

toJSON ​

readonly toJSON: Store_ToJSON<keyof T, T[keyof T]>

Defined in: store/src/types/IStore.ts:465

Convert list of items (Map) to JSON string of 2D Array

Inherited from ​

Omit.toJSON

toString ​

readonly toString: (data?) => string

Defined in: store/src/types/IStore.ts:473

Convert list of items (Map) to JSON string of 2D Array

Parameters ​

data? ​

Map<keyof T, T[keyof T]>

Returns ​

string

Inherited from ​

Omit.toString

type ​

type: string

Defined in: store/src/types/IObjectStore.ts:17

Default: object

Overrides ​

Omit.type

unsubscribe ​

readonly unsubscribe: () => void

Defined in: store/src/types/IStore.ts:483

Unsubscribe from all internal subscriptions.

This will result in:

  • Automatic writing to storage being disabled (manual writes via instance.write() will still work).
  • The onChange callback no longer being triggered.
  • The instance stopping listening to force update cache triggers.

Returns ​

void

Inherited from ​

Omit.unsubscribe

validate? ​

optional validate?: Store_ValidatorFactory<IObjectStore<T, CacheDisabled>, IObjectStore_ValidatorParams<T>>

Defined in: store/src/types/IObjectStore.ts:64

A configuration object containing optional validation hooks for specific store operations.

See IStore.validate for more details.

For a list of actions that can be validated, see IObjectStore_ValidatorParams.

values ​

readonly values: () => T[keyof T][]

Defined in: store/src/types/IStore.ts:545

Get all values as an array

Returns ​

T[keyof T][]

Inherited from ​

Omit.values

write ​

readonly write: (data?, silent?) => boolean

Defined in: store/src/types/IStore.ts:558

Write data to the underlying storage (localStorage or file).

Parameters ​

data? ​

Map<keyof T, T[keyof T]>

(optional) Data to write.

  • If provided, it overwrites the storage.
  • If not provided, the current in-memory data is used (if cache is enabled).
silent? ​

boolean

(optional) Whether to throw error on failure. Default: true if delay

Returns ​

boolean

true if the write was successful, false otherwise.

Inherited from ​

Omit.write

Methods ​

get() ​

get<TKey>(key): T[keyof T] | undefined

Defined in: store/src/types/IObjectStore.ts:19

Get item by key

Type Parameters ​

TKey ​

TKey extends string | number | symbol

Parameters ​

key ​

TKey

Returns ​

T[keyof T] | undefined

Overrides ​

Omit.get

getAll() ​

getAll(forceRead?): TypedMap<T>

Defined in: store/src/types/IObjectStore.ts:21

Get all items

Parameters ​

forceRead? ​

boolean

Returns ​

TypedMap<T>

data map

Overrides ​

Omit.getAll

set() ​

set<TKey, Value>(key, value): IObjectStore<T, CacheDisabled>

Defined in: store/src/types/IObjectStore.ts:31

Set item by key

Type Parameters ​

TKey ​

TKey extends string | number | symbol

Value ​

Value

Parameters ​

key ​

TKey

value ​

Value | ((currentValue?) => Value)

value or function

Returns ​

IObjectStore<T, CacheDisabled>

Example ​

javascript
import { Store } from '@superutils/store'

const store = new Store<string, number>()
store.set('count', 1)
store.set('count', (prevCount = 0) => prevCount + 1)

Overrides ​

Omit.set

setAll() ​

setAll<Replace, Data>(data, replace?, silent?, validated?): IObjectStore<T, CacheDisabled>

Defined in: store/src/types/IObjectStore.ts:36

Set multiple entries at once and/or replace the storage entries

Type Parameters ​

Replace ​

Replace extends boolean = false

Data ​

Data extends object | Partial<T> = Replace extends true ? T : Partial<T>

Parameters ​

data ​

Data | TypedMap<Data>

(optional) Data to add. Default: new Map()

replace? ​

Replace

(optional) Whether to merge with or replace current data.

  • true: replace all entries with data
  • false: merge with current data (existing entries with matching keys will be overwritten)

Default: false

silent? ​

boolean

(optional) Whether to throw error on failure.

Default: true

validated? ​

boolean

Returns ​

IObjectStore<T, CacheDisabled>

store instance

Overrides ​

Omit.setAll

toMap() ​

toMap<Data>(data?): TypedMap<Data>

Defined in: store/src/types/IObjectStore.ts:51

Convert data/object to typed map

Type Parameters ​

Data ​

Data extends object = T

Parameters ​

data? ​

Data

Returns ​

TypedMap<Data>

toObject() ​

toObject<O>(data?): O

Defined in: store/src/types/IObjectStore.ts:53

Convert list of items into an object

Type Parameters ​

O ​

O extends object = T

Parameters ​

data? ​

Map<keyof T, T[keyof T]> | TypedMap<T>

Returns ​

O

Overrides ​

Omit.toObject