acrylblends 0.3.0 → 0.4.1

package/plugins/acryl-router/src/core/helper/streaming/text.test.ts

@@ -0,0 +1,34 @@
+import { streamText } from './index.ts'
+import { Context } from '../../context.ts'
+
+describe('Text Streaming Helper', () => {
+  const req = new Request('http://localhost/')
+  let c: Context
+  beforeEach(() => {
+    c = new Context(req)
+  })
+
+  it('Check streamText Response', async () => {
+    const res = streamText(c, async (stream) => {
+      for (let i = 0; i < 3; i++) {
+        await stream.write(`${i}`)
+        await stream.sleep(1)
+      }
+    })
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('content-type')).toMatch(/^text\/plain/)
+    expect(res.headers.get('x-content-type-options')).toBe('nosniff')
+    expect(res.headers.get('transfer-encoding')).toBe('chunked')
+
+    if (!res.body) {
+      throw new Error('Body is null')
+    }
+    const reader = res.body.getReader()
+    const decoder = new TextDecoder()
+    for (let i = 0; i < 3; i++) {
+      const { value } = await reader.read()
+      expect(decoder.decode(value)).toEqual(`${i}`)
+    }
+  })
+})

package/plugins/acryl-router/src/core/helper/streaming/text.ts

@@ -0,0 +1,15 @@
+import type { Context } from '../../context.ts'
+import { TEXT_PLAIN } from '../../context.ts'
+import type { StreamingApi } from '../../utils/stream.ts'
+import { stream } from './index.ts'
+
+export const streamText = (
+  c: Context,
+  cb: (stream: StreamingApi) => Promise<void>,
+  onError?: (e: Error, stream: StreamingApi) => Promise<void>
+): Response => {
+  c.header('Content-Type', TEXT_PLAIN)
+  c.header('X-Content-Type-Options', 'nosniff')
+  c.header('Transfer-Encoding', 'chunked')
+  return stream(c, cb, onError)
+}

package/plugins/acryl-router/src/core/helper/streaming/utils.ts

@@ -0,0 +1,11 @@
+export let isOldBunVersion = (): boolean => {
+  // @ts-expect-error @types/bun is not installed
+  const version: string = typeof Bun !== 'undefined' ? Bun.version : undefined
+  if (version === undefined) {
+    return false
+  }
+  const result = version.startsWith('1.1') || version.startsWith('1.0') || version.startsWith('0.')
+  // Avoid running this check on every call
+  isOldBunVersion = () => result
+  return result
+}

package/plugins/acryl-router/src/core/helper/testing/index.test.ts

@@ -0,0 +1,42 @@
+import { testClient } from './index.ts'
+import { App } from '../../app.ts'
+
+describe('acryl testClient', () => {
+  it('Should return the correct search result', async () => {
+    const app = new App().get('/search', (c) => c.json({ hello: 'world' }))
+    const res = await testClient(app).search.$get()
+    expect(await res.json()).toEqual({ hello: 'world' })
+  })
+
+  it('Should return the correct environment variables value', async () => {
+    type Bindings = { hello: string }
+    const app = new App<{ Bindings: Bindings }>().get('/search', (c) => {
+      return c.json({ hello: c.env.hello })
+    })
+    const res = await testClient(app, { hello: 'world' }).search.$get()
+    expect(await res.json()).toEqual({ hello: 'world' })
+  })
+
+  it('Should use the passed in headers', async () => {
+    const app = new App().get('/search', (c) => {
+      return c.json({ query: c.req.header('x-query') })
+    })
+    const res = await testClient(app, undefined, undefined, {
+      headers: { 'x-query': 'abc' },
+    }).search.$get()
+    expect(await res.json()).toEqual({ query: 'abc' })
+  })
+
+  it('Should return a correct URL with out throwing an error', async () => {
+    const app = new App().get('/abc', (c) => c.json(0))
+    const url = testClient(app).abc.$url()
+    expect(url.pathname).toBe('/abc')
+  })
+
+  it('Should not throw an error with $ws()', async () => {
+    vi.stubGlobal('WebSocket', class {})
+    const app = new App().get('/ws', (c) => c.text('Fake response of a WebSocket'))
+    // @ts-expect-error $ws is not typed correctly
+    expect(() => testClient(app).ws.$ws()).not.toThrowError()
+  })
+})

package/plugins/acryl-router/src/core/helper/testing/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @module
+ * Testing Helper for App.
+ */
+
+import { hc } from '../../client/index.ts'
+import type { ClientRequestOptions } from '../../client/index.ts'
+import type { Client } from '../../client/types.ts'
+import type { ExecutionContext } from '../../context.ts'
+import type { App } from '../../app.ts'
+import type { Schema } from '../../types.ts'
+import type { UnionToIntersection } from '../../utils/types.ts'
+
+type ExtractEnv<T> = T extends App<infer E, Schema, string> ? E : never
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const testClient = <T extends App<any, Schema, string>>(
+  app: T,
+  Env?: ExtractEnv<T>['Bindings'] | {},
+  executionCtx?: ExecutionContext,
+  options?: Omit<ClientRequestOptions, 'fetch'>
+): UnionToIntersection<Client<T, 'http://localhost'>> => {
+  const customFetch = (input: RequestInfo | URL, init?: RequestInit) => {
+    return app.request(input, init, Env, executionCtx)
+  }
+
+  return hc<typeof app, 'http://localhost'>('http://localhost', { ...options, fetch: customFetch })
+}

package/plugins/acryl-router/src/core/helper/websocket/index.test.ts

@@ -0,0 +1,124 @@
+import type { WSContextInit } from './index.ts'
+import { WSContext, createWSMessageEvent, defineWebSocketHelper } from './index.ts'
+import { Context } from '../../context.ts'
+
+describe('`createWSMessageEvent`', () => {
+  it('Should `createWSMessageEvent` is working for string', () => {
+    const randomString = Math.random().toString()
+    const event = createWSMessageEvent(randomString)
+
+    expect(event.data).toBe(randomString)
+  })
+  it('Should `createWSMessageEvent` type is `message`', () => {
+    const event = createWSMessageEvent('')
+    expect(event.type).toBe('message')
+  })
+})
+describe('defineWebSocketHelper', () => {
+  it('defineWebSocketHelper should work', async () => {
+    const upgradeWebSocket = defineWebSocketHelper(() => {
+      return new Response('Hello World', {
+        status: 200,
+      })
+    })
+    const response = await upgradeWebSocket(() => ({}))(
+      new Context(new Request('http://localhost')),
+      () => Promise.resolve()
+    )
+    expect(response).toBeTruthy()
+    expect((response as Response).status).toBe(200)
+  })
+  it('When response is undefined, should call next()', async () => {
+    const upgradeWebSocket = defineWebSocketHelper(() => {
+      return
+    })
+    const next = vi.fn()
+    await upgradeWebSocket(() => ({}))(new Context(new Request('http://localhost')), next)
+    expect(next).toBeCalled()
+  })
+  it('Use upgradeWebSocket in return', async () => {
+    const upgradeWebSocket = defineWebSocketHelper(() => {
+      return new Response('Hello World', {
+        status: 200,
+      })
+    })
+    const c = new Context(new Request('http://localhost'))
+    const res = await upgradeWebSocket(c, {})
+    expect(res.status).toBe(200)
+  })
+  it('When upgrading failed and use it in handler, it should throw error', async () => {
+    const upgradeWebSocket = defineWebSocketHelper(() => {
+      return
+    })
+    const c = new Context(new Request('http://localhost'))
+    await expect(() => upgradeWebSocket(c, {})).rejects.toThrow()
+  })
+})
+describe('WSContext', () => {
+  it('Should close() works', async () => {
+    type Result = [number | undefined, string | undefined]
+    let ws!: WSContext
+    const promise = new Promise<Result>((resolve) => {
+      ws = new WSContext({
+        close(code, reason) {
+          resolve([code, reason])
+        },
+      } as WSContextInit)
+    })
+    ws.close(0, 'reason')
+    const [code, reason] = await promise
+    expect(code).toBe(0)
+    expect(reason).toBe('reason')
+  })
+  it('Should send() works', async () => {
+    let ws!: WSContext
+    const promise = new Promise<string | ArrayBuffer | Uint8Array<ArrayBuffer>>((resolve) => {
+      ws = new WSContext({
+        send(data: string | ArrayBuffer | Uint8Array<ArrayBuffer>, _options) {
+          resolve(data)
+        },
+      } as WSContextInit)
+    })
+    ws.send('Hello')
+    expect(await promise).toBe('Hello')
+  })
+  it('Should readyState works', () => {
+    const ws = new WSContext({
+      readyState: 0,
+    } as WSContextInit)
+    expect(ws.readyState).toBe(0)
+  })
+  it('Should normalize URL', () => {
+    const stringURLWS = new WSContext({
+      url: 'http://localhost',
+    } as WSContextInit)
+    expect(stringURLWS.url).toBeInstanceOf(URL)
+
+    const urlURLWS = new WSContext({
+      url: new URL('http://localhost'),
+    } as WSContextInit)
+    expect(urlURLWS.url).toBeInstanceOf(URL)
+
+    const nullURLWS = new WSContext({
+      url: undefined,
+    } as WSContextInit)
+    expect(nullURLWS.url).toBeNull()
+  })
+  it('Should normalize message in send()', () => {
+    let data: string | ArrayBuffer | Uint8Array | null = null
+    const wsContext = new WSContext({
+      send(received, _options) {
+        data = received
+      },
+    } as WSContextInit)
+
+    wsContext.send('string')
+    expect(data).toBe('string')
+
+    wsContext.send(new ArrayBuffer(16))
+    expect(data).toBeInstanceOf(ArrayBuffer)
+
+    wsContext.send(new Uint8Array(16))
+    expect(data).toBeInstanceOf(Uint8Array)
+  })
+})

package/plugins/acryl-router/src/core/helper/websocket/index.ts

@@ -0,0 +1,140 @@
+/**
+ * @module
+ * WebSocket Helper for App.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { Context } from '../../context.ts'
+import type { MiddlewareHandler, TypedResponse } from '../../types.ts'
+import type { StatusCode } from '../../utils/http-status.ts'
+
+/**
+ * WebSocket Event Listeners type
+ */
+export interface WSEvents<T = unknown> {
+  onOpen?: (evt: Event, ws: WSContext<T>) => void
+  onMessage?: (evt: MessageEvent<WSMessageReceive>, ws: WSContext<T>) => void
+  onClose?: (evt: CloseEvent, ws: WSContext<T>) => void
+  onError?: (evt: Event, ws: WSContext<T>) => void
+}
+
+/**
+ * Upgrade WebSocket Type
+ */
+export interface UpgradeWebSocket<T = unknown, U = any, _WSEvents = WSEvents<T>> {
+  (
+    createEvents: (c: Context) => _WSEvents | Promise<_WSEvents>,
+    options?: U
+  ): MiddlewareHandler<
+    any,
+    string,
+    {
+      outputFormat: 'ws'
+    }
+  >
+  (
+    c: Context,
+    events: _WSEvents,
+    options?: U
+  ): Promise<Response & TypedResponse<{}, StatusCode, 'ws'>>
+}
+
+/**
+ * ReadyState for WebSocket
+ */
+export type WSReadyState = 0 | 1 | 2 | 3
+
+/**
+ * An argument for WSContext class
+ */
+export interface WSContextInit<T = unknown> {
+  send(data: string | ArrayBuffer | Uint8Array<ArrayBuffer>, options: SendOptions): void
+  close(code?: number, reason?: string): void
+
+  raw?: T
+  readyState: WSReadyState
+  url?: string | URL | null
+  protocol?: string | null
+}
+
+/**
+ * Options for sending message
+ */
+export interface SendOptions {
+  compress?: boolean
+}
+
+/**
+ * A context for controlling WebSockets
+ */
+export class WSContext<T = unknown> {
+  #init: WSContextInit<T>
+  constructor(init: WSContextInit<T>) {
+    this.#init = init
+    this.raw = init.raw
+    this.url = init.url ? new URL(init.url) : null
+    this.protocol = init.protocol ?? null
+  }
+  send(source: string | ArrayBuffer | Uint8Array<ArrayBuffer>, options?: SendOptions): void {
+    this.#init.send(source, options ?? {})
+  }
+  raw?: T
+  binaryType: BinaryType = 'arraybuffer'
+  get readyState(): WSReadyState {
+    return this.#init.readyState
+  }
+  url: URL | null
+  protocol: string | null
+  close(code?: number, reason?: string) {
+    this.#init.close(code, reason)
+  }
+}
+
+export type WSMessageReceive = string | Blob | ArrayBufferLike
+
+export const createWSMessageEvent = (source: WSMessageReceive): MessageEvent<WSMessageReceive> => {
+  return new MessageEvent<WSMessageReceive>('message', {
+    data: source,
+  })
+}
+
+export interface WebSocketHelperDefineContext {}
+export type WebSocketHelperDefineHandler<T, U> = (
+  c: Context,
+  events: WSEvents<T>,
+  options?: U
+) => Promise<Response | void> | Response | void
+
+/**
+ * Create a WebSocket adapter/helper
+ */
+export const defineWebSocketHelper = <T = unknown, U = any>(
+  handler: WebSocketHelperDefineHandler<T, U>
+): UpgradeWebSocket<T, U> => {
+  return ((
+    ...args:
+      | [createEvents: (c: Context) => WSEvents<T> | Promise<WSEvents<T>>, options?: U]
+      | [c: Context, events: WSEvents<T>, options?: U]
+  ) => {
+    if (typeof args[0] === 'function') {
+      const [createEvents, options] = args
+      return async function upgradeWebSocket(c, next) {
+        const events = await createEvents(c)
+        const result = await handler(c, events, options as U)
+        if (result) {
+          return result
+        }
+        await next()
+      }
+    } else {
+      const [c, events, options] = args as [c: Context, events: WSEvents<T>, options?: U]
+      return (async () => {
+        const upgraded = await handler(c, events, options as U)
+        if (!upgraded) {
+          throw new Error('Failed to upgrade WebSocket')
+        }
+        return upgraded
+      })()
+    }
+  }) as UpgradeWebSocket<T, U>
+}

package/plugins/acryl-router/src/core/http-exception.test.ts

@@ -0,0 +1,45 @@
+import { HTTPException } from './http-exception.ts'
+
+describe('HTTPException', () => {
+  it('Should be 401 HTTP exception object', async () => {
+    // We should throw an exception if is not authorized
+    // because next handlers should not be fired.
+    const exception = new HTTPException(401, {
+      message: 'Unauthorized',
+    })
+    const res = exception.getResponse()
+
+    expect(res.status).toBe(401)
+    expect(await res.text()).toBe('Unauthorized')
+    expect(exception.status).toBe(401)
+    expect(exception.message).toBe('Unauthorized')
+  })
+
+  it('Should be accessible to the object causing the exception', async () => {
+    // We should pass the cause of the error to the cause option
+    // because it makes debugging easier.
+    const error = new Error('Server Error')
+    const exception = new HTTPException(500, {
+      message: 'Internal Server Error',
+      cause: error,
+    })
+    const res = exception.getResponse()
+
+    expect(res.status).toBe(500)
+    expect(await res.text()).toBe('Internal Server Error')
+    expect(exception.status).toBe(500)
+    expect(exception.message).toBe('Internal Server Error')
+    expect(exception.cause).toBe(error)
+  })
+
+  it('Should prioritize the status code over the code in the response', async () => {
+    const exception = new HTTPException(400, {
+      res: new Response('An exception', {
+        status: 200,
+      }),
+    })
+    const res = exception.getResponse()
+    expect(res.status).toBe(400)
+    expect(await res.text()).toBe('An exception')
+  })
+})

package/plugins/acryl-router/src/core/http-exception.ts

@@ -0,0 +1,77 @@
+/**
+ * @module
+ * This module provides the `HTTPException` class.
+ */
+
+import type { ContentfulStatusCode } from './utils/http-status.ts'
+
+/**
+ * Options for creating an `HTTPException`.
+ * @property res - Optional response object to use.
+ * @property message - Optional custom error message.
+ * @property cause - Optional cause of the error.
+ */
+type HTTPExceptionOptions = {
+  res?: Response
+  message?: string
+  cause?: unknown
+}
+
+/**
+ * `HTTPException` must be used when a fatal error such as authentication failure occurs.
+ *
+ *
+ * @param {StatusCode} status - status code of HTTPException
+ * @param {HTTPExceptionOptions} options - options of HTTPException
+ * @param {HTTPExceptionOptions["res"]} options.res - response of options of HTTPException
+ * @param {HTTPExceptionOptions["message"]} options.message - message of options of HTTPException
+ * @param {HTTPExceptionOptions["cause"]} options.cause - cause of options of HTTPException
+ *
+ * @example
+ * ```ts
+ * import { HTTPException } from 'acryl-router'
+ *
+ * // ...
+ *
+ * app.post('/auth', async (c, next) => {
+ *   // authentication
+ *   if (authorized === false) {
+ *     throw new HTTPException(401, { message: 'Custom error message' })
+ *   }
+ *   await next()
+ * })
+ * ```
+ */
+export class HTTPException extends Error {
+  readonly res?: Response
+  readonly status: ContentfulStatusCode
+
+  /**
+   * Creates an instance of `HTTPException`.
+   * @param status - HTTP status code for the exception. Defaults to 500.
+   * @param options - Additional options for the exception.
+   */
+  constructor(status: ContentfulStatusCode = 500, options?: HTTPExceptionOptions) {
+    super(options?.message, { cause: options?.cause })
+    this.res = options?.res
+    this.status = status
+  }
+
+  /**
+   * Returns the response object associated with the exception.
+   * If a response object is not provided, a new response is created with the error message and status code.
+   * @returns The response object.
+   */
+  getResponse(): Response {
+    if (this.res) {
+      const newResponse = new Response(this.res.body, {
+        status: this.status,
+        headers: this.res.headers,
+      })
+      return newResponse
+    }
+    return new Response(this.message, {
+      status: this.status,
+    })
+  }
+}

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

@@ -0,0 +1,53 @@
+/**
+ * @module
+ *
+ * App - Web Framework built on Web Standards
+ *
+ * @example
+ * ```ts
+ * import { App } from 'acryl-router'
+ * const app = new App()
+ *
+ * app.get('/', (c) => c.text('App!'))
+ *
+ * export default app
+ * ```
+ */
+
+import { App } from './app.ts'
+
+/**
+ * Types for environment variables, error handlers, handlers, middleware handlers, and more.
+ */
+export type {
+  Env,
+  ErrorHandler,
+  Handler,
+  MiddlewareHandler,
+  Next,
+  NotFoundResponse,
+  NotFoundHandler,
+  ValidationTargets,
+  Input,
+  Schema,
+  ToSchema,
+  TypedResponse,
+} from './types.ts'
+/**
+ * Types for context, context variable map, context renderer, and execution context.
+ */
+export { Context } from './context.ts'
+export type { ContextVariableMap, ContextRenderer, ExecutionContext } from './context.ts'
+/**
+ * Type for AppRequest.
+ */
+export type { AppRequest } from './request.ts'
+/**
+ * Types for inferring request and response types and client request options.
+ */
+export type { InferRequestType, InferResponseType, ClientRequestOptions } from './client/index.ts'
+
+/**
+ * App framework for building web applications.
+ */
+export { App }