React Adapter
Using IngestX deeply within React
If you are building a React application, the core @izanagi-labs/ingestx library directly. However, wiring up state, progress indicators, and cancellation logic manually can require boilerplate.
The @izanagi-labs/ingestx/react sub package provides a specialized useIngest hook that manages the entire lifecycle of an ingestion internally, exposing reactive state variables ready to map directly to your UI.
Import
import { useIngest } from "@izanagi-labs/ingestx/react";useIngest Hook
The hook takes no initial arguments. It returns a tuple of state variables and control functions.
const {
ingest, // Function to start ingestion
pause, // Function to pause active ingestion
resume, // Function to resume paused ingestion
cancel, // Function to halt ingestion
reset, // Function to clear results/errors to initial state
status, // Current IngestionStatus
progress, // Current Progress object
result, // FinalOutput when completed
error, // IngestionError when failed
} = useIngest<MyDataRow>();Example Implementation
This practical component demonstrates how to bind an <input type="file"> to the useIngest hook, visualizing progress and handling both successful parsing and validation failures.
import React from 'react';
import { useIngest } from '@izanagi-labs/ingestx/react';
import { ix } from '@izanagi-labs/ingestx';
import type { ColumnConfig } from '@izanagi-labs/ingestx';
const columns: ColumnConfig[] = [
{ key: "id", name: "User ID", schema: ix.string() },
{ key: "age", name: "Age", schema: ix.number().min(18) }
];
export function IngestionComponent() {
const { ingest, status, progress, result, error, cancel, reset } = useIngest();
const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
const file = e.target.files?.[0];
if (!file) return;
try {
await ingest({
file,
columns,
collectResults: true, // We want the data returned into the `result` state
chunkSize: 5000,
});
} catch (err) {
console.error("Ingestion failed to start:", err);
}
};
return (
<div className="p-4 border rounded shadow">
<h2 className="text-xl mb-4">Upload Users</h2>
{status === 'idle' && (
<input type="file" accept=".csv,.xlsx" onChange={handleFileChange} />
)}
{status === 'running' && progress && (
<div>
<p>Processing: {(progress.percentage ?? 0 * 100).toFixed(0)}%</p>
<p>Rows: {progress.processedRows}</p>
<button onClick={cancel} className="text-red-500">Cancel</button>
</div>
)}
{status === 'completed' && result && (
<div>
<h3 className="text-green-600">Complete!</h3>
<p>Valid Rows: {result.validRowsCount}</p>
<p>Invalid Rows: {result.invalidRowsCount}</p>
<button onClick={reset}>Upload Another</button>
</div>
)}
{status === 'failed' && error && (
<div className="text-red-600">
<h3>Error: {error.type}</h3>
<p>{error.message}</p>
<button onClick={reset}>Try Again</button>
</div>
)}
</div>
);
}Concurrency Guards
The useIngest hook is designed to safely handle React component unmounts and prevent overlapping runs:
- Unmount Safety: If the component unmounts while ingestion is running, the hook automatically invokes
cancel()internally. - Single Run: If
ingest()is called while a run is already active (e.g.status === 'running'), it throws an error immediately to prevent concurrent state pollution.