type-safe-web-storage v0.0.12

type-safe-web-storage

A minimal and light-weight package to acces web storages in a type safe way. You will need to provide a zod schema that will be used to parse the data from the local/session storage. With this approach an error is raised if the data does not match the desired type (it may happen if the user manually edit the data in the storages).

Installation

npm install zod type-safe-web-storage
// or
yarn add zod type-safe-web-storage

Usage

import { z } from "zod";
import { initStorageState } from "type-safe-web-storage";

const state = initStorageState({
  type: "local", //Determine if local or session storage
  key: "peson", //The key for the chosen storage
  //You zod schema, that will determine the type of the state
  schema: z.object({
    name: z.string(),
    surname: z.string().optional(),
    dog: z.object({
      name: z.string(),
      age: z.number().nullable(),
    }),
    friends: z.array(z.string()),
  }),
  //Additional, non required option, useful to control error handling
  options: {
    resetStateOnParsingError: true, //Default: false
    throwParsingError: false, //Default: true
  },
});

/**
 * const stateSnapshot: {
 *     name: string;
 *     dog: {
 *         name: string;
 *         age: number | null;
 *     };
 *     friends: string[];
 *     surname?: string | undefined;
 * } | null
 */
const stateSnapshot = state.getStorageState();

/**
 * setStorageState: (value: {
 *     name: string;
 *     dog: {
 *         name: string;
 *         age: number | null;
 *     };
 *     friends: string[];
 *     surname?: string | undefined;
 * }) => void
 */
state.setStorageState({
  name: "Riccardo",
  dog: {
    name: "Pascal",
    age: 10,
  },
  friends: ["Marco", "Davide"],
});

/**
 * Remove value from the storage
 */
state.setStorageState(null);

When the storage state is set a StorageEvent is dispatched. This can be useful to sync the state in the same or different browser tabs.

const handleStorageChange = (e: StorageEvent) => {
  //handle only relevant events
  if (e.key !== "person" || e.storageArea !== window.localStorage) return;

  console.log(e.newValue); //Log stringified state
};
window.addEventListener("storage", handleStorageChange);