# xlstream-fork > Turns XLSX into a readable stream. Latest version **2.6.0** (published 2020-11-16) · MIT license · 0 weekly downloads ## Install ```sh npm install xlstream-fork pnpm add xlstream-fork yarn add xlstream-fork bun add xlstream-fork ``` ## Health **Score 35/100 (D)** — status: abandoned. Positive: has types; no vulnerabilities; high quality score. Warnings: low downloads; no esm support. Negative: abandoned. ## Facts | | | |---|---| | Version | 2.6.0 | | Published | 2020-11-16 | | First published | 2020-11-16 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 6 | | Unpacked size | 37.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 177 | | Maintainers | santypk4 | ## Links - npm: https://www.npmjs.com/package/xlstream-fork - Repository: https://github.com/Claviz/xlstream - Homepage: https://github.com/Claviz/xlstream#readme - Issues: https://github.com/Claviz/xlstream/issues - npm.io page: https://npm.io/package/xlstream-fork ## Dependencies (6) - [ssf](https://npm.io/package/ssf.md) ^0.11.2 - [fclone](https://npm.io/package/fclone.md) ^1.0.11 - [saxophone](https://npm.io/package/saxophone.md) ^0.6.1 - [sax-stream](https://npm.io/package/sax-stream.md) ^1.3.0 - [node-stream-zip](https://npm.io/package/node-stream-zip.md) ^1.11.3 - [deep-rename-keys](https://npm.io/package/deep-rename-keys.md) ^0.2.1 ## Recent versions - 2.6.0 (latest) — 2020-11-16 - 2.5.0 — 2020-11-16 - 2.4.0 — 2020-11-16 ## README [![Build Status](https://travis-ci.org/Claviz/xlstream.svg?branch=master)](https://travis-ci.org/Claviz/xlstream) [![codecov](https://codecov.io/gh/Claviz/xlstream/branch/master/graph/badge.svg)](https://codecov.io/gh/Claviz/xlstream) ![npm](https://img.shields.io/npm/v/xlstream.svg) # xlstream Memory-efficiently turns XLSX file into a [transform stream](https://nodejs.org/api/stream.html#stream_duplex_and_transform_streams) with all its benefits. * Stream is **pausable**. * Emits all **default events** (`data`, `end`, etc.) * Returns **header**, **raw** and **formatted** row data in just one `data` event. * Maintains desirable behavior of **merged cells**. * Supports files created by **OpenXML**. * Supports **standard**, **Excel** and **custom number formats**. ## Installation ``` npm install xlstream ``` ## Example `source.xlsx` contents: | A | B | |-------|-----| | hello | 123 | Where `123` is a `123.123` number formatted to be rounded to integer. **Script:** ```javascript const { getXlsxStream } = require('xlstream'); (async () => { const stream = await getXlsxStream({ filePath: './source.xlsx', sheet: 0, }); stream.on('data', x => console.log(x)); })(); ``` **Result:** ```JSON { "raw": { "obj": { "A": "hello", "B": 123.123 }, "arr": [ "hello", 123.123 ] }, "formatted": { "obj": { "A": "hello", "B": 123 }, "arr": [ "hello", 123 ] }, "header": [] } ``` ## getXlsxStream Returns _transform stream_ of the sheet. ### Options | option | type | description | |-----------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | filePath | `string` | Path to the XLSX file | | sheet | `string` or `number` | If `string` is passed, finds sheet by it's name. If `number`, finds sheet by it's index. | | withHeader | `boolean` or `number` | If `true`, column names will be taken from the first sheet row. If duplicated header name is found, column name will be prepended with column letter to maintain uniqueness. 0-based row location can be passed to this option if header is not located on the first row. | | ignoreEmpty | `boolean` | If `true`, empty rows won't be emitted. | | fillMergedCells | `boolean` | If `true`, merged cells will have the same value (by default, only the first cell of merged cells is filled with value). **Warning!** Enabling this feature may increase streaming time because file must be processed to detect merged cells before actual stream. | | numberFormat | `standard` or `excel` or `object` | By default `standard` format is used. Excel implementation of number formatting differs from standard (can be read [here](https://docs.microsoft.com/en-us/openspecs/office_standards/ms-oi29500/17d11129-219b-4e2c-88db-45844d21e528)) so `excel` option can be used to match this difference. If custom formatting is needed, a dictionary object can be passed to this option. | ## getXlsxStreams Async [generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*) which yields transform streams of the sheets. ### Options | Option | Type | Description | |----------|------------------------|---------------------------------------------| | filePath | `string` | Path to the _XLSX file_ | | sheets | array of sheet objects | Options of sheet object can be found below. | #### Sheet object | option | type | description | |-----------------|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | id | `string` or `number` | If `string` is passed, finds sheet by it's name. If `number`, finds sheet by it's index. | | withHeader | `boolean` | If `true`, column names will be taken from the first sheet row. If duplicated header name is found, column name will be prepended with column letter to maintain uniqueness. 0-based row location can be passed to this option if header is not located on the first row. | | ignoreEmpty | `boolean` | If `true`, empty rows won't be emitted. | | fillMergedCells | `boolean` | If `true`, merged cells will have the same value (by default, only the first cell of merged cells is filled with value). **Warning!** Enabling this feature may increase streaming time because file must be processed to detect merged cells before actual stream. | | numberFormat | `standard` or `excel` or `object` | By default `standard` format is used. Excel implementation of number formatting differs from standard (can be read [here](https://docs.microsoft.com/en-us/openspecs/office_standards/ms-oi29500/17d11129-219b-4e2c-88db-45844d21e528)) so `excel` option can be used to match this difference. If custom formatting is needed, a dictionary object can be passed to this option. | ## getWorksheets Returns array of sheets with `name` and `hidden` info. ### Options | Option | Type | Description | |----------|----------|-------------------------| | filePath | `string` | Path to the _XLSX file_ | ## Building You can build `js` source by using `npm run build` command. ## Testing Tests can be run by using `npm test` command. --- _Source: https://npm.io/package/xlstream-fork · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._