web-csv-toolbox 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Yuki Yamazaki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# web-csv-toolbox
+
+A CSV Toolbox utilizing Web Standard APIs.
+
+## Key concepts
+
+- Web Standards first.
+  - Using the [Web Streams API](https://streams.spec.whatwg.org/).
+- TypeScript friendly & User friendly.
+  - Fully typed and documented.
+- Zero dependencies.
+  - Using only Web Standards APIs.
+- Property-based testing.
+  - Using [fast-check](https://fast-check.dev/) and [vitest](https://vitest.dev).
+- **To Be Tested** Cross platform.
+  - Works on browsers and Node.js, Deno
+    - Only web standard APIs are used, so it should work with these Runtimes.
+
+## Key features
+
+- Parses CSV files using the [WHATWG Streams API](https://streams.spec.whatwg.org/).
+- Supports parsing CSV files from strings, `ReadableStream`s, and `Response` objects.
+- Supports parsing CSV files with different delimiters and quotation characters.
+  - Defaults to `,` and `"` respectively.
+  - Supports parsing TSV files by setting `delimiter` to `\t`.
+  - Supports parsing with multi-character/multi-byte delimiters and quotation characters.
+- Supports parsing binary CSV files.
+
+## Installation
+
+```sh
+npm install web-csv-toolbox
+```
+
+## Usage
+
+### Parsing CSV files from strings
+
+```js
+import { parse } from 'web-csv-toolbox';
+
+const csv = `name,age
+Alice,42
+Bob,69`;
+
+for await (const record of parse(csv)) {
+  console.log(record);
+}
+// Prints:
+// { name: 'Alice', age: '42' }
+// { name: 'Bob', age: '69' }
+```
+
+## Parsing CSV files from `ReadableStream`s
+
+```js
+import { parse } from 'web-csv-toolbox';
+
+const csv = `name,age
+Alice,42
+Bob,69`;
+
+const stream = new ReadableStream({
+  start(controller) {
+    controller.enqueue(csv);
+    controller.close();
+  },
+});
+
+for await (const record of parse(stream)) {
+  console.log(record);
+}
+// Prints:
+// { name: 'Alice', age: '42' }
+// { name: 'Bob', age: '69' }
+```
+
+### Parsing CSV files from `Response` objects
+
+```js
+import { parse } from 'web-csv-toolbox';
+
+const response = await fetch('https://example.com/data.csv');
+
+for await (const record of parse(response)) {
+  console.log(record);
+}
+// Prints:
+// { name: 'Alice', age: '42' }
+// { name: 'Bob', age: '69' }
+```
+
+### Parsing CSV files with different delimiters and quotation characters
+
+```js
+import { parse } from 'web-csv-toolbox';
+
+const csv = `name\tage
+Alice\t42
+Bob\t69`;
+
+for await (const record of parse(csv, { delimiter: '\t' })) {
+  console.log(record);
+}
+// Prints:
+// { name: 'Alice', age: '42' }
+// { name: 'Bob', age: '69' }
+```
+
+### Parsing CSV files with different headers
+
+```js
+import { parse } from 'web-csv-toolbox';
+
+const csv = `Alice,42
+Bob,69`;
+
+for await (const record of parse(csv, { headers: ['name', 'age'] })) {
+  console.log(record);
+}
+// Prints:
+// { name: 'Alice', age: '42' }
+// { name: 'Bob', age: '69' }
+```
+
+## API
+
+### High-level APIs
+
+#### `parse(input[, options]): AsyncIterableIterator<Record>` function
+
+Returns an asynchronous iterable of records.
+
+##### `input` parameter
+
+The input to parse. This can be a `string`, a `ReadableStream` of `string`s or `Uint8Array`s, or a `Response` object.
+
+##### `options` parameter
+
+An optional object with the following properties:
+
+###### `options.delimiter`
+
+The character used to separate fields in the CSV input. Defaults to `,`.
+
+###### `options.quotation`
+
+The character used to quote fields in the CSV input. Defaults to `"`.
+
+###### `options.headers`
+
+An optional array of strings to use as the headers for the parsed records.
+
+If not provided, the first record will be used as the headers.
+
+###### `options.decompression`
+
+The decompression format to use when parsing the binary CSV input.
+
+If not provided, the input will be treated as text.
+
+Possible values are:
+
+- `gzip`
+- `deflate`
+- `deflate-raw`
+  - Note: This format is supported in Node.js v21.2.0 and above.
+
+###### `options.charset`
+
+The character set to use when parsing the binary CSV input.
+
+Defaults to `utf-8`.
+
+###### `options.ignoreBOM`
+
+Whether to ignore a leading BOM in the CSV input.
+Defaults to `false`.
+
+###### `options.fatal`
+
+Whether to throw an error if the CSV input is invalid.
+Defaults to `false`.
+
+### Low-level APIs
+
+For low-level API details, please refer to [source code](https://github.com/kamiazya/web-csv-toolbox).
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "web-csv-toolbox",
+  "version": "0.0.1",
+  "description": "A CSV Toolbox utilizing Web Standard APIs.",
+  "type": "module",
+  "main": "lib/index.js",
+  "module": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "exports": {
+    ".": {
+      "default": "./lib/index.js",
+      "types": "./lib/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest",
+    "format": "biome format . --write",
+    "lint": "biome lint .",
+    "check": "biome check src --apply",
+    "check:no-apply": "biome check src",
+    "build": "rollup -c rollup.config.ts --configPlugin rollup-plugin-typescript2 && biome format lib --write",
+    "prepare": "husky install"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kamiazya/web-csv-toolbox.git"
+  },
+  "keywords": [
+    "csv",
+    "parser",
+    "web-streams",
+    "web-streams-api"
+  ],
+  "author": "Yuki Yamazaki <yuki@kamiazya.tech>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/kamiazya/web-csv-toolbox/issues"
+  },
+  "homepage": "https://github.com/kamiazya/web-csv-toolbox#readme",
+  "devDependencies": {
+    "@biomejs/biome": "1.4.1",
+    "@changesets/cli": "^2.27.1",
+    "@fast-check/vitest": "^0.0.8",
+    "husky": "^8.0.0",
+    "jsdom": "^23.0.1",
+    "lint-staged": "^15.2.0",
+    "rollup": "^4.9.1",
+    "rollup-plugin-delete": "^2.0.0",
+    "rollup-plugin-dts": "^6.1.0",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "typescript": "^5.3.2",
+    "vitest": "^0.34.6"
+  }
+}