@talelk/newui-data 0.0.0-stage → 1.1.0

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

package/src/resource/useDoctype.ts

@@ -0,0 +1,128 @@
+import { type Accessor, createSignal } from 'solid-js'
+import type { RequestError } from './client'
+import { createResource, type Resource, type ResourceFetcher } from './resource'
+
+/** A single doctype-level write action. */
+export interface DoctypeAction<TResult = unknown, TInput = unknown> {
+  data: Accessor<TResult | null>
+  loading: Accessor<boolean>
+  error: Accessor<RequestError | null>
+  submit: (input: TInput) => Promise<TResult | null>
+  reset: () => void
+}
+
+/** Options for {@link useDoctype}. */
+export interface UseDoctypeOptions {
+  fetcher?: ResourceFetcher
+}
+
+/** Params for a document method. */
+export interface RunDocMethodInput {
+  name: string
+  method: string
+  params?: Record<string, unknown>
+}
+
+/** Params for a doctype-level method. */
+export interface RunMethodInput {
+  method: string
+  params?: Record<string, unknown>
+}
+
+/** The write actions {@link useDoctype} returns. */
+export interface UseDoctypeReturn<TDoc = Record<string, unknown>> {
+  insert: DoctypeAction<TDoc, Partial<TDoc>>
+  delete: DoctypeAction<unknown, string>
+  setValue: DoctypeAction<TDoc, Record<string, unknown> & { name: string }>
+  runDocMethod: DoctypeAction<unknown, RunDocMethodInput>
+  runMethod: DoctypeAction<unknown, RunMethodInput>
+}
+
+const INSERT_URL = 'frappe.client.insert'
+const SET_VALUE_URL = 'frappe.client.set_value'
+const DELETE_URL = 'frappe.client.delete'
+const RUN_DOC_METHOD_URL = 'run_doc_method'
+
+/**
+ * The signal-based replacement for frappe-ui's `useDoctype`: the doctype-level
+ * write actions (`insert`, `delete`, `setValue`, `runDocMethod`, `runMethod`),
+ * each an inert resource that fires on `submit`.
+ */
+export function useDoctype<TDoc = Record<string, unknown>>(
+  doctype: string,
+  options: UseDoctypeOptions = {},
+): UseDoctypeReturn<TDoc> {
+  const { fetcher } = options
+
+  const insertResource = createResource<TDoc, Partial<TDoc>>({
+    url: INSERT_URL,
+    method: 'POST',
+    makeParams: (input) => ({ doc: { doctype, ...(input as Partial<TDoc>) } }),
+    fetcher,
+  })
+
+  const deleteResource = createResource<unknown, string>({
+    url: DELETE_URL,
+    method: 'POST',
+    makeParams: (input) => ({ doctype, name: input }),
+    fetcher,
+  })
+
+  const setValueResource = createResource<
+    TDoc,
+    Record<string, unknown> & { name: string }
+  >({
+    url: SET_VALUE_URL,
+    method: 'POST',
+    makeParams: ({ name, ...values }) => ({ doctype, name, fieldname: values }),
+    fetcher,
+  })
+
+  const runDocMethodResource = createResource<unknown, RunDocMethodInput>({
+    url: RUN_DOC_METHOD_URL,
+    method: 'POST',
+    makeParams: ({ name, method, params }) => ({
+      dt: doctype,
+      dn: name,
+      method,
+      args: params ?? {},
+    }),
+    fetcher,
+  })
+
+  // `runMethod` POSTs to the method name itself, which is only known per call.
+  // `makeParams` runs before the URL is resolved (see `createResource`), so the
+  // signal it writes is already visible when the URL is read.
+  const [methodUrl, setMethodUrl] = createSignal('')
+  const runMethodResource = createResource<unknown, RunMethodInput>({
+    url: () => methodUrl(),
+    method: 'POST',
+    makeParams: ({ method, params }) => {
+      setMethodUrl(() => method)
+      return params ?? {}
+    },
+    fetcher,
+  })
+
+  function toAction<TResult, TInput>(
+    resource: Resource<TResult, TInput>,
+  ): DoctypeAction<TResult, TInput> {
+    return {
+      data: resource.data,
+      loading: resource.loading,
+      error: resource.error,
+      submit: (input: TInput) => resource.submit(input),
+      reset: resource.reset,
+    }
+  }
+
+  return {
+    insert: toAction<TDoc, Partial<TDoc>>(insertResource),
+    delete: toAction<unknown, string>(deleteResource),
+    setValue: toAction<TDoc, Record<string, unknown> & { name: string }>(
+      setValueResource,
+    ),
+    runDocMethod: toAction<unknown, RunDocMethodInput>(runDocMethodResource),
+    runMethod: toAction<unknown, RunMethodInput>(runMethodResource),
+  }
+}

package/src/resource/useList.test.ts

@@ -0,0 +1,32 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { useList } from './useList'
+
+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('useList', () => {
+  it('delegates to the list resource', async () => {
+    const mock = vi.fn(async () => mockResponse({ message: [{ name: 'T-1' }] }))
+    vi.stubGlobal('fetch', mock)
+
+    const list = useList<{ name: string }>({ doctype: 'Task' })
+    const rows = await list.reload()
+
+    expect(rows).toEqual([{ name: 'T-1' }])
+    expect(mock).toHaveBeenCalledWith(
+      '/api/method/frappe.client.get_list',
+      expect.objectContaining({ method: 'POST' }),
+    )
+  })
+})

package/src/resource/useList.ts

@@ -0,0 +1,22 @@
+import {
+  createListResource,
+  type ListResource,
+  type ListResourceOptions,
+} from './list'
+
+/** Options for {@link useList}. */
+export type UseListOptions<TRow = Record<string, unknown>> =
+  ListResourceOptions<TRow>
+
+/** The signal-based surface {@link useList} returns. */
+export type UseListReturn<TRow = Record<string, unknown>> = ListResource<TRow>
+
+/**
+ * A thin composable over {@link createListResource}: a paginated, filterable
+ * list read through signals.
+ */
+export function useList<TRow = Record<string, unknown>>(
+  options: ListResourceOptions<TRow>,
+): ListResource<TRow> {
+  return createListResource(options)
+}

package/src/resource/useNewDoc.test.ts

@@ -0,0 +1,67 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { useNewDoc } from './useNewDoc'
+
+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('useNewDoc', () => {
+  it('builds a doc and inserts it', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: { name: 'T-9' } }))
+    const newDoc = useNewDoc<{ name: string; subject: string }>('Task', {
+      subject: 'Hi',
+    })
+
+    expect(newDoc.doc()).toEqual({ subject: 'Hi' })
+    newDoc.setDoc((doc) => ({ ...doc, subject: 'Bye' }))
+
+    const created = await newDoc.submit()
+
+    expect(created).toEqual({ name: 'T-9' })
+    expect(urlAt(fetchMock)).toBe('/api/method/frappe.client.insert')
+    expect(bodyAt(fetchMock)).toEqual({
+      doc: { doctype: 'Task', subject: 'Bye' },
+    })
+  })
+
+  it('reset clears the draft', async () => {
+    stubFetch(mockResponse({ message: { name: 'T-9' } }))
+    const newDoc = useNewDoc<{ subject: string }>('Task', { subject: 'Hi' })
+
+    newDoc.setDoc({ subject: 'Bye' })
+    newDoc.reset()
+
+    expect(newDoc.doc()).toEqual({ subject: 'Hi' })
+    expect(newDoc.data()).toBe(null)
+  })
+})

package/src/resource/useNewDoc.ts

@@ -0,0 +1,78 @@
+import { type Accessor, createSignal } from 'solid-js'
+import type { RequestError } from './client'
+import { createResource, type ResourceFetcher } from './resource'
+
+/** Options for {@link useNewDoc}. */
+export interface UseNewDocOptions {
+  onSuccess?: (doc: Record<string, unknown>) => void
+  onError?: (error: RequestError) => void
+  fetcher?: ResourceFetcher
+}
+
+/** The signal-based surface {@link useNewDoc} returns. */
+export interface UseNewDocReturn<TDoc = Record<string, unknown>> {
+  /** The document being built, edited through {@link UseNewDocReturn.setDoc}. */
+  doc: Accessor<Partial<TDoc>>
+  setDoc: (
+    values: Partial<TDoc> | ((current: Partial<TDoc>) => Partial<TDoc>),
+  ) => void
+  /** The created document, once `submit` resolves. */
+  data: Accessor<TDoc | null>
+  loading: Accessor<boolean>
+  error: Accessor<RequestError | null>
+  /** Insert the document (`frappe.client.insert`). */
+  submit: () => Promise<TDoc | null>
+  reset: () => void
+}
+
+const INSERT_URL = 'frappe.client.insert'
+
+/**
+ * The signal-based replacement for frappe-ui's `useNewDoc`: build a document
+ * locally, then insert it.
+ */
+export function useNewDoc<TDoc extends object = Record<string, unknown>>(
+  doctype: string,
+  initialValues: Partial<TDoc> = {},
+  options: UseNewDocOptions = {},
+): UseNewDocReturn<TDoc> {
+  const [doc, setDocSignal] = createSignal<Partial<TDoc>>({ ...initialValues })
+
+  const resource = createResource<TDoc, Record<string, unknown>>({
+    url: INSERT_URL,
+    method: 'POST',
+    makeParams: (input) => ({ doc: { doctype, ...input } }),
+    fetcher: options.fetcher,
+    onSuccess: (data) => options.onSuccess?.(data as Record<string, unknown>),
+    onError: options.onError,
+  })
+
+  function setDoc(
+    next: Partial<TDoc> | ((current: Partial<TDoc>) => Partial<TDoc>),
+  ): void {
+    if (typeof next === 'function') {
+      setDocSignal((current) => next(current))
+      return
+    }
+    setDocSignal(() => next)
+  }
+
+  function submit(): Promise<TDoc | null> {
+    return resource.submit(doc() as Record<string, unknown>)
+  }
+
+  function reset(): void {
+    setDocSignal(() => ({ ...initialValues }))
+    resource.reset()
+  }
+
+  return {
+    doc,
+    setDoc,
+    data: resource.data,
+    loading: resource.loading,
+    error: resource.error,
+    submit,
+    reset,
+  }
+}

package/src/select.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest'
+import { first, optionsOf } from './select'
+
+describe('select', () => {
+  it('mirrors values into options and unwraps with a fallback', () => {
+    expect(optionsOf(['Name', 'Size'])).toEqual([
+      { label: 'Name', value: 'Name' },
+      { label: 'Size', value: 'Size' },
+    ])
+    expect(first(['Size'], 'Name')).toBe('Size')
+    expect(first([], 'Name')).toBe('Name')
+  })
+})

package/src/select.ts

@@ -0,0 +1,19 @@
+/**
+ * Select plumbing: a string list to options, and the chosen value back.
+ *
+ * Every page turned a list into `{ label, value }` inline and unwrapped the
+ * single-value array the same way. Two spellings, once.
+ */
+
+export interface SelectOption {
+  label: string
+  value: string
+}
+
+/** `['Name', 'Size']` → `[{ label: 'Name', value: 'Name' }, …]`. */
+export const optionsOf = (values: readonly string[]): SelectOption[] =>
+  values.map((value) => ({ label: value, value }))
+
+/** The chosen value, or `fallback` when the selection is empty. */
+export const first = (value: string[], fallback: string): string =>
+  value[0] ?? fallback