starlight-server 0.0.1

package/dist/swagger/index.js

@@ -0,0 +1,168 @@
+// import fsPromise from 'node:fs/promises'
+// import path from 'node:path'
+// import { getAbsoluteFSPath } from 'swagger-ui-dist'
+// import { HTTPError } from '../http/index.js'
+// import {
+//   type Router,
+//   type PathParameters,
+//   type BaseContext,
+//   type ResponseDataType,
+// } from '../router/index.js'
+// import { normalizePath } from '../router/match.js'
+// import type { OpenAPI, Schema, PathItem } from './openapi-spec.js'
+export {};
+// export function registerSwaggerRoute(
+//   router: Router,
+//   endpoint: string = '/swagger',
+//   customFields: OpenAPICustomFields = { info: { title: 'API Document', version: '0.0.1' } },
+// ) {
+//   router.register('GET', normalizePath(endpoint) + '/*', pageRoute)
+//   router.register(
+//     'GET',
+//     normalizePath(endpoint) + '/api-swagger.json',
+//     apiRoute.bind(null, router, customFields),
+//   )
+// }
+// /**
+//  * ---------------------------------
+//  * swagger 页面路由
+//  * ---------------------------------
+//  */
+// async function pageRoute({ response }: BaseContext, pathParameters: PathParameters) {
+//   const file = (pathParameters['*'] ?? '') || 'index.html'
+//   const swaggerDir = getAbsoluteFSPath()
+//   const abspath = path.join(swaggerDir, file)
+//   if (!cache.has(abspath)) {
+//     try {
+//       const stat = await fsPromise.stat(abspath)
+//       if (!stat.isFile()) throw new HTTPError(404)
+//     } catch (e) {
+//       throw new HTTPError(404)
+//     }
+//     const content = await fsPromise.readFile(abspath)
+//     const replacemented = replacement(abspath, content)
+//     cache.set(abspath, replacemented)
+//   }
+//   response.text(cache.get(abspath)!)
+// }
+// const cache = new Map<string, Buffer | string>()
+// function replacement(abspath: string, content: Buffer) {
+//   if (/swagger-initializer.js/.exec(abspath)) {
+//     return content
+//       .toString()
+//       .replace('https://petstore.swagger.io/v2/swagger.json', './api-swagger.json')
+//     // .replace('SwaggerUIBundle({', 'SwaggerUIBundle({\n    defaultModelsExpandDepth: 1,\n    defaultModelExpandDepth: 1,')
+//   }
+//   return content
+// }
+// /**
+//  * ---------------------------------
+//  * swagger API 路由
+//  * ---------------------------------
+//  */
+// type OpenAPICustomFields = Omit<OpenAPI, 'openapi' | 'paths' | 'components'>
+// function apiRoute(router: Router, customFields: OpenAPICustomFields, { response }: BaseContext) {
+//   const swaggerJSON: OpenAPI = {
+//     ...customFields,
+//     openapi: '3.1.0',
+//     paths: makePaths(router),
+//     components: {
+//       schemas: makeRefs(router),
+//     },
+//   }
+//   response.json(swaggerJSON)
+// }
+// function makeRefs(router: Router) {
+//   const schemas: Record<string, Schema> = {}
+//   for (const [id, type] of Object.entries(router.responseReferences)) {
+//     schemas[id] = responseDataType2Schema(type)
+//   }
+//   return schemas
+// }
+// function makePaths(router: Router) {
+//   const paths: Record<string, PathItem> = {}
+//   return paths
+// }
+// function responseDataType2Schema(type: ResponseDataType): Schema {
+//   if (type === 'null') return { nullable: true }
+//   if (typeof type === 'object' && 'array' in type && type.array.includes('null')) {
+//     return {
+//       nullable: true,
+//       ...responseDataType2Schema(type as ResponseDataType.filter(v => v !== 'null') as ResponseDataType),
+//     }
+//   }
+//   const nullable = type === 'null' || (Array.isArray(type) && type.includes('null'))
+//   return {
+//     nullable,
+//   }
+// }
+// type Obj = { [k: string]: unknown }
+// function string(desc?: string, options?: Obj) {
+//   return { type: 'string', description: desc, ...(options ?? {}) }
+// }
+// function number(desc?: string, options?: Obj) {
+//   return { type: 'number', description: desc, ...(options ?? {}) }
+// }
+// function boolean(desc?: string, options?: Obj) {
+//   return { type: 'boolean', description: desc, ...(options ?? {}) }
+// }
+// function object(properties: unknown, extra?: Obj) {
+//   return { type: 'object', properties, ...(extra ?? {}) }
+// }
+// function array(items: unknown, extra?: Obj) {
+//   return { type: 'array', items, ...(extra ?? {}) }
+// }
+// function ref(name: string) {
+//   return { $ref: '#/components/schemas/' + name }
+// }
+// function jsonSchema(schema: string | Obj) {
+//   return {
+//     content: {
+//       'application/json': {
+//         schema: typeof schema === 'string' ? ref(schema) : schema,
+//       },
+//     },
+//   }
+// }
+// function route(params: {
+//   category: string
+//   describe: string
+//   path: string
+//   body?: string | Obj
+//   response?: string | Obj
+// }) {
+//   return {
+//     [params.path]: {
+//       post: {
+//         tags: [params.category],
+//         summary: params.describe,
+//         operationId: params.path,
+//         requestBody: params.body !== undefined ? jsonSchema(params.body) : undefined,
+//         responses: {
+//           default: {
+//             description: 'OK',
+//             ...jsonSchema(params.response ?? object({})),
+//           },
+//         },
+//       },
+//     },
+//   }
+// }
+// function response(schema: unknown) {
+//   return {
+//     type: 'object',
+//     properties: {
+//       success: boolean(undefined, { enum: [true] }),
+//       data: schema,
+//     },
+//   }
+// }
+// function pageResp(itemSchema: unknown) {
+//   return response({
+//     type: 'object',
+//     properties: {
+//       total: number(),
+//       list: array(itemSchema),
+//     },
+//   })
+// }

package/dist/swagger/openapi-spec.d.ts

@@ -0,0 +1,261 @@
+/**
+ * OpenAPI Specification
+ * https://swagger.io/specification/
+ */
+export interface OpenAPI {
+    openapi: '3.1.0';
+    info: Info;
+    servers?: Server[];
+    paths: Paths;
+    components?: Components;
+    security?: SecurityRequirement[];
+    tags?: Tag[];
+    externalDocs?: ExternalDocumentation;
+}
+export interface Info extends Extendable {
+    title: string;
+    summary?: string;
+    description?: string;
+    termsOfService?: string;
+    contact?: Contact;
+    license?: License;
+    version: string;
+}
+export interface Contact extends Extendable {
+    name?: string;
+    url?: string;
+    email?: string;
+}
+export interface License extends Extendable {
+    name: string;
+    url?: string;
+}
+export interface Server extends Extendable {
+    url: string;
+    description?: CommonMark;
+    variables?: Record<string, ServerVariable>;
+}
+export interface ServerVariable extends Extendable {
+    enum?: [string] & string[];
+    default: string;
+    description: CommonMark;
+}
+export interface Components extends Extendable {
+    schemas?: Record<string, Schema>;
+    responses?: Record<string, Response | Reference>;
+    parameters?: Record<string, Parameter | Reference>;
+    examples?: Record<string, Example | Reference>;
+    requestBodies?: Record<string, RequestBody | Reference>;
+    headers?: Record<string, Header | Reference>;
+    securitySchemes?: Record<string, SecurityScheme | Reference>;
+    links?: Record<string, Link | Reference>;
+    callbacks?: Record<string, Callback | Reference>;
+    pathItems?: Record<string, PathItem | Reference>;
+}
+export interface Paths extends Extendable {
+    [path: string]: PathItem;
+}
+export interface PathItem extends Extendable {
+    $ref?: string;
+    summary?: string;
+    description?: CommonMark;
+    get?: Operation;
+    put?: Operation;
+    post?: Operation;
+    delete?: Operation;
+    options?: Operation;
+    head?: Operation;
+    patch?: Operation;
+    trace?: Operation;
+    servers?: Server[];
+    parameters?: (Parameter | Reference)[];
+}
+export interface Operation {
+    tags?: string[];
+    summary?: string;
+    description?: CommonMark;
+    externalDocs?: ExternalDocumentation;
+    operationId?: string;
+    parameters?: (Parameter | Reference)[];
+    requestBody?: RequestBody | Reference;
+    responses: Responses;
+    callbacks?: Record<string, Callback | Reference>;
+    deprecated?: boolean;
+}
+export interface ExternalDocumentation {
+    description?: CommonMark;
+    url: string;
+}
+export interface Parameter extends Extendable {
+    name: string;
+    in: ParameterLocation;
+    description?: CommonMark;
+    required?: boolean;
+    deprecated?: boolean;
+    allowEmptyValue?: boolean;
+    style?: ParameterStyle;
+    explode?: boolean;
+    allowReserved?: boolean;
+    schema?: Schema | Reference;
+    example?: unknown;
+    examples?: Record<string, Example | Reference>;
+    content?: Record<string, MediaType>;
+}
+export type ParameterLocation = 'query' | 'header' | 'path' | 'cookie';
+export type ParameterStyle = string;
+export interface RequestBody extends Extendable {
+    description?: CommonMark;
+    content: Record<string, MediaType>;
+    required?: boolean;
+}
+export interface MediaType extends Extendable {
+    schema?: Schema | Reference;
+    example?: unknown;
+    examples?: Record<string, Example | Reference>;
+    encoding?: Record<string, Encoding>;
+}
+export interface Encoding extends Extendable {
+    contentType?: string;
+    headers?: Record<string, Header | Reference>;
+    style?: ParameterStyle;
+    explode?: boolean;
+    allowReserved?: boolean;
+}
+export interface Responses extends Extendable {
+    default: Response | Reference;
+    [HTTPStatus: string]: Response | Reference;
+}
+export interface Response extends Extendable {
+    descriptoin: CommonMark;
+    headers?: Record<string, Header | Reference>;
+    content?: Record<string, MediaType>;
+    links?: Record<string, Link | Reference>;
+}
+export interface Callback extends Extendable {
+    [expression: Expression]: PathItem;
+}
+export interface Example extends Extendable {
+    summary?: string;
+    description?: CommonMark;
+    value?: unknown;
+    externalValue?: string;
+}
+export interface Link extends Extendable {
+    operationRef?: string;
+    operationId?: string;
+    parameters?: Record<string, unknown>;
+    requestBody?: unknown;
+    description?: string;
+    server?: Server;
+}
+export type Header = Omit<Parameter, 'name' | 'in'>;
+export interface Tag extends Extendable {
+    name: string;
+    description?: CommonMark;
+    externalDocs?: ExternalDocumentation;
+}
+export interface Reference {
+    $ref: string;
+    summary: string;
+    description: string;
+}
+export interface Schema extends Extendable {
+    nullable?: boolean;
+    discriminator?: Discriminator;
+    readonly?: boolean;
+    writeOnly?: boolean;
+    xml?: XML;
+    externalDocs?: ExternalDocumentation;
+    example?: unknown;
+    deprecated?: boolean;
+    multipleOf?: number;
+    maximum?: number;
+    exclusiveMaximum?: boolean;
+    minimum?: number;
+    exclusiveMinimum?: boolean;
+    maxLength?: number;
+    minLength?: number;
+    pattern?: string;
+    items?: Schema;
+    maxItems?: number;
+    minItems?: number;
+    uniqueItems?: boolean;
+    maxProperties?: number;
+    minProperties?: string;
+    required?: [string] & string[];
+    properties?: Record<string, Schema>;
+    additionalProperties?: boolean | Schema;
+    enum?: unknown[];
+    type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+    allOf?: Schema[];
+    anyOf?: Schema[];
+    oneOf?: Schema[];
+    not?: Schema;
+    title?: string;
+    description?: CommonMark;
+    default?: unknown;
+    format?: string;
+}
+export interface Discriminator {
+    propertyName?: string;
+    mapping?: Record<string, string>;
+}
+export interface XML extends Extendable {
+    name?: string;
+    namespace?: string;
+    prefix?: string;
+    attribute?: boolean;
+    wrapped?: boolean;
+}
+export interface SecurityScheme extends Extendable {
+    type: string;
+    description?: string;
+    name: string;
+    in: string;
+    schema: string;
+    bearerFormat?: string;
+    flows: OAuthFlows;
+    openIdConnectUrl: string;
+}
+export interface OAuthFlows extends Extendable {
+    implicit?: OAuthFlow;
+    password?: OAuthFlow;
+    clientCredentials?: OAuthFlow;
+    authorizationCode?: OAuthFlow;
+}
+export interface OAuthFlow extends Extendable {
+    authorizationUrl: string;
+    tokenUrl: string;
+    refreshUrl?: string;
+    scopes: Record<string, string>;
+}
+export interface SecurityRequirement {
+    [name: string]: string;
+}
+export type Extendable = {};
+export type CommonMark = string;
+export type Expression = string;
+export interface TypedSchema<T> extends Schema {
+    allOf?: TypedSchema<T>[];
+    anyOf?: TypedSchema<T>[];
+    oneOf?: TypedSchema<T>[];
+    not?: TypedSchema<T>;
+    example?: T;
+    enum?: T[];
+    default?: T;
+}
+export interface StringSchema extends TypedSchema<string> {
+    type: 'string';
+}
+export interface NumberSchema extends TypedSchema<number> {
+    type: 'number';
+}
+export interface BooleanSchema extends TypedSchema<boolean> {
+    type: 'boolean';
+}
+export interface ObjectSchema extends TypedSchema<Record<string, unknown>> {
+    type: 'object';
+}
+export interface ArraySchema extends TypedSchema<unknown[]> {
+    type: 'array';
+}

package/dist/swagger/openapi-spec.js

@@ -0,0 +1,5 @@
+/**
+ * OpenAPI Specification
+ * https://swagger.io/specification/
+ */
+export {};

package/dist/validators/array.d.ts

@@ -0,0 +1,9 @@
+import { Validator } from './common.js';
+export interface ArrayOptions {
+    item: Validator;
+    min?: number;
+    max?: number;
+}
+export declare class ArrayValidator extends Validator<ArrayOptions> {
+    validate(fieldName: string, value: unknown): import("@anjianshi/utils").Success<unknown> | import("@anjianshi/utils").Failed<string>;
+}

package/dist/validators/array.js

@@ -0,0 +1,28 @@
+import { success, failed } from '@anjianshi/utils';
+import { Validator } from './common.js';
+export class ArrayValidator 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 (!Array.isArray(value))
+            return failed(`${fieldName} should be an array`);
+        if (typeof opt.min === 'number' && value.length < opt.min)
+            return failed(`array ${fieldName}'s length should >= ${opt.min}`);
+        if (typeof opt.max === 'number' && value.length > opt.max)
+            return failed(`array ${fieldName}'s length should <= ${opt.max}`);
+        const formatted = [];
+        for (let i = 0; i < value.length; i++) {
+            const itemResult = opt.item.validate(`${fieldName}[${i}]`, value[i]);
+            if (itemResult.success)
+                formatted.push(itemResult.data);
+            else
+                return itemResult;
+        }
+        return success(formatted);
+    }
+}

package/dist/validators/boolean.d.ts

@@ -0,0 +1,4 @@
+import { Validator } from './common.js';
+export declare class BooleanValidator extends Validator {
+    validate(fieldName: string, value: unknown): import("@anjianshi/utils").Success<unknown> | import("@anjianshi/utils").Failed<string>;
+}

package/dist/validators/boolean.js

@@ -0,0 +1,28 @@
+import { success, failed } from '@anjianshi/utils';
+import { Validator } from './common.js';
+export class BooleanValidator 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;
+        if (typeof value === 'string') {
+            const str = value.trim().toLocaleLowerCase();
+            if (['1', 'true', 'on', 'yes'].includes(str))
+                value = true;
+            else if (['0', 'false', 'off', 'no'].includes(str))
+                value = false;
+        }
+        else if (typeof value === 'number') {
+            if (value === 1)
+                value = true;
+            else if (value === 0)
+                value = false;
+        }
+        if (typeof value !== 'boolean')
+            return failed(`${fieldName} must be true or false`);
+        return success(value);
+    }
+}

package/dist/validators/common.d.ts

@@ -0,0 +1,23 @@
+import { type MaySuccess } from '@anjianshi/utils';
+export interface CommonOptions {
+    /**
+     * allow `null`
+     * @default false
+     */
+    null: boolean;
+    /**
+     * allow `undefined`
+     * @default false
+     */
+    void: boolean;
+    /**
+     * 默认值，原值为 undefined 时生效（原值为 null 不会生效），指定后 void 选项将失去作用。
+     * default value，used when original value is `undefined`(not for null), and make `void` option no effect.
+     */
+    defaults: unknown;
+}
+export declare class Validator<Opt = unknown> {
+    readonly options: Opt & CommonOptions;
+    constructor(options: Opt & Partial<CommonOptions>);
+    validate(fieldName: string, value: unknown): MaySuccess<unknown>;
+}

package/dist/validators/common.js

@@ -0,0 +1,25 @@
+import { success, failed } from '@anjianshi/utils';
+export class Validator {
+    options;
+    constructor(options) {
+        this.options = {
+            null: false,
+            void: false,
+            defaults: undefined,
+            ...options,
+        };
+    }
+    validate(fieldName, value) {
+        if (typeof value === 'undefined') {
+            if (typeof this.options.defaults !== 'undefined') {
+                value = this.options.defaults;
+            }
+            else if (!this.options.void) {
+                return failed(`${fieldName} must have a value`);
+            }
+        }
+        if (value === null && !this.options.null)
+            return failed(`${fieldName} cannot be null`);
+        return success(value);
+    }
+}

package/dist/validators/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 实现数据验证、格式化
+ * Implement data validation and formatting
+ */
+import { ArrayValidator } from './array.js';
+import { BooleanValidator } from './boolean.js';
+import { Validator, type CommonOptions } from './common.js';
+import { NumberValidator } from './number.js';
+import { ObjectValidator } from './object.js';
+import { StringValidator } from './string.js';
+/**
+ * 仅检查空值，不检查具体格式
+ * Check only for empty values, not for specific formatting
+ */
+export declare function any(options?: Partial<CommonOptions>): Validator<unknown>;
+export declare function string(...args: ConstructorParameters<typeof StringValidator>): StringValidator;
+export declare function number(...args: ConstructorParameters<typeof NumberValidator>): NumberValidator;
+export declare function boolean(options?: Partial<CommonOptions>): BooleanValidator;
+export declare function array(itemValidator: Validator, options?: Omit<ConstructorParameters<typeof ArrayValidator>[0], 'item'>): ArrayValidator;
+export declare function object(structOrValue: Record<string, Validator> | Validator, options?: Partial<CommonOptions>): ObjectValidator;

package/dist/validators/index.js

@@ -0,0 +1,38 @@
+/**
+ * 实现数据验证、格式化
+ * Implement data validation and formatting
+ */
+import { ArrayValidator } from './array.js';
+import { BooleanValidator } from './boolean.js';
+import { Validator } from './common.js';
+import { NumberValidator } from './number.js';
+import { ObjectValidator } from './object.js';
+import { StringValidator } from './string.js';
+/**
+ * 仅检查空值，不检查具体格式
+ * Check only for empty values, not for specific formatting
+ */
+export function any(options) {
+    return new Validator(options ?? {});
+}
+export function string(...args) {
+    return new StringValidator(...args);
+}
+export function number(...args) {
+    return new NumberValidator(...args);
+}
+export function boolean(options) {
+    return new BooleanValidator(options ?? {});
+}
+export function array(itemValidator, options) {
+    return new ArrayValidator({
+        item: itemValidator,
+        ...(options ?? {}),
+    });
+}
+export function object(structOrValue, options) {
+    return new ObjectValidator({
+        ...(structOrValue instanceof Validator ? { value: structOrValue } : { struct: structOrValue }),
+        ...options,
+    });
+}

package/dist/validators/number.d.ts

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,13 @@
+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>;
+}