Merge pull request #9 from polarsignals/better_error

Improve error message when ACF unavailable

Author: umanwizard

js/index.js

@@ -11,27 +11,29 @@ if (process.platform == 'linux') {
     const { AsyncLocalStorage } = require('node:async_hooks');
     let als = undefined;
 
-    function hasAsyncContextFrame() {
+    function asyncContextFrameError() {
         const [major] = process.versions.node.split('.').map(Number);
 
         // If explicitly disabled, it's not in use.
-        if (process.execArgv.includes('--no-async-context-frame')) return false;
+        if (process.execArgv.includes('--no-async-context-frame')) return "Node explicitly launched with --no-async-context-frame";
 
         // Since Node 24, AsyncContextFrame is the default unless disabled.
-        if (major >= 24) return true;
+        if (major >= 24) return undefined;
 
         // In Node 22/23, it existed behind an experimental flag.
-        if (process.execArgv.includes('--experimental-async-context-frame')) return true;
+        if (process.execArgv.includes('--experimental-async-context-frame')) return undefined;
+        if (major >= 22) return "Node versions prior to v24 must be launched with --experimental-async-context-frame";
 
         // Older versions: not available.
-        return false;
+        return "Node major versions prior to v22 do not support the feature at all";
     }
 
     function ensureHook() {
         if (als)
             return;
-        if (!hasAsyncContextFrame()) {
-            throw new Error("This library can only run with async context frame support enabled");
+        const err = asyncContextFrameError();
+        if (err) {
+            throw new Error(`Custom labels requires async_context_frame support, which is unavailable: ${err}.`);
         }
         als = new AsyncLocalStorage();
         addon.storeHash(als);