fetchbook

Fetchbook

Fetchbook is a command-line tool designed to help you manage your collections of HTTP requests. It is based on the standard RequestInit object, and runs in TypeScript with bun.sh.

You can try it out just by running this command:

npx fetchbook run --demo -v

[!WARNING] :construction_worker_woman: Fetchbook is currently under active development, expect breaking changes.

Installation

To use Fetchbook in you own project:

npx fetchbook init

To create a separate Fetchbook project:

npx fetchbook init <project name>

Alternatively, you can install it manually:

npm install fetchbook

Usage

Fetchbook is split in different commands that operate on one or multiple fetch story files.

Run

fetchbook run [story] [options]

Run one or many fetch story files.

Demo

npx fetchbook run --demo -v

Arguments

• [story] (optional): Path to a fetch story file (or folder) that describes an HTTP request. If omitted, Fetchbook will prompt you to search and choose a fetch story in the current folder.

Options

• -a, --all: Run all fetch story files in the current folder recursively.
• -v, --verbose: Enable verbose output, providing additional information about the request and response.
• -d, --dry-run: Perform a dry run, simulating the request without making an actual HTTP call.

Examples

1. Run a single fetch story file:

   fetchbook run path/to/your/story.fetch.ts
   

2. Run all fetch story files in the current folder and its subfolders:

   fetchbook run -a
   

3. Perform a dry run of a fetch story file:

   fetchbook run path/to/your/story.fetch.ts -d
   

4. Run a fetch story file with verbose output:

   fetchbook run path/to/your/story.fetch.ts -v
   

Export

fetchbook export [story] [options]

Export a fetch story file as other formats (now only curl is supported) and display it in the terminal instead of making the HTTP request.

Demo

npx fetchbook export --format=curl --demo -a

Arguments

• [story] (optional): Path to a fetch story file (or folder) that describes an HTTP request. If omitted, Fetchbook will prompt you to search and choose a fetch story in the current folder.

Options

• -f, --format: Export the request as a cURL command and display it in the terminal instead of making the HTTP request.
• -a, --all: Export all fetch story files in the current folder recursively.

Examples

1. Export a single fetch story file as a cURL command:

   fetchbook export --format curl path/to/your/story.fetch.ts
   

2. Export all fetch story files in the current folder and its subfolders:

   fetchbook export --format curl -a
   

Init

npx fetchbook init [name]

Initialize a fetchbook project.

Arguments

• [name] (optional): Name of the project. If set Fetchbook will create a new folder with a package.json file and a bunch of sample fetch story files. If not set Fetchbook will initialize an existing project.

Examples

1. Run a single fetch story file:

   npx fetchbook init my-fetchbook-project
   

Fetch Story Files

Fetch story files are TypeScript modules ending with .fetch.ts that must comply with the following type definition:

type FetchStory = {
  name: string;
  url: string;
  init: RequestInit;
  expect?: Partial<{
    status: number;
    statusText: string;
    headers: Record<string, string>;
    body: any;
  }>;
  before?: FetchStory[];
  after?: FetchStory[];
};

Here's an explanation of each property within the FetchStory type definition:

• name (string): A descriptive name for the story, helping you identify and organize your requests.
• url (string): The URL of the HTTP request.
• init (RequestInit): An object containing the request's initialization options, including method, headers, and body.
• expect (optional): Defines your expectations for the response, such as expected HTTP status code, status text, headers and body.
• before (optional): An array of FetchStory objects representing requests to execute before the main request.
• after (optional): An array of FetchStory objects representing requests to execute after the main request.

Example Fetch Story File

Here's an example of a Fetchbook fetch story file adhering to the TypeScript definition and the naming convention (ending with .fetch.ts):

// examples/venusaur.fetch.ts
import { FetchStory } from "fetchbook";

const story: FetchStory = {
  name: "Get info about Venusaur",
  url: "https://pokeapi.co/api/v2/pokemon/venusaur",
  init: {
    method: "GET",
  },
  expect: {
    status: 200,
    headers: {
      "content-type": "application/json; charset=utf-8",
    },
    body: {
      order: 3,
      name: "venusaur",
      height: 20,
      weight: 1000,
    },
  },
};

export default story;

Ensure that your story files adhere to this structure, type definition, and the naming convention (.fetch.ts) to work seamlessly with Fetchbook. You can create multiple fetch story files to describe different HTTP requests and use Fetchbook to manage and execute them as needed.

Contributing

Contributions are welcome! These are some of the current pending tasks:

• Print response body by default to mimic a standard cURL request.
• Run stories with a runner like listr2.
• Add command to create a story: fetchbook create.
• Add command to import a story from other formats: fetchbook import.
• Add a command to start a web ui: fetchbook studio.

License

Fetchbook is licensed under the MIT License. Feel free to use and modify it according to your needs.

---

Enjoy using Fetchbook for efficient HTTP request management! If you encounter any issues or have suggestions for improvement, please don't hesitate to open an issue or contribute to the project.