@talelk/newui-data 0.0.0-stage → 1.0.0

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,
+  }
+}

package/src/resource/local.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createLocalStore } from './local'
+
+// jsdom provides a working `localStorage` (vitest sets an http origin), so the
+// default backend is exercised for real; the memory fallback is tested by
+// passing `storage: null` and by hiding the global.
+
+let prefix = 0
+function nextPrefix(): string {
+  prefix += 1
+  return `test-${prefix}:`
+}
+
+beforeEach(() => {
+  localStorage.clear()
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  localStorage.clear()
+})
+
+describe('createLocalStore', () => {
+  it('round-trips JSON values through localStorage', () => {
+    const store = createLocalStore({ prefix: nextPrefix() })
+
+    store.set('doc', { name: 'T-1', tags: ['a', 'b'] })
+    store.set('count', 3)
+    store.set('flag', false)
+
+    expect(store.persistent).toBe(true)
+    expect(store.get('doc')).toEqual({ name: 'T-1', tags: ['a', 'b'] })
+    expect(store.get('count')).toBe(3)
+    expect(store.get('flag')).toBe(false)
+  })
+
+  it('returns null for a missing or unparseable entry', () => {
+    const store = createLocalStore<unknown>({ prefix: 'broken:' })
+    expect(store.get('nope')).toBe(null)
+
+    // A value written outside the JSON contract must not throw on read.
+    localStorage.setItem('broken:x', 'not json')
+    expect(store.get('x')).toBe(null)
+  })
+
+  it('scopes keys, delete, has, keys and clear to its prefix', () => {
+    const store = createLocalStore({ prefix: 'mine:' })
+    const other = createLocalStore({ prefix: 'other:' })
+
+    store.set('a', 1)
+    store.set('b', 2)
+    other.set('a', 9)
+
+    expect(store.has('a')).toBe(true)
+    expect(store.keys().sort()).toEqual(['a', 'b'])
+    expect(other.keys()).toEqual(['a'])
+
+    store.delete('a')
+    expect(store.has('a')).toBe(false)
+    expect(other.get('a')).toBe(9)
+
+    store.clear()
+    expect(store.keys()).toEqual([])
+    expect(other.get('a')).toBe(9)
+  })
+
+  it('persists across store instances that share a prefix', () => {
+    const first = createLocalStore<{ v: number }>({ prefix: 'shared:' })
+    first.set('k', { v: 1 })
+
+    const second = createLocalStore<{ v: number }>({ prefix: 'shared:' })
+    expect(second.get('k')).toEqual({ v: 1 })
+  })
+
+  it('falls back to memory when storage is explicitly null', () => {
+    const store = createLocalStore({ prefix: nextPrefix(), storage: null })
+
+    expect(store.persistent).toBe(false)
+    store.set('k', 'v')
+    expect(store.get('k')).toBe('v')
+    expect(store.has('k')).toBe(true)
+    expect(store.keys()).toEqual(['k'])
+    store.clear()
+    expect(store.keys()).toEqual([])
+  })
+
+  it('falls back to memory when localStorage is unavailable (SSR)', () => {
+    vi.stubGlobal('localStorage', undefined)
+    const store = createLocalStore({ prefix: nextPrefix() })
+
+    expect(store.persistent).toBe(false)
+    store.set('k', { v: 1 })
+    expect(store.get('k')).toEqual({ v: 1 })
+  })
+
+  it('drops writes when the backing storage throws', () => {
+    const throwing = {
+      length: 0,
+      key: () => null,
+      getItem: () => null,
+      setItem: () => {
+        throw new Error('QuotaExceededError')
+      },
+      removeItem: () => {},
+    } as unknown as Storage
+    const store = createLocalStore({ prefix: nextPrefix(), storage: throwing })
+
+    expect(() => store.set('k', 1)).not.toThrow()
+    expect(store.get('k')).toBe(null)
+  })
+})

package/src/resource/local.ts

@@ -0,0 +1,155 @@
+/**
+ * A `localStorage`-backed key/value store for caching resource data.
+ *
+ * The synchronous sibling of {@link createIdbStore}: values are JSON-encoded, so
+ * anything `JSON.parse(JSON.stringify(value))` round-trips is safe to cache.
+ * Every call is guarded for SSR — with no `localStorage` the store silently
+ * falls back to an in-memory `Map`, so importing and using it on the server
+ * never throws. It is a plain API (no Solid reactivity): a cache is not a view.
+ */
+
+/** The storage backend a {@link LocalStore} reads and writes. */
+type LocalStoreBackend = Storage | null
+
+/** A synchronous, JSON, key/value cache. */
+export interface LocalStore<T = unknown> {
+  /** The stored value, or `null` when the key is absent or not JSON. */
+  get(key: string): T | null
+  /** JSON-encode and persist a value. */
+  set(key: string, value: T): void
+  /** Remove a key. */
+  delete(key: string): void
+  /** Whether the key exists. */
+  has(key: string): boolean
+  /** Every key owned by this store, with the prefix stripped. */
+  keys(): string[]
+  /** Remove every key owned by this store. */
+  clear(): void
+  /** False when the store fell back to memory (SSR, or storage disabled). */
+  readonly persistent: boolean
+}
+
+/** Options for {@link createLocalStore}. */
+export interface LocalStoreOptions {
+  /** Key prefix, so several stores can share one `localStorage`. */
+  prefix?: string
+  /** Storage backend. Defaults to the global `localStorage`. */
+  storage?: LocalStoreBackend
+}
+
+function defaultStorage(): LocalStoreBackend {
+  try {
+    return typeof localStorage === 'undefined' ? null : localStorage
+  } catch {
+    // A sandboxed or disabled `localStorage` throws on access, not on use.
+    return null
+  }
+}
+
+/**
+ * Create a synchronous cache over `localStorage`.
+ *
+ * Keys are namespaced by `prefix` (default `newui:`), so a store owns only the
+ * entries it wrote: `keys()` and `clear()` never touch another store's data.
+ * A storage that throws (quota exceeded, disabled) degrades to a no-op write
+ * rather than failing the caller.
+ */
+export function createLocalStore<T = unknown>(
+  options: LocalStoreOptions = {},
+): LocalStore<T> {
+  const prefix = options.prefix ?? 'newui:'
+  const storage =
+    options.storage === undefined ? defaultStorage() : options.storage
+  const memory = new Map<string, string>()
+
+  const scoped = (key: string): string => `${prefix}${key}`
+
+  function get(key: string): T | null {
+    let raw: string | null
+    if (storage) {
+      try {
+        raw = storage.getItem(scoped(key))
+      } catch {
+        raw = null
+      }
+    } else {
+      raw = memory.get(key) ?? null
+    }
+    if (raw === null) return null
+    try {
+      return JSON.parse(raw) as T
+    } catch {
+      return null
+    }
+  }
+
+  function set(key: string, value: T): void {
+    const raw = JSON.stringify(value)
+    if (storage) {
+      try {
+        storage.setItem(scoped(key), raw)
+      } catch {
+        // Quota or disabled storage: the write is dropped, not fatal.
+      }
+    } else {
+      memory.set(key, raw)
+    }
+  }
+
+  function remove(key: string): void {
+    if (storage) {
+      try {
+        storage.removeItem(scoped(key))
+      } catch {
+        // Nothing to do — the entry is already unreachable.
+      }
+    } else {
+      memory.delete(key)
+    }
+  }
+
+  function has(key: string): boolean {
+    if (storage) {
+      try {
+        return storage.getItem(scoped(key)) !== null
+      } catch {
+        return false
+      }
+    }
+    return memory.has(key)
+  }
+
+  function keys(): string[] {
+    if (!storage) return [...memory.keys()]
+    const owned: string[] = []
+    try {
+      for (let index = 0; index < storage.length; index++) {
+        const key = storage.key(index)
+        if (key?.startsWith(prefix)) {
+          owned.push(key.slice(prefix.length))
+        }
+      }
+    } catch {
+      return []
+    }
+    return owned
+  }
+
+  function clear(): void {
+    if (!storage) {
+      memory.clear()
+      return
+    }
+    for (const key of keys()) remove(key)
+  }
+
+  return {
+    get,
+    set,
+    delete: remove,
+    has,
+    keys,
+    clear,
+    persistent: storage !== null,
+  }
+}