@talelk/newui-data 0.0.0-stage → 1.1.0

package/src/resource/client.test.ts

@@ -0,0 +1,173 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  getConfig,
+  isAbortError,
+  normalizeError,
+  RequestError,
+  request,
+  resetConfig,
+  setConfig,
+} from './client'
+
+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(response: Response): FetchCall {
+  const mock = vi.fn(async () => response)
+  vi.stubGlobal('fetch', mock)
+  return mock as unknown as FetchCall
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  resetConfig()
+})
+
+describe('request', () => {
+  it('POSTs a dotted method to /api/method and unwraps message', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: [1, 2, 3] }))
+    const result = await request({
+      url: 'frappe.client.get_list',
+      params: { doctype: 'Task' },
+    })
+
+    expect(result).toEqual([1, 2, 3])
+    expect(fetchMock).toHaveBeenCalledWith(
+      '/api/method/frappe.client.get_list',
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ doctype: 'Task' }),
+      }),
+    )
+  })
+
+  it('appends GET params as the query string', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: { name: 'T-1' } }))
+    await request({
+      url: 'frappe.client.get',
+      method: 'GET',
+      params: { doctype: 'Task', name: 'T-1' },
+    })
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      '/api/method/frappe.client.get?doctype=Task&name=T-1',
+      expect.objectContaining({ method: 'GET' }),
+    )
+  })
+
+  it('prepends the configured base URL, headers and credentials', async () => {
+    setConfig({
+      baseUrl: 'https://example.com/',
+      headers: { 'X-Frappe-Site-Name': 'site' },
+    })
+    const fetchMock = stubFetch(mockResponse({ message: 'pong' }))
+    await request({ url: '/api/method/ping' })
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://example.com/api/method/ping',
+      expect.objectContaining({
+        credentials: 'include',
+        headers: expect.objectContaining({
+          Accept: 'application/json',
+          'X-Frappe-Site-Name': 'site',
+        }),
+      }),
+    )
+  })
+
+  it('accepts a headers getter', async () => {
+    setConfig({ headers: () => ({ Authorization: 'token abc' }) })
+    const fetchMock = stubFetch(mockResponse({ message: 'ok' }))
+    await request({ url: 'myapp.api.ping' })
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      '/api/method/myapp.api.ping',
+      expect.objectContaining({
+        headers: expect.objectContaining({ Authorization: 'token abc' }),
+      }),
+    )
+  })
+
+  it('returns the whole body when it carries docs', async () => {
+    stubFetch(mockResponse({ docs: [{ name: 'T-1' }], message: 'ignored' }))
+    const result = await request({ url: 'run_doc_method' })
+    expect(result).toEqual({ docs: [{ name: 'T-1' }], message: 'ignored' })
+  })
+
+  it('returns the whole body for the login endpoint', async () => {
+    stubFetch(mockResponse({ message: 'Logged In', full_name: 'Ada' }))
+    const result = await request({ url: '/api/method/login', method: 'POST' })
+    expect(result).toEqual({ message: 'Logged In', full_name: 'Ada' })
+  })
+
+  it('rejects with a normalized RequestError on a non-2xx response', async () => {
+    stubFetch(
+      mockResponse(
+        {
+          exc_type: 'ValidationError',
+          _server_messages: JSON.stringify([
+            JSON.stringify({ message: 'Bad value' }),
+          ]),
+        },
+        { ok: false, status: 417, statusText: 'Expectation Failed' },
+      ),
+    )
+
+    const error = (await request({ url: 'x.y' }).catch(
+      (e) => e,
+    )) as RequestError
+    expect(error).toBeInstanceOf(RequestError)
+    expect(error.status).toBe(417)
+    expect(error.excType).toBe('ValidationError')
+    expect(error.messages).toEqual(['Bad value'])
+  })
+
+  it('falls back to Internal Server Error when the body has no message', async () => {
+    stubFetch(mockResponse({}, { ok: false, status: 500 }))
+    const error = (await request({ url: 'x.y' }).catch(
+      (e) => e,
+    )) as RequestError
+    expect(error.messages).toEqual(['Internal Server Error'])
+  })
+
+  it('throws when url is missing', async () => {
+    await expect(request({ url: '' })).rejects.toBeInstanceOf(RequestError)
+  })
+})
+
+describe('config', () => {
+  it('merges keys and resets', () => {
+    setConfig({ baseUrl: '/base' })
+    setConfig({ headers: { A: '1' } })
+    expect(getConfig()).toEqual({ baseUrl: '/base', headers: { A: '1' } })
+    resetConfig()
+    expect(getConfig()).toEqual({})
+  })
+})
+
+describe('normalizeError', () => {
+  it('coerces arbitrary values and preserves the name', () => {
+    expect(normalizeError('boom')).toBeInstanceOf(RequestError)
+
+    const abort = new Error('aborted')
+    abort.name = 'AbortError'
+    const normalized = normalizeError(abort)
+    expect(normalized).toBeInstanceOf(RequestError)
+    expect(isAbortError(normalized)).toBe(true)
+  })
+})

package/src/resource/client.ts

@@ -0,0 +1,307 @@
+/**
+ * The framework-neutral request client for the resource layer.
+ *
+ * A Solid port of frappe-ui's `frappeRequest` + `request` pair, reduced to what
+ * the signal-based resources need: a configurable base URL / headers, POST to
+ * `/api/method/<dotted.method>`, JSON in and out, and one error shape for every
+ * way a request can fail. It is pure — the only side effect is `fetch` — so the
+ * whole thing is testable by stubbing the global.
+ *
+ * Nothing here touches Solid. `resource.ts` wraps it with signals.
+ */
+
+/** Configuration merged by {@link setConfig}. Every field is optional. */
+export interface ClientConfig {
+  /** Base URL prepended to relative (`/`-rooted) request URLs. */
+  baseUrl?: string
+  /** Extra headers merged into every request. Static, or a getter. */
+  headers?: Record<string, string> | (() => Record<string, string>)
+  /**
+   * Credentials mode. Defaults to `same-origin`, or `include` when a
+   * `baseUrl` is configured (cookie-based cross-origin auth).
+   */
+  credentials?: RequestCredentials
+  /** Called with Frappe's `_server_messages` when a successful response carries them. */
+  onServerMessages?: (messages: string[]) => void
+  /** The fetch implementation. Defaults to the global `fetch`. */
+  fetch?: typeof fetch
+}
+
+const defaults: ClientConfig = {}
+
+/**
+ * Merge configuration. Keys are merged, not replaced, so calling it twice
+ * (`baseUrl`, then `headers`) keeps both. Use {@link resetConfig} in tests.
+ */
+export function setConfig(config: ClientConfig): void {
+  Object.assign(defaults, config)
+}
+
+/** A copy of the current configuration. */
+export function getConfig(): ClientConfig {
+  return { ...defaults }
+}
+
+/** Clear every configured value, back to the built-in defaults. */
+export function resetConfig(): void {
+  for (const key of Object.keys(defaults) as (keyof ClientConfig)[]) {
+    delete defaults[key]
+  }
+}
+
+/** Options for a single {@link request}. */
+export interface RequestOptions {
+  /** Absolute URL, `/api/method/…`, or a dotted method name (`frappe.client.get`). */
+  url: string
+  /** HTTP method. Defaults to `POST`, Frappe's convention for method calls. */
+  method?: string
+  /** Query params (GET) or JSON body (everything else). */
+  params?: Record<string, unknown>
+  /** Per-request headers, merged last. */
+  headers?: Record<string, string>
+  /** Abort signal for the fetch. */
+  signal?: AbortSignal
+  /** Overrides the configured credentials mode. */
+  credentials?: RequestCredentials
+}
+
+/** One field of Frappe's JSON error body. */
+interface FrappeResponseBody {
+  docs?: unknown
+  exc?: string
+  exc_type?: string
+  message?: unknown
+  _server_messages?: string
+  _error_message?: string
+}
+
+/** Options accepted by {@link RequestError}. */
+export interface RequestErrorOptions {
+  status?: number
+  response?: Response
+  excType?: string
+  exc?: string
+  messages?: string[]
+}
+
+/**
+ * What every request failure rejects with: transport errors, non-2xx
+ * responses, and an ok response whose body will not parse. Narrow by field
+ * (`error.status`, `error.messages`); `messages` is always a `string[]`.
+ */
+export class RequestError extends Error {
+  readonly status?: number
+  readonly response?: Response
+  readonly excType?: string
+  readonly exc?: string
+  readonly messages: string[]
+
+  constructor(message: string, options: RequestErrorOptions = {}) {
+    super(message)
+    this.name = 'RequestError'
+    this.status = options.status
+    this.response = options.response
+    this.excType = options.excType
+    this.exc = options.exc
+    this.messages = options.messages ?? []
+  }
+}
+
+/** True for a deliberate abort, which is not a resource error. */
+export function isAbortError(error: unknown): boolean {
+  return (
+    !!error &&
+    typeof error === 'object' &&
+    (error as { name?: unknown }).name === 'AbortError'
+  )
+}
+
+/**
+ * Coerce anything thrown by `fetch` (or the caller's `transform`) into a
+ * {@link RequestError}, preserving the original `name` so `AbortError` stays
+ * detectable.
+ */
+export function normalizeError(error: unknown): RequestError {
+  if (error instanceof RequestError) return error
+  const message = error instanceof Error ? error.message : String(error)
+  const normalized = new RequestError(message)
+  if (error instanceof Error && error.name) normalized.name = error.name
+  return normalized
+}
+
+function resolveUrl(rawUrl: string): string {
+  if (/^https?:\/\//i.test(rawUrl)) return rawUrl
+  const path = rawUrl.startsWith('/') ? rawUrl : `/api/method/${rawUrl}`
+  const { baseUrl } = defaults
+  if (baseUrl && path.startsWith('/')) {
+    return baseUrl.replace(/\/+$/, '') + path
+  }
+  return path
+}
+
+function resolveHeaders(options: RequestOptions): Record<string, string> {
+  const configHeaders = defaults.headers
+  const extra =
+    typeof configHeaders === 'function'
+      ? configHeaders()
+      : (configHeaders ?? {})
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    'Content-Type': 'application/json; charset=utf-8',
+    ...extra,
+    ...(options.headers ?? {}),
+  }
+  if (typeof window !== 'undefined' && window.csrf_token) {
+    if (window.csrf_token !== '{{ csrf_token }}') {
+      headers['X-Frappe-CSRF-Token'] = window.csrf_token
+    }
+  }
+  return headers
+}
+
+declare global {
+  interface Window {
+    csrf_token?: string
+  }
+}
+
+function appendQuery(url: string, params: Record<string, unknown>): string {
+  const search = new URLSearchParams()
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null) continue
+    search.append(
+      key,
+      typeof value === 'object' ? JSON.stringify(value) : String(value),
+    )
+  }
+  const query = search.toString()
+  return query ? `${url}?${query}` : url
+}
+
+function isLoginUrl(url: string): boolean {
+  const path = url.split(/[?#]/)[0]?.replace(/\/+$/, '') ?? ''
+  return path === '/api/method/login' || path.endsWith('/api/method/login')
+}
+
+function parseExc(exc: string | undefined): string | undefined {
+  if (!exc) return undefined
+  try {
+    const parsed = JSON.parse(exc) as unknown
+    if (Array.isArray(parsed) && parsed.length > 0) return String(parsed[0])
+    return exc
+  } catch {
+    return exc
+  }
+}
+
+function normalizeMessages(body: FrappeResponseBody): string[] {
+  let messages: string[] = []
+  if (body._server_messages) {
+    try {
+      const parsed = JSON.parse(body._server_messages) as unknown
+      if (Array.isArray(parsed)) messages = parsed.map(String)
+    } catch {
+      messages = []
+    }
+  }
+  if (body.message !== undefined)
+    messages = messages.concat(String(body.message))
+  messages = messages
+    .map((message) => {
+      try {
+        const parsed = JSON.parse(message) as { message?: string }
+        return parsed.message ?? message
+      } catch {
+        return message
+      }
+    })
+    .filter(Boolean)
+  if (messages.length === 0) {
+    messages = body._error_message
+      ? [body._error_message]
+      : ['Internal Server Error']
+  }
+  return messages
+}
+
+function reportServerMessages(body: FrappeResponseBody): void {
+  if (!body._server_messages) return
+  const handler = defaults.onServerMessages
+  if (!handler) return
+  try {
+    const parsed = JSON.parse(body._server_messages) as unknown
+    if (Array.isArray(parsed)) handler(parsed.map(String))
+  } catch {
+    // A malformed `_server_messages` is not worth failing an ok response over.
+  }
+}
+
+/**
+ * Fetch a Frappe method and return its `message`.
+ *
+ * `url` may be absolute, `/api/method/…`, or a bare dotted method name. GET
+ * params become the query string; every other method sends them as a JSON body.
+ * A body carrying `docs` (or the login endpoint) is returned whole; otherwise
+ * `message` is unwrapped. Failures reject with a {@link RequestError}.
+ */
+export async function request<TResponse = unknown>(
+  options: RequestOptions,
+): Promise<TResponse> {
+  if (!options.url) {
+    throw new RequestError('[request] options.url is required')
+  }
+  const method = (options.method ?? 'POST').toUpperCase()
+  const resolved = resolveUrl(options.url)
+  const headers = resolveHeaders(options)
+
+  let url = resolved
+  let body: string | undefined
+  if (options.params && method === 'GET') {
+    url = appendQuery(resolved, options.params)
+  } else if (options.params) {
+    body = JSON.stringify(options.params)
+  }
+
+  const credentials =
+    options.credentials ??
+    defaults.credentials ??
+    (defaults.baseUrl && resolved.startsWith(defaults.baseUrl)
+      ? 'include'
+      : undefined)
+
+  const fetchImpl = defaults.fetch ?? fetch
+  const response = await fetchImpl(url, {
+    method,
+    headers,
+    body,
+    signal: options.signal,
+    ...(credentials ? { credentials } : {}),
+  })
+
+  if (response.ok) {
+    const data = (await response.json()) as FrappeResponseBody
+    reportServerMessages(data)
+    if (data.docs !== undefined || isLoginUrl(url)) {
+      return data as TResponse
+    }
+    return data.message as TResponse
+  }
+
+  const text = await response.text()
+  let errorBody: FrappeResponseBody = {}
+  try {
+    errorBody = JSON.parse(text) as FrappeResponseBody
+  } catch {
+    // A non-JSON error body (login HTML, proxy error) still fails as a request.
+  }
+  const detail = [url, errorBody.exc_type, errorBody._error_message]
+    .filter(Boolean)
+    .join(' ')
+  throw new RequestError(detail || response.statusText || 'Request failed', {
+    status: response.status,
+    response,
+    excType: errorBody.exc_type,
+    exc: parseExc(errorBody.exc),
+    messages: normalizeMessages(errorBody),
+  })
+}

package/src/resource/connect-realtime.test.ts

@@ -0,0 +1,135 @@
+import { QueryClient } from '@tanstack/solid-query'
+import { createSignal } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import { connectRealtime } from './connect-realtime'
+import type { Realtime } from './realtime'
+
+/** A socket-shaped test double: `emit` stands in for a server push. */
+function fakeRealtime() {
+  const handlers = new Map<string, Set<(data: unknown) => void>>()
+  const [connected, setConnected] = createSignal(false)
+  const socket: Realtime = {
+    connected,
+    connect: () => setConnected(true),
+    on(event, listener) {
+      const set = handlers.get(event) ?? new Set()
+      set.add(listener)
+      handlers.set(event, set)
+      return () => set.delete(listener)
+    },
+    off(event, listener) {
+      handlers.get(event)?.delete(listener)
+    },
+    send: () => {},
+    close: () => setConnected(false),
+  }
+  return {
+    socket,
+    emit(event: string, data: unknown) {
+      for (const listener of handlers.get(event) ?? []) listener(data)
+    },
+  }
+}
+
+function makeClient() {
+  const client = new QueryClient({
+    defaultOptions: { queries: { retry: false, gcTime: Infinity } },
+  })
+  const invalidate = vi.spyOn(client, 'invalidateQueries')
+  return { client, invalidate }
+}
+
+describe('connectRealtime', () => {
+  it('invalidates the doctype prefix for list events', () => {
+    const { client, invalidate } = makeClient()
+    const { socket, emit } = fakeRealtime()
+    connectRealtime(client, { realtime: socket, doctype: 'Task' })
+
+    emit('list_update', { doctype: 'Task' })
+    expect(invalidate).toHaveBeenCalledWith({ queryKey: ['Task'] })
+  })
+
+  it('invalidates the exact key for doc events', () => {
+    const { client, invalidate } = makeClient()
+    const { socket, emit } = fakeRealtime()
+    connectRealtime(client, { realtime: socket, doctype: 'Task' })
+
+    emit('list_update', { doctype: 'Task', name: 'TASK-1' })
+    expect(invalidate).toHaveBeenCalledWith({
+      queryKey: ['Task', 'TASK-1'],
+      exact: true,
+    })
+  })
+
+  it('honours an explicit event type over the name heuristic', () => {
+    const { client, invalidate } = makeClient()
+    const { socket, emit } = fakeRealtime()
+    connectRealtime(client, { realtime: socket, doctype: 'Task' })
+
+    emit('list_update', { doctype: 'Task', name: 'TASK-1', type: 'list' })
+    expect(invalidate).toHaveBeenCalledWith({ queryKey: ['Task'] })
+  })
+
+  it('filters by doctype and reports the normalized event', () => {
+    const { client, invalidate } = makeClient()
+    const { socket, emit } = fakeRealtime()
+    const onEvent = vi.fn()
+    connectRealtime(client, { realtime: socket, doctype: 'Task' }, { onEvent })
+
+    emit('list_update', { doctype: 'Invoice', name: 'INV-1' })
+    expect(invalidate).not.toHaveBeenCalled()
+    expect(onEvent).not.toHaveBeenCalled()
+
+    emit('list_update', { doctype: 'Task', name: 'TASK-1' })
+    expect(onEvent).toHaveBeenCalledWith({
+      type: 'doc',
+      doctype: 'Task',
+      name: 'TASK-1',
+    })
+  })
+
+  it('subscribes to the event names the app declares', () => {
+    const { client, invalidate } = makeClient()
+    const { socket, emit } = fakeRealtime()
+    connectRealtime(client, {
+      realtime: socket,
+      doctype: ['Task', 'Invoice'],
+      events: ['doc_update'],
+    })
+
+    emit('list_update', { doctype: 'Task' })
+    expect(invalidate).not.toHaveBeenCalled()
+    emit('doc_update', { doctype: 'Invoice', name: 'INV-2' })
+    expect(invalidate).toHaveBeenCalledWith({
+      queryKey: ['Invoice', 'INV-2'],
+      exact: true,
+    })
+  })
+
+  it('ignores payloads that are not change events', () => {
+    const { client, invalidate } = makeClient()
+    const { socket, emit } = fakeRealtime()
+    const onEvent = vi.fn()
+    connectRealtime(client, { realtime: socket, doctype: 'Task' }, { onEvent })
+
+    emit('list_update', 'ping')
+    emit('list_update', { name: 'no-doctype' })
+    emit('list_update', null)
+    expect(invalidate).not.toHaveBeenCalled()
+    expect(onEvent).not.toHaveBeenCalled()
+  })
+
+  it('stops listening on close, leaving the socket itself alone', () => {
+    const { client, invalidate } = makeClient()
+    const { socket, emit } = fakeRealtime()
+    const connection = connectRealtime(client, {
+      realtime: socket,
+      doctype: 'Task',
+    })
+
+    connection.close()
+    emit('list_update', { doctype: 'Task' })
+    expect(invalidate).not.toHaveBeenCalled()
+    expect(socket.connected()).toBe(false)
+  })
+})