feat: Refactor and update WASM module and build scripts

- Removed .yarnrc.yml and yarn.lock files, transitioning to npm for package management.
- Enhanced build.sh and docker-build.sh scripts for improved error handling and clarity.
- Updated package.json to reflect new project name and version, and added necessary fields for npm publishing.
- Expanded API in index.d.ts to include InitOptions and updated function signatures for compress and decompress.
- Revised README for clarity on usage with Vite and updated examples.
- Reworked test suite to utilize modern JavaScript features and ensure compatibility with the new API structure.

This commit prepares the project for npm trusted publishing and improves overall usability and documentation.

Author: joaner

.github/workflows/ci.yml

@@ -3,37 +3,21 @@ name: CI
 on:
   push:
     branches: [main]
-    tags: ["v*"]
   pull_request:
-    branches: ["*"]
+    branches: [main]
 
 jobs:
-  wasm-zstd:
+  build-test:
     runs-on: ubuntu-latest
-
-    permissions:
-      contents: read
-      # https://docs.npmjs.com/generating-provenance-statements#publishing-packages-with-provenance-via-github-actions
-      id-token: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        node-version: [18.x, 20.x, 22.x]
-
     steps:
-      - uses: actions/checkout@v6
-      - run: corepack enable
-      - uses: actions/setup-node@v6
-        with:
-          node-version: ${{ matrix.node-version }}
-          registry-url: https://registry.npmjs.org
-          cache: yarn
+      - uses: actions/checkout@v4
 
-      - run: yarn install --immutable
-      - run: yarn build
-      - run: yarn test
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
 
-      - name: Publish to NPM
-        if: ${{ startsWith(github.ref, 'refs/tags/v') && matrix.node-version == '18.x' }}
-        run: yarn npm publish --provenance --access public
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npm run pack:check

.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  validate:
+    name: Validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npm run pack:check
+
+      - name: Upload package artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 1
+
+  publish-npm:
+    name: Publish to npm
+    needs: validate
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - name: Download package artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish-npm
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ github.ref_name }}
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(github.ref_name, '-') }}

.yarnrc.yml

@@ -1,64 +1,62 @@
-# @foxglove/wasm-zstd
+# @ioai/wasm-zstd
 
-https://github.com/facebook/zstd compiled to WebAssembly and exposed as a high-level TypeScript/JavaScript API . PRs welcome!
+Vite-friendly WebAssembly bindings for [facebook/zstd](https://github.com/facebook/zstd).
 
 ## API
 
-`@foxglove/wasm-zstd` exports:
+`@ioai/wasm-zstd` exports:
 
 ```typescript
-export const isLoaded: Promise<boolean>;
+export interface InitOptions {
+  wasmUrl?: string | URL;
+  wasmBinary?: ArrayBuffer | ArrayBufferView;
+  locateFile?: (path: string, prefix: string) => string;
+  module?: Record<string, unknown>;
+}
+
+export function init(options?: InitOptions): Promise<void>;
 export function compressBound(size: number): number;
-export function compress(buffer: Uint8Array, compressionLevel?: number): Buffer;
-export function decompress(buffer: Uint8Array, size: number): Buffer;
+export function compress(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, compressionLevel?: number): Uint8Array;
+export function decompress(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, size: number): Uint8Array;
 ```
 
-Here is an example of compressing then decompressing with this library:
-
-```js
-import fs from "fs/promises";
-import zstd from "@foxglove/wasm-zstd";
+## Usage with Vite
 
-async function main() {
-  const inputData = await fs.readFile("input.txt");
+Import the wasm binary as an explicit URL and initialize the module once before calling
+`compress` or `decompress`.
 
-  // Wait for the wasm module to load
-  await zstd.isLoaded;
+```ts
+import { compress, decompress, init } from "@ioai/wasm-zstd";
+import wasmUrl from "@ioai/wasm-zstd/wasm-zstd.wasm?url";
 
-  // Compress and save to a file with zstd compression level 3
-  const compressedBytes = zstd.compress(inputData, 3);
-  await fs.writeFile("compressed.zst", compressedBytes);
+await init({ wasmUrl });
 
-  // Currently you need to know the size of the output buffer so the wasm runtime
-  // can allocate enough bytes to decompress into
-  const outputSize = inputData.byteLength;
-
-  // Decompress
-  const decompressedBytes = zstd.decompress(compressedBytes, inputData.byteLength);
-  assert(decompressedBytes.byteLength === inputData.byteLength);
-}
+const compressed = compress(new TextEncoder().encode("hello zstd"), 3);
+const decompressed = decompress(compressed, "hello zstd".length);
 ```
 
-## Using the module in a browser
+This pattern works in browser main-thread code, Web Workers, and Vite production builds because
+Vite owns the `.wasm` asset URL.
 
-Emscripten compiled WebAssembly modules are built in 2 parts: a `.js` side and a `.wasm` side. In the browser the `.js` side needs to download the `.wasm` side from the server so it can compile it. There is [more information available in the emscripten documentation](https://kripken.github.io/emscripten-site/docs/compiling/Deploying-Pages.html).
+## Usage with custom loaders
 
-## Developing locally
+If you already have the wasm bytes, pass them with `wasmBinary`:
 
-1. Run `yarn install` to install dependencies.
-2. Run `yarn build` to invoke emcc inside a Docker container and compile the code in `wasm-zstd.c` as well as the required zstd source files. The output will be in `dist/` on the host machine.
-3. Run `yarn test` to run the tests.
+```ts
+import { init } from "@ioai/wasm-zstd";
 
-## License
+await init({ wasmBinary });
+```
 
-@foxglove/wasm-zstd is licensed under the [MIT License](https://opensource.org/licenses/MIT).
+## Developing locally
 
-## Releasing
+1. Run `npm install`.
+2. Run `npm run build` to invoke emcc inside Docker and compile `src/wasm-zstd.c` plus the vendored zstd sources.
+3. Run `npm test`.
 
-1. Run `yarn version --[major|minor|patch]` to bump version
-2. Run `git push && git push --tags` to push new tag
-3. GitHub Actions will take care of the rest
+The generated package files are written to `dist/`.
+
+## License
 
-## Stay in touch
+`@ioai/wasm-zstd` is licensed under the [MIT License](https://opensource.org/licenses/MIT).
 
-Join our [Slack channel](https://foxglove.dev/slack) to ask questions, share feedback, and stay up to date on what our team is working on.

README.md

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+set -euo pipefail
+
+mkdir -p dist
 
 emcc \
   vendor/zstd/lib/common/debug.c \
@@ -29,8 +32,9 @@ emcc \
   -o dist/wasm-zstd.js src/wasm-zstd.c `# this runs emscripten on the code in wasm-zstd.c` \
   -O3 `# compile with all optimizations enabled` \
   -s WASM=1 `# compile to .wasm instead of asm.js` \
-  --pre-js pre.js `# include pre.js at the top of wasm-zstd.js` \
-  -s MODULARIZE=1 `# include module boilerplate for better node/webpack interop` \
+  -s MODULARIZE=1 `# expose a module factory instead of mutating globals` \
+  -s EXPORT_ES6=1 `# emit an ES module that Vite can bundle` \
+  -s ENVIRONMENT=web,worker `# avoid Node-only fs/path/require branches in browser builds` \
   -s NO_EXIT_RUNTIME=1 `# keep the process around after main exits` \
   -s TOTAL_STACK=1048576 `# use a 1MB stack size instead of the default 5MB` \
   -s INITIAL_MEMORY=2097152 `# start with a 2MB allocation instead of 16MB, we will dynamically grow` \

build.sh

@@ -1,10 +1,11 @@
 #!/usr/bin/env bash
+set -euo pipefail
 
 SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
-cd $SCRIPT_DIR
+cd "$SCRIPT_DIR"
 
-docker build . -t wasm-zstd
+docker build --progress=plain . -t ioai-wasm-zstd
 
 mkdir -p dist
 
-docker run --rm -v "${SCRIPT_DIR}/dist":/src/dist -t wasm-zstd ./build.sh
+docker run --rm -v "${SCRIPT_DIR}/dist":/src/dist ioai-wasm-zstd ./build.sh

docker-build.sh

@@ -1,6 +1,32 @@
-declare module "@foxglove/wasm-zstd" {
-  export const isLoaded: Promise<boolean>;
-  export function compressBound(size: number): number;
-  export function compress(buffer: Uint8Array, compressionLevel?: number): Buffer;
-  export function decompress(buffer: Uint8Array, size: number): Buffer;
+export interface InitOptions {
+  /**
+   * URL for the generated wasm file. In Vite, import it with:
+   * `import wasmUrl from "@ioai/wasm-zstd/wasm-zstd.wasm?url"`.
+   */
+  wasmUrl?: string | URL;
+
+  /**
+   * Raw wasm bytes. Useful for Node tests or custom loaders.
+   */
+  wasmBinary?: ArrayBuffer | ArrayBufferView;
+
+  /**
+   * Advanced Emscripten file resolver. Ignored when wasmUrl is provided.
+   */
+  locateFile?: (path: string, prefix: string) => string;
+
+  /**
+   * Additional Emscripten module options.
+   */
+  module?: Record<string, unknown>;
 }
+
+export function init(options?: InitOptions): Promise<void>;
+export function compressBound(size: number): number;
+export function compress(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, compressionLevel?: number): Uint8Array;
+export function decompress(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, size: number): Uint8Array;
+
+/**
+ * Exposes the raw Emscripten module for tests and diagnostics.
+ */
+export function getModuleForTesting(): unknown;