Workers Fetch

https://github.com/yusukebe/workers-fetch
Admin
Workers Fetch is a curl-like CLI tool for testing Cloudflare Workers locally, allowing users to send...
Tokens:3,360
Snippets:14
Trust Score:9.7
Update:11 months ago
Show doc for...
Tokens:
Raw
### Install Workers Fetch using npm

Source: https://github.com/yusukebe/workers-fetch/blob/main/README.md

Installs the workers-fetch CLI tool globally using npm. This makes the `workers-fetch` command available in your terminal for immediate use. Ensure you have Node.js and npm installed.

```bash
npm install -g workers-fetch
```

--------------------------------

### Get Worker Start Options with Auto Config Detection (TypeScript)

Source: https://context7.com/yusukebe/workers-fetch/llms.txt

Generates configuration options for starting a Cloudflare Worker, including automatic detection of configuration files like `wrangler.json` or `wrangler.toml`. It accepts `FetchOptions` which can specify an explicit config file path. Requires `getWorkerStartOptions` from `workers-fetch/helpers`.

```typescript
import { getWorkerStartOptions } from 'workers-fetch/helpers'
import type { FetchOptions } from 'workers-fetch/helpers'

// Explicit config file
const options1: FetchOptions = {
  method: 'GET',
  config: 'wrangler.toml'
}
const startOpts1 = getWorkerStartOptions(options1)
// Result: {
//   dev: { logLevel: 'none' },
//   config: 'wrangler.toml'
// }

// Auto-detect config (searches for wrangler.json, wrangler.jsonc, wrangler.toml)
const options2: FetchOptions = {
  method: 'POST'
}
const startOpts2 = getWorkerStartOptions(options2)
// Result: {
//   dev: { logLevel: 'none' },
//   config: 'wrangler.json'  // or first found config file
// }

// Custom config path
const options3: FetchOptions = {
  method: 'GET',
  config: './config/custom-wrangler.json'
}
const startOpts3 = getWorkerStartOptions(options3)
// Result: {
//   dev: { logLevel: 'none' },
//   config: './config/custom-wrangler.json'
// }
```

--------------------------------

### Perform GET, POST requests with Workers Fetch

Source: https://github.com/yusukebe/workers-fetch/blob/main/README.md

Demonstrates various ways to use the `workers-fetch` CLI. It shows how to make a simple GET request (auto-detecting wrangler config), a GET request with a specific path, a POST request with headers and data, and how to specify a custom configuration file.

```bash
# GET request (auto-detects wrangler.json, wrangler.jsonc, or wrangler.toml)
workers-fetch

# With path
workers-fetch /api/users

# POST request
workers-fetch -X POST -H "Content-Type:application/json" -d '{"name":"test"}' /api/users

# Custom config file
workers-fetch -c wrangler.toml /api/test
```

--------------------------------

### CLI Command Examples for Workers Fetch

Source: https://context7.com/yusukebe/workers-fetch/llms.txt

Demonstrates various ways to use the workers-fetch CLI tool to send HTTP requests to local Cloudflare Workers. Supports different HTTP methods, custom headers, request bodies, and configuration files. All commands output responses in a structured JSON format.

```bash
# Simple GET request to root path
workers-fetch

# GET request to specific path
workers-fetch /api/users

# POST request with JSON body and headers
workers-fetch -X POST \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer abc123" \
  -d '{"name":"John Doe","email":"john@example.com"}' \
  /api/users

# PUT request with custom config file
workers-fetch -X PUT \
  -c ./config/wrangler.toml \
  -H "Content-Type:application/json" \
  -d '{"status":"active"}' \
  /api/users/123

# DELETE request
workers-fetch -X DELETE -H "Authorization:Bearer token" /api/users/123

# Output format (all commands return JSON):
# {
#   "status": 200,
#   "statusText": "OK",
#   "headers": {
#     "content-type": "application/json"
#   },
#   "body": "{\"message\":\"success\",\"id\":123}"
# }
```

--------------------------------

### Programmatic Request Sending with Workers Fetch

Source: https://context7.com/yusukebe/workers-fetch/llms.txt

Shows how to use the `sendRequest` function from `workers-fetch/helpers` to programmatically interact with local Cloudflare Workers. This includes basic GET requests and POST requests with custom headers and data. The function handles Worker initialization, request execution, and response formatting, returning a structured `FetchResult`. It also demonstrates error handling and Worker disposal.

```typescript
import { sendRequest } from 'workers-fetch/helpers'
import type { FetchOptions, FetchResult } from 'workers-fetch/helpers'

// Basic GET request
const options: FetchOptions = {
  method: 'GET',
  config: 'wrangler.json'
}

let worker: any

try {
  const result: FetchResult = await sendRequest('/api/health', options, (w) => {
    worker = w
  })

  console.log(`Status: ${result.status}`)
  console.log(`Body: ${result.body}`)
} catch (error) {
  console.error('Request failed:', error.message)
  // Error thrown if config file not found: "Config file not found: wrangler.json"
} finally {
  if (worker) {
    await worker.dispose()
  }
}

// POST request with headers and body
const postOptions: FetchOptions = {
  method: 'POST',
  header: [
    'Content-Type:application/json',
    'X-API-Key:secret123'
  ],
  data: JSON.stringify({
    title: 'New Post',
    content: 'This is the content',
    published: true
  }),
  config: 'wrangler.toml'
}

try {
  const result = await sendRequest('/api/posts', postOptions, (w) => {
    worker = w
  })

  // Note: If worker startup takes >= 1 second, a message is logged to stderr:
  // "Starting worker... (1.2s)"

  // Expected output:
  // {
  //   status: 201,
  //   statusText: 'Created',
  //   headers: { 'content-type': 'application/json' },
  //   body: '{"id":456,"title":"New Post"}'
  // }
} finally {
  if (worker) await worker.dispose()
}
```

--------------------------------

### Build URL from Path String (TypeScript)

Source: https://context7.com/yusukebe/workers-fetch/llms.txt

Constructs a complete URL from a given path string, ensuring it starts with a leading slash and appends it to a base URL. This function is useful for creating absolute URLs for fetch requests. It requires the `buildUrl` function from `workers-fetch/helpers`.

```typescript
import { buildUrl } from 'workers-fetch/helpers'

// Path with leading slash
const url1 = buildUrl('/api/users')
// Result: 'http://example.com/api/users'

// Path without leading slash
const url2 = buildUrl('api/users')
// Result: 'http://example.com/api/users'

// Root path
const url3 = buildUrl('/')
// Result: 'http://example.com/'

// Nested path
const url4 = buildUrl('/api/v1/users/123/posts')
// Result: 'http://example.com/api/v1/users/123/posts'

// Path with query parameters
const url5 = buildUrl('/api/search?q=test&limit=10')
// Result: 'http://example.com/api/search?q=test&limit=10'
```

--------------------------------

### Workers Fetch CLI Options

Source: https://github.com/yusukebe/workers-fetch/blob/main/README.md

Details the available command-line options for the `workers-fetch` tool. These options allow customization of the request method, headers, data payload, and configuration file path, enabling flexible testing scenarios.

```bash
# Request path (default: /)
[path]

# HTTP method (default: GET)
-X, --method <method>

# Custom headers (multiple allowed)
-H, --header <headers...>

# Request body data
-d, --data <data>

# Path to wrangler config file (auto-detected if not specified)
-c, --config <path>
```

--------------------------------

### Build Request Options with FetchOptions and Headers (TypeScript)

Source: https://context7.com/yusukebe/workers-fetch/llms.txt

Constructs a request options object suitable for Fetch API calls, combining user-provided FetchOptions and parsed headers. It handles different HTTP methods, request bodies, and header inclusion. Dependencies include `workers-fetch/helpers` for `buildRequestOptions` and `parseHeaders`.

```typescript
import { buildRequestOptions, parseHeaders } from 'workers-fetch/helpers'
import type { FetchOptions } from 'workers-fetch/helpers'

// GET request without body
const getOptions: FetchOptions = {
  method: 'GET'
}
const getHeaders = parseHeaders(['Accept:application/json'])
const getRequest = buildRequestOptions(getOptions, getHeaders)
// Result: {
//   method: 'GET',
//   headers: { 'Accept': 'application/json' }
// }

// POST request with body
const postOptions: FetchOptions = {
  method: 'POST',
  data: JSON.stringify({ name: 'Test User', age: 30 })
}
const postHeaders = parseHeaders([
  'Content-Type:application/json',
  'Authorization:Bearer token123'
])
const postRequest = buildRequestOptions(postOptions, postHeaders)
// Result: {
//   method: 'POST',
//   headers: {
//     'Content-Type': 'application/json',
//     'Authorization': 'Bearer token123'
//   },
//   body: '{"name":"Test User","age":30}'
// }

// PUT request with custom headers
const putOptions: FetchOptions = {
  method: 'PUT',
  data: '<xml><status>active</status></xml>'
}
const putHeaders = parseHeaders(['Content-Type:application/xml'])
const putRequest = buildRequestOptions(putOptions, putHeaders)
// Result: {
//   method: 'PUT',
//   headers: { 'Content-Type': 'application/xml' },
//   body: '<xml><status>active</status></xml>'
// }
```

--------------------------------

### Workers Fetch JSON Output Format

Source: https://github.com/yusukebe/workers-fetch/blob/main/README.md

Illustrates the expected JSON output format from `workers-fetch`. This structure provides details about the HTTP response, including status code, status text, headers, and the response body, facilitating automated testing and debugging.

```json
{
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"message\":\"success\"}"
}
```

--------------------------------

### Parsing Headers with Workers Fetch Utility

Source: https://context7.com/yusukebe/workers-fetch/llms.txt

Illustrates the usage of the `parseHeaders` function from `workers-fetch/helpers` to convert an array of header strings into a key-value object. It handles single and multiple headers, values containing colons, and whitespace trimming. The function gracefully handles undefined input by returning an empty object.

```typescript
import { parseHeaders } from 'workers-fetch/helpers'

// Parse single header
const headers1 = parseHeaders(['Content-Type:application/json'])
// Result: { 'Content-Type': 'application/json' }

// Parse multiple headers
const headers2 = parseHeaders([
  'Content-Type:application/json',
  'Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9',
  'X-Custom-Header:custom-value'
])
// Result: {
//   'Content-Type': 'application/json',
//   'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9',
//   'X-Custom-Header': 'custom-value'
// }

// Handle headers with colons in values
const headers3 = parseHeaders(['X-URL:https://example.com:8080'])
// Result: { 'X-URL': 'https://example.com:8080' }

// Handle whitespace trimming
const headers4 = parseHeaders([
  ' Content-Type: application/json ',
  'Authorization : Bearer token '
])
// Result: {
//   'Content-Type': 'application/json',
//   'Authorization': 'Bearer token'
// }

// Handle undefined input
const headers5 = parseHeaders(undefined)
// Result: {}
```

--------------------------------

### Format Fetch API Response to FetchResult (TypeScript)

Source: https://context7.com/yusukebe/workers-fetch/llms.txt

Transforms a standard Fetch API `Response` object and its body text into a structured `FetchResult` object. This includes status, status text, headers (converted to a plain object), and the response body. It requires the `formatResponse` function from `workers-fetch/helpers`.

```typescript
import { formatResponse } from 'workers-fetch/helpers'
import type { FetchResult } from 'workers-fetch/helpers'

// Success response with headers
const response1 = {
  status: 200,
  statusText: 'OK',
  headers: new Map([
    ['content-type', 'application/json'],
    ['cache-control', 'no-cache'],
    ['x-request-id', 'abc-123']
  ])
}
const body1 = JSON.stringify({ message: 'Success', data: [1, 2, 3] })
const result1: FetchResult = formatResponse(response1, body1)
// Result: {
//   status: 200,
//   statusText: 'OK',
//   headers: {
//     'content-type': 'application/json',
//     'cache-control': 'no-cache',
//     'x-request-id': 'abc-123'
//   },
//   body: '{"message":"Success","data":[1,2,3]}'
// }

// Error response
const response2 = {
  status: 404,
  statusText: 'Not Found',
  headers: new Map([['content-type', 'text/plain']])
}
const body2 = 'Resource not found'
const result2 = formatResponse(response2, body2)
// Result: {
//   status: 404,
//   statusText: 'Not Found',
//   headers: { 'content-type': 'text/plain' },
//   body: 'Resource not found'
// }

// Response with no headers
const response3 = {
  status: 204,
  statusText: 'No Content',
  headers: new Map()
}
const result3 = formatResponse(response3, '')
// Result: {
//   status: 204,
//   statusText: 'No Content',
//   headers: {},
//   body: ''
// }
```
Tokens:
Raw