muya 2.2.8 → 2.3.0

package/README.md

@@ -1,268 +1,271 @@
-
 # **Muya 🌀**
 
-Muya is simple and lightweight react state management library.
+*A tiny, type-safe state manager for React with a dead-simple mental model:*
+- **Create a state**
+- **Read it in components**
+- **Update it**
+- **Derive more states when you need to**
 
 ---
 
 [![Build](https://github.com/samuelgja/muya/actions/workflows/build.yml/badge.svg)](https://github.com/samuelgja/muya/actions/workflows/build.yml)
-[![Code Quality Check](https://github.com/samuelgja/muya/actions/workflows/code-check.yml/badge.svg)](https://github.com/samuelgja/muya/actions/workflows/code-check.yml)
-[![Build Size](https://img.shields.io/bundlephobia/minzip/muya?label=Bundle%20size)](https://bundlephobia.com/result?p=muya)
-
+[![Code Quality](https://github.com/samuelgja/muya/actions/workflows/code-check.yml/badge.svg)](https://github.com/samuelgja/muya/actions/workflows/code-check.yml)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/muya?label=Bundle%20size)](https://bundlephobia.com/result?p=muya)
 
-- **Simplified API**: Only `create` and `select`.
-- **Batch Updates**: Built-in batching ensures efficient `muya` state updates internally.
-- **TypeScript Support**: Type first.
-- **Lightweight**: Minimal bundle size.
+## ✨ Highlights
+- **2-call API**: `create` and `select` (plus a tiny hook `useValue`)
+- **React-friendly**: internal batching; opt-in equality checks to skip renders
+- **Type-first**: full TypeScript support
+- **Lightweight**: built for small mental & bundle footprint
 
 ---
 
-## 📦 **Installation**
-
-Install with your favorite package manager:
+## 📦 Install
 ```bash
 bun add muya@latest
-```
-```bash
-npm install muya@latest
-```
-```bash
+# or
+npm i muya@latest
+# or
 yarn add muya@latest
 ```
 
 ---
 
-## 📝 **Quick Start**
+## 🏃 Quick Start
 
-### **Create and Use State**
+```tsx
+import { create } from 'muya'
 
-```typescript
-import { create } from 'muya';
+// 1) Make a state
+const counter = create(0)
 
-const useCounter = create(0);
-
-// Access in a React component
-function Counter() {
-  const count = useCounter(); // Call state directly
+// 2) Read it inside React
+export function Counter() {
+  const count = counter() // state is a hook
   return (
     <div>
-      <button onClick={() => useCounter.set((prev) => prev + 1)}>Increment</button>
+      <button onClick={() => counter.set(n => n + 1)}>+1</button>
       <p>Count: {count}</p>
     </div>
-  );
+  )
 }
 ```
 
 ---
 
-### **Select and Slice State**
-
-Use `select` to derive a slice of the state:
-
-```typescript
-const state = create({ count: 0, value: 42 });
-
-const countSlice = state.select((s) => s.count);
-
-// Also async is possible, but Muya do not recommend 
-// It can lead to spaghetti re-renders code which is hard to maintain and debug
-const asyncCountSlice = state.select(async (s) => {
-  const data = await fetchData();
-  return data.count;
-});
-```
-
----
-
-### **Combine Multiple States**
+## 🧩 Selecting / Deriving
 
-Combine multiple states into a derived state via `select` method:
+Create derived states from one or many sources.
 
-```typescript
+```ts
 import { create, select } from 'muya'
 
-const state1 = create(1);
-const state2 = create(2);
+const a = create(1)
+const b = create(2)
 
-const sum = select([state1, state2], (s1, s2) => s1 + s2);
-```
+// Single source
+const doubleA = a.select(n => n * 2)
 
-### **Equality Check**
-
-Customize equality checks to prevent unnecessary updates:
+// Multiple sources
+const sum = select([a, b], (x, y) => x + y)
+```
 
-```typescript
-const state = create({ a: 1, b: 2 }, (prev, next) => prev.b === next.b);
+**Equality checks** (to avoid re-emits):
 
-// Updates only when `b` changes
-state.set((prev) => ({ ...prev, a: prev.a + 1 }));
+```ts
+const obj = create({ a: 1, b: 2 }, (prev, next) => prev.b === next.b)
+obj.set(p => ({ ...p, a: p.a + 1 })) // does not notify (b unchanged)
 ```
 
-Or in select methods:
+You can also add an equality function on a `select`:
 
-```typescript
-const derived = select([state1, state2], (s1, s2) => s1 + s2, (prev, next) => prev === next);
+```ts
+const stable = select([a, b], (x, y) => x + y, (prev, next) => prev === next)
 ```
 
 ---
 
+## 🎣 Using in Components
 
-## 🖥️ **Using State in Components**
+Muya states are callable hooks. Prefer that.  
+If you want a hook wrapper or slicing, use `useValue`.
 
-Access state directly or through `useValue` hook:
+```tsx
+import { create, useValue } from 'muya'
 
-### **Option 1: Access State Directly**
-Each state can be called as the hook directly
-```typescript
-const userState = create(0);
+const user = create({ id: 'u1', name: 'Ada', admin: false })
 
-function App() {
-  const user = userState(); // Directly call state
-  return <p>User: {user}</p>;
+// Option 1: call the state directly
+function Profile() {
+  const u = user()
+  return <div>{u.name}</div>
 }
-```
 
-### **Option 2: Use the Hook**
-Or for convenience, there is `useValue` method
-```typescript
-import { useValue } from 'muya';
-
-function App() {
-  const user = useValue(userState); // Access state via hook
-  return <p>User: {user}</p>;
-}
-```
-
-### **Option 3: Slice with Hook**
-For efficient re-renders, `useValue` provides a slicing method.
-```typescript
-function App() {
-  const count = useValue(state, (s) => s.count); // Use selector in hook
-  return <p>Count: {count}</p>;
+// Option 2: useValue for a selector
+function OnlyName() {
+  const name = useValue(user, u => u.name)
+  return <div>{name}</div>
 }
 ```
 
 ---
 
-## 📖 **API Overview**
+## ⚡ Async & Lazy (the 2-minute mental model)
 
-### **`create`**
+**Immediate vs Lazy**
+```ts
+create(0)          // immediate: value exists now
+create(() => 0)    // lazy: computed on first read (.get() / component render)
+```
 
-Create a new state:
+**Async sources**
+```ts
+async function fetchInitial() { return 0 }
+create(fetchInitial)          // lazy + async
+create(Promise.resolve(0))    // immediate + async
+```
 
-```typescript
-const state = create(initialValue, isEqual?);
+**Setting with async state**
+- `state.set(2)` **overrides immediately** (cancels previous pending promise)
+- `state.set(prev => prev + 1)` **waits for the current promise to resolve** so `prev` is always the resolved value
 
-// Methods:
-state.get(); // Get current value
-state.set(value); // Update value
-state.listen(listener); // Subscribe to changes
-state.select(selector, isEqual?); // Create derived state
-state.destroy(); // Unsubscribe from changes, useful for dynamic state creation in components
-state.withName(name); // Add a name for debugging, otherwise it will be auto generated number
+**Async selectors**
+```ts
+const base = create(0)
+const plusOne = base.select(async n => {
+  await doWork()
+  return n + 1
+})
 ```
+- Async selects **suspend** the first time (and when their upstream async value requires it)
+- A sync selector reading an async parent will **suspend once** on initial load
 
-### **`select`**
+> Tip: Prefer keeping selectors **sync** and performing async work **before** calling `set`. It keeps render trees predictable.
 
-Combine or derive new states:
+---
 
-```typescript
-const derived = select([state1, state2], (s1, s2) => s1 + s2);
+## 🧪 API (short and sweet)
 
-// Methods:
-derived.get(); // Get current value
-derived.listen(listener); // Subscribe to changes
-derived.select(selector, isEqual?); // Create nested derived state
-derived.destroy(); // Unsubscribe from changes, useful for dynamic state creation in components
-derived.withName(name); // Add a name for debugging, otherwise it will be auto generated number
-```
+### `create<T>(initial, isEqual?) => State<T>`
+**State methods**
+- `get(): T` — read current value (resolves lazy/async when needed)
+- `set(value | (prev) => next)` — update value (batched)
+- `listen(fn)` — subscribe, returns `unsubscribe`
+- `select(selector, isEqual?)` — derive new state from this state
+- `destroy()` — clear listeners and dispose
+- `withName(name)` — add a debug label (DevTools)
 
-### **`useValue`**
+### `select([states], derive, isEqual?) => State<R>`
+Derive a state from one or multiple states.
 
-React hook to access state:
-
-```typescript
-const value = useValue(state, (s) => s.slice); // Optional selector
-```
+### `useValue(state, selector?)`
+React hook to read a state or a slice.
 
 ---
 
-## ⚠️ **Notes**
+## 🪵 DevTools
+In **dev**, Muya auto-connects to Redux DevTools if present and reports state updates by name.  
+Use `state.withName('CartItems')` to make timelines readable.
 
-- **Equality Check**: Prevent unnecessary updates by passing a custom equality function to `create` or `select`.
-- **Batch Updates**: Muya batches internal updates for better performance, reducing communication overhead similarly how react do.
-- **Async Selectors / Derives**: Muya has support for async selectors / derives, but do not recommend to use as it can lead to spaghetti re-renders code which is hard to maintain and debug, if you want so, you can or maybe you should consider using other alternatives like `Jotai`.
+---
 
+## 🤝 Patterns & Anti-patterns
 
+**✅ Good**
+- Keep selectors pure and fast
+- Use equality checks to avoid unnecessary updates
+- Do async outside, then `set` synchronously
+
+**⚠️ Be cautious**
+- Deep async chains of selectors → harder to debug and may re-suspend often
+- Long-running async work inside selectors → push it out of render path
 
-`Muya` encourage use async updates withing sync state like this:
-```typescript
-const state = create({ data: null });
-async function update() {
-  const data = await fetchData();
-  state.set({ data });
-}
-```
 ---
 
-But of course you can do
+## 🧭 Examples
 
-Note: Handling async updates for the state (`set`) will cancel the previous pending promise.
-```typescript
-const state = create(0)
-const asyncState = state.select(async (s) => {
-  await longPromise(100)
-  return s + 1
-})
+**Boolean flags derived from async state (suspends only once):**
+```tsx
+const user = create(fetchUser) // async lazy
+const isAdmin = user.select(u => u.role === 'admin')
+// First mount suspends while user loads, subsequent updates are instant
+```
+
+**Batching inside events:**
+```ts
+function onCheckout() {
+  cart.set(c => applyDiscount(c))
+  total.set(t => t - 10)
+  // Muya batches internally; React sees one commit
+}
 ```
+
 ---
 
-### Lazy resolution
-`Muya` can be used in `immediate` mode or in `lazy` mode. When create a state with just plain data, it will be in immediate mode, but if you create a state with a function, it will be in lazy mode. This is useful when you want to create a state that is executed only when it is accessed for the first time.
+## 🗃️ (Optional) Muya + SQLite Companion
 
+If you’re using the companion `muya/sqlite` package, you can manage large, queryable lists with React-friendly pagination:
 
-```typescript
-// immediate mode, so no matter what, this value is already stored in memory
-const state = create(0)
+```ts
+import { createSqliteState } from 'muya/sqlite'
+import { useSqliteValue } from 'muya/sqlite'
 
-// lazy mode, value is not stored in memory until it is accessed for the first time via get or component render
-const state = create(() => 0)
-```
+type Person = { id: string; name: string; age: number }
+
+const people = createSqliteState<Person>({
+  backend,            // e.g. expo-sqlite / bunMemoryBackend
+  tableName: 'People',
+  key: 'id',
+  indexes: ['age'],   // optional
+})
 
-And in async:
-```typescript
-// we can create some initial functions like this
-async function initialLoad() {
-  return 0
+// In React: stepwise fetching + where/order/limit
+function PeopleList() {
+  const [rows, actions] = useSqliteValue(people, { sorBy: 'age', order: 'asc', limit: 50 }, [])
+  return (
+    <>
+      <ul>{rows.map(p => <li key={p.id}>{p.name}</li>)}</ul>
+      <button onClick={() => actions.next()}>Load more</button>
+      <button onClick={() => actions.reset()}>Reset</button>
+    </>
+  )
 }
-// immediate mode, so no matter what, this value is already stored in memory
-const state = create(initialLoad)
-// or
-const state = create(Promise.resolve(0))
+```
 
-// lazy mode, value is not stored in memory until it is accessed for the first time via get or component render
-const state = create(() => Promise.resolve(0))  
+**Quick ops**
+```ts
+await people.batchSet([{ id:'1', name:'Alice', age:30 }])
+await people.set({ id:'2', name:'Bob', age:25 })
+await people.delete('1')
+const alice = await people.get('2', p => p.name)  // 'Bob'
+const count = await people.count({ where: { age: { gt: 20 } } })
+for await (const p of people.search({ where: { name: { like: '%Ali%' }}})) { /* … */ }
 ```
 
-And when setting state when initial value is promise, set is always sync.
-But as in react there are two methods how to set a state. Directly `.set(2)` or with a function `.set((prev) => prev + 1)`.
+---
+
+## ❓ FAQ
+
+**Is Muya a replacement for Redux/Zustand/Jotai?**  
+No—Muya is intentionally tiny. If you need complex middleware, effects, or ecosystem plugins, those tools are great choices.
 
-So how `set` state will behave with async initial value?
-1. Directly call `.set(2)` will be sync, and will set the value to 2 (it will cancel the initial promise)
-2. Call `.set((prev) => prev + 1)` will wait until previous promise is resolved, so previous value in set callback is always resolved. 
+**Can I use Suspense?**  
+Yes. Async states/selectors will suspend on first read (and when upstream requires it).
 
-### Async selectors knowledge base
-1. Values in selectors derived from another async selectors will be always sync **(not promise)**
-2. If the selector is async (`state.select(async (s) => s + 1)`) it will automatically use suspense mode, so on each change it firstly resolved promise (hit suspense) and then update the value.
-3. If the selector is sync, but it's derived from async selector, it will also be in suspense mode - but it depends what the parent is, if the parent is async state, it will hit the suspense only once, on initial load, but if the parent is another async selector, it will hit suspense on each change.
+**How do I avoid re-renders?**  
+Provide an `isEqual(prev, next)` to `create` or `select`, or select a smaller slice in `useValue`.
 
-### Debugging
-`Muya` in dev mode automatically connects to the `redux` devtools extension if it is installed in the browser. For now devtool api is simple - state updates.
+---
 
-## 🙏 **Acknowledgments**
+## 🧪 Testing Tips
+- State reads/writes are synchronous, but **async sources/selectors** resolve over time. In tests, use `await waitFor(...)` around expectations that depend on async resolution.
 
-This library is a fun, experimental project and not a replacement for robust state management tools. For more advanced use cases, consider libraries like `Zustand`, `Jotai`, or `Redux`. 
-If you enjoy `Muya`, please give it a ⭐️! :)
+---
 
+## 📜 License
+MIT — if you like Muya, a ⭐️ is always appreciated!
 
+---
 
+### Changelog / Contributing
+See repo issues and PRs. Keep changes small and measured—Muya’s value is simplicity.

package/esm/sqlite/table/table.js

@@ -1,4 +1,4 @@
-import{getWhereQuery as h}from"./where";const O=500,N=100;function D(E){return"$."+E}function I(E,n){if(!(!E||!n))return n.split(".").reduce((r,y)=>{if(typeof r=="object"&&r!==null&&y in r)return r[y]},E)}async function M(E){const{backend:n,tableName:r,indexes:y,key:S,disablePragmaOptimization:$}=E,d=S!==void 0;$||(await n.execute("PRAGMA journal_mode=WAL;"),await n.execute("PRAGMA synchronous=NORMAL;"),await n.execute("PRAGMA temp_store=MEMORY;"),await n.execute("PRAGMA cache_size=-20000;")),d?await n.execute(`
+import{getWhereQuery as p}from"./where";const O=500,N=100;function D(E){return"$."+E}function I(E,n){if(!(!E||!n))return n.split(".").reduce((r,y)=>{if(typeof r=="object"&&r!==null&&y in r)return r[y]},E)}async function M(E){const{backend:n,tableName:r,indexes:y,key:S,disablePragmaOptimization:$}=E,d=S!==void 0;$||(await n.execute("PRAGMA journal_mode=WAL;"),await n.execute("PRAGMA synchronous=NORMAL;"),await n.execute("PRAGMA temp_store=MEMORY;"),await n.execute("PRAGMA cache_size=-20000;")),d?await n.execute(`
       CREATE TABLE IF NOT EXISTS ${r} (
         key TEXT PRIMARY KEY,
         data TEXT NOT NULL
@@ -8,4 +8,4 @@ import{getWhereQuery as h}from"./where";const O=500,N=100;function D(E){return"$
         data TEXT NOT NULL
       );
     `);for(const t of y??[]){const o=String(t);await n.execute(`CREATE INDEX IF NOT EXISTS idx_${r}_${o.replaceAll(/\W/g,"_")}
-       ON ${r} (json_extract(data, '${D(o)}'));`)}function k(t){if(d)return I(t,String(S))}async function g(t){return(await t.select("SELECT changes() AS c"))[0]?.c??0}const p={backend:n,async set(t,o){const e=o??n,a=JSON.stringify(t);if(d){const s=k(t);if(s==null)throw new Error(`Document is missing the configured key "${String(S)}". Provide it or create the table without "key".`);if(await e.execute(`UPDATE ${r} SET data = ? WHERE key = ?`,[a,s]),await g(e)===1)return{key:s,op:"update"};try{return await e.execute(`INSERT INTO ${r} (key, data) VALUES (?, ?)`,[s,a]),{key:s,op:"insert"}}catch{return await e.execute(`UPDATE ${r} SET data = ? WHERE key = ?`,[a,s]),{key:s,op:"update"}}}await e.execute(`INSERT INTO ${r} (data) VALUES (?)`,[a]);const u=(await e.select("SELECT last_insert_rowid() AS id"))[0]?.id;if(typeof u!="number")throw new Error("Failed to retrieve last_insert_rowid()");return{key:u,op:"insert"}},async get(t,o=e=>e){const e=d?"key = ?":"rowid = ?",a=await n.select(`SELECT rowid, data FROM ${r} WHERE ${e}`,[t]);if(a.length===0)return;const{data:i,rowid:u}=a[0],s=JSON.parse(i);return o(s,{rowId:u})},async delete(t){const o=d?"key = ?":"rowid = ?";if(await n.execute(`DELETE FROM ${r} WHERE ${o}`,[t]),((await n.select("SELECT changes() AS c"))[0]?.c??0)>0)return{key:t,op:"delete"}},async*search(t={}){const{sortBy:o,order:e="asc",limit:a,offset:i=0,where:u,select:s=l=>l,stepSize:c=N}=t,w=h(u),f=`SELECT rowid, data FROM ${r} ${w}`;let T=0,A=i;for(;;){let l=f;o?l+=` ORDER BY json_extract(data, '${D(String(o))}') COLLATE NOCASE ${e.toUpperCase()}`:l+=d?` ORDER BY key COLLATE NOCASE ${e.toUpperCase()}`:` ORDER BY rowid ${e.toUpperCase()}`;const R=a?Math.min(c,a-T):c;l+=` LIMIT ${R} OFFSET ${A}`;const m=await n.select(l);if(m.length===0)break;for(const{rowid:b,data:L}of m){if(a&&T>=a)return;const x=JSON.parse(L);yield s(x,{rowId:b}),T++}if(m.length<R||a&&T>=a)break;A+=m.length}},async count(t={}){const o=h(t.where),e=`SELECT COUNT(*) as count FROM ${r} ${o}`;return(await n.select(e))[0]?.count??0},async deleteBy(t){const o=h(t),e=d?"key":"rowid",a=[];return await n.transaction(async i=>{const u=await i.select(`SELECT ${e} AS k FROM ${r} ${o}`);if(u.length===0)return;const s=u.map(c=>c.k);for(let c=0;c<s.length;c+=O){const w=s.slice(c,c+O),f=w.map(()=>"?").join(",");await i.execute(`DELETE FROM ${r} WHERE ${e} IN (${f})`,w)}for(const c of s)a.push({key:c,op:"delete"})}),a},async clear(){await n.execute(`DELETE FROM ${r}`)},async batchSet(t){const o=[];return await n.transaction(async e=>{for(const a of t){const i=await p.set(a,e);o.push(i)}}),o}};return p}export{N as DEFAULT_STEP_SIZE,M as createTable,I as getByPath};
+       ON ${r} (json_extract(data, '${D(o)}'));`)}function k(t){if(d)return I(t,String(S))}async function g(t){return(await t.select("SELECT changes() AS c"))[0]?.c??0}const h={backend:n,async set(t,o){const e=o??n,a=JSON.stringify(t);if(d){const s=k(t);if(s==null)throw new Error(`Document is missing the configured key "${String(S)}". Provide it or create the table without "key".`);if(await e.execute(`UPDATE ${r} SET data = ? WHERE key = ?`,[a,s]),await g(e)===1)return{key:s,op:"update"};try{return await e.execute(`INSERT INTO ${r} (key, data) VALUES (?, ?)`,[s,a]),{key:s,op:"insert"}}catch{return await e.execute(`UPDATE ${r} SET data = ? WHERE key = ?`,[a,s]),{key:s,op:"update"}}}await e.execute(`INSERT INTO ${r} (data) VALUES (?)`,[a]);const u=(await e.select("SELECT last_insert_rowid() AS id"))[0]?.id;if(typeof u!="number")throw new Error("Failed to retrieve last_insert_rowid()");return{key:u,op:"insert"}},async get(t,o=e=>e){const e=d?"key = ?":"rowid = ?",a=await n.select(`SELECT rowid, data FROM ${r} WHERE ${e}`,[t]);if(a.length===0)return;const{data:i,rowid:u}=a[0],s=JSON.parse(i);return o(s,{rowId:u})},async delete(t){const o=d?"key = ?":"rowid = ?";if(await n.execute(`DELETE FROM ${r} WHERE ${o}`,[t]),((await n.select("SELECT changes() AS c"))[0]?.c??0)>0)return{key:t,op:"delete"}},async*search(t={}){const{sortBy:o,order:e="asc",limit:a,offset:i=0,where:u,select:s=l=>l,stepSize:c=N}=t,w=p(u),f=`SELECT rowid, data FROM ${r} ${w}`;let T=0,A=i;for(;;){let l=f;o?l+=` ORDER BY json_extract(data, '${D(String(o))}') COLLATE NOCASE ${e.toUpperCase()}`:l+=d?` ORDER BY key COLLATE NOCASE ${e.toUpperCase()}`:` ORDER BY rowid ${e.toUpperCase()}`;const R=a?Math.min(c,a-T):c;l+=` LIMIT ${R} OFFSET ${A}`;const m=await n.select(l);if(m.length===0)break;for(const{rowid:b,data:L}of m){if(a&&T>=a)return;const x=JSON.parse(L);yield s(x,{rowId:b}),T++}if(m.length<R||a&&T>=a)break;A+=m.length}},async count(t={}){const o=p(t.where),e=`SELECT COUNT(*) as count FROM ${r} ${o}`;return(await n.select(e))[0]?.count??0},async deleteBy(t){const o=p(t),e=d?"key":"rowid",a=[];return await n.transaction(async i=>{const u=await i.select(`SELECT ${e} AS k FROM ${r} ${o}`);if(u.length===0)return;const s=u.map(c=>c.k);for(let c=0;c<s.length;c+=O){const w=s.slice(c,c+O),f=w.map(()=>"?").join(",");await i.execute(`DELETE FROM ${r} WHERE ${e} IN (${f})`,w)}for(const c of s)a.push({key:c,op:"delete"})}),a},async clear(){await n.execute(`DELETE FROM ${r}`)},async batchSet(t){const o=[];return await n.transaction(async e=>{for(const a of t){const i=await h.set(a,e);o.push(i)}}),o}};return h}export{N as DEFAULT_STEP_SIZE,M as createTable,I as getByPath,D as toJsonPath};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muya",
-  "version": "2.2.8",
+  "version": "2.3.0",
   "author": "samuel.gjabel@gmail.com",
   "repository": "https://github.com/samuelgjabel/muya",
   "main": "cjs/index.js",

package/src/__tests__/bench.test.tsx

@@ -12,6 +12,13 @@ import { useValue } from '../use-value'
 import { atom, useAtom } from 'jotai'
 import { create } from '../create'
 
+/**
+ * Utility to render a hook and measure the time it takes to reach a certain state
+ * @param hook The hook to render
+ * @param getValue Function to extract the value to monitor from the hook's return data
+ * @param toBe The target value to wait for
+ * @returns An object containing the hook's result, a waitFor function, and a promise that resolves with the time taken
+ */
 function renderPerfHook<T>(hook: () => T, getValue: (data: T) => number, toBe: number) {
   let onResolve = (_value: number) => {}
   const resolvePromise = new Promise<number>((resolve) => {

package/src/__tests__/test-utils.ts

@@ -1,6 +1,11 @@
 /* eslint-disable unicorn/prevent-abbreviations */
 import { Component } from 'react'
 
+/**
+ * Create a promise that resolves after a specified time
+ * @param time Time in ms to wait
+ * @returns A promise that resolves after the specified time
+ */
 export function longPromise(time = 200): Promise<number> {
   return new Promise((resolve) => {
     setTimeout(() => {

package/src/create-state.ts

@@ -12,6 +12,11 @@ interface GetStateOptions<T> {
 }
 
 let stateId = 0
+
+/**
+ * Generate a unique state ID
+ * @returns A unique state ID
+ */
 function getStateId() {
   return stateId++
 }
@@ -19,6 +24,8 @@ function getStateId() {
 type FullState<T> = GetStateOptions<T>['set'] extends undefined ? GetState<T> : State<T>
 /**
  * This is just utility function to create state base data
+ * @param options Options to create state
+ * @returns FullState<T>
  */
 export function createState<T>(options: GetStateOptions<T>): FullState<T> {
   const { get, destroy, set, getSnapshot } = options

package/src/create.ts

@@ -8,9 +8,16 @@ import { createState } from './create-state'
 export const STATE_SCHEDULER = createScheduler()
 
 /**
- * Create state from a default value.
+ * Create a new state with an initial value and optional equality check
+ * @param initialValue The initial value or a function that returns the initial value
+ * @param isEqual Optional custom equality check function
+ * @returns A State<T> object
  */
 export function create<T>(initialValue: DefaultValue<T>, isEqual: IsEqual<T> = isEqualBase): State<T> {
+  /**
+   * Get the current value of the state, initializing it if necessary.
+   * @returns The current value of the state
+   */
   function getValue(): T {
     try {
       if (isUndefined(state.cache.current)) {
@@ -28,6 +35,11 @@ export function create<T>(initialValue: DefaultValue<T>, isEqual: IsEqual<T> = i
     return state.cache.current
   }
 
+  /**
+   * Handle async set value when previous value is promise and new value is function
+   * @param previousPromise Previous promise
+   * @param value New value function
+   */
   async function handleAsyncSetValue(previousPromise: Promise<T>, value: SetStateCb<T>) {
     await previousPromise
     const newValue = value(state.cache.current as Awaited<T>)
@@ -35,6 +47,10 @@ export function create<T>(initialValue: DefaultValue<T>, isEqual: IsEqual<T> = i
     state.cache.current = resolvedValue
   }
 
+  /**
+   * Set value to state
+   * @param value Value to set
+   */
   function setValue(value: SetValue<T>) {
     const previous = getValue()
     const isFunctionValue = isSetValueFunction(value)

package/src/debug/development-tools.ts

@@ -20,6 +20,10 @@ interface SendOptions {
   value: unknown
   name: string
 }
+/**
+ * Send state information to Redux DevTools if available
+ * @param options Options containing message, type, value, and name
+ */
 function sendToDevelopmentTools(options: SendOptions) {
   if (!reduxDevelopmentTools) {
     return
@@ -31,12 +35,23 @@ function sendToDevelopmentTools(options: SendOptions) {
   reduxDevelopmentTools.send(name, { value, type, message }, type)
 }
 
+/**
+ * Create a listener function for development tools that sends state updates
+ * @param name The name of the state
+ * @param type The type of the state ('state' or 'derived')
+ * @returns A listener function that sends updates to development tools
+ */
 function developmentToolsListener(name: string, type: StateType) {
   return (value: unknown) => {
     sendToDevelopmentTools({ name, type, value, message: 'update' })
   }
 }
 
+/**
+ * Subscribe a state to development tools if available
+ * @param state The state to subscribe
+ * @returns A function to unsubscribe from development tools
+ */
 export function subscribeToDevelopmentTools<T>(state: State<T> | GetState<T>) {
   if (process.env.NODE_ENV === 'production') {
     return

package/src/scheduler.ts

@@ -27,6 +27,9 @@ export function createScheduler() {
   let frame = performance.now()
   let scheduled = false
 
+  /**
+   * Schedule the next flush based on time and item count thresholds
+   */
   function schedule() {
     const startFrame = performance.now()
     const frameSizeDiffIn = startFrame - frame
@@ -47,6 +50,9 @@ export function createScheduler() {
     }
   }
 
+  /**
+   * Flush the current batch of scheduled items
+   */
   function flush() {
     if (batches.size === 0) {
       return