{"id":15659930,"url":"https://github.com/xunnamius/babel-plugin-explicit-exports-references","last_synced_at":"2025-09-26T02:31:29.281Z","repository":{"id":42572414,"uuid":"358261300","full_name":"Xunnamius/babel-plugin-explicit-exports-references","owner":"Xunnamius","description":"⚡ Transforms all internal references to a module's exports such that each reference starts with \"module.exports\" instead of directly referencing an internal name.","archived":false,"fork":false,"pushed_at":"2024-07-15T16:16:17.000Z","size":998,"stargazers_count":20,"open_issues_count":7,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-09T14:33:41.571Z","etag":null,"topics":["babel","default","each","explicit","export","exports","function","jest","mock","module","other","refer","reference","references","same","test"],"latest_commit_sha":null,"homepage":"https://npm.im/babel-plugin-explicit-exports-references","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Xunnamius.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-15T13:02:32.000Z","updated_at":"2024-09-18T11:08:49.000Z","dependencies_parsed_at":"2024-06-18T20:07:09.310Z","dependency_job_id":"d0a512cf-e0fa-4db5-99ab-daaa9db72dea","html_url":"https://github.com/Xunnamius/babel-plugin-explicit-exports-references","commit_stats":{"total_commits":28,"total_committers":1,"mean_commits":28.0,"dds":0.0,"last_synced_commit":"4ee7a46f6998c7a36f1bc30e91f263b2e878fd6a"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xunnamius%2Fbabel-plugin-explicit-exports-references","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xunnamius%2Fbabel-plugin-explicit-exports-references/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xunnamius%2Fbabel-plugin-explicit-exports-references/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xunnamius%2Fbabel-plugin-explicit-exports-references/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Xunnamius","download_url":"https://codeload.github.com/Xunnamius/babel-plugin-explicit-exports-references/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234286149,"owners_count":18808432,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babel","default","each","explicit","export","exports","function","jest","mock","module","other","refer","reference","references","same","test"],"created_at":"2024-10-03T13:19:36.275Z","updated_at":"2025-09-26T02:31:28.961Z","avatar_url":"https://github.com/Xunnamius.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- prettier-ignore-start --\u003e\n\n\u003c!-- badges-start --\u003e\n\n[![Black Lives Matter!][badge-blm]][link-blm]\n[![Maintenance status][badge-maintenance]][link-repo]\n[![Last commit timestamp][badge-last-commit]][link-repo]\n[![Open issues][badge-issues]][link-issues]\n[![Pull requests][badge-pulls]][link-pulls]\n[![codecov][badge-codecov]][link-codecov]\n[![Source license][badge-license]][link-license]\n[![NPM version][badge-npm]][link-npm]\n[![semantic-release][badge-semantic-release]][link-semantic-release]\n\n\u003c!-- badges-end --\u003e\n\n\u003c!-- prettier-ignore-end --\u003e\n\n# babel-plugin-explicit-exports-references\n\nTransforms all internal references to a module's exports such that each\nreference starts with `module.exports` instead of directly referencing an\ninternal name. This enables easy mocking of specific (exported) functions in\nJest with Babel/TypeScript, even when the mocked functions call each other in\nthe same module.\n\n## Installation and Usage\n\n```Bash\nnpm install --save-dev babel-plugin-explicit-exports-references\n```\n\nAnd in your `babel.config.js`:\n\n```typescript\nmodule.exports = {\n  plugins: ['explicit-exports-references']\n};\n```\n\n**Note**: it is recommended that this plugin only be enabled when `NODE_ENV` is\n`test`. Using this plugin elsewhere, such as in production, can lead to\nincreased build size. For example:\n\n```javascript\nmodule.exports = {\n  parserOpts: { ... },\n  plugins: [ ... ],\n  env: {\n      test: {\n        plugins: ['explicit-exports-references']\n      }\n  }\n};\n```\n\nFinally, run Babel through your toolchain (Webpack, Jest, etc) or manually:\n\n```bash\nnpx babel src --out-dir dist\n```\n\n## AST Algorithm\n\n\u003e To see detailed output on how this plugin transforms your code, enable [debug\n\u003e mode][2]:\n\u003e `DEBUG='babel-plugin-explicit-exports-references:*' npx jest your-test-file`\n\nThe plugin begins by looking for default and named export declarations in a\nprogram.\n\nFor default exports, it looks for function declarations and class declarations\nthat have ids (i.e. variable names), like `export default function main() {}`,\nand updates any Identifiers referencing that id.\n\nFor named exports, it looks for function and class declarations too, but also\nvariable declarations like `export const foo = 5;` and\n`export { x as default, y, x as z };`. **Enums are explicitly ignored.** Any\nIdentifiers that reference the declaration's id or specifier are updated.\n\nWhen updating references, by default only Identifiers are transformed.\nAssignment Expressions can also be transformed, but doing so is [currently\nunstable][1]. All other reference types are ignored, including TypeScript types\nand Identifiers within their own declarations.\n\nThe following enables transforming Assignment Expressions along with\nIdentifiers:\n\n\u003c!-- prettier-ignore-start --\u003e\n```javascript\nmodule.exports = {\n  plugins: [\n    ['explicit-exports-references', { transformAssignExpr: true }]\n  ]\n};\n```\n\u003c!-- prettier-ignore-end --\u003e\n\n## Motivation\n\nSuppose we have the following `myModule.ts` TypeScript file:\n\n```typescript\n// file: myModule.ts\n\nexport function foo() {\n  // This function works fine in production but throws on our local test machine\n  throw new Error('failed to do expensive network stuff');\n  return;\n}\n\nexport function bar() {\n  // ...\n  foo();\n  return 5;\n}\n\nexport function baz() {\n  // ...\n  foo();\n  return 50;\n}\n```\n\nLets say we want to unit test `myModule.ts`. Specifically, we want to test `bar`\nand `baz`. We don't want to unit test `foo` because a) attempting to run it on\nour local machine will always fail, which is why b) it is covered by our\nintegration tests instead. We simply want to ensure `bar` and `baz` work, and\nthat they both _call_ `foo` without _running_ `foo`.\n\nIf we expect a function to be called, and we want an alternative implementation\nrun when it is called, the easy and obvious solution is to [mock it][3].\n\nSo suppose we create the following `myModule.test.ts` Jest test file, mocking\n`foo` with a [noop](\u003chttps://en.wikipedia.org/wiki/NOP_(code)\u003e):\n\n```typescript\n// file: myModule.test.ts\n\nimport * as myModule from './myModule';\n\nit('bar does what I want', () =\u003e {\n  const spy = jest.spyOn(myModule, 'foo').mockImplementation(() =\u003e undefined);\n\n  expect(myModule.bar()).toBe(5);\n  expect(spy).toBeCalled();\n\n  spy.mockRestore();\n});\n\nit('baz does what I want', () =\u003e {\n  const spy = jest.spyOn(myModule, 'foo').mockImplementation(() =\u003e undefined);\n\n  expect(myModule.baz()).toBe(50);\n  expect(spy).toBeCalled();\n\n  spy.mockRestore();\n});\n```\n\nThis file tests that `bar` and `baz` do what we want, and whenever they call\n`foo` the dummy version is called instead and no error is thrown. Or rather,\nthat seems like it should be the thing that happens. Unfortunately, if we run\nthis code, the above tests will fail because `foo` throws\n_`failed to do expensive network stuff`_.\n\nIs this a bug?\n\nAfter encountering this problem over five years ago, someone posed the question\nto the Jest project:\n[how do you mock a specific function in a module?](https://github.com/facebook/jest/issues/936),\nto which a contributor\n[responded](https://github.com/facebook/jest/issues/936#issuecomment-214939935):\n\n\u003e Supporting the above by mocking a function after requiring a module is\n\u003e impossible in JavaScript – there is (almost) no way to retrieve the binding\n\u003e that foo refers to and modify it.\n\u003e\n\u003e However, if you change your code to this:\n\u003e\n\u003e ```typescript\n\u003e var foo = function foo() {};\n\u003e var bar = function bar() {\n\u003e   exports.foo();\n\u003e };\n\u003e\n\u003e exports.foo = foo;\n\u003e exports.bar = bar;\n\u003e ```\n\u003e\n\u003e and then in your test file you do:\n\u003e\n\u003e ```typescript\n\u003e var module = require('../module');\n\u003e module.foo = jest.fn();\n\u003e module.bar();\n\u003e ```\n\u003e\n\u003e it will work just as expected. This is what we do at Facebook where we don't\n\u003e use ES2015.\n\u003e\n\u003e While ES2015 modules may have immutable bindings for what they export, the\n\u003e underlying compiled code that babel compiles to right now doesn't enforce any\n\u003e such constraints. I see no way currently to support exactly what you are\n\u003e asking...\n\nEssentially, this plugin aims to automate the suggestion above, allowing you to\nmock a specific module function using standard Jest spies by automatically\nreplacing references to exported identifiers with an explicit reference of the\nform `module.exports.${identifier}`. No assembly required.\n\nWith this plugin loaded into Babel, the tests in the motivating example above\npass! 🎉\n\n### Prior Art\n\nPrior solutions include:\n\n- [Manually rewrite all refs to exported identifiers as `exports.${identifier}`](https://github.com/facebook/jest/issues/936#issuecomment-611860173)\n- [Manually rewrite all function and class declarations as expressions](https://github.com/facebook/jest/issues/936#issuecomment-545080082)\n- [Manually place every function and class declaration in a separate file](https://github.com/facebook/jest/issues/936#issuecomment-687632079)\n  (yikes)\n- [Rewrite your tests to use `rewire` dark magic](https://github.com/facebook/jest/issues/936#issuecomment-611860173)\n- [Spend an hour hand-crafting a bespoke nth-level module mock](https://github.com/facebook/jest/issues/936#issuecomment-743688960)\n\nFurther reading and additional solutions:\n\n- https://medium.com/@DavideRama/mock-spy-exported-functions-within-a-single-module-in-jest-cdf2b61af642\n- https://medium.com/@qjli/how-to-mock-specific-module-function-in-jest-715e39a391f4\n- https://kennethteh90.medium.com/jest-how-to-mock-functions-that-reference-each-other-from-the-same-module-9f1d3293ec81\n- https://github.com/facebook/jest/issues/936\n\n## Documentation\n\nFurther documentation can be found under [`docs/`][docs].\n\n## Contributing and Support\n\n**[New issues][choose-new-issue] and [pull requests][pr-compare] are always\nwelcome and greatly appreciated! 🤩** Just as well, you can [star 🌟 this\nproject][link-repo] to let me know you found it useful! ✊🏿 Thank you!\n\nSee [CONTRIBUTING.md][contributing] and [SUPPORT.md][support] for more\ninformation.\n\n[badge-blm]: https://xunn.at/badge-blm 'Join the movement!'\n[link-blm]: https://xunn.at/donate-blm\n[badge-maintenance]:\n  https://img.shields.io/maintenance/active/2023\n  'Is this package maintained?'\n[link-repo]:\n  https://github.com/xunnamius/babel-plugin-explicit-exports-references\n[badge-last-commit]:\n  https://img.shields.io/github/last-commit/xunnamius/babel-plugin-explicit-exports-references\n  'When was the last commit to the official repo?'\n[badge-issues]:\n  https://isitmaintained.com/badge/open/Xunnamius/babel-plugin-explicit-exports-references.svg\n  'Number of known issues with this package'\n[link-issues]:\n  https://github.com/Xunnamius/babel-plugin-explicit-exports-references/issues?q=\n[badge-pulls]:\n  https://img.shields.io/github/issues-pr/xunnamius/babel-plugin-explicit-exports-references\n  'Number of open pull requests'\n[link-pulls]:\n  https://github.com/xunnamius/babel-plugin-explicit-exports-references/pulls\n[badge-codecov]:\n  https://codecov.io/gh/Xunnamius/babel-plugin-explicit-exports-references/branch/main/graph/badge.svg?token=HWRIOBAAPW\n  'Is this package well-tested?'\n[link-codecov]:\n  https://codecov.io/gh/Xunnamius/babel-plugin-explicit-exports-references\n[package-json]: package.json\n[badge-license]:\n  https://img.shields.io/npm/l/babel-plugin-explicit-exports-references\n  \"This package's source license\"\n[link-license]:\n  https://github.com/Xunnamius/babel-plugin-explicit-exports-references/blob/main/LICENSE\n[badge-npm]:\n  https://api.ergodark.com/badges/npm-pkg-version/babel-plugin-explicit-exports-references\n  'Install this package using npm or yarn!'\n[link-npm]:\n  https://www.npmjs.com/package/babel-plugin-explicit-exports-references\n[badge-semantic-release]:\n  https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg\n  'This repo practices continuous integration and deployment!'\n[link-semantic-release]: https://github.com/semantic-release/semantic-release\n[side-effects-key]:\n  https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free\n[exports-main-key]:\n  https://github.com/nodejs/node/blob/8d8e06a345043bec787e904edc9a2f5c5e9c275f/doc/api/packages.md#package-entry-points\n[choose-new-issue]:\n  https://github.com/Xunnamius/babel-plugin-explicit-exports-references/issues/new/choose\n[pr-compare]:\n  https://github.com/Xunnamius/babel-plugin-explicit-exports-references/compare\n[contributing]: CONTRIBUTING.md\n[support]: .github/SUPPORT.md\n[docs]: docs\n[1]:\n  https://github.com/Xunnamius/babel-plugin-explicit-exports-references/issues/2\n[2]: https://www.npmjs.com/package/debug\n[3]: https://jestjs.io/docs/jest-object#jestspyonobject-methodname\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxunnamius%2Fbabel-plugin-explicit-exports-references","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxunnamius%2Fbabel-plugin-explicit-exports-references","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxunnamius%2Fbabel-plugin-explicit-exports-references/lists"}