or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

Files

docs

application-setup.mdauthentication.mddata-operations.mdforms.mdindex.mdnavigation.mdtables-lists.mdutilities.md

data-operations.mddocs/

0

# Data Operations & CRUD Hooks

1

2

Comprehensive data management hooks for CRUD operations, custom queries, and real-time data synchronization.

3

4

## Capabilities

5

6

### Query Hooks

7

8

#### useList Hook

9

10

Fetches multiple records from a resource with support for pagination, filtering, sorting, and real-time updates.

11

12

```typescript { .api }

13

/**

14

* Fetches multiple records from a resource with comprehensive query options

15

* @param params - Configuration for the list query

16

* @returns Query result with data and pagination information

17

*/

18

function useList<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(

19

params?: UseListConfig<TQueryFnData, TError, TData>

20

): UseListReturnType<TData, TError>;

21

22

interface UseListConfig<TQueryFnData, TError, TData> {

23

/** Resource name - inferred from route if not provided */

24

resource?: string;

25

/** Pagination configuration */

26

pagination?: Pagination;

27

/** Sorting configuration */

28

sorters?: CrudSorting;

29

/** Filtering configuration */

30

filters?: CrudFilters;

31

/** Additional metadata for the query */

32

meta?: MetaQuery;

33

/** Specific data provider to use */

34

dataProviderName?: string;

35

/** React Query options */

36

queryOptions?: UseQueryOptions<GetListResponse<TQueryFnData>, TError>;

37

/** Success notification configuration */

38

successNotification?: SuccessErrorNotification | false;

39

/** Error notification configuration */

40

errorNotification?: SuccessErrorNotification | false;

41

/** Live mode configuration */

42

liveMode?: LiveModeProps;

43

/** Callback when live event received */

44

onLiveEvent?: (event: LiveEvent) => void;

45

/** Auto-invalidation configuration */

46

invalidates?: Array<string>;

47

/** Override mutation mode */

48

mutationMode?: MutationMode;

49

}

50

51

interface UseListReturnType<TData, TError> {

52

/** React Query result object */

53

query: UseQueryResult<GetListResponse<TData>, TError>;

54

/** Processed result with data and total */

55

result: {

56

data: TData[];

57

total: number | undefined;

58

};

59

}

60

```

61

62

**Usage Example:**

63

64

```typescript

65

import { useList } from "@refinedev/core";

66

67

function PostsList() {

68

const { data: posts, isLoading, error } = useList({

69

resource: "posts",

70

pagination: {

71

current: 1,

72

pageSize: 10,

73

mode: "server"

74

},

75

sorters: [{

76

field: "createdAt",

77

order: "desc"

78

}],

79

filters: [{

80

field: "status",

81

operator: "eq",

82

value: "published"

83

}],

84

meta: {

85

populate: ["author", "category"]

86

}

87

});

88

89

if (isLoading) return <div>Loading...</div>;

90

if (error) return <div>Error: {error.message}</div>;

91

92

return (

93

<div>

94

{posts?.data.map(post => (

95

<article key={post.id}>

96

<h3>{post.title}</h3>

97

<p>{post.content}</p>

98

</article>

99

))}

100

</div>

101

);

102

}

103

```

104

105

#### useOne Hook

106

107

Fetches a single record by its identifier with support for real-time updates and caching.

108

109

```typescript { .api }

110

/**

111

* Fetches a single record by ID

112

* @param params - Configuration for the single record query

113

* @returns Query result with the fetched record

114

*/

115

function useOne<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(

116

params: UseOneConfig<TQueryFnData, TError, TData>

117

): UseOneReturnType<TData, TError>;

118

119

interface UseOneConfig<TQueryFnData, TError, TData> {

120

/** Resource name - inferred from route if not provided */

121

resource?: string;

122

/** Record identifier to fetch */

123

id: BaseKey;

124

/** Additional metadata for the query */

125

meta?: MetaQuery;

126

/** Specific data provider to use */

127

dataProviderName?: string;

128

/** React Query options */

129

queryOptions?: UseQueryOptions<GetOneResponse<TQueryFnData>, TError>;

130

/** Success notification configuration */

131

successNotification?: SuccessErrorNotification | false;

132

/** Error notification configuration */

133

errorNotification?: SuccessErrorNotification | false;

134

/** Live mode configuration */

135

liveMode?: LiveModeProps;

136

/** Callback when live event received */

137

onLiveEvent?: (event: LiveEvent) => void;

138

}

139

140

interface UseOneReturnType<TData, TError> {

141

/** React Query result object */

142

query: UseQueryResult<GetOneResponse<TData>, TError>;

143

}

144

```

145

146

#### useMany Hook

147

148

Fetches multiple records by their identifiers in a single request.

149

150

```typescript { .api }

151

/**

152

* Fetches multiple records by their IDs

153

* @param params - Configuration for the multiple records query

154

* @returns Query result with the fetched records

155

*/

156

function useMany<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(

157

params: UseManyConfig<TQueryFnData, TError, TData>

158

): UseManyReturnType<TData, TError>;

159

160

interface UseManyConfig<TQueryFnData, TError, TData> {

161

/** Resource name - inferred from route if not provided */

162

resource?: string;

163

/** Array of record identifiers to fetch */

164

ids: BaseKey[];

165

/** Additional metadata for the query */

166

meta?: MetaQuery;

167

/** Specific data provider to use */

168

dataProviderName?: string;

169

/** React Query options */

170

queryOptions?: UseQueryOptions<GetManyResponse<TQueryFnData>, TError>;

171

/** Success notification configuration */

172

successNotification?: SuccessErrorNotification | false;

173

/** Error notification configuration */

174

errorNotification?: SuccessErrorNotification | false;

175

/** Live mode configuration */

176

liveMode?: LiveModeProps;

177

/** Callback when live event received */

178

onLiveEvent?: (event: LiveEvent) => void;

179

}

180

181

interface UseManyReturnType<TData, TError> {

182

/** React Query result object */

183

query: UseQueryResult<GetManyResponse<TData>, TError>;

184

}

185

```

186

187

#### useInfiniteList Hook

188

189

Provides infinite scrolling functionality for large datasets with incremental loading.

190

191

```typescript { .api }

192

/**

193

* Provides infinite scrolling/pagination functionality

194

* @param params - Configuration for infinite list query

195

* @returns Infinite query result with pagination controls

196

*/

197

function useInfiniteList<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(

198

params?: UseInfiniteListConfig<TQueryFnData, TError, TData>

199

): UseInfiniteListReturnType<TData, TError>;

200

201

interface UseInfiniteListConfig<TQueryFnData, TError, TData> {

202

/** Resource name */

203

resource?: string;

204

/** Pagination configuration */

205

pagination?: Pagination;

206

/** Sorting configuration */

207

sorters?: CrudSorting;

208

/** Filtering configuration */

209

filters?: CrudFilters;

210

/** Additional metadata */

211

meta?: MetaQuery;

212

/** Data provider name */

213

dataProviderName?: string;

214

/** React Query infinite options */

215

queryOptions?: UseInfiniteQueryOptions<GetListResponse<TQueryFnData>, TError>;

216

/** Success notification */

217

successNotification?: SuccessErrorNotification | false;

218

/** Error notification */

219

errorNotification?: SuccessErrorNotification | false;

220

}

221

222

interface UseInfiniteListReturnType<TData, TError> {

223

/** React Query infinite result */

224

query: UseInfiniteQueryResult<InfiniteData<GetListResponse<TData>>, TError>;

225

/** Flattened data from all pages */

226

data: TData[] | undefined;

227

/** Total count across all pages */

228

total: number | undefined;

229

/** Whether more data can be fetched */

230

hasNextPage: boolean | undefined;

231

/** Function to fetch next page */

232

fetchNextPage: () => void;

233

/** Whether next page is being fetched */

234

isFetchingNextPage: boolean;

235

}

236

```

237

238

### Mutation Hooks

239

240

#### useCreate Hook

241

242

Creates new records with support for optimistic updates, notifications, and cache invalidation.

243

244

```typescript { .api }

245

/**

246

* Creates a new record with mutation handling

247

* @param params - Configuration for the create mutation

248

* @returns Mutation function and state

249

*/

250

function useCreate<TData = BaseRecord, TError = HttpError, TVariables = {}>(

251

params?: UseCreateConfig<TData, TError, TVariables>

252

): UseCreateReturnType<TData, TError, TVariables>;

253

254

interface UseCreateConfig<TData, TError, TVariables> {

255

/** React Query mutation options */

256

mutationOptions?: UseMutationOptions<CreateResponse<TData>, TError, UseCreateParams<TVariables>>;

257

}

258

259

interface UseCreateReturnType<TData, TError, TVariables> {

260

/** Mutation function to execute create */

261

mutate: (params: UseCreateParams<TVariables>, options?: MutationObserverOptions<CreateResponse<TData>, TError, UseCreateParams<TVariables>>) => void;

262

/** Async mutation function */

263

mutateAsync: (params: UseCreateParams<TVariables>, options?: MutationObserverOptions<CreateResponse<TData>, TError, UseCreateParams<TVariables>>) => Promise<CreateResponse<TData>>;

264

/** React Query mutation result */

265

mutation: UseMutationResult<CreateResponse<TData>, TError, UseCreateParams<TVariables>>;

266

}

267

268

interface UseCreateParams<TVariables> {

269

/** Resource name */

270

resource: string;

271

/** Data to create */

272

values: TVariables;

273

/** Additional metadata */

274

meta?: MetaQuery;

275

/** Data provider name */

276

dataProviderName?: string;

277

/** Cache invalidation configuration */

278

invalidates?: Array<string>;

279

/** Success notification */

280

successNotification?: SuccessErrorNotification | false;

281

/** Error notification */

282

errorNotification?: SuccessErrorNotification | false;

283

/** Override mutation mode */

284

mutationMode?: MutationMode;

285

/** Timeout for undoable mutations */

286

undoableTimeout?: number;

287

}

288

```

289

290

**Usage Example:**

291

292

```typescript

293

import { useCreate } from "@refinedev/core";

294

295

function CreatePostForm() {

296

const { mutate: createPost, isLoading } = useCreate();

297

298

const handleSubmit = (values: { title: string; content: string }) => {

299

createPost({

300

resource: "posts",

301

values,

302

successNotification: {

303

message: "Post created successfully!",

304

description: "Your new post has been published.",

305

type: "success"

306

},

307

meta: {

308

populate: ["author"]

309

}

310

});

311

};

312

313

return (

314

<form onSubmit={handleSubmit}>

315

{/* Form fields */}

316

<button type="submit" disabled={isLoading}>

317

{isLoading ? "Creating..." : "Create Post"}

318

</button>

319

</form>

320

);

321

}

322

```

323

324

#### useUpdate Hook

325

326

Updates existing records with optimistic updates and undoable operations.

327

328

```typescript { .api }

329

/**

330

* Updates an existing record with mutation handling

331

* @param params - Configuration for the update mutation

332

* @returns Mutation function and state

333

*/

334

function useUpdate<TData = BaseRecord, TError = HttpError, TVariables = {}>(

335

params?: UseUpdateConfig<TData, TError, TVariables>

336

): UseUpdateReturnType<TData, TError, TVariables>;

337

338

interface UseUpdateConfig<TData, TError, TVariables> {

339

/** React Query mutation options */

340

mutationOptions?: UseMutationOptions<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>;

341

}

342

343

interface UseUpdateReturnType<TData, TError, TVariables> {

344

/** Mutation function to execute update */

345

mutate: (params: UseUpdateParams<TVariables>, options?: MutationObserverOptions<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>) => void;

346

/** Async mutation function */

347

mutateAsync: (params: UseUpdateParams<TVariables>, options?: MutationObserverOptions<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>) => Promise<UpdateResponse<TData>>;

348

/** React Query mutation result */

349

mutation: UseMutationResult<UpdateResponse<TData>, TError, UseUpdateParams<TVariables>>;

350

}

351

352

interface UseUpdateParams<TVariables> {

353

/** Resource name */

354

resource: string;

355

/** Record identifier to update */

356

id: BaseKey;

357

/** Data to update */

358

values: TVariables;

359

/** Additional metadata */

360

meta?: MetaQuery;

361

/** Data provider name */

362

dataProviderName?: string;

363

/** Cache invalidation configuration */

364

invalidates?: Array<string>;

365

/** Success notification */

366

successNotification?: SuccessErrorNotification | false;

367

/** Error notification */

368

errorNotification?: SuccessErrorNotification | false;

369

/** Override mutation mode */

370

mutationMode?: MutationMode;

371

/** Timeout for undoable mutations */

372

undoableTimeout?: number;

373

}

374

```

375

376

#### useDelete Hook

377

378

Deletes records with support for soft delete, confirmations, and undo functionality.

379

380

```typescript { .api }

381

/**

382

* Deletes a record with mutation handling

383

* @param params - Configuration for the delete mutation

384

* @returns Mutation function and state

385

*/

386

function useDelete<TData = BaseRecord, TError = HttpError>(

387

params?: UseDeleteConfig<TData, TError>

388

): UseDeleteReturnType<TData, TError>;

389

390

interface UseDeleteConfig<TData, TError> {

391

/** React Query mutation options */

392

mutationOptions?: UseMutationOptions<DeleteOneResponse<TData>, TError, UseDeleteParams>;

393

}

394

395

interface UseDeleteReturnType<TData, TError> {

396

/** Mutation function to execute delete */

397

mutate: (params: UseDeleteParams, options?: MutationObserverOptions<DeleteOneResponse<TData>, TError, UseDeleteParams>) => void;

398

/** Async mutation function */

399

mutateAsync: (params: UseDeleteParams, options?: MutationObserverOptions<DeleteOneResponse<TData>, TError, UseDeleteParams>) => Promise<DeleteOneResponse<TData>>;

400

/** React Query mutation result */

401

mutation: UseMutationResult<DeleteOneResponse<TData>, TError, UseDeleteParams>;

402

}

403

404

interface UseDeleteParams {

405

/** Resource name */

406

resource: string;

407

/** Record identifier to delete */

408

id: BaseKey;

409

/** Additional metadata */

410

meta?: MetaQuery;

411

/** Data provider name */

412

dataProviderName?: string;

413

/** Cache invalidation configuration */

414

invalidates?: Array<string>;

415

/** Success notification */

416

successNotification?: SuccessErrorNotification | false;

417

/** Error notification */

418

errorNotification?: SuccessErrorNotification | false;

419

/** Override mutation mode */

420

mutationMode?: MutationMode;

421

/** Timeout for undoable mutations */

422

undoableTimeout?: number;

423

}

424

```

425

426

### Bulk Operations

427

428

#### useCreateMany Hook

429

430

Creates multiple records in a single operation for batch processing.

431

432

```typescript { .api }

433

/**

434

* Creates multiple records in batch

435

* @param params - Configuration for the bulk create mutation

436

* @returns Mutation function and state for bulk creation

437

*/

438

function useCreateMany<TData = BaseRecord, TError = HttpError, TVariables = {}>(

439

params?: UseCreateManyConfig<TData, TError, TVariables>

440

): UseCreateManyReturnType<TData, TError, TVariables>;

441

442

interface UseCreateManyParams<TVariables> {

443

/** Resource name */

444

resource: string;

445

/** Array of data to create */

446

values: TVariables[];

447

/** Additional metadata */

448

meta?: MetaQuery;

449

/** Data provider name */

450

dataProviderName?: string;

451

/** Cache invalidation configuration */

452

invalidates?: Array<string>;

453

/** Success notification */

454

successNotification?: SuccessErrorNotification | false;

455

/** Error notification */

456

errorNotification?: SuccessErrorNotification | false;

457

}

458

```

459

460

#### useUpdateMany Hook

461

462

Updates multiple records by their identifiers in a single operation.

463

464

```typescript { .api }

465

/**

466

* Updates multiple records in batch

467

* @param params - Configuration for the bulk update mutation

468

* @returns Mutation function and state for bulk updates

469

*/

470

function useUpdateMany<TData = BaseRecord, TError = HttpError, TVariables = {}>(

471

params?: UseUpdateManyConfig<TData, TError, TVariables>

472

): UseUpdateManyReturnType<TData, TError, TVariables>;

473

474

interface UseUpdateManyParams<TVariables> {

475

/** Resource name */

476

resource: string;

477

/** Array of record identifiers to update */

478

ids: BaseKey[];

479

/** Data to update */

480

values: TVariables;

481

/** Additional metadata */

482

meta?: MetaQuery;

483

/** Data provider name */

484

dataProviderName?: string;

485

/** Cache invalidation configuration */

486

invalidates?: Array<string>;

487

/** Success notification */

488

successNotification?: SuccessErrorNotification | false;

489

/** Error notification */

490

errorNotification?: SuccessErrorNotification | false;

491

}

492

```

493

494

#### useDeleteMany Hook

495

496

Deletes multiple records by their identifiers in a single operation.

497

498

```typescript { .api }

499

/**

500

* Deletes multiple records in batch

501

* @param params - Configuration for the bulk delete mutation

502

* @returns Mutation function and state for bulk deletion

503

*/

504

function useDeleteMany<TData = BaseRecord, TError = HttpError>(

505

params?: UseDeleteManyConfig<TData, TError>

506

): UseDeleteManyReturnType<TData, TError>;

507

508

interface UseDeleteManyParams {

509

/** Resource name */

510

resource: string;

511

/** Array of record identifiers to delete */

512

ids: BaseKey[];

513

/** Additional metadata */

514

meta?: MetaQuery;

515

/** Data provider name */

516

dataProviderName?: string;

517

/** Cache invalidation configuration */

518

invalidates?: Array<string>;

519

/** Success notification */

520

successNotification?: SuccessErrorNotification | false;

521

/** Error notification */

522

errorNotification?: SuccessErrorNotification | false;

523

}

524

```

525

526

### Custom Data Operations

527

528

#### useCustom Hook

529

530

Executes custom API queries that don't fit standard CRUD patterns.

531

532

```typescript { .api }

533

/**

534

* Executes custom API queries

535

* @param params - Configuration for custom query

536

* @returns Query result with custom data

537

*/

538

function useCustom<TQueryFnData = BaseRecord, TError = HttpError, TData = TQueryFnData>(

539

params: UseCustomConfig<TQueryFnData, TError, TData>

540

): UseCustomReturnType<TData, TError>;

541

542

interface UseCustomConfig<TQueryFnData, TError, TData> {

543

/** Custom URL endpoint */

544

url: string;

545

/** HTTP method */

546

method: "get" | "delete" | "head" | "options" | "post" | "put" | "patch";

547

/** Additional configuration */

548

config?: {

549

/** Request headers */

550

headers?: Record<string, string>;

551

/** URL query parameters */

552

query?: Record<string, any>;

553

/** Request payload */

554

payload?: Record<string, any>;

555

/** Request filters */

556

filters?: CrudFilters;

557

/** Request sorters */

558

sorters?: CrudSorting;

559

/** Pagination */

560

pagination?: Pagination;

561

};

562

/** Additional metadata */

563

meta?: MetaQuery;

564

/** Data provider name */

565

dataProviderName?: string;

566

/** React Query options */

567

queryOptions?: UseQueryOptions<CustomResponse<TQueryFnData>, TError>;

568

/** Success notification */

569

successNotification?: SuccessErrorNotification | false;

570

/** Error notification */

571

errorNotification?: SuccessErrorNotification | false;

572

}

573

574

interface UseCustomReturnType<TData, TError> {

575

/** React Query result */

576

query: UseQueryResult<CustomResponse<TData>, TError>;

577

}

578

579

interface CustomResponse<TData> {

580

data: TData;

581

}

582

```

583

584

#### useCustomMutation Hook

585

586

Executes custom API mutations for non-standard operations.

587

588

```typescript { .api }

589

/**

590

* Executes custom API mutations

591

* @param params - Configuration for custom mutation

592

* @returns Mutation function and state

593

*/

594

function useCustomMutation<TData = BaseRecord, TError = HttpError, TVariables = {}>(

595

params?: UseCustomMutationConfig<TData, TError, TVariables>

596

): UseCustomMutationReturnType<TData, TError, TVariables>;

597

598

interface UseCustomMutationConfig<TData, TError, TVariables> {

599

/** React Query mutation options */

600

mutationOptions?: UseMutationOptions<CustomResponse<TData>, TError, UseCustomMutationParams<TVariables>>;

601

}

602

603

interface UseCustomMutationParams<TVariables> {

604

/** Custom URL endpoint */

605

url: string;

606

/** HTTP method */

607

method: "get" | "delete" | "head" | "options" | "post" | "put" | "patch";

608

/** Request configuration */

609

config?: {

610

/** Request headers */

611

headers?: Record<string, string>;

612

/** Request payload */

613

payload?: TVariables;

614

};

615

/** Additional metadata */

616

meta?: MetaQuery;

617

/** Data provider name */

618

dataProviderName?: string;

619

/** Success notification */

620

successNotification?: SuccessErrorNotification | false;

621

/** Error notification */

622

errorNotification?: SuccessErrorNotification | false;

623

}

624

```

625

626

### Data Provider Utilities

627

628

#### useDataProvider Hook

629

630

Provides direct access to the data provider instance for advanced operations.

631

632

```typescript { .api }

633

/**

634

* Gets access to the data provider instance

635

* @returns Data provider instance or provider map

636

*/

637

function useDataProvider(): DataProviderResult;

638

639

type DataProviderResult = DataProvider | Record<string, DataProvider>;

640

```

641

642

#### useApiUrl Hook

643

644

Generates the base API URL for a specific resource using the data provider.

645

646

```typescript { .api }

647

/**

648

* Gets the API URL for a resource

649

* @param params - Configuration for API URL generation

650

* @returns Query result with the API URL

651

*/

652

function useApiUrl(params?: UseApiUrlConfig): UseApiUrlReturnType;

653

654

interface UseApiUrlConfig {

655

/** Data provider name */

656

dataProviderName?: string;

657

}

658

659

interface UseApiUrlReturnType {

660

/** Query result with API URL */

661

query: UseQueryResult<string, Error>;

662

}

663

```

664

665

## Types

666

667

```typescript { .api }

668

interface MetaQuery {

669

[key: string]: any;

670

}

671

672

interface SuccessErrorNotification {

673

message: string;

674

description?: string;

675

type: "success" | "error" | "progress";

676

}

677

678

interface LiveEvent {

679

channel: string;

680

type: "created" | "updated" | "deleted";

681

payload: {

682

ids?: BaseKey[];

683

[key: string]: any;

684

};

685

date: Date;

686

}

687

688

interface GetListParams {

689

resource: string;

690

pagination?: Pagination;

691

sorters?: CrudSorting;

692

filters?: CrudFilters;

693

meta?: MetaQuery;

694

}

695

696

interface GetOneParams {

697

resource: string;

698

id: BaseKey;

699

meta?: MetaQuery;

700

}

701

702

interface GetManyParams {

703

resource: string;

704

ids: BaseKey[];

705

meta?: MetaQuery;

706

}

707

708

interface CreateParams<TVariables> {

709

resource: string;

710

variables: TVariables;

711

meta?: MetaQuery;

712

}

713

714

interface UpdateParams<TVariables> {

715

resource: string;

716

id: BaseKey;

717

variables: TVariables;

718

meta?: MetaQuery;

719

}

720

721

interface DeleteOneParams {

722

resource: string;

723

id: BaseKey;

724

meta?: MetaQuery;

725

}

726

727

interface CustomParams {

728

url: string;

729

method: "get" | "delete" | "head" | "options" | "post" | "put" | "patch";

730

filters?: CrudFilters;

731

sorters?: CrudSorting;

732

pagination?: Pagination;

733

payload?: Record<string, any>;

734

query?: Record<string, any>;

735

headers?: Record<string, string>;

736

meta?: MetaQuery;

737

}

738

```