Express CSV Logo

Types

Use x.row() to define the schema you pass to CSVImporter. Each field controls how uploaded values are parsed, validated, labeled, and typed before they reach your app.

Basic Usage

import { CSVImporter, x, type Infer } from "@expresscsv/sdk";

const userSchema = x.row({
  name: x.string().label("Full Name"),
  email: x.string().email().label("Email Address"),
  age: x.number().label("Age").min(18),
  startDate: x.date().label("Start Date"),
  active: x.boolean().label("Active").optional(),
});

type UserRow = Infer<typeof userSchema>;

const importer = new CSVImporter({
  schema: userSchema,
  publishableKey: "pk_test_...",
  importIdentifier: "user-import",
});

importer.open({
  onData: async (chunk, next) => {
    const records: UserRow[] = chunk.records;
    await saveImportedUsers(records);
    next();
  },
});

Each key becomes a column the user maps to. The field type determines how values are parsed and validated before your onData callback or webhook runs.

Field Types

Custom Validation

Use Refine for custom validators with .refine(), .refineBatch(), and suggested fixes.

Dynamic Schemas

You can build the schema conditionally before constructing CSVImporter:

function buildSchema(includeVatId: boolean) {
  return x.row({
    companyName: x.string(),
    email: x.string().email(),
    ...(includeVatId ? { vatId: x.string() } : {}),
  });
}

const schema = buildSchema(true);

const importer = new CSVImporter({
  schema,
  publishableKey: "pk_test_...",
  importIdentifier: "company-import",
});

TypeScript Inference

Use Infer<typeof schema> to extract the validated row type from your schema:

import { x, type Infer } from "@expresscsv/sdk";

const schema = x.row({
  name: x.string(),
  age: x.number(),
  active: x.boolean().optional(),
});

type Row = Infer<typeof schema>;
// { name: string; age: number; active?: boolean }

When you use that schema with CSVImporter, chunk.records is inferred automatically inside onData, so you usually do not need manual type annotations.

On this page

Basic UsageField TypesCustom ValidationDynamic SchemasTypeScript Inference