try to simplify esmock.d.ts types file

[iambumblehead]

esmock.d.ts basically repeats the same definitions many times, because esmock's main function signature is exported in ways that are foreign to typescript. The various main esmock calls are shown below and they all have the same signature,

import esmock, { strict } from 'esmock'

const moduleId = './example.js';
const parent = import.meta.url
const mocks = {}
const globalmocks = {}
const opts = {}

esmock(moduleId, mocks, globalmocks, opts)
esmock(moduleId, parent, mocks, globalmocks, opts)
esmock.p(moduleId, mocks, globalmocks, opts) // persist cache
esmock.p(moduleId, parent, mocks, globalmocks, opts)
strict(moduleId, mocks, globalmocks, opts)
strict(moduleId, parent, mocks, globalmocks, opts)
strict.p(moduleId, mocks, globalmocks, opts) // persist cache
strict.p(moduleId, parent, mocks, globalmocks, opts)
esmock.strict(moduleId, mocks, globalmocks, opts)
esmock.strict(moduleId, parent, mocks, globalmocks, opts)
esmock.strict.p(moduleId, mocks, globalmocks, opts) // persist cache
esmock.strict.p(moduleId, parent, mocks, globalmocks, opts)

Searching for a way to re-use one documentation block and/or one esmock function signature, these attempts failed...

• attempted to use the inheritdoc tag, but vscode did not show documentation for functions using inheritdoc,
• attempted to define esmock function "types", then define those inside an esmock interface (rather than namespace) this didn't work and anyway was unable to export esmock as a "union" of esmock function and esmock interface

[iambumblehead]

@jsejcksn feel free to ignore me, but would give your experienced opinion on this types file? I experimented with some things from your answer here https://stackoverflow.com/questions/70629311/export-same-function-with-different-names-and-types but did not succeed and that's how I found you :)

[iambumblehead]

let's merge this... this esmock.d.ts file smaller and results seem acceptable in vscode

[jsejcksn]

@iambumblehead Hello. I'm just seeing this.

Would you give your opinion?
I experimented with some things ... but did not succeed

I'm not familiar with your codebase (and it looks like you might have already resolved whatever issue you encountered since this was merged), but do you have a specific question at this point?

[iambumblehead]

@jsejcksn thank you for your response. I don't understand typescript well but believed there might be a more compact way to format this types file, so I messaged you to ask for your general advice --is there a better way to write this types file?

You might, I thought, recommend a way to reuse function declarations or documentation tags here, but it seems typescript does not support these features, and the same declarations and tags are currently typed out for each function.

[jsejcksn]

@iambumblehead You seem to be asking about JSDoc, which is an entirely separate specification from TypeScript. However, TypeScript does support a subset of JSDoc's syntax.

Again, I haven't reviewed your codebase, but perhaps you're looking for something like this?

TS Playground

type MockMap = { [specifier: string]: any };

type Options = {
  strict?: boolean | undefined;
  purge?: boolean | undefined;
  isModuleNotFoundError?: boolean | undefined;
};

/**
 * Mocks imports for the module specified by {@link modulePath}.
 *
 * @param modulePath The module whose imports will be mocked.
 *
 * @param parent A URL used to resolve relative specifiers, typically
 * `import.meta.url`. If not specified, inferred via the stack. Useful with
 * source maps.
 *
 * @param defs A mapping of import specifiers to mock definitions.
 *
 * @param gdefs A globally applied mapping of import specifiers to mock
 * definitions.
 *
 * @param opts
 *
 * @returns The result of importing {@link modulePath}, similar to
 * `import(modulePath)`.
 */
type MockFunction = {
  (
    modulePath: string,
    parent: string,
    defs?: MockMap,
    gdefs?: MockMap,
    opts?: Options,
  ): any;
  (
    modulePath: string,
    defs?: MockMap,
    gdefs?: MockMap,
    opts?: Options,
  ): any;
};

/**
 * By default, mock definitions are merged with the original module definitions.
 * To avoid the default behaviour, use esmock.strict.
 */
declare const esmock: MockFunction & {
  /**
   * Uses caching to support `await import()` inside the mocked import tree.
   *
   * After using this function, consider calling {@link esmock.purge}
   * to free memory.
   */
  p: MockFunction;

  /**
   * Removes caching created by {@link esmock.p}.
   *
   * @param mockModule A module object returned from {@link esmock.p}.
   */
  purge: (mockModule: any) => void;

  /**
   * The "strict" variant replaces original module definitions
   * with mock definitions.
   */
  strict: MockFunction & {
    p: MockFunction;
  };
};

/**
 * The "strict" variant replaces original module definitions
 * with mock definitions.
 */
declare const strict: typeof esmock['strict'];

export {
  esmock as default,
  strict,
  type MockFunction,
  type MockMap,
  type Options,
};

[iambumblehead]

@jsejcksn wow your version looks amazing

All tests pass and here are screenshots from vscode

I'm not sure how to make the param docs appear in vscode, such as @param gdefs A globally applied mapping of import specifiers to mock but probably I am just unfamiliar with typescript.

The smaller adjustments and edits you made are also great. Thank you.

If you would make a PR I would be glad to merge it :)

[jsejcksn]

I'm not sure how to make the param docs appear in vscode

@iambumblehead I'm not positive either and would need to experiment more: IntelliSense is what provides those quick info suggestions: that's also discrete from the TypeScript compiler.

You might check out the JSDoc @see directive (JSDoc, TS).

If you would make a PR I would be glad to merge it :)

PR created: #164