acrylblends 0.3.0 → 0.4.0

package/plugins/acryl-router/src/core/context.ts

@@ -0,0 +1,781 @@
+import { AppRequest } from './request.ts'
+import type { Result } from './router.ts'
+import type {
+  Env,
+  FetchEventLike,
+  H,
+  Input,
+  NotFoundHandler,
+  RouterRoute,
+  TypedResponse,
+} from './types.ts'
+import type { ResponseHeader } from './utils/headers.ts'
+import { HtmlEscapedCallbackPhase, resolveCallback } from './utils/html.ts'
+import type { ContentfulStatusCode, RedirectStatusCode, StatusCode } from './utils/http-status.ts'
+import type { BaseMime } from './utils/mime.ts'
+import type { InvalidJSONValue, IsAny, JSONParsed, JSONValue } from './utils/types.ts'
+
+type HeaderRecord =
+  | Record<'Content-Type', BaseMime>
+  | Record<ResponseHeader, string | string[]>
+  | Record<string, string | string[]>
+
+/**
+ * Data type can be a string, ArrayBuffer, Blob, Uint8Array (buffer), or ReadableStream.
+ */
+export type Data = string | ArrayBuffer | Blob | ReadableStream | Uint8Array<ArrayBuffer>
+
+/**
+ * Interface for the execution context in a web worker or similar environment.
+ */
+export interface ExecutionContext {
+  /**
+   * Extends the lifetime of the event callback until the promise is settled.
+   *
+   * @param promise - A promise to wait for.
+   */
+  waitUntil(promise: Promise<unknown>): void
+  /**
+   * Allows the event to be passed through to subsequent event listeners.
+   */
+  passThroughOnException(): void
+  /**
+   * For compatibility with Wrangler 4.x.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  props: any
+  /**
+   * For compatibility with Wrangler 4.x.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  exports?: any
+}
+
+/**
+ * Interface for context variable mapping.
+ */
+export interface ContextVariableMap {}
+
+/**
+ * Interface for context renderer.
+ */
+export interface ContextRenderer {}
+
+/**
+ * Interface representing a renderer for content.
+ *
+ * @interface DefaultRenderer
+ * @param {string | Promise<string>} content - The content to be rendered, which can be either a string or a Promise resolving to a string.
+ * @returns {Response | Promise<Response>} - The response after rendering the content, which can be either a Response or a Promise resolving to a Response.
+ */
+interface DefaultRenderer {
+  (content: string | Promise<string>): Response | Promise<Response>
+}
+
+/**
+ * Renderer type which can either be a ContextRenderer or DefaultRenderer.
+ */
+export type Renderer = ContextRenderer extends Function ? ContextRenderer : DefaultRenderer
+
+/**
+ * Extracts the props for the renderer.
+ */
+export type PropsForRenderer = [...Required<Parameters<Renderer>>] extends [unknown, infer Props]
+  ? Props
+  : unknown
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Layout<T = Record<string, any>> = (props: T) => any
+
+/**
+ * Interface for getting context variables.
+ *
+ * @template E - Environment type.
+ */
+interface Get<E extends Env> {
+  <Key extends keyof E['Variables']>(key: Key): E['Variables'][Key]
+  <Key extends keyof ContextVariableMap>(key: Key): ContextVariableMap[Key]
+}
+
+/**
+ * Interface for setting context variables.
+ *
+ * @template E - Environment type.
+ */
+interface Set<E extends Env> {
+  <Key extends keyof E['Variables']>(key: Key, value: E['Variables'][Key]): void
+  <Key extends keyof ContextVariableMap>(key: Key, value: ContextVariableMap[Key]): void
+}
+
+/**
+ * Interface for creating a new response.
+ */
+interface NewResponse {
+  (data: Data | null, status?: StatusCode, headers?: HeaderRecord): Response
+  (data: Data | null, init?: ResponseOrInit): Response
+}
+
+/**
+ * Interface for responding with a body.
+ */
+interface BodyRespond {
+  // if we return content, only allow the status codes that allow for returning the body
+  <T extends Data, U extends ContentfulStatusCode>(
+    data: T,
+    status?: U,
+    headers?: HeaderRecord
+  ): Response & TypedResponse<T, U, 'body'>
+  <T extends Data, U extends ContentfulStatusCode>(
+    data: T,
+    init?: ResponseOrInit<U>
+  ): Response & TypedResponse<T, U, 'body'>
+  <T extends null, U extends StatusCode>(
+    data: T,
+    status?: U,
+    headers?: HeaderRecord
+  ): Response & TypedResponse<null, U, 'body'>
+  <T extends null, U extends StatusCode>(
+    data: T,
+    init?: ResponseOrInit<U>
+  ): Response & TypedResponse<null, U, 'body'>
+}
+
+/**
+ * Interface for responding with text.
+ *
+ * @interface TextRespond
+ * @template T - The type of the text content.
+ * @template U - The type of the status code.
+ *
+ * @param {T} text - The text content to be included in the response.
+ * @param {U} [status] - An optional status code for the response.
+ * @param {HeaderRecord} [headers] - An optional record of headers to include in the response.
+ *
+ * @returns {Response & TypedResponse<T, U, 'text'>} - The response after rendering the text content, typed with the provided text and status code types.
+ */
+interface TextRespond {
+  <T extends string, U extends ContentfulStatusCode = ContentfulStatusCode>(
+    text: T,
+    status?: U,
+    headers?: HeaderRecord
+  ): Response & TypedResponse<T, U, 'text'>
+  <T extends string, U extends ContentfulStatusCode = ContentfulStatusCode>(
+    text: T,
+    init?: ResponseOrInit<U>
+  ): Response & TypedResponse<T, U, 'text'>
+}
+
+/**
+ * Interface for responding with JSON.
+ *
+ * @interface JSONRespond
+ * @template T - The type of the JSON value or simplified unknown type.
+ * @template U - The type of the status code.
+ *
+ * @param {T} object - The JSON object to be included in the response.
+ * @param {U} [status] - An optional status code for the response.
+ * @param {HeaderRecord} [headers] - An optional record of headers to include in the response.
+ *
+ * @returns {JSONRespondReturn<T, U>} - The response after rendering the JSON object, typed with the provided object and status code types.
+ */
+interface JSONRespond {
+  <
+    T extends JSONValue | {} | InvalidJSONValue,
+    U extends ContentfulStatusCode = ContentfulStatusCode,
+  >(
+    object: T,
+    status?: U,
+    headers?: HeaderRecord
+  ): JSONRespondReturn<T, U>
+  <
+    T extends JSONValue | {} | InvalidJSONValue,
+    U extends ContentfulStatusCode = ContentfulStatusCode,
+  >(
+    object: T,
+    init?: ResponseOrInit<U>
+  ): JSONRespondReturn<T, U>
+}
+
+/**
+ * @template T - The type of the JSON value or simplified unknown type.
+ * @template U - The type of the status code.
+ *
+ * @returns {Response & TypedResponse<JSONParsed<T>, U, 'json'>} - The response after rendering the JSON object, typed with the provided object and status code types.
+ */
+type JSONRespondReturn<
+  T extends JSONValue | {} | InvalidJSONValue,
+  U extends ContentfulStatusCode,
+> = Response & TypedResponse<JSONParsed<T>, U, 'json'>
+
+/**
+ * Interface representing a function that responds with HTML content.
+ *
+ * @param html - The HTML content to respond with, which can be a string or a Promise that resolves to a string.
+ * @param status - (Optional) The HTTP status code for the response.
+ * @param headers - (Optional) A record of headers to include in the response.
+ * @param init - (Optional) The response initialization object.
+ *
+ * @returns A Response object or a Promise that resolves to a Response object.
+ */
+interface HTMLRespond {
+  <T extends string | Promise<string>>(
+    html: T,
+    status?: ContentfulStatusCode,
+    headers?: HeaderRecord
+  ): T extends string ? Response : Promise<Response>
+  <T extends string | Promise<string>>(
+    html: T,
+    init?: ResponseOrInit<ContentfulStatusCode>
+  ): T extends string ? Response : Promise<Response>
+}
+
+/**
+ * Options for configuring the context.
+ *
+ * @template E - Environment type.
+ */
+type ContextOptions<E extends Env> = {
+  /**
+   * Bindings for the environment.
+   */
+  env: E['Bindings']
+  /**
+   * Execution context for the request.
+   */
+  executionCtx?: FetchEventLike | ExecutionContext | undefined
+  /**
+   * Handler for not found responses.
+   */
+  notFoundHandler?: NotFoundHandler<E>
+  matchResult?: Result<[H, RouterRoute]>
+  path?: string
+}
+
+interface SetHeadersOptions {
+  append?: boolean
+}
+
+interface SetHeaders {
+  (name: 'Content-Type', value?: BaseMime, options?: SetHeadersOptions): void
+  (name: ResponseHeader, value?: string, options?: SetHeadersOptions): void
+  (name: string, value?: string, options?: SetHeadersOptions): void
+}
+
+type ResponseHeadersInit =
+  | [string, string][]
+  | Record<'Content-Type', BaseMime>
+  | Record<ResponseHeader, string>
+  | Record<string, string>
+  | Headers
+
+interface ResponseInit<T extends StatusCode = StatusCode> {
+  headers?: ResponseHeadersInit
+  status?: T
+  statusText?: string
+}
+
+type ResponseOrInit<T extends StatusCode = StatusCode> = ResponseInit<T> | Response
+
+export const TEXT_PLAIN = 'text/plain; charset=UTF-8'
+
+const setDefaultContentType = (contentType: string, headers?: HeaderRecord): HeaderRecord => {
+  return {
+    'Content-Type': contentType,
+    ...headers,
+  }
+}
+
+const createResponseInstance = (
+  body?: BodyInit | null | undefined,
+  init?: globalThis.ResponseInit
+): Response => new Response(body, init)
+
+export class Context<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  E extends Env = any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  P extends string = any,
+  I extends Input = {},
+> {
+  #rawRequest: Request
+  #req: AppRequest<P, I['out']> | undefined
+  /**
+   * `.env` can get bindings (environment variables, secrets, KV namespaces, D1 database, R2 bucket etc.) in Cloudflare Workers.
+   *
+   *
+   * @example
+   * ```ts
+   * // Environment object for Cloudflare Workers
+   * app.get('*', async c => {
+   *   const counter = c.env.COUNTER
+   * })
+   * ```
+   */
+  env: E['Bindings'] = {}
+  #var: Map<unknown, unknown> | undefined
+  finalized: boolean = false
+  /**
+   * `.error` can get the error object from the middleware if the Handler throws an error.
+   *
+   *
+   * @example
+   * ```ts
+   * app.use('*', async (c, next) => {
+   *   await next()
+   *   if (c.error) {
+   *     // do something...
+   *   }
+   * })
+   * ```
+   */
+  error: Error | undefined
+
+  #status: StatusCode | undefined
+  #executionCtx: FetchEventLike | ExecutionContext | undefined
+  #res: Response | undefined
+  #layout: Layout<PropsForRenderer & { Layout: Layout }> | undefined
+  #renderer: Renderer | undefined
+  #notFoundHandler: NotFoundHandler<E> | undefined
+  #preparedHeaders: Headers | undefined
+
+  #matchResult: Result<[H, RouterRoute]> | undefined
+  #path: string | undefined
+
+  /**
+   * Creates an instance of the Context class.
+   *
+   * @param req - The Request object.
+   * @param options - Optional configuration options for the context.
+   */
+  constructor(req: Request, options?: ContextOptions<E>) {
+    this.#rawRequest = req
+    if (options) {
+      this.#executionCtx = options.executionCtx
+      this.env = options.env
+      this.#notFoundHandler = options.notFoundHandler
+      this.#path = options.path
+      this.#matchResult = options.matchResult
+    }
+  }
+
+  /**
+   * `.req` is the instance of {@link AppRequest}.
+   */
+  get req(): AppRequest<P, I['out']> {
+    this.#req ??= new AppRequest(this.#rawRequest, this.#path, this.#matchResult)
+    return this.#req
+  }
+
+  /**
+   * The FetchEvent associated with the current request.
+   *
+   * @throws Will throw an error if the context does not have a FetchEvent.
+   */
+  get event(): FetchEventLike {
+    if (this.#executionCtx && 'respondWith' in this.#executionCtx) {
+      return this.#executionCtx
+    } else {
+      throw Error('This context has no FetchEvent')
+    }
+  }
+
+  /**
+   * The ExecutionContext associated with the current request.
+   *
+   * @throws Will throw an error if the context does not have an ExecutionContext.
+   */
+  get executionCtx(): ExecutionContext {
+    if (this.#executionCtx) {
+      return this.#executionCtx as ExecutionContext
+    } else {
+      throw Error('This context has no ExecutionContext')
+    }
+  }
+
+  /**
+   * The Response object for the current request.
+   */
+  get res(): Response {
+    return (this.#res ||= createResponseInstance(null, {
+      headers: (this.#preparedHeaders ??= new Headers()),
+    }))
+  }
+
+  /**
+   * Sets the Response object for the current request.
+   *
+   * @param _res - The Response object to set.
+   */
+  set res(_res: Response | undefined) {
+    if (this.#res && _res) {
+      _res = createResponseInstance(_res.body, _res)
+      for (const [k, v] of this.#res.headers.entries()) {
+        if (k === 'content-type') {
+          continue
+        }
+        if (k === 'set-cookie') {
+          const cookies = this.#res.headers.getSetCookie()
+          _res.headers.delete('set-cookie')
+          for (const cookie of cookies) {
+            _res.headers.append('set-cookie', cookie)
+          }
+        } else {
+          _res.headers.set(k, v)
+        }
+      }
+    }
+    this.#res = _res
+    this.finalized = true
+  }
+
+  /**
+   * `.render()` can create a response within a layout.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/', (c) => {
+   *   return c.render('Hello!')
+   * })
+   * ```
+   */
+  render: Renderer = (...args) => {
+    this.#renderer ??= (content: string | Promise<string>) => this.html(content)
+    return this.#renderer(...args)
+  }
+
+  /**
+   * Sets the layout for the response.
+   *
+   * @param layout - The layout to set.
+   * @returns The layout function.
+   */
+  setLayout = (
+    layout: Layout<PropsForRenderer & { Layout: Layout }>
+  ): Layout<
+    PropsForRenderer & {
+      Layout: Layout
+    }
+  > => (this.#layout = layout)
+
+  /**
+   * Gets the current layout for the response.
+   *
+   * @returns The current layout function.
+   */
+  getLayout = (): Layout<PropsForRenderer & { Layout: Layout }> | undefined => this.#layout
+
+  /**
+   * `.setRenderer()` can set the layout in the custom middleware.
+   *
+   *
+   * @example
+   * ```tsx
+   * app.use('*', async (c, next) => {
+   *   c.setRenderer((content) => {
+   *     return c.html(
+   *       <html>
+   *         <body>
+   *           <p>{content}</p>
+   *         </body>
+   *       </html>
+   *     )
+   *   })
+   *   await next()
+   * })
+   * ```
+   */
+  setRenderer = (renderer: Renderer): void => {
+    this.#renderer = renderer
+  }
+
+  /**
+   * `.header()` can set headers.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/welcome', (c) => {
+   *   // Set headers
+   *   c.header('X-Message', 'Hello!')
+   *   c.header('Content-Type', 'text/plain')
+   *
+   *   // Append multiple headers using the append option (e.g. Vary)
+   *   c.header('Vary', 'Accept-Encoding', { append: true })
+   *   c.header('Vary', 'User-Agent', { append: true })
+   *
+   *   return c.body('Thank you for coming')
+   * })
+   * ```
+   */
+  header: SetHeaders = (name, value, options): void => {
+    if (this.finalized) {
+      this.#res = createResponseInstance((this.#res as Response).body, this.#res)
+    }
+    const headers = this.#res ? this.#res.headers : (this.#preparedHeaders ??= new Headers())
+    if (value === undefined) {
+      headers.delete(name)
+    } else if (options?.append) {
+      headers.append(name, value)
+    } else {
+      headers.set(name, value)
+    }
+  }
+
+  status = (status: StatusCode): void => {
+    this.#status = status
+  }
+
+  /**
+   * `.set()` can set the value specified by the key.
+   *
+   *
+   * @example
+   * ```ts
+   * app.use('*', async (c, next) => {
+   *   c.set('message', 'App is hot!!')
+   *   await next()
+   * })
+   * ```
+   */
+  set: Set<
+    IsAny<E> extends true
+      ? {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          Variables: ContextVariableMap & Record<PropertyKey, any>
+        }
+      : E
+  > = (key: PropertyKey, value: unknown) => {
+    this.#var ??= new Map()
+    this.#var.set(key, value)
+  }
+
+  /**
+   * `.get()` can use the value specified by the key.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/', (c) => {
+   *   const message = c.get('message')
+   *   return c.text(`The message is "${message}"`)
+   * })
+   * ```
+   */
+  get: Get<
+    IsAny<E> extends true
+      ? {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          Variables: ContextVariableMap & Record<PropertyKey, any>
+        }
+      : E
+  > = (key: PropertyKey) => {
+    return this.#var ? this.#var.get(key) : undefined
+  }
+
+  /**
+   * `.var` can access the value of a variable.
+   *
+   *
+   * @example
+   * ```ts
+   * const result = c.var.client.oneMethod()
+   * ```
+   */
+  // c.var.propName is a read-only
+  get var(): Readonly<
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ContextVariableMap & (IsAny<E['Variables']> extends true ? Record<string, any> : E['Variables'])
+  > {
+    if (!this.#var) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      return {} as any
+    }
+    return Object.fromEntries(this.#var)
+  }
+
+  #newResponse(
+    data: Data | null,
+    arg?: StatusCode | ResponseOrInit,
+    headers?: HeaderRecord
+  ): Response {
+    let responseHeaders = this.#res ? new Headers(this.#res.headers) : this.#preparedHeaders
+
+    if (typeof arg === 'object' && arg.headers) {
+      responseHeaders ??= new Headers()
+      for (const [key, value] of new Headers(arg.headers)) {
+        if (key === 'set-cookie') {
+          responseHeaders.append(key, value)
+        } else {
+          responseHeaders.set(key, value)
+        }
+      }
+    }
+
+    if (headers) {
+      if (!responseHeaders) {
+        let count = 0
+        for (const k in headers) {
+          if (++count > 1 || typeof headers[k as keyof HeaderRecord] !== 'string') {
+            responseHeaders = new Headers()
+            break
+          }
+        }
+      }
+      if (responseHeaders) {
+        for (const k in headers) {
+          const v = headers[k as keyof HeaderRecord]
+          if (typeof v === 'string') {
+            responseHeaders.set(k, v)
+          } else {
+            responseHeaders.delete(k)
+            for (const v2 of v) {
+              responseHeaders.append(k, v2)
+            }
+          }
+        }
+      }
+    }
+
+    const status = typeof arg === 'number' ? arg : (arg?.status ?? this.#status)
+    return createResponseInstance(data, {
+      status,
+      headers: responseHeaders ?? (headers as Record<string, string> | undefined),
+    })
+  }
+
+  newResponse: NewResponse = (...args) => this.#newResponse(...(args as Parameters<NewResponse>))
+
+  /**
+   * `.body()` can return the HTTP response.
+   * You can set headers with `.header()` and set HTTP status code with `.status`.
+   * This can also be set in `.text()`, `.json()` and so on.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/welcome', (c) => {
+   *   // Set headers
+   *   c.header('X-Message', 'Hello!')
+   *   c.header('Content-Type', 'text/plain')
+   *   // Set HTTP status code
+   *   c.status(201)
+   *
+   *   // Return the response body
+   *   return c.body('Thank you for coming')
+   * })
+   * ```
+   */
+  body: BodyRespond = (
+    data: Data | null,
+    arg?: StatusCode | RequestInit,
+    headers?: HeaderRecord
+  ): ReturnType<BodyRespond> => this.#newResponse(data, arg, headers) as ReturnType<BodyRespond>
+
+  /**
+   * `.text()` can render text as `Content-Type:text/plain`.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/say', (c) => {
+   *   return c.text('Hello!')
+   * })
+   * ```
+   */
+  text: TextRespond = (
+    text: string,
+    arg?: ContentfulStatusCode | ResponseOrInit,
+    headers?: HeaderRecord
+  ): ReturnType<TextRespond> => {
+    return !this.#preparedHeaders && !this.#status && !arg && !headers && !this.finalized
+      ? (new Response(text) as ReturnType<TextRespond>)
+      : (this.#newResponse(
+          text,
+          arg,
+          setDefaultContentType(TEXT_PLAIN, headers)
+        ) as ReturnType<TextRespond>)
+  }
+
+  /**
+   * `.json()` can render JSON as `Content-Type:application/json`.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/api', (c) => {
+   *   return c.json({ message: 'Hello!' })
+   * })
+   * ```
+   */
+  json: JSONRespond = <
+    T extends JSONValue | {} | InvalidJSONValue,
+    U extends ContentfulStatusCode = ContentfulStatusCode,
+  >(
+    object: T,
+    arg?: U | ResponseOrInit<U>,
+    headers?: HeaderRecord
+  ): JSONRespondReturn<T, U> => {
+    return this.#newResponse(
+      JSON.stringify(object),
+      arg,
+      setDefaultContentType('application/json', headers)
+    ) /* eslint-disable @typescript-eslint/no-explicit-any */ as any
+  }
+
+  html: HTMLRespond = (
+    html: string | Promise<string>,
+    arg?: ContentfulStatusCode | ResponseOrInit<ContentfulStatusCode>,
+    headers?: HeaderRecord
+  ): Response | Promise<Response> => {
+    const res = (html: string) =>
+      this.#newResponse(html, arg, setDefaultContentType('text/html; charset=UTF-8', headers))
+    return typeof html === 'object'
+      ? resolveCallback(html, HtmlEscapedCallbackPhase.Stringify, false, {}).then(res)
+      : res(html)
+  }
+
+  /**
+   * `.redirect()` can Redirect, default status code is 302.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/redirect', (c) => {
+   *   return c.redirect('/')
+   * })
+   * app.get('/redirect-permanently', (c) => {
+   *   return c.redirect('/', 301)
+   * })
+   * ```
+   */
+  redirect = <T extends RedirectStatusCode = 302>(
+    location: string | URL,
+    status?: T
+  ): Response & TypedResponse<undefined, T, 'redirect'> => {
+    const locationString = String(location)
+    this.header(
+      'Location',
+      // Multibytes should be encoded
+      // eslint-disable-next-line no-control-regex
+      !/[^\x00-\xFF]/.test(locationString) ? locationString : encodeURI(locationString)
+    )
+    return this.newResponse(null, status ?? 302) as any
+  }
+
+  /**
+   * `.notFound()` can return the Not Found Response.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/notfound', (c) => {
+   *   return c.notFound()
+   * })
+   * ```
+   */
+  notFound = (): ReturnType<NotFoundHandler> => {
+    this.#notFoundHandler ??= () => createResponseInstance()
+    return this.#notFoundHandler(this)
+  }
+}