{"id":14969230,"url":"https://github.com/mateonunez/fastify-orama","last_synced_at":"2025-10-26T07:31:18.663Z","repository":{"id":46238635,"uuid":"515105924","full_name":"mateonunez/fastify-orama","owner":"mateonunez","description":"Orama search-engine plugin for Fastify","archived":false,"fork":false,"pushed_at":"2025-10-14T17:05:25.000Z","size":195,"stargazers_count":20,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-15T03:53:13.991Z","etag":null,"topics":["fastify","fastify-plugin","lyra","nodejs","orama"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/fastify-orama","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/mateonunez.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-07-18T08:55:42.000Z","updated_at":"2025-10-14T17:05:22.000Z","dependencies_parsed_at":"2023-07-28T00:51:37.913Z","dependency_job_id":"d9b3d476-2db9-40bf-b9cd-296e8467cd7a","html_url":"https://github.com/mateonunez/fastify-orama","commit_stats":{"total_commits":149,"total_committers":4,"mean_commits":37.25,"dds":0.3221476510067114,"last_synced_commit":"125c2aea52eef2c6560e0cf3e10ca4d1faf0cbf3"},"previous_names":["mateonunez/fastify-lyra"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/mateonunez/fastify-orama","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateonunez%2Ffastify-orama","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateonunez%2Ffastify-orama/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateonunez%2Ffastify-orama/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateonunez%2Ffastify-orama/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mateonunez","download_url":"https://codeload.github.com/mateonunez/fastify-orama/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateonunez%2Ffastify-orama/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280977261,"owners_count":26423759,"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","status":"online","status_checked_at":"2025-10-25T02:00:06.499Z","response_time":81,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["fastify","fastify-plugin","lyra","nodejs","orama"],"created_at":"2024-09-24T13:41:24.124Z","updated_at":"2025-10-26T07:31:18.363Z","avatar_url":"https://github.com/mateonunez.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# fastify-orama\n\n![Continuous Integration](https://github.com/mateonunez/fastify-orama/workflows/ci/badge.svg)\n\n[Orama](https://oramasearch.com/) plugin for Fastify.\n\n## Installation\n\n```\nnpm install fastify-orama\n```\n\n### Compatibility\n\n| Plugin version | Fastify version | Orama version |\n|----------------|:---------------:|--------------:|\n| `^3.0.0`       |    `^5.0.0`     |      `^3.0.0` |\n| `^2.0.0`       |    `^5.0.0`     |      `^2.0.0` |\n| `^1.0.0`       |    `^4.0.0`     |      `^2.0.0` |\n\n****\n\n## Usage\n\nThis plugin adds the `orama` decorator to your Fastify application.\nThe decorator exposes all the methods\nthat [the Orama class exposes](https://docs.oramasearch.com/open-source/usage/create).\n\nThe `options` object is passed directly to the `Orama.create` constructor,\nso it supports [all the options that Orama supports](https://docs.oramasearch.com/open-source/usage/create).\n\n### Example\n\n```js\nimport Fastify from 'fastify'\nimport fastifyOrama from 'fastify-orama'\n\nconst app = Fastify()\n\napp.register(fastifyOrama, {\n  schema: {\n    quote: \"string\",\n    author: \"string\"\n  }\n})\n\napp.get('/quotes/:query', async function handler (req, reply) {\n  const { params: { query } } = req\n\n  const search = app.orama.search({\n    term: query,\n    properties: [\"quote\"]\n  })\n\n  return { quotes: search.hits }\n})\n\napp.listen({ port: 3000 })\n```\n\n## Usage with data persistence\n\nThis plugin supports data persistence out of the box.\nYou need to pass the `persistence` option to the plugin registration!\n\nThis plugin uses [\n`@oramasearch/plugin-data-persistence`](https://docs.oramasearch.com/open-source/plugins/plugin-data-persistence)\nunder the hood to allow users to `load` or `persist` database instances.\n\nTurning on the `persistence` option will add the `fastify.orama.persist()` method to your Fastify application.\nYou must call this method to save the database instance to the persistence layer, otherwise your data will be lost.\n\n### PersistenceInFile\n\nThis plugin comes with a `PersistenceInFile` class that allows you to persist your data in a file.\nIf the file exists, the plugin will load the data from it when the plugin is registered.\n\nIts constructor accepts the following options:\n\n- `filePath`: The path to the file where the data will be persisted. Default: `./orama.msp`\n- `format`: The format of the file where the data will be persisted. Default: `binary`\n- `mustExistOnStart`: Whether the file must exist when the plugin is registered or not. Default: `false`. Note that if\n  the file does not exist, you must specify the `schema` option in the plugin registration.\n\n```js\nimport Fastify from 'fastify'\nimport { fastifyOrama, PersistenceInFile } from 'fastify-orama'\n\nconst app = Fastify()\n\n// The database must exists to load it in your Fastify application\napp.register(fastifyOrama, {\n  schema: {\n    quote: \"string\",\n    author: \"string\"\n  },\n  persistence: new PersistenceInFile({\n    filePath: './db.json', // Default: './orama.msp'\n    format: 'json', // Default: 'binary',\n    mustExistOnStart: true // Default: false\n  })\n})\n\napp.post('/quotes', function (req, reply) {\n  const { body: { author, quote } } = req\n\n  fastify.orama.insert({\n    author,\n    quote\n  })\n\n  return { success: true }\n})\n\napp.addHook('onClose', async function persist (app) {\n  const path = await app.orama.persist()\n  app.log.info(`Database saved to ${path}`)\n})\n\napp.listen({ port: 3000 })\n```\n\n### PersistenceInMemory\n\nThis plugin comes with a `PersistenceInMemory` class that allows you to persist your data in memory.\nThis adapter may be useful for testing purposes, when you need to share the same database instance between multiple\ntests.\n\nIts constructor accepts the following options:\n\n- `jsonIndex`: The stringified JSON representation of the database instance. Default: `null`\n\n```js\nimport Fastify from 'fastify'\nimport { fastifyOrama, PersistenceInMemory } from 'fastify-orama'\n\nconst appOne = Fastify()\n\nawait appOne.register(fastifyOrama, {\n  schema: { author: 'string', quote: 'string' },\n  persistence: new PersistenceInMemory()\n})\n\n// Do some stuff with the database\nappOne.orama.insert({\n  quote: 'Orama and Fastify are awesome together.',\n  author: 'Mateo Nunez'\n})\n\nconst inMemoryDb = await appOne.orama.persist()\n\n// Close the Fastify application\nawait appOne.close()\n\n\n// Create a new Fastify test case\nconst appTwo = Fastify()\nawait appTwo.register(fastifyOrama, {\n  persistence: new PersistenceInMemory({\n    jsonIndex: inMemoryDb // Pass the in-memory database to the new Fastify application\n  })\n})\n\n// The database is persisted between Fastify applications\nconst results = appTwo.orama.search({ term: 'Mateo Nunez' })\n```\n\n### Custom persistence\n\nIf you need a custom persistence layer, you can implement your own persistence class.\nTo do so, you need to implement the following methods:\n\n```js\nconst customPersistance = {\n  restore: async function restore () {\n    // Restore the database instance from the persistence layer\n    // Return the database instance or null if it does not exist\n  },\n\n  persist: async function persist (db) {\n    // Persist the database instance to the persistence layer\n    // Whatever this method returns will be passed to the `app.orama.persist()` method\n  }\n}\n\nawait fastify.register(fastifyOrama, {\n  schema,\n  persistence: customPersistance\n})\n```\n\n## Orama Internals\n\nDo you need to access the [Orama internals utilities](https://docs.oramasearch.com/internals/utilities)?\nNo problem!\n\n```js\nimport { fastifyOrama, oramaInternals } from 'fastify-orama'\n\nconst app = Fastify()\n\n// The database must exists to load it in your Fastify application\napp.register(fastifyOrama, {\n  schema: {\n    quote: \"string\",\n    author: \"string\"\n  }\n})\n\napp.get('/genId', function handler (req, reply) {\n  return { newId: oramaInternals.uniqueId() }\n})\n```\n\n## Typescript\n\nThis plugin comes with Typescript support out of the box.\nUsing the `withOrama` helper, you can access the `orama` decorator in your Fastify application with the correct schema.\n\n```ts\nimport Fastify from 'fastify'\n\nimport { PersistenceInMemory, fastifyOrama } from 'fastify-orama'\n\nconst app = Fastify()\n\nconst mySchema = {\n  quote: 'string',\n  author: 'string'\n} as const\n\nawait app.register(fastifyOrama, {\n  schema: mySchema,\n  persistence: new PersistenceInMemory()\n})\n\nconst appWithOrama = app.withOrama\u003ctypeof mySchema\u003e()\nconst id = appWithOrama.orama.insert({ quote: 'Hello', author: 'World' })\n\nappWithOrama.get('/hello', async () =\u003e {\n\n  const {orama} = appWithOrama\n  const result = orama.search({ term: 'hello' })\n\n  return {\n    hello: result.hits\n  }\n})\n```\n\nUsage with `fastify-plugin`:\n\n```ts\nimport fp from 'fastify-plugin'\n\nfp(function plugins(fastify) {\n  const fastifyWithOrama = fastify.withOrama\u003ctypeof mySchema\u003e()\n\n  expectType\u003c{\n    insert: (document: PartialSchemaDeep\u003cTypedDocument\u003cOrama\u003ctypeof mySchema\u003e\u003e\u003e) =\u003e string,\n    search: (params: SearchParams\u003cOrama\u003cSchema\u003ctypeof mySchema\u003e\u003e, typeof mySchema\u003e) =\u003e Results\u003cSchema\u003ctypeof mySchema\u003e\u003e,\n    persist?: () =\u003e Promise\u003cany\u003e,\n  }\u003e(fastifyWithOrama.orama)\n})\n```\n\n## License\n\nfastifyOrama is licensed under the [MIT](LICENSE) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateonunez%2Ffastify-orama","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmateonunez%2Ffastify-orama","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateonunez%2Ffastify-orama/lists"}