muya 2.5.1 → 2.5.3

package/src/sqlite/create-sqlite.ts

@@ -2,7 +2,18 @@ import { STATE_SCHEDULER } from '../create'
 import { getId } from '../utils/id'
 import type { Backend } from './table'
 import { createTable } from './table/table'
-import type { DbOptions, DocType, Key, MutationResult, SearchOptions, Table } from './table/table.types'
+import type {
+  DbOptions,
+  DocType,
+  DotPath,
+  GetFieldType,
+  GroupByOptions,
+  GroupByResult,
+  Key,
+  MutationResult,
+  SearchOptions,
+  Table,
+} from './table/table.types'
 import type { Where } from './table/where'
 
 export interface CreateSqliteOptions<Document extends DocType> extends Omit<DbOptions<Document>, 'backend'> {
@@ -26,6 +37,10 @@ export interface SyncTable<Document extends DocType> {
   readonly count: (options?: { where?: Where<Document> }) => Promise<number>
   readonly deleteBy: (where: Where<Document>) => Promise<MutationResult<Document>[]>
   readonly clear: () => Promise<void>
+  readonly groupBy: <Field extends DotPath<Document>>(
+    field: Field,
+    options?: GroupByOptions<Document>,
+  ) => Promise<Array<GroupByResult<GetFieldType<Document, Field>>>>
 }
 
 /**
@@ -139,6 +154,10 @@ export function createSqliteState<Document extends DocType>(options: CreateSqlit
       const table = await getTable()
       return await table.count(countOptions)
     },
+    async groupBy(field, groupByOptions) {
+      const table = await getTable()
+      return await table.groupBy(field, groupByOptions)
+    },
   }
 
   return state

package/src/sqlite/table/table.ts

@@ -4,7 +4,18 @@
 /* eslint-disable @typescript-eslint/no-shadow */
 /* eslint-disable no-shadow */
 import type { Backend } from './backend'
-import type { Table, DbOptions, DocType, Key, SearchOptions, MutationResult } from './table.types'
+import type {
+  Table,
+  DbOptions,
+  DocType,
+  Key,
+  SearchOptions,
+  MutationResult,
+  GroupByResult,
+  GroupByOptions,
+  DotPath,
+  GetFieldType,
+} from './table.types'
 import { unicodeTokenizer, type FtsTokenizerOptions } from './tokenizer'
 import type { Where } from './where'
 import { getWhereQuery } from './where'
@@ -299,6 +310,23 @@ export async function createTable<Document extends DocType>(options: DbOptions<D
       await backend.execute(`DELETE FROM ${tableName}`)
     },
 
+    async groupBy<Field extends DotPath<Document>>(
+      field: Field,
+      options: GroupByOptions<Document> = {},
+    ): Promise<Array<GroupByResult<GetFieldType<Document, Field>>>> {
+      const whereSql = getWhereQuery<Document>(options.where, tableName)
+      const jsonPath = toJsonPath(String(field))
+      const query = `
+        SELECT json_extract(data, '${jsonPath}') AS groupKey, COUNT(*) AS count
+        FROM ${tableName}
+        ${whereSql}
+        GROUP BY groupKey
+      `
+      type FieldType = GetFieldType<Document, Field>
+      const results = await backend.select<Array<{ groupKey: FieldType; count: number }>>(query)
+      return results.map((row) => ({ key: row.groupKey, count: row.count }))
+    },
+
     async batchSet(documents: Document[]) {
       const mutations: MutationResult<Document>[] = []
       await backend.transaction(async (tx) => {

package/src/sqlite/table/table.types.ts

@@ -30,6 +30,18 @@ type DotPathRaw<T, D extends number = 5> = [D] extends [never]
 
 export type DotPath<T> = DotPathRaw<MakeAllFieldAsRequired<T>>
 
+/**
+ * Extract the value type at a given dot path
+ * e.g., GetFieldType<{ user: { name: string } }, 'user.name'> = string
+ */
+export type GetFieldType<T, Path extends string> = Path extends `${infer First}.${infer Rest}`
+  ? First extends keyof T
+    ? GetFieldType<T[First], Rest>
+    : never
+  : Path extends keyof T
+    ? T[Path]
+    : never
+
 // Built-in FTS5 tokenizers
 export type FtsTokenizer =
   | 'porter' // English stemming
@@ -86,6 +98,15 @@ interface MutationResultUpdateInsert<T> extends MutationResultBase<T> {
 
 export type MutationResult<T> = MutationResultDelete<T> | MutationResultUpdateInsert<T>
 
+export interface GroupByResult<K> {
+  readonly key: K
+  readonly count: number
+}
+
+export interface GroupByOptions<Document extends DocType> {
+  readonly where?: Where<Document>
+}
+
 export interface Table<Document extends DocType> extends DbNotGeneric {
   readonly set: (document: Document, backendOverride?: Backend) => Promise<MutationResult<Document>>
   readonly batchSet: (documents: Document[]) => Promise<MutationResult<Document>[]>
@@ -97,6 +118,10 @@ export interface Table<Document extends DocType> extends DbNotGeneric {
   readonly count: (options?: { where?: Where<Document> }) => Promise<number>
   readonly deleteBy: (where: Where<Document>) => Promise<MutationResult<Document>[]>
   readonly clear: () => Promise<void>
+  readonly groupBy: <Field extends DotPath<Document>>(
+    field: Field,
+    options?: GroupByOptions<Document>,
+  ) => Promise<Array<GroupByResult<GetFieldType<Document, Field>>>>
 }
 
 export type MakeAllFieldAsRequired<T> = {

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

@@ -1,5 +1,5 @@
 import type { Backend } from './table';
-import type { DbOptions, DocType, Key, MutationResult, SearchOptions } from './table/table.types';
+import type { DbOptions, DocType, DotPath, GetFieldType, GroupByOptions, GroupByResult, Key, MutationResult, SearchOptions } from './table/table.types';
 import type { Where } from './table/where';
 export interface CreateSqliteOptions<Document extends DocType> extends Omit<DbOptions<Document>, 'backend'> {
     readonly backend: Backend | Promise<Backend>;
@@ -21,6 +21,7 @@ export interface SyncTable<Document extends DocType> {
     }) => Promise<number>;
     readonly deleteBy: (where: Where<Document>) => Promise<MutationResult<Document>[]>;
     readonly clear: () => Promise<void>;
+    readonly groupBy: <Field extends DotPath<Document>>(field: Field, options?: GroupByOptions<Document>) => Promise<Array<GroupByResult<GetFieldType<Document, Field>>>>;
 }
 /**
  * Create a SyncTable that wraps a Table and provides reactive capabilities

package/types/sqlite/table/table.types.d.ts

@@ -19,6 +19,11 @@ type DotPathRaw<T, D extends number = 5> = [D] extends [never] ? never : T exten
     [K in Extract<keyof T, string>]: T[K] extends object ? K | `${K}.${DotPathRaw<T[K], Previous[D]>}` : K;
 }[Extract<keyof T, string>] : never;
 export type DotPath<T> = DotPathRaw<MakeAllFieldAsRequired<T>>;
+/**
+ * Extract the value type at a given dot path
+ * e.g., GetFieldType<{ user: { name: string } }, 'user.name'> = string
+ */
+export type GetFieldType<T, Path extends string> = Path extends `${infer First}.${infer Rest}` ? First extends keyof T ? GetFieldType<T[First], Rest> : never : Path extends keyof T ? T[Path] : never;
 export type FtsTokenizer = 'porter' | 'simple' | 'icu' | 'unicode61' | FtsTokenizerOptions;
 export interface FtsType<Document extends DocType> {
     readonly type: 'fts';
@@ -59,6 +64,13 @@ interface MutationResultUpdateInsert<T> extends MutationResultBase<T> {
     document: T;
 }
 export type MutationResult<T> = MutationResultDelete<T> | MutationResultUpdateInsert<T>;
+export interface GroupByResult<K> {
+    readonly key: K;
+    readonly count: number;
+}
+export interface GroupByOptions<Document extends DocType> {
+    readonly where?: Where<Document>;
+}
 export interface Table<Document extends DocType> extends DbNotGeneric {
     readonly set: (document: Document, backendOverride?: Backend) => Promise<MutationResult<Document>>;
     readonly batchSet: (documents: Document[]) => Promise<MutationResult<Document>[]>;
@@ -71,6 +83,7 @@ export interface Table<Document extends DocType> extends DbNotGeneric {
     }) => Promise<number>;
     readonly deleteBy: (where: Where<Document>) => Promise<MutationResult<Document>[]>;
     readonly clear: () => Promise<void>;
+    readonly groupBy: <Field extends DotPath<Document>>(field: Field, options?: GroupByOptions<Document>) => Promise<Array<GroupByResult<GetFieldType<Document, Field>>>>;
 }
 export type MakeAllFieldAsRequired<T> = {
     [K in keyof T]-?: T[K] extends object ? MakeAllFieldAsRequired<T[K]> : T[K];

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> {
     /**