@nmshd/typescript-rest 3.0.5

package/.ci/runChecks.sh

@@ -0,0 +1,7 @@
+set -e
+
+npm ci
+npm run build
+npm run lint
+npx license-check
+npx better-npm-audit audit --exclude=1096727,1097682

package/.eslintrc.js

@@ -0,0 +1,226 @@
+module.exports = {
+    env: {
+        es6: true,
+        node: true
+    },
+    ignorePatterns: ['.eslintrc.js', 'jest.config.js'],
+    extends: [
+        'plugin:@typescript-eslint/recommended',
+        'plugin:@typescript-eslint/recommended-requiring-type-checking',
+        'prettier'
+    ],
+    parser: '@typescript-eslint/parser',
+    parserOptions: {
+        project: ['tsconfig.json', 'test/tsconfig.json'],
+        sourceType: 'module'
+    },
+    plugins: ['eslint-plugin-jsdoc', 'eslint-plugin-prefer-arrow', '@typescript-eslint'],
+    root: true,
+    rules: {
+        '@typescript-eslint/adjacent-overload-signatures': 'error',
+        '@typescript-eslint/array-type': [
+            'error',
+            {
+                default: 'generic'
+            }
+        ],
+        '@typescript-eslint/ban-types': 'off',
+        '@typescript-eslint/consistent-type-assertions': 'error',
+        '@typescript-eslint/dot-notation': 'off',
+        '@typescript-eslint/explicit-function-return-type': 'off',
+        '@typescript-eslint/explicit-module-boundary-types': 'off',
+        '@typescript-eslint/indent': 'off',
+        '@typescript-eslint/member-delimiter-style': [
+            'error',
+            {
+                multiline: {
+                    delimiter: 'semi',
+                    requireLast: true
+                },
+                singleline: {
+                    delimiter: 'semi',
+                    requireLast: false
+                }
+            }
+        ],
+        '@typescript-eslint/naming-convention': [
+            'off',
+            {
+                selector: 'variable',
+                format: ['camelCase', 'UPPER_CASE', 'PascalCase'],
+                leadingUnderscore: 'allow',
+                trailingUnderscore: 'forbid'
+            }
+        ],
+        '@typescript-eslint/no-empty-function': 'error',
+        '@typescript-eslint/no-empty-interface': 'error',
+        '@typescript-eslint/no-explicit-any': 'off',
+        '@typescript-eslint/no-misused-new': 'error',
+        '@typescript-eslint/no-namespace': 'error',
+        '@typescript-eslint/no-parameter-properties': 'off',
+        '@typescript-eslint/no-shadow': [
+            'error',
+            {
+                hoist: 'all'
+            }
+        ],
+        '@typescript-eslint/no-unused-expressions': 'error',
+        '@typescript-eslint/no-use-before-define': 'off',
+        '@typescript-eslint/no-var-requires': 'off',
+        '@typescript-eslint/prefer-for-of': 'error',
+        '@typescript-eslint/prefer-function-type': 'error',
+        '@typescript-eslint/prefer-namespace-keyword': 'error',
+        '@typescript-eslint/semi': ['error', 'always'],
+        '@typescript-eslint/triple-slash-reference': [
+            'error',
+            {
+                path: 'always',
+                types: 'prefer-import',
+                lib: 'always'
+            }
+        ],
+        '@typescript-eslint/type-annotation-spacing': 'off',
+        '@typescript-eslint/typedef': 'off',
+        '@typescript-eslint/unified-signatures': 'error',
+        'arrow-parens': ['off', 'always'],
+        'brace-style': ['off', 'off'],
+        'comma-dangle': 'off',
+        complexity: 'off',
+        'constructor-super': 'error',
+        'dot-notation': 'off',
+        'eol-last': 'off',
+        eqeqeq: ['error', 'smart'],
+        'guard-for-in': 'error',
+        'id-denylist': [
+            'error',
+            'any',
+            'Number',
+            'number',
+            'String',
+            'string',
+            'Boolean',
+            'boolean',
+            'Undefined',
+            'undefined'
+        ],
+        'id-match': 'error',
+        indent: 'off',
+        'jsdoc/check-alignment': 'error',
+        'jsdoc/check-indentation': 'error',
+        // "jsdoc/newline-after-description": "error",
+        'linebreak-style': 'off',
+        'max-classes-per-file': 'off',
+        'max-len': 'off',
+        'new-parens': 'off',
+        'newline-per-chained-call': 'off',
+        'no-bitwise': 'error',
+        'no-caller': 'error',
+        'no-cond-assign': 'error',
+        'no-console': [
+            'error',
+            {
+                allow: [
+                    'warn',
+                    'dir',
+                    'time',
+                    'timeEnd',
+                    'timeLog',
+                    'trace',
+                    'assert',
+                    'clear',
+                    'count',
+                    'countReset',
+                    'group',
+                    'groupEnd',
+                    'table',
+                    'debug',
+                    'info',
+                    'dirxml',
+                    'groupCollapsed',
+                    'Console',
+                    'profile',
+                    'profileEnd',
+                    'timeStamp',
+                    'context',
+                    'createTask'
+                ]
+            }
+        ],
+        'no-debugger': 'error',
+        'no-empty': 'error',
+        'no-empty-function': 'off',
+        'no-eval': 'error',
+        'no-extra-semi': 'off',
+        'no-fallthrough': 'off',
+        'no-invalid-this': 'off',
+        'no-irregular-whitespace': 'off',
+        'no-multiple-empty-lines': 'off',
+        'no-new-wrappers': 'error',
+        'no-shadow': 'off',
+        'no-throw-literal': 'error',
+        'no-trailing-spaces': 'off',
+        'no-undef-init': 'error',
+        'no-underscore-dangle': 'off',
+        'no-unsafe-finally': 'error',
+        'no-unused-expressions': 'off',
+        'no-unused-labels': 'error',
+        'no-use-before-define': 'off',
+        'no-var': 'error',
+        'object-shorthand': ['error', 'never'],
+        'one-var': ['error', 'never'],
+        'padded-blocks': [
+            'off',
+            {
+                blocks: 'never'
+            },
+            {
+                allowSingleLineBlocks: true
+            }
+        ],
+        'prefer-arrow/prefer-arrow-functions': [
+            'error',
+            {
+                allowStandaloneDeclarations: true
+            }
+        ],
+        'prefer-const': 'error',
+        'quote-props': 'off',
+        radix: 'error',
+        'react/jsx-curly-spacing': 'off',
+        'react/jsx-equals-spacing': 'off',
+        'react/jsx-tag-spacing': [
+            'off',
+            {
+                afterOpening: 'allow',
+                closingSlash: 'allow'
+            }
+        ],
+        'react/jsx-wrap-multilines': 'off',
+        semi: 'off',
+        'space-before-function-paren': 'off',
+        'space-in-parens': ['off', 'never'],
+        'spaced-comment': [
+            'error',
+            'always',
+            {
+                markers: ['/']
+            }
+        ],
+        'use-isnan': 'error',
+        'valid-typeof': 'off',
+        '@typescript-eslint/no-unsafe-argument': 'off',
+        '@typescript-eslint/no-unsafe-member-access': 'off',
+        'constructor-super': 'off',
+        '@typescript-eslint/no-unsafe-assignment': 'off',
+        '@typescript-eslint/no-unsafe-return': 'off',
+        '@typescript-eslint/no-unsafe-call': 'off',
+        '@typescript-eslint/unbound-method': 'off',
+        '@typescript-eslint/no-unused-vars': [
+            'error',
+            {
+                argsIgnorePattern: '^_',
+                varsIgnorePattern: '^_'
+            }
+        ]
+    }
+};

package/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    groups:
+      update-github-actions-dependencies:
+        patterns:
+          - '*'
+    reviewers:
+      - 'jkoenig134'
+    labels:
+      - 'dependencies'
+
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    groups:
+      update-npm-dependencies:
+        patterns:
+          - '*'
+    reviewers:
+      - 'jkoenig134'
+    labels:
+      - 'dependencies'

package/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  run-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: current
+      - run: bash .ci/runChecks.sh
+
+  publish-npm:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: current
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm run build
+      - run: npx enhanced-publish --if-possible --use-preid-as-tag
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+    needs: ['run-checks']

package/.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Test
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  run-checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: current
+      - run: bash .ci/runChecks.sh
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: current
+      - run: npm ci
+      - run: npm run build
+      - run: npm run test

package/.prettierrc

@@ -0,0 +1,27 @@
+{
+  "semi": true,
+  "tabWidth": 4,
+  "singleQuote": true,
+  "printWidth": 120,
+  "trailingComma": "none",
+  "overrides": [
+    {
+      "files": "*.json",
+      "options": {
+        "tabWidth": 2
+      }
+    },
+    {
+      "files": "*.yml",
+      "options": {
+        "tabWidth": 2
+      }
+    },
+    {
+      "files": ".prettierrc",
+      "options": {
+        "tabWidth": 2
+      }
+    }
+  ]
+}

package/.vscode/settings.json

@@ -0,0 +1,31 @@
+{
+  "[jsonc]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[yaml]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[markdown]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "editor.formatOnSave": true,
+  "editor.formatOnPaste": true,
+  "files.autoSave": "off",
+  "html.format.wrapAttributes": "preserve-aligned",
+  "xmlTools.splitAttributesOnFormat": true,
+  "xmlTools.enforcePrettySelfClosingTagOnFormat": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "always"
+  },
+  "files.eol": "\n",
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

package/LICENSE

@@ -0,0 +1,22 @@
+
+The MIT License (MIT)
+
+Copyright (c) 2016 Thiago da Rosa de Bustamante
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+[![npm version](https://badge.fury.io/js/typescript-rest.svg)](https://badge.fury.io/js/typescript-rest)
+![Master Workflow](https://github.com/thiagobustamante/typescript-rest/workflows/Master%20Workflow/badge.svg)
+[![Coverage Status](https://codecov.io/gh/thiagobustamante/typescript-rest/branch/master/graph/badge.svg)](https://codecov.io/gh/thiagobustamante/typescript-rest)
+[![Known Vulnerabilities](https://snyk.io/test/github/thiagobustamante/typescript-rest/badge.svg?targetFile=package.json)](https://snyk.io/test/github/thiagobustamante/typescript-rest?targetFile=package.json)
+[![BCH compliance](https://bettercodehub.com/edge/badge/thiagobustamante/typescript-rest?branch=master)](https://bettercodehub.com/)
+
+# REST Services for Typescript
+
+This is a lightweight annotation-based [expressjs](http://expressjs.com/) extension for typescript.
+
+It can be used to define your APIs using decorators.
+
+**Table of Contents**
+
+-   [REST Services for Typescript](#rest-services-for-typescript)
+    -   [Installation](#installation)
+    -   [Configuration](#configuration)
+    -   [Basic Usage](#basic-usage)
+    -   [Using with an IoC Container](#using-with-an-ioc-container)
+    -   [Complete Guide](#complete-guide)
+    -   [Boilerplate Project](#boilerplate-project)
+
+## Installation
+
+This library only works with typescript. Ensure it is installed:
+
+```bash
+npm install typescript -g
+```
+
+To install typescript-rest:
+
+```bash
+npm install typescript-rest --save
+```
+
+## Configuration
+
+Typescript-rest requires the following TypeScript compilation options in your tsconfig.json file:
+
+```typescript
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "target": "es6" // or anything newer like esnext
+  }
+}
+```
+
+## Basic Usage
+
+```typescript
+import * as express from 'express';
+import { Server, Path, GET, PathParam } from 'typescript-rest';
+
+@Path('/hello')
+class HelloService {
+    @Path(':name')
+    @GET
+    sayHello(@PathParam('name') name: string): string {
+        return 'Hello ' + name;
+    }
+}
+
+let app: express.Application = express();
+Server.buildServices(app);
+
+app.listen(3000, function () {
+    console.log('Rest Server listening on port 3000!');
+});
+```
+
+That's it. You can just call now:
+
+```
+GET http://localhost:3000/hello/joe
+```
+
+## Using with an IoC Container
+
+Install the IoC container and the serviceFactory for the IoC Container
+
+```bash
+npm install @nmshd/typescript-rest --save
+npm install @nmshd/typescript-ioc --save
+npm install @nmshd/typescript-rest-ioc --save
+```
+
+Then add a rest.config file in the root of your project:
+
+```json
+{
+    "serviceFactory": "@nmshd/typescript-rest-ioc"
+}
+```
+
+And you can use Injections, Request scopes and all the features of the IoC Container. It is possible to use it with any other IoC Container, like Inversify.
+
+Example:
+
+```typescript
+class HelloService {
+    sayHello(name: string) {
+        return 'Hello ' + name;
+    }
+}
+
+@Path('/hello')
+class HelloRestService {
+    @Inject
+    private helloService: HelloService;
+
+    @Path(':name')
+    @GET
+    sayHello(@PathParam('name') name: string): string {
+        return this.sayHello(name);
+    }
+}
+```
+
+## Complete Guide
+
+Check our [documentation](https://github.com/thiagobustamante/typescript-rest/wiki).
+
+## Boilerplate Project
+
+You can check [this project](https://github.com/vrudikov/typescript-rest-boilerplate) to get started.

package/dist/decorators/methods.d.ts

@@ -0,0 +1,165 @@
+import 'reflect-metadata';
+/**
+ * A decorator to tell the [[Server]] that a method
+ * should be called to process HTTP GET requests.
+ *
+ * For example:
+ *
+ * ```
+ * @ Path('people')
+ * class PeopleService {
+ *   @ GET
+ *   getPeople() {
+ *      // ...
+ *   }
+ * }
+ * ```
+ *
+ * Will create a service that listen for requests like:
+ *
+ * ```
+ * GET http://mydomain/people
+ * ```
+ */
+export declare function GET(target: any, propertyKey: string): void;
+/**
+ * A decorator to tell the [[Server]] that a method
+ * should be called to process HTTP POST requests.
+ *
+ * For example:
+ *
+ * ```
+ * @ Path('people')
+ * class PeopleService {
+ *   @ POST
+ *   addPerson() {
+ *      // ...
+ *   }
+ * }
+ * ```
+ *
+ * Will create a service that listen for requests like:
+ *
+ * ```
+ * POST http://mydomain/people
+ * ```
+ */
+export declare function POST(target: any, propertyKey: string): void;
+/**
+ * A decorator to tell the [[Server]] that a method
+ * should be called to process HTTP PUT requests.
+ *
+ * For example:
+ *
+ * ```
+ * @ Path('people')
+ * class PeopleService {
+ *   @ PUT
+ *   @ Path(':id')
+ *   savePerson(person: Person) {
+ *      // ...
+ *   }
+ * }
+ * ```
+ *
+ * Will create a service that listen for requests like:
+ *
+ * ```
+ * PUT http://mydomain/people/123
+ * ```
+ */
+export declare function PUT(target: any, propertyKey: string): void;
+/**
+ * A decorator to tell the [[Server]] that a method
+ * should be called to process HTTP DELETE requests.
+ *
+ * For example:
+ *
+ * ```
+ * @ Path('people')
+ * class PeopleService {
+ *   @ DELETE
+ *   @ Path(':id')
+ *   removePerson(@ PathParam('id')id: string) {
+ *      // ...
+ *   }
+ * }
+ * ```
+ *
+ * Will create a service that listen for requests like:
+ *
+ * ```
+ * PUT http://mydomain/people/123
+ * ```
+ */
+export declare function DELETE(target: any, propertyKey: string): void;
+/**
+ * A decorator to tell the [[Server]] that a method
+ * should be called to process HTTP HEAD requests.
+ *
+ * For example:
+ *
+ * ```
+ * @ Path('people')
+ * class PeopleService {
+ *   @ HEAD
+ *   headPerson() {
+ *      // ...
+ *   }
+ * }
+ * ```
+ *
+ * Will create a service that listen for requests like:
+ *
+ * ```
+ * HEAD http://mydomain/people/123
+ * ```
+ */
+export declare function HEAD(target: any, propertyKey: string): void;
+/**
+ * A decorator to tell the [[Server]] that a method
+ * should be called to process HTTP OPTIONS requests.
+ *
+ * For example:
+ *
+ * ```
+ * @ Path('people')
+ * class PeopleService {
+ *   @ OPTIONS
+ *   optionsPerson() {
+ *      // ...
+ *   }
+ * }
+ * ```
+ *
+ * Will create a service that listen for requests like:
+ *
+ * ```
+ * OPTIONS http://mydomain/people/123
+ * ```
+ */
+export declare function OPTIONS(target: any, propertyKey: string): void;
+/**
+ * A decorator to tell the [[Server]] that a method
+ * should be called to process HTTP PATCH requests.
+ *
+ * For example:
+ *
+ * ```
+ * @ Path('people')
+ * class PeopleService {
+ *   @ PATCH
+ *   @ Path(':id')
+ *   savePerson(person: Person) {
+ *      // ...
+ *   }
+ * }
+ * ```
+ *
+ * Will create a service that listen for requests like:
+ *
+ * ```
+ * PATCH http://mydomain/people/123
+ * ```
+ */
+export declare function PATCH(target: any, propertyKey: string): void;