
<a name="readmemd"></a>

# @borgar/xlsx-convert

## Classes

- [EncryptionError](#classesencryptionerrormd)
- [InvalidFileError](#classesinvalidfileerrormd)
- [MissingSheetError](#classesmissingsheeterrormd)
- [UnsupportedError](#classesunsupportederrormd)

## Type Aliases

- [ConversionOptions](#type-aliasesconversionoptionsmd)
- [CSVConversionOptions](#type-aliasescsvconversionoptionsmd)
- [MdwResolver](#type-aliasesmdwresolvermd)

## Functions

- [convert](#functionsconvertmd)
- [convertBinary](#functionsconvertbinarymd)
- [convertCSV](#functionsconvertcsvmd)


<a name="classesencryptionerrormd"></a>

# EncryptionError

## Extends

- `Error`

## Constructors

### Constructor

```ts
new EncryptionError(message?: string): EncryptionError;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `message?` | `string` |

#### Returns

`EncryptionError`

#### Inherited from

```ts
Error.constructor
```

### Constructor

```ts
new EncryptionError(message?: string, options?: ErrorOptions): EncryptionError;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `message?` | `string` |
| `options?` | `ErrorOptions` |

#### Returns

`EncryptionError`

#### Inherited from

```ts
Error.constructor
```

## Properties

| Property | Modifier | Type | Description | Inherited from |
| ------ | ------ | ------ | ------ | ------ |
| <a id="cause"></a> `cause?` | `public` | `unknown` | - | `Error.cause` |
| <a id="message"></a> `message` | `public` | `string` | - | `Error.message` |
| <a id="name"></a> `name` | `public` | `string` | - | `Error.name` |
| <a id="stack"></a> `stack?` | `public` | `string` | - | `Error.stack` |
| <a id="stacktracelimit"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` |

## Methods

### captureStackTrace()

```ts
static captureStackTrace(targetObject: object, constructorOpt?: Function): void;
```

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

#### Returns

`void`

#### Inherited from

```ts
Error.captureStackTrace
```

***

### prepareStackTrace()

```ts
static prepareStackTrace(err: Error, stackTraces: CallSite[]): any;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `err` | `Error` |
| `stackTraces` | `CallSite`[] |

#### Returns

`any`

#### See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

#### Inherited from

```ts
Error.prepareStackTrace
```


<a name="classesinvalidfileerrormd"></a>

# InvalidFileError

## Extends

- `Error`

## Constructors

### Constructor

```ts
new InvalidFileError(message?: string): InvalidFileError;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `message?` | `string` |

#### Returns

`InvalidFileError`

#### Inherited from

```ts
Error.constructor
```

### Constructor

```ts
new InvalidFileError(message?: string, options?: ErrorOptions): InvalidFileError;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `message?` | `string` |
| `options?` | `ErrorOptions` |

#### Returns

`InvalidFileError`

#### Inherited from

```ts
Error.constructor
```

## Properties

| Property | Modifier | Type | Description | Inherited from |
| ------ | ------ | ------ | ------ | ------ |
| <a id="cause"></a> `cause?` | `public` | `unknown` | - | `Error.cause` |
| <a id="message"></a> `message` | `public` | `string` | - | `Error.message` |
| <a id="name"></a> `name` | `public` | `string` | - | `Error.name` |
| <a id="stack"></a> `stack?` | `public` | `string` | - | `Error.stack` |
| <a id="stacktracelimit"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` |

## Methods

### captureStackTrace()

```ts
static captureStackTrace(targetObject: object, constructorOpt?: Function): void;
```

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

#### Returns

`void`

#### Inherited from

```ts
Error.captureStackTrace
```

***

### prepareStackTrace()

```ts
static prepareStackTrace(err: Error, stackTraces: CallSite[]): any;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `err` | `Error` |
| `stackTraces` | `CallSite`[] |

#### Returns

`any`

#### See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

#### Inherited from

```ts
Error.prepareStackTrace
```


<a name="classesmissingsheeterrormd"></a>

# MissingSheetError

## Extends

- `Error`

## Constructors

### Constructor

```ts
new MissingSheetError(message?: string): MissingSheetError;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `message?` | `string` |

#### Returns

`MissingSheetError`

#### Inherited from

```ts
Error.constructor
```

### Constructor

```ts
new MissingSheetError(message?: string, options?: ErrorOptions): MissingSheetError;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `message?` | `string` |
| `options?` | `ErrorOptions` |

#### Returns

`MissingSheetError`

#### Inherited from

```ts
Error.constructor
```

## Properties

| Property | Modifier | Type | Description | Inherited from |
| ------ | ------ | ------ | ------ | ------ |
| <a id="cause"></a> `cause?` | `public` | `unknown` | - | `Error.cause` |
| <a id="message"></a> `message` | `public` | `string` | - | `Error.message` |
| <a id="name"></a> `name` | `public` | `string` | - | `Error.name` |
| <a id="stack"></a> `stack?` | `public` | `string` | - | `Error.stack` |
| <a id="stacktracelimit"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` |

## Methods

### captureStackTrace()

```ts
static captureStackTrace(targetObject: object, constructorOpt?: Function): void;
```

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

#### Returns

`void`

#### Inherited from

```ts
Error.captureStackTrace
```

***

### prepareStackTrace()

```ts
static prepareStackTrace(err: Error, stackTraces: CallSite[]): any;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `err` | `Error` |
| `stackTraces` | `CallSite`[] |

#### Returns

`any`

#### See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

#### Inherited from

```ts
Error.prepareStackTrace
```


<a name="classesunsupportederrormd"></a>

# UnsupportedError

## Extends

- `Error`

## Constructors

### Constructor

```ts
new UnsupportedError(message?: string): UnsupportedError;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `message?` | `string` |

#### Returns

`UnsupportedError`

#### Inherited from

```ts
Error.constructor
```

### Constructor

```ts
new UnsupportedError(message?: string, options?: ErrorOptions): UnsupportedError;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `message?` | `string` |
| `options?` | `ErrorOptions` |

#### Returns

`UnsupportedError`

#### Inherited from

```ts
Error.constructor
```

## Properties

| Property | Modifier | Type | Description | Inherited from |
| ------ | ------ | ------ | ------ | ------ |
| <a id="cause"></a> `cause?` | `public` | `unknown` | - | `Error.cause` |
| <a id="message"></a> `message` | `public` | `string` | - | `Error.message` |
| <a id="name"></a> `name` | `public` | `string` | - | `Error.name` |
| <a id="stack"></a> `stack?` | `public` | `string` | - | `Error.stack` |
| <a id="stacktracelimit"></a> `stackTraceLimit` | `static` | `number` | The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured _after_ the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. | `Error.stackTraceLimit` |

## Methods

### captureStackTrace()

```ts
static captureStackTrace(targetObject: object, constructorOpt?: Function): void;
```

Creates a `.stack` property on `targetObject`, which when accessed returns
a string representing the location in the code at which
`Error.captureStackTrace()` was called.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

The first line of the trace will be prefixed with
`${myObject.name}: ${myObject.message}`.

The optional `constructorOpt` argument accepts a function. If given, all frames
above `constructorOpt`, including `constructorOpt`, will be omitted from the
generated stack trace.

The `constructorOpt` argument is useful for hiding implementation
details of error generation from the user. For instance:

```js
function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `targetObject` | `object` |
| `constructorOpt?` | `Function` |

#### Returns

`void`

#### Inherited from

```ts
Error.captureStackTrace
```

***

### prepareStackTrace()

```ts
static prepareStackTrace(err: Error, stackTraces: CallSite[]): any;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `err` | `Error` |
| `stackTraces` | `CallSite`[] |

#### Returns

`any`

#### See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

#### Inherited from

```ts
Error.prepareStackTrace
```


<a name="functionsconvertmd"></a>

# convert()

```ts
function convert(filename: string, options?: ConversionOptions): Promise<Workbook>;
```

Load and convert an XLSX file into a JSON format.

The returned JSF structure contains most of the data from the original file, although some details
may be lost in the conversion process.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `filename` | `string` | Target filename to convert |
| `options?` | [`ConversionOptions`](#type-aliasesconversionoptionsmd) | Conversion options |

## Returns

`Promise`\<[`Workbook`](https://jsfkit.github.io/types/Workbook)\>

A JSON spreadsheet object.


<a name="functionsconvertbinarymd"></a>

# convertBinary()

```ts
function convertBinary(
   buffer: ArrayBuffer | Buffer<ArrayBufferLike>, 
   filename: string, 
options?: ConversionOptions): Promise<Workbook>;
```

Convert an XLSX binary into a JSON format.

The returned JSF structure contains most of the data from the original file, although some details
may be lost in the conversion process.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `buffer` | `ArrayBuffer` \| `Buffer`\<`ArrayBufferLike`\> | Buffer containing the file to convert |
| `filename` | `string` | Name of the file being converted |
| `options?` | [`ConversionOptions`](#type-aliasesconversionoptionsmd) | Conversion options |

## Returns

`Promise`\<[`Workbook`](https://jsfkit.github.io/types/Workbook)\>

A JSON spreadsheet formatted object.


<a name="functionsconvertcsvmd"></a>

# convertCSV()

```ts
function convertCSV(
   csvStream: string, 
   name: string, 
   options?: CSVConversionOptions): Workbook;
```

Convert a CSV/TSV into JSF format.

The returned JSF structure contains all the data table found in the file presented as
a spreadsheet table.

## Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `csvStream` | `string` | A string of CSV data |
| `name` | `string` | Name of the file being converted, to be used as the workbook name |
| `options?` | [`CSVConversionOptions`](#type-aliasescsvconversionoptionsmd) | Conversion options |

## Returns

[`Workbook`](https://jsfkit.github.io/types/Workbook)

A JSON spreadsheet formatted object.


<a name="type-aliasescsvconversionoptionsmd"></a>

# CSVConversionOptions

```ts
type CSVConversionOptions = {
  delimiter?: null | "," | ";" | "\t";
  escapeChar?: null | "\" | "\"";
  locale?: string;
  sheetName?: string;
  skipEmptyLines?: boolean;
  table?: boolean;
};
```

CSV convertion options

## Properties

| Property | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| <a id="delimiter"></a> `delimiter?` | `null` \| `","` \| `";"` \| "\t" | `null` | The delimiter to use to parse the CSV. Normally this is auto-detected. |
| <a id="escapechar"></a> `escapeChar?` | `null` \| "\\" \| "\"" | `'"'` | The character used to escape quotation marks in strings. |
| <a id="locale"></a> `locale?` | `string` | `'en-US'` | The locale (as a BCP 47 string) to use when parsing dates and numbers. **See** |
| <a id="sheetname"></a> `sheetName?` | `string` | `'Sheet1'` | The name of the sheet to create in the resulting workbook. |
| <a id="skipemptylines"></a> `skipEmptyLines?` | `boolean` | `true` | Skip empty lines instead of creating empty rows. |
| <a id="table"></a> `table?` | `boolean` | `false` | Create a table descriptor object for the data in the sheet. |


<a name="type-aliasesconversionoptionsmd"></a>

# ConversionOptions

```ts
type ConversionOptions = {
  cellFormulas?: boolean;
  imageCallback?: (data?: ArrayBuffer, filename?: string) => Promise<string | void> | string | void;
  resolveMdw?: MdwResolver;
  skipMerged?: boolean;
  skipStyledEmptyCells?: boolean;
  warn?: (message: string) => void;
};
```

Convertion options

## Properties

| Property | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| <a id="cellformulas"></a> `cellFormulas?` | `boolean` | `false` | Formulas are attached to cells rather than being included as a separate list. |
| <a id="imagecallback"></a> `imageCallback?` | (`data?`: `ArrayBuffer`, `filename?`: `string`) => `Promise`\<`string` \| `void`\> \| `string` \| `void` | `undefined` | Image reading callback. All read images are passed through this callback if it is provided. This is useful, for example, for extracting the images to disk. If the return value is a string, the value will be used in the images record on the workbook instead of the standard data-URI conversion. |
| <a id="resolvemdw"></a> `resolveMdw?` | [`MdwResolver`](#type-aliasesmdwresolvermd) | `undefined` | Resolve the Max Digit Width (in pixels) for the workbook's Normal font, used to convert column widths from OOXML character units to pixels. Returning null/undefined defers to the built-in table (Aptos Narrow, Calibri, Arial); unknown fonts then fall back to MDW 6 (and warn). Supply this to size columns correctly for fonts outside the table. |
| <a id="skipmerged"></a> `skipMerged?` | `boolean` | `true` | Skip cells that are a part of merges. |
| <a id="skipstyledemptycells"></a> `skipStyledEmptyCells?` | `boolean` | `false` | Drop cells that have a style but no value or formula, unless the style is visible (fill, border, etc.). |
| <a id="warn"></a> `warn?` | (`message`: `string`) => `void` | `undefined` | Warning callback. If provided, warnings are passed to this function; otherwise they are silently discarded. |


<a name="type-aliasesmdwresolvermd"></a>

# MdwResolver

```ts
type MdwResolver = (fontFamily: string, fontSizePt: number) => number | null | undefined;
```

Resolve an MDW for an arbitrary font. Returning null/undefined defers to the built-in table.

## Parameters

| Parameter | Type |
| ------ | ------ |
| `fontFamily` | `string` |
| `fontSizePt` | `number` |

## Returns

`number` \| `null` \| `undefined`