feat: new invoke syntax

Author: soedirgo

src/FunctionsClient.ts

@@ -0,0 +1,115 @@
+import { resolveFetch } from './helper'
+import {
+  Fetch,
+  FunctionsFetchError,
+  FunctionsHttpError,
+  FunctionsRelayError,
+  FunctionsResponse,
+} from './types'
+
+export class FunctionsClient {
+  protected url: string
+  protected headers: Record<string, string>
+  protected fetch: Fetch
+
+  constructor(
+    url: string,
+    {
+      headers = {},
+      customFetch,
+    }: {
+      headers?: Record<string, string>
+      customFetch?: Fetch
+    } = {}
+  ) {
+    this.url = url
+    this.headers = headers
+    this.fetch = resolveFetch(customFetch)
+  }
+
+  /**
+   * Updates the authorization header
+   * @params token - the new jwt token sent in the authorisation header
+   */
+  setAuth(token: string) {
+    this.headers.Authorization = `Bearer ${token}`
+  }
+
+  /**
+   * Invokes a function
+   * @param functionName - the name of the function to invoke
+   * @param functionArgs - the arguments to the function
+   * @param options - function invoke options
+   * @param options.headers - headers to send with the request
+   */
+  async invoke(
+    functionName: string,
+    functionArgs: any,
+    {
+      headers = {},
+    }: {
+      headers?: Record<string, string>
+    } = {}
+  ): Promise<FunctionsResponse> {
+    try {
+      let _headers: Record<string, string> = {}
+      let body: any
+      if (functionArgs instanceof Blob || functionArgs instanceof ArrayBuffer) {
+        // will work for File as File inherits Blob
+        // also works for ArrayBuffer as it is the same underlying structure as a Blob
+        _headers['Content-Type'] = 'application/octet-stream'
+        body = functionArgs
+      } else if (typeof functionArgs === 'string') {
+        // plain string
+        _headers['Content-Type'] = 'text/plain'
+        body = functionArgs
+      } else if (functionArgs instanceof FormData) {
+        // don't set content-type headers
+        // Request will automatically add the right boundary value
+        body = functionArgs
+      } else {
+        // default, assume this is JSON
+        _headers['Content-Type'] = 'application/json'
+        body = JSON.stringify(functionArgs)
+      }
+
+      const response = await this.fetch(`${this.url}/${functionName}`, {
+        method: 'POST',
+        // headers priority is (high to low):
+        // 1. invoke-level headers
+        // 2. client-level headers
+        // 3. default Content-Type header
+        headers: { ..._headers, ...this.headers, ...headers },
+        body,
+      }).catch((fetchError) => {
+        throw new FunctionsFetchError(fetchError)
+      })
+
+      const isRelayError = response.headers.get('x-relay-error')
+      if (isRelayError && isRelayError === 'true') {
+        throw new FunctionsRelayError(response)
+      }
+
+      if (!response.ok) {
+        throw new FunctionsHttpError(response)
+      }
+
+      let responseType = (response.headers.get('Content-Type') ?? 'text/plain').split(';')[0].trim()
+      let data: any
+      if (responseType === 'application/json') {
+        data = await response.json()
+      } else if (responseType === 'application/octet-stream') {
+        data = await response.blob()
+      } else if (responseType === 'multipart/form-data') {
+        data = await response.formData()
+      } else {
+        // default to text
+        data = await response.text()
+      }
+
+      return { data, error: null }
+    } catch (error) {
+      return { data: null, error }
+    }
+  }
+}

src/helper.ts

@@ -1,4 +1,4 @@
-type Fetch = typeof fetch
+import { Fetch } from './types'
 
 export const resolveFetch = (customFetch?: Fetch): Fetch => {
   let _fetch: Fetch

src/index.ts

@@ -1,70 +1,8 @@
-import { resolveFetch } from './helper'
-import { Fetch, FunctionInvokeOptions } from './types'
-
-export class FunctionsClient {
-  protected url: string
-  protected headers: Record<string, string>
-  protected fetch: Fetch
-
-  constructor(
-    url: string,
-    {
-      headers = {},
-      customFetch,
-    }: {
-      headers?: Record<string, string>
-      customFetch?: Fetch
-    } = {}
-  ) {
-    this.url = url
-    this.headers = headers
-    this.fetch = resolveFetch(customFetch)
-  }
-
-  /**
-   * Updates the authorization header
-   * @params token - the new jwt token sent in the authorisation header
-   */
-  setAuth(token: string) {
-    this.headers.Authorization = `Bearer ${token}`
-  }
-
-  /**
-   * Invokes a function
-   * @param functionName - the name of the function to invoke
-   */
-  async invoke<T = any>(
-    functionName: string,
-    invokeOptions?: FunctionInvokeOptions
-  ): Promise<{ data: T; error: null } | { data: null; error: Error }> {
-    try {
-      const { headers, body } = invokeOptions ?? {}
-      const response = await this.fetch(`${this.url}/${functionName}`, {
-        method: 'POST',
-        headers: Object.assign({}, this.headers, headers),
-        body,
-      })
-
-      const isRelayError = response.headers.get('x-relay-error')
-      if (isRelayError && isRelayError === 'true') {
-        return { data: null, error: new Error(await response.text()) }
-      }
-
-      let data
-      const { responseType } = invokeOptions ?? {}
-      if (!responseType || responseType === 'json') {
-        data = await response.json()
-      } else if (responseType === 'arrayBuffer') {
-        data = await response.arrayBuffer()
-      } else if (responseType === 'blob') {
-        data = await response.blob()
-      } else {
-        data = await response.text()
-      }
-
-      return { data, error: null }
-    } catch (error: any) {
-      return { data: null, error }
-    }
-  }
-}
+export { FunctionsClient } from './FunctionsClient'
+export {
+  FunctionsError,
+  FunctionsFetchError,
+  FunctionsHttpError,
+  FunctionsRelayError,
+  FunctionsResponse,
+} from './types'

src/types.ts

@@ -1,17 +1,42 @@
 export type Fetch = typeof fetch
 
-export enum ResponseType {
-  json,
-  text,
-  arrayBuffer,
-  blob,
+/**
+ * Response format
+ *
+ */
+interface FunctionsResponseSuccess {
+  data: any
+  error: null
+}
+interface FunctionsResponseFailure {
+  data: null
+  error: any
+}
+export type FunctionsResponse = FunctionsResponseSuccess | FunctionsResponseFailure
+
+export class FunctionsError extends Error {
+  context: any
+  constructor(message: string, name = 'FunctionsError', context?: any) {
+    super(message)
+    super.name = name
+    this.context = context
+  }
+}
+
+export class FunctionsFetchError extends FunctionsError {
+  constructor(context: any) {
+    super('Failed to perform request to Edge Function', 'FunctionsFetchError', context)
+  }
+}
+
+export class FunctionsRelayError extends FunctionsError {
+  constructor(context: any) {
+    super('Relay error communicating with deno backend', 'FunctionsRelayError', context)
+  }
 }
 
-export type FunctionInvokeOptions = {
-  /** object representing the headers to send with the request */
-  headers?: { [key: string]: string }
-  /** the body of the request */
-  body?: Blob | BufferSource | FormData | URLSearchParams | ReadableStream<Uint8Array> | string
-  /** how the response should be parsed. The default is `json` */
-  responseType?: keyof typeof ResponseType
+export class FunctionsHttpError extends FunctionsError {
+  constructor(context: any) {
+    super('Edge Function returned a non-2xx status code', 'FunctionsHttpError', context)
+  }
 }