wasm-bindgen-lite 0.1.0

package/Cargo.lock

@@ -0,0 +1,27 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "wasm-bindgen-lite"
+version = "0.1.0"
+
+[[package]]
+name = "wasm-bindgen-lite-example-browser"
+version = "0.1.0"
+
+[[package]]
+name = "wasm-bindgen-lite-example-node"
+version = "0.1.0"
+
+[[package]]
+name = "wasm-bindgen-lite-example-offset-split"
+version = "0.1.0"
+
+[[package]]
+name = "wasm-bindgen-lite-example-simd-sum"
+version = "0.1.0"
+
+[[package]]
+name = "wasm-bindgen-lite-example-streaming-lines"
+version = "0.1.0"

package/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "wasm-bindgen-lite"
+version = "0.1.0"
+edition = "2021"
+description = "CLI tool and runtime to build Rust crates into minimal, SIMD-optimized WASM packages with JS loaders"
+license = "MIT"
+repository = "https://github.com/addmaple/wasm-bindgen-lite"
+
+[workspace]
+members = ["examples/*"]
+
+[lib]
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+
+[profile.release]
+opt-level = "s"
+lto = true
+codegen-units = 1
+panic = "abort"
+strip = true
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 wasm-bindgen-lite contributors
+
+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,313 @@
+# wasm-bindgen-lite
+
+An ultra-minimal, high-performance CLI tool and runtime for building Rust WebAssembly packages.
+
+`wasm-bindgen-lite` is designed for developers who want the performance of Rust WASM without the overhead and complexity of `wasm-bindgen`. It provides a thin, manual-memory-management layer that is perfect for performance-critical utilities like encoders, decoders, crypto, and data processing.
+
+## Why "Lite"?
+
+Traditional `wasm-bindgen` generates a lot of glue code and often hides the underlying memory management. While convenient, it can introduce overhead and make it difficult to optimize data transfers.
+
+**`wasm-bindgen-lite` gives you:**
+
+- **Zero-cost ABI**: Uses standard `extern "C"` functions.
+- **Manual Control**: Explicit `alloc` and `free` for maximum efficiency.
+- **SIMD by Default**: Built-in support for SIMD detection and fallback.
+- **Tiny Runtime**: A minimal JS wrapper (usually < 2KB) that works in Node.js and browsers.
+- **Modern ESM**: Pure ESM output for modern build tools and runtimes.
+
+## Key Features
+
+- 🚀 **SIMD Fallback**: Automatically compiles two versions of your WASM (baseline and SIMD). The runtime detects support and loads the fastest one.
+- 📦 **Dual Loaders**: Supports standard `.wasm` files (best for caching) or inlined base64 (best for single-file distribution).
+- 🔄 **Streaming Support**: Built-in integration with `TransformStream` for processing data chunks on the fly.
+- 🛠️ **Configurable**: Simple `wasm-bindgen-lite.config.json` to define your exports and behavior.
+- ⚡ **Optimized**: Integrated with `wasm-opt` for smallest possible binaries.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -D wasm-bindgen-lite
+```
+
+### 2. Prepare your Rust code
+
+Expose `alloc_bytes` and `free_bytes` along with your functions. No `wasm-bindgen` dependency required!
+
+```rust
+use std::alloc::{alloc, dealloc, Layout};
+use std::mem;
+
+#[no_mangle]
+pub unsafe extern "C" fn alloc_bytes(len: usize) -> *mut u8 {
+    let layout = Layout::from_size_align(len, mem::align_of::<u8>()).unwrap();
+    alloc(layout)
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn free_bytes(ptr: *mut u8, len: usize) {
+    let layout = Layout::from_size_align(len, mem::align_of::<u8>()).unwrap();
+    dealloc(ptr, layout);
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn my_transform(
+    in_ptr: *const u8, in_len: usize,
+    out_ptr: *mut u8, _out_len: usize,
+) -> isize {
+    let input = std::slice::from_raw_parts(in_ptr, in_len);
+    let output = std::slice::from_raw_parts_mut(out_ptr, in_len);
+
+    for i in 0..in_len {
+        output[i] = input[i].wrapping_add(1);
+    }
+
+    in_len as isize
+}
+```
+
+### 3. Build
+
+Run the CLI to compile and generate JS loaders:
+
+```bash
+rustup target add wasm32-unknown-unknown
+npx wasm-bindgen-lite build --crate . --out ./wasm-dist
+```
+
+### 4. Use in JavaScript
+
+If you've published your output as an npm package (e.g., `my-wasm-pkg`), consumers can simply import it. Modern runtimes and bundlers will automatically pick the correct version (Node vs Browser) via conditional exports.
+
+```javascript
+import { init, my_transform } from 'my-wasm-pkg'
+
+await init()
+
+const input = new Uint8Array([1, 2, 3])
+const output = my_transform(input)
+console.log(output) // Uint8Array([2, 3, 4])
+```
+
+## Publishing & Automatic Export Configuration
+
+When you build your project, `wasm-bindgen-lite` automatically detects your `package.json` and adds or updates the `exports` field to point to the generated artifacts.
+
+This ensures that modern runtimes and bundlers automatically pick the correct version (Node vs Browser) via conditional exports.
+
+### Generated Exports Configuration
+
+```json
+{
+  "exports": {
+    ".": {
+      "browser": "./wasm-dist/browser.js",
+      "node": "./wasm-dist/node.js",
+      "default": "./wasm-dist/node.js"
+    },
+    "./inline": {
+      "browser": "./wasm-dist/browser-inline.js",
+      "node": "./wasm-dist/node-inline.js",
+      "default": "./wasm-dist/node-inline.js"
+    }
+  }
+}
+```
+
+### Import Examples
+
+#### Standard (Automatic Environment Detection)
+
+Used by Vite, Webpack, and Node.js.
+
+```javascript
+import { init, my_transform } from 'my-wasm-pkg'
+await init()
+```
+
+#### Inline (Zero External Files)
+
+Perfect for serverless or single-file distribution.
+
+```javascript
+import { init, my_transform } from 'my-wasm-pkg/inline'
+await init()
+```
+
+#### CDN (jsDelivr, unpkg, etc.)
+
+Because the browser loader uses modern `import.meta.url` resolution, it works out-of-the-box on CDNs. No extra configuration is needed.
+
+```javascript
+import {
+  init,
+  my_transform,
+} from 'https://cdn.jsdelivr.net/npm/my-wasm-pkg/wasm-dist/browser.js'
+await init()
+```
+
+> **Note**: For advanced users, there is a `wasmDelivery: { type: "jsdelivr" }` config option if you want to bundle the JS locally but fetch WASM binaries from a CDN (offloading).
+
+## Initialization Modes (`autoInit`)
+
+The `autoInit` setting controls how and when the WASM module is instantiated.
+
+### 1. `off` (Default)
+
+You must manually call `init()` and wait for it before calling any WASM functions.
+
+```javascript
+import { init, process } from 'my-wasm-pkg'
+await init()
+const result = process(data) // Sync call
+```
+
+### 2. `lazy` (Automatic & Async)
+
+The generated wrapper functions are `async`. They will automatically call `init()` on the first invocation.
+
+```javascript
+import { process } from 'my-wasm-pkg'
+const result = await process(data) // First call inits automatically
+const result2 = await process(data2) // Subsequent calls use existing init
+```
+
+### 3. `eager` (Immediate)
+
+`init()` is called immediately when the module is imported.
+
+```javascript
+import { init, process } from 'my-wasm-pkg'
+// init() is already running in the background
+await init() // Ensure it's finished
+const result = process(data)
+```
+
+## Custom JS Wrapper
+
+You can provide a `js.custom` file to add high-level APIs. It has access to the internal `core.js` utilities.
+
+**Example `src/wrapper.js`:**
+
+```javascript
+import { createTransformStream } from './core.js'
+export * from './core.js' // Re-export everything from core
+
+const decoder = new TextDecoder()
+
+export function createLineStream() {
+  // createTransformStream handles alloc/free for you
+  const wasmSplit = createTransformStream('splitLines')
+
+  return wasmSplit.readable.pipeThrough(
+    new TransformStream({
+      transform(chunk, controller) {
+        controller.enqueue(decoder.decode(chunk))
+      },
+    })
+  )
+}
+```
+
+Specify it in your config:
+
+```json
+{
+  "js": { "custom": "src/wrapper.js" }
+}
+```
+
+## Configuration (`wasm-bindgen-lite.config.json`)
+
+```json
+{
+  "outDir": "wasm-dist",
+  "artifactBaseName": "mod",
+  "inline": true,
+  "targets": { "baseline": true, "simd": true },
+  "wasmOpt": { "mode": "auto", "args": ["-Oz"] },
+  "js": {
+    "emit": ["node", "browser", "inline"],
+    "custom": "src/wrapper.js"
+  },
+  "exports": [
+    {
+      "abi": "my_transform",
+      "name": "process",
+      "return": "bytes",
+      "reuseBuffer": true
+    }
+  ],
+  "autoInit": "lazy",
+  "stream": {
+    "enable": true,
+    "export": "process",
+    "delimiter": 10
+  },
+  "wasmDelivery": { "type": "relative" }
+}
+```
+
+### Configuration Options
+
+| Option                  | Description                                                  | Default       |
+| ----------------------- | ------------------------------------------------------------ | ------------- |
+| `outDir`                | Directory for generated files                                | `"dist"`      |
+| `artifactBaseName`      | Base name for `.wasm` files                                  | `"mod"`       |
+| `inline`                | Whether to generate inline JS modules                        | `false`       |
+| `autoInit`              | `"off"`, `"lazy"`, `"eager"`                                 | `"off"`       |
+| `exports`               | List of WASM functions to wrap                               | `[]`          |
+| `exports[].abi`         | Name of the `extern "C"` function in Rust                    | required      |
+| `exports[].name`        | Name of the exported JS function                             | same as `abi` |
+| `exports[].return`      | Return type: `bytes`, `f32`, `i32`, `u32`, etc.              | `"bytes"`     |
+| `exports[].reuseBuffer` | If true, reuses the same memory buffer to reduce allocations | `false`       |
+| `stream.enable`         | Generates a `createTransformStream()` helper                 | `false`       |
+| `js.custom`             | Path to a custom JS file to include in the runtime           | `null`        |
+
+## Advanced Usage
+
+### SIMD Acceleration
+
+`wasm-bindgen-lite` automatically compiles your Rust code with SIMD features enabled for the `.simd.wasm` target. The runtime detects support and picks the optimal binary.
+
+### Streaming Processing
+
+Use `createTransformStream()` for high-performance data pipelines:
+
+```javascript
+import { init, createTransformStream } from 'my-wasm-pkg'
+await init()
+
+const response = await fetch('data.bin')
+const processed = response.body.pipeThrough(createTransformStream())
+```
+
+## CLI Reference
+
+```bash
+wasm-bindgen-lite build [options]
+
+Options:
+  --crate <path>      Path to Rust crate (default: ".")
+  --out <path>        Output directory
+  --release           Build in release mode (default)
+  --debug             Build in debug mode
+  --inline            Generate inline JS loaders
+  --no-simd           Disable SIMD build
+  --wasm-opt          Enable wasm-opt (default)
+  --wasm-opt-args     Custom args for wasm-opt
+```
+
+## Examples
+
+- [node-basic](./examples/node-basic): Minimal Node.js setup.
+- [browser-vite](./examples/browser-vite): Modern browser setup with Vite.
+- [simd-sum](./examples/simd-sum): SIMD-accelerated array processing.
+- [streaming-lines](./examples/streaming-lines): Streaming data with custom wrappers.
+- [offset-split](./examples/offset-split): Advanced buffer management and complex ABI.
+
+## License
+
+MIT

package/bin/wasm-bindgen-lite.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { runBuild, runClean, printHelp } from '../src/cli/index.js'
+
+function parseArgs(raw) {
+  const [command, ...rest] = raw
+  const opts = {}
+  const unknown = []
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i]
+    switch (arg) {
+      case '--crate':
+        opts.crate = rest[++i]
+        break
+      case '--out':
+        opts.out = rest[++i]
+        break
+      case '--config':
+        opts.configPath = rest[++i]
+        break
+      case '--release':
+        opts.release = true
+        break
+      case '--debug':
+        opts.release = false
+        break
+      case '--inline':
+        opts.inline = true
+        break
+      case '--no-inline':
+        opts.inline = false
+        break
+      case '--simd':
+        opts.simd = true
+        break
+      case '--no-simd':
+        opts.simd = false
+        break
+      case '--wasm-opt':
+        opts.wasmOptMode = 'on'
+        break
+      case '--no-wasm-opt':
+        opts.wasmOptMode = 'off'
+        break
+      case '--wasm-opt-args':
+        opts.wasmOptArgs = (rest[++i] || '').split(' ').filter(Boolean)
+        break
+      case '--update-package-json':
+        opts.updatePackageJson = true
+        break
+      case '--no-update-package-json':
+        opts.updatePackageJson = false
+        break
+      case '--help':
+      case '-h':
+        opts.help = true
+        break
+      default:
+        if (arg.startsWith('-')) {
+          unknown.push(arg)
+        } else {
+          unknown.push(arg)
+        }
+        break
+    }
+  }
+
+  return { command, opts, unknown }
+}
+
+async function main() {
+  const { command, opts, unknown } = parseArgs(process.argv.slice(2))
+
+  if (opts.help || !command || command === 'help') {
+    printHelp()
+    return
+  }
+
+  if (unknown.length) {
+    console.warn(`Ignoring unknown arguments: ${unknown.join(', ')}`)
+  }
+
+  if (command === 'build') {
+    await runBuild(opts)
+    return
+  }
+
+  if (command === 'clean') {
+    await runClean(opts)
+    return
+  }
+
+  console.error(`Unknown command: ${command}`)
+  printHelp()
+  process.exitCode = 1
+}
+
+main().catch((err) => {
+  console.error(err?.stack || err)
+  process.exitCode = 1
+})

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "wasm-bindgen-lite",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CLI tool to build Rust crates into minimal, SIMD-optimized WASM packages with JS loaders",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/addmaple/wasm-bindgen-lite.git"
+  },
+  "homepage": "https://github.com/addmaple/wasm-bindgen-lite#readme",
+  "bugs": {
+    "url": "https://github.com/addmaple/wasm-bindgen-lite/issues"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "Cargo.toml",
+    "Cargo.lock",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "wasm-bindgen-lite": "./bin/wasm-bindgen-lite.js"
+  },
+  "main": "./src/cli/index.js",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "node bin/wasm-bindgen-lite.js build --crate . --out dist --no-update-package-json",
+    "test": "cargo test && node scripts/test.js",
+    "test:examples": "./scripts/test-examples.sh",
+    "lint": "npm run lint:js && npm run lint:rust",
+    "lint:js": "eslint . && prettier --check .",
+    "lint:rust": "cargo clippy --workspace -- -D warnings",
+    "format": "prettier --write . && cargo fmt"
+  },
+  "keywords": [
+    "wasm",
+    "rust",
+    "simd",
+    "minimal",
+    "loader"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "base64-js": "^1.5.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "globals": "^16.5.0",
+    "prettier": "^3.7.4"
+  },
+  "exports": {
+    ".": "./src/cli/index.js"
+  }
+}

package/scripts/build.js

@@ -0,0 +1,91 @@
+import { execSync } from 'node:child_process'
+import { mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const ROOT = join(__dirname, '..')
+const DIST = join(ROOT, 'dist')
+const SRC_JS = join(ROOT, 'src/js')
+
+function run(cmd, env = {}) {
+  console.log(`> ${cmd}`)
+  execSync(cmd, { stdio: 'inherit', env: { ...process.env, ...env } })
+}
+
+// 1. Ensure target directory exists
+mkdirSync(join(DIST, 'wasm'), { recursive: true })
+mkdirSync(join(DIST, 'wasm-inline'), { recursive: true })
+
+// 2. Build WASM (Baseline)
+console.log('Building baseline WASM...')
+run('cargo build --target wasm32-unknown-unknown --release')
+const baselineWasm = join(
+  ROOT,
+  'target/wasm32-unknown-unknown/release/wasm_bindgen_lite.wasm'
+)
+
+// 3. Build WASM (SIMD)
+console.log('Building SIMD WASM...')
+run('cargo build --target wasm32-unknown-unknown --release', {
+  RUSTFLAGS: '-C target-feature=+simd128',
+})
+const simdWasm = join(
+  ROOT,
+  'target/wasm32-unknown-unknown/release/wasm_bindgen_lite.wasm'
+)
+// Note: Since we are building the same crate, we need to move the baseline first or build into different targets.
+// Actually, cargo build will overwrite. Let's build baseline, move it, then build SIMD.
+
+// Let's redo step 2 and 3 properly
+console.log('Building baseline WASM...')
+run('cargo build --target wasm32-unknown-unknown --release')
+copyFileSync(baselineWasm, join(DIST, 'wasm/mod.base.wasm'))
+
+console.log('Building SIMD WASM...')
+run('cargo build --target wasm32-unknown-unknown --release', {
+  RUSTFLAGS: '-C target-feature=+simd128',
+})
+copyFileSync(simdWasm, join(DIST, 'wasm/mod.simd.wasm'))
+
+// 4. Optimize (Optional - check for wasm-opt)
+try {
+  run('wasm-opt --version')
+  console.log('Optimizing WASM...')
+  run(
+    `wasm-opt -Oz ${join(DIST, 'wasm/mod.base.wasm')} -o ${join(DIST, 'wasm/mod.base.wasm')}`
+  )
+  run(
+    `wasm-opt -Oz ${join(DIST, 'wasm/mod.simd.wasm')} -o ${join(DIST, 'wasm/mod.simd.wasm')}`
+  )
+} catch (e) {
+  console.warn('wasm-opt not found, skipping optimization.')
+}
+
+// 5. Generate inline JS modules
+function generateInline(name, wasmPath) {
+  const bytes = readFileSync(wasmPath)
+  const content = `// auto-generated\nexport const wasmBytes = new Uint8Array([${bytes.join(',')}]);\n`
+  writeFileSync(join(DIST, `wasm-inline/mod.${name}.wasm.js`), content)
+}
+
+console.log('Generating inline WASM modules...')
+generateInline('base', join(DIST, 'wasm/mod.base.wasm'))
+generateInline('simd', join(DIST, 'wasm/mod.simd.wasm'))
+
+// 6. Copy JS files
+console.log('Copying JS loaders...')
+const jsFiles = [
+  'core.js',
+  'util.js',
+  'browser.js',
+  'node.js',
+  'browser-inline.js',
+  'node-inline.js',
+]
+
+for (const f of jsFiles) {
+  copyFileSync(join(SRC_JS, f), join(DIST, f))
+}
+
+console.log('Build complete!')

package/scripts/test-examples.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+set -e
+
+# Build the root package first
+npm run build
+
+for dir in examples/*; do
+  if [ -d "$dir" ]; then
+    echo "--- Testing $dir ---"
+    cd "$dir"
+    npm install
+    npm run build:wasm
+    if npm run test --if-present; then
+      echo "Tests passed for $dir"
+    fi
+    if npm run demo --if-present; then
+      echo "Demo passed for $dir"
+    fi
+    if [ -d "tests" ] && [ -f "playwright.config.js" ]; then
+      npx playwright install chromium
+      npm run test:pw
+    fi
+    cd ../..
+  fi
+done