@nmshd/typescript-rest 3.0.5

package/src/server/model/metadata.ts

@@ -0,0 +1,118 @@
+'use strict';
+
+import { HttpMethod, ParserType, ServiceProcessor } from './server-types';
+
+export interface ServiceProperty {
+    type: ParamType;
+    name: string;
+    propertyType: any;
+}
+
+/**
+ * Metadata for REST service classes
+ */
+export class ServiceClass {
+    [key: string]: any;
+
+    public targetClass: any;
+    public path: string;
+    public authenticator: Record<string, Array<string>>;
+    public preProcessors: Array<ServiceProcessor>;
+    public postProcessors: Array<ServiceProcessor>;
+    public methods: Map<string, ServiceMethod>;
+    public bodyParserOptions: any;
+    public bodyParserType: ParserType;
+    public languages: Array<string>;
+    public accepts: Array<string>;
+    public properties: Map<string, ServiceProperty>;
+    public isAbstract: boolean = false;
+    public ignoreNextMiddlewares: boolean = false;
+    constructor(targetClass: any) {
+        this.targetClass = targetClass;
+        this.methods = new Map<string, ServiceMethod>();
+        this.properties = new Map<string, ServiceProperty>();
+    }
+
+    public addProperty(key: string, property: ServiceProperty) {
+        this.properties.set(key, property);
+    }
+
+    public hasProperties(): boolean {
+        return this.properties && this.properties.size > 0;
+    }
+}
+
+/**
+ * Metadata for REST service methods
+ */
+export class ServiceMethod {
+    [key: string]: any;
+
+    public name: string;
+    public path: string;
+    public authenticator: Record<string, Array<string>>;
+    public resolvedPath: string;
+    public httpMethod: HttpMethod;
+    public parameters: Array<MethodParam> = new Array<MethodParam>();
+    public mustParseCookies: boolean = false;
+    public files: Array<FileParam> = new Array<FileParam>();
+    public mustParseBody: boolean = false;
+    public bodyParserOptions: any;
+    public bodyParserType: ParserType;
+    public mustParseForms: boolean = false;
+    public acceptMultiTypedParam: boolean = false;
+    public languages: Array<string>;
+    public accepts: Array<string>;
+    public resolvedLanguages: Array<string>;
+    public resolvedAccepts: Array<string>;
+    public preProcessors: Array<ServiceProcessor>;
+    public postProcessors: Array<ServiceProcessor>;
+    public ignoreNextMiddlewares: boolean = false;
+}
+
+/**
+ * Metadata for File parameters on REST methods
+ */
+export class FileParam {
+    public name: string;
+    public singleFile: boolean;
+    constructor(name: string, singleFile: boolean) {
+        this.name = name;
+        this.singleFile = singleFile;
+    }
+}
+
+/**
+ * Metadata for REST service method parameters
+ */
+export class MethodParam {
+    public name: string;
+    public type: Function;
+    public paramType: ParamType;
+    constructor(name: string, type: Function, paramType: ParamType) {
+        this.name = name;
+        this.type = type;
+        this.paramType = paramType;
+    }
+}
+
+/**
+ * Enumeration of accepted parameter types
+ */
+export enum ParamType {
+    path = 'path',
+    query = 'query',
+    header = 'header',
+    cookie = 'cookie',
+    form = 'form',
+    body = 'body',
+    param = 'param',
+    file = 'file',
+    files = 'files',
+    context = 'context',
+    context_request = 'context_request',
+    context_response = 'context_response',
+    context_next = 'context_next',
+    context_accept = 'context_accept',
+    context_accept_language = 'context_accept_language'
+}

package/src/server/model/return-types.ts

@@ -0,0 +1,109 @@
+'use strict';
+
+import { ReferencedResource } from './server-types';
+
+/**
+ * Inform that a new resource was created. Server will
+ * add a Location header and set status to 201
+ */
+export class NewResource<T> extends ReferencedResource<T> {
+    /**
+     * Constructor. Receives the location of the new resource created.
+     * @param location To be added to the Location header on response
+     * @param body To be added to the response body
+     */
+    constructor(location: string, body?: T) {
+        super(location, 201);
+        this.body = body;
+    }
+}
+
+/**
+ * Inform that the request was accepted but is not completed.
+ * A Location header should inform the location where the user
+ * can monitor his request processing status.
+ */
+export class RequestAccepted<T> extends ReferencedResource<T> {
+    /**
+     * Constructor. Receives the location where information about the
+     * request processing can be found.
+     * @param location To be added to the Location header on response
+     * @param body To be added to the response body
+     */
+    constructor(location: string, body?: T) {
+        super(location, 202);
+        this.body = body;
+    }
+}
+
+/**
+ * Inform that the resource has permanently
+ * moved to a new location, and that future references should use a
+ * new URI with their requests.
+ */
+export class MovedPermanently<T> extends ReferencedResource<T> {
+    /**
+     * Constructor. Receives the location where the resource can be found.
+     * @param location To be added to the Location header on response
+     * @param body To be added to the response body
+     */
+    constructor(location: string, body?: T) {
+        super(location, 301);
+        this.body = body;
+    }
+}
+
+/**
+ * Inform that the resource has temporarily
+ * moved to another location, but that future references should
+ * still use the original URI to access the resource.
+ */
+export class MovedTemporarily<T> extends ReferencedResource<T> {
+    /**
+     * Constructor. Receives the location where the resource can be found.
+     * @param location To be added to the Location header on response
+     * @param body To be added to the response body
+     */
+    constructor(location: string, body?: T) {
+        super(location, 302);
+        this.body = body;
+    }
+}
+
+/**
+ * Used to download a resource.
+ */
+export class DownloadResource {
+    /**
+     * Constructor.
+     * @param filePath The file path to download.
+     * @param fileName The file name
+     */
+    constructor(
+        public filePath: string,
+        public fileName: string
+    ) {}
+}
+
+/**
+ * Used to download binary data as a file.
+ */
+export class DownloadBinaryData {
+    /**
+     * Constructor. Receives the location of the resource.
+     * @param content The binary data to be downloaded as a file.
+     * @param mimeType The mime-type to be passed on Content-Type header.
+     * @param fileName The file name
+     */
+    constructor(
+        public content: Buffer,
+        public mimeType: string,
+        public fileName?: string
+    ) {}
+}
+
+/**
+ * If returned by a service, no response will be sent to client. Use it
+ * if you want to send the response by yourself.
+ */
+export const NoResponse = {};

package/src/server/model/server-types.ts

@@ -0,0 +1,130 @@
+'use strict';
+
+import * as express from 'express';
+
+/**
+ * Limits for file uploads
+ */
+export interface FileLimits {
+    /** Max field name size (Default: 100 bytes) */
+    fieldNameSize?: number;
+    /** Max field value size (Default: 1MB) */
+    fieldSize?: number;
+    /** Max number of non- file fields (Default: Infinity) */
+    fields?: number;
+    /** For multipart forms, the max file size (in bytes)(Default: Infinity) */
+    fileSize?: number;
+    /** For multipart forms, the max number of file fields (Default: Infinity) */
+    files?: number;
+    /** For multipart forms, the max number of parts (fields + files)(Default: Infinity) */
+    parts?: number;
+    /** For multipart forms, the max number of header key=> value pairs to parse Default: 2000(same as node's http). */
+    headerPairs?: number;
+}
+
+/**
+ * The supported HTTP methods.
+ */
+export enum HttpMethod {
+    GET = 'GET',
+    POST = 'POST',
+    PUT = 'PUT',
+    DELETE = 'DELETE',
+    HEAD = 'HEAD',
+    OPTIONS = 'OPTIONS',
+    PATCH = 'PATCH'
+}
+
+/**
+ * Represents the current context of the request being handled.
+ */
+export class ServiceContext {
+    /**
+     * The resolved language to be used in the current request handling.
+     */
+    public language: string;
+    /**
+     * The preferred media type to be used in the current request handling.
+     */
+    public accept: string;
+    /**
+     * The request object.
+     */
+    public request: express.Request;
+    /**
+     * The response object
+     */
+    public response: express.Response;
+    /**
+     * The next function. It can be used to delegate to the next middleware
+     * registered the processing of the current request.
+     */
+    public next: express.NextFunction;
+}
+
+/**
+ * Used to create a reference to a resource.
+ */
+export abstract class ReferencedResource<T> {
+    /**
+     * the body to be sent
+     */
+    public body: T;
+
+    /**
+     * Constructor. Receives the location of the resource.
+     * @param location To be added to the Location header on response
+     * @param statusCode the response status code to be sent
+     */
+    constructor(
+        public location: string,
+        public statusCode: number
+    ) {}
+}
+
+/**
+ * The factory used to instantiate the object services
+ */
+export interface ServiceFactory {
+    /**
+     * Create a new service object. Called before each request handling.
+     */
+    create: (serviceClass: Function, context: ServiceContext) => any;
+    /**
+     * Return the type used to handle requests to the target service.
+     * By default, returns the serviceClass received, but you can use this
+     * to implement IoC integrations, once some frameworks like typescript-ioc or
+     * Inversify can override constructors for injectable types.
+     */
+    getTargetClass: (serviceClass: Function) => FunctionConstructor;
+}
+
+/**
+ * An optional authenticator for rest services
+ */
+export interface ServiceAuthenticator {
+    /**
+     * Get the user list of roles.
+     */
+    getRoles: (req: express.Request, res: express.Response) => Array<string>;
+    /**
+     * Initialize the authenticator
+     */
+    initialize(router: express.Router): void;
+    /**
+     * Retrieve the middleware used to authenticate users.
+     */
+    getMiddleware(): express.RequestHandler;
+}
+
+export type ServiceProcessor = (req: express.Request, res?: express.Response) => void | Promise<void>;
+export type ParameterConverter = (paramValue: any) => any;
+
+/**
+ * The types of parsers to parse the message body
+ */
+export enum ParserType {
+    json = 'json',
+    text = 'text',
+    raw = 'raw'
+}

package/src/server/parameter-processor.ts

@@ -0,0 +1,105 @@
+'use strict';
+
+import * as debug from 'debug';
+import { Errors } from '../typescript-rest';
+import { ParamType, ServiceProperty } from './model/metadata';
+import { ParameterConverter, ServiceContext } from './model/server-types';
+import { ServerContainer } from './server-container';
+
+type ParameterContextMapper = (context: ServiceContext, property: ServiceProperty) => any;
+
+export class ParameterProcessor {
+    public static get() {
+        return ParameterProcessor.instance;
+    }
+    private static instance = new ParameterProcessor();
+    private static defaultParamConverter: ParameterConverter = (p: any) => p;
+
+    private parameterMapper: Map<ParamType, ParameterContextMapper>;
+    private debugger = {
+        build: debug('typescript-rest:parameter-processor:build'),
+        runtime: debug('typescript-rest:parameter-processor:runtime')
+    };
+
+    private constructor() {
+        this.parameterMapper = this.initializeParameterMappers();
+    }
+
+    public processParameter(context: ServiceContext, property: ServiceProperty) {
+        const processor = this.parameterMapper.get(property.type);
+        if (!processor) {
+            throw new Errors.BadRequestError('Invalid parameter type');
+        }
+        return processor(context, property);
+    }
+
+    private initializeParameterMappers() {
+        this.debugger.build('Initializing parameters processors');
+        const parameterMapper: Map<ParamType, ParameterContextMapper> = new Map();
+
+        parameterMapper.set(ParamType.path, (context, property) =>
+            this.convertType(context.request.params[property.name], property.propertyType)
+        );
+        parameterMapper.set(ParamType.query, (context, property) =>
+            this.convertType(context.request.query[property.name] as string, property.propertyType)
+        );
+        parameterMapper.set(ParamType.header, (context, property) =>
+            this.convertType(context.request.header(property.name), property.propertyType)
+        );
+        parameterMapper.set(ParamType.cookie, (context, property) =>
+            this.convertType(context.request.cookies[property.name], property.propertyType)
+        );
+        parameterMapper.set(ParamType.body, (context, property) =>
+            this.convertType(context.request.body, property.propertyType)
+        );
+        parameterMapper.set(ParamType.file, (context, property) => {
+            this.debugger.runtime('Processing file parameter');
+            const files: Array<Express.Multer.File> = context.request.files
+                ? // @ts-expect-error will be an array
+                  context.request.files[property.name]
+                : null;
+            if (files && files.length > 0) {
+                return files[0];
+            }
+            return null;
+        });
+        parameterMapper.set(ParamType.files, (context, property) => {
+            this.debugger.runtime('Processing files parameter');
+            // @ts-expect-error will be an array
+            return context.request.files?.[property.name];
+        });
+        parameterMapper.set(ParamType.form, (context, property) =>
+            this.convertType(context.request.body[property.name], property.propertyType)
+        );
+        parameterMapper.set(ParamType.param, (context, property) => {
+            const paramValue = context.request.body[property.name] || context.request.query[property.name];
+            return this.convertType(paramValue, property.propertyType);
+        });
+        parameterMapper.set(ParamType.context, (context) => context);
+        parameterMapper.set(ParamType.context_request, (context) => context.request);
+        parameterMapper.set(ParamType.context_response, (context) => context.response);
+        parameterMapper.set(ParamType.context_next, (context) => context.next);
+        parameterMapper.set(ParamType.context_accept, (context) => context.accept);
+        parameterMapper.set(ParamType.context_accept_language, (context) => context.language);
+
+        return parameterMapper;
+    }
+
+    private convertType(paramValue: string | boolean, paramType: Function): any {
+        const serializedType = paramType['name'];
+        this.debugger.runtime('Processing parameter. received type: %s, received value:', serializedType, paramValue);
+        switch (serializedType) {
+            case 'Number':
+                return paramValue === undefined ? paramValue : parseFloat(paramValue as string);
+            case 'Boolean':
+                return paramValue === undefined ? paramValue : paramValue === 'true' || paramValue === true;
+            default:
+                let converter = ServerContainer.get().paramConverters.get(paramType);
+                if (!converter) {
+                    converter = ParameterProcessor.defaultParamConverter;
+                }
+
+                return converter(paramValue);
+        }
+    }
+}