How to describe the interface of a simple Just fun

Question

I'm trying to write a simple interface in typescript for the first time and having doubts about pretty much everything.

The question is simple. How to describe this simple jest matcher extension?

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

expect.extend({
  /** Compare the two values inside two functors with Object.is
   * @method
   * @augments 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}`
      }
    }
  }
})

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

I have tried this but not sure about the generic types at all:

import { Matchers } from 'jest'

interface Functor<T> {
  (value?: any): {
    fmap: (f: value) => Functor<T>
  }
}

interface Matchers<R> {
  functorToBe(actual: Functor<T>, expected:  Functor<T>): R
}

Ref: JSDoc document object method extending other class

The gist of the jest type definition for Matchers<R>:

/**
 * The `expect` function is used every time you want to test a value.
 * You will rarely call `expect` by itself.
 */
interface Expect {
    /**
     * The `expect` function is used every time you want to test a value.
     * You will rarely call `expect` by itself.
     *
     * @param actual The value to apply matchers against.
     */
    <T = any>(actual: T): Matchers<T>;
    /**
     * You can use `expect.extend` to add your own matchers to Jest.
     */
    extend(obj: ExpectExtendMap): void;
    // etc.
}

Well, this is confusing. The only index.d.ts in the jest repo is https://github.com/facebook/jest/blob/master/packages/jest-editor-support/index.d.ts but that is not the one I get in vscode, which is https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/jest/index.d.ts#L471.

Answer 1

The extension

Your merge of Matchers is almost right, but from looking at the jest types on Definitely Typed [1], I can see that Matchers is nested inside a jest namespace. The part of the Typescript handbook that covers this is namespace merging.

namespace jest {
    export interface Matchers<R> {
        functorToBe<T>(actual: Functor<T>, expected:  Functor<T>): R;
    }
}

When I tested this, I needed a tsconfig.json to get my JS files to see the declaration:

{
    "compilerOptions": {
        "allowJs": true,
        "checkJs": true,
    },
    "include": [
        "test.js",
        "extensions.ts",
    ]
}

A jsconfig.json is almost the same thing, but doesn't require you to add "allowJs": true explicitly. But note that adding a tsconfig or jsconfig will turn off automatic downloads of types from Definitely Typed, and you'll have to manually npm install @types/jest (plus any other types for libraries you use). If you don't want to add a tsconfig, I was able to manually add a reference in the JS file as the first line:

/// <reference path="./extensions.ts" />

The type of the new method

It should be something like:

functorToBe(expected: R): R;

Here is where things get confusing to me. Let me know if you have questions about this part of the problem and I will try to help.