starlight-server 1.2.0 → 1.5.0

package/dist/validators/number.d.ts

@@ -1,10 +0,0 @@
-import { Validator, type CommonOptions } from './common.js';
-export interface NumberOptions {
-    min?: number;
-    max?: number;
-    float: boolean;
-}
-export declare class NumberValidator extends Validator<NumberOptions> {
-    constructor(options?: Partial<NumberOptions> & Partial<CommonOptions>);
-    validate(fieldName: string, value: unknown): import("@anjianshi/utils").Success<unknown> | import("@anjianshi/utils").Failed<string>;
-}

package/dist/validators/number.js

@@ -1,30 +0,0 @@
-import { success, failed } from '@anjianshi/utils';
-import { Validator } from './common.js';
-export class NumberValidator extends Validator {
-    constructor(options) {
-        super({
-            float: false,
-            ...(options ?? {}),
-        });
-    }
-    validate(fieldName, value) {
-        const superResult = super.validate(fieldName, value);
-        if (!superResult.success)
-            return superResult;
-        value = superResult.data;
-        if (value === null || value === undefined)
-            return superResult;
-        const opt = this.options;
-        if (typeof value === 'string')
-            value = parseFloat(value);
-        if (typeof value !== 'number' || !isFinite(value))
-            return failed(`${fieldName} must be a valid number`);
-        if (!opt.float && value % 1 !== 0)
-            return failed(`${fieldName} must be a integer`);
-        if (typeof opt.min === 'number' && value < opt.min)
-            return failed(`${fieldName} must >= ${opt.min}`);
-        if (typeof opt.max === 'number' && value > opt.max)
-            return failed(`${fieldName} must <= ${opt.max}`);
-        return success(value);
-    }
-}

package/dist/validators/object.d.ts

@@ -1,13 +0,0 @@
-import { Validator } from './common.js';
-/**
- * struct 用于有明确键值对结构的对象；value 用于有任意 key 的对象
- * use `struct` is used for objects with an explicit key-value structure; `value` is used for objects with arbitrary keys.
- */
-export type ObjectOptions = {
-    struct: Record<string, Validator>;
-} | {
-    value: Validator;
-};
-export declare class ObjectValidator extends Validator<ObjectOptions> {
-    validate(fieldName: string, value: unknown): import("@anjianshi/utils").Success<unknown> | import("@anjianshi/utils").Failed<string>;
-}

package/dist/validators/object.js

@@ -1,36 +0,0 @@
-import { success, failed } from '@anjianshi/utils';
-import isPlainObject from 'lodash/isPlainObject.js';
-import { Validator } from './common.js';
-export class ObjectValidator extends Validator {
-    validate(fieldName, value) {
-        const superResult = super.validate(fieldName, value);
-        if (!superResult.success)
-            return superResult;
-        value = superResult.data;
-        if (value === null || value === undefined)
-            return superResult;
-        const opt = this.options;
-        if (!isPlainObject(value))
-            return failed(`${fieldName} should be a plain object`);
-        const formatted = {};
-        if ('struct' in opt) {
-            for (const [key, itemValidator] of Object.entries(opt.struct)) {
-                const itemResult = itemValidator.validate(`${fieldName}["${key}"]`, value[key]);
-                if (itemResult.success)
-                    formatted[key] = itemResult.data;
-                else
-                    return itemResult;
-            }
-        }
-        else {
-            for (const [key, itemValue] of Object.entries(value)) {
-                const itemResult = opt.value.validate(`${fieldName}["${key}"]`, itemValue);
-                if (itemResult.success)
-                    formatted[key] = itemResult.data;
-                else
-                    return itemResult;
-            }
-        }
-        return success(formatted);
-    }
-}

package/dist/validators/string.d.ts

@@ -1,11 +0,0 @@
-import { Validator, type CommonOptions } from './common.js';
-export interface StringOptions {
-    min?: number;
-    max?: number;
-    pattern?: RegExp;
-    trim: boolean;
-}
-export declare class StringValidator extends Validator<StringOptions> {
-    constructor(options?: Partial<StringOptions> & Partial<CommonOptions>);
-    validate(fieldName: string, value: unknown): import("@anjianshi/utils").Success<unknown> | import("@anjianshi/utils").Failed<string>;
-}

package/dist/validators/string.js

@@ -1,29 +0,0 @@
-import { success, failed } from '@anjianshi/utils';
-import { Validator } from './common.js';
-export class StringValidator extends Validator {
-    constructor(options) {
-        super({
-            trim: true,
-            ...(options ?? {}),
-        });
-    }
-    validate(fieldName, value) {
-        const superResult = super.validate(fieldName, value);
-        if (!superResult.success)
-            return superResult;
-        value = superResult.data;
-        if (value === null || value === undefined)
-            return superResult;
-        const opt = this.options;
-        if (typeof value !== 'string')
-            return failed(`${fieldName} should be a string`);
-        const formatted = opt.trim ? value.trim() : value;
-        if (typeof opt.min === 'number' && formatted.length < opt.min)
-            return failed(`${fieldName}'s length must >= ${opt.min}`);
-        if (typeof opt.max === 'number' && formatted.length > opt.max)
-            return failed(`${fieldName}'s length must <= ${opt.max}`);
-        if (opt.pattern && !opt.pattern.exec(formatted))
-            return failed(`${fieldName} does not match the pattern.`);
-        return success(formatted);
-    }
-}

package/src/router/cors.ts

@@ -1,54 +0,0 @@
-import { type Request, type ResponseUtils } from '@/http/index.js'
-
-/**
- * CORS 配置
- *
- * - false: 不处理跨域
- * - true: 支持且不设限（等同于 { allowOrigin: '*', allowHeaders: '*', exposeHeaders: '*' }）
- * - { allowOrigin, allowHeaders, exposeHeaders }: 手动配置
- *
- * allowHeaders 仅对 Preflight 请求有效
- * exposeHeaders 仅对非 Preflight 请求有效
- */
-export type CORSOptions =
-  | boolean
-  | { allowOrigin?: string; allowHeaders?: string; exposeHeaders?: string }
-
-/**
- * 若当前请求是 CORS Preflight 请求，返回实际请求的 method，否则返回 null
- */
-export function getMethodFromCORSPreflight(request: Request) {
-  if (
-    request.method === 'OPTIONS' &&
-    request.headers['Access-Control-Request-Methods'] !== undefined
-  ) {
-    const rawMethod = request.headers['Access-Control-Request-Methods']
-    return Array.isArray(rawMethod) ? rawMethod[0]! : rawMethod
-  }
-  return null
-}
-
-/**
- * 输出 CORS 相关 headers
- */
-export function outputCORSHeaders(
-  response: ResponseUtils,
-  cors: CORSOptions,
-  isPreflight: boolean,
-) {
-  if (cors === true) {
-    response.headers(['Access-Control-Allow-Origin', '*'])
-    if (isPreflight) response.headers(['Access-Control-Allow-Headers', '*'])
-    else response.headers(['Access-Control-Expose-Headers', '*'])
-  } else if (cors !== false) {
-    if (cors.allowOrigin !== undefined)
-      response.header('Access-Control-Allow-Origin', cors.allowOrigin)
-    if (isPreflight && cors.allowHeaders !== undefined)
-      response.header('Access-Control-Allow-Headers', cors.allowHeaders)
-    if (!isPreflight && cors.exposeHeaders !== undefined)
-      response.header('Access-Control-Expose-Headers', cors.exposeHeaders)
-  } else {
-    // 若指定为“不处理跨域”，则不输出 headers，浏览器会默认服务端不允许跨域请求
-    // （后续 route handler 仍有机会自行设置 CORS headers）
-  }
-}

package/src/router/match.ts

@@ -1,194 +0,0 @@
-/**
- * 匹配路由路径
- *
- * 支持的格式：
- * 1. /abc/ abc/ /abc => 这几种形式等价
- * 2. /abc/:foo/bar => 命名参数（foo）
- * 3. /abc/:foo?/bar => 可选命名参数（foo）
- * 4. /abc/* => 后续路径（任意长度，* 只能出现在路由最后面，匹配结果不含开头的“/”）
- *
- * 路由不区分大小写
- */
-import escapeRegExp from 'lodash/escapeRegExp.js'
-
-/**
- * 标准化路径
- * 移除首尾和重复的 '/'，完成后有 path 有这几种可能的格式： ''、'abc'、'abc/def'
- * 例如 /abc/def 和 abc/def/ 都会变成 abc/def
- *
- * 注意：此操作不会统一大小写，因此不保证标准化后两个字符串在代码层面 ===
- */
-export function normalizePath(path: string) {
-  if (path.startsWith('/')) path = path.slice(1)
-  if (path.endsWith('/')) path = path.slice(0, -1)
-  path = path.replace(/\/+/g, '/')
-  return path
-}
-
-/**
- * 解析路由路径定义
- * '/abc/:foo?/*' => [{ type: 'text', text: 'abc' }, { type: 'named', name: 'foo', optional: true }, { type: 'rest' }]
- */
-function parseRoutePath(routePath: string): ParsedPath {
-  const normalizedPath = normalizePath(routePath)
-
-  const nodes: PathNode[] = []
-  const pathParts = normalizedPath.split('/')
-  for (const [i, part] of pathParts.entries()) {
-    if (part.startsWith(':') && part !== ':' && part !== ':?') {
-      const optional = part.endsWith('?')
-      const name = optional ? part.slice(1, -1) : part.slice(1)
-      if (name === '*') throw new Error('route path parameter name cannot be "*"')
-      nodes.push({ type: PathNodeType.Named, name, optional })
-    } else if (part === '*' && i === pathParts.length - 1) {
-      nodes.push({ type: PathNodeType.Rest })
-    } else {
-      nodes.push({ type: PathNodeType.Text, text: part })
-    }
-  }
-
-  return nodes
-}
-
-enum PathNodeType {
-  /** 纯文本 */
-  Text = 'text',
-  /** 命名参数 */
-  Named = 'named',
-  /** 后续路径 */
-  Rest = 'rest',
-}
-type PathNode =
-  | { type: PathNodeType.Text; text: string }
-  | { type: PathNodeType.Named; name: string; optional: boolean }
-  | { type: PathNodeType.Rest }
-type ParsedPath = PathNode[]
-
-/**
- * 把路由定义转换成正则表达式
- *
- * Nodes                      | Path          | RegExp
- * -------------------------- | ------------- | ----------------------------
- * []                         |               | ^$
- * ['abc']                    | abc           | ^abc$
- * ['abc', named:foo, 'xyz']  | abc/:foo/xyz  | ^abc/([^/]+?)/xyz$
- * ['abc', named:foo?, 'xyz'] | abc/:foo?/xyz | ^abc(?:/([^/]+?))?/xyz$
- * ['abc', named:foo?, rest]  | abc/:foo?/*   | ^abc(?:/([^/]+?))?(?:/(.+))?$
- *
- * ^(?:/(.+))?$
- */
-function parsedPathToRegExp(parsedPath: ParsedPath) {
-  const regexpParts: string[] = []
-  for (const node of parsedPath) {
-    const prefix = node === parsedPath[0] ? '' : '/'
-    if (node.type === PathNodeType.Text) {
-      regexpParts.push(prefix + escapeRegExp(node.text))
-    } else if (node.type === PathNodeType.Named) {
-      regexpParts.push(node.optional ? `(?:${prefix}([^/]+?))?` : `${prefix}([^/]+?)`)
-    } else {
-      regexpParts.push(`(?:${prefix}(.+))?`)
-    }
-  }
-  return new RegExp('^' + regexpParts.join('') + '$', 'i')
-}
-
-/**
- * 比较两个路径的优先级（两个路由都能匹配路径时，优先级更高的生效）
- *
- * pathA 优先：-1
- * pathB 优先：1
- *
- * 规则：
- * 1. 挨个 node 比对
- * 2. 先匹配各节点的类型，text > named > named optional > rest
- * 3. 节点类型都一致，节点数量多的优先级更高
- * 4. 节点类型、数量都一样，后出现的覆盖先出现的
- */
-function pathSorter(pathA: ParsedPath, pathB: ParsedPath) {
-  const typePriorities = [PathNodeType.Text, PathNodeType.Named, PathNodeType.Rest]
-
-  const length = Math.max(pathA.length, pathB.length)
-  for (let i = 0; i < length; i++) {
-    const a = pathA[i]
-    const b = pathB[i]
-
-    // 若 nodes 长度不一样，长的优先
-    if (a === undefined) return -1
-    else if (b === undefined) return 1
-
-    // node 类型不一样，按类型排序
-    const aTypePriority = typePriorities.indexOf(a.type)
-    const bTypePriority = typePriorities.indexOf(b.type)
-    if (aTypePriority !== bTypePriority) return aTypePriority - bTypePriority
-
-    // 若都是 named 类型但 optional 不同
-    if (
-      a.type === PathNodeType.Named &&
-      b.type === PathNodeType.Named &&
-      a.optional !== b.optional
-    ) {
-      return a.optional ? 1 : -1
-    }
-  }
-
-  // 长度、类型都一样，后出现的优先
-  return 1
-}
-
-/**
- * 返回匹配的路由及匹配上的路径参数
- */
-export function matchRoutes<R extends BasicRoute>(requestPath: string, routes: R[]) {
-  if (!parsedCache.has(routes)) {
-    // 解析路由路径并按优先级排序
-    const parsedRoutes = routes
-      .map(route => {
-        const parsedPath = parseRoutePath(route.path)
-        const regexp = parsedPathToRegExp(parsedPath)
-        return { parsedPath, regexp, route }
-      })
-      .sort((a, b) => pathSorter(a.parsedPath, b.parsedPath))
-    parsedCache.set(routes, parsedRoutes)
-  }
-
-  requestPath = normalizePath(requestPath)
-  const parsedRoutes = parsedCache.get(routes)!
-  return parsedRoutes
-    .map(({ parsedPath, regexp, route }) => {
-      const match = regexp.exec(requestPath)
-      if (!match) return null
-
-      const pathParameters = matchPathParameters(parsedPath, [...match].slice(1))
-      return { route, pathParameters } as RouteMatch<R>
-    })
-    .filter((matched): matched is Exclude<typeof matched, null> => matched !== null)
-}
-const parsedCache = new WeakMap<
-  BasicRoute[], // eslint-disable-line @typescript-eslint/no-explicit-any
-  { parsedPath: ParsedPath; regexp: RegExp; route: BasicRoute }[] // eslint-disable-line @typescript-eslint/no-explicit-any
->()
-
-export type BasicRoute = { path: string }
-
-export interface RouteMatch<R> {
-  route: R
-  pathParameters: PathParameters
-}
-
-/**
- * 把匹配到的路径参数映射成键值对
- * 没匹配到的内容（optional named node / rest node）值为 undefined
- */
-function matchPathParameters(parsedPath: ParsedPath, parameterNames: (string | undefined)[]) {
-  const parameters: PathParameters = {}
-  for (const node of parsedPath) {
-    if (node.type === PathNodeType.Text) continue
-    else if (node.type === PathNodeType.Named) parameters[node.name] = parameterNames.shift()!
-    else parameters['*'] = parameterNames.shift()!
-  }
-  return parameters
-}
-export type PathParameters = {
-  [name: string]: string | undefined
-  '*'?: string
-}

package/src/router/parameters.ts

@@ -1,175 +0,0 @@
-/**
- * 实现通过 query / body parameters 的解析和验证
- */
-import { success } from '@anjianshi/utils'
-import { type Request, HTTPError } from '@/http/index.js'
-import { type Validator, type CommonOptions } from '@/validators/common.js'
-import * as validators from '@/validators/index.js'
-import { type Route } from './router.js'
-
-/**
- * ----------------------------------------
- * 类型定义
- * ----------------------------------------
- */
-
-/**
- * 请求参数定义
- */
-export interface Parameter {
-  /** 字段名 */
-  name: string
-
-  /** 文字描述  */
-  description?: string
-
-  type: ParameterDataType
-
-  /** 默认值，应与 type 匹配。若指定，则不再需要 required 规则。 */
-  defaults?: unknown
-
-  /** 是否允许为 undefined  */
-  required?: boolean
-
-  /** 是否允许为 null */
-  nullable?: boolean
-
-  /** 验证规则，会传给 type 对应的 validator */
-  validate?: Record<string, unknown>
-}
-
-export type BasicDataType = 'string' | 'number' | 'boolean'
-
-export type BasicParameter = Pick<
-  Parameter,
-  'type' | 'validate' | 'required' | 'nullable' | 'defaults' | 'description'
->
-
-/**
- * 请求参数的数据类型定义
- */
-export type ParameterDataType =
-  | BasicDataType
-  | { array: BasicParameter }
-  | { record: BasicParameter } // 对应 object validator 的 value 类型
-  | { object: Record<string, BasicParameter> } // 对应 object validator 的 struct 类型
-
-/**
- * ----------------------------------------
- * 基础功能实现
- * ----------------------------------------
- */
-
-/**
- * 基于 parameter 定义验证、格式化数据
- */
-function validateParameters<T>(parameters: Parameter[], rawData: Record<string, unknown>) {
-  const result = {} as Record<string, unknown>
-  for (const parameter of parameters) {
-    const validator = getValidatorOfParameter(parameter)
-    const validateRes = validator.validate(parameter.name, rawData[parameter.name])
-    if (validateRes.success) result[parameter.name] = validateRes.data
-    else return validateRes
-  }
-  return success(result as T)
-}
-
-/**
- * 获取指定 parameter 的 validator
- */
-function getValidatorOfParameter(parameter: BasicParameter) {
-  if (!validatorCache.has(parameter)) {
-    const validatorConstructor = getValidatorConstructor(parameter.type) as typeof validators.any
-    const options = {
-      null: parameter.nullable,
-      void: typeof parameter.required === 'boolean' ? !parameter.required : undefined,
-      defaults: parameter.defaults,
-      ...(parameter.validate ?? {}),
-    }
-    const validator = validatorConstructor(options)
-    validatorCache.set(parameter, validator)
-  }
-  return validatorCache.get(parameter)!
-}
-const validatorCache = new WeakMap<BasicParameter, ReturnType<typeof validators.any>>()
-
-/**
- * 取得与参数类型对应的 validator constructor
- */
-function getValidatorConstructor(type: ParameterDataType): (options: CommonOptions) => Validator {
-  if (typeof type === 'string') return validators[type]
-
-  if ('array' in type) {
-    const itemValidator = getValidatorOfParameter(type.array)
-    return validators.array.bind(null, itemValidator)
-  }
-
-  if ('record' in type) {
-    const itemValidator = getValidatorOfParameter(type.record)
-    return validators.object.bind(null, itemValidator)
-  }
-
-  const struct: Record<string, Validator> = {}
-  for (const [key, innerParameter] of Object.entries(type.object)) {
-    struct[key] = getValidatorOfParameter(innerParameter)
-  }
-  return validators.object.bind(null, struct)
-}
-
-/**
- * ----------------------------------------
- * 与请求内容对接
- * ----------------------------------------
- */
-
-/**
- * 验证 query 内容
- */
-export function parseQuery<T>(route: Route, request: Request) {
-  if (!route.query) throw new HTTPError(500, 'Call parseQuery() need query parameter definition.')
-
-  const values: Record<string, unknown> = {}
-  for (const parameter of route.query) {
-    values[parameter.name] = getQueryParameterValue(request, parameter)
-  }
-
-  const res = validateParameters<T>(route.query, values)
-  if (res.success) return res.data
-  throw new HTTPError(400, res.error)
-}
-
-function getQueryParameterValue(request: Request, parameter: Parameter) {
-  // array
-  if (typeof parameter.type === 'object' && 'array' in parameter.type) {
-    return request.query.getAll(parameter.name + '[]')
-  }
-
-  // undefined
-  const raw = request.query.get(parameter.name)
-  if (raw === null || raw === '') return undefined
-
-  // basic type
-  if (typeof parameter.type === 'string') return raw
-
-  // object
-  try {
-    return JSON.parse(raw) as unknown
-  } catch (error) {
-    throw new HTTPError(400, `Invalid JSON value for query parameter "${parameter.name}".`)
-  }
-}
-
-/**
- * 验证 body 内容
- */
-export async function parseJSONBody<T>(route: Route, request: Request) {
-  if (!route.body) throw new HTTPError(500, 'call parseJSONBody() need body parameter definition.')
-
-  const body = await request.body.json()
-  if (typeof body !== 'object' || body === null || Array.isArray(body))
-    throw new HTTPError(400, 'Invalid JSON body, should be an object.')
-
-  const res = validateParameters<T>(route.body, body as Record<string, unknown>)
-  if (res.success) return res.data
-  throw new HTTPError(400, res.error)
-}