sidwebworks/zod-xlsx

README

ZOD-XLSX

A xlsx based resource validator using Zod schemas

Supports both ESM and CJS

Installation

Note: This package requires Zod and xlsx as peer dependencies

# With npm
npm install zod-xlsx xlsx zod

# With yarn
yarn add zod-xlsx xlsx zod

# With pnpm
pnpm add zod-xlsx xlsx zod

Usage

The library exports a single function called createValidator which takes in a xlsx workbook and creates a validator object.

Please make sure your top row of the sheet (xlsx or xls) file contains only header content for the columns as it's required for the library to function properly.

import { createValidator } from "zod-xlsx"
import xlsx from "xlsx"

const workbook = xlsx.readFile(/*path to your file*/)

const validator = createValidator(workbook)

const schema = z.object({
  "First Name": z.string(),
  "Last Name": z.string(),
  Gender: z.enum(["Male", "Female"]),
  Country: z.string(),
  Age: z.number(),
  Date: z.string(),
  Id: z.number(),
})

const result = validator.validate(schema)

OUTPUT

{
  valid: [
    { issues: [], isValid: true, data: [Object] },
    { issues: [], isValid: true, data: [Object] },
    { issues: [], isValid: true, data: [Object] },
    { issues: [], isValid: true, data: [Object] },
  ]
  invalid: [
    { issues: [Object], isValid: false, data: [Object] },
    { issues: [Object], isValid: false, data: [Object] },
    { issues: [Object], isValid: false, data: [Object] },
  ]
}

API Reference

createValidator

Function to create a new validator object with the given workbook. It takes an options object as the second arguement.

export interface ValidatorOptions {
  // Comes from xlsx
  header?: Sheet2JSONOpts["header"]
  blankrows?: Sheet2JSONOpts["blankrows"]
  skipHidden?: Sheet2JSONOpts["skipHidden"]

  // Zod-xlsx options
  sheetName?: string
  onValid?: (data: any) => void
  onInvalid?: (data: any) => void
}

sheetName: name of the sheet to use, defaults to the first sheet in the document.
onValid: hook which gets called after every valid item is processed.
onValid: hook which gets called after every invalid item is processed.

For details on what each of the xlsx option does can be found: Here

validator.validate()

Synchronously parses all the rows against the given schema and returns the result.

validator.validateAsync()

Asynchronously parses all the rows against the given schema without blocking the event loop, it does this using batch processing. (500 is the default batch size)

Depending on your usecase, its possible to configure the batchSize like so: validateAsync(schema, { batchSize: 500 }).

License

MIT © sidwebworks