webcodecs-node 0.3.0 → 0.5.1

package/dist/utils/buffer-pool.js

@@ -0,0 +1,278 @@
+/**
+ * Buffer Pool - Reuses typed array buffers to reduce allocation overhead
+ *
+ * Frequently allocating large buffers (e.g., 1080p frame = ~8MB) can cause
+ * GC pressure. This pool maintains reusable buffers organized by size buckets.
+ *
+ * Usage:
+ * - For temporary buffers in format conversions, encoding, decoding
+ * - NOT for long-lived VideoFrame/AudioData data (those follow WebCodecs lifecycle)
+ */
+import { createLogger } from './logger.js';
+const logger = createLogger('BufferPool');
+/**
+ * Default size buckets optimized for video frames:
+ * - Small: 720p I420 (~1.4MB), 720p RGBA (~3.7MB)
+ * - Medium: 1080p I420 (~3.1MB), 1080p RGBA (~8.3MB)
+ * - Large: 4K I420 (~12.4MB), 4K RGBA (~33MB)
+ */
+const DEFAULT_SIZE_BUCKETS = [
+    512 * 1024, // 512KB - small audio/thumbnails
+    1024 * 1024, // 1MB
+    2 * 1024 * 1024, // 2MB - 720p I420
+    4 * 1024 * 1024, // 4MB - 720p RGBA / 1080p I420
+    8 * 1024 * 1024, // 8MB - 1080p RGBA
+    16 * 1024 * 1024, // 16MB - 4K I420
+    32 * 1024 * 1024, // 32MB - 4K RGBA
+    64 * 1024 * 1024, // 64MB - 8K I420
+];
+const DEFAULT_CONFIG = {
+    sizeBuckets: DEFAULT_SIZE_BUCKETS,
+    maxBuffersPerBucket: 4,
+    idleTimeoutMs: 30_000,
+    trackStats: false,
+};
+/**
+ * Buffer pool for efficient buffer reuse
+ */
+class BufferPool {
+    buckets = new Map();
+    config;
+    cleanupTimer = null;
+    disposed = false;
+    stats = {
+        hits: 0,
+        misses: 0,
+        allocations: 0,
+        returns: 0,
+        discards: 0,
+        totalPooled: 0,
+        totalPooledBytes: 0,
+    };
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        // Initialize buckets
+        for (const size of this.config.sizeBuckets) {
+            this.buckets.set(size, []);
+        }
+        this.startCleanupTimer();
+    }
+    /**
+     * Acquire a buffer of at least the specified size
+     * Returns a buffer from the pool if available, or allocates a new one
+     *
+     * @param size - Minimum required buffer size in bytes
+     * @returns Uint8Array of at least the requested size
+     */
+    acquire(size) {
+        if (this.disposed) {
+            return new Uint8Array(size);
+        }
+        const bucketSize = this.findBucketSize(size);
+        if (bucketSize === null) {
+            // Size too large for buckets, allocate directly
+            if (this.config.trackStats) {
+                this.stats.allocations++;
+                this.stats.misses++;
+            }
+            return new Uint8Array(size);
+        }
+        const bucket = this.buckets.get(bucketSize);
+        if (bucket.length > 0) {
+            const entry = bucket.pop();
+            if (this.config.trackStats) {
+                this.stats.hits++;
+                this.stats.totalPooled--;
+                this.stats.totalPooledBytes -= bucketSize;
+            }
+            // Return a view of the buffer with exact requested size
+            return entry.buffer.subarray(0, size);
+        }
+        // No pooled buffer available, allocate new one at bucket size
+        if (this.config.trackStats) {
+            this.stats.allocations++;
+            this.stats.misses++;
+        }
+        const buffer = new Uint8Array(bucketSize);
+        return buffer.subarray(0, size);
+    }
+    /**
+     * Return a buffer to the pool for reuse
+     *
+     * @param buffer - The buffer to return (must be the original buffer, not a subarray)
+     */
+    release(buffer) {
+        if (!buffer || this.disposed) {
+            return;
+        }
+        // Get the underlying buffer's full length
+        const fullBuffer = buffer.byteLength === buffer.buffer.byteLength
+            ? buffer
+            : new Uint8Array(buffer.buffer, buffer.byteOffset);
+        const bucketSize = this.findExactBucketSize(fullBuffer.byteLength);
+        if (bucketSize === null) {
+            // Not a poolable size, let GC handle it
+            if (this.config.trackStats) {
+                this.stats.discards++;
+            }
+            return;
+        }
+        const bucket = this.buckets.get(bucketSize);
+        if (bucket.length >= this.config.maxBuffersPerBucket) {
+            // Bucket full, let GC handle this buffer
+            if (this.config.trackStats) {
+                this.stats.discards++;
+            }
+            return;
+        }
+        // Add to pool
+        bucket.push({
+            buffer: fullBuffer,
+            lastUsed: Date.now(),
+        });
+        if (this.config.trackStats) {
+            this.stats.returns++;
+            this.stats.totalPooled++;
+            this.stats.totalPooledBytes += bucketSize;
+        }
+    }
+    /**
+     * Get pool statistics
+     */
+    getStats() {
+        return { ...this.stats };
+    }
+    /**
+     * Clear all pooled buffers
+     */
+    clear() {
+        for (const bucket of this.buckets.values()) {
+            bucket.length = 0;
+        }
+        this.stats.totalPooled = 0;
+        this.stats.totalPooledBytes = 0;
+        logger.debug('Buffer pool cleared');
+    }
+    /**
+     * Dispose the pool and release all buffers
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        this.clear();
+        logger.info('Buffer pool disposed');
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Private methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Find the smallest bucket that can fit the requested size
+     */
+    findBucketSize(size) {
+        for (const bucketSize of this.config.sizeBuckets) {
+            if (bucketSize >= size) {
+                return bucketSize;
+            }
+        }
+        return null;
+    }
+    /**
+     * Find exact bucket size match
+     */
+    findExactBucketSize(size) {
+        if (this.buckets.has(size)) {
+            return size;
+        }
+        return null;
+    }
+    startCleanupTimer() {
+        // Run cleanup every 10 seconds
+        this.cleanupTimer = setInterval(() => {
+            this.cleanupIdleBuffers();
+        }, 10_000);
+        // Don't prevent process from exiting
+        if (this.cleanupTimer.unref) {
+            this.cleanupTimer.unref();
+        }
+    }
+    cleanupIdleBuffers() {
+        const now = Date.now();
+        let removed = 0;
+        let bytesRemoved = 0;
+        for (const [size, bucket] of this.buckets) {
+            // Keep at least one buffer per bucket for quick reuse
+            const keepCount = 1;
+            for (let i = bucket.length - 1; i >= keepCount; i--) {
+                const entry = bucket[i];
+                if ((now - entry.lastUsed) > this.config.idleTimeoutMs) {
+                    bucket.splice(i, 1);
+                    removed++;
+                    bytesRemoved += size;
+                }
+            }
+        }
+        if (removed > 0) {
+            if (this.config.trackStats) {
+                this.stats.totalPooled -= removed;
+                this.stats.totalPooledBytes -= bytesRemoved;
+            }
+            logger.debug(`Cleaned up ${removed} idle buffers (${(bytesRemoved / 1024 / 1024).toFixed(1)}MB)`);
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Global pool singleton
+// ─────────────────────────────────────────────────────────────────────────────
+let globalPool = null;
+/**
+ * Get the global buffer pool
+ * Creates one on first access with default configuration
+ */
+export function getBufferPool() {
+    if (!globalPool) {
+        globalPool = new BufferPool();
+    }
+    return globalPool;
+}
+/**
+ * Initialize the global pool with custom configuration
+ * Should be called before first use if custom config is needed
+ */
+export function initBufferPool(config) {
+    if (globalPool) {
+        globalPool.dispose();
+    }
+    globalPool = new BufferPool(config);
+    return globalPool;
+}
+/**
+ * Dispose the global pool
+ * Call this when shutting down the application
+ */
+export function disposeBufferPool() {
+    if (globalPool) {
+        globalPool.dispose();
+        globalPool = null;
+    }
+}
+/**
+ * Acquire a buffer from the global pool
+ * @param size - Minimum required buffer size in bytes
+ */
+export function acquireBuffer(size) {
+    return getBufferPool().acquire(size);
+}
+/**
+ * Release a buffer back to the global pool
+ * @param buffer - The buffer to return
+ */
+export function releaseBuffer(buffer) {
+    getBufferPool().release(buffer);
+}
+export { BufferPool };
+//# sourceMappingURL=buffer-pool.js.map

package/dist/utils/buffer-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer-pool.js","sourceRoot":"","sources":["../../src/utils/buffer-pool.ts"],"names":[],"mappings":"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"}

package/dist/utils/codec-cache.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Cached codec string parsing utilities
+ *
+ * Codec strings are parsed frequently throughout the codebase.
+ * Caching avoids repeated string operations for the same codec.
+ */
+/**
+ * Parsed codec information
+ */
+export interface ParsedCodec {
+    /** Base codec identifier (e.g., 'avc1', 'hev1', 'vp09') */
+    base: string;
+    /** Normalized codec name (e.g., 'h264', 'hevc', 'vp9') */
+    name: VideoCodecName | AudioCodecName | null;
+    /** Original codec string */
+    original: string;
+    /** Whether this is a video codec */
+    isVideo: boolean;
+    /** Whether this is an audio codec */
+    isAudio: boolean;
+}
+export type VideoCodecName = 'h264' | 'hevc' | 'vp8' | 'vp9' | 'av1';
+export type AudioCodecName = 'aac' | 'opus' | 'mp3' | 'vorbis' | 'flac';
+/**
+ * Get the base codec identifier from a codec string (cached)
+ *
+ * @example
+ * getCodecBase('avc1.42001E') // 'avc1'
+ * getCodecBase('vp09.00.10.08') // 'vp09'
+ * getCodecBase('opus') // 'opus'
+ */
+export declare function getCodecBase(codec: string): string;
+/**
+ * Parse a codec string and return structured information (cached)
+ *
+ * @example
+ * parseCodec('avc1.42001E')
+ * // { base: 'avc1', name: 'h264', original: 'avc1.42001E', isVideo: true, isAudio: false }
+ */
+export declare function parseCodec(codec: string): ParsedCodec;
+/**
+ * Get normalized video codec name from codec string (cached)
+ *
+ * @returns Normalized name or null if not a recognized video codec
+ */
+export declare function getVideoCodecName(codec: string): VideoCodecName | null;
+/**
+ * Get normalized audio codec name from codec string (cached)
+ *
+ * @returns Normalized name or null if not a recognized audio codec
+ */
+export declare function getAudioCodecName(codec: string): AudioCodecName | null;
+/**
+ * Check if a codec string represents a video codec
+ */
+export declare function isVideoCodec(codec: string): boolean;
+/**
+ * Check if a codec string represents an audio codec
+ */
+export declare function isAudioCodec(codec: string): boolean;
+/**
+ * Clear the codec caches (for testing)
+ */
+export declare function clearCodecCache(): void;
+//# sourceMappingURL=codec-cache.d.ts.map

package/dist/utils/codec-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-cache.d.ts","sourceRoot":"","sources":["../../src/utils/codec-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,IAAI,CAAC;IAC7C,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AACrE,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAgCxE;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOlD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAiBrD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAGtE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAGtE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAGtC"}

package/dist/utils/codec-cache.js

@@ -0,0 +1,116 @@
+/**
+ * Cached codec string parsing utilities
+ *
+ * Codec strings are parsed frequently throughout the codebase.
+ * Caching avoids repeated string operations for the same codec.
+ */
+// Cache for codec base extraction (e.g., 'avc1.42001E' -> 'avc1')
+const codecBaseCache = new Map();
+// Cache for full codec parsing results
+const codecParseCache = new Map();
+/**
+ * Video codec base to name mapping
+ */
+const VIDEO_CODEC_MAP = {
+    'avc1': 'h264',
+    'avc3': 'h264',
+    'h264': 'h264',
+    'hvc1': 'hevc',
+    'hev1': 'hevc',
+    'hevc': 'hevc',
+    'h265': 'hevc',
+    'vp8': 'vp8',
+    'vp9': 'vp9',
+    'vp09': 'vp9',
+    'av01': 'av1',
+    'av1': 'av1',
+};
+/**
+ * Audio codec base to name mapping
+ */
+const AUDIO_CODEC_MAP = {
+    'mp4a': 'aac',
+    'aac': 'aac',
+    'opus': 'opus',
+    'mp3': 'mp3',
+    'vorbis': 'vorbis',
+    'flac': 'flac',
+};
+/**
+ * Get the base codec identifier from a codec string (cached)
+ *
+ * @example
+ * getCodecBase('avc1.42001E') // 'avc1'
+ * getCodecBase('vp09.00.10.08') // 'vp09'
+ * getCodecBase('opus') // 'opus'
+ */
+export function getCodecBase(codec) {
+    let base = codecBaseCache.get(codec);
+    if (base === undefined) {
+        base = codec.split('.')[0].toLowerCase();
+        codecBaseCache.set(codec, base);
+    }
+    return base;
+}
+/**
+ * Parse a codec string and return structured information (cached)
+ *
+ * @example
+ * parseCodec('avc1.42001E')
+ * // { base: 'avc1', name: 'h264', original: 'avc1.42001E', isVideo: true, isAudio: false }
+ */
+export function parseCodec(codec) {
+    let parsed = codecParseCache.get(codec);
+    if (parsed === undefined) {
+        const base = getCodecBase(codec);
+        const videoName = VIDEO_CODEC_MAP[base] ?? null;
+        const audioName = AUDIO_CODEC_MAP[base] ?? null;
+        parsed = {
+            base,
+            name: videoName ?? audioName,
+            original: codec,
+            isVideo: videoName !== null,
+            isAudio: audioName !== null,
+        };
+        codecParseCache.set(codec, parsed);
+    }
+    return parsed;
+}
+/**
+ * Get normalized video codec name from codec string (cached)
+ *
+ * @returns Normalized name or null if not a recognized video codec
+ */
+export function getVideoCodecName(codec) {
+    const parsed = parseCodec(codec);
+    return parsed.isVideo ? parsed.name : null;
+}
+/**
+ * Get normalized audio codec name from codec string (cached)
+ *
+ * @returns Normalized name or null if not a recognized audio codec
+ */
+export function getAudioCodecName(codec) {
+    const parsed = parseCodec(codec);
+    return parsed.isAudio ? parsed.name : null;
+}
+/**
+ * Check if a codec string represents a video codec
+ */
+export function isVideoCodec(codec) {
+    return parseCodec(codec).isVideo;
+}
+/**
+ * Check if a codec string represents an audio codec
+ */
+export function isAudioCodec(codec) {
+    return parseCodec(codec).isAudio;
+}
+/**
+ * Clear the codec caches (for testing)
+ */
+export function clearCodecCache() {
+    codecBaseCache.clear();
+    codecParseCache.clear();
+}
+//# sourceMappingURL=codec-cache.js.map

package/dist/utils/codec-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-cache.js","sourceRoot":"","sources":["../../src/utils/codec-cache.ts"],"names":[],"mappings":"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"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Standardized error utilities for WebCodecs compliance
+ *
+ * The WebCodecs spec uses specific DOMException error names:
+ * - InvalidStateError: operation on wrong state
+ * - NotSupportedError: unsupported codec/config
+ * - DataError: malformed/corrupt data
+ * - EncodingError: codec processing failure
+ * - AbortError: operation was aborted
+ * - TypeError: invalid parameters (thrown, not via callback)
+ * - QuotaExceededError: queue full
+ * - TimeoutError: operation timed out
+ */
+import { DOMException } from '../types/index.js';
+/**
+ * Standard WebCodecs error types
+ */
+export type WebCodecsErrorName = 'InvalidStateError' | 'NotSupportedError' | 'DataError' | 'EncodingError' | 'AbortError' | 'QuotaExceededError' | 'TimeoutError';
+/**
+ * Create a WebCodecs-compliant error
+ */
+export declare function createWebCodecsError(message: string, name: WebCodecsErrorName): DOMException;
+/**
+ * Create an InvalidStateError (e.g., encoder not configured)
+ */
+export declare function invalidStateError(message: string): DOMException;
+/**
+ * Create a NotSupportedError (e.g., unsupported codec)
+ */
+export declare function notSupportedError(message: string): DOMException;
+/**
+ * Create a DataError (e.g., corrupt input data)
+ */
+export declare function dataError(message: string): DOMException;
+/**
+ * Create an EncodingError (e.g., codec processing failed)
+ */
+export declare function encodingError(message: string): DOMException;
+/**
+ * Create an AbortError (e.g., operation was reset/closed)
+ */
+export declare function abortError(message: string): DOMException;
+/**
+ * Create a QuotaExceededError (e.g., queue full)
+ */
+export declare function quotaExceededError(message: string): DOMException;
+/**
+ * Create a TimeoutError (e.g., operation timed out)
+ */
+export declare function timeoutError(message: string): DOMException;
+/**
+ * Wrap an error as a DOMException if it isn't already
+ *
+ * @param error - The error to wrap
+ * @param defaultName - The error name to use if error is not a DOMException
+ */
+export declare function wrapAsWebCodecsError(error: unknown, defaultName?: WebCodecsErrorName): DOMException;
+/**
+ * Check if an error is a specific WebCodecs error type
+ */
+export declare function isWebCodecsError(error: unknown, name: WebCodecsErrorName): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,mBAAmB,GACnB,mBAAmB,GACnB,WAAW,GACX,eAAe,GACf,YAAY,GACZ,oBAAoB,GACpB,cAAc,CAAC;AAEnB;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,kBAAkB,GACvB,YAAY,CAEd;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAE/D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAE/D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAEvD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAE3D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAExD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAEhE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,WAAW,GAAE,kBAAoC,GAChD,YAAY,CAQd;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAElF"}

package/dist/utils/errors.js

@@ -0,0 +1,84 @@
+/**
+ * Standardized error utilities for WebCodecs compliance
+ *
+ * The WebCodecs spec uses specific DOMException error names:
+ * - InvalidStateError: operation on wrong state
+ * - NotSupportedError: unsupported codec/config
+ * - DataError: malformed/corrupt data
+ * - EncodingError: codec processing failure
+ * - AbortError: operation was aborted
+ * - TypeError: invalid parameters (thrown, not via callback)
+ * - QuotaExceededError: queue full
+ * - TimeoutError: operation timed out
+ */
+import { DOMException } from '../types/index.js';
+/**
+ * Create a WebCodecs-compliant error
+ */
+export function createWebCodecsError(message, name) {
+    return new DOMException(message, name);
+}
+/**
+ * Create an InvalidStateError (e.g., encoder not configured)
+ */
+export function invalidStateError(message) {
+    return new DOMException(message, 'InvalidStateError');
+}
+/**
+ * Create a NotSupportedError (e.g., unsupported codec)
+ */
+export function notSupportedError(message) {
+    return new DOMException(message, 'NotSupportedError');
+}
+/**
+ * Create a DataError (e.g., corrupt input data)
+ */
+export function dataError(message) {
+    return new DOMException(message, 'DataError');
+}
+/**
+ * Create an EncodingError (e.g., codec processing failed)
+ */
+export function encodingError(message) {
+    return new DOMException(message, 'EncodingError');
+}
+/**
+ * Create an AbortError (e.g., operation was reset/closed)
+ */
+export function abortError(message) {
+    return new DOMException(message, 'AbortError');
+}
+/**
+ * Create a QuotaExceededError (e.g., queue full)
+ */
+export function quotaExceededError(message) {
+    return new DOMException(message, 'QuotaExceededError');
+}
+/**
+ * Create a TimeoutError (e.g., operation timed out)
+ */
+export function timeoutError(message) {
+    return new DOMException(message, 'TimeoutError');
+}
+/**
+ * Wrap an error as a DOMException if it isn't already
+ *
+ * @param error - The error to wrap
+ * @param defaultName - The error name to use if error is not a DOMException
+ */
+export function wrapAsWebCodecsError(error, defaultName = 'EncodingError') {
+    if (error instanceof DOMException) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new DOMException(error.message, defaultName);
+    }
+    return new DOMException(String(error), defaultName);
+}
+/**
+ * Check if an error is a specific WebCodecs error type
+ */
+export function isWebCodecsError(error, name) {
+    return error instanceof DOMException && error.name === name;
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAcjD;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,IAAwB;IAExB,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;AACxD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;AACxD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;AACnD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAc,EACd,cAAkC,eAAe;IAEjD,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc,EAAE,IAAwB;IACvE,OAAO,KAAK,YAAY,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;AAC9D,CAAC"}