valtio-define 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Hairyf <wwu710632@gmail.com>
+
+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,253 @@
+# valtio-define
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![bundle][bundle-src]][bundle-href]
+[![JSDocs][jsdocs-src]][jsdocs-href]
+[![License][license-src]][license-href]
+
+⚡ Quickly create a fully functional and robust Valtio factory
+
+## Installation
+
+```bash
+npm install valtio-define
+```
+
+## Usage
+
+### Basic Store
+
+```tsx
+import { defineStore, useStore } from 'valtio-define'
+
+const store = defineStore({
+  state: () => ({ count: 0 }),
+  actions: {
+    increment() {
+      this.count++
+    },
+  },
+})
+
+function Counter() {
+  const state = useStore(store)
+  return (
+    <div>
+      <button onClick={store.increment}>Increment</button>
+      <div>{state.count}</div>
+    </div>
+  )
+}
+```
+
+### With Getters
+
+```tsx
+const store = defineStore({
+  state: () => ({ count: 0 }),
+  getters: {
+    doubled() {
+      return this.count * 2
+    },
+  },
+  actions: {
+    increment() {
+      this.count++
+    },
+  },
+})
+
+function Counter() {
+  const state = useStore(store)
+  return (
+    <div>
+      <div>
+        Count:
+        {state.count}
+      </div>
+      <div>
+        Doubled:
+        {state.doubled}
+      </div>
+      <button onClick={store.increment}>Increment</button>
+    </div>
+  )
+}
+```
+
+### Async Actions with Status
+
+```tsx
+import { defineStore, useStatus, useStore } from 'valtio-define'
+
+const store = defineStore({
+  state: () => ({ data: null }),
+  actions: {
+    async fetchData() {
+      const response = await fetch('/api/data')
+      this.data = await response.json()
+    },
+  },
+})
+
+function DataComponent() {
+  const state = useStore(store)
+  const status = useStatus(store)
+
+  return (
+    <div>
+      {status.loading && <div> Store all actions are loading...</div>}
+      {status.finished && <div> Store all actions are finished...</div>}
+      {status.error && <div> Store all actions are error...</div>}
+
+      {status.fetchData.finished && <div> Data fetched successfully...</div>}
+      {status.fetchData.error && (
+        <div>
+          {' '}
+          Error fetching data:
+          {status.fetchData.error.message}
+        </div>
+      )}
+      {state.data && <div>{JSON.stringify(state.data)}</div>}
+      <button onClick={store.fetchData}>Fetch Data</button>
+    </div>
+  )
+}
+```
+
+### Persistence
+
+```tsx
+const store = defineStore(
+  {
+    state: () => ({ count: 0 }),
+    actions: {
+      increment() {
+        this.count++
+      },
+    },
+  },
+  {
+    persist: true // or { key: 'my-store', storage: localStorage, paths: ['count'] }
+  }
+)
+```
+
+If the persist is a boolean value, it will use `structure-id` to generate a unique key for the store.
+
+### Subscribe to Changes
+
+```tsx
+const store = defineStore({
+  state: () => ({ count: 0 }),
+  actions: {
+    increment() {
+      this.count++
+    },
+  },
+})
+
+// Subscribe to state changes
+const unsubscribe = store.$subscribe((state) => {
+  console.log('State changed:', state)
+})
+
+// Subscribe to status changes
+const unsubscribeStatus = store.$subscribe.status((status) => {
+  console.log('Status changed:', status)
+})
+```
+
+### Patch State
+
+```tsx
+// Patch with object
+store.$patch({ count: 10 })
+
+// Patch with function
+store.$patch((state) => {
+  state.count += 5
+})
+```
+
+### Signal (JSX Component)
+
+```tsx
+function App() {
+  return (
+    <div>
+      {store.$signal(state => (
+        <div>
+          Count:
+          {state.count}
+        </div>
+      ))}
+      {store.$signal.status(status => (
+        status.loading && <div>Loading...</div>
+      ))}
+    </div>
+  )
+}
+```
+
+## API
+
+### `defineStore(store, options?)`
+
+Creates a store with state, actions, and getters.
+
+**Parameters:**
+- `store.state`: Initial state object or factory function
+- `store.actions`: Object containing action methods
+- `store.getters`: Object containing getter methods
+- `options.persist`: Persistence configuration (boolean or object)
+
+**Returns:** Store instance with reactive state and actions
+
+### `useStore(store)`
+
+React hook that returns a snapshot of the store state.
+
+**Parameters:**
+- `store`: Store instance created by `defineStore`
+
+**Returns:** Snapshot of the store state
+
+### `useStatus(store)`
+
+React hook that returns the status of all actions.
+
+**Parameters:**
+- `store`: Store instance created by `defineStore`
+
+**Returns:** Status object with loading, finished, and error states
+
+### `proxyWithPersistent(initialObject, options?)`
+
+Creates a persistent proxy state.
+
+**Parameters:**
+- `initialObject`: Initial state object
+- `options.key`: Storage key (auto-generated if not provided)
+- `options.storage`: Storage instance (defaults to localStorage)
+- `options.paths`: Array of paths to persist (defaults to all)
+
+**Returns:** Persistent proxy state
+
+## License
+
+[MIT](./LICENSE) License © [Hairyf](https://github.com/hairyf)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/valtio-define?style=flat&colorA=080f12&colorB=1fa669
+[npm-version-href]: https://npmjs.com/package/valtio-define
+[npm-downloads-src]: https://img.shields.io/npm/dm/valtio-define?style=flat&colorA=080f12&colorB=1fa669
+[npm-downloads-href]: https://npmjs.com/package/valtio-define
+[bundle-src]: https://img.shields.io/bundlephobia/minzip/valtio-define?style=flat&colorA=080f12&colorB=1fa669&label=minzip
+[bundle-href]: https://bundlephobia.com/result?p=valtio-define
+[license-src]: https://img.shields.io/github/license/hairyf/valtio-define.svg?style=flat&colorA=080f12&colorB=1fa669
+[license-href]: https://github.com/hairyf/valtio-define/blob/main/LICENSE
+[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
+[jsdocs-href]: https://www.jsdocs.io/package/valtio-define

package/dist/index.d.mts

@@ -0,0 +1,88 @@
+import { Snapshot } from "valtio";
+
+//#region src/types/index.d.ts
+type Actions<S> = Record<string, (this: S, ...args: any) => any>;
+type Getters<S> = Record<string, (this: S) => any>;
+type ActionsOmitThisParameter<A extends Actions<any>> = { [K in keyof A]: (...args: Parameters<A[K]>) => ReturnType<A[K]> };
+interface Status {
+  finished: boolean;
+  loading: boolean;
+  error: Error | null;
+}
+type ActionsStatus<A extends Actions<any>> = Status & { [K in keyof A]: Status };
+type GettersReturnType<G extends Getters<any>> = { [K in keyof G]: ReturnType<G[K]> };
+interface StoreDefine<S extends object, A extends Actions<S>, G extends Getters<S>> {
+  state: (() => S) | S;
+  actions?: A;
+  getters?: G;
+}
+interface StoreOptions {
+  persist?: boolean | PersistentOptions;
+}
+interface StoreSignal<S, A extends Actions<S>, G extends Getters<S>> {
+  <T>(fn: (state: S & GettersReturnType<G>) => T): T;
+  status: <T>(fn: (status: ActionsStatus<A>) => T) => T;
+}
+interface StoreSubscribe<S, A extends Actions<S>, G extends Getters<S>> {
+  (listener: (state: S & GettersReturnType<G>) => void): () => void;
+  status: (listener: (status: ActionsStatus<A>) => void) => () => void;
+}
+interface StorePatch<S, G extends Getters<S>> {
+  (patch: Partial<S> | ((state: S & GettersReturnType<G>) => void)): void;
+}
+type Store<S, A extends Actions<S>, G extends Getters<S>> = {
+  $subscribe: StoreSubscribe<S, A, G>;
+  $patch: StorePatch<S, G>;
+  $state: S & GettersReturnType<G> & ActionsOmitThisParameter<A>;
+  $actions: ActionsOmitThisParameter<A>;
+  $getters: GettersReturnType<G>;
+  $status: ActionsStatus<A>;
+  $signal: StoreSignal<S, A, G>;
+} & ActionsOmitThisParameter<A>;
+interface PersistentOptions {
+  key?: string;
+  storage?: Storage;
+  paths?: string[];
+}
+//#endregion
+//#region src/define-store.d.ts
+/**
+ * @description Define a store
+ * @example
+ * ```tsx
+ * const store = defineStore({
+ *   state: () => ({ count: 0 }),
+ *   actions: {
+ *     increment() {
+ *       this.count++
+ *     },
+ *   },
+ * })
+ *
+ * store.increment()
+ * console.log(store.$state.count) // 1
+ *
+ * function Component() {
+ *   const store = useStore(store)
+ *   return (
+ *     <div>
+ *       <button onClick={store.increment}>Increment</button>
+ *       <div>{store.count}</div>
+ *     </div>
+ *   )
+ * }
+ *
+ * ```
+ */
+declare function defineStore<S extends object, A extends Actions<S>, G extends Getters<S>>(store: StoreDefine<S, A, G>, options?: StoreOptions): Store<S, A, G>;
+//#endregion
+//#region src/persistent.d.ts
+declare function proxyWithPersistent<T extends object>(initialObject: T, options?: PersistentOptions): T;
+//#endregion
+//#region src/use-status.d.ts
+declare function useStatus<S extends object, A extends Actions<S>, G extends Getters<S>>(store: Store<S, A, G>): Snapshot<ActionsStatus<A>>;
+//#endregion
+//#region src/use-store.d.ts
+declare function useStore<S extends object, A extends Actions<S>, G extends Getters<S>>(store: Store<S, A, G>): Snapshot<S & GettersReturnType<G>>;
+//#endregion
+export { defineStore, proxyWithPersistent, useStatus, useStore };

package/dist/index.mjs

@@ -0,0 +1,183 @@
+import { createElement } from "react";
+import { proxy, subscribe, useSnapshot } from "valtio";
+import { jsonTryParse } from "@hairy/utils";
+import { generateStructureId } from "structure-id";
+
+//#region src/utils/index.ts
+function track(action, status) {
+	let loadings = 0;
+	const tracking = () => {
+		loadings++ === 0 && (status.loading = true);
+	};
+	const done = () => {
+		!--loadings && (status.loading = false);
+	};
+	const fulfilled = (value) => {
+		status.finished = true;
+		done();
+		return value;
+	};
+	const rejected = (error) => {
+		status.error = error;
+		done();
+		throw error;
+	};
+	return function(...args) {
+		tracking();
+		try {
+			const value = action(...args);
+			return value instanceof Promise ? value.then(fulfilled, rejected) : fulfilled(value);
+		} catch (error) {
+			rejected(error);
+		}
+	};
+}
+function get(obj, path) {
+	return path.split(".").reduce((result, key) => result?.[key], obj);
+}
+function set(obj, path, value) {
+	const keys = path.split(".");
+	const lastKey = keys.pop();
+	const target = keys.reduce((result, key) => result[key] ??= {}, obj);
+	target[lastKey] = value;
+}
+
+//#endregion
+//#region src/persistent.ts
+function proxyWithPersistent(initialObject, options = {}) {
+	options.key = options.key || generateStructureId(initialObject);
+	const storage = options.storage || (typeof localStorage !== "undefined" ? localStorage : void 0);
+	const state = proxy(jsonTryParse(storage?.getItem(options.key)) || initialObject);
+	subscribe(state, () => {
+		const paths = options.paths || Object.keys(state);
+		const statePaths = {};
+		for (const key of paths) set(statePaths, key, get(state, key));
+		storage?.setItem(options.key, JSON.stringify(statePaths));
+	});
+	return state;
+}
+
+//#endregion
+//#region src/define-store.ts
+/**
+* @description Define a store
+* @example
+* ```tsx
+* const store = defineStore({
+*   state: () => ({ count: 0 }),
+*   actions: {
+*     increment() {
+*       this.count++
+*     },
+*   },
+* })
+*
+* store.increment()
+* console.log(store.$state.count) // 1
+*
+* function Component() {
+*   const store = useStore(store)
+*   return (
+*     <div>
+*       <button onClick={store.increment}>Increment</button>
+*       <div>{store.count}</div>
+*     </div>
+*   )
+* }
+*
+* ```
+*/
+function defineStore(store, options = {}) {
+	const state = typeof store.state === "function" ? store.state() : store.state;
+	const getters = store.getters || {};
+	const actions = store.actions || {};
+	const status = {};
+	status.finished = false;
+	status.loading = false;
+	status.error = null;
+	const $status = proxy(status);
+	const $state = options.persist ? proxyWithPersistent(state, options.persist === true ? {} : options.persist) : proxy(state);
+	const $actions = {};
+	const $getters = {};
+	setupActions($state, actions, $actions, $status);
+	setupGetters(state, $state, getters, $getters);
+	setupStatus($actions, $status);
+	function $subscribe(listener) {
+		return subscribe($state, () => listener($state));
+	}
+	$subscribe.status = function(listener) {
+		return subscribe($status, () => listener($status));
+	};
+	function $patch(patch) {
+		if (typeof patch === "function") patch($state);
+		else Object.assign($state, patch);
+	}
+	function $signal(fn) {
+		return createElement(() => fn(useSnapshot($state)));
+	}
+	$signal.status = function(fn) {
+		return createElement(() => fn(useSnapshot($status)));
+	};
+	return {
+		$subscribe,
+		$patch,
+		$state,
+		$status,
+		$actions,
+		$getters,
+		$signal,
+		...$actions
+	};
+}
+function setupActions($state, actions, $actions, $status) {
+	for (const key in actions) {
+		$status[key] = {
+			finished: false,
+			loading: false,
+			error: null
+		};
+		$actions[key] = track(actions[key].bind($state), $status[key]);
+		Object.defineProperty($state, key, { get: () => $actions[key] });
+	}
+}
+function setupGetters(state, $state, getters, $getters) {
+	for (const key in getters) {
+		Object.defineProperty($getters, key, {
+			get: () => state[key],
+			enumerable: true
+		});
+		Object.defineProperty(state, key, {
+			get: () => getters[key].call($state),
+			enumerable: true
+		});
+	}
+}
+function setupStatus($actions, $status) {
+	Object.defineProperty($status, "loading", {
+		get: () => Object.keys($actions).some((key) => $status[key].loading),
+		enumerable: true
+	});
+	Object.defineProperty($status, "finished", {
+		get: () => Object.keys($actions).every((key) => $status[key].finished),
+		enumerable: true
+	});
+	Object.defineProperty($status, "error", {
+		get: () => Object.keys($actions).find((key) => $status[key].error),
+		enumerable: true
+	});
+}
+
+//#endregion
+//#region src/use-status.ts
+function useStatus(store) {
+	return useSnapshot(store.$status);
+}
+
+//#endregion
+//#region src/use-store.ts
+function useStore(store) {
+	return useSnapshot(store.$state);
+}
+
+//#endregion
+export { defineStore, proxyWithPersistent, useStatus, useStore };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "valtio-define",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "⚡quickly create a fully functional and robust Valtio factory",
+  "author": "Hairyf <wwu710632@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/hairyf/valtio-define#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hairyf/valtio-define.git"
+  },
+  "bugs": "https://github.com/hairyf/valtio-define/issues",
+  "keywords": [],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^18.2.0"
+  },
+  "dependencies": {
+    "@hairy/utils": "^1.39.0",
+    "structure-id": "^1.2.9",
+    "valtio": "^2.2.0"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^6.2.0",
+    "@antfu/ni": "^27.0.1",
+    "@antfu/utils": "^9.3.0",
+    "@types/node": "^24.10.0",
+    "@types/react": "^19.2.6",
+    "@vitejs/plugin-react": "^5.1.1",
+    "bumpp": "^10.3.1",
+    "eslint": "^9.39.1",
+    "lint-staged": "^16.2.6",
+    "react": "^19.2.0",
+    "simple-git-hooks": "^2.13.1",
+    "tinyexec": "^1.0.2",
+    "tsdown": "^0.16.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.1",
+    "vitest": "^4.0.7",
+    "vitest-package-exports": "^0.1.1",
+    "yaml": "^2.8.1"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"
+  },
+  "lint-staged": {
+    "*": "eslint --fix"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "eslint",
+    "release": "bumpp",
+    "start": "tsx src/index.ts",
+    "test": "vitest",
+    "typecheck": "tsc"
+  }
+}