reactish-state 1.2.1-alpha.2 → 2.0.0-alpha.0

package/README.md

@@ -2,22 +2,23 @@
 
 > Simple, decentralized (atomic) state management for React.
 
-[![NPM](https://img.shields.io/npm/v/reactish-state.svg)](https://www.npmjs.com/package/reactish-state) [![NPM](https://img.shields.io/bundlephobia/minzip/reactish-state)](https://bundlephobia.com/package/reactish-state) [![bundlejs](https://img.shields.io/badge/bundlejs-.com-blue.svg)](https://bundlejs.com/?q=reactish-state&treeshake=%5B*%5D&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%5D%7D%7D)
+[![NPM](https://img.shields.io/npm/v/reactish-state.svg)](https://www.npmjs.com/package/reactish-state) [![bundlejs](https://deno.bundlejs.com/?q=reactish-state&treeshake=%5B*%5D&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%5D%7D%7D&badge=simple)](https://bundlejs.com/?q=reactish-state&treeshake=%5B*%5D&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%5D%7D%7D) [![NPM](https://img.shields.io/bundlephobia/minzip/reactish-state)](https://bundlephobia.com/package/reactish-state)
 
 💡 [Quick examples](#examples)    🔧 [TypeScript usage](#typescript-usage)
 
-## ✨Highlights✨
+## ✨ Highlights ✨
 
-- Decentralized state management
-- Unopinionated and easy-to-use API
-- No need to wrap app in Context or prop drilling
+- Decentralized (atomic) state management
+- Simple, unopinionated API
+- No Context wrapper or prop drilling required
 - React components re-render only on changes
 - Compatible with React 18/19 concurrent rendering
-- Selectors are memoized by default
-- Feature extensible with middleware or plugins
+- Built-in memoized selectors
+- Extensible with middleware and plugins
 - State persistable to browser storage
-- Support for Redux dev tools via middleware
-- [Less than 1KB](https://bundlejs.com/?q=reactish-state&treeshake=%5B*%5D&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%5D%7D%7D): simple and small
+- Redux DevTools support via middleware
+- Fully compatible with React Compiler
+- Ultra-lightweight: [<1KB](https://bundlejs.com/?q=reactish-state&treeshake=%5B*%5D&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%5D%7D%7D)
 
 ## Install
 
@@ -25,7 +26,38 @@
 npm install reactish-state
 ```
 
-## Quick start
+## Table of Contents
+
+- [Quick start](#quick-start)
+  - [State](#we-begin-by-creating-some-state)
+  - [State with actions](#a-state-can-also-have-custom-actions-bound-to-it)
+  - [Selectors](#selector-can-create-derived-state)
+  - [Usage in React](#use-the-state-and-selectors-in-your-react-components)
+- [Why another library?](#why-another-state-management-library)
+- [Why decentralized?](#why-decentralized-state-management)
+- [Why not Zustand?](#why-choose-this-over-zustand)
+- [Recipes](#recipes)
+  - [Immutable updates](#state-should-be-updated-immutably)
+  - [Memoized selectors](#selectors-are-memoized)
+  - [Async updates](#async-state-updates)
+  - [Accessing other state in actions](#accessing-other-state-or-selectors-inside-actions)
+  - [Usage outside React](#interacting-with-state-or-selectors-outside-react)
+  - [Destructuring actions](#destructuring-actions-for-easier-access)
+  - [useSelector](#selector-that-depends-on-props-or-local-state)
+  - [Redux-like reducers](#still-perfer-redux-like-reducers)
+- [Middleware](#middleware)
+  - [Persist middleware](#persist-middleware)
+  - [Immer middleware](#immer-middleware)
+  - [Redux devtools middleware](#redux-devtools-middleware)
+  - [Multiple middleware](#using-multiple-middleware)
+  - [Different middleware](#using-different-middleware-in-different-states)
+- [Plugins](#plugins)
+  - [Redux devtools plugin](#redux-devtools-plugin)
+- [TypeScript usage](#typescript-usage)
+- [Examples](#examples)
+- [React 16/17 setup](#react-1617-setup)
+
+# Quick start
 
 ### We begin by creating some state
 
@@ -384,21 +416,17 @@ dispatch({ type: "DECREASE", by: 7 });
 console.log(countState.get()); // Print 3
 ```
 
-## Middleware
+# Middleware
 
-You can enhance the functionality of state with middleware. Instead of using the `state` export, use the `createState` export from the library. Middleware is a function that receives `set`, `get`, and `subscribe`, and should return a new set function.
+You can enhance state functionality using middleware. Instead of the `state` export, use the `stateBuilder` export from the library. A middleware is a function that receives a state object and returns a new `set` function, which can add custom behavior while still calling the current `set` in the middleware chain.
 
 ```js
-import { createState } from "reactish-state";
-
-const state = createState({
-  middleware:
-    ({ set, get }) =>
-    (...args) => {
-      set(...args);
-      // Log the state every time after calling `set`
-      console.log("New state", get());
-    }
+import { stateBuilder } from "reactish-state";
+
+const state = stateBuilder(({ set, get }) => (...args) => {
+  set(...args);
+  // Log the state every time after calling `set`
+  console.log("New state", get());
 });
 
 // Now the `state` function has middleware wired up
@@ -420,13 +448,13 @@ filterState.set("COMPLETED"); // Print "New state 'COMPLETED'"
 You can save the state to browser storage using the `persist` middleware.
 
 ```js
-import { createState } from "reactish-state";
+import { stateBuilder } from "reactish-state";
 import { persist } from "reactish-state/middleware";
 
 // Create the persist middleware,
 // optionally provide a `prefix` to prepend to the keys in storage
 const persistMiddleware = persist({ prefix: "myApp-" });
-const state = createState({ middleware: persistMiddleware });
+const state = stateBuilder(persistMiddleware.middleware);
 
 const countState = state(
   0,
@@ -457,10 +485,10 @@ const persistMiddleware = persist({ getStorage: () => sessionStorage });
 You can update state mutably using the `immer` middleware.
 
 ```js
-import { createState } from "reactish-state";
+import { stateBuilder } from "reactish-state";
 import { immer } from "reactish-state/middleware/immer";
 
-const state = createState({ middleware: immer });
+const state = stateBuilder(immer);
 
 let todoId = 1;
 const todos = state([], (set) => ({
@@ -488,10 +516,10 @@ todos.toggle(1);
 This middleware provides integration with the Redux DevTools browser extension. Individual states are combined into a single object in Redux DevTools for easy inspection.
 
 ```js
-import { createState } from "reactish-state";
+import { stateBuilder } from "reactish-state";
 import { reduxDevtools } from "reactish-state/middleware";
 
-const state = createState({ middleware: reduxDevtools({ name: "todoApp" }) });
+const state = stateBuilder(reduxDevtools({ name: "todoApp" }));
 
 const todos = state(
   [],
@@ -523,14 +551,14 @@ const filter = state("ALL", null, { key: "filter" });
 
 ## Using multiple middleware
 
-Middleware is chainable. You can use the `applyMiddleware` utility to chain multiple middleware and pass the result to `createState`.
+Middleware is chainable. You can use the `applyMiddleware` utility to chain multiple middleware and pass the result to `stateBuilder`.
 
 ```js
 import { applyMiddleware } from "reactish-state/middleware";
 
-const state = createState({
-  middleware: applyMiddleware([immer, reduxDevtools(), persist()])
-});
+const state = stateBuilder(
+  applyMiddleware([reduxDevtools(), persist().middleware, immer])
+);
 ```
 
 ## Using different middleware in different states
@@ -538,44 +566,38 @@ const state = createState({
 This is naturally achievable thanks to the decentralized state model.
 
 ```js
-const persistState = createState({ middleware: persist() });
-const immerState = createState({ middleware: immer });
+const persistableState = stateBuilder(persist().middleware);
+const immerState = stateBuilder(immer);
 
-const visibilityFilter = persistState("ALL"); // Will be persisted
+const visibilityFilter = persistableState("ALL"); // Will be persisted
 const todos = immerState([]); // Can be mutated
 ```
 
 This also eliminates the need to implement a whitelist or blacklist in the persist middleware.
 
-## Plugins
+# Plugins
 
-While middleware enhances state, plugins allow you to hook into selectors. The key difference is that plugins don’t return a `set` function, as selectors are read-only. Similarly, you use the `createSelector` export from the library instead of `selector`.
+While middleware enhances state, plugins allow you to hook into selectors. The key difference is that plugins don’t return a `set` function, as selectors are read-only. Similarly, you use the `selectorBuilder` export from the library instead of `selector`.
 
 ```js
-import { state, createSelector } from "reactish-state";
-
-const selector = createSelector({
-  plugin: ({ get, subscribe }, config) => {
-    subscribe(() => {
-      // Log the selector value every time it changes
-      // `config` can hold contextual data from the selector
-      console.log(`${config?.key} selector:`, get());
-    });
-  }
+import { state, selectorBuilder } from "reactish-state";
+
+const selector = selectorBuilder(({ get, subscribe, meta }) => {
+  subscribe(() => {
+    // Log the selector value every time it changes
+    // `meta` returns metadata of the selector
+    console.log(`${meta()} selector:`, get());
+  });
 });
 
 const countState = state(0);
 const doubleSelector = selector(
   countState,
   (count) => count * 2,
-  // Provide contextual data in the last parameter to identify the selector
-  {
-    key: "double"
-  }
+  // Provide metadata in the last parameter to identify the selector
+  "double"
 );
-const squareSelector = selector(countState, (count) => count * count, {
-  key: "square"
-});
+const squareSelector = selector(countState, (count) => count * count, "square");
 
 countState.set(5); // Logs - double selector: 10, square selector: 25
 ```
@@ -587,10 +609,10 @@ Likewise, there is an `applyPlugin` function for applying multiple plugins.
 Individual selectors are combined into a single object in Redux DevTools for easy inspection.
 
 ```js
-import { createSelector } from "reactish-state";
+import { selectorBuilder } from "reactish-state";
 import { reduxDevtools } from "reactish-state/plugin";
 
-const selector = createSelector({ plugin: reduxDevtools() });
+const selector = selectorBuilder(reduxDevtools());
 // Then use the `selector` as usual...
 ```
 

package/dist/cjs/index.cjs

@@ -8,10 +8,10 @@ var shim = require('./react/shim.cjs');
 
 
 
-exports.createState = state.createState;
 exports.state = state.state;
-exports.createSelector = selector.createSelector;
+exports.stateBuilder = state.stateBuilder;
 exports.selector = selector.selector;
+exports.selectorBuilder = selector.selectorBuilder;
 exports.useSnapshot = useSnapshot.useSnapshot;
 exports.useSelector = useSelector.useSelector;
 exports.setReactShim = shim.setReactShim;

package/dist/cjs/middleware/applyMiddleware.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+const applyMiddleware = (middlewares, {
+  fromRight
+} = {}) => api => middlewares[fromRight ? 'reduceRight' : 'reduce']((set, middleware) => middleware ? middleware({
+  ...api,
+  set
+}) : set, api.set);
+
+exports.applyMiddleware = applyMiddleware;

package/dist/cjs/middleware/immer.cjs

@@ -0,0 +1,9 @@
+'use strict';
+
+var immer$1 = require('immer');
+
+const immer = ({
+  set
+}) => (value, context) => set(typeof value === 'function' ? immer$1.produce(value) : value, context);
+
+exports.immer = immer;

package/dist/cjs/middleware/persist.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+const persist = ({
+  prefix,
+  getStorage = () => localStorage
+} = {}) => {
+  const states = [];
+  return {
+    middleware: ({
+      set,
+      get,
+      meta
+    }) => {
+      let key = meta()?.key;
+      if (process.env.NODE_ENV !== 'production' && !key) throw new Error('[reactish-state] state should be provided with a string `key` in the config object when the `persist` middleware is used.');
+      if (prefix) key = prefix + key;
+      states.push([key, set]);
+      return (...args) => {
+        set(...args);
+        try {
+          getStorage().setItem(key, JSON.stringify(get()));
+        } catch (_unused) {
+          /* continue regardless of error */
+        }
+      };
+    },
+    hydrate: () => {
+      states.forEach(([key, set]) => {
+        try {
+          const value = getStorage().getItem(key);
+          value != null && set(value !== 'undefined' ? JSON.parse(value) : undefined, `HYDRATE_${key}`);
+        } catch (_unused2) {
+          /* continue regardless of error */
+        }
+      });
+      states.length = 0;
+    }
+  };
+};
+
+exports.persist = persist;

package/dist/{middleware/cjs → cjs/middleware}/reduxDevtools.cjs

@@ -4,22 +4,24 @@ const reduxDevtools = ({
   name
 } = {}) => {
   let devtoolsExt;
-  if (process.env.NODE_ENV === 'production' || typeof window === 'undefined' || !(devtoolsExt = window.__REDUX_DEVTOOLS_EXTENSION__)) return;
+  if (process.env.NODE_ENV === 'production' || typeof window === 'undefined' || !(devtoolsExt = window.__REDUX_DEVTOOLS_EXTENSION__)) {
+    return;
+  }
   const devtools = devtoolsExt.connect({
     name
   });
   const mergedState = {};
   return ({
     set,
-    get
-  }, config) => {
-    const key = config?.key;
-    if (!key) throw new Error('[reactish-state] state should be provided with a string `key` in the config object when the `reduxDevtools` middleware is used.');
+    get,
+    meta
+  }) => {
+    const key = meta()?.key;
+    if (process.env.NODE_ENV !== 'production' && !key) throw new Error('[reactish-state] state should be provided with a string `key` in the config object when the `reduxDevtools` middleware is used.');
     mergedState[key] = get();
     devtools.init(mergedState);
-    return (...args) => {
-      const [value, action] = args;
-      set(...args);
+    return (value, action) => {
+      set(value, action);
       mergedState[key] = get();
       devtools.send(typeof action === 'string' ? {
         type: action

package/dist/cjs/plugin/applyPlugin.cjs

@@ -0,0 +1,5 @@
+'use strict';
+
+const applyPlugin = plugins => selector => plugins.forEach(plugin => plugin?.(selector));
+
+exports.applyPlugin = applyPlugin;

package/dist/{plugin/cjs → cjs/plugin}/reduxDevtools.cjs

@@ -11,10 +11,11 @@ const reduxDevtools = ({
   const mergedState = {};
   return ({
     get,
-    subscribe
-  }, config) => {
-    const key = config?.key;
-    if (!key) throw new Error('[reactish-state] state should be provided with a string `key` in the config object when the `reduxDevtools` plugin is used.');
+    subscribe,
+    meta
+  }) => {
+    const key = meta()?.key;
+    if (process.env.NODE_ENV !== 'production' && !key) throw new Error('[reactish-state] selector should be provided with a string `key` in the config object when the `reduxDevtools` plugin is used.');
     const updateState = () => {
       mergedState[key] = get();
       devtools.init(mergedState);

package/dist/cjs/vanilla/selector.cjs

@@ -2,13 +2,11 @@
 
 var utils = require('../utils.cjs');
 
-const createSelector = ({
-  plugin
-} = {}) => (...items) => {
+const selectorBuilder = plugin => (...items) => {
   const length = items.length;
   const cutoff = typeof items[length - 1] === 'function' ? length - 1 : length - 2;
   const selectorFunc = items[cutoff];
-  const config = items[cutoff + 1];
+  const metadata = items[cutoff + 1];
   items.length = cutoff;
   let cache;
   const selector = {
@@ -19,12 +17,14 @@ const createSelector = ({
       cache = [args, value];
       return value;
     },
-    subscribe: utils.createSubscriber(items)
+    subscribe: utils.createSubscriber(items),
+    meta: () => metadata
   };
-  plugin?.(selector, config);
+  plugin?.(selector);
   return selector;
+  // Wrap TSelectorMeta in a tuple to prevent conditional type distribution;
 };
-const selector = /*#__PURE__*/createSelector();
+const selector = /*#__PURE__*/selectorBuilder();
 
-exports.createSelector = createSelector;
 exports.selector = selector;
+exports.selectorBuilder = selectorBuilder;

package/dist/cjs/vanilla/state.cjs

@@ -1,13 +1,12 @@
 'use strict';
 
-const createState = ({
-  middleware
-} = {}) => (initialValue, actionBuilder, config) => {
+const stateBuilder = middleware => (initialValue, actionBuilder, metadata) => {
   let value = initialValue;
   const listeners = new Set();
   const get = () => value;
   const readonlyState = {
     get,
+    meta: () => metadata,
     subscribe: listener => {
       listeners.add(listener);
       return () => listeners.delete(listener);
@@ -24,14 +23,15 @@ const createState = ({
   if (middleware) set = middleware({
     ...readonlyState,
     set
-  }, config);
+  });
   return {
     ...actionBuilder?.(set, get),
     ...readonlyState,
     set
   };
+  // Wrap TStateMeta in a tuple to prevent conditional type distribution
 };
-const state = /*#__PURE__*/createState();
+const state = /*#__PURE__*/stateBuilder();
 
-exports.createState = createState;
 exports.state = state;
+exports.stateBuilder = stateBuilder;

package/dist/esm/index.mjs

@@ -1,5 +1,5 @@
-export { createState, state } from './vanilla/state.mjs';
-export { createSelector, selector } from './vanilla/selector.mjs';
+export { state, stateBuilder } from './vanilla/state.mjs';
+export { selector, selectorBuilder } from './vanilla/selector.mjs';
 export { useSnapshot } from './react/useSnapshot.mjs';
 export { useSelector } from './react/useSelector.mjs';
 export { setReactShim } from './react/shim.mjs';

package/dist/esm/middleware/applyMiddleware.mjs

@@ -0,0 +1,8 @@
+const applyMiddleware = (middlewares, {
+  fromRight
+} = {}) => api => middlewares[fromRight ? 'reduceRight' : 'reduce']((set, middleware) => middleware ? middleware({
+  ...api,
+  set
+}) : set, api.set);
+
+export { applyMiddleware };

package/dist/esm/middleware/immer.mjs

@@ -0,0 +1,7 @@
+import { produce } from 'immer';
+
+const immer = ({
+  set
+}) => (value, context) => set(typeof value === 'function' ? produce(value) : value, context);
+
+export { immer };

package/dist/esm/middleware/persist.mjs

@@ -0,0 +1,39 @@
+const persist = ({
+  prefix,
+  getStorage = () => localStorage
+} = {}) => {
+  const states = [];
+  return {
+    middleware: ({
+      set,
+      get,
+      meta
+    }) => {
+      let key = meta()?.key;
+      if (process.env.NODE_ENV !== 'production' && !key) throw new Error('[reactish-state] state should be provided with a string `key` in the config object when the `persist` middleware is used.');
+      if (prefix) key = prefix + key;
+      states.push([key, set]);
+      return (...args) => {
+        set(...args);
+        try {
+          getStorage().setItem(key, JSON.stringify(get()));
+        } catch (_unused) {
+          /* continue regardless of error */
+        }
+      };
+    },
+    hydrate: () => {
+      states.forEach(([key, set]) => {
+        try {
+          const value = getStorage().getItem(key);
+          value != null && set(value !== 'undefined' ? JSON.parse(value) : undefined, `HYDRATE_${key}`);
+        } catch (_unused2) {
+          /* continue regardless of error */
+        }
+      });
+      states.length = 0;
+    }
+  };
+};
+
+export { persist };

package/dist/{middleware/esm → esm/middleware}/reduxDevtools.mjs

@@ -2,22 +2,24 @@ const reduxDevtools = ({
   name
 } = {}) => {
   let devtoolsExt;
-  if (process.env.NODE_ENV === 'production' || typeof window === 'undefined' || !(devtoolsExt = window.__REDUX_DEVTOOLS_EXTENSION__)) return;
+  if (process.env.NODE_ENV === 'production' || typeof window === 'undefined' || !(devtoolsExt = window.__REDUX_DEVTOOLS_EXTENSION__)) {
+    return;
+  }
   const devtools = devtoolsExt.connect({
     name
   });
   const mergedState = {};
   return ({
     set,
-    get
-  }, config) => {
-    const key = config?.key;
-    if (!key) throw new Error('[reactish-state] state should be provided with a string `key` in the config object when the `reduxDevtools` middleware is used.');
+    get,
+    meta
+  }) => {
+    const key = meta()?.key;
+    if (process.env.NODE_ENV !== 'production' && !key) throw new Error('[reactish-state] state should be provided with a string `key` in the config object when the `reduxDevtools` middleware is used.');
     mergedState[key] = get();
     devtools.init(mergedState);
-    return (...args) => {
-      const [value, action] = args;
-      set(...args);
+    return (value, action) => {
+      set(value, action);
       mergedState[key] = get();
       devtools.send(typeof action === 'string' ? {
         type: action

package/dist/esm/plugin/applyPlugin.mjs

@@ -0,0 +1,3 @@
+const applyPlugin = plugins => selector => plugins.forEach(plugin => plugin?.(selector));
+
+export { applyPlugin };

package/dist/{plugin/esm → esm/plugin}/reduxDevtools.mjs

@@ -9,10 +9,11 @@ const reduxDevtools = ({
   const mergedState = {};
   return ({
     get,
-    subscribe
-  }, config) => {
-    const key = config?.key;
-    if (!key) throw new Error('[reactish-state] state should be provided with a string `key` in the config object when the `reduxDevtools` plugin is used.');
+    subscribe,
+    meta
+  }) => {
+    const key = meta()?.key;
+    if (process.env.NODE_ENV !== 'production' && !key) throw new Error('[reactish-state] selector should be provided with a string `key` in the config object when the `reduxDevtools` plugin is used.');
     const updateState = () => {
       mergedState[key] = get();
       devtools.init(mergedState);

package/dist/esm/vanilla/selector.mjs

@@ -1,12 +1,10 @@
 import { createSubscriber, getSelectorValues, isEqual } from '../utils.mjs';
 
-const createSelector = ({
-  plugin
-} = {}) => (...items) => {
+const selectorBuilder = plugin => (...items) => {
   const length = items.length;
   const cutoff = typeof items[length - 1] === 'function' ? length - 1 : length - 2;
   const selectorFunc = items[cutoff];
-  const config = items[cutoff + 1];
+  const metadata = items[cutoff + 1];
   items.length = cutoff;
   let cache;
   const selector = {
@@ -17,11 +15,13 @@ const createSelector = ({
       cache = [args, value];
       return value;
     },
-    subscribe: createSubscriber(items)
+    subscribe: createSubscriber(items),
+    meta: () => metadata
   };
-  plugin?.(selector, config);
+  plugin?.(selector);
   return selector;
+  // Wrap TSelectorMeta in a tuple to prevent conditional type distribution;
 };
-const selector = /*#__PURE__*/createSelector();
+const selector = /*#__PURE__*/selectorBuilder();
 
-export { createSelector, selector };
+export { selector, selectorBuilder };

package/dist/esm/vanilla/state.mjs

@@ -1,11 +1,10 @@
-const createState = ({
-  middleware
-} = {}) => (initialValue, actionBuilder, config) => {
+const stateBuilder = middleware => (initialValue, actionBuilder, metadata) => {
   let value = initialValue;
   const listeners = new Set();
   const get = () => value;
   const readonlyState = {
     get,
+    meta: () => metadata,
     subscribe: listener => {
       listeners.add(listener);
       return () => listeners.delete(listener);
@@ -22,13 +21,14 @@ const createState = ({
   if (middleware) set = middleware({
     ...readonlyState,
     set
-  }, config);
+  });
   return {
     ...actionBuilder?.(set, get),
     ...readonlyState,
     set
   };
+  // Wrap TStateMeta in a tuple to prevent conditional type distribution
 };
-const state = /*#__PURE__*/createState();
+const state = /*#__PURE__*/stateBuilder();
 
-export { createState, state };
+export { state, stateBuilder };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reactish-state",
-  "version": "1.2.1-alpha.2",
+  "version": "2.0.0-alpha.0",
   "description": "Simple, decentralized (atomic) state management for React.",
   "author": "Zheng Song",
   "license": "MIT",
@@ -50,23 +50,23 @@
     },
     "./middleware": {
       "types": "./types/middleware/index.d.ts",
-      "require": "./dist/middleware/cjs/index.cjs",
-      "default": "./dist/middleware/esm/index.mjs"
+      "require": "./dist/cjs/middleware/index.cjs",
+      "default": "./dist/esm/middleware/index.mjs"
     },
     "./middleware/immer": {
       "types": "./types/middleware/immer.d.ts",
-      "require": "./dist/middleware/cjs/immer.cjs",
-      "default": "./dist/middleware/esm/immer.mjs"
+      "require": "./dist/cjs/middleware/immer.cjs",
+      "default": "./dist/esm/middleware/immer.mjs"
     },
     "./plugin": {
       "types": "./types/plugin/index.d.ts",
-      "require": "./dist/plugin/cjs/index.cjs",
-      "default": "./dist/plugin/esm/index.mjs"
+      "require": "./dist/cjs/plugin/index.cjs",
+      "default": "./dist/esm/plugin/index.mjs"
     },
     "./shim": {
       "types": "./types/shim/index.d.ts",
-      "require": "./dist/shim/cjs/index.cjs",
-      "default": "./dist/shim/esm/index.mjs"
+      "require": "./dist/cjs/shim/index.cjs",
+      "default": "./dist/esm/shim/index.mjs"
     },
     "./package.json": "./package.json"
   },

package/types/middleware/applyMiddleware.d.ts

@@ -1,5 +1,5 @@
 import type { Middleware } from '../types';
-declare const applyMiddleware: <TConfig>(middlewares: (Middleware<TConfig> | undefined)[], options?: {
+declare const applyMiddleware: <TStateMeta>(middlewares: (Middleware<TStateMeta> | undefined)[], options?: {
     fromRight?: boolean;
-}) => Middleware<TConfig>;
+}) => Middleware<TStateMeta>;
 export { applyMiddleware };

package/types/middleware/persist.d.ts

@@ -1,11 +1,11 @@
-import type { Middleware, Config } from '../types';
-interface PersistMiddleware extends Middleware<Config> {
-    hydrate(this: void): void;
+import type { Middleware, Metadata } from '../types';
+interface Persist<TStateMeta extends Metadata> {
+    middleware: Middleware<TStateMeta>;
+    hydrate: () => void;
 }
-type Persist = (options?: {
+declare const persist: <TStateMeta extends Metadata>({ prefix, getStorage }?: {
     prefix?: string;
-    getStorage?: () => Pick<Storage, 'getItem' | 'setItem'>;
-}) => PersistMiddleware;
-declare const persist: Persist;
-export type { Persist, PersistMiddleware };
+    getStorage?: () => Pick<Storage, "getItem" | "setItem">;
+}) => Persist<TStateMeta>;
+export type { Persist };
 export { persist };

package/types/middleware/reduxDevtools.d.ts

@@ -1,7 +1,5 @@
-import type { Middleware, Config } from '../types';
-type ReduxDevtools = (options?: {
+import type { Middleware, Metadata } from '../types';
+declare const reduxDevtools: <TStateMeta extends Metadata>({ name }?: {
     name?: string;
-}) => Middleware<Config> | undefined;
-declare const reduxDevtools: ReduxDevtools;
-export type { ReduxDevtools };
+}) => Middleware<TStateMeta> | undefined;
 export { reduxDevtools };

package/types/plugin/applyPlugin.d.ts

@@ -1,3 +1,3 @@
 import type { Plugin } from '../types';
-declare const applyPlugin: <TConfig>(plugins: (Plugin<TConfig> | undefined)[]) => Plugin<TConfig>;
+declare const applyPlugin: <TSelectorMeta>(plugins: (Plugin<TSelectorMeta> | undefined)[]) => Plugin<TSelectorMeta>;
 export { applyPlugin };

package/types/plugin/reduxDevtools.d.ts

@@ -1,7 +1,5 @@
-import type { Plugin, Config } from '../types';
-type ReduxDevtools = (options?: {
+import type { Plugin, Metadata } from '../types';
+declare const reduxDevtools: <TSelectorMeta extends Metadata>({ name }?: {
     name?: string;
-}) => Plugin<Config> | undefined;
-declare const reduxDevtools: ReduxDevtools;
-export type { ReduxDevtools };
+}) => Plugin<TSelectorMeta> | undefined;
 export { reduxDevtools };

package/types/react/useSnapshot.d.ts

@@ -1,3 +1,3 @@
-import type { Selector } from '../types';
-declare const useSnapshot: <TValue>({ subscribe, get }: Selector<TValue>) => TValue;
+import type { Observable } from '../types';
+declare const useSnapshot: <TValue>({ subscribe, get }: Observable<TValue>) => TValue;
 export { useSnapshot };

package/types/types.d.ts

@@ -1,35 +1,42 @@
+export interface Metadata {
+    key: string;
+}
 export type Getter<TValue> = () => TValue;
 export type Setter<TValue, TContext = unknown> = (newValue: TValue | ((value: TValue) => TValue), context?: TContext) => void;
 export type Unsubscriber = () => void;
 export type StateListener<TValue> = (nextValue: TValue, prevValue: TValue) => void;
 export type StateSubscriber<TValue> = (listener: StateListener<TValue>) => Unsubscriber;
-export interface State<TValue, TContext = unknown> {
+export interface State<TValue, TMeta = unknown, TContext = unknown> {
     get: Getter<TValue>;
     set: Setter<TValue, TContext>;
     subscribe: StateSubscriber<TValue>;
+    meta: () => TMeta;
+}
+export type StateWithAction<TValue, TAction, TMeta = unknown, TContext = unknown> = Omit<TAction, keyof State<TValue, TMeta, TContext>> & State<TValue, TMeta, TContext>;
+export type ActionBuilder<TValue, TAction, TContext = unknown> = (set: Setter<TValue, TContext>, get: Getter<TValue>) => TAction;
+export interface StateBuilder {
+    <TValue, TContext = unknown>(): State<TValue | undefined, undefined, TContext>;
+    <TValue, TContext = unknown>(initialValue: TValue): State<TValue, undefined, TContext>;
+    <TValue, TMeta, TContext = unknown>(initialValue: TValue, actionBuilder: null | undefined, metadata: TMeta): State<TValue, TMeta, TContext>;
+    <TValue, TAction, TContext = unknown>(initialValue: TValue, actionBuilder: ActionBuilder<TValue, TAction, TContext>): StateWithAction<TValue, TAction, undefined, TContext>;
+    <TValue, TAction, TMeta, TContext = unknown>(initialValue: TValue, actionBuilder: ActionBuilder<TValue, TAction, TContext>, metadata: TMeta): StateWithAction<TValue, TAction, TMeta, TContext>;
 }
-export type StateWithAction<TValue, TAction, TContext = unknown> = Omit<TAction, keyof State<TValue, TContext>> & State<TValue, TContext>;
-export type ActionBuilder<TValue, TAction, TContext = unknown> = (set: Setter<TValue, TContext>, get: () => TValue) => TAction;
-export interface StateBuilder<TConfig = unknown> {
-    <TValue, TContext = unknown>(): State<TValue | undefined, TContext>;
-    <TValue, TContext = unknown>(initialValue: TValue): State<TValue, TContext>;
-    <TValue, TContext = unknown>(initialValue: TValue, actionBuilder: null | undefined, config?: TConfig): State<TValue, TContext>;
-    <TValue, TAction, TContext = unknown>(initialValue: TValue, actionBuilder: ActionBuilder<TValue, TAction, TContext>, config?: TConfig): StateWithAction<TValue, TAction, TContext>;
+export interface StateBuilderWithMeta<TStateMeta> {
+    <TValue, TMeta extends TStateMeta, TContext = unknown>(initialValue: TValue, actionBuilder: null | undefined, metadata: TMeta): State<TValue, TMeta, TContext>;
+    <TValue, TAction, TMeta extends TStateMeta, TContext = unknown>(initialValue: TValue, actionBuilder: ActionBuilder<TValue, TAction, TContext>, metadata: TMeta): StateWithAction<TValue, TAction, TMeta, TContext>;
 }
 export type SelectorListener = () => void;
 export type SelectorSubscriber = (listener: SelectorListener) => Unsubscriber;
-export interface Selector<TValue> {
+export interface Observable<TValue> {
     get: Getter<TValue>;
     subscribe: SelectorSubscriber;
 }
-export interface Config {
-    key?: string;
+export interface Selector<TValue, TMeta = unknown> extends Observable<TValue> {
+    meta: () => TMeta;
 }
-export interface Middleware<TConfig = unknown> {
-    <TValue, TContext = unknown>(state: State<TValue, TContext>, config?: TConfig): Setter<TValue, TContext>;
-}
-export interface Plugin<TConfig = unknown> {
-    <TValue>(selector: Selector<TValue>, config?: TConfig): void;
+export type Middleware<TStateMeta = never> = <TValue, TMeta extends TStateMeta, TContext = unknown>(state: State<TValue, TMeta, TContext>) => Setter<TValue, TContext>;
+export interface Plugin<TSelectorMeta = never> {
+    <TValue, TMeta extends TSelectorMeta>(selector: Selector<TValue, TMeta>): void;
 }
 export type SelectorArray = Selector<unknown>[];
 export type SelectorValueArray<TArray extends SelectorArray> = {
@@ -40,7 +47,10 @@ export type SelectorParams<TArray extends SelectorArray, TValue> = [
     ...TArray,
     SelectorFunc<TArray, TValue>
 ];
-export interface SelectorBuilder<TConfig = unknown> {
+export interface SelectorBuilder {
     <TArray extends SelectorArray, TValue>(...items: SelectorParams<TArray, TValue>): Selector<TValue>;
-    <TArray extends SelectorArray, TValue>(...items: [...SelectorParams<TArray, TValue>, TConfig]): Selector<TValue>;
+    <TArray extends SelectorArray, TValue, TMeta>(...items: [...SelectorParams<TArray, TValue>, TMeta]): Selector<TValue>;
+}
+export interface SelectorBuilderWithMeta<TSelectorMeta> {
+    <TArray extends SelectorArray, TValue, TMeta extends TSelectorMeta>(...items: [...SelectorParams<TArray, TValue>, TMeta]): Selector<TValue>;
 }

package/types/vanilla/selector.d.ts

@@ -1,6 +1,4 @@
-import type { Plugin, SelectorBuilder } from '../types';
-declare const createSelector: <TConfig>({ plugin }?: {
-    plugin?: Plugin<TConfig>;
-}) => SelectorBuilder<TConfig>;
-declare const selector: SelectorBuilder<unknown>;
-export { selector, createSelector };
+import type { Plugin, SelectorBuilder, SelectorBuilderWithMeta } from '../types';
+declare const selectorBuilder: <TSelectorMeta = never>(plugin?: Plugin<TSelectorMeta>) => [TSelectorMeta] extends [never] ? SelectorBuilder : SelectorBuilderWithMeta<TSelectorMeta>;
+declare const selector: SelectorBuilder;
+export { selector, selectorBuilder };

package/types/vanilla/state.d.ts

@@ -1,6 +1,4 @@
-import type { StateBuilder, Middleware } from '../types';
-declare const createState: <TConfig>({ middleware }?: {
-    middleware?: Middleware<TConfig>;
-}) => StateBuilder<TConfig>;
-declare const state: StateBuilder<unknown>;
-export { state, createState };
+import type { StateBuilder, StateBuilderWithMeta, Middleware } from '../types';
+declare const stateBuilder: <TStateMeta = never>(middleware?: Middleware<TStateMeta>) => [TStateMeta] extends [never] ? StateBuilder : StateBuilderWithMeta<TStateMeta>;
+declare const state: StateBuilder;
+export { state, stateBuilder };

package/dist/middleware/cjs/applyMiddleware.cjs

@@ -1,10 +0,0 @@
-'use strict';
-
-const applyMiddleware = (middlewares, {
-  fromRight
-} = {}) => (api, config) => middlewares[fromRight ? 'reduceRight' : 'reduce']((set, middleware) => middleware ? middleware({
-  ...api,
-  set
-}, config) : set, api.set);
-
-exports.applyMiddleware = applyMiddleware;

package/dist/middleware/cjs/immer.cjs

@@ -1,9 +0,0 @@
-'use strict';
-
-var immer$1 = require('immer');
-
-const immer = ({
-  set
-}) => (value, ...rest) => set(typeof value === 'function' ? immer$1.produce(value) : value, ...rest);
-
-exports.immer = immer;

package/dist/middleware/cjs/persist.cjs

@@ -1,39 +0,0 @@
-'use strict';
-
-const persist = ({
-  prefix,
-  getStorage = () => localStorage
-} = {}) => {
-  const states = [];
-  const middleware = ({
-    set,
-    get
-  }, config) => {
-    let key = config?.key || '';
-    if (!key) throw new Error('[reactish-state] state should be provided with a string `key` in the config object when the `persist` middleware is used.');
-    if (prefix) key = prefix + key;
-    states.push([key, set]);
-    return (...args) => {
-      set(...args);
-      try {
-        getStorage().setItem(key, JSON.stringify(get()));
-      } catch (_unused) {
-        /* continue regardless of error */
-      }
-    };
-  };
-  middleware.hydrate = () => {
-    states.forEach(([key, set]) => {
-      try {
-        const value = getStorage().getItem(key);
-        value != null && set(value !== 'undefined' ? JSON.parse(value) : undefined, `HYDRATE_${key}`);
-      } catch (_unused2) {
-        /* continue regardless of error */
-      }
-    });
-    states.length = 0;
-  };
-  return middleware;
-};
-
-exports.persist = persist;

package/dist/middleware/esm/applyMiddleware.mjs

@@ -1,8 +0,0 @@
-const applyMiddleware = (middlewares, {
-  fromRight
-} = {}) => (api, config) => middlewares[fromRight ? 'reduceRight' : 'reduce']((set, middleware) => middleware ? middleware({
-  ...api,
-  set
-}, config) : set, api.set);
-
-export { applyMiddleware };

package/dist/middleware/esm/immer.mjs

@@ -1,7 +0,0 @@
-import { produce } from 'immer';
-
-const immer = ({
-  set
-}) => (value, ...rest) => set(typeof value === 'function' ? produce(value) : value, ...rest);
-
-export { immer };

package/dist/middleware/esm/persist.mjs

@@ -1,37 +0,0 @@
-const persist = ({
-  prefix,
-  getStorage = () => localStorage
-} = {}) => {
-  const states = [];
-  const middleware = ({
-    set,
-    get
-  }, config) => {
-    let key = config?.key || '';
-    if (!key) throw new Error('[reactish-state] state should be provided with a string `key` in the config object when the `persist` middleware is used.');
-    if (prefix) key = prefix + key;
-    states.push([key, set]);
-    return (...args) => {
-      set(...args);
-      try {
-        getStorage().setItem(key, JSON.stringify(get()));
-      } catch (_unused) {
-        /* continue regardless of error */
-      }
-    };
-  };
-  middleware.hydrate = () => {
-    states.forEach(([key, set]) => {
-      try {
-        const value = getStorage().getItem(key);
-        value != null && set(value !== 'undefined' ? JSON.parse(value) : undefined, `HYDRATE_${key}`);
-      } catch (_unused2) {
-        /* continue regardless of error */
-      }
-    });
-    states.length = 0;
-  };
-  return middleware;
-};
-
-export { persist };

package/dist/plugin/cjs/applyPlugin.cjs

@@ -1,5 +0,0 @@
-'use strict';
-
-const applyPlugin = plugins => (selector, config) => plugins.forEach(plugin => plugin?.(selector, config));
-
-exports.applyPlugin = applyPlugin;

package/dist/plugin/esm/applyPlugin.mjs

@@ -1,3 +0,0 @@
-const applyPlugin = plugins => (selector, config) => plugins.forEach(plugin => plugin?.(selector, config));
-
-export { applyPlugin };