From 18ef270cc2b312633c0aeab1db0d3b4217def011 Mon Sep 17 00:00:00 2001
From: Chris Zuber <shgysk8zer0@gmail.com>
Date: Fri, 27 Feb 2026 13:22:53 -0800
Subject: [PATCH] Use DisposableStack for resource cleanup

Introduce DisposableStack-based lifecycle management for the barcode scanner: createBarcodeScanner now accepts a `base` (DocumentOrShadowRoot) to find video elements by id and an optional `stack` to manage disposables. Internals now adopt/defer abort controllers, wake lock and media stream via a DisposableStack/AsyncDisposableStack, attach stack disposal on abort, and surface a disposable on the returned scanner object. index.js `start()` was converted to async and updated to use a DisposableStack for start/stop handling. CHANGELOG updated and package.json version bumped to 1.2.3 with dev dependency version bumps.
---
 CHANGELOG.md      |  7 +++++
 index.js          | 13 +++++----
 package-lock.json | 22 +++++++++------
 package.json      | 12 ++++-----
 scanner.js        | 69 ++++++++++++++++++++++++++++++++---------------
 5 files changed, 80 insertions(+), 43 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a2f7638..9382298 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [v1.2.3] - 2026-02-27
+
+### Added
+- Add a `DisposableStack` to clean-up
+- Add support for passing a `base` (document or Shadow Root) to get `<video>` from
+- Support numerous forms of disposal
+
 ## [v1.2.2] - 2025-12-16
 
 ### Added
diff --git a/index.js b/index.js
index 3e8c81c..caea4a2 100644
--- a/index.js
+++ b/index.js
@@ -7,17 +7,16 @@ document.adoptedStyleSheets = [reset, theme, btn];
 
 preloadRxing();
 
-function start() {
-	const controller = new AbortController();
-	const signal = controller.signal;
+async function start() {
 	const btn = document.getElementById('stop');
+	const stack = new DisposableStack();
 
 	createBarcodeScanner(({ rawValue, format }) => {
 		const li = document.createElement('li');
 		li.textContent = `[${format}] ${rawValue}`;
 		document.getElementById('results').append(li);
-	}, { frameRate: 24, signal, video: 'scanner', chimeType: 'sawtooth', chimeFrequency: 4000, chimeDuration: 0.1 }).catch(err => {
-		controller.abort(err);
+	}, { frameRate: 24, video: 'scanner', chimeType: 'sawtooth', chimeFrequency: 4000, chimeDuration: 0.1, stack }).catch(err => {
+		stack.disposeAsync();
 		reportError(err);
 		const li = document.createElement('li');
 		li.textContent = err.message;
@@ -25,10 +24,10 @@ function start() {
 	});
 
 	btn.addEventListener('click', ({ currentTarget }) => {
-		controller.abort();
+		stack.dispose();
 		currentTarget.disabled = true;
 		document.getElementById('start').disabled = false;
-	}, { once: true, signal });
+	}, { once: true });
 
 	btn.disabled = false;
 }
diff --git a/package-lock.json b/package-lock.json
index 7745dc9..82d89b1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@aegisjsproject/barcodescanner",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@aegisjsproject/barcodescanner",
-      "version": "1.2.2",
+      "version": "1.2.3",
       "funding": [
         {
           "type": "librepay",
@@ -22,12 +22,12 @@
         "@aegisjsproject/dev-server": "^1.0.5",
         "@aegisjsproject/http-utils": "^1.0.4",
         "@rollup/plugin-terser": "^0.4.4",
-        "@shgysk8zer0/eslint-config": "^1.0.4",
+        "@shgysk8zer0/eslint-config": "^1.0.5",
         "@shgysk8zer0/http-server": "^1.1.1",
-        "@shgysk8zer0/importmap": "^1.7.7",
-        "@shgysk8zer0/polyfills": "^0.6.0",
-        "eslint": "^10.0.0",
-        "rollup": "^4.40.1"
+        "@shgysk8zer0/importmap": "^1.7.11",
+        "@shgysk8zer0/polyfills": "^0.6.2",
+        "eslint": "^10.0.2",
+        "rollup": "^4.59.0"
       },
       "engines": {
         "node": ">=18.0.0"
@@ -966,6 +966,7 @@
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
       "dev": true,
+      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -1100,6 +1101,7 @@
       "resolved": "https://registry.npmjs.org/eslint/-/eslint-10.0.2.tgz",
       "integrity": "sha512-uYixubwmqJZH+KLVYIVKY1JQt7tysXhtj21WSvjcSmU5SVNzMus1bgLe+pAt816yQ8opKfheVVoPLqvVMGejYw==",
       "dev": true,
+      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.2",
@@ -1662,6 +1664,7 @@
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.59.0.tgz",
       "integrity": "sha512-2oMpl67a3zCH9H79LeMcbDhXW/UmWG/y2zuqnF2jQq5uq9TbM9TVyXvA4+t+ne2IIkBdrLpAaRQAvo7YI/Yyeg==",
       "dev": true,
+      "peer": true,
       "dependencies": {
         "@types/estree": "1.0.8"
       },
@@ -2389,7 +2392,8 @@
       "version": "8.16.0",
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
-      "dev": true
+      "dev": true,
+      "peer": true
     },
     "acorn-jsx": {
       "version": "5.3.2",
@@ -2484,6 +2488,7 @@
       "resolved": "https://registry.npmjs.org/eslint/-/eslint-10.0.2.tgz",
       "integrity": "sha512-uYixubwmqJZH+KLVYIVKY1JQt7tysXhtj21WSvjcSmU5SVNzMus1bgLe+pAt816yQ8opKfheVVoPLqvVMGejYw==",
       "dev": true,
+      "peer": true,
       "requires": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.2",
@@ -2889,6 +2894,7 @@
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.59.0.tgz",
       "integrity": "sha512-2oMpl67a3zCH9H79LeMcbDhXW/UmWG/y2zuqnF2jQq5uq9TbM9TVyXvA4+t+ne2IIkBdrLpAaRQAvo7YI/Yyeg==",
       "dev": true,
+      "peer": true,
       "requires": {
         "@rollup/rollup-android-arm-eabi": "4.59.0",
         "@rollup/rollup-android-arm64": "4.59.0",
diff --git a/package.json b/package.json
index 4a04714..9fdc6e7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@aegisjsproject/barcodescanner",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "A simple barcode scanner module ",
   "keywords": [
     "barcode",
@@ -78,11 +78,11 @@
     "@aegisjsproject/dev-server": "^1.0.5",
     "@aegisjsproject/http-utils": "^1.0.4",
     "@rollup/plugin-terser": "^0.4.4",
-    "@shgysk8zer0/eslint-config": "^1.0.4",
+    "@shgysk8zer0/eslint-config": "^1.0.5",
     "@shgysk8zer0/http-server": "^1.1.1",
-    "@shgysk8zer0/importmap": "^1.7.7",
-    "@shgysk8zer0/polyfills": "^0.6.0",
-    "eslint": "^10.0.0",
-    "rollup": "^4.40.1"
+    "@shgysk8zer0/importmap": "^1.7.11",
+    "@shgysk8zer0/polyfills": "^0.6.2",
+    "eslint": "^10.0.2",
+    "rollup": "^4.59.0"
   }
 }
diff --git a/scanner.js b/scanner.js
index 574d187..42a9e82 100644
--- a/scanner.js
+++ b/scanner.js
@@ -75,6 +75,8 @@ function _getConstraint(val) {
  * @param {OscillatorType} [options.chimeType="sine"] Shape of the audio for the chime
  * @param {number} [options.chimeVolume=0.2] Chime volume on detect
  * @param {Function} [options.errorHandler=reportError] Callback for handling errors
+ * @param {DocumentOrShadowRoot} [options.base=document] Base to query for video ID if passed a string/id for a `<video>`
+ * @param {DisposableStack|AsyncDisposableStack} [options.stack] Optional stack to handle disposal
  * @param {number} [options.width] Requested camera width
  * @param {number} [options.height] Requested camera height
  * @param {AbortSignal} [options.signal] Abort signal to abort the stream/video
@@ -91,6 +93,8 @@ export async function createBarcodeScanner(callback = console.log, {
 	chimeType = CHIME_TYPE,
 	chimeVolume = CHIME_VOLUME,
 	errorHandler = reportError,
+	base = document,
+	stack,
 	width,
 	height,
 	signal,
@@ -99,7 +103,7 @@ export async function createBarcodeScanner(callback = console.log, {
 
 	if (typeof video === 'string') {
 		return await createBarcodeScanner(callback, {
-			video: document.getElementById(video),
+			video: base.getElementById(video),
 			delay,
 			formats,
 			facingMode,
@@ -109,6 +113,7 @@ export async function createBarcodeScanner(callback = console.log, {
 			chimeType,
 			chimeVolume,
 			errorHandler,
+			stack,
 			width,
 			height,
 			signal,
@@ -117,20 +122,49 @@ export async function createBarcodeScanner(callback = console.log, {
 		reject(new TypeError(`Expected a <video> but got a ${typeof video}.`));
 	} else if (signal instanceof AbortSignal && signal.aborted) {
 		reject(signal.reason);
+	} else if (stack?.disposed) {
+		throw new DOMException('Stack was disposed.', 'AbortError');
 	} else {
 		let frame = NaN;
-		const controller = new AbortController();
-		const loadController = new AbortController();
+
+		/**
+		 * @type {{ adopt: <T>(value: T, onDispose: (val: T) => void) => T, dispose: () => void }}
+		*/
+		const disposableStack = stack instanceof DisposableStack || stack instanceof AsyncDisposableStack
+			? stack.use(new DisposableStack())
+			: new DisposableStack();
+
+		const controller = disposableStack.adopt(
+			new AbortController(),
+			controller => controller.abort(new DOMException('Stack disposed.', 'AbortError'))
+		);
+
+		const loadController = disposableStack.adopt(
+			new AbortController(),
+			controller => controller.abort(new DOMException('Stack disposed.', 'AbortError'))
+		);
+
 		const sig = signal instanceof AbortSignal
 			? AbortSignal.any([signal, controller.signal])
 			: controller.signal;
 
 		const scanner = new BarcodeDetector({ formats });
 		const wakeLock = 'wakeLock' in navigator
-			? await navigator.wakeLock.request('screen').catch(() => undefined)
+			? disposableStack.adopt(
+				await navigator.wakeLock.request('screen').catch(() => undefined),
+				lock => lock?.released || lock?.release()
+			)
 			: undefined;
 
-		const stream = await navigator.mediaDevices.getUserMedia({
+		disposableStack.defer(() => {
+			video.srcObject = null;
+			video.cancelVideoFrameCallback(frame);
+		});
+
+		/**
+		 * @type {MediaStream}
+		 */
+		const stream = disposableStack.adopt(await navigator.mediaDevices.getUserMedia({
 			audio: false,
 			video: {
 				frameRate: _getConstraint(frameRate),
@@ -138,7 +172,7 @@ export async function createBarcodeScanner(callback = console.log, {
 				width: _getConstraint(width),
 				height: _getConstraint(height),
 			},
-		});
+		}), stream => stream.getTracks().forEach(track => track.stop()));
 
 		const [track] = stream.getVideoTracks();
 
@@ -169,7 +203,7 @@ export async function createBarcodeScanner(callback = console.log, {
 			const { width, height } = track.getSettings();
 			target.width = width;
 			target.height = height;
-			resolve({ controller, video, stream, wakeLock, signal: sig });
+			resolve({ controller, video, stream, wakeLock, signal: sig, [Symbol.dispose]: disposableStack[Symbol.dispose].bind(disposableStack), stack: disposableStack });
 			drawFrame();
 			loadController.abort();
 		}, { once: true, signal: sig });
@@ -181,22 +215,13 @@ export async function createBarcodeScanner(callback = console.log, {
 			reject(err);
 		}, { once: true, signal: sig });
 
-		sig.addEventListener('abort', async ({ target }) => {
-			video.cancelVideoFrameCallback(frame);
-			video.pause();
-			video.srcObject = null;
-			stream.getTracks().forEach(track => track.stop());
+		sig?.addEventListener('abort', disposableStack.dispose.bind(disposableStack), { once: true });
 
-			if (typeof wakeLock === 'object') {
-				await wakeLock.release();
-			}
-
-			if (! loadController.signal.aborted) {
-				loadController.abort(target.reason);
-			}
-		}, { once: true });
-
-		video.play();
+		video.play().catch(err => {
+			reject(err);
+			controller.abort(err);
+			disposableStack.dispose();
+		});
 	}
 
 	return promise;