npm package: @fizzwiz/mockchain
Description: A mockable Promise library for easily testing asynchronous operations in isolation.
Author: Roberto Venditti
Latest version: 0.0.0-dev.1

# 🃏 @fizzwiz/mockchain

**A mockable Promise for testing asynchronous operations in distributed systems.**

`MockChain` is a lightweight, fully mockable `Promise` subclass that allows you to **test asynchronous communication** among peers, servers, or browser clients.
Each async operation can be wrapped in a `MockChain`, giving you full control over its resolution or rejection in tests.

🔗 Visit the blog: [**mockchain.blog.fizzwiz.cloud**](https://mockchain.blog.fizzwiz.cloud)

---

## ✨ Features

* **Mockable Promises:** Wrap any asynchronous operation and control its outcome.
* **Configurable auto-start:** Pass `autoStart = false` to delay execution until `.mock()` or `.fail()` is manually invoked.
* **Delayed resolution/rejection:** Use `mockAfter` and `failAfter` to simulate network latency.
* **Factory methods:** Conveniently wrap fetch requests, WebSocket messages, or any event emitter.
* **Chainable:** Preserves native Promise chaining while remaining mockable.
* **Root access:** Use `.root` to access the first node in a chain.
* **Parent navigation:** Access the previous node via `.parent`.

---

## 📦 Installation

```bash
npm install @fizzwiz/mockchain
```

### Browser (via CDN)

```html
<script src="https://cdn.jsdelivr.net/npm/@fizzwiz/mockchain/dist/mockchain.bundle.js"></script>
<script>
  const { MockChain } = window.mockchain;
</script>
```

The global `mockchain` object exposes all classes.

---

## 🚀 Quick Start

```javascript
import { MockChain } from '@fizzwiz/mockchain';

// Implement a mockable async-like method
function doFetch(url, autoStart = true) {
  const chain = MockChain.from(fetch(url), autoStart)
    .then(res => res.json());
  return chain;
}

// Test the method in isolation
const chain = doFetch(undefined, false); // get a non-auto-start chain
chain.root.mock(new Response(JSON.stringify({ ok: true }))); // trigger the chain manually
const result = await chain; // the final resolved value
console.log(result); // -> { ok: true }
```

---

## 📘 API

### Class: `MockChain`

#### Instance Methods

* `mock(value)` — force resolve with `value`.
* `fail(error)` — force reject with `error`.
* `mockAfter(ms, value)` — resolve after a delay.
* `failAfter(ms, error)` — reject after a delay.
* Standard `then`, `catch`, and `finally` methods are overridden to preserve mockability.
* `.root` — reference the top-level node of the chain.
* `.parent` — reference the previous node in the chain.

#### Static Methods

* `resolve(value)` — create a resolved MockChain.
* `reject(reason)` — create a rejected MockChain.
* `from(valueOrPromise, autoStart = true, parent = null)` — convert any Promise or value into a MockChain.
* `fromResponse(url, opts, autoStart = true)` — wrap a fetch request.
* `fromMessage(ws, isMessage?, attach = false, autoStart = true)` — wrap WebSocket messages.
* `fromEvent(emitter, eventName, isEvent?, attach = false, autoStart = true)` — wrap any Node.js or browser event.

💡 **Note:**
All static constructors support the `autoStart` flag:

* When `autoStart = true`, the executor runs immediately (like a normal Promise).
* When `autoStart = false`, execution is deferred until `.mock()` or `.fail()` is called.
* `fromResponse` → `.mock()` expects a `Response` object.
* `fromMessage`, `fromEvent` → `.mock()` expects the emitted event argument(s).

---

## 🥪 Example Use Cases

* Testing distributed node communication and behavior in isolation — without a live network.
* Simulating server or WebSocket responses in browser-based peers.
* Mocking event-driven behaviors during development or CI runs.
* Controlling intermediate steps in promise chains using `.parent` or `.root`.
* Debugging async flows built from extemporaneous arrow functions rather than dedicated functions.

---

## 📝 Contributing

Contributions, ideas, and feedback are welcome!
Please open an issue or pull request on [GitHub](https://github.com/fizzwiz/mockchain).

---

## 📄 License

MIT © [fizzwiz](https://github.com/fizzwiz)
🔗 [mockchain.blog.fizzwiz.cloud](https://mockchain.blog.fizzwiz.cloud)