{"id":15582959,"url":"https://github.com/nfroidure/whook","last_synced_at":"2025-04-07T15:05:47.593Z","repository":{"id":29936189,"uuid":"33482446","full_name":"nfroidure/whook","owner":"nfroidure","description":"Build strong and efficient REST web services.","archived":false,"fork":false,"pushed_at":"2025-03-18T08:14:43.000Z","size":11228,"stargazers_count":32,"open_issues_count":22,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-31T14:12:10.475Z","etag":null,"topics":["dependency-injection","hacktoberfest","openapi","openapi3","rest-api","router","server"],"latest_commit_sha":null,"homepage":"https://slides.com/nfroidure/introducing-whook","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nfroidure.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["nfroidure"]}},"created_at":"2015-04-06T13:09:13.000Z","updated_at":"2025-03-18T08:14:13.000Z","dependencies_parsed_at":"2023-02-18T03:15:30.429Z","dependency_job_id":"e234d689-6b33-4403-a672-cdb4da01e079","html_url":"https://github.com/nfroidure/whook","commit_stats":{"total_commits":462,"total_committers":8,"mean_commits":57.75,"dds":"0.11471861471861466","last_synced_commit":"652fda413f804d13d93e1f2989c30a520d069b12"},"previous_names":[],"tags_count":135,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfroidure%2Fwhook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfroidure%2Fwhook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfroidure%2Fwhook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nfroidure%2Fwhook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nfroidure","download_url":"https://codeload.github.com/nfroidure/whook/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247675597,"owners_count":20977376,"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":["dependency-injection","hacktoberfest","openapi","openapi3","rest-api","router","server"],"created_at":"2024-10-02T20:03:04.775Z","updated_at":"2025-04-07T15:05:47.562Z","avatar_url":"https://github.com/nfroidure.png","language":"TypeScript","funding_links":["https://github.com/sponsors/nfroidure"],"categories":[],"sub_categories":[],"readme":"[//]: # ( )\n[//]: # (This file is automatically generated by a `metapak`)\n[//]: # (module. Do not change it  except between the)\n[//]: # (`content:start/end` flags, your changes would)\n[//]: # (be overridden.)\n[//]: # ( )\n# whook\n\u003e Build strong and efficient REST web services.\n\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/nfroidure/whook/blob/main/LICENSE)\n\n\n[//]: # (::contents:start)\n\nWhy write code when you have an OpenAPI 3.1 definition?\n\n![The Whook's logo](./whook.svg)\n\n## Summary\n\nWhook eats your documentation and provides you with a performant router that\ntakes care of running the right code for the right operation.\n\nBy using the [OpenAPI](https://www.openapis.org/) standard and the dependency\ninjection pattern, Whook provides a convenient, highly modular and easily\ntestable back end framework.\n\n## Quickstart\n\nTo start a new Whook project:\n\n```sh\n# Initialize the project\nnpm init @whook;\ncd my_project_name;\n\n# Check install with a dry run of the server\nnpm run dev -- __inject httpServer,process,dryRun\n\n# Run tests\nnpm t\n\n# Start developing\nnpm run watch\n\n# Build the project\nnpm run build\n\n# Start the compiled project\nnpm start\n\n# Start the built project\nnode builds/local/server/start.js\n\n# Create a new handler/service/provider\nnpm run whook -- create\n```\n\n## Why use Whook?\n\n- robust: types, functional programming\n- highly modular, extendable and reusable\n- fully integrated and production ready\n- can be deployed anywhere (serverless, docker, microservices): enter the\n  anylith era\n- easy to test: TDD, E2E tests made easy\n- feature complete for most API use cases\n- ease your work but embrace projects complexity\n\n## Usage\n\nA tutorial is still to be written, expect it to come very soon. The above\n[quickstart command](#quickstart) is a good starting point.\n\nThat said you can check the following \"How to\" PRs:\n\n- [add GraphQL](https://github.com/nfroidure/whook/pull/62)\n- [deploy with Docker](https://github.com/nfroidure/whook/pull/164)\n- [deploy on AWS Lambda](https://github.com/nfroidure/whook/pull/54)\n- [deploy with GCP Cloud Functions](https://github.com/nfroidure/whook/pull/66)\n\nAlso, the [`packages/` folder](./packages) contains a lot of easy to setup\nmodules with well detailed readmes and setup instructions.\n\nFinally, search for Whook's package easily with the\n[NPM's Whook tag](https://www.npmjs.com/search?q=keywords:whook). Also the\n[Knifecycle tag](https://www.npmjs.com/search?q=keywords:knifecycle) can be\nuseful to find projects using the same dependency injection library.\n\nIf you have any question or issue using Whook, post your help request to stack\noverflow with the\n[Whook tag](https://stackoverflow.com/questions/ask?tags=whook). Questions with\nthis tag will be regularly checked by Whook's authors.\n\nFinally, if you encounter any bug (unexpected error, feature requests, OpenAPI\nspecification violation), please fill an issue!\n\n## Principles\n\n[Check this deck](https://slides.com/nfroidure/introducing-whook) for a complete\nintroduction to Whook's principles!\n\n### Global overview\n\nThis projects aims to make creating well documented and highly customizable REST\nAPIs a breeze. It is based on years of experience\n[building REST APIs with NodeJS](https://insertafter.com/en/blog/http_rest_apis_with_nodejs.html).\n\nBy relying on the [OpenAPI schemas](https://www.openapis.org/) to declare a new\nendpoint, this project forces documentation before code. It also is highly\ncustomizable since based on the dependency injection with inversion of control\npattern allowing you to override or wrap its main constituents.\n\n![Architecture Overview](./overview.svg)\n\nThe Whook route handling flow is very simple.\n\nFirst, we have a HTTPServer that handles requests and serves responses (the\n`httpServer` service).\n\nThen, the `httpTransaction` transform the NodeJS requests into raw serializable\nones (raw objects with no methods nor internal states, useful for testing).\n\nThen the router (`httpRouter`) deal with that request to test which handler\nneeds to be run by comparing the method/path couple with the OpenAPI operations\ndeclarations.\n\nOnce found, it simply runs the right route handler with the OpenAPI parameters\nvalue filled from the serializable request. The handler simply have to return a\nserializable response object in turn.\n\nIf any error occurs within this process, than the `errorHandler` is responsible\nfor providing the now lacking response object based on the error it catches.\n\nAnd that's it, you have your REST API. We have\n[no middleware](http://insertafter.com/en/blog/no_more_middlewares.html) concept\nhere. Instead, every handler is a simple function taking parameters and\nreturning a response. It makes those functions very easily composable (in a\nfunctional programming sense).\n\nYou may add global wrappers to change every routes input/output on the fly or\nadd a local wrapper specifically to one or a few routes.\n\n### Core concepts\n\nWhook work by adding ingredients to you API:\n\n- **configuration**: Whook look ups for `config/{NODE_ENV}/config.js` files. It\n  creates constants you can inject in your routes and services.\n- **API**: It defines the various endpoint of your API and how to map these to\n  routes thanks to the well known OpenAPI format (formerly Swagger),\n- **routes**: to define an implement API endpoints,\n- **crons**: to define and implement periodic tasks,\n- **consumers**: to implement queues/streams consumers,\n- **services**: various services that deal with side effects,\n- **wrappers**: higher order functions you can apply to routes, crons or\n  consumers (CORS, authentication...).\n\nYou can see a lot of those concepts implemented in the\n[Whook example](./packages/whook-example) folder.\n\nWhook's DI system relies on the\n[Knifecyle](https://github.com/nfroidure/knifecycle) module. It is great for\nadding or easily override/wrap a lot of its core component and brings\ninstrumentation and testability to your code bases.\n\n## Contributing\n\nContributors are very welcome to help pushing Whook forward!\n\nClone this project's repository and run:\n\n```sh\nnpm i\nnpm run build\nnpm run metapak\nnpm t\n```\n\nThe repository is based on LernaJS that allows to host several NPM packages in a\nsingle repository. That said, to keep it simple it only proxies the packages\ncommands.\n\nInstall those\n[VSCode extensions](https://insertafter.com/en/blog/my_vscode_configuration.html)\nto get a smooth developer experience.\n\nFor committing run:\n\n```sh\nnpm run cz\n```\n\n## Publishing\n\n```sh\nNODE_ENV=cli npm run lerna  -- publish\n```\n\n[//]: # (::contents:end)\n\n# Authors\n- [Nicolas Froidure](http://insertafter.com/en/index.html)\n- [Vincent Da Silva](https://dasilvavincent.github.io/PortFolio/)\n- [Ayoub HAD-DAD](https://github.com/AubHaddad)\n\n# License\n[MIT](https://github.com/nfroidure/whook/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnfroidure%2Fwhook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnfroidure%2Fwhook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnfroidure%2Fwhook/lists"}