zustand-lite 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Piotr Siatkowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# 🧠 Zustand Lite
+
+[![npm version](https://img.shields.io/npm/v/zustand-lite?color=blue)](https://www.npmjs.com/package/zustand-lite)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/zustand-lite)](https://bundlephobia.com/package/zustand-lite)
+[![license](https://img.shields.io/npm/l/zustand-lite)](./LICENSE)
+[![Types](https://img.shields.io/badge/TypeScript-ready-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![GitHub stars](https://img.shields.io/github/stars/PiotrSiatkowski/zustand-lite?style=social)](https://github.com/PiotrSiatkowski/zustand-lite)
+
+---
+
+Zustand Lite is a **zero-boilerplate** state management wrapper built specifically for **frontend developers** who want powerful and scalable global state without the usual complexity. Designed for simplicity, it gives you everything you need out-of-the-box — from selectors to setters to middleware — while remaining lightweight and extensible. With seamless support for plugins, devtools, and state encapsulation, managing state becomes a breeze, not a chore.
+
+> A zero-boilerplate wrapper around [Zustand](https://github.com/pmndrs/zustand), focused on ergonomics, plugins, and powerful dynamic extension — inspired by [zustand-x](https://github.com/udecode/zustand-x) and selector auto-generation patterns.
+
+---
+
+## 🚀 Features
+
+- 😊 Write only code that matters -> save lines
+- ✅ Type-safe getter/setter generators for every field
+- 🔌 First-class **plugin system**
+- 🧩 Optional **middleware integration** (devtools, persist)
+- 🛠 Chainable API: `.extendGetters(...)`, `.extendSetters(...)`, `.restrictState(...)`
+- 👁 Named devtools actions and store labeling
+- 🧼 No runtime dependencies other than Zustand
+
+---
+
+## 📦 Installation
+
+```bash
+npm install zustand zustand-lite
+# or
+pnpm add zustand zustand-lite
+```
+
+---
+
+## 🛠 Basic Usage
+
+```ts
+import { createStore } from 'zustand-lite';
+
+const initialState: {
+  foo: string;
+  bar: {
+    x: number;
+    y: number;
+  }
+} = {
+  foo: '',
+  bar: {
+    x: 0,
+    y: 0,
+  }
+};
+
+export const store = createStore(initialState)
+  .extendGetters(({ get }) => ({
+    area: () => get.bar().x * get.bar().y,
+  }))
+  .extendSetters(({ get, set }) => ({
+    translateX: (dx: number) => set.bar(({ x: get.bar().x + dx, y: get.bar().y })),
+  }))
+  .restrictState(['bar']);
+
+// Usage
+store.use.area();          // React-friendly subscription, re-renders only when area changes.
+store.get.foo();           // Synchronous accessor
+store.set.translateX(2);   // Safe setter
+store.api.getState();      // Native Zustand store API
+```
+
+---
+
+## 🧠 API Overview
+
+### `createStore(initialState, options)`
+
+Creates a typed store with optional plugins and middleware.
+
+**Options:**
+
+| Key          | Type                                                                       | Description                            |
+|--------------|----------------------------------------------------------------------------|----------------------------------------|
+| `name`       | `string`                                                                   | Name shown in Redux DevTools           |
+| `plugins`    | `StoreApiPlugin[]`                                                         | Array of plugins to extend the store   |
+| `middlewares`| `{ devtools?: true or DevtoolsOptions, persist?: true or PersistOptions }` | Middleware configuration               |
+
+---
+
+### Chainable Methods
+
+- **`.extendGetters(fn)`**  
+  Add additional derived getters based on current state.
+
+- **`.extendSetters(fn)`**  
+  Add additional typed setters.
+
+- **`.restrictState(keys?: string[])`**  
+  Hide selected fields from the public API, returning a minimal store (removes config methods as well).
+
+---
+
+### Store Interface
+
+After creation, your store includes:
+
+| Property           | Purpose                                                 |
+|--------------------|---------------------------------------------------------|
+| `store.use.foo()`  | React hook getter for subscribing to `foo`              |
+| `store.get.foo()`  | Direct synchronous access to `foo`                      |
+| `store.set.foo(v)` | Set a new value for `foo`                               |
+| `store.api`        | The native Zustand store API (getState, setState, etc.) |
+
+---
+
+## 🧩 Plugin System
+
+You can define plugins that inject additional state or behavior:
+
+```ts
+import { StoreApiPlugin } from 'zustand-lite';
+
+type Setters = {
+  reset: () => void;
+};
+
+export const reset: StoreApiPlugin<{}, {}, Setters> = {
+  extends: store => {
+    return store.extendSetters(({ api }) => ({
+      reset: () => {
+        const initialState = api.getInitialState?.() ?? {};
+        api.setState(() => initialState, true);
+      },
+    }));
+  },
+};
+```
+
+Apply it like this:
+
+```ts
+const store = createStore({}, { plugins: [reset] });
+```
+
+---
+
+## 🧪 DevTools Integration
+
+You can add the most useful middlewares:
+
+```ts
+{
+  name: 'MyApp/CounterStore',
+  middlewares: {
+    devtools: true,
+    persist: {
+      ...options,
+    },
+  }
+}
+```
+
+---
+
+## 🧱 Built With
+
+- [Zustand](https://github.com/pmndrs/zustand)
+- Inspired by [zustand-x](https://github.com/udecode/zustand-x)
+
+---
+
+## 📘 License
+
+MIT — free to use, extend, and improve.
+
+---
+
+## 🤝 Contributing
+
+Pull requests, feedback, and ideas are welcome!  
+If you'd like to publish your own plugins, we recommend namespacing them under:
+
+```
+zustand-lite/plugin-*
+```
+
+or adding them to the main repository under the plugins directory.
+
+---

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { StoreApiPlugin } from './types';
+export { createStore } from './lib/createStore';
+export { reset } from './plugins/reset';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createStore } from './lib/createStore';
+export { reset } from './plugins/reset';

package/dist/lib/createStore.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Entire zustand-lite no-boilerplate functionality is inspired by this recipe:
+ * https://docs.pmnd.rs/zustand/guides/auto-generating-selectors and 3th party
+ * zustand-x repository: https://github.com/udecode/zustand-x.
+ **/
+import { DevtoolsOptions, PersistOptions } from 'zustand/middleware';
+import { AugmentedApiData, AugmentedGetters, AugmentedSetters, State, StoreApi, StoreApiPluginList } from '../types';
+export declare function createStore<T extends State, Plugins extends StoreApiPluginList = []>(initialState: T, options?: {
+    name?: string;
+    plugins?: [...Plugins];
+    middlewares?: {
+        devtools?: true | DevtoolsOptions;
+        persist?: true | PersistOptions<any>;
+    };
+}): StoreApi<AugmentedApiData<T, Plugins>, AugmentedGetters<Plugins>, AugmentedSetters<Plugins>>;

package/dist/lib/createStore.js

@@ -0,0 +1,56 @@
+/**
+ * Entire zustand-lite no-boilerplate functionality is inspired by this recipe:
+ * https://docs.pmnd.rs/zustand/guides/auto-generating-selectors and 3th party
+ * zustand-x repository: https://github.com/udecode/zustand-x.
+ **/
+import { devtools, persist } from 'zustand/middleware';
+import { createStore as createVanillaStore } from 'zustand/vanilla';
+import { extendGetters } from './extendGetters';
+import { extendSetters } from './extendSetters';
+import { generateStateGet } from './generateStateGet';
+import { generateStateSet } from './generateStateSet';
+import { generateStateUse } from './generateStateUse';
+import { restrictState } from './restrictState';
+export function createStore(initialState, options) {
+    const { name = 'zustand-lite', plugins = [], middlewares = {} } = options ?? {};
+    // Merge state from plugins to be available for future use.
+    let mergedState = initialState;
+    plugins.forEach(plugin => {
+        if (plugin.creates) {
+            mergedState = { ...mergedState, ...plugin.creates() };
+        }
+    });
+    // Apply supported middlewares.
+    let initializer = () => mergedState;
+    if (middlewares.devtools) {
+        initializer = devtools(initializer, middlewares.devtools === true ? { name } : middlewares.devtools);
+    }
+    if (middlewares.persist) {
+        initializer = persist(initializer, middlewares.persist === true ? { name } : middlewares.persist);
+    }
+    // Create a vanilla zustand store to wrap.
+    const storeApi = createVanillaStore(initializer);
+    // Create zustand-lite wrapper.
+    let store = {
+        api: storeApi,
+        get: generateStateGet(storeApi),
+        set: generateStateSet(storeApi, !!middlewares.devtools, name),
+        use: generateStateUse(storeApi),
+        extendGetters(builder) {
+            return extendGetters(builder, this);
+        },
+        extendSetters(builder) {
+            return extendSetters(builder, this);
+        },
+        restrictState(publicState = []) {
+            return restrictState(publicState, mergedState, this);
+        },
+    };
+    // Extend store getters and setters with plugins.
+    plugins.forEach(plugin => {
+        if (plugin.extends) {
+            store = plugin.extends(store);
+        }
+    });
+    return store;
+}

package/dist/lib/extendGetters.d.ts

@@ -0,0 +1,2 @@
+import { Default, GettersBuilder, State, StoreApi } from '../types';
+export declare function extendGetters<Builder extends GettersBuilder<T, Getters, Setters>, T extends State = Default, Getters = Default, Setters = Default>(builder: Builder, thisApi: StoreApi<T, Getters, Setters>): StoreApi<T, Getters & ReturnType<Builder>, Setters>;

package/dist/lib/extendGetters.js

@@ -0,0 +1,23 @@
+import { shallow } from 'zustand/shallow';
+import { useStoreWithEqualityFn } from 'zustand/traditional';
+export function extendGetters(builder, thisApi) {
+    const use = { ...thisApi.use };
+    const get = { ...thisApi.get };
+    Object.keys(builder(thisApi)).forEach(key => {
+        // @ts-ignore
+        use[key] = (...args) => 
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        useStoreWithEqualityFn(thisApi.api, () => {
+            return builder(thisApi)[key](...args);
+        }, shallow);
+        // @ts-ignore
+        get[key] = (...args) => {
+            return builder(thisApi)[key](...args);
+        };
+    });
+    return {
+        ...thisApi,
+        get,
+        use,
+    };
+}

package/dist/lib/extendSetters.d.ts

@@ -0,0 +1,2 @@
+import { Default, SettersBuilder, State, StoreApi } from '../types';
+export declare function extendSetters<Builder extends SettersBuilder<T, Getters, Setters>, T extends State = Default, Getters = Default, Setters = Default>(builder: Builder, thisApi: StoreApi<T, Getters, Setters>): StoreApi<T, Getters, Setters & ReturnType<Builder>>;

package/dist/lib/extendSetters.js

@@ -0,0 +1,9 @@
+export function extendSetters(builder, thisApi) {
+    return {
+        ...thisApi,
+        set: {
+            ...thisApi.set,
+            ...builder(thisApi),
+        },
+    };
+}

package/dist/lib/generateStateGet.d.ts

@@ -0,0 +1,3 @@
+import { StoreApi } from 'zustand/vanilla';
+import { GetRecord, State } from '../types';
+export declare function generateStateGet<T extends State>(api: StoreApi<T>): GetRecord<T>;

package/dist/lib/generateStateGet.js

@@ -0,0 +1,11 @@
+export function generateStateGet(api) {
+    const getters = {};
+    const initialState = api.getState();
+    Object.keys(initialState).forEach(key => {
+        getters[key] = () => api.getState()[key];
+    });
+    Object.getOwnPropertySymbols(initialState).forEach(symbol => {
+        getters[symbol] = () => api.getState()[symbol];
+    });
+    return getters;
+}

package/dist/lib/generateStateSet.d.ts

@@ -0,0 +1,3 @@
+import { StoreApi } from 'zustand/vanilla';
+import { SetRecord, State } from '../types';
+export declare function generateStateSet<T extends State>(api: StoreApi<T>, hasDevtools: boolean, storeName: string): SetRecord<T>;

package/dist/lib/generateStateSet.js

@@ -0,0 +1,16 @@
+export function generateStateSet(api, hasDevtools, storeName) {
+    const setters = {};
+    Object.keys(api.getState()).forEach(key => {
+        setters[key] = (value) => {
+            if (api.getState()[key] === value) {
+                return;
+            }
+            const setState = api.setState;
+            setState(state => ({
+                ...state,
+                [key]: value,
+            }), false, hasDevtools ? { type: `${storeName}/${key}`, payload: { [key]: value } } : undefined);
+        };
+    });
+    return setters;
+}

package/dist/lib/generateStateUse.d.ts

@@ -0,0 +1,3 @@
+import { StoreApi } from 'zustand';
+import { GetRecord, State } from '../types';
+export declare function generateStateUse<T extends State>(api: StoreApi<T>): GetRecord<T>;

package/dist/lib/generateStateUse.js

@@ -0,0 +1,12 @@
+import { shallow } from 'zustand/shallow';
+import { useStoreWithEqualityFn } from 'zustand/traditional';
+export function generateStateUse(api) {
+    const getters = {};
+    Object.keys(api.getState()).forEach(key => {
+        getters[key] = (equalityFn = shallow) => {
+            // eslint-disable-next-line react-hooks/rules-of-hooks
+            return useStoreWithEqualityFn(api, (state) => state[key], equalityFn);
+        };
+    });
+    return getters;
+}

package/dist/lib/restrictState.d.ts

@@ -0,0 +1,2 @@
+import { Empty, GetRecord, SetRecord, State, StoreApi, StoreApiEncapsulated } from '../types';
+export declare function restrictState<T extends State, Key extends keyof T, Getters extends GetRecord<any> = Empty, Setters extends SetRecord<any> = Empty>(privateState: Key[], mergedState: T, thisApi: StoreApi<T, Getters, Setters>): StoreApiEncapsulated<Omit<T, Key>, Getters, Setters>;

package/dist/lib/restrictState.js

@@ -0,0 +1,13 @@
+export function restrictState(privateState, mergedState, thisApi) {
+    return {
+        api: thisApi.api,
+        set: thisApi.set,
+        use: thisApi.use,
+        get: Object.keys(thisApi.get).reduce((acc, key) => mergedState[key] && privateState.includes(key)
+            ? acc
+            : {
+                ...acc,
+                [key]: thisApi.get[key],
+            }, {}),
+    };
+}

package/dist/plugins/reset.d.ts

@@ -0,0 +1,6 @@
+import { StoreApiPlugin } from '../types';
+type PluginResetSetters = {
+    reset: () => void;
+};
+export declare const reset: StoreApiPlugin<{}, {}, PluginResetSetters>;
+export {};

package/dist/plugins/reset.js

@@ -0,0 +1,10 @@
+export const reset = {
+    extends: store => {
+        return store.extendSetters(({ api }) => ({
+            reset: () => {
+                const initialState = api.getInitialState?.() ?? {};
+                api.setState(() => initialState, true);
+            },
+        }));
+    },
+};

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+import { StoreApi as StoreApiLib } from 'zustand';
+export type State = Record<string | symbol, unknown>;
+export type Empty = Record<string, never>;
+export type Default = Record<string | symbol, any>;
+export type EqualityChecker<T> = (state: T, newState: T) => boolean;
+export type StoreApiGet<T extends State, Getters> = Required<GetRecord<T>> & Getters;
+export type StoreApiUse<T extends State, Getters> = Required<UseRecord<T>> & Getters;
+export type StoreApiSet<T extends State, Setters> = Required<SetRecord<T>> & Setters;
+export type StoreApiEncapsulated<T extends State = Empty, Getters = Default, Setters = Default> = {
+    api: StoreApiLib<T>;
+    get: StoreApiGet<T, Getters>;
+    set: StoreApiSet<T, Setters>;
+    use: StoreApiUse<T, Getters>;
+};
+export type StoreApi<T extends State = Empty, Getters = Default, Setters = Default> = {
+    api: StoreApiLib<T>;
+    get: StoreApiGet<T, Getters>;
+    set: StoreApiSet<T, Setters>;
+    use: StoreApiUse<T, Getters>;
+    extendGetters<Builder extends GettersBuilder<T, Getters, Setters>>(builder: Builder): StoreApi<T, Getters & ReturnType<Builder>, Setters>;
+    extendSetters<Builder extends SettersBuilder<T, Getters, Setters>>(builder: Builder): StoreApi<T, Getters, Setters & ReturnType<Builder>>;
+    restrictState(): StoreApiEncapsulated<T, Getters, Setters>;
+    restrictState<Key extends keyof T>(publicState: Key[]): StoreApiEncapsulated<Pick<T, Key>, Getters, Setters>;
+};
+export type GettersBuilder<T extends State, Getters = Default, Setters = Default> = (args: {
+    api: StoreApiLib<T>;
+    get: StoreApiGet<T, Getters>;
+    set: StoreApiSet<T, Setters>;
+}) => Record<string, (...args: any[]) => {} | null>;
+export type SettersBuilder<T extends State, Getters = Default, Setters = Default> = (args: {
+    api: StoreApiLib<T>;
+    get: StoreApiGet<T, Getters>;
+    set: StoreApiSet<T, Setters>;
+}) => Record<string, (...args: any[]) => void>;
+export type GetRecord<O extends Record<string, any>> = {
+    [K in keyof O]: () => O[K];
+};
+export type UseRecord<O extends Record<string, any>> = {
+    [K in keyof O]: (equalityFn?: EqualityChecker<O[K]>) => O[K];
+};
+export type SetRecord<O extends Record<string, any>> = {
+    [K in keyof O]: (value: O[K]) => void;
+};
+export type StoreApiPlugin<NewApiData extends State, NewGetters, NewSetters> = {
+    creates?: () => NewApiData;
+    extends?: (store: StoreApi<NewApiData, NewGetters, NewSetters>) => StoreApi<NewApiData, NewGetters, NewSetters>;
+};
+export type StoreApiPluginList = StoreApiPlugin<any, any, any>[];
+export type AugmentedApiData<T, Plugins extends StoreApiPluginList> = T & UnionToIntersection<ExtractPluginTypes<Plugins, 'create'>[number]>;
+export type AugmentedGetters<Plugins extends StoreApiPluginList> = UnionToIntersection<ExtractPluginTypes<Plugins, 'extend'>[number]['getters']>;
+export type AugmentedSetters<Plugins extends StoreApiPluginList> = UnionToIntersection<ExtractPluginTypes<Plugins, 'extend'>[number]['setters']>;
+type ExtractPluginTypes<Plugins extends StoreApiPluginList, Key extends 'create' | 'extend'> = {
+    [K in keyof Plugins]: Plugins[K] extends StoreApiPlugin<infer S, infer G, infer A> ? Key extends 'create' ? S : Key extends 'extend' ? {
+        getters: G;
+        setters: A;
+    } : never : never;
+};
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "zustand-lite",
+  "version": "0.1.2",
+  "description": "Zustand Lite builds upon zustand, by auto-generating selectors and simplifying API even more.",
+  "main": "dist/index.js",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/PiotrSiatkowski/zustand-lite.git",
+    "web": "https://github.com/PiotrSiatkowski/zustand-lite"
+  },
+  "author": "Piotr Siatkowski <p.siatkowski@gmail.com>",
+  "keywords": [
+    "zustand",
+    "state-management",
+    "react",
+    "store",
+    "plugin",
+    "typescript",
+    "no-boilerplate"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zustand": "^5.0.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.3"
+  },
+  "private": false
+}