woff2-encode-wasm 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kyosuke Nakamura
+
+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,201 @@
+# woff2-encode-wasm
+
+Encode TTF/OTF fonts to WOFF2 using the official [google/woff2](https://github.com/google/woff2) C++ library compiled to WebAssembly.
+
+**Primary runtime target: Cloudflare Workers.** Also works in Node.js ≥ 18 and Deno.
+
+## What this package does
+
+- Encodes TTF or OTF font bytes into WOFF2 format.
+- Uses the same encoder as the `woff2_compress` CLI from google/woff2.
+- Runs entirely in-memory — no filesystem, no child processes, no native addons.
+
+## What this package does NOT do
+
+- WOFF2 **decoding** (decompression) is out of scope.
+- This is not a general-purpose font conversion toolkit.
+- It does not parse, subset, or modify font tables.
+- It does not serve or render fonts.
+
+## Install
+
+```bash
+npm install woff2-encode-wasm
+```
+
+> **Note:** This package is ESM-only. It cannot be `require()`'d from CommonJS.
+
+## API
+
+```ts
+import { init, encode } from 'woff2-encode-wasm';
+
+// Initialise the Wasm module (required once before encoding).
+await init(wasmSource);
+
+// Encode a font.
+const woff2Bytes: Uint8Array = await encode(ttfBytes);
+```
+
+### `init(source: WasmSource): Promise<void>`
+
+Initialise the WebAssembly module. Must be called once before `encode()`.
+
+`WasmSource` can be:
+
+| Type | Use case |
+|---|---|
+| `WebAssembly.Module` | Cloudflare Workers (import `.wasm` file) |
+| `ArrayBuffer` / `Uint8Array` | Node.js / Deno (read `.wasm` bytes) |
+| `Response` / `Promise<Response>` | `fetch()` based loading |
+
+Calling `init()` again after successful initialisation is a no-op.
+
+### `encode(input: Uint8Array): Promise<Uint8Array>`
+
+Encode TTF/OTF bytes to WOFF2. Returns a fresh `Uint8Array` that the caller owns.
+
+Throws if:
+- Module is not initialised.
+- Input is empty or not a `Uint8Array`.
+- The font is corrupt or unsupported.
+
+## Usage
+
+### Cloudflare Workers
+
+```js
+import wasmModule from 'woff2-encode-wasm/encoder.wasm';
+import { init, encode } from 'woff2-encode-wasm';
+
+// Initialise once (cached across requests in the same isolate).
+const ready = init(wasmModule);
+
+export default {
+  async fetch(request) {
+    await ready;
+    const input = new Uint8Array(await request.arrayBuffer());
+    const woff2 = await encode(input);
+    return new Response(woff2, {
+      headers: { 'Content-Type': 'font/woff2' },
+    });
+  },
+};
+```
+
+### Node.js
+
+```js
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { init, encode } from 'woff2-encode-wasm';
+
+const require = createRequire(import.meta.url);
+const wasmPath = require.resolve('woff2-encode-wasm/encoder.wasm');
+await init(readFileSync(wasmPath));
+
+const ttf = new Uint8Array(readFileSync('input.ttf'));
+const woff2 = await encode(ttf);
+```
+
+### Deno
+
+```ts
+import { init, encode } from 'npm:woff2-encode-wasm';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const wasmPath = require.resolve('woff2-encode-wasm/encoder.wasm');
+await init(Deno.readFileSync(wasmPath));
+
+const ttf = new Uint8Array(await Deno.readFile('input.ttf'));
+const woff2 = await encode(ttf);
+```
+
+```bash
+deno run --allow-read --allow-env your_script.ts
+```
+
+## Build from source
+
+Prerequisites:
+
+- [Emscripten SDK](https://emscripten.org/docs/getting_started/) (`emcc` on PATH) — for building the `.wasm`
+- [Deno](https://deno.com/) — only needed for `npm test` (runs the Deno smoke test)
+
+```bash
+npm run build          # fetch deps + compile wasm + compile TS
+npm test               # run all tests (Node + Workers + Deno)
+npm run test:node      # Node.js tests only (no Deno required)
+npm run test:workers   # Cloudflare Workers tests only
+```
+
+Individual steps:
+
+```bash
+npm run fetch-deps     # download google/woff2 v1.0.2 + brotli v1.1.0
+npm run build:wasm     # compile to dist/encoder.wasm (~750 KB)
+npm run build:js       # compile TS to dist/index.js + dist/index.d.ts
+```
+
+> **Release note:** `npm pack` / `npm publish` runs `prepack`, which
+> rebuilds JS/types via `tsc` so they are always in sync with source.
+> The `.wasm` binary is **not** rebuilt automatically because `emcc` may
+> not be available on the publishing machine. If you change
+> `src/native/wrapper.cc` or the build script, run `npm run build:wasm`
+> manually before publishing.
+
+## Architecture
+
+```
+src/native/wrapper.cc   Thin C ABI over woff2::ConvertTTFToWOFF2
+src/index.ts            ESM wrapper — init() + encode()
+scripts/fetch-deps.sh   Downloads pinned google/woff2 + brotli releases
+scripts/build-wasm.sh   Emscripten build: .cc/.c → standalone .wasm
+```
+
+The `.wasm` is built with `STANDALONE_WASM=1` and has only two imports:
+
+| Import | Purpose |
+|---|---|
+| `env.emscripten_notify_memory_growth` | No-op callback on memory growth |
+| `wasi_snapshot_preview1.proc_exit` | Abort (should never fire) |
+
+This makes the module trivially instantiable in any environment without Emscripten's JS glue.
+
+### C ABI
+
+| Export | Signature |
+|---|---|
+| `woff2_alloc` | `(size: u32) → ptr` |
+| `woff2_free` | `(ptr) → void` |
+| `woff2_encode` | `(input_ptr, input_len: u32) → i32` (0 = success) |
+| `woff2_result_ptr` | `() → ptr` |
+| `woff2_result_size` | `() → u32` |
+| `woff2_result_free` | `() → void` |
+
+### Memory ownership
+
+1. JS allocates input buffer via `woff2_alloc`, copies font bytes in.
+2. `woff2_encode` allocates the output internally.
+3. JS reads the result via `woff2_result_ptr` / `woff2_result_size`, copies into a fresh `Uint8Array`.
+4. JS frees the result with `woff2_result_free` and the input with `woff2_free`.
+
+## Known limitations
+
+- **Encoding only.** There is no `decode()` function and none is planned.
+- **TTF / OTF only.** TrueType Collections (`.ttc`) are not supported by the upstream encoder.
+- **Synchronous Wasm execution.** Very large fonts may block the event loop. For Workers, this is bounded by the CPU time limit.
+- **~750 KB Wasm binary.** This is after `-O3 -flto`. Most of the size comes from the Brotli encoder tables.
+
+## Versions
+
+| Dependency | Version |
+|---|---|
+| google/woff2 | v1.0.2 |
+| google/brotli | v1.1.0 |
+| Emscripten | CI pinned to 5.0.5 (local builds may vary) |
+
+## License
+
+MIT — same as the upstream google/woff2 and google/brotli.

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * woff2-encode-wasm — Encode TTF/OTF fonts to WOFF2 using the official
+ * google/woff2 library compiled to WebAssembly.
+ *
+ * This module intentionally only encodes. WOFF2 decoding is out of scope.
+ *
+ * ## Instantiation strategy
+ *
+ * The standalone .wasm has two tiny imports that we stub:
+ *   - env.emscripten_notify_memory_growth  (no-op, called when memory grows)
+ *   - wasi_snapshot_preview1.proc_exit     (throws — should never fire)
+ *
+ * For Cloudflare Workers the caller passes a pre-compiled WebAssembly.Module
+ * (imported from the .wasm file by the bundler). For Node.js and Deno the
+ * caller can pass an ArrayBuffer or Uint8Array of the .wasm bytes.
+ */
+/** Source material accepted by {@link init}. */
+export type WasmSource = WebAssembly.Module | BufferSource | Response | Promise<Response>;
+/**
+ * Initialise the WebAssembly module.
+ *
+ * In **Cloudflare Workers**, pass the imported `.wasm` module:
+ * ```ts
+ * import wasmModule from './encoder.wasm';
+ * import { init, encode } from 'woff2-encode-wasm';
+ * await init(wasmModule);
+ * ```
+ *
+ * In **Node.js / Deno**, pass the raw `.wasm` bytes:
+ * ```ts
+ * await init(fs.readFileSync('encoder.wasm'));
+ * ```
+ *
+ * Calling `init()` again after initialisation has started is a no-op —
+ * the first call's source wins.
+ */
+export declare function init(source: WasmSource): Promise<void>;
+/**
+ * Encode a TTF or OTF font to WOFF2.
+ *
+ * @param input - Raw font bytes (TTF or OTF).
+ * @returns WOFF2-encoded bytes.
+ * @throws If the module is not initialised, input is empty, or encoding fails.
+ */
+export declare function encode(input: Uint8Array): Promise<Uint8Array>;

package/dist/index.js

@@ -0,0 +1,164 @@
+/**
+ * woff2-encode-wasm — Encode TTF/OTF fonts to WOFF2 using the official
+ * google/woff2 library compiled to WebAssembly.
+ *
+ * This module intentionally only encodes. WOFF2 decoding is out of scope.
+ *
+ * ## Instantiation strategy
+ *
+ * The standalone .wasm has two tiny imports that we stub:
+ *   - env.emscripten_notify_memory_growth  (no-op, called when memory grows)
+ *   - wasi_snapshot_preview1.proc_exit     (throws — should never fire)
+ *
+ * For Cloudflare Workers the caller passes a pre-compiled WebAssembly.Module
+ * (imported from the .wasm file by the bundler). For Node.js and Deno the
+ * caller can pass an ArrayBuffer or Uint8Array of the .wasm bytes.
+ */
+let exports = null;
+let initPromise = null;
+const importObject = {
+    env: {
+        // Called by Emscripten when ALLOW_MEMORY_GROWTH triggers a resize.
+        emscripten_notify_memory_growth(_memoryIndex) {
+            // No-op — we re-read memory.buffer on every encode() call.
+        },
+    },
+    wasi_snapshot_preview1: {
+        proc_exit(code) {
+            throw new Error(`woff2 wasm called proc_exit(${code})`);
+        },
+    },
+};
+/**
+ * Initialise the WebAssembly module.
+ *
+ * In **Cloudflare Workers**, pass the imported `.wasm` module:
+ * ```ts
+ * import wasmModule from './encoder.wasm';
+ * import { init, encode } from 'woff2-encode-wasm';
+ * await init(wasmModule);
+ * ```
+ *
+ * In **Node.js / Deno**, pass the raw `.wasm` bytes:
+ * ```ts
+ * await init(fs.readFileSync('encoder.wasm'));
+ * ```
+ *
+ * Calling `init()` again after initialisation has started is a no-op —
+ * the first call's source wins.
+ */
+export async function init(source) {
+    if (exports)
+        return;
+    if (initPromise)
+        return initPromise;
+    initPromise = (async () => {
+        let instance;
+        if (source instanceof WebAssembly.Module) {
+            // Cloudflare Workers path: already a compiled Module
+            instance = await WebAssembly.instantiate(source, importObject);
+        }
+        else if (source instanceof Response || source instanceof Promise) {
+            // Streaming compile from fetch Response.
+            // instantiateStreaming requires content-type: application/wasm.
+            // Fall back to arrayBuffer() when the MIME type is wrong or
+            // when instantiateStreaming is not available.
+            const response = source instanceof Promise ? await source : source;
+            if (!response.ok) {
+                throw new Error(`woff2-encode-wasm: fetch failed with HTTP ${response.status}` +
+                    (response.url ? ` (${response.url})` : '') + '.');
+            }
+            if (typeof WebAssembly.instantiateStreaming === 'function' &&
+                (response.headers.get('content-type') || '').trim().toLowerCase().startsWith('application/wasm')) {
+                const result = await WebAssembly.instantiateStreaming(response, importObject);
+                instance = result.instance;
+            }
+            else {
+                const buf = await response.arrayBuffer();
+                const result = await WebAssembly.instantiate(buf, importObject);
+                instance = result.instance;
+            }
+        }
+        else if (source) {
+            // ArrayBuffer / Uint8Array path (Node.js, Deno)
+            const result = await WebAssembly.instantiate(source, importObject);
+            instance = result.instance;
+        }
+        else {
+            throw new Error('woff2-encode-wasm: init() requires a WasmSource argument. ' +
+                'Pass a WebAssembly.Module (Workers) or ArrayBuffer/Uint8Array (Node/Deno).');
+        }
+        const ex = instance.exports;
+        // STANDALONE_WASM reactors must call _initialize() once.
+        ex._initialize();
+        exports = ex;
+    })();
+    try {
+        await initPromise;
+    }
+    catch (err) {
+        // Allow retrying on failure.
+        initPromise = null;
+        throw err;
+    }
+}
+const WOFF2_SIGNATURE = 0x774f4632; // 'wOF2'
+/**
+ * Encode a TTF or OTF font to WOFF2.
+ *
+ * @param input - Raw font bytes (TTF or OTF).
+ * @returns WOFF2-encoded bytes.
+ * @throws If the module is not initialised, input is empty, or encoding fails.
+ */
+export async function encode(input) {
+    if (!exports) {
+        throw new Error('woff2-encode-wasm: module not initialised. Call init() first.');
+    }
+    if (!(input instanceof Uint8Array) || input.length === 0) {
+        throw new Error('woff2-encode-wasm: input must be a non-empty Uint8Array.');
+    }
+    const { memory, woff2_alloc, woff2_free, woff2_encode, woff2_result_ptr, woff2_result_size, woff2_result_free } = exports;
+    // 1. Allocate input buffer in Wasm memory and copy data in.
+    const inputPtr = woff2_alloc(input.length);
+    if (inputPtr === 0) {
+        throw new Error('woff2-encode-wasm: failed to allocate input buffer.');
+    }
+    try {
+        new Uint8Array(memory.buffer, inputPtr, input.length).set(input);
+        // 2. Call the encoder.
+        const rc = woff2_encode(inputPtr, input.length);
+        if (rc !== 0) {
+            const messages = {
+                1: 'MaxWOFF2CompressedSize returned 0 — input is not a valid font.',
+                2: 'Failed to allocate output buffer.',
+                3: 'ConvertTTFToWOFF2 failed — font may be corrupt or unsupported.',
+                4: 'Null input pointer.',
+            };
+            throw new Error(`woff2-encode-wasm: encoding failed (code ${rc}). ${messages[rc] ?? ''}`);
+        }
+        // 3. Copy result out of Wasm memory into a fresh Uint8Array,
+        //    then always free the Wasm-side result buffer.
+        try {
+            const resultPtr = woff2_result_ptr();
+            const resultSize = woff2_result_size();
+            // Re-read memory.buffer — it may have grown during encoding.
+            const result = new Uint8Array(memory.buffer, resultPtr, resultSize).slice();
+            // Sanity check: WOFF2 files start with 'wOF2'.
+            if (result.length >= 4) {
+                const sig = (result[0] << 24) | (result[1] << 16) | (result[2] << 8) | result[3];
+                if (sig !== WOFF2_SIGNATURE) {
+                    throw new Error('woff2-encode-wasm: output does not have wOF2 signature.');
+                }
+            }
+            return result;
+        }
+        finally {
+            // 4. Free the Wasm-side result buffer even if the signature check throws.
+            woff2_result_free();
+        }
+    }
+    finally {
+        // Always free the input buffer.
+        woff2_free(inputPtr);
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "woff2-encode-wasm",
+  "version": "0.1.1",
+  "description": "Encode TTF/OTF fonts to WOFF2 using the official google/woff2 library compiled to WebAssembly",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./encoder.wasm": "./dist/encoder.wasm"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/encoder.wasm"
+  ],
+  "scripts": {
+    "fetch-deps": "bash scripts/fetch-deps.sh",
+    "build:wasm": "bash scripts/build-wasm.sh",
+    "build:js": "tsc",
+    "build": "npm run fetch-deps && npm run build:wasm && npm run build:js",
+    "test": "npm run test:node && npm run test:workers && npm run test:deno",
+    "test:node": "vitest run --config vitest.config.ts",
+    "test:workers": "vitest run --config vitest.workers.config.ts",
+    "test:deno": "deno run --allow-read test/deno-smoke.ts",
+    "prepack": "npm run build:js && test -f dist/encoder.wasm || (echo 'ERROR: dist/encoder.wasm missing. Run npm run build:wasm first.' >&2 && exit 1)",
+    "clean": "rm -rf dist vendor/google-woff2 vendor/brotli"
+  },
+  "keywords": [
+    "woff2",
+    "encode",
+    "wasm",
+    "webassembly",
+    "font",
+    "ttf",
+    "otf",
+    "cloudflare-workers"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kyosuke/woff2-encode-wasm.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.14.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2",
+    "wrangler": "^4.80.0"
+  }
+}