@expresscsv/schemas

Schema authoring and type inference for ExpressCSV, without the importer launcher.

Use this package when you want to define schemas in shared or backend code without pulling in any frontend, importer, or React dependencies.

Usage

import { type Infer, x } from '@expresscsv/schemas';

const employeeSchema = x.row({
  name: x.string(),
  email: x.string().email(),
  salary: x.number().currency('USD').optional(),
});

type Employee = Infer<typeof employeeSchema>;

Shared And Backend Code

Because @expresscsv/schemas has no frontend launcher dependencies, you can define your schema once in shared code and reuse its inferred type across your frontend and backend.

import { type Infer, x } from '@expresscsv/schemas';

export const employeeSchema = x.row({
  email: x.string().email().label('Email'),
  name: x.string().label('Full Name'),
  startDate: x.date().optional().label('Start Date'),
});

export type Employee = Infer<typeof employeeSchema>;

Runtime-Built Schemas

If your backend or shared code has a fixed schema, model it with x.row(...):

import { x } from '@expresscsv/schemas';

export const customerSchema = x.row({
  email: x.string().email().label('Email'),
  lifecycleStage: x
    .select([
      { label: 'Lead', value: 'lead' },
      { label: 'Customer', value: 'customer' },
      { label: 'Churned', value: 'churned' },
    ])
    .label('Lifecycle Stage'),
  accountOwner: x.string().label('Account Owner').optional(),
});

x.row(...) also works for runtime-built schemas, which is useful when the shape depends on account data, user preferences, or enabled custom fields.

import { x } from '@expresscsv/schemas';

export function buildCustomerSchema(options: {
  collectCrmId: boolean;
  collectHealthScore: boolean;
  collectSegment: boolean;
}) {
  return x.row({
    email: x.string().email().label('Email'),
    companyName: x.string().label('Company Name'),
    ...(options.collectCrmId ? { crmId: x.string().label('CRM ID') } : {}),
    ...(options.collectHealthScore
      ? { healthScore: x.number().label('Health Score') }
      : {}),
    ...(options.collectSegment
      ? {
          segment: x
            .select([
              { label: 'SMB', value: 'smb' },
              { label: 'Mid-Market', value: 'mid-market' },
              { label: 'Enterprise', value: 'enterprise' },
            ])
            .label('Segment'),
        }
      : {}),
  });
}

const customerSchema = buildCustomerSchema({
  collectCrmId: true,
  collectHealthScore: false,
  collectSegment: true,
});

Dynamic schema assembly preserves the same runtime parsing behavior, but it can widen Infer<typeof schema> because the exact keys are no longer fully known to TypeScript. Use it intentionally.

Exports

x
Infer
ExType
ExBaseDef
ExRow
ExRowShape
ExRowWithOptionalColumns

Not included

This package intentionally does not export the importer launcher, React bindings, or importer configuration types. Use @expresscsv/sdk or @expresscsv/react for those integration surfaces.