acrylblends 0.3.0 → 0.4.0

package/plugins/acryl-router/src/core/utils/url.ts

@@ -0,0 +1,337 @@
+/**
+ * @module
+ * URL utility.
+ */
+
+export type Pattern = readonly [string, string, RegExp | true] | '*'
+
+export const splitPath = (path: string): string[] => {
+  const paths = path.split('/')
+  if (paths[0] === '') {
+    paths.shift()
+  }
+  return paths
+}
+
+export const splitRoutingPath = (routePath: string): string[] => {
+  const { groups, path } = extractGroupsFromPath(routePath)
+
+  const paths = splitPath(path)
+  return replaceGroupMarks(paths, groups)
+}
+
+const extractGroupsFromPath = (path: string): { groups: [string, string][]; path: string } => {
+  const groups: [string, string][] = []
+
+  path = path.replace(/\{[^}]+\}/g, (match, index) => {
+    const mark = `@${index}`
+    groups.push([mark, match])
+    return mark
+  })
+
+  return { groups, path }
+}
+
+const replaceGroupMarks = (paths: string[], groups: [string, string][]): string[] => {
+  for (let i = groups.length - 1; i >= 0; i--) {
+    const [mark] = groups[i]
+
+    for (let j = paths.length - 1; j >= 0; j--) {
+      if (paths[j].includes(mark)) {
+        paths[j] = paths[j].replace(mark, groups[i][1])
+        break
+      }
+    }
+  }
+
+  return paths
+}
+
+const patternCache: { [key: string]: Pattern } = {}
+export const getPattern = (label: string, next?: string): Pattern | null => {
+  // *            => wildcard
+  // :id{[0-9]+}  => ([0-9]+)
+  // :id          => (.+)
+
+  if (label === '*') {
+    return '*'
+  }
+
+  const match = label.match(/^\:([^\{\}]+)(?:\{(.+)\})?$/)
+  if (match) {
+    const cacheKey = `${label}#${next}`
+    if (!patternCache[cacheKey]) {
+      if (match[2]) {
+        patternCache[cacheKey] =
+          next && next[0] !== ':' && next[0] !== '*'
+            ? [cacheKey, match[1], new RegExp(`^${match[2]}(?=/${next})`)]
+            : [label, match[1], new RegExp(`^${match[2]}$`)]
+      } else {
+        patternCache[cacheKey] = [label, match[1], true]
+      }
+    }
+
+    return patternCache[cacheKey]
+  }
+
+  return null
+}
+
+type Decoder = (str: string) => string
+export const tryDecode = (str: string, decoder: Decoder): string => {
+  try {
+    return decoder(str)
+  } catch {
+    return str.replace(/(?:%[0-9A-Fa-f]{2})+/g, (match) => {
+      try {
+        return decoder(match)
+      } catch {
+        return match
+      }
+    })
+  }
+}
+
+/**
+ * Try to apply decodeURI() to given string.
+ * If it fails, skip invalid percent encoding or invalid UTF-8 sequences, and apply decodeURI() to the rest as much as possible.
+ * @param str The string to decode.
+ * @returns The decoded string that sometimes contains undecodable percent encoding.
+ * @example
+ * tryDecodeURI('Hello%20World') // 'Hello World'
+ * tryDecodeURI('Hello%20World/%A4%A2') // 'Hello World/%A4%A2'
+ */
+export const tryDecodeURI = (str: string): string => tryDecode(str, decodeURI)
+
+export const getPath = (request: Request): string => {
+  const url = request.url
+  const start = url.indexOf('/', url.indexOf(':') + 4)
+  let i = start
+  for (; i < url.length; i++) {
+    const charCode = url.charCodeAt(i)
+    if (charCode === 37) {
+      // '%'
+      // If the path contains percent encoding, use `indexOf()` to find '?' or '#' and return the result immediately.
+      // Although this is a performance disadvantage, it is acceptable since we prefer cases that do not include percent encoding.
+      const queryIndex = url.indexOf('?', i)
+      const hashIndex = url.indexOf('#', i)
+      const end =
+        queryIndex === -1
+          ? hashIndex === -1
+            ? undefined
+            : hashIndex
+          : hashIndex === -1
+            ? queryIndex
+            : Math.min(queryIndex, hashIndex)
+      const path = url.slice(start, end)
+      return tryDecodeURI(path.includes('%25') ? path.replace(/%25/g, '%2525') : path)
+    } else if (charCode === 63 || charCode === 35) {
+      // '?' or '#'
+      break
+    }
+  }
+  return url.slice(start, i)
+}
+
+/**
+ * @deprecated
+ * Use the `URL` API instead.
+ */
+export const getQueryStrings = (url: string): string => {
+  const queryIndex = url.indexOf('?', 8)
+  if (queryIndex === -1) {
+    return ''
+  }
+
+  const hashIndex = url.indexOf('#', 8)
+  return hashIndex === -1
+    ? url.slice(queryIndex)
+    : queryIndex < hashIndex
+      ? url.slice(queryIndex, hashIndex)
+      : ''
+}
+
+export const getPathNoStrict = (request: Request): string => {
+  const result = getPath(request)
+
+  // if strict routing is false => `/hello/hey/` and `/hello/hey` are treated the same
+  return result.length > 1 && result.at(-1) === '/' ? result.slice(0, -1) : result
+}
+
+/**
+ * Merge paths.
+ * @param {string[]} ...paths - The paths to merge.
+ * @returns {string} The merged path.
+ * @example
+ * mergePath('/api', '/users') // '/api/users'
+ * mergePath('/api/', '/users') // '/api/users'
+ * mergePath('/api', '/') // '/api'
+ * mergePath('/api/', '/') // '/api/'
+ */
+export const mergePath: (...paths: string[]) => string = (
+  base: string | undefined,
+  sub: string | undefined,
+  ...rest: string[]
+): string => {
+  if (rest.length) {
+    sub = mergePath(sub as string, ...rest)
+  }
+  return `${base?.[0] === '/' ? '' : '/'}${base}${
+    sub === '/' ? '' : `${base?.at(-1) === '/' ? '' : '/'}${sub?.[0] === '/' ? sub.slice(1) : sub}`
+  }`
+}
+
+export const checkOptionalParameter = (path: string): string[] | null => {
+  /*
+    If path is `/api/animals/:type?` it will return:
+    [`/api/animals`, `/api/animals/:type`]
+    in other cases it will return null
+  */
+
+  if (path.charCodeAt(path.length - 1) !== 63 || !path.includes(':')) {
+    return null
+  }
+
+  const segments = path.split('/')
+  const results: string[] = []
+  let basePath = ''
+
+  segments.forEach((segment) => {
+    if (segment !== '' && !/\:/.test(segment)) {
+      basePath += '/' + segment
+    } else if (/\:/.test(segment)) {
+      if (segment.charCodeAt(segment.length - 1) === 63) {
+        if (results.length === 0 && basePath === '') {
+          results.push('/')
+        } else {
+          results.push(basePath)
+        }
+        const optionalSegment = segment.slice(0, -1)
+        basePath += '/' + optionalSegment
+        results.push(basePath)
+      } else {
+        basePath += '/' + segment
+      }
+    }
+  })
+
+  return results.filter((v, i, a) => a.indexOf(v) === i)
+}
+
+export const tryDecodeURIComponent = (str: string): string =>
+  str.indexOf('%') !== -1 ? tryDecode(str, decodeURIComponent_) : str
+
+// Optimized
+const _decodeURI = (value: string): string => {
+  if (value.indexOf('+') !== -1) {
+    value = value.replace(/\+/g, ' ')
+  }
+  return tryDecodeURIComponent(value)
+}
+
+const _getQueryParam = (
+  url: string,
+  key?: string,
+  multiple?: boolean
+): string | undefined | Record<string, string> | string[] | Record<string, string[]> => {
+  const hashIndex = url.indexOf('#', 8)
+  if (hashIndex !== -1) {
+    url = url.slice(0, hashIndex)
+  }
+
+  let encoded
+
+  if (!multiple && key && key.indexOf('%') === -1 && key.indexOf('+') === -1) {
+    // optimized for unencoded key
+
+    let keyIndex = url.indexOf('?', 8)
+    if (keyIndex === -1) {
+      return undefined
+    }
+    if (!url.startsWith(key, keyIndex + 1)) {
+      keyIndex = url.indexOf(`&${key}`, keyIndex + 1)
+    }
+    while (keyIndex !== -1) {
+      const trailingKeyCode = url.charCodeAt(keyIndex + key.length + 1)
+      if (trailingKeyCode === 61) {
+        const valueIndex = keyIndex + key.length + 2
+        const endIndex = url.indexOf('&', valueIndex)
+        return _decodeURI(url.slice(valueIndex, endIndex === -1 ? undefined : endIndex))
+      } else if (trailingKeyCode == 38 || isNaN(trailingKeyCode)) {
+        return ''
+      }
+      keyIndex = url.indexOf(`&${key}`, keyIndex + 1)
+    }
+
+    encoded = /[%+]/.test(url)
+    if (!encoded) {
+      return undefined
+    }
+    // fallback to default routine
+  }
+
+  const results: Record<string, string> | Record<string, string[]> = Object.create(null)
+  encoded ??= /[%+]/.test(url)
+
+  let keyIndex = url.indexOf('?', 8)
+  while (keyIndex !== -1) {
+    const nextKeyIndex = url.indexOf('&', keyIndex + 1)
+    let valueIndex = url.indexOf('=', keyIndex)
+    if (valueIndex > nextKeyIndex && nextKeyIndex !== -1) {
+      valueIndex = -1
+    }
+    let name = url.slice(
+      keyIndex + 1,
+      valueIndex === -1 ? (nextKeyIndex === -1 ? undefined : nextKeyIndex) : valueIndex
+    )
+    if (encoded) {
+      name = _decodeURI(name)
+    }
+
+    keyIndex = nextKeyIndex
+
+    if (name === '') {
+      continue
+    }
+
+    let value
+    if (valueIndex === -1) {
+      value = ''
+    } else {
+      value = url.slice(valueIndex + 1, nextKeyIndex === -1 ? undefined : nextKeyIndex)
+      if (encoded) {
+        value = _decodeURI(value)
+      }
+    }
+
+    if (multiple) {
+      if (!(results[name] && Array.isArray(results[name]))) {
+        results[name] = []
+      }
+      ;(results[name] as string[]).push(value)
+    } else {
+      results[name] ??= value
+    }
+  }
+
+  return key ? results[key] : results
+}
+
+export const getQueryParam: (
+  url: string,
+  key?: string
+) => string | undefined | Record<string, string> = _getQueryParam as (
+  url: string,
+  key?: string
+) => string | undefined | Record<string, string>
+
+export const getQueryParams = (
+  url: string,
+  key?: string
+): string[] | undefined | Record<string, string[]> => {
+  return _getQueryParam(url, key, true) as string[] | undefined | Record<string, string[]>
+}
+
+// `decodeURIComponent` is a long name.
+// By making it a function, we can use it commonly when minified, reducing the amount of code.
+export const decodeURIComponent_ = decodeURIComponent

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

@@ -0,0 +1,8 @@
+/**
+ * @module
+ * Validator for App.
+ */
+
+export { validator } from './validator.ts'
+export type { ValidationFunction } from './validator.ts'
+export type { InferInput } from './utils.ts'

package/plugins/acryl-router/src/core/validator/utils.test.ts

@@ -0,0 +1,82 @@
+import { expectTypeOf } from 'vitest'
+import type { InferInput, IsLiteralUnion } from './utils.ts'
+
+describe('IsLiteralUnion', () => {
+  it('should return true for literal union types', () => {
+    expectTypeOf<IsLiteralUnion<'asc' | 'desc', string>>().toEqualTypeOf<true>()
+  })
+
+  it('should return false for single literal', () => {
+    expectTypeOf<IsLiteralUnion<'asc', string>>().toEqualTypeOf<false>()
+  })
+
+  it('should return false for wide string type', () => {
+    expectTypeOf<IsLiteralUnion<string, string>>().toEqualTypeOf<false>()
+  })
+
+  it('should return true for literal union with undefined', () => {
+    expectTypeOf<IsLiteralUnion<'asc' | 'desc' | undefined, string>>().toEqualTypeOf<true>()
+  })
+})
+
+describe('InferInput', () => {
+  it('should preserve literal union types for query', () => {
+    expectTypeOf<InferInput<{ orderBy: 'asc' | 'desc' }, 'query'>>().toEqualTypeOf<{
+      orderBy: 'asc' | 'desc'
+    }>()
+  })
+
+  it('should convert string to string | string[] for query', () => {
+    expectTypeOf<InferInput<{ page: string }, 'query'>>().toEqualTypeOf<{
+      page: string | string[]
+    }>()
+  })
+
+  it('should convert number to string | string[] for query', () => {
+    expectTypeOf<InferInput<{ page: number }, 'query'>>().toEqualTypeOf<{
+      page: string | string[]
+    }>()
+  })
+
+  it('should preserve optional union (T | undefined) for query', () => {
+    expectTypeOf<InferInput<{ name?: string | undefined }, 'query'>>().toEqualTypeOf<{
+      name?: string | undefined
+    }>()
+  })
+
+  it('should preserve literal union with undefined for query', () => {
+    expectTypeOf<InferInput<{ orderBy?: 'asc' | 'desc' | undefined }, 'query'>>().toEqualTypeOf<{
+      orderBy?: 'asc' | 'desc' | undefined
+    }>()
+  })
+
+  it('should convert unknown to string | string[] for query (coerce support)', () => {
+    expectTypeOf<InferInput<{ page: unknown }, 'query'>>().toEqualTypeOf<{
+      page: string | string[]
+    }>()
+  })
+
+  it('should handle object | undefined for query (optional schema)', () => {
+    expectTypeOf<InferInput<{ name?: string | undefined } | undefined, 'query'>>().toEqualTypeOf<
+      { name?: string | undefined } | undefined
+    >()
+  })
+
+  it('should convert string to string for param', () => {
+    expectTypeOf<InferInput<{ id: string }, 'param'>>().toEqualTypeOf<{
+      id: string
+    }>()
+  })
+
+  it('should convert string to string for header', () => {
+    expectTypeOf<InferInput<{ authorization: string }, 'header'>>().toEqualTypeOf<{
+      authorization: string
+    }>()
+  })
+
+  it('should convert string to string for cookie', () => {
+    expectTypeOf<InferInput<{ session: string }, 'cookie'>>().toEqualTypeOf<{
+      session: string
+    }>()
+  })
+})

package/plugins/acryl-router/src/core/validator/utils.ts

@@ -0,0 +1,69 @@
+import type { FormValue, ParsedFormValue, ValidationTargets } from '../types.ts'
+import type { UnionToIntersection } from '../utils/types.ts'
+
+/**
+ * Checks if T is a literal union type (e.g., 'asc' | 'desc')
+ * that should be preserved in input types.
+ * Returns true for union literals, false for single literals or wide types.
+ */
+export type IsLiteralUnion<T, Base> = [Exclude<T, undefined>] extends [Base]
+  ? [Exclude<T, undefined>] extends [UnionToIntersection<Exclude<T, undefined>>]
+    ? false
+    : true
+  : false
+
+// Check if type is an optional union (T | undefined) but not unknown/any
+type IsOptionalUnion<T> = [unknown] extends [T]
+  ? false // unknown or any
+  : undefined extends T
+    ? true
+    : false
+
+// Helper to force TypeScript to expand type aliases
+type SimplifyDeep<T> = { [K in keyof T]: T[K] } & {}
+
+type InferInputInner<
+  Output,
+  Target extends keyof ValidationTargets,
+  T extends FormValue,
+> = SimplifyDeep<{
+  [K in keyof Output]: IsLiteralUnion<Output[K], string> extends true
+    ? Output[K]
+    : IsOptionalUnion<Output[K]> extends true
+      ? Output[K]
+      : Target extends 'form'
+        ? T | T[]
+        : Target extends 'query'
+          ? string | string[]
+          : Target extends 'param'
+            ? string
+            : Target extends 'header'
+              ? string
+              : Target extends 'cookie'
+                ? string
+                : unknown
+}>
+
+/**
+ * Utility type to infer input types for validation targets.
+ * Preserves literal union types (e.g., 'asc' | 'desc') while using
+ * the default ValidationTargets type for other values.
+ *
+ * @example
+ * ```ts
+ * // In @acryl-router/zod-validator or similar:
+ * type Input = InferInput<z.input<Schema>, 'query'>
+ * // { orderBy: 'asc' | 'desc', page: string | string[] }
+ * ```
+ */
+export type InferInput<
+  Output,
+  Target extends keyof ValidationTargets,
+  T extends FormValue = ParsedFormValue,
+> = [Exclude<Output, undefined>] extends [never]
+  ? {}
+  : [Exclude<Output, undefined>] extends [object]
+    ? undefined extends Output
+      ? SimplifyDeep<InferInputInner<Exclude<Output, undefined>, Target, T>> | undefined
+      : SimplifyDeep<InferInputInner<Output, Target, T>>
+    : {}