muya 2.1.0 → 2.1.2

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

@@ -0,0 +1,38 @@
+import { Database, type Statement } from 'bun:sqlite'
+import type { Backend } from './backend'
+import { MapDeque } from './map-deque'
+
+export function bunMemoryBackend(): Backend {
+  const db = Database.open(':memory:')
+  const prepares = new MapDeque<string, Statement>(100)
+  function getStatement(query: string): Statement {
+    if (prepares.has(query)) {
+      return prepares.get(query)!
+    }
+    const stmt = db.prepare(query)
+    prepares.set(query, stmt)
+    return stmt
+  }
+
+  const backend: Backend = {
+    execute: async (query, params = []) => {
+      const q = getStatement(query)
+      const result = q.run(...(params as never[]))
+      return {
+        rowsAffected: result.changes,
+        changes: result.changes,
+      }
+    },
+    transaction: async (callback) => {
+      return db.transaction(() => callback(backend))()
+    },
+    path: db.filename,
+    select: async (query, params = []) => {
+      const q = getStatement(query)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const result = q.all(...(params as never[])) as Array<Record<string, any>>
+      return result as never
+    },
+  }
+  return backend
+}

package/src/sqlite/table/map-deque.ts

@@ -0,0 +1,29 @@
+export class MapDeque<K, V> extends Map<K, V> {
+  constructor(
+    private maxSize: number,
+    entries?: ReadonlyArray<readonly [K, V]> | null,
+  ) {
+    super(entries)
+    if (this.maxSize <= 0) {
+      throw new RangeError('maxSize must be greater than 0')
+    }
+  }
+
+  override set(key: K, value: V): this {
+    if (this.has(key)) {
+      super.set(key, value)
+      return this
+    }
+
+    if (this.size >= this.maxSize) {
+      const firstKey = this.keys().next().value
+      if (firstKey !== undefined) {
+        this.delete(firstKey)
+      }
+    }
+
+    super.set(key, value)
+
+    return this
+  }
+}

package/src/sqlite/table/table.ts

@@ -0,0 +1,200 @@
+// table.ts
+/* eslint-disable sonarjs/different-types-comparison */
+/* eslint-disable sonarjs/cognitive-complexity */
+/* eslint-disable @typescript-eslint/no-shadow */
+/* eslint-disable no-shadow */
+import type { Table, DbOptions, DocType, Key, SearchOptions, MutationResult } from './table.types'
+import { getWhereQuery, type Where } from './where'
+
+const DELETE_IN_CHUNK = 500 // keep well below SQLite's default 999 parameter limit
+export const DEFAULT_STEP_SIZE = 100
+export async function createTable<Document extends DocType>(options: DbOptions<Document>): Promise<Table<Document>> {
+  const { backend, tableName, indexes, key } = options
+  const hasUserKey = key !== undefined
+
+  // Schema
+  if (hasUserKey) {
+    await backend.execute(`
+      CREATE TABLE IF NOT EXISTS ${tableName} (
+        key TEXT PRIMARY KEY,
+        data TEXT NOT NULL
+      );
+    `)
+  } else {
+    await backend.execute(`
+      CREATE TABLE IF NOT EXISTS ${tableName} (
+        data TEXT NOT NULL
+      );
+    `)
+  }
+
+  // JSON expression indexes for fields under data
+  for (const index of indexes ?? []) {
+    const idx = String(index)
+    await backend.execute(`CREATE INDEX IF NOT EXISTS idx_${tableName}_${idx} ON ${tableName} (json_extract(data, '$.${idx}'));`)
+  }
+
+  function getKeyFromDocument(document: Document): Key | undefined {
+    return hasUserKey ? (document[key as keyof Document] as unknown as Key | undefined) : undefined
+  }
+
+  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
+  }
+
+  const table: Table<Document> = {
+    backend,
+
+    async set(document, backendOverride) {
+      const db = backendOverride ?? backend
+      const json = JSON.stringify(document)
+
+      if (hasUserKey) {
+        const id = getKeyFromDocument(document)
+        if (id === undefined || id === null) {
+          throw new Error(
+            `Document is missing the configured key "${String(key)}". Provide it or create the table without "key".`,
+          )
+        }
+
+        // Fast path: UPDATE first
+        await db.execute(`UPDATE ${tableName} SET data = ? WHERE key = ?`, [json, id])
+        const updated = await getChanges(db)
+        if (updated === 1) return { key: id, op: 'update' }
+
+        // No row updated => try INSERT
+        try {
+          await db.execute(`INSERT INTO ${tableName} (key, data) VALUES (?, ?)`, [id, json])
+          return { key: id, op: 'insert' }
+        } catch {
+          await db.execute(`UPDATE ${tableName} SET data = ? WHERE key = ?`, [json, id])
+          return { key: id, op: 'update' }
+        }
+      }
+
+      // ROWID mode
+      await db.execute(`INSERT INTO ${tableName} (data) VALUES (?)`, [json])
+      const rows = await db.select<Array<{ id: number }>>(`SELECT last_insert_rowid() AS id`)
+      const rowid = rows[0]?.id
+      if (typeof rowid !== 'number') throw new Error('Failed to retrieve last_insert_rowid()')
+      const result: MutationResult = { key: rowid, op: 'insert' }
+      return result
+    },
+
+    // --- FIXED: include rowid ---
+    async get<Selected = Document>(
+      keyValue: Key,
+      selector: (document: Document, meta: { rowid: number }) => Selected = (d, _m) => d as unknown as Selected,
+    ) {
+      const whereKey = hasUserKey ? `key = ?` : `rowid = ?`
+      const result = await backend.select<Array<{ data: string; rowid: number }>>(
+        `SELECT rowid, data FROM ${tableName} WHERE ${whereKey}`,
+        [keyValue],
+      )
+      if (result.length === 0) return
+      const [item] = result
+      const { data, rowid } = item
+      const document = JSON.parse(data) as Document
+      return selector(document, { rowid }) as Selected
+    },
+
+    async delete(keyValue: Key) {
+      const whereKey = hasUserKey ? `key = ?` : `rowid = ?`
+      await backend.execute(`DELETE FROM ${tableName} WHERE ${whereKey}`, [keyValue])
+      const changed = await backend.select<Array<{ c: number }>>(`SELECT changes() AS c`)
+      if ((changed[0]?.c ?? 0) > 0) {
+        return { key: keyValue, op: 'delete' }
+      }
+      return
+    },
+
+    // --- FIXED: include rowid in search ---
+    async *search<Selected = Document>(options: SearchOptions<Document, Selected> = {}): AsyncIterableIterator<Selected> {
+      const {
+        sorBy,
+        order = 'asc',
+        limit,
+        offset = 0,
+        where,
+        select = (document, _meta) => document as unknown as Selected,
+        stepSize = DEFAULT_STEP_SIZE,
+      } = options
+
+      let baseQuery = `SELECT rowid, data FROM ${tableName}`
+      if (where) baseQuery += ' ' + getWhereQuery(where)
+
+      let yielded = 0
+      let currentOffset = offset
+      while (true) {
+        let query = baseQuery
+
+        if (sorBy) {
+          query += ` ORDER BY json_extract(data, '$.${String(sorBy)}') COLLATE NOCASE ${order.toUpperCase()}`
+        } else {
+          query += hasUserKey ? ` ORDER BY key COLLATE NOCASE ${order.toUpperCase()}` : ` ORDER BY rowid ${order.toUpperCase()}`
+        }
+
+        const batchLimit = limit ? Math.min(stepSize, limit - yielded) : stepSize
+        query += ` LIMIT ${batchLimit} OFFSET ${currentOffset}`
+
+        const results = await backend.select<Array<{ rowid: number; data: string }>>(query)
+        if (results.length === 0) break
+
+        for (const { rowid, data } of results) {
+          if (limit && yielded >= limit) return
+          const document = JSON.parse(data) as Document
+          yield select(document, { rowId: rowid }) as Selected
+          yielded++
+        }
+
+        if (results.length < batchLimit || (limit && yielded >= limit)) break
+        currentOffset += results.length
+      }
+    },
+
+    async count(options: { where?: Where<Document> } = {}) {
+      const { where } = options
+      let query = `SELECT COUNT(*) as count FROM ${tableName}`
+      if (where) query += ' ' + getWhereQuery(where)
+      const result = await backend.select<Array<{ count: number }>>(query)
+      return result[0]?.count ?? 0
+    },
+
+    async deleteBy(where: Where<Document>) {
+      const whereQuery = getWhereQuery(where)
+      const keyCol = hasUserKey ? 'key' : 'rowid'
+
+      const results: MutationResult[] = []
+      await backend.transaction(async (tx) => {
+        const rows = await tx.select<Array<{ k: Key }>>(`SELECT ${keyCol} AS k, rowid FROM ${tableName} ${whereQuery}`)
+        if (rows.length === 0) return
+
+        const allKeys = rows.map((r) => r.k)
+
+        for (let index = 0; index < allKeys.length; index += DELETE_IN_CHUNK) {
+          const chunk = allKeys.slice(index, index + DELETE_IN_CHUNK)
+          const placeholders = chunk.map(() => '?').join(',')
+          await tx.execute(`DELETE FROM ${tableName} WHERE ${keyCol} IN (${placeholders})`, chunk as unknown as unknown[])
+        }
+
+        for (const k of allKeys) results.push({ key: k, op: 'delete' })
+      })
+
+      return results
+    },
+
+    async batchSet(documents: Document[]) {
+      const mutations: MutationResult[] = []
+      await backend.transaction(async (tx) => {
+        for (const document of documents) {
+          const m = await table.set(document, tx)
+          mutations.push(m)
+        }
+      })
+      return mutations
+    },
+  }
+
+  return table
+}

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

@@ -0,0 +1,55 @@
+// table.types.ts
+import type { Backend } from './backend'
+import type { Where } from './where'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type DocType = { [key: string]: any }
+export type KeyTypeAvailable = 'string' | 'number'
+
+export interface DbOptions<Document extends DocType> {
+  readonly sorBy?: keyof Document
+  readonly order?: 'asc' | 'desc'
+  readonly tableName: string
+  readonly indexes?: Array<keyof Document>
+  readonly backend: Backend
+  /**
+   * Optional key. If omitted, the table uses implicit SQLite ROWID as the key.
+   */
+  readonly key?: keyof Document
+}
+
+interface DbNotGeneric {
+  readonly backend: Backend
+}
+
+export interface SearchOptions<Document extends DocType, Selected = Document> {
+  readonly sorBy?: keyof Document
+  readonly order?: 'asc' | 'desc'
+  readonly limit?: number
+  readonly offset?: number
+  readonly where?: Where<Document>
+  readonly stepSize?: number
+  /**
+   * Naive projection. Prefer specialized queries for heavy fan-out graphs.
+   */
+  readonly select?: (document: Document, meta: { rowId: number }) => Selected
+}
+
+export type Key = string | number
+
+export type MutationOp = 'insert' | 'update' | 'delete'
+export interface MutationResult {
+  key: Key
+  op: MutationOp
+}
+
+export interface Table<Document extends DocType> extends DbNotGeneric {
+  readonly set: (document: Document, backendOverride?: Backend) => Promise<MutationResult>
+  readonly batchSet: (documents: Document[]) => Promise<MutationResult[]>
+  readonly get: <Selected = Document>(key: Key, selector?: (document: Document) => Selected) => Promise<Selected | undefined>
+
+  readonly delete: (key: Key) => Promise<MutationResult | undefined>
+  readonly search: <Selected = Document>(options?: SearchOptions<Document, Selected>) => AsyncIterableIterator<Selected>
+  readonly count: (options?: { where?: Where<Document> }) => Promise<number>
+  readonly deleteBy: (where: Where<Document>) => Promise<MutationResult[]>
+}

package/src/sqlite/table/where.ts

@@ -0,0 +1,267 @@
+/* eslint-disable sonarjs/no-nested-conditional */
+/* eslint-disable sonarjs/cognitive-complexity */
+// -------------------------------------------------------------
+// Simplified `Where` type: each field may be a `Condition`
+// *or* directly a `Document[K]`/`Document[K][]`, shorthand for "is"/"in".
+// We also allow the special literal "KEY" to filter by the primary‐key column.
+// -------------------------------------------------------------
+
+export interface Field {
+  readonly table: string
+  readonly field: string
+}
+
+interface Condition<Document extends Record<string, unknown>, K extends keyof Document = keyof Document> {
+  readonly is?: Document[K] | Array<Document[K]>
+  readonly isNot?: Document[K] | Array<Document[K]>
+  readonly gt?: Document[K] | Array<Document[K]>
+  readonly gte?: Document[K] | Array<Document[K]>
+  readonly lt?: Document[K] | Array<Document[K]>
+  readonly lte?: Document[K] | Array<Document[K]>
+  readonly in?: Document[K] | Array<Document[K]>
+  readonly notIn?: Document[K] | Array<Document[K]>
+  readonly like?: Document[K] | Array<Document[K]>
+}
+
+/**
+ * We extend `keyof Document` by the special literal "KEY".
+ * That means users can write `{ KEY: ... }` in addition to `{ someField: ... }`.
+ *
+ * - If K extends keyof Document, then primitive values must match Document[K].
+ * - If K === "KEY", then primitive values are treated as strings/Array<string>.
+ */
+export type Where<Document extends Record<string, unknown>> =
+  | {
+      [K in keyof Document | 'KEY']?:
+        | Condition<Document, K extends keyof Document ? K : keyof Document>
+        | (K extends keyof Document ? Document[K] : string)
+        | (K extends keyof Document ? Array<Document[K]> : string[])
+    }
+  | {
+      readonly AND?: Array<Where<Document>>
+      readonly OR?: Array<Where<Document>>
+      readonly NOT?: Where<Document>
+    }
+
+// -------------------------------------------------------------
+// A tiny helper to escape/inline a single primitive into SQL.
+// -------------------------------------------------------------
+function inlineValue(value: unknown): string {
+  if (typeof value === 'string') {
+    return `'${(value as string).split("'").join("''")}'`
+  }
+  if (typeof value === 'number') {
+    return (value as number).toString()
+  }
+  if (typeof value === 'boolean') {
+    return (value as boolean) ? '1' : '0'
+  }
+  return `'${String(value).split("'").join("''")}'`
+}
+
+// -------------------------------------------------------------
+// Build the expression for a given field.
+// If field === "KEY", refer directly to the primary‐key column (`key`).
+// Otherwise, extract from JSON `data`.
+// -------------------------------------------------------------
+function getFieldExpr(field: string, value: unknown, tableAlias?: string): string {
+  const prefix = tableAlias ? `${tableAlias}.` : ''
+  if (field === 'KEY') {
+    // Use double‐quotes around key to avoid conflicts with reserved words
+    return `"${prefix}key"`
+  }
+
+  // Otherwise, treat as JSON field under "data"
+  if (typeof value === 'string') {
+    return `CAST(json_extract(${prefix}data, '$.${field}') AS TEXT)`
+  }
+  if (typeof value === 'boolean') {
+    return `CAST(json_extract(${prefix}data, '$.${field}') AS INTEGER)`
+  }
+  if (typeof value === 'number') {
+    return `CAST(json_extract(${prefix}data, '$.${field}') AS NUMERIC)`
+  }
+  return `json_extract(${prefix}data, '$.${field}')`
+}
+
+// -------------------------------------------------------------
+// Valid operators set (for quick membership checks).
+// -------------------------------------------------------------
+const OPS_SET: ReadonlySet<string> = new Set(['is', 'isNot', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'like'])
+
+function isUndefined(value: unknown): value is undefined {
+  return value === undefined
+}
+
+// -------------------------------------------------------------
+// Main recursive parser: turn a `Where<Document>` into a SQL clause
+// (without the leading "WHERE").
+// -------------------------------------------------------------
+export function getWhere<Document extends Record<string, unknown>>(where: Where<Document>, tableAlias?: string): string {
+  if (!where || typeof where !== 'object') {
+    return ''
+  }
+
+  // ----- Logical branches: AND / OR / NOT -----
+  if (!isUndefined(where.AND)) {
+    const array = where.AND as Array<Where<Document>>
+    if (Array.isArray(array) && array.length > 0) {
+      let combined = ''
+      let firstAdded = false
+      for (const sub of array) {
+        const clause = getWhere(sub, tableAlias)
+        if (!clause) continue
+        if (firstAdded) combined += ' AND '
+        combined += clause
+        firstAdded = true
+      }
+      return firstAdded ? `(${combined})` : ''
+    }
+    return ''
+  }
+
+  if (!isUndefined(where.OR)) {
+    const array = where.OR as Array<Where<Document>>
+    if (Array.isArray(array) && array.length > 0) {
+      let combined = ''
+      let firstAdded = false
+      for (const sub of array) {
+        const clause = getWhere(sub, tableAlias)
+        if (!clause) continue
+        if (firstAdded) combined += ' OR '
+        combined += clause
+        firstAdded = true
+      }
+      return firstAdded ? `(${combined})` : ''
+    }
+    return ''
+  }
+
+  if (!isUndefined(where.NOT)) {
+    const sub = where.NOT as Where<Document>
+    if (sub && typeof sub === 'object') {
+      const clause = getWhere(sub, tableAlias)
+      return clause ? `(NOT ${clause})` : ''
+    }
+    return ''
+  }
+
+  // ----- Field‐based conditions: default is AND across fields -----
+  let fieldClauses = ''
+  let anyFieldClause = false
+
+  for (const key in where as Record<string, unknown>) {
+    if (key === 'AND' || key === 'OR' || key === 'NOT') continue
+
+    const rawValue = (where as Record<string, unknown>)[key]
+    if (rawValue == null) continue
+
+    // If the user provided a primitive or an array, coerce it to a Condition:
+    //  - single primitive → { is: rawVal }
+    //  - array           → { in: rawVal }
+    let cond: Condition<Document, typeof key>
+    if (typeof rawValue !== 'object' || Array.isArray(rawValue)) {
+      cond = Array.isArray(rawValue) ? { in: rawValue } : ({ is: rawValue } as Condition<Document, typeof key>)
+    } else {
+      cond = rawValue as Condition<Document, typeof key>
+    }
+
+    // Iterate only over real operator keys that exist on this `cond`
+    for (const opKey of Object.keys(cond) as Array<keyof typeof cond>) {
+      if (!OPS_SET.has(opKey as string)) continue
+      const rawOpValue = cond[opKey]
+      if (rawOpValue == null) continue
+
+      // Always treat it as an array for uniformity:
+      const array = Array.isArray(rawOpValue) ? (rawOpValue as unknown[]) : [rawOpValue]
+      if (array.length === 0) continue
+
+      // Handle `is` / `isNot` / `in` / `notIn`
+      if (opKey === 'is' || opKey === 'isNot' || opKey === 'in' || opKey === 'notIn') {
+        const [firstValue] = array
+        const fieldExpr = getFieldExpr(key, firstValue, tableAlias)
+
+        // Build comma‐separated list without using `.map()`
+        let inList = ''
+        if (array.length > 1) {
+          for (const [index, elt] of array.entries()) {
+            if (index > 0) inList += ','
+            inList += inlineValue(elt)
+          }
+        }
+
+        switch (opKey) {
+          case 'is': {
+            fieldClauses +=
+              array.length > 1
+                ? (anyFieldClause ? ' AND ' : '') + `${fieldExpr} IN (${inList})`
+                : (anyFieldClause ? ' AND ' : '') + `${fieldExpr} = ${inlineValue(array[0])}`
+            break
+          }
+          case 'isNot': {
+            fieldClauses +=
+              array.length > 1
+                ? (anyFieldClause ? ' AND ' : '') + `${fieldExpr} NOT IN (${inList})`
+                : (anyFieldClause ? ' AND ' : '') + `${fieldExpr} <> ${inlineValue(array[0])}`
+            break
+          }
+          case 'in': {
+            fieldClauses +=
+              array.length > 1
+                ? (anyFieldClause ? ' AND ' : '') + `${fieldExpr} IN (${inList})`
+                : (anyFieldClause ? ' AND ' : '') + `${fieldExpr} IN (${inlineValue(array[0])})`
+            break
+          }
+          case 'notIn': {
+            fieldClauses +=
+              array.length > 1
+                ? (anyFieldClause ? ' AND ' : '') + `${fieldExpr} NOT IN (${inList})`
+                : (anyFieldClause ? ' AND ' : '') + `${fieldExpr} NOT IN (${inlineValue(array[0])})`
+            break
+          }
+        }
+
+        anyFieldClause = true
+        continue
+      }
+
+      // Handle comparisons: gt, gte, lt, lte, like
+      for (const v of array) {
+        const fieldExpr = getFieldExpr(key, v, tableAlias)
+        switch (opKey) {
+          case 'gt': {
+            fieldClauses += (anyFieldClause ? ' AND ' : '') + `${fieldExpr} > ${inlineValue(v)}`
+            break
+          }
+          case 'gte': {
+            fieldClauses += (anyFieldClause ? ' AND ' : '') + `${fieldExpr} >= ${inlineValue(v)}`
+            break
+          }
+          case 'lt': {
+            fieldClauses += (anyFieldClause ? ' AND ' : '') + `${fieldExpr} < ${inlineValue(v)}`
+            break
+          }
+          case 'lte': {
+            fieldClauses += (anyFieldClause ? ' AND ' : '') + `${fieldExpr} <= ${inlineValue(v)}`
+            break
+          }
+          case 'like': {
+            fieldClauses += (anyFieldClause ? ' AND ' : '') + `${fieldExpr} LIKE ${inlineValue(v)}`
+            break
+          }
+        }
+        anyFieldClause = true
+      }
+    }
+  }
+
+  return anyFieldClause ? `(${fieldClauses})` : ''
+}
+
+// -------------------------------------------------------------
+// Wrap `parse(...)` in "WHERE (…)". If empty, return "".
+// -------------------------------------------------------------
+export function getWhereQuery<Document extends Record<string, unknown>>(where: Where<Document>): string {
+  const clause = getWhere(where)
+  return clause ? `WHERE ${clause}` : ''
+}

package/src/sqlite/use-sqlite-value.ts

@@ -0,0 +1,76 @@
+import { useCallback, useDebugValue, useId, useLayoutEffect, useMemo, type DependencyList } from 'react'
+import type { SyncTable } from './create-sqlite-state'
+import type { DocType } from './table/table.types'
+import { isError, isPromise } from '../utils/is'
+import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector'
+import type { Where } from './table/where'
+
+export interface SqLiteActions {
+  readonly next: () => Promise<boolean>
+  readonly reset: () => Promise<void>
+}
+
+export interface UseSearchOptions<Document extends DocType, Selected = Document> {
+  readonly sorBy?: keyof Document
+  readonly order?: 'asc' | 'desc'
+  readonly limit?: number
+  readonly offset?: number
+  readonly where?: Where<Document>
+  readonly stepSize?: number
+  /**
+   * Naive projection. Prefer specialized queries for heavy fan-out graphs.
+   */
+  readonly select?: (document: Document) => Selected
+}
+
+export function useSqliteValue<Document extends DocType, Selected = Document>(
+  state: SyncTable<Document>,
+  options: UseSearchOptions<Document, Selected> = {},
+  deps: DependencyList = [],
+): [undefined extends Selected ? Document[] : Selected[], SqLiteActions] {
+  const { select } = options
+
+  const id = useId()
+
+  useLayoutEffect(() => {
+    state.updateSearchOptions(id, { ...options, select: undefined })
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps)
+
+  const selector = useCallback(
+    (documents: Document[]) => {
+      // eslint-disable-next-line unicorn/no-array-callback-reference
+      return select ? documents.map(select) : (documents as unknown as Selected[])
+    },
+    [select],
+  )
+
+  const subscribe = useCallback(
+    (onStorageChange: () => void) => {
+      return state.subscribe(id, onStorageChange)
+    },
+    [state, id],
+  )
+
+  const getSnapshot = useCallback(() => {
+    return state.getSnapshot(id)
+  }, [state, id])
+
+  const value = useSyncExternalStoreWithSelector<Document[], Selected[]>(subscribe, getSnapshot, getSnapshot, selector)
+
+  useDebugValue(value)
+  if (isPromise(value)) {
+    throw value
+  }
+  if (isError(value)) {
+    throw value
+  }
+
+  const actions = useMemo((): SqLiteActions => {
+    return {
+      next: () => state.next(id),
+      reset: () => state.refresh(id),
+    }
+  }, [id, state])
+  return [value as undefined extends Selected ? Document[] : Selected[], actions]
+}

package/src/types.ts

@@ -63,4 +63,5 @@ export interface State<T> extends GetState<T> {
    */
   withName: (name: string) => State<T>
   isSet: true
+  cache: Cache<T>
 }