@keeratita/heic-converter 0.3.0 → 0.4.1

package/README.md

@@ -14,6 +14,9 @@ Designed specifically for environments with strict **Content Security Policy (CS
 - 🌐 **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`, `webp`, and `svg` (embedded lossless vector).
+- 📐 **Resize Support**: Downscale with `maxWidth`/`maxHeight` or apply a uniform `scale` factor during conversion.
+- 📚 **Batch Conversion**: Convert many images at once with bounded concurrency via `convertMany`.
+- 🧵 **Web Worker Helper**: Offload conversions to a Web Worker with `convertHeicInWorker` to keep the UI thread responsive.
 
 ---
 
@@ -171,6 +174,89 @@ const jpegBlob = await convertHeic(heicBlob, {
 > [!TIP]
 > Since the WebAssembly module runs on the main browser thread, the UI thread will be occupied during conversion. For maximum responsiveness when converting large images, it is highly recommended to run this library inside a standard JS **Web Worker** and communicate progress back to the main thread.
 
+### 7. Resizing Images
+
+Downscale to fit within maximum dimensions (aspect ratio is preserved, images smaller than the bounds are never upscaled):
+
+```typescript
+import { convertHeic } from '@keeratita/heic-converter';
+
+const thumbnailBlob = await convertHeic(heicBlob, {
+  to: 'jpeg',
+  maxWidth: 800,
+  maxHeight: 600,
+});
+```
+
+Or apply a uniform scale factor (can also upscale):
+
+```typescript
+const halfSizeBlob = await convertHeic(heicBlob, {
+  to: 'webp',
+  scale: 0.5,
+});
+```
+
+### 8. Batch Conversion
+
+Convert many images at once with bounded concurrency (default `4`). Results are returned in input order; if any conversion fails, the promise rejects as soon as the failure is known with an error that identifies the failing item:
+
+```typescript
+import { convertMany } from '@keeratita/heic-converter';
+
+const blobs = await convertMany(heicFiles, {
+  to: 'png',
+  concurrency: 3,
+  onProgress: (index, percent) => {
+    console.log(`Image ${index}: ${Math.round(percent)}%`);
+  },
+});
+```
+
+### 9. Web Worker Conversion
+
+Run the conversion inside a Web Worker so the main thread stays responsive. Create a worker script that uses this library:
+
+```js
+// converter.worker.js
+import { convertHeic } from '@keeratita/heic-converter';
+
+self.onmessage = async (event) => {
+  const { input, options } = event.data;
+  try {
+    const blob = await convertHeic(input, {
+      ...options,
+      onProgress: (percent) => self.postMessage({ type: 'progress', percent }),
+    });
+    self.postMessage({ type: 'result', ok: true, blob });
+  } catch (error) {
+    self.postMessage({ type: 'result', ok: false, error: error?.stack ?? error?.message ?? String(error) });
+  }
+};
+```
+
+Then convert from the main thread:
+
+```typescript
+import { convertHeicInWorker } from '@keeratita/heic-converter';
+
+const jpegBlob = await convertHeicInWorker(heicBlob, {
+  workerUrl: new URL('./converter.worker.js', import.meta.url),
+  workerType: 'module',
+  to: 'jpeg',
+  quality: 0.9,
+  onProgress: (percent) => console.log(`${Math.round(percent)}%`),
+});
+```
+
+> [!NOTE]
+> - Use `workerType: 'module'` when the worker script uses ES module imports (as in the example above). The default is `'classic'`, which requires the script to be pre-bundled (e.g. by Vite or webpack) — static ES imports are not supported in classic workers.
+> - `workerUrl` should be a compile-time constant; the script runs with the page's privileges.
+> - Only `progress` and `result` messages are understood; any other message type is ignored.
+> - `decoder`, `onProgress`, and `workerUrl` are not structured-cloneable, so they are not sent to the worker. Progress is forwarded through `{ type: 'progress', percent }` messages instead.
+> - `timeoutMs` (default `60000`) bounds how long the promise waits for a result; set `0` to disable.
+> - This helper is **browser-only**: it rejects in Node.js, where there is no global `Worker`.
+
 ---
 
 ## 🔒 Content Security Policy (CSP)
@@ -198,6 +284,31 @@ Converts a HEIC image file to a standard web format.
   - `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)
+  - `maxWidth`: `number` (Downscale to fit within this width, preserving aspect ratio. Never upscales)
+  - `maxHeight`: `number` (Downscale to fit within this height, preserving aspect ratio. Never upscales)
+  - `scale`: `number` (Uniform scale factor, e.g. `0.5` halves the image. Takes precedence over `maxWidth`/`maxHeight`)
+- **Returns**: `Promise<Blob>`
+
+### `convertMany(inputs, options?)`
+
+Converts multiple HEIC images with bounded concurrency. Results are returned in input order; rejects as soon as a conversion fails, with an error identifying the failing item index.
+
+- **`inputs`**: `Array<Blob | File | ArrayBuffer | Uint8Array>`
+- **`options`**: (optional) `ConvertManyOptions` — same as `ConvertOptions`, except `onProgress` uses the batch signature below; plus:
+  - `concurrency`: `number` (Maximum concurrent conversions. Default: `4`)
+  - `onProgress`: `(index: number, percent: number) => void` (Per-item progress callback)
+  - `decoder`: `IHeicDecoder` (Optional. When provided, the same instance is shared by all concurrent conversions and must be safe for concurrent `decode()` calls)
+- **Returns**: `Promise<Blob[]>`
+
+### `convertHeicInWorker(input, options)`
+
+Converts a HEIC image inside a Web Worker. The worker script must implement the message protocol shown in [Usage section 9](#9-web-worker-conversion). Browser-only; rejects in Node.js.
+
+- **`input`**: `Blob | File | ArrayBuffer | Uint8Array`
+- **`options`**: `WorkerConvertOptions` — same as `ConvertOptions`, plus:
+  - `workerUrl`: `string | URL` (URL of the worker script; should be a compile-time constant)
+  - `workerType`: `'classic' | 'module'` (Worker script type. Default: `'classic'`; use `'module'` for scripts with ES imports)
+  - `timeoutMs`: `number` (Maximum wait for the result in milliseconds. Default: `60000`; `0` disables)
 - **Returns**: `Promise<Blob>`
 
 ### `LibheifDecoder(options?)`
@@ -231,12 +342,14 @@ If you want to build or modify the WASM wrapper, you will need **Docker** instal
 
 ### Build WebAssembly
 
-To compile the underlying `libheif` and `libde265` libraries from source using Emscripten:
+To compile the underlying [`libheif`](https://github.com/strukturag/libheif) and [`libde265`](https://github.com/strukturag/libde265) libraries from source using Emscripten:
 
 ```bash
 npm run build:wasm
 ```
 
+See [WASM_DEPENDENCIES.md](WASM_DEPENDENCIES.md) for the pinned upstream library versions.
+
 ### Build JS & TS Typings
 
 To compile the TypeScript library code to ESM/CJS bundles under the `dist/` directory:

package/dist/index.d.mts

@@ -20,7 +20,27 @@ interface IHeicDecoder {
     free(): void;
 }
 type ImageFormat = 'jpeg' | 'jpg' | 'png' | 'svg' | 'webp';
-interface ConvertOptions {
+type HeicInput = Blob | File | ArrayBuffer | Uint8Array;
+interface ResizeOptions {
+    /**
+     * Maximum width in pixels. The image is downscaled to fit within this
+     * bound while preserving the aspect ratio. Images smaller than the bound
+     * are never upscaled.
+     */
+    maxWidth?: number;
+    /**
+     * Maximum height in pixels. The image is downscaled to fit within this
+     * bound while preserving the aspect ratio. Images smaller than the bound
+     * are never upscaled.
+     */
+    maxHeight?: number;
+    /**
+     * Uniform scale factor applied to both dimensions (e.g. 0.5 halves the
+     * image). Takes precedence over `maxWidth` and `maxHeight` when set.
+     */
+    scale?: number;
+}
+interface ConvertOptions extends ResizeOptions {
     /**
      * Target format for the conversion.
      * @default 'jpeg'
@@ -42,6 +62,25 @@ interface ConvertOptions {
      */
     onProgress?: (percent: number) => void;
 }
+interface ConvertManyOptions extends Omit<ConvertOptions, 'onProgress'> {
+    /**
+     * Maximum number of conversions running concurrently.
+     * @default 4
+     */
+    concurrency?: number;
+    /**
+     * Optional progress callback that receives the item index and its
+     * progress percentage (0 to 100) during decoding.
+     */
+    onProgress?: (index: number, percent: number) => void;
+    /**
+     * Optional custom decoder implementation to inject. When provided, the
+     * same instance is shared by all concurrent conversions, so it must be
+     * safe for concurrent `decode()` calls. If not provided, a fresh
+     * default LibheifDecoder is created per item.
+     */
+    decoder?: IHeicDecoder;
+}
 
 interface LibheifDecoderOptions {
     /**
@@ -84,6 +123,71 @@ declare class LibheifDecoder implements IHeicDecoder {
     free(): void;
 }
 
+interface WorkerConvertOptions extends ConvertOptions {
+    /**
+     * URL of the worker script that performs the conversion. Should be a
+     * compile-time constant (e.g. `new URL('./worker.js', import.meta.url)`
+     * under a bundler); the script runs with the page's privileges.
+     */
+    workerUrl: string | URL;
+    /**
+     * Maximum time in milliseconds to wait for the worker result before
+     * rejecting with a timeout. Defaults to 60000 (60s). Set to 0 to
+     * disable the timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * Worker script type. Use `'module'` when the script uses ES module
+     * imports (e.g. `import { convertHeic } from ...`); `'classic'`
+     * scripts must be pre-bundled.
+     * @default 'classic'
+     */
+    workerType?: 'classic' | 'module';
+}
+/**
+ * Converts a HEIC image inside a Web Worker so the main thread stays
+ * responsive during the (potentially slow) WASM decode.
+ *
+ * The worker script is user-provided and must handle the following message
+ * protocol:
+ *
+ * ```js
+ * // converter.worker.js
+ * import { convertHeic } from '@keeratita/heic-converter';
+ *
+ * self.onmessage = async (event) => {
+ *   const { input, options } = event.data;
+ *   try {
+ *     const blob = await convertHeic(input, {
+ *       ...options,
+ *       onProgress: (percent) => self.postMessage({ type: 'progress', percent }),
+ *     });
+ *     self.postMessage({ type: 'result', ok: true, blob });
+ *   } catch (error) {
+ *     self.postMessage({ type: 'result', ok: false, error: error?.stack ?? error?.message ?? String(error) });
+ *   }
+ * };
+ * ```
+ *
+ * ```ts
+ * const jpegBlob = await convertHeicInWorker(heicBlob, {
+ *   workerUrl: new URL('./converter.worker.js', import.meta.url),
+ *   workerType: 'module',
+ *   to: 'jpeg',
+ * });
+ * ```
+ *
+ * Only `progress` and `result` messages are understood; any other message
+ * type is ignored. Use `workerType: 'module'` when the script uses ES
+ * module imports (as in the example above); `'classic'` scripts must be
+ * pre-bundled, since static ES imports are not supported there.
+ *
+ * @param input HEIC image as a Blob, File, ArrayBuffer, or Uint8Array.
+ * @param options Conversion options plus the worker script URL.
+ * @returns A Promise resolving to the converted image as a Blob.
+ */
+declare function convertHeicInWorker(input: HeicInput, options: WorkerConvertOptions): Promise<Blob>;
+
 /**
  * Releases any cached decoder resources.
  *
@@ -98,6 +202,20 @@ declare function freeSharedDecoder(): void;
  * @param options Conversion configuration options.
  * @returns A Promise resolving to the converted image as a Blob.
  */
-declare function convertHeic(input: Blob | File | ArrayBuffer | Uint8Array, options?: ConvertOptions): Promise<Blob>;
+declare function convertHeic(input: HeicInput, options?: ConvertOptions): Promise<Blob>;
+/**
+ * Converts multiple HEIC images to a standard web format.
+ *
+ * Conversions run with a bounded concurrency (default 4) and results are
+ * returned in the same order as the inputs. If any conversion fails, the
+ * returned promise rejects as soon as the failure is known (in-flight
+ * conversions are allowed to finish in the background) with an error that
+ * identifies the failing item index.
+ *
+ * @param inputs HEIC images as Blobs, Files, ArrayBuffers, or Uint8Arrays.
+ * @param options Batch conversion options.
+ * @returns A Promise resolving to the converted images as Blobs, in input order.
+ */
+declare function convertMany(inputs: HeicInput[], options?: ConvertManyOptions): Promise<Blob[]>;
 
-export { type ConvertOptions, type DecodedImage, type IHeicDecoder, type ImageFormat, LibheifDecoder, type LibheifDecoderOptions, convertHeic, freeSharedDecoder };
+export { type ConvertManyOptions, type ConvertOptions, type DecodedImage, type HeicInput, type IHeicDecoder, type ImageFormat, LibheifDecoder, type LibheifDecoderOptions, type ResizeOptions, type WorkerConvertOptions, convertHeic, convertHeicInWorker, convertMany, freeSharedDecoder };

package/dist/index.d.ts

@@ -20,7 +20,27 @@ interface IHeicDecoder {
     free(): void;
 }
 type ImageFormat = 'jpeg' | 'jpg' | 'png' | 'svg' | 'webp';
-interface ConvertOptions {
+type HeicInput = Blob | File | ArrayBuffer | Uint8Array;
+interface ResizeOptions {
+    /**
+     * Maximum width in pixels. The image is downscaled to fit within this
+     * bound while preserving the aspect ratio. Images smaller than the bound
+     * are never upscaled.
+     */
+    maxWidth?: number;
+    /**
+     * Maximum height in pixels. The image is downscaled to fit within this
+     * bound while preserving the aspect ratio. Images smaller than the bound
+     * are never upscaled.
+     */
+    maxHeight?: number;
+    /**
+     * Uniform scale factor applied to both dimensions (e.g. 0.5 halves the
+     * image). Takes precedence over `maxWidth` and `maxHeight` when set.
+     */
+    scale?: number;
+}
+interface ConvertOptions extends ResizeOptions {
     /**
      * Target format for the conversion.
      * @default 'jpeg'
@@ -42,6 +62,25 @@ interface ConvertOptions {
      */
     onProgress?: (percent: number) => void;
 }
+interface ConvertManyOptions extends Omit<ConvertOptions, 'onProgress'> {
+    /**
+     * Maximum number of conversions running concurrently.
+     * @default 4
+     */
+    concurrency?: number;
+    /**
+     * Optional progress callback that receives the item index and its
+     * progress percentage (0 to 100) during decoding.
+     */
+    onProgress?: (index: number, percent: number) => void;
+    /**
+     * Optional custom decoder implementation to inject. When provided, the
+     * same instance is shared by all concurrent conversions, so it must be
+     * safe for concurrent `decode()` calls. If not provided, a fresh
+     * default LibheifDecoder is created per item.
+     */
+    decoder?: IHeicDecoder;
+}
 
 interface LibheifDecoderOptions {
     /**
@@ -84,6 +123,71 @@ declare class LibheifDecoder implements IHeicDecoder {
     free(): void;
 }
 
+interface WorkerConvertOptions extends ConvertOptions {
+    /**
+     * URL of the worker script that performs the conversion. Should be a
+     * compile-time constant (e.g. `new URL('./worker.js', import.meta.url)`
+     * under a bundler); the script runs with the page's privileges.
+     */
+    workerUrl: string | URL;
+    /**
+     * Maximum time in milliseconds to wait for the worker result before
+     * rejecting with a timeout. Defaults to 60000 (60s). Set to 0 to
+     * disable the timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * Worker script type. Use `'module'` when the script uses ES module
+     * imports (e.g. `import { convertHeic } from ...`); `'classic'`
+     * scripts must be pre-bundled.
+     * @default 'classic'
+     */
+    workerType?: 'classic' | 'module';
+}
+/**
+ * Converts a HEIC image inside a Web Worker so the main thread stays
+ * responsive during the (potentially slow) WASM decode.
+ *
+ * The worker script is user-provided and must handle the following message
+ * protocol:
+ *
+ * ```js
+ * // converter.worker.js
+ * import { convertHeic } from '@keeratita/heic-converter';
+ *
+ * self.onmessage = async (event) => {
+ *   const { input, options } = event.data;
+ *   try {
+ *     const blob = await convertHeic(input, {
+ *       ...options,
+ *       onProgress: (percent) => self.postMessage({ type: 'progress', percent }),
+ *     });
+ *     self.postMessage({ type: 'result', ok: true, blob });
+ *   } catch (error) {
+ *     self.postMessage({ type: 'result', ok: false, error: error?.stack ?? error?.message ?? String(error) });
+ *   }
+ * };
+ * ```
+ *
+ * ```ts
+ * const jpegBlob = await convertHeicInWorker(heicBlob, {
+ *   workerUrl: new URL('./converter.worker.js', import.meta.url),
+ *   workerType: 'module',
+ *   to: 'jpeg',
+ * });
+ * ```
+ *
+ * Only `progress` and `result` messages are understood; any other message
+ * type is ignored. Use `workerType: 'module'` when the script uses ES
+ * module imports (as in the example above); `'classic'` scripts must be
+ * pre-bundled, since static ES imports are not supported there.
+ *
+ * @param input HEIC image as a Blob, File, ArrayBuffer, or Uint8Array.
+ * @param options Conversion options plus the worker script URL.
+ * @returns A Promise resolving to the converted image as a Blob.
+ */
+declare function convertHeicInWorker(input: HeicInput, options: WorkerConvertOptions): Promise<Blob>;
+
 /**
  * Releases any cached decoder resources.
  *
@@ -98,6 +202,20 @@ declare function freeSharedDecoder(): void;
  * @param options Conversion configuration options.
  * @returns A Promise resolving to the converted image as a Blob.
  */
-declare function convertHeic(input: Blob | File | ArrayBuffer | Uint8Array, options?: ConvertOptions): Promise<Blob>;
+declare function convertHeic(input: HeicInput, options?: ConvertOptions): Promise<Blob>;
+/**
+ * Converts multiple HEIC images to a standard web format.
+ *
+ * Conversions run with a bounded concurrency (default 4) and results are
+ * returned in the same order as the inputs. If any conversion fails, the
+ * returned promise rejects as soon as the failure is known (in-flight
+ * conversions are allowed to finish in the background) with an error that
+ * identifies the failing item index.
+ *
+ * @param inputs HEIC images as Blobs, Files, ArrayBuffers, or Uint8Arrays.
+ * @param options Batch conversion options.
+ * @returns A Promise resolving to the converted images as Blobs, in input order.
+ */
+declare function convertMany(inputs: HeicInput[], options?: ConvertManyOptions): Promise<Blob[]>;
 
-export { type ConvertOptions, type DecodedImage, type IHeicDecoder, type ImageFormat, LibheifDecoder, type LibheifDecoderOptions, convertHeic, freeSharedDecoder };
+export { type ConvertManyOptions, type ConvertOptions, type DecodedImage, type HeicInput, type IHeicDecoder, type ImageFormat, LibheifDecoder, type LibheifDecoderOptions, type ResizeOptions, type WorkerConvertOptions, convertHeic, convertHeicInWorker, convertMany, freeSharedDecoder };