muya 2.2.9 → 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/package.json

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