@talelk/newui-data 0.0.0-stage → 1.1.0

package/src/resource/realtime.ts

@@ -0,0 +1,287 @@
+import { type Accessor, createSignal } from 'solid-js'
+
+/**
+ * A realtime transport over a `WebSocket`.
+ *
+ * This is a **plain-`WebSocket`** helper, not a socket.io client: it opens one
+ * socket to a configurable URL and multiplexes subscriptions over it through
+ * `on`/`off`/`close`. The socket is created by an injectable
+ * {@link RealtimeSocketFactory}, so a consumer who already uses socket.io can
+ * pass `io(url)` as the factory — a socket.io `Socket` satisfies
+ * {@link RealtimeSocket} — and get named events for free. The wire protocol is
+ * deliberately *not* implemented here.
+ *
+ * The default factory adapts the native `WebSocket` to the same surface: it
+ * forwards the `open`/`close`/`error` lifecycle events and delivers each
+ * message as a single `message` event carrying the raw `event.data`. With the
+ * native transport there is no event multiplexing on the wire, so named
+ * subscriptions only fire under a transport that provides them (socket.io).
+ */
+
+/** A listener registered with {@link Realtime.on}. */
+export type RealtimeListener = (...args: unknown[]) => void
+
+/**
+ * The minimal socket surface the realtime helper drives. A native `WebSocket`
+ * is adapted to it by the default factory; a `socket.io-client` `Socket`
+ * already satisfies it, so it can be passed through
+ * {@link RealtimeOptions.factory} directly.
+ */
+export interface RealtimeSocket {
+  on(event: string, listener: RealtimeListener): unknown
+  off(event: string, listener: RealtimeListener): unknown
+  close(): void
+  send?(data: unknown): void
+  /** Whether the socket is currently connected (socket.io exposes this). */
+  readonly connected?: boolean
+}
+
+/** Build the transport for a URL. See {@link RealtimeOptions.factory}. */
+export type RealtimeSocketFactory = (
+  url: string,
+  protocols?: string | string[],
+) => RealtimeSocket
+
+/** The map of event name to payload, for a typed {@link Realtime}. */
+export interface RealtimeEventMap {
+  [event: string]: unknown
+}
+
+/** Options for {@link createRealtime}. */
+export interface RealtimeOptions {
+  /** WebSocket URL, or an accessor for a reactive URL. */
+  url: string | (() => string)
+  /** Subprotocols passed to the native `WebSocket` constructor. */
+  protocols?: string | string[]
+  /**
+   * Socket factory. Defaults to a native `WebSocket` adapter. Pass a
+   * socket.io client factory (`(url) => io(url)`) to reuse that transport.
+   */
+  factory?: RealtimeSocketFactory
+  /** Connect on creation. Defaults to `true`. */
+  auto?: boolean
+  /**
+   * Reconnect after an unexpected close, with exponential backoff. Defaults to
+   * `true`. Set `false` when the injected transport (socket.io) reconnects on
+   * its own.
+   */
+  reconnect?: boolean
+  /** First reconnect delay in ms. Defaults to `1000`. */
+  reconnectDelay?: number
+  /** Cap on the reconnect delay in ms. Defaults to `30000`. */
+  maxReconnectDelay?: number
+  onOpen?: () => void
+  onClose?: (event?: unknown) => void
+  onError?: (event?: unknown) => void
+}
+
+/** The signal-based realtime handle {@link createRealtime} returns. */
+export interface Realtime<TEvents extends RealtimeEventMap = RealtimeEventMap> {
+  /** Whether the socket is currently connected. */
+  connected: Accessor<boolean>
+  /** Open the connection. Idempotent while already open. */
+  connect(): void
+  /** Subscribe to an event. Returns an unsubscribe function. */
+  on<K extends keyof TEvents & string>(
+    event: K,
+    listener: (data: TEvents[K]) => void,
+  ): () => void
+  /** Unsubscribe a listener previously registered with `on`. */
+  off(event: string, listener: RealtimeListener): void
+  /** Send a payload; the native transport JSON-encodes non-strings. */
+  send(data: unknown): void
+  /** Close the connection and stop reconnecting. */
+  close(): void
+}
+
+const DEFAULT_RECONNECT_DELAY = 1000
+const DEFAULT_MAX_RECONNECT_DELAY = 30_000
+
+/** Adapt a native `WebSocket` to {@link RealtimeSocket}. */
+function nativeFactory(
+  url: string,
+  protocols?: string | string[],
+): RealtimeSocket {
+  const socket = protocols ? new WebSocket(url, protocols) : new WebSocket(url)
+  const messageHandlers = new Map<
+    RealtimeListener,
+    (event: MessageEvent) => void
+  >()
+
+  return {
+    on(event, listener) {
+      if (event === 'message') {
+        const handler = (message: MessageEvent) => listener(message.data)
+        messageHandlers.set(listener, handler)
+        socket.addEventListener('message', handler)
+        return
+      }
+      socket.addEventListener(
+        event as keyof WebSocketEventMap,
+        listener as EventListener,
+      )
+    },
+    off(event, listener) {
+      if (event === 'message') {
+        const handler = messageHandlers.get(listener)
+        if (handler) {
+          socket.removeEventListener('message', handler)
+          messageHandlers.delete(listener)
+        }
+        return
+      }
+      socket.removeEventListener(
+        event as keyof WebSocketEventMap,
+        listener as EventListener,
+      )
+    },
+    close() {
+      socket.close()
+    },
+    send(data) {
+      socket.send(typeof data === 'string' ? data : JSON.stringify(data))
+    },
+    get connected() {
+      return socket.readyState === WebSocket.OPEN
+    },
+  }
+}
+
+/** The default factory, or `undefined` when there is no browser `WebSocket`. */
+function defaultFactory(): RealtimeSocketFactory | undefined {
+  if (typeof window === 'undefined' || typeof WebSocket === 'undefined') {
+    return undefined
+  }
+  return nativeFactory
+}
+
+/**
+ * Open a WebSocket and expose typed `on`/`off`/`close` over it.
+ *
+ * `connected` is a signal. Subscriptions registered before the socket exists
+ * are replayed onto every (re)connection, so a consumer can call `on` in any
+ * order. Lifecycle events are accepted in both dialects — `open`/`close` for a
+ * native `WebSocket`, `connect`/`disconnect` for socket.io.
+ */
+export function createRealtime<
+  TEvents extends RealtimeEventMap = RealtimeEventMap,
+>(options: RealtimeOptions): Realtime<TEvents> {
+  const [connected, setConnected] = createSignal(false)
+  const listeners = new Map<string, Set<RealtimeListener>>()
+  const reconnectEnabled = options.reconnect !== false
+  const baseDelay = options.reconnectDelay ?? DEFAULT_RECONNECT_DELAY
+  const maxDelay = options.maxReconnectDelay ?? DEFAULT_MAX_RECONNECT_DELAY
+
+  let socket: RealtimeSocket | null = null
+  let stopped = false
+  let attempt = 0
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const currentUrl = (): string =>
+    typeof options.url === 'function' ? options.url() : options.url
+
+  function handleOpen(): void {
+    attempt = 0
+    setConnected(true)
+    options.onOpen?.()
+  }
+
+  function handleClose(event?: unknown): void {
+    setConnected(false)
+    options.onClose?.(event)
+    socket = null
+    if (!stopped && reconnectEnabled) scheduleReconnect()
+  }
+
+  function handleError(event?: unknown): void {
+    options.onError?.(event)
+  }
+
+  function scheduleReconnect(): void {
+    if (timer) return
+    const delay = Math.min(baseDelay * 2 ** attempt, maxDelay)
+    attempt += 1
+    timer = setTimeout(() => {
+      timer = null
+      open()
+    }, delay)
+  }
+
+  function attach(target: RealtimeSocket): void {
+    const isCurrent = (): boolean => socket === target
+    target.on('open', () => {
+      if (isCurrent()) handleOpen()
+    })
+    target.on('connect', () => {
+      if (isCurrent()) handleOpen()
+    })
+    target.on('close', (event) => {
+      if (isCurrent()) handleClose(event)
+    })
+    target.on('disconnect', (event) => {
+      if (isCurrent()) handleClose(event)
+    })
+    target.on('error', (event) => {
+      if (isCurrent()) handleError(event)
+    })
+    for (const [event, set] of listeners) {
+      for (const listener of set) target.on(event, listener)
+    }
+  }
+
+  function open(): void {
+    if (socket || stopped) return
+    const create = options.factory ?? defaultFactory()
+    if (!create) return
+    const target = create(currentUrl(), options.protocols)
+    socket = target
+    attach(target)
+    // A socket that is already connected (e.g. socket.io with `autoConnect`)
+    // does not re-fire `connect`, so reflect its state now.
+    if (target.connected) handleOpen()
+  }
+
+  function connect(): void {
+    stopped = false
+    open()
+  }
+
+  function on<K extends keyof TEvents & string>(
+    event: K,
+    listener: (data: TEvents[K]) => void,
+  ): () => void {
+    const wrapped = listener as RealtimeListener
+    const set = listeners.get(event) ?? new Set<RealtimeListener>()
+    set.add(wrapped)
+    listeners.set(event, set)
+    socket?.on(event, wrapped)
+    return () => off(event, wrapped)
+  }
+
+  function off(event: string, listener: RealtimeListener): void {
+    listeners.get(event)?.delete(listener)
+    socket?.off(event, listener)
+  }
+
+  function send(data: unknown): void {
+    socket?.send?.(data)
+  }
+
+  function close(): void {
+    stopped = true
+    if (timer) {
+      clearTimeout(timer)
+      timer = null
+    }
+    const target = socket
+    // `handleClose` only runs for the current socket, so call it before the
+    // socket is detached; the transport's own close event is then ignored.
+    handleClose()
+    target?.close()
+  }
+
+  // Auto-connect on creation. `connect` is a plain action, not a signal read.
+  if (options.auto !== false) connect()
+
+  return { connected, connect, on, off, send, close }
+}

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