Try the live demo
Installation
You can install Lyra using npm
, yarn
, pnpm
:
npm i @lyrasearch/lyra
yarn add @lyrasearch/lyra
pnpm add @lyrasearch/lyra
Usage
Lyra is quite simple to use. The first thing to do is to create a new database instance and set an indexing schema:
import { create, insert, remove, search } from "@lyrasearch/lyra";
const db = create({
schema: {
author: "string",
quote: "string",
},
});
Lyra will only index string properties, but will allow you to set and store additional data if needed.
Once the db instance is created, you can start adding some documents:
insert(db, {
quote:
"It is during our darkest moments that we must focus to see the light.",
author: "Aristotle",
});
insert(db, {
quote:
"If you really look closely, most overnight successes took a long time.",
author: "Steve Jobs",
});
insert(db, {
quote:
"If you are not willing to risk the usual, you will have to settle for the ordinary.",
author: "Jim Rohn",
});
insert(db, {
quote: "You miss 100% of the shots you don't take",
author: "Wayne Gretzky - Michael Scott",
});
Please note that the insert
function is synchronous. If you have a large
number of documents, we highly recommend using the insertBatch
function
instead, which prevents the event loop from blocking. This operation is
asynchronous and returns a promise:
await insertBatch(db, [
{
quote:
"It is during our darkest moments that we must focus to see the light.",
author: "Aristotle",
},
{
quote:
"If you really look closely, most overnight successes took a long time.",
author: "Steve Jobs",
},
{
quote:
"If you are not willing to risk the usual, you will have to settle for the ordinary.",
author: "Jim Rohn",
},
{
quote: "You miss 100% of the shots you don't take",
author: "Wayne Gretzky - Michael Scott",
},
]);
After the data has been inserted, you can finally start to query the database.
const searchResult = search(db, {
term: "if",
properties: "*",
});
In the case above, you will be searching for all the documents containing the
word if
, looking up in every schema property (AKA index):
{
elapsed: 99, // elapsed time is in microseconds
hits: [
{
id: 'ckAOPGTA5qLXx0MgNr1Zy',
quote: 'If you really look closely, most overnight successes took a long time.',
author: 'Steve Jobs'
},
{
id: 'fyl-_1veP78IO-wszP86Z',
quote: 'If you are not willing to risk the usual, you will have to settle for the ordinary.',
author: 'Jim Rohn'
}
],
count: 2
}
You can also restrict the lookup to a specific property:
const searchResult = search(db, {
term: "Michael",
properties: ["author"],
});
Result:
{
elapsed: 111,
hits: [
{
id: 'L1tpqQxc0c2djrSN2a6TJ',
quote: "You miss 100% of the shots you don't take",
author: 'Wayne Gretzky - Michael Scott'
}
],
count: 1
}
If needed, you can also delete a given document by using the remove
method:
remove(db, "L1tpqQxc0c2djrSN2a6TJ");
Language
Lyra supports multiple languages. By default, it will use the english
language,
You can specify a different language by using the defaultLanguage
property
during Lyra initialization.
By default, Lyra will analyze your input using an English
Porter Stemmer function.
You can replace the default stemmer with the a custom one, or a pre-built one
shipped with the default Lyra installation.
Example (using ESM):
import { create } from "@lyrasearch/lyra";
import { stemmer } from "@lyrasearch/lyra/dist/stemmer/esm/it";
const db = create({
schema: {
author: "string",
quote: "string",
},
defaultLanguage: "italian",
tokenizer: {
stemmingFn: stemmer,
},
});
Example (using CJS):
const { create } = require("@lyrasearch/lyra");
const { stemmer } = require("@lyrasearch/lyra/dist/stemmer/cjs/it");
const db = create({
schema: {
author: "string",
quote: "string",
},
defaultLanguage: "italian",
tokenizer: {
stemmingFn: stemmer,
},
});
Right now, Lyra supports 22 languages and stemmers out of the box:
- Armenian
- Arabic
- Danish
- Spanish
- English
- Finnish
- French
- German
- Greek
- Hindi
- Hungarian
- Indonesian
- Italian
- Irish
- Dutch
- Nepali
- Norwegian
- Portuguese
- Romanian
- Russian
- Serbian
- Swedish
- Turkish
Hooks
When dealing with asynchronous operations, hooks are an excelent mechanism to
intercept and perform operations during the workflow. Lyra supports hooks
natively. The create
function allows you to specific a sequence of hooks.
import { create } from "@lyrasearch/lyra";
const db = create({
schema: {},
hooks: {
// HERE
},
});
Important: The hooks run in the same context as the main function execution. It means, that if your hook takes X milliseconds to resolve, the Lyra function will take X + Y (where Y = Lyra operation).
afterInsert hook
The afterInsert
hook is called after the insertion of a document into the
database. The hook
will be called with the id
of the inserted document.
Example:
import { create, insertWithHooks } from "@lyrasearch/lyra";
async function hook1 (id: string): Promise<void> {
// called before hook2
}
function hook2 (id: string): void {
// ...
}
const db = create({
schema: {
author: "string",
quote: "string",
},
hooks: {
afterInsert: [hook1, hook2],
},
});
await insertWithHooks(db, { author: "test", quote: "test" })
License
Lyra is licensed under the Apache 2.0 license.