muya 2.5.0 → 2.5.2

package/src/sqlite/use-sqlite.ts

@@ -1,11 +1,25 @@
 /* eslint-disable sonarjs/cognitive-complexity */
-import { useCallback, useLayoutEffect, useReducer, useRef, type DependencyList } from 'react'
+import { useCallback, useLayoutEffect, useReducer, useRef, useState, type DependencyList } from 'react'
 import type { SyncTable } from './create-sqlite'
 import type { DocType, Key, SqlSeachOptions } from './table/table.types'
 import { DEFAULT_PAGE_SIZE } from './table'
 import { shallow } from '../utils/shallow'
 const MAX_ITERATIONS = 10_000
 
+/**
+ * Shallow compare two dependency arrays
+ * @param previousDeps Previous deps array
+ * @param nextDeps Next deps array
+ * @returns True if arrays have same length and all items are strictly equal
+ */
+function shallowEqualDeps(previousDeps: DependencyList, nextDeps: DependencyList): boolean {
+  if (previousDeps.length !== nextDeps.length) return false
+  for (const [index, previousDep] of previousDeps.entries()) {
+    if (!Object.is(previousDep, nextDeps[index])) return false
+  }
+  return true
+}
+
 export interface SqLiteActions {
   /**
    * Load the next page of results and return if isDone to show more results.
@@ -17,8 +31,15 @@ export interface SqLiteActions {
    * @returns void
    */
   readonly reset: () => Promise<void>
+  /**
+   * Map of document keys to their index in the results array.
+   */
   readonly keysIndex: Map<Key, number>
-  readonly isResetting?: boolean
+  /**
+   * True when deps changed but fresh data hasn't loaded yet.
+   * Use this to show stale/dimmed UI while new results are loading.
+   */
+  readonly isStale: boolean
 }
 
 export interface UseSearchOptions<Document extends DocType, Selected = Document> extends SqlSeachOptions<Document> {
@@ -48,6 +69,11 @@ export function useSqliteValue<Document extends DocType, Selected = Document>(
   const keysIndex = useRef(new Map<Key, number>())
   const iteratorRef = useRef<AsyncIterableIterator<{ doc: Document; meta: { key: Key } }> | null>(null)
 
+  // Track "settled" deps - the deps value when data last finished loading
+  // isStale is derived: true when current deps differ from settled deps
+  const [settledDeps, setSettledDeps] = useState<DependencyList | null>(null)
+  const isStale = settledDeps === null || !shallowEqualDeps(settledDeps, deps)
+
   const updateIterator = useCallback(() => {
     // eslint-disable-next-line sonarjs/no-unused-vars
     const { select: _ignore, ...resetOptions } = options
@@ -198,17 +224,26 @@ export function useSqliteValue<Document extends DocType, Selected = Document>(
   }, [state])
 
   useLayoutEffect(() => {
+    // Capture current deps for this effect invocation
+    const currentDeps = deps
     resetDataAndUpdateIterator()
-    nextPage()
+    nextPage().then(() => {
+      // Mark these deps as settled when data finishes loading
+      setSettledDeps(currentDeps)
+    })
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, deps)
 
   const resetCb = useCallback(async () => {
+    // Set settledDeps to null to make isStale=true during reset
+    setSettledDeps(null)
     resetDataAndUpdateIterator()
     await nextPage()
-  }, [nextPage, resetDataAndUpdateIterator])
+    // After data loads, mark current deps as settled
+    setSettledDeps(deps)
+  }, [nextPage, resetDataAndUpdateIterator, deps])
 
-  return [itemsRef.current, { nextPage, reset: resetCb, keysIndex: keysIndex.current }] as [
+  return [itemsRef.current, { nextPage, reset: resetCb, keysIndex: keysIndex.current, isStale }] as [
     (undefined extends Selected ? Document[] : Selected[]) | null,
     SqLiteActions,
   ]

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/sqlite/use-sqlite.d.ts

@@ -12,8 +12,15 @@ export interface SqLiteActions {
      * @returns void
      */
     readonly reset: () => Promise<void>;
+    /**
+     * Map of document keys to their index in the results array.
+     */
     readonly keysIndex: Map<Key, number>;
-    readonly isResetting?: boolean;
+    /**
+     * True when deps changed but fresh data hasn't loaded yet.
+     * Use this to show stale/dimmed UI while new results are loading.
+     */
+    readonly isStale: boolean;
 }
 export interface UseSearchOptions<Document extends DocType, Selected = Document> extends SqlSeachOptions<Document> {
     /**

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>;