@talelk/newui-data 0.0.0-stage → 1.1.0

package/src/resource/connect-realtime.ts

@@ -0,0 +1,121 @@
+import type { QueryClient } from '@tanstack/solid-query'
+import type { Realtime } from './realtime'
+
+/**
+ * The realtime-to-cache bridge.
+ *
+ * `connectRealtime` subscribes to a {@link createRealtime} socket and
+ * invalidates the matching TanStack Query keys: a **list** event invalidates
+ * the `[doctype]` prefix — every query that reads that doctype — and a **doc**
+ * event invalidates exactly `[doctype, name]`. It is a function, not a hook:
+ * the cache is the integration point, and the socket factory finally has a
+ * consumer.
+ */
+
+/** A normalized change: `list` moves a whole doctype, `doc` one record. */
+export interface RealtimeEvent {
+  type: 'list' | 'doc'
+  doctype: string
+  name?: string
+}
+
+/** What the cache listens to. */
+export interface RealtimeResource {
+  /** The socket returned by {@link createRealtime}. */
+  realtime: Realtime
+  /** Doctype(s) whose changes should invalidate the cache. */
+  doctype: string | readonly string[]
+  /**
+   * Event names carrying `{ doctype, name }` payloads. Defaults to
+   * `['list_update']` — the event Frappe emits for every change.
+   */
+  events?: readonly string[]
+}
+
+/** Options for {@link connectRealtime}. */
+export interface ConnectRealtimeOptions {
+  /** Called for every event that passes the `doctype` filter. */
+  onEvent?: (event: RealtimeEvent) => void
+}
+
+/** The handle {@link connectRealtime} returns. */
+export interface RealtimeConnection {
+  /** Unsubscribe from the socket. The socket itself stays open — the app
+   * owns its lifecycle, and other consumers may still be on it. */
+  close(): void
+}
+
+/**
+ * Normalize one socket payload. A payload with a `type` wins; otherwise a
+ * `name` means one document changed and its absence means the list did.
+ */
+function normalizeEvent(data: unknown): RealtimeEvent | undefined {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    return undefined
+  }
+  const payload = data as Record<string, unknown>
+  if (typeof payload['doctype'] !== 'string') return undefined
+  const name = typeof payload['name'] === 'string' ? payload['name'] : undefined
+  let type: 'list' | 'doc'
+  if (payload['type'] === 'list' || payload['type'] === 'doc') {
+    type = payload['type']
+  } else {
+    type = name ? 'doc' : 'list'
+  }
+  return { type, doctype: payload['doctype'], ...(name ? { name } : {}) }
+}
+
+/**
+ * Bridge a socket to a query cache.
+ *
+ * ```ts
+ * const socket = createRealtime({ url: realtimeUrl })
+ * const connection = connectRealtime(queryClient, {
+ *   realtime: socket,
+ *   doctype: 'Task',
+ *   onEvent: (event) => console.debug(event),
+ * })
+ * connection.close() // stop listening; the socket stays open
+ * ```
+ */
+export function connectRealtime(
+  queryClient: QueryClient,
+  resource: RealtimeResource,
+  options: ConnectRealtimeOptions = {},
+): RealtimeConnection {
+  const wanted = new Set(
+    typeof resource.doctype === 'string'
+      ? [resource.doctype]
+      : resource.doctype,
+  )
+  const events = resource.events ?? ['list_update']
+  const unsubscribes: (() => void)[] = []
+
+  for (const event of events) {
+    unsubscribes.push(
+      resource.realtime.on(event, (data) => {
+        const normalized = normalizeEvent(data)
+        if (!normalized) return
+        if (wanted.size > 0 && !wanted.has(normalized.doctype)) return
+        if (normalized.type === 'doc' && normalized.name) {
+          void queryClient.invalidateQueries({
+            queryKey: [normalized.doctype, normalized.name],
+            exact: true,
+          })
+        } else {
+          void queryClient.invalidateQueries({
+            queryKey: [normalized.doctype],
+          })
+        }
+        options.onEvent?.(normalized)
+      }),
+    )
+  }
+
+  return {
+    close() {
+      for (const unsubscribe of unsubscribes) unsubscribe()
+      unsubscribes.length = 0
+    },
+  }
+}

package/src/resource/document.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createDocumentResource } from './document'
+
+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('createDocumentResource', () => {
+  it('loads the document and tracks dirty state', async () => {
+    stubFetch(mockResponse({ message: { name: 'T-1', subject: 'Hi' } }))
+    const resource = createDocumentResource<{ name: string; subject: string }>({
+      doctype: 'Task',
+      name: 'T-1',
+      auto: false,
+    })
+
+    await resource.reload()
+    expect(resource.doc()).toEqual({ name: 'T-1', subject: 'Hi' })
+    expect(resource.originalDoc()).toEqual({ name: 'T-1', subject: 'Hi' })
+    expect(resource.isDirty()).toBe(false)
+
+    resource.setDoc((doc) => ({
+      ...(doc ?? { name: '', subject: '' }),
+      subject: 'Bye',
+    }))
+    expect(resource.doc()).toEqual({ name: 'T-1', subject: 'Bye' })
+    expect(resource.isDirty()).toBe(true)
+  })
+
+  it('save posts only the changed fields', async () => {
+    const fetchMock = stubFetch(
+      mockResponse({ message: { name: 'T-1', subject: 'Hi', status: 'Open' } }),
+      mockResponse({
+        message: { name: 'T-1', subject: 'Bye', status: 'Open' },
+      }),
+    )
+    const resource = createDocumentResource({
+      doctype: 'Task',
+      name: 'T-1',
+      auto: false,
+    })
+
+    await resource.reload()
+    resource.setDoc((doc) => ({
+      ...(doc as Record<string, unknown>),
+      subject: 'Bye',
+    }))
+    await resource.save()
+
+    expect(urlAt(fetchMock, 1)).toBe('/api/method/frappe.client.set_value')
+    expect(bodyAt(fetchMock, 1)).toEqual({
+      doctype: 'Task',
+      name: 'T-1',
+      fieldname: { subject: 'Bye' },
+    })
+    expect(resource.isDirty()).toBe(false)
+  })
+
+  it('save with no changes does not hit the network', async () => {
+    const fetchMock = stubFetch(mockResponse({ message: { name: 'T-1' } }))
+    const resource = createDocumentResource({
+      doctype: 'Task',
+      name: 'T-1',
+      auto: false,
+    })
+
+    await resource.reload()
+    expect(fetchMock.mock.calls.length).toBe(1)
+
+    await resource.save()
+    expect(fetchMock.mock.calls.length).toBe(1)
+  })
+
+  it('setValue posts explicit values', async () => {
+    const fetchMock = stubFetch(
+      mockResponse({ message: { name: 'T-1' } }),
+      mockResponse({ message: { name: 'T-1', subject: 'X' } }),
+    )
+    const resource = createDocumentResource({
+      doctype: 'Task',
+      name: 'T-1',
+      auto: false,
+    })
+
+    await resource.reload()
+    await resource.setValue({ subject: 'X' })
+
+    expect(bodyAt(fetchMock, 1)).toEqual({
+      doctype: 'Task',
+      name: 'T-1',
+      fieldname: { subject: 'X' },
+    })
+    expect(resource.doc()).toEqual({ name: 'T-1', subject: 'X' })
+  })
+
+  it('delete posts and clears the document', async () => {
+    const fetchMock = stubFetch(
+      mockResponse({ message: { name: 'T-1' } }),
+      mockResponse({ message: 'ok' }),
+    )
+    const resource = createDocumentResource({
+      doctype: 'Task',
+      name: 'T-1',
+      auto: false,
+    })
+
+    await resource.reload()
+    await resource.delete()
+
+    expect(urlAt(fetchMock, 1)).toBe('/api/method/frappe.client.delete')
+    expect(bodyAt(fetchMock, 1)).toEqual({ doctype: 'Task', name: 'T-1' })
+    expect(resource.doc()).toBe(null)
+  })
+
+  it('fetches on creation by default', async () => {
+    stubFetch(mockResponse({ message: { name: 'T-1' } }))
+    const resource = createDocumentResource({ doctype: 'Task', name: 'T-1' })
+
+    await vi.waitFor(() => expect(resource.doc()).toEqual({ name: 'T-1' }))
+  })
+})

package/src/resource/document.ts

@@ -0,0 +1,198 @@
+import { type Accessor, createSignal } from 'solid-js'
+import type { RequestError } from './client'
+import { createResource, type Resource, type ResourceFetcher } from './resource'
+
+/** Per-operation overrides for a document resource. */
+export interface DocumentOperationOptions<TResult> {
+  /** Overrides the default endpoint. */
+  url?: string
+  onSuccess?: (result: TResult) => void
+  onError?: (error: RequestError) => void
+}
+
+/** Options for {@link createDocumentResource}. */
+export interface DocumentResourceOptions<TDoc = Record<string, unknown>> {
+  doctype: string
+  /** Document name, or an accessor for a reactive name. */
+  name: string | (() => string)
+  /** Fetch on creation. Defaults to `true`. */
+  auto?: boolean
+  /** Overrides the default get endpoint (`frappe.client.get`). */
+  url?: string
+  /** Map the raw document. */
+  transform?: (doc: TDoc) => TDoc
+  onSuccess?: (doc: TDoc) => void
+  onError?: (error: RequestError) => void
+  setValue?: DocumentOperationOptions<TDoc>
+  delete?: DocumentOperationOptions<unknown>
+  fetcher?: ResourceFetcher
+}
+
+/** A single-document resource with local edits and dirty tracking. */
+export interface DocumentResource<TDoc = Record<string, unknown>> {
+  doctype: string
+  name: Accessor<string>
+  doc: Accessor<TDoc | null>
+  /** The last saved/loaded copy, for dirty comparison. */
+  originalDoc: Accessor<TDoc | null>
+  isDirty: Accessor<boolean>
+  loading: Accessor<boolean>
+  error: Accessor<RequestError | null>
+  fetched: Accessor<boolean>
+  /** The underlying GET resource. */
+  get: Resource<TDoc>
+  /** POST the changed fields to `frappe.client.set_value`. */
+  save: () => Promise<TDoc | null>
+  /** POST explicit `fieldname` values. */
+  setValue: (values: Record<string, unknown>) => Promise<TDoc | null>
+  /** POST to `frappe.client.delete` and clear the doc. */
+  delete: () => Promise<unknown>
+  /** Refetch the document. */
+  reload: () => Promise<TDoc | null>
+  /** Edit the document locally. */
+  setDoc: (doc: TDoc | ((current: TDoc | null) => TDoc)) => void
+}
+
+const GET_URL = 'frappe.client.get'
+const SET_VALUE_URL = 'frappe.client.set_value'
+const DELETE_URL = 'frappe.client.delete'
+
+function cloneDoc<TDoc>(doc: TDoc | null): TDoc | null {
+  if (doc === null) return null
+  return JSON.parse(JSON.stringify(doc)) as TDoc
+}
+
+/**
+ * The signal-based replacement for frappe-ui's `createDocumentResource`.
+ *
+ * `doc` is a local signal; `setDoc` edits it, `isDirty` compares it to
+ * `originalDoc`, and `save` sends only the changed fields (skipping the
+ * network entirely when nothing changed). `setValue`/`delete` write through.
+ */
+export function createDocumentResource<TDoc = Record<string, unknown>>(
+  options: DocumentResourceOptions<TDoc>,
+): DocumentResource<TDoc> {
+  const name = (): string =>
+    typeof options.name === 'function' ? options.name() : options.name
+
+  const [doc, setDocSignal] = createSignal<TDoc | null>(null)
+  const [originalDoc, setOriginalDoc] = createSignal<TDoc | null>(null)
+
+  const transform = options.transform
+  const mapDoc = transform
+    ? (data: unknown) => transform(data as TDoc)
+    : undefined
+
+  const get = createResource<TDoc>({
+    url: options.url ?? GET_URL,
+    method: 'GET',
+    params: () => ({ doctype: options.doctype, name: name() }),
+    transform: mapDoc,
+    fetcher: options.fetcher,
+    onSuccess: (data) => {
+      setDocSignal(() => data)
+      setOriginalDoc(() => cloneDoc(data))
+      options.onSuccess?.(data)
+    },
+    onError: (error) => {
+      setDocSignal(() => null)
+      setOriginalDoc(() => null)
+      options.onError?.(error)
+    },
+  })
+
+  const setValueResource = createResource<TDoc, Record<string, unknown>>({
+    url: options.setValue?.url ?? SET_VALUE_URL,
+    method: 'POST',
+    makeParams: (input) => ({
+      doctype: options.doctype,
+      name: name(),
+      fieldname: input,
+    }),
+    transform: mapDoc,
+    fetcher: options.fetcher,
+    onSuccess: (data) => {
+      setDocSignal(() => data)
+      setOriginalDoc(() => cloneDoc(data))
+      options.setValue?.onSuccess?.(data)
+    },
+    onError: (error) => {
+      // Roll the local edit back to the last saved copy.
+      setDocSignal(() => originalDoc())
+      options.setValue?.onError?.(error)
+    },
+  })
+
+  const deleteResource = createResource<unknown>({
+    url: options.delete?.url ?? DELETE_URL,
+    method: 'POST',
+    params: () => ({ doctype: options.doctype, name: name() }),
+    fetcher: options.fetcher,
+    onSuccess: (data) => {
+      setDocSignal(() => null)
+      setOriginalDoc(() => null)
+      options.delete?.onSuccess?.(data)
+    },
+    onError: (error) => options.delete?.onError?.(error),
+  })
+
+  const isDirty = (): boolean =>
+    JSON.stringify(doc() ?? null) !== JSON.stringify(originalDoc() ?? null)
+
+  function changedFields(): Record<string, unknown> {
+    const current = (cloneDoc(doc()) ?? {}) as Record<string, unknown>
+    const original = (originalDoc() ?? {}) as Record<string, unknown>
+    const values: Record<string, unknown> = {}
+    for (const key in current) {
+      if (JSON.stringify(current[key]) !== JSON.stringify(original[key])) {
+        values[key] = current[key]
+      }
+    }
+    // Identity/meta fields are never writable through `set_value`.
+    delete values['doctype']
+    delete values['name']
+    return values
+  }
+
+  function setValue(values: Record<string, unknown>): Promise<TDoc | null> {
+    return setValueResource.submit(values)
+  }
+
+  function save(): Promise<TDoc | null> {
+    const values = changedFields()
+    if (Object.keys(values).length === 0) return Promise.resolve(doc())
+    return setValue(values)
+  }
+
+  function setDoc(next: TDoc | ((current: TDoc | null) => TDoc)): void {
+    if (typeof next === 'function') {
+      const updater = next as (current: TDoc | null) => TDoc
+      setDocSignal(() => updater(doc()))
+      return
+    }
+    setDocSignal(() => next)
+  }
+
+  function reload(): Promise<TDoc | null> {
+    return get.reload()
+  }
+
+  if (options.auto !== false) void reload()
+
+  return {
+    doctype: options.doctype,
+    name,
+    doc,
+    originalDoc,
+    isDirty,
+    loading: get.loading,
+    error: get.error,
+    fetched: get.fetched,
+    get,
+    save,
+    setValue,
+    delete: () => deleteResource.submit(),
+    reload,
+    setDoc,
+  }
+}

package/src/resource/idb.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from 'vitest'
+import { createIdbStore } from './idb'
+
+/**
+ * jsdom ships no IndexedDB, so the native code path is driven by a minimal
+ * in-memory `IDBFactory` implementing exactly the subset `createIdbStore`
+ * uses: open + upgrade, one object store, and get/put/delete/getAllKeys/clear.
+ * Requests settle on a microtask, as the real API does, which is why the store
+ * must attach its handlers after the request is created.
+ */
+
+interface FakeRequest {
+  result: unknown
+  error: DOMException | Error | null
+  onsuccess: ((event: Event) => void) | null
+  onerror: ((event: Event) => void) | null
+  onupgradeneeded: ((event: Event) => void) | null
+}
+
+function makeRequest(work: () => unknown): FakeRequest {
+  const request: FakeRequest = {
+    result: undefined,
+    error: null,
+    onsuccess: null,
+    onerror: null,
+    onupgradeneeded: null,
+  }
+  queueMicrotask(() => {
+    try {
+      request.result = work()
+      request.onsuccess?.(new Event('success'))
+    } catch (error) {
+      request.error = error as Error
+      request.onerror?.(new Event('error'))
+    }
+  })
+  return request
+}
+
+function makeFactory(): { factory: IDBFactory; opens: () => number } {
+  const data = new Map<IDBValidKey, unknown>()
+  const stores = new Set<string>()
+  let opens = 0
+
+  const objectStore = {
+    get: (key: IDBValidKey) => makeRequest(() => data.get(key)),
+    put: (value: unknown, key: IDBValidKey) =>
+      makeRequest(() => {
+        data.set(key, value)
+        return key
+      }),
+    delete: (key: IDBValidKey) =>
+      makeRequest(() => {
+        data.delete(key)
+        return undefined
+      }),
+    getAllKeys: () => makeRequest(() => [...data.keys()]),
+    clear: () =>
+      makeRequest(() => {
+        data.clear()
+        return undefined
+      }),
+  }
+
+  const db = {
+    objectStoreNames: { contains: (name: string) => stores.has(name) },
+    createObjectStore: (name: string) => {
+      stores.add(name)
+      return {}
+    },
+    transaction: () => ({ objectStore: () => objectStore }),
+    close: () => {},
+  }
+
+  const factory = {
+    open: () => {
+      opens += 1
+      const request: FakeRequest = {
+        result: db,
+        error: null,
+        onsuccess: null,
+        onerror: null,
+        onupgradeneeded: null,
+      }
+      queueMicrotask(() => {
+        request.onupgradeneeded?.(new Event('upgradeneeded'))
+        request.onsuccess?.(new Event('success'))
+      })
+      return request as unknown as IDBOpenDBRequest
+    },
+  }
+
+  return { factory: factory as unknown as IDBFactory, opens: () => opens }
+}
+
+describe('createIdbStore', () => {
+  it('stores and reads structured-clone values through IndexedDB', async () => {
+    const { factory } = makeFactory()
+    const store = createIdbStore({ factory })
+
+    expect(store.persistent).toBe(true)
+    await store.set('doc', { name: 'T-1', tags: ['a', 'b'] })
+    expect(await store.get('doc')).toEqual({ name: 'T-1', tags: ['a', 'b'] })
+    expect(await store.get('missing')).toBe(null)
+  })
+
+  it('lists, deletes and clears keys', async () => {
+    const { factory } = makeFactory()
+    const store = createIdbStore({ factory })
+
+    await store.set('a', 1)
+    await store.set('b', 2)
+    expect((await store.keys()).sort()).toEqual(['a', 'b'])
+
+    await store.delete('a')
+    expect(await store.keys()).toEqual(['b'])
+
+    await store.clear()
+    expect(await store.keys()).toEqual([])
+  })
+
+  it('opens the database once and reuses it', async () => {
+    const { factory, opens } = makeFactory()
+    const store = createIdbStore({ factory })
+
+    await store.set('a', 1)
+    await store.get('a')
+    await store.set('b', 2)
+    expect(opens()).toBe(1)
+  })
+
+  it('falls back to memory when IndexedDB is unavailable', async () => {
+    const store = createIdbStore({ factory: null })
+
+    expect(store.persistent).toBe(false)
+    await store.set('k', { v: 1 })
+    expect(await store.get('k')).toEqual({ v: 1 })
+    expect(await store.keys()).toEqual(['k'])
+    await store.delete('k')
+    expect(await store.get('k')).toBe(null)
+    await store.clear()
+    expect(await store.keys()).toEqual([])
+  })
+
+  it('reports non-persistence when there is no global indexedDB', () => {
+    // jsdom does not implement IndexedDB, so the default is the memory store.
+    const store = createIdbStore()
+    expect(store.persistent).toBe(false)
+  })
+
+  it('rejects when the database fails to open', async () => {
+    const failing = {
+      open: () => {
+        const request: FakeRequest = {
+          result: undefined,
+          error: new Error('permission denied'),
+          onsuccess: null,
+          onerror: null,
+          onupgradeneeded: null,
+        }
+        queueMicrotask(() => request.onerror?.(new Event('error')))
+        return request
+      },
+    } as unknown as IDBFactory
+    const store = createIdbStore({ factory: failing })
+
+    await expect(store.get('x')).rejects.toThrow('permission denied')
+  })
+})