valtio-define 1.2.0 → 1.2.1

package/README.md

@@ -7,7 +7,7 @@
 [![coverage][coverage-src]][coverage-href]
 [![License][license-src]][license-href].
 
-⚡️ **valtio-define** is a lightweight factory for creating fully functional, robust [Valtio](https://valtio.dev) stores. It simplifies state management in React by providing a structured API for state, actions, and computed getters.
+⚡️ **valtio-define** is a lightweight factory for creating fully functional, robust [Valtio](https://github.com/pmndrs/valtio) stores. It simplifies state management in React by providing a structured API for state, actions, and computed getters.
 
 ## 📦 Installation
 
@@ -15,8 +15,18 @@
 pnpm add valtio-define
 ```
 
+<details>
+<summary>Are you an AI?</summary>
+
+You can run <code>npx skills add hairyf/valtio-define --skill valtio-define -y</code> to install the skills!
+
+Remember to ask your owner which <a href="https://github.com/vercel-labs/skills?tab=readme-ov-file#supported-agents">Agents</a> need to be supported (using the <code>--agent</code> parameter of skills) to avoid installing too many default <code>agents</code> directories.
+
+</details>
+
 ## 🚀 Quick Start
 
+
 ### Basic Store
 
 `defineStore` allows you to encapsulate state and logic in one place. Use `useStore` to consume the reactive state in your components.
@@ -161,6 +171,28 @@ function Profile() {
 }
 ```
 
+### Controlled inputs may lose caret position
+
+Ref: https://github.com/pmndrs/valtio/issues/270
+
+This happens because Valtio batches state updates causing React to re-render after the input event. React resets the DOM value and loses the caret position.
+
+Use `{ sync: true }` to update synchronously and preserve the caret:
+
+```tsx
+function Input() {
+  const { text } = useStore(store, { sync: true })
+  // const [text, setText] = storeToState(store, 'text', { sync: true })
+
+  return (
+    <input
+      onChange={e => store.text = e.target.value}
+      value={text}
+    />
+  )
+}
+```
+
 -----
 
 ## 🛰 Store API

package/dist/index.d.mts

@@ -38,18 +38,21 @@ declare function use(plugin: Plugin): void;
 declare function defineStore<S extends object = {}, A extends Actions<S> = {}, G extends Getters<S> = {}>(define: StoreDefine<S, A, G>): Store<S, A, G>;
 //#endregion
 //#region src/hooks.d.ts
-interface UseStoreOptions {
+declare function useStore<S extends object, A extends Actions<S>, G extends Getters<S>>(store: Store<S, A, G>, options?: {
   sync?: boolean;
-}
-declare function useStore<S extends object, A extends Actions<S>, G extends Getters<S>>(store: Store<S, A, G>, options?: UseStoreOptions): Snapshot<S & GettersReturnType<G> & A>;
+}): Snapshot<S & GettersReturnType<G> & A>;
 //#endregion
 //#region src/utils.d.ts
-declare function storeToState<S extends object, K extends keyof S>(store: Store<S>, key: K): [S[K], Dispatch<SetStateAction<S[K]>>];
-declare function storeToStates<S extends object>(store: Store<S>): { [K in keyof S]: [S[K], Dispatch<SetStateAction<S[K]>>] };
+declare function storeToState<S extends object, K extends keyof S>(store: Store<S>, key: K, options?: {
+  sync?: boolean;
+}): [S[K], Dispatch<SetStateAction<S[K]>>];
+declare function storeToStates<S extends object>(store: Store<S>, options?: {
+  sync?: boolean;
+}): { [K in keyof S]: [S[K], Dispatch<SetStateAction<S[K]>>] };
 //#endregion
 //#region src/index.d.ts
 declare const _default: {
   use: typeof use;
 };
 //#endregion
-export { Actions, ActionsOmitThisParameter, ActionsTree, Getters, GettersReturnType, Patch, Plugin, PluginContext, Signal, Store, StoreDefine, StoreDefineOptions, StoreOptions, Subscribe, SubscribeKey, UseStoreOptions, _default as default, defineStore, plugins, storeToState, storeToStates, use, useStore };
+export { Actions, ActionsOmitThisParameter, ActionsTree, Getters, GettersReturnType, Patch, Plugin, PluginContext, Signal, Store, StoreDefine, StoreDefineOptions, StoreOptions, Subscribe, SubscribeKey, _default as default, defineStore, plugins, storeToState, storeToStates, use, useStore };

package/dist/index.mjs

@@ -1 +1 @@
-import{proxy as e,ref as t,subscribe as n,useSnapshot as r}from"valtio";import{createElement as i}from"react";import{subscribeKey as a}from"valtio/utils";const o=e([]);function s(e){o.push(e)}function c(s){let c=typeof s.state==`function`?s.state():s.state,u=s.getters||{},d=s.actions||{},f=e(c),p={},m={},h=new WeakSet;for(let e in d)p[e]=t(d[e].bind(f)),f[e]=p[e];for(let e in u)l(f,e,()=>u[e].call(f)),l(m,e,()=>f[e]);function g(e){return n(f,t=>e(f,t))}function _(e,t){return a(f,e,e=>t(e),!0)}function v(e){typeof e==`function`?e(f):Object.assign(f,e)}function y(e){return i(()=>e(r(f)))}function b(e){o.push(e),C(e)}let x={$subscribe:g,$subscribeKey:_,$patch:v,$state:f,$actions:p,$getters:m,$signal:y,use:b},S=new Proxy(x,{get(e,t){return t in p?p[t]:t in e?e[t]:f[t]},has(e,t){return t in e||t in p||t in f},set(e,t,n){return t in f?f[t]=n:e[t]=n,!0}});function C(e){h.has(e)||(h.add(e),e({store:S,options:s}))}for(let e of o)C(e);return n(o,()=>{for(let e of o)C(e)}),S}function l(e,t,n){Object.defineProperty(e,t,{get:n,enumerable:!0})}function u(e,t){return r(e.$state,t)}function d(e,t){let n=u(e);function r(n){typeof n==`function`?e.$patch(e=>{e[t]=n(e[t])}):e.$patch(e=>{e[t]=n})}return[n[t],r]}function f(e){return Object.fromEntries(Object.keys(e.$state).map(t=>[t,d(e,t)]))}var p={use:s};export{p as default,c as defineStore,o as plugins,d as storeToState,f as storeToStates,s as use,u as useStore};
+import{proxy as e,ref as t,subscribe as n,useSnapshot as r}from"valtio";import{createElement as i}from"react";import{subscribeKey as a}from"valtio/utils";const o=e([]);function s(e){o.push(e)}function c(s){let c=typeof s.state==`function`?s.state():s.state,u=s.getters||{},d=s.actions||{},f=e(c),p={},m={},h=new WeakSet;for(let e in d)p[e]=t(d[e].bind(f)),f[e]=p[e];for(let e in u)l(f,e,()=>u[e].call(f)),l(m,e,()=>f[e]);function g(e){return n(f,t=>e(f,t))}function _(e,t){return a(f,e,e=>t(e),!0)}function v(e){typeof e==`function`?e(f):Object.assign(f,e)}function y(e){return i(()=>e(r(f)))}function b(e){o.push(e),C(e)}let x={$subscribe:g,$subscribeKey:_,$patch:v,$state:f,$actions:p,$getters:m,$signal:y,use:b},S=new Proxy(x,{get(e,t){return t in p?p[t]:t in e?e[t]:f[t]},has(e,t){return t in e||t in p||t in f},set(e,t,n){return t in f?f[t]=n:e[t]=n,!0}});function C(e){h.has(e)||(h.add(e),e({store:S,options:s}))}for(let e of o)C(e);return n(o,()=>{for(let e of o)C(e)}),S}function l(e,t,n){Object.defineProperty(e,t,{get:n,enumerable:!0})}function u(e,t){return r(e.$state,t)}function d(e,t,n){let r=u(e,n);function i(n){typeof n==`function`?e.$patch(e=>{e[t]=n(e[t])}):e.$patch(e=>{e[t]=n})}return[r[t],i]}function f(e,t){return Object.fromEntries(Object.keys(e.$state).map(n=>[n,d(e,n,t)]))}var p={use:s};export{p as default,c as defineStore,o as plugins,d as storeToState,f as storeToStates,s as use,u as useStore};

package/dist/plugins/index.d.mts

@@ -1,2 +1,2 @@
-import { PersistentMountOptions, StorePersistentOptions, persist } from "./persist/index.mjs";
-export { PersistentMountOptions, StorePersistentOptions, persist };
+import { PersistentMountOptions, persist } from "./persist/index.mjs";
+export { PersistentMountOptions, persist };

package/dist/plugins/persist/index.d.mts

@@ -8,9 +8,6 @@ interface PersistentMountOptions {
    */
   hydrate?: boolean;
 }
-interface StorePersistentOptions {
-  mount: () => void;
-}
 declare function persist({
   hydrate
 }?: PersistentMountOptions): Plugin;
@@ -21,4 +18,4 @@ declare module 'valtio-define' {
   interface StoreOptions extends PersistentStore {}
 }
 //#endregion
-export { PersistentMountOptions, StorePersistentOptions, persist };
+export { PersistentMountOptions, persist };

package/dist/plugins/persist/index.mjs

@@ -1 +1 @@
-import{subscribe as e}from"valtio";import{get as t,set as n}from"@hairy/utils";import{destr as r}from"destr";import{generateStructureId as i}from"structure-id";function a({hydrate:a=!0}={}){return o=>{let{persist:s,getters:c}=o.options,{$state:l}=o.store;if(!s)return;let u=s===!0?{}:s,d=u.key||i(l),f=u.storage??(typeof localStorage<`u`?localStorage:void 0);if(!f?.getItem||!f?.setItem)return;let p=!1;function m(e){let t=r(e);t&&typeof t==`object`&&(Object.keys(c||{}).forEach(e=>Reflect.deleteProperty(t,e)),Object.assign(l,t)),p=!0}function h(){let e=f.getItem(d);e instanceof Promise?e.then(m):m(e)}function g(){e(l,()=>{if(!p)return;let e=(u.paths||Object.keys(l)).reduce((e,r)=>n(e,r,t(l,r)),{});f.setItem(d,JSON.stringify(e))})}o.store.$persist={mount:h},a&&h(),g()}}export{a as persist};
+import{subscribe as e}from"valtio";import{get as t,set as n}from"@hairy/utils";import{destr as r}from"destr";import{generateStructureId as i}from"structure-id";function a({hydrate:a=!0}={}){return o=>{let{persist:s,getters:c}=o.options,{$state:l}=o.store;if(o.store.$persist?.unmount?.(),!s)return;let u=s===!0?{}:s,d=u.key||i(l),f=u.storage??(typeof localStorage<`u`?localStorage:void 0);if(!f?.getItem||!f?.setItem)return;let p=o.store.$persist?.meta??{mounted:!1,hydrated:!1};function m(e){let t=r(e);t&&typeof t==`object`&&(Object.keys(c||{}).forEach(e=>Reflect.deleteProperty(t,e)),Object.assign(l,t)),p.hydrated=!0}function h(){p.mounted=!0;let e=f.getItem(d);e instanceof Promise?e.then(m):m(e)}function g(){p.unsubscribe?.(),p.unsubscribe=void 0}function _(){g(),p.unsubscribe=e(l,()=>{if(!p.hydrated)return;let e=(u.paths||Object.keys(l)).reduce((e,r)=>n(e,r,t(l,r)),{});f.setItem(d,JSON.stringify(e))})}o.store.$persist={mount:h,unmount:g,meta:p},a&&!p.mounted&&h(),_()}}export{a as persist};

package/dist/plugins/persist/types.d.mts

@@ -12,10 +12,17 @@ interface PersistentOptions<S extends object> {
   storage?: Storage;
   paths?: DeepKeys<S>[];
 }
+interface PersistentMeta {
+  mounted: boolean;
+  hydrated: boolean;
+  unsubscribe?: () => void;
+}
 interface PersistentStore {
   $persist: {
     mount: () => void;
+    unmount: () => void;
+    meta: PersistentMeta;
   };
 }
 //#endregion
-export { DeepKeys, PersistentOptions, PersistentStore, Storage };
+export { DeepKeys, PersistentMeta, PersistentOptions, PersistentStore, Storage };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "valtio-define",
   "type": "module",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "⚡quickly create a fully functional and robust Valtio factory",
   "author": "Hairyf <wwu710632@gmail.com>",
   "license": "MIT",

package/README.OLD.md

@@ -1,391 +0,0 @@
-# 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]
-[![coverage][coverage-src]][coverage-href]
-[![License][license-src]][license-href]
-
-⚡ Quickly create a fully functional and robust [Valtio](https://valtio.dev) factory
-
-## Installation
-
-```bash
-pnpm add valtio-define
-```
-
-## Usage
-
-### Basic Store
-
-Create a reactive store with state and actions. The store provides a simple and intuitive API for managing state in React applications, built on top of Valtio.
-
-```tsx
-import { defineStore, useStore } from 'valtio-define'
-
-const store = defineStore({
-  state: () => ({ count: 0 }),
-  actions: {
-    increment() {
-      this.count++
-    },
-  },
-})
-
-function Counter() {
-  const { count } = useStore(store)
-  return (
-    <div>
-      <button onClick={store.increment}>Increment</button>
-      <div>{count}</div>
-    </div>
-  )
-}
-```
-
-### With Getters
-
-Getters are computed properties that automatically update when their dependencies change. They provide a clean way to derive state without manually tracking dependencies.
-
-```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>
-  )
-}
-```
-
-### Persistence
-
-The persistence plugin allows you to persist store state to storage (e.g., localStorage).
-
-First, register the persist plugin:
-
-```tsx
-import valtio from 'valtio-define'
-import { persist } from 'valtio-define/plugins'
-
-// Register the persist plugin globally
-valtio.use(persist())
-```
-
-Then use it in your store:
-
-```tsx
-import { defineStore } from 'valtio-define'
-
-const store = defineStore({
-  state: () => ({ count: 0 }),
-  actions: {
-    increment() {
-      this.count++
-    },
-  },
-  persist: {
-    key: 'my-store',
-    storage: localStorage,
-    paths: ['count'], // Only persist 'count', or omit to persist all state
-  },
-})
-```
-
-If `persist` is `true`, it will use `structure-id` to generate a unique key for the store automatically.
-
-```tsx
-const store = defineStore({
-  state: () => ({ count: 0 }),
-  persist: true, // Auto-generates key using structure-id
-})
-```
-
-You can pass `hydrate` when registering the plugin (default `true`). When `true`, state is hydrated from storage as soon as the store is created. Set `hydrate: false` when you need to avoid running persistence during server-side rendering, and manually mount persist in your App entry instead:
-
-```tsx
-// Register with hydrate: false
-store.use(persist({ hydrate: false }))
-
-// In your App (client entry), after store is used:
-useEffect(() => store.$persist.mount(), [])
-```
-
-### 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 specific key changes
-const unsubscribeKey = store.$subscribeKey('count', (value) => {
-  console.log('Count changed:', value)
-})
-```
-
-### 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>
-      Count:
-      {' '}
-      {store.$signal(state => state.count)}
-    </div>
-  )
-}
-```
-
-### Store to State Hooks
-
-Convert store state to React hooks similar to `useState`. This provides a more React-idiomatic way to access and update store state.
-
-#### `storeToState(store, key)`
-
-Returns a tuple `[state, setter]` for a single store key, similar to React's `useState`.
-
-```tsx
-import { defineStore, storeToState } from 'valtio-define'
-
-const store = defineStore({
-  state: { count: 0, name: 'test' },
-})
-
-function Counter() {
-  const [count, setCount] = storeToState(store, 'count')
-  const [name, setName] = storeToState(store, 'name')
-
-  return (
-    <div>
-      <button onClick={() => setCount(count + 1)}>Increment</button>
-      <button onClick={() => setCount(prev => prev + 1)}>Increment (functional)</button>
-      <div>
-        Count:
-        {count}
-      </div>
-      <div>
-        Name:
-        {name}
-      </div>
-    </div>
-  )
-}
-```
-
-**Parameters:**
-- `store`: Store instance created by `defineStore`
-- `key`: Key of the state property to access
-
-**Returns:** `[state, setter]` tuple where:
-- `state`: Current value of the state property
-- `setter`: Function to update the state (accepts value or updater function)
-
-#### `storeToStates(store)`
-
-Returns an object with all store keys mapped to `[state, setter]` tuples.
-
-```tsx
-function Component() {
-  const {
-    count: [count, setCount],
-    name: [name, setName],
-    user: [user, setUser],
-  } = storeToStates(store)
-
-  return (
-    <div>
-      <button onClick={() => setCount(count + 1)}>Increment</button>
-      <div>
-        Count:
-        {count}
-      </div>
-      <div>
-        Name:
-        {name}
-      </div>
-      <div>
-        User:
-        {user.name}
-      </div>
-    </div>
-  )
-}
-```
-
-**Parameters:**
-- `store`: Store instance created by `defineStore`
-
-**Returns:** Object where each key maps to a `[state, setter]` tuple
-
-## API
-
-### `defineStore(store)`
-
-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
-- `store.persist`: Persistence plugin configuration (boolean or object) - see [Persistence Plugin](#persistence)
-
-**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
-
-### `storeToState(store, key)`
-
-React hook that returns a `[state, setter]` tuple for a single store key, similar to React's `useState`.
-
-**Parameters:**
-- `store`: Store instance created by `defineStore`
-- `key`: Key of the state property to access
-
-**Returns:** `[state, setter]` tuple where:
-- `state`: Current value of the state property
-- `setter`: Function to update the state (accepts value or updater function like `setState(value)` or `setState(prev => newValue)`)
-
-### `storeToStates(store)`
-
-React hook that returns an object with all store keys mapped to `[state, setter]` tuples.
-
-**Parameters:**
-- `store`: Store instance created by `defineStore`
-
-**Returns:** Object where each key maps to a `[state, setter]` tuple, preserving the correct type for each property
-
-### Plugins
-
-Plugins allow you to extend store functionality. You can use plugins globally or per-store.
-
-#### Global Plugin Registration
-
-```tsx
-import valtio from 'valtio-define'
-import { persist } from 'valtio-define/plugins'
-
-// Register plugin globally - applies to all stores
-valtio.use(persist())
-```
-
-#### Per-Store Plugin Registration
-
-```tsx
-import { defineStore } from 'valtio-define'
-import { persist } from 'valtio-define/plugins'
-
-const store = defineStore({
-  state: () => ({ count: 0 }),
-})
-
-// Register plugin for this specific store
-store.use(persist())
-```
-
-#### Creating Custom Plugins
-
-```tsx
-import type { Plugin } from 'valtio-define'
-
-function myPlugin() {
-  ({ store, options }: PluginContext) => {
-    // Access store methods
-    store.$subscribe((state) => {
-      console.log('State changed:', state)
-    })
-
-    // Access store options
-    if (options.someOption) {
-    // Do something
-    }
-  }
-}
-
-declare module 'valtio-define' {
-  export interface StoreDefine<S extends object, A extends ActionsTree, G extends Getters<any>> {
-    myPlugin?: {
-      someOption?: boolean
-    }
-  }
-}
-
-// Use the plugin
-use(myPlugin())
-```
-
-**Plugin Context:**
-- `context.store`: The store instance with all methods (`$state`, `$patch`, `$subscribe`, etc.)
-- `context.options`: The original store definition options
-
-## 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
-[coverage-src]: https://codecov.io/gh/hairyf/valtio-define/graph/badge.svg?token=PG5YIEEEHJ
-[coverage-href]: https://codecov.io/gh/hairyf/valtio-define