Add WASM support with bindings for CityJSONSeq operations

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: Cargo Check
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Rust
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+      - name: Run fmt
+        run: cargo fmt -- --check
+      - name: Run clippy
+        run: cargo clippy
+      - name: Run check
+        run: cargo check

Cargo.toml

@@ -9,6 +9,8 @@ readme = "README.md"
 homepage = "https://github.com/cityjson/cjseq"
 repository = "https://github.com/cityjson/cjseq"
 
+[lib]
+crate-type = ["cdylib", "rlib"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
@@ -19,4 +21,15 @@ serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 # serde_derive = "1.0"
 
+# WASM dependencies
+wasm-bindgen = { version = "0.2", features = ["serde-serialize"] }
+serde-wasm-bindgen = "0.6"
 
+[dependencies.web-sys]
+version = "0.3"
+features = ["console"]
+
+# WASM-specific dependencies
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+console_error_panic_hook = "0.1"
+getrandom = { version = "0.2", features = ["js"] }

README.md

@@ -27,7 +27,7 @@
 
 ## Usage
 
-`cjseq` takes input from either a file or the standard input (stdin, if no file path is given as argument), and it always outputs the results to the standard output (stdout). 
+`cjseq` takes input from either a file or the standard input (stdin, if no file path is given as argument), and it always outputs the results to the standard output (stdout).
 The output can be a CityJSON object or a CityJSONSeq stream.
 
 ### Convert CityJSON to CityJSONSeq
@@ -70,3 +70,17 @@ cat ./data/*.city.jsonl | cjseq collect > hugefile.city.json
 
   1. the input CityJSON/Seq must be v1.1 or v2.0 (v1.0 will panic).
   2. the input JSON must be CityJSON schema-valid, use [cjval](https://github.com/cityjson/cjval) to validate.
+
+## WASM bindings
+
+`cjseq` can be used in JavaScript/TypeScript applications via WASM bindings.
+
+```sh
+cargo install wasm-pack
+```
+
+Build the WASM bindings:
+
+```sh
+wasm-pack build --release --target web --out-dir js
+```

js/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Hugo Ledoux
+
+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.

js/README.md

@@ -0,0 +1,72 @@
+
+# cjseq
+
+[![crates.io](https://img.shields.io/crates/v/cjseq.svg)](https://crates.io/crates/cjseq)
+
+`cjseq` is a Rust libray+binary for creating, processing, and modifying [CityJSONSeq](https://cityjson.org/cityjsonseq) files, as well as converting to/from [CityJSON](https://cityjson.org).
+
+## Installation
+
+### Installing the binary
+
+1. Install the [Rust compiler](https://www.rust-lang.org/learn/get-started)
+2. Run `cargo install cjseq`
+3. Then a binary called `cjseq` is installed system-wide
+
+### Installing the library
+
+1. Install the [Rust compiler](https://www.rust-lang.org/learn/get-started)
+2. Run `cargo install cjseq`
+
+### Compiling the project
+
+1. Install the [Rust compiler](https://www.rust-lang.org/learn/get-started)
+2. Clone the repository: `git clone https://github.com/cityjson/cjseq.git`
+3. Build the project: `cargo build --release`
+4. Run the program: `./target/release/cjseq --help`
+
+## Usage
+
+`cjseq` takes input from either a file or the standard input (stdin, if no file path is given as argument), and it always outputs the results to the standard output (stdout). 
+The output can be a CityJSON object or a CityJSONSeq stream.
+
+### Convert CityJSON to CityJSONSeq
+
+Convert a CityJSON file to a CityJSONSeq stream:
+
+```sh
+cjseq cat myfile.city.json > myfile.city.jsonl
+```
+
+Alternatively, to use stdin:
+
+```sh
+cat myfile.city.json | cjseq cat
+```
+
+### Convert CityJSONSeq to CityJSON
+
+Convert a CityJSONSeq stream to a CityJSON file:
+
+```sh
+cat ./data/3dbag_b2.city.jsonl | cjseq collect > 3dbag_b2.city.json
+```
+
+```sh
+cjseq collect ./data/3dbag_b2.city.jsonl > 3dbag_b2.city.json
+```
+
+[Globbing](https://en.wikipedia.org/wiki/Glob_(programming)) works for the `collect` command:
+
+```sh
+cat ./data/*.city.jsonl | cjseq collect > hugefile.city.json
+```
+
+### Filter CityJSONSeq
+
+`cat myfile.city.jsonl | cjseq filter --bbox 85007 446179 85168 446290 > mysubset.city.jsonl`
+
+## Input constraints
+
+  1. the input CityJSON/Seq must be v1.1 or v2.0 (v1.0 will panic).
+  2. the input JSON must be CityJSON schema-valid, use [cjval](https://github.com/cityjson/cjval) to validate.

js/cjseq.d.ts

@@ -0,0 +1,62 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Initialize the WASM module with panic hook for better error messages
+ */
+export function main(): void;
+/**
+ * Convert a base CityJSON metadata and array of CityJSONFeatures into a complete CityJSON object
+ *
+ * # Arguments
+ * * `base_cj` - The base CityJSON metadata object (typically first line of CityJSONSeq)
+ * * `features` - Array of CityJSONFeature objects
+ *
+ * # Returns
+ * * `Result<JsValue, JsValue>` - Complete CityJSON object or error
+ *
+ * # Example
+ * ```javascript
+ * import init, { cjseqToCj } from './cjseq.js';
+ *
+ * await init();
+ * const result = cjseqToCj(baseCityJSON, featuresArray);
+ * ```
+ */
+export function cjseqToCj(base_cj: any, features: any): any;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+  readonly memory: WebAssembly.Memory;
+  readonly cjseqToCj: (a: any, b: any) => [number, number, number];
+  readonly main: () => void;
+  readonly __wbindgen_malloc: (a: number, b: number) => number;
+  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+  readonly __wbindgen_exn_store: (a: number) => void;
+  readonly __externref_table_alloc: () => number;
+  readonly __wbindgen_export_4: WebAssembly.Table;
+  readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+  readonly __externref_table_dealloc: (a: number) => void;
+  readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+/**
+* Instantiates the given `module`, which can either be bytes or
+* a precompiled `WebAssembly.Module`.
+*
+* @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+*
+* @returns {InitOutput}
+*/
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+* If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+* for everything else, calls `WebAssembly.instantiate` directly.
+*
+* @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+*
+* @returns {Promise<InitOutput>}
+*/
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;