@atproto-labs/fetch 0.0.1 → 0.1.1

package/src/fetch-response.ts

@@ -1,27 +1,58 @@
-import { Transformer, compose } from '@atproto-labs/transformer'
-import { z } from 'zod'
+import { Transformer, pipe } from '@atproto-labs/pipe'
 
-import { FetchError, FetchErrorOptions } from './fetch-error.js'
-import { Json, ifObject, ifString } from './util.js'
+// optional dependency for typing purposes
+import type { ZodTypeAny, ParseParams, TypeOf } from 'zod'
+
+import { FetchError } from './fetch-error.js'
 import { TransformedResponse } from './transformed-response.js'
+import {
+  Json,
+  MaxBytesTransformStream,
+  cancelBody,
+  ifObject,
+  ifString,
+  logCancellationError,
+} from './util.js'
 
 export type ResponseTranformer = Transformer<Response>
 export type ResponseMessageGetter = Transformer<Response, string | undefined>
 
-const extractResponseMessage: ResponseMessageGetter = async (response) => {
-  if (!response.body) return undefined
+export class FetchResponseError extends FetchError {
+  constructor(
+    public readonly response: Response,
+    statusCode: number = response.status,
+    message: string = response.statusText,
+    options?: ErrorOptions,
+  ) {
+    super(statusCode, message, options)
+  }
 
-  const contentType = response.headers.get('content-type')
-  if (!contentType) return undefined
+  static async from(
+    response: Response,
+    customMessage: string | ResponseMessageGetter = extractResponseMessage,
+    statusCode = response.status,
+    options?: ErrorOptions,
+  ) {
+    const message =
+      typeof customMessage === 'string'
+        ? customMessage
+        : typeof customMessage === 'function'
+          ? await customMessage(response)
+          : undefined
+
+    return new FetchResponseError(response, statusCode, message, options)
+  }
+}
 
-  const mimeType = contentType.split(';')[0].trim()
+const extractResponseMessage: ResponseMessageGetter = async (response) => {
+  const mimeType = extractMime(response)
   if (!mimeType) return undefined
 
   try {
     if (mimeType === 'text/plain') {
       return await response.text()
     } else if (/^application\/(?:[^+]+\+)?json$/i.test(mimeType)) {
-      const json = await response.json()
+      const json: unknown = await response.json()
 
       if (typeof json === 'string') return json
 
@@ -41,127 +72,170 @@ const extractResponseMessage: ResponseMessageGetter = async (response) => {
   return undefined
 }
 
-export class FetchResponseError extends FetchError {
-  constructor(
-    response: Response,
-    statusCode: number = response.status,
-    message: string = response.statusText,
-    options?: Omit<FetchErrorOptions, 'response'>,
-  ) {
-    super(statusCode, message, { response, ...options })
+export async function peekJson(
+  response: Response,
+  maxSize = Infinity,
+): Promise<undefined | Json> {
+  const type = extractMime(response)
+  if (type !== 'application/json') return undefined
+  checkLength(response, maxSize)
+
+  // 1) Clone the request so we can consume the body
+  const clonedResponse = response.clone()
+
+  // 2) Make sure the request's body is not too large
+  const limitedResponse =
+    response.body && maxSize < Infinity
+      ? new TransformedResponse(
+          clonedResponse,
+          new MaxBytesTransformStream(maxSize),
+        )
+      : // Note: some runtimes (e.g. react-native) don't expose a body property
+        clonedResponse
+
+  // 3) Parse the JSON
+  return limitedResponse.json()
+}
+
+export function checkLength(response: Response, maxBytes: number) {
+  // Note: negation accounts for invalid value types (NaN, non numbers)
+  if (!(maxBytes >= 0)) {
+    throw new TypeError('maxBytes must be a non-negative number')
+  }
+  const length = extractLength(response)
+  if (length != null && length > maxBytes) {
+    throw new FetchResponseError(response, 502, 'Response too large')
   }
+  return length
+}
 
-  static async from(
-    response: Response,
-    statusCode = response.status,
-    customMessage: string | ResponseMessageGetter = extractResponseMessage,
-    options?: Omit<FetchErrorOptions, 'response'>,
-  ) {
-    const message =
-      typeof customMessage === 'string'
-        ? customMessage
-        : typeof customMessage === 'function'
-          ? await customMessage(response)
-          : undefined
+export function extractLength(response: Response) {
+  const contentLength = response.headers.get('Content-Length')
+  if (contentLength == null) return undefined
+  if (!/^\d+$/.test(contentLength)) {
+    throw new FetchResponseError(response, 502, 'Invalid Content-Length')
+  }
+  const length = Number(contentLength)
+  if (!Number.isSafeInteger(length)) {
+    throw new FetchResponseError(response, 502, 'Content-Length too large')
+  }
+  return length
+}
 
-    // Make sure the body gets consumed as, in some environments (Node 👀), the
-    // response will not automatically be GC'd.
-    if (!response.bodyUsed) await response.body?.cancel()
+export function extractMime(response: Response) {
+  const contentType = response.headers.get('Content-Type')
+  if (contentType == null) return undefined
 
-    return new FetchResponseError(response, statusCode, message, options)
+  return contentType.split(';', 1)[0]!.trim()
+}
+
+/**
+ * If the transformer results in an error, ensure that the response body is
+ * consumed as, in some environments (Node 👀), the response will not
+ * automatically be GC'd.
+ *
+ * @see {@link https://undici.nodejs.org/#/?id=garbage-collection}
+ * @param [onCancellationError] - Callback to handle any async body cancelling
+ * error. Defaults to logging the error. Do not use `null` if the request is
+ * cloned.
+ */
+export function cancelBodyOnError<T>(
+  transformer: Transformer<Response, T>,
+  onCancellationError: null | ((err: unknown) => void) = logCancellationError,
+): (response: Response) => Promise<T> {
+  return async (response) => {
+    try {
+      return await transformer(response)
+    } catch (err) {
+      await cancelBody(response, onCancellationError ?? undefined)
+      throw err
+    }
   }
 }
 
 export function fetchOkProcessor(
   customMessage?: string | ResponseMessageGetter,
 ): ResponseTranformer {
-  return async (response) => {
-    if (response.ok) return response
-    throw await FetchResponseError.from(response, undefined, customMessage)
-  }
+  return cancelBodyOnError((response) => {
+    return fetchOkTransformer(response, customMessage)
+  })
+}
+
+export async function fetchOkTransformer(
+  response: Response,
+  customMessage?: string | ResponseMessageGetter,
+) {
+  if (response.ok) return response
+  throw await FetchResponseError.from(response, customMessage)
 }
 
 export function fetchMaxSizeProcessor(maxBytes: number): ResponseTranformer {
   if (maxBytes === Infinity) return (response) => response
   if (!Number.isFinite(maxBytes) || maxBytes < 0) {
-    throw new TypeError('maxBytes must be a non-negative number')
+    throw new TypeError('maxBytes must be a 0, Infinity or a positive number')
   }
-  return async (response) => fetchResponseMaxSize(response, maxBytes)
+  return cancelBodyOnError((response) => {
+    return fetchResponseMaxSizeChecker(response, maxBytes)
+  })
 }
 
-export async function fetchResponseMaxSize(
+export function fetchResponseMaxSizeChecker(
   response: Response,
   maxBytes: number,
-): Promise<Response> {
+): Response {
   if (maxBytes === Infinity) return response
-  if (!response.body) return response
+  checkLength(response, maxBytes)
 
-  const contentLength = response.headers.get('content-length')
-  if (contentLength) {
-    const length = Number(contentLength)
-    if (!(length < maxBytes)) {
-      const err = new FetchResponseError(response, 502, 'Response too large')
-      await response.body.cancel(err)
-      throw err
-    }
-  }
-
-  let bytesRead = 0
-
-  const transform = new TransformStream<Uint8Array, Uint8Array>({
-    transform: (
-      chunk: Uint8Array,
-      ctrl: TransformStreamDefaultController<Uint8Array>,
-    ) => {
-      if ((bytesRead += chunk.length) <= maxBytes) {
-        ctrl.enqueue(chunk)
-      } else {
-        ctrl.error(new FetchResponseError(response, 502, 'Response too large'))
-      }
-    },
-  })
+  // Some engines (react-native 👀) don't expose a body property. In that case,
+  // we will only rely on the Content-Length header.
+  if (!response.body) return response
 
+  const transform = new MaxBytesTransformStream(maxBytes)
   return new TransformedResponse(response, transform)
 }
 
-export type ContentTypeCheckFn = (contentType: string) => boolean
-export type ContentTypeCheck = string | RegExp | ContentTypeCheckFn
+export type MimeTypeCheckFn = (mimeType: string) => boolean
+export type MimeTypeCheck = string | RegExp | MimeTypeCheckFn
 
 export function fetchTypeProcessor(
-  expectedType: ContentTypeCheck,
+  expectedMime: MimeTypeCheck,
   contentTypeRequired = true,
 ): ResponseTranformer {
-  const isExpected: ContentTypeCheckFn =
-    typeof expectedType === 'string'
-      ? (ct) => ct === expectedType
-      : expectedType instanceof RegExp
-        ? (ct) => expectedType.test(ct)
-        : expectedType
+  const isExpected: MimeTypeCheckFn =
+    typeof expectedMime === 'string'
+      ? (mimeType) => mimeType === expectedMime
+      : expectedMime instanceof RegExp
+        ? (mimeType) => expectedMime.test(mimeType)
+        : expectedMime
+
+  return cancelBodyOnError((response) => {
+    return fetchResponseTypeChecker(response, isExpected, contentTypeRequired)
+  })
+}
 
-  return async (response) => {
-    const contentType = response.headers
-      .get('content-type')
-      ?.split(';')[0]!
-      .trim()
-
-    if (contentType) {
-      if (!isExpected(contentType)) {
-        throw await FetchResponseError.from(
-          response,
-          502,
-          `Unexpected response Content-Type (${contentType})`,
-        )
-      }
-    } else if (contentTypeRequired) {
+export async function fetchResponseTypeChecker(
+  response: Response,
+  isExpectedMime: MimeTypeCheckFn,
+  contentTypeRequired = true,
+): Promise<Response> {
+  const mimeType = extractMime(response)
+  if (mimeType) {
+    if (!isExpectedMime(mimeType)) {
       throw await FetchResponseError.from(
         response,
+        `Unexpected response Content-Type (${mimeType})`,
         502,
-        'Missing response Content-Type header',
       )
     }
-
-    return response
+  } else if (contentTypeRequired) {
+    throw await FetchResponseError.from(
+      response,
+      'Missing response Content-Type header',
+      502,
+    )
   }
+
+  return response
 }
 
 export type ParsedJsonResponse<T = Json> = {
@@ -169,17 +243,9 @@ export type ParsedJsonResponse<T = Json> = {
   json: T
 }
 
-export async function jsonTranformer<T = Json>(
+export async function fetchResponseJsonTranformer<T = Json>(
   response: Response,
 ): Promise<ParsedJsonResponse<T>> {
-  if (response.body === null) {
-    throw new FetchResponseError(response, 502, 'No response body')
-  }
-
-  if (response.bodyUsed) {
-    throw new FetchResponseError(response, 500, 'Response body already used')
-  }
-
   try {
     const json = (await response.json()) as T
     return { response, json }
@@ -194,19 +260,19 @@ export async function jsonTranformer<T = Json>(
 }
 
 export function fetchJsonProcessor<T = Json>(
-  contentType: ContentTypeCheck = /^application\/(?:[^+]+\+)?json$/,
+  expectedMime: MimeTypeCheck = /^application\/(?:[^+]+\+)?json$/,
   contentTypeRequired = true,
 ): Transformer<Response, ParsedJsonResponse<T>> {
-  return compose(
-    fetchTypeProcessor(contentType, contentTypeRequired),
-    jsonTranformer<T>,
+  return pipe(
+    fetchTypeProcessor(expectedMime, contentTypeRequired),
+    cancelBodyOnError(fetchResponseJsonTranformer<T>),
   )
 }
 
-export function fetchJsonZodProcessor<S extends z.ZodTypeAny>(
+export function fetchJsonZodProcessor<S extends ZodTypeAny>(
   schema: S,
-  params?: Partial<z.ParseParams>,
-): Transformer<ParsedJsonResponse, z.infer<S>> {
-  return async (jsonResponse: ParsedJsonResponse): Promise<z.infer<S>> =>
+  params?: Partial<ParseParams>,
+): Transformer<ParsedJsonResponse, TypeOf<S>> {
+  return async (jsonResponse: ParsedJsonResponse): Promise<TypeOf<S>> =>
     schema.parseAsync(jsonResponse.json, params)
 }

package/src/fetch-wrap.ts

@@ -1,101 +1,150 @@
-import { Fetch } from './fetch.js'
+import { FetchRequestError } from './fetch-request.js'
+import { Fetch, FetchContext, toRequestTransformer } from './fetch.js'
 import { TransformedResponse } from './transformed-response.js'
-
-export const loggedFetchWrap = ({
-  fetch = globalThis.fetch as Fetch,
-} = {}): Fetch => {
-  return async function (request) {
-    return fetchLog.call(this, request, fetch)
-  }
-}
-
-async function fetchLog(
-  this: ThisParameterType<Fetch>,
-  request: Request,
-  fetch: Fetch = globalThis.fetch,
-) {
-  console.info(
-    `> ${request.method} ${request.url}\n` +
-      stringifyPayload(request.headers, await request.clone().text()),
-  )
-
-  try {
-    const response = await fetch(request)
-
-    console.info(
-      `< HTTP/1.1 ${response.status} ${response.statusText}\n` +
-        stringifyPayload(response.headers, await response.clone().text()),
-    )
-
-    return response
-  } catch (error) {
-    console.error(`< Error:`, error)
-
-    throw error
-  }
+import { padLines, stringifyMessage } from './util.js'
+
+type LogFn<Args extends unknown[]> = (...args: Args) => void | PromiseLike<void>
+
+export function loggedFetch<C = FetchContext>({
+  fetch = globalThis.fetch as Fetch<C>,
+  logRequest = true as boolean | LogFn<[request: Request]>,
+  logResponse = true as boolean | LogFn<[response: Response, request: Request]>,
+  logError = true as boolean | LogFn<[error: unknown, request: Request]>,
+}) {
+  const onRequest =
+    logRequest === true
+      ? async (request) => {
+          const requestMessage = await stringifyMessage(request)
+          console.info(
+            `> ${request.method} ${request.url}\n${padLines(requestMessage, '  ')}`,
+          )
+        }
+      : logRequest || undefined
+
+  const onResponse =
+    logResponse === true
+      ? async (response) => {
+          const responseMessage = await stringifyMessage(response.clone())
+          console.info(
+            `< HTTP/1.1 ${response.status} ${response.statusText}\n${padLines(responseMessage, '  ')}`,
+          )
+        }
+      : logResponse || undefined
+
+  const onError =
+    logError === true
+      ? async (error) => {
+          console.error(`< Error:`, error)
+        }
+      : logError || undefined
+
+  if (!onRequest && !onResponse && !onError) return fetch
+
+  return toRequestTransformer(async function (
+    this: C,
+    request,
+  ): Promise<Response> {
+    if (onRequest) await onRequest(request)
+
+    try {
+      const response = await fetch.call(this, request)
+
+      if (onResponse) await onResponse(response, request)
+
+      return response
+    } catch (error) {
+      if (onError) await onError(error, request)
+
+      throw error
+    }
+  })
 }
 
-const stringifyPayload = (headers: Headers, body: string) =>
-  [stringifyHeaders(headers), stringifyBody(body)]
-    .filter(Boolean)
-    .join('\n  ') + '\n  '
-
-const stringifyHeaders = (headers: Headers) =>
-  Array.from(headers)
-    .map(([name, value]) => `  ${name}: ${value}\n`)
-    .join('')
-
-const stringifyBody = (body: string) =>
-  body ? `\n  ${body.replace(/\r?\n/g, '\\n')}` : ''
-
-export const timeoutFetchWrap = ({
-  fetch = globalThis.fetch as Fetch,
+export const timedFetch = <C = FetchContext>(
   timeout = 60e3,
-} = {}): Fetch => {
+  fetch: Fetch<C> = globalThis.fetch,
+): Fetch<C> => {
   if (timeout === Infinity) return fetch
   if (!Number.isFinite(timeout) || timeout <= 0) {
     throw new TypeError('Timeout must be positive')
   }
-  return async function (request) {
-    return fetchTimeout.call(this, request, timeout, fetch)
-  }
+  return toRequestTransformer(async function (
+    this: C,
+    request,
+  ): Promise<Response> {
+    const controller = new AbortController()
+    const signal = controller.signal
+
+    const abort = () => {
+      controller.abort()
+    }
+    const cleanup = () => {
+      clearTimeout(timer)
+      request.signal?.removeEventListener('abort', abort)
+    }
+
+    const timer = setTimeout(abort, timeout)
+    if (typeof timer === 'object') timer.unref?.() // only on node
+    request.signal?.addEventListener('abort', abort)
+
+    signal.addEventListener('abort', cleanup)
+
+    const response = await fetch.call(this, request, { signal })
+
+    if (!response.body) {
+      cleanup()
+      return response
+    } else {
+      // Cleanup the timer & event listeners when the body stream is closed
+      const transform = new TransformStream({ flush: cleanup })
+      return new TransformedResponse(response, transform)
+    }
+  })
 }
 
-export async function fetchTimeout(
-  this: ThisParameterType<Fetch>,
-  request: Request,
-  timeout = 30e3,
-  fetch: Fetch = globalThis.fetch,
-): Promise<Response> {
-  if (timeout === Infinity) return fetch(request)
-  if (!Number.isFinite(timeout) || timeout <= 0) {
-    throw new TypeError('Timeout must be positive')
-  }
-
-  const controller = new AbortController()
-  const signal = controller.signal
-
-  const abort = () => {
-    controller.abort()
-  }
-  const cleanup = () => {
-    clearTimeout(timeoutId)
-    request.signal?.removeEventListener('abort', abort)
-  }
-
-  const timeoutId = setTimeout(abort, timeout).unref()
-  request.signal?.addEventListener('abort', abort)
-
-  signal.addEventListener('abort', cleanup)
-
-  const response = await fetch(new Request(request, { signal }))
-
-  if (!response.body) {
-    cleanup()
-    return response
-  } else {
-    // Cleanup the timer & event listeners when the body stream is closed
-    const transform = new TransformStream({ flush: cleanup })
-    return new TransformedResponse(response, transform)
-  }
+/**
+ * Wraps a fetch function to bind it to a specific context, and wrap any thrown
+ * errors into a FetchRequestError.
+ *
+ * @example
+ *
+ * ```ts
+ * class MyClient {
+ *   constructor(private fetch = globalThis.fetch) {}
+ *
+ *   async get(url: string) {
+ *     // This will generate an error, because the context used is not a
+ *     // FetchContext (it's a MyClient instance).
+ *     return this.fetch(url)
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ *
+ * ```ts
+ * class MyClient {
+ *   private fetch: Fetch<unknown>
+ *
+ *   constructor(fetch = globalThis.fetch) {
+ *     this.fetch = bindFetch(fetch)
+ *   }
+ *
+ *   async get(url: string) {
+ *     return this.fetch(url) // no more error
+ *   }
+ * }
+ * ```
+ */
+export function bindFetch<C = FetchContext>(
+  fetch: Fetch<C> = globalThis.fetch,
+  context: C = globalThis as C,
+) {
+  return toRequestTransformer(async (request) => {
+    try {
+      return await fetch.call(context, request)
+    } catch (err) {
+      throw FetchRequestError.from(request, err)
+    }
+  })
 }

package/src/fetch.ts

@@ -1,4 +1,39 @@
-export type Fetch = (
-  this: void | null | typeof globalThis,
-  input: Request,
+import { ThisParameterOverride } from './util.js'
+
+export type FetchContext = void | null | typeof globalThis
+
+export type FetchBound = (
+  input: string | URL | Request,
+  init?: RequestInit,
 ) => Promise<Response>
+
+// NOT using "typeof globalThis.fetch" here because "globalThis.fetch" does not
+// have a "this" parameter, while runtimes do ensure that "fetch" is called with
+// the correct "this" parameter (either null, undefined, or window).
+
+export type Fetch<C = FetchContext> = ThisParameterOverride<C, FetchBound>
+
+export type SimpleFetchBound = (input: Request) => Promise<Response>
+export type SimpleFetch<C = FetchContext> = ThisParameterOverride<
+  C,
+  SimpleFetchBound
+>
+
+export function toRequestTransformer<C, O>(
+  requestTransformer: (this: C, input: Request) => O,
+): ThisParameterOverride<
+  C,
+  (input: string | URL | Request, init?: RequestInit) => O
+> {
+  return function (this: C, input, init) {
+    return requestTransformer.call(this, asRequest(input, init))
+  }
+}
+
+export function asRequest(
+  input: string | URL | Request,
+  init?: RequestInit,
+): Request {
+  if (!init && input instanceof Request) return input
+  return new Request(input, init)
+}

package/src/transformed-response.ts

@@ -2,11 +2,14 @@ export class TransformedResponse extends Response {
   #response: Response
 
   constructor(response: Response, transform: TransformStream) {
-    if (response.body && response.bodyUsed) {
+    if (!response.body) {
+      throw new TypeError('Response body is not available')
+    }
+    if (response.bodyUsed) {
       throw new TypeError('Response body is already used')
     }
 
-    super(response.body?.pipeThrough(transform) ?? null, {
+    super(response.body.pipeThrough(transform), {
       status: response.status,
       statusText: response.statusText,
       headers: response.headers,