{"_id":"@axmit/scythe-core","_rev":"3-cf09291ea733982700538190005473bd","name":"@axmit/scythe-core","dist-tags":{"latest":"1.8.8"},"versions":{"1.8.8":{"name":"@axmit/scythe-core","version":"1.8.8","contributors":[{"name":"Artem Shorin","email":"temansky95@gmail.com"},{"name":"Valerii Epifanov","email":"ve1994@gmail.com"}],"keywords":["es6","express"],"scripts":{"unit":"mocha --require ts-node/register --require tsconfig-paths/register --timeout 15000 ./lib/**/*.spec.ts","build":"rm -rf ./dist && tsc","prepublishOnly":"yarn build"},"description":"Core module for scythe framework","homepage":"https://gitlab.com/scythe-infra/scythe","main":"dist/index.js","types":"dist/index.d.ts","license":"ISC","repository":{"type":"git","url":"git+https://gitlab.com/scythe-infra/scythe.git"},"dependencies":{"@scythe/types":"1.0.2","@types/body-parser":"~1.17.0","@types/express":"~4.17.0","@types/lodash":"^4.14.123","@types/node":"~12.6.9","@types/node-schedule":"~1.2.2","@types/request":"~2.48.1","@types/socket.io":"^2.1.13","@types/supertest":"^2.0.8","@types/swagger-ui-express":"^3.0.0","@types/validator":"^10.9.0","ajv":"^6.7.0","body-parser":"~1.19.0","express":"~4.17.1","flatted":"^2.0.1","lodash":"^4.17.11","log4js":"^4.3.1","node-schedule":"~1.3.1","openapi3-ts":"^1.2.0","reflect-metadata":"^0.1.13","socket.io":"^3.1.2","socket.io-adapter":"^2.2.0","socket.io-parser":"^4.0.4","swagger-parser":"^8.0.0","swagger-ui-express":"^4.0.2","tslib":"^2.1.0","typescript":"^4.2.2","validator":"^11.1.0"},"devDependencies":{"@types/mocha":"~5.2.5","@types/socket.io-client":"^1.4.32","husky":"^3.0.2","lint-staged":"^9.2.1","mocha":"^6.1.4","prettier":"^1.15.3","should":"~13.2.3","socket.io-client":"^3.1.2","supertest":"^4.0.2","ts-node":"^9.1.1","tsconfig-paths":"^3.8.0"},"husky":{"hooks":{"pre-commit":"lint-staged"}},"lint-staged":{"*.{tsx,jsx,ts,js,json,css,md}":["prettier --config .prettierrc --write","git add"]},"gitHead":"0d23df475f2a95a426bc902f4a70541b07acc93b","bugs":{"url":"https://gitlab.com/scythe-infra/scythe/issues"},"_id":"@axmit/scythe-core@1.8.8","_nodeVersion":"12.18.3","_npmVersion":"6.14.6","dist":{"integrity":"sha512-4M3tmvqjdh9ETxM+QJ0wSKnPPRApClf7ihstlUp8o7uCTfnPe7XVmQY4Ol7OpJ74ojlBSZZmD0Ur7kEAYyO4Qw==","shasum":"c93be4289b2e89dd211abdf1a3340e92bf1a8ef1","tarball":"https://registry.npmjs.org/@axmit/scythe-core/-/scythe-core-1.8.8.tgz","fileCount":129,"unpackedSize":348098,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJgP4UBCRA9TVsSAnZWagAAaCgQAJ1G6PV8webwvQ7PjBrz\nDTbLUnRLSVcm6jisav/h4pEsMdk1tLJKReQc5LjjqJDfEk+ChgKViZM5RZZN\nhBV1KT1d24RHJa220msXNGDaNA53BAVN/Ox2nh+/MIeSVlo+ah7bcrg0N9UA\npBJ2kZ2NSj+pHbr3kKY6bPRr5B4MfgBdfEuLWtPtyv3+Dl2v7RfjKbEnaeG1\nf5D7xiyp0Q8AfTMcrka6mjR6CulOoTaTUfKDt7LojiKYqnPG7npcP3B8P+kV\nWPjs0hqrqj+xUAJXdjWBJBxU4F9SZ+B1i3SGgMYO8UVs0H7zbBiJVXYF+j9i\nv/Gy5jrqYIk0rIb7jvfIIVupli0rPc5WLfHBmBUxG26oz/GHHIksfieIZxkf\nzHLuPPighKD1sl4mLKbSMey7uLeobUUAsopp3fnJVBDVVpWDeJjhnifY6zxD\nE/viv19rWyORKhN5mr9QYShtyWWnvn62q6Y5CM8inFPGUk1LFwPmGCzG+1vt\nAOCGQNwBSI/ilEFIGGeutf9xi6hAEyy6h4wUtr9kiomTm86FH/EafgID7JHx\nx110T3WvjGoqKa7/JYqkz2sYs3jY5i9ObVLv4GIJijafVFtKqbUGtjEEeihs\nJQGIISEOf3kXKIdrNmAU4el22LgJPzLLk2ANazVlwUFhGpKAiyldbC8yEvPf\nAbK5\r\n=gfhR\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCD0hobDylq/0G6GSL7xx14uUgjhcgtdm+M87jXri37iwIgfkL8CSwSz7pFC+XhbNGk0Smytkvv9gQ+r4KUiihtGhA="}]},"_npmUser":{"name":"axmit-engineers","email":"engineers@axmit.com"},"directories":{},"maintainers":[{"name":"axmit-boris","email":"boris@axmit.com"},{"name":"axmit-engineers","email":"engineers@axmit.com"},{"name":"itersh","email":"ivan@axmit.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/scythe-core_1.8.8_1614775552750_0.6083660518581617"},"_hasShrinkwrap":false}},"time":{"created":"2021-03-03T12:45:52.749Z","1.8.8":"2021-03-03T12:45:52.919Z","modified":"2023-07-14T10:57:35.229Z"},"maintainers":[{"email":"engineers@axmit.com","name":"axmit-engineers"}],"description":"Core module for scythe framework","homepage":"https://gitlab.com/scythe-infra/scythe","keywords":["es6","express"],"repository":{"type":"git","url":"git+https://gitlab.com/scythe-infra/scythe.git"},"contributors":[{"name":"Artem Shorin","email":"temansky95@gmail.com"},{"name":"Valerii Epifanov","email":"ve1994@gmail.com"}],"bugs":{"url":"https://gitlab.com/scythe-infra/scythe/issues"},"license":"ISC","readme":"# Common information\n\nThis micro-framework created to help implement NodeJS backend applications with TypeScript without pain. The main idea is to provide several abstractions and tools to increase development speed and use popular used technologies as built-in features powered by TypeScript and also add ability for extension without losing flexibility. We use ExpressJS as core technology.\n\n# Table of contents\n\n<!--ts-->\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Built-in features](#built-in-features)\n\n  - [Scythe Application Builder](#scythe-application-builder)\n  - [Scythe Application](#scythe-application)\n  - [Routing](#routing)\n    - [Decorators](#decorators)\n    - [Scythe Router Builder](#scythe-router-builder)\n  - [Open API](#open-api)\n    - [Open API Components Builder](#open-api-components-builder)\n    - [Open API Helpers](#open-api-helpers)\n    - [Open API Validator](#open-api-validator)\n      <!--te-->\n\n# Installation\n\n`npm i @scythe/core` or `yarn add @scythe/core`\n\n# Usage\n\nTo create application you can use `ScytheApplicationBuilder` (see below for more information).\n\n```typescript\nimport { ScytheApplicationBuilder } from '@scythe/core';\n\nexport const testApp = new ScytheApplicationBuilder().build();\n```\n\nThis module will export instance of `ScytheApplication` (see below for more information) all you need to do is to call `start` method.\n\nLet's make it more complex and create endpoint to get sample string. Logic part that contain routing, docs and middleware definitions called controller. Controller is abstract class with TypeScript decorators for storing metadata upon which routing, OpenAPI documentation, middlewares logic etc are generated.\n\n```typescript\nimport { controller, get, summary, description, response } from '@scythe/core';\n\n@controller('/test', 'Test')\nexport abstract class TestController {\n  @get()\n  @summary('Test')\n  @description('Test description')\n  @response(200, 'string')\n  public testGet() {\n    return 'sample string';\n  }\n}\n```\n\nAnd update main application file to\n\n```typescript\nimport { ScytheApplicationBuilder } from '@scythe/core';\nimport { TestController } from './TestController';\n\nexport const testApp = new ScytheApplicationBuilder().addController(TestController).build();\n```\n\nThis will create express server on 3030 port with 2 endpoints:\n\n1. GET /test - which will return sample string\n2. GET /swagger - which will render swagger docks by metadata from decorators\n\nTo add more endpoints just define more methods with decorators (to see all available decorators keep reading).\n\n# Built-in features\n\n## .env\n\nAll .env variables will be available throught `proces.env[VARIABLE_NAME]`.  \nThis particular module use only one variable is:\n\n```\nPORT = 3030 //defines your server port\n```\n\n## Scythe Application Builder\n\nThis tool helps you to build Scythe Application (you can also use `ScytheApplication` class itself). Base example was provided in usage section.\n\n### Available `ScytheApplicationBuilder` methods:\n\n#### .setConfig(config: IConfig): ScytheApplicationBuilder\n\nSets config for the application. Available fields:\n\n- `withoutServer?: boolean` - if sets to true, application will be started without express server\n- `validateRequests?: boolean` - sets validation for requests according to open API schema (see more in OpenAPI validation section)\n- `validateResponse?: boolean` - sets validation for responses according to open API schema (see more in OpenAPI validation section)\n- `hydrateOpenAPIModels?: boolean` - enables hydration by OpenAPI docks\n- `openAPIInfo?: InfoObject` - info object for OpenAPI docs\n- `openAPIDocksEndpoint?: string`- endpoint to open api docs UI generated from metadata\n\nDefault config is:\n\n```\nvalidateResponse: true\nvalidateRequests: true\n```\n\n#### .setLogPath(path: string): ScytheApplicationBuilder\n\nSets path to application log file. Default path is `./logs/application.log`\n\n#### .addRouter(url: PathParams, router: IBuiltRouter): ScytheApplicationBuilder\n\nAdds router created by `ScytheRouterBuilder`, which will be mounted on `url` passed in params\n\n#### .addModule(module): ScytheApplicationBuilder\n\nAdds custom module to your application (more about modules see in `https://www.npmjs.com/package/@scythe/types`\n\n#### .addAdditionalMiddleware(middleware: RequestHandler): ScytheApplicationBuilder\n\nAdds additional middleware into middlewares poll. Accept ordinary express middleware as param\n\n#### .addJob(schedule: string, job: TJobHandler): ScytheApplicationBuilder\n\nSchedule a job to be executed by timetable. Params:\n\n- schedule: string - CRON schedule string\n- job: Function - function to be executed\n\n#### .addController(Controller: any, basePath?: string): ScytheApplicationBuilder\n\nAdds controller to current application to be mounted on basePath.  \nController is abstract class decorated with @controller decorator (see more in decorators section)\n\n#### .build(): ScytheApplication\n\nBuilds `ScytheApplication` based on provided info\n\n## Scythe Application\n\nBase application class which contains almost all necessary logic.\n\n### Available `ScytheApplication` methods\n\n#### constructor(config: IConfig, logPath: string, additionalMiddlewares: RequestHandler[] = [])\n\nInits application with provided params:\n\n##### config\n\n- `withoutServer?: boolean` - if sets to true, application will be started without express server\n- `validateRequests?: boolean` - sets validation for requests according to open API schema (see more in OpenAPI validation section)\n- `validateResponse?: boolean` - sets validation for responses according to open API schema (see more in OpenAPI validation section)\n- `hydrateOpenAPIModels?: boolean` - enables hydration by OpenAPI docks\n- `openAPIInfo?: InfoObject` - info object for OpenAPI docs\n- `openAPIDocksEndpoint?: string` - endpoint to open api docs UI generated from metadata\n\n##### logPath\n\nPath to application log file\n\n##### additionalMiddlewares\n\nArray of express middlewares to be applied\n\n#### .addRouter(url: PathParams, router: IBuiltRouter): void\n\nAdds router created by `ScytheRouterBuilder`, which will be mounted on `url` passed in params\n\n#### .addModule(module): void\n\nAdds custom module to your application (more about modules see in `https://www.npmjs.com/package/@scythe/types`\n\n#### .start(): void\n\nStarts an application running all modules and creating express servers if needs to\n\n#### .addJob(schedule: string, job: TJobHandler): void\n\nSchedule a job to be executed by timetable. Params:\n\n- schedule: string - CRON schedule string\n- job: Function - function to be executed\n\n#### .registerController(Controller: any, basePath?: string): void\n\nAdds controller to current application to be mounted on basePath.  \nController is abstract class decorated with `@controller` or `@webSocketController` decorator (see more in decorators section)\n\n#### .stop(): void\n\nStops application destroying connections and stopping jobs and modules\n\n#### .getOpenAPIDocs(): OpenAPIObject\n\nReturn generated open API docs\n\n## Routing\n\n### Decorators\n\nThis framework provides amount of decorators to create controller to simplify working with routing/docs/validation ets.\n\n#### Available decorators:\n\n#### `@controller(path: string, tag?: string): ClassDecorator`\n\nSets decorated class as controller. All methods inside will be mounted on path from params. If tag param is passed, all endpoints will have this open API tag by default\n\n#### `@baseSecurity(securitySchema: string): ClassDecorator`\n\nSets base security schema for controller. Accept name of open API defined security schema\n\n#### `@commonMiddlewares(...middlewares: RequestHandler[]): ClassDecorator`\n\nSets common middlewares to be executed before each method logic in controller\n\n#### `@method(method: string, path: string = '/'): MethodDecorator`\n\nBinds http method to class method. If class method decorated with it, it will be treated as endpoint by passed path\n\n#### `@get(path: string = '/'): MethodDecorator`\n\nAlias for get method\n\n#### `@put(path: string = '/'): MethodDecorator`\n\nAlias for put method\n\n#### `@del(path: string = '/'): MethodDecorator`\n\nAlias for delete method\n\n#### `@post(path: string = '/'): MethodDecorator`\n\nAlias for post method\n\n#### `@patch(path: string = '/'): MethodDecorator`\n\nAlias for patch method\n\n#### `@middlewares(...middlewares: RequestHandler[]): MethodDecorator`\n\nSets middlewares to be executed before method logic in controller\n\n#### `@tag(tag: string): MethodDecorator`\n\nSets open API tag\n\n#### `@summary(summary: string): MethodDecorator`\n\nSets Open API summary\n\n#### `@description(description: string): MethodDecorator`\n\nSets Open API description\n\n#### `@response(responseCode: number, type: string | INewable, isArray: boolean = false): MethodDecorator`\n\nSets Open API response by path as Open API schema reference with selected response status code\n\n#### `@defaultResponses(...responses: EDefaultResponse[]): MethodDecorator`\n\nSets predefined responses. Can be:\n\n- EDefaultResponse.NotFound\n- EDefaultResponse.NoContent\n- EDefaultResponse.Unauthorized\n- EDefaultResponse.Forbidden\n- EDefaultResponse.ValidationError\n\n#### `@parameters(...parameters: ParameterObject[]): MethodDecorator`\n\nSets Open API parameters\n\n#### `@headerParameter(name: string, schema: string, required: boolean = true): MethodDecorator`\n\nSets Open API header parameter by its schema reference name\n\n#### `@security(name: string): MethodDecorator`\n\nSets Open API security schema by its name\n\n#### `@deprecated(): MethodDecorator`\n\nMark endpoint as deprecated\n\n### Scythe Router Builder\n\nBuilder for express routing implementation, it provides extended version of express router by adding methods to write open API docs.  \nShould be used only if controllers do not cover your case.  \nUsage:\n\n```typescript\nimport { ScytheRouterBuilder } from '@scythe/core';\n\nconst builder = new ScytheRouterBuilder();\nbuilder\n  .useNamespace('/yourPath')\n  .useOpenAPIDocs({\n    get: {\n      tags: ['Your Tags'],\n      summary: 'Summary',\n      description: 'Descrition',\n      consumes: ['application/json'],\n      produces: ['application/json'],\n      parameters: [{ name: 'filter', description: 'filter', required: false, type: 'string', in: 'query' }],\n      responses: {\n        '200': {\n          description: 'description',\n          type: 'array',\n          items: {\n            $ref: '#/definitions/swagerSchemaName'\n          }\n        }\n      }\n    }\n  })\n  .buildNamespace()\n  .get(yourMiddlewaresGoesHere);\n\nexport const awesomeRouter = builder.buildRouter();\n```\n\n#### Available methods:\n\n#### .useNamespace(namespace: string): ScytheRouterBuilder\n\nDefine route namespace (ex. `/users`, `/users/:id`)\n\n#### .useOpenAPIDocs(specs: PathItemObject): ScytheRouterBuilder\n\nSets OpenAPI docs for your namespace\n\n#### .setOpenAPIComponents(schema)\n\nSets OpenAPI definitions for your router\n\n#### .buildNamespace()\n\nBuilds namespace and return express router route instance, where you can add any request methods\n\n#### .buildRouter()\n\nBuilds router to be passed into `ScytheApplication` or `ScytheApplicationBuilder`\n\n## Open API\n\nThis framework provides full set of types of Open API v3, so it'll be easy for you to implement all definitions.\n\n### Open API Components Builder\n\nThis builder helps you create Open API definition to pass into controller or router builder\n\n#### Available methods:\n\n#### .useOpenAPISchemas(schemas: TOpenAPISchemas): OpenAPIComponentsBuilder\n\nSets Open API schemas according to Open API v3\n\n#### .useOpenAPIResponses(responses: TOpenAPIResponses): OpenAPIComponentsBuilder\n\nSets Open API responses according to Open API v3\n\n#### .useOpenAPIParameters(parameters: TOpenAPIParameters): OpenAPIComponentsBuilder\n\nSets Open API parameters according to Open API v3\n\n#### .useOpenAPIExamples(examples: TOpenAPIExamples): OpenAPIComponentsBuilder\n\nSets Open API examples according to Open API v3\n\n#### .useOpenAPIRequestBodies(requestBodies: TOpenAPIRequestBodies): OpenAPIComponentsBuilder\n\nSets Open API request bodies according to Open API v3\n\n#### .useOpenAPIHeaders(headers: TOpenAPIHeaders): OpenAPIComponentsBuilder\n\nSets Open API headers according to Open API v3\n\n#### .useOpenAPISecuritySchemas(securitySchemas: TOpenAPISecuritySchemas): OpenAPIComponentsBuilder\n\nSets Open API security schemas according to Open API v3\n\n#### .useOpenAPILinks(links: TOpenAPILinks): OpenAPIComponentsBuilder\n\nSets Open API links according to Open API v3\n\n#### .useOpenAPICallbacks(callbacks: TOpenAPICallbacks): OpenAPIComponentsBuilder\n\nSets Open API callbacks according to Open API v3\n\n#### .buildComponents()\n\nBuilds all components to be passed into @registerComponents decorator or into router builder\n\n### Open API Helpers\n\nThis part provides amount of function helpers to ease Open API components writing\n\n#### Available helpers:\n\n#### getQueryParam(name: string, schema: SchemaObject | ReferenceObject, required: boolean = true)\n\nGenerates Open API query param component\n\n##### Example:\n\n```\n{\n name: 'test', in: 'query', schema: { $ref: '#/components/schemas/test' }, required: true}\n```\n\n#### createRefContent(schemaName: string, isArray: boolean = false)\n\nCreates Open API json content based on schema.\n\n##### Example:\n\n```\n{\n content: { 'application/json': { schema: { $ref: '#/components/schemas/test' } } }}\n```\n\n#### createSchemaContent(schema: SchemaObject)\n\nSame as `createRefContent` only take Open API schema object\n\n#### getRefObject(name: string, type: EComponentTypes = EComponentTypes.Schemas)\n\nGenerates Open API ref object by passed type. Available types:\n\n- EComponentTypes.Schemas\n- EComponentTypes.RequestBodies\n- EComponentTypes.Responses\n- EComponentTypes.Parameters\n- EComponentTypes.Examples\n- EComponentTypes.Headers\n- EComponentTypes.SecuritySchemas\n- EComponentTypes.Links\n- EComponentTypes.Callbacks\n\n##### Example:\n\n```\n{\n $ref: '#/componens/headers/TestHeader'}\n```\n\n#### createValidationError(dataPath: string, message: string)\n\nReturn object representation of Open API validation error object (same object returns by Open API Validator)\n\n##### Example:\n\n```\n{\n error: { message: 'Validation error', details: [{ dataPath: '.body.test', message: 'should be string' }] }}\n```\n\n### Open API Validator\n\nIf pass\n\n```\nvalidateResponse: true\nvalidateRequests: true\n```\n\ninto your application, all your responses/requests will be validated according to your Open API definitions.\n","readmeFilename":"readme.md"}