useDocyrusDataSourceFields

Lightweight schema hook for one Docyrus data source on React Native. Returns the data source and its field list (including inline enum options), served cache-first from the shared inventory so no extra request is made after the post-sign-in warm-up.

Edit on GitHubEditllms.txt

iOSAndroidExpo Go

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-docyrus-data-source-fields

Required Packages(3 packages)

pnpm add @docyrus/api-client @docyrus/app-utils @tanstack/react-query

This hook is native-only. Web components that only need the field list (bulk update, import wizard, dummy-data generator) take it from the much larger useDocyrusFormView / useDocyrusDataViewSelect hooks. On native, BulkUpdateDialog, useDocyrusDataImportWizard and useDocyrusDummyDataGeneratorWizard use this hook instead.

It needs a QueryClientProvider above it. The fetch runs through createDataSourceClient(client, { inventory: getSharedDocyrusInventory(client) }):

getBySlug(appSlug, dataSourceSlug) is served from the shared inventory with fields and inline enum options.
On a cache miss the scoped GET has no fields (system data sources), so the hook fetches again with { expand: 'enums' }.

All consumers share the query key ['docyrus', 'dataSourceFields', appSlug, dataSourceSlug] (exported as docyrusDataSourceFieldsQueryKey), so mounting the hook in several places causes a single request.

Usage

import { useDocyrusClient } from '@docyrus/signin/react-native';

import { useDocyrusDataSourceFields } from '@/hooks/docyrus-native/use-docyrus-data-source-fields';

export function TaskFieldList() {
  const client = useDocyrusClient();
  const { fields, isLoading, error } = useDocyrusDataSourceFields({
    client,
    appSlug: 'base',
    dataSourceSlug: 'task'
  });

  if (isLoading) return <Spinner />;
  if (error) return <Text>{error.message}</Text>;

  return fields.map(field => <Text key={field.slug}>{`${field.name} · ${field.type}`}</Text>);
}

Gating and pre-resolved fields

// Only fetch while a sheet is open
useDocyrusDataSourceFields({ client, appSlug, dataSourceSlug, enabled: open });

// Reuse fields you already have: the fetch is skipped entirely
useDocyrusDataSourceFields({ client, appSlug, dataSourceSlug, fields: gridFields });

API Reference

Options (`UseDocyrusDataSourceFieldsOptions`)

Option	Type	Default	Description
`client`	`RestApiClient \| null \| undefined`	—	Authenticated REST client. The query waits while it is missing (required).
`appSlug`	`string`	—	App slug (required).
`dataSourceSlug`	`string`	—	Data source slug (required).
`enabled`	`boolean`	`true`	Gate the fetch (for example only while a dialog is open).
`fields`	`ReadonlyArray<DocyrusFieldLike>`	—	Pre-resolved fields. When set, nothing is fetched and these are returned.
`staleTime`	`number`	`300000` (5 minutes)	React Query stale time (ms).

Result (`UseDocyrusDataSourceFieldsResult`)

Field	Type	Description
`dataSource`	`DataSource \| null`	The data source record from `@docyrus/app-utils`.
`fields`	`ReadonlyArray<DocyrusFieldLike>`	Its fields, or the `fields` option. Empty while loading.
`isLoading`	`boolean`	First load in progress (always `false` with pre-resolved `fields`).
`error`	`Error \| null`	Fetch error.
`refetch`	`() => void`	Refetch the schema.

DocyrusFieldLike

Field	Type	Description
`id`	`string`	Field id.
`slug`	`string`	Field slug.
`name`	`string`	Display name.
`type`	`IFieldType \| string`	Field type (`field-text`, `field-select`, …).
`options`	`unknown`	Raw field options.
`enums`	`unknown`	Inline enum options.
`[key: string]`	`unknown`	Any other schema keys.

Exports

Export	Description
`useDocyrusDataSourceFields(options)`	The hook.
`docyrusDataSourceFieldsQueryKey(appSlug, dataSourceSlug)`	Shared query key, for example to invalidate the schema after a studio change.

Type Exports

Type	Description
`UseDocyrusDataSourceFieldsOptions`	Hook options.
`UseDocyrusDataSourceFieldsResult`	Hook result.

useDocyrusDataSourceFields

On this page