The Fetch module provides utilities for parsing curl-style arguments, building Web API Request objects, and parsing Response objects. It’s designed for implementing HTTP gateways and REST API integrations.
Functions
parseArgv
Parses curl-style argv into a structured fetch input.
function parseArgv(argv: string[]): FetchInput
Array of command-line arguments in curl style
Structured input object with path, method, headers, body, and query parameters
Example
import { Fetch } from 'incur'
const input = Fetch.parseArgv([
'users',
'123',
'--method', 'POST',
'--data', '{"name":"Alice"}',
'--header', 'Authorization: Bearer token',
'--limit', '10'
])
// Returns:
// {
// path: '/users/123',
// method: 'POST',
// headers: Headers { 'authorization': 'Bearer token' },
// body: '{"name":"Alice"}',
// query: URLSearchParams { 'limit': '10' }
// }
Reserved Flags
--method / -X - HTTP method (GET, POST, etc.)--data / -d - Request body--body - Request body (alternative)--header / -H - HTTP header (format: Name: Value)
All other flags become query parameters.
buildRequest
Constructs a standard Web API Request from a FetchInput.
function buildRequest(input: FetchInput): Request
Structured fetch input object
Standard Web API Request object
Example
import { Fetch } from 'incur'
const input: Fetch.FetchInput = {
path: '/api/users',
method: 'GET',
headers: new Headers(),
body: undefined,
query: new URLSearchParams({ limit: '10' })
}
const request = Fetch.buildRequest(input)
// Standard Request with URL: http://localhost/api/users?limit=10
parseResponse
Parses a fetch Response into structured output.
async function parseResponse(response: Response): Promise<FetchOutput>
Structured output with status, headers, and parsed data
Example
import { Fetch } from 'incur'
const response = await fetch('https://api.example.com/users')
const output = await Fetch.parseResponse(response)
// Returns:
// {
// ok: true,
// status: 200,
// data: { users: [...] }, // Parsed JSON or text
// headers: response.headers
// }
isStreamingResponse
Returns true if the response body is a stream that should be consumed incrementally.
function isStreamingResponse(response: Response): boolean
true if the response is NDJSON streaming, false otherwise
Example
import { Fetch } from 'incur'
const response = await fetch('https://api.example.com/stream')
if (Fetch.isStreamingResponse(response)) {
for await (const chunk of Fetch.parseStreamingResponse(response)) {
console.log(chunk)
}
} else {
const output = await Fetch.parseResponse(response)
console.log(output.data)
}
parseStreamingResponse
Parses a streaming response body as an async generator of parsed NDJSON chunks.
async function* parseStreamingResponse(
response: Response
): AsyncGenerator<unknown, void, unknown>
Web API Response object with content-type: application/x-ndjson
return
AsyncGenerator<unknown, void, unknown>
Async generator yielding parsed NDJSON chunks
Example
import { Fetch } from 'incur'
const response = await fetch('https://api.example.com/events')
for await (const event of Fetch.parseStreamingResponse(response)) {
console.log('Event:', event)
// Each event is a parsed JSON object from an NDJSON line
}
Types
Structured input parsed from curl-style argv.
type FetchInput = {
body: string | undefined
headers: Headers
method: string
path: string
query: URLSearchParams
}
body
string | undefined
required
Request body string
Request path (starts with /)
FetchOutput
Structured output from a fetch Response.
type FetchOutput = {
data: unknown
headers: Headers
ok: boolean
status: number
}
Parsed response data (JSON object or text string)
true for 2xx status codes
Usage Patterns
Building an HTTP Gateway
import { Cli, Fetch } from 'incur'
const cli = Cli.create({
name: 'api',
version: '1.0.0',
commands: {
call: Cli.command({
description: 'Call API endpoint',
run: async ({ argv }) => {
const input = Fetch.parseArgv(argv)
const request = Fetch.buildRequest(input)
// Rewrite URL to actual API
const url = new URL(request.url)
url.host = 'api.example.com'
url.protocol = 'https:'
const response = await fetch(new Request(url, request))
const output = await Fetch.parseResponse(response)
return output.data
}
})
}
})
Handling Streaming Responses
import { Cli, Fetch } from 'incur'
const cli = Cli.create({
name: 'stream',
version: '1.0.0',
commands: {
events: Cli.command({
run: async function* () {
const response = await fetch('https://api.example.com/events')
if (Fetch.isStreamingResponse(response)) {
for await (const event of Fetch.parseStreamingResponse(response)) {
yield event
}
}
}
})
}
})
