{"id":24087124,"url":"https://github.com/hapipal/ahem","last_synced_at":"2025-05-05T17:58:21.516Z","repository":{"id":57115151,"uuid":"222465516","full_name":"hapipal/ahem","owner":"hapipal","description":"hapi plugins as libraries","archived":false,"fork":false,"pushed_at":"2023-02-27T05:44:04.000Z","size":56,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-10T13:18:03.909Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/hapipal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-11-18T14:15:09.000Z","updated_at":"2023-01-14T14:25:44.000Z","dependencies_parsed_at":"2023-01-22T01:48:33.376Z","dependency_job_id":null,"html_url":"https://github.com/hapipal/ahem","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapipal%2Fahem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapipal%2Fahem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapipal%2Fahem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapipal%2Fahem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hapipal","download_url":"https://codeload.github.com/hapipal/ahem/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252548016,"owners_count":21766097,"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":[],"created_at":"2025-01-10T03:02:18.743Z","updated_at":"2025-05-05T17:58:21.497Z","avatar_url":"https://github.com/hapipal.png","language":"JavaScript","readme":"# ahem\nhapi plugins as libraries\n\n[![Build Status](https://app.travis-ci.com/hapipal/ahem.svg?branch=main)](https://app.travis-ci.com/hapipal/ahem) [![Coverage Status](https://coveralls.io/repos/hapipal/ahem/badge.svg?branch=main\u0026service=github)](https://coveralls.io/github/hapipal/ahem?branch=main)\n\nLead Maintainer - [Devin Ivy](https://github.com/devinivy)\n\n## Installation\n```sh\nnpm install @hapipal/ahem\n```\n\n## Usage\n\u003e See also the [API Reference](API.md)\n\u003e\n\u003e Ahem is intended for use with hapi v20+ and nodejs v16+ (_see v2 for lower support_).  Ensure you've installed @hapi/hapi within your project.\n\nAhem's purpose is to encourage new possibilites for hapi plugin composition and portability.  It's a small tool that offers only subtly different functionality from [glue](https://github.com/hapijs/glue); but unlike glue, ahem's API is designed to strongly reinforce the perspective of hapi plugins as being instantiable general-purpose libraries, and not just web servers.\n\nAhem has applications in building non-server projects using hapi, creating servers with multiple connections, safely sharing functionality across plugins, and testing hapi plugins (particularly complex application plugins that use [schwifty](https://github.com/hapipal/schwifty) models or [schmervice](https://github.com/hapipal/schmervice) services).  Finally, ahem is compatible with schmervice, and plugins can be used as services under schmervice.  We think the collection of examples below should help to illustrate.\n\n### Examples\n\n#### Treat vision as a library\n\nThe most basic usage of ahem is to instance a plugin with some plugin options.  Here we treat vision as an adapter-based templating library rather than as a hapi plugin.\n\n```js\n// npm install @hapipal/ahem @hapi/hapi @hapi/vision handlebars\nconst Vision = require('@hapi/vision');\nconst Handlebars = require('handlebars');\nconst Ahem = require('@hapipal/ahem');\n\n// Before continuing, create a template:\n// mkdir templates \u0026\u0026 echo 'Hello, {{name}}!' \u003e templates/hello.hbs\n\n(async () =\u003e {\n\n    const vision = await Ahem.instance(Vision, {\n        engines: { hbs: Handlebars },\n        relativeTo: __dirname,\n        path: 'templates'\n    });\n\n    const message = await vision.render('hello', { name: 'Clarice' });\n\n    console.log(message); // Hello, Clarice!\n})();\n```\n\n#### Instantiate your application with its dependencies\n\nIf your application has external plugin dependencies then you can specify those using the `register` option.\n\n```js\n// npm install @hapipal/ahem @hapi/hapi @hapipal/schwifty knex sqlite3\nconst Schwifty = require('@hapipal/schwifty');\nconst Ahem = require('@hapipal/ahem');\nconst App = require('./app');\n\n// Below assumes your application plugin\n// uses schwifty and has an objection Users model.\n\n(async () =\u003e {\n\n    const app = await Ahem.instance(App, {}, {\n        register: [\n            {\n                plugin: Schwifty,\n                options: {\n                    knex: {\n                        client: 'sqlite3',\n                        useNullAsDefault: true,\n                        connection: {\n                            filename: ':memory:'\n                        }\n                    }\n                }\n            }\n        ]\n    });\n\n    const { Users } = app.model();\n\n    const paldo = await Users.query().insertAndFetch({ name: 'paldo' });\n\n    console.log(paldo);\n})();\n```\n\n#### Instantiate your application, controlled by a server\n\nYou might want to use one of your application plugins within a separate hapi project or deployment.  In this case you usually want the instance of your application to be \"tied\" to the lifecycle of the primary hapi server of that project: when you initialize/start/stop the primary server you would like your application instance to do the same.  In hapi jargon you want your application to be \"controlled\" by that server (see [`server.control()`](https://hapi.dev/api#-servercontrolserver) for more info).  Ahem can take care of this for you, if you simply provide the primary server as an argument.\n\n```js\n// npm install @hapipal/ahem @hapi/hapi\nconst Hapi = require('@hapi/hapi');\nconst Ahem = require('@hapipal/ahem');\nconst App = require('./app');\n\n(async () =\u003e {\n\n    const server = Hapi.server();\n\n    const app = await Ahem.instance(server, App);\n\n    // app is not yet initialized\n\n    await server.initialize();\n\n    // app is now initialized too\n\n    await server.stop();\n\n    // app is now stopped too\n})();\n```\n\n##### Using ahem as a plugin for controlled usage\n\nAhem can also be used as a plugin, e.g. for repeated \"controlled\" usage by the same server.  This style emphasizes the relationship between hapi's plugin registration with `server.register()` versus ahem's plugin instancing: the former has a major effect on `server` and the latter does not.  An equivalent way to write the above example using ahem as a plugin would look like this.\n\n```js\n// npm install @hapipal/ahem @hapi/hapi\nconst Hapi = require('@hapi/hapi');\nconst Ahem = require('@hapipal/ahem');\nconst App = require('./app');\n\n(async () =\u003e {\n\n    const server = Hapi.server();\n\n    await server.register(Ahem);\n\n    const app = await server.instance(App);\n\n    // app is not yet initialized\n\n    await server.initialize();\n\n    // app is now initialized too\n\n    await server.stop();\n\n    // app is now stopped too\n})();\n```\n\n#### Treat vision as a service\n\nSchmervice recognizes hapi plugin instances as valid services, which means that you can register an instance created by ahem with schmervice without any friction.  Schmervice will use the name of the plugin (i.e. it's `name` attribute) as the service's name by default.  You can specify a different name using [`Schmervice.withName()`](https://github.com/hapipal/schmervice/blob/master/API.md#schmervicewithnamename-options-servicefactory) if desired.\n\n```js\n// npm install @hapipal/ahem schmervice @hapi/hapi @hapi/vision handlebars\nconst Hapi = require('@hapi/hapi');\nconst Vision = require('@hapi/vision');\nconst Handlebars = require('handlebars');\nconst Schmervice = require('@hapipal/schmervice');\nconst Ahem = require('@hapipal/ahem');\n\n// Before continuing, create a template:\n// mkdir templates \u0026\u0026 echo 'Hello, {{name}}!' \u003e templates/hello.hbs\n\n(async () =\u003e {\n\n    const server = Hapi.server();\n\n    await server.register(Schmervice);\n\n    const vision = await Ahem.instance(Vision, {\n        engines: { hbs: Handlebars },\n        relativeTo: __dirname,\n        path: 'templates'\n    })\n\n    server.registerService(vision);\n\n    const { vision: templatingService } = server.services();\n\n    const message = await templatingService.render('hello', { name: 'Clarice' });\n\n    console.log(message); // Hello, Clarice!\n})();\n```\n\n#### Deploy a server with many connections\n\nIn hapi v17 hapi [dropped support](https://github.com/hapijs/hapi/issues/3572) for multiple connections.  Ahem offers a convenient way to reintroduce multiple connections to your project.  Below we demonstrate the use-case of redirecting HTTP to HTTPS in a single process using the `server` option to specify a port.  Note that this is another example of \"controlled\" usage similar to [this example](#instantiate-your-application-controlled-by-a-server) above.\n\n```js\n// npm install @hapipal/ahem @hapi/hapi hapi-require-https\nconst Fs = require('fs');\nconst Hapi = require('@hapi/hapi');\nconst Ahem = require('@hapipal/ahem');\nconst RequireHttps = require('hapi-require-https');\nconst App = require('./app');\n\n// Note, the example below utilizes ports 80 and 443 which\n// typically require special privileges. It's more common\n// to deploy node behind a reverse proxy in production.\n\n(async () =\u003e {\n\n    const server = Hapi.server({\n        port: 443,\n        tls: {\n            key: Fs.readFileSync('key.pem'),\n            cert: Fs.readFileSync('cert.pem')\n        }\n    });\n\n    await server.register(App);\n\n    await Ahem.instance(server, RequireHttps, {\n        proxy: false    // See https://github.com/bendrucker/hapi-require-https#proxy\n    }, {\n        server: {\n            port: 80\n        }\n    });\n\n    await server.start();\n\n    console.log(`Server started at ${server.info.uri}`);\n})();\n```\n\n#### Instance vision as a factory\n\nAhem offers an additional style for wrapping hapi plugins into a library: you can turn a plugin into a factory for an instance using [`Ahem.toFactory(plugin)`](API.md#ahemtofactoryplugin).\n\n```js\n// npm install @hapipal/ahem @hapi/hapi @hapi/vision handlebars\nconst Vision = require('@hapi/vision');\nconst Handlebars = require('handlebars');\nconst Ahem = require('@hapipal/ahem');\n\n// Before continuing, create a template:\n// mkdir templates \u0026\u0026 echo 'Hello, {{name}}!' \u003e templates/hello.hbs\n\n(async () =\u003e {\n\n    const createVision = Ahem.toFactory(Vision);\n\n    const vision = await createVision({\n        engines: { hbs: Handlebars },\n        relativeTo: __dirname,\n        path: 'templates'\n    });\n\n    const message = await vision.render('hello', { name: 'Clarice' });\n\n    console.log(message); // Hello, Clarice!\n})();\n```\n\n#### Advanced usage\n\nAhem has a handful of other options that can be used too.  Check out the [API Reference](API.md) for more info.\n\n```js\n// npm install @hapipal/ahem @hapi/hapi @hapi/vision handlebars\nconst Vision = require('@hapi/vision');\nconst Handlebars = require('handlebars');\nconst Ahem = require('@hapipal/ahem');\n\n// Before continuing, create a template:\n// mkdir templates \u0026\u0026 echo 'Hello, {{name}}!' \u003e templates/hello.hbs\n\n(async () =\u003e {\n\n    const server = Hapi.server();\n\n    await Ahem.instance(server, Vision, {\n        engines: { hbs: Handlebars },\n        relativeTo: __dirname,\n        path: 'templates'\n    }, {\n        controlled: false,\n        initialize: true,\n        decorateRoot: false,\n        decorateControlled: false\n    });\n\n    const message = await server.render('hello', { name: 'Clarice' });\n\n    console.log(message); // Hello, Clarice!\n})();\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhapipal%2Fahem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhapipal%2Fahem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhapipal%2Fahem/lists"}