microsoft / microsoft/TypeScript

JSDoc @augments doesn’t allow function calls to augment existing types

Open
#26,675 7 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Domain: JavaScript Domain: JSDoc Experience Enhancement Suggestion
Dominant language
Go
Stars
111k
Forks
14.3k
Avg merge
2d 4h
Merged PRs (30d)
132

Description

I wrote a simple extension of jest.Matchers but I can not get the typescript type checker to recognize my extension.

TypeScript Version: 3.0.1 (and 3.1.0-dev.20180825)
The description below is for 3.0.1 - for 3.1.0-dev.20180825 all jest functions show errors, so I don't even think that the parser gets to my type at all.

[ts] Cannot find name 'describe'.
[ts] Cannot find name 'test'.
[ts] Cannot find name 'expect

Used via vscode version: 1.26.1

Search Terms:
is:issue is:open jsdoc extends
is:issue is:open jsdoc @augments
is:issue is:open jsdoc "@augments"

I first asked this as a question on StackOverflow but after waiting a few days, I now suspect it is a bug in typescript's JSDoc implementation.

I also read the FAQ and found the link to jest but didn't find any information there either.

I'm using plain JavaScript and the code runs perfectly.

Code

// @ts-check

const getFunctorValue = F => {
  let x
  F.fmap(v => x = v)
  return x
}


expect.extend({
  /**
  * @extends jest.Matchers
  * @param {*} actual The functor you want to test.
  * @param {*} expected The functor you expect.
  */
  functorToBe(actual, expected) {
    const actualValue = getFunctorValue(actual)
    const expectedValue = getFunctorValue(expected)
    const pass = Object.is(actualValue, expectedValue)
    return {
      pass,
      message () {
        return `expected ${actualValue} of ${actual} to ${pass ? '' : 'not'} be ${expectedValue} of ${expected}`
      }
    }
  }
})

/**
* @param {*} v Any value
*/
function just (v) {
  return {
    fmap: f => just(f(v))
  }
}

describe('Functor Law', () => {
  test('equational reasoning (identity)', () => {
    expect(just(1)).functorToBe(just(1))
  })
})

Expected behavior:
expect().functorToBe should be recognized as a function.

Actual behavior:
But in the line with expect(just(1)).functorToBe(just(1)),
I get a red underline under functorToBe and the following error message:

[ts] Property 'functorToBe' does not exist on type 'Matchers<{ [x: string]: any; fmap: (f: any) => any; }>'.
any

I got jest.Matchers from writing expect() in vscode and looked at the description.

image of vscode intellisense displaying jest.Matchers as return type for expect()

Playground Link:

Related Issues:
No.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the supplied plain JavaScript example with TypeScript 3.0.1 or typescript@next, focusing on the JSDoc @extends/@augments handling around jest.Matchers. Done means expect(just(1)).functorToBe(just(1)) type-checks without the missing-property error and the Jest functions are recognized.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
compilers
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.