@extk/expressive 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,262 @@
+import winston, { Logger as Logger$1 } from 'winston';
+import * as express from 'express';
+import { RequestHandler, Request } from 'express';
+import * as express_serve_static_core from 'express-serve-static-core';
+import { RouteParameters } from 'express-serve-static-core';
+import * as morgan from 'morgan';
+import * as helmet from 'helmet';
+
+type ExpressRoute = string;
+type ExpressLocalsObj = Record<string, any>;
+type ExpressHandler = RequestHandler<RouteParameters<ExpressRoute>, any, any, qs.ParsedQs, ExpressLocalsObj[]>;
+type PaginationQuery = {
+    limit?: string | number;
+    page?: string | number;
+};
+type Pagination = {
+    limit: number;
+    offset: number;
+};
+type ReqSnapshot = {
+    readonly query: qs.ParsedQs;
+    readonly path: string;
+    readonly method: string;
+    readonly userId: string | number | undefined;
+};
+
+type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head' | 'options' | 'trace';
+type OtherString = string & {};
+type ContentType = 'application/json' | 'application/xml' | 'text/plain' | 'text/html' | OtherString;
+type AlertHandler = (err: Error & Record<string, any>, reqSnapshot?: ReqSnapshot) => void | Promise<void>;
+type Logger = Logger$1;
+type Container = {
+    logger: Logger;
+    alertHandler?: AlertHandler;
+};
+
+type Schema = Record<string, unknown> | {
+    $ref: string;
+};
+type Content = {
+    description?: string;
+    content?: Partial<Record<ContentType, {
+        schema: Schema;
+    }>>;
+};
+type Param = {
+    in: 'path' | 'query' | 'headers';
+    name: string;
+    desciption: string;
+    required: boolean;
+    schema: Schema;
+};
+type Servers = {
+    url: string;
+    description?: string;
+}[];
+type PathItem = {
+    summary?: string;
+    requestBody?: Content;
+    parameters?: Param[];
+    servers?: Servers;
+    responses?: Record<string, Content>;
+    tags?: string[];
+    operationId?: string;
+    deprecated?: boolean;
+    security?: AuthMethod[];
+};
+type AuthMethod = Record<string, string[]>;
+type SecurityScheme = {
+    type: 'http';
+    scheme: 'basic' | 'bearer';
+} | {
+    type: 'apiKey';
+    in: 'header';
+    name: string;
+} | {
+    type: 'openIdConnect';
+    openIdConnectUrl: string;
+} | {
+    type: 'oauth2';
+    flows: {
+        authorizationCode: {
+            authorizationUrl: string;
+            tokenUrl: string;
+            scopes: Record<string, string>;
+        };
+    };
+};
+type SwaggerConfig = {
+    openapi: '3.1.0';
+    info?: {
+        version?: string;
+        title?: string;
+        termsOfService?: string;
+    };
+    externalDocs?: {
+        url?: string;
+        description?: string;
+    };
+    servers?: Servers;
+    paths: Record<string, {
+        summary?: string;
+        description?: string;
+        servers?: Servers;
+    } & Partial<Record<HttpMethod, PathItem>>>;
+    components: {
+        schemas?: Record<string, Schema>;
+        securitySchemes?: Record<string, SecurityScheme>;
+    };
+    security?: AuthMethod[];
+};
+
+declare class ApiError extends Error {
+    readonly code: string;
+    readonly httpStatusCode: number;
+    data?: unknown;
+    constructor(message: string, httpStatusCode: number, errorCode: string);
+    setData<T>(data: T): this;
+}
+declare class NotFoundError extends ApiError {
+    constructor(message?: string);
+}
+declare class DuplicateError extends ApiError {
+    constructor(message?: string);
+}
+declare class BadRequestError extends ApiError {
+    constructor(message?: string);
+}
+declare class SchemaValidationError extends ApiError {
+    constructor(message?: string);
+}
+declare class FileTooBigError extends ApiError {
+    constructor();
+}
+declare class InvalidFileTypeError extends ApiError {
+    constructor();
+}
+declare class InvalidCredentialsError extends ApiError {
+    constructor();
+}
+declare class InternalError extends ApiError {
+    constructor();
+}
+declare class TooManyRequestsError extends ApiError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends ApiError {
+    constructor(message?: string);
+}
+declare class TokenExpiredError extends ApiError {
+    constructor(message?: string);
+}
+declare class UserUnauthorizedError extends ApiError {
+    constructor(message?: string);
+}
+
+declare function parsePositiveInteger<T>(v: T, defaultValue: number, max?: number): number;
+declare function parseIdOrFail(v: unknown): number;
+declare function slugify(text: string): string;
+declare function getTmpDir(): string;
+declare function getTmpPath(...steps: string[]): string;
+declare function parseDefaultPagination(query: PaginationQuery): Pagination;
+declare function createReqSnapshot(req: Request & {
+    user?: {
+        id?: string | number;
+    };
+}): ReqSnapshot;
+
+declare function isDev(): boolean;
+declare function isProd(): boolean;
+declare function getEnvVar(configName: string): string;
+type Env = 'dev' | 'prod' | OtherString;
+
+declare const createLogger: (options?: winston.LoggerOptions) => winston.Logger;
+declare const getDefaultFileLogger: (name?: string) => winston.Logger;
+declare const getDefaultConsoleLogger: (name?: string) => winston.Logger;
+
+declare function jsonSchema(schema: Schema): Content;
+declare function jsonSchemaRef(name: string): Content;
+declare function param(inP: Param['in'], id: string, schema: Schema, required?: boolean, description?: string, name?: string): Param;
+declare function pathParam(id: string, schema: Schema, required?: boolean, description?: string, name?: string): Param;
+declare function queryParam(id: string, schema: Schema, required?: boolean, description?: string, name?: string): Param;
+declare function headerParam(id: string, schema: Schema, required?: boolean, description?: string, name?: string): Param;
+declare const SWG: {
+    param: typeof param;
+    pathParam: typeof pathParam;
+    queryParam: typeof queryParam;
+    headerParam: typeof headerParam;
+    jsonSchema: typeof jsonSchema;
+    jsonSchemaRef: typeof jsonSchemaRef;
+    security: (name: string) => AuthMethod;
+    securitySchemes: {
+        readonly BasicAuth: () => SecurityScheme;
+        readonly BearerAuth: () => SecurityScheme;
+        readonly ApiKeyAuth: (headerName: string) => SecurityScheme;
+        readonly OpenID: (openIdConnectUrl: string) => SecurityScheme;
+        readonly OAuth2: (authorizationUrl: string, tokenUrl: string, scopes: Record<string, string>) => SecurityScheme;
+    };
+};
+
+declare class ApiErrorResponse<T = undefined> {
+    readonly status = "error";
+    readonly message: string;
+    readonly errorCode: string;
+    readonly errors?: T;
+    constructor(message: string, errorCode: string, errors?: T);
+}
+
+declare class ApiResponse<T = undefined> {
+    status: string;
+    result?: T;
+    constructor(result?: T);
+}
+
+declare function bootstrap(container: Container): {
+    notFoundMiddleware: (_req: express.Request, res: express.Response, _next: express.NextFunction) => void;
+    silently: (fn: () => Promise<void>, reqSnapshot?: ReqSnapshot) => void;
+    getErrorHandlerMiddleware: (errorMapper?: (err: Error & Record<string, unknown>) => ApiError | null | undefined) => (err: Error & Record<string, unknown>, req: express.Request, res: express.Response, _next: express.NextFunction) => Promise<void>;
+    swaggerBuilder: () => {
+        withInfo(info: SwaggerConfig["info"]): /*elided*/ any;
+        withServers(servers: Servers): /*elided*/ any;
+        withSecuritySchemes(schemes: Record<string, SecurityScheme>): /*elided*/ any;
+        withSchemas(schemas: Record<string, Schema>): /*elided*/ any;
+        withDefaultSecurity(globalAuthMethods: AuthMethod[]): /*elided*/ any;
+        get(): SwaggerConfig;
+    };
+    expressiveServer(configs: {
+        swagger: {
+            path: ExpressRoute;
+            doc: SwaggerConfig;
+        };
+        options?: {
+            helmet?: Readonly<helmet.HelmetOptions>;
+            morgan?: Readonly<{
+                format: string;
+                options?: Parameters<typeof morgan>[1];
+            }>;
+        };
+        app?: express.Express;
+    }): express.Express;
+    expressiveRouter(configs: {
+        oapi?: {
+            tags?: string[];
+            servers?: Servers;
+            security?: AuthMethod[];
+        };
+    }): {
+        router: express_serve_static_core.Router;
+        addRoute(context: {
+            method: HttpMethod;
+            path: ExpressRoute;
+            oapi?: {
+                pathOverride?: string;
+                pathParameters?: Param[];
+                headerParameters?: Param[];
+                queryParameters?: Param[];
+            } & Omit<PathItem, "parameters">;
+        }, ...handlers: ExpressHandler[]): express_serve_static_core.Router;
+    };
+};
+
+export { type AlertHandler, ApiError, ApiErrorResponse, ApiResponse, type AuthMethod, BadRequestError, type Container, type Content, type ContentType, DuplicateError, type Env, type ExpressHandler, type ExpressLocalsObj, type ExpressRoute, FileTooBigError, ForbiddenError, type HttpMethod, InternalError, InvalidCredentialsError, InvalidFileTypeError, type Logger, NotFoundError, type OtherString, type Pagination, type PaginationQuery, type Param, type PathItem, type ReqSnapshot, SWG, type Schema, SchemaValidationError, type SecurityScheme, type Servers, type SwaggerConfig, TokenExpiredError, TooManyRequestsError, UserUnauthorizedError, bootstrap, createLogger, createReqSnapshot, getDefaultConsoleLogger, getDefaultFileLogger, getEnvVar, getTmpDir, getTmpPath, isDev, isProd, parseDefaultPagination, parseIdOrFail, parsePositiveInteger, slugify };

package/dist/index.d.ts

@@ -0,0 +1,262 @@
+import winston, { Logger as Logger$1 } from 'winston';
+import * as express from 'express';
+import { RequestHandler, Request } from 'express';
+import * as express_serve_static_core from 'express-serve-static-core';
+import { RouteParameters } from 'express-serve-static-core';
+import * as morgan from 'morgan';
+import * as helmet from 'helmet';
+
+type ExpressRoute = string;
+type ExpressLocalsObj = Record<string, any>;
+type ExpressHandler = RequestHandler<RouteParameters<ExpressRoute>, any, any, qs.ParsedQs, ExpressLocalsObj[]>;
+type PaginationQuery = {
+    limit?: string | number;
+    page?: string | number;
+};
+type Pagination = {
+    limit: number;
+    offset: number;
+};
+type ReqSnapshot = {
+    readonly query: qs.ParsedQs;
+    readonly path: string;
+    readonly method: string;
+    readonly userId: string | number | undefined;
+};
+
+type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete' | 'head' | 'options' | 'trace';
+type OtherString = string & {};
+type ContentType = 'application/json' | 'application/xml' | 'text/plain' | 'text/html' | OtherString;
+type AlertHandler = (err: Error & Record<string, any>, reqSnapshot?: ReqSnapshot) => void | Promise<void>;
+type Logger = Logger$1;
+type Container = {
+    logger: Logger;
+    alertHandler?: AlertHandler;
+};
+
+type Schema = Record<string, unknown> | {
+    $ref: string;
+};
+type Content = {
+    description?: string;
+    content?: Partial<Record<ContentType, {
+        schema: Schema;
+    }>>;
+};
+type Param = {
+    in: 'path' | 'query' | 'headers';
+    name: string;
+    desciption: string;
+    required: boolean;
+    schema: Schema;
+};
+type Servers = {
+    url: string;
+    description?: string;
+}[];
+type PathItem = {
+    summary?: string;
+    requestBody?: Content;
+    parameters?: Param[];
+    servers?: Servers;
+    responses?: Record<string, Content>;
+    tags?: string[];
+    operationId?: string;
+    deprecated?: boolean;
+    security?: AuthMethod[];
+};
+type AuthMethod = Record<string, string[]>;
+type SecurityScheme = {
+    type: 'http';
+    scheme: 'basic' | 'bearer';
+} | {
+    type: 'apiKey';
+    in: 'header';
+    name: string;
+} | {
+    type: 'openIdConnect';
+    openIdConnectUrl: string;
+} | {
+    type: 'oauth2';
+    flows: {
+        authorizationCode: {
+            authorizationUrl: string;
+            tokenUrl: string;
+            scopes: Record<string, string>;
+        };
+    };
+};
+type SwaggerConfig = {
+    openapi: '3.1.0';
+    info?: {
+        version?: string;
+        title?: string;
+        termsOfService?: string;
+    };
+    externalDocs?: {
+        url?: string;
+        description?: string;
+    };
+    servers?: Servers;
+    paths: Record<string, {
+        summary?: string;
+        description?: string;
+        servers?: Servers;
+    } & Partial<Record<HttpMethod, PathItem>>>;
+    components: {
+        schemas?: Record<string, Schema>;
+        securitySchemes?: Record<string, SecurityScheme>;
+    };
+    security?: AuthMethod[];
+};
+
+declare class ApiError extends Error {
+    readonly code: string;
+    readonly httpStatusCode: number;
+    data?: unknown;
+    constructor(message: string, httpStatusCode: number, errorCode: string);
+    setData<T>(data: T): this;
+}
+declare class NotFoundError extends ApiError {
+    constructor(message?: string);
+}
+declare class DuplicateError extends ApiError {
+    constructor(message?: string);
+}
+declare class BadRequestError extends ApiError {
+    constructor(message?: string);
+}
+declare class SchemaValidationError extends ApiError {
+    constructor(message?: string);
+}
+declare class FileTooBigError extends ApiError {
+    constructor();
+}
+declare class InvalidFileTypeError extends ApiError {
+    constructor();
+}
+declare class InvalidCredentialsError extends ApiError {
+    constructor();
+}
+declare class InternalError extends ApiError {
+    constructor();
+}
+declare class TooManyRequestsError extends ApiError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends ApiError {
+    constructor(message?: string);
+}
+declare class TokenExpiredError extends ApiError {
+    constructor(message?: string);
+}
+declare class UserUnauthorizedError extends ApiError {
+    constructor(message?: string);
+}
+
+declare function parsePositiveInteger<T>(v: T, defaultValue: number, max?: number): number;
+declare function parseIdOrFail(v: unknown): number;
+declare function slugify(text: string): string;
+declare function getTmpDir(): string;
+declare function getTmpPath(...steps: string[]): string;
+declare function parseDefaultPagination(query: PaginationQuery): Pagination;
+declare function createReqSnapshot(req: Request & {
+    user?: {
+        id?: string | number;
+    };
+}): ReqSnapshot;
+
+declare function isDev(): boolean;
+declare function isProd(): boolean;
+declare function getEnvVar(configName: string): string;
+type Env = 'dev' | 'prod' | OtherString;
+
+declare const createLogger: (options?: winston.LoggerOptions) => winston.Logger;
+declare const getDefaultFileLogger: (name?: string) => winston.Logger;
+declare const getDefaultConsoleLogger: (name?: string) => winston.Logger;
+
+declare function jsonSchema(schema: Schema): Content;
+declare function jsonSchemaRef(name: string): Content;
+declare function param(inP: Param['in'], id: string, schema: Schema, required?: boolean, description?: string, name?: string): Param;
+declare function pathParam(id: string, schema: Schema, required?: boolean, description?: string, name?: string): Param;
+declare function queryParam(id: string, schema: Schema, required?: boolean, description?: string, name?: string): Param;
+declare function headerParam(id: string, schema: Schema, required?: boolean, description?: string, name?: string): Param;
+declare const SWG: {
+    param: typeof param;
+    pathParam: typeof pathParam;
+    queryParam: typeof queryParam;
+    headerParam: typeof headerParam;
+    jsonSchema: typeof jsonSchema;
+    jsonSchemaRef: typeof jsonSchemaRef;
+    security: (name: string) => AuthMethod;
+    securitySchemes: {
+        readonly BasicAuth: () => SecurityScheme;
+        readonly BearerAuth: () => SecurityScheme;
+        readonly ApiKeyAuth: (headerName: string) => SecurityScheme;
+        readonly OpenID: (openIdConnectUrl: string) => SecurityScheme;
+        readonly OAuth2: (authorizationUrl: string, tokenUrl: string, scopes: Record<string, string>) => SecurityScheme;
+    };
+};
+
+declare class ApiErrorResponse<T = undefined> {
+    readonly status = "error";
+    readonly message: string;
+    readonly errorCode: string;
+    readonly errors?: T;
+    constructor(message: string, errorCode: string, errors?: T);
+}
+
+declare class ApiResponse<T = undefined> {
+    status: string;
+    result?: T;
+    constructor(result?: T);
+}
+
+declare function bootstrap(container: Container): {
+    notFoundMiddleware: (_req: express.Request, res: express.Response, _next: express.NextFunction) => void;
+    silently: (fn: () => Promise<void>, reqSnapshot?: ReqSnapshot) => void;
+    getErrorHandlerMiddleware: (errorMapper?: (err: Error & Record<string, unknown>) => ApiError | null | undefined) => (err: Error & Record<string, unknown>, req: express.Request, res: express.Response, _next: express.NextFunction) => Promise<void>;
+    swaggerBuilder: () => {
+        withInfo(info: SwaggerConfig["info"]): /*elided*/ any;
+        withServers(servers: Servers): /*elided*/ any;
+        withSecuritySchemes(schemes: Record<string, SecurityScheme>): /*elided*/ any;
+        withSchemas(schemas: Record<string, Schema>): /*elided*/ any;
+        withDefaultSecurity(globalAuthMethods: AuthMethod[]): /*elided*/ any;
+        get(): SwaggerConfig;
+    };
+    expressiveServer(configs: {
+        swagger: {
+            path: ExpressRoute;
+            doc: SwaggerConfig;
+        };
+        options?: {
+            helmet?: Readonly<helmet.HelmetOptions>;
+            morgan?: Readonly<{
+                format: string;
+                options?: Parameters<typeof morgan>[1];
+            }>;
+        };
+        app?: express.Express;
+    }): express.Express;
+    expressiveRouter(configs: {
+        oapi?: {
+            tags?: string[];
+            servers?: Servers;
+            security?: AuthMethod[];
+        };
+    }): {
+        router: express_serve_static_core.Router;
+        addRoute(context: {
+            method: HttpMethod;
+            path: ExpressRoute;
+            oapi?: {
+                pathOverride?: string;
+                pathParameters?: Param[];
+                headerParameters?: Param[];
+                queryParameters?: Param[];
+            } & Omit<PathItem, "parameters">;
+        }, ...handlers: ExpressHandler[]): express_serve_static_core.Router;
+    };
+};
+
+export { type AlertHandler, ApiError, ApiErrorResponse, ApiResponse, type AuthMethod, BadRequestError, type Container, type Content, type ContentType, DuplicateError, type Env, type ExpressHandler, type ExpressLocalsObj, type ExpressRoute, FileTooBigError, ForbiddenError, type HttpMethod, InternalError, InvalidCredentialsError, InvalidFileTypeError, type Logger, NotFoundError, type OtherString, type Pagination, type PaginationQuery, type Param, type PathItem, type ReqSnapshot, SWG, type Schema, SchemaValidationError, type SecurityScheme, type Servers, type SwaggerConfig, TokenExpiredError, TooManyRequestsError, UserUnauthorizedError, bootstrap, createLogger, createReqSnapshot, getDefaultConsoleLogger, getDefaultFileLogger, getEnvVar, getTmpDir, getTmpPath, isDev, isProd, parseDefaultPagination, parseIdOrFail, parsePositiveInteger, slugify };