acrylblends 0.2.0 → 0.4.0

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

@@ -0,0 +1,249 @@
+import type { App } from '../app.ts'
+import type { FormValue, ValidationTargets } from '../types.ts'
+import { serialize } from '../utils/cookie.ts'
+import type { UnionToIntersection } from '../utils/types.ts'
+import type { BuildSearchParamsFn, Callback, Client, ClientRequestOptions } from './types.ts'
+import {
+  buildSearchParams,
+  deepMerge,
+  mergePath,
+  removeIndexString,
+  replaceUrlParam,
+  replaceUrlProtocol,
+} from './utils.ts'
+
+const createProxy = (callback: Callback, path: string[]) => {
+  const proxy: unknown = new Proxy(() => {}, {
+    get(_obj, key) {
+      if (typeof key !== 'string' || key === 'then') {
+        return undefined
+      }
+      return createProxy(callback, [...path, key])
+    },
+    apply(_1, _2, args) {
+      return callback({
+        path,
+        args,
+      })
+    },
+  })
+  return proxy
+}
+
+const appendQueryParams = (url: string, searchParams: URLSearchParams): string => {
+  const queryString = searchParams.toString()
+  return queryString ? `${url}?${queryString}` : url
+}
+
+class ClientRequestImpl {
+  private url: string
+  private method: string
+  private buildSearchParams: BuildSearchParamsFn
+  private queryParams: URLSearchParams | undefined = undefined
+  private pathParams: Record<string, string> = {}
+  private rBody: BodyInit | undefined
+  private cType: string | undefined = undefined
+
+  constructor(
+    url: string,
+    method: string,
+    options: {
+      buildSearchParams: BuildSearchParamsFn
+    }
+  ) {
+    this.url = url
+    this.method = method
+    this.buildSearchParams = options.buildSearchParams
+  }
+  fetch = async (
+    args?: ValidationTargets<FormValue> & {
+      param?: Record<string, string>
+    },
+    opt?: ClientRequestOptions
+  ) => {
+    if (args) {
+      if (args.query) {
+        this.queryParams = this.buildSearchParams(args.query)
+      }
+
+      if (args.form) {
+        const form = new FormData()
+        for (const [k, v] of Object.entries(args.form)) {
+          if (v === undefined) {
+            continue
+          }
+          if (Array.isArray(v)) {
+            for (const v2 of v) {
+              if (v2 === undefined) {
+                continue
+              }
+              form.append(k, v2)
+            }
+          } else {
+            form.append(k, v)
+          }
+        }
+        this.rBody = form
+      }
+
+      if (args.json !== undefined) {
+        this.rBody = JSON.stringify(args.json)
+        this.cType = 'application/json'
+      }
+
+      if (args.param) {
+        this.pathParams = args.param
+      }
+    }
+
+    let methodUpperCase = this.method.toUpperCase()
+
+    const headerValues: Record<string, string | undefined> = {
+      ...args?.header,
+      ...(typeof opt?.headers === 'function' ? await opt.headers() : opt?.headers),
+    }
+
+    if (args?.cookie) {
+      const cookies: string[] = []
+      for (const [key, value] of Object.entries(args.cookie)) {
+        if (value === undefined) {
+          continue
+        }
+        cookies.push(serialize(key, value))
+      }
+      if (cookies.length > 0) {
+        headerValues['Cookie'] = cookies.join('; ')
+      }
+    }
+
+    if (this.cType) {
+      headerValues['Content-Type'] = this.cType
+    }
+
+    const headers = new Headers()
+    for (const [key, value] of Object.entries(headerValues)) {
+      if (value !== undefined) {
+        headers.set(key, value)
+      }
+    }
+    let url = this.url
+
+    url = removeIndexString(url)
+    url = replaceUrlParam(url, this.pathParams)
+
+    if (this.queryParams) {
+      url = appendQueryParams(url, this.queryParams)
+    }
+    methodUpperCase = this.method.toUpperCase()
+    const setBody = !(methodUpperCase === 'GET' || methodUpperCase === 'HEAD')
+
+    // Pass URL string to 1st arg for testing with MSW and node-fetch
+    return (opt?.fetch || fetch)(url, {
+      body: setBody ? this.rBody : undefined,
+      method: methodUpperCase,
+      headers: headers,
+      ...opt?.init,
+    })
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const hc = <T extends App<any, any, any>, Prefix extends string = string>(
+  baseUrl: Prefix,
+  options?: ClientRequestOptions
+) =>
+  createProxy(function proxyCallback(opts) {
+    const buildSearchParamsOption = options?.buildSearchParams ?? buildSearchParams
+    const parts = [...opts.path]
+    const lastParts = parts.slice(-3).reverse()
+
+    // allow calling .toString() and .valueOf() on the proxy
+    if (lastParts[0] === 'toString') {
+      if (lastParts[1] === 'name') {
+        // e.g. hc().somePath.name.toString() -> "somePath"
+        return lastParts[2] || ''
+      }
+      // e.g. hc().somePath.toString()
+      return proxyCallback.toString()
+    }
+
+    if (lastParts[0] === 'valueOf') {
+      if (lastParts[1] === 'name') {
+        // e.g. hc().somePath.name.valueOf() -> "somePath"
+        return lastParts[2] || ''
+      }
+      // e.g. hc().somePath.valueOf()
+      return proxyCallback
+    }
+
+    let method = ''
+    if (/^\$/.test(lastParts[0] as string)) {
+      const last = parts.pop()
+      if (last) {
+        method = last.replace(/^\$/, '')
+      }
+    }
+
+    const path = parts.join('/')
+    const url = mergePath(baseUrl, path)
+    if (method === 'url' || method === 'path') {
+      // Strip the synthetic `index` segment before substituting params, so that a param
+      // whose value is `index` is not mistaken for one.
+      let result = removeIndexString(url)
+      if (opts.args[0]) {
+        if (opts.args[0].param) {
+          result = replaceUrlParam(result, opts.args[0].param)
+        }
+        if (opts.args[0].query) {
+          result = appendQueryParams(result, buildSearchParamsOption(opts.args[0].query))
+        }
+      }
+      if (method === 'url') {
+        return new URL(result)
+      }
+      return result.slice(baseUrl.replace(/\/+$/, '').length).replace(/^\/?/, '/')
+    }
+    if (method === 'ws') {
+      const normalizedUrl = removeIndexString(url)
+      const webSocketUrl = replaceUrlProtocol(
+        opts.args[0]?.param ? replaceUrlParam(normalizedUrl, opts.args[0].param) : normalizedUrl,
+        'ws'
+      )
+      const targetUrl = new URL(webSocketUrl)
+
+      const queryParams: Record<string, string | string[]> | undefined = opts.args[0]?.query
+      if (queryParams) {
+        const searchParams = buildSearchParamsOption(queryParams)
+        searchParams.forEach((value, key) => {
+          targetUrl.searchParams.append(key, value)
+        })
+      }
+      const establishWebSocket = (...args: ConstructorParameters<typeof WebSocket>) => {
+        if (options?.webSocket !== undefined && typeof options.webSocket === 'function') {
+          return options.webSocket(...args)
+        }
+        return new WebSocket(...args)
+      }
+
+      return establishWebSocket(targetUrl.toString())
+    }
+
+    const req = new ClientRequestImpl(url, method, {
+      buildSearchParams: buildSearchParamsOption,
+    })
+    if (method) {
+      options ??= {}
+      const reqOptions: ClientRequestOptions = { ...opts.args[1] }
+      const baseHeaders = options.headers
+      const reqHeaders = reqOptions.headers
+      if (baseHeaders && reqHeaders) {
+        reqOptions.headers = async () => ({
+          ...(typeof baseHeaders === 'function' ? await baseHeaders() : baseHeaders),
+          ...(typeof reqHeaders === 'function' ? await reqHeaders() : reqHeaders),
+        })
+      }
+      const args = deepMerge<ClientRequestOptions>(options, reqOptions)
+      return req.fetch(opts.args[0], args)
+    }
+    return req
+  }, []) as UnionToIntersection<Client<T, Prefix>>

package/plugins/acryl-router/src/core/client/fetch-result-please.ts

@@ -0,0 +1,95 @@
+/**
+ * @description This file is a modified version of `fetch-result-please` (`ofetch`), minimalized and adapted to App's custom needs.
+ *
+ * @link https://www.npmjs.com/package/fetch-result-please
+ */
+
+const nullBodyResponses = new Set([101, 204, 205, 304])
+
+/**
+ * Smartly parses and return the consumable result from a fetch `Response`.
+ *
+ * Throwing a structured error if the response is not `ok`. ({@link DetailedError})
+ */
+export async function fetchRP(fetchRes: Response | Promise<Response>): Promise<any> {
+  const _fetchRes = (await fetchRes) as unknown as Response & {
+    _data: any
+    /**
+     * @description BodyInit property from whatwg-fetch polyfill
+     *
+     * @link https://github.com/JakeChampion/fetch/blob/main/fetch.js#L238
+     */
+    _bodyInit?: any
+  }
+
+  const hasBody =
+    (_fetchRes.body || _fetchRes._bodyInit) && !nullBodyResponses.has(_fetchRes.status)
+
+  if (hasBody) {
+    const responseType = detectResponseType(_fetchRes)
+    _fetchRes._data = await _fetchRes[responseType]()
+  }
+
+  if (!_fetchRes.ok) {
+    throw new DetailedError(`${_fetchRes.status} ${_fetchRes.statusText}`, {
+      statusCode: _fetchRes?.status,
+      detail: {
+        data: _fetchRes?._data,
+        statusText: _fetchRes?.statusText,
+      },
+    })
+  }
+
+  return _fetchRes._data
+}
+
+export class DetailedError extends Error {
+  /**
+   * Additional `message` that will be logged AND returned to client
+   */
+  public detail?: any
+  /**
+   * Additional `code` that will be logged AND returned to client
+   */
+  public code?: any
+  /**
+   * Additional value that will be logged AND NOT returned to client
+   */
+  public log?: any
+  /**
+   * Optionally set the status code to return, in a web server context
+   */
+  public statusCode?: any
+
+  constructor(
+    message: string,
+    options: { detail?: any; code?: any; statusCode?: number; log?: any } = {}
+  ) {
+    super(message)
+    this.name = 'DetailedError'
+    this.log = options.log
+    this.detail = options.detail
+    this.code = options.code
+    this.statusCode = options.statusCode
+  }
+}
+
+// This is used to match the content-type header for 'json'
+const jsonRegex = /^application\/(?:[\w!#$%&*.^`~-]*\+)?json(?:;.+)?$/i
+
+function detectResponseType(response: Response): 'json' | 'text' {
+  const _contentType = response.headers.get('content-type')
+
+  if (!_contentType) {
+    return 'text'
+  }
+
+  // `_contentType` might look like: `application/json; charset=utf-8`, `text/plain`, so we get the first part before `;`
+  const contentType = _contentType.split(';').shift()!
+
+  if (jsonRegex.test(contentType)) {
+    return 'json'
+  }
+
+  return 'text'
+}

package/plugins/acryl-router/src/core/client/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @module
+ * The HTTP Client for App.
+ */
+
+export { hc } from './client.ts'
+export { parseResponse, DetailedError } from './utils.ts'
+export type {
+  InferResponseType,
+  InferRequestType,
+  Fetch,
+  ClientRequestOptions,
+  ClientRequest,
+  ClientResponse,
+  ApplyGlobalResponse,
+  PickResponseByStatusCode,
+} from './types.ts'

package/plugins/acryl-router/src/core/client/types.test.ts

@@ -0,0 +1,149 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { expectTypeOf } from 'vitest'
+import { hc } from './index.ts'
+import { App } from '../index.ts'
+import { defineWebSocketHelper } from '../helper/websocket/index.ts'
+import type { TypedURL } from './types.ts'
+
+// The Deno adapter is not part of ACRYL; these tests only build client URLs, so a helper that never upgrades stands in for it.
+const upgradeWebSocket = defineWebSocketHelper(async () => {})
+
+describe('WebSockets', () => {
+  const app = new App()
+    .get(
+      '/ws',
+      upgradeWebSocket(() => ({}))
+    )
+    .get('/', (c) => c.json({}))
+  const client = hc<typeof app>('/')
+
+  it('WebSocket route', () => {
+    expectTypeOf(client.ws).toMatchTypeOf<{
+      $ws: () => WebSocket
+    }>()
+  })
+  it('Not WebSocket Route', () => {
+    expectTypeOf<
+      typeof client.index extends { $ws: () => WebSocket } ? false : true
+    >().toEqualTypeOf(true)
+  })
+})
+
+describe('without the leading slash', () => {
+  const app = new App()
+    .get('foo', (c) => c.json({}))
+    .get('foo/bar', (c) => c.json({}))
+    .get('foo/:id/baz', (c) => c.json({}))
+  const client = hc<typeof app, 'http://localhost'>('http://localhost')
+  it('`foo` should have `$get`', () => {
+    expectTypeOf(client.foo).toHaveProperty('$get')
+    expectTypeOf(client.foo.$url()).toEqualTypeOf<TypedURL<'http:', 'localhost', '', '/foo', ''>>()
+    expectTypeOf(client.foo.$path()).toEqualTypeOf<'/foo'>()
+  })
+  it('`foo.bar` should not have `$get`', () => {
+    expectTypeOf(client.foo.bar).toHaveProperty('$get')
+    expectTypeOf(client.foo.bar.$url()).toEqualTypeOf<
+      TypedURL<'http:', 'localhost', '', '/foo/bar', ''>
+    >()
+    expectTypeOf(client.foo.bar.$path()).toEqualTypeOf<'/foo/bar'>()
+  })
+  it('`foo[":id"].baz` should have `$get`', () => {
+    expectTypeOf(client.foo[':id'].baz).toHaveProperty('$get')
+    expectTypeOf(client.foo[':id'].baz.$url()).toEqualTypeOf<
+      TypedURL<'http:', 'localhost', '', '/foo/:id/baz', ''>
+    >()
+    expectTypeOf(
+      client.foo[':id'].baz.$url({
+        param: { id: '123' },
+      })
+    ).toEqualTypeOf<TypedURL<'http:', 'localhost', '', '/foo/123/baz', ''>>()
+    expectTypeOf(
+      client.foo[':id'].baz.$url({
+        param: { id: '123' },
+        query: { q: 'acryl' },
+      })
+    ).toEqualTypeOf<TypedURL<'http:', 'localhost', '', '/foo/123/baz', `?${string}`>>()
+
+    expectTypeOf(client.foo[':id'].baz.$path()).toEqualTypeOf<'/foo/:id/baz'>()
+    expectTypeOf(
+      client.foo[':id'].baz.$path({
+        param: { id: '123' },
+      })
+    ).toEqualTypeOf<'/foo/123/baz'>()
+    expectTypeOf(
+      client.foo[':id'].baz.$path({
+        param: { id: '123' },
+        query: { q: 'acryl' },
+      })
+    ).toEqualTypeOf<`/foo/123/baz?${string}`>()
+  })
+})
+
+describe('with the leading slash', () => {
+  const app = new App()
+    .get('/foo', (c) => c.json({}))
+    .get('/foo/bar', (c) => c.json({}))
+    .get('/foo/:id/baz', (c) => c.json({}))
+  const client = hc<typeof app>('')
+  it('`foo` should have `$get`', () => {
+    expectTypeOf(client.foo).toHaveProperty('$get')
+  })
+  it('`foo.bar` should not have `$get`', () => {
+    expectTypeOf(client.foo.bar).toHaveProperty('$get')
+  })
+  it('`foo[":id"].baz` should have `$get`', () => {
+    expectTypeOf(client.foo[':id'].baz).toHaveProperty('$get')
+  })
+})
+
+describe('app.all()', () => {
+  const app = new App()
+    .all('/all-route', (c) => c.json({ msg: 'all methods' }))
+    .get('/get-route', (c) => c.json({ msg: 'get only' }))
+  const client = hc<typeof app>('http://localhost', { fetch: app.request })
+
+  it('should NOT expose $all on the client', () => {
+    expectTypeOf<
+      (typeof client)['all-route'] extends { $all: unknown } ? true : false
+    >().toEqualTypeOf<false>()
+  })
+
+  it('should still expose valid HTTP methods like $get', () => {
+    expectTypeOf(client['get-route']).toHaveProperty('$get')
+  })
+
+  it('should expose all standard HTTP methods for routes defined with app.all()', () => {
+    // $all routes should have all standard HTTP methods typed
+    expectTypeOf(client['all-route']).toHaveProperty('$get')
+    expectTypeOf(client['all-route']).toHaveProperty('$post')
+    expectTypeOf(client['all-route']).toHaveProperty('$put')
+    expectTypeOf(client['all-route']).toHaveProperty('$delete')
+    expectTypeOf(client['all-route']).toHaveProperty('$options')
+    expectTypeOf(client['all-route']).toHaveProperty('$patch')
+    expectTypeOf(client['all-route']).toHaveProperty('$query')
+  })
+
+  it('should have correct return type for expanded methods', async () => {
+    // The response type should match the original handler's return type
+    const res = await client['all-route'].$get()
+    expectTypeOf(res.json()).resolves.toEqualTypeOf<{ msg: string }>()
+  })
+})
+
+describe('with base URL pathname', () => {
+  const app = new App()
+    .get('foo', (c) => c.json({}))
+    .get('foo/bar', (c) => c.json({}))
+    .get('foo/:id/baz', (c) => c.json({}))
+  const client = hc<typeof app, 'http://localhost/api'>('http://localhost/api')
+  it('$path', () => {
+    expectTypeOf(client.foo.$path()).toEqualTypeOf<'/foo'>()
+    expectTypeOf(client.foo.bar.$path()).toEqualTypeOf<'/foo/bar'>()
+    expectTypeOf(
+      client.foo[':id'].baz.$path({
+        param: { id: '123' },
+        query: { q: 'acryl' },
+      })
+    ).toEqualTypeOf<`/foo/123/baz?${string}`>()
+  })
+})