Skip to content

API Reference

Jump to bottom
Sébastien Cottinet edited this page Jun 15, 2021 · 2 revisions

Table of Contents

constructor

Instantiates a new Koncorde engine.

constructor(options: KoncordeOptions = null)

Arguments

Name Type Description
options KoncordeOptions Optional parameters

options

KoncordeOptions is an interface exposed by the Koncorde module, with the following properties:

Name Type Default Description
maxConditions Number 50 The maximum number of conditions a filter can hold. This limit is applied after the filter has been standardized, meaning that it can trigger with an apparent lower number of conditions. It is advised to test performances and memory consumption impacts before increasing this value. If set to 0, no limit is applied.
seed Buffer fixed 32 bytes buffer containing a fixed random seed.
regExpEngine String re2 Set the engine to either re2 or js. The former is not fully compatible with PCREs, while the latter is vulnerable to catastrophic backtracking, making it unsafe if regular expressions are provided by end-users.

convertDistance

static convertDistance(distance: string): number

Utility method converting a distance value to meters.

Accepted units:

  • m, meter, meters
  • ft, feet, feets
  • in, inch, inches
  • yd, yard, yards
  • mi, mile, miles

Accepted unit modifiers: from yocto- (10e-21) to yotta- (10e24), and their corresponding short forms (e.g. kilometers or km)

Accepted formats: <int (spaces accepted)>[.|,]<decimal><spaces><unit>.

Examples:

import { Koncorde } from 'koncorde';

// Prints: 4.88442
console.log(Koncorde.convertDistance('192.3in'));

// Prints: 3456580
console.log(Koncorde.convertDistance('3 456,58 kilometers'));
convertDistance(distance: string): number

Arguments

Name Type Description
distance string Distance to convert

Returns

The distance converted in meters (type: number)

convertGeopoint

static convertGeopoint(point: string|JSONObject): { lat: number; lon: number; }

Converts one of the accepted geopoint format into the following standardized version:

{
    "lat": 12.345,
    "lon": 67.890
}

Accepted input formats (with latitude = 43.6021299 and longitude = 3.8989713):

  • [ 43.6021299, 3.8989713 ]
  • "43.6021299, 3.8989713"
  • "spfb09x0ud5s" (geohash)
  • { lat: 43.6021299, lon: 3.8989713 }

Alternative:

  • { latLon: [ 43.6021299, 3.8989713 ] }
  • { latLon: { lat: 43.6021299, lon: 3.8989713 } }
  • { latLon: "43.6021299, 3.8989713" }
  • { latLon: "spfb09x0ud5s"} (geohash)

Also accepted:

  • { lat_lon: [ 43.6021299, 3.8989713 ] }
  • { lat_lon: { lat: 43.6021299, lon: 3.8989713 } }
  • { lat_lon: "43.6021299, 3.8989713" }
  • { lat_lon: "spfb09x0ud5s"} (geohash)

Example:

import { Koncorde } from 'koncorde';

// Prints: Coordinate { lat: 43.6021299, lon: 3.8989713 }
console.log(Koncorde.convertGeopoint('spfb09x0ud5s'));
convertGeopoint(point: string|JSONObject): { lat: number; lon: number; }

Arguments

Name Type Description
point `string JSONObject`

Returns

An object containing the following properties: lat (latitude, type: number), lon (longitude, type: number)

getFilterIds

Returns the list of registered filter identifiers.

getFilterIds (index: string = null): string[]

Arguments

Name Type Description
index string (OPTIONAL) Index name. Uses the default one if none is provided

Returns

An array of filter unique identifiers corresponding to filters registered on the provided index-collection pair.

getIndexes

Returns the list of named indexes registered in this Koncorde instance

getIndexes (): string[]

Returns

An array of index names.

hasFilterId

Tells whether a filter identifier is known by Koncorde.

hasFilterId (filterId: string, index: string = null): boolean

Arguments

Name Type Description
filterId string Filter unique identifier
index string (OPTIONAL) Index name. Uses the default one if none is provided

Returns

A boolean value telling whether Koncorde knows the provided filter ID or not.

normalize

Verifies and normalizes a search filter.

This method does not modify the internal storage. To save a filter, the store method must be called afterward.

If you do not need the filter unique identifier prior to save a filter in the engine, then consider using the all-in-one register method instead.

normalize(filter: JSONObject, index: string = null): NormalizedFilter

Arguments

Name Type Description
filter object Search filters in Koncorde format
index string (OPTIONAL) Index name. Uses the default one if none is provided

Returns

A NormalizedFilter instance.

register

Registers a search filter in Koncorde. This method is equivalent to executing normalize + store.

register (filter: JSONObject, index: string = null): string

Arguments

Name Type Description
filter object Search filters in Koncorde format
index string (OPTIONAL) Index name. Uses the default one if none is provided

Returns

A string representing the filter identifier.

remove

Removes a filter from an index.

remove (filterId: string, index: string = null): void

Arguments

Name Type Description
filterId string Filter unique ID. Obtained by using register
index string (OPTIONAL) Index name. Uses the default one if none is provided

store

Stores a normalized filter (obtained with normalize).

store (normalized: NormalizedFilter): string

Arguments

Name Type Description
normalized Object Normalized filter, obtained with normalize

Returns

A string representing the filter identifier.

test

Test data against filters registered in the engine, returning matching filter identifiers, if any.

This method only tests filters in the targeted index: if no index name is provided, then Koncorde will target the default index.

test (data: JSONObject, index: string = null): string[]

Arguments

Name Type Description
data object Data to test against filters
index string (OPTIONAL) Index name. Uses the default one if none is provided

Returns

An array of filter identifiers matching the provided data (and/or documentId, if any).

validate

Tests the provided filter without storing it in the engine, to check whether it is well-formed or not.

validate (filter: JSONObject): void

Arguments

Name Type Description
filter object A filter in Koncorde format

Returns

Throws with an appropriate error if the provided filter is invalid.

Clone this wiki locally