read-excel-file 8.0.1 → 8.0.3

package/types/parseData/parseDataError.d.ts

@@ -1,104 +1,128 @@
 import { CellValue } from '../types.d.js'
 
 import {
-	Constructor,
-	ParseDataValueCustomType,
-	ParseDataValueType,
+	StringType,
+	DateType,
+	NumberType,
+	BooleanType,
 	Integer,
 	Email,
-	URL
+	URL,
+	ParseDataCustomType,
+	ParseDataValueType
 } from './parseDataValueType.d.js'
 
-// When `error` is `"required"`, `value` could only be `null` or `undefined`.
 export interface ParseDataValueRequiredError<
-	ParseDataValueType = unknown,
-	ColumnTitle = string
+	ColumnTitle extends string = string,
+	CustomType extends ParseDataCustomType<unknown> = never
 > {
 	// row: number;
 	column: ColumnTitle;
-	type?: ParseDataValueType;
+	// `type: undefined` is treated as `type: String`.
+	type?: ParseDataValueType<CustomType>;
 	error: 'required';
 	reason: undefined;
+	// When `error` is `"required"`, `value` could only be `null` or `undefined`.
+	// * `null` means "cell is empty"
+	// * `undefined` means "column is missing"
 	value: null | undefined;
 }
 
-// When `error` is not `"required"`, `value` is known to not be `null` or `undefined`
-// because when `value` is `null` or `undefined`, it won't be parsed at all,
-// so there can't be any error thrown during parsing phase.
 interface ParseDataError_<
-	ParseDataValueType extends ParseDataValueCustomType<unknown> | undefined = ParseDataValueCustomType<unknown>,
-	ColumnTitle = string,
-	ErrorMessage extends string = string,
-	ErrorReason extends string | undefined = string | undefined
+	ColumnTitle extends string,
+	// ` | undefined` is added to support `parseData()` errors that originate
+	// on properties that have no `type` property specified. In such cases,
+	// `type` defaults to `String`.
+	//
+	// One could ask: "Why is then the `type` not simply marked as optional?".
+	// The answer is that `type` could only be `undefined` in case of `parseData()` errors
+	// that originate from `type: String` parser while other type parsers can't have `type` be `undefined`.
+	//
+	Type extends ParseDataValueType<unknown> | undefined,
+	ErrorMessage extends string,
+	ErrorReason extends string | undefined
 > {
 	// row: number;
 	column: ColumnTitle;
-	type: ParseDataValueType;
+	type: Type;
 	error: ErrorMessage;
 	reason: ErrorReason;
+	// When `error` is not `"required"`, `value` is known to not be `null` or `undefined`
+	// because when `value` is `null` or `undefined`, it won't be parsed at all,
+	// so there can't be any error thrown during parsing phase.
 	value: CellValue;
 }
 
-export interface ParseDataError<
-	ParseDataValueType extends ParseDataValueCustomType<unknown> = ParseDataValueCustomType<unknown>,
-	ColumnTitle = string,
-	ErrorMessage extends string = string,
-	ErrorReason extends string | undefined = string | undefined
+export type ParseDataCustomTypeErrorMessage<
+	CustomType extends ParseDataCustomType<unknown>
+> = string
+
+export type ParseDataCustomTypeErrorReason<
+	CustomType extends ParseDataCustomType<unknown>,
+	ErrorMessage extends ParseDataCustomTypeErrorMessage<CustomType>
+> = string | undefined
+
+// This is just a public export. It's not used internally.
+interface ParseDataErrorCustomType<
+	ColumnTitle extends string = string,
+	CustomType extends ParseDataCustomType<unknown> = never,
+	ErrorMessage extends ParseDataCustomTypeErrorMessage<CustomType> = string,
+	ErrorReason extends ParseDataCustomTypeErrorReason<CustomType, ErrorMessage> = string | undefined
 > extends ParseDataError_<
-	ParseDataValueType,
 	ColumnTitle,
+	CustomType,
 	ErrorMessage,
 	ErrorReason
 > {}
 
-interface ParseDataErrorNotABoolean<ColumnTitle = string> extends ParseDataError_<
-	Constructor<Boolean>,
+interface ParseDataErrorNotABoolean<ColumnTitle extends string = string> extends ParseDataError_<
 	ColumnTitle,
+	BooleanType,
 	'not_a_boolean',
 	undefined
 > {
 	value: Exclude<CellValue, boolean>;
 }
 
-interface ParseDataErrorNotADate<ColumnTitle = string> extends ParseDataError_<
-	Constructor<Date>,
+interface ParseDataErrorNotADate<ColumnTitle extends string = string> extends ParseDataError_<
 	ColumnTitle,
+	DateType,
 	'not_a_date',
 	undefined
 > {
 	value: Exclude<CellValue, typeof Date | number>;
 }
 
-interface ParseDataErrorDateOutOfBounds<ColumnTitle = string> extends ParseDataError_<
-	Constructor<Date>,
+interface ParseDataErrorDateOutOfBounds<ColumnTitle extends string = string> extends ParseDataError_<
 	ColumnTitle,
+	DateType,
 	'out_of_bounds',
 	undefined
 > {
 	value: typeof Date;
 }
 
-interface ParseDataErrorNotAString<ColumnTitle = string> extends ParseDataError_<
-	Constructor<String> | undefined,
+interface ParseDataErrorNotAString<ColumnTitle extends string = string> extends ParseDataError_<
 	ColumnTitle,
+	StringType | undefined,
 	'not_a_string',
 	undefined
 > {
 	value: Exclude<CellValue, string | number>;
 }
 
-interface ParseDataErrorStringInvalidNumber<ColumnTitle = string> extends ParseDataError_<
-	Constructor<String> | undefined,
+interface ParseDataErrorStringInvalidNumber<ColumnTitle extends string = string> extends ParseDataError_<
 	ColumnTitle,
+	StringType | undefined,
 	'invalid_number',
 	undefined
 > {
 	value: number;
 }
 
-interface ParseDataErrorStringNumberOutOfBounds<ColumnTitle = string> extends ParseDataError_<
-	Constructor<String> | undefined,
+interface ParseDataErrorStringNumberOutOfBounds<ColumnTitle extends string = string> extends ParseDataError_<
 	ColumnTitle,
+	StringType | undefined,
 	'out_of_bounds',
 	undefined
 > {
@@ -106,11 +130,11 @@ interface ParseDataErrorStringNumberOutOfBounds<ColumnTitle = string> extends Pa
 }
 
 interface ParseDataErrorNotANumber<
-	Type extends ParseDataValueCustomType<unknown> | undefined = Constructor<Number>,
-	ColumnTitle = string
+	ColumnTitle extends string = string,
+	Type extends ParseDataCustomType<unknown> | undefined = NumberType
 > extends ParseDataError_<
-	Type,
 	ColumnTitle,
+	Type,
 	'not_a_number',
 	undefined
 > {
@@ -118,11 +142,11 @@ interface ParseDataErrorNotANumber<
 }
 
 interface ParseDataErrorNotANumberString<
-	Type extends ParseDataValueCustomType<unknown> | undefined = Constructor<Number>,
-	ColumnTitle = string
+	ColumnTitle extends string = string,
+	Type extends ParseDataCustomType<unknown> | undefined = NumberType
 > extends ParseDataError_<
-	Type,
 	ColumnTitle,
+	Type,
 	'not_a_number',
 	undefined
 > {
@@ -130,11 +154,11 @@ interface ParseDataErrorNotANumberString<
 }
 
 interface ParseDataErrorNumberInvalid<
-	Type extends ParseDataValueCustomType<unknown> | undefined = Constructor<Number>,
-	ColumnTitle = string
+	ColumnTitle extends string = string,
+	Type extends ParseDataCustomType<unknown> | undefined = NumberType
 > extends ParseDataError_<
-	Type,
 	ColumnTitle,
+	Type,
 	'invalid_number',
 	undefined
 > {
@@ -142,80 +166,80 @@ interface ParseDataErrorNumberInvalid<
 }
 
 interface ParseDataErrorNumberOutOfBounds<
-	Type extends ParseDataValueCustomType<unknown> | undefined = Constructor<Number>,
-	ColumnTitle = string
+	ColumnTitle extends string = string,
+	Type extends ParseDataCustomType<unknown> | undefined = NumberType
 > extends ParseDataError_<
-	Type,
 	ColumnTitle,
+	Type,
 	'out_of_bounds',
 	undefined
 > {
 	value: number | string;
 }
 
-type ParseDataBaseValueTypeError<ColumnTitle = string> =
+type ParseDataBaseValueTypeError<ColumnTitle extends string = string> =
 	| ParseDataErrorNotABoolean<ColumnTitle>
 	| ParseDataErrorNotADate<ColumnTitle>
 	| ParseDataErrorDateOutOfBounds<ColumnTitle>
 	| ParseDataErrorNotAString<ColumnTitle>
 	| ParseDataErrorStringInvalidNumber<ColumnTitle>
 	| ParseDataErrorStringNumberOutOfBounds<ColumnTitle>
-	| ParseDataErrorNotANumber<Constructor<Number>, ColumnTitle>
-	| ParseDataErrorNotANumberString<Constructor<Number>, ColumnTitle>
-	| ParseDataErrorNumberInvalid<Constructor<Number>, ColumnTitle>
-	| ParseDataErrorNumberOutOfBounds<Constructor<Number>, ColumnTitle>;
+	| ParseDataErrorNotANumber<ColumnTitle, NumberType>
+	| ParseDataErrorNotANumberString<ColumnTitle, NumberType>
+	| ParseDataErrorNumberInvalid<ColumnTitle, NumberType>
+	| ParseDataErrorNumberOutOfBounds<ColumnTitle, NumberType>;
 
-interface ParseDataErrorNotAnInteger<ColumnTitle = string> extends ParseDataError_<
-	typeof Integer,
+interface ParseDataErrorNotAnInteger<ColumnTitle extends string = string> extends ParseDataError_<
 	ColumnTitle,
+	typeof Integer,
 	'not_an_integer',
 	undefined
 > {
 	value: number | string;
 }
 
-interface ParseDataErrorIntegerNotANumber<ColumnTitle = string> extends ParseDataErrorNotANumber<typeof Integer, ColumnTitle> {}
-interface ParseDataErrorIntegerNotANumberString<ColumnTitle = string> extends ParseDataErrorNotANumberString<typeof Integer, ColumnTitle> {}
-interface ParseDataErrorIntegerNumberInvalid<ColumnTitle = string> extends ParseDataErrorNumberInvalid<typeof Integer, ColumnTitle> {}
-interface ParseDataErrorIntegerNumberOutOfBounds<ColumnTitle = string> extends ParseDataErrorNumberOutOfBounds<typeof Integer, ColumnTitle> {}
+interface ParseDataErrorIntegerNotANumber<ColumnTitle extends string = string> extends ParseDataErrorNotANumber<ColumnTitle, typeof Integer> {}
+interface ParseDataErrorIntegerNotANumberString<ColumnTitle extends string = string> extends ParseDataErrorNotANumberString<ColumnTitle, typeof Integer> {}
+interface ParseDataErrorIntegerNumberInvalid<ColumnTitle extends string = string> extends ParseDataErrorNumberInvalid<ColumnTitle, typeof Integer> {}
+interface ParseDataErrorIntegerNumberOutOfBounds<ColumnTitle extends string = string> extends ParseDataErrorNumberOutOfBounds<ColumnTitle, typeof Integer> {}
 
-interface ParseDataErrorNotAUrl<ColumnTitle = string> extends ParseDataError_<
-	typeof URL,
+interface ParseDataErrorNotAUrl<ColumnTitle extends string = string> extends ParseDataError_<
 	ColumnTitle,
+	typeof URL,
 	'not_a_url',
 	undefined
 > {
 	value: string;
 }
 
-interface ParseDataErrorUrlNotAString<ColumnTitle = string> extends ParseDataError_<
-	typeof URL,
+interface ParseDataErrorUrlNotAString<ColumnTitle extends string = string> extends ParseDataError_<
 	ColumnTitle,
+	typeof URL,
 	'not_a_string',
 	undefined
 > {
 	value: Exclude<CellValue, string>;
 }
 
-interface ParseDataErrorNotAnEmail<ColumnTitle = string> extends ParseDataError_<
-	typeof Email,
+interface ParseDataErrorNotAnEmail<ColumnTitle extends string = string> extends ParseDataError_<
 	ColumnTitle,
+	typeof Email,
 	'not_an_email',
 	undefined
 > {
 	value: string;
 }
 
-interface ParseDataErrorEmailNotAString<ColumnTitle = string> extends ParseDataError_<
-	typeof Email,
+interface ParseDataErrorEmailNotAString<ColumnTitle extends string = string> extends ParseDataError_<
 	ColumnTitle,
+	typeof Email,
 	'not_a_string',
 	undefined
 > {
 	value: Exclude<CellValue, string>;
 }
 
-type ParseDataAdditionalBuiltInValueTypeError<ColumnTitle = string> =
+type ParseDataAdditionalValueTypeError<ColumnTitle extends string = string> =
 	| ParseDataErrorNotAnInteger<ColumnTitle>
 	| ParseDataErrorIntegerNotANumber<ColumnTitle>
 	| ParseDataErrorIntegerNotANumberString<ColumnTitle>
@@ -226,14 +250,32 @@ type ParseDataAdditionalBuiltInValueTypeError<ColumnTitle = string> =
 	| ParseDataErrorNotAnEmail<ColumnTitle>
 	| ParseDataErrorEmailNotAString<ColumnTitle>;
 
-type ParseDataBuiltInValueTypeError<ColumnTitle = string> =
+type ParseDataBuiltInValueTypeError<ColumnTitle extends string = string> =
 	| ParseDataBaseValueTypeError<ColumnTitle>
-	| ParseDataAdditionalBuiltInValueTypeError<ColumnTitle>;
+	| ParseDataAdditionalValueTypeError<ColumnTitle>;
+
+interface ParseDataArrayValueSyntaxError<
+	ColumnTitle extends string = string,
+	ParseDataCustomType_ extends ParseDataCustomType<unknown> = ParseDataCustomType<unknown>
+> extends ParseDataError_<
+	ColumnTitle,
+	ParseDataValueType<ParseDataCustomType_>,
+	'invalid',
+	'syntax'
+> {}
 
-export type ParseDataPossibleError<
-	ParseDataValueCustomType_ extends ParseDataValueCustomType<unknown>,
-	ColumnTitle = string
+export type ParseDataError<
+	ColumnTitle extends string = string,
+	CustomType extends ParseDataCustomType<unknown> = never,
+	ErrorMessage extends ParseDataCustomTypeErrorMessage<CustomType> = string,
+	ErrorReason extends ParseDataCustomTypeErrorReason<CustomType, ErrorMessage> = string | undefined
 > =
 	| ParseDataBuiltInValueTypeError<ColumnTitle>
-	| ParseDataValueRequiredError<ParseDataValueType<ParseDataValueCustomType_>, ColumnTitle>
-	| ParseDataError<ParseDataValueType<ParseDataValueCustomType_>, ColumnTitle>;
+	| ParseDataValueRequiredError<ColumnTitle, ParseDataValueType<CustomType>>
+	| ParseDataArrayValueSyntaxError<ColumnTitle, ParseDataValueType<CustomType>>
+	| ParseDataErrorCustomType<
+		ColumnTitle,
+		ParseDataValueType<CustomType>,
+		ErrorMessage,
+		ErrorReason
+	>;

package/types/parseData/parseDataSchema.d.ts

@@ -1,4 +1,4 @@
-import { ParseDataValueType, ParseDataValueCustomType } from './parseDataValueType.js'
+import { ParseDataValueType, ParseDataCustomType } from './parseDataValueType.js'
 
 type SchemaEntryRequiredOrNot<Object> = boolean | ((row: Object) => boolean);
 
@@ -9,7 +9,7 @@ interface SchemaEntryForValue<
 	ColumnTitle extends string
 > {
 	column: ColumnTitle;
-	type?: ParseDataValueType<ParseDataValueCustomType<Object[Key]>>;
+	type?: ParseDataValueType<ParseDataCustomType<Object[Key]>>;
 	oneOf?: Object[Key][];
 	required?: SchemaEntryRequiredOrNot<TopLevelObject>;
 	validate?(value: Object[Key]): void;

package/types/parseData/parseDataValueType.d.ts

@@ -15,31 +15,36 @@ export type Constructor<Type> =
 					? BooleanConstructor
 					: never;
 
+export type StringType = Constructor<String>;
+export type DateType = Constructor<Date>;
+export type NumberType = Constructor<Number>;
+export type BooleanType = Constructor<Boolean>;
+
 // Parsed value `type` (foundational ones).
-type BaseType =
+type ParseDataBaseType =
 	Constructor<String> |
 	Constructor<Date> |
 	Constructor<Number> |
 	Constructor<Boolean>;
 
-// Parsed value `type` (custom one).
-// A function that receives a cell `value` and returns a "parsed" value.
-// Returning `undefined` will have same effect as returning `null`.
-// When cell value is `undefined` or `null`, its `type` is completely ignored (skipped).
-export type ParseDataValueCustomType<ParsedValue> = (value: CellValue) => ParsedValue | undefined | null;
-
 // Parsed value `type` (additional built-in ones).
 export function Integer(value: CellValue): number;
 export function URL(value: CellValue): string;
 export function Email(value: CellValue): string;
 
-type AdditionalBuiltInParseDataValueType =
+type ParseDataAdditionalType =
 	| typeof Integer
 	| typeof URL
 	| typeof Email;
 
+// Parsed value `type` (custom one).
+// A function that receives a cell `value` and returns a "parsed" value.
+// Returning `undefined` will have same effect as returning `null`.
+// When cell value is `undefined` or `null`, its `type` is completely ignored (skipped).
+export type ParseDataCustomType<ParsedValue> = (value: CellValue) => ParsedValue | undefined;
+
 // Schema entry `type`: foundational ones, additional ones, custom ones.
-export type ParseDataValueType<ParseDataValueCustomType> =
-	| BaseType
-	| AdditionalBuiltInParseDataValueType
-	| ParseDataValueCustomType;
+export type ParseDataValueType<ParseDataCustomType> =
+	| ParseDataBaseType
+	| ParseDataAdditionalType
+	| ParseDataCustomType;

package/universal/index.d.ts

@@ -18,6 +18,10 @@ import {
 	Schema
 } from '../types/parseData/parseDataSchema.d.js';
 
+import {
+	ParseDataError
+} from '../types/parseData/parseDataError.d.js';
+
 export {
 	CellValue,
 	Row,
@@ -25,7 +29,12 @@ export {
 } from '../types/types.d.js';
 
 export {
-	ParseDataValueCustomType as ParseDataValueType,
+	ParseDataCustomType,
+	// Base `type`s when parsing data.
+	StringType as String,
+	DateType as Date,
+	NumberType as Number,
+	BooleanType as Boolean,
 	// Additional built-in `type`s when parsing data.
 	Integer,
 	Email,
@@ -33,6 +42,8 @@ export {
 } from '../types/parseData/parseDataValueType.d.js';
 
 export {
+	ParseDataCustomTypeErrorMessage,
+	ParseDataCustomTypeErrorReason,
 	ParseDataError,
 	ParseDataValueRequiredError
 } from '../types/parseData/parseDataError.d.js';
@@ -63,9 +74,10 @@ export function readSheet<ParsedNumber = number>(
 
 export function parseData<
 	Object extends object,
-	ColumnTitle extends string
+	ColumnTitle extends string,
+	Error extends ParseDataError
 >(
 	data: SheetData,
 	schema: Schema<Object, ColumnTitle>,
 	options?: ParseDataOptions
-): ParseDataResult<Object>;
+): ParseDataResult<Object, Error>;

package/web-worker/index.d.ts

@@ -18,6 +18,10 @@ import {
 	Schema
 } from '../types/parseData/parseDataSchema.d.js';
 
+import {
+	ParseDataError
+} from '../types/parseData/parseDataError.d.js';
+
 export {
 	CellValue,
 	Row,
@@ -25,7 +29,12 @@ export {
 } from '../types/types.d.js';
 
 export {
-	ParseDataValueCustomType as ParseDataValueType,
+	ParseDataCustomType,
+	// Base `type`s when parsing data.
+	StringType as String,
+	DateType as Date,
+	NumberType as Number,
+	BooleanType as Boolean,
 	// Additional built-in `type`s when parsing data.
 	Integer,
 	Email,
@@ -33,6 +42,8 @@ export {
 } from '../types/parseData/parseDataValueType.d.js';
 
 export {
+	ParseDataCustomTypeErrorMessage,
+	ParseDataCustomTypeErrorReason,
 	ParseDataError,
 	ParseDataValueRequiredError
 } from '../types/parseData/parseDataError.d.js';
@@ -63,9 +74,10 @@ export function readSheet<ParsedNumber = number>(
 
 export function parseData<
 	Object extends object,
-	ColumnTitle extends string
+	ColumnTitle extends string,
+	Error extends ParseDataError
 >(
 	data: SheetData,
 	schema: Schema<Object, ColumnTitle>,
 	options?: ParseDataOptions
-): ParseDataResult<Object>;
+): ParseDataResult<Object, Error>;