web-csv-toolbox 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +117 -64
- package/lib/index.d.ts +496 -23
- package/lib/index.js +33 -216
- package/lib/index.umd.js +1 -0
- package/package.json +7 -4
package/README.md
CHANGED
|
@@ -1,38 +1,73 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
[](https://github.com/kamiazya/web-csv-toolbox/actions/workflows/node.js.yaml)
|
|
4
|
+
[](https://badge.fury.io/js/web-csv-toolbox)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
[](http://makeapullrequest.com)
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# `🌐 web-csv-toolbox 💽`
|
|
2
11
|
|
|
3
12
|
A CSV Toolbox utilizing Web Standard APIs.
|
|
4
13
|
|
|
5
|
-
|
|
14
|
+
🔗
|
|
6
15
|
|
|
7
|
-
-
|
|
8
|
-
|
|
9
|
-
-
|
|
10
|
-
|
|
11
|
-
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
- Only web standard APIs are used, so it should work with these Runtimes.
|
|
16
|
+
[](https://github.com/kamiazya/web-csv-toolbox)
|
|
17
|
+
[](https://www.npmjs.com/package/web-csv-toolbox)
|
|
18
|
+
[](https://yarnpkg.com/package/web-csv-toolbox)
|
|
19
|
+
[](https://kamiazya.github.io/web-csv-toolbox/)
|
|
20
|
+
[](https://github.com/sponsors/kamiazya)
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
[](https://biomejs.dev/)
|
|
24
|
+
[](https://vitest.dev/)
|
|
25
|
+
[](https://rollupjs.org/)
|
|
18
26
|
|
|
19
|
-
|
|
27
|
+
</div>
|
|
20
28
|
|
|
21
|
-
|
|
22
|
-
- Supports parsing CSV files from strings, `ReadableStream`s, and `Response` objects.
|
|
23
|
-
- Supports parsing CSV files with different delimiters and quotation characters.
|
|
24
|
-
- Defaults to `,` and `"` respectively.
|
|
25
|
-
- Supports parsing TSV files by setting `delimiter` to `\t`.
|
|
26
|
-
- Supports parsing with multi-character/multi-byte delimiters and quotation characters.
|
|
27
|
-
- Supports parsing binary CSV files.
|
|
29
|
+
---
|
|
28
30
|
|
|
29
|
-
##
|
|
31
|
+
## Key Concepts ✨
|
|
32
|
+
|
|
33
|
+
- 🌐 **Web Standards first.**
|
|
34
|
+
- Utilizing the Web Standards APIs, such as the [Web Streams API](https://developer.mozilla.org/en/docs/Web/API/Streams_API).
|
|
35
|
+
- ❤️ **TypeScript friendly & User friendly.**
|
|
36
|
+
- Fully typed and documented.
|
|
37
|
+
- 0️⃣ **Zero dependencies.**
|
|
38
|
+
- Using only Web Standards APIs.
|
|
39
|
+
- 💪 **Property-based testing.**
|
|
40
|
+
- Using [fast-check](https://fast-check.dev/) and [vitest](https://vitest.dev).
|
|
41
|
+
- ✅ **_To Be Tested_** **Cross-platform.**
|
|
42
|
+
- Works on browsers, Node.js, and Deno.
|
|
43
|
+
- Only web standard APIs are used, so it should work with these runtimes.
|
|
44
|
+
|
|
45
|
+
## Key Features 📗
|
|
46
|
+
|
|
47
|
+
- 🌊 **Efficient CSV Parsing with Streams**
|
|
48
|
+
- 💻 Leveraging the [WHATWG Streams API](https://streams.spec.whatwg.org/) and other Web APIs for seamless and efficient data processing.
|
|
49
|
+
- 🎨 **Flexible Source Support**
|
|
50
|
+
- 🧩 Parse CSVs directly from `string`s, `ReadableStream`s, or `Response` objects.
|
|
51
|
+
- ⚙️ **Advanced Parsing Options**: Customize your experience with various delimiters and quotation marks.
|
|
52
|
+
- 🔄 Defaults to `,` and `"` respectively.
|
|
53
|
+
- 🛠️ Use multi-character/multi-byte delimiters and quotations.
|
|
54
|
+
- 💾 **Specialized Binary CSV Parsing**: Leverage Stream-based processing for versatility and strength.
|
|
55
|
+
- 🔄 Flexible BOM handling.
|
|
56
|
+
- 🗜️ Supports various compression formats.
|
|
57
|
+
- 🔤 Charset specification for diverse encoding.
|
|
58
|
+
|
|
59
|
+
## Installation 📥
|
|
30
60
|
|
|
31
61
|
```sh
|
|
32
|
-
|
|
62
|
+
# Install with npm
|
|
63
|
+
$ npm install web-csv-toolbox
|
|
64
|
+
# Or Yarn
|
|
65
|
+
$ yarn add web-csv-toolbox
|
|
66
|
+
# Or pnpm
|
|
67
|
+
$ pnpm add web-csv-toolbox
|
|
33
68
|
```
|
|
34
69
|
|
|
35
|
-
## Usage
|
|
70
|
+
## Usage 📘
|
|
36
71
|
|
|
37
72
|
### Parsing CSV files from strings
|
|
38
73
|
|
|
@@ -107,7 +142,7 @@ for await (const record of parse(csv, { delimiter: '\t' })) {
|
|
|
107
142
|
// { name: 'Bob', age: '69' }
|
|
108
143
|
```
|
|
109
144
|
|
|
110
|
-
### Parsing CSV files with
|
|
145
|
+
### Parsing CSV files with headers
|
|
111
146
|
|
|
112
147
|
```js
|
|
113
148
|
import { parse } from 'web-csv-toolbox';
|
|
@@ -123,69 +158,87 @@ for await (const record of parse(csv, { headers: ['name', 'age'] })) {
|
|
|
123
158
|
// { name: 'Bob', age: '69' }
|
|
124
159
|
```
|
|
125
160
|
|
|
126
|
-
## APIs
|
|
127
|
-
|
|
128
|
-
### High-level APIs
|
|
129
|
-
|
|
130
|
-
#### `parse(input[, options]): AsyncIterableIterator<Record>` function
|
|
131
|
-
|
|
132
|
-
Returns an asynchronous iterable of records.
|
|
161
|
+
## APIs 🧑💻
|
|
133
162
|
|
|
134
|
-
|
|
163
|
+
### High-level APIs 🚀
|
|
135
164
|
|
|
136
|
-
|
|
165
|
+
These APIs are designed for **Simplicity and Ease of Use**,
|
|
166
|
+
providing an intuitive and straightforward experience for users.
|
|
137
167
|
|
|
138
|
-
|
|
168
|
+
- **`function parse(input[, options]): AsyncIterableIterator<CSVRecord>`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parse-1.html)
|
|
169
|
+
- Parses various CSV input formats into an asynchronous iterable of records.
|
|
170
|
+
- **`function parse.toArray(input[, options]): Promise<CSVRecord[]>`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parse.toArray.html)
|
|
171
|
+
- Parses CSV input into an array of records, ideal for smaller data sets.
|
|
139
172
|
|
|
140
|
-
|
|
173
|
+
The `input` paramater can be a `string`, a [ReadableStream](https://developer.mozilla.org/docs/Web/API/ReadableStream)
|
|
174
|
+
of `string`s or [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)s,
|
|
175
|
+
or a [Response](https://developer.mozilla.org/docs/Web/API/Response) object.
|
|
141
176
|
|
|
142
|
-
|
|
177
|
+
### Middle-level APIs 🧱
|
|
143
178
|
|
|
144
|
-
|
|
179
|
+
These APIs are optimized for **Enhanced Performance and Control**,
|
|
180
|
+
catering to users who need more detailed and fine-tuned functionality.
|
|
145
181
|
|
|
146
|
-
|
|
182
|
+
- **`function parseBinaryStream(stream[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseBinaryStream-1.html)
|
|
183
|
+
- Parses binary streams with precise control over data types.
|
|
184
|
+
- **`function parseResponse(response[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseResponse-1.html)
|
|
185
|
+
- Customized parsing directly from `Response` objects.
|
|
186
|
+
- **`function parseStream(stream[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseStream-1.html)
|
|
187
|
+
- Stream-based parsing for larger or continuous data.
|
|
188
|
+
- **`function parseString(string[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseString-1.html)
|
|
189
|
+
- Efficient parsing of CSV strings.
|
|
190
|
+
- **`function parseStringStream(stream[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseStringStream-1.html)
|
|
191
|
+
- Combines string-based parsing with stream processing.
|
|
147
192
|
|
|
148
|
-
|
|
193
|
+
### Low-level APIs ⚙️
|
|
149
194
|
|
|
150
|
-
|
|
195
|
+
These APIs are built for **Advanced Customization and Pipeline Design**,
|
|
196
|
+
ideal for developers looking for in-depth control and flexibility.
|
|
151
197
|
|
|
152
|
-
|
|
198
|
+
- **`class LexerTransformer`**: [📑](https://kamiazya.github.io/web-csv-toolbox/classes/LexerTransformer.html)
|
|
199
|
+
- A TransformStream class for lexical analysis of CSV data.
|
|
200
|
+
- **`class RecordAssemblerTransformer`**: [📑](https://kamiazya.github.io/web-csv-toolbox/classes/RecordAssemblerTransformar.html)
|
|
201
|
+
- Handles the assembly of parsed data into records.
|
|
153
202
|
|
|
154
|
-
|
|
203
|
+
## Options Configuration 🛠️
|
|
155
204
|
|
|
156
|
-
|
|
205
|
+
### Common Options ⚙️
|
|
157
206
|
|
|
158
|
-
|
|
207
|
+
| Option | Description | Default | Notes |
|
|
208
|
+
| -------------- | ------------------------------------- | ----------- | ----- |
|
|
209
|
+
| `delimiter` | Character to separate fields | `,` | |
|
|
210
|
+
| `quotation` | Character used for quoting fields | `"` | |
|
|
211
|
+
| `headers` | Custom headers for the parsed records | First row | If not provided, the first row is used as headers |
|
|
159
212
|
|
|
160
|
-
|
|
213
|
+
### Advanced Options (Binary-Specific) 🧬
|
|
161
214
|
|
|
162
|
-
|
|
215
|
+
| Option | Description | Default | Notes |
|
|
216
|
+
| --------------- | ------------------------------------------------- | --------- | ---------------------- |
|
|
217
|
+
| `charset` | Character encoding for binary CSV inputs | `utf-8` | See [Encoding API Compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings) for the encoding formats that can be specified. |
|
|
218
|
+
| `decompression` | Decompression algorithm for compressed CSV inputs | | See [DecompressionStream Compatibility](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream#browser_compatibilit). |
|
|
219
|
+
| `ignoreBOM` | Whether to ignore Byte Order Mark (BOM) | `false` | See [TextDecoderOptions.ignoreBOM](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoderStream/ignoreBOM) for more information about the BOM. |
|
|
220
|
+
| `fatal` | Throw an error on invalid characters | `false` | See [TextDecoderOptions.fatal](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoderStream/fatal) for more information. |
|
|
163
221
|
|
|
164
|
-
|
|
165
|
-
- `deflate`
|
|
166
|
-
- `deflate-raw`
|
|
167
|
-
- Note: This format is supported in Node.js v21.2.0 and above.
|
|
222
|
+
## How to Contribute 💪
|
|
168
223
|
|
|
169
|
-
|
|
224
|
+
## Star ⭐
|
|
170
225
|
|
|
171
|
-
The
|
|
226
|
+
The easiest way to contribute is to use the library and star [repository](https://github.com/kamiazya/web-csv-toolbox/).
|
|
172
227
|
|
|
173
|
-
|
|
228
|
+
### Questions 💭
|
|
174
229
|
|
|
175
|
-
|
|
230
|
+
Feel free to ask questions on [GitHub Discussions](https://github.com/kamiazya/web-csv-toolbox/discussions).
|
|
176
231
|
|
|
177
|
-
|
|
178
|
-
Defaults to `false`.
|
|
232
|
+
### Report bugs / request additional features 💡
|
|
179
233
|
|
|
180
|
-
|
|
234
|
+
Please register at [GitHub Issues](https://github.com/kamiazya/web-csv-toolbox/issues/new/choose).
|
|
181
235
|
|
|
182
|
-
|
|
183
|
-
Defaults to `false`.
|
|
236
|
+
### Financial Support 💸
|
|
184
237
|
|
|
185
|
-
|
|
238
|
+
Please support [kamiazya](https://github.com/sponsors/kamiazya).
|
|
186
239
|
|
|
187
|
-
|
|
240
|
+
> Even just a dollar is enough motivation to develop 😊
|
|
188
241
|
|
|
189
|
-
## License
|
|
242
|
+
## License ⚖️
|
|
190
243
|
|
|
191
|
-
[
|
|
244
|
+
This software is released under the MIT License, see [LICENSE](https://github.com/kamiazya/web-csv-toolbox?tab=MIT-1-ov-file).
|