API Reference#

⚠️ Important Version Notice#

v0.0.3 Breaking Changes#

v0.0.3 introduces major changes including:

1. Framework-specific entry points: Now requires importing from specific framework entry points
2. Unified API: All frameworks use the useStorage function name
3. Zero external dependencies: Framework dependencies are treated as external

Migration Guide#

Old version (v0.0.1-beta.8 and earlier):

1import { useStorage } from 'ew-responsive-store';
2import { useReactStorage } from 'ew-responsive-store';

New version (v0.0.3+):

1// Vue
2import { useStorage } from 'ew-responsive-store/vue';
3
4// React
5import { useStorage } from 'ew-responsive-store/react';
6
7// Other frameworks...

v0.0.3+ Multi-Framework Support#

useStorage (Vue) - v0.0.3+#

The useStorage function is the core API of the ew-responsive-store library. It allows you to create reactive state that is synchronized with browser storage (localStorage or sessionStorage).

Type Definition#

1function useStorage<T>(
2  key: string,
3  initialValue: T,
4  options: StoreOptions = {
5    storage: StoreType.LOCAL,
6    immediate: true,
7    deep: true,
8  }
9): Ref<T>;

Parameters#

Options#

The options parameter accepts the following properties:

Additionally, all Vue watch options are supported, as StoreOptions extends WatchOptions from Vue.

Returns#

A reactive Ref<T> that is synchronized with the specified storage.

Example#

1import { useStorage } from "ew-responsive-store/vue";
2import { StoreType } from "ew-responsive-store";
3
4// Basic usage with localStorage
5const count = useStorage("count", 0);
6
7// Using sessionStorage
8const user = useStorage(
9  "user",
10  { name: "John" },
11  { storage: StoreType.SESSION }
12);
13
14// Disabling deep watching
15const list = useStorage("list", [1, 2, 3], { deep: false });
16
17// Disabling immediate effect
18const settings = useStorage(
19  "settings",
20  { theme: "dark" },
21  { immediate: false }
22);

useStorage (React) - v0.0.3+#

React version of the useStorage function, providing a React-native experience.

Type Definition#

1function useStorage<T>(
2  key: string,
3  initialValue: T,
4  options: ReactStoreOptions = {
5    storage: StoreType.LOCAL,
6  }
7): readonly [T, (newValue: T) => void];

Parameters#

Options#

The options parameter accepts the following properties:

Returns#

A tuple containing:

• [0]: The current value of type T
• [1]: A setter function to update the value

Example#

1import React from 'react';
2import { useStorage, StoreType } from "ew-responsive-store/react";
3
4function Counter() {
5  // Basic usage with localStorage
6  const [count, setCount] = useStorage("count", 0);
7  
8  // Using sessionStorage
9  const [user, setUser] = useStorage(
10    "user",
11    { name: "John", age: 25 },
12    { storage: StoreType.SESSION }
13  );
14
15  const increment = () => setCount(count + 1);
16
17  return (
18    <div>
19      <p>Count: {count}</p>
20      <button onClick={increment}>Increment</button>
21      
22      <p>User: {user.name} ({user.age})</p>
23      <button onClick={() => setUser({ ...user, age: user.age + 1 })}>
24        Increase Age
25      </button>
26    </div>
27  );
28}

useStorage (Preact) - v0.0.3+#

Preact version of the useStorage function, same API as React but optimized for Preact.

1import { useStorage } from "ew-responsive-store/preact";
2
3function Counter() {
4  const [count, setCount] = useStorage("count", 0);
5  return <div>Count: {count}</div>;
6}

useStorage (Solid) - v0.0.3+#

Solid version of the useStorage function, returns Solid signals.

1import { useStorage } from "ew-responsive-store/solid";
2
3function Counter() {
4  const [count, setCount] = useStorage("count", 0);
5  return <div>Count: {count()}</div>;
6}

useStorage (Svelte) - v0.0.3+#

Svelte version of the useStorage function, returns Svelte store.

1<script>
2  import { useStorage } from "ew-responsive-store/svelte";
3  
4  const store = useStorage("count", 0);
5  let count = $store;
6</script>
7
8<div>Count: {count}</div>

useStorage (Angular) - v0.0.3+#

Angular version of the useStorage function, returns Angular signals.

1import { Component } from '@angular/core';
2import { useStorage } from "ew-responsive-store/angular";
3
4@Component({
5  template: `<div>Count: {{ count() }}</div>`
6})
7export class CounterComponent {
8  private storage = useStorage("count", 0);
9  count = this.storage.value;
10}

useStorage (Vanilla JS) - v0.0.3+#

Vanilla JavaScript version of the useStorage function, returns a storage manager object.

1import { useStorage } from "ew-responsive-store/vanilla";
2
3const storage = useStorage("count", 0);
4
5// Get current value
6console.log(storage.value); // 0
7
8// Update value
9storage.setValue(1);
10console.log(storage.value); // 1
11
12// Subscribe to changes
13storage.subscribe((newValue) => {
14  console.log("Value changed:", newValue);
15});

Legacy API (v0.0.1-beta.8 and earlier)#

useStorage (Vue) - v0.0.1-beta.8#

The useStorage function is the core API of the ew-responsive-store library. It allows you to create reactive state that is synchronized with browser storage (localStorage or sessionStorage).

Type Definition#

1function useStorage<T>(
2  key: string,
3  initialValue: T,
4  options: StoreOptions = {
5    storage: StoreType.LOCAL,
6    immediate: true,
7    deep: true,
8  }
9): Ref<T>;

Parameters#

Options#

The options parameter accepts the following properties:

Additionally, all Vue watch options are supported, as StoreOptions extends WatchOptions from Vue.

Returns#

A reactive Ref<T> that is synchronized with the specified storage.

Example#

1import { useStorage } from "ew-responsive-store";
2import { StoreType } from "ew-responsive-store/typings/core/enum";
3
4// Basic usage with localStorage
5const count = useStorage("count", 0);
6
7// Using sessionStorage
8const user = useStorage(
9  "user",
10  { name: "John" },
11  { storage: StoreType.SESSION }
12);
13
14// Disabling deep watching
15const list = useStorage("list", [1, 2, 3], { deep: false });
16
17// Disabling immediate effect
18const settings = useStorage(
19  "settings",
20  { theme: "dark" },
21  { immediate: false }
22);

useReactStorage (React) - v0.0.1-beta.7#

The useReactStorage function is designed specifically for React applications. It provides a React-native way to manage state that is synchronized with browser storage.

Type Definition#

1function useReactStorage<T>(
2  key: string,
3  initialValue: T,
4  options: ReactStoreOptions = {
5    storage: StoreType.LOCAL,
6  }
7): readonly [T, (newValue: T) => void];

Parameters#

Options#

The options parameter accepts the following properties:

Returns#

A tuple containing:

• [0]: The current value of type T
• [1]: A setter function to update the value

Example#

1import React from 'react';
2import { useReactStorage, StoreType } from "ew-responsive-store";
3
4function Counter() {
5  // Basic usage with localStorage
6  const [count, setCount] = useReactStorage("count", 0);
7  
8  // Using sessionStorage
9  const [user, setUser] = useReactStorage(
10    "user",
11    { name: "John", age: 25 },
12    { storage: StoreType.SESSION }
13  );
14
15  // Complex data types
16  const [todos, setTodos] = useReactStorage("todos", [
17    { id: 1, text: "Learn React", completed: false },
18    { id: 2, text: "Learn TypeScript", completed: true }
19  ]);
20
21  const increment = () => setCount(count + 1);
22  const addTodo = (text: string) => {
23    setTodos([...todos, { 
24      id: Date.now(), 
25      text, 
26      completed: false 
27    }]);
28  };
29
30  return (
31    <div>
32      <p>Count: {count}</p>
33      <button onClick={increment}>Increment</button>
34      
35      <p>User: {user.name} ({user.age})</p>
36      <button onClick={() => setUser({ ...user, age: user.age + 1 })}>
37        Increase Age
38      </button>
39      
40      <div>
41        <h3>Todos:</h3>
42        {todos.map(todo => (
43          <div key={todo.id}>
44            <span style={{ textDecoration: todo.completed ? 'line-through' : 'none' }}>
45              {todo.text}
46            </span>
47          </div>
48        ))}
49      </div>
50    </div>
51  );
52}

Cross-tab Synchronization#

useReactStorage automatically synchronizes data across browser tabs using the storage event:

1import { useReactStorage } from "ew-responsive-store";
2
3function App() {
4  const [theme, setTheme] = useReactStorage("theme", "light");
5  
6  // This will automatically update in other tabs when changed
7  const toggleTheme = () => {
8    setTheme(theme === "light" ? "dark" : "light");
9  };
10
11  return (
12    <div className={`app ${theme}`}>
13      <button onClick={toggleTheme}>
14        Switch to {theme === "light" ? "dark" : "light"} theme
15      </button>
16    </div>
17  );
18}

Error Handling#

The hook will throw an error if storage is not available:

1import { useReactStorage } from "ew-responsive-store";
2
3function SafeStorage() {
4  try {
5    const [data, setData] = useReactStorage("data", {});
6    return <div>Storage is available</div>;
7  } catch (error) {
8    return <div>Storage is not available: {error.message}</div>;
9  }
10}

parseStr#

The parseStr function is a utility for parsing string values. It provides two parsing modes: EVAL and JSON.

Type Definition#

1function parseStr<T>(
2  str: string,
3  type: parseStrType = parseStrType.JSON
4): T | null;

Parameters#

Returns#

The parsed value of type T, or null if parsing fails.

Example#

1import { parseStr, ParseStrType } from "ew-responsive-store";
2
3// Parse JSON
4const data = parseStr<{ name: string }>('{ "name": "John" }');
5// Result: { name: 'John' }
6
7// Execute JavaScript code
8const result = parseStr<number>("1 + 2", ParseStrType.EVAL);
9// Result: 3

Utility Functions#

isValidJSON#

Checks if a string is valid JSON.

1function isValidJSON(val: string): boolean;

isStorageEnabled#

Checks if a storage type is enabled in the current environment.

1function isStorageEnabled(storage: Storage): boolean;

Enums#

StoreType#

Defines the available storage types.

1enum StoreType {
2  LOCAL = "localStorage",
3  SESSION = "sessionStorage",
4}

parseStrType#

Defines the available parsing methods for parseStr.

1enum parseStrType {
2  EVAL = "eval",
3  JSON = "json",
4}