Home

Awesome

meilisearch-helper

codecov

A helper library for meilisearch-js that provides convenient utility methods to simplify common operations and enhance your Meilisearch experience.

Installation

npm install meilisearch-helper

Usage

Filter

There are two ways to build a MeiliSearch filter:

  1. Use the buildMeiliSearchFilter function to build a filter from a MongoDB-style filter object.
  2. Use the MeiliSearchFilterBuilder class to build a filter with a fluent API.

Note: CONTAINS and STARTS WITH are experimental features. Use the experimental features endpoint to enable them. More details can be found in the MeiliSearch documentation.

buildMeiliSearchFilter

import { buildMeiliSearchFilter } from 'meilisearch-helper';

type FilterableAttributes = 'name' | 'age' | 'isStudent';

const filter = buildMeiliSearchFilter<FilterableAttributes>({
  $or: [
    { $or: [{ name: 'John' }, { name: 'Doe' }] },
    { $and: [{ age: { $gt: 18 } }, { isStudent: true }] },
  ],
  age: { $lt: 30 },
  $geoRadius: {
    lat: 45.472735,
    lng: 9.184019,
    distanceInMeters: 2000,
  },
});

console.log(filter);
// => ((name = "John" OR name = "Doe") OR age > 18 AND isStudent = true) AND age < 30 AND _geoRadius(45.472735, 9.184019, 2000)

Supported operators:

More examples can be found in the tests.

MeiliSearchFilterBuilder

Simple example:

import { MeiliSearchFilterBuilder } from 'meilisearch-helper';

type Person = {
  name: string;
  age: number;
  isStudent: boolean;
};
type FilterableAttributes = keyof Person;

function buildFilter(query: Partial<Person>) {
  let builder = new MeiliSearchFilterBuilder<FilterableAttributes>();

  if (query.name) {
    builder = builder.where('name', '=', query.name); // MeiliSearchFilterBuilder is immutable, you must re-assign!
  }

  if (query.age) {
    builder = builder.where('age', '=', query.age);
  }

  if (query.isStudent) {
    builder = builder.where('isStudent', '=', query.isStudent);
  }

  return builder.build();
}

console.log(buildFilter({ name: 'John', age: 20, isStudent: true }));
// => name = "John" AND age = 20 AND isStudent = true

Complex example:

import { MeiliSearchFilterBuilder } from 'meilisearch-helper';

type FilterableAttributes = 'name' | 'age' | 'isStudent';

// eb is a function to build a simple filter expression, more details below
const filter = new MeiliSearchFilterBuilder<FilterableAttributes>()
  .where((eb) =>
    eb.or([
      eb.or([eb('name', '=', 'John'), eb('name', '=', 'Doe')]),
      eb.and([eb('age', '>', 18), eb('isStudent', '=', true)]),
    ]),
  )
  .where('age', '<', 30)
  .where((eb) => eb.geoRadius(45.472735, 9.184019, 2000))
  .build();

console.log(filter);
// => ((name = "John" OR name = "Doe") OR age > 18 AND isStudent = true) AND age < 30 AND _geoRadius(45.472735, 9.184019, 2000)

eb (expression builder): A function to build a simple filter expression.

eb('age', '>', 18); // => age > 18
eb.or([eb('age', '>', 18), 'isStudent = true']); // => (age > 18 OR isStudent = true)
eb.and([eb('age', '>', 18), 'isStudent = true']); // => age > 18 AND isStudent = true
eb.geoRadius(45.472735, 9.184019, 2000); // => _geoRadius(45.472735, 9.184019, 2000)
eb.geoBoundingBox(
  { lat: 45.472735, lng: 19.184019 },
  { lat: 25.472735, lng: 9.184019 },
); // => _geoBoundingBox([45.472735, 19.184019], [25.472735, 9.184019])

supported operators:

More examples can be found in the tests.

Sort

buildMeiliSearchSort

Build a MeiliSearch sort from an object.

import { buildMeiliSearchSort } from 'meilisearch-helper';

type SortableAttributes = 'name' | 'age';

const sort = buildMeiliSearchSort<SortableAttributes>({
  name: 1,
  age: -1,
  _geoPoint: { lat: 48.8561446, lng: 2.2978204, direction: 1 },
});

console.log(sort);
// => [ "name:asc", "age:desc", "_geoPoint(48.8561446, 2.2978204):asc" ]

More examples can be found in the tests.

Supported directions:

License

MIT