@napi-rs/canvas 0.1.83 → 0.1.84

package/index.d.ts

@@ -619,6 +619,121 @@ export interface AvifConfig {
   /** set to '4:2:0' to use chroma subsampling, default '4:4:4' */
   chromaSubsampling?: ChromaSubsampling
 }
+
+/** GIF encoding configuration for single-frame encoding */
+export interface GifConfig {
+  /**
+   * Quality for NeuQuant color quantization (1-30, lower = slower but better quality)
+   * @default 10
+   */
+  quality?: number
+}
+
+/** Configuration for the GIF encoder (animated GIFs) */
+export interface GifEncoderConfig {
+  /**
+   * Loop count: 0 = infinite loop, positive number = finite loops
+   * @default 0 (infinite)
+   */
+  repeat?: number
+  /**
+   * Quality for NeuQuant color quantization (1-30, lower = slower but better quality)
+   * @default 10
+   */
+  quality?: number
+}
+
+/** Configuration for individual GIF frames */
+export interface GifFrameConfig {
+  /**
+   * Frame delay in milliseconds
+   * @default 100
+   */
+  delay?: number
+  /** Disposal method for this frame */
+  disposal?: GifDisposal
+  /** Transparent color index (0-255), if the frame has transparency */
+  transparent?: number
+  /** X offset of this frame within the canvas */
+  left?: number
+  /** Y offset of this frame within the canvas */
+  top?: number
+}
+
+/** GIF frame disposal method */
+export enum GifDisposal {
+  /** Keep the frame visible (default) */
+  Keep = 0,
+  /** Clear the frame area to the background color */
+  Background = 1,
+  /** Restore to the previous frame */
+  Previous = 2,
+}
+
+/**
+ * GIF Encoder for creating animated GIFs.
+ * Implements `Disposable` interface for use with the `using` keyword (ES2024).
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const encoder = new GifEncoder(100, 100, { repeat: 0, quality: 10 });
+ * encoder.addFrame(rgbaData, 100, 100, { delay: 100 });
+ * encoder.addFrame(rgbaData2, 100, 100, { delay: 100 });
+ * const buffer = encoder.finish();
+ *
+ * // With `using` keyword (automatic cleanup)
+ * {
+ *   using encoder = new GifEncoder(100, 100);
+ *   encoder.addFrame(frame1, 100, 100, { delay: 100 });
+ *   const buffer = encoder.finish();
+ * } // encoder automatically disposed
+ * ```
+ */
+export class GifEncoder implements Disposable {
+  /**
+   * Create a new GIF encoder with the specified dimensions
+   * @param width - Width of the GIF canvas in pixels
+   * @param height - Height of the GIF canvas in pixels
+   * @param config - Optional encoder configuration
+   */
+  constructor(width: number, height: number, config?: GifEncoderConfig)
+
+  /** Width of the GIF canvas */
+  readonly width: number
+  /** Height of the GIF canvas */
+  readonly height: number
+  /** Number of frames added so far */
+  readonly frameCount: number
+
+  /**
+   * Add a frame from RGBA pixel data
+   * @param data - RGBA pixel data (must be width * height * 4 bytes)
+   * @param width - Width of the frame in pixels
+   * @param height - Height of the frame in pixels
+   * @param config - Optional frame configuration
+   */
+  addFrame(data: Uint8Array, width: number, height: number, config?: GifFrameConfig): void
+
+  /**
+   * Finish encoding and return the GIF data.
+   * Clears all accumulated frames after encoding.
+   * @throws Error if no frames have been added
+   */
+  finish(): Buffer
+
+  /**
+   * Dispose of the encoder, clearing all accumulated frames without encoding.
+   * Called automatically when using the `using` keyword.
+   */
+  dispose(): void
+
+  /**
+   * Symbol.dispose implementation for ES2024 Explicit Resource Management.
+   * Allows using `using encoder = new GifEncoder(...)` syntax.
+   */
+  [Symbol.dispose](): void
+}
 /**
  * https://en.wikipedia.org/wiki/Chroma_subsampling#Types_of_sampling_and_subsampling
  * https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Video_concepts
@@ -676,24 +791,29 @@ export class Canvas {
   encodeSync(format: 'webp' | 'jpeg', quality?: number): Buffer
   encodeSync(format: 'png'): Buffer
   encodeSync(format: 'avif', cfg?: AvifConfig): Buffer
+  encodeSync(format: 'gif', quality?: number): Buffer
   encode(format: 'webp' | 'jpeg', quality?: number): Promise<Buffer>
   encode(format: 'png'): Promise<Buffer>
   encode(format: 'avif', cfg?: AvifConfig): Promise<Buffer>
+  encode(format: 'gif', quality?: number): Promise<Buffer>
   encodeStream(format: 'webp' | 'jpeg', quality?: number): ReadableStream<Buffer>
   encodeStream(format: 'png'): ReadableStream<Buffer>
   toBuffer(mime: 'image/png'): Buffer
   toBuffer(mime: 'image/jpeg' | 'image/webp', quality?: number): Buffer
   toBuffer(mime: 'image/avif', cfg?: AvifConfig): Buffer
+  toBuffer(mime: 'image/gif', quality?: number): Buffer
   // raw pixels
   data(): Buffer
   toDataURL(mime?: 'image/png'): string
   toDataURL(mime: 'image/jpeg' | 'image/webp', quality?: number): string
-  toDataURL(mime?: 'image/jpeg' | 'image/webp' | 'image/png', quality?: number): string
+  toDataURL(mime: 'image/gif', quality?: number): string
+  toDataURL(mime?: 'image/jpeg' | 'image/webp' | 'image/png' | 'image/gif', quality?: number): string
   toDataURL(mime?: 'image/avif', cfg?: AvifConfig): string
 
   toDataURLAsync(mime?: 'image/png'): Promise<string>
   toDataURLAsync(mime: 'image/jpeg' | 'image/webp', quality?: number): Promise<string>
-  toDataURLAsync(mime?: 'image/jpeg' | 'image/webp' | 'image/png', quality?: number): Promise<string>
+  toDataURLAsync(mime: 'image/gif', quality?: number): Promise<string>
+  toDataURLAsync(mime?: 'image/jpeg' | 'image/webp' | 'image/png' | 'image/gif', quality?: number): Promise<string>
   toDataURLAsync(mime?: 'image/avif', cfg?: AvifConfig): Promise<string>
 
   toBlob(callback: (blob: Blob | null) => void, mime?: string, quality?: number): void

package/index.js

@@ -17,12 +17,21 @@ const {
   StrokeCap,
   convertSVGTextToPath,
   PdfDocument,
+  GifEncoder,
+  GifDisposal,
 } = require('./js-binding')
 
 const { DOMPoint, DOMMatrix, DOMRect } = require('./geometry')
 
 const loadImage = require('./load-image')
 
+// Add Symbol.dispose support for GifEncoder (ECMAScript 2024 Explicit Resource Management)
+if (GifEncoder && typeof Symbol.dispose !== 'undefined') {
+  GifEncoder.prototype[Symbol.dispose] = function () {
+    this.dispose()
+  }
+}
+
 const SvgExportFlag = {
   ConvertTextToPaths: 0x01,
   NoPrettyXML: 0x02,
@@ -178,4 +187,7 @@ module.exports = {
   CanvasElement,
   SVGCanvas,
   PDFDocument: PdfDocument,
+  // GIF encoding
+  GifEncoder,
+  GifDisposal,
 }

package/js-binding.js

@@ -460,3 +460,5 @@ module.exports.PathOp = nativeBinding.PathOp
 module.exports.StrokeCap = nativeBinding.StrokeCap
 module.exports.StrokeJoin = nativeBinding.StrokeJoin
 module.exports.SvgExportFlag = nativeBinding.SvgExportFlag
+module.exports.GifEncoder = nativeBinding.GifEncoder
+module.exports.GifDisposal = nativeBinding.GifDisposal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@napi-rs/canvas",
-  "version": "0.1.83",
+  "version": "0.1.84",
   "description": "Canvas for Node.js with skia backend",
   "main": "index.js",
   "repository": {
@@ -77,7 +77,7 @@
     "@jimp/png": "^0.22.12",
     "@napi-rs/cli": "^3.1.1",
     "@octokit/rest": "^22.0.0",
-    "@oxc-node/core": "^0.0.34",
+    "@oxc-node/core": "^0.0.35",
     "@taplo/cli": "^0.7.0",
     "@types/lodash": "^4.17.17",
     "@types/node": "^24.0.0",
@@ -102,7 +102,7 @@
     "semver": "^7.7.2",
     "skia-canvas": "^3.0.0",
     "table": "^6.9.0",
-    "tinybench": "^5.0.0",
+    "tinybench": "^6.0.0",
     "typescript": "^5.8.3"
   },
   "lint-staged": {
@@ -142,15 +142,15 @@
   },
   "packageManager": "yarn@4.12.0",
   "optionalDependencies": {
-    "@napi-rs/canvas-linux-x64-gnu": "0.1.83",
-    "@napi-rs/canvas-darwin-x64": "0.1.83",
-    "@napi-rs/canvas-win32-x64-msvc": "0.1.83",
-    "@napi-rs/canvas-linux-arm-gnueabihf": "0.1.83",
-    "@napi-rs/canvas-linux-x64-musl": "0.1.83",
-    "@napi-rs/canvas-linux-arm64-gnu": "0.1.83",
-    "@napi-rs/canvas-linux-arm64-musl": "0.1.83",
-    "@napi-rs/canvas-darwin-arm64": "0.1.83",
-    "@napi-rs/canvas-android-arm64": "0.1.83",
-    "@napi-rs/canvas-linux-riscv64-gnu": "0.1.83"
+    "@napi-rs/canvas-linux-x64-gnu": "0.1.84",
+    "@napi-rs/canvas-darwin-x64": "0.1.84",
+    "@napi-rs/canvas-win32-x64-msvc": "0.1.84",
+    "@napi-rs/canvas-linux-arm-gnueabihf": "0.1.84",
+    "@napi-rs/canvas-linux-x64-musl": "0.1.84",
+    "@napi-rs/canvas-linux-arm64-gnu": "0.1.84",
+    "@napi-rs/canvas-linux-arm64-musl": "0.1.84",
+    "@napi-rs/canvas-darwin-arm64": "0.1.84",
+    "@napi-rs/canvas-android-arm64": "0.1.84",
+    "@napi-rs/canvas-linux-riscv64-gnu": "0.1.84"
   }
 }