@sovgut/state

Type-safe, synchronous state management for the browser with a unified API over localStorage, sessionStorage, cookies, and in-memory storage. Each backend exposes the same interface and an isolated observer for change notifications.

Contents

• Installation
• Overview
• Storage backends
• Reading and writing values
• Type casting
• Observing changes
• React integration
• API reference
• Error handling
• License

Installation

npm install @sovgut/state

yarn add @sovgut/state

pnpm add @sovgut/state

The package ships as ES modules with bundled type declarations and has no runtime dependencies.

Overview

import { LocalState } from "@sovgut/state";

LocalState.set("user", { id: 1, name: "Alice" });

const user = LocalState.get("user");

LocalState.on("user", (value) => {
  console.log("user changed:", value);
});

LocalState, SessionState, MemoryState, and CookieState are static classes. There is nothing to instantiate; import a backend and call its methods directly.

Storage backends

All backends share the same core interface. They differ in where data is stored and how long it survives.

| Backend | Storage | Lifetime | | -------------- | ------------------- | ------------------------------------- | | LocalState | localStorage | Persists across browser sessions | | SessionState | sessionStorage | Cleared when the tab is closed | | MemoryState | In-memory Map | Cleared on page reload | | CookieState | document.cookie | Configurable via cookie attributes |

LocalState

import { LocalState } from "@sovgut/state";

LocalState.set("theme", "dark");
const theme = LocalState.get("theme"); // "dark"

SessionState

import { SessionState } from "@sovgut/state";

SessionState.set("draft", { subject: "", body: "" });
const draft = SessionState.get("draft");

MemoryState

Values are stored by reference without a JSON roundtrip, so Date, Map, Set, and class instances survive a get/set cycle unchanged. Stored objects are not defensively copied.

import { MemoryState } from "@sovgut/state";

MemoryState.set("cache", new Map([["key", "value"]]));
const cache = MemoryState.get<Map<string, string>>("cache");

CookieState

set accepts standard cookie attributes. path defaults to / and sameSite defaults to lax. When sameSite is none, secure is enabled automatically.

import { CookieState } from "@sovgut/state";

CookieState.set("sessionId", "abc123", {
  expires: 7,        // days from now, or a Date
  secure: true,
  sameSite: "strict",
});

Cookies set with a custom path or domain must be removed with the same values, because browsers require an exact match to delete a cookie:

CookieState.set("token", value, { path: "/admin" });
CookieState.remove("token", { path: "/admin" });

Reading and writing values

Writing

Values written to LocalState, SessionState, and CookieState are JSON-serialized. A value that cannot be serialized — undefined, a function, a symbol, or a circular reference — causes set to throw.

LocalState.set("count", 42);
LocalState.set("name", "Alice");
LocalState.set("isActive", true);
LocalState.set("tags", ["typescript", "state"]);
LocalState.set("settings", {
  theme: "dark",
  notifications: { email: true, push: false },
});

Reading

get returns the stored value, or undefined when the key is absent.

const count = LocalState.get("count");        // 42
const missing = LocalState.get("nonexistent"); // undefined

Provide a fallback to return a default when the key is absent or holds an empty value. The fallback also drives the inferred return type.

const theme = LocalState.get("theme", { fallback: "light" }); // string
const score = LocalState.get("score", { fallback: 0 });       // number
const tags = LocalState.get("tags", { fallback: [] as string[] }); // string[]

Use strict to throw StateDoesNotExist when the key is absent.

try {
  const token = LocalState.get("token", { strict: true });
} catch (error) {
  // key was not present
}

Removing and checking

LocalState.remove("user");   // remove one key
LocalState.clear();          // remove all keys for this backend
LocalState.has("user");      // boolean

Type casting

Provide a cast option to coerce a stored value to a primitive type. Supported targets are "string", "number", "boolean", and "bigint".

LocalState.set("value", "42");

LocalState.get("value", { cast: "string" });  // "42"
LocalState.get("value", { cast: "number" });  // 42
LocalState.get("value", { cast: "boolean" }); // true
LocalState.get("value", { cast: "bigint" });  // 42n

An impossible cast — for example "abc" to number — returns the fallback when one is provided, or throws StateInvalidCast when strict is set. Boolean casting treats "false", "0", and "" as false.

A generic parameter can be supplied to type the return value directly:

interface User {
  id: number;
  name: string;
}

const user = LocalState.get<User>("currentUser");
const required = LocalState.get<User>("currentUser", { strict: true });

Observing changes

Each backend maintains its own listener registry, so LocalState listeners do not fire on SessionState events. Listeners receive the new value, or null when a key is removed or cleared.

const handler = (value) => console.log("changed:", value);

LocalState.on("user", handler);   // subscribe
LocalState.once("user", handler); // fire at most once
LocalState.off("user", handler);  // unsubscribe

Note: storing an explicit null via set emits null as well, so a listener cannot distinguish "set to null" from "removed" by the payload alone.

Additional inspection and cleanup methods are available:

LocalState.listenerCount("user");   // number of listeners for a key
LocalState.eventNames();            // keys with at least one listener
LocalState.removeListener("user");  // remove all listeners for one key
LocalState.removeAllListeners();    // remove every listener on the backend

A listener that throws is isolated: the error is logged and other listeners still run.

React integration

The library is framework-agnostic. A minimal hook that keeps component state synchronized with a backend:

import { useCallback, useEffect, useState } from "react";
import { LocalState, type IStorageEventData } from "@sovgut/state";

function useLocalState<T>(key: string, initialValue: T) {
  const [value, setValue] = useState<T>(() =>
    LocalState.get(key, { fallback: initialValue }),
  );

  useEffect(() => {
    const handler = (event: IStorageEventData<T>) => {
      setValue(event ?? initialValue);
    };

    LocalState.on(key, handler);
    return () => LocalState.off(key, handler);
  }, [key, initialValue]);

  const update = useCallback(
    (next: T) => LocalState.set(key, next),
    [key],
  );

  return [value, update] as const;
}

function ThemeToggle() {
  const [theme, setTheme] = useLocalState("theme", "light");

  return (
    <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
      {theme}
    </button>
  );
}

API reference

The methods below are shared by all four backends unless noted otherwise.

get<T>(key, options?): T | undefined

Retrieves a value from storage.

| Option | Type | Description | | ---------- | --------------------------------------------- | ---------------------------------------------------- | | fallback | T | Returned when the key is absent or holds an empty value. | | strict | boolean | Throw StateDoesNotExist when the key is absent. | | cast | "string" \| "number" \| "boolean" \| "bigint" | Coerce the stored value to a primitive type. |

set<T>(key, value): void

Stores a value. Throws when the value cannot be serialized or the backend rejects the write. CookieState.set(key, value, options?) additionally accepts cookie attributes:

| Option | Type | Description | | ---------- | -------------------------------- | ------------------------------------------------------- | | expires | Date \| number | Expiration date, or number of days from now. | | maxAge | number | Maximum age in seconds. Takes precedence over expires.| | domain | string | Domain the cookie is scoped to. | | path | string | Path the cookie is scoped to. Defaults to /. | | secure | boolean | Send only over HTTPS. Required when sameSite is none. | | sameSite | "strict" \| "lax" \| "none" | SameSite policy. Defaults to lax. |

remove(key): void

Removes a value. CookieState.remove(key, options?) accepts path and domain, which must match the values used when the cookie was set.

clear(): void

Removes every value for the backend and emits null for each removed key.

has(key): boolean

Returns whether a key exists.

Observer methods

| Method | Description | | ----------------------------- | ------------------------------------------------ | | on(event, callback) | Add a listener. | | once(event, callback) | Add a listener that fires at most once. | | off(event, callback) | Remove a specific listener. | | removeListener(event) | Remove all listeners for one key. | | removeAllListeners() | Remove every listener on the backend. | | listenerCount(event) | Number of listeners registered for a key. | | eventNames() | Keys that have at least one listener. |

Error handling

Both error types carry structured fields for programmatic handling.

import { StateDoesNotExist, StateInvalidCast } from "@sovgut/state";

try {
  LocalState.get("token", { strict: true });
} catch (error) {
  if (error instanceof StateDoesNotExist) {
    console.error(`"${error.key}" not found in ${error.storage}`);
  }
}

try {
  LocalState.set("value", "not-a-number");
  LocalState.get("value", { cast: "number", strict: true });
} catch (error) {
  if (error instanceof StateInvalidCast) {
    console.error(
      `cannot cast "${error.value}" to ${error.type} for "${error.key}"`,
    );
  }
}

License

Released under the MIT License.