muya 2.2.8 → 2.2.9

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.2.9",
   "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

package/src/select.ts

@@ -13,14 +13,23 @@ type AwaitedArray<T extends Array<unknown>> = {
   [K in keyof T]: Awaited<T[K]>
 }
 /**
- * Selecting state from multiple states.
- * It will create new state in read-only mode (without set).
+ * Create a derived state from multiple dependency states using a selector function
+ * @param states An array of dependency states
+ * @param selector A function that takes the values of the dependency states and returns a derived value
+ * @param isEqual Optional custom equality check function to prevent unnecessary updates
+ * @returns A GetState<T> representing the derived state
  */
 export function select<T = unknown, S extends Array<unknown> = []>(
   states: StateDependencies<S>,
   selector: (...values: AwaitedArray<S>) => T,
   isEqual?: IsEqual<T>,
 ): GetState<T> {
+  /**
+   * Compute the derived value based on the current values of the dependency states.
+   * If any dependency state is a promise, the result will be a promise that resolves
+   * once all dependencies are resolved.
+   * @returns The computed value or a promise that resolves to the computed value
+   */
   function computedValue(): T {
     let hasPromise = false
     const values = states.map((state) => {
@@ -47,6 +56,11 @@ export function select<T = unknown, S extends Array<unknown> = []>(
     const result = selector(...(values as AwaitedArray<S>))
     return result
   }
+  /**
+   * Get the current snapshot of the derived state.
+   * If the current cached value is undefined, it computes a new value.
+   * @returns The current snapshot value of the derived state
+   */
   function getSnapshot(): T {
     if (isUndefined(state.cache.current)) {
       const newValue = computedValue()
@@ -54,6 +68,12 @@ export function select<T = unknown, S extends Array<unknown> = []>(
     }
     return state.cache.current
   }
+  /**
+   * Get the current value of the derived state, initializing it if necessary.
+   * If the current cached value is a promise, it returns a new promise that resolves
+   * once the cached promise resolves, ensuring that undefined values are re-evaluated.
+   * @returns The current value of the derived state or a promise that resolves to it
+   */
   function getValue(): T {
     if (isUndefined(state.cache.current)) {
       const newValue = computedValue()

package/src/sqlite/__tests__/use-sqlite.test.tsx

@@ -1,3 +1,4 @@
+/* eslint-disable jsdoc/require-jsdoc */
 import { act, renderHook } from '@testing-library/react-hooks'
 import { createSqliteState } from '../create-sqlite'
 import { useSqliteValue } from '../use-sqlite'

package/src/sqlite/create-sqlite.ts

@@ -13,6 +13,10 @@ type SearchId = string
 const STATE_SCHEDULER = createScheduler()
 
 let stateId = 0
+/**
+ * Get a unique state ID
+ * @returns The unique state ID
+ */
 function getStateId() {
   return stateId++
 }
@@ -50,13 +54,28 @@ interface DataItems<Document extends DocType> {
   options?: SearchOptions<Document, unknown>
 }
 
+/**
+ * Create a SyncTable that wraps a Table and provides reactive capabilities
+ * @param options Options to create the SyncTable, including the backend and table name
+ * @returns A SyncTable instance with methods to interact with the underlying Table and manage reactive searches
+ */
 export function createSqliteState<Document extends DocType>(options: CreateSqliteOptions<Document>): SyncTable<Document> {
   const id = getStateId()
+
+  /**
+   * Get a unique schedule ID for a search ID
+   * @param searchId The search ID
+   * @returns The unique schedule ID
+   */
   function getScheduleId(searchId: SearchId) {
     return `state-${id}-search-${searchId}`
   }
 
   let cachedTable: Table<Document> | undefined
+  /**
+   * Get or create the underlying table
+   * @returns The Table instance
+   */
   async function getTable() {
     if (!cachedTable) {
       const { backend, ...rest } = options
@@ -75,6 +94,12 @@ export function createSqliteState<Document extends DocType>(options: CreateSqlit
   const listeners = new Map<SearchId, () => void>()
   const iterators = new Map<SearchId, AsyncIterableIterator<NextResult>>()
 
+  /**
+   * Next step in the iterator
+   * @param searchId The search ID
+   * @param data The data items to process
+   * @returns boolean indicating if new items were added
+   */
   async function next(searchId: SearchId, data: DataItems<Document>): Promise<boolean> {
     const iterator = iterators.get(searchId)
     const { options = {} } = data
@@ -101,6 +126,10 @@ export function createSqliteState<Document extends DocType>(options: CreateSqlit
     return true
   }
 
+  /**
+   * Notify listeners of up dates
+   * @param searchId The search ID to notify
+   */
   function notifyListeners(searchId: SearchId) {
     const searchListeners = listeners.get(searchId)
     if (searchListeners) {
@@ -108,6 +137,10 @@ export function createSqliteState<Document extends DocType>(options: CreateSqlit
     }
   }
 
+  /**
+   * Refresh the cache for a search ID
+   * @param searchId The search ID to refresh
+   */
   async function refreshCache(searchId: SearchId) {
     const table = await getTable()
     const data = cachedData.get(searchId)
@@ -119,11 +152,20 @@ export function createSqliteState<Document extends DocType>(options: CreateSqlit
     data.items = []
     await next(searchId, data)
   }
+  /**
+   * Refresh the data and notify listeners
+   * @param searchId The search ID to refresh
+   */
   async function refresh(searchId: SearchId) {
     await refreshCache(searchId)
     notifyListeners(searchId)
   }
 
+  /**
+   * Handle changes to the data
+   * @param mutationResult The mutation result
+   * @returns A set of search IDs that need to be updated
+   */
   function handleChange(mutationResult: MutationResult) {
     const { key, op } = mutationResult
     // find all cached data with key
@@ -147,6 +189,10 @@ export function createSqliteState<Document extends DocType>(options: CreateSqlit
     return searchIds
   }
 
+  /**
+   * Handle multiple changes
+   * @param mutationResults The array of mutation results
+   */
   async function handleChanges(mutationResults: MutationResult[]) {
     const updateSearchIds = new Set<SearchId>()
     for (const mutationResult of mutationResults) {
@@ -165,6 +211,12 @@ export function createSqliteState<Document extends DocType>(options: CreateSqlit
 
   const clearSchedulers = new Set<() => void>()
 
+  /**
+   * Register data for a search ID
+   * @param searchId The search ID
+   * @param options Optional search options
+   * @returns The data items for the search ID
+   */
   function registerData(searchId: SearchId, options?: SearchOptions<Document, unknown>) {
     if (!cachedData.has(searchId)) {
       cachedData.set(searchId, { items: [], options, keys: new Set() })

package/src/sqlite/select-sql.ts

@@ -16,11 +16,21 @@ export interface SqlSeachOptions<Document extends DocType> {
 }
 
 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>,

package/src/sqlite/table/bun-backend.ts

@@ -2,9 +2,18 @@ import { Database, type Statement } from 'bun:sqlite'
 import type { Backend } from './backend'
 import { MapDeque } from './map-deque'
 
+/**
+ * Create an in-memory SQLite backend using Bun's SQLite implementation
+ * @returns A Backend instance for in-memory SQLite operations
+ */
 export function bunMemoryBackend(): Backend {
   const db = Database.open(':memory:')
   const prepares = new MapDeque<string, Statement>(100)
+  /**
+   * Get or prepare a SQLite statement, caching it for future use
+   * @param query The SQL query string
+   * @returns The prepared SQLite statement
+   */
   function getStatement(query: string): Statement {
     if (prepares.has(query)) {
       return prepares.get(query)!

package/src/sqlite/table/table.ts

@@ -11,11 +11,21 @@ import { getWhereQuery } from './where'
 const DELETE_IN_CHUNK = 500 // keep well below SQLite's default 999 parameter limit
 export const DEFAULT_STEP_SIZE = 100
 
-// --- Helpers for JSON dot paths ---
-function toJsonPath(dot: string) {
+/**
+ * Convert a dot-separated path to a JSON path
+ * @param dot The dot-separated path
+ * @returns The JSON path
+ */
+export function toJsonPath(dot: string) {
   return '$.' + dot
 }
 
+/**
+ * Get a nested value from an object using a dot-separated path
+ * @param object The object to get the value from
+ * @param path The dot-separated path to the value
+ * @returns The value at the specified path, or undefined if not found
+ */
 export function getByPath<T extends object>(object: T, path: string): unknown {
   if (!object || !path) return undefined
   // eslint-disable-next-line unicorn/no-array-reduce
@@ -27,6 +37,11 @@ export function getByPath<T extends object>(object: T, path: string): unknown {
   }, object)
 }
 
+/**
+ * Create a new table in the database with the given options
+ * @param options The options for creating the table
+ * @returns The created table
+ */
 export async function createTable<Document extends DocType>(options: DbOptions<Document>): Promise<Table<Document>> {
   const { backend, tableName, indexes, key, disablePragmaOptimization } = options
   const hasUserKey = key !== undefined
@@ -64,11 +79,21 @@ export async function createTable<Document extends DocType>(options: DbOptions<D
     )
   }
 
+  /**
+   * Get the key value from a document
+   * @param document The document to extract the key from
+   * @returns The key value or undefined if no user key is configured
+   */
   function getKeyFromDocument(document: Document): Key | undefined {
     if (!hasUserKey) return undefined
     return getByPath(document, String(key)) as Key | undefined
   }
 
+  /**
+   * Get the number of rows changed by the last operation
+   * @param conn The database connection
+   * @returns The number of rows changed
+   */
   async function getChanges(conn: typeof backend): Promise<number> {
     const r = await conn.select<Array<{ c: number }>>(`SELECT changes() AS c`)
     return r[0]?.c ?? 0

package/src/sqlite/table/where.ts

@@ -34,9 +34,11 @@ export type Where<T extends Record<string, unknown>> =
       readonly NOT?: Where<T>
     }
 
-// -------------------------------------------------------------
-// Tiny helpers
-// -------------------------------------------------------------
+/**
+ * Inline a value for SQL query, with proper escaping for strings
+ * @param value The value to inline
+ * @returns The inlined value as a string
+ */
 function inlineValue(value: unknown): string {
   if (typeof value === 'string') return `'${value.replaceAll("'", "''")}'`
   if (typeof value === 'number') return value.toString()
@@ -44,6 +46,13 @@ function inlineValue(value: unknown): string {
   return `'${String(value).replaceAll("'", "''")}'`
 }
 
+/**
+ * Get SQL expression for a field, with proper casting based on value type
+ * @param field The field name
+ * @param value The field value
+ * @param tableAlias Optional table alias to prefix the field name
+ * @returns The SQL expression for the field
+ */
 function getFieldExpr(field: string, value: unknown, tableAlias?: string): string {
   const prefix = tableAlias ? `${tableAlias}.` : ''
   if (field === 'KEY') {
@@ -57,9 +66,12 @@ function getFieldExpr(field: string, value: unknown, tableAlias?: string): strin
 
 const OPS_SET: ReadonlySet<string> = new Set(['is', 'isNot', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'like'])
 
-// -------------------------------------------------------------
-// Flatten nested objects to dot-paths
-// -------------------------------------------------------------
+/**
+ * Flatten a nested Where object into a single-level object with dot-separated keys
+ * @param object The nested Where object
+ * @param prefix The prefix for the current recursion level (used internally)
+ * @returns A flattened object with dot-separated keys
+ */
 function flattenWhere(object: Record<string, unknown>, prefix = ''): Record<string, unknown> {
   const result: Record<string, unknown> = {}
 
@@ -81,9 +93,12 @@ function flattenWhere(object: Record<string, unknown>, prefix = ''): Record<stri
   return result
 }
 
-// -------------------------------------------------------------
-// Main recursive builder
-// -------------------------------------------------------------
+/**
+ * Write SQL WHERE clause from a Where object
+ * @param where The Where object defining the conditions
+ * @param tableAlias Optional table alias to prefix field names
+ * @returns The SQL WHERE clause string (without the "WHERE" keyword)
+ */
 export function getWhere<T extends Record<string, unknown>>(where: Where<T>, tableAlias?: string): string {
   if (!where || typeof where !== 'object') return ''
 
@@ -172,9 +187,11 @@ export function getWhere<T extends Record<string, unknown>>(where: Where<T>, tab
   return anyField ? `(${fieldClauses})` : ''
 }
 
-// -------------------------------------------------------------
-// Public wrapper: adds "WHERE" if needed
-// -------------------------------------------------------------
+/**
+ * Get SQL WHERE clause from a Where object
+ * @param where The Where object defining the conditions
+ * @returns The SQL WHERE clause string (without the "WHERE" keyword)
+ */
 export function getWhereQuery<T extends Record<string, unknown>>(where?: Where<T>): string {
   if (!where) return ''
   const clause = getWhere(where)

package/src/sqlite/use-sqlite.ts

@@ -17,6 +17,14 @@ export interface UseSearchOptions<Document extends DocType, Selected = Document>
   readonly select?: (document: Document) => Selected
 }
 
+/**
+ * React hook to subscribe to a SyncTable and get its current snapshot, with optional search options and selector for derived state
+ * @param state The SyncTable to subscribe to
+ * @param options Optional search options to filter and sort the documents
+ * @param deps Dependency list to control when to update the search options
+ * @returns A tuple containing the current array of documents (or selected documents) and an object with actions to interact with the SyncTable
+ * @throws If the value is a Promise or an Error, it will be thrown to be handled by an error boundary or suspense
+ */
 export function useSqliteValue<Document extends DocType, Selected = Document>(
   state: SyncTable<Document>,
   options: UseSearchOptions<Document, Selected> = {},

package/src/use-value.ts

@@ -3,6 +3,13 @@ import { EMPTY_SELECTOR, type GetState } from './types'
 import { isError, isPromise } from './utils/is'
 import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector'
 
+/**
+ * React hook to subscribe to a state and get its value, with optional selector for derived state
+ * @param state The state to subscribe to
+ * @param selector Optional function to derive a value from the state
+ * @returns The current value of the state or the derived value from the selector
+ * @throws If the value is a Promise or an Error, it will be thrown to be handled by an error boundary or suspense
+ */
 export function useValue<T, S>(
   state: GetState<T>,
   selector: (stateValue: Awaited<T>) => S = EMPTY_SELECTOR,

package/src/utils/common.ts

@@ -11,6 +11,9 @@ export class AbortError extends Error {
 }
 /**
  * Cancelable promise function, return promise and controller
+ * @param promise Original promise
+ * @param previousController Previous AbortController to abort if exists
+ * @returns CancelablePromise<T>
  */
 export function cancelablePromise<T>(promise: Promise<T>, previousController?: AbortController): CancelablePromise<T> {
   if (previousController) {
@@ -32,6 +35,10 @@ export function cancelablePromise<T>(promise: Promise<T>, previousController?: A
 
 /**
  * Check if the cache value is different from the previous value.
+ * If they are the same, return false to avoid unnecessary updates.
+ * @param cache - The cache object containing current and previous values
+ * @param isEqual - Optional custom equality check function
+ * @returns boolean indicating whether an update should occur
  */
 export function canUpdate<T>(cache: Cache<T>, isEqual: IsEqual<T> = isEqualBase): boolean {
   if (!isUndefined(cache.current)) {
@@ -45,6 +52,9 @@ export function canUpdate<T>(cache: Cache<T>, isEqual: IsEqual<T> = isEqualBase)
 
 /**
  * Handle async updates for `create` and `select`
+ * @param state - state object
+ * @param value - new value
+ * @returns T or Promise<T>
  */
 export function handleAsyncUpdate<T>(state: State<T>, value: T): T {
   const {

package/src/utils/create-emitter.ts

@@ -15,8 +15,9 @@ export interface Emitter<T, P = undefined> {
  * T: Type of the state
  * R: Type of the snapshot
  * P: Type of the parameters
- * @param getSnapshot
- * @returns
+ * @param getSnapshot Function to get the current snapshot
+ * @param getInitialSnapshot Optional function to get the initial snapshot
+ * @returns An emitter object with methods to manage listeners and emit events
  */
 export function createEmitter<T, P = undefined>(getSnapshot: () => T, getInitialSnapshot?: () => T): Emitter<T, P> {
   const listeners = new Set<(...params: P[]) => void>()

package/src/utils/is.ts

@@ -1,3 +1,4 @@
+/* eslint-disable jsdoc/require-jsdoc */
 import type { SetStateCb, SetValue, State } from '../types'
 import { AbortError } from './common'
 
@@ -27,9 +28,11 @@ export function isEqualBase<T>(valueA: T, valueB: T): boolean {
   }
   return !!Object.is(valueA, valueB)
 }
+
 export function isSetValueFunction<T>(value: SetValue<T>): value is SetStateCb<T> {
   return typeof value === 'function'
 }
+
 export function isAbortError(value: unknown): value is AbortError {
   return value instanceof AbortError
 }

package/src/utils/shallow.ts

@@ -1,6 +1,13 @@
 /* eslint-disable sonarjs/cognitive-complexity */
 import { isArray, isMap, isSet } from './is'
 
+/**
+ * Performs a shallow comparison between two values to determine if they are equivalent.
+ * This function checks if the two values are the same reference, or if they are objects,
+ * @param valueA The first value to compare.
+ * @param valueB The second value to compare.
+ * @returns True if the values are shallowly equal, false otherwise.
+ */
 export function shallow<T>(valueA: T, valueB: T): boolean {
   if (valueA == valueB) {
     return true

package/types/__tests__/test-utils.d.ts

@@ -1,4 +1,9 @@
 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 declare function longPromise(time?: number): Promise<number>;
 export declare class ErrorBoundary extends Component<{
     fallback: React.ReactNode;

package/types/create-state.d.ts

@@ -8,6 +8,8 @@ interface GetStateOptions<T> {
 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 declare function createState<T>(options: GetStateOptions<T>): FullState<T>;
 export {};

package/types/create.d.ts

@@ -4,6 +4,9 @@ export declare const STATE_SCHEDULER: {
     schedule<T>(id: string | number | symbol, value: T): void;
 };
 /**
- * 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 declare function create<T>(initialValue: DefaultValue<T>, isEqual?: IsEqual<T>): State<T>;

package/types/debug/development-tools.d.ts

@@ -1,3 +1,8 @@
 import type { GetState, State } from '../types';
 export type StateType = 'state' | 'derived';
+/**
+ * Subscribe a state to development tools if available
+ * @param state The state to subscribe
+ * @returns A function to unsubscribe from development tools
+ */
 export declare function subscribeToDevelopmentTools<T>(state: State<T> | GetState<T>): (() => void) | undefined;

package/types/select.d.ts

@@ -6,8 +6,11 @@ type AwaitedArray<T extends Array<unknown>> = {
     [K in keyof T]: Awaited<T[K]>;
 };
 /**
- * Selecting state from multiple states.
- * It will create new state in read-only mode (without set).
+ * Create a derived state from multiple dependency states using a selector function
+ * @param states An array of dependency states
+ * @param selector A function that takes the values of the dependency states and returns a derived value
+ * @param isEqual Optional custom equality check function to prevent unnecessary updates
+ * @returns A GetState<T> representing the derived state
  */
 export declare function select<T = unknown, S extends Array<unknown> = []>(states: StateDependencies<S>, selector: (...values: AwaitedArray<S>) => T, isEqual?: IsEqual<T>): GetState<T>;
 export {};

package/types/sqlite/create-sqlite.d.ts

@@ -24,5 +24,10 @@ export interface SyncTable<Document extends DocType> {
     readonly next: (searchId: SearchId) => Promise<boolean>;
     readonly select: <Params extends unknown[]>(compute: (...args: Params) => SearchOptions<Document>) => CreateState<Document, Params>;
 }
+/**
+ * Create a SyncTable that wraps a Table and provides reactive capabilities
+ * @param options Options to create the SyncTable, including the backend and table name
+ * @returns A SyncTable instance with methods to interact with the underlying Table and manage reactive searches
+ */
 export declare function createSqliteState<Document extends DocType>(options: CreateSqliteOptions<Document>): SyncTable<Document>;
 export {};

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

@@ -11,4 +11,10 @@ export interface SqlSeachOptions<Document extends DocType> {
     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>;

package/types/sqlite/table/bun-backend.d.ts

@@ -1,2 +1,6 @@
 import type { Backend } from './backend';
+/**
+ * Create an in-memory SQLite backend using Bun's SQLite implementation
+ * @returns A Backend instance for in-memory SQLite operations
+ */
 export declare function bunMemoryBackend(): Backend;

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

@@ -1,4 +1,21 @@
 import type { Table, DbOptions, DocType } from './table.types';
 export declare const DEFAULT_STEP_SIZE = 100;
+/**
+ * Convert a dot-separated path to a JSON path
+ * @param dot The dot-separated path
+ * @returns The JSON path
+ */
+export declare function toJsonPath(dot: string): string;
+/**
+ * Get a nested value from an object using a dot-separated path
+ * @param object The object to get the value from
+ * @param path The dot-separated path to the value
+ * @returns The value at the specified path, or undefined if not found
+ */
 export declare function getByPath<T extends object>(object: T, path: string): unknown;
+/**
+ * Create a new table in the database with the given options
+ * @param options The options for creating the table
+ * @returns The created table
+ */
 export declare function createTable<Document extends DocType>(options: DbOptions<Document>): Promise<Table<Document>>;

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

@@ -16,6 +16,17 @@ export type Where<T extends Record<string, unknown>> = {
     readonly OR?: Array<Where<T>>;
     readonly NOT?: Where<T>;
 };
+/**
+ * Write SQL WHERE clause from a Where object
+ * @param where The Where object defining the conditions
+ * @param tableAlias Optional table alias to prefix field names
+ * @returns The SQL WHERE clause string (without the "WHERE" keyword)
+ */
 export declare function getWhere<T extends Record<string, unknown>>(where: Where<T>, tableAlias?: string): string;
+/**
+ * Get SQL WHERE clause from a Where object
+ * @param where The Where object defining the conditions
+ * @returns The SQL WHERE clause string (without the "WHERE" keyword)
+ */
 export declare function getWhereQuery<T extends Record<string, unknown>>(where?: Where<T>): string;
 export {};

package/types/sqlite/use-sqlite.d.ts

@@ -12,4 +12,12 @@ export interface UseSearchOptions<Document extends DocType, Selected = Document>
      */
     readonly select?: (document: Document) => Selected;
 }
+/**
+ * React hook to subscribe to a SyncTable and get its current snapshot, with optional search options and selector for derived state
+ * @param state The SyncTable to subscribe to
+ * @param options Optional search options to filter and sort the documents
+ * @param deps Dependency list to control when to update the search options
+ * @returns A tuple containing the current array of documents (or selected documents) and an object with actions to interact with the SyncTable
+ * @throws If the value is a Promise or an Error, it will be thrown to be handled by an error boundary or suspense
+ */
 export declare function useSqliteValue<Document extends DocType, Selected = Document>(state: SyncTable<Document>, options?: UseSearchOptions<Document, Selected>, deps?: DependencyList): [undefined extends Selected ? Document[] : Selected[], SqLiteActions];

package/types/use-value.d.ts

@@ -1,2 +1,9 @@
 import { type GetState } from './types';
+/**
+ * React hook to subscribe to a state and get its value, with optional selector for derived state
+ * @param state The state to subscribe to
+ * @param selector Optional function to derive a value from the state
+ * @returns The current value of the state or the derived value from the selector
+ * @throws If the value is a Promise or an Error, it will be thrown to be handled by an error boundary or suspense
+ */
 export declare function useValue<T, S>(state: GetState<T>, selector?: (stateValue: Awaited<T>) => S): undefined extends S ? Awaited<T> : S;

package/types/utils/common.d.ts

@@ -8,13 +8,23 @@ export declare class AbortError extends Error {
 }
 /**
  * Cancelable promise function, return promise and controller
+ * @param promise Original promise
+ * @param previousController Previous AbortController to abort if exists
+ * @returns CancelablePromise<T>
  */
 export declare function cancelablePromise<T>(promise: Promise<T>, previousController?: AbortController): CancelablePromise<T>;
 /**
  * Check if the cache value is different from the previous value.
+ * If they are the same, return false to avoid unnecessary updates.
+ * @param cache - The cache object containing current and previous values
+ * @param isEqual - Optional custom equality check function
+ * @returns boolean indicating whether an update should occur
  */
 export declare function canUpdate<T>(cache: Cache<T>, isEqual?: IsEqual<T>): boolean;
 /**
  * Handle async updates for `create` and `select`
+ * @param state - state object
+ * @param value - new value
+ * @returns T or Promise<T>
  */
 export declare function handleAsyncUpdate<T>(state: State<T>, value: T): T;

package/types/utils/create-emitter.d.ts

@@ -14,7 +14,8 @@ export interface Emitter<T, P = undefined> {
  * T: Type of the state
  * R: Type of the snapshot
  * P: Type of the parameters
- * @param getSnapshot
- * @returns
+ * @param getSnapshot Function to get the current snapshot
+ * @param getInitialSnapshot Optional function to get the initial snapshot
+ * @returns An emitter object with methods to manage listeners and emit events
  */
 export declare function createEmitter<T, P = undefined>(getSnapshot: () => T, getInitialSnapshot?: () => T): Emitter<T, P>;

package/types/utils/shallow.d.ts

@@ -1 +1,8 @@
+/**
+ * Performs a shallow comparison between two values to determine if they are equivalent.
+ * This function checks if the two values are the same reference, or if they are objects,
+ * @param valueA The first value to compare.
+ * @param valueB The second value to compare.
+ * @returns True if the values are shallowly equal, false otherwise.
+ */
 export declare function shallow<T>(valueA: T, valueB: T): boolean;