zibri 1.0.0 → 1.1.0

package/README.md

@@ -1 +1,2 @@
-# Zibri
+# Zibri
+An express based backend framework.

package/dist/index.d.mts

@@ -0,0 +1,490 @@
+import { Request, Response, Express, NextFunction } from 'express';
+import { Repository as Repository$1, FindManyOptions, FindOneOptions, ColumnType, DataSourceOptions as DataSourceOptions$1, DataSource as DataSource$1, EntitySchema, EntitySchemaColumnOptions, Transaction } from 'typeorm';
+import { oas31 } from 'openapi3-ts';
+
+interface DataSourceServiceInterface {
+    init: () => Promise<void>;
+}
+
+declare class DataSourceService implements DataSourceServiceInterface {
+    private readonly logger;
+    constructor();
+    init(): Promise<void>;
+}
+
+declare function DataSource(): ClassDecorator;
+
+type StringPropertyMetadata = {
+    required: boolean;
+    type: 'string';
+    primary: boolean;
+};
+type StringPropertyMetadataInput = Partial<StringPropertyMetadata> & Pick<StringPropertyMetadata, 'type'>;
+
+type NumberPropertyMetadata = {
+    required: boolean;
+    type: 'number';
+    primary: boolean;
+};
+type NumberPropertyMetadataInput = Partial<NumberPropertyMetadata> & Pick<NumberPropertyMetadata, 'type'>;
+
+type Newable<T> = new (...args: any[]) => T;
+
+type DeepPartial<T> = T | (T extends (infer U)[] ? DeepPartial<U>[] : T extends Map<infer K, infer V> ? Map<DeepPartial<K>, DeepPartial<V>> : T extends Set<infer M> ? Set<DeepPartial<M>> : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T);
+
+type OmitStrict<T extends object, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
+
+type ObjectPropertyMetadata = {
+    required: boolean;
+    type: 'object';
+    cls: Newable<unknown>;
+};
+type ObjectPropertyMetadataInput = Partial<ObjectPropertyMetadata> & Pick<ObjectPropertyMetadata, 'type' | 'cls'>;
+
+type ArrayPropertyMetadata = {
+    required: boolean;
+    type: 'array';
+    itemType: Exclude<PropertyMetadata['type'], 'object' | 'array'> | Newable<unknown>;
+};
+type ArrayPropertyMetadataInput = Partial<ArrayPropertyMetadata> & Pick<ArrayPropertyMetadata, 'type' | 'itemType'>;
+
+type DatePropertyMetadata = {
+    required: boolean;
+    type: 'date';
+};
+type DatePropertyMetadataInput = Partial<DatePropertyMetadata> & Pick<DatePropertyMetadata, 'type'>;
+
+type PropertyMetadata = StringPropertyMetadata | NumberPropertyMetadata | ObjectPropertyMetadata | ArrayPropertyMetadata | DatePropertyMetadata;
+type PropertyMetadataInput = StringPropertyMetadataInput | NumberPropertyMetadataInput | ObjectPropertyMetadataInput | ArrayPropertyMetadataInput | DatePropertyMetadataInput;
+declare function Property(data: PropertyMetadataInput): PropertyDecorator;
+
+type EntityMetadata = {
+    tableName: string;
+};
+declare function Entity(tableName?: string): ClassDecorator;
+
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type IntersectionInstances<T extends Newable<unknown>[]> = UnionToIntersection<InstanceType<T[number]>>;
+declare function IntersectionType<Bases extends Newable<unknown>[]>(...bases: Bases): Newable<IntersectionInstances<Bases>>;
+
+declare function PartialType<T>(Base: Newable<T>): Newable<Partial<T>>;
+
+declare function PickType<T, K extends keyof T>(Base: Newable<T>, keys: readonly K[]): Newable<Pick<T, K>>;
+
+declare function OmitType<T, K extends keyof T>(Base: Newable<T>, keys: readonly K[]): Newable<Omit<T, K>>;
+
+type BaseEntity = {
+    id: string | number;
+};
+declare class Repository<T extends BaseEntity> {
+    private readonly entityName;
+    private readonly typeOrmRepository;
+    private readonly logger;
+    constructor(entityName: string, typeOrmRepository: Repository$1<T>);
+    create(data: DeepPartial<T>): Promise<T>;
+    findById(id: T['id']): Promise<T>;
+    findAll(options?: FindManyOptions<T>): Promise<T[]>;
+    findOne(options: FindOneOptions<T>): Promise<T>;
+    updateById(id: T['id'], data: DeepPartial<T>): Promise<T>;
+    deleteById(id: T['id']): Promise<void>;
+}
+
+type DataSourceOptions = DataSourceOptions$1;
+declare abstract class BaseDataSource {
+    protected readonly columnTypeMappingOverride: Partial<Record<PropertyMetadata['type'], ColumnType>>;
+    private get columnTypeMapping();
+    abstract readonly options: OmitStrict<DataSourceOptions, 'entities'>;
+    abstract readonly entities: Newable<BaseEntity>[];
+    protected ds?: DataSource$1;
+    init(): Promise<void>;
+    protected getEntitySchemas(): EntitySchema[];
+    protected propertyToColumnOptions(metadata: PropertyMetadata): EntitySchemaColumnOptions;
+    getRepository<T extends BaseEntity>(cls: Newable<T>): Repository<T>;
+    startTransaction(): Transaction;
+}
+
+type DiToken<T> = Newable<T> | string;
+
+type DiProvider<T> = {
+    token: DiToken<T>;
+    useClass?: Newable<T>;
+    useFactory?: (...deps: unknown[]) => T;
+};
+
+declare function Injectable<T>(token?: DiToken<T>): ClassDecorator;
+
+declare function Inject<T>(token: DiToken<T>): ParameterDecorator;
+
+declare function repositoryTokenFor<T extends BaseEntity>(entity: Newable<T>): string;
+declare function InjectRepository<T extends BaseEntity>(entityClass: Newable<T>): ParameterDecorator;
+
+declare const ZIBRI_DI_TOKENS: {
+    readonly ROUTER: "zi.router";
+    readonly LOG_LEVEL: "zi.log_level";
+    readonly LOGGER: "zi.logger";
+    readonly ASSET_SERVICE: "zi.asset_service";
+    readonly GLOBAL_ERROR_HANDLER: "zi.global_error_handler";
+    readonly OPEN_API_SERVICE: "zi.open_api_service";
+    readonly PARSER: "zi.parser_service";
+    readonly VALIDATION_SERVICE: "zi.validation_service";
+    readonly DATA_SOURCE_SERVICE: "zi.data_source_service";
+};
+
+declare function inject<T>(token: DiToken<T>): T;
+
+declare enum HttpMethod {
+    GET = "get",
+    POST = "post",
+    PUT = "put",
+    PATCH = "patch",
+    DELETE = "delete"
+}
+
+declare enum HttpStatus {
+    INTERNAL_SERVER_ERROR = 500,
+    NOT_FOUND_ERROR = 404,
+    BAD_REQUEST = 400
+}
+
+declare enum MimeType {
+    JSON = "application/json",
+    HTML = "text/html"
+}
+declare function isMimeType(value: string): value is MimeType;
+
+type KnownHeader = 'Accept' | 'Accept-Encoding' | 'Authorization' | 'Cache-Control' | 'Content-Length' | 'Content-Type' | 'Cookie' | 'Host' | 'Origin' | 'Referer' | 'User-Agent' | 'X-Requested-With' | 'X-Forwarded-For' | 'X-Forwarded-Host' | 'X-Forwarded-Proto' | 'X-Real-IP' | 'X-Correlation-ID' | 'If-None-Match' | 'If-Modified-Since' | 'Connection' | 'DNT' | 'Sec-Fetch-Mode' | 'Sec-Fetch-Site' | 'TE';
+
+interface BodyParserInterface {
+    readonly contentType: MimeType;
+    parse: (req: Request) => Promise<unknown>;
+}
+
+declare function BodyParser(): ClassDecorator;
+
+type Route = `/${string}`;
+type ControllerRouteConfiguration = {
+    httpMethod: HttpMethod;
+    route: Route;
+    controllerMethod: string;
+};
+
+type RouteConfiguration = {
+    httpMethod: HttpMethod;
+    route: Route;
+    handler: (req: Request, res: Response) => unknown | Promise<unknown>;
+};
+
+interface RouterInterface {
+    registerController: <T extends Object>(controllerClass: Newable<T>, ...params: any[]) => void;
+    register: (route: RouteConfiguration, ...params: any[]) => void;
+    attachTo: (app: ZibriApplication, ...params: any[]) => void;
+}
+
+declare class Router implements RouterInterface {
+    private readonly router;
+    private readonly logger;
+    private readonly parser;
+    private readonly validationService;
+    constructor();
+    attachTo(app: ZibriApplication): void;
+    register(route: RouteConfiguration): void;
+    registerController<T extends Object>(controllerClass: Newable<T>): void;
+    private routeToRequestHandler;
+    private controllerRouteToRequestHandler;
+    private resolveRouteParams;
+}
+
+declare function Controller(baseRoute: Route): ClassDecorator;
+
+declare function Get(path?: Route): MethodDecorator;
+
+declare function Post(path?: Route): MethodDecorator;
+
+declare function Delete(path?: Route): MethodDecorator;
+
+declare function Patch(path?: Route): MethodDecorator;
+
+type PathParamMetadata = {
+    name: string;
+    description?: string;
+    required: boolean;
+    type: 'string' | 'number';
+};
+type BaseQueryParamMetadata = {
+    name: string;
+    description?: string;
+    required: boolean;
+};
+type SimpleQueryParamMetadata = BaseQueryParamMetadata & {
+    type: 'string' | 'number' | 'boolean' | 'date';
+};
+type SimpleQueryParamMetadataInput = Partial<OmitStrict<SimpleQueryParamMetadata, 'name'>>;
+type ObjectQueryParamMetadata = BaseQueryParamMetadata & {
+    type: 'object';
+    cls: Newable<unknown>;
+};
+type ObjectQueryParamMetadataInput = OmitStrict<ObjectQueryParamMetadata, 'name' | keyof BaseQueryParamMetadata> & Partial<OmitStrict<BaseQueryParamMetadata, 'name'>>;
+type ArrayQueryParamMetadata = BaseQueryParamMetadata & {
+    type: 'array';
+    itemType: 'string' | 'number' | 'boolean' | 'date' | Newable<unknown>;
+};
+type ArrayQueryParamMetadataInput = OmitStrict<ArrayQueryParamMetadata, 'name' | keyof BaseQueryParamMetadata> & Partial<OmitStrict<BaseQueryParamMetadata, 'name'>>;
+type QueryParamMetadata = SimpleQueryParamMetadata | ObjectQueryParamMetadata | ArrayQueryParamMetadata;
+type QueryParamMetadataInput = SimpleQueryParamMetadataInput | ObjectQueryParamMetadataInput | ArrayQueryParamMetadataInput;
+type HeaderParamMetadata = {
+    name: KnownHeader | Omit<string, KnownHeader>;
+    description?: string;
+    required: boolean;
+    type: 'string' | 'number' | 'boolean' | 'date';
+};
+declare namespace Param {
+    function path(name: string, options?: Partial<OmitStrict<PathParamMetadata, 'name'>>): ParameterDecorator;
+    function query(name: string, options?: QueryParamMetadataInput): ParameterDecorator;
+    function header(name: KnownHeader | Omit<string, KnownHeader>, options?: Partial<OmitStrict<HeaderParamMetadata, 'name'>>): ParameterDecorator;
+}
+
+type BodyMetadata = {
+    modelClass: Newable<unknown>;
+    index: number;
+    name: string;
+    description?: string;
+    required: boolean;
+};
+type BodyMetadataInput = Partial<OmitStrict<BodyMetadata, 'modelClass' | 'index' | 'name'>>;
+declare function Body(modelClass: Newable<unknown>, options?: BodyMetadataInput): ParameterDecorator;
+
+interface ParserInterface {
+    parseRequestBody: (req: Request) => Promise<unknown>;
+    parsePathParam: (req: Request, metadata: PathParamMetadata) => unknown;
+    parseQueryParam: (req: Request, metadata: QueryParamMetadata) => unknown;
+    parseHeaderParam: (req: Request, metadata: HeaderParamMetadata) => unknown;
+    attachTo: (app: ZibriApplication) => void;
+}
+
+declare class Parser implements ParserInterface {
+    private readonly logger;
+    private readonly bodyParsers;
+    private readonly pathParamParseFunctions;
+    private readonly queryParamParseFunctions;
+    private readonly headerParamParseFunctions;
+    constructor();
+    parseHeaderParam(req: Request, metadata: HeaderParamMetadata): unknown;
+    parseQueryParam(req: Request, metadata: QueryParamMetadata): unknown;
+    parsePathParam(req: Request, metadata: PathParamMetadata): unknown;
+    parseRequestBody(req: Request): Promise<unknown>;
+    attachTo(): void;
+}
+
+declare class JsonBodyParser implements BodyParserInterface {
+    readonly contentType: MimeType;
+    parse(req: Request): Promise<unknown>;
+}
+
+type ZibriApplicationOptions = {
+    name: string;
+    controllers: Newable<unknown>[];
+    dataSources?: Newable<BaseDataSource>[];
+    providers?: DiProvider<unknown>[];
+    bodyParsers?: Newable<BodyParserInterface>[];
+};
+
+/**
+ * A zibri application.
+ */
+declare class ZibriApplication {
+    private readonly options;
+    readonly express: Express;
+    private _router;
+    get router(): RouterInterface;
+    private logger;
+    private assetService;
+    private openApiService;
+    private parser;
+    private dataSourceService;
+    constructor(options: ZibriApplicationOptions);
+    init(): Promise<void>;
+    /**
+     * Starts on the given port.
+     * @param port - The port to start on.
+     * @throws When the app has already been started.
+     */
+    start(port: number): void;
+}
+
+type GlobalErrorHandler = (err: unknown, req: Request, res: Response, next: NextFunction) => void;
+
+declare const errorHandler: GlobalErrorHandler;
+
+declare abstract class HttpError extends Error {
+    status: HttpStatus;
+    title: string;
+    paragraphs: string[];
+    constructor(message: string | string[], status: HttpStatus, title: string, options?: ErrorOptions);
+}
+declare function isHttpError(value: unknown): value is HttpError;
+
+declare class InternalServerError extends HttpError {
+    constructor(message: string | string[], options?: ErrorOptions);
+}
+
+declare class NotFoundError extends HttpError {
+    constructor(message: string | string[], options?: ErrorOptions);
+}
+
+declare class UnmatchedRouteError extends NotFoundError {
+    constructor(originalUrl: string, options?: ErrorOptions);
+}
+
+declare class BadRequestError extends HttpError {
+    constructor(message: string | string[], options?: ErrorOptions);
+}
+
+type ValidationProblem = {
+    key: string;
+    message: string;
+};
+declare class IsRequiredValidationProblem implements ValidationProblem {
+    readonly key: string;
+    readonly message: string;
+    constructor(key: string);
+}
+
+interface ValidationServiceInterface {
+    validateRequestBody: (model: unknown, cls: Newable<unknown>) => void;
+    validateHeaderParam: (param: unknown, meta: HeaderParamMetadata) => void;
+    validatePathParam: (param: unknown, meta: PathParamMetadata) => void;
+    validateQueryParam: (param: unknown, meta: QueryParamMetadata) => void;
+}
+
+declare class ValidationService implements ValidationServiceInterface {
+    private readonly pathParamValidationFunctions;
+    private readonly queryParamValidationFunctions;
+    private readonly headerParamValidationFunctions;
+    private readonly propertyValidationFunctions;
+    private validateObjectQueryParam;
+    private validateArrayQueryParam;
+    validateHeaderParam(param: unknown, meta: HeaderParamMetadata): void;
+    validatePathParam(param: unknown, meta: PathParamMetadata): void;
+    validateQueryParam(param: unknown, meta: QueryParamMetadata): void;
+    validateRequestBody(model: unknown, cls: Newable<unknown>): void;
+    private validateModel;
+    private validateProperty;
+    private validateArrayProperty;
+    private getPropertyArrayItemMetadata;
+    private getQueryArrayItemMetadata;
+    private validateObjectProperty;
+}
+
+type ValidationErrorType = 'body' | 'path' | 'query' | 'header';
+declare class ValidationError extends BadRequestError {
+    constructor(type: ValidationErrorType, problems: ValidationProblem[], options?: ErrorOptions);
+}
+
+interface AssetServiceInterface {
+    readonly assetsPath: string;
+    readonly assetsRoute: Route;
+    attachTo: (app: ZibriApplication, ...params: any[]) => void;
+}
+
+declare class AssetService implements AssetServiceInterface {
+    private readonly logger;
+    readonly assetsPath: string;
+    readonly assetsRoute: Route;
+    constructor();
+    attachTo(app: ZibriApplication): void;
+    private buildFileTree;
+    private mapToTree;
+    private walk;
+}
+
+declare enum AppState {
+    OFFLINE = "offline",
+    CREATED = "created",
+    INITIALIZED = "initialized",
+    RUNNING = "running"
+}
+type AppData = {
+    state: AppState;
+    name?: string;
+};
+declare abstract class GlobalRegistry {
+    private static readonly appData;
+    static readonly injectables: DiProvider<unknown>[];
+    static readonly controllerClasses: Newable<Object>[];
+    static readonly dataSourceClasses: Newable<BaseDataSource>[];
+    static readonly entityClasses: Newable<BaseEntity>[];
+    static readonly bodyParsers: Newable<BodyParserInterface>[];
+    private static readonly validateAppStateChange;
+    static getAppData<K extends keyof AppData>(key: K): AppData[K];
+    static setAppData(options: ZibriApplicationOptions): void;
+    static markAppAsCreated(): void;
+    static markAppAsInitialized(): void;
+    static markAppAsRunning(): void;
+    static isAppRunning(): boolean;
+    static isAppInitialized(): boolean;
+    static isAppCreated(): boolean;
+    private static changeAppState;
+}
+
+interface LoggerInterface {
+    debug: (...messages: (string | number)[]) => void;
+    info: (...messages: (string | number)[]) => void;
+    warn: (...messages: (string | number)[]) => void;
+    error: (...messages: (string | number | Error)[]) => void;
+    critical: (...messages: (string | number | Error)[]) => void;
+}
+
+declare const LOG_LEVEL_VALUES: {
+    readonly debug: 0;
+    readonly info: 1;
+    readonly warn: 2;
+    readonly error: 3;
+    readonly critical: 4;
+};
+type LogLevels = typeof LOG_LEVEL_VALUES;
+type LogLevel = keyof LogLevels;
+declare class Logger implements LoggerInterface {
+    debug(...messages: (string | number)[]): void;
+    info(...messages: (string | number)[]): void;
+    warn(...messages: (string | number)[]): void;
+    error(...messages: (string | number | Error)[]): void;
+    critical(...messages: (string | number | Error)[]): void;
+    private log;
+    private getTimestamp;
+}
+
+type OpenApiDefinition = oas31.OpenAPIObject;
+type OpenApiPaths = oas31.PathsObject;
+type OpenApiOperation = oas31.OperationObject;
+type OpenApiParameter = (oas31.ParameterObject | oas31.ReferenceObject);
+type OpenApiRequestBodyObject = oas31.RequestBodyObject;
+type OpenApiSchemaObject = oas31.SchemaObject;
+
+interface OpenApiServiceInterface {
+    readonly openApiRoute: Route;
+    attachTo: (app: ZibriApplication) => void;
+    createOpenApiDefinition: (app: ZibriApplication) => OpenApiDefinition;
+}
+
+declare class OpenApiService implements OpenApiServiceInterface {
+    readonly openApiRoute: Route;
+    private readonly logger;
+    private readonly assetService;
+    constructor();
+    attachTo(app: ZibriApplication): void;
+    createOpenApiDefinition(): OpenApiDefinition;
+    private resolveOpenApiPaths;
+    private buildOpenApiBody;
+    private buildOpenApiSchemaForModel;
+    private extractPathParamNames;
+    private buildPathParameters;
+    private buildQueryParameters;
+    private queryParamToSchema;
+    private getQueryArrayItemMetadata;
+    private buildHeaderParameters;
+    private headerParamToSchema;
+}
+
+export { type AppData, AppState, type ArrayQueryParamMetadata, AssetService, type AssetServiceInterface, BadRequestError, BaseDataSource, type BaseEntity, Body, type BodyMetadata, type BodyMetadataInput, BodyParser, type BodyParserInterface, Controller, type ControllerRouteConfiguration, DataSource, type DataSourceOptions, DataSourceService, type DataSourceServiceInterface, Delete, type DiProvider, type DiToken, Entity, type EntityMetadata, Get, type GlobalErrorHandler, GlobalRegistry, type HeaderParamMetadata, HttpError, HttpMethod, HttpStatus, Inject, InjectRepository, Injectable, InternalServerError, IntersectionType, IsRequiredValidationProblem, JsonBodyParser, type KnownHeader, type LogLevel, type LogLevels, Logger, type LoggerInterface, MimeType, type Newable, NotFoundError, type ObjectQueryParamMetadata, OmitType, type OpenApiDefinition, type OpenApiOperation, type OpenApiParameter, type OpenApiPaths, type OpenApiRequestBodyObject, type OpenApiSchemaObject, OpenApiService, type OpenApiServiceInterface, Param, Parser, type ParserInterface, PartialType, Patch, type PathParamMetadata, PickType, Post, Property, type PropertyMetadata, type PropertyMetadataInput, type QueryParamMetadata, Repository, type Route, type RouteConfiguration, Router, type RouterInterface, type SimpleQueryParamMetadata, UnmatchedRouteError, ValidationError, type ValidationProblem, ValidationService, type ValidationServiceInterface, ZIBRI_DI_TOKENS, ZibriApplication, type ZibriApplicationOptions, errorHandler, inject, isHttpError, isMimeType, repositoryTokenFor };