fastify-orama - GitLite

KO | EN

gitlite — search

#swift #framework #ruby #containers #shell #awesome-list #list #devops #nextjs #api

fastify-orama

(★ 20)

Orama search-engine plugin for Fastify

File Explorer

ZIP Download

- - ci.yml
- dependabot.yml
- pre-commit
- - in-file.js
  - in-memory.js
- - index.tst.ts
- index.test.js
- orama-proxy.test.js
- persistence.test.js
.borp.yaml
.gitignore
.npmignore
index.d.ts
index.js
LICENSE
package.json
README.md
tsconfig.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`npm install`

View Details ▼

Install Node packages.

npm {{[i|install]}}

Install dependencies listed in `package.json`:

npm {{[i|install]}} {{package_name}}@{{version}}

Download a specific version of a package and add it to the list of dependencies in `package.json`:

npm {{[i|install]}} {{package_name}} {{[-D|--save-dev]}}

Download the latest version of a package and add it to the list of dev dependencies in `package.json`:

# Project Badges

Continuous Integration

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[Orama](https://oramasearch.com/) plugin for Fastify.

## Installation

```
npm install fastify-orama
```

### Compatibility

| Plugin version | Fastify version | Orama version |
|----------------|:---------------:|--------------:|
| `^3.0.0`       |    `^5.0.0`     |      `^3.0.0` |
| `^2.0.0`       |    `^5.0.0`     |      `^2.0.0` |
| `^1.0.0`       |    `^4.0.0`     |      `^2.0.0` |

****

## Usage

This plugin adds the `orama` decorator to your Fastify application.
The decorator exposes all the methods
that [the Orama class exposes](https://docs.oramasearch.com/open-source/usage/create).

The `options` object is passed directly to the `Orama.create` constructor,
so it supports [all the options that Orama supports](https://docs.oramasearch.com/open-source/usage/create).

### Example

```js
import Fastify from 'fastify'
import fastifyOrama from 'fastify-orama'

const app = Fastify()

app.register(fastifyOrama, {
  schema: {
    quote: "string",
    author: "string"
  }
})

app.get('/quotes/:query', async function handler (req, reply) {
  const { params: { query } } = req

const search = app.orama.search({
    term: query,
    properties: ["quote"]
  })

return { quotes: search.hits }
})

app.listen({ port: 3000 })
```

## Usage with data persistence

This plugin supports data persistence out of the box.
You need to pass the `persistence` option to the plugin registration!

This plugin uses [
`@oramasearch/plugin-data-persistence`](https://docs.oramasearch.com/open-source/plugins/plugin-data-persistence)
under the hood to allow users to `load` or `persist` database instances.

Turning on the `persistence` option will add the `fastify.orama.persist()` method to your Fastify application.
You must call this method to save the database instance to the persistence layer, otherwise your data will be lost.

### PersistenceInFile

This plugin comes with a `PersistenceInFile` class that allows you to persist your data in a file.
If the file exists, the plugin will load the data from it when the plugin is registered.

Its constructor accepts the following options:

- `filePath`: The path to the file where the data will be persisted. Default: `./orama.msp`
- `format`: The format of the file where the data will be persisted. Default: `binary`
- `mustExistOnStart`: Whether the file must exist when the plugin is registered or not. Default: `false`. Note that if
  the file does not exist, you must specify the `schema` option in the plugin registration.

```js
import Fastify from 'fastify'
import { fastifyOrama, PersistenceInFile } from 'fastify-orama'

const app = Fastify()

// The database must exists to load it in your Fastify application
app.register(fastifyOrama, {
  schema: {
    quote: "string",
    author: "string"
  },
  persistence: new PersistenceInFile({
    filePath: './db.json', // Default: './orama.msp'
    format: 'json', // Default: 'binary',
    mustExistOnStart: true // Default: false
  })
})

app.post('/quotes', function (req, reply) {
  const { body: { author, quote } } = req

fastify.orama.insert({
    author,
    quote
  })

return { success: true }
})

app.addHook('onClose', async function persist (app) {
  const path = await app.orama.persist()
  app.log.info(`Database saved to ${path}`)
})

app.listen({ port: 3000 })
```

### PersistenceInMemory

This plugin comes with a `PersistenceInMemory` class that allows you to persist your data in memory.
This adapter may be useful for testing purposes, when you need to share the same database instance between multiple
tests.

Its constructor accepts the following options:

- `jsonIndex`: The stringified JSON representation of the database instance. Default: `null`

```js
import Fastify from 'fastify'
import { fastifyOrama, PersistenceInMemory } from 'fastify-orama'

const appOne = Fastify()

await appOne.register(fastifyOrama, {
  schema: { author: 'string', quote: 'string' },
  persistence: new PersistenceInMemory()
})

// Do some stuff with the database
appOne.orama.insert({
  quote: 'Orama and Fastify are awesome together.',
  author: 'Mateo Nunez'
})

const inMemoryDb = await appOne.orama.persist()

// Close the Fastify application
await appOne.close()

// Create a new Fastify test case
const appTwo = Fastify()
await appTwo.register(fastifyOrama, {
  persistence: new PersistenceInMemory({
    jsonIndex: inMemoryDb // Pass the in-memory database to the new Fastify application
  })
})

// The database is persisted between Fastify applications
const results = appTwo.orama.search({ term: 'Mateo Nunez' })
```

### Custom persistence

If you need a custom persistence layer, you can implement your own persistence class.
To do so, you need to implement the following methods:

```js
const customPersistance = {
  restore: async function restore () {
    // Restore the database instance from the persistence layer
    // Return the database instance or null if it does not exist
  },

persist: async function persist (db) {
    // Persist the database instance to the persistence layer
    // Whatever this method returns will be passed to the `app.orama.persist()` method
  }
}

await fastify.register(fastifyOrama, {
  schema,
  persistence: customPersistance
})
```

## Orama Internals

Do you need to access the [Orama internals utilities](https://docs.oramasearch.com/internals/utilities)?
No problem!

```js
import { fastifyOrama, oramaInternals } from 'fastify-orama'

const app = Fastify()

// The database must exists to load it in your Fastify application
app.register(fastifyOrama, {
  schema: {
    quote: "string",
    author: "string"
  }
})

app.get('/genId', function handler (req, reply) {
  return { newId: oramaInternals.uniqueId() }
})
```

## Typescript

This plugin comes with Typescript support out of the box.
Using the `withOrama` helper, you can access the `orama` decorator in your Fastify application with the correct schema.

```ts
import Fastify from 'fastify'

import { PersistenceInMemory, fastifyOrama } from 'fastify-orama'

const app = Fastify()

const mySchema = {
  quote: 'string',
  author: 'string'
} as const

await app.register(fastifyOrama, {
  schema: mySchema,
  persistence: new PersistenceInMemory()
})

const appWithOrama = app.withOrama<typeof mySchema>()
const id = appWithOrama.orama.insert({ quote: 'Hello', author: 'World' })

appWithOrama.get('/hello', async () => {

const {orama} = appWithOrama
  const result = orama.search({ term: 'hello' })

return {
    hello: result.hits
  }
})
```

Usage with `fastify-plugin`:

```ts
import fp from 'fastify-plugin'

fp(function plugins(fastify) {
  const fastifyWithOrama = fastify.withOrama<typeof mySchema>()

expectType<{
    insert: (document: PartialSchemaDeep<TypedDocument<Orama<typeof mySchema>>>) => string,
    search: (params: SearchParams<Orama<Schema<typeof mySchema>>, typeof mySchema>) => Results<Schema<typeof mySchema>>,
    persist?: () => Promise<any>,
  }>(fastifyWithOrama.orama)
})
```

## License

fastifyOrama is licensed under the [MIT](LICENSE) license.