acrylblends 0.3.0 → 0.4.0

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

@@ -0,0 +1,502 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { HTTPException } from './http-exception.ts'
+import { GET_MATCH_RESULT } from './request/constants.ts'
+import type { Result } from './router.ts'
+import type {
+  Input,
+  InputToDataByTarget,
+  ParamKeyToRecord,
+  ParamKeys,
+  RemoveQuestion,
+  RouterRoute,
+  ValidationTargets,
+} from './types.ts'
+import { parseBody } from './utils/body.ts'
+import type { BodyData, ParseBodyOptions } from './utils/body.ts'
+import type { CustomHeader, RequestHeader } from './utils/headers.ts'
+import type { Simplify, UnionToIntersection } from './utils/types.ts'
+import { getQueryParam, getQueryParams, tryDecodeURIComponent } from './utils/url.ts'
+
+type Body = {
+  json: any
+  text: string
+  arrayBuffer: ArrayBuffer
+  blob: Blob
+  formData: FormData
+}
+type BodyCache = Partial<Body>
+
+type OptionalRequestInitProperties = 'window' | 'priority'
+type RequiredRequestInit = Required<Omit<RequestInit, OptionalRequestInitProperties>> & {
+  [Key in OptionalRequestInitProperties]?: RequestInit[Key]
+}
+
+export class AppRequest<P extends string = '/', I extends Input['out'] = {}> {
+  /**
+   * `.raw` can get the raw Request object.
+   *
+   *
+   * @example
+   * ```ts
+   * // For Cloudflare Workers
+   * app.post('/', async (c) => {
+   *   const metadata = c.req.raw.cf?.hostMetadata?
+   *   ...
+   * })
+   * ```
+   */
+  raw: Request
+
+  #validatedData: { [K in keyof ValidationTargets]?: {} } | undefined // Short name of validatedData
+  #matchResult: Result<[unknown, RouterRoute]>
+  routeIndex: number = 0
+  /**
+   * `.path` can get the pathname of the request.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/about/me', (c) => {
+   *   const pathname = c.req.path // `/about/me`
+   * })
+   * ```
+   */
+  path: string
+  bodyCache: BodyCache = {}
+
+  constructor(
+    request: Request,
+    path: string = '/',
+    matchResult: Result<[unknown, RouterRoute]> = [[]]
+  ) {
+    this.raw = request
+    this.path = path
+    this.#matchResult = matchResult
+  }
+
+  /**
+   * `.req.param()` gets the path parameters.
+   *
+   *
+   * @example
+   * ```ts
+   * const name = c.req.param('name')
+   * // or all parameters at once
+   * const { id, comment_id } = c.req.param()
+   * ```
+   */
+  param<P2 extends ParamKeys<P> = ParamKeys<P>>(
+    key: string extends P ? never : P2 extends `${infer _}?` ? never : P2
+  ): string
+  param<P2 extends RemoveQuestion<ParamKeys<P>> = RemoveQuestion<ParamKeys<P>>>(
+    key: P2
+  ): string | undefined
+  param(key: string): string | undefined
+  param<P2 extends string = P>(): Simplify<UnionToIntersection<ParamKeyToRecord<ParamKeys<P2>>>>
+  param(key?: string): unknown {
+    return key ? this.#getDecodedParam(key) : this.#getAllDecodedParams()
+  }
+
+  #getDecodedParam(key: string): string | undefined {
+    const paramKey = this.#matchResult[0][this.routeIndex]?.[1][key]
+    const param = this.#getParamValue(paramKey)
+    return param && tryDecodeURIComponent(param)
+  }
+
+  #getAllDecodedParams(): Record<string, string> {
+    const decoded: Record<string, string> = {}
+
+    const keys = Object.keys(this.#matchResult[0][this.routeIndex]?.[1] ?? {})
+    for (const key of keys) {
+      const value = this.#getParamValue(this.#matchResult[0][this.routeIndex][1][key])
+      if (value !== undefined) {
+        decoded[key] = tryDecodeURIComponent(value)
+      }
+    }
+
+    return decoded
+  }
+
+  #getParamValue(paramKey: any): string | undefined {
+    return this.#matchResult[1] ? this.#matchResult[1][paramKey as any] : paramKey
+  }
+
+  /**
+   * `.query()` can get querystring parameters.
+   *
+   *
+   * @example
+   * ```ts
+   * // Query params
+   * app.get('/search', (c) => {
+   *   const query = c.req.query('q')
+   * })
+   *
+   * // Get all params at once
+   * app.get('/search', (c) => {
+   *   const { q, limit, offset } = c.req.query()
+   * })
+   * ```
+   */
+  query(key: string): string | undefined
+  query(): Record<string, string>
+  query(key?: string) {
+    return getQueryParam(this.url, key)
+  }
+
+  /**
+   * `.queries()` can get multiple querystring parameter values, e.g. /search?tags=A&tags=B
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/search', (c) => {
+   *   // tags will be string[]
+   *   const tags = c.req.queries('tags')
+   * })
+   * ```
+   */
+  queries(key: string): string[] | undefined
+  queries(): Record<string, string[]>
+  queries(key?: string) {
+    return getQueryParams(this.url, key)
+  }
+
+  /**
+   * `.header()` can get the request header value.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/', (c) => {
+   *   const userAgent = c.req.header('User-Agent')
+   * })
+   * ```
+   */
+  header(name: RequestHeader): string | undefined
+  header(name: string): string | undefined
+  header(): Record<RequestHeader | (string & CustomHeader), string>
+  header(name?: string) {
+    if (name) {
+      return this.raw.headers.get(name) ?? undefined
+    }
+
+    const headerData: Record<string, string | undefined> = Object.create(null)
+    this.raw.headers.forEach((value, key) => {
+      headerData[key] = value
+    })
+    return headerData
+  }
+
+  /**
+   * `.parseBody()` can parse Request body of type `multipart/form-data` or `application/x-www-form-urlencoded`
+   *
+   *
+   * @example
+   * ```ts
+   * app.post('/entry', async (c) => {
+   *   const body = await c.req.parseBody()
+   * })
+   * ```
+   */
+  async parseBody<Options extends Partial<ParseBodyOptions>, T extends BodyData<Options>>(
+    options?: Options
+  ): Promise<T>
+  async parseBody<T extends BodyData>(options?: Partial<ParseBodyOptions>): Promise<T>
+  async parseBody(options?: Partial<ParseBodyOptions>) {
+    return parseBody(this, options)
+  }
+
+  #cachedBody = (key: keyof Body) => {
+    const { bodyCache, raw } = this
+    const cachedBody = bodyCache[key]
+
+    if (cachedBody) {
+      return cachedBody
+    }
+
+    for (const anyCachedKey in bodyCache) {
+      return (bodyCache[anyCachedKey as keyof Body] as Promise<BodyInit>).then((body) => {
+        if (anyCachedKey === 'json') {
+          body = JSON.stringify(body)
+        }
+        // Rebuilding the body through a bare `Response` loses the request's media
+        // type, so a representation that needs it (e.g. `formData()`) can no longer
+        // be produced even though the bytes are still available. Carry the original
+        // `Content-Type` over, except for `FormData`, where `Response` must generate
+        // a fresh multipart boundary of its own.
+        const contentType =
+          anyCachedKey === 'formData' ? undefined : raw.headers.get('content-type')
+        return new Response(body, {
+          headers: contentType ? { 'Content-Type': contentType } : undefined,
+        })[key]()
+      })
+    }
+
+    return (bodyCache[key] = raw[key]())
+  }
+
+  /**
+   * `.json()` can parse Request body of type `application/json`
+   *
+   *
+   * @example
+   * ```ts
+   * app.post('/entry', async (c) => {
+   *   const body = await c.req.json()
+   * })
+   * ```
+   */
+  json<T = any>(): Promise<T> {
+    return this.#cachedBody('text').then((text: string) => JSON.parse(text))
+  }
+
+  /**
+   * `.text()` can parse Request body of type `text/plain`
+   *
+   *
+   * @example
+   * ```ts
+   * app.post('/entry', async (c) => {
+   *   const body = await c.req.text()
+   * })
+   * ```
+   */
+  text(): Promise<string> {
+    return this.#cachedBody('text')
+  }
+
+  /**
+   * `.arrayBuffer()` parse Request body as an `ArrayBuffer`
+   *
+   *
+   * @example
+   * ```ts
+   * app.post('/entry', async (c) => {
+   *   const body = await c.req.arrayBuffer()
+   * })
+   * ```
+   */
+  arrayBuffer(): Promise<ArrayBuffer> {
+    return this.#cachedBody('arrayBuffer')
+  }
+
+  /**
+   * `.bytes()` parses the request body as a `Uint8Array`.
+   *
+   *
+   * @example
+   * ```ts
+   * app.post('/entry', async (c) => {
+   *   const body = await c.req.bytes()
+   * })
+   * ```
+   */
+  bytes(): Promise<Uint8Array> {
+    return this.#cachedBody('arrayBuffer').then((buffer: ArrayBuffer) => new Uint8Array(buffer))
+  }
+
+  /**
+   * Parses the request body as a `Blob`.
+   * @example
+   * ```ts
+   * app.post('/entry', async (c) => {
+   *   const body = await c.req.blob();
+   * });
+   * ```
+   */
+  blob(): Promise<Blob> {
+    return this.#cachedBody('blob')
+  }
+
+  /**
+   * Parses the request body as `FormData`.
+   * @example
+   * ```ts
+   * app.post('/entry', async (c) => {
+   *   const body = await c.req.formData();
+   * });
+   * ```
+   */
+  formData(): Promise<FormData> {
+    return this.#cachedBody('formData')
+  }
+
+  /**
+   * Adds validated data to the request.
+   *
+   * @param target - The target of the validation.
+   * @param data - The validated data to add.
+   */
+  addValidatedData(target: keyof ValidationTargets, data: {}) {
+    ;(this.#validatedData ??= {})[target] = data
+  }
+
+  /**
+   * Gets validated data from the request.
+   *
+   * @param target - The target of the validation.
+   * @returns The validated data.
+   *
+   */
+  valid<T extends keyof I & keyof ValidationTargets>(target: T): InputToDataByTarget<I, T>
+  valid(target: keyof ValidationTargets) {
+    return this.#validatedData?.[target] as unknown
+  }
+
+  /**
+   * `.url` can get the request url strings.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/about/me', (c) => {
+   *   const url = c.req.url // `http://localhost:8787/about/me`
+   *   ...
+   * })
+   * ```
+   */
+  get url(): string {
+    return this.raw.url
+  }
+
+  /**
+   * `.method` can get the method name of the request.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/about/me', (c) => {
+   *   const method = c.req.method // `GET`
+   * })
+   * ```
+   */
+  get method(): string {
+    return this.raw.method
+  }
+
+  get [GET_MATCH_RESULT](): Result<[unknown, RouterRoute]> {
+    return this.#matchResult
+  }
+
+  /**
+   * `.matchedRoutes` can return a matched route in the handler
+   *
+   * @deprecated
+   *
+   * Use matchedRoutes helper defined in "acryl-router/route" instead.
+   *
+   *
+   * @example
+   * ```ts
+   * app.use('*', async function logger(c, next) {
+   *   await next()
+   *   c.req.matchedRoutes.forEach(({ handler, method, path }, i) => {
+   *     const name = handler.name || (handler.length < 2 ? '[handler]' : '[middleware]')
+   *     console.log(
+   *       method,
+   *       ' ',
+   *       path,
+   *       ' '.repeat(Math.max(10 - path.length, 0)),
+   *       name,
+   *       i === c.req.routeIndex ? '<- respond from here' : ''
+   *     )
+   *   })
+   * })
+   * ```
+   */
+  get matchedRoutes(): RouterRoute[] {
+    return this.#matchResult[0].map(([[, route]]) => route)
+  }
+
+  /**
+   * `.routePath` can retrieve the path registered within the handler
+   *
+   * @deprecated
+   *
+   * Use routePath helper defined in "acryl-router/route" instead.
+   *
+   *
+   * @example
+   * ```ts
+   * app.get('/posts/:id', (c) => {
+   *   return c.json({ path: c.req.routePath })
+   * })
+   * ```
+   */
+  get routePath(): string {
+    return this.#matchResult[0].map(([[, route]]) => route)[this.routeIndex].path
+  }
+}
+
+/**
+ * Clones a AppRequest's underlying raw Request object.
+ *
+ * This utility handles both consumed and unconsumed request bodies:
+ * - If the request body hasn't been consumed, it uses the native `clone()` method
+ * - If the request body has been consumed, it reconstructs a new Request using cached body data
+ *
+ * This is particularly useful when you need to:
+ * - Process the same request body multiple times
+ * - Pass requests to external services after validation
+ *
+ * @param req - The AppRequest object to clone
+ * @returns A Promise that resolves to a new Request object with the same properties
+ * @throws {HTTPException} If the request body was consumed directly via `req.raw`
+ *   without using AppRequest methods (e.g., `req.json()`, `req.text()`), making it
+ *   impossible to reconstruct the body from cache
+ *
+ * @example
+ * ```ts
+ * // Clone after consuming the body (e.g., after validation)
+ * app.post('/forward',
+ *   validator('json', (data) => data),
+ *   async (c) => {
+ *     const validated = c.req.valid('json')
+ *     // Body has been consumed, but cloneRawRequest still works
+ *     const clonedReq = await cloneRawRequest(c.req)
+ *     return fetch('http://backend-service.com', clonedReq)
+ *   }
+ * )
+ * ```
+ */
+export const cloneRawRequest = async (req: AppRequest): Promise<Request> => {
+  if (!req.raw.bodyUsed) {
+    return req.raw.clone()
+  }
+
+  const cacheKey = (Object.keys(req.bodyCache) as Array<keyof Body>)[0]
+  if (!cacheKey) {
+    throw new HTTPException(500, {
+      message:
+        'Cannot clone request: body was already consumed and not cached. Please use AppRequest methods (e.g., req.json(), req.text()) instead of consuming req.raw directly.',
+    })
+  }
+
+  let body: BodyInit = await req[cacheKey]()
+  const headers = req.header()
+  if (cacheKey === 'json') {
+    body = JSON.stringify(body)
+    delete headers['content-length']
+  } else if (body instanceof FormData) {
+    delete headers['content-type']
+    delete headers['content-length']
+  }
+
+  const requestInit: RequiredRequestInit = {
+    body,
+    cache: req.raw.cache,
+    credentials: req.raw.credentials,
+    headers,
+    integrity: req.raw.integrity,
+    keepalive: req.raw.keepalive,
+    method: req.method,
+    mode: req.raw.mode,
+    redirect: req.raw.redirect,
+    referrer: req.raw.referrer,
+    referrerPolicy: req.raw.referrerPolicy,
+    signal: req.raw.signal,
+  }
+
+  return new Request(req.url, requestInit)
+}