@keeratita/heic-converter 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @keeratita/heic-converter
 
-A modern, lightweight TypeScript library to convert `.heic` and `.heif` images to standard web formats (JPEG, PNG, SVG) client-side in the browser or on the backend in Node.js.
+A modern, lightweight TypeScript library to convert `.heic` and `.heif` images to standard web formats (JPEG, PNG, WebP, SVG) client-side in the browser or on the backend in Node.js.
 
 Designed specifically for environments with strict **Content Security Policy (CSP)** rules, it is built with WebAssembly compiled **without** dynamic code execution (`eval()` or `new Function()`).
 
@@ -10,10 +10,10 @@ Designed specifically for environments with strict **Content Security Policy (CS
 
 - 🔒 **CSP Compliant**: Emscripten glue code is compiled with `-s DYNAMIC_EXECUTION=0`. Safe to run without `'unsafe-eval'`.
 - 🧩 **Dependency Injection Architecture**: Swap the decoder module easily by implementing a simple `IHeicDecoder` interface.
-- ⚡ **Optimized Performance**: Reuses a single shared WASM instance across calls by default. Decodes an image in milliseconds.
+- ⚡ **Optimized Performance**: A fresh decoder instance is created and released per conversion — memory is reclaimed promptly and concurrent conversions never share mutable WASM state.
 - 🌐 **Isomorphic / Universal**: Runs in Node.js (decoding) and browser (decoding & canvas-based encoding).
 - 📦 **No Bloat**: Zero external production dependencies. Small footprint.
-- 🎨 **Format Support**: Convert to `jpeg` (with quality configuration), `png`, and `svg` (embedded lossless vector).
+- 🎨 **Format Support**: Convert to `jpeg` (with quality configuration), `png`, `webp`, and `svg` (embedded lossless vector).
 
 ---
 
@@ -25,6 +25,16 @@ npm install @keeratita/heic-converter
 
 ---
 
+## 🌍 Live Demo (GitHub Pages)
+
+Try the browser demo here:
+
+https://keeratita.github.io/heic-converter/
+
+The demo is auto-deployed from the `main` branch by the GitHub Actions workflow in `.github/workflows/demo-pages.yml`.
+
+---
+
 ## 🚀 Usage
 
 ### 1. Browser: Simple Conversion
@@ -46,9 +56,34 @@ const imageUrl = URL.createObjectURL(jpegBlob);
 document.querySelector('img').src = imageUrl;
 ```
 
-### 2. Browser: Serving and Locating WASM (Custom Assets Path)
+### 2. Browser: WebP Output
 
-By default, the library tries to fetch `heic-decoder.wasm` relative to the current module script path (`import.meta.url`). 
+WebP offers excellent compression with quality configuration:
+
+```typescript
+import { convertHeic } from '@keeratita/heic-converter';
+
+const webpBlob = await convertHeic(heicBlob, {
+  to: 'webp',
+  quality: 0.8,
+});
+```
+
+### 3. Browser: SVG Output
+
+SVG wraps the raster image as an embedded lossless PNG inside an SVG container:
+
+```typescript
+import { convertHeic } from '@keeratita/heic-converter';
+
+const svgBlob = await convertHeic(heicBlob, {
+  to: 'svg',
+});
+```
+
+### 4. Browser: Serving and Locating WASM (Custom Assets Path)
+
+By default, the library tries to fetch `heic-decoder.wasm` relative to the current module script path (`import.meta.url`).
 
 If your bundler places files in a custom assets folder or CDN, you can configure the default decoder or inject a custom one:
 
@@ -57,13 +92,13 @@ import { convertHeic, LibheifDecoder } from '@keeratita/heic-converter';
 
 // Create decoder with custom asset paths
 const decoder = new LibheifDecoder({
-  locateFile: (path, prefix) => `https://cdn.example.com/assets/${path}`
+  locateFile: (path, prefix) => `https://cdn.example.com/assets/${path}`,
 });
 
 // Pass the custom decoder in options
 const pngBlob = await convertHeic(heicBlob, {
   to: 'png',
-  decoder: decoder
+  decoder: decoder,
 });
 ```
 
@@ -79,13 +114,13 @@ const decoder = new LibheifDecoder({ wasmBinary });
 
 const jpegBlob = await convertHeic(heicBlob, {
   to: 'jpeg',
-  decoder: decoder
+  decoder: decoder,
 });
 ```
 
-### 3. Node.js: Decoding Raw Pixel Data
+### 5. Node.js: Decoding Raw Pixel Data
 
-Since Node.js lacks the native browser Canvas API, `convertHeic` (which relies on Canvas to encode raster formats) will throw an error on the backend. 
+Since Node.js lacks the native browser Canvas API, `convertHeic` (which relies on Canvas to encode raster formats) will throw an error on the backend.
 
 However, you can use the `LibheifDecoder` in Node.js to retrieve the raw RGBA pixels and then encode them using libraries like `sharp` or `pngjs`:
 
@@ -96,26 +131,27 @@ import sharp from 'sharp'; // external node image library
 
 async function convertNode() {
   const heicData = new Uint8Array(fs.readFileSync('input.heic'));
-  
+
   const decoder = new LibheifDecoder();
   await decoder.initialize();
-  
-  // Decodes to { width, height, data: Uint8ClampedArray (RGBA) }
+
+  // Decodes to { width, height, data: Uint8ClampedArray (RGBA) }.
+  // data is an independent copy — safe to use after decoder.free().
   const { width, height, data } = await decoder.decode(heicData);
-  
+
   // Process raw pixels using sharp
-  await sharp(Buffer.from(data.buffer), {
-    raw: { width, height, channels: 4 }
+  await sharp(Buffer.from(data), {
+    raw: { width, height, channels: 4 },
   })
-  .toFormat('jpeg')
-  .toFile('output.jpg');
-  
+    .toFormat('jpeg')
+    .toFile('output.jpg');
+
   // Clean up WASM memory
   decoder.free();
 }
 ```
 
-### 4. Progress Tracking (e.g. for Large Images)
+### 6. Progress Tracking (e.g. for Large Images)
 
 For large images, you can pass an `onProgress` callback to track the conversion progress (0% to 100%):
 
@@ -158,8 +194,8 @@ Converts a HEIC image file to a standard web format.
 
 - **`input`**: `Blob | File | ArrayBuffer | Uint8Array`
 - **`options`**: (optional) `ConvertOptions`
-  - `to`: `'jpeg' | 'jpg' | 'png' | 'svg'` (Default: `'jpeg'`)
-  - `quality`: `number` (0.0 to 1.0, only applicable to JPEG. Default: `0.92`)
+  - `to`: `'jpeg' | 'jpg' | 'png' | 'webp' | 'svg'` (Default: `'jpeg'`)
+  - `quality`: `number` (0.0 to 1.0, applicable to JPEG and WebP. Default: `0.92`)
   - `decoder`: `IHeicDecoder` (Inject custom decoder instance)
   - `onProgress`: `(percent: number) => void` (Optional callback, receives progress percentage from `0` to `100` during decoding)
 - **Returns**: `Promise<Blob>`
@@ -172,13 +208,13 @@ The default WASM-based implementation of `IHeicDecoder`.
   - `locateFile`: `(path: string, prefix: string) => string`
   - `wasmBinary`: `ArrayBuffer`
 - **Methods**:
-  - `initialize(): Promise<void>`: Loads and initializes the WASM wrapper.
-  - `decode(data: Uint8Array, onProgress?: (percent: number) => void): Promise<DecodedImage>`: Decodes the HEIC bytes to raw RGBA, with optional progress callback.
-  - `free(): void`: Releases allocated WebAssembly heap memory.
+  - `initialize(): Promise<void>`: Loads and initializes the WASM wrapper. Safe to call concurrently; the module loads at most once per instance.
+  - `decode(data: Uint8Array, onProgress?: (percent: number) => void): Promise<DecodedImage>`: Decodes the HEIC bytes to raw RGBA, with optional progress callback. Returns an independent copy of the pixel data — safe to use after `free()`.
+  - `free(): void`: Releases allocated WebAssembly heap memory. Idempotent.
 
 ### `freeSharedDecoder()`
 
-The library keeps a shared instance of `LibheifDecoder` to speed up subsequent calls. Call `freeSharedDecoder()` when your application is done converting images to release memory.
+Kept for **API compatibility**. Decoders are now created and released per conversion, so there is no shared instance to release — calling this function is a no-op.
 
 ```typescript
 import { freeSharedDecoder } from '@keeratita/heic-converter';
@@ -194,47 +230,67 @@ freeSharedDecoder();
 If you want to build or modify the WASM wrapper, you will need **Docker** installed.
 
 ### Build WebAssembly
+
 To compile the underlying `libheif` and `libde265` libraries from source using Emscripten:
+
 ```bash
 npm run build:wasm
 ```
 
 ### Build JS & TS Typings
+
 To compile the TypeScript library code to ESM/CJS bundles under the `dist/` directory:
+
 ```bash
 npm run build
 ```
 
 ### Run Unit Tests
+
 ```bash
 npm run test
 ```
 
+### Run Browser E2E Tests
+
+Real browser conversions against the CSP sandbox and the GitHub Pages demo (`docs/`):
+
+```bash
+npx playwright install chromium   # one-time
+npm run test:e2e
+```
+
 ### Run Interactive CSP Sandbox
+
 To test the converter in a local browser running under a strict Content Security Policy, start the sandbox server:
+
 ```bash
 npm run sandbox
 ```
+
 Then navigate to: `http://localhost:3000`
 
 ### Release / Versioning
+
 To bump the package version (following SemVer) and push the release commits/tags to the git remote:
+
 ```bash
 npm run release
 ```
+
 Alternatively, you can pass the release type as an argument:
+
 ```bash
 npm run release patch
 npm run release minor
 npm run release major
 npm run release current
 ```
-This script will automatically run the linter, build the TS library, run the unit tests. For `patch`, `minor`, and `major`, it bumps the version (updating `package.json`/`package-lock.json`), commits the changes with a Conventional Commit message (`chore(release): X.Y.Z`), tags the commit, and pushes both the commit and tag to the remote. For `current`, it simply tags the current commit with the existing version in `package.json` (e.g. `vX.Y.Z`) and pushes that tag to the remote without committing or altering files.
 
+This script will automatically run the linter, build the TS library, run the unit tests. For `patch`, `minor`, and `major`, it bumps the version (updating `package.json`/`package-lock.json`), commits the changes with a Conventional Commit message (`chore(release): X.Y.Z`), tags the commit, and pushes both the commit and tag to the remote. For `current`, it simply tags the current commit with the existing version in `package.json` (e.g. `vX.Y.Z`) and pushes that tag to the remote without committing or altering files.
 
 ---
 
 ## 📄 License
 
 MIT © Keerati Tansawatcharoen
-

package/dist/index.d.mts

@@ -19,7 +19,7 @@ interface IHeicDecoder {
      */
     free(): void;
 }
-type ImageFormat = 'jpeg' | 'jpg' | 'png' | 'svg';
+type ImageFormat = 'jpeg' | 'jpg' | 'png' | 'svg' | 'webp';
 interface ConvertOptions {
     /**
      * Target format for the conversion.
@@ -28,7 +28,7 @@ interface ConvertOptions {
     to?: ImageFormat;
     /**
      * Quality of the converted image (between 0.0 and 1.0).
-     * Only applicable for 'jpeg' (and 'jpg') format.
+     * Applicable for 'jpeg', 'jpg', and 'webp' formats.
      * @default 0.92
      */
     quality?: number;
@@ -59,9 +59,15 @@ declare class LibheifDecoder implements IHeicDecoder {
     private options?;
     private module;
     private decoderInstance;
+    /**
+     * Memoized module-loading promise so concurrent initialize()/decode() calls
+     * on the same instance never instantiate (or mutate) the module twice.
+     */
+    private initPromise;
     constructor(options?: LibheifDecoderOptions);
     /**
      * Initializes the WebAssembly module and instantiates the HEIC decoder.
+     * Safe to call concurrently: the module is loaded at most once per instance.
      */
     initialize(): Promise<void>;
     /**
@@ -72,17 +78,21 @@ declare class LibheifDecoder implements IHeicDecoder {
     decode(data: Uint8Array, onProgress?: (percent: number) => void): Promise<DecodedImage>;
     /**
      * Cleans up the WebAssembly decoder instance and resources.
+     * Idempotent: safe to call multiple times. After free(), the instance must
+     * be re-initialized (createHeicDecoderModule runs again on the next call).
      */
     free(): void;
 }
 
 /**
- * Releases the resources allocated for the shared default decoder instance.
- * Call this when no further HEIC conversions are needed to free memory.
+ * Releases any cached decoder resources.
+ *
+ * Decoders are now created and released per conversion, so there is no shared
+ * instance to free. This function is kept for API compatibility.
  */
 declare function freeSharedDecoder(): void;
 /**
- * Converts HEIC image data to a standard web format (JPEG, PNG, or SVG).
+ * Converts HEIC image data to a standard web format (JPEG, PNG, WebP, or SVG).
  *
  * @param input HEIC image as a Blob, File, ArrayBuffer, or Uint8Array.
  * @param options Conversion configuration options.

package/dist/index.d.ts

@@ -19,7 +19,7 @@ interface IHeicDecoder {
      */
     free(): void;
 }
-type ImageFormat = 'jpeg' | 'jpg' | 'png' | 'svg';
+type ImageFormat = 'jpeg' | 'jpg' | 'png' | 'svg' | 'webp';
 interface ConvertOptions {
     /**
      * Target format for the conversion.
@@ -28,7 +28,7 @@ interface ConvertOptions {
     to?: ImageFormat;
     /**
      * Quality of the converted image (between 0.0 and 1.0).
-     * Only applicable for 'jpeg' (and 'jpg') format.
+     * Applicable for 'jpeg', 'jpg', and 'webp' formats.
      * @default 0.92
      */
     quality?: number;
@@ -59,9 +59,15 @@ declare class LibheifDecoder implements IHeicDecoder {
     private options?;
     private module;
     private decoderInstance;
+    /**
+     * Memoized module-loading promise so concurrent initialize()/decode() calls
+     * on the same instance never instantiate (or mutate) the module twice.
+     */
+    private initPromise;
     constructor(options?: LibheifDecoderOptions);
     /**
      * Initializes the WebAssembly module and instantiates the HEIC decoder.
+     * Safe to call concurrently: the module is loaded at most once per instance.
      */
     initialize(): Promise<void>;
     /**
@@ -72,17 +78,21 @@ declare class LibheifDecoder implements IHeicDecoder {
     decode(data: Uint8Array, onProgress?: (percent: number) => void): Promise<DecodedImage>;
     /**
      * Cleans up the WebAssembly decoder instance and resources.
+     * Idempotent: safe to call multiple times. After free(), the instance must
+     * be re-initialized (createHeicDecoderModule runs again on the next call).
      */
     free(): void;
 }
 
 /**
- * Releases the resources allocated for the shared default decoder instance.
- * Call this when no further HEIC conversions are needed to free memory.
+ * Releases any cached decoder resources.
+ *
+ * Decoders are now created and released per conversion, so there is no shared
+ * instance to free. This function is kept for API compatibility.
  */
 declare function freeSharedDecoder(): void;
 /**
- * Converts HEIC image data to a standard web format (JPEG, PNG, or SVG).
+ * Converts HEIC image data to a standard web format (JPEG, PNG, WebP, or SVG).
  *
  * @param input HEIC image as a Blob, File, ArrayBuffer, or Uint8Array.
  * @param options Conversion configuration options.