@atproto-labs/fetch 0.0.1 → 0.1.0

package/src/fetch-wrap.ts

@@ -1,101 +1,122 @@
-import { Fetch } from './fetch.js'
+import { FetchRequestError } from './fetch-request.js'
+import { Fetch, FetchContext, toRequestTransformer } from './fetch.js'
 import { TransformedResponse } from './transformed-response.js'
+import { padLines, stringifyMessage } from './util.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,
+export function loggedFetch<C = FetchContext>(
+  fetch: Fetch<C> = globalThis.fetch,
 ) {
-  console.info(
-    `> ${request.method} ${request.url}\n` +
-      stringifyPayload(request.headers, await request.clone().text()),
-  )
-
-  try {
-    const response = await fetch(request)
-
+  return toRequestTransformer(async function (
+    this: C,
+    request,
+  ): Promise<Response> {
+    const requestMessage = await stringifyMessage(request)
     console.info(
-      `< HTTP/1.1 ${response.status} ${response.statusText}\n` +
-        stringifyPayload(response.headers, await response.clone().text()),
+      `> ${request.method} ${request.url}\n${padLines(requestMessage, '  ')}`,
     )
 
-    return response
-  } catch (error) {
-    console.error(`< Error:`, error)
-
-    throw error
-  }
-}
+    try {
+      const response = await fetch.call(this, request)
 
-const stringifyPayload = (headers: Headers, body: string) =>
-  [stringifyHeaders(headers), stringifyBody(body)]
-    .filter(Boolean)
-    .join('\n  ') + '\n  '
+      const responseMessage = await stringifyMessage(response.clone())
+      console.info(
+        `< HTTP/1.1 ${response.status} ${response.statusText}\n${padLines(responseMessage, '  ')}`,
+      )
 
-const stringifyHeaders = (headers: Headers) =>
-  Array.from(headers)
-    .map(([name, value]) => `  ${name}: ${value}\n`)
-    .join('')
+      return response
+    } catch (error) {
+      console.error(`< Error:`, error)
 
-const stringifyBody = (body: string) =>
-  body ? `\n  ${body.replace(/\r?\n/g, '\\n')}` : ''
+      throw error
+    }
+  })
+}
 
-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,

package/src/util.ts

@@ -1,15 +1,18 @@
-// TODO: Move to a shared package ?
+// @TODO: Move some of these to a shared package ?
 
 export type JsonScalar = string | number | boolean | null
 export type Json = JsonScalar | Json[] | { [key: string]: undefined | Json }
 export type JsonObject = { [key: string]: Json }
 export type JsonArray = Json[]
 
-declare global {
-  interface JSON {
-    parse(text: string, reviver?: (key: any, value: any) => any): Json
-  }
-}
+export type ThisParameterOverride<
+  C,
+  Fn extends (...a: any) => any,
+> = Fn extends (...args: infer P) => infer R
+  ? ((this: C, ...args: P) => R) & {
+      bind(context: C): (...args: P) => R
+    }
+  : never
 
 export function isIp(hostname: string) {
   // IPv4
@@ -21,10 +24,8 @@ export function isIp(hostname: string) {
   return false
 }
 
-// TODO: Move to a shared package ?
-
 const plainObjectProto = Object.prototype
-export const ifObject = <V>(v?: V) => {
+export const ifObject = <V>(v: V) => {
   if (typeof v === 'object' && v != null && !Array.isArray(v)) {
     const proto = Object.getPrototypeOf(v)
     if (proto === null || proto === plainObjectProto) {
@@ -33,27 +34,136 @@ export const ifObject = <V>(v?: V) => {
         ? never
         : V extends Json
           ? V
-          : // Plain object are (mostly) safe to access as Json
-            { [key: string]: unknown }
+          : // Plain object are (mostly) safe to access using a string index
+            Record<string, unknown>
     }
   }
 
   return undefined
 }
 
-export const ifArray = <V>(v?: V) => (Array.isArray(v) ? v : undefined)
-export const ifScalar = <V>(v?: V) => {
-  switch (typeof v) {
-    case 'string':
-    case 'number':
-    case 'boolean':
-      return v
-    default:
-      if (v === null) return null as V & null
-      return undefined as V extends JsonScalar ? never : undefined
+export const ifString = <V>(v: V) => (typeof v === 'string' ? v : undefined)
+
+export class MaxBytesTransformStream extends TransformStream<
+  Uint8Array,
+  Uint8Array
+> {
+  constructor(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')
+    }
+
+    let bytesRead = 0
+
+    super({
+      transform: (
+        chunk: Uint8Array,
+        ctrl: TransformStreamDefaultController<Uint8Array>,
+      ) => {
+        if ((bytesRead += chunk.length) <= maxBytes) {
+          ctrl.enqueue(chunk)
+        } else {
+          ctrl.error(new Error('Response too large'))
+        }
+      },
+    })
+  }
+}
+
+const LINE_BREAK = /\r?\n/g
+export function padLines(input: string, pad: string) {
+  if (!input) return input
+  return pad + input.replace(LINE_BREAK, `$&${pad}`)
+}
+
+/**
+ * @param [onCancellationError] - Callback that will trigger to asynchronously
+ * handle any error that occurs while cancelling the response body. Providing
+ * this will speed up the process and avoid potential deadlocks. Defaults to
+ * awaiting the cancellation operation. use `"log"` to log the error.
+ * @see {@link https://undici.nodejs.org/#/?id=garbage-collection}
+ * @note awaiting this function's result, when no `onCancellationError` is
+ * provided, might result in a dead lock. Indeed, if the response was cloned(),
+ * the response.body.cancel() method will not resolve until the other response's
+ * body is consumed/cancelled.
+ *
+ * @example
+ * ```ts
+ * // Make sure response was not cloned, or that every cloned response was
+ * // consumed/cancelled before awaiting this function's result.
+ * await cancelBody(response)
+ * ```
+ * @example
+ * ```ts
+ * await cancelBody(response, (err) => {
+ *   // No biggie, let's just log the error
+ *   console.warn('Failed to cancel response body', err)
+ * })
+ * ```
+ * @example
+ * ```ts
+ * // Will generate an "unhandledRejection" if an error occurs while cancelling
+ * // the response body. This will likely crash the process.
+ * await cancelBody(response, (err) => { throw err })
+ * ```
+ */
+export async function cancelBody(
+  body: Body,
+  onCancellationError?: 'log' | ((err: unknown) => void),
+): Promise<void> {
+  if (
+    body.body &&
+    !body.bodyUsed &&
+    !body.body.locked &&
+    // Support for alternative fetch implementations
+    typeof body.body.cancel === 'function'
+  ) {
+    if (typeof onCancellationError === 'function') {
+      void body.body.cancel().catch(onCancellationError)
+    } else if (onCancellationError === 'log') {
+      void body.body.cancel().catch(logCancellationError)
+    } else {
+      await body.body.cancel()
+    }
+  }
+}
+
+export function logCancellationError(err: unknown): void {
+  console.warn('Failed to cancel response body', err)
+}
+
+export async function stringifyMessage(input: Body & { headers: Headers }) {
+  try {
+    const headers = stringifyHeaders(input.headers)
+    const payload = await stringifyBody(input)
+    return headers && payload ? `${headers}\n${payload}` : headers || payload
+  } finally {
+    void cancelBody(input, 'log')
+  }
+}
+
+function stringifyHeaders(headers: Headers) {
+  return Array.from(headers)
+    .map(([name, value]) => `${name}: ${value}`)
+    .join('\n')
+}
+
+async function stringifyBody(body: Body) {
+  try {
+    const blob = await body.blob()
+    if (blob.type?.startsWith('text/')) {
+      const text = await blob.text()
+      return JSON.stringify(text)
+    }
+
+    if (/application\/(?:\w+\+)?json/.test(blob.type)) {
+      const text = await blob.text()
+      return text.includes('\n') ? JSON.stringify(JSON.parse(text)) : text
+    }
+
+    return `[Body size: ${blob.size}, type: ${JSON.stringify(blob.type)} ]`
+  } catch {
+    return '[Body could not be read]'
   }
 }
-export const ifBoolean = <V>(v?: V) => (typeof v === 'boolean' ? v : undefined)
-export const ifString = <V>(v?: V) => (typeof v === 'string' ? v : undefined)
-export const ifNumber = <V>(v?: V) => (typeof v === 'number' ? v : undefined)
-export const ifNull = <V>(v?: V) => (v === null ? v : undefined)

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": ["../../../tsconfig/isomorphic.json"],
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/tsconfig.json

@@ -1,8 +1,4 @@
 {
-  "extends": "../../tsconfig/isomorphic.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src"]
+  "include": [],
+  "references": [{ "path": "./tsconfig.build.json" }]
 }