fix: Add more precise types to Cypress.Commands

Author: xumepadismal

cli/types/cypress.d.ts

@@ -7,13 +7,29 @@ declare namespace Cypress {
   type HttpMethod = string
   type RequestBody = string | object
   type ViewportOrientation = 'portrait' | 'landscape'
-  type PrevSubject = 'optional' | 'element' | 'document' | 'window'
+  type PrevSubject = keyof PrevSubjectMap
   type TestingType = 'e2e' | 'component'
   type PluginConfig = (on: PluginEvents, config: PluginConfigOptions) => void | ConfigOptions | Promise<ConfigOptions>
 
+  interface PrevSubjectMap {
+    optional: unknown
+    element: JQuery
+    document: JQuery<HTMLDocument>
+    window: Window
+  }
+
   interface CommandOptions {
     prevSubject: boolean | PrevSubject | PrevSubject[]
   }
+  interface CommandFn<T extends keyof ChainableMethods> {
+    (...args: Parameters<ChainableMethods[T]>): ReturnType<ChainableMethods[T]> | void
+  }
+  interface CommandFnWithSubject<T extends keyof ChainableMethods, S = JQuery> {
+    (prevSubject: S, ...args: Parameters<ChainableMethods[T]>): ReturnType<ChainableMethods[T]> | void
+  }
+  interface CommandFnWithOriginalFn<T extends keyof Chainable> {
+    (originalFn: ChainableMethods[T], ...args: Parameters<ChainableMethods[T]>): ReturnType<ChainableMethods[T]> | void
+  }
   interface ObjectLike {
     [key: string]: any
   }
@@ -420,9 +436,11 @@ declare namespace Cypress {
      * @see https://on.cypress.io/api/commands
      */
     Commands: {
-      add<T extends keyof Chainable>(name: T, fn: Chainable[T]): void
-      add<T extends keyof Chainable>(name: T, options: CommandOptions, fn: Chainable[T]): void
-      overwrite<T extends keyof Chainable>(name: T, fn: Chainable[T]): void
+      add<T extends keyof Chainable>(name: T, fn: CommandFn<T>): void
+      add<T extends keyof Chainable, S extends PrevSubject>(name: T, options: { prevSubject: S | Array<Exclude<S, 'optional'>> }, fn: CommandFnWithSubject<T, PrevSubjectMap[S]>): void
+      add<T extends keyof Chainable, S extends PrevSubject>(name: T, options: { prevSubject: 'optional' | ['optional', ...S[]] }, fn: CommandFnWithSubject<T, PrevSubjectMap[S] | void>): void
+      add<T extends keyof Chainable, S>(name: T, options: CommandOptions, fn: CommandFnWithSubject<T, S>): void
+      overwrite<T extends keyof Chainable>(name: T, fn: CommandFnWithOriginalFn<T>): void
     }
 
     /**
@@ -2255,6 +2273,12 @@ declare namespace Cypress {
     $$<TElement extends Element = HTMLElement>(selector: JQuery.Selector, context?: Element | Document | JQuery): JQuery<TElement>
   }
 
+  type ChainableMethods<Subject = any> = {
+    [P in keyof Chainable<Subject>]: Chainable<Subject>[P] extends ((...args: any[]) => any)
+        ? Chainable<Subject>[P]
+        : never
+  }
+
   interface SinonSpyAgent<A extends sinon.SinonSpy> {
     log(shouldOutput?: boolean): Omit<A, 'withArgs'> & Agent<A>
 

cli/types/tests/cypress-tests.ts

@@ -74,20 +74,53 @@ namespace CypressCommandsTests {
     arg
     return
   })
-  Cypress.Commands.add('newCommand', { prevSubject: true }, (arg) => {
+  Cypress.Commands.add('newCommand', (arg) => {
     // $ExpectType string
     arg
+  })
+  Cypress.Commands.add('newCommand', { prevSubject: true }, (subject, arg) => {
+    subject // $ExpectType unknown
+    arg // $ExpectType string
+    return
+  })
+  Cypress.Commands.add('newCommand', { prevSubject: 'optional' }, (subject, arg) => {
+    subject // $ExpectType unknown
+    arg // $ExpectType string
     return
   })
+  Cypress.Commands.add('newCommand', { prevSubject: 'optional' }, (subject, arg) => {
+    subject // $ExpectType unknown
+    arg // $ExpectType string
+  })
+  Cypress.Commands.add('newCommand', { prevSubject: 'document' }, (subject, arg) => {
+    subject // $ExpectType JQuery<HTMLDocument>
+    arg // $ExpectType string
+  })
+  Cypress.Commands.add('newCommand', { prevSubject: 'window' }, (subject, arg) => {
+    subject // $ExpectType Window
+    arg // $ExpectType string
+  })
+  Cypress.Commands.add('newCommand', { prevSubject: 'element' }, (subject, arg) => {
+    subject // $ExpectType JQuery<HTMLElement>
+    arg // $ExpectType string
+  })
+  Cypress.Commands.add('newCommand', { prevSubject: ['element', 'document', 'window'] }, (subject, arg) => {
+    subject // $ExpectType Window | JQuery<HTMLElement> | JQuery<HTMLDocument>
+    arg // $ExpectType string
+  })
+  Cypress.Commands.add('newCommand', { prevSubject: ['optional', 'window', 'document', 'element'] }, (subject, arg) => {
+    subject // $ExpectType void | Window | JQuery<HTMLElement> | JQuery<HTMLDocument>
+    arg // $ExpectType string
+  })
   Cypress.Commands.add('newCommand', (arg) => {
     // $ExpectType string
     arg
     return new Promise((resolve) => {})
   })
-  Cypress.Commands.overwrite('newCommand', (arg) => {
-    // $ExpectType string
-    arg
-    return
+  Cypress.Commands.overwrite('newCommand', (originalFn, arg) => {
+    arg // $ExpectType string
+    originalFn // $ExpectedType Chainable['newCommand']
+    originalFn(arg) // $ExpectType void
   })
 }