Flat API ClientSide DataProvider
The CAPIFlatClientDataProvider extends the standard ClientSide provider to interact directly with internal or external APIs via the RequestProvider to manage flat data structures.
This provider manages data fetching, caching strategies, and deduplication for API requests, updating the local UI state dynamically.
Extends: Flat ClientSide DataProvider
Uses: RequestProvider
// --- Client Side (Vue) ---
import { CAPIFlatClientDataProvider } from '@katlux/providers/data'
const provider = new CAPIFlatClientDataProvider({
cacheStrategy: 'Memory',
cacheLifetime: 60000,
refreshOnMutation: true
})
await provider.setAPIUrl('/api/v1/users') // Automatically fetches all data
// Performs POST /api/v1/users and refreshes list if refreshOnMutation is true
await provider.create({ name: 'Jane Doe' })
// --- Server Side (Nuxt Nitro) ---
// server/api/v1/users.get.ts
export default defineEventHandler(async (event) => {
// ClientSide providers fetch the entire dataset directly
// Pagination and filtering occurs locally in the browser.
const allData = await fetchDatabaseUsers()
// Expected structure by the Datatable and Katlux toolkit: { rows: Array<any>, rowCount: number }
// rows: Must be a flat array of objects, e.g. [{id: 1, name: 'A'}, {id: 2, name: 'B'}]
return {
rows: allData,
rowCount: allData.length
}
})
// server/api/v1/users.post.ts
export default defineEventHandler(async (event) => {
// Data arrives exactly as sent by the client `provider.create({ name: 'Jane Doe' })`
const body = await readBody(event) // Format: { name: 'Jane Doe' }
const newUser = await insertDatabaseUser(body)
// Returning the inserted object integrates it back into the local cached DataProvider structure
// Expected returned format: { id: 1, name: 'Jane Doe' }
return newUser
})Configuration options passed when initializing the API provider.
| Property | Type | Default | Description |
|---|---|---|---|
| pageSize | number | 10 | Number of items to display per page |
| currentPage | number | 1 | Initial page to display |
| filter | IDataFilter | null | Initial filter configuration |
| sortList | IDataSort[] | [] | Initial sorting configuration |
| SSR | boolean | false | Indicates if Server Side Rendering requests are executed |
| cacheStrategy | ECacheStrategy | null | Defines the caching behavior for the RequestProvider integration |
| cacheLifetime | number | 0 | Cache TTL in milliseconds |
| deduplicate | boolean | true | Whether to deduplicate identical concurrent requests |
| refreshOnMutation | boolean | false | Re-fetches the entire list globally via API if create/update/delete are successfully resolved |
| urlPageParam | string | '' | URL query parameter key for two-way page synchronization (e.g., 'page') |
Provides full control over data fetching, pagination, and state.
| Name | Type | Description |
|---|---|---|
| pageSize | Ref<number> | Current items per page (writable) |
| currentPage | Ref<number> | Current active page (writable) |
| rowCount | Ref<number> | Total number of items after filtering |
| loading | Ref<boolean> | Reactive loading state |
| pageData | Ref<any[]> | Array of items for the currently active page |
| apiUrl | Ref<string> | The endpoint used by RequestProvider |
| setAPIUrl | (url: string) => Promise<void> | Sets the URL and immediately fetches data |
| refresh | (hardRefresh?: boolean) => Promise<void> | Re-fetches data from source. Cache will only be overridden if hardRefresh is true. |
| setFilter | (filter: IDataFilter | null) => void | Updates the active filter and resets pagination |
| setSortList | (sort: IDataSort[]) => void | Updates the active sorting and resets pagination |
| create / update | (item: any) => Promise<void> | Performs API mutations (POST/PUT) |
| delete | (items: any[]) => Promise<void> | Performs API deletion (DELETE) |
Note: Unlike server-side providers, client-side API providers do not use a TPageDataHandler. The entire dataset is loaded once into the client browser via the API endpoint, and pagination/filtering/sorting are managed locally.
Each row returned by the API must be a plain object with a unique identifier field (default: id). The full dataset is fetched once and managed locally — filtering and sorting happen on the client.
// Server response shape (fetched once at setAPIUrl)
{
rowCount: 42,
rows: [
{ id: 1, name: 'Alice', role: 'Admin' },
{ id: 2, name: 'Bob', role: 'User' }
]
}The id field name is configurable via the idKey constructor option.