starlight-server 1.6.2 → 1.6.4

package/dist/http/request.d.ts

@@ -36,6 +36,8 @@ export declare class Request {
     constructor(nodeRequest: NodeRequest, logger: Logger, bodyOptions: BodyOptions);
     /**
      * 获取 HTTP Header，支持任意大小写形式：content-type / Content-Type
+     * 若 loose 为 true，固定返回一个字符串。有多个值时返回第一个，header 不存在时返回空字符串。
      */
-    getHeader<const K extends string>(key: K): http.IncomingHttpHeaders[Lowercase<K>];
+    getHeader<const K extends string>(key: K, loose?: false): http.IncomingHttpHeaders[Lowercase<K>];
+    getHeader<const K extends string>(key: K, loose: true): string;
 }

package/dist/http/request.js

@@ -52,10 +52,17 @@ export class Request {
         this.headers = nodeRequest.headers;
         this.body = new RequestBody(nodeRequest, bodyOptions);
     }
-    /**
-     * 获取 HTTP Header，支持任意大小写形式：content-type / Content-Type
-     */
-    getHeader(key) {
-        return this.headers[key.toLowerCase()];
+    getHeader(key, loose) {
+        const value = this.headers[key.toLowerCase()];
+        if (loose === true) {
+            if (typeof value === 'string')
+                return value;
+            if (Array.isArray(value) && value.length > 0)
+                return value[1];
+            return '';
+        }
+        else {
+            return value;
+        }
     }
 }

package/dist/http/response.d.ts

@@ -8,7 +8,11 @@ import { type NodeResponse } from './types.js';
 export declare class ResponseUtils {
     readonly nodeResponse: NodeResponse;
     readonly logger: Logger;
-    constructor(nodeResponse: NodeResponse, logger: Logger);
+    /** 处理 JSON 输出中的自定义类型 */
+    jsonReplacer?: ((key: string, value: unknown) => unknown) | undefined;
+    constructor(nodeResponse: NodeResponse, logger: Logger, 
+    /** 处理 JSON 输出中的自定义类型 */
+    jsonReplacer?: ((key: string, value: unknown) => unknown) | undefined);
     header(name: string, value: string): void;
     headers(...items: [string, string][]): void;
     text(content: string | Buffer): void;

package/dist/http/response.js

@@ -7,9 +7,13 @@ import { HTTPError } from './types.js';
 export class ResponseUtils {
     nodeResponse;
     logger;
-    constructor(nodeResponse, logger) {
+    jsonReplacer;
+    constructor(nodeResponse, logger, 
+    /** 处理 JSON 输出中的自定义类型 */
+    jsonReplacer) {
         this.nodeResponse = nodeResponse;
         this.logger = logger;
+        this.jsonReplacer = jsonReplacer;
     }
     header(name, value) {
         this.nodeResponse.setHeader(name, value);
@@ -25,7 +29,7 @@ export class ResponseUtils {
      */
     json(data) {
         try {
-            const json = JSON.stringify(data);
+            const json = JSON.stringify(data, this.jsonReplacer);
             this.header('Content-Type', 'application/json; charset=UTF-8');
             this.nodeResponse.end(json);
         }

package/dist/http/server.d.ts

@@ -28,4 +28,6 @@ export declare function startHTTPServer(options: BodyOptions & {
     handler?: RequestHandler;
     logger: Logger;
     port: number;
+    /** 处理 JSON 输出中的自定义类型，详见 JSON.stringify() 的 replacer 参数 */
+    jsonReplacer?: (key: string, value: unknown) => unknown;
 }): void;

package/dist/http/server.js

@@ -30,7 +30,7 @@ export function startHTTPServer(options) {
         const logMethod = nodeRequest.method ?? 'UNKNOWN';
         const logUrl = nodeRequest.url ?? '';
         logger.info('<--', logMethod, logUrl);
-        const response = new ResponseUtils(nodeResponse, logger);
+        const response = new ResponseUtils(nodeResponse, logger, options.jsonReplacer);
         try {
             const request = new Request(nodeRequest, logger, bodyOptions);
             await handler(request, response);

package/dist/router/helpers.d.ts

@@ -1,6 +1,12 @@
-import { type Validator, validators } from '@anjianshi/utils/validators/index.js';
+import { type Validator } from '@anjianshi/utils/validators/index.js';
 import { type BasicContext } from './index.js';
-export { validators };
-export declare function validatePathParameters<T>(this: BasicContext, struct: Record<string, Validator>): T;
-export declare function validateQuery<T>(this: BasicContext, struct: Record<string, Validator>): T;
-export declare function validateBody<T>(this: BasicContext, struct: Record<string, Validator>): Promise<T>;
+export declare class Helpers {
+    readonly context: BasicContext;
+    constructor(context: BasicContext);
+    validatePathParameters<T>(struct: Record<string, Validator>): T;
+    validateQuery<T>(struct: Record<string, Validator>): T;
+    validateBody<T>(struct: Record<string, Validator>): Promise<T>;
+    success(data?: unknown): void;
+    failed(message: string, code?: string | number): void;
+    failed<T>(message: string, code: string | number | undefined, data: T): void;
+}

package/dist/router/helpers.js

@@ -1,24 +1,36 @@
+import { success, failed } from '@anjianshi/utils';
 import { validators } from '@anjianshi/utils/validators/index.js';
 import { HTTPError } from '../index.js';
-export { validators };
-export function validatePathParameters(struct) {
-    const result = validators.struct(struct).validate('path', this.pathParameters);
-    if (result.success)
-        return result.data;
-    throw new HTTPError(400, result.message);
-}
-export function validateQuery(struct) {
-    const result = validators.struct(struct).validate('query', this.request.query);
-    if (result.success)
-        return result.data;
-    throw new HTTPError(400, result.message);
-}
-export async function validateBody(struct) {
-    const body = await this.request.body.json();
-    if (typeof body !== 'object' || body === null || Array.isArray(body))
-        throw new HTTPError(400, 'Invalid JSON body, should be an object.');
-    const result = validators.struct(struct).validate('body', this.request.body);
-    if (result.success)
-        return result.data;
-    throw new HTTPError(400, result.message);
+export class Helpers {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    validatePathParameters(struct) {
+        const result = validators.struct(struct).validate('path', this.context.pathParameters);
+        if (result.success)
+            return result.data;
+        throw new HTTPError(400, result.message);
+    }
+    validateQuery(struct) {
+        const result = validators.struct(struct).validate('query', this.context.request.query);
+        if (result.success)
+            return result.data;
+        throw new HTTPError(400, result.message);
+    }
+    async validateBody(struct) {
+        const body = await this.context.request.body.json();
+        if (typeof body !== 'object' || body === null || Array.isArray(body))
+            throw new HTTPError(400, 'Invalid JSON body, should be an object.');
+        const result = validators.struct(struct).validate('body', body);
+        if (result.success)
+            return result.data;
+        throw new HTTPError(400, result.message);
+    }
+    success(data) {
+        this.context.response.json(success(data));
+    }
+    failed(message, code, data) {
+        this.context.response.json(failed(message, code, data));
+    }
 }

package/dist/router/index.d.ts

@@ -1,18 +1,20 @@
-import { type validators } from '@anjianshi/utils/validators/index.js';
+import { validators } from '@anjianshi/utils/validators/index.js';
 import { type CORSRule } from '../http/cors.js';
 import { type Request, type ResponseUtils } from '../http/index.js';
 import { Swagger, type Method } from '../swagger/index.js';
-import * as helpers from './helpers.js';
+import { Helpers } from './helpers.js';
 import { type PathParameters } from './match-path.js';
-type WithoutThis<T extends (...args: any[]) => unknown> = (...args: Parameters<T>) => ReturnType<T>;
+type HelpersInst = InstanceType<typeof Helpers>;
 export interface BasicContext {
     request: Request;
     response: ResponseUtils;
     pathParameters: PathParameters;
-    validatePathParameters: WithoutThis<typeof helpers.validatePathParameters>;
-    validateQuery: WithoutThis<typeof helpers.validateQuery>;
-    validateBody: WithoutThis<typeof helpers.validateBody>;
+    validatePathParameters: HelpersInst['validatePathParameters'];
+    validateQuery: HelpersInst['validateQuery'];
+    validateBody: HelpersInst['validateBody'];
     validators: typeof validators;
+    success: HelpersInst['success'];
+    failed: HelpersInst['failed'];
 }
 /** 使用者可自行补充 Context 定义  */
 export interface Context extends BasicContext {
@@ -59,7 +61,7 @@ export declare class Router {
      * route 调用 / context 配置
      * -------------------------------
      */
-    private executor;
+    protected executor: (basicContext: BasicContext, route: Route) => Promise<void>;
     setExecutor(executor: typeof this.executor): void;
     /**
      * ----------------------

package/dist/router/index.js

@@ -1,8 +1,9 @@
 import { joinPath } from '@anjianshi/utils';
+import { validators } from '@anjianshi/utils/validators/index.js';
 import { getPreflightRequestMethod, handleCORS } from '../http/cors.js';
 import { HTTPError } from '../http/index.js';
 import { Swagger } from '../swagger/index.js';
-import * as helpers from './helpers.js';
+import { Helpers } from './helpers.js';
 import { matchPath } from './match-path.js';
 export class Router {
     /**
@@ -95,13 +96,17 @@ export class Router {
             throw new HTTPError(405); // 有路径匹配的路由，但是没有 method 匹配的
         }
         const basicContext = {};
+        const helpers = new Helpers(basicContext);
         Object.assign(basicContext, {
             request,
             response,
             pathParameters: matched.parameters,
-            validatePathParameters: helpers.validatePathParameters.bind(basicContext),
-            validateQuery: helpers.validateQuery.bind(basicContext),
-            validateBody: helpers.validateBody.bind(basicContext),
+            validatePathParameters: helpers.validatePathParameters.bind(helpers),
+            validateQuery: helpers.validateQuery.bind(helpers),
+            validateBody: helpers.validateBody.bind(helpers),
+            validators,
+            success: helpers.success.bind(helpers),
+            failed: helpers.failed.bind(helpers),
         });
         await this.executor(basicContext, matched.route);
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-server",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "Simple But Powerful Node.js HTTP Server",
   "type": "module",
   "keywords": [
@@ -51,8 +51,9 @@
   "eslintIgnore": [],
   "prettier": "@anjianshi/presets-prettier/prettierrc",
   "scripts": {
-    "dev": "rimraf dist && (concurrently --raw \"tsc-with-alias --watch\" \"nodemon dist/demo/index.js\")",
+    "demo": "rimraf dist && (concurrently --raw \"tsc-with-alias --watch\" \"nodemon dist/demo/index.js\")",
     "build": "rimraf dist && tsc-with-alias",
+    "watch": "rimraf dist && tsc-with-alias --watch",
     "lint": "tsc --noEmit && eslint './src/**/*'"
   }
 }

package/src/http/request.ts

@@ -42,7 +42,7 @@ export class Request {
   constructor(
     readonly nodeRequest: NodeRequest,
     protected readonly logger: Logger,
-    bodyOptions: BodyOptions
+    bodyOptions: BodyOptions,
   ) {
     if (nodeRequest.method === undefined) throw new HTTPError(405)
     this.method = nodeRequest.method.toUpperCase()
@@ -65,8 +65,21 @@ export class Request {
 
   /**
    * 获取 HTTP Header，支持任意大小写形式：content-type / Content-Type
+   * 若 loose 为 true，固定返回一个字符串。有多个值时返回第一个，header 不存在时返回空字符串。
    */
-  getHeader<const K extends string>(key: K): http.IncomingHttpHeaders[Lowercase<K>] {
-    return this.headers[key.toLowerCase()]
+  getHeader<const K extends string>(key: K, loose?: false): http.IncomingHttpHeaders[Lowercase<K>]
+  getHeader<const K extends string>(key: K, loose: true): string
+  getHeader<const K extends string>(
+    key: K,
+    loose?: boolean,
+  ): http.IncomingHttpHeaders[Lowercase<K>] | string {
+    const value = this.headers[key.toLowerCase()]
+    if (loose === true) {
+      if (typeof value === 'string') return value
+      if (Array.isArray(value) && value.length > 0) return value[1]!
+      return ''
+    } else {
+      return value
+    }
   }
 }

package/src/http/response.ts

@@ -7,7 +7,12 @@ import { HTTPError, type NodeResponse } from './types.js'
  * Encapsulate functions for outputting response content.
  */
 export class ResponseUtils {
-  constructor(readonly nodeResponse: NodeResponse, readonly logger: Logger) {}
+  constructor(
+    readonly nodeResponse: NodeResponse,
+    readonly logger: Logger,
+    /** 处理 JSON 输出中的自定义类型 */
+    public jsonReplacer?: (key: string, value: unknown) => unknown,
+  ) {}
 
   header(name: string, value: string) {
     this.nodeResponse.setHeader(name, value)
@@ -26,7 +31,7 @@ export class ResponseUtils {
    */
   json(data: unknown) {
     try {
-      const json = JSON.stringify(data)
+      const json = JSON.stringify(data, this.jsonReplacer)
       this.header('Content-Type', 'application/json; charset=UTF-8')
       this.nodeResponse.end(json)
     } catch (e) {

package/src/http/server.ts

@@ -33,7 +33,9 @@ export function startHTTPServer(
     handler?: RequestHandler
     logger: Logger
     port: number
-  }
+    /** 处理 JSON 输出中的自定义类型，详见 JSON.stringify() 的 replacer 参数 */
+    jsonReplacer?: (key: string, value: unknown) => unknown
+  },
 ) {
   const { handler = placeholderHandler, logger, port, ...bodyOptions } = options
 
@@ -43,7 +45,7 @@ export function startHTTPServer(
     const logUrl = nodeRequest.url ?? ''
     logger.info('<--', logMethod, logUrl)
 
-    const response = new ResponseUtils(nodeResponse, logger)
+    const response = new ResponseUtils(nodeResponse, logger, options.jsonReplacer)
     try {
       const request = new Request(nodeRequest, logger, bodyOptions)
       await handler(request, response)

package/src/router/helpers.ts

@@ -1,27 +1,40 @@
+import { success, failed } from '@anjianshi/utils'
 import { type Validator, validators } from '@anjianshi/utils/validators/index.js'
 import { HTTPError } from '@/index.js'
 import { type BasicContext } from './index.js'
 
-export { validators }
+export class Helpers {
+  constructor(readonly context: BasicContext) {}
 
-export function validatePathParameters<T>(this: BasicContext, struct: Record<string, Validator>) {
-  const result = validators.struct(struct).validate('path', this.pathParameters)
-  if (result.success) return result.data as T
-  throw new HTTPError(400, result.message)
-}
+  validatePathParameters<T>(struct: Record<string, Validator>) {
+    const result = validators.struct(struct).validate('path', this.context.pathParameters)
+    if (result.success) return result.data as T
+    throw new HTTPError(400, result.message)
+  }
 
-export function validateQuery<T>(this: BasicContext, struct: Record<string, Validator>) {
-  const result = validators.struct(struct).validate('query', this.request.query)
-  if (result.success) return result.data as T
-  throw new HTTPError(400, result.message)
-}
+  validateQuery<T>(struct: Record<string, Validator>) {
+    const result = validators.struct(struct).validate('query', this.context.request.query)
+    if (result.success) return result.data as T
+    throw new HTTPError(400, result.message)
+  }
+
+  async validateBody<T>(struct: Record<string, Validator>) {
+    const body = await this.context.request.body.json()
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+      throw new HTTPError(400, 'Invalid JSON body, should be an object.')
+
+    const result = validators.struct(struct).validate('body', body)
+    if (result.success) return result.data as T
+    throw new HTTPError(400, result.message)
+  }
 
-export async function validateBody<T>(this: BasicContext, struct: Record<string, Validator>) {
-  const body = await this.request.body.json()
-  if (typeof body !== 'object' || body === null || Array.isArray(body))
-    throw new HTTPError(400, 'Invalid JSON body, should be an object.')
+  success(data?: unknown) {
+    this.context.response.json(success(data))
+  }
 
-  const result = validators.struct(struct).validate('body', this.request.body)
-  if (result.success) return result.data as T
-  throw new HTTPError(400, result.message)
+  failed(message: string, code?: string | number): void
+  failed<T>(message: string, code: string | number | undefined, data: T): void
+  failed<T>(message: string, code?: string | number, data?: T) {
+    this.context.response.json(failed(message, code, data))
+  }
 }

package/src/router/index.ts

@@ -1,20 +1,22 @@
 import { joinPath } from '@anjianshi/utils'
-import { type validators } from '@anjianshi/utils/validators/index.js'
+import { validators } from '@anjianshi/utils/validators/index.js'
 import { getPreflightRequestMethod, handleCORS, type CORSRule } from '@/http/cors.js'
 import { HTTPError, type Request, type ResponseUtils } from '@/http/index.js'
 import { Swagger, type Method } from '@/swagger/index.js'
-import * as helpers from './helpers.js'
+import { Helpers } from './helpers.js'
 import { matchPath, type PathParameters } from './match-path.js'
 
-type WithoutThis<T extends (...args: any[]) => unknown> = (...args: Parameters<T>) => ReturnType<T>
+type HelpersInst = InstanceType<typeof Helpers>
 export interface BasicContext {
   request: Request
   response: ResponseUtils
   pathParameters: PathParameters
-  validatePathParameters: WithoutThis<typeof helpers.validatePathParameters>
-  validateQuery: WithoutThis<typeof helpers.validateQuery>
-  validateBody: WithoutThis<typeof helpers.validateBody>
+  validatePathParameters: HelpersInst['validatePathParameters']
+  validateQuery: HelpersInst['validateQuery']
+  validateBody: HelpersInst['validateBody']
   validators: typeof validators
+  success: HelpersInst['success']
+  failed: HelpersInst['failed']
 }
 
 /** 使用者可自行补充 Context 定义  */
@@ -96,7 +98,7 @@ export class Router {
    * route 调用 / context 配置
    * -------------------------------
    */
-  private executor = async (basicContext: BasicContext, route: Route) => {
+  protected executor = async (basicContext: BasicContext, route: Route) => {
     await route.handler(basicContext as Context)
   }
   setExecutor(executor: typeof this.executor) {
@@ -132,13 +134,17 @@ export class Router {
     }
 
     const basicContext = {} as BasicContext
+    const helpers = new Helpers(basicContext)
     Object.assign(basicContext, {
       request,
       response,
       pathParameters: matched.parameters,
-      validatePathParameters: helpers.validatePathParameters.bind(basicContext),
-      validateQuery: helpers.validateQuery.bind(basicContext),
-      validateBody: helpers.validateBody.bind(basicContext),
+      validatePathParameters: helpers.validatePathParameters.bind(helpers),
+      validateQuery: helpers.validateQuery.bind(helpers),
+      validateBody: helpers.validateBody.bind(helpers),
+      validators,
+      success: helpers.success.bind(helpers),
+      failed: helpers.failed.bind(helpers),
     })
     await this.executor(basicContext, matched.route)
   }