unistash 2.0.0

package/README.md

@@ -0,0 +1,50 @@
+# unistash
+
+**Write once. Stash anywhere.** A tiny, typed, zero-dependency React state library.
+
+```bash
+npm install unistash
+```
+
+```tsx
+import { createStore } from "unistash";
+
+const useCounter = createStore({
+  state: { count: 0 },
+  actions: {
+    increment: (s) => ({ count: s.count + 1 }),
+    add: (s, n: number) => ({ count: s.count + n }),
+  },
+  computed: {
+    doubled: (s) => s.count * 2,
+  },
+});
+
+function Counter() {
+  const { count, doubled, increment } = useCounter();
+  return <button onClick={() => increment()}>{count} ({doubled})</button>;
+}
+```
+
+## Selectors
+
+```tsx
+// re-renders only when `count` changes
+const count = useCounter((s) => s.count);
+
+// custom equality
+import { shallow } from "unistash";
+const { a, b } = useCounter((s) => ({ a: s.count, b: s.doubled }), shallow);
+```
+
+## Imperative API
+
+```ts
+useCounter.getState();
+useCounter.setState({ count: 5 });
+const unsubscribe = useCounter.subscribe((snapshot) => {
+  /* ... */
+});
+```
+
+Requires React 18 or 19 (peer dependency). Zero runtime dependencies.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createStore } from "./react/createStore";
+export { shallow } from "./shallow";
+export type { ActionFn, BoundActions, ComputedFn, ComputedReturns, Snapshot, StoreConfig, StoreHook, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,eAAe,EACf,QAAQ,EACR,WAAW,EACX,SAAS,GACV,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createStore } from "./react/createStore";
+export { shallow } from "./shallow";

package/dist/react/createStore.d.ts

@@ -0,0 +1,7 @@
+import type { StoreHook } from "../types";
+export declare function createStore<TState extends object, TActions extends Record<string, (state: TState, ...args: never[]) => Partial<TState>>, TComputed extends Record<string, (state: TState) => unknown>>(config: {
+    state: TState;
+    actions?: TActions;
+    computed?: TComputed;
+}): StoreHook<TState, TActions, TComputed>;
+//# sourceMappingURL=createStore.d.ts.map

package/dist/react/createStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createStore.d.ts","sourceRoot":"","sources":["../../src/react/createStore.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAY,SAAS,EAAE,MAAM,UAAU,CAAC;AAGpD,wBAAgB,WAAW,CACzB,MAAM,SAAS,MAAM,EACrB,QAAQ,SAAS,MAAM,CACrB,MAAM,EACN,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CACrD,EACD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,EAC5D,MAAM,EAAE;IACR,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB,GAAG,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,CA6DzC"}

package/dist/react/createStore.js

@@ -0,0 +1,32 @@
+import { useRef, useSyncExternalStore } from "react";
+import { createVanillaStore } from "../vanilla/store";
+export function createStore(config) {
+    // The vanilla store is internally loosely typed; we apply the real types here.
+    const store = createVanillaStore(config);
+    const identity = (snapshot) => snapshot;
+    function useStore(selector = identity, equalityFn = Object.is) {
+        // Per-component memo so the value handed to useSyncExternalStore is
+        // referentially stable when the selected slice is unchanged.
+        const memo = useRef(null);
+        const getSelection = (snapshot) => {
+            const cached = memo.current;
+            if (cached && cached.snapshot === snapshot) {
+                return cached.selection;
+            }
+            const next = selector(snapshot);
+            if (cached && equalityFn(cached.selection, next)) {
+                // Keep the previous selection reference; just advance the snapshot pointer.
+                memo.current = { snapshot, selection: cached.selection };
+                return cached.selection;
+            }
+            memo.current = { snapshot, selection: next };
+            return next;
+        };
+        return useSyncExternalStore(store.subscribe, () => getSelection(store.getSnapshot()), () => getSelection(store.getServerSnapshot()));
+    }
+    const hook = useStore;
+    hook.getState = store.getState;
+    hook.setState = store.setState;
+    hook.subscribe = store.subscribe;
+    return hook;
+}

package/dist/shallow.d.ts

@@ -0,0 +1,2 @@
+export declare function shallow<T>(a: T, b: T): boolean;
+//# sourceMappingURL=shallow.d.ts.map

package/dist/shallow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shallow.d.ts","sourceRoot":"","sources":["../src/shallow.ts"],"names":[],"mappings":"AAAA,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CA4B9C"}

package/dist/shallow.js

@@ -0,0 +1,23 @@
+export function shallow(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" ||
+        a === null ||
+        typeof b !== "object" ||
+        b === null) {
+        return false;
+    }
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const key of keysA) {
+        if (
+        // biome-ignore lint/suspicious/noPrototypeBuiltins: Object.hasOwn is ES2022; this package targets ES2020
+        !Object.prototype.hasOwnProperty.call(b, key) ||
+            !Object.is(a[key], b[key])) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/** An action: receives current state plus args, returns a partial to shallow-merge. */
+export type ActionFn<TState> = (state: TState, ...args: never[]) => Partial<TState>;
+/** A computed selector: derives a value from state. */
+export type ComputedFn<TState> = (state: TState) => unknown;
+/** Configuration passed to createStore. */
+export interface StoreConfig<TState extends object, TActions extends Record<string, ActionFn<TState>>, TComputed extends Record<string, ComputedFn<TState>>> {
+    state: TState;
+    actions?: TActions;
+    computed?: TComputed;
+}
+/** Strips the leading `state` param from each action: (state, ...args) => P  ->  (...args) => void. */
+export type BoundActions<TActions> = {
+    [K in keyof TActions]: TActions[K] extends (state: never, ...args: infer P) => unknown ? (...args: P) => void : never;
+};
+/** Maps each computed fn to its return type. */
+export type ComputedReturns<TComputed> = {
+    [K in keyof TComputed]: TComputed[K] extends (state: never) => infer R ? R : never;
+};
+/** The merged value the hook returns / the selector receives. */
+export type Snapshot<TState, TActions, TComputed> = TState & ComputedReturns<TComputed> & BoundActions<TActions>;
+/** The hook returned by createStore: bare call + selector overload + imperative statics. */
+export interface StoreHook<TState extends object, TActions, TComputed> {
+    (): Snapshot<TState, TActions, TComputed>;
+    <U>(selector: (snapshot: Snapshot<TState, TActions, TComputed>) => U, equalityFn?: (a: U, b: U) => boolean): U;
+    getState: () => TState;
+    setState: (partial: Partial<TState> | ((state: TState) => Partial<TState>)) => void;
+    subscribe: (listener: (snapshot: Snapshot<TState, TActions, TComputed>) => void) => () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,MAAM,MAAM,QAAQ,CAAC,MAAM,IAAI,CAC7B,KAAK,EAAE,MAAM,EACb,GAAG,IAAI,EAAE,KAAK,EAAE,KACb,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB,uDAAuD;AACvD,MAAM,MAAM,UAAU,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAE5D,2CAA2C;AAC3C,MAAM,WAAW,WAAW,CAC1B,MAAM,SAAS,MAAM,EACrB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,EACjD,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAEpD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,uGAAuG;AACvG,MAAM,MAAM,YAAY,CAAC,QAAQ,IAAI;KAClC,CAAC,IAAI,MAAM,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,SAAS,CACzC,KAAK,EAAE,KAAK,EACZ,GAAG,IAAI,EAAE,MAAM,CAAC,KACb,OAAO,GACR,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,GACpB,KAAK;CACV,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,eAAe,CAAC,SAAS,IAAI;KACtC,CAAC,IAAI,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,CAAC,GAClE,CAAC,GACD,KAAK;CACV,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,IAAI,MAAM,GACxD,eAAe,CAAC,SAAS,CAAC,GAC1B,YAAY,CAAC,QAAQ,CAAC,CAAC;AAEzB,4FAA4F;AAC5F,MAAM,WAAW,SAAS,CAAC,MAAM,SAAS,MAAM,EAAE,QAAQ,EAAE,SAAS;IACnE,IAAI,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC,CAAC,EACA,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,KAAK,CAAC,EAChE,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,GACnC,CAAC,CAAC;IACL,QAAQ,EAAE,MAAM,MAAM,CAAC;IACvB,QAAQ,EAAE,CACR,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,KAC5D,IAAI,CAAC;IACV,SAAS,EAAE,CACT,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC,KAAK,IAAI,KAChE,MAAM,IAAI,CAAC;CACjB"}

package/dist/types.js

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

package/dist/vanilla/store.d.ts

@@ -0,0 +1,16 @@
+type AnyState = Record<string, unknown>;
+export interface VanillaStore<TSnapshot> {
+    getState: () => AnyState;
+    setState: (partial: AnyState | ((state: AnyState) => AnyState)) => void;
+    subscribe: (listener: (snapshot: TSnapshot) => void) => () => void;
+    getSnapshot: () => TSnapshot;
+    getServerSnapshot: () => TSnapshot;
+}
+export interface VanillaConfig {
+    state: AnyState;
+    actions?: Record<string, (state: AnyState, ...args: unknown[]) => AnyState>;
+    computed?: Record<string, (state: AnyState) => unknown>;
+}
+export declare function createVanillaStore<TSnapshot = AnyState>(config: VanillaConfig): VanillaStore<TSnapshot>;
+export {};
+//# sourceMappingURL=store.d.ts.map

package/dist/vanilla/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/vanilla/store.ts"],"names":[],"mappings":"AAAA,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAExC,MAAM,WAAW,YAAY,CAAC,SAAS;IACrC,QAAQ,EAAE,MAAM,QAAQ,CAAC;IACzB,QAAQ,EAAE,CAAC,OAAO,EAAE,QAAQ,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,QAAQ,CAAC,KAAK,IAAI,CAAC;IACxE,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IACnE,WAAW,EAAE,MAAM,SAAS,CAAC;IAC7B,iBAAiB,EAAE,MAAM,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC;CACzD;AAsBD,wBAAgB,kBAAkB,CAAC,SAAS,GAAG,QAAQ,EACrD,MAAM,EAAE,aAAa,GACpB,YAAY,CAAC,SAAS,CAAC,CAwDzB"}

package/dist/vanilla/store.js

@@ -0,0 +1,65 @@
+function assertNoCollisions(config) {
+    const seen = new Set();
+    const groups = [
+        ["state", Object.keys(config.state)],
+        ["computed", config.computed ? Object.keys(config.computed) : []],
+        ["actions", config.actions ? Object.keys(config.actions) : []],
+    ];
+    for (const [, keys] of groups) {
+        for (const key of keys) {
+            if (seen.has(key)) {
+                throw new Error(`unistash: key "${key}" collides across state/computed/actions. ` +
+                    `State, computed, and action names must be unique.`);
+            }
+            seen.add(key);
+        }
+    }
+}
+export function createVanillaStore(config) {
+    assertNoCollisions(config);
+    let state = { ...config.state };
+    const listeners = new Set();
+    // Bound actions are created once and reused (stable references).
+    const boundActions = {};
+    if (config.actions) {
+        for (const key of Object.keys(config.actions)) {
+            const fn = config.actions[key];
+            boundActions[key] = (...args) => {
+                setState(fn(state, ...args));
+            };
+        }
+    }
+    function buildSnapshot() {
+        const computedValues = {};
+        if (config.computed) {
+            for (const key of Object.keys(config.computed)) {
+                computedValues[key] = config.computed[key](state);
+            }
+        }
+        return {
+            ...state,
+            ...computedValues,
+            ...boundActions,
+        };
+    }
+    let snapshot = buildSnapshot();
+    const serverSnapshot = snapshot; // stable reference for SSR
+    const getState = () => state;
+    function setState(partial) {
+        const next = typeof partial === "function" ? partial(state) : partial;
+        state = { ...state, ...next };
+        snapshot = buildSnapshot();
+        for (const listener of listeners) {
+            listener(snapshot);
+        }
+    }
+    const subscribe = (listener) => {
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    };
+    const getSnapshot = () => snapshot;
+    const getServerSnapshot = () => serverSnapshot;
+    return { getState, setState, subscribe, getSnapshot, getServerSnapshot };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "unistash",
+  "version": "2.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Write once. Stash anywhere. A tiny, typed, zero-dependency React state library.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "unistash",
+    "state-management",
+    "react",
+    "store",
+    "typescript",
+    "hooks",
+    "zero-dependency"
+  ],
+  "author": "ShobhitPatra<shobhitpatra.dev@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ShobhitPatra/unistash",
+    "directory": "packages/unistash"
+  },
+  "homepage": "https://unistash-seven.vercel.app",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "typescript": "^5.0.0",
+    "@unistash/tsconfig": "0.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}