@talelk/newui-data 0.0.0-stage → 1.1.0

package/src/query/collection.ts

@@ -0,0 +1,207 @@
+import {
+  createMutation,
+  createQuery,
+  keepPreviousData,
+  type QueryKey,
+  useQueryClient,
+} from '@tanstack/solid-query'
+import type { Accessor } from 'solid-js'
+import type { NewRecord, Repository } from './repository'
+
+/**
+ * A list and the four things a page does to it.
+ *
+ * `createCollection` is the kit's answer to "how does a page hold its records":
+ * one query for the list, and mutations that are **optimistic and reversible** —
+ * a patch lands on screen immediately, and a failed request puts the previous
+ * list back. The page renders `isPending` / `error` and never touches the cache.
+ *
+ * The list is keyed by `key`, so two panes reading the same collection share one
+ * request and one update. The repository stays the only place that knows where
+ * the records come from.
+ */
+
+export interface ListQuery<T> {
+  /** The records; `[]` while the first request is in flight. */
+  rows: Accessor<T[]>
+  /** The first request has not settled. */
+  isPending: Accessor<boolean>
+  /** A request is in flight, first or refetch. */
+  isFetching: Accessor<boolean>
+  /** The last request failed; `error` says why. */
+  isError: Accessor<boolean>
+  error: Accessor<Error | undefined>
+  /** Re-run the list request (the "Try again" button). */
+  refetch: () => Promise<unknown>
+}
+
+export interface CollectionMutation<Input, Result> {
+  mutate: (input: Input) => void
+  /** Resolves when the mutation *and* the list refresh have settled. */
+  mutateAsync: (input: Input) => Promise<Result>
+  isPending: Accessor<boolean>
+  error: Accessor<Error | undefined>
+}
+
+export interface Collection<T extends { id: string }, New = NewRecord<T>> {
+  query: ListQuery<T>
+  create: CollectionMutation<New, T>
+  update: CollectionMutation<{ id: string; patch: Partial<T> }, T>
+  /** Patch many at once — the bulk action. */
+  updateMany: CollectionMutation<{ ids: string[]; patch: Partial<T> }, T[]>
+  remove: CollectionMutation<{ ids: string[] }, void>
+}
+
+export interface CollectionOptions<
+  T extends { id: string },
+  New = NewRecord<T>,
+> {
+  /** The cache identity. Same key = same collection. */
+  key: QueryKey
+  repository: Repository<T, New>
+  /** The list's freshness. Defaults to the client's. */
+  staleTime?: number
+  /** Retries after the first failure. Defaults to the client's. */
+  retry?: number | false
+  /**
+   * Poll the list on an interval. Off (`false`) by default — the client's
+   * `refetchOnWindowFocus: false` says returning to the tab is not a refresh;
+   * this is the explicit dial for data that genuinely changes on its own.
+   */
+  refetchInterval?: number | false
+  /**
+   * Keep the previous response on screen while the next one is in flight, so
+   * a server-mode page change never blanks the table. The rows are stale for
+   * one round trip; an empty table is not the alternative anyone asked for.
+   */
+  keepPreviousData?: boolean
+  /** Every mutation reports here first, so a page can word one notice. */
+  onError?: (error: Error) => void
+}
+
+function asError(value: unknown): Error | undefined {
+  if (value === null || value === undefined) return undefined
+  return value instanceof Error ? value : new Error(String(value))
+}
+
+export function createListQuery<T extends { id: string }>(
+  options: () => CollectionOptions<T, never>,
+): ListQuery<T> {
+  const query = createQuery(() => ({
+    queryKey: options().key,
+    queryFn: ({ signal }) => options().repository.list({ signal }),
+    staleTime: options().staleTime,
+    retry: options().retry,
+    refetchInterval: options().refetchInterval,
+    placeholderData: options().keepPreviousData ? keepPreviousData : undefined,
+    throwOnError: false,
+  }))
+  return {
+    rows: () => query.data ?? [],
+    isPending: () => query.isPending,
+    isFetching: () => query.isFetching,
+    isError: () => query.isError,
+    error: () => asError(query.error),
+    refetch: () => query.refetch(),
+  }
+}
+
+export function createCollection<T extends { id: string }, New = NewRecord<T>>(
+  options: () => CollectionOptions<T, New>,
+): Collection<T, New> {
+  const queryClient = useQueryClient()
+  const key = () => options().key
+  const fail = (error: unknown) => {
+    const normalised = asError(error)
+    if (normalised) options().onError?.(normalised)
+    return normalised
+  }
+  const previous = () => queryClient.getQueryData<T[]>(key())
+  const restore = (snapshot: T[] | undefined) => {
+    if (snapshot) queryClient.setQueryData(key(), snapshot)
+  }
+  const patchRows = (ids: string[], patch: Partial<T>) => {
+    const wanted = new Set(ids)
+    queryClient.setQueryData<T[]>(key(), (rows = []) =>
+      rows.map((row) => (wanted.has(row.id) ? { ...row, ...patch } : row)),
+    )
+  }
+
+  const query = createListQuery(options)
+
+  const create = createMutation(() => ({
+    mutationFn: (input: New) => options().repository.create(input),
+    // Not optimistic: a new record's id and defaults are the repository's to
+    // decide, so guessing them would show a row that then changes identity.
+    onError: (error) => void fail(error),
+    onSettled: () => queryClient.invalidateQueries({ queryKey: key() }),
+  }))
+
+  const update = createMutation(() => ({
+    mutationFn: ({ id, patch }: { id: string; patch: Partial<T> }) =>
+      options().repository.update(id, patch),
+    onMutate: async ({ id, patch }) => {
+      await queryClient.cancelQueries({ queryKey: key() })
+      const snapshot = previous()
+      patchRows([id], patch)
+      return { snapshot }
+    },
+    onError: (error, _input, context) => {
+      restore(context?.snapshot)
+      void fail(error)
+    },
+    onSettled: () => queryClient.invalidateQueries({ queryKey: key() }),
+  }))
+
+  const updateMany = createMutation(() => ({
+    mutationFn: async ({ ids, patch }: { ids: string[]; patch: Partial<T> }) =>
+      Promise.all(ids.map((id) => options().repository.update(id, patch))),
+    onMutate: async ({ ids, patch }) => {
+      await queryClient.cancelQueries({ queryKey: key() })
+      const snapshot = previous()
+      patchRows(ids, patch)
+      return { snapshot }
+    },
+    onError: (error, _input, context) => {
+      restore(context?.snapshot)
+      void fail(error)
+    },
+    onSettled: () => queryClient.invalidateQueries({ queryKey: key() }),
+  }))
+
+  const remove = createMutation(() => ({
+    mutationFn: ({ ids }: { ids: string[] }) =>
+      options().repository.remove(ids),
+    onMutate: async ({ ids }) => {
+      await queryClient.cancelQueries({ queryKey: key() })
+      const snapshot = previous()
+      const wanted = new Set(ids)
+      queryClient.setQueryData<T[]>(key(), (rows = []) =>
+        rows.filter((row) => !wanted.has(row.id)),
+      )
+      return { snapshot }
+    },
+    onError: (error, _input, context) => {
+      restore(context?.snapshot)
+      void fail(error)
+    },
+    onSettled: () => queryClient.invalidateQueries({ queryKey: key() }),
+  }))
+
+  const wrap = <Input, Result>(
+    mutation: ReturnType<typeof createMutation<Result, Error, Input>>,
+  ): CollectionMutation<Input, Result> => ({
+    mutate: (input: Input) => mutation.mutate(input),
+    mutateAsync: (input: Input) => mutation.mutateAsync(input),
+    isPending: () => mutation.isPending,
+    error: () => asError(mutation.error),
+  })
+
+  return {
+    query,
+    create: wrap(create),
+    update: wrap(update),
+    updateMany: wrap(updateMany),
+    remove: wrap(remove),
+  }
+}

package/src/query/index.ts

@@ -0,0 +1,4 @@
+export * from './client'
+export * from './collection'
+export * from './repository'
+export * from './server-table'

package/src/query/repository.ts

@@ -0,0 +1,30 @@
+/**
+ * A repository is the seam between a page and wherever its records live.
+ *
+ * It is deliberately small: `list`, `create`, `update`, `remove`. Domain verbs
+ * (`complete`, `archive`, `comment`) are `update(id, patch)` with a different
+ * name at the call site — a contract that grows a method per business action is
+ * a database, not a seam.
+ *
+ * `list` is the only read. A page that needs one record filters the list it
+ * already has; a remote adapter that wants a single request can still expose
+ * `list` and let the query cache hold the collection, which is what every local
+ * example does.
+ */
+export interface Repository<T extends { id: string }, New = NewRecord<T>> {
+  /** Every record, in the order the collection wants them shown. */
+  list(options?: { signal?: AbortSignal }): Promise<T[]>
+  /** Create one; resolves with the stored record (its real id included). */
+  create(input: New, options?: { signal?: AbortSignal }): Promise<T>
+  /** Patch one; resolves with the stored record. */
+  update(
+    id: string,
+    patch: Partial<T>,
+    options?: { signal?: AbortSignal },
+  ): Promise<T>
+  /** Delete many at once; resolves when they are gone. */
+  remove(ids: string[], options?: { signal?: AbortSignal }): Promise<void>
+}
+
+/** What a caller must supply to create a record: everything but the id it gets. */
+export type NewRecord<T> = Omit<T, 'id'> & { id?: string }

package/src/query/server-table.test.ts

@@ -0,0 +1,136 @@
+import { createRoot } from 'solid-js'
+import { describe, expect, it, vi } from 'vitest'
+import type { UrlStateAdapter } from '../url-state'
+import { createServerTableState, type ServerTableState } from './server-table'
+
+function setup(...args: Parameters<typeof createServerTableState>): {
+  state: ServerTableState
+  dispose: () => void
+} {
+  let dispose!: () => void
+  let state!: ServerTableState
+  createRoot((d) => {
+    dispose = d
+    state = createServerTableState(...args)
+  })
+  return { state, dispose }
+}
+
+interface FakeAdapter extends UrlStateAdapter {
+  last(): URLSearchParams
+}
+
+function adapter(search = ''): FakeAdapter {
+  let last = new URLSearchParams(search)
+  const replace = vi.fn((params: URLSearchParams) => {
+    last = params
+  })
+  return {
+    search: () => search,
+    replace,
+    last: () => last,
+  }
+}
+
+describe('createServerTableState', () => {
+  it('starts from the defaults or the initial slices', () => {
+    const { state, dispose } = setup({
+      initial: {
+        sorting: [{ id: 'name', desc: false }],
+        pagination: { pageSize: 25 },
+      },
+    })
+    expect(state.sorting()).toEqual([{ id: 'name', desc: false }])
+    expect(state.columnFilters()).toEqual([])
+    expect(state.globalFilter()).toBe('')
+    expect(state.pagination()).toEqual({ pageIndex: 0, pageSize: 25 })
+    dispose()
+  })
+
+  it('a sort change returns the result to page 0', () => {
+    const { state, dispose } = setup()
+    state.setPageIndex(4)
+    expect(state.pagination().pageIndex).toBe(4)
+    state.setSorting([{ id: 'amount', desc: true }])
+    expect(state.sorting()).toEqual([{ id: 'amount', desc: true }])
+    expect(state.pagination().pageIndex).toBe(0)
+    dispose()
+  })
+
+  it('a filter change returns the result to page 0', () => {
+    const { state, dispose } = setup()
+    state.setPageIndex(2)
+    state.setColumnFilters([{ id: 'status', value: 'open' }])
+    expect(state.columnFilters()).toEqual([{ id: 'status', value: 'open' }])
+    expect(state.pagination().pageIndex).toBe(0)
+    state.setGlobalFilter('beta')
+    state.setPageIndex(7)
+    state.setGlobalFilter('gamma')
+    expect(state.pagination().pageIndex).toBe(0)
+    dispose()
+  })
+
+  it('paging moves without touching the other slices', () => {
+    const { state, dispose } = setup()
+    state.setSorting([{ id: 'name', desc: true }])
+    state.setPageIndex(3)
+    expect(state.pagination()).toEqual({ pageIndex: 3, pageSize: 10 })
+    expect(state.sorting()).toEqual([{ id: 'name', desc: true }])
+    dispose()
+  })
+
+  it('resizing the page keeps the top row', () => {
+    const { state, dispose } = setup()
+    state.setPageIndex(2) // rows 20..29 at pageSize 10
+    state.setPageSize(20)
+    expect(state.pagination()).toEqual({ pageIndex: 1, pageSize: 20 })
+    dispose()
+  })
+
+  it('the query key carries every slice over the base', () => {
+    const { state, dispose } = setup()
+    state.setSorting([{ id: 'name', desc: false }])
+    state.setGlobalFilter('acme')
+    state.setPageIndex(2)
+    expect(state.key(['tasks'])).toEqual([
+      'tasks',
+      {
+        sorting: [{ id: 'name', desc: false }],
+        columnFilters: [],
+        globalFilter: 'acme',
+        pagination: { pageIndex: 2, pageSize: 10 },
+      },
+    ])
+    dispose()
+  })
+
+  it('writes the slices to the URL under the namespace', async () => {
+    const url = adapter()
+    const { state, dispose } = setup({
+      sync: { adapter: url, namespace: 'tasks' },
+    })
+    state.setSorting([{ id: 'name', desc: true }])
+    // One coalesced `replace` per tick, so the write lands on the next microtask.
+    await Promise.resolve()
+    const written = url.last().get('tasks.sorting')
+    expect(JSON.parse(written ?? '')).toEqual([{ id: 'name', desc: true }])
+    expect(url.last().get('tasks.pagination')).toContain('"pageIndex":0')
+    dispose()
+  })
+
+  it('the URL seeds the store on creation', () => {
+    const url = adapter(
+      `?tasks.sorting=${encodeURIComponent(
+        JSON.stringify([{ id: 'amount', desc: true }]),
+      )}&tasks.pagination=${encodeURIComponent(
+        JSON.stringify({ pageIndex: 3, pageSize: 10 }),
+      )}`,
+    )
+    const { state, dispose } = setup({
+      sync: { adapter: url, namespace: 'tasks' },
+    })
+    expect(state.sorting()).toEqual([{ id: 'amount', desc: true }])
+    expect(state.pagination()).toEqual({ pageIndex: 3, pageSize: 10 })
+    dispose()
+  })
+})

package/src/query/server-table.ts

@@ -0,0 +1,181 @@
+import type { QueryKey } from '@tanstack/solid-query'
+import type { Accessor } from 'solid-js'
+import {
+  createUrlState,
+  type UrlStateAdapter,
+  type UrlStateValue,
+} from '../url-state'
+
+/**
+ * The query state of a server-mode table.
+ *
+ * `createServerTableState` owns the slices a server-mode `DataTable` mirrors:
+ * sorting, column filters, the global filter and pagination. It is a store,
+ * not a hook — the page creates it once and wires its accessors and setters
+ * into the table's controlled props, so the same state drives the request, the
+ * query key and (with a router adapter) the URL.
+ *
+ * The reset rule lives here as it does in the table: a sort or filter change
+ * returns the result to page 0, because page 3 of a result set that just
+ * changed shape is not a page anyone asked for.
+ *
+ * The slices are structural copies of TanStack Table's state shapes — this
+ * package never imports the table engine, so the app is the only place the
+ * two meet.
+ */
+
+// Type aliases, not interfaces: the slices serialize through `createUrlState`,
+// whose value contract needs the implicit index signature a type alias carries.
+
+/** One sort entry: a column id and its direction. */
+export type ServerTableSort = {
+  id: string
+  desc: boolean
+}
+
+/** One column filter: a column id and its value. */
+export type ServerTableColumnFilter = {
+  id: string
+  value: unknown
+}
+
+/** Where the user is in the result set. */
+export type ServerTablePagination = {
+  pageIndex: number
+  pageSize: number
+}
+
+export interface ServerTableStateOptions {
+  /** What the page renders before the URL or the user has said anything. */
+  initial?: {
+    sorting?: ServerTableSort[]
+    columnFilters?: ServerTableColumnFilter[]
+    globalFilter?: string
+    pagination?: Partial<ServerTablePagination>
+  }
+  /**
+   * Pipe the slices through `createUrlState` so they serialize to query
+   * parameters. Keys are namespaced (`table.sorting` by default) so one URL
+   * can host several surfaces. Without an adapter the store is plain signals.
+   */
+  sync?: {
+    adapter?: UrlStateAdapter
+    /** Query-key namespace for the slices. Defaults to `table`. */
+    namespace?: string
+  }
+}
+
+export interface ServerTableState {
+  sorting: Accessor<ServerTableSort[]>
+  columnFilters: Accessor<ServerTableColumnFilter[]>
+  globalFilter: Accessor<string>
+  pagination: Accessor<ServerTablePagination>
+  /** Replaces the sort entries and returns to page 0. */
+  setSorting: (next: ServerTableSort[]) => void
+  /** Replaces the column filters and returns to page 0. */
+  setColumnFilters: (next: ServerTableColumnFilter[]) => void
+  /** Replaces the search term and returns to page 0. */
+  setGlobalFilter: (next: string) => void
+  /** Moves within the result set. */
+  setPageIndex: (pageIndex: number) => void
+  /** Resizes the page, preserving the top row. */
+  setPageSize: (pageSize: number) => void
+  /** The whole pagination slice at once. */
+  setPagination: (next: ServerTablePagination) => void
+  /**
+   * The slices as one query key, so two pages with the same table state share
+   * one request. Pass the collection's own key as `base`.
+   */
+  key: (base?: QueryKey) => QueryKey
+}
+
+const DEFAULT_NAMESPACE = 'table'
+
+/**
+ * A server-mode table's sorting, filtering and pagination as one store,
+ * optionally serialized to the URL.
+ */
+export function createServerTableState(
+  options: ServerTableStateOptions = {},
+): ServerTableState {
+  const ns = options.sync?.namespace ?? DEFAULT_NAMESPACE
+  const initialPagination: ServerTablePagination = {
+    pageIndex: 0,
+    pageSize: 10,
+    ...options.initial?.pagination,
+  }
+  // The slices are typed by TanStack's shapes, not by `UrlStateValue`; the
+  // URL layer only ever JSON-round-trips them, so the boundary is a cast.
+  const initial: Record<string, UrlStateValue> = {
+    [`${ns}.sorting`]: options.initial?.sorting ?? [],
+    [`${ns}.columnFilters`]: (options.initial?.columnFilters ??
+      []) as UrlStateValue,
+    [`${ns}.globalFilter`]: options.initial?.globalFilter ?? '',
+    [`${ns}.pagination`]: initialPagination,
+  }
+  const url = createUrlState(initial, { adapter: options.sync?.adapter })
+
+  // `createUrlState` types every key as `UrlStateValue`; the store re-types
+  // them back. Values round-trip through JSON, so the casts are the whole
+  // story — the URL never sees a value this file did not write.
+  const signals = url as unknown as Record<string, Accessor<UrlStateValue>>
+  const read = <T>(key: string): Accessor<T> => {
+    const accessor = signals[key]
+    if (!accessor) throw new Error(`createUrlState is missing key "${key}"`)
+    return () => accessor() as T
+  }
+  const sorting = read<ServerTableSort[]>(`${ns}.sorting`)
+  const columnFilters = read<ServerTableColumnFilter[]>(`${ns}.columnFilters`)
+  const globalFilter = read<string>(`${ns}.globalFilter`)
+  const pagination = read<ServerTablePagination>(`${ns}.pagination`)
+
+  const setPagination = (next: ServerTablePagination) => {
+    url.set(`${ns}.pagination`, next)
+  }
+  /** The reset rule: a changed query starts at page 0. */
+  const resetPageIndex = () => {
+    const current = pagination()
+    if (current.pageIndex !== 0) setPagination({ ...current, pageIndex: 0 })
+  }
+
+  return {
+    sorting,
+    columnFilters,
+    globalFilter,
+    pagination,
+    setSorting: (next) => {
+      url.set(`${ns}.sorting`, next)
+      resetPageIndex()
+    },
+    setColumnFilters: (next) => {
+      url.set(`${ns}.columnFilters`, next as UrlStateValue)
+      resetPageIndex()
+    },
+    setGlobalFilter: (next) => {
+      url.set(`${ns}.globalFilter`, next)
+      resetPageIndex()
+    },
+    setPageIndex: (pageIndex) => {
+      setPagination({ ...pagination(), pageIndex })
+    },
+    setPageSize: (pageSize) => {
+      const current = pagination()
+      const size = Math.max(1, pageSize)
+      const topRow = current.pageIndex * current.pageSize
+      setPagination({
+        pageIndex: Math.floor(topRow / size),
+        pageSize: size,
+      })
+    },
+    setPagination,
+    key: (base = []) => [
+      ...base,
+      {
+        sorting: sorting(),
+        columnFilters: columnFilters(),
+        globalFilter: globalFilter(),
+        pagination: pagination(),
+      },
+    ],
+  }
+}