socket-lib/src/http-request/response-types.ts at main · SocketDev/socket-lib · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
/**
 * @file Types for HTTP response surface — `HttpResponse` with its fetch-like
 *   body accessors, and `HttpResponseError` for `throwOnError`. Split out of
 *   `http-request/types.ts` for size hygiene.
 */

import type { IncomingHttpHeaders } from 'node:http'

import type { IncomingResponse } from './request-types'

/**
 * HTTP response object with fetch-like interface. Provides multiple ways to
 * access the response body.
 */
export interface HttpResponse {
  /**
   * Get response body as ArrayBuffer. Useful for binary data or when you need
   * compatibility with browser APIs.
   *
   * @example
   *   ;```ts
   *   const response = await httpRequest('https://example.com/image.png')
   *   const arrayBuffer = response.arrayBuffer()
   *   console.log(arrayBuffer.byteLength)
   *   ```
   *
   * @returns The response body as an ArrayBuffer
   */
  arrayBuffer(): ArrayBuffer
  /**
   * Raw response body as Buffer. Direct access to the underlying Node.js
   * Buffer.
   *
   * @example
   *   ;```ts
   *   const response = await httpRequest('https://example.com/data')
   *   console.log(response.body.length) // Size in bytes
   *   console.log(response.body.toString('hex')) // View as hex
   *   ```
   */
  body: Buffer
  /**
   * HTTP response headers. Keys are lowercase header names, values can be
   * strings or string arrays.
   *
   * @example
   *   ;```ts
   *   const response = await httpRequest('https://example.com')
   *   console.log(response.headers['content-type'])
   *   console.log(response.headers['set-cookie']) // May be string[]
   *   ```
   */
  headers: IncomingHttpHeaders
  /**
   * Parse response body as JSON. Type parameter `T` allows specifying the
   * expected JSON structure.
   *
   * @example
   *   ;```ts
   *   interface User {
   *     name: string
   *     id: number
   *   }
   *   const response = await httpRequest('https://api.example.com/user')
   *   const user = response.json<User>()
   *   console.log(user.name, user.id)
   *   ```
   *
   * @template T - Expected JSON type (defaults to `unknown`)
   *
   * @returns Parsed JSON data
   *
   * @throws {SyntaxError} When response body is not valid JSON
   */
  json<T = unknown>(): T
  /**
   * Whether the request was successful (status code 200-299).
   *
   * @example
   *   ;```ts
   *   const response = await httpRequest('https://example.com/data')
   *   if (response.ok) {
   *     console.log('Success:', response.json())
   *   } else {
   *     console.error('Failed:', response.status, response.statusText)
   *   }
   *   ```
   */
  ok: boolean
  /**
   * HTTP status code (e.g., 200, 404, 500).
   */
  status: number
  /**
   * HTTP status message (e.g., "OK", "Not Found", "Internal Server Error").
   */
  statusText: string
  /**
   * Get response body as UTF-8 text string.
   *
   * @example
   *   ;```ts
   *   const response = await httpRequest('https://example.com')
   *   const html = response.text()
   *   console.log(html.includes('<html>'))
   *   ```
   *
   * @returns The response body as a string
   */
  text(): string
  /**
   * The underlying Node.js IncomingResponse for advanced use cases (e.g.,
   * streaming, custom header inspection). Only available when the response was
   * not consumed by the convenience methods.
   */
  rawResponse?: IncomingResponse | undefined
}

/**
 * Error thrown when an HTTP response has a non-2xx status code and
 * `throwOnError` is enabled. Carries the full `HttpResponse` so callers can
 * inspect status, headers, and body.
 */
export class HttpResponseError extends Error {
  response: HttpResponse

  constructor(response: HttpResponse, message?: string | undefined) {
    const statusCode = response.status ?? 'unknown'
    const statusMessage = response.statusText || 'No status message'
    super(message ?? `HTTP ${statusCode}: ${statusMessage}`)
    this.name = 'HttpResponseError'
    this.response = response
    Error.captureStackTrace(this, HttpResponseError)
  }
}