@plitzi/nexus 0.32.0 → 0.32.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @plitzi/nexus
 
+## 0.32.1
+
+### Patch Changes
+
+- v0.32.1
+
 ## 0.32.0
 
 ### Minor Changes

package/README.md

@@ -22,26 +22,51 @@ function Counter() {
 }
 ```
 
+## The whole imperative API in three verbs
+
+Outside React, a store speaks three words. `get`, `set` and `watch` are typed against your state and cover the common case — the longer `getState` / `getPath` / `subscribePath` names stay for advanced reads (default values) and back-compat.
+
+```ts
+import { createStore } from '@plitzi/nexus';
+
+const store = createStore<State>({ count: 0, user: { name: 'Carlos' } });
+
+store.get('user.name');                 // 'Carlos'  (one path, no full merge)
+store.get();                            // entire state
+store.set('user.name', 'Ada');          // typed dot-path write
+store.set('count', n => n + 1);         // updater form
+const off = store.watch('user.name', name => render(name)); // fires only for this path
+```
+
 ## What each piece is for
 
+### Core — the 90%
+
 | Import | What it's for |
 |---|---|
-| `createStore` | Create a vanilla store (no React needed). |
+| `createStore` | Create a vanilla store (no React needed). Exposes `get` / `set` / `watch`. |
 | `createStoreHook<T>()` | Bind your state type once → fully-typed `useStore*` hooks. |
 | `StoreProvider` | Put a store on React context; optionally scope/sync/record it. |
 | `useStore` | Subscribe + write a path (or paths). Re-renders on change only. |
+
+### Advanced — reach for it when you need it
+
+Also importable from the focused `@plitzi/nexus/advanced` entry point, which keeps root autocomplete on the Core.
+
+| Import | What it's for |
+|---|---|
 | `useStoreSetter` | A stable setter — write without subscribing/re-rendering. |
 | `useStoreGetter` | A stable getter — read current values in callbacks, no re-render. |
 | `useStoreById` | Get a named ancestor store's `StoreApi` by `id` (reachable across disconnected providers). |
 | `useStoreSync` | Mirror an external value (props) **into** the store. |
 | `createDerived` / `useDerived` | A memoized value computed from store paths (reselect-style). |
-| `createEntityAdapter` | CRUD updaters + selectors for a normalized `Record<id, T>` map. |
+| `createEntityAdapter` / `createEntityStore` | CRUD + selectors for a normalized `Record<id, T>` map; the store variant adds O(1) per-item updates. |
+| `createAsync` / `useAsync` / `useAsyncValue` | Race-safe fetch landed on a path; inline UI or Suspense. |
 | `loggerMiddleware` / `persistMiddleware` / `historyMiddleware` / `reduxDevToolsMiddleware` | Middlewares: log, persist to storage, record time-travel, connect to Redux DevTools. |
+| `getStoreHistory` / `useStoreHistory` | Undo / redo / jump-to-snapshot action log (enabled by `historyMiddleware`). |
 | `setCodegenEnabled` | Force on/off the `new Function` codegen path (auto-detects CSP/SSR). |
-| `createServerSnapshot` | Mark server-fetched data for RSC → Client handoff. |
-| `isServerSnapshot` | Check if a value has the SSR marker flag. |
+| `createServerSnapshot` / `isServerSnapshot` | Mark server-fetched data for RSC → Client handoff, and check the marker. |
 | `bindServerAction` | Optimistic updates + revalidation for Next.js Server Actions. |
-| `getStoreHistory` / `useStoreHistory` | Undo / redo / jump-to-snapshot action log (enabled by `historyMiddleware`). |
 
 ## Architecture
 

package/dist/advanced/index.d.ts

@@ -0,0 +1,7 @@
+export { default as useStoreById } from '../createStore/hooks/useStoreById';
+export { default as useStoreSetter } from '../createStore/hooks/useStoreSetter';
+export * from '../async';
+export * from '../derived';
+export * from '../entities';
+export * from '../history';
+export * from '../middleware';

package/dist/advanced/index.mjs

@@ -0,0 +1,16 @@
+import e from "../createStore/hooks/useStoreById.mjs";
+import t from "../createStore/hooks/useStoreSetter.mjs";
+import { createAsync as n } from "../async/createAsync.mjs";
+import { useAsync as r } from "../async/hooks/useAsync.mjs";
+import { useAsyncValue as i } from "../async/hooks/useAsyncValue.mjs";
+import { createDerived as a } from "../derived/createDerived.mjs";
+import { useDerived as o } from "../derived/hooks/useDerived.mjs";
+import { createEntityAdapter as s } from "../entities/createEntityAdapter.mjs";
+import { createEntityStore as c } from "../entities/createEntityStore.mjs";
+import { getStoreHistory as l, historyMiddleware as u } from "../middleware/historyMiddleware.mjs";
+import { useStoreHistory as d } from "../history/hooks/useStoreHistory.mjs";
+import { loggerMiddleware as f } from "../middleware/loggerMiddleware.mjs";
+import { persistMiddleware as p } from "../middleware/persistMiddleware.mjs";
+import { reduxDevToolsMiddleware as m } from "../middleware/reduxDevToolsMiddleware.mjs";
+import { cascade as h } from "../middleware/cascade.mjs";
+export { h as cascade, n as createAsync, a as createDerived, s as createEntityAdapter, c as createEntityStore, l as getStoreHistory, u as historyMiddleware, f as loggerMiddleware, p as persistMiddleware, m as reduxDevToolsMiddleware, r as useAsync, i as useAsyncValue, o as useDerived, e as useStoreById, d as useStoreHistory, t as useStoreSetter };

package/dist/createStore/createStore.mjs

@@ -1,17 +1,17 @@
-import { createChainReads as e } from "./helpers/createChainReads.mjs";
-import { createSetState as t } from "./helpers/createSetState.mjs";
-import { forwardParentChanges as n } from "./helpers/forwardParentChanges.mjs";
-import r from "./helpers/Subscribers.mjs";
-import i from "./helpers/PathTrie.mjs";
+import e from "./hooks/useStoreSetter.mjs";
+import t from "./helpers/Subscribers.mjs";
+import { createChainReads as n } from "./helpers/createChainReads.mjs";
+import { createSetState as r } from "./helpers/createSetState.mjs";
+import { forwardParentChanges as i } from "./helpers/forwardParentChanges.mjs";
+import a from "./helpers/PathTrie.mjs";
 import "./helpers/scopeCollisions.mjs";
-import a from "./hooks/useStore.mjs";
-import o from "./hooks/useStoreGetter.mjs";
-import s from "./hooks/useStoreSetter.mjs";
+import o from "./hooks/useStore.mjs";
+import s from "./hooks/useStoreGetter.mjs";
 import c from "./hooks/useStoreSync.mjs";
 //#region src/createStore/createStore.ts
 var l = 0;
-function u(a, o) {
-	let s = {}, c, u = new r(), d = new r(), f = new i(), p = new r(), m = () => {
+function u(e, o) {
+	let s = {}, c, u = new t(), d = new t(), f = new a(), p = new t(), m = () => {
 		p.length !== 0 && p.forEach((e) => e());
 	}, h = [], g = [], _ = [], v = o?.parent;
 	++l;
@@ -23,11 +23,11 @@ function u(a, o) {
 			path: n
 		};
 		for (let e = 0, t = g.length; e < t; e++) g[e](r);
-	}, b = () => s, x = () => c ??= { ...s }, { getState: S, getPath: C, invalidate: w, resetCache: T, getMergeCount: E } = e(b, x, v), D = () => {
+	}, b = () => s, x = () => c ??= { ...s }, { getState: S, getPath: C, invalidate: w, resetCache: T, getMergeCount: E } = n(b, x, v), D = () => {
 		w(), m();
 	}, O, k, A = !1;
 	v && (T(), k = v.subscribeInvalidate?.(D));
-	let { setState: j, batch: M } = t({
+	let { setState: j, batch: M } = r({
 		getOwnState: b,
 		getOwnSnapshot: x,
 		setOwnState: (e) => {
@@ -45,7 +45,7 @@ function u(a, o) {
 		invalidateDescendants: m,
 		onDelegateToParent: void 0
 	}), N = () => u.length > 0 || f.size > 0 || d.length > 0, P = () => {
-		O || !v || (w(), T(), O = n(v, u, f, d, S, y, w), d.length > 0 && O.seedBaseline());
+		O || !v || (w(), T(), O = i(v, u, f, d, S, y, w), d.length > 0 && O.seedBaseline());
 	}, F = () => {
 		O && (O.unsubscribe(), O = void 0, T());
 	}, I = () => {
@@ -56,25 +56,34 @@ function u(a, o) {
 		let t = L(d.add(e));
 		return O?.seedBaseline(), t;
 	};
-	s = typeof a == "function" ? a(j, S) : a;
+	s = typeof e == "function" ? e(j, S) : e;
 	let V = {
 		id: o?.id,
 		getState: S,
 		getPath: C,
 		setState: j,
-		withBase: (e) => ({
-			getState: (t) => {
-				let n = C(e);
-				return n === void 0 && t !== void 0 ? t : n;
-			},
-			getPath: (t, n) => {
-				let r = C(`${e}.${t}`);
-				return r === void 0 && n !== void 0 ? n : r;
-			},
-			setState: (t, n) => j(t === void 0 ? e : `${e}.${t}`, n),
-			subscribe: (t) => z(e, t),
-			subscribePath: (t, n) => z(`${e}.${t}`, n)
-		}),
+		get: ((e) => e === void 0 ? S() : C(e)),
+		set: j,
+		watch: ((e, t) => typeof e == "function" ? R(e) : z(e, t)),
+		withBase: (e) => {
+			let t = (t, n) => j(t === void 0 ? e : `${e}.${t}`, n);
+			return {
+				getState: (t) => {
+					let n = C(e);
+					return n === void 0 && t !== void 0 ? t : n;
+				},
+				getPath: (t, n) => {
+					let r = C(`${e}.${t}`);
+					return r === void 0 && n !== void 0 ? n : r;
+				},
+				setState: t,
+				subscribe: (t) => z(e, t),
+				subscribePath: (t, n) => z(`${e}.${t}`, n),
+				get: (t) => C(t === void 0 ? e : `${e}.${t}`),
+				set: t,
+				watch: (t, n) => typeof t == "function" ? z(e, t) : z(`${e}.${t}`, n)
+			};
+		},
 		batch: M,
 		subscribe: R,
 		subscribePath: z,
@@ -99,23 +108,23 @@ function u(a, o) {
 	return V;
 }
 var d = () => {
-	function e(e, t) {
-		return a(e, t);
+	function t(e, t) {
+		return o(e, t);
 	}
-	function t(e, t, n) {
+	function n(e, t, n) {
 		c(e, t, n);
 	}
-	function n(e, t) {
-		return o(e, t);
-	}
 	function r(e, t) {
 		return s(e, t);
 	}
+	function i(t, n) {
+		return e(t, n);
+	}
 	return {
-		useStore: e,
-		useStoreSync: t,
-		useStoreGetter: n,
-		useStoreSetter: r
+		useStore: t,
+		useStoreSync: n,
+		useStoreGetter: r,
+		useStoreSetter: i
 	};
 };
 //#endregion

package/dist/createStore/helpers/createChainReads.mjs

@@ -1,19 +1,19 @@
-import { deepMerge as e, isPlainObject as t } from "./deepMerge.mjs";
-import n from "../../helpers/getByPath.mjs";
+import e from "../../helpers/getByPath.mjs";
+import { deepMerge as t, isPlainObject as n } from "./deepMerge.mjs";
 //#region src/createStore/helpers/createChainReads.ts
 function r(r, i, a) {
 	if (!a) return {
 		getState: i,
-		getPath: (e) => n(r(), e),
+		getPath: (t) => e(r(), t),
 		invalidate: () => {},
 		resetCache: () => {},
 		getMergeCount: () => 0
 	};
-	let o = a, s = !0, c = !1, l, u = 0, d = /* @__PURE__ */ new Map(), f = () => (u++, e(o.getState(), i())), p = () => ((s || l === void 0) && (l = f(), s = !1), l), m = (e) => {
-		let i = n(r(), e);
-		if (i === void 0) return o.getPath(e);
-		let a = o.getPath(e);
-		return a === void 0 || !t(i) || !t(a) ? i : n(p(), e);
+	let o = a, s = !0, c = !1, l, u = 0, d = /* @__PURE__ */ new Map(), f = () => (u++, t(o.getState(), i())), p = () => ((s || l === void 0) && (l = f(), s = !1), l), m = (t) => {
+		let i = e(r(), t);
+		if (i === void 0) return o.getPath(t);
+		let a = o.getPath(t);
+		return a === void 0 || !n(i) || !n(a) ? i : e(p(), t);
 	};
 	return {
 		getState: p,

package/dist/index.d.ts

@@ -2,16 +2,17 @@ import { default as createStore } from './createStore';
 import { default as useStoreById } from './createStore/hooks/useStoreById';
 import { default as useStoreSetter } from './createStore/hooks/useStoreSetter';
 import { default as StoreProvider } from './StoreProvider';
-export * from './async';
 export * from './createStore';
+export * from './StoreProvider';
+export * from './types';
+export { createStore, StoreProvider };
+export * from './async';
 export * from './derived';
 export * from './entities';
 export * from './history';
 export * from './middleware';
-export * from './StoreProvider';
 export * from './createStore/hooks/useStoreSetter';
 export * from './createStore/hooks/useStoreById';
-export * from './types';
-export { createStore, StoreProvider, useStoreById, useStoreSetter };
+export { useStoreById, useStoreSetter };
 export { setCodegenEnabled } from './createStore/helpers/writeByPath';
 export { createServerSnapshot, isServerSnapshot } from './rsc';

package/dist/index.mjs

@@ -1,23 +1,23 @@
-import { createAsync as e } from "./async/createAsync.mjs";
-import { useAsync as t } from "./async/hooks/useAsync.mjs";
-import { useAsyncValue as n } from "./async/hooks/useAsyncValue.mjs";
-import { setCodegenEnabled as r } from "./createStore/helpers/writeByPath.mjs";
-import { CANCEL as i } from "./types/StoreTypes.mjs";
-import { StoreContext as a, StoreRegistryContext as o } from "./StoreContext.mjs";
-import s from "./createStore/hooks/useStoreSetter.mjs";
-import { createStoreHook as c } from "./createStore/createStore.mjs";
-import l from "./createStore/index.mjs";
-import { createDerived as u } from "./derived/createDerived.mjs";
-import { useDerived as d } from "./derived/hooks/useDerived.mjs";
-import { createEntityAdapter as f } from "./entities/createEntityAdapter.mjs";
-import { createEntityStore as p } from "./entities/createEntityStore.mjs";
-import { getStoreHistory as m, historyMiddleware as h } from "./middleware/historyMiddleware.mjs";
-import { useStoreHistory as g } from "./history/hooks/useStoreHistory.mjs";
-import _ from "./createStore/hooks/useStoreById.mjs";
-import { createServerSnapshot as v, isServerSnapshot as y } from "./rsc/index.mjs";
-import b from "./StoreProvider.mjs";
-import { loggerMiddleware as x } from "./middleware/loggerMiddleware.mjs";
-import { persistMiddleware as S } from "./middleware/persistMiddleware.mjs";
-import { reduxDevToolsMiddleware as C } from "./middleware/reduxDevToolsMiddleware.mjs";
-import { cascade as w } from "./middleware/cascade.mjs";
-export { i as CANCEL, a as StoreContext, b as StoreProvider, o as StoreRegistryContext, w as cascade, e as createAsync, u as createDerived, f as createEntityAdapter, p as createEntityStore, v as createServerSnapshot, l as createStore, c as createStoreHook, m as getStoreHistory, h as historyMiddleware, y as isServerSnapshot, x as loggerMiddleware, S as persistMiddleware, C as reduxDevToolsMiddleware, r as setCodegenEnabled, t as useAsync, n as useAsyncValue, d as useDerived, _ as useStoreById, g as useStoreHistory, s as useStoreSetter };
+import { StoreContext as e, StoreRegistryContext as t } from "./StoreContext.mjs";
+import n from "./createStore/hooks/useStoreById.mjs";
+import r from "./createStore/hooks/useStoreSetter.mjs";
+import { createAsync as i } from "./async/createAsync.mjs";
+import { useAsync as a } from "./async/hooks/useAsync.mjs";
+import { useAsyncValue as o } from "./async/hooks/useAsyncValue.mjs";
+import { createDerived as s } from "./derived/createDerived.mjs";
+import { useDerived as c } from "./derived/hooks/useDerived.mjs";
+import { createEntityAdapter as l } from "./entities/createEntityAdapter.mjs";
+import { createEntityStore as u } from "./entities/createEntityStore.mjs";
+import { getStoreHistory as d, historyMiddleware as f } from "./middleware/historyMiddleware.mjs";
+import { useStoreHistory as p } from "./history/hooks/useStoreHistory.mjs";
+import { loggerMiddleware as m } from "./middleware/loggerMiddleware.mjs";
+import { persistMiddleware as h } from "./middleware/persistMiddleware.mjs";
+import { reduxDevToolsMiddleware as g } from "./middleware/reduxDevToolsMiddleware.mjs";
+import { cascade as _ } from "./middleware/cascade.mjs";
+import { setCodegenEnabled as v } from "./createStore/helpers/writeByPath.mjs";
+import { CANCEL as y } from "./types/StoreTypes.mjs";
+import { createStoreHook as b } from "./createStore/createStore.mjs";
+import x from "./createStore/index.mjs";
+import { createServerSnapshot as S, isServerSnapshot as C } from "./rsc/index.mjs";
+import w from "./StoreProvider.mjs";
+export { y as CANCEL, e as StoreContext, w as StoreProvider, t as StoreRegistryContext, _ as cascade, i as createAsync, s as createDerived, l as createEntityAdapter, u as createEntityStore, S as createServerSnapshot, x as createStore, b as createStoreHook, d as getStoreHistory, f as historyMiddleware, C as isServerSnapshot, m as loggerMiddleware, h as persistMiddleware, g as reduxDevToolsMiddleware, v as setCodegenEnabled, a as useAsync, o as useAsyncValue, c as useDerived, n as useStoreById, p as useStoreHistory, r as useStoreSetter };

package/dist/middleware/historyMiddleware.mjs

@@ -1,27 +1,27 @@
-import { isPlainObject as e } from "../createStore/helpers/deepMerge.mjs";
-import t from "../helpers/getByPath.mjs";
-import { isDisabled as n } from "./isDisabled.mjs";
+import e from "../helpers/getByPath.mjs";
+import { isDisabled as t } from "./isDisabled.mjs";
+import { isPlainObject as n } from "../createStore/helpers/deepMerge.mjs";
 import r from "../helpers/isPathAffected.mjs";
 //#region src/middleware/historyMiddleware.ts
-var i = (t, n, r = 12) => {
-	if (!Object.is(t, n)) {
-		if (r <= 0 || !e(t) || !e(n)) return {
+var i = (e, t, r = 12) => {
+	if (!Object.is(e, t)) {
+		if (r <= 0 || !n(e) || !n(t)) return {
 			path: "",
-			value: n
+			value: t
 		};
-		for (let e of new Set([...Object.keys(t), ...Object.keys(n)])) {
-			if (Object.is(t[e], n[e])) continue;
-			let a = i(t[e], n[e], r - 1);
+		for (let n of new Set([...Object.keys(e), ...Object.keys(t)])) {
+			if (Object.is(e[n], t[n])) continue;
+			let a = i(e[n], t[n], r - 1);
 			if (a) return {
-				path: a.path ? `${e}.${a.path}` : e,
+				path: a.path ? `${n}.${a.path}` : n,
 				value: a.value
 			};
 		}
 	}
 };
-function a(e, n = {}) {
+function a(t, n = {}) {
 	let a = n.limit ?? 100, o = n.path, s = n.shouldRecord, c = [{
-		state: e.getState(),
+		state: t.getState(),
 		timestamp: Date.now()
 	}], l = 0, u = !1, d = () => ({
 		entries: c,
@@ -32,10 +32,10 @@ function a(e, n = {}) {
 		f = d(), p.forEach((e) => e());
 	}, h = ({ path: n }) => {
 		if (u || s && !s(n) || o && n !== void 0 && !r(n, o)) return;
-		let d = l < c.length - 1 ? c.slice(0, l + 1) : c, f = d[d.length - 1].state, p = e.getState(), h = n ?? o, g, _ = n ?? o;
+		let d = l < c.length - 1 ? c.slice(0, l + 1) : c, f = d[d.length - 1].state, p = t.getState(), h = n ?? o, g, _ = n ?? o;
 		if (_) try {
-			let e = i(t(f, _), t(p, _));
-			e && (h = e.path ? `${_}.${e.path}` : _, g = e.value);
+			let t = i(e(f, _), e(p, _));
+			t && (h = t.path ? `${_}.${t.path}` : _, g = t.value);
 		} catch {}
 		let v = [...d, {
 			path: h,
@@ -48,9 +48,9 @@ function a(e, n = {}) {
 		if (n < 0 || n >= c.length || n === l) return;
 		let r = c[n].state;
 		if (u = !0, o) {
-			let n = t(r, o);
-			e.setState(o, () => n);
-		} else e.setState(void 0, () => r);
+			let n = e(r, o);
+			t.setState(o, () => n);
+		} else t.setState(void 0, () => r);
 		u = !1, l = n, m();
 	};
 	return {
@@ -62,7 +62,7 @@ function a(e, n = {}) {
 			travelTo: g,
 			clear: () => {
 				c = [{
-					state: e.getState(),
+					state: t.getState(),
 					timestamp: Date.now()
 				}], l = 0, m();
 			}
@@ -75,9 +75,9 @@ function s(e) {
 	return o.get(e);
 }
 var c = (e) => {
-	let t = e?.enabled;
+	let n = e?.enabled;
 	return (r) => {
-		if (n(t, r.getState())) return;
+		if (t(n, r.getState())) return;
 		let { handle: i, record: s } = a(r, e);
 		return o.set(r, i), { onChange: s };
 	};

package/dist/types/StoreTypes.d.ts

@@ -74,12 +74,30 @@ export type BoundStore<TBase> = {
     setState: SetFromBaseFn<TBase>;
     subscribe: (listener: Listener) => () => void;
     subscribePath: TBase extends object ? <SubP extends PathOf<TBase>>(subPath: SubP, listener: Listener) => () => void : (listener: Listener) => () => void;
+    get: TBase extends object ? {
+        (): TBase | undefined;
+        <SubP extends PathOf<TBase>>(subPath: SubP): PathValue<TBase, SubP> | undefined;
+    } : () => TBase | undefined;
+    set: SetFromBaseFn<TBase>;
+    watch: TBase extends object ? {
+        (listener: Listener): () => void;
+        <SubP extends PathOf<TBase>>(subPath: SubP, listener: Listener): () => void;
+    } : (listener: Listener) => () => void;
 };
 export type StoreApi<T> = {
     id?: string;
     getState: GetState<T>;
     getPath: <P extends PathOf<T>>(path: P) => PathValue<T, P> | undefined;
     setState: SetState<T>;
+    get: {
+        (): T;
+        <P extends PathOf<T>>(path: P): PathValue<T, P> | undefined;
+    };
+    set: SetState<T>;
+    watch: {
+        (listener: Listener): () => void;
+        <P extends PathOf<T>>(path: P, listener: Listener): () => void;
+    };
     withBase: <P extends PathOf<T>>(basePath: P) => BoundStore<NonNullable<PathValue<T, P>>>;
     batch: <R>(fn: () => R) => R;
     subscribe: (listener: Listener) => () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/nexus",
-  "version": "0.32.0",
+  "version": "0.32.1",
   "license": "Apache-2.0",
   "files": [
     "dist",
@@ -47,6 +47,14 @@
       "types": "./dist/StoreProvider.d.ts",
       "import": "./dist/StoreProvider.mjs"
     },
+    "./advanced": {
+      "types": "./dist/advanced/index.d.ts",
+      "import": "./dist/advanced/index.mjs"
+    },
+    "./advanced/index": {
+      "types": "./dist/advanced/index.d.ts",
+      "import": "./dist/advanced/index.mjs"
+    },
     "./async": {
       "types": "./dist/async/index.d.ts",
       "import": "./dist/async/index.mjs"