muya 2.5.0 → 2.5.1

package/README.md

@@ -1,271 +1,525 @@
-# **Muya 🌀**
+# Muya
 
-*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**
-
----
+A tiny, type-safe state manager for React.
 
 [![Build](https://github.com/samuelgja/muya/actions/workflows/build.yml/badge.svg)](https://github.com/samuelgja/muya/actions/workflows/build.yml)
 [![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)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/muya?label=size)](https://bundlephobia.com/result?p=muya)
+[![npm](https://img.shields.io/npm/v/muya)](https://www.npmjs.com/package/muya)
+
+---
+
+## Why Muya?
 
-## ✨ 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
+| Feature        | useState + Context | Zustand | Jotai     | Muya            |
+| -------------- | ------------------ | ------- | --------- | --------------- |
+| Bundle size    | 0kb (built-in)     | ~2.9kb  | ~2.4kb    | **~1.5kb**      |
+| Boilerplate    | High               | Low     | Low       | **Minimal**     |
+| TypeScript     | Manual             | Good    | Good      | **First-class** |
+| Async support  | Manual             | Manual  | Built-in  | **Built-in**    |
+| Derived state  | Manual             | Manual  | Built-in  | **Built-in**    |
+| React Suspense | No                 | No      | Yes       | **Yes**         |
+| Batching       | React handles      | Manual  | Automatic | **Automatic**   |
 
 ---
 
-## 📦 Install
+## Installation
+
 ```bash
-bun add muya@latest
+npm install muya
 # or
-npm i muya@latest
+bun add muya
 # or
-yarn add muya@latest
+yarn add muya
 ```
 
 ---
 
-## 🏃 Quick Start
+## Quick Start
 
 ```tsx
 import { create } from 'muya'
 
-// 1) Make a state
 const counter = create(0)
 
-// 2) Read it inside React
-export function Counter() {
+function Counter() {
   const count = counter() // state is a hook
-  return (
-    <div>
-      <button onClick={() => counter.set(n => n + 1)}>+1</button>
-      <p>Count: {count}</p>
-    </div>
-  )
+  return <button onClick={() => counter.set((n) => n + 1)}>Count: {count}</button>
 }
 ```
 
+That's it. No providers, no setup, no boilerplate.
+
 ---
 
-## 🧩 Selecting / Deriving
+## Comparison
 
-Create derived states from one or many sources.
+### vs useState + useContext
 
-```ts
-import { create, select } from 'muya'
+**Before** (React Context):
+
+```tsx
+// 1. Create context
+const CountContext = createContext(null)
+
+// 2. Create provider component
+function CountProvider({ children }) {
+  const [count, setCount] = useState(0)
+  return <CountContext.Provider value={{ count, setCount }}>{children}</CountContext.Provider>
+}
+
+// 3. Create custom hook
+function useCount() {
+  const context = useContext(CountContext)
+  if (!context) throw new Error('Must be in provider')
+  return context
+}
+
+// 4. Wrap your app
+function App() {
+  return (
+    <CountProvider>
+      <Counter />
+    </CountProvider>
+  )
+}
 
-const a = create(1)
-const b = create(2)
+// 5. Finally use it
+function Counter() {
+  const { count, setCount } = useCount()
+  return <button onClick={() => setCount((n) => n + 1)}>{count}</button>
+}
+```
 
-// Single source
-const doubleA = a.select(n => n * 2)
+**After** (Muya):
+
+```tsx
+const counter = create(0)
 
-// Multiple sources
-const sum = select([a, b], (x, y) => x + y)
+function Counter() {
+  const count = counter()
+  return <button onClick={() => counter.set((n) => n + 1)}>{count}</button>
+}
 ```
 
-**Equality checks** (to avoid re-emits):
+### vs Zustand
+
+**Zustand**:
+
+```tsx
+import { create } from 'zustand'
 
-```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)
+const useStore = create((set) => ({
+  count: 0,
+  increment: () => set((state) => ({ count: state.count + 1 })),
+}))
+
+function Counter() {
+  const count = useStore((state) => state.count)
+  const increment = useStore((state) => state.increment)
+  return <button onClick={increment}>{count}</button>
+}
 ```
 
-You can also add an equality function on a `select`:
+**Muya**:
+
+```tsx
+import { create } from 'muya'
 
-```ts
-const stable = select([a, b], (x, y) => x + y, (prev, next) => prev === next)
+const counter = create(0)
+
+function Counter() {
+  const count = counter()
+  return <button onClick={() => counter.set((n) => n + 1)}>{count}</button>
+}
 ```
 
 ---
 
-## 🎣 Using in Components
+## Core API
+
+### `create(initial, isEqual?)`
 
-Muya states are callable hooks. Prefer that.  
-If you want a hook wrapper or slicing, use `useValue`.
+Create a state. The state itself is a hook.
+
+```tsx
+// Simple value
+const name = create('Ada')
+
+// Object
+const user = create({ id: 1, name: 'Ada', role: 'admin' })
+
+// Lazy (computed on first read)
+const expensive = create(() => computeExpensiveValue())
+
+// Async
+const data = create(fetch('/api/data').then((r) => r.json()))
+const lazyData = create(() => fetch('/api/data').then((r) => r.json()))
+
+// With equality check (skip updates when equal)
+const position = create({ x: 0, y: 0 }, (prev, next) => prev.x === next.x && prev.y === next.y)
+```
+
+### State Methods
+
+```tsx
+const counter = create(0)
+
+// Read (outside React)
+counter.get() // 0
+
+// Update
+counter.set(5)
+counter.set((prev) => prev + 1)
+
+// Subscribe (outside React)
+const unsubscribe = counter.listen((value) => console.log(value))
+
+// Derive new state
+const doubled = counter.select((n) => n * 2)
+
+// Debug name (for DevTools)
+counter.withName('counter')
+
+// Cleanup
+counter.destroy()
+```
+
+### `select([states], derive, isEqual?)`
+
+Derive state from multiple sources.
+
+```tsx
+import { create, select } from 'muya'
+
+const firstName = create('Ada')
+const lastName = create('Lovelace')
+
+const fullName = select([firstName, lastName], (first, last) => `${first} ${last}`)
+
+function Greeting() {
+  const name = fullName() // 'Ada Lovelace'
+  return <h1>Hello, {name}</h1>
+}
+```
+
+### `useValue(state, selector?)`
+
+Hook for reading state with optional selector.
 
 ```tsx
 import { create, useValue } from 'muya'
 
-const user = create({ id: 'u1', name: 'Ada', admin: false })
+const user = create({ id: 1, name: 'Ada', role: 'admin' })
 
-// Option 1: call the state directly
-function Profile() {
-  const u = user()
-  return <div>{u.name}</div>
+function UserName() {
+  // Only re-renders when name changes
+  const name = useValue(user, (u) => u.name)
+  return <span>{name}</span>
 }
+```
+
+### `useValueLoadable(state, selector?)`
+
+Hook for async states without Suspense. Returns `[value, isLoading, isError, error]`.
+
+```tsx
+import { create, useValueLoadable } from 'muya'
+
+const data = create(() => fetch('/api/data').then((r) => r.json()))
 
-// Option 2: useValue for a selector
-function OnlyName() {
-  const name = useValue(user, u => u.name)
-  return <div>{name}</div>
+function DataView() {
+  const [value, isLoading, isError, error] = useValueLoadable(data)
+
+  if (isLoading) return <Spinner />
+  if (isError) return <Error message={error.message} />
+  return <Display data={value} />
 }
 ```
 
 ---
 
-## ⚡ Async & Lazy (the 2-minute mental model)
+## Async States
+
+### Async Initialization
 
-**Immediate vs Lazy**
-```ts
-create(0)          // immediate: value exists now
-create(() => 0)    // lazy: computed on first read (.get() / component render)
+```tsx
+// Promise (loads immediately)
+const user = create(fetch('/api/user').then((r) => r.json()))
+
+// Lazy async (loads on first read)
+const user = create(() => fetch('/api/user').then((r) => r.json()))
 ```
 
-**Async sources**
-```ts
-async function fetchInitial() { return 0 }
-create(fetchInitial)          // lazy + async
-create(Promise.resolve(0))    // immediate + async
+### Async Updates
+
+```tsx
+const user = create(() => fetchUser())
+
+// Override immediately (cancels pending)
+user.set({ id: 1, name: 'New User' })
+
+// Wait for current value, then update
+user.set((prev) => ({ ...prev, name: 'Updated' }))
 ```
 
-**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
+### Async Selectors
+
+```tsx
+const userId = create(1)
 
-**Async selectors**
-```ts
-const base = create(0)
-const plusOne = base.select(async n => {
-  await doWork()
-  return n + 1
+const userDetails = userId.select(async (id) => {
+  const response = await fetch(`/api/users/${id}`)
+  return response.json()
 })
+
+// Suspends on first read
+function UserProfile() {
+  const details = userDetails()
+  return <Profile {...details} />
+}
 ```
-- 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
 
-> Tip: Prefer keeping selectors **sync** and performing async work **before** calling `set`. It keeps render trees predictable.
+### With Suspense
 
----
+```tsx
+const data = create(() => fetchData())
 
-## 🧪 API (short and sweet)
+function App() {
+  return (
+    <Suspense fallback={<Loading />}>
+      <DataView />
+    </Suspense>
+  )
+}
 
-### `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)
+function DataView() {
+  const value = data() // suspends until resolved
+  return <div>{value}</div>
+}
+```
 
-### `select([states], derive, isEqual?) => State<R>`
-Derive a state from one or multiple states.
+### Without Suspense
 
-### `useValue(state, selector?)`
-React hook to read a state or a slice.
+```tsx
+const data = create(() => fetchData())
 
----
+function DataView() {
+  const [value, isLoading, isError, error] = useValueLoadable(data)
 
-## 🪵 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.
+  if (isLoading) return <Loading />
+  if (isError) return <Error error={error} />
+  return <div>{value}</div>
+}
+```
 
 ---
 
-## 🤝 Patterns & Anti-patterns
+## Patterns
 
-**✅ Good**
-- Keep selectors pure and fast
-- Use equality checks to avoid unnecessary updates
-- Do async outside, then `set` synchronously
+### Computed Values
 
-**⚠️ 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
+```tsx
+const items = create([
+  { id: 1, name: 'Apple', price: 1.5, quantity: 2 },
+  { id: 2, name: 'Banana', price: 0.5, quantity: 5 },
+])
 
----
+const total = items.select((list) => list.reduce((sum, item) => sum + item.price * item.quantity, 0))
+
+const count = items.select((list) => list.length)
+```
 
-## 🧭 Examples
+### Actions
 
-**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
+const cart = create({ items: [], discount: 0 })
+
+const cartActions = {
+  addItem: (item) =>
+    cart.set((state) => ({
+      ...state,
+      items: [...state.items, item],
+    })),
+
+  applyDiscount: (percent) =>
+    cart.set((state) => ({
+      ...state,
+      discount: percent,
+    })),
+
+  clear: () => cart.set({ items: [], discount: 0 }),
+}
+
+// Usage
+cartActions.addItem({ id: 1, name: 'Book', price: 20 })
 ```
 
-**Batching inside events:**
-```ts
-function onCheckout() {
-  cart.set(c => applyDiscount(c))
-  total.set(t => t - 10)
-  // Muya batches internally; React sees one commit
+### Shallow Equality
+
+```tsx
+import { create, shallow } from 'muya'
+
+const list = create(
+  [1, 2, 3],
+  shallow, // built-in shallow comparison
+)
+
+// Won't notify if array contents are the same
+list.set([1, 2, 3])
+```
+
+### Batching
+
+Multiple updates in the same event are batched automatically:
+
+```tsx
+function checkout() {
+  cart.set((c) => applyDiscount(c))
+  total.set((t) => t - 10)
+  inventory.set((i) => decrementStock(i))
+  // React sees one render
 }
 ```
 
 ---
 
-## 🗃️ (Optional) Muya + SQLite Companion
+## DevTools
+
+Muya auto-connects to Redux DevTools in development.
+
+```tsx
+const counter = create(0).withName('counter')
+const user = create({ name: 'Ada' }).withName('user')
+```
+
+---
+
+## SQLite Companion
 
-If you’re using the companion `muya/sqlite` package, you can manage large, queryable lists with React-friendly pagination:
+For large, queryable lists with pagination. Works with expo-sqlite, better-sqlite3, or in-memory.
 
-```ts
-import { createSqliteState } from 'muya/sqlite'
-import { useSqliteValue } from 'muya/sqlite'
+```tsx
+import { createSqliteState, useSqliteValue } from 'muya/sqlite'
 
-type Person = { id: string; name: string; age: number }
+type Task = { id: string; title: string; done: boolean; priority: number }
 
-const people = createSqliteState<Person>({
-  backend,            // e.g. expo-sqlite / bunMemoryBackend
-  tableName: 'People',
+const tasks = createSqliteState<Task>({
+  backend,
+  tableName: 'tasks',
   key: 'id',
-  indexes: ['age'],   // optional
+  indexes: ['priority', 'done'],
 })
+```
+
+### React Hook with Pagination
+
+```tsx
+function TaskList() {
+  const [rows, actions] = useSqliteValue(tasks, { sortBy: 'priority', order: 'desc', limit: 20 }, [])
 
-// 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>
+      {rows.map((task) => (
+        <TaskItem key={task.id} task={task} />
+      ))}
+      <button onClick={actions.next}>Load more</button>
+      <button onClick={actions.reset}>Reset</button>
     </>
   )
 }
 ```
 
-**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%' }}})) { /* … */ }
+### CRUD Operations
+
+```tsx
+// Create
+await tasks.set({ id: '1', title: 'Buy milk', done: false, priority: 1 })
+
+// Batch create
+await tasks.batchSet([
+  { id: '2', title: 'Walk dog', done: false, priority: 2 },
+  { id: '3', title: 'Read book', done: true, priority: 3 },
+])
+
+// Read
+const task = await tasks.get('1')
+const title = await tasks.get('1', (t) => t.title)
+
+// Update
+await tasks.set({ id: '1', title: 'Buy milk', done: true, priority: 1 })
+
+// Delete
+await tasks.delete('1')
+
+// Batch delete
+await tasks.batchDelete(['2', '3'])
+
+// Count
+const total = await tasks.count()
+const pending = await tasks.count({ where: { done: false } })
 ```
 
----
+### Querying
 
-## ❓ FAQ
+```tsx
+// Search with where clause
+for await (const task of tasks.search({
+  where: { done: false, priority: { gt: 1 } },
+  orderBy: 'priority',
+  order: 'desc',
+})) {
+  console.log(task.title)
+}
 
-**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.
+```
 
-**Can I use Suspense?**  
-Yes. Async states/selectors will suspend on first read (and when upstream requires it).
+**Where clause operators:**
 
-**How do I avoid re-renders?**  
-Provide an `isEqual(prev, next)` to `create` or `select`, or select a smaller slice in `useValue`.
+| Operator | Example                         | Description            |
+| -------- | ------------------------------- | ---------------------- |
+| equals   | `{ done: false }`               | Exact match            |
+| gt       | `{ priority: { gt: 5 } }`       | Greater than           |
+| gte      | `{ priority: { gte: 5 } }`      | Greater than or equal  |
+| lt       | `{ priority: { lt: 5 } }`       | Less than              |
+| lte      | `{ priority: { lte: 5 } }`      | Less than or equal     |
+| like     | `{ title: { like: '%milk%' } }` | SQL LIKE pattern match |
 
 ---
 
-## 🧪 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.
+## TypeScript
+
+Full type inference out of the box:
+
+```tsx
+const user = create({ id: 1, name: 'Ada', role: 'admin' as const })
+// Type: State<{ id: number; name: string; role: 'admin' }>
+
+const role = user.select((u) => u.role)
+// Type: State<'admin'>
+
+const name = useValue(user, (u) => u.name)
+// Type: string
+```
 
 ---
 
-## 📜 License
-MIT — if you like Muya, a ⭐️ is always appreciated!
+## FAQ
+
+**Is Muya a replacement for Redux/Zustand/Jotai?**
+Muya is intentionally minimal. If you need middleware, devtools plugins, or large ecosystem, consider those alternatives.
+
+**How do I avoid re-renders?**
+Use `isEqual` function with `create`/`select`, or use a selector with `useValue` to subscribe to a slice.
+
+**Can I use Suspense?**
+Yes. Async states suspend on first read. Use `useValueLoadable` if you prefer loading states over Suspense.
+
+**Does it work with React Native?**
+Yes, Muya has no DOM dependencies.
 
 ---
 
-### Changelog / Contributing
-See repo issues and PRs. Keep changes small and measured—Muya’s value is simplicity.
+## License
+
+MIT

package/cjs/index.js

@@ -1 +1 @@
-"use strict";var V=Object.defineProperty;var N=Object.getOwnPropertyDescriptor;var K=Object.getOwnPropertyNames;var Y=Object.prototype.hasOwnProperty;var W=(e,t)=>{for(var o in t)V(e,o,{get:t[o],enumerable:!0})},J=(e,t,o,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of K(t))!Y.call(e,s)&&s!==o&&V(e,s,{get:()=>t[s],enumerable:!(a=N(t,s))||a.enumerable});return e};var Q=e=>J(V({},"__esModule",{value:!0}),e);var $={};W($,{EMPTY_SELECTOR:()=>D,create:()=>z,isAbortError:()=>I,isArray:()=>g,isEqualBase:()=>m,isError:()=>v,isFunction:()=>h,isMap:()=>x,isPromise:()=>f,isSet:()=>E,isSetValueFunction:()=>O,isState:()=>Z,isUndefined:()=>d,select:()=>k,shallow:()=>F,useValue:()=>C});module.exports=Q($);var T=class extends Error{static Error="AbortError"};function X(e,t){t&&t.abort();let o=new AbortController,{signal:a}=o;return{promise:new Promise((n,u)=>{a.addEventListener("abort",()=>{u(new T)}),e.then(n).catch(u)}),controller:o}}function y(e,t=m){if(!d(e.current)){if(!d(e.previous)&&t(e.current,e.previous))return!1;e.previous=e.current}return!0}function p(e,t){let{cache:o,emitter:{emit:a}}=e;if(!f(t))return t;o.abortController&&o.abortController.abort();let{promise:s,controller:n}=X(t,o.abortController);return o.abortController=n,s.then(u=>{o.current=u,a()}).catch(u=>{I(u)||(o.current=u,a())})}function f(e){return e instanceof Promise}function h(e){return typeof e=="function"}function x(e){return e instanceof Map}function E(e){return e instanceof Set}function g(e){return Array.isArray(e)}function m(e,t){return e===t?!0:!!Object.is(e,t)}function O(e){return typeof e=="function"}function I(e){return e instanceof T}function v(e){return e instanceof Error}function d(e){return e===void 0}function Z(e){return h(e)&&"get"in e&&"set"in e&&"isSet"in e&&e.isSet===!0}var D=e=>e;function U(){let e=new Map,t=new Set,o=performance.now(),a=!1;function s(){let u=performance.now(),r=u-o,{size:i}=t;if(r<.2&&i>0&&i<10){o=u,n();return}a||(a=!0,Promise.resolve().then(()=>{a=!1,o=performance.now(),n()}))}function n(){if(t.size===0)return;let u=new Set,r=new Map;for(let i of t){if(e.has(i.id)){u.add(i.id);let{onResolveItem:c}=e.get(i.id);c&&c(i.value),r.has(i.id)||r.set(i.id,[]),r.get(i.id).push(i.value)}t.delete(i)}if(t.size>0){s();return}for(let i of u){let c=r.get(i);e.get(i)?.onScheduleDone(c)}}return{add(u,r){return e.set(u,r),()=>{e.delete(u)}},schedule(u,r){t.add({value:r,id:u}),s()}}}function k(e,t,o){function a(){let c=!1,l=e.map(A=>{let w=A.get();return f(w)&&(c=!0),w});return c?new Promise((A,w)=>{Promise.all(l).then(G=>{if(G.some(_=>d(_)))return w(new T);let j=t(...G);A(j)})}):t(...l)}function s(){if(d(r.cache.current)){let c=a();r.cache.current=p(r,c)}return r.cache.current}function n(){if(d(r.cache.current)){let l=a();r.cache.current=p(r,l)}let{current:c}=r.cache;return f(c)?new Promise(l=>{c.then(S=>{if(d(S)){l(n());return}l(S)})}):r.cache.current}let u=[];for(let c of e){let l=c.emitter.subscribe(()=>{b.schedule(r.id,null)});u.push(l)}let r=P({destroy(){for(let c of u)c();i(),r.emitter.clear(),r.cache.current=void 0},get:n,getSnapshot:s}),i=b.add(r.id,{onScheduleDone(){let c=a();r.cache.current=p(r,c),y(r.cache,o)&&r.emitter.emit()}});return r}var R=require("react");var L=require("use-sync-external-store/shim/with-selector");function C(e,t=D){let{emitter:o}=e,a=(0,L.useSyncExternalStoreWithSelector)(e.emitter.subscribe,o.getSnapshot,o.getInitialSnapshot,t);if((0,R.useDebugValue)(a),f(a)||v(a))throw a;return a}function q(e,t){let o=new Set,a=[];return{clear:()=>{for(let s of a)s();o.clear()},subscribe:s=>(o.add(s),()=>{o.delete(s)}),emit:(...s)=>{for(let n of o)n(...s)},contains:s=>o.has(s),getSnapshot:e,getInitialSnapshot:t,getSize:()=>o.size,subscribeToOtherEmitter(s){let n=s.subscribe(()=>{this.emit()});a.push(n)}}}var M=0;function H(){return M++,M.toString(36)}function P(e){let{get:t,destroy:o,set:a,getSnapshot:s}=e,n=!!a,u={},r=function(i){return C(r,i)};return r.isSet=n,r.id=H(),r.emitter=q(s),r.destroy=o,r.listen=function(i){return this.emitter.subscribe(()=>{let c=t();f(c)||i(t())})},r.withName=function(i){return this.stateName=i,this},r.select=function(i,c=m){return k([r],i,c)},r.get=t,r.set=a,r.cache=u,r}var b=U();function z(e,t=m){function o(){try{if(d(n.cache.current)){let r=h(e)?e():e,i=p(n,r);return n.cache.current=i,n.cache.current}return n.cache.current}catch(r){n.cache.current=r}return n.cache.current}async function a(r,i){await r;let c=i(n.cache.current),l=p(n,c);n.cache.current=l}function s(r){let i=o(),c=O(r);if(c&&f(i)){a(i,r);return}n.cache.abortController&&n.cache.abortController.abort();let l=c?r(i):r,S=p(n,l);n.cache.current=S}let n=P({get:o,destroy(){o(),u(),n.emitter.clear(),n.cache.current=void 0},set(r){b.schedule(n.id,r)},getSnapshot:o}),u=b.add(n.id,{onScheduleDone(){n.cache.current=o(),y(n.cache,t)&&n.emitter.emit()},onResolveItem:s});return h(e)||o(),n}function F(e,t){if(e==t)return!0;if(typeof e!="object"||e==null||typeof t!="object"||t==null)return!1;if(x(e)&&x(t)){if(e.size!==t.size)return!1;for(let[s,n]of e)if(!Object.is(n,t.get(s)))return!1;return!0}if(E(e)&&E(t)){if(e.size!==t.size)return!1;for(let s of e)if(!t.has(s))return!1;return!0}if(g(e)&&g(t)){if(e.length!==t.length)return!1;for(let[s,n]of e.entries())if(!Object.is(n,t[s]))return!1;return!0}let o=Object.keys(e),a=Object.keys(t);if(o.length!==a.length)return!1;for(let s of o)if(!Object.prototype.hasOwnProperty.call(t,s)||!Object.is(e[s],t[s]))return!1;return!0}
+"use strict";var O=Object.defineProperty;var Y=Object.getOwnPropertyDescriptor;var W=Object.getOwnPropertyNames;var J=Object.prototype.hasOwnProperty;var Q=(e,t)=>{for(var n in t)O(e,n,{get:t[n],enumerable:!0})},X=(e,t,n,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of W(t))!J.call(e,s)&&s!==n&&O(e,s,{get:()=>t[s],enumerable:!(a=Y(t,s))||a.enumerable});return e};var Z=e=>X(O({},"__esModule",{value:!0}),e);var ee={};Q(ee,{EMPTY_SELECTOR:()=>w,create:()=>F,isAbortError:()=>v,isArray:()=>k,isEqualBase:()=>S,isError:()=>b,isFunction:()=>h,isMap:()=>g,isPromise:()=>l,isSet:()=>P,isSetValueFunction:()=>D,isState:()=>B,isUndefined:()=>f,select:()=>V,shallow:()=>j,useValue:()=>C,useValueLoadable:()=>_});module.exports=Z(ee);var T=class extends Error{static Error="AbortError"};function $(e,t){t&&t.abort();let n=new AbortController,{signal:a}=n;return{promise:new Promise((o,c)=>{a.addEventListener("abort",()=>{c(new T)}),e.then(o).catch(c)}),controller:n}}function E(e,t=S){if(!f(e.current)){if(!f(e.previous)&&t(e.current,e.previous))return!1;e.previous=e.current}return!0}function p(e,t){let{cache:n,emitter:{emit:a}}=e;if(!l(t))return t;n.abortController&&n.abortController.abort();let{promise:s,controller:o}=$(t,n.abortController);return n.abortController=o,s.then(c=>{n.current=c,a()}).catch(c=>{v(c)||(n.current=c,a())})}function l(e){return e instanceof Promise}function h(e){return typeof e=="function"}function g(e){return e instanceof Map}function P(e){return e instanceof Set}function k(e){return Array.isArray(e)}function S(e,t){return e===t?!0:!!Object.is(e,t)}function D(e){return typeof e=="function"}function v(e){return e instanceof T}function b(e){return e instanceof Error}function f(e){return e===void 0}function B(e){return h(e)&&"get"in e&&"set"in e&&"isSet"in e&&e.isSet===!0}var w=e=>e;function G(){let e=new Map,t=new Set,n=performance.now(),a=!1;function s(){let c=performance.now(),r=c-n,{size:i}=t;if(r<.2&&i>0&&i<10){n=c,o();return}a||(a=!0,Promise.resolve().then(()=>{a=!1,n=performance.now(),o()}))}function o(){if(t.size===0)return;let c=new Set,r=new Map;for(let i of t){if(e.has(i.id)){c.add(i.id);let{onResolveItem:u}=e.get(i.id);u&&u(i.value),r.has(i.id)||r.set(i.id,[]),r.get(i.id).push(i.value)}t.delete(i)}if(t.size>0){s();return}for(let i of c){let u=r.get(i);e.get(i)?.onScheduleDone(u)}}return{add(c,r){return e.set(c,r),()=>{e.delete(c)}},schedule(c,r){t.add({value:r,id:c}),s()}}}function V(e,t,n){function a(){let u=!1,d=e.map(L=>{let x=L.get();return l(x)&&(u=!0),x});return u?new Promise((L,x)=>{Promise.all(d).then(R=>{if(R.some(K=>f(K)))return x(new T);let N=t(...R);L(N)})}):t(...d)}function s(){if(f(r.cache.current)){let u=a();r.cache.current=p(r,u)}return r.cache.current}function o(){if(f(r.cache.current)){let d=a();r.cache.current=p(r,d)}let{current:u}=r.cache;return l(u)?new Promise(d=>{u.then(m=>{if(f(m)){d(o());return}d(m)})}):r.cache.current}let c=[];for(let u of e){let d=u.emitter.subscribe(()=>{y.schedule(r.id,null)});c.push(d)}let r=A({destroy(){for(let u of c)u();i(),r.emitter.clear(),r.cache.current=void 0},get:o,getSnapshot:s}),i=y.add(r.id,{onScheduleDone(){let u=a();r.cache.current=p(r,u),E(r.cache,n)&&r.emitter.emit()}});return r}var U=require("react");var M=require("use-sync-external-store/shim/with-selector");function C(e,t=w){let{emitter:n}=e,a=(0,M.useSyncExternalStoreWithSelector)(e.emitter.subscribe,n.getSnapshot,n.getInitialSnapshot,t);if((0,U.useDebugValue)(a),l(a)||b(a))throw a;return a}function q(e,t){let n=new Set,a=[];return{clear:()=>{for(let s of a)s();n.clear()},subscribe:s=>(n.add(s),()=>{n.delete(s)}),emit:(...s)=>{for(let o of n)o(...s)},contains:s=>n.has(s),getSnapshot:e,getInitialSnapshot:t,getSize:()=>n.size,subscribeToOtherEmitter(s){let o=s.subscribe(()=>{this.emit()});a.push(o)}}}var H=0;function z(){return H++,H.toString(36)}function A(e){let{get:t,destroy:n,set:a,getSnapshot:s}=e,o=!!a,c={},r=function(i){return C(r,i)};return r.isSet=o,r.id=z(),r.emitter=q(s),r.destroy=n,r.listen=function(i){return this.emitter.subscribe(()=>{let u=t();l(u)||i(t())})},r.withName=function(i){return this.stateName=i,this},r.select=function(i,u=S){return V([r],i,u)},r.get=t,r.set=a,r.cache=c,r}var y=G();function F(e,t=S){function n(){try{if(f(o.cache.current)){let r=h(e)?e():e,i=p(o,r);return o.cache.current=i,o.cache.current}return o.cache.current}catch(r){o.cache.current=r}return o.cache.current}async function a(r,i){await r;let u=i(o.cache.current),d=p(o,u);o.cache.current=d}function s(r){let i=n(),u=D(r);if(u&&l(i)){a(i,r);return}o.cache.abortController&&o.cache.abortController.abort();let d=u?r(i):r,m=p(o,d);o.cache.current=m}let o=A({get:n,destroy(){n(),c(),o.emitter.clear(),o.cache.current=void 0},set(r){y.schedule(o.id,r)},getSnapshot:n}),c=y.add(o.id,{onScheduleDone(){o.cache.current=n(),E(o.cache,t)&&o.emitter.emit()},onResolveItem:s});return h(e)||n(),o}var I=require("react");function _(e,t=w){let{emitter:n}=e,a=(0,I.useSyncExternalStore)(n.subscribe,n.getSnapshot,n.getInitialSnapshot);return(0,I.useDebugValue)(a),l(a)?[void 0,!0,!1,void 0]:b(a)?[void 0,!1,!0,a]:[t(a),!1,!1,void 0]}function j(e,t){if(e==t)return!0;if(typeof e!="object"||e==null||typeof t!="object"||t==null)return!1;if(g(e)&&g(t)){if(e.size!==t.size)return!1;for(let[s,o]of e)if(!Object.is(o,t.get(s)))return!1;return!0}if(P(e)&&P(t)){if(e.size!==t.size)return!1;for(let s of e)if(!t.has(s))return!1;return!0}if(k(e)&&k(t)){if(e.length!==t.length)return!1;for(let[s,o]of e.entries())if(!Object.is(o,t[s]))return!1;return!0}let n=Object.keys(e),a=Object.keys(t);if(n.length!==a.length)return!1;for(let s of n)if(!Object.prototype.hasOwnProperty.call(t,s)||!Object.is(e[s],t[s]))return!1;return!0}

package/esm/index.js

@@ -1 +1 @@
-export*from"./utils/is";export*from"./types";import{create as f}from"./create";import{select as p}from"./select";import{useValue as l}from"./use-value";import{shallow as s}from"./utils/shallow";export{f as create,p as select,s as shallow,l as useValue};
+export*from"./utils/is";export*from"./types";import{create as a}from"./create";import{select as p}from"./select";import{useValue as m}from"./use-value";import{useValueLoadable as s}from"./use-value-loadable";import{shallow as b}from"./utils/shallow";export{a as create,p as select,b as shallow,m as useValue,s as useValueLoadable};

package/esm/use-value-loadable.js

@@ -0,0 +1 @@
+import{useDebugValue as n,useSyncExternalStore as s}from"react";import{EMPTY_SELECTOR as u}from"./types";import{isError as r,isPromise as l}from"./utils/is";function b(t,d=u){const{emitter:a}=t,e=s(a.subscribe,a.getSnapshot,a.getInitialSnapshot);return n(e),l(e)?[void 0,!0,!1,void 0]:r(e)?[void 0,!1,!0,e]:[d(e),!1,!1,void 0]}export{b as useValueLoadable};

package/package.json

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

package/src/__tests__/use-value-loadable.test.tsx

@@ -0,0 +1,135 @@
+import { renderHook, act } from '@testing-library/react-hooks'
+import { waitFor } from '@testing-library/react'
+import { create } from '../create'
+import { useValueLoadable } from '../use-value-loadable'
+import { longPromise } from './test-utils'
+
+describe('useValueLoadable', () => {
+  it('should return value immediately for sync state', () => {
+    const state = create(42)
+    const { result } = renderHook(() => useValueLoadable(state))
+
+    const [value, isLoading, isError, error] = result.current
+    expect(value).toBe(42)
+    expect(isLoading).toBe(false)
+    expect(isError).toBe(false)
+    expect(error).toBeUndefined()
+  })
+
+  it('should return loading state for async state', async () => {
+    const state = create(longPromise(50))
+    const { result } = renderHook(() => useValueLoadable(state))
+
+    // Initially loading
+    expect(result.current[0]).toBeUndefined()
+    expect(result.current[1]).toBe(true)
+    expect(result.current[2]).toBe(false)
+    expect(result.current[3]).toBeUndefined()
+
+    // After resolution
+    await waitFor(() => {
+      expect(result.current[0]).toBe(0)
+      expect(result.current[1]).toBe(false)
+      expect(result.current[2]).toBe(false)
+      expect(result.current[3]).toBeUndefined()
+    })
+  })
+
+  it('should return error state when state throws', () => {
+    const testError = new Error('Test error')
+    const state = create(() => {
+      throw testError
+    })
+    const { result } = renderHook(() => useValueLoadable(state))
+
+    const [value, isLoading, isError, error] = result.current
+    expect(value).toBeUndefined()
+    expect(isLoading).toBe(false)
+    expect(isError).toBe(true)
+    expect(error).toBe(testError)
+  })
+
+  it('should return error state when async state rejects', async () => {
+    const testError = new Error('Async error')
+    const state = create(Promise.reject(testError))
+    const { result } = renderHook(() => useValueLoadable(state))
+
+    await waitFor(() => {
+      expect(result.current[0]).toBeUndefined()
+      expect(result.current[1]).toBe(false)
+      expect(result.current[2]).toBe(true)
+      expect(result.current[3]).toBe(testError)
+    })
+  })
+
+  it('should update when sync state changes', async () => {
+    const state = create(1)
+    const { result } = renderHook(() => useValueLoadable(state))
+
+    expect(result.current[0]).toBe(1)
+
+    act(() => {
+      state.set(2)
+    })
+
+    await waitFor(() => {
+      expect(result.current[0]).toBe(2)
+      expect(result.current[1]).toBe(false)
+      expect(result.current[2]).toBe(false)
+    })
+  })
+
+  it('should work with selector', () => {
+    const state = create({ count: 10, name: 'test' })
+    const { result } = renderHook(() => useValueLoadable(state, (s) => s.count))
+
+    const [value, isLoading, isError] = result.current
+    expect(value).toBe(10)
+    expect(isLoading).toBe(false)
+    expect(isError).toBe(false)
+  })
+
+  it('should work with selector on async state', async () => {
+    const state = create(Promise.resolve({ count: 5, name: 'async' }))
+    const { result } = renderHook(() => useValueLoadable(state, (s) => s.count))
+
+    // Initially loading
+    expect(result.current[1]).toBe(true)
+
+    await waitFor(() => {
+      expect(result.current[0]).toBe(5)
+      expect(result.current[1]).toBe(false)
+    })
+  })
+
+  it('should not throw to suspense boundary', async () => {
+    const state = create(longPromise(50))
+    const renderCount = jest.fn()
+
+    const { result } = renderHook(() => {
+      renderCount()
+      return useValueLoadable(state)
+    })
+
+    // Should render without throwing
+    expect(renderCount).toHaveBeenCalled()
+    expect(result.current[1]).toBe(true)
+
+    await waitFor(() => {
+      expect(result.current[1]).toBe(false)
+    })
+  })
+
+  it('should provide type narrowing when isLoading is false', () => {
+    const state = create(42)
+    const { result } = renderHook(() => useValueLoadable(state))
+
+    const [value, isLoading, isError] = result.current
+
+    if (!isLoading && !isError) {
+      // TypeScript should know value is number here
+      const number_: number = value
+      expect(number_).toBe(42)
+    }
+  })
+})

package/src/index.ts

@@ -3,4 +3,5 @@ export * from './types'
 export { create } from './create'
 export { select } from './select'
 export { useValue } from './use-value'
+export { useValueLoadable, type LoadableResult } from './use-value-loadable'
 export { shallow } from './utils/shallow'

package/src/use-value-loadable.ts

@@ -0,0 +1,39 @@
+import { useDebugValue, useSyncExternalStore } from 'react'
+import { EMPTY_SELECTOR, type GetState } from './types'
+import { isError, isPromise } from './utils/is'
+
+type LoadableLoading = [undefined, true, false, undefined]
+type LoadableSuccess<T> = [T, false, false, undefined]
+type LoadableError = [undefined, false, true, Error]
+
+export type LoadableResult<T> = LoadableLoading | LoadableSuccess<T> | LoadableError
+
+/**
+ * React hook to subscribe to a state and get its value without throwing to Suspense.
+ * Returns a tuple of [value, isLoading, isError, error] for handling async states.
+ * @param state The state to subscribe to
+ * @param selector Optional function to derive a value from the state
+ * @returns Tuple of [value, isLoading, isError, error] with discriminated union types
+ */
+export function useValueLoadable<T, S = undefined>(
+  state: GetState<T>,
+  selector: (stateValue: Awaited<T>) => S = EMPTY_SELECTOR,
+): LoadableResult<undefined extends S ? Awaited<T> : S> {
+  const { emitter } = state
+
+  const rawValue = useSyncExternalStore(emitter.subscribe, emitter.getSnapshot, emitter.getInitialSnapshot)
+
+  useDebugValue(rawValue)
+
+  if (isPromise(rawValue)) {
+    return [undefined, true, false, undefined] as LoadableResult<undefined extends S ? Awaited<T> : S>
+  }
+
+  if (isError(rawValue)) {
+    return [undefined, false, true, rawValue] as LoadableResult<undefined extends S ? Awaited<T> : S>
+  }
+
+  const selectedValue = selector(rawValue as Awaited<T>)
+
+  return [selectedValue, false, false, undefined] as LoadableResult<undefined extends S ? Awaited<T> : S>
+}

package/types/index.d.ts

@@ -3,4 +3,5 @@ export * from './types';
 export { create } from './create';
 export { select } from './select';
 export { useValue } from './use-value';
+export { useValueLoadable, type LoadableResult } from './use-value-loadable';
 export { shallow } from './utils/shallow';

package/types/use-value-loadable.d.ts

@@ -0,0 +1,14 @@
+import { type GetState } from './types';
+type LoadableLoading = [undefined, true, false, undefined];
+type LoadableSuccess<T> = [T, false, false, undefined];
+type LoadableError = [undefined, false, true, Error];
+export type LoadableResult<T> = LoadableLoading | LoadableSuccess<T> | LoadableError;
+/**
+ * React hook to subscribe to a state and get its value without throwing to Suspense.
+ * Returns a tuple of [value, isLoading, isError, error] for handling async states.
+ * @param state The state to subscribe to
+ * @param selector Optional function to derive a value from the state
+ * @returns Tuple of [value, isLoading, isError, error] with discriminated union types
+ */
+export declare function useValueLoadable<T, S = undefined>(state: GetState<T>, selector?: (stateValue: Awaited<T>) => S): LoadableResult<undefined extends S ? Awaited<T> : S>;
+export {};

package/esm/sqlite/select-sql.js

@@ -1 +0,0 @@
-import{createState as l}from"../create-state";let n=0;function o(){return n++,`${n.toString(36)}-sql`}function S(r,a){const{subscribe:c,updateSearchOptions:s}=r,m=o();return(...u)=>{const e=o(),p=c(e,m,()=>{t.emitter.emit()}),i=a(...u),t=l({destroy(){p(),t.emitter.clear(),t.cache.current=void 0},get(){return r.getSnapshot(e)},getSnapshot(){return r.getSnapshot(e)}});return s(e,i),t}}export{S as selectSql};

package/src/sqlite/select-sql.ts

@@ -1,65 +0,0 @@
-import { createState } from '../create-state'
-import type { GetState } from '../types'
-import type { SyncTable } from './create-sqlite'
-import type { DocType, DotPath } from './table/table.types'
-import type { Where } from './table/where'
-
-export type CreateState<Document, Params extends unknown[]> = (...params: Params) => GetState<Document[]>
-
-export interface SqlSeachOptions<Document extends DocType> {
-  readonly sortBy?: DotPath<Document>
-  readonly order?: 'asc' | 'desc'
-  readonly limit?: number
-  readonly offset?: number
-  readonly where?: Where<Document>
-  readonly stepSize?: number
-}
-
-let stateId = 0
-/**
- * Generate a unique state ID
- * @returns A unique state ID
- */
-function getStateId() {
-  stateId++
-  return `${stateId.toString(36)}-sql`
-}
-
-/**
- * Create a state that derives its value from a SyncTable using a compute function
- * @param state The SyncTable to derive from
- * @param compute A function that takes parameters and returns SqlSeachOptions to filter the SyncTable
- * @returns A function that takes parameters and returns a GetState of the derived documents
- */
-export function selectSql<Document extends DocType, Params extends unknown[] = []>(
-  state: SyncTable<Document>,
-  compute: (...args: Params) => SqlSeachOptions<Document>,
-): CreateState<Document, Params> {
-  const { subscribe, updateSearchOptions } = state
-  const componentId = getStateId()
-  const result: CreateState<Document, Params> = (...params) => {
-    const searchId = getStateId()
-    const destroy = subscribe(searchId, componentId, () => {
-      getState.emitter.emit()
-    })
-
-    const options = compute(...params)
-    const getState = createState<Document[]>({
-      destroy() {
-        destroy()
-        getState.emitter.clear()
-        getState.cache.current = undefined
-      },
-      get() {
-        return state.getSnapshot(searchId)
-      },
-      getSnapshot() {
-        return state.getSnapshot(searchId)
-      },
-    })
-    updateSearchOptions<Document>(searchId, options)
-
-    return getState
-  }
-  return result
-}

package/types/sqlite/select-sql.d.ts

@@ -1,20 +0,0 @@
-import type { GetState } from '../types';
-import type { SyncTable } from './create-sqlite';
-import type { DocType, DotPath } from './table/table.types';
-import type { Where } from './table/where';
-export type CreateState<Document, Params extends unknown[]> = (...params: Params) => GetState<Document[]>;
-export interface SqlSeachOptions<Document extends DocType> {
-    readonly sortBy?: DotPath<Document>;
-    readonly order?: 'asc' | 'desc';
-    readonly limit?: number;
-    readonly offset?: number;
-    readonly where?: Where<Document>;
-    readonly stepSize?: number;
-}
-/**
- * Create a state that derives its value from a SyncTable using a compute function
- * @param state The SyncTable to derive from
- * @param compute A function that takes parameters and returns SqlSeachOptions to filter the SyncTable
- * @returns A function that takes parameters and returns a GetState of the derived documents
- */
-export declare function selectSql<Document extends DocType, Params extends unknown[] = []>(state: SyncTable<Document>, compute: (...args: Params) => SqlSeachOptions<Document>): CreateState<Document, Params>;