@talelk/newui-data 1.0.0 → 1.1.0

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

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/index.ts

@@ -21,6 +21,13 @@ export {
   resetConfig,
   setConfig,
 } from './client'
+export type {
+  ConnectRealtimeOptions,
+  RealtimeConnection,
+  RealtimeEvent,
+  RealtimeResource,
+} from './connect-realtime'
+export { connectRealtime } from './connect-realtime'
 export type {
   DocumentOperationOptions,
   DocumentResource,

package/src/table-persist.test.ts

@@ -0,0 +1,258 @@
+import { createRoot } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import type { ConfigStorage } from './config-store'
+import {
+  createTablePersist,
+  type TablePersist,
+  type TablePersistOptions,
+} from './table-persist'
+import type { UrlStateAdapter } from './url-state'
+
+/** A Map-backed storage that records what was written. */
+function memoryStorage(): ConfigStorage & { map: Map<string, string> } {
+  const map = new Map<string, string>()
+  return {
+    map,
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => void map.set(key, value),
+    removeItem: (key) => void map.delete(key),
+    keys: () => [...map.keys()],
+  }
+}
+
+function adapter(
+  search = '',
+): UrlStateAdapter & { last: () => URLSearchParams } {
+  let last = new URLSearchParams(search)
+  return {
+    search: () => search,
+    replace: vi.fn((params: URLSearchParams) => {
+      last = params
+    }),
+    last: () => last,
+  }
+}
+
+async function flushMicrotasks(): Promise<void> {
+  await Promise.resolve()
+  await Promise.resolve()
+}
+
+function setup(
+  options: Omit<TablePersistOptions, 'id'> & { id?: string } = {},
+) {
+  let dispose!: () => void
+  let persist!: TablePersist
+  createRoot((d) => {
+    dispose = d
+    persist = createTablePersist({ id: 'orders', ...options })
+  })
+  return { persist, dispose }
+}
+
+const layout = {
+  visibility: { date: true, amount: false },
+  order: ['date', 'amount'],
+  sizing: { date: 140 },
+  pinning: { left: ['date'], right: [] },
+}
+
+describe('createTablePersist', () => {
+  it('round-trips the whole state through the document', () => {
+    const storage = memoryStorage()
+    const { persist: first, dispose } = setup({ storage })
+
+    first.commit({
+      columns: layout,
+      sorting: [{ id: 'date', desc: true }],
+      columnFilters: [{ id: 'region', value: 'EMEA' }],
+      density: 'compact',
+      pageSize: 25,
+    })
+
+    const { persist: second } = setup({ storage })
+    expect(second.hydrate(['date', 'amount'])).toEqual({
+      columns: layout,
+      sorting: [{ id: 'date', desc: true }],
+      columnFilters: [{ id: 'region', value: 'EMEA' }],
+      density: 'compact',
+      pageSize: 25,
+      dropped: [],
+    })
+
+    // The document is a versioned envelope with the table-view type.
+    const raw = JSON.parse(
+      storage.map.get('newui.tables:orders') ?? '',
+    ) as Record<string, unknown>
+    expect(raw['v']).toBe(1)
+    expect(raw['type']).toBe('table-view')
+    dispose()
+  })
+
+  it('commits keep fields the table did not mention', () => {
+    const storage = memoryStorage()
+    const { persist, dispose } = setup({ storage })
+    persist.commit({ density: 'compact', pageSize: 25 })
+    persist.commit({ sorting: [{ id: 'amount', desc: false }] })
+
+    const { persist: reloaded } = setup({ storage })
+    const state = reloaded.hydrate([])
+    expect(state.density).toBe('compact')
+    expect(state.pageSize).toBe(25)
+    expect(state.sorting).toEqual([{ id: 'amount', desc: false }])
+    dispose()
+  })
+
+  it('drops persisted columns that no longer exist', () => {
+    const storage = memoryStorage()
+    const { persist, dispose } = setup({ storage })
+    persist.commit({
+      columns: {
+        visibility: { date: true, ghost: false, amount: true },
+        order: ['date', 'ghost', 'amount'],
+        sizing: { ghost: 100 },
+        pinning: { left: ['ghost'], right: [] },
+      },
+    })
+
+    const { persist: reloaded } = setup({ storage })
+    const state = reloaded.hydrate(['date', 'amount', 'new'])
+    expect(state.dropped).toEqual(['ghost'])
+    expect(state.columns).toEqual({
+      visibility: { date: true, amount: true },
+      order: ['date', 'amount', 'new'],
+      sizing: {},
+      pinning: { left: [], right: [] },
+    })
+    dispose()
+  })
+
+  it('migrates a document that predates the versioned shape', () => {
+    const storage = memoryStorage()
+    // What an older release wrote: visible ids in `columns`, `sort` not `sorting`.
+    storage.setItem(
+      'newui.tables:legacy',
+      JSON.stringify({
+        v: 1,
+        name: 'legacy',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+        doc: {
+          columns: ['date', 'amount'],
+          sort: [{ id: 'date', desc: true }],
+        },
+      }),
+    )
+    const { persist, dispose } = setup({ storage, id: 'legacy' })
+    const state = persist.hydrate(['date', 'amount'])
+    expect(state.sorting).toEqual([{ id: 'date', desc: true }])
+    expect(state.columns).toEqual({
+      visibility: { date: true, amount: true },
+      order: ['date', 'amount'],
+      sizing: {},
+      pinning: { left: [], right: [] },
+    })
+    dispose()
+  })
+
+  it('writes the view half to the URL and reads it back', async () => {
+    const bridge = adapter()
+    const storage = memoryStorage()
+    const { persist, dispose } = setup({
+      storage,
+      url: { adapter: bridge },
+    })
+
+    persist.commit({
+      sorting: [{ id: 'amount', desc: true }],
+      columnFilters: [{ id: 'region', value: 'EMEA' }],
+      density: 'compact',
+      pageSize: 50,
+      columns: layout,
+    })
+    await flushMicrotasks()
+
+    const params = bridge.last()
+    expect(JSON.parse(params.get('orders.sort') ?? '')).toEqual([
+      { id: 'amount', desc: true },
+    ])
+    expect(params.get('orders.pageSize')).toBe('50')
+    expect(params.get('orders.density')).toBe('compact')
+    // The column layout is a preference, not a link — never in the URL.
+    expect([...params.keys()].some((key) => key.includes('columns'))).toBe(
+      false,
+    )
+
+    const deep = adapter(new URLSearchParams(params).toString())
+    const { persist: reloaded } = setup({ storage, url: { adapter: deep } })
+    const state = reloaded.hydrate(['date', 'amount'])
+    expect(state.sorting).toEqual([{ id: 'amount', desc: true }])
+    expect(state.columnFilters).toEqual([{ id: 'region', value: 'EMEA' }])
+    expect(state.density).toBe('compact')
+    expect(state.pageSize).toBe(50)
+    expect(state.columns).toEqual(layout)
+    dispose()
+  })
+
+  it('lets the URL win over the document', () => {
+    const storage = memoryStorage()
+    const { persist, dispose } = setup({ storage })
+    persist.commit({ sorting: [{ id: 'date', desc: true }], pageSize: 10 })
+
+    const deep = adapter(
+      '?orders.sort=%5B%7B%22id%22%3A%22amount%22%2C%22desc%22%3Afalse%7D%5D',
+    )
+    const { persist: reloaded } = setup({ storage, url: { adapter: deep } })
+    expect(reloaded.hydrate([]).sorting).toEqual([
+      { id: 'amount', desc: false },
+    ])
+    dispose()
+  })
+
+  it('reports a storage backend that rejects the write', () => {
+    const rejecting: ConfigStorage = {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error('quota')
+      },
+      removeItem: () => {},
+      keys: () => [],
+    }
+    const onPersistError = vi.fn()
+    const { persist, dispose } = setup({ storage: rejecting, onPersistError })
+    persist.commit({ pageSize: 25 })
+    expect(onPersistError).toHaveBeenCalledTimes(1)
+    expect(onPersistError.mock.calls[0]?.[0]?.message).toContain('orders')
+    dispose()
+  })
+
+  it('reports a stored document that no longer parses', () => {
+    const storage = memoryStorage()
+    storage.setItem('newui.tables:orders', '{not json')
+    const onPersistError = vi.fn()
+    const { persist, dispose } = setup({ storage, onPersistError })
+    expect(persist.hydrate(['date'])).toEqual({ dropped: [] })
+    expect(onPersistError).toHaveBeenCalledTimes(1)
+    dispose()
+  })
+
+  it('forgets everything on reset', async () => {
+    const bridge = adapter()
+    const storage = memoryStorage()
+    const { persist, dispose } = setup({ storage, url: { adapter: bridge } })
+    persist.commit({
+      columns: layout,
+      sorting: [{ id: 'date', desc: true }],
+      pageSize: 25,
+    })
+    await flushMicrotasks()
+
+    persist.reset()
+    await flushMicrotasks()
+
+    expect(storage.map.has('newui.tables:orders')).toBe(false)
+    expect([...bridge.last()].length).toBe(0)
+    const { persist: reloaded } = setup({ storage })
+    expect(reloaded.hydrate(['date', 'amount'])).toEqual({ dropped: [] })
+    dispose()
+  })
+})