Registry / web-framework / alveron-middleware-persistence

alveron-middleware-persistence

library8.0.3jsnpmunverified

Alveron Middleware Persistence is a specialized middleware designed to integrate a state persistence layer into Alveron applications. Alveron is a lightweight, Elm-inspired state management library for React (approx. 1.2kb) that leverages React's `useState` hook and handles asynchronous side effects. This middleware enables Alveron stores to automatically persist their state to browser storage mechanisms like `localStorage` or `sessionStorage`, ensuring that application data endures across page reloads or browser sessions. The current stable version, 8.0.3, is designed to work seamlessly with Alveron versions greater than 8.0.0. While a specific release cadence for this middleware is not publicly documented, its versioning typically aligns with major releases of the core `alveron` library. Its primary differentiator is its direct compatibility and integration within the Alveron ecosystem, providing a structured approach to state hydration and rehydration tailored for Alveron's model, actions, and effects architecture.

web-framework database

npm install alveron-middleware-persistence

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ALVERON-MIDDLEWARE

alveron-middleware-persistence

web-frameworkjavascriptv8.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

persistenceMiddleware

✓ import persistenceMiddleware from 'alveron-middleware-persistence';

✗ const persistenceMiddleware = require('alveron-middleware-persistence');

The library primarily uses ESM exports. Use named imports if specific utility functions are also exported.

PersistenceConfig

✓ import persistenceMiddleware, { PersistenceConfig } from 'alveron-middleware-persistence';

Type import for configuring the middleware (if exported, otherwise define inline).

This example demonstrates how to integrate `alveron-middleware-persistence` with an Alveron store to persist and rehydrate a simple counter's state using `localStorage`. It shows the basic setup of an Alveron store with actions and how to apply the configured persistence middleware.

import * as React from 'react'; import { useStoreWithMiddleware, Middleware } from 'alveron'; import persistenceMiddleware from 'alveron-middleware-persistence'; interface Model { count: number; lastUpdate: string; } interface Actions { increment: (amount?: number) => Model; decrement: (amount?: number) => Model; } const initialModel: Model = { count: 0, lastUpdate: new Date().toISOString(), }; const actions = { increment: (amount: number = 1) => (prevState: Model) => [ { ...prevState, count: prevState.count + amount, lastUpdate: new Date().toISOString() }, ], decrement: (amount: number = 1) => (prevState: Model) => [ { ...prevState, count: prevState.count - amount, lastUpdate: new Date().toISOString() }, ], }; // Define persistence configuration const persistenceConfig = { key: 'my-alveron-app-state', // Unique key for localStorage storage: localStorage, // or sessionStorage // Optional: only persist `count`, not `lastUpdate` partialize: (state: Model) => ({ count: state.count }), }; const persistedCounterMiddleware: Middleware<Model, Actions> = persistenceMiddleware(persistenceConfig); function Counter() { const [state, { increment, decrement }] = useStoreWithMiddleware( actions, initialModel, [persistedCounterMiddleware] ); return ( <div> <h1>Count: {state.count}</h1> <p>Last updated: {new Date(state.lastUpdate).toLocaleTimeString()}</p> <button onClick={() => increment()}>Increment</button> <button onClick={() => decrement()}>Decrement</button> <button onClick={() => localStorage.clear()}>Clear Storage</button> <p>Refresh the page to see the count persist!</p> </div> ); } function App() { return ( <React.StrictMode> <Counter /> </React.StrictMode> ); } export default App;

Debug

Known issues

breakingMajor version updates (e.g., from v7 to v8) typically introduce breaking changes, often related to underlying Alveron API changes or persistence configuration format. Consult Alveron's changelog and this middleware's documentation for migration steps.

fix

Review the official Alveron and alveron-middleware-persistence documentation for migration guides and updated API usage when upgrading major versions.

affects: >=8.0.0

gotchaChanges to the shape of your persisted state (e.g., adding/removing properties, changing data types) can lead to hydration errors or unexpected behavior if old, incompatible data exists in `localStorage` or `sessionStorage`. Users' browsers might hold stale data from previous versions of your application.

fix

Implement a versioning strategy within your persistence configuration (if supported by the library) and provide migration functions. For development, manually clear browser storage (`localStorage.clear()`) after schema changes. For production, consider user-data migration strategies or default fallbacks for undefined properties.

affects: >=1.0.0

gotchaThis middleware is designed for browser environments using `localStorage` or `sessionStorage`. Attempting to use it directly in a Node.js environment (e.g., for Server-Side Rendering) without appropriate polyfills for these browser APIs will result in runtime errors.

fix

Ensure the middleware is only executed in browser contexts, or provide global polyfills for `localStorage` and `sessionStorage` (e.g., using `node-localstorage` or a mock) for SSR or Node.js testing environments.

affects: >=1.0.0

Errors

Common errors & fixes

Uncaught TypeError: Cannot read properties of undefined (reading 'getItem')

Attempting to use the middleware in a Node.js environment (e.g., SSR) where `localStorage` or `sessionStorage` are not defined.

fix

Wrap your Alveron store initialization with a check for `typeof window !== 'undefined'` or provide `localStorage` / `sessionStorage` polyfills for Node.js environments.

TypeError: (0 , _alveron_middleware_persistence__WEBPACK_IMPORTED_MODULE_1__.default) is not a function

Incorrect CommonJS `require()` usage for an ESM-first package or incorrect named vs default import syntax in an ESM context.

fix

For ESM, use `import persistenceMiddleware from 'alveron-middleware-persistence';`. For CommonJS (if supported), ensure correct interop or use a bundler that handles ESM imports correctly.

Error: Alveron: useStoreWithMiddleware expects the 'alveron' library to be installed. Please ensure it's in your dependencies.

The peer dependency `alveron` is missing or an incompatible version is installed.

fix

Install or upgrade Alveron: `npm install alveron@'>8.0.0'` or `yarn add alveron@'>8.0.0'`.

Upgrade

Version history

8.0.3latest on npm

Audit

Dependencies

alveronrequiredRequired as a peer dependency for Alveron state management functionality.

Agent activity

25 hits · last 30 days

node

Anthropic

OpenAI (training)

Resources

githubhttps://github.com/robinweser/alveron ↗

packagehttps://www.npmjs.com/package/alveron-middleware-persistence ↗

homepagehttps://alveron.js.org ↗