@talelk/newui-data 0.0.0-stage → 1.0.0

package/src/resource/resource.test.ts

@@ -0,0 +1,186 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { RequestError } from './client'
+import { createResource } from './resource'
+
+function mockResponse(
+  body: unknown,
+  init: { ok?: boolean; status?: number; statusText?: string } = {},
+): Response {
+  const { ok = true, status = 200, statusText = 'OK' } = init
+  return {
+    ok,
+    status,
+    statusText,
+    json: async () => body,
+    text: async () => (typeof body === 'string' ? body : 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('createResource', () => {
+  it('loads data and tracks the loading transition', async () => {
+    stubFetch(mockResponse({ message: { name: 'T-1' } }))
+    const resource = createResource<{ name: string }>({
+      url: 'frappe.client.get',
+      method: 'GET',
+    })
+
+    expect(resource.loading()).toBe(false)
+    const promise = resource.reload()
+    expect(resource.loading()).toBe(true)
+
+    const data = await promise
+    expect(data).toEqual({ name: 'T-1' })
+    expect(resource.data()).toEqual({ name: 'T-1' })
+    expect(resource.loading()).toBe(false)
+    expect(resource.error()).toBe(null)
+    expect(resource.fetched()).toBe(true)
+  })
+
+  it('reload resolves on error, sets error and restores previous data', async () => {
+    stubFetch(
+      mockResponse({ message: { name: 'A' } }),
+      mockResponse(
+        { _error_message: 'nope' },
+        { ok: false, status: 500, statusText: 'Server Error' },
+      ),
+    )
+    const resource = createResource<{ name: string }>({
+      url: 'frappe.client.get',
+      method: 'GET',
+    })
+
+    await resource.reload()
+    const result = await resource.reload()
+
+    expect(result).toEqual({ name: 'A' })
+    expect(resource.data()).toEqual({ name: 'A' })
+    expect(resource.error()).toBeInstanceOf(RequestError)
+    expect(resource.loading()).toBe(false)
+  })
+
+  it('submit rejects on error', async () => {
+    stubFetch(
+      mockResponse(
+        { _error_message: 'bad' },
+        { ok: false, status: 400, statusText: 'Bad Request' },
+      ),
+    )
+    const resource = createResource({ url: 'frappe.client.insert' })
+
+    await expect(resource.submit()).rejects.toBeInstanceOf(RequestError)
+    expect(resource.error()).toBeInstanceOf(RequestError)
+  })
+
+  it('sends makeParams output to the configured url and method', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: 'ok' }))
+    const resource = createResource<string, { name: string }>({
+      url: 'frappe.client.delete',
+      method: 'POST',
+      makeParams: ({ name }) => ({ doctype: 'Task', name }),
+    })
+
+    await resource.submit({ name: 'T-1' })
+
+    expect(urlAt(fetchMock)).toBe('/api/method/frappe.client.delete')
+    expect(bodyAt(fetchMock)).toEqual({ doctype: 'Task', name: 'T-1' })
+  })
+
+  it('auto fetches on creation', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: 1 }))
+    const resource = createResource<number>({
+      url: 'myapp.api.count',
+      method: 'GET',
+      auto: true,
+    })
+
+    await vi.waitFor(() => expect(resource.data()).toBe(1))
+    expect(fetchMock.mock.calls.length).toBe(1)
+  })
+
+  it('supports setData and reset', () => {
+    const resource = createResource<number>({ url: 'x', initialData: 0 })
+
+    resource.setData(5)
+    expect(resource.data()).toBe(5)
+
+    resource.setData((current) => (current ?? 0) + 1)
+    expect(resource.data()).toBe(6)
+
+    resource.reset()
+    expect(resource.data()).toBe(0)
+    expect(resource.fetched()).toBe(false)
+    expect(resource.loading()).toBe(false)
+  })
+
+  it('aborts an in-flight request without surfacing an error', async () => {
+    const mock = vi.fn(
+      (_url: string, init?: RequestInit) =>
+        new Promise<Response>((_resolve, reject) => {
+          init?.signal?.addEventListener('abort', () => {
+            const error = new Error('aborted')
+            error.name = 'AbortError'
+            reject(error)
+          })
+        }),
+    )
+    vi.stubGlobal('fetch', mock)
+
+    const resource = createResource({ url: 'myapp.api.slow' })
+    const promise = resource.reload()
+    expect(resource.loading()).toBe(true)
+
+    resource.abort()
+    await promise
+
+    expect(resource.loading()).toBe(false)
+    expect(resource.error()).toBe(null)
+  })
+
+  it('discards a superseded response', async () => {
+    let resolveFirst: ((value: Response) => void) | undefined
+    const first = new Promise<Response>((resolve) => {
+      resolveFirst = resolve
+    })
+    const mock = vi
+      .fn()
+      .mockReturnValueOnce(first)
+      .mockResolvedValueOnce(mockResponse({ message: { name: 'second' } }))
+    vi.stubGlobal('fetch', mock)
+
+    const resource = createResource<{ name: string }>({
+      url: 'frappe.client.get',
+      method: 'GET',
+    })
+
+    const stale = resource.reload()
+    const fresh = resource.reload()
+    resolveFirst?.(mockResponse({ message: { name: 'first' } }))
+    await Promise.all([stale, fresh])
+
+    expect(resource.data()).toEqual({ name: 'second' })
+  })
+})

package/src/resource/resource.ts

@@ -0,0 +1,213 @@
+import { type Accessor, createSignal } from 'solid-js'
+import {
+  isAbortError,
+  normalizeError,
+  type RequestError,
+  type RequestOptions,
+  request,
+} from './client'
+
+/** The request function a resource uses. Defaults to the module {@link request}. */
+export type ResourceFetcher = <TResponse = unknown>(
+  options: RequestOptions,
+) => Promise<TResponse>
+
+/**
+ * Options for {@link createResource}. `url` and `params` may be accessors so
+ * the resource re-reads them on every fetch (a reactive `name`, a filter).
+ */
+export interface ResourceOptions<
+  TData = unknown,
+  TInput = unknown,
+  TParams = Record<string, unknown>,
+> {
+  /** Absolute URL, `/api/method/…`, or a dotted method name. Accessor allowed. */
+  url: string | (() => string)
+  /** HTTP method. Defaults to `POST`. */
+  method?: string
+  /** Static params, or an accessor for reactive params. */
+  params?: TParams | (() => TParams)
+  /**
+   * Map the value passed to `reload`/`submit` into request params. When absent,
+   * a passed value is used as the params directly.
+   */
+  makeParams?: (input: TInput) => TParams
+  /** Value before the first fetch. */
+  initialData?: TData | null
+  /** Fetch on creation. Defaults to `false`. */
+  auto?: boolean
+  /** Map the raw response into `TData`. */
+  transform?: (data: unknown) => TData
+  onSuccess?: (data: TData) => void
+  onError?: (error: RequestError) => void
+  /** Custom request function; defaults to the module client. */
+  fetcher?: ResourceFetcher
+}
+
+/**
+ * A generic, signal-based resource. Every field is an accessor; every action is
+ * a plain function. There is no Vue `ref`/`reactive` and no `v-model`.
+ */
+export interface Resource<TData = unknown, TInput = unknown> {
+  data: Accessor<TData | null>
+  loading: Accessor<boolean>
+  error: Accessor<RequestError | null>
+  /** True once a fetch has resolved at least once. */
+  fetched: Accessor<boolean>
+  /** The in-flight promise, or the last one. */
+  promise: Accessor<Promise<TData | null> | null>
+  /** Read: fetch, resolving with the data (or the previous data) even on failure. */
+  reload: (input?: TInput) => Promise<TData | null>
+  /** Alias of {@link Resource.reload}. */
+  fetch: (input?: TInput) => Promise<TData | null>
+  /** Write: like `reload`, but rejects on failure. */
+  submit: (input?: TInput) => Promise<TData | null>
+  /** Replace `data`, directly or from its current value. */
+  setData: (data: TData | ((current: TData | null) => TData)) => void
+  /** Back to `initialData`, clearing loading/error/fetched. */
+  reset: () => void
+  /** Abort the in-flight request without surfacing an error. */
+  abort: () => void
+}
+
+/**
+ * The signal-based replacement for frappe-ui's `createResource`.
+ *
+ * `reload` (and its `fetch` alias) resolves on failure — a read reports through
+ * `error`. `submit` rejects on failure — a write must not run its success path.
+ * A new fetch aborts the previous one; a superseded response is discarded, so
+ * `data` always reflects the newest request.
+ */
+export function createResource<
+  TData = unknown,
+  TInput = unknown,
+  TParams = Record<string, unknown>,
+>(options: ResourceOptions<TData, TInput, TParams>): Resource<TData, TInput> {
+  const fetcher: ResourceFetcher = options.fetcher ?? request
+
+  const [data, setDataSignal] = createSignal<TData | null>(
+    options.initialData ?? null,
+  )
+  const [loading, setLoading] = createSignal(false)
+  const [error, setError] = createSignal<RequestError | null>(null)
+  const [fetched, setFetched] = createSignal(false)
+  const [promise, setPromise] = createSignal<Promise<TData | null> | null>(null)
+
+  let controller: AbortController | null = null
+  // Monotonic request id. Only the newest request may write state; an older
+  // response (or a superseded abort) is ignored.
+  let sequence = 0
+
+  function resolveUrl(): string {
+    return typeof options.url === 'function' ? options.url() : options.url
+  }
+
+  function resolveParams(input: TInput | undefined): TParams | undefined {
+    if (options.makeParams) return options.makeParams(input as TInput)
+    if (input !== undefined) return input as unknown as TParams
+    const params = options.params
+    if (typeof params === 'function') return (params as () => TParams)()
+    return params
+  }
+
+  function transform(value: unknown): TData {
+    if (options.transform) {
+      const result = options.transform(value)
+      if (result !== undefined) return result
+    }
+    return value as TData
+  }
+
+  function execute(
+    input: TInput | undefined,
+    rejectOnError: boolean,
+  ): Promise<TData | null> {
+    const current = ++sequence
+    controller?.abort()
+    controller = new AbortController()
+    setLoading(true)
+    setError(null)
+    const previous = data()
+
+    const params = resolveParams(input)
+    const result = fetcher<TData>({
+      url: resolveUrl(),
+      method: options.method,
+      params: params as Record<string, unknown> | undefined,
+      signal: controller.signal,
+    })
+      .then((response) => {
+        if (current !== sequence) return data()
+        const transformed = transform(response)
+        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)
+        setDataSignal(() => previous)
+        options.onError?.(normalized)
+        if (rejectOnError) throw normalized
+        return data()
+      })
+      .finally(() => {
+        if (current === sequence) setLoading(false)
+      })
+
+    setPromise(result)
+    return result
+  }
+
+  function reload(input?: TInput): Promise<TData | null> {
+    return execute(input, false)
+  }
+
+  function submit(input?: TInput): Promise<TData | null> {
+    return execute(input, true)
+  }
+
+  function setData(next: TData | ((current: TData | null) => TData)): void {
+    if (typeof next === 'function') {
+      const updater = next as (current: TData | null) => TData
+      setDataSignal(() => updater(data()))
+      return
+    }
+    setDataSignal(() => next)
+  }
+
+  function reset(): void {
+    controller?.abort()
+    sequence++
+    setDataSignal(() => options.initialData ?? null)
+    setLoading(false)
+    setError(null)
+    setFetched(false)
+    setPromise(null)
+  }
+
+  function abort(): void {
+    controller?.abort()
+  }
+
+  // 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,
+    promise,
+    reload,
+    fetch: reload,
+    submit,
+    setData,
+    reset,
+    abort,
+  }
+}

package/src/resource/useCall.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { useCall } from './useCall'
+
+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] ?? ''
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('useCall', () => {
+  it('fetches immediately and exposes signals', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: { count: 3 } }))
+    const call = useCall<{ count: number }>({
+      url: 'frappe.client.get_count',
+      method: 'GET',
+    })
+
+    await vi.waitFor(() => expect(call.data()).toEqual({ count: 3 }))
+    expect(urlAt(fetchMock)).toBe('/api/method/frappe.client.get_count')
+    expect(call.loading()).toBe(false)
+    expect(call.error()).toBe(null)
+  })
+
+  it('does not fetch when immediate is false', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: 1 }))
+    const call = useCall<number>({
+      url: 'myapp.api.count',
+      method: 'GET',
+      immediate: false,
+    })
+
+    expect(fetchMock.mock.calls.length).toBe(0)
+    await call.reload()
+    expect(fetchMock.mock.calls.length).toBe(1)
+    expect(call.data()).toBe(1)
+  })
+})

package/src/resource/useCall.ts

@@ -0,0 +1,74 @@
+import type { Accessor } from 'solid-js'
+import type { RequestError } from './client'
+import { createResource, type ResourceFetcher } from './resource'
+
+/** Options for {@link useCall}. Mirrors {@link ResourceOptions} with signals out. */
+export interface UseCallOptions<
+  TResponse = unknown,
+  TParams = Record<string, unknown>,
+> {
+  url: string | (() => string)
+  /** HTTP method. Defaults to `GET`. */
+  method?: string
+  params?: TParams | (() => TParams)
+  /** Fetch on creation. Defaults to `true`. */
+  immediate?: boolean
+  initialData?: TResponse | null
+  transform?: (data: unknown) => TResponse
+  onSuccess?: (data: TResponse) => void
+  onError?: (error: RequestError) => void
+  fetcher?: ResourceFetcher
+}
+
+/** The signal-based surface {@link useCall} returns. */
+export interface UseCallReturn<TResponse = unknown> {
+  data: Accessor<TResponse | null>
+  loading: Accessor<boolean>
+  error: Accessor<RequestError | null>
+  fetched: Accessor<boolean>
+  /** Read: fetch, resolving even on failure. */
+  execute: () => Promise<TResponse | null>
+  fetch: () => Promise<TResponse | null>
+  reload: () => Promise<TResponse | null>
+  /** Write: fetch, rejecting on failure. */
+  submit: () => Promise<TResponse | null>
+  abort: () => void
+  reset: () => void
+  setData: (
+    data: TResponse | ((current: TResponse | null) => TResponse),
+  ) => void
+}
+
+/**
+ * A thin composable over {@link createResource}: call a Frappe method and read
+ * the result through signals.
+ */
+export function useCall<TResponse = unknown, TParams = Record<string, unknown>>(
+  options: UseCallOptions<TResponse, TParams>,
+): UseCallReturn<TResponse> {
+  const resource = createResource<TResponse, unknown, TParams>({
+    url: options.url,
+    method: options.method ?? 'GET',
+    params: options.params,
+    initialData: options.initialData ?? null,
+    auto: options.immediate ?? true,
+    transform: options.transform,
+    onSuccess: options.onSuccess,
+    onError: options.onError,
+    fetcher: options.fetcher,
+  })
+
+  return {
+    data: resource.data,
+    loading: resource.loading,
+    error: resource.error,
+    fetched: resource.fetched,
+    execute: () => resource.reload(),
+    fetch: () => resource.reload(),
+    reload: () => resource.reload(),
+    submit: () => resource.submit(),
+    abort: resource.abort,
+    reset: resource.reset,
+    setData: resource.setData,
+  }
+}

package/src/resource/useDoc.test.ts

@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { useDoc } from './useDoc'
+
+function mockResponse(body: unknown): Response {
+  return {
+    ok: true,
+    status: 200,
+    statusText: 'OK',
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as unknown as Response
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('useDoc', () => {
+  it('delegates to the document resource', async () => {
+    const mock = vi.fn(async () => mockResponse({ message: { name: 'T-1' } }))
+    vi.stubGlobal('fetch', mock)
+
+    const doc = useDoc<{ name: string }>({ doctype: 'Task', name: 'T-1' })
+
+    await vi.waitFor(() => expect(doc.doc()).toEqual({ name: 'T-1' }))
+    expect(mock).toHaveBeenCalledWith(
+      '/api/method/frappe.client.get?doctype=Task&name=T-1',
+      expect.objectContaining({ method: 'GET' }),
+    )
+  })
+})

package/src/resource/useDoc.ts

@@ -0,0 +1,23 @@
+import {
+  createDocumentResource,
+  type DocumentResource,
+  type DocumentResourceOptions,
+} from './document'
+
+/** Options for {@link useDoc}. */
+export type UseDocOptions<TDoc = Record<string, unknown>> =
+  DocumentResourceOptions<TDoc>
+
+/** The signal-based surface {@link useDoc} returns. */
+export type UseDocReturn<TDoc = Record<string, unknown>> =
+  DocumentResource<TDoc>
+
+/**
+ * A thin composable over {@link createDocumentResource}: load a single
+ * document and edit it through signals.
+ */
+export function useDoc<TDoc = Record<string, unknown>>(
+  options: DocumentResourceOptions<TDoc>,
+): DocumentResource<TDoc> {
+  return createDocumentResource(options)
+}

package/src/resource/useDoctype.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { useDoctype } from './useDoctype'
+
+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('useDoctype', () => {
+  it('insert posts the wrapped doc', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: { name: 'T-1' } }))
+    const doctype = useDoctype<{ name: string }>('Task')
+
+    const created = await doctype.insert.submit({ name: 'T-1' })
+
+    expect(created).toEqual({ name: 'T-1' })
+    expect(urlAt(fetchMock)).toBe('/api/method/frappe.client.insert')
+    expect(bodyAt(fetchMock)).toEqual({ doc: { doctype: 'Task', name: 'T-1' } })
+  })
+
+  it('setValue splits the name out of the values', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: { name: 'T-1' } }))
+    const doctype = useDoctype('Task')
+
+    await doctype.setValue.submit({ name: 'T-1', subject: 'X' })
+
+    expect(bodyAt(fetchMock)).toEqual({
+      doctype: 'Task',
+      name: 'T-1',
+      fieldname: { subject: 'X' },
+    })
+  })
+
+  it('delete posts the name', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: 'ok' }))
+    const doctype = useDoctype('Task')
+
+    await doctype.delete.submit('T-1')
+
+    expect(urlAt(fetchMock)).toBe('/api/method/frappe.client.delete')
+    expect(bodyAt(fetchMock)).toEqual({ doctype: 'Task', name: 'T-1' })
+  })
+
+  it('runDocMethod posts dt/dn/method/args', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: { ok: true } }))
+    const doctype = useDoctype('Task')
+
+    await doctype.runDocMethod.submit({
+      name: 'T-1',
+      method: 'submit',
+      params: { force: true },
+    })
+
+    expect(urlAt(fetchMock)).toBe('/api/method/run_doc_method')
+    expect(bodyAt(fetchMock)).toEqual({
+      dt: 'Task',
+      dn: 'T-1',
+      method: 'submit',
+      args: { force: true },
+    })
+  })
+
+  it('runMethod posts to the method name', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: 'ok' }))
+    const doctype = useDoctype('Task')
+
+    await doctype.runMethod.submit({
+      method: 'myapp.api.ping',
+      params: { x: 1 },
+    })
+
+    expect(urlAt(fetchMock)).toBe('/api/method/myapp.api.ping')
+    expect(bodyAt(fetchMock)).toEqual({ x: 1 })
+  })
+})