Make Conversion.cancel() cause execute() to throw (closes #271)

dev/convert.html

@@ -100,6 +100,7 @@
 			},
 			*/
 			video: () => ({
+				forceTranscode: true,
 				allowRotationMetadata: false,
 				//width: 720,
 				//frameRate: 30,
@@ -181,7 +182,7 @@
 			},
 			trim: {
 				start: 0,
-				end: 4
+				//end: 4
 			},
 		});
 		console.log(conversion);

docs/guide/converting-media-files.md

@@ -108,7 +108,7 @@ Sometimes, you may want to cancel an ongoing conversion process. For this, use t
 await conversion.cancel(); // Resolves once the conversion is canceled
 ```
 
-This automatically frees up all resources used by the conversion process.
+This automatically frees up all resources used by the conversion process and will cause any ongoing call to `execute` to throw a `ConversionCanceledError`.
 
 ## Video options
 

src/conversion.ts

@@ -822,7 +822,7 @@ export class Conversion {
 		}
 
 		if (this._canceled) {
-			await new Promise(() => {}); // Never resolve
+			throw new ConversionCanceledError();
 		}
 
 		await this.output.finalize();
@@ -832,7 +832,10 @@ export class Conversion {
 		}
 	}
 
-	/** Cancels the conversion process. Does nothing if the conversion is already complete. */
+	/**
+	 * Cancels the conversion process, causing any ongoing `execute` call to throw a `ConversionCanceledError`.
+	 * Does nothing if the conversion is already complete.
+	 */
 	async cancel() {
 		if (this.output.state === 'finalizing' || this.output.state === 'finalized') {
 			return;
@@ -1589,6 +1592,19 @@ export class Conversion {
 	}
 }
 
+/**
+ * Thrown when a conversion couldn't complete due to being canceled.
+ * @group Conversion
+ * @public
+ */
+export class ConversionCanceledError extends Error {
+	/** Creates a new {@link ConversionCanceledError}. */
+	constructor(message = 'Conversion has been canceled.') {
+		super(message);
+		this.name = 'ConversionCanceledError';
+	}
+}
+
 const MAX_TIMESTAMP_GAP = 5;
 
 /**

src/index.ts

@@ -190,6 +190,7 @@ export {
 	ConversionOptions,
 	ConversionVideoOptions,
 	ConversionAudioOptions,
+	ConversionCanceledError,
 	DiscardedTrack,
 } from './conversion';
 export {