refactor: use options object for WASM function args, improve docs

- Add relevant links to all READMEs and source code
- Resolve clippy lints

czv:

- Add more docs for top-level items
- Add suggestion to use builder methods instead of functions
- Disable slice and slice tests until operation is complete

czv-wasm:

- Use tsify_next for allowing objects as parameters
- Add nodejs example and instructions

czv-wasm/Cargo.toml

@@ -12,6 +12,9 @@ crate-type = ["cdylib", "rlib"]
 [dependencies]
 anyhow = "1.0.86"
 csv = "1.3.0"
+serde = { version = "1.0.203", features = ["derive"] }
+serde-wasm-bindgen = "0.6.5"
 thiserror = "1.0.61"
+tsify-next = "0.5.3"
 wasm-bindgen = { version = "0.2" }
 wasm-bindgen-test = { version = "0.3.42" }

czv-wasm/README.md

@@ -2,8 +2,12 @@
 
 WebAssembly (JavaScript and TypeScript) library for [czv](https://github.com/rzmk/czv). czv is a library of CSV-related operations for data engineering and analysis tasks.
 
--   For a Rust library see [czv](https://github.com/rzmk/czv/tree/main/czv).
--   For a Python library see [czv-python](https://github.com/rzmk/czv/tree/main/czv-python).
+## Links
+
+-   czv GitHub repository: <https://github.com/rzmk/czv>
+-   Rust: [crates.io/crates/czv](https://crates.io/crates/czv) ([source code](https://github.com/rzmk/czv/tree/main/czv))
+-   WebAssembly (JavaScript/TypeScript): [npmjs.com/package/czv](https://www.npmjs.com/package/czv) ([source code](https://github.com/rzmk/czv/tree/main/czv-wasm))
+-   Python: [pypi.org/project/czv](https://pypi.org/project/czv/) ([source code](https://github.com/rzmk/czv/tree/main/czv-python))
 
 ## Installation and example
 
@@ -23,7 +27,11 @@ apple,2.50
 banana,3.00
 strawberry,1.50`;
 
-const output = czv.rowCount(data);
+const output = czv.rowCount({
+    file_data: data,
+    include_header_row: true,
+});
+
 console.log(output);
 ```
 
@@ -38,9 +46,11 @@ cargo install wasm-pack
 ### Build WASM for web
 
 ```bash
-wasm-pack build --release --target web
+wasm-pack build --release --target web --out-name czv
 ```
 
+**Note**: Currently you must modify the `pkg/package.json` by replacing the name from `czv-wasm` to `czv`.
+
 ### Test WASM for browser
 
 ```bash

czv-wasm/examples/basic-demo/README.md

@@ -0,0 +1 @@
+If you want to modify the TypeScript code then after you save your modifications you must run `tsc script.ts --module es2022 --target es2022` to generate a compatible `script.js` file.

czv-wasm/examples/basic-demo/index.html

@@ -40,30 +40,7 @@
             </tr>
         </tbody>
     </table>
-    <script type="module">
-        const input = document.getElementById("upload")
-        const progress = document.getElementById("progress")
-
-        import init, * as czv from "../../pkg/czv.js";
-        // Must run `await init()` or `initSync()` first for web use
-        await init();
-
-        const fileReader = new FileReader()
-
-        fileReader.onloadstart = () => {
-            progress.style.display = "block";
-        }
-
-        fileReader.onloadend = () => {
-            document.getElementById("column-count").innerText = czv.columnCount(fileReader.result)
-            document.getElementById("row-count").innerText = czv.rowCount(fileReader.result)
-            progress.style.display = "none";
-        }
-
-        input.addEventListener("change", () => {
-            fileReader.readAsText(input.files[0])
-        })
-    </script>
+    <script src="script.js" type="module"></script>
 </body>
 
 </html>

czv-wasm/examples/basic-demo/script.js

@@ -0,0 +1,27 @@
+const progress = document.getElementById("progress");
+import init, * as czv from "../../pkg/czv.js";
+// Must run `await init()` or `initSync()` first for web use
+await init();
+const fileReader = new FileReader();
+fileReader.onloadstart = () => {
+    if (progress)
+        progress.style.display = "block";
+};
+fileReader.onloadend = () => {
+    const rowCountElement = document.getElementById("row-count");
+    const columnCountElement = document.getElementById("column-count");
+    if (rowCountElement)
+        rowCountElement.innerText = String(czv.rowCount({
+            file_data: fileReader.result,
+        }));
+    if (columnCountElement)
+        columnCountElement.innerText = String(czv.columnCount({ file_data: fileReader.result }));
+    if (progress)
+        progress.style.display = "none";
+};
+const input = document.getElementById("upload");
+if (input)
+    input.addEventListener("change", () => {
+        // @ts-ignore
+        fileReader.readAsText(input.files[0]);
+    });

czv-wasm/examples/basic-demo/script.ts

@@ -0,0 +1,34 @@
+const progress = document.getElementById("progress");
+
+import init, * as czv from "../../pkg/czv.js";
+// Must run `await init()` or `initSync()` first for web use
+await init();
+
+const fileReader = new FileReader();
+
+fileReader.onloadstart = () => {
+    if (progress) progress.style.display = "block";
+};
+
+fileReader.onloadend = () => {
+    const rowCountElement = document.getElementById("row-count");
+    const columnCountElement = document.getElementById("column-count");
+    if (rowCountElement)
+        rowCountElement.innerText = String(
+            czv.rowCount({
+                file_data: fileReader.result as string,
+            })
+        );
+    if (columnCountElement)
+        columnCountElement.innerText = String(
+            czv.columnCount({ file_data: fileReader.result as string })
+        );
+    if (progress) progress.style.display = "none";
+};
+
+const input = document.getElementById("upload");
+if (input)
+    input.addEventListener("change", () => {
+        // @ts-ignore
+        fileReader.readAsText(input.files[0]);
+    });

czv-wasm/examples/node-demo/README.md

@@ -0,0 +1,4 @@
+To run this example:
+
+1. Build the `nodejs` compatible bundle in the `czv-wasm` directory with `wasm-pack build -t nodejs --release --out-name czv-ts`.
+2. Run `bunx tsx sample.ts` (or `npx`, `pnpx`, etc.).

czv-wasm/examples/node-demo/sample.ts

@@ -0,0 +1,12 @@
+import czv from "../../pkg/czv-ts";
+
+const options: czv.RowCountOptions = {
+    file_data: `fruit,price,
+apple,2.50
+banana,3.00
+strawberry,1.50`,
+};
+
+const output = czv.rowCount(options);
+
+console.log(output); // 4

czv-wasm/src/count.rs

@@ -1,32 +1,50 @@
 use crate::Result;
 use csv::ReaderBuilder;
+use serde::{Deserialize, Serialize};
+use tsify_next::Tsify;
 use wasm_bindgen::prelude::*;
 
+/// Options for `rowCount`.
+#[derive(Tsify, Serialize, Deserialize)]
+#[tsify(into_wasm_abi, from_wasm_abi)]
+pub struct RowCountOptions {
+    /// CSV file data.
+    pub file_data: String,
+
+    #[tsify(optional)]
+    /// Specify whether to include the header row (first row) in the row count.
+    /// Default is false.
+    pub include_header_row: Option<bool>,
+}
+
 /// Returns a count of the total number of rows.
-///
-/// @param {string} `file_data` CSV file data.
-/// @param {boolean | undefined} `include_header_row` Specify whether to include the header row (first row) in the row count. Default is false.
-/// @returns {number}
 #[wasm_bindgen(skip_jsdoc, js_name = rowCount)]
-pub fn row_count(file_data: String, include_header_row: Option<bool>) -> Result<usize> {
+pub fn row_count(options: RowCountOptions) -> Result<usize> {
     let mut rdr = ReaderBuilder::new();
 
-    rdr.has_headers(!include_header_row.unwrap_or(false));
-    return Ok(rdr.from_reader(file_data.as_bytes()).records().count());
+    rdr.has_headers(!options.include_header_row.unwrap_or(false));
+
+    Ok(rdr
+        .from_reader(options.file_data.as_bytes())
+        .records()
+        .count())
+}
+
+/// Options for `columnCount`.
+#[derive(Tsify, Serialize, Deserialize)]
+#[tsify(into_wasm_abi, from_wasm_abi)]
+pub struct ColumnCountOptions {
+    /// CSV file data.
+    pub file_data: String,
 }
 
 /// Returns a count of the total number of columns (fields).
-///
-/// ## Arguments
-///
-/// @param {string} `file_data` CSV file data.
 #[wasm_bindgen(skip_jsdoc, js_name = columnCount)]
-pub fn column_count(file_data: Option<String>) -> Result<usize> {
+pub fn column_count(options: ColumnCountOptions) -> Result<usize> {
     let rdr = ReaderBuilder::new();
 
-    if let Some(file_data) = file_data {
-        return Ok(rdr.from_reader(file_data.as_bytes()).headers()?.len());
-    } else {
-        bail!("Could not determine a file path or file data for column_count_builder.");
-    }
+    Ok(rdr
+        .from_reader(options.file_data.as_bytes())
+        .headers()?
+        .len())
 }

czv-wasm/src/lib.rs

@@ -1,3 +1,45 @@
+//! # czv
+//!
+//! WASM library for [czv](https://github.com/rzmk/czv). CSV operations library for data engineering/analysis tasks.
+//!
+//! # Example
+//!
+//! Let's say we want to print the total number of non-header rows in our data:
+//!
+//! ```js
+//! import init, * as czv from "czv";
+//! // Must run `await init()` or `initSync()` first for web use
+//! await init();
+//!
+//! const data = `fruits,price
+//! apple,2.50
+//! banana,3.00
+//! strawberry,1.50`;
+//!
+//! const output = czv.rowCount({
+//!     file_data: data,
+//!     include_header_row: true,
+//! });
+//!
+//! console.log(output);
+//! ```
+//!
+//! For a full website example see the example's source code here: https://www.npmjs.com/package/czv) <https://github.com/rzmk/czv/tree/main/czv-wasm/examples/basic-demo>
+//!
+//! # Links
+//!
+//! - czv GitHub repository: <https://github.com/rzmk/czv>
+//! - Rust: [crates.io/crates/czv](https://crates.io/crates/czv) ([source code](https://github.com/rzmk/czv/tree/main/czv))
+//! - WebAssembly (JavaScript/TypeScript): [npmjs.com/package/czv](https://www.npmjs.com/package/czv) ([source code](https://github.com/rzmk/czv/tree/main/czv-wasm))
+//! - Python: [pypi.org/project/czv](https://pypi.org/project/czv/) ([source code](https://github.com/rzmk/czv/tree/main/czv-python))
+
+#![allow(
+    // https://github.com/madonoharu/tsify/issues/42
+    non_snake_case,
+    // https://github.com/rustwasm/wasm-bindgen/issues/3945
+    clippy::empty_docs
+)]
+
 use wasm_bindgen::JsValue;
 
 // Error-handling helpers
@@ -11,9 +53,15 @@ impl From<csv::Error> for CzvError {
     }
 }
 
-impl Into<JsValue> for CzvError {
-    fn into(self) -> JsValue {
-        JsValue::from_str(self.to_string().as_str())
+impl From<serde_wasm_bindgen::Error> for CzvError {
+    fn from(value: serde_wasm_bindgen::Error) -> Self {
+        value.into()
+    }
+}
+
+impl From<CzvError> for JsValue {
+    fn from(val: CzvError) -> Self {
+        JsValue::from_str(val.to_string().as_str())
     }
 }
 

czv-wasm/tests/count.rs

@@ -1,4 +1,5 @@
 use czv_wasm;
+use czv_wasm::count::RowCountOptions;
 use czv_wasm::Result;
 use wasm_bindgen_test::*;
 wasm_bindgen_test::wasm_bindgen_test_configure!(run_in_browser);
@@ -6,14 +7,15 @@ wasm_bindgen_test::wasm_bindgen_test_configure!(run_in_browser);
 #[test]
 #[wasm_bindgen_test]
 fn basic() -> Result<()> {
-    let result = czv_wasm::count::row_count(
-        "fruit,price
+    let options = RowCountOptions {
+        file_data: "fruit,price
 apple,2.00
 banana,1.50
 strawberry,3.00"
             .to_string(),
-        Some(false),
-    )?;
+        include_header_row: Some(false),
+    };
+    let result = czv_wasm::count::row_count(options)?;
     assert_eq!(result, 3);
     Ok(())
 }