Hello modpod

.c8rc.json

@@ -0,0 +1,7 @@
+{
+	"all": true,
+	"include": ["src/", "index.js"],
+	"exclude": ["**.test.js"],
+	"skip-full": true,
+	"reporter": ["text-summary", "lcov"]
+}

.editorconfig

@@ -0,0 +1,14 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+indent_style = tab
+
+[{package.json,*.yml}]
+indent_style = space
+indent_size = 2

.eslintrc.cjs

@@ -0,0 +1,15 @@
+module.exports = {
+	plugins: ["@stylistic/js"],
+	env: {
+		node: true,
+		es2024: true
+	},
+	extends: ["eslint:recommended", "prettier"],
+	parserOptions: {
+		ecmaVersion: "latest",
+		sourceType: "module"
+	},
+	rules: {
+		"no-unused-vars": ["error", {argsIgnorePattern: "^_"}]
+	}
+};

.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install
+        run: npm ci
+
+      - name: Test
+        run: npm test
+
+      - name: Coveralls
+        uses: coverallsapp/github-action@v1

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+coverage/
+.DS_Store

.nvmrc

@@ -0,0 +1 @@
+v20.10.0

.prettierignore

@@ -0,0 +1 @@
+package*.json

.prettierrc

@@ -0,0 +1,7 @@
+{
+	"semi": true,
+	"trailingComma": "none",
+	"singleQuote": false,
+	"printWidth": 120,
+	"bracketSpacing": false
+}

LICENSE.md

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2023 Josh Bush
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -0,0 +1,85 @@
+# modpod
+
+Isolate your ES Modules for testing.
+
+```shell
+ npm i -D modpod
+```
+
+## Easy Mode
+
+```js
+import {test} from "node:test";
+
+import modpod from "modpod";
+
+test("easy mode", async () => {
+	const instance = await modpod("./target.js", {
+		"./dep.js": {
+			// Replaces `export default function(){...}` in ./dep.js
+			default: () => "mocked default",
+			// Replaces `export function otherThing(){...}` in ./dep.js
+			otherThing: () => "mocked named export 'otherThing'"
+		}
+	});
+
+	// Exercise instance
+	// Assert what you expected would happen
+});
+```
+
+The default export is a function that sets up a mock environment, imports the target, and cleans up.
+
+- `modpod()` is a shallow mock. It'll only replace dependencies one level deep.
+
+- `modpod.strict()` will make sure that all dependencies of `./target.js` are mocked. If an import is missing a mock, an error will be thrown.
+
+- `modpod.deep()` will replace `./dep.js` anywhere it is imported. Even if it's a dependency of a dependency.
+
+**Note:** If a mock is declared, but never used, then an error will be thrown.
+
+## Hard Mode
+
+If you need more control over the mock lifecycle (like dynamic imports), then you'll need to use the `Mocker` class directly.
+
+Let's consider a few files:
+
+target.js
+
+```js
+export async function doSomething() {
+	const dep = await import("./dep.js");
+	return dep();
+}
+```
+
+dep.js
+
+```js
+export default () => "dep";
+```
+
+Now we can write a test that handles the dynamic import.
+
+```js
+import assert from "node:assert";
+import {test, mock} from "node:test";
+
+import {Mocker} from "modpod";
+
+test("hard mode", async (t) => {
+	const m = new Mocker({strict: true});
+	t.after(() => m.dispose()); // Clean up
+
+	const dep = mock.fn(() => "mocked");
+	m.mock("./dep.js", {
+		default: dep
+	});
+
+	const instance = await m.import("./target.js");
+	assert.strictEqual(dep.mock.calls.length, 0);
+
+	const result = await instance.doSomething();
+	assert.strictEqual(dep.mock.calls.length, 1);
+});
+```

index.js

@@ -0,0 +1,24 @@
+import "./src/register.js";
+import internal from "./src/internal.js";
+import Mocker from "./src/mocker.js";
+
+async function _mock(module, mocks, opts) {
+	const m = new Mocker(opts, {[internal]: 3});
+	try {
+		for (const [k, v] of Object.entries(mocks)) {
+			m.mock(k, v);
+		}
+		const instance = await m.import(module);
+		return instance;
+	} finally {
+		m.dispose();
+	}
+}
+
+const mock = (module, mocks) => _mock(module, mocks, {});
+mock.deep = (module, mocks) => _mock(module, mocks, {deep: true});
+mock.strict = (module, mocks) => _mock(module, mocks, {strict: true});
+
+export default mock;
+
+export {Mocker};