├── .gitattributes ├── .github ├── dependabot.yml └── workflows │ └── ci.yml ├── .gitignore ├── LICENSE ├── README.md ├── es-docker.sh ├── eslint.config.js ├── index.js ├── lib └── isElasticsearchClient.js ├── package.json ├── test └── index.test.js └── types ├── index.d.ts └── index.test-d.ts /.gitattributes: -------------------------------------------------------------------------------- 1 | # Set default behavior to automatically convert line endings 2 | * text=auto eol=lf 3 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "github-actions" 4 | directory: "/" 5 | schedule: 6 | interval: "monthly" 7 | open-pull-requests-limit: 10 8 | 9 | - package-ecosystem: "npm" 10 | directory: "/" 11 | schedule: 12 | interval: "monthly" 13 | open-pull-requests-limit: 10 14 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | - next 8 | - 'v*' 9 | paths-ignore: 10 | - 'docs/**' 11 | - '*.md' 12 | pull_request: 13 | paths-ignore: 14 | - 'docs/**' 15 | - '*.md' 16 | 17 | permissions: 18 | contents: read 19 | 20 | jobs: 21 | test: 22 | permissions: 23 | contents: write 24 | pull-requests: write 25 | uses: fastify/workflows/.github/workflows/plugins-ci-elasticsearch.yml@v5 26 | with: 27 | lint: true 28 | license-check: true 29 | elasticsearch-version: 8.15.2 30 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | lerna-debug.log* 8 | .pnpm-debug.log* 9 | 10 | # Diagnostic reports (https://nodejs.org/api/report.html) 11 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 12 | 13 | # Runtime data 14 | pids 15 | *.pid 16 | *.seed 17 | *.pid.lock 18 | 19 | # Directory for instrumented libs generated by jscoverage/JSCover 20 | lib-cov 21 | 22 | # Coverage directory used by tools like istanbul 23 | coverage 24 | *.lcov 25 | 26 | # nyc test coverage 27 | .nyc_output 28 | 29 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 30 | .grunt 31 | 32 | # Bower dependency directory (https://bower.io/) 33 | bower_components 34 | 35 | # node-waf configuration 36 | .lock-wscript 37 | 38 | # Compiled binary addons (https://nodejs.org/api/addons.html) 39 | build/Release 40 | 41 | # Dependency directories 42 | node_modules/ 43 | jspm_packages/ 44 | 45 | # Snowpack dependency directory (https://snowpack.dev/) 46 | web_modules/ 47 | 48 | # TypeScript cache 49 | *.tsbuildinfo 50 | 51 | # Optional npm cache directory 52 | .npm 53 | 54 | # Optional eslint cache 55 | .eslintcache 56 | 57 | # Optional stylelint cache 58 | .stylelintcache 59 | 60 | # Microbundle cache 61 | .rpt2_cache/ 62 | .rts2_cache_cjs/ 63 | .rts2_cache_es/ 64 | .rts2_cache_umd/ 65 | 66 | # Optional REPL history 67 | .node_repl_history 68 | 69 | # Output of 'npm pack' 70 | *.tgz 71 | 72 | # Yarn Integrity file 73 | .yarn-integrity 74 | 75 | # dotenv environment variable files 76 | .env 77 | .env.development.local 78 | .env.test.local 79 | .env.production.local 80 | .env.local 81 | 82 | # parcel-bundler cache (https://parceljs.org/) 83 | .cache 84 | .parcel-cache 85 | 86 | # Next.js build output 87 | .next 88 | out 89 | 90 | # Nuxt.js build / generate output 91 | .nuxt 92 | dist 93 | 94 | # Gatsby files 95 | .cache/ 96 | # Comment in the public line in if your project uses Gatsby and not Next.js 97 | # https://nextjs.org/blog/next-9-1#public-directory-support 98 | # public 99 | 100 | # vuepress build output 101 | .vuepress/dist 102 | 103 | # vuepress v2.x temp and cache directory 104 | .temp 105 | .cache 106 | 107 | # Docusaurus cache and generated files 108 | .docusaurus 109 | 110 | # Serverless directories 111 | .serverless/ 112 | 113 | # FuseBox cache 114 | .fusebox/ 115 | 116 | # DynamoDB Local files 117 | .dynamodb/ 118 | 119 | # TernJS port file 120 | .tern-port 121 | 122 | # Stores VSCode versions used for testing VSCode extensions 123 | .vscode-test 124 | 125 | # yarn v2 126 | .yarn/cache 127 | .yarn/unplugged 128 | .yarn/build-state.yml 129 | .yarn/install-state.gz 130 | .pnp.* 131 | 132 | # Vim swap files 133 | *.swp 134 | 135 | # macOS files 136 | .DS_Store 137 | 138 | # Clinic 139 | .clinic 140 | 141 | # lock files 142 | bun.lockb 143 | package-lock.json 144 | pnpm-lock.yaml 145 | yarn.lock 146 | 147 | # editor files 148 | .vscode 149 | .idea 150 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018-2019 Fastify 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # @fastify/elasticsearch 2 | 3 | [![CI](https://github.com/fastify/fastify-elasticsearch/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/fastify-elasticsearch/actions/workflows/ci.yml) 4 | [![NPM version](https://img.shields.io/npm/v/@fastify/elasticsearch.svg?style=flat)](https://www.npmjs.com/package/@fastify/elasticsearch) 5 | [![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard) 6 | 7 | Fastify plugin for [Elasticsearch](https://www.elastic.co/elasticsearch/) for sharing the same ES client in every part of your server. 8 | Under the hood, the official [elasticsearch](https://www.npmjs.com/package/@elastic/elasticsearch) module is used. 9 | 10 | 11 | ## Install 12 | 13 | ``` 14 | npm i @fastify/elasticsearch 15 | ``` 16 | 17 | ### Compatibility 18 | | Plugin version | Fastify version | 19 | | ---------------|-----------------| 20 | | `>=4.x` | `^5.x` | 21 | | `^3.x` | `^4.x` | 22 | | `^2.x` | `^3.x` | 23 | | `^1.x` | `^2.x` | 24 | | `^1.x` | `^1.x` | 25 | 26 | 27 | Please note that if a Fastify version is out of support, then so are the corresponding versions of this plugin 28 | in the table above. 29 | See [Fastify's LTS policy](https://github.com/fastify/fastify/blob/main/docs/Reference/LTS.md) for more details. 30 | 31 | ## Usage 32 | Add it to your project with `register` and you are done! 33 | The plugin accepts the [same options](https://github.com/elastic/elasticsearch-js#client-options) as the client. 34 | 35 | ```js 36 | const fastify = require('fastify')() 37 | 38 | fastify.register(require('@fastify/elasticsearch'), { node: 'http://localhost:9200' }) 39 | 40 | fastify.get('/user', async function (req, reply) { 41 | const { body } = await this.elastic.search({ 42 | index: 'tweets', 43 | body: { 44 | query: { match: { text: req.query.q }} 45 | } 46 | }) 47 | 48 | return body.hits.hits 49 | }) 50 | 51 | fastify.listen({ port: 3000 }, err => { 52 | if (err) throw err 53 | }) 54 | ``` 55 | 56 | By default, `@fastify/elasticsearch` will try to ping the cluster as soon as you start Fastify, but in some cases pinging may not be supported due to the user permissions. If you want, you can disable the initial ping with the `healthcheck` option: 57 | ```js 58 | fastify.register(require('@fastify/elasticsearch'), { 59 | node: 'http://localhost:9200', 60 | healthcheck: false 61 | }) 62 | ``` 63 | 64 | If you need to connect to different clusters, you can also pass a `namespace` option: 65 | ```js 66 | const fastify = require('fastify')() 67 | 68 | fastify.register(require('@fastify/elasticsearch'), { 69 | node: 'http://localhost:9200', 70 | namespace: 'cluster1' 71 | }) 72 | 73 | fastify.register(require('@fastify/elasticsearch'), { 74 | node: 'http://localhost:9201', 75 | namespace: 'cluster2' 76 | }) 77 | 78 | fastify.get('/user', async function (req, reply) { 79 | const { body } = await this.elastic.cluster1.search({ 80 | index: 'tweets', 81 | body: { 82 | query: { match: { text: req.query.q }} 83 | } 84 | }) 85 | 86 | return body.hits.hits 87 | }) 88 | 89 | fastify.listen({ port: 3000 }, err => { 90 | if (err) throw err 91 | }) 92 | ``` 93 | 94 | ## Versioning 95 | By default the latest and greatest version of the Elasticsearch client is used, see the [compatibility](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/introduction.html#_compatibility) table to understand if the embedded client is correct for you. 96 | If it is not, you can pass a custom client via the `client` option. 97 | ```js 98 | const fastify = require('fastify')() 99 | const { Client } = require('@elastic/elasticsearch') 100 | 101 | fastify.register(require('@fastify/elasticsearch'), { 102 | client: new Client({ node: 'http://localhost:9200' }) 103 | }) 104 | 105 | fastify.get('/user', async function (req, reply) { 106 | const { body } = await this.elastic.search({ 107 | index: 'tweets', 108 | body: { 109 | query: { match: { text: req.query.q }} 110 | } 111 | }) 112 | 113 | return body.hits.hits 114 | }) 115 | 116 | fastify.listen({ port: 3000 }, err => { 117 | if (err) throw err 118 | }) 119 | ``` 120 | 121 | ## License 122 | 123 | Licensed under [MIT](./LICENSE). 124 | -------------------------------------------------------------------------------- /es-docker.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # run this file to get a working ES instance 4 | # for running the test locally 5 | 6 | exec docker run \ 7 | --rm \ 8 | -e "discovery.type=single-node" \ 9 | -e "xpack.security.enabled=false" \ 10 | -p 9200:9200 \ 11 | docker.elastic.co/elasticsearch/elasticsearch:8.15.2 12 | -------------------------------------------------------------------------------- /eslint.config.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | module.exports = require('neostandard')({ 4 | ignores: require('neostandard').resolveIgnoresFromGitignore(), 5 | ts: true 6 | }) 7 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const fp = require('fastify-plugin') 4 | const { Client } = require('@elastic/elasticsearch') 5 | const isElasticsearchClient = require('./lib/isElasticsearchClient') 6 | 7 | async function fastifyElasticsearch (fastify, options) { 8 | const { namespace, healthcheck } = options 9 | delete options.namespace 10 | delete options.healthcheck 11 | 12 | const client = options.client || new Client(options) 13 | 14 | if (healthcheck !== false) { 15 | await client.ping() 16 | } 17 | 18 | if (namespace) { 19 | if (!fastify.elastic) { 20 | fastify.decorate('elastic', {}) 21 | } 22 | 23 | if (fastify.elastic[namespace]) { 24 | throw new Error(`Elasticsearch namespace already used: ${namespace}`) 25 | } 26 | 27 | fastify.elastic[namespace] = client 28 | 29 | fastify.addHook('onClose', async (instance) => { 30 | // v8 client.close returns a promise and does not accept a callback 31 | await instance.elastic[namespace].close() 32 | }) 33 | } else { 34 | fastify 35 | .decorate('elastic', client) 36 | .addHook('onClose', async (instance) => { 37 | await instance.elastic.close() 38 | }) 39 | } 40 | } 41 | 42 | module.exports = fp(fastifyElasticsearch, { 43 | fastify: '5.x', 44 | name: '@fastify/elasticsearch' 45 | }) 46 | module.exports.default = fastifyElasticsearch 47 | module.exports.fastifyElasticsearch = fastifyElasticsearch 48 | 49 | module.exports.isElasticsearchClient = isElasticsearchClient 50 | -------------------------------------------------------------------------------- /lib/isElasticsearchClient.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const { Client } = require('@elastic/elasticsearch') 4 | 5 | module.exports = function isElasticsearchClient (value) { 6 | return value instanceof Client 7 | } 8 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@fastify/elasticsearch", 3 | "version": "4.0.2", 4 | "description": "Fastify plugin for elastic search", 5 | "main": "index.js", 6 | "type": "commonjs", 7 | "types": "types/index.d.ts", 8 | "scripts": { 9 | "lint": "eslint", 10 | "lint:fix": "eslint --fix", 11 | "test": "npm run test:unit && npm run test:typescript", 12 | "test:unit": "c8 --100 node --test", 13 | "test:typescript": "tsd" 14 | }, 15 | "repository": { 16 | "type": "git", 17 | "url": "git+https://github.com/fastify/fastify-elasticsearch.git" 18 | }, 19 | "keywords": [ 20 | "fastify", 21 | "elastic", 22 | "elasticsearch", 23 | "elastic search", 24 | "ES" 25 | ], 26 | "author": "Tommaso Allevi - @allevo", 27 | "contributors": [ 28 | { 29 | "name": "Matteo Collina", 30 | "email": "hello@matteocollina.com" 31 | }, 32 | { 33 | "name": "James Sumners", 34 | "url": "https://james.sumners.info" 35 | }, 36 | { 37 | "name": "Tomas Della Vedova", 38 | "url": "http://delved.org" 39 | }, 40 | { 41 | "name": "Frazer Smith", 42 | "email": "frazer.dev@icloud.com", 43 | "url": "https://github.com/fdawgs" 44 | } 45 | ], 46 | "license": "MIT", 47 | "bugs": { 48 | "url": "https://github.com/fastify/fastify-elasticsearch/issues" 49 | }, 50 | "homepage": "https://github.com/fastify/fastify-elasticsearch#readme", 51 | "funding": [ 52 | { 53 | "type": "github", 54 | "url": "https://github.com/sponsors/fastify" 55 | }, 56 | { 57 | "type": "opencollective", 58 | "url": "https://opencollective.com/fastify" 59 | } 60 | ], 61 | "dependencies": { 62 | "@elastic/elasticsearch": "^9.0.2", 63 | "fastify-plugin": "^5.0.0" 64 | }, 65 | "devDependencies": { 66 | "@fastify/pre-commit": "^2.1.0", 67 | "@types/node": "^22.0.0", 68 | "c8": "^10.1.2", 69 | "eslint": "^9.17.0", 70 | "fastify": "^5.0.0", 71 | "neostandard": "^0.12.0", 72 | "tsd": "^0.32.0" 73 | }, 74 | "publishConfig": { 75 | "access": "public" 76 | } 77 | } 78 | -------------------------------------------------------------------------------- /test/index.test.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | const { test } = require('node:test') 4 | const { Client } = require('@elastic/elasticsearch') 5 | const Fastify = require('fastify') 6 | const fastifyElasticsearch = require('..') 7 | const isElasticsearchClient = require('..').isElasticsearchClient 8 | 9 | test('with reachable cluster', async t => { 10 | const fastify = Fastify() 11 | t.after(() => fastify.close()) 12 | fastify.register(fastifyElasticsearch, { node: 'http://localhost:9200' }) 13 | 14 | await fastify.ready() 15 | t.assert.equal(fastify.elastic.name, 'elasticsearch-js') 16 | }) 17 | 18 | test('with unreachable cluster', async t => { 19 | const fastify = Fastify() 20 | t.after(() => fastify.close()) 21 | fastify.register(fastifyElasticsearch, { node: 'http://localhost:9201' }) 22 | 23 | try { 24 | await fastify.ready() 25 | t.assert.fail('should not boot successfully') 26 | } catch (err) { 27 | t.assert.ok(err) 28 | } 29 | }) 30 | 31 | test('with unreachable cluster and healthcheck disabled', async t => { 32 | const fastify = Fastify() 33 | t.after(() => fastify.close()) 34 | fastify.register(fastifyElasticsearch, { 35 | node: 'http://localhost:9201', 36 | healthcheck: false 37 | }) 38 | 39 | try { 40 | await fastify.ready() 41 | t.assert.equal(fastify.elastic.name, 'elasticsearch-js') 42 | } catch { 43 | t.assert.fail('should not error') 44 | } 45 | }) 46 | 47 | test('namespaced', async t => { 48 | const fastify = Fastify() 49 | t.after(() => fastify.close()) 50 | fastify.register(fastifyElasticsearch, { 51 | node: 'http://localhost:9200', 52 | namespace: 'cluster' 53 | }) 54 | 55 | await fastify.ready() 56 | t.assert.equal(fastify.elastic.cluster.name, 'elasticsearch-js') 57 | t.assert.equal(isElasticsearchClient(fastify.elastic), false) 58 | t.assert.equal(isElasticsearchClient(fastify.elastic.cluster), true) 59 | await fastify.close() 60 | }) 61 | 62 | test('namespaced (errored)', async t => { 63 | const fastify = Fastify() 64 | t.after(() => fastify.close()) 65 | fastify.register(fastifyElasticsearch, { 66 | node: 'http://localhost:9200', 67 | namespace: 'cluster' 68 | }) 69 | 70 | fastify.register(fastifyElasticsearch, { 71 | node: 'http://localhost:9200', 72 | namespace: 'cluster' 73 | }) 74 | 75 | try { 76 | await fastify.ready() 77 | t.assert.fail('should not boot successfully') 78 | } catch (err) { 79 | t.assert.ok(err) 80 | } 81 | }) 82 | 83 | test('custom client', async t => { 84 | const client = new Client({ 85 | node: 'http://localhost:9200', 86 | name: 'custom' 87 | }) 88 | 89 | const fastify = Fastify() 90 | t.after(() => fastify.close()) 91 | fastify.register(fastifyElasticsearch, { client }) 92 | 93 | await fastify.ready() 94 | t.assert.equal(isElasticsearchClient(fastify.elastic), true) 95 | t.assert.equal(fastify.elastic.name, 'custom') 96 | await fastify.close() 97 | }) 98 | 99 | test('Missing configuration', async t => { 100 | const fastify = Fastify() 101 | t.after(() => fastify.close()) 102 | fastify.register(fastifyElasticsearch) 103 | 104 | try { 105 | await fastify.ready() 106 | t.assert.fail('should not boot successfully') 107 | } catch (err) { 108 | t.assert.ok(err) 109 | } 110 | }) 111 | -------------------------------------------------------------------------------- /types/index.d.ts: -------------------------------------------------------------------------------- 1 | import type { FastifyPluginAsync } from 'fastify' 2 | import type { Client, ClientOptions } from '@elastic/elasticsearch' 3 | 4 | declare module 'fastify' { 5 | interface FastifyInstance { 6 | elastic: Client & Record; 7 | isElasticsearchClient(value: unknown): value is Client 8 | } 9 | } 10 | 11 | type FastifyElasticsearch = FastifyPluginAsync & { 12 | isElasticsearchClient: (value: any) => value is Client 13 | } 14 | 15 | declare namespace fastifyElasticsearch { 16 | export interface FastifyElasticsearchOptions extends ClientOptions { 17 | namespace?: string; 18 | healthcheck?: boolean; 19 | client?: Client; 20 | } 21 | 22 | export const fastifyElasticsearch: FastifyElasticsearch 23 | export { fastifyElasticsearch as default } 24 | } 25 | 26 | declare function fastifyElasticsearch (...params: Parameters): ReturnType 27 | export = fastifyElasticsearch 28 | -------------------------------------------------------------------------------- /types/index.test-d.ts: -------------------------------------------------------------------------------- 1 | import fastifyElasticsearch from '..' 2 | import Fastify from 'fastify' 3 | import { expectAssignable, expectType } from 'tsd' 4 | import { Client } from '@elastic/elasticsearch' 5 | 6 | const fastify = Fastify() 7 | fastify.register(fastifyElasticsearch, { node: 'http://localhost:9200' }) 8 | 9 | expectType(fastify.isElasticsearchClient(fastify.elastic)) 10 | expectType(fastify.isElasticsearchClient(fastify.elastic.asyncSearch)) 11 | expectType(fastify.isElasticsearchClient(fastify.elastic.aasdf)) 12 | expectAssignable<(value: any) => value is Client>(fastifyElasticsearch.isElasticsearchClient) 13 | --------------------------------------------------------------------------------