From b083b23ab0c7655b9fa251b058951c0741d8a4b3 Mon Sep 17 00:00:00 2001
From: David <dwc5496@gmail.com>
Date: Mon, 28 Sep 2026 21:19:31 +0000
Subject: [PATCH] capability: on() without a function says what it got and what
 to pass

The message read "the handler of TurnOn is a function", which states the
opposite of what went wrong. It is now
  on("TurnOff") got undefined as the handler: pass a function that takes
  the context of the directive
under the endpoint and the interface, as every DeclarationError.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 dist/cjs/device/Capability.js  | 5 +++--
 dist/esm/device/Capability.js  | 5 +++--
 src/device/Capability.ts       | 4 +++-
 test/dispatch/dispatch.test.js | 2 ++
 4 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/dist/cjs/device/Capability.js b/dist/cjs/device/Capability.js
index bcedbca..923f645 100644
--- a/dist/cjs/device/Capability.js
+++ b/dist/cjs/device/Capability.js
@@ -36,8 +36,9 @@ class Capability {
         if (name !== "*" && this.descriptor.tier !== 3 && !names.includes(name)) {
             throw new types_js_1.DeclarationError(this, `${name} is not a directive of the interface, which has ${names.join(", ") || "none"}`);
         }
-        if (typeof handler !== "function")
-            throw new types_js_1.DeclarationError(this, `the handler of ${name} is a function`);
+        if (typeof handler !== "function") {
+            throw new types_js_1.DeclarationError(this, `on("${name}") got ${handler === null ? "null" : typeof handler} as the handler: pass a function that takes the context of the directive`);
+        }
         this.handlers.set(name, handler);
         return this;
     }
diff --git a/dist/esm/device/Capability.js b/dist/esm/device/Capability.js
index 8eb316b..ecbb7a3 100644
--- a/dist/esm/device/Capability.js
+++ b/dist/esm/device/Capability.js
@@ -33,8 +33,9 @@ export class Capability {
         if (name !== "*" && this.descriptor.tier !== 3 && !names.includes(name)) {
             throw new DeclarationError(this, `${name} is not a directive of the interface, which has ${names.join(", ") || "none"}`);
         }
-        if (typeof handler !== "function")
-            throw new DeclarationError(this, `the handler of ${name} is a function`);
+        if (typeof handler !== "function") {
+            throw new DeclarationError(this, `on("${name}") got ${handler === null ? "null" : typeof handler} as the handler: pass a function that takes the context of the directive`);
+        }
         this.handlers.set(name, handler);
         return this;
     }
diff --git a/src/device/Capability.ts b/src/device/Capability.ts
index ceca181..c4c427b 100644
--- a/src/device/Capability.ts
+++ b/src/device/Capability.ts
@@ -101,7 +101,9 @@ export class Capability<P extends Properties = Properties, D extends Directives
     if (name !== "*" && this.descriptor.tier !== 3 && !names.includes(name)) {
       throw new DeclarationError(this, `${name} is not a directive of the interface, which has ${names.join(", ") || "none"}`);
     }
-    if (typeof handler !== "function") throw new DeclarationError(this, `the handler of ${name} is a function`);
+    if (typeof handler !== "function") {
+      throw new DeclarationError(this, `on("${name}") got ${handler === null ? "null" : typeof handler} as the handler: pass a function that takes the context of the directive`);
+    }
     this.handlers.set(name, handler);
     return this;
   }
diff --git a/test/dispatch/dispatch.test.js b/test/dispatch/dispatch.test.js
index afa1327..41246c3 100644
--- a/test/dispatch/dispatch.test.js
+++ b/test/dispatch/dispatch.test.js
@@ -139,6 +139,8 @@ test("on(): \"*\" and onDirective() take what has no handler of its own; a name
   assert.deepEqual(called, ["TurnOn TurnOn", "* TurnOff", "device SetBrightness"]);
   assert.throws(() => power.on("Toggle", by("Toggle")), (err) => err instanceof DeclarationError
     && err.message === "lamp-1: Alexa.PowerController: Toggle is not a directive of the interface, which has TurnOn, TurnOff");
+  assert.throws(() => power.on("TurnOff"), (err) => err instanceof DeclarationError
+    && err.message === "lamp-1: Alexa.PowerController: on(\"TurnOff\") got undefined as the handler: pass a function that takes the context of the directive");
 });
 
 test("a handler that throws or rejects answers INTERNAL_ERROR, the bridge reports what it threw, and nothing is left unhandled", async () => {