feat: checkContext type narrowing

Author: fratzinger

.claude/settings.json

@@ -6,7 +6,8 @@
       "Bash(npx vitest typecheck *)",
       "Bash(npx vitepress *)",
       "Bash(npx prettier *)",
-      "Bash(pnpm test)"
+      "Bash(pnpm test)",
+      "Bash(npx eslint *)"
     ]
   }
 }

src/internal.utils.ts

@@ -8,6 +8,7 @@ export const hasOwnProperty = (
 }
 
 export type MaybeArray<T> = T | readonly T[]
+export type UnpackMaybeArray<T> = T extends readonly (infer E)[] ? E : T
 export const toArray = <T>(value: T | readonly T[]): T[] =>
   Array.isArray(value) ? [...value] : [value as T]
 

src/utils/check-context/check-context.util.test-d.ts

@@ -22,51 +22,108 @@ type App = typeof app
 type AppCtx = HookContext<App>
 type UserCtx = HookContext<App, MemoryService<User>>
 
-const context = {} as UserCtx
-const appContext = {} as AppCtx
-
 it('options overload accepts valid options', () => {
-  checkContext(context, { type: 'before' })
-  checkContext(context, { method: 'create' })
-  checkContext(context, {
+  const ctx1 = {} as UserCtx
+  checkContext(ctx1, { type: 'before' })
+  const ctx2 = {} as UserCtx
+  checkContext(ctx2, { method: 'create' })
+  const ctx3 = {} as UserCtx
+  checkContext(ctx3, {
     type: ['before', 'around'],
     method: ['create', 'patch'],
   })
-  checkContext(context, { type: 'before', label: 'myHook' })
-  checkContext(context, { path: 'users' })
+  const ctx4 = {} as UserCtx
+  checkContext(ctx4, { type: 'before', label: 'myHook' })
+  const ctx5 = {} as UserCtx
+  checkContext(ctx5, { path: 'users' })
 })
 
 it('options overload rejects invalid type', () => {
+  const ctx = {} as UserCtx
   // @ts-expect-error "invalid" is not a valid HookType
-  checkContext(context, { type: 'invalid' })
+  checkContext(ctx, { type: 'invalid' })
 })
 
 it('options overload accepts valid path for app-level context', () => {
-  checkContext(appContext, { path: 'users' })
-  checkContext(appContext, { path: 'messages' })
-  checkContext(appContext, { path: ['users', 'messages'] })
+  const ctx1 = {} as AppCtx
+  checkContext(ctx1, { path: 'users' })
+  const ctx2 = {} as AppCtx
+  checkContext(ctx2, { path: 'messages' })
+  const ctx3 = {} as AppCtx
+  checkContext(ctx3, { path: ['users', 'messages'] })
 })
 
 it('options overload rejects invalid path for service-specific context', () => {
+  const ctx = {} as UserCtx
   // @ts-expect-error "messages" is not valid when context is narrowed to MemoryService<User>
-  checkContext(context, { path: 'messages' })
+  checkContext(ctx, { path: 'messages' })
 })
 
 it('options overload rejects invalid path for app-level context', () => {
+  const ctx = {} as AppCtx
   // @ts-expect-error "nonExistent" is not a valid service path
-  checkContext(appContext, { path: 'nonExistent' })
+  checkContext(ctx, { path: 'nonExistent' })
 })
 
 it('positional overload accepts valid args', () => {
-  checkContext(context, 'before')
-  checkContext(context, ['before', 'after'])
-  checkContext(context, 'before', 'create')
-  checkContext(context, ['before', 'around'], ['create', 'patch'], 'myHook')
-  checkContext(context, null, 'create')
-  checkContext(context, undefined, 'create')
+  const ctx1 = {} as UserCtx
+  checkContext(ctx1, 'before')
+  const ctx2 = {} as UserCtx
+  checkContext(ctx2, ['before', 'after'])
+  const ctx3 = {} as UserCtx
+  checkContext(ctx3, 'before', 'create')
+  const ctx4 = {} as UserCtx
+  checkContext(ctx4, ['before', 'around'], ['create', 'patch'], 'myHook')
+  const ctx5 = {} as UserCtx
+  checkContext(ctx5, null, 'create')
+  const ctx6 = {} as UserCtx
+  checkContext(ctx6, undefined, 'create')
 })
 
 it('positional overload rejects invalid type', () => {
   // @ts-expect-error "invalid" is not a valid HookType
   checkContext(context, 'invalid')
 })
+
+it('narrows path with options overload', () => {
+  const ctx = {} as AppCtx
+  checkContext(ctx, { path: ['users', 'messages'] })
+  expectTypeOf(ctx.path).toEqualTypeOf<'users' | 'messages'>()
+})
+
+it('narrows path with single value', () => {
+  const ctx = {} as AppCtx
+  checkContext(ctx, { path: 'users' })
+  expectTypeOf(ctx.path).toEqualTypeOf<'users'>()
+})
+
+it('narrows type with options overload', () => {
+  const ctx = {} as AppCtx
+  checkContext(ctx, { type: ['before', 'around'] })
+  expectTypeOf(ctx.type).toEqualTypeOf<'before' | 'around'>()
+})
+
+it('narrows method with options overload', () => {
+  const ctx = {} as AppCtx
+  checkContext(ctx, { method: ['create', 'patch'] })
+  expectTypeOf(ctx.method).toEqualTypeOf<'create' | 'patch'>()
+})
+
+it('narrows type with positional overload', () => {
+  const ctx = {} as AppCtx
+  checkContext(ctx, 'before')
+  expectTypeOf(ctx.type).toEqualTypeOf<'before'>()
+})
+
+it('narrows type and method with positional overload', () => {
+  const ctx = {} as AppCtx
+  checkContext(ctx, ['before', 'around'], ['create', 'patch'])
+  expectTypeOf(ctx.type).toEqualTypeOf<'before' | 'around'>()
+  expectTypeOf(ctx.method).toEqualTypeOf<'create' | 'patch'>()
+})
+
+it('does not narrow when null is passed in positional overload', () => {
+  const ctx = {} as AppCtx
+  checkContext(ctx, null, 'create')
+  expectTypeOf(ctx.method).toEqualTypeOf<'create'>()
+})

src/utils/check-context/check-context.util.ts

@@ -4,6 +4,24 @@ import {
   isContext,
   type IsContextOptions,
 } from '../../predicates/is-context/is-context.predicate.js'
+import type { UnpackMaybeArray } from '../../internal.utils.js'
+
+type NarrowedContext<H extends HookContext, O> = H &
+  (O extends { path: infer P }
+    ? [P] extends [undefined | null]
+      ? unknown
+      : { path: UnpackMaybeArray<P> }
+    : unknown) &
+  (O extends { type: infer T }
+    ? [T] extends [undefined | null]
+      ? unknown
+      : { type: UnpackMaybeArray<T> }
+    : unknown) &
+  (O extends { method: infer M }
+    ? [M] extends [undefined | null]
+      ? unknown
+      : { method: UnpackMaybeArray<M> }
+    : unknown)
 
 export type CheckContextOptions<H extends HookContext = HookContext> =
   IsContextOptions<H> & {
@@ -14,6 +32,7 @@ export type CheckContextOptions<H extends HookContext = HookContext> =
  * Validates that the hook context matches the expected type(s) and method(s).
  * Throws an error if the context is invalid, preventing hooks from running in
  * unsupported configurations. Typically used internally by other hooks.
+ * Also narrows the context type based on the passed options.
  *
  * @example
  * ```ts
@@ -23,22 +42,26 @@ export type CheckContextOptions<H extends HookContext = HookContext> =
  *   checkContext(context, ['before', 'around'], ['create', 'patch'], 'myHook')
  *   // or with options object:
  *   checkContext(context, { type: ['before', 'around'], method: ['create', 'patch'], label: 'myHook' })
- *   // ... hook logic
+ *   // context.type is now 'before' | 'around', context.method is now 'create' | 'patch'
  * }
  * ```
  *
  * @see https://utils.feathersjs.com/utils/check-context.html
  */
-export function checkContext<H extends HookContext = HookContext>(
+export function checkContext<
+  H extends HookContext,
+  const O extends CheckContextOptions<NoInfer<H>>,
+>(context: H, options: O): asserts context is NarrowedContext<H, O>
+export function checkContext<
+  H extends HookContext,
+  const T extends HookType | HookType[] | null | undefined = undefined,
+  const M extends MethodName | MethodName[] | null | undefined = undefined,
+>(
   context: H,
-  options: CheckContextOptions<NoInfer<H>>,
-): void
-export function checkContext<H extends HookContext = HookContext>(
-  context: H,
-  type?: HookType | HookType[] | null,
-  methods?: MethodName | MethodName[] | null,
+  type?: T,
+  methods?: M,
   label?: string,
-): void
+): asserts context is NarrowedContext<H, { type: T; method: M }>
 export function checkContext<H extends HookContext = HookContext>(
   context: H,
   typeOrOptions?: