Superutils

Appearance

Interface: IDataStorage<Key, Value, CacheDisabled> ​

Defined in: packages/rx/src/data-storage/types.ts:129

Type Parameters ​

Key ​

Key extends StorageKey

Value ​

Value extends StorageValue

CacheDisabled ​

CacheDisabled extends boolean = false

Properties ​

cacheDisabled ​

readonly cacheDisabled: CacheDisabled

Defined in: packages/rx/src/data-storage/types.ts:135

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

clear() ​

readonly clear: () => IDataStorage<Key, Value, CacheDisabled>

Defined in: packages/rx/src/data-storage/types.ts:197

Clear all items

Returns ​

IDataStorage<Key, Value, CacheDisabled>

delay ​

readonly delay: number

Defined in: packages/rx/src/data-storage/types.ts:145

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

delayOptions? ​

readonly optional delayOptions: DelayOptions

Defined in: packages/rx/src/data-storage/types.ts:147

delete() ​

readonly delete: (key) => IDataStorage<Key, Value, CacheDisabled>

Defined in: packages/rx/src/data-storage/types.ts:200

Delete one or more items by their respective keys

Parameters ​

key ​

Key | Key[]

Returns ​

IDataStorage<Key, Value, CacheDisabled>

filter ​

readonly filter: StorageFilter<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:208

Filter items by predicate

find ​

readonly find: StorageFind<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:205

Find an item by predicate or search criteria

get() ​

readonly get: (key) => Value | undefined

Defined in: packages/rx/src/data-storage/types.ts:211

Get item by key

Parameters ​

key ​

Key

Returns ​

Value | undefined

getAll() ​

readonly getAll: (forceUpdate) => Map<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:218

Get all items

Parameters ​

forceUpdate ​

boolean

(optional) if true and cache is enabled, reads & updates data directly from storage

Returns ​

Map<Key, Value>

has() ​

readonly has: (key) => boolean

Defined in: packages/rx/src/data-storage/types.ts:221

Check if key exists

Parameters ​

key ​

Key

Returns ​

boolean

init() ​

readonly init: (initialValue?) => boolean

Defined in: packages/rx/src/data-storage/types.ts:234

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<Key, Value>

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

Returns ​

boolean

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

initialized ​

readonly initialized: boolean

Defined in: packages/rx/src/data-storage/types.ts:152

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

keys() ​

readonly keys: () => Key[]

Defined in: packages/rx/src/data-storage/types.ts:237

Get all keys

Returns ​

Key[]

map ​

readonly map: StorageMap<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:240

Map each item on the data to an Array

name? ​

readonly optional name: string

Defined in: packages/rx/src/data-storage/types.ts:160

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: ''

onChange? ​

optional onChange: StorageOnChangeFn<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:247

Callback to be invoked whenever value change is triggered.

If onChange invocation fails, it will be ignored gracefully.

onError? ​

optional onError: StorageOnErrorFn

Defined in: packages/rx/src/data-storage/types.ts:254

Callback to be invoked whenever read/write operation fails.

If onError invocation failure will be ignored gracefully.

parse? ​

readonly optional parse: StorageParseFn<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:263

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

This can be used to override the default JSON.parse behavior and serves as the counterpart to stringify. If this function is not provided, throws an error, or returns undefined, the default JSON.parse will be used as a fallback.

read() ​

readonly read: () => Map<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:266

Read directly from the localStorage (browser) or file (NodeJS) without triggering the this.subject.

Returns ​

Map<Key, Value>

readonly search: StorageSearch<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:269

Search items

set() ​

readonly set: (key, value) => IDataStorage<Key, Value, CacheDisabled>

Defined in: packages/rx/src/data-storage/types.ts:272

Set item by key

Parameters ​

key ​

Key

value ​

Value

Returns ​

IDataStorage<Key, Value, CacheDisabled>

setAll() ​

readonly setAll: (data?, replace?) => IDataStorage<Key, Value, CacheDisabled>

Defined in: packages/rx/src/data-storage/types.ts:287

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

Parameters ​

data? ​

Map<Key, Value>

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

replace? ​

boolean

(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

Returns ​

IDataStorage<Key, Value, CacheDisabled>

size ​

readonly size: number

Defined in: packages/rx/src/data-storage/types.ts:163

Get the number of items

sort ​

readonly sort: StorageSort<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:304

Sort items in the storage.

Param ​

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 ​

(optional) Sorting options.

Param ​

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

Returns ​

The sorted Map.

spaces? ​

optional spaces: number

Defined in: packages/rx/src/data-storage/types.ts:166

Number of spaces to use when stringifying. Default: undefined

storage? ​

readonly optional storage: StorageCompact | null

Defined in: packages/rx/src/data-storage/types.ts:181

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.
  • If undefined, will not attempt to use globalThis.localStorage, if available
  • If null, will not attempt to use globalThis.localStorage

Default:

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

stringify? ​

readonly optional stringify: StorageStringifyFn<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:335

Callback function to customize the serialization of data to be stored to storage.

Useful when data needs to be sanitised before storing and/or remove circlar references.

Example ​

javascript
import fetch from '@superutils/fetch'
import { DataStorage } from '@superutils/rx'
import { LocalStorage } from 'node-localstorage'

// Create a localStorage alternative for NodeJS that reads and writes to JSON files.
// This is not necessary for browsers
globalThis.localStorage = new LocalStorage('./data', 1e7)

const storage = new DataStorage('products.json')
storage.stringify = data => Array
	.from(data)
 .map(([key, product]) => [
   key,
   { id: product.id, title: product.title } // only store what's needed
 ])

const { products } = await fetch('[DUMMYJSON-DOT-COM]/products)
const productsMap = result.products.map(p => [p.id, p])
storage.setAll(productsMap, true)
console.log(storage.getAll())

subject ​

readonly subject: CacheDisabled extends true ? Subject<Map<Key, Value>> : BehaviorSubject<Map<Key, Value>>

Defined in: packages/rx/src/data-storage/types.ts:192

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.

toArray() ​

readonly toArray: () => [Key, Value][]

Defined in: packages/rx/src/data-storage/types.ts:338

Convert list of items (Map) to 2D Array

Returns ​

[Key, Value][]

toJSON ​

readonly toJSON: StorageToJSON<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:341

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

toObject() ​

readonly toObject: () => Record<Key, Value>

Defined in: packages/rx/src/data-storage/types.ts:344

Convert list of items into an object

Returns ​

Record<Key, Value>

toString() ​

readonly toString: () => string

Defined in: packages/rx/src/data-storage/types.ts:347

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

Returns ​

string

unsubscribe() ​

readonly unsubscribe: () => void

Defined in: packages/rx/src/data-storage/types.ts:357

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

values() ​

readonly values: () => Value[]

Defined in: packages/rx/src/data-storage/types.ts:360

Get all values as an array

Returns ​

Value[]

write() ​

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

Defined in: packages/rx/src/data-storage/types.ts:375

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

Parameters ​

data? ​

Map<Key, Value>

(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 suppress errors if the write operation fails.

  • true: Returns false on failure without throwing.
  • false: Throws an error on failure.

Default: this.silent

Returns ​

void

true if the write was successful, false otherwise.