open-index/open-npm huggingface dataset:
npm package: @qfetch/core
Description: Core framework for composable fetch middlewares.
Author: vabatta
Latest version: 0.2.2

# @qfetch/core

Core framework for composable fetch middlewares.

## Overview

Provides TypeScript types and composition utilities for building middleware that wraps the native `fetch` API. Create reusable request/response processing logic through a clean middleware pattern.

## Installation

```bash
npm install @qfetch/core
```

## Quick Start

```typescript
import { compose, pipeline, type MiddlewareExecutor } from '@qfetch/core';

// Create a simple logging middleware
function withLogger(): MiddlewareExecutor {
  return (next) => async (input, init) => {
    console.log('Request:', input);
    const response = await next(input, init);
    console.log('Response:', response.status);
    return response;
  };
}

// Compose middlewares (right-to-left execution)
const qfetch = compose(
  withLogger(),
  // other middlewares...
)(fetch);

// Or use pipeline for left-to-right execution
const qfetch2 = pipeline(
  withLogger(),
  // other middlewares...
)(fetch);

await qfetch('https://api.example.com/users');
```

## Documentation

For complete API reference, examples, and type definitions, see the [API documentation](https://qfetch.github.io/qfetch/modules/_qfetch_core.html).

## Standards References

- [MDN: Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) - Native fetch interface
- [WHATWG Fetch Standard](https://fetch.spec.whatwg.org/) - Fetch specification
npm package: @qfetch/middleware-authorization
Description: Fetch middleware for authorization header injection and 401 retry handling.
Author: vabatta
Latest version: 0.1.0

# @qfetch/middleware-authorization

Fetch middleware for automatic `Authorization` header injection with retry on `401 Unauthorized`.

## Overview

Injects `Authorization` headers using a flexible `TokenProvider` interface. When a `401 Unauthorized` response is received, the middleware refreshes the token and retries according to the configured backoff strategy. Supports any authorization scheme (Bearer, Basic, Token, etc.).

Intended for use with [`@qfetch/core`](https://github.com/qfetch/qfetch/tree/main/packages/core#readme).

## Installation

```bash
npm install @qfetch/middleware-authorization @proventuslabs/retry-strategies
```

## Quick Start

```typescript
import { withAuthorization } from '@qfetch/middleware-authorization';
import { withBaseUrl } from '@qfetch/middleware-base-url';
import { withResponseError } from '@qfetch/middleware-response-error';
import { constant, upto } from '@proventuslabs/retry-strategies';
import { compose } from '@qfetch/core';

// Token provider that refreshes on 401 retry
let accessToken = 'initial-token';

const api = compose(
  withResponseError(),
  withAuthorization({
    tokenProvider: {
      getToken: async () => {
        // On retry after 401, this fetches a fresh token
        return { accessToken, tokenType: 'Bearer' };
      },
    },
    // Retry once immediately on 401
    strategy: () => upto(1, constant(0)),
  }),
  withBaseUrl('https://api.example.com/v1/'),
)(fetch);

// Automatic auth header injection and 401 retry
const user = await api('me').then(r => r.json());
```

## Documentation

For complete API reference, examples, and type definitions, see the [API documentation](https://qfetch.github.io/qfetch/modules/_qfetch_middleware_authorization.html).

## Standards References

- [RFC 9110 - 401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) - Unauthorized status code
- [RFC 9110 - Authorization](https://www.rfc-editor.org/rfc/rfc9110.html#name-authorization) - Authorization header
- [RFC 6750 - Bearer Token Usage](https://www.rfc-editor.org/rfc/rfc6750.html) - Bearer authentication scheme
- [RFC 7617 - Basic Authentication](https://www.rfc-editor.org/rfc/rfc7617.html) - Basic authentication scheme
npm package: @qfetch/middleware-base-url
Description: Fetch middleware for base URL resolution using standard URL constructor behavior.
Author: vabatta
Latest version: 0.1.0

# @qfetch/middleware-base-url

Fetch middleware for resolving URLs against a configured base URL.

## Overview

Resolves string request URLs against a base URL using the WHATWG URL Standard (`new URL(input, base)`). Relative URLs are resolved, absolute paths replace the pathname, and absolute URLs with schemes bypass the base entirely. URL and Request objects pass through unchanged.

Intended for use with [`@qfetch/core`](https://github.com/qfetch/qfetch/tree/main/packages/core#readme).

## Installation

```bash
npm install @qfetch/middleware-base-url
```

## Quick Start

```typescript
import { withBaseUrl } from '@qfetch/middleware-base-url';
import { withHeaders } from '@qfetch/middleware-headers';
import { compose } from '@qfetch/core';

// Environment-aware API client
const apiBaseUrl = process.env.API_URL ?? 'https://api.example.com/v1/';

const api = compose(
  withHeaders({ 'Accept': 'application/json' }),
  withBaseUrl(apiBaseUrl),
)(fetch);

// Use relative paths throughout your application
const users = await api('users').then(r => r.json());
const user = await api('users/123').then(r => r.json());
const posts = await api('posts?limit=10').then(r => r.json());
```

## Documentation

For complete API reference, examples, and type definitions, see the [API documentation](https://qfetch.github.io/qfetch/modules/_qfetch_middleware_base_url.html).

## Standards References

- [WHATWG URL Standard](https://url.spec.whatwg.org/) - Defines URL resolution behavior
- [MDN: URL API](https://developer.mozilla.org/en-US/docs/Web/API/URL) - Browser implementation documentation
npm package: @qfetch/middleware-headers
Description: Fetch middleware for adding default headers to requests.
Author: vabatta
Latest version: 0.1.0

# @qfetch/middleware-headers

Fetch middleware for adding default headers to outgoing requests.

## Overview

Sets default headers on outgoing requests using the standard `Headers` API. Request headers take precedence over middleware headers. Supports both plain objects and `Headers` instances. Header names are case-insensitive per HTTP specification.

Intended for use with [`@qfetch/core`](https://github.com/qfetch/qfetch/tree/main/packages/core#readme).

## Installation

```bash
npm install @qfetch/middleware-headers
```

## Quick Start

```typescript
import { withHeaders } from '@qfetch/middleware-headers';
import { withBaseUrl } from '@qfetch/middleware-base-url';
import { withAuthorization } from '@qfetch/middleware-authorization';
import { compose } from '@qfetch/core';

// Build an API client with default headers for JSON communication
const api = compose(
  withHeaders({
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'X-Client-Version': '1.0.0',
  }),
  withBaseUrl('https://api.example.com/v1/'),
)(fetch);

// All requests include the default headers
await api('users', {
  method: 'POST',
  body: JSON.stringify({ name: 'Alice' }),
});
```

## Documentation

For complete API reference, examples, and type definitions, see the [API documentation](https://qfetch.github.io/qfetch/modules/_qfetch_middleware_headers.html).

## Standards References

- [RFC 9110 - HTTP Semantics: Header Fields](https://www.rfc-editor.org/rfc/rfc9110.html#name-header-fields) - HTTP header field specification
- [MDN: Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) - Browser implementation documentation
npm package: @qfetch/middleware-query-params
Description: Fetch middleware for adding query parameters to request URLs.
Author: vabatta
Latest version: 0.1.0

# @qfetch/middleware-query-params

Fetch middleware for adding query parameters to outgoing request URLs.

## Overview

Sets default query parameters on request URLs using the standard `URLSearchParams` API. Parameters are properly encoded and merged with existing query strings, with request parameters taking precedence. Supports array values in both repeated key (`?tags=a&tags=b`) and bracket notation (`?tags[]=a&tags[]=b`) formats.

Intended for use with [`@qfetch/core`](https://github.com/qfetch/qfetch/tree/main/packages/core#readme).

## Installation

```bash
npm install @qfetch/middleware-query-params
```

## Quick Start

```typescript
import { withQueryParams } from '@qfetch/middleware-query-params';
import { withBaseUrl } from '@qfetch/middleware-base-url';
import { compose } from '@qfetch/core';

// API client with default pagination and filtering
const api = compose(
  withQueryParams({
    format: 'json',
    limit: '25',
    fields: ['id', 'name', 'email'],  // ?fields=id&fields=name&fields=email
  }),
  withBaseUrl('https://api.example.com/v1/'),
)(fetch);

// Fetch paginated users with defaults applied
const users = await api('users').then(r => r.json());
// → https://api.example.com/v1/users?format=json&limit=25&fields=id&fields=name&fields=email

// Request params override defaults
const page2 = await api('users?page=2&limit=50').then(r => r.json());
// → ...?format=json&limit=25&fields=...&page=2&limit=50 (limit=50 takes precedence)
```

## Documentation

For complete API reference, examples, and type definitions, see the [API documentation](https://qfetch.github.io/qfetch/modules/_qfetch_middleware_query_params.html).

## Standards References

- [WHATWG URL Standard](https://url.spec.whatwg.org/) - Defines URL and URLSearchParams behavior
- [MDN: URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) - Browser implementation documentation
npm package: @qfetch/middleware-response-error
Description: Fetch middleware for throwing errors based on HTTP response status codes.
Author: vabatta
Latest version: 0.1.0

# @qfetch/middleware-response-error

Fetch middleware for throwing errors on HTTP error responses.

## Overview

Automatically throws errors for HTTP responses based on status codes. By default, throws a `ResponseError` for any response with status >= 400. Provides flexible customization through status-specific mappers and configurable thresholds, enabling standardized error handling across your application.

Intended for use with [`@qfetch/core`](https://github.com/qfetch/qfetch/tree/main/packages/core#readme).

## Installation

```bash
npm install @qfetch/middleware-response-error
```

## Quick Start

```typescript
import { withResponseError, ResponseError } from '@qfetch/middleware-response-error';
import { withRetryStatus } from '@qfetch/middleware-retry-status';
import { withBaseUrl } from '@qfetch/middleware-base-url';
import { upto, zero } from '@proventuslabs/retry-strategies';
import { compose } from '@qfetch/core';

// Custom application errors
class NotFoundError extends Error {
  constructor(public url: string) {
    super(`Resource not found: ${url}`);
    this.name = 'NotFoundError';
  }
}

// API client with custom error handling
const api = compose(
  withResponseError({
    statusMap: new Map([
      [404, (res) => new NotFoundError(res.url)],
      [400, async (res) => {
        const body = await res.json();
        return new Error(`Validation failed: ${body.message}`);
      }],
    ]),
  }),
  withRetryStatus({ strategy: () => upto(3, zero()) }),
  withBaseUrl('https://api.example.com/v1/'),
)(fetch);

try {
  const user = await api('users/123').then(r => r.json());
} catch (error) {
  if (error instanceof NotFoundError) {
    // Handle 404 specifically
  } else if (error instanceof ResponseError) {
    // Handle other HTTP errors (500, etc.)
    console.log(error.status, error.statusText);
  }
}
```

## Documentation

For complete API reference, examples, and type definitions, see the [API documentation](https://qfetch.github.io/qfetch/modules/_qfetch_middleware_response_error.html).

## Standards References

- [MDN: Response.ok](https://developer.mozilla.org/en-US/docs/Web/API/Response/ok) - Response success indicator
- [MDN: HTTP Status Codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) - HTTP status code reference
npm package: @qfetch/middleware-retry-after
Description: Fetch middleware for server-directed retry timing based on Retry-After headers.
Author: vabatta
Latest version: 0.1.1

# @qfetch/middleware-retry-after

Fetch middleware for **server-directed** retry timing based on `Retry-After` headers.

## Overview

Respects server-provided retry timing for rate limiting and temporary unavailability. When a response includes a valid `Retry-After` header with a retryable status code (`429` or `503` by default), the middleware waits the server-specified duration before retrying. Supports both delay-seconds and HTTP-date formats per RFC 9110.

Intended for use with [`@qfetch/core`](https://github.com/qfetch/qfetch/tree/main/packages/core#readme).

## Installation

```bash
npm install @qfetch/middleware-retry-after @proventuslabs/retry-strategies
```

## Quick Start

```typescript
import { withRetryAfter } from '@qfetch/middleware-retry-after';
import { withBaseUrl } from '@qfetch/middleware-base-url';
import { withResponseError } from '@qfetch/middleware-response-error';
import { fullJitter, upto } from '@proventuslabs/retry-strategies';
import { compose } from '@qfetch/core';

// Resilient API client that respects rate limits
const api = compose(
  withResponseError(),
  withRetryAfter({
    // Retry up to 3 times with jitter to prevent thundering herd
    strategy: () => upto(3, fullJitter(100, 5_000)),
    // Cap server-requested delays at 30 seconds
    maxServerDelay: 30_000,
  }),
  withBaseUrl('https://api.example.com/v1/'),
)(fetch);

// Automatic retry on 429/503 with Retry-After header
const data = await api('resource').then(r => r.json());
```

## Documentation

For complete API reference, examples, and type definitions, see the [API documentation](https://qfetch.github.io/qfetch/modules/_qfetch_middleware_retry_after.html).

## Standards References

- [RFC 9110 §10.2.3 - Retry-After](https://www.rfc-editor.org/rfc/rfc9110.html#section-10.2.3) - Defines `Retry-After` header format and semantics
- [RFC 6585 §4 - 429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585.html#section-4) - Rate limiting status code
- [RFC 9110 §15.6.4 - 503 Service Unavailable](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.4) - Temporary unavailability status code
npm package: @qfetch/middleware-retry-status
Description: Fetch middleware for client-controlled retry timing based on response status codes.
Author: vabatta
Latest version: 0.1.0

# @qfetch/middleware-retry-status

Fetch middleware for **client-controlled** retry timing based on response status codes.

## Overview

Retries transient failures using configurable backoff strategies. When a response has a retryable status code (`408`, `429`, `500`, `502`, `503`, `504` by default), the middleware waits according to the strategy before retrying. Unlike `middleware-retry-after`, retry timing is entirely client-controlled.

Intended for use with [`@qfetch/core`](https://github.com/qfetch/qfetch/tree/main/packages/core#readme).

## Installation

```bash
npm install @qfetch/middleware-retry-status @proventuslabs/retry-strategies
```

## Quick Start

```typescript
import { withRetryStatus } from '@qfetch/middleware-retry-status';
import { withBaseUrl } from '@qfetch/middleware-base-url';
import { withResponseError } from '@qfetch/middleware-response-error';
import { exponential, upto } from '@proventuslabs/retry-strategies';
import { compose } from '@qfetch/core';

// Resilient API client with exponential backoff
const api = compose(
  withResponseError(),
  withRetryStatus({
    // Retry up to 3 times with exponential backoff (1s, 2s, 4s)
    strategy: () => upto(3, exponential(1_000, 2)),
  }),
  withBaseUrl('https://api.example.com/v1/'),
)(fetch);

// Automatic retry on transient failures (500, 502, 503, 504, etc.)
const data = await api('resource').then(r => r.json());
```

## Documentation

For complete API reference, examples, and type definitions, see the [API documentation](https://qfetch.github.io/qfetch/modules/_qfetch_middleware_retry_status.html).

## Standards References

- [RFC 9110 - Status Codes](https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes) - HTTP status code definitions
- [RFC 9110 §15.5.9 - 408 Request Timeout](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.9) - Client timeout status
- [RFC 9110 §15.6 - Server Error 5xx](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6) - Server error status codes
npm package: @qfetch/middlewares
Description: Collection of all qfetch middlewares - convenience package for importing all middlewares at once.
Author: vabatta
Latest version: 0.1.0

# @qfetch/middlewares

Collection of all qfetch middlewares - convenience package for importing all middlewares at once.

## Overview

This package re-exports all official qfetch middlewares with pinned versions, providing a single import point for all middleware functionality.

**Included middlewares:**
- `@qfetch/middleware-authorization` - Authorization header injection with 401 retry
- `@qfetch/middleware-base-url` - Base URL resolution
- `@qfetch/middleware-query-params` - Query parameter management
- `@qfetch/middleware-retry-after` - Retry-After header handling
- `@qfetch/middleware-retry-status` - Status code based retry

## Installation

```bash
npm install @qfetch/middlewares @qfetch/core
```

## Usage

```typescript
import {
  withAuthorization,
  withBaseUrl,
  withQueryParams,
  withRetryAfter,
  withRetryStatus,
} from "@qfetch/middlewares";
import { compose } from "@qfetch/core";

const qfetch = compose(
  withRetryStatus({ statuses: [500, 502, 503], strategy: () => /* ... */ }),
  withRetryAfter(),
  withQueryParams({ version: "v2" }),
  withBaseUrl("https://api.example.com")
)(fetch);

await qfetch("/users");
```

## Individual Packages

For more control over versions or to reduce bundle size, you can install middlewares individually:

```bash
npm install @qfetch/middleware-base-url @qfetch/middleware-retry-status
```

## API

All exports from individual middleware packages are re-exported:

### Authorization
- `withAuthorization(opts)` - Adds authorization headers with 401 retry
- `AuthorizationOptions`, `AuthorizationToken`, `TokenProvider` types

### Base URL
- `withBaseUrl(baseUrl)` - Resolves relative URLs against a base URL

### Query Params
- `withQueryParam(name, value, opts?)` - Adds a single query parameter
- `withQueryParams(params, opts?)` - Adds multiple query parameters
- `ArrayFormat`, `QueryParamOptions`, `QueryParamsOptions`, `QueryValue` types

### Retry-After
- `withRetryAfter(opts?)` - Handles Retry-After response headers
- `RetryAfterOptions` type

### Retry Status
- `withRetryStatus(opts)` - Retries on specific HTTP status codes
- `RetryStatusOptions` type

## Version Policy

This package pins exact versions of all middleware dependencies to ensure consistent behavior. When new middleware versions are released, this package will be updated with a corresponding version bump.
npm package: @qfetch/qfetch
Description: Composable fetch middlewares - includes core utilities and all official middlewares.
Author: vabatta
Latest version: 0.1.0

# qfetch

Composable fetch middlewares - includes core utilities and all official middlewares.

## Installation

```bash
npm install qfetch
```

## Usage

```ts
import {
  compose,
  withAuthorization,
  withBaseUrl,
  withHeaders,
  withQueryParams,
  withRetryAfter,
  withRetryStatus,
} from "qfetch";

const qfetch = compose(
  withRetryStatus({ statuses: [500, 502, 503] }),
  withRetryAfter(),
  withHeaders({ "Content-Type": "application/json" }),
  withBaseUrl("https://api.example.com")
)(fetch);

// Use like regular fetch
const response = await qfetch("/users");
```

## What's included

- **Core**: `compose`, `pipeline` - middleware composition utilities
- **Middlewares**:
  - `withAuthorization` - Add authorization headers with token refresh
  - `withBaseUrl` - Prepend base URL to requests
  - `withHeaders` - Add default headers to requests
  - `withQueryParams` - Add query parameters to request URLs
  - `withRetryAfter` - Retry requests based on Retry-After header
  - `withRetryStatus` - Retry requests based on HTTP status codes

## Individual packages

If you only need specific functionality, install individual packages:

- `@qfetch/core` - Core composition utilities
- `@qfetch/middleware-authorization`
- `@qfetch/middleware-base-url`
- `@qfetch/middleware-headers`
- `@qfetch/middleware-query-params`
- `@qfetch/middleware-retry-after`
- `@qfetch/middleware-retry-status`
- `@qfetch/middlewares` - All middlewares without core

## License

MIT