acrylblends 0.2.0 → 0.4.0

package/plugins/acryl-router/src/core/middleware/language/language.ts

@@ -0,0 +1,314 @@
+/**
+ * @module
+ * Language module for App.
+ */
+import type { Context } from '../../context.ts'
+import { setCookie, getCookie } from '../../helper/cookie/index.ts'
+import type { MiddlewareHandler } from '../../types.ts'
+import { parseAccept } from '../../utils/accept.ts'
+
+export type DetectorType = 'path' | 'querystring' | 'cookie' | 'header'
+export type CacheType = 'cookie'
+
+export interface DetectorOptions {
+  /** Order of language detection strategies */
+  order: DetectorType[]
+  /** Query parameter name for language */
+  lookupQueryString: string
+  /** Cookie name for language */
+  lookupCookie: string
+  /** Index in URL path where language code appears */
+  lookupFromPathIndex: number
+  /** Header key for language detection */
+  lookupFromHeaderKey: string
+  /** Caching strategies */
+  caches: CacheType[] | false
+  /** Cookie configuration options */
+  cookieOptions?: {
+    domain?: string
+    path?: string
+    sameSite?: 'Strict' | 'Lax' | 'None'
+    secure?: boolean
+    maxAge?: number
+    httpOnly?: boolean
+  }
+  /** Whether to ignore case in language codes */
+  ignoreCase: boolean
+  /** Default language if none detected */
+  fallbackLanguage: string
+  /** List of supported language codes */
+  supportedLanguages: string[]
+  /** Optional function to transform detected language codes */
+  convertDetectedLanguage?: (lang: string) => string
+  /** Enable debug logging */
+  debug?: boolean
+}
+
+export interface LanguageVariables {
+  language: string
+}
+
+export const DEFAULT_OPTIONS: DetectorOptions = {
+  order: ['querystring', 'cookie', 'header'],
+  lookupQueryString: 'lang',
+  lookupCookie: 'language',
+  lookupFromHeaderKey: 'accept-language',
+  lookupFromPathIndex: 0,
+  caches: ['cookie'],
+  ignoreCase: true,
+  fallbackLanguage: 'en',
+  supportedLanguages: ['en'],
+  cookieOptions: {
+    sameSite: 'Strict',
+    secure: true,
+    maxAge: 365 * 24 * 60 * 60,
+    httpOnly: true,
+  },
+  debug: false,
+}
+/**
+ * Parse Accept-Language header values with quality scores
+ * @param header Accept-Language header string
+ * @returns Array of parsed languages with quality scores
+ */
+export function parseAcceptLanguage(header: string): Array<{ lang: string; q: number }> {
+  return parseAccept(header).map(({ type, q }) => ({ lang: type, q }))
+}
+
+/**
+ * Validate and normalize language codes
+ * @param lang Language code to normalize
+ * @param options Detector options
+ * @returns Normalized language code or undefined
+ */
+export const normalizeLanguage = (
+  lang: string | null | undefined,
+  options: DetectorOptions
+): string | undefined => {
+  if (!lang) {
+    return undefined
+  }
+
+  try {
+    let normalizedLang = lang.trim()
+    if (options.convertDetectedLanguage) {
+      normalizedLang = options.convertDetectedLanguage(normalizedLang)
+    }
+
+    const compLang = options.ignoreCase ? normalizedLang.toLowerCase() : normalizedLang
+    const compSupported = options.supportedLanguages.map((l) =>
+      options.ignoreCase ? l.toLowerCase() : l
+    )
+
+    // Exact match
+    const exactIndex = compSupported.indexOf(compLang)
+    if (exactIndex !== -1) {
+      return options.supportedLanguages[exactIndex]
+    }
+
+    // Progressive truncation (RFC 4647 Lookup)
+    let longestMatchIndex = -1
+    let longestMatchLength = -1
+    for (let i = 0; i < compSupported.length; i++) {
+      const candidate = compSupported[i]
+      if (
+        candidate.length < compLang.length &&
+        candidate.length > longestMatchLength &&
+        compLang.startsWith(candidate) &&
+        compLang[candidate.length] === '-'
+      ) {
+        longestMatchIndex = i
+        longestMatchLength = candidate.length
+      }
+    }
+    if (longestMatchIndex !== -1) {
+      return options.supportedLanguages[longestMatchIndex]
+    }
+
+    return undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Detects language from query parameter
+ */
+export const detectFromQuery = (c: Context, options: DetectorOptions): string | undefined => {
+  const query = c.req.query(options.lookupQueryString)
+  return normalizeLanguage(query, options)
+}
+
+/**
+ * Detects language from cookie
+ */
+export const detectFromCookie = (c: Context, options: DetectorOptions): string | undefined => {
+  const cookie = getCookie(c, options.lookupCookie)
+  return normalizeLanguage(cookie, options)
+}
+
+/**
+ * Detects language from Accept-Language header
+ */
+export function detectFromHeader(c: Context, options: DetectorOptions): string | undefined {
+  try {
+    const acceptLanguage = c.req.header(options.lookupFromHeaderKey)
+    if (!acceptLanguage) {
+      return undefined
+    }
+
+    const languages = parseAcceptLanguage(acceptLanguage)
+    for (const { lang, q } of languages) {
+      // A quality value of 0 means the language is explicitly rejected
+      // (RFC 9110 §12.5.4), so it must not be detected.
+      if (q === 0) {
+        continue
+      }
+      const normalizedLang = normalizeLanguage(lang, options)
+      if (normalizedLang) {
+        return normalizedLang
+      }
+    }
+    return undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Detects language from URL path
+ */
+export function detectFromPath(c: Context, options: DetectorOptions): string | undefined {
+  const url = new URL(c.req.url)
+  const pathSegments = url.pathname.split('/').filter(Boolean)
+  const langSegment = pathSegments[options.lookupFromPathIndex]
+  return normalizeLanguage(langSegment, options)
+}
+
+/**
+ * Collection of all language detection strategies
+ */
+export const detectors = {
+  querystring: detectFromQuery,
+  cookie: detectFromCookie,
+  header: detectFromHeader,
+  path: detectFromPath,
+} as const
+
+/** Type for detector functions */
+export type DetectorFunction = (c: Context, options: DetectorOptions) => string | undefined
+
+/** Type-safe detector map */
+export type Detectors = Record<keyof typeof detectors, DetectorFunction>
+
+/**
+ * Validate detector options
+ * @param options Detector options to validate
+ * @throws Error if options are invalid
+ */
+export function validateOptions(options: DetectorOptions): void {
+  if (!options.supportedLanguages.includes(options.fallbackLanguage)) {
+    throw new Error('Fallback language must be included in supported languages')
+  }
+
+  if (options.lookupFromPathIndex < 0) {
+    throw new Error('Path index must be non-negative')
+  }
+
+  if (!options.order.every((detector) => Object.keys(detectors).includes(detector))) {
+    throw new Error('Invalid detector type in order array')
+  }
+}
+
+/**
+ * Cache detected language
+ */
+function cacheLanguage(c: Context, language: string, options: DetectorOptions): void {
+  if (!Array.isArray(options.caches) || !options.caches.includes('cookie')) {
+    return
+  }
+
+  try {
+    setCookie(c, options.lookupCookie, language, options.cookieOptions)
+  } catch (error) {
+    if (options.debug) {
+      console.error('Failed to cache language:', error)
+    }
+  }
+}
+
+/**
+ * Detect language from request
+ */
+const detectLanguage = (c: Context, options: DetectorOptions): string => {
+  let detectedLang: string | undefined
+
+  for (const detectorName of options.order) {
+    const detector = detectors[detectorName]
+
+    try {
+      detectedLang = detector(c, options)
+      if (detectedLang) {
+        if (options.debug) {
+          console.log(`Language detected from ${detectorName}: ${detectedLang}`)
+        }
+        break
+      }
+    } catch (error) {
+      if (options.debug) {
+        console.error(`Error in ${detectorName} detector:`, error)
+      }
+      continue
+    }
+  }
+
+  const finalLang = detectedLang || options.fallbackLanguage
+
+  if (detectedLang && options.caches) {
+    cacheLanguage(c, finalLang, options)
+  }
+
+  return finalLang
+}
+
+/**
+ * Language detector middleware factory
+ * @param userOptions Configuration options for the language detector
+ * @returns App middleware function
+ *
+ * @example
+ * ```ts
+ * type Variables = LanguageVariables
+ * const app = new App<{ Variables: Variables }>()
+ *
+ * app.use(
+ *   languageDetector({
+ *     supportedLanguages: ['en', 'ja'], // Must include fallback
+ *     fallbackLanguage: 'en', // Required
+ *   })
+ * )
+ *
+ * app.get('/', (c) => {
+ *   const lang = c.get('language')
+ *   return c.text(`Current language: ${lang}`)
+ * })
+ * ```
+ */
+export const languageDetector = (userOptions: Partial<DetectorOptions>): MiddlewareHandler => {
+  const options: DetectorOptions = {
+    ...DEFAULT_OPTIONS,
+    ...userOptions,
+    cookieOptions: {
+      ...DEFAULT_OPTIONS.cookieOptions,
+      ...userOptions.cookieOptions,
+    },
+  }
+
+  validateOptions(options)
+
+  return async function languageDetector(ctx, next) {
+    const lang = detectLanguage(ctx, options)
+    ctx.set('language', lang)
+    await next()
+  }
+}

package/plugins/acryl-router/src/core/middleware/logger/index.test.ts

@@ -0,0 +1,204 @@
+import { logger } from './index.ts'
+import { App } from '../../app.ts'
+
+describe('Logger by Middleware', () => {
+  let app: App
+  let log: string
+
+  beforeEach(() => {
+    function sleep(time: number) {
+      return new Promise((resolve) => setTimeout(resolve, time))
+    }
+
+    app = new App()
+
+    const logFn = (str: string) => {
+      log = str
+    }
+
+    const shortRandomString = 'acryl'
+    const longRandomString = 'acryl'.repeat(1000)
+
+    app.use('*', logger(logFn))
+    app.get('/short', (c) => c.text(shortRandomString))
+    app.get('/long', (c) => c.text(longRandomString))
+    app.get('/seconds', async (c) => {
+      await sleep(1000)
+
+      return c.text(longRandomString)
+    })
+    app.get('/empty', (c) => c.text(''))
+    app.get('/redirect', (c) => {
+      return c.redirect('/empty', 301)
+    })
+    app.get('/server-error', (c) => {
+      const res = new Response('', { status: 511 })
+      if (c.req.query('status')) {
+        // test status code not yet supported by runtime `Response` object
+        Object.defineProperty(res, 'status', { value: parseInt(c.req.query('status') as string) })
+      }
+      return res
+    })
+  })
+
+  it('Log status 200 with empty body', async () => {
+    const res = await app.request('http://localhost/empty')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(log.startsWith('--> GET /empty \x1b[32m200\x1b[0m')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+
+  it('Log status 200 with small body', async () => {
+    const res = await app.request('http://localhost/short')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(log.startsWith('--> GET /short \x1b[32m200\x1b[0m')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+
+  it('Log status 200 with small body and query param', async () => {
+    const res = await app.request('http://localhost/short?foo=bar')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(log.startsWith('--> GET /short?foo=bar \x1b[32m200\x1b[0m')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+
+  it('Log status 200 with big body', async () => {
+    const res = await app.request('http://localhost/long')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(log.startsWith('--> GET /long \x1b[32m200\x1b[0m')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+
+  it('Time in seconds', async () => {
+    const res = await app.request('http://localhost/seconds')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(log.startsWith('--> GET /seconds \x1b[32m200\x1b[0m')).toBe(true)
+    expect(log).toMatch(/1s/)
+  })
+
+  it('Log status 301 with empty body', async () => {
+    const res = await app.request('http://localhost/redirect')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(301)
+    expect(log.startsWith('--> GET /redirect \x1b[36m301\x1b[0m')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+
+  it('Log status 404', async () => {
+    const msg = 'Default 404 Not Found'
+    app.all('*', (c) => {
+      return c.text(msg, 404)
+    })
+    const res = await app.request('http://localhost/notfound')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(404)
+    expect(log.startsWith('--> GET /notfound \x1b[33m404\x1b[0m')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+
+  it('Log status 511 with empty body', async () => {
+    const res = await app.request('http://localhost/server-error')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(511)
+    expect(log.startsWith('--> GET /server-error \x1b[31m511\x1b[0m')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+
+  it('Log status 100', async () => {
+    const res = await app.request('http://localhost/server-error?status=100')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(100)
+    expect(log.startsWith('--> GET /server-error?status=100 100')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+
+  it('Log status 700', async () => {
+    const res = await app.request('http://localhost/server-error?status=700')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(700)
+    expect(log.startsWith('--> GET /server-error?status=700 700')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+})
+
+describe('Logger by Middleware in NO_COLOR', () => {
+  let app: App
+  let log: string
+
+  beforeEach(() => {
+    vi.stubEnv('NO_COLOR', '1')
+    function sleep(time: number) {
+      return new Promise((resolve) => setTimeout(resolve, time))
+    }
+
+    app = new App()
+
+    const logFn = (str: string) => {
+      log = str
+    }
+
+    const shortRandomString = 'acryl'
+    const longRandomString = 'acryl'.repeat(1000)
+
+    app.use('*', logger(logFn))
+    app.get('/short', (c) => c.text(shortRandomString))
+    app.get('/long', (c) => c.text(longRandomString))
+    app.get('/seconds', async (c) => {
+      await sleep(1000)
+
+      return c.text(longRandomString)
+    })
+    app.get('/empty', (c) => c.text(''))
+  })
+  afterAll(() => {
+    vi.unstubAllEnvs()
+  })
+  it('Log status 200 with empty body', async () => {
+    const res = await app.request('http://localhost/empty')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(log.startsWith('--> GET /empty 200')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+
+  it('Log status 200 with small body', async () => {
+    const res = await app.request('http://localhost/short')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(log.startsWith('--> GET /short 200')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+
+  it('Log status 200 with big body', async () => {
+    const res = await app.request('http://localhost/long')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(log.startsWith('--> GET /long 200')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+
+  it('Time in seconds', async () => {
+    const res = await app.request('http://localhost/seconds')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(200)
+    expect(log.startsWith('--> GET /seconds 200')).toBe(true)
+    expect(log).toMatch(/1s/)
+  })
+
+  it('Log status 404', async () => {
+    const msg = 'Default 404 Not Found'
+    app.all('*', (c) => {
+      return c.text(msg, 404)
+    })
+    const res = await app.request('http://localhost/notfound')
+    expect(res).not.toBeNull()
+    expect(res.status).toBe(404)
+    expect(log.startsWith('--> GET /notfound 404')).toBe(true)
+    expect(log).toMatch(/m?s$/)
+  })
+})

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

@@ -0,0 +1,95 @@
+/**
+ * @module
+ * Logger Middleware for App.
+ */
+
+import type { MiddlewareHandler } from '../../types.ts'
+import { getColorEnabledAsync } from '../../utils/color.ts'
+
+const LogPrefix = {
+  Outgoing: '-->',
+  Incoming: '<--',
+  Error: 'xxx',
+} as const
+type LogPrefix = (typeof LogPrefix)[keyof typeof LogPrefix]
+
+const humanize = (times: string[]) => {
+  const [delimiter, separator] = [',', '.']
+
+  const orderTimes = times.map((v) => v.replace(/(\d)(?=(\d\d\d)+(?!\d))/g, '$1' + delimiter))
+
+  return orderTimes.join(separator)
+}
+
+const time = (start: number) => {
+  const delta = Date.now() - start
+  return humanize([delta < 1000 ? delta + 'ms' : Math.round(delta / 1000) + 's'])
+}
+
+const colorStatus = async (status: number) => {
+  const colorEnabled = await getColorEnabledAsync()
+  if (colorEnabled) {
+    switch ((status / 100) | 0) {
+      case 5: // red = error
+        return `\x1b[31m${status}\x1b[0m`
+      case 4: // yellow = warning
+        return `\x1b[33m${status}\x1b[0m`
+      case 3: // cyan = redirect
+        return `\x1b[36m${status}\x1b[0m`
+      case 2: // green = success
+        return `\x1b[32m${status}\x1b[0m`
+    }
+  }
+  // Fallback to unsupported status code.
+  // E.g.) Bun and Deno supports new Response with 101, but Node.js does not.
+  // And those may evolve to accept more status.
+  return `${status}`
+}
+
+type PrintFunc = (str: string, ...rest: string[]) => void
+
+async function log(
+  fn: PrintFunc,
+  prefix: string,
+  method: string,
+  path: string,
+  status: number = 0,
+  elapsed?: string
+) {
+  const out =
+    prefix === LogPrefix.Incoming
+      ? `${prefix} ${method} ${path}`
+      : `${prefix} ${method} ${path} ${await colorStatus(status)} ${elapsed}`
+  fn(out)
+}
+
+/**
+ * Logger Middleware for App.
+ *
+ *
+ * @param {PrintFunc} [fn=console.log] - Optional function for customized logging behavior.
+ * @returns {MiddlewareHandler} The middleware handler function.
+ *
+ * @example
+ * ```ts
+ * const app = new App()
+ *
+ * app.use(logger())
+ * app.get('/', (c) => c.text('Hello App!'))
+ * ```
+ */
+export const logger = (fn: PrintFunc = console.log): MiddlewareHandler => {
+  return async function logger(c, next) {
+    const { method, url } = c.req
+
+    const path = url.slice(url.indexOf('/', 8))
+
+    await log(fn, LogPrefix.Incoming, method, path)
+
+    const start = Date.now()
+
+    await next()
+
+    await log(fn, LogPrefix.Outgoing, method, path, c.res.status, time(start))
+  }
+}