[WIP] Add API documentation

joshuajaco · Jul 29, 2023 · 9eb144b · 9eb144b
1 parent 2a7238a
commit 9eb144b
Show file tree

Hide file tree

Showing 2 changed files with 499 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -50,6 +50,380 @@ console.log(await response.json()); // { message: "Hello World" }
 await mockServer.stop();
 ```
 
+# API
+
+## `MockServer`
+
+### `constructor(options): MockServer`
+
+Creates a new [`MockServer`](#mockserver) instance.
+
+| Param   | Type                  |
+| ------- | --------------------- |
+| options | [`Options`](#options) |
+
+#### Example
+
+```ts
+const mockServer = new MockServer({ port: 3000 });
+```
+
+### `start(): Promise<void>`
+
+Starts the mock server.
+
+#### Example
+
+```ts
+await mockServer.start();
+```
+
+### `stop(): Promise<void>`
+
+Stops the mock server.
+
+#### Example
+
+```ts
+await mockServer.stop();
+```
+
+### `port(): number`
+
+Get the port the mock server is running on.
+
+#### Example
+
+```ts
+const port = mockServer.port();
+console.log(port); // 3000
+```
+
+### `mock(matcher, response, options): MockServer`
+
+Register a mock.
+
+Returns the [`MockServer`](#mockserver) instance.
+
+| Param    | Type                                            |
+| -------- | ----------------------------------------------- |
+| matcher  | [`Matcher`](#matcher)                           |
+| response | `string` \| `number` \| [`Response`](#response) |
+| options  | [`MockOptions`](#mockoptions)                   |
+
+#### Example
+
+```ts
+mockServer.mock("/test", { status: 204 });
+
+const response = await fetch("http://localhost:3000/test");
+
+console.log(response.status); // 204
+```
+
+### `get(matcher, response, options): MockServer`
+
+Register a mock for requests with method `GET`.
+
+Returns the [`MockServer`](#mockserver) instance.
+
+| Param    | Type                                                |
+| -------- | --------------------------------------------------- |
+| matcher  | `string` \| `RegExp` \| [`MatcherObj`](#matcherobj) |
+| response | `string` \| `number` \| [`Response`](#response)     |
+| options  | [`MockOptions`](#mockoptions)                       |
+
+#### Example
+
+```ts
+mockServer.get("/test", {
+  status: 200,
+  body: { message: "Hello World" },
+});
+
+const response = await fetch("http://localhost:3000/test");
+
+console.log(response.status); // 200
+console.log(await response.json()); // { message: "Hello World" }
+```
+
+### `post(matcher, response, options): MockServer`
+
+Register a mock for requests with method `POST`.
+
+Returns the [`MockServer`](#mockserver) instance.
+
+| Param    | Type                                                |
+| -------- | --------------------------------------------------- |
+| matcher  | `string` \| `RegExp` \| [`MatcherObj`](#matcherobj) |
+| response | `string` \| `number` \| [`Response`](#response)     |
+| options  | [`MockOptions`](#mockoptions)                       |
+
+#### Example
+
+```ts
+mockServer.post("/test", {
+  status: 201,
+  body: { message: "Hello World" },
+});
+
+const response = await fetch("http://localhost:3000/test", {
+  method: "POST",
+  body: JSON.stringify({ message: "Hello World" }),
+});
+
+console.log(response.status); // 201
+console.log(await response.json()); // { message: "Hello World" }
+```
+
+### `patch(matcher, response, options): MockServer`
+
+Register a mock for requests with method `PATCH`.
+
+Returns the [`MockServer`](#mockserver) instance.
+
+| Param    | Type                                                |
+| -------- | --------------------------------------------------- |
+| matcher  | `string` \| `RegExp` \| [`MatcherObj`](#matcherobj) |
+| response | `string` \| `number` \| [`Response`](#response)     |
+| options  | [`MockOptions`](#mockoptions)                       |
+
+#### Example
+
+```ts
+mockServer.patch("/test", {
+  status: 200,
+  body: { message: "Hello World" },
+});
+
+const response = await fetch("http://localhost:3000/test", {
+  method: "PATCH",
+  body: JSON.stringify({ message: "Hello World" }),
+});
+
+console.log(response.status); // 200
+console.log(await response.json()); // { message: "Hello World" }
+```
+
+### `delete(matcher, response, options): MockServer`
+
+Register a mock for requests with method `DELETE`.
+
+Returns the [`MockServer`](#mockserver) instance.
+
+| Param    | Type                                                |
+| -------- | --------------------------------------------------- |
+| matcher  | `string` \| `RegExp` \| [`MatcherObj`](#matcherobj) |
+| response | `string` \| `number` \| [`Response`](#response)     |
+| options  | [`MockOptions`](#mockoptions)                       |
+
+#### Example
+
+```ts
+mockServer.patch("/test", { status: 204 });
+
+const response = await fetch("http://localhost:3000/test", {
+  method: "DELETE",
+});
+
+console.log(response.status); // 204
+```
+
+### `mocks(): readonly Mock[]`
+
+Get all registered mocks.
+
+Returns an array of [`Mock`](#mock) objects.
+
+#### Example
+
+```ts
+mockServer.mock({ path: "/test" }, { status: 204 });
+
+const mocks = mockServer.mocks();
+
+console.log(mocks); // [{ matcher: "/test", response: { status: 204 } }]
+```
+
+### `calls(): readonly Call[]`
+
+Get all registered calls.
+
+Returns an array of [`Call`](#call) objects.
+
+#### Example
+
+```ts
+mockServer.mock({ path: "/test" }, { status: 204 });
+await fetch("http://localhost:3000/test");
+
+const calls = mockServer.calls();
+
+console.log(calls); // [{ path: "/test", method: "GET" }]
+```
+
+### `hasBeenCalledWith(matcher): boolean`
+
+Returns `true` if the route has been called with the given `matcher`, `false` otherwise.
+
+| Param   | Type                  |
+| ------- | --------------------- |
+| matcher | [`Matcher`](#matcher) |
+
+#### Example
+
+```ts
+mockServer.get("/test", { status: 200 });
+
+console.log(mockServer.hasBeenCalledWith("/test")); // false
+
+await fetch("http://localhost:3000/test");
+
+console.log(mockServer.hasBeenCalledWith("/test")); // true
+```
+
+### `hasBeenCalledTimes(times, matcher): boolean`
+
+Returns `true` if the route has been called `times` times with the given `matcher`, `false` otherwise.
+
+| Param   | Type                  |
+| ------- | --------------------- |
+| times   | `number`              |
+| matcher | [`Matcher`](#matcher) |
+
+```ts
+mockServer.get("/test", { status: 200 });
+
+console.log(mockServer.hasBeenCalledTimes(0, "/test")); // true
+console.log(mockServer.hasBeenCalledTimes(1, "/test")); // false
+
+await fetch("http://localhost:3000/test");
+
+console.log(mockServer.hasBeenCalledTimes(0, "/test")); // false
+console.log(mockServer.hasBeenCalledTimes(1, "/test")); // true
+```
+
+### `reset(): void`
+
+Reset all mocks and calls.
+
+#### Example
+
+```ts
+mockServer.get("/test", { status: 200 });
+await fetch("http://localhost:3000/test");
+
+console.log(mockServer.mocks()); // [{ matcher: "/test", response: { status: 200 } }]
+console.log(mockServer.calls()); // [{ path: "/test", method: "GET" }]
+
+mockServer.reset();
+
+console.log(mockServer.mocks()); // []
+console.log(mockServer.calls()); // []
+```
+
+### `resetMocks(): void`
+
+Reset all mocks.
+
+#### Example
+
+```ts
+mockServer.get("/test", { status: 200 });
+
+console.log(mockServer.mocks()); // [{ matcher: "/test", response: { status: 200 } }]
+
+mockServer.resetMocks();
+
+console.log(mockServer.mocks()); // []
+```
+
+### `resetCalls(): void`
+
+Reset all calls.
+
+#### Example
+
+```ts
+mockServer.get("/test", { status: 200 });
+await fetch("http://localhost:3000/test");
+
+console.log(mockServer.calls()); // [{ path: "/test", method: "GET" }]
+
+mockServer.resetCalls();
+
+console.log(mockServer.calls()); // []
+```
+
+## `Options`
+
+| Property | Type     | Description                        |
+| -------- | -------- | ---------------------------------- |
+| port     | `number` | the port to run the mock server on |
+
+## `Matcher`
+
+Type alias for [`MatcherObj`](#matcherobj) | [`MatcherFn`](#matcherfn).
+
+```ts
+type Matcher = MatcherObj | MatcherFn;
+```
+
+## `MatcherObj`
+
+| Property | Type     | Description                        |
+| -------- | -------- | ---------------------------------- |
+| path     | `string` | the port to run the mock server on |
+| method   | `string` | the port to run the mock server on |
+
+## `MatcherFn`
+
+```ts
+type MatcherFn = (req: express.Request) => boolean;
+```
+
+## `Response`
+
+Type alias for [`ResponseObj`](#responseobj) | [`ResponseFn`](#responsefn).
+
+```ts
+type Response = ResponseObj | ResponseFn;
+```
+
+## `ResponseObj`
+
+| Property | Type     | Description                        |
+| -------- | -------- | ---------------------------------- |
+| path     | `string` | the port to run the mock server on |
+| method   | `string` | the port to run the mock server on |
+
+## `ResponseFn`
+
+```ts
+type ResponseFn = (req: express.Request) => ResponseObj;
+```
+
+## `MockOptions`
+
+| Property  | Type                     | Description                        |
+| --------- | ------------------------ | ---------------------------------- |
+| overwrite | `boolean` \| `undefined` | the port to run the mock server on |
+
+## `Mock`
+
+| Property | Type          | Description                        |
+| -------- | ------------- | ---------------------------------- |
+| matcher  | `Matcher`     | the port to run the mock server on |
+| response | `Response`    | the port to run the mock server on |
+| options  | `MockOptions` | the port to run the mock server on |
+
+## `Call`
+
+| Property | Type              | Description                        |
+| -------- | ----------------- | ---------------------------------- |
+| request  | `express.Request` | the port to run the mock server on |
+| matcher  | `Matcher`         | the port to run the mock server on |
+
 # License
 
 [MIT](https://github.com/joshuajaco/mocaron/blob/main/LICENSE)