fix: checkContext better error message

fratzinger · fratzinger · commit 318f34571260 · 2026-03-11T15:06:38.000+01:00
diff --git a/docs/migrating-from-feathers-hooks-common.md b/docs/migrating-from-feathers-hooks-common.md
@@ -46,6 +46,46 @@ The old `cache` hook only worked for `get` requests and did not work with varyin
 
 The new `cache` hook caches `get` and `find` requests and considers the `params` object when caching. This means that if you call the same `get` or `find` request with different `params`, it will cache each unique request separately.
 
+## `checkContext`
+
+The `checkContext` utility has been updated with an options object syntax and now supports **TypeScript type narrowing**. After calling `checkContext`, the compiler automatically narrows `context.type`, `context.method`, and `context.path` based on the options you pass.
+
+The old positional arguments still work but the options object is recommended:
+
+```ts
+// old
+import { checkContext } from "feathers-hooks-common";
+
+checkContext(context, "before", ["create", "patch"], "myHook");
+
+// new (recommended: options object with type narrowing)
+import { checkContext } from "feathers-utils/utils";
+
+checkContext(context, {
+  type: "before",
+  method: ["create", "patch"],
+  label: "myHook",
+});
+
+// After checkContext, TypeScript narrows the types:
+context.type; // 'before'
+context.method; // 'create' | 'patch'
+```
+
+You can also narrow by `path`, which was not available in the old API:
+
+```ts
+checkContext(context, {
+  type: ["before", "around"],
+  method: ["create", "patch"],
+  path: "users",
+});
+
+context.type; // 'before' | 'around'
+context.method; // 'create' | 'patch'
+context.path; // 'users'
+```
+
 ## `callingParams`
 
 The `callingParams` utility was removed. If you need it please reach out to us in this [github issue](https://github.com/feathersjs/feathers-utils/issues/1).
diff --git a/src/utils/check-context/check-context.util.test.ts b/src/utils/check-context/check-context.util.test.ts
@@ -164,13 +164,29 @@ describe('util checkContext', () => {
           type: 'before',
           label: 'myHook',
         }),
-      ).toThrow("The 'myHook' hook has invalid context.")
+      ).toThrow(
+        "The 'myHook' hook has invalid context (type: expected 'before' but got 'after').",
+      )
     })
 
     it('uses default label when not provided', () => {
       expect(() =>
         checkContext(make('after', 'create'), { type: 'before' }),
-      ).toThrow("The 'anonymous' hook has invalid context.")
+      ).toThrow(
+        "The 'anonymous' hook has invalid context (type: expected 'before' but got 'after').",
+      )
+    })
+
+    it('shows multiple mismatches in error message', () => {
+      expect(() =>
+        checkContext(make('after', 'patch'), {
+          type: ['before', 'around'],
+          method: 'create',
+          label: 'myHook',
+        }),
+      ).toThrow(
+        "The 'myHook' hook has invalid context (type: expected 'before' | 'around' but got 'after', method: expected 'create' but got 'patch').",
+      )
     })
   })
 })
diff --git a/src/utils/check-context/check-context.util.ts b/src/utils/check-context/check-context.util.ts
@@ -92,6 +92,26 @@ export function checkContext<H extends HookContext = HookContext>(
   }
 
   if (!isContext(options)(context)) {
-    throw new Error(`The '${hookLabel}' hook has invalid context.`)
+    const details: string[] = []
+
+    if (options.type != null) {
+      details.push(
+        `type: expected '${Array.isArray(options.type) ? options.type.join("' | '") : options.type}' but got '${context.type}'`,
+      )
+    }
+    if (options.method != null) {
+      details.push(
+        `method: expected '${Array.isArray(options.method) ? options.method.join("' | '") : options.method}' but got '${context.method}'`,
+      )
+    }
+    if (options.path != null) {
+      details.push(
+        `path: expected '${Array.isArray(options.path) ? options.path.join("' | '") : options.path}' but got '${context.path}'`,
+      )
+    }
+
+    throw new Error(
+      `The '${hookLabel}' hook has invalid context (${details.join(', ')}).`,
+    )
   }
 }
