@pproenca/node-webcodecs 0.1.1-alpha.0 → 0.1.1-alpha.6

package/lib/video-decoder.ts

@@ -17,6 +17,9 @@ import { VideoFrame } from './video-frame';
 // Load native addon with type assertion
 const native = binding as NativeModule;
 
+// Default backpressure threshold for limiting in-flight chunks
+const DEFAULT_MAX_QUEUE_DEPTH = 16;
+
 export class VideoDecoder extends CodecBase {
   private _native: NativeVideoDecoder;
   private _controlQueue: ControlMessageQueue;
@@ -25,6 +28,9 @@ export class VideoDecoder extends CodecBase {
   private _errorCallback: (error: DOMException) => void;
   private _resourceId: symbol;
 
+  // Backpressure support
+  private _maxQueueDepth: number = DEFAULT_MAX_QUEUE_DEPTH;
+
   constructor(init: VideoDecoderInit) {
     super();
     // W3C spec: output and error callbacks are required
@@ -38,7 +44,6 @@ export class VideoDecoder extends CodecBase {
     this._resourceId = ResourceManager.getInstance().register(this);
 
     const outputCallback: VideoDecoderOutputCallback = (nativeFrame) => {
-      // Decrement queue size when output received
       this._decodeQueueSize = Math.max(0, this._decodeQueueSize - 1);
 
       // Wrap the native frame as a VideoFrame
@@ -71,11 +76,78 @@ export class VideoDecoder extends CodecBase {
     return this._native.codecSaturated;
   }
 
+  /**
+   * Returns a Promise that resolves when the decoder has capacity for more chunks.
+   * Use this to implement backpressure in high-throughput decoding pipelines.
+   *
+   * When the internal queue is full (decodeQueueSize >= maxQueueDepth), calling
+   * `await decoder.ready` will pause until capacity is available.
+   *
+   * @example
+   * for (const chunk of chunks) {
+   *   await decoder.ready;  // Wait for capacity
+   *   decoder.decode(chunk);
+   * }
+   */
+  get ready(): Promise<void> {
+    // If we have capacity, resolve immediately
+    if (this._decodeQueueSize < this._maxQueueDepth) {
+      return Promise.resolve();
+    }
+
+    // Otherwise, poll until capacity is available.
+    // We use setTimeout(1ms) polling to allow TSFN output callbacks to execute.
+    // setTimeout ensures we yield through the full event loop cycle, including
+    // the I/O phase where TSFN callbacks are delivered.
+    return new Promise<void>((resolve) => {
+      const checkCapacity = () => {
+        if (this._decodeQueueSize < this._maxQueueDepth) {
+          resolve();
+        } else {
+          // Yield full event loop cycle to allow output callbacks to run
+          setTimeout(checkCapacity, 1);
+        }
+      };
+      // Initial yield to allow any pending callbacks to run
+      setTimeout(checkCapacity, 1);
+    });
+  }
+
+  /**
+   * The maximum queue depth before backpressure is applied.
+   * Default is 16. Adjust based on memory constraints and frame size.
+   */
+  get maxQueueDepth(): number {
+    return this._maxQueueDepth;
+  }
+
+  set maxQueueDepth(value: number) {
+    if (value < 1) {
+      throw new RangeError('maxQueueDepth must be at least 1');
+    }
+    this._maxQueueDepth = value;
+  }
+
   configure(config: VideoDecoderConfig): void {
     // W3C spec: throw if closed
     if (this.state === 'closed') {
       throw new DOMException('Decoder is closed', 'InvalidStateError');
     }
+
+    // Validate rotation (node-webcodecs extension)
+    if ('rotation' in config && config.rotation !== undefined) {
+      if (![0, 90, 180, 270].includes(config.rotation)) {
+        throw new TypeError(`rotation must be 0, 90, 180, or 270, got ${config.rotation}`);
+      }
+    }
+
+    // Validate flip (node-webcodecs extension)
+    if ('flip' in config && config.flip !== undefined) {
+      if (typeof config.flip !== 'boolean') {
+        throw new TypeError('flip must be a boolean');
+      }
+    }
+
     this._needsKeyFrame = true;
     // Configure synchronously to set state immediately per W3C spec
     this._native.configure(config);
@@ -111,7 +183,17 @@ export class VideoDecoder extends CodecBase {
       return Promise.reject(new DOMException('Decoder is closed', 'InvalidStateError'));
     }
     await this._controlQueue.flush();
-    return this._native.flush();
+
+    // Flush the native decoder (waits for worker queue to drain)
+    this._native.flush();
+
+    // Poll for pending TSFN callbacks to complete.
+    // This allows the event loop to run (delivering callbacks) while we wait.
+    // Using setTimeout(1ms) instead of setImmediate to ensure other event loop
+    // phases (timers, I/O) can run, preventing event loop starvation.
+    while (this._native.pendingFrames > 0) {
+      await new Promise((resolve) => setTimeout(resolve, 1)); // 1ms poll
+    }
   }
 
   reset(): void {

package/lib/video-encoder.ts

@@ -17,12 +17,18 @@ import type { VideoFrame } from './video-frame';
 // Load native addon with type assertion
 const native = binding as NativeModule;
 
+// Default backpressure threshold for limiting in-flight frames
+const DEFAULT_MAX_QUEUE_DEPTH = 16;
+
 export class VideoEncoder extends CodecBase {
   private _native: NativeVideoEncoder;
   private _controlQueue: ControlMessageQueue;
   private _encodeQueueSize: number = 0;
   private _resourceId: symbol;
 
+  // Backpressure support
+  private _maxQueueDepth: number = DEFAULT_MAX_QUEUE_DEPTH;
+
   constructor(init: VideoEncoderInit) {
     super();
     // W3C spec: output and error callbacks are required
@@ -35,19 +41,32 @@ export class VideoEncoder extends CodecBase {
     this._resourceId = ResourceManager.getInstance().register(this);
 
     const outputCallback: VideoEncoderOutputCallback = (chunk, metadata) => {
-      // Decrement queue size when output received
       this._encodeQueueSize = Math.max(0, this._encodeQueueSize - 1);
 
-      const wrappedChunk = new EncodedVideoChunk({
-        type: chunk.type as 'key' | 'delta',
-        timestamp: chunk.timestamp,
-        duration: chunk.duration ?? undefined,
-        data: chunk.data,
-      });
+      // The native layer now returns an EncodedVideoChunk directly (not a plain object).
+      // Check if it's already a native chunk (has close method) vs plain object (has data buffer).
+      // Native chunks have close() but no 'data' property; plain objects have 'data' buffer.
+      let wrappedChunk: EncodedVideoChunk;
+      if ('data' in chunk && chunk.data instanceof Buffer) {
+        // Legacy path: plain object from sync encoder - wrap it
+        wrappedChunk = new EncodedVideoChunk({
+          type: chunk.type as 'key' | 'delta',
+          timestamp: chunk.timestamp,
+          duration: chunk.duration ?? undefined,
+          data: chunk.data,
+        });
+      } else {
+        // New path: already a native EncodedVideoChunk from async encoder
+        // Wrap without copying data
+        wrappedChunk = EncodedVideoChunk._fromNative(
+          chunk as unknown as import('./native-types').NativeEncodedVideoChunk,
+        );
+      }
       init.output(wrappedChunk, metadata);
 
       // Fire ondequeue after output
       this._triggerDequeue();
+
     };
 
     this._native = new native.VideoEncoder({
@@ -68,6 +87,59 @@ export class VideoEncoder extends CodecBase {
     return this._native.codecSaturated;
   }
 
+  /**
+   * Returns a Promise that resolves when the encoder has capacity for more frames.
+   * Use this to implement backpressure in high-throughput encoding pipelines.
+   *
+   * When the internal queue is full (encodeQueueSize >= maxQueueDepth), calling
+   * `await encoder.ready` will pause until capacity is available.
+   *
+   * @example
+   * for (const frame of frames) {
+   *   await encoder.ready;  // Wait for capacity
+   *   encoder.encode(frame);
+   *   frame.close();
+   * }
+   */
+  get ready(): Promise<void> {
+    // If we have capacity, resolve immediately
+    if (this._encodeQueueSize < this._maxQueueDepth) {
+      return Promise.resolve();
+    }
+
+    // Otherwise, poll until capacity is available.
+    // We use setTimeout(1ms) polling to allow TSFN output callbacks to execute.
+    // setTimeout ensures we yield through the full event loop cycle, including
+    // the I/O phase where TSFN callbacks are delivered.
+    return new Promise<void>((resolve) => {
+      const checkCapacity = () => {
+        if (this._encodeQueueSize < this._maxQueueDepth) {
+          resolve();
+        } else {
+          // Yield full event loop cycle to allow output callbacks to run
+          setTimeout(checkCapacity, 1);
+        }
+      };
+      // Initial yield to allow any pending callbacks to run
+      setTimeout(checkCapacity, 1);
+    });
+  }
+
+  /**
+   * The maximum queue depth before backpressure is applied.
+   * Default is 16. Adjust based on memory constraints and frame size.
+   */
+  get maxQueueDepth(): number {
+    return this._maxQueueDepth;
+  }
+
+  set maxQueueDepth(value: number) {
+    if (value < 1) {
+      throw new RangeError('maxQueueDepth must be at least 1');
+    }
+    this._maxQueueDepth = value;
+  }
+
   configure(config: VideoEncoderConfig): void {
     // W3C spec: throw if closed
     if (this.state === 'closed') {
@@ -84,6 +156,10 @@ export class VideoEncoder extends CodecBase {
   }
 
   encode(frame: VideoFrame, options?: { keyFrame?: boolean }): void {
+    // W3C spec: throw if not configured
+    if (this.state !== 'configured') {
+      throw new DOMException(`Encoder is ${this.state}`, 'InvalidStateError');
+    }
     ResourceManager.getInstance().recordActivity(this._resourceId);
     this._encodeQueueSize++;
     // Call native encode directly - frame must be valid at call time
@@ -105,12 +181,18 @@ export class VideoEncoder extends CodecBase {
 
     // Poll for pending TSFN callbacks to complete.
     // This allows the event loop to run (delivering callbacks) while we wait.
+    // Using setTimeout(1ms) instead of setImmediate to ensure other event loop
+    // phases (timers, I/O) can run, preventing event loop starvation.
     while (this._native.pendingChunks > 0) {
-      await new Promise((resolve) => setImmediate(resolve));
+      await new Promise((resolve) => setTimeout(resolve, 1)); // 1ms poll
     }
   }
 
   reset(): void {
+    // W3C spec: throw if closed
+    if (this.state === 'closed') {
+      throw new DOMException('Encoder is closed', 'InvalidStateError');
+    }
     this._controlQueue.clear();
     this._encodeQueueSize = 0;
     this._native.reset();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pproenca/node-webcodecs",
   "description": "WebCodecs API implementation for Node.js using FFmpeg",
-  "version": "0.1.1-alpha.0",
+  "version": "0.1.1-alpha.6",
   "author": "Pedro Proenca",
   "homepage": "https://github.com/pproenca/node-webcodecs",
   "repository": {
@@ -12,29 +12,47 @@
     "url": "https://github.com/pproenca/node-webcodecs/issues"
   },
   "scripts": {
-    "build": "npm run build:native && npm run build:ts",
-    "build:ts": "tsc",
+    "build": "node-gyp rebuild && tsc",
     "build:native": "node-gyp rebuild",
-    "build:native:debug": "node-gyp rebuild --debug",
-    "install": "node install/check.js || npm run build",
+    "build:ts": "tsc",
+    "build:debug": "node-gyp rebuild --debug && tsc",
+    "rebuild": "npm run clean && npm run build",
     "clean": "rm -rf src/build/ .nyc_output/ coverage/ test/fixtures/output.*",
-    "test": "npm run lint && npm run test-unit",
-    "test-unit": "vitest run --config test/vitest.config.ts",
-    "lint": "npm run lint-cpp && npm run lint-js && npm run lint-types",
-    "lint-cpp": "cpplint --quiet src/*.h src/*.cc",
-    "lint-js": "biome lint",
-    "lint-types": "tsd",
-    "package-from-local-build": "node npm/from-local-build.js",
-    "package-release-notes": "node npm/release-notes.js"
+    "check": "npm run lint && npm test",
+    "test": "npm run test:fast && npm run test:guardrails",
+    "test:fast": "tsx --test --test-concurrency=1 --import ./test/setup.ts --test-timeout=30000 test/golden/*.test.ts test/unit/*.test.ts",
+    "test:golden": "tsx --test --test-concurrency=1 --import ./test/setup.ts --test-timeout=30000 test/golden/*.test.ts",
+    "test:unit": "tsx --test --test-concurrency=1 --import ./test/setup.ts --test-timeout=30000 test/unit/*.test.ts",
+    "test:stress": "tsx --test --test-concurrency=1 --import ./test/setup.ts --test-timeout=60000 test/stress/*.test.ts",
+    "test:contracts": "node test/contracts/video_encoder/state_machine.js && node test/contracts/audio_encoder/state_machine.js && node test/contracts/video_decoder/state_machine.js && node test/contracts/audio_decoder/state_machine.js",
+    "test:guardrails": "node test/guardrails/fuzzer.js && node test/guardrails/event_loop_lag.js",
+    "test:coverage": "c8 --check-coverage --lines 70 --branches 60 --functions 70 --statements 70 --include lib/**/*.ts --exclude lib/**/*.d.ts --exclude lib/types.ts npm run test:fast",
+    "lint": "npm run lint:cpp && npm run lint:ts && npm run lint:types && npm run lint:md",
+    "lint:cpp": "cpplint --quiet src/*.h src/*.cc",
+    "lint:ts": "biome lint",
+    "lint:types": "tsd",
+    "lint:md": "prettier --check \"**/*.md\"",
+    "format": "npm run format:md",
+    "format:md": "prettier --write \"**/*.md\"",
+    "version:bump": "node scripts/bump-version.js",
+    "create-platform-packages": "node scripts/create-platform-packages.mjs"
   },
   "type": "commonjs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
   "files": [
-    "install",
     "lib",
     "dist",
-    "src/*.{cc,h,gyp}"
+    "src/*.{cc,h,gyp}",
+    "binding.gyp"
   ],
   "keywords": [
     "webcodecs",
@@ -46,35 +64,33 @@
   "tsd": {
     "directory": "test/types"
   },
+  "optionalDependencies": {
+    "@pproenca/node-webcodecs-darwin-arm64": "0.1.1-alpha.5",
+    "@pproenca/node-webcodecs-darwin-x64": "0.1.1-alpha.5",
+    "@pproenca/node-webcodecs-linux-x64": "0.1.1-alpha.5"
+  },
   "dependencies": {
-    "detect-libc": "^2.0.3",
     "node-gyp-build": "^4.8.0"
   },
-  "optionalDependencies": {
-    "@pproenca/node-webcodecs-darwin-arm64": "0.1.0",
-    "@pproenca/node-webcodecs-darwin-x64": "0.1.0",
-    "@pproenca/node-webcodecs-linux-x64": "0.1.0",
-    "@pproenca/node-webcodecs-linuxmusl-x64": "0.1.0",
-    "@pproenca/node-webcodecs-win32-x64": "0.1.0"
-  },
   "devDependencies": {
     "@biomejs/biome": "^2.3.10",
     "@cpplint/cli": "^0.1.0",
-    "@types/node": "*",
-    "c8": "^10.1.2",
+    "@types/node": "^25.0.3",
+    "c8": "^10.1.3",
     "express": "^5.2.1",
-    "mediabunny": "^1.25.4",
-    "node-addon-api": "^8.0.0",
-    "node-gyp": "^10.0.0",
+    "mediabunny": "^1.27.3",
+    "node-addon-api": "^8.5.0",
+    "node-gyp": "^12.1.0",
+    "prebuildify": "^6.0.1",
+    "prettier": "^3.7.4",
     "tsd": "^0.33.0",
-    "tsx": "^4.20.6",
+    "tsx": "^4.21.0",
     "typedoc": "^0.28.15",
-    "typescript": "^5.6.3",
-    "vitest": "^4.0.15"
+    "typescript": "^5.9.3"
   },
   "license": "MIT",
   "engines": {
-    "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+    "node": "^20.17.0 || ^22.9.0 || >=24"
   },
   "publishConfig": {
     "access": "public",

package/src/addon.cc

@@ -41,6 +41,45 @@ void ClearFFmpegWarningsJS(const Napi::CallbackInfo& info) {
   webcodecs::ClearFFmpegWarnings();
 }
 
+// Counter accessor functions (following sharp pattern for observability)
+Napi::Value GetCounterQueueJS(const Napi::CallbackInfo& info) {
+  return Napi::Number::New(info.Env(), webcodecs::counterQueue.load());
+}
+
+Napi::Value GetCounterProcessJS(const Napi::CallbackInfo& info) {
+  return Napi::Number::New(info.Env(), webcodecs::counterProcess.load());
+}
+
+Napi::Value GetCounterFramesJS(const Napi::CallbackInfo& info) {
+  return Napi::Number::New(info.Env(), webcodecs::counterFrames.load());
+}
+
+Napi::Value GetCountersJS(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  Napi::Object counters = Napi::Object::New(env);
+
+  // New per-class counters
+  counters.Set("videoFrames",
+               static_cast<double>(webcodecs::counterVideoFrames.load()));
+  counters.Set("audioData",
+               static_cast<double>(webcodecs::counterAudioData.load()));
+  counters.Set("videoEncoders",
+               static_cast<double>(webcodecs::counterVideoEncoders.load()));
+  counters.Set("videoDecoders",
+               static_cast<double>(webcodecs::counterVideoDecoders.load()));
+  counters.Set("audioEncoders",
+               static_cast<double>(webcodecs::counterAudioEncoders.load()));
+  counters.Set("audioDecoders",
+               static_cast<double>(webcodecs::counterAudioDecoders.load()));
+
+  // Legacy counters (for backwards compatibility)
+  counters.Set("queue", webcodecs::counterQueue.load());
+  counters.Set("process", webcodecs::counterProcess.load());
+  counters.Set("frames", webcodecs::counterFrames.load());
+
+  return counters;
+}
+
 // Test helper for AttrAsEnum template
 Napi::Value TestAttrAsEnum(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
@@ -54,11 +93,22 @@ Napi::Value TestAttrAsEnum(const Napi::CallbackInfo& info) {
   return Napi::String::New(env, webcodecs::ColorPrimariesToString(primaries));
 }
 
+// Cleanup hook called when the Node.js environment is being torn down.
+// This prevents the static destruction order fiasco where FFmpeg's log
+// callback might access destroyed static objects during process exit.
+static void CleanupCallback(void* arg) {
+  webcodecs::ShutdownFFmpegLogging();
+}
+
 Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
   // Thread-safe FFmpeg initialization
   webcodecs::InitFFmpeg();
   webcodecs::InitFFmpegLogging();
 
+  // Register cleanup hook to disable FFmpeg logging before static destructors.
+  // This fixes crashes on macOS x64 where FFmpeg logs during process exit.
+  napi_add_env_cleanup_hook(env, CleanupCallback, nullptr);
+
   InitVideoEncoder(env, exports);
   InitVideoDecoder(env, exports);
   InitVideoFrame(env, exports);
@@ -82,6 +132,13 @@ Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
   exports.Set("clearFFmpegWarnings",
               Napi::Function::New(env, ClearFFmpegWarningsJS));
 
+  // Export global counter functions (following sharp pattern for observability)
+  exports.Set("getCounterQueue", Napi::Function::New(env, GetCounterQueueJS));
+  exports.Set("getCounterProcess",
+              Napi::Function::New(env, GetCounterProcessJS));
+  exports.Set("getCounterFrames", Napi::Function::New(env, GetCounterFramesJS));
+  exports.Set("getCounters", Napi::Function::New(env, GetCountersJS));
+
   // Export test helpers
   exports.Set("testAttrAsEnum", Napi::Function::New(env, TestAttrAsEnum));