@talelk/newui-data 0.0.0-stage → 1.0.0

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

package/src/resource/idb.ts

@@ -0,0 +1,167 @@
+/**
+ * An IndexedDB-backed, Promise-based key/value store for caching resource data.
+ *
+ * The asynchronous sibling of {@link createLocalStore}, written against the
+ * native `indexedDB` API — no `idb`/`idb-keyval` dependency. Values are stored
+ * with the structured-clone algorithm, so objects, arrays, `Date`s, `Blob`s and
+ * the like round-trip without an explicit `JSON.stringify`.
+ *
+ * SSR-safe: with no `indexedDB` (the server, or a browser with it disabled) the
+ * store falls back to an in-memory `Map` and every method still resolves, so a
+ * caller never has to branch on `typeof window`. The `indexedDB` implementation
+ * is injectable through {@link IdbStoreOptions.factory}, which is also how the
+ * unit tests drive the native code path (jsdom ships no IndexedDB).
+ */
+
+/** A Promise-based, structured-clone key/value cache. */
+export interface IdbStore<T = unknown> {
+  /** The stored value, or `null` when the key is absent. */
+  get(key: string): Promise<T | null>
+  /** Persist a value. */
+  set(key: string, value: T): Promise<void>
+  /** Remove a key. */
+  delete(key: string): Promise<void>
+  /** Every key currently in the store. */
+  keys(): Promise<string[]>
+  /** Remove every key. */
+  clear(): Promise<void>
+  /** False when the store fell back to memory (SSR, or no IndexedDB). */
+  readonly persistent: boolean
+  /** Close the underlying database, if one was opened. */
+  close(): void
+}
+
+/** Options for {@link createIdbStore}. */
+export interface IdbStoreOptions {
+  /** Database name. Defaults to `newui`. */
+  name?: string
+  /** Object store name. Defaults to `keyval`. */
+  store?: string
+  /** Database version. Defaults to `1`. */
+  version?: number
+  /** IndexedDB implementation. Defaults to the global `indexedDB`. */
+  factory?: IDBFactory | null
+}
+
+function defaultFactory(): IDBFactory | null {
+  try {
+    return typeof indexedDB === 'undefined' ? null : indexedDB
+  } catch {
+    return null
+  }
+}
+
+/** Resolve an {@link IDBRequest} on success and reject on error. */
+function promisify<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result)
+    request.onerror = () =>
+      reject(request.error ?? new Error('IndexedDB request failed'))
+  })
+}
+
+/**
+ * Create a Promise-based cache over IndexedDB.
+ *
+ * The database is opened lazily on the first operation and reused. When no
+ * IndexedDB implementation is available the store keeps values in memory, so
+ * `get`/`set`/`keys` behave identically (minus persistence) and `persistent`
+ * reports the difference.
+ */
+export function createIdbStore<T = unknown>(
+  options: IdbStoreOptions = {},
+): IdbStore<T> {
+  const dbName = options.name ?? 'newui'
+  const storeName = options.store ?? 'keyval'
+  const version = options.version ?? 1
+  const factory =
+    options.factory === undefined ? defaultFactory() : options.factory
+  const memory = new Map<string, T>()
+
+  let opening: Promise<IDBDatabase> | null = null
+
+  function open(): Promise<IDBDatabase> {
+    if (!factory) {
+      return Promise.reject(new Error('IndexedDB is not available'))
+    }
+    if (opening) return opening
+    opening = new Promise<IDBDatabase>((resolve, reject) => {
+      const request = factory.open(dbName, version)
+      request.onupgradeneeded = () => {
+        const db = request.result
+        if (!db.objectStoreNames.contains(storeName)) {
+          db.createObjectStore(storeName)
+        }
+      }
+      request.onsuccess = () => resolve(request.result)
+      request.onerror = () =>
+        reject(
+          request.error ?? new Error(`Failed to open IndexedDB "${dbName}"`),
+        )
+    })
+    return opening
+  }
+
+  async function store(mode: IDBTransactionMode): Promise<IDBObjectStore> {
+    const db = await open()
+    return db.transaction(storeName, mode).objectStore(storeName)
+  }
+
+  async function get(key: string): Promise<T | null> {
+    if (!factory) return memory.get(key) ?? null
+    const objectStore = await store('readonly')
+    const value = (await promisify(objectStore.get(key))) as T | undefined
+    return value ?? null
+  }
+
+  async function set(key: string, value: T): Promise<void> {
+    if (!factory) {
+      memory.set(key, value)
+      return
+    }
+    const objectStore = await store('readwrite')
+    await promisify(objectStore.put(value, key))
+  }
+
+  async function remove(key: string): Promise<void> {
+    if (!factory) {
+      memory.delete(key)
+      return
+    }
+    const objectStore = await store('readwrite')
+    await promisify(objectStore.delete(key))
+  }
+
+  async function keys(): Promise<string[]> {
+    if (!factory) return [...memory.keys()]
+    const objectStore = await store('readonly')
+    const all = await promisify(objectStore.getAllKeys())
+    return all.map(String)
+  }
+
+  async function clear(): Promise<void> {
+    if (!factory) {
+      memory.clear()
+      return
+    }
+    const objectStore = await store('readwrite')
+    await promisify(objectStore.clear())
+  }
+
+  function close(): void {
+    const current = opening
+    if (!current) return
+    opening = null
+    void current.then((db) => db.close()).catch(() => {})
+  }
+
+  return {
+    get,
+    set,
+    delete: remove,
+    keys,
+    clear,
+    persistent: factory !== null,
+    close,
+  }
+}

package/src/resource/index.ts

@@ -0,0 +1,70 @@
+/**
+ * The signal-based data layer: a configurable request client, generic
+ * resources, and the thin composables over them.
+ *
+ * Ported from frappe-ui's `resources/` + `data-fetching/`, translated to Solid
+ * signals. No Vue `ref`/`reactive`, no `v-model` — every value is an accessor
+ * (`() => T`) and every action a plain function.
+ */
+
+export type {
+  ClientConfig,
+  RequestErrorOptions,
+  RequestOptions,
+} from './client'
+export {
+  getConfig,
+  isAbortError,
+  normalizeError,
+  RequestError,
+  request,
+  resetConfig,
+  setConfig,
+} from './client'
+export type {
+  DocumentOperationOptions,
+  DocumentResource,
+  DocumentResourceOptions,
+} from './document'
+export { createDocumentResource } from './document'
+export type { IdbStore, IdbStoreOptions } from './idb'
+export { createIdbStore } from './idb'
+export type {
+  ListFilters,
+  ListResource,
+  ListResourceOptions,
+} from './list'
+export { createListResource } from './list'
+export type { LocalStore, LocalStoreOptions } from './local'
+export { createLocalStore } from './local'
+export type {
+  Realtime,
+  RealtimeEventMap,
+  RealtimeListener,
+  RealtimeOptions,
+  RealtimeSocket,
+  RealtimeSocketFactory,
+} from './realtime'
+export { createRealtime } from './realtime'
+export type {
+  Resource,
+  ResourceFetcher,
+  ResourceOptions,
+} from './resource'
+export { createResource } from './resource'
+export type { UseCallOptions, UseCallReturn } from './useCall'
+export { useCall } from './useCall'
+export type { UseDocOptions, UseDocReturn } from './useDoc'
+export { useDoc } from './useDoc'
+export type {
+  DoctypeAction,
+  RunDocMethodInput,
+  RunMethodInput,
+  UseDoctypeOptions,
+  UseDoctypeReturn,
+} from './useDoctype'
+export { useDoctype } from './useDoctype'
+export type { UseListOptions, UseListReturn } from './useList'
+export { useList } from './useList'
+export type { UseNewDocOptions, UseNewDocReturn } from './useNewDoc'
+export { useNewDoc } from './useNewDoc'