{"id":21474851,"url":"https://github.com/cbinet/volcano","last_synced_at":"2025-03-17T07:45:37.273Z","repository":{"id":57393711,"uuid":"140143396","full_name":"CBinet/volcano","owner":"CBinet","description":"A framework built on top of the express.js library","archived":false,"fork":false,"pushed_at":"2018-08-21T00:18:44.000Z","size":360,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-25T19:39:30.548Z","etag":null,"topics":["api","express","framework","http","websocket","ws"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/volcano-express","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CBinet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-07-08T06:30:08.000Z","updated_at":"2018-08-21T00:18:45.000Z","dependencies_parsed_at":"2022-09-15T12:20:44.090Z","dependency_job_id":null,"html_url":"https://github.com/CBinet/volcano","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CBinet%2Fvolcano","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CBinet%2Fvolcano/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CBinet%2Fvolcano/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CBinet%2Fvolcano/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CBinet","download_url":"https://codeload.github.com/CBinet/volcano/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243997037,"owners_count":20380980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","express","framework","http","websocket","ws"],"created_at":"2024-11-23T10:33:22.657Z","updated_at":"2025-03-17T07:45:37.250Z","avatar_url":"https://github.com/CBinet.png","language":"TypeScript","readme":"# Volcano-express\n\n- [Installation](#installation)\n- [Get started](#get-started)\n  - [Prerequisites](#prerequisites)\n  - [Create the project](#create-the-project)\n- [Dependency Injection Module](#dependency-injection-module)\n  - [Registering](#registering)\n  - [Resolving](#resolving)\n- [Http Module](#http-module)\n  - [Http Controller](#http-controller)\n  - [Http Middleware](#http-middleware)\n- [Websocket Module](#websocket-module)\n  - [Websocket Controller](#websocket-controller)\n  - [Websocket Middleware](#websocket-middleware)\n\n## Get started\n\n### Prerequisites\n\n```dos\nnpm install volcano-express-cli -g\n ```\n\n### Create the project\n  \nTo create all the files and import all the dependencies needed for a new project, simply use the **init** command from the CLI.  \nThe **init** command will create all the files needed to get started.\n\n```dos\nvolcano --init\n```\n\nYou can find more informations on the CLI commands on the [Volcano-express CLI](https://www.npmjs.com/package/volcano-express-cli) npm package page.\n\n### Start the server\n\nTo start the server, use the **npm start** command.  \nBy default, the server starts at port 3000.\n\n```dos\nnpm start\n```\n\nIf the server starts with no error, it outputs a success message in the console :\n\n```dos\nServer started at port 3000\n```\n\n### Test the server\n\nOnce you have started the server, you should be able to test it with an http request at :\n\n```dos\nGET/ http://localhost:3000/demo\n```\n\nYou should receive a 200 OK response with the following content if everything is working properly :\n\n```dos\n\"Demo\"\n```\n\n## Dependency Injection Module\n\n### Registering\n\nThere are multiples ways to register your services to inject them into your controllers or other services :\n\n- Using the **@Injectable** decorator :\n\n```ts\n@Injectable(CarRepository)\nexport class InMemoryCarRepository {\n    ...\n}\n```\n\n- Using service registering the main file :\n\n```ts\nconst server = Volcano.createServer({\n    controllers : [...],\n    middlewares: [...],\n    services: [\n        { interface: CarRepository, use: InMemoryCarRepository }\n    ]\n});\n```\n\n- Using the **ServiceLocator** register method to register the service directly :\n\n```ts\nServiceLocator.register(CarRepository, InMemoryCarRepository);\n```\n\n### Resolving\n\nA few way are available to inject the registered services into your controllers or others services.\n\n- You can use the **@Inject** decorator :\n\n```ts\n@Inject(CarRepository) private carRepository: CarRepository;\n```\n\n- You can also call the **ServiceLocator** resolve method to get a service instance directly :\n\n```ts\nprivate carRepository: CarRepository = ServiceLocator.resolve(CarRepository);\n```\n\n## Http Module\n\n### Http Controller\n\n```ts\n@Controller()\nexport class CarController extends HttpController {}\n```\n\n#### Http actions\n\nThe following http actions are supported by the **HttpController** :\n\n- **GET**\n- **POST**\n- **PUT**\n- **DELETE**\n\n```ts\n@Controller()\nexport class CarController extends HttpController {\n\n    @GET('cars')\n    getCars(): Result { ... }\n\n    @POST('cars')\n    addCar(car: Car): Result { ... }\n\n    @PUT('cars/:id')\n    updateCar(id: string, car: Car): Result { ... }\n\n    @DELETE('cars/:id')\n    deleteCar(id: string): Result { ... }\n}\n```\n\nThe parameters of an **HttpAction** decorated method must be in this given order :\nThe parameters from the route (i.e.: id in '/cars/:id) must be first, in appearing order. The body will always be the last parameter of a signature. **GET** decorated method cannot have a body.\n\n```ts\n@Controller()\nexport class CarController extends HttpController {\n\n    @PUT('cars/:id')\n    updateCar(id: string, car: Car): Result {\n        ...\n    }\n}\n```\n\nIn the above example, **id** is the first parameter because it comes from the route. The last parameter (**car**) is the request body.\n\nThe **Result** that must be returned by an HttpAction needs an **HttpStatusCode**. The content is optional.  \nThe following types are the ones available by default :\n\n- **JsonResult** : Returns JSON response\n- **TextResult** : Returns TEXT response\n- **HtmlResult** : Returns HTML response\n- **XmlResult** : Returns XML response\n\n```ts\n@Controller()\nexport class CarController extends HttpController {\n\n    @GET('cars')\n    getCars(): Result {\n        const cars = ...\n        return new JsonResult(HttpStatusCode.OK, cars);\n    }\n}\n```\n\nYou can also extend the **Result** class to implement a custom return type:\n\n```ts\nexport class CustomResult extends Result {\n\n    sendWith(response: Response): void {\n        response.status(this.statusCode).send(...)\n    }\n}\n```\n\n### Http middleware\n\nMiddlewares are used to intercept requests before an **HttpAction** from a [**HttpController**](#http-controller) is called.  \nYou can add middlewares to a controller or a specific route to intercept requests.  \nWhen a request is intercepted, you have access to the actuals **express** request and response.\n\n#### Creating an http middleware\n\nYou can create a middleware by extending the **HttpMiddleware** class :\n\n```ts\nexport class Logger extends HttpMiddleware {\n\n    intercept(request: Request, response: Response): boolean {\n        console.log('I am interceptor');\n        return true;\n    }\n}\n```\n\n#### Applying a middleware to an http controller\n\nWhen you add a middleware on a controller, it will apply the middleware for all the routes of that controller :\n\n```ts\n@Middleware(Logger) // \u003c-- Added a middleware to all the routes\n@Controller()\nexport class PingController extends HttpController {\n    ...\n}\n```\n\n#### Applying a middleware to a specific route\n\nYou can also add it on specific routes :\n\n```ts\n@Controller()\nexport class PingController extends HttpController {\n\n    @GET('ping', [Logger]) // \u003c-- Added a middleware to this specific route\n    ping(): JsonResult {\n        ...\n    }\n}\n```\n\n#### Http middlewares order\n\nWhen you have multiple middlewares applied to a controller or route, they will always apply in order of appearance in the method signature :\n\n```ts\n@GET('ping', [Logger, Guard]) // \u003c-- Logger will be first, Guard will be second\nping(): JsonResult {\n    ...\n}\n```\n\nWhen you have middlewares on the controller and on a route, the middlewares from the controller will be applied first :\n\n```ts\n@Middleware(Logger) // \u003c-- Logger will be first\n@Controller()\nexport class PingController extends HttpController {\n\n    @GET('ping', [Guard]) // \u003c-- Guard will be second\n    ping(): JsonResult {\n        ...\n    }\n}\n```\n\n## Websocket Module\n\n### Websocket Controller\n\n#### Websocket actions\n\nThe following websocket actions are supported by the **WebsocketController** :\n\n- **OnConnect**\n- **OnDisconnect**\n- **OnMessage**\n\n```ts\n@WebsocketController()\nexport class ChatController extends WsController {\n\n    @OnConnect()\n    onConnect(websocket: Websocket, server: Server): WebsocketResponse { ... }\n\n    @OnDisconnect()\n    onDisconnect(websocket: Websocket, server: Server) : WebsocketResponse { ... }\n\n    @On('message')\n    onSendMessage(message: string, websocket: Websocket, server: Server) : WebsocketResponse { ... }\n}\n```\n\nThe parameters of a **WebsocketAction** decorated method must be in this given order :\n\n- **OnConnect** and **OnDisconnect** : The OnConnect and OnDisconnect have both access to the websocket instance and the server instance in that given order.\n\n```ts\n@OnConnect()\nonConnect(websocket: Websocket, server: Server): WebsocketResponse { ... }\n\n@OnDisconnect()\nonDisconnect(websocket: Websocket, server: Server) : WebsocketResponse { ... }\n```\n\n- **OnMessage** : The OnMessage method has as first parameter the body of the message. The OnMessage have also access to the websocket instance and the server instance in that given order as the last two (2) parameters of the signature.\n\n```ts\n@On('message')\nonSendMessage(message: string, websocket: Websocket, server: Server) : WebsocketResponse { ... }\n```\n\nThe **WebsocketResponse** that must be returned by WebsocketAction need a content.  \nYou can specify which clients to send the response to with the broadcast property or the receivers list.\nThe following types are the ones available by default :\n\n- **JsonWebsocketResponse** : Returns JSON response\n- **TextWebsocketResponse** : Returns TEXT response\n- **XmlWebsocketResponse** : Returns XML response\n\nFor example, a **JsonWebsocketResponse** return would look like this :\n\n```ts\n@OnConnect()\nonConnect(websocket: Websocket, server: Server): WebsocketResponse {\n    const sessionId = ...\n    return new JsonWebsocketResponse({sessionId, event: \"Has come online\"}, broadcast: true);\n}\n```\n\nThis would send a message to all the connected clients which says that someone has just come online :\n\n```json\n{\n    \"sessionId\" : \"...\",\n    \"event\" : \"Has come online\"\n}\n```\n\nYou can also extend the **WebsocketResponse** class to implement a custom return type:\n\n```ts\nexport class CustomWebsocketResponse extends WebsocketResponse {\n\n    sendWith(server: Server, websocket: Websocket) {\n        const content = ...\n        this.send(server, websocket, content);\n    }\n}\n```\n\n### Websocket middleware\n\nMiddlewares are used to intercept requests before an **WebsocketAction** from a [**WebsocketController**](#websocket-controller) is called.  \nYou can add middlewares to a controller or a specific action to intercept requests.\n\n#### Creating a websocket middleware\n\nYou can create a middleware by extending the **WebsocketMiddleware** class :\n\n```ts\nexport class Logger extends HttpMiddleware {\n\n    intercept(request: Request, response: Response): boolean {\n        console.log('I am interceptor');\n        return true;\n    }\n}\n```\n\n#### Applying a middleware to a websocket controller\n\nWhen you add a middleware on a controller, it will apply the middleware for all the actions of that controller :\n\n```ts\n@Middleware(Logger) // \u003c-- Added a middleware to all the routes\n@WebsocketController()\nexport class ChatController extends WsController {\n    ...\n}\n```\n\n#### Applying a middleware to a specific action\n\nYou can also add it on specific action :\n\n```ts\n@WebsocketController()\nexport class ChatController extends WsController {\n\n    @OnConnect([Logger]) // \u003c-- Added a middleware to this specific action\n    onConnect(websocket: Websocket, server: Server): WebsocketResponse {\n        ...\n    }\n}\n```\n\n#### Websocket middlewares order\n\nLook at the [Http middlewares order](#http-middlewares-order) section for how the middlewares order works.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbinet%2Fvolcano","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcbinet%2Fvolcano","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbinet%2Fvolcano/lists"}