Writing your own plugins

With Orama v2.0.0-beta.5, we introduced the new plugin system. This allows you to write your own plugins and use them in your Orama project.

The Orama plugin system is meant to replace the old hooks system, which is now deprecated.

If you had any custom hook, it would be incredibly easy to migrate it to a plugin, as the APIs are 100% backward compatible.

Creating a plugin

A plugin is essentially a JavaScript object with a name and a series of hook functions.

An example plugin could look like this:

function loggerPlugin() {
  return {
    name: "logger",
    beforeSearch: (orama, query) => {
      console.log(
        `About to search for ${query.term} on Orama instance ${orama.id}`
      );
    },
  };
}

And you can then use it in your Orama instance like this:

import { create, insert, search } from "@orama/orama";

function loggerPlugin() {
  return {
    name: "logger",
    beforeSearch: (orama, query) => {
      console.log(
        `About to search for ${query.term} on Orama instance ${orama.id}`
      );
    },
  };
}

const orama = create({
  id: "my-instance", // Remember, IDs are automatically generated if not provided
  schema: {
    name: "string",
  },
  plugins: [loggerPlugin()],
});

insert(orama, { name: "John" });
search(orama, { term: "John" });

// Console logs: "About to search for john on Orama instance my-instance"

Every plugin should have:

• A name property, which is a string (mandatory)
• Any hook function you want to use (optional)

Plugin hooks

With v2.0.0-beta.5, we essentially moved the hooks from the components property of the Orama instance to the plugins property.

The available hooks are:

• beforeInsert
• afterInsert
• beforeRemove
• afterRemove
• beforeUpdate
• afterUpdate
• beforeSearch
• afterSearch
• beforeInsertMultiple
• afterInsertMultiple
• beforeRemoveMultiple
• afterRemoveMultiple
• beforeUpdateMultiple
• afterUpdateMultiple

beforeInsert

Runs before an insert operation. Receives the Orama instance, the document ID, and the entire document to be inserted as arguments.

function beforeInsertPluginExample() {
  return {
    name: "before-insert-plugin",
    beforeInsert: (orama, id, document) => {
      console.log("Orama instance: ", orama);
      console.log("Document id: ", id);
      console.log("Document to be inserted: ", document);
    },
  };
}

afterInsert

Runs after an insert operation. Receives the Orama instance, the document ID, and the entire document as arguments.

function afterInsertPluginExample() {
  return {
    name: "after-insert-plugin",
    afterInsert: (orama, id, document) => {
      console.log("Orama instance: ", orama);
      console.log("Document id: ", id);
      console.log("Document inserted: ", document);
    },
  };
}

beforeRemove

Runs before a remove operation. Receives the Orama instance and the document ID to be removed as arguments.

function beforeRemovePluginExample() {
  return {
    name: "before-remove-plugin",
    beforeRemove: (orama, id) => {
      console.log("Orama instance: ", orama);
      console.log("Document id: ", id);
    },
  };
}

afterRemove

Runs after a remove operation. Receives the Orama instance and the document ID removed as arguments.

function afterRemovePluginExample() {
  return {
    name: "after-remove-plugin",
    afterRemove: (orama, id) => {
      console.log("Orama instance: ", orama);
      console.log("Document id: ", id);
    },
  };
}

beforeUpdate

Runs before an update operation. Receives the Orama instance and the document ID to be updated as arguments.

function beforeUpdatePluginExample() {
  return {
    name: "before-update-plugin",
    beforeUpdate: (orama, id) => {
      console.log("Orama instance: ", orama);
      console.log("Document id: ", id);
    },
  };
}

afterUpdate

Runs after an update operation. Receives the Orama instance and the document ID as arguments.

function afterUpdatePluginExample() {
  return {
    name: "after-update-plugin",
    afterUpdate: (orama, id) => {
      console.log("Orama instance: ", orama);
      console.log("Document id: ", id);
    },
  };
}

beforeSearch

Runs before a search operation. Receives the Orama instance and the query object as arguments.

function beforeSearchPluginExample() {
  return {
    name: "before-search-plugin",
    beforeSearch: (orama, query) => {
      console.log("Orama instance: ", orama);
      console.log("Query: ", query);
    },
  };
}

afterSearch

Runs after a search operation. Receives the Orama instance, the query object, and the search results as arguments.

function afterSearchPluginExample() {
  return {
    name: "after-search-plugin",
    afterSearch: (orama, query, result) => {
      console.log("Orama instance: ", orama);
      console.log("Query: ", query);
      console.log("Search result: ", result);
    },
  };
}

beforeInsertMultiple

Runs before an insertMultiple operation. Receives the Orama instance and the documents to be inserted as arguments.

Caution

Since the insertMultiple operation is calling the insert operation underneath, the beforeInsertMultiple hook will be called for each document.
If there’s an existing beforeInsert hook in the plugin, it will be called for each document as well.

function beforeInsertMultiplePluginExample() {
  return {
    name: "before-insert-multiple-plugin",
    beforeInsertMultiple: (orama, documents) => {
      console.log("Orama instance: ", orama);
      console.log("Documents to be inserted: ", documents);
    },
  };
}

afterInsertMultiple

Runs after an insertMultiple operation. Receives the Orama instance and the documents inserted as arguments.

Caution

Since the insertMultiple operation is calling the insert operation underneath, the afterInsertMultiple hook will be called for each document.
If there’s an existing afterInsert hook in the plugin, it will be called for each document as well.

function afterInsertMultiplePluginExample() {
  return {
    name: "after-insert-multiple-plugin",
    afterInsertMultiple: (orama, documents) => {
      console.log("Orama instance: ", orama);
      console.log("Documents inserted: ", documents);
    },
  };
}

beforeRemoveMultiple

Runs before a removeMultiple operation. Receives the Orama instance and the IDs of the documents to be removed as arguments.

Caution

Since the removeMultiple operation is calling the remove operation underneath, the beforeRemoveMultiple hook will be called for each document.
If there’s an existing beforeRemove hook in the plugin, it will be called for each document as well.

function beforeRemoveMultiplePluginExample() {
  return {
    name: "before-remove-multiple-plugin",
    beforeRemoveMultiple: (orama, ids) => {
      console.log("Orama instance: ", orama);
      console.log("Document IDs to be removed: ", ids);
    },
  };
}

afterRemoveMultiple

Runs after a removeMultiple operation. Receives the Orama instance and the IDs of the documents removed as arguments.

Caution

Since the removeMultiple operation is calling the remove operation underneath, the afterRemoveMultiple hook will be called for each document.
If there’s an existing afterRemove hook in the plugin, it will be called for each document as well.

function afterRemoveMultiplePluginExample() {
  return {
    name: "after-remove-multiple-plugin",
    afterRemoveMultiple: (orama, ids) => {
      console.log("Orama instance: ", orama);
      console.log("Document IDs removed: ", ids);
    },
  };
}

beforeUpdateMultiple

Runs before an updateMultiple operation. Receives the Orama instance and the IDs of the documents to be updated as arguments.

Caution

Since the updateMultiple operation is calling the update operation underneath, the beforeUpdateMultiple hook will be called for each document.
If there’s an existing beforeUpdate hook in the plugin, it will be called for each document as well.

Also, consider that the update operation is a shorthand for the remove and insert operations.
This means that the beforeRemove and beforeInsert hooks will be called for each document as well.

function beforeUpdateMultiplePluginExample() {
  return {
    name: "before-update-multiple-plugin",
    beforeUpdateMultiple: (orama, ids) => {
      console.log("Orama instance: ", orama);
      console.log("Document IDs to be updated: ", ids);
    },
  };
}

afterUpdateMultiple

Runs after an updateMultiple operation. Receives the Orama instance and the IDs of the documents updated as arguments.

Caution

Since the updateMultiple operation is calling the update operation underneath, the afterUpdateMultiple hook will be called for each document.
If there’s an existing afterUpdate hook in the plugin, it will be called for each document as well.

Also, consider that the update operation is a shorthand for the remove and insert operations.
This means that the afterRemove and afterInsert hooks will be called for each document as well.

function afterUpdateMultiplePluginExample() {
  return {
    name: "after-update-multiple-plugin",
    afterUpdateMultiple: (orama, ids) => {
      console.log("Orama instance: ", orama);
      console.log("Document IDs updated: ", ids);
    },
  };
}

Migrating from hooks to plugins

If you were using the old hooks system, you can easily migrate to the new plugin system by moving your hooks to a single plugin.

For instance, if you had a beforeInsert hook, you can migrate it to a plugin like this:

import { create } from '@orama/orama'

const db = create({
  schema: {
    name: 'string'
  },
 components: {
   beforeInsert: (orama, id, document) => {
     console.log('Orama instance: ', orama)
     console.log('Document id: ', id)
     console.log('Document to be inserted: ', document)
   }
 }
 plugins: [
   {
     name: 'before-insert-plugin',
     beforeInsert: (orama, id, document) => {
       console.log('Orama instance: ', orama)
       console.log('Document id: ', id)
       console.log('Document to be inserted: ', document)
     }
   }
 ]
})

Types, behavior, and arguments are 100% backward compatible, so you don’t need to change anything else.