@violetflux/kerros 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Violetflux
+
+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,39 @@
+# Kerros
+
+Tiny, selector-first React stores with stable Providers and official external-store semantics.
+
+```bash
+bun add @violetflux/kerros
+```
+
+```tsx
+import { createStore } from '@violetflux/kerros'
+import { useState } from 'react'
+
+export const [useCounter, CounterProvider] = createStore(() => {
+  const [count, setCount] = useState(0)
+
+  return { count, setCount }
+})
+
+function Counter() {
+  const { count, setCount } = useCounter(s => ({
+    count: s.count,
+    setCount: s.setCount,
+  }))
+
+  return <button onClick={() => setCount(count + 1)}>{count}</button>
+}
+```
+
+Kerros uses `use-sync-external-store/shim/with-selector`, so the same package works with React 17, 18, and 19. Selectors may be declared inline. Their returned objects are compared with top-level shallow equality.
+
+Stores compose through normal Provider nesting: an inner store hook can select values from an outer store. This keeps dependencies explicit and prevents a global store from becoming a single rerender domain.
+
+- [Documentation](https://violetflux.github.io/kerros/)
+- [API reference](https://violetflux.github.io/kerros/api/)
+- [Migration from hox](https://violetflux.github.io/kerros/guide/migration)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,59 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let react = require("react");
+let use_sync_external_store_shim_with_selector = require("use-sync-external-store/shim/with-selector");
+//#region src/index.tsx
+const useStoreLayoutEffect = typeof window === "undefined" ? react.useEffect : react.useLayoutEffect;
+/**
+* Create a selector-first React Store and its matching Provider
+*/
+function createStore(useStoreValue) {
+	const StoreContext = (0, react.createContext)(void 0);
+	const storeName = useStoreValue.name || "KerrosStore";
+	/** Run the Store hook and publish its committed snapshot */
+	const StoreProvider = (props) => {
+		const { children, ...storeProps } = props;
+		const value = useStoreValue(storeProps);
+		const [container] = (0, react.useState)(() => createStoreContainer(value));
+		useStoreLayoutEffect(() => container.publish(value), [container, value]);
+		return (0, react.createElement)(StoreContext.Provider, { value: container }, children);
+	};
+	StoreProvider.displayName = `${storeName}Provider`;
+	StoreContext.displayName = `${storeName}Context`;
+	/** Select Store fields through the stable Provider container */
+	const useStore = (selector) => {
+		const container = (0, react.useContext)(StoreContext);
+		if (!container) throw new Error("Kerros store hook must be used within its matching Provider");
+		return (0, use_sync_external_store_shim_with_selector.useSyncExternalStoreWithSelector)(container.subscribe, container.getSnapshot, container.getSnapshot, selector, shallowEqual);
+	};
+	return [useStore, StoreProvider];
+}
+/**
+* Create the stable external-store container for one Provider instance
+*/
+function createStoreContainer(initialSnapshot) {
+	let snapshot = initialSnapshot;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		getSnapshot: () => snapshot,
+		publish: (nextSnapshot) => {
+			if (Object.is(snapshot, nextSnapshot)) return;
+			snapshot = nextSnapshot;
+			for (const listener of listeners) listener();
+		},
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+/**
+* Compare selector objects by their enumerable top-level fields
+*/
+function shallowEqual(left, right) {
+	if (Object.is(left, right)) return true;
+	const leftKeys = Object.keys(left);
+	if (leftKeys.length !== Object.keys(right).length) return false;
+	return leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && Object.is(left[key], right[key]));
+}
+//#endregion
+exports.createStore = createStore;

package/dist/index.d.cts

@@ -0,0 +1,16 @@
+import { FC, PropsWithChildren } from "react";
+//#region src/index.d.ts
+/** Store selector returning an object compared with shallow equality */
+type StoreSelector<TStore, TSelection extends object> = (store: TStore) => TSelection;
+/** Hook used by consumers to select Store fields */
+interface StoreHook<TStore> {
+  <TSelection extends object>(selector: StoreSelector<TStore, TSelection>): TSelection;
+}
+/** Provider created for a Store hook */
+type StoreProvider<TProps> = FC<PropsWithChildren<TProps>>;
+/**
+ * Create a selector-first React Store and its matching Provider
+ */
+declare function createStore<TStore, TProps = Record<never, never>>(useStoreValue: (props: TProps) => TStore): readonly [StoreHook<TStore>, StoreProvider<TProps>];
+//#endregion
+export { StoreHook, StoreProvider, StoreSelector, createStore };

package/dist/index.d.mts

@@ -0,0 +1,16 @@
+import { FC, PropsWithChildren } from "react";
+//#region src/index.d.ts
+/** Store selector returning an object compared with shallow equality */
+type StoreSelector<TStore, TSelection extends object> = (store: TStore) => TSelection;
+/** Hook used by consumers to select Store fields */
+interface StoreHook<TStore> {
+  <TSelection extends object>(selector: StoreSelector<TStore, TSelection>): TSelection;
+}
+/** Provider created for a Store hook */
+type StoreProvider<TProps> = FC<PropsWithChildren<TProps>>;
+/**
+ * Create a selector-first React Store and its matching Provider
+ */
+declare function createStore<TStore, TProps = Record<never, never>>(useStoreValue: (props: TProps) => TStore): readonly [StoreHook<TStore>, StoreProvider<TProps>];
+//#endregion
+export { StoreHook, StoreProvider, StoreSelector, createStore };

package/dist/index.mjs

@@ -0,0 +1,58 @@
+import { createContext, createElement, useContext, useEffect, useLayoutEffect, useState } from "react";
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
+//#region src/index.tsx
+const useStoreLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+/**
+* Create a selector-first React Store and its matching Provider
+*/
+function createStore(useStoreValue) {
+	const StoreContext = createContext(void 0);
+	const storeName = useStoreValue.name || "KerrosStore";
+	/** Run the Store hook and publish its committed snapshot */
+	const StoreProvider = (props) => {
+		const { children, ...storeProps } = props;
+		const value = useStoreValue(storeProps);
+		const [container] = useState(() => createStoreContainer(value));
+		useStoreLayoutEffect(() => container.publish(value), [container, value]);
+		return createElement(StoreContext.Provider, { value: container }, children);
+	};
+	StoreProvider.displayName = `${storeName}Provider`;
+	StoreContext.displayName = `${storeName}Context`;
+	/** Select Store fields through the stable Provider container */
+	const useStore = (selector) => {
+		const container = useContext(StoreContext);
+		if (!container) throw new Error("Kerros store hook must be used within its matching Provider");
+		return useSyncExternalStoreWithSelector(container.subscribe, container.getSnapshot, container.getSnapshot, selector, shallowEqual);
+	};
+	return [useStore, StoreProvider];
+}
+/**
+* Create the stable external-store container for one Provider instance
+*/
+function createStoreContainer(initialSnapshot) {
+	let snapshot = initialSnapshot;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		getSnapshot: () => snapshot,
+		publish: (nextSnapshot) => {
+			if (Object.is(snapshot, nextSnapshot)) return;
+			snapshot = nextSnapshot;
+			for (const listener of listeners) listener();
+		},
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+/**
+* Compare selector objects by their enumerable top-level fields
+*/
+function shallowEqual(left, right) {
+	if (Object.is(left, right)) return true;
+	const leftKeys = Object.keys(left);
+	if (leftKeys.length !== Object.keys(right).length) return false;
+	return leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && Object.is(left[key], right[key]));
+}
+//#endregion
+export { createStore };

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@violetflux/kerros",
+  "version": "0.1.0",
+  "description": "A tiny selector-first React store built on useSyncExternalStore.",
+  "keywords": [
+    "react",
+    "state-management",
+    "store",
+    "selector",
+    "use-sync-external-store"
+  ],
+  "homepage": "https://violetflux.github.io/kerros/",
+  "bugs": {
+    "url": "https://github.com/violetflux/kerros/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/violetflux/kerros.git"
+  },
+  "license": "MIT",
+  "author": "Violetflux",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "rspress dev",
+    "docs:build": "rspress build",
+    "docs:preview": "rspress preview",
+    "docs:check": "bun scripts/check-docs.ts",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "bun run lint && bun run typecheck && bun run test && bun run build && bun run docs:check && bun run docs:build",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "use-sync-external-store": "1.6.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@rspress/core": "2.0.17",
+    "@types/node": "26.1.1",
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "@types/use-sync-external-store": "1.5.0",
+    "eslint": "10.7.0",
+    "eslint-plugin-react-hooks": "7.1.1",
+    "globals": "17.7.0",
+    "jsdom": "29.1.1",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "tsdown": "0.22.9",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.64.0",
+    "vitest": "4.1.10"
+  }
+}