read-excel-file 9.0.5 → 9.0.7

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+9.0.7 / 28.04.2026
+==================
+
+* Fixed `error.row` [bug](https://gitlab.com/catamphetamine/read-excel-file/-/work_items/111) when it was always equal to `1`.
+* Re-added `schema` parameter in `readSheet()` function.
+
 9.0.0 / 18.04.2026
 ==================
 
@@ -42,6 +48,7 @@
         * The `errors` don't have a `row` property anymore because it could be derived from "data row" number.
           * In version `9.x`, the `row` property has been re-added, so consider migrating straight to `9.x`.
         * In version `9.x`, the returned result of `parseData()` has been changed back to `{ errors, objects }`, so consider migrating straight to `9.x`. In that case, if there're no errors, `errors` will be `undefined`; otherwise, `errors` will be a non-empty array and `objects` will be `undefined`.
+        * In version `9.x`, the `schema` parameter was re-added to `readSheet()` function, so consider migrating straight to `9.x`.
   * Renamed some `schema`-related parameters:
     * `schemaPropertyValueForMissingColumn` → `propertyValueWhenColumnIsMissing`
     * `schemaPropertyValueForMissingValue` → `propertyValueWhenCellIsEmpty`

package/README.md

@@ -47,6 +47,7 @@ Also check out [`write-excel-file`](https://www.npmjs.com/package/write-excel-fi
         * The `errors` don't have a `row` property anymore because it could be derived from "data row" number.
           * In version `9.x`, the `row` property has been re-added, so consider migrating straight to `9.x`.
         * In version `9.x`, the returned result of `parseData()` has been changed back to `{ errors, objects }`, so consider migrating straight to `9.x`. In that case, if there're no errors, `errors` will be `undefined`; otherwise, `errors` will be a non-empty array and `objects` will be `undefined`.
+        * In version `9.x`, the `schema` parameter was re-added to `readSheet()` function, so consider migrating straight to `9.x`.
   * Renamed some `schema`-related parameters:
     * `schemaPropertyValueForMissingColumn` → `propertyValueWhenColumnIsMissing`
     * `schemaPropertyValueForMissingValue` → `propertyValueWhenCellIsEmpty`
@@ -96,6 +97,8 @@ Also check out [`write-excel-file`](https://www.npmjs.com/package/write-excel-fi
     * `ParseDataValueRequiredError` → `ParseSheetDataValueRequiredError`
     * `ParseDataResult` → `ParseSheetDataResult`
   * In a `schema`, a nested object could be declared as: `{ required: true/false, schema: { ... } }`. This is still true but the `required` flag is now only allowed to be either `undefined` or `false`, so `true` value is not allowed. The reason is quite simple. If a nested object as a whole is marked as `required: true`, and then it happens to be empty, a `"required"` error should be returned for it. But that error would also have to include a `column` title, and a nested object simply can't be pinned down to a single column in a sheet because it is by definition spread over multiple columns. So instead of marking a nested object as a whole with `required: true`, mark the specific required properties of it.
+  * Re-added `schema` parameter to `readSheet()` function.
+    * `const { objects, errors } = readSheet(data, { schema })`
 </details>
 
 ## Install
@@ -161,6 +164,8 @@ The result is a non-empty array of "sheets". Each "sheet" is an object with prop
 * `data` — Sheet data. An array of rows. Each row is an array of values — `string`, `number`, `boolean` or `Date`.
   * Example: `[ ['Name','Age'], ['John Smith',30], ['Kate Brown',15] ]`
 
+Also, a very common use case is to read a list of JSON objects from an `.xlsx` file. To do that, pass a [`schema`](#schema) parameter to `readSheet()` function.
+
 ## Import
 
 This package provides a separate `import` path for each different environment, as described below.
@@ -325,14 +330,15 @@ Here're the results of reading [sample `.xlsx` files](https://examplefile.com/do
 
 ## Schema
 
-Oftentimes, the task is not just to read the "raw" spreadsheet data but also to convert each row of that data to a JSON object having a certain structure. Because it's such a common task, this package exports a named function `parseSheetData(data, schema)` which does exactly that. It parses sheet data into an array of JSON objects according to a pre-defined `schema` which describes how should a row of data be converted to a JSON object.
+Oftentimes, the task is not just to read the "raw" spreadsheet data but also to convert each row of that data to a JSON object having a certain structure. Because it's such a common task, this package provides an easy way to do that — just pass a `schema` parameter when calling `readSheet()` function and it will automatically parse sheet data into an array of JSON objects according to that `schema` (which basically describes all properties of the object and which column should be mapped to which property). The only requirement is that the sheet data should adhere to a simple structure: the first row should be a header row with just column titles, and each following row should specify the values for those columns.
 
 ```js
-import { readSheet, parseSheetData } from "read-excel-file/browser"
+import { readSheet } from 'read-excel-file/node'
 
-const data = await readSheet(file)
 const schema = { ... }
-const { objects, errors } = parseSheetData(data, schema)
+
+const { objects, errors } = await readSheet(file, { schema })
+
 if (errors) {
   console.error(errors)
 } else {
@@ -340,11 +346,11 @@ if (errors) {
 }
 ```
 
-The `parseSheetData()` function returns an object — `{ objects, errors }`. Depending on whether there were any errors when parsing the data, either `objects` or `errors` property will be `undefined`.
-
-The sheet data that is being parsed should adhere to a simple structure: the first row should be a header row with just column titles, and each following row should specify the values for those columns.
+The result is `{ objects, errors }`
+* If there were any errors, `objects` will be `undefined` and `errors` will be a list of errors.
+* If there were no errors, `errors` will be `undefined` and `objects` will be a list of objects.
 
-The `schema` argument should describe the structure of the resulting JSON objects. An example of a `schema` is provided at the end of this section.
+`schema` should describe the structure of the resulting JSON objects. An example of a `schema` is provided at the end of this section.
 
 Specifically, a `schema` should be an object having the same keys as a resulting JSON object, with values being nested objects having the following properties:
 
@@ -395,6 +401,8 @@ If there're any errors during the conversion process, the `errors` property retu
   * `row: 1` means "first row of data", etc.
   * Don't mind the header row.
 * `column: string` — The column title.
+* `columnIndex: number` — The column index.
+  * `columnIndex: 0` means "first column", etc.
 * `value?: any` — The cell value.
 * `type?: any` — The `type` of the property, as defined by the `schema`.
 
@@ -463,11 +471,8 @@ const schema = {
 // If this code was written in TypeScript, `schema` would've been declared as:
 // const schema: Schema<Object, ColumnTitle> = { ... }
 
-// Read `data` from an `.xlsx` file
-const data = await readSheet(file)
-
-// Parse `data` using a `schema`
-const { objects, errors } = parseSheetData(data, schema)
+// Read `data` from an `.xlsx` file and parse it using a `schema`.
+const { objects, errors } = await readSheet(file, { schema })
 
 // There have been no errors when parsing the sheet data, so `errors` is `undefined`.
 // Should there have been any errors when parsing the sheet data, `errors` would've been
@@ -501,6 +506,21 @@ function PhoneNumber(value) {
 }
 ```
 
+Also, for convenience, this package exports the same feature as a separate function — `parseSheetData(sheetData, schema)`.
+
+```js
+import { readSheet, parseSheetData } from 'read-excel-file/node'
+
+const schema = { ... }
+const sheetData = await readSheet(file)
+const { objects, errors } = parseSheetData(sheetData, schema)
+if (errors) {
+  console.error(errors)
+} else {
+  console.log(objects)
+}
+```
+
 <details>
 <summary>An example of defining a <strong>custom <code>type</code></strong> in <strong>TypeScript</strong></summary>
 

package/browser/index.d.ts

@@ -1,35 +1,48 @@
 // The contents of this file is identical between the different exports:
 // `/node`, `/browser`, etc.
 
-import { Input } from './input.d.js'
+import type { Input } from './input.d.js'
 
-import {
-	SheetData,
-	ReadOptions,
-	ReadFileResult
-} from '../types/types.d.js';
+import type {
+	SheetData
+} from '../types/SheetData.d.js'
 
-import {
+import type {
+	Sheet
+} from '../types/Sheet.d.js'
+
+import type {
+	Options
+} from '../types/Options.d.js'
+
+import type {
+	OptionsWithSchema
+} from '../types/OptionsWithSchema.d.js'
+
+import type {
 	ParseSheetDataOptions,
 	ParseSheetDataResult
-} from '../types/parseSheetData/parseSheetData.d.js';
+} from '../types/parseSheetData/parseSheetData.d.js'
 
-import {
+import type {
 	Schema
-} from '../types/parseSheetData/parseSheetDataSchema.d.js';
+} from '../types/parseSheetData/parseSheetDataSchema.d.js'
 
-import {
+import type {
 	ParseSheetDataError
-} from '../types/parseSheetData/parseSheetDataError.d.js';
+} from '../types/parseSheetData/parseSheetDataError.d.js'
 
-export {
+export type {
 	CellValue,
 	Row,
-	SheetData,
+	SheetData
+} from '../types/SheetData.d.js'
+
+export type {
 	Sheet
-} from '../types/types.d.js';
+} from '../types/Sheet.d.js'
 
-export {
+export type {
 	ParseSheetDataCustomType,
 	// Base `type`s when parsing data.
 	StringType as String,
@@ -40,45 +53,55 @@ export {
 	Integer,
 	Email,
 	URL
-} from '../types/parseSheetData/parseSheetDataValueType.d.js';
+} from '../types/parseSheetData/parseSheetDataValueType.d.js'
 
-export {
+export type {
 	ParseSheetDataCustomTypeErrorMessage,
 	ParseSheetDataCustomTypeErrorReason,
 	ParseSheetDataError,
 	ParseSheetDataValueRequiredError
-} from '../types/parseSheetData/parseSheetDataError.d.js';
+} from '../types/parseSheetData/parseSheetDataError.d.js'
 
-export {
+export type {
 	ParseSheetDataResult
-} from '../types/parseSheetData/parseSheetData.d.js';
+} from '../types/parseSheetData/parseSheetData.d.js'
 
-export {
+export type {
 	Schema
-} from '../types/parseSheetData/parseSheetDataSchema.d.js';
+} from '../types/parseSheetData/parseSheetDataSchema.d.js'
 
 export default function readXlsxFile<ParsedNumber = number>(
 	input: Input,
-	options?: ReadOptions<ParsedNumber>
-): Promise<ReadFileResult<ParsedNumber>>;
+	options?: Options<ParsedNumber>
+): Promise<Sheet<ParsedNumber>[]>;
 
 export function readSheet<ParsedNumber = number>(
 	input: Input,
 	sheet?: number | string,
-	options?: ReadOptions<ParsedNumber>
+	options?: Options<ParsedNumber>
 ): Promise<SheetData<ParsedNumber>>;
 
 export function readSheet<ParsedNumber = number>(
 	input: Input,
-	options?: ReadOptions<ParsedNumber>
+	options?: Options<ParsedNumber>
 ): Promise<SheetData<ParsedNumber>>;
 
+export function readSheet<
+	Object extends object,
+	ColumnTitle extends string = string,
+	Error extends ParseSheetDataError = ParseSheetDataError<ColumnTitle>,
+	ParsedNumber = number
+>(
+	input: Input,
+	options: OptionsWithSchema<Object, ColumnTitle, ParsedNumber>
+): Promise<ParseSheetDataResult<Object, ColumnTitle, Error>>;
+
 export function parseSheetData<
 	Object extends object,
-	ColumnTitle extends string,
-	Error extends ParseSheetDataError
+	ColumnTitle extends string = string,
+	Error extends ParseSheetDataError = ParseSheetDataError<ColumnTitle>
 >(
 	data: SheetData,
 	schema: Schema<Object, ColumnTitle>,
 	options?: ParseSheetDataOptions
-): ParseSheetDataResult<Object, Error>;
+): ParseSheetDataResult<Object, ColumnTitle, Error>;