@talelk/newui-data 0.0.0-stage → 1.1.0

package/src/resource/idb.ts

@@ -0,0 +1,167 @@
+/**
+ * An IndexedDB-backed, Promise-based key/value store for caching resource data.
+ *
+ * The asynchronous sibling of {@link createLocalStore}, written against the
+ * native `indexedDB` API — no `idb`/`idb-keyval` dependency. Values are stored
+ * with the structured-clone algorithm, so objects, arrays, `Date`s, `Blob`s and
+ * the like round-trip without an explicit `JSON.stringify`.
+ *
+ * SSR-safe: with no `indexedDB` (the server, or a browser with it disabled) the
+ * store falls back to an in-memory `Map` and every method still resolves, so a
+ * caller never has to branch on `typeof window`. The `indexedDB` implementation
+ * is injectable through {@link IdbStoreOptions.factory}, which is also how the
+ * unit tests drive the native code path (jsdom ships no IndexedDB).
+ */
+
+/** A Promise-based, structured-clone key/value cache. */
+export interface IdbStore<T = unknown> {
+  /** The stored value, or `null` when the key is absent. */
+  get(key: string): Promise<T | null>
+  /** Persist a value. */
+  set(key: string, value: T): Promise<void>
+  /** Remove a key. */
+  delete(key: string): Promise<void>
+  /** Every key currently in the store. */
+  keys(): Promise<string[]>
+  /** Remove every key. */
+  clear(): Promise<void>
+  /** False when the store fell back to memory (SSR, or no IndexedDB). */
+  readonly persistent: boolean
+  /** Close the underlying database, if one was opened. */
+  close(): void
+}
+
+/** Options for {@link createIdbStore}. */
+export interface IdbStoreOptions {
+  /** Database name. Defaults to `newui`. */
+  name?: string
+  /** Object store name. Defaults to `keyval`. */
+  store?: string
+  /** Database version. Defaults to `1`. */
+  version?: number
+  /** IndexedDB implementation. Defaults to the global `indexedDB`. */
+  factory?: IDBFactory | null
+}
+
+function defaultFactory(): IDBFactory | null {
+  try {
+    return typeof indexedDB === 'undefined' ? null : indexedDB
+  } catch {
+    return null
+  }
+}
+
+/** Resolve an {@link IDBRequest} on success and reject on error. */
+function promisify<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result)
+    request.onerror = () =>
+      reject(request.error ?? new Error('IndexedDB request failed'))
+  })
+}
+
+/**
+ * Create a Promise-based cache over IndexedDB.
+ *
+ * The database is opened lazily on the first operation and reused. When no
+ * IndexedDB implementation is available the store keeps values in memory, so
+ * `get`/`set`/`keys` behave identically (minus persistence) and `persistent`
+ * reports the difference.
+ */
+export function createIdbStore<T = unknown>(
+  options: IdbStoreOptions = {},
+): IdbStore<T> {
+  const dbName = options.name ?? 'newui'
+  const storeName = options.store ?? 'keyval'
+  const version = options.version ?? 1
+  const factory =
+    options.factory === undefined ? defaultFactory() : options.factory
+  const memory = new Map<string, T>()
+
+  let opening: Promise<IDBDatabase> | null = null
+
+  function open(): Promise<IDBDatabase> {
+    if (!factory) {
+      return Promise.reject(new Error('IndexedDB is not available'))
+    }
+    if (opening) return opening
+    opening = new Promise<IDBDatabase>((resolve, reject) => {
+      const request = factory.open(dbName, version)
+      request.onupgradeneeded = () => {
+        const db = request.result
+        if (!db.objectStoreNames.contains(storeName)) {
+          db.createObjectStore(storeName)
+        }
+      }
+      request.onsuccess = () => resolve(request.result)
+      request.onerror = () =>
+        reject(
+          request.error ?? new Error(`Failed to open IndexedDB "${dbName}"`),
+        )
+    })
+    return opening
+  }
+
+  async function store(mode: IDBTransactionMode): Promise<IDBObjectStore> {
+    const db = await open()
+    return db.transaction(storeName, mode).objectStore(storeName)
+  }
+
+  async function get(key: string): Promise<T | null> {
+    if (!factory) return memory.get(key) ?? null
+    const objectStore = await store('readonly')
+    const value = (await promisify(objectStore.get(key))) as T | undefined
+    return value ?? null
+  }
+
+  async function set(key: string, value: T): Promise<void> {
+    if (!factory) {
+      memory.set(key, value)
+      return
+    }
+    const objectStore = await store('readwrite')
+    await promisify(objectStore.put(value, key))
+  }
+
+  async function remove(key: string): Promise<void> {
+    if (!factory) {
+      memory.delete(key)
+      return
+    }
+    const objectStore = await store('readwrite')
+    await promisify(objectStore.delete(key))
+  }
+
+  async function keys(): Promise<string[]> {
+    if (!factory) return [...memory.keys()]
+    const objectStore = await store('readonly')
+    const all = await promisify(objectStore.getAllKeys())
+    return all.map(String)
+  }
+
+  async function clear(): Promise<void> {
+    if (!factory) {
+      memory.clear()
+      return
+    }
+    const objectStore = await store('readwrite')
+    await promisify(objectStore.clear())
+  }
+
+  function close(): void {
+    const current = opening
+    if (!current) return
+    opening = null
+    void current.then((db) => db.close()).catch(() => {})
+  }
+
+  return {
+    get,
+    set,
+    delete: remove,
+    keys,
+    clear,
+    persistent: factory !== null,
+    close,
+  }
+}

package/src/resource/index.ts

@@ -0,0 +1,77 @@
+/**
+ * The signal-based data layer: a configurable request client, generic
+ * resources, and the thin composables over them.
+ *
+ * Ported from frappe-ui's `resources/` + `data-fetching/`, translated to Solid
+ * signals. No Vue `ref`/`reactive`, no `v-model` — every value is an accessor
+ * (`() => T`) and every action a plain function.
+ */
+
+export type {
+  ClientConfig,
+  RequestErrorOptions,
+  RequestOptions,
+} from './client'
+export {
+  getConfig,
+  isAbortError,
+  normalizeError,
+  RequestError,
+  request,
+  resetConfig,
+  setConfig,
+} from './client'
+export type {
+  ConnectRealtimeOptions,
+  RealtimeConnection,
+  RealtimeEvent,
+  RealtimeResource,
+} from './connect-realtime'
+export { connectRealtime } from './connect-realtime'
+export type {
+  DocumentOperationOptions,
+  DocumentResource,
+  DocumentResourceOptions,
+} from './document'
+export { createDocumentResource } from './document'
+export type { IdbStore, IdbStoreOptions } from './idb'
+export { createIdbStore } from './idb'
+export type {
+  ListFilters,
+  ListResource,
+  ListResourceOptions,
+} from './list'
+export { createListResource } from './list'
+export type { LocalStore, LocalStoreOptions } from './local'
+export { createLocalStore } from './local'
+export type {
+  Realtime,
+  RealtimeEventMap,
+  RealtimeListener,
+  RealtimeOptions,
+  RealtimeSocket,
+  RealtimeSocketFactory,
+} from './realtime'
+export { createRealtime } from './realtime'
+export type {
+  Resource,
+  ResourceFetcher,
+  ResourceOptions,
+} from './resource'
+export { createResource } from './resource'
+export type { UseCallOptions, UseCallReturn } from './useCall'
+export { useCall } from './useCall'
+export type { UseDocOptions, UseDocReturn } from './useDoc'
+export { useDoc } from './useDoc'
+export type {
+  DoctypeAction,
+  RunDocMethodInput,
+  RunMethodInput,
+  UseDoctypeOptions,
+  UseDoctypeReturn,
+} from './useDoctype'
+export { useDoctype } from './useDoctype'
+export type { UseListOptions, UseListReturn } from './useList'
+export { useList } from './useList'
+export type { UseNewDocOptions, UseNewDocReturn } from './useNewDoc'
+export { useNewDoc } from './useNewDoc'

package/src/resource/list.test.ts

@@ -0,0 +1,150 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createListResource } from './list'
+
+function mockResponse(body: unknown): Response {
+  return {
+    ok: true,
+    status: 200,
+    statusText: 'OK',
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as unknown as Response
+}
+
+interface FetchCall {
+  mock: { calls: Array<[string, RequestInit]> }
+}
+
+function stubFetch(...responses: Response[]): FetchCall {
+  const mock = vi.fn()
+  for (const response of responses) mock.mockResolvedValueOnce(response)
+  vi.stubGlobal('fetch', mock)
+  return mock as unknown as FetchCall
+}
+
+function urlAt(mock: FetchCall, index = 0): string {
+  return mock.mock.calls[index]?.[0] ?? ''
+}
+
+function bodyAt(mock: FetchCall, index = 0): Record<string, unknown> {
+  const call = mock.mock.calls[index]
+  return JSON.parse(String(call?.[1]?.body)) as Record<string, unknown>
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('createListResource', () => {
+  it('reloads from the list endpoint with filters and a window limit', async () => {
+    const fetchMock = stubFetch(
+      mockResponse({ message: [{ name: 'T-1' }, { name: 'T-2' }] }),
+    )
+    const list = createListResource({
+      doctype: 'Task',
+      filters: { status: 'Open' },
+      pageLength: 20,
+    })
+
+    const rows = await list.reload()
+
+    expect(rows).toEqual([{ name: 'T-1' }, { name: 'T-2' }])
+    expect(urlAt(fetchMock)).toBe('/api/method/frappe.client.get_list')
+    expect(bodyAt(fetchMock)).toEqual({
+      doctype: 'Task',
+      filters: { status: 'Open' },
+      start: 0,
+      limit: 20,
+      limit_start: 0,
+      limit_page_length: 20,
+    })
+    expect(list.hasNextPage()).toBe(false)
+    expect(list.hasPreviousPage()).toBe(false)
+  })
+
+  it('next advances the window and refetches', async () => {
+    const page = Array.from({ length: 20 }, (_, i) => ({ name: `T-${i}` }))
+    const fetchMock = stubFetch(
+      mockResponse({ message: page }),
+      mockResponse({ message: page }),
+    )
+    const list = createListResource({ doctype: 'Task', pageLength: 20 })
+
+    await list.reload()
+    expect(list.hasNextPage()).toBe(true)
+
+    await list.next()
+    expect(list.start()).toBe(20)
+    expect(list.hasPreviousPage()).toBe(true)
+    expect(bodyAt(fetchMock, 1)).toEqual({
+      doctype: 'Task',
+      filters: null,
+      start: 0,
+      limit: 40,
+      limit_start: 0,
+      limit_page_length: 40,
+    })
+
+    await list.previous()
+    expect(list.start()).toBe(0)
+    expect(bodyAt(fetchMock, 2)).toEqual({
+      doctype: 'Task',
+      filters: null,
+      start: 0,
+      limit: 20,
+      limit_start: 0,
+      limit_page_length: 20,
+    })
+  })
+
+  it('setFilters resets to the first page and refetches', async () => {
+    const fetchMock = stubFetch(
+      mockResponse({ message: [] }),
+      mockResponse({ message: [] }),
+    )
+    const list = createListResource({ doctype: 'Task', pageLength: 20 })
+
+    await list.next()
+    await list.setFilters({ status: 'Closed' })
+
+    expect(list.start()).toBe(0)
+    expect(list.filters()).toEqual({ status: 'Closed' })
+    expect(bodyAt(fetchMock, 1)).toEqual({
+      doctype: 'Task',
+      filters: { status: 'Closed' },
+      start: 0,
+      limit: 20,
+      limit_start: 0,
+      limit_page_length: 20,
+    })
+  })
+
+  it('sets error and resolves on failure', async () => {
+    stubFetch({
+      ok: false,
+      status: 500,
+      statusText: 'Server Error',
+      json: async () => ({}),
+      text: async () => JSON.stringify({ _error_message: 'boom' }),
+    } as unknown as Response)
+    const list = createListResource({ doctype: 'Task' })
+
+    const rows = await list.reload()
+
+    expect(rows).toBe(null)
+    expect(list.error()).not.toBe(null)
+    expect(list.loading()).toBe(false)
+  })
+
+  it('applies transform to the rows', async () => {
+    stubFetch(mockResponse({ message: [{ name: 'T-1' }, { name: 'T-2' }] }))
+    const list = createListResource<{ name: string }>({
+      doctype: 'Task',
+      transform: (rows) => rows.slice(0, 1),
+    })
+
+    const rows = await list.reload()
+    expect(rows).toEqual([{ name: 'T-1' }])
+    expect(list.data()).toEqual([{ name: 'T-1' }])
+  })
+})

package/src/resource/list.ts

@@ -0,0 +1,230 @@
+import { type Accessor, createSignal } from 'solid-js'
+import {
+  isAbortError,
+  normalizeError,
+  type RequestError,
+  request,
+} from './client'
+import type { ResourceFetcher } from './resource'
+
+/** A Frappe filter map (`{ status: 'Open', name: ['like', '%x%'] }`). */
+export type ListFilters = Record<string, unknown>
+
+/** Options for {@link createListResource}. */
+export interface ListResourceOptions<TRow = Record<string, unknown>> {
+  doctype: string
+  /** Fields to select. */
+  fields?: string[]
+  /** Filters, or an accessor for reactive filters. */
+  filters?: ListFilters | (() => ListFilters)
+  /** OR-filters (`or_filters`). */
+  orFilters?: ListFilters | (() => ListFilters)
+  /** `order_by` clause, e.g. `modified desc`. */
+  orderBy?: string
+  /** Initial page offset. Defaults to `0`. */
+  start?: number
+  /** Rows per page. Defaults to `20`. */
+  pageLength?: number
+  groupBy?: string
+  parent?: string
+  debug?: boolean | number
+  /** Overrides the default list endpoint. */
+  url?: string
+  /** Fetch on creation. Defaults to `false`. */
+  auto?: boolean
+  /** Map the raw rows. */
+  transform?: (rows: TRow[]) => TRow[]
+  onSuccess?: (rows: TRow[]) => void
+  onError?: (error: RequestError) => void
+  fetcher?: ResourceFetcher
+}
+
+/** A paginated, filterable list resource. */
+export interface ListResource<TRow = Record<string, unknown>> {
+  data: Accessor<TRow[] | null>
+  loading: Accessor<boolean>
+  error: Accessor<RequestError | null>
+  fetched: Accessor<boolean>
+  filters: Accessor<ListFilters | null>
+  /** Current page offset (the `start` of the window). */
+  start: Accessor<number>
+  pageLength: Accessor<number>
+  hasNextPage: Accessor<boolean>
+  hasPreviousPage: Accessor<boolean>
+  /** Refetch the window from the start. */
+  reload: () => Promise<TRow[] | null>
+  /** Alias of {@link ListResource.reload}. */
+  fetch: () => Promise<TRow[] | null>
+  /** Advance one page and refetch. */
+  next: () => Promise<TRow[] | null>
+  /** Go back one page and refetch. */
+  previous: () => Promise<TRow[] | null>
+  /** Replace the filters, reset to the first page, and refetch. */
+  setFilters: (filters: ListFilters) => Promise<TRow[] | null>
+  /** Replace `data` without a request. */
+  setData: (rows: TRow[]) => void
+  reset: () => void
+}
+
+const DEFAULT_LIST_URL = 'frappe.client.get_list'
+
+function resolveFilters(
+  value: ListFilters | (() => ListFilters) | undefined,
+): ListFilters | undefined {
+  return typeof value === 'function' ? value() : value
+}
+
+/**
+ * The signal-based replacement for frappe-ui's `createListResource`.
+ *
+ * Pagination is a sliding window: `reload` always fetches from `start = 0` with
+ * a limit of `start + pageLength`, so `data` holds every row up to the current
+ * page. `next`/`previous` move the window and refetch; `hasNextPage` is true
+ * when the server returned a full window.
+ */
+export function createListResource<TRow = Record<string, unknown>>(
+  options: ListResourceOptions<TRow>,
+): ListResource<TRow> {
+  const fetcher: ResourceFetcher = options.fetcher ?? request
+
+  const [data, setDataSignal] = createSignal<TRow[] | null>(null)
+  const [loading, setLoading] = createSignal(false)
+  const [error, setError] = createSignal<RequestError | null>(null)
+  const [fetched, setFetched] = createSignal(false)
+  const [start, setStart] = createSignal(options.start ?? 0)
+  const [pageLength] = createSignal(options.pageLength ?? 20)
+  const [hasNextPage, setHasNextPage] = createSignal(true)
+  const hasPreviousPage = (): boolean => start() > 0
+
+  // `setFilters` wins over the option; both may be an accessor.
+  const [filtersOverride, setFiltersOverride] =
+    createSignal<ListFilters | null>(null)
+  const filters = (): ListFilters | null => {
+    const override = filtersOverride()
+    if (override) return override
+    const value = options.filters
+    if (typeof value === 'function') return value()
+    return value ?? null
+  }
+
+  let controller: AbortController | null = null
+  let sequence = 0
+
+  function makeParams(limit: number): Record<string, unknown> {
+    return {
+      doctype: options.doctype,
+      fields: options.fields,
+      filters: filters(),
+      or_filters: resolveFilters(options.orFilters),
+      order_by: options.orderBy,
+      start: 0,
+      limit,
+      limit_start: 0,
+      limit_page_length: limit,
+      group_by: options.groupBy,
+      parent: options.parent,
+      debug: options.debug,
+    }
+  }
+
+  function transform(rows: TRow[]): TRow[] {
+    if (options.transform) {
+      const result = options.transform(rows)
+      if (Array.isArray(result)) return result
+    }
+    return rows
+  }
+
+  function reload(): Promise<TRow[] | null> {
+    const current = ++sequence
+    controller?.abort()
+    controller = new AbortController()
+    setLoading(true)
+    setError(null)
+
+    const limit = start() + pageLength()
+    const result = fetcher<TRow[]>({
+      url: options.url ?? DEFAULT_LIST_URL,
+      method: 'POST',
+      params: makeParams(limit),
+      signal: controller.signal,
+    })
+      .then((rows) => {
+        if (current !== sequence) return data()
+        const list = Array.isArray(rows) ? rows : []
+        setHasNextPage(list.length >= limit)
+        const transformed = transform(list)
+        setDataSignal(() => transformed)
+        setFetched(true)
+        options.onSuccess?.(transformed)
+        return transformed
+      })
+      .catch((caught: unknown) => {
+        if (current !== sequence || isAbortError(caught)) return data()
+        const normalized = normalizeError(caught)
+        setError(normalized)
+        options.onError?.(normalized)
+        return data()
+      })
+      .finally(() => {
+        if (current === sequence) setLoading(false)
+      })
+
+    return result
+  }
+
+  function next(): Promise<TRow[] | null> {
+    setStart(start() + pageLength())
+    return reload()
+  }
+
+  function previous(): Promise<TRow[] | null> {
+    setStart(Math.max(0, start() - pageLength()))
+    return reload()
+  }
+
+  function setFilters(next: ListFilters): Promise<TRow[] | null> {
+    setFiltersOverride(() => next)
+    setStart(0)
+    return reload()
+  }
+
+  function setData(rows: TRow[]): void {
+    setDataSignal(() => transform(rows))
+  }
+
+  function reset(): void {
+    controller?.abort()
+    sequence++
+    setDataSignal(() => null)
+    setLoading(false)
+    setError(null)
+    setFetched(false)
+    setStart(options.start ?? 0)
+    setHasNextPage(true)
+  }
+
+  // Auto-fetch on creation. `reload` is a plain action, not a signal — the
+  // reactivity rule cannot tell the difference, so it is silenced here.
+  // eslint-disable-next-line solid/reactivity
+  if (options.auto) void reload()
+
+  return {
+    data,
+    loading,
+    error,
+    fetched,
+    filters,
+    start,
+    pageLength,
+    hasNextPage,
+    hasPreviousPage,
+    reload,
+    fetch: reload,
+    next,
+    previous,
+    setFilters,
+    setData,
+    reset,
+  }
+}