mock-anything

https://www.npmjs.com/package/mock-anything

Tiny TypeScript utility to temporarily replace a method on an object and restore it.

No test framework.
No module mocking.
No magic.

check example.js for more examples :)

Questions or issues? Open an issue on GitHub – happy to help.

✨ What is this?

mock-anything lets you override a function explicitly and safely:

• return values (sync)
• throw errors
• resolve promises (async)
• apply behavior once (once)
• apply behavior multiple times (times)
• apply behavior based on arguments (withArgs)
• inspect call count and arguments (called, calledArgs)
• apply behavior on call index (onCall)
• reset data but keeps the mock (reset)
• restore the original function
• restore all mocks at once (restoreAll)
• conditional behavior (until) - please see examples to avoid bugs or loops

Perfect for:

• scripts
• tools
• small tests
• POCs
• Node utilities

❌ What this is NOT

• ❌ Not a test framework
• ❌ Not module/import mocking
• ❌ Not a Jest/Sinon replacement
• ❌ No globals, no loaders

You must have access to the object + method reference.

📦 Install

npm install mock-anything

🚀 Basic Usage

import { mock } from "mock-anything";

const api = {
  getUser() {
    return { id: 1 };
  },
};

const m = mock(api, "getUser").returns({ id: 42 });

api.getUser(); // { id: 42 }
api.getUser(); // { id: 42 }

console.log(m.called()); // 2

m.restore();

api.getUser(); // { id: 1 }

🔁 Async example

const api = {
  async fetchUser() {
    return { id: 1 };
  },
};

const m = mock(api, "fetchUser").resolves({ id: 99 });

await api.fetchUser(); // { id: 99 }

m.restore();

🔂 once()

Apply behavior only on the first call.

mock(api, "fetch")
  .once().throws(new Error("timeout"))
  .returns("ok");

api.fetch(); // throws
api.fetch(); // "ok"
api.fetch(); // "ok"

🎯 withArgs()

Apply behavior based on arguments.

mock(api, "calc")
  .withArgs(1, 2).returns(3)
  .withArgs(2, 2).returns(4)
  .returns(0); // fallback

api.calc(1, 2); // 3
api.calc(2, 2); // 4
api.calc(9, 9); // 0

Works with async too:

mock(api, "fetchUser")
  .withArgs(1).resolves({ id: 100 })
  .withArgs(2).resolves({ id: 200 })
  .resolves({ id: -1 });

📊 API

mock(target, key)
  .returns(value)        // return a value
  .throws(error)         // throw an error
  .resolves(value)       // resolve a promise
  .once()                // apply behavior once
  .times(n)              // apply behavior multiple times
  .withArgs(...args)     // apply behavior based on arguments
  .called()              // get call count
  .calledArgs()          // get arguments of each call
  .reset()               // reset data but keeps the mock
  .onCall(n)             // apply behavior based on call index
  .until(() => bool)     // apply behavior based on a boolean condition
  .restore();            // restore the original function

restoreAll();             // restore all mocks at once

🧠 Design principles

• Explicit > magic
• Small API surface
• Safe monkey-patching
• Easy to reason about
• Easy to remove

📜 License

MIT