create-request 1.6.1 → 2.0.0-next.0

package/dist/library/BodyRequest.d.ts

@@ -1,100 +0,0 @@
-import { BaseRequest } from "./BaseRequest.js";
-import type { Body, GraphQLOptions } from "./types.js";
-import type { ResponseWrapper } from "./ResponseWrapper.js";
-/**
- * Base class for requests that can have a body (POST, PUT, PATCH)
- */
-export declare abstract class BodyRequest extends BaseRequest {
-    protected _body?: Body;
-    private _bodyType?;
-    private _gqlOpts;
-    /**
-     * Sets the request body. Automatically detects the body type and sets appropriate Content-Type header.
-     * Supports JSON objects/arrays, strings, FormData, Blob, ArrayBuffer, URLSearchParams, and ReadableStream.
-     *
-     * @param body - The request body. Can be:
-     *   - A JSON-serializable object or array (automatically stringified)
-     *   - A string (sets Content-Type to `text/plain` if not already set)
-     *   - FormData, Blob, File, ArrayBuffer, TypedArray, URLSearchParams, or ReadableStream
-     * @returns The request instance for chaining
-     * @throws {RequestError} If the body is a JSON object that cannot be stringified
-     *
-     * @example
-     * ```typescript
-     * // JSON object (automatically stringified)
-     * request.withBody({ name: 'John', age: 30 });
-     *
-     * @example
-     * // JSON array
-     * request.withBody([1, 2, 3]);
-     *
-     * @example
-     * // String
-     * request.withBody('plain text');
-     *
-     * @example
-     * // FormData
-     * const formData = new FormData();
-     * formData.append('file', fileBlob);
-     * request.withBody(formData);
-     *
-     * @example
-     * // Blob
-     * request.withBody(new Blob(['content'], { type: 'text/plain' }));
-     * ```
-     */
-    withBody(body: Body): this;
-    /**
-     * Sets a GraphQL query or mutation as the request body.
-     * Automatically formats the body as JSON and sets Content-Type to `application/json`.
-     * If `throwOnError` is enabled in options, the response will be checked for GraphQL errors
-     * and a RequestError will be thrown if any are found.
-     *
-     * @param query - The GraphQL query or mutation string (e.g., `'query { user { id } }'`)
-     * @param variables - Optional variables object to pass with the query. Must be a plain object.
-     * @param options - Optional GraphQL-specific options
-     * @param options.throwOnError - If `true`, throws a RequestError when the GraphQL response contains errors
-     * @returns The request instance for chaining
-     * @throws {RequestError} If the query is empty, variables is invalid, or JSON stringification fails
-     *
-     * @example
-     * ```typescript
-     * // Simple query with variables
-     * const request = create.post('/graphql')
-     *   .withGraphQL('query { user(id: $id) { name email } }', { id: '123' });
-     * const data = await request.getJson();
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Mutation with variables
-     * const request = create.post('/graphql')
-     *   .withGraphQL('mutation { createUser(name: $name) { id } }', { name: 'John' });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Throw error if GraphQL response contains errors
-     * const request = create.post('/graphql')
-     *   .withGraphQL('query { user { id } }', undefined, { throwOnError: true });
-     * // If the response has errors, this will throw a RequestError
-     * const data = await request.getJson();
-     * ```
-     */
-    withGraphQL(query: string, variables?: Record<string, unknown>, options?: GraphQLOptions): this;
-    /**
-     * Check if Content-Type header is already set (case-insensitive)
-     */
-    private _hasCT;
-    private _setCT;
-    /**
-     * Get the GraphQL options if set
-     * @returns The GraphQL options or undefined
-     */
-    protected _gql(): GraphQLOptions | undefined;
-    /**
-     * Execute the request and return the ResponseWrapper
-     * Overrides the base implementation to add body handling
-     */
-    getResponse(): Promise<ResponseWrapper>;
-}

package/dist/library/RequestError.d.ts

@@ -1,181 +0,0 @@
-/**
- * Extract a message from an unknown thrown value
- * @internal
- */
-export declare const errorMessage: (e: unknown) => string;
-/**
- * Coerce an unknown thrown value to an Error
- * @internal
- */
-export declare const toError: (e: unknown) => Error;
-/**
- * Error class for HTTP request failures.
- * Extends the standard Error class with additional context about the failed request.
- *
- * @example
- * ```typescript
- * try {
- *   await create.get('/api/users').getJson();
- * } catch (error) {
- *    console.log(`Request failed: ${error.message}`);
- *    console.log(`URL: ${error.url}`);
- *    console.log(`Method: ${error.method}`);
- *    console.log(`Status: ${error.status}`);
- *    console.log(`Body: ${error.body}`); // Raw response body (if available)
- *    console.log(error.getJson()); // Body parsed as JSON (or undefined)
- *    console.log(`Is timeout: ${error.isTimeout}`);
- *    console.log(`Is aborted: ${error.isAborted}`);
- * }
- * ```
- */
-export declare class RequestError extends Error {
-    /** HTTP status code if the request received a response (e.g., 404, 500) */
-    readonly status?: number;
-    /** The Response object if the request received a response before failing */
-    readonly response?: Response;
-    /**
-     * The raw response body as text, if a response was received and its body could be read.
-     * `undefined` for errors without a response (network errors, timeouts, aborts)
-     * or when the body could not be read.
-     */
-    readonly body?: string;
-    /** The URL that was requested */
-    readonly url: string;
-    /** The HTTP method that was used (e.g., 'GET', 'POST') */
-    readonly method: string;
-    /** Whether the request failed due to a timeout */
-    readonly isTimeout: boolean;
-    /** Whether the request was aborted (cancelled) */
-    readonly isAborted: boolean;
-    /** Cached result of parsing `body` as JSON (lazily populated by getJson) */
-    private _parsed?;
-    /**
-     * Creates a new RequestError instance.
-     *
-     * @param message - Error message describing what went wrong
-     * @param url - The URL that was requested
-     * @param method - The HTTP method that was used
-     * @param options - Additional error context
-     * @param options.status - HTTP status code if available
-     * @param options.response - The Response object if available
-     * @param options.body - The raw response body as text, if available
-     * @param options.isTimeout - Whether this was a timeout error
-     * @param options.isAborted - Whether the request was aborted
-     * @param options.cause - The underlying error that caused this error
-     */
-    constructor(message: string, url: string, method: string, options?: {
-        status?: number;
-        response?: Response;
-        body?: string;
-        isTimeout?: boolean;
-        isAborted?: boolean;
-        cause?: Error;
-    });
-    /**
-     * Parses the captured response body (`body`) as JSON.
-     * The result is cached, so repeated calls don't re-parse.
-     * This method never throws - it returns `undefined` when there is no body
-     * or the body is not valid JSON, making it safe to use in error handlers.
-     *
-     * @returns The parsed JSON body, or `undefined` if no body was captured or it isn't valid JSON
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   await create.post('/api/users').withBody(user).getJson();
-     * } catch (error) {
-     *   if (error instanceof RequestError) {
-     *     const details = error.getJson<{ message: string; code: string }>();
-     *     console.log(details?.message ?? error.body ?? error.message);
-     *   }
-     * }
-     * ```
-     */
-    getJson<T = unknown>(): T | undefined;
-    /**
-     * Safely reads the body of a Response as text without consuming it.
-     * The response is cloned before reading, so the original body remains readable.
-     * Never throws - returns `undefined` if the body is unavailable or cannot be read
-     * (e.g., already consumed, locked stream, or read failure).
-     *
-     * @param response - The Response to read the body from
-     * @returns The body as text, or `undefined` if it could not be read
-     *
-     * @example
-     * ```typescript
-     * const body = await RequestError.captureBody(response);
-     * throw RequestError.fromResponse(response, url, 'GET', body);
-     * ```
-     */
-    static captureBody(response: Response): Promise<string | undefined>;
-    /**
-     * Creates a RequestError for a timeout failure.
-     *
-     * @param url - The URL that timed out
-     * @param method - The HTTP method that was used
-     * @param timeoutMs - The timeout duration in milliseconds
-     * @returns A RequestError with `isTimeout` set to `true`
-     *
-     * @example
-     * ```typescript
-     * throw RequestError.timeout('/api/data', 'GET', 5000);
-     * ```
-     */
-    static timeout(url: string, method: string, timeoutMs: number): RequestError;
-    /**
-     * Creates a RequestError from an HTTP error response.
-     * Used when the server returns a non-2xx status code.
-     *
-     * @param response - The Response object from the failed request
-     * @param url - The URL that was requested
-     * @param method - The HTTP method that was used
-     * @param body - The response body as text, if already read (see {@link RequestError.captureBody})
-     * @returns A RequestError with the status code, response object, and body (if provided)
-     *
-     * @example
-     * ```typescript
-     * const response = await fetch('/api/users');
-     * if (!response.ok) {
-     *   const body = await RequestError.captureBody(response);
-     *   throw RequestError.fromResponse(response, '/api/users', 'GET', body);
-     * }
-     * ```
-     */
-    static fromResponse(response: Response, url: string, method: string, body?: string): RequestError;
-    /**
-     * Creates a RequestError from a network-level error.
-     * Automatically detects and categorizes common network errors (timeouts, DNS errors, connection errors).
-     *
-     * @param url - The URL that failed
-     * @param method - The HTTP method that was used
-     * @param originalError - The original error that occurred (e.g., from fetch)
-     * @returns A RequestError with enhanced error message and context
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   await fetch('/api/data');
-     * } catch (error) {
-     *   if (error instanceof Error) {
-     *     throw RequestError.networkError('/api/data', 'GET', error);
-     *   }
-     * }
-     * ```
-     */
-    static networkError(url: string, method: string, originalError: Error): RequestError;
-    /**
-     * Creates a RequestError for an aborted (cancelled) request.
-     *
-     * @param url - The URL that was aborted
-     * @param method - The HTTP method that was used
-     * @returns A RequestError with `isAborted` set to `true`
-     *
-     * @example
-     * ```typescript
-     * const controller = new AbortController();
-     * controller.abort();
-     * throw RequestError.abortError('/api/data', 'GET');
-     * ```
-     */
-    static abortError(url: string, method: string): RequestError;
-}

package/dist/library/ResponseWrapper.d.ts

@@ -1,193 +0,0 @@
-import type { GraphQLOptions } from "./types.js";
-/**
- * Wrapper for HTTP responses with methods to transform the response data.
- * Provides convenient methods to parse the response body in different formats.
- * Response bodies are cached after the first read, so you can call multiple methods
- * (e.g., `getJson()` and `getText()`) on the same response.
- *
- * @example
- * ```typescript
- * const response = await create.get('/api/users').getResponse();
- * console.log(response.status); // 200
- * console.log(response.ok); // true
- * const data = await response.getJson();
- * ```
- */
-export declare class ResponseWrapper {
-    /** The URL that was requested (if available) */
-    readonly url?: string;
-    /** The HTTP method that was used (if available) */
-    readonly method?: string;
-    private readonly _res;
-    private _gqlOpts?;
-    private _blob?;
-    private _text?;
-    private _json?;
-    private _buf?;
-    constructor(response: Response, url?: string, method?: string, graphQLOptions?: GraphQLOptions);
-    /**
-     * HTTP status code (e.g., 200, 404, 500)
-     */
-    get status(): number;
-    /**
-     * HTTP status text (e.g., "OK", "Not Found", "Internal Server Error")
-     */
-    get statusText(): string;
-    /**
-     * Response headers as a Headers object
-     */
-    get headers(): Headers;
-    /**
-     * Whether the response status is in the 200-299 range (successful)
-     */
-    get ok(): boolean;
-    /**
-     * The raw Response object from the fetch API.
-     * Use this if you need direct access to the underlying Response.
-     */
-    get raw(): Response;
-    /**
-     * Create a RequestError carrying this response's context
-     * @param message - The error message
-     * @param withBody - Whether to attach the cached body text to the error
-     */
-    private _err;
-    /**
-     * Read the response body via the given reader, wrapping failures in a RequestError
-     * @throws RequestError if the body has already been consumed or reading fails
-     */
-    private _read;
-    /**
-     * Check if the response body has already been consumed and throw an error if so
-     * @throws RequestError if the body has already been consumed
-     */
-    private _checkUsed;
-    /**
-     * Check for GraphQL errors and throw if throwOnError is enabled
-     * @param data - The parsed JSON data
-     * @throws RequestError if GraphQL response contains errors and throwOnError is enabled
-     */
-    private _checkGql;
-    /**
-     * Parse the response body as JSON
-     * If GraphQL options are set with throwOnError=true, will check for GraphQL errors and throw.
-     *
-     * Returns `null` for empty responses (204 No Content, content-length: 0, or empty body).
-     * This handles common API patterns where PUT/DELETE operations return no content on success.
-     *
-     * @returns The parsed JSON data, or `null` for empty responses
-     * @throws {RequestError} When the request fails, JSON parsing fails, or GraphQL errors occur (if throwOnError enabled).
-     *
-     * @example
-     * const data = await response.getJson();
-     * if (data !== null) {
-     *   console.log(data.items);
-     * }
-     *
-     * @example
-     * // Error handling - errors are always RequestError
-     * try {
-     *   const data = await response.getJson();
-     * } catch (error) {
-     *   if (error instanceof RequestError) {
-     *     console.log(error.status, error.url, error.method);
-     *   }
-     * }
-     */
-    getJson<T = unknown>(): Promise<T | null>;
-    /**
-     * Get the response body as text.
-     * The result is cached, so subsequent calls return the same value without re-reading the body.
-     *
-     * @returns A promise that resolves to the response body as a string
-     * @throws {RequestError} When the body has already been consumed or reading fails
-     *
-     * @example
-     * ```typescript
-     * const text = await response.getText();
-     * console.log(text); // "Hello, world!"
-     * ```
-     */
-    getText(): Promise<string>;
-    /**
-     * Get the response body as a Blob.
-     * Useful for downloading files or handling binary data.
-     * The result is cached, so subsequent calls return the same value without re-reading the body.
-     *
-     * @returns A promise that resolves to the response body as a Blob
-     * @throws {RequestError} When the body has already been consumed or reading fails
-     *
-     * @example
-     * ```typescript
-     * const blob = await response.getBlob();
-     * const url = URL.createObjectURL(blob);
-     * // Use the blob URL for downloading or displaying
-     * ```
-     */
-    getBlob(): Promise<Blob>;
-    /**
-     * Get the response body as an ArrayBuffer.
-     * Useful for processing binary data at a low level.
-     * The result is cached, so subsequent calls return the same value without re-reading the body.
-     *
-     * @returns A promise that resolves to the response body as an ArrayBuffer
-     * @throws {RequestError} When the body has already been consumed or reading fails
-     *
-     * @example
-     * ```typescript
-     * const buffer = await response.getArrayBuffer();
-     * const uint8Array = new Uint8Array(buffer);
-     * // Process the binary data
-     * ```
-     */
-    getArrayBuffer(): Promise<ArrayBuffer>;
-    /**
-     * Get the raw response body as a ReadableStream
-     * Note: This consumes the response body and should only be called once.
-     * Unlike other methods, streams cannot be cached, so this will throw if the body is already consumed.
-     *
-     * @returns The response body as a ReadableStream or null
-     * @throws {RequestError} When the response body has already been consumed
-     *
-     * @example
-     * const stream = response.getBody();
-     * if (stream) {
-     *   const reader = stream.getReader();
-     *   // Process the stream
-     * }
-     */
-    getBody(): ReadableStream<Uint8Array> | null;
-    /**
-     * Extract specific data using a selector function
-     * If no selector is provided, returns the full JSON response.
-     *
-     * Returns `null` for empty responses (204 No Content, content-length: 0, or empty body).
-     * If a selector is provided and data is `null`, the selector will receive `null`.
-     *
-     * @param selector - Optional function to extract and transform data
-     * @returns A promise that resolves to the selected data, or `null` for empty responses
-     * @throws {RequestError} When the request fails, JSON parsing fails, or the selector throws an error
-     *
-     * @example
-     * // Get full response
-     * const data = await response.getData();
-     * if (data !== null) {
-     *   console.log(data.items);
-     * }
-     *
-     * @example
-     * // Extract specific data (use null-safe selector for empty responses)
-     * const users = await response.getData(data => data?.results?.users);
-     *
-     * @example
-     * // Error handling - errors are always RequestError
-     * try {
-     *   const data = await response.getData();
-     * } catch (error) {
-     *   if (error instanceof RequestError) {
-     *     console.log(error.status, error.url, error.method);
-     *   }
-     * }
-     */
-    getData<T = unknown, R = T>(selector?: (data: T | null) => R): Promise<T | R | null>;
-}