feat: add programmatic Node interface

Fixes #16
Fixes #13

.mementorc

@@ -0,0 +1,3 @@
+{
+  "target-url": "https://api.punkapi.com/v2"
+}

README.md

@@ -21,7 +21,7 @@ When building a UI, or working on any project that rely on external services, ma
 
 Memento acts as a development buddy that remembers the requests that your application is sending, the server response, and will respond to your app without the need for requests to go over the internet.
 
-*Pro-tip: Memento may also be used for stubbing external services for integration or end-to-end testing 🎉*
+*Pro-tip: Memento may also be used for [stubbing external services for integration or end-to-end testing](./examples/stub-external-services) 🎉*
 
 ## Getting started
 
@@ -31,37 +31,39 @@ The most basic configuration file to cache the [PunkApi](https://punkapi.com/doc
 
 ```json
 {
-  "targetUrl": "https://api.punkapi.com/v2",
-  "cache-location": "file"
+  "target-url": "https://api.punkapi.com/v2"
 }
 ```
 
-An example for using Memento with create-react-app can be found [here](./example/create-react-app).
+### Examples
+
+- [Usage with Create React App](./examples/create-react-app)
+- [Stubbing external services for integration tests](./examples/stub-external-services)
 
 ### Options
 
 The following options are supported:
 
-| Option         | Description                                             | Example               | Default value |
-| -------------- | ------------------------------------------------------- | --------------------- | ------------- |
-| targetUrl      | The API base URL                                        | http://localhost:4000 | None          |
-| delay          | A delay in milliseconds to be applied to each HTTP call | 1000                  | 0             |
-| port           | The port used to launch Memento                         | 9876                  | 3344          |
-| cache-location | The cache mechanism used for storing responses          | file                  | memory        |
+| Option          | Description                                             | Example               | Default value  |
+| --------------- | ------------------------------------------------------- | --------------------- | -------------- |
+| target-url      | The API base URL                                        | http://localhost:4000 | None           |
+| delay           | A delay in milliseconds to be applied to each HTTP call | 1000                  | 0              |
+| port            | The port used to launch Memento                         | 9876                  | 3344           |
+| cache-directory | The cache directory used for storing responses          | memento-integration   | .memento-cache |
 
 ## Using the CLI
 
 Launching Memento will start the interactive Memento CLI, where you can type commands to modify the cached requests and responses. The documentation can be found by typing `help` in the command prompt.
 
 ## Cache location
 
-By default, memento caches the responses in memory, which means that these responses will be lost when memento restarts.
-
-If you wish to persist responses, you can configure the `cache-location` in the configuration file to `file`. By doing so, memento will create a `.memento-cache` directory in the current directory where each response will be mapped to a directory containing:
+By default, memento will create a `.memento-cache` directory in the current directory where each response will be mapped to a directory containing:
 
 - `metadata.json` - A file containing information about the request and the response.
 - `body.{json,xml,txt}` - The response content. The extension depends on the response `content-type` header. You may edit this file to edit the response.
 
+You may override this directory by providing a `cache-directory` in the configuration file. this may be useful for storing environment dependent responses.
+
 ## Contributing
 
 Below is a list of commands you will probably find useful.

bin/memento.js

@@ -1,4 +1,19 @@
 #!/usr/bin/env node
+
+/* eslint-disable @typescript-eslint/no-var-requires */
 process.env.NODE_ENV = 'production';
 
-require('../dist');
+const { Memento, createCli } = require('../dist');
+
+const memento = Memento();
+
+memento.run().then(() => {
+  createCli({ container: memento.container }).show();
+});
+
+function stopServer() {
+  memento.stop();
+}
+
+process.on('SIGINT', stopServer);
+process.on('exit', stopServer);

examples/create-react-app/.mementorc

@@ -1,6 +1,5 @@
 {
-  "targetUrl": "https://api.punkapi.com/v2",
+  "target-url": "https://api.punkapi.com/v2",
   "delay": 0,
-  "port": 3344,
-  "cache-location": "file"
+  "port": 3344
 }

examples/stub-external-services/.mementorc

@@ -0,0 +1,3 @@
+{
+  "target-url": "https://pokeapi.co/api/v2"
+}

examples/stub-external-services/README.md

@@ -0,0 +1,24 @@
+# How to stub external services?
+
+1. Add memento as a dev dependency: `yarn add @antoinechalifour/memento --dev` or `npm install --save-dev @antoinechalifour/memento`
+2. Add a `.mementorc` in your project.
+3. Configure your test environment for using Memento as the API url
+4. Import memento in your test files, and plug it into your test runner hooks
+
+```js
+const { Memento } = require('@antoinechalifour/memento');
+
+const memento = Memento({
+  cacheDirectory: path.join(__dirname, '<path to cache directory>')
+});
+
+beforeAll(async () => {
+  await memento.run();
+});
+
+afterAll(() => {
+  memento.stop();
+});
+```
+
+5. If the requests are not in the cache on the first test run, the assertions will be made against the actual API responses. On the next runs, they will be made against the cache.