https://github.com/sidwebworks/zod-xlsx
A xlsx based resource validator using Zod schemas for data imports and more
https://github.com/sidwebworks/zod-xlsx
async-validation node validation xlsx zod
Last synced: 7 months ago
JSON representation
A xlsx based resource validator using Zod schemas for data imports and more
- Host: GitHub
- URL: https://github.com/sidwebworks/zod-xlsx
- Owner: sidwebworks
- License: mit
- Created: 2022-06-13T08:17:49.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-06-15T13:16:37.000Z (11 months ago)
- Last Synced: 2025-09-29T12:40:25.270Z (7 months ago)
- Topics: async-validation, node, validation, xlsx, zod
- Language: TypeScript
- Homepage:
- Size: 149 KB
- Stars: 46
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ZOD-XLSX
[](https://www.npmjs.com/package/zod-xlsx)
[](https://github.com/semantic-release/semantic-release)
> A xlsx based resource validator using Zod schemas
**Supports both ESM and CJS**
## Installation
> Note:
> This package requires [Zod](https://www.npmjs.com/package/zod) and [xlsx](https://www.npmjs.com/package/xlsx) as peer dependencies
```bash
# 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.
```ts
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**
```js
{
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.
```ts
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](https://docs.sheetjs.com/docs/api/utilities#json)
### **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](https://github.com/sidwebworks)