useDocyrusDataExport

Server-side export for Docyrus data sources — POSTs a query payload to the export edge function and streams the result file straight to the browser.

Edit on GitHubEditllms.txt

Installation

pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-export

Required Packages(2 packages)

pnpm add @docyrus/api-client react-querybuilder

This hook is distributed as source. It needs an authenticated RestApiClient from @docyrus/api-client somewhere above your component tree.

useDocyrusDataExport wraps the Docyrus server-side export endpoint (POST /v1/edge/run/query-export). The server applies the same filters, search, and column projection used by the items query and streams back a binary file (xlsx by default). RestApiClient.download() then writes it to the user's browser using the Content-Disposition filename.

Use this hook when:

The export needs to cover more rows than the grid currently has loaded.
You want the canonical, server-authored xlsx (with formatting, formula columns, lookups resolved).
You want filters, search, and column visibility to round-trip exactly as the user sees them.

For exports of an already-loaded array of rows (no server round-trip, four formats including JSON and Markdown), use useDataExport instead.

Hook	Where serialization happens	Formats	Best for
`useDataExport`	Client	csv, json, markdown, xlsx	In-memory rows, custom columns, selection-only exports
`useDocyrusDataExport`	Server (edge function)	xlsx (default), csv	Full data source, large exports, canonical Docyrus output

Usage

Basic example

'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { Button } from '@docyrus/ui/primitives/ui/button';
import { useDocyrusDataExport } from '@docyrus/ui/library/hooks/use-docyrus-data-export';

export function ExportContactsButton({ dataSourceId }: { dataSourceId: string }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const { exportData, isExporting, error } = useDocyrusDataExport({ client });

  return (
    <>
      <Button
        disabled={isExporting}
        onClick={() => exportData({ dataSourceId })}>
        {isExporting ? 'Exporting…' : 'Export'}
      </Button>
      {error ? <p className="text-destructive">{error.message}</p> : null}
    </>
  );
}

With no extra payload fields, the server defaults apply: every exportable column, no filters, the hook's defaultLimit (10 000 rows), and xlsx output.

Mirroring the visible grid

Pair the hook with useDocyrusDataGrid so the export reflects exactly what the user sees — same filters, same search, same column visibility:

const grid = useDocyrusDataGrid({ client, appSlug, dataSourceSlug });
const { exportData, isExporting } = useDocyrusDataExport({ client });

async function handleExport() {
  await exportData({
    dataSourceId: grid.dataSourceId,
    columns: grid.visibleColumnSlugs, // visible-only, in display order
    filters: grid.filterGroup,
    filterKeyword: grid.search,
    limit: 50000
  });
}

Free-form extras (server-controlled fields)

Any unknown keys on the payload are forwarded verbatim. Use this for tenant-specific fields the server understands without changing the hook:

await exportData({
  dataSourceId,
  columns: ['name', 'email', 'createdOn'],
  format: 'csv',
  // forwarded as-is
  timezone: 'Europe/Istanbul',
  locale: 'tr-TR'
});

Override the endpoint

const { exportData } = useDocyrusDataExport({
  client,
  endpoint: '/v1/edge/run/tenant-export',
  defaultLimit: 25000
});

Override only when a deployment exposes the export edge function under a non-standard route.

API Reference

Parameters — `UseDocyrusDataExportOptions`

Option	Type	Default	Description
`client`	`RestApiClient`	—	Authenticated REST client used to POST the export request. Required.
`defaultLimit`	`number`	`10000`	Default row cap when `payload.limit` is omitted.
`endpoint`	`string`	`'/v1/edge/run/query-export'`	Endpoint path. Override only when a deployment exposes the export edge function under a different route.

`exportData(payload)` — `DocyrusDataExportPayload`

Field	Type	Default	Description
`dataSourceId`	`string`	—	Target data source ID — required by the edge query. Required.
`columns`	`'*' \| ReadonlyArray<string>`	`'*'`	Columns to include. Pass `'*'` (or omit) to let the server default to every exportable field, or an array of field slugs to project a specific subset.
`filters`	`RuleGroupType \| null`	`null`	Filter group applied to the underlying items query. Pass the same shape used by the items endpoint (combinator + rules). Empty rule groups are normalised to `null` server-side.
`filterKeyword`	`string`	—	Free-text keyword search forwarded to the server. Omitted from the request body when empty.
`limit`	`number`	`defaultLimit`	Maximum number of rows to export. Falls back to `defaultLimit` when omitted or non-positive.
`format`	`'xlsx' \| 'csv'`	`'xlsx'`	Optional override for the export format. Final format is server-controlled.
`[key: string]`	`unknown`	—	Free-form extras forwarded verbatim to the endpoint.

Return Value — `UseDocyrusDataExportResult`

Property	Type	Description
`exportData`	`(payload: DocyrusDataExportPayload) => Promise<void>`	Trigger a server-side export. Resolves once the file has been streamed to the browser; rejects with the original error (which is also stored in `error`).
`isExporting`	`boolean`	`true` while a request is in flight. Use it to disable the trigger button.
`error`	`Error \| null`	Last error thrown by `exportData`. Cleared on every new attempt.

Type Exports

Type	Description
`UseDocyrusDataExportOptions`	Hook input (`client`, `defaultLimit`, `endpoint`).
`UseDocyrusDataExportResult`	Hook return value (`exportData`, `isExporting`, `error`).
`DocyrusDataExportPayload`	Body shape POSTed to the export endpoint. Includes the index signature for forwarding extras.

Backend connection

Method	Endpoint	Purpose
`POST`	`/v1/edge/run/query-export`	Server reads the payload, applies filters/search/column projection, and streams back a binary file (xlsx by default). The browser saves it using the `Content-Disposition` filename.

The endpoint can be overridden via the endpoint option when a deployment exposes the export edge function under a different route.

Notes

Empty filter groups ({ combinator: 'and', rules: [] }) are normalised to null before the request leaves the client so the server query plan stays clean.
client.download() handles the binary response: it reads the Content-Disposition filename, builds a Blob, and triggers the download via a temporary <a download> element.
Errors are stored on error and re-thrown from exportData() so callers can await and catch (or rely on the state).
This hook does not project rows or own a column UI — pair it with useDocyrusDataGrid (or any source of dataSourceId + filter group) to drive the payload.