constructors


BaseValidationType

Since Kuzzle 1.0.0

The BaseValidationType constructor provides a base to create your own validation types. It provides a common structure for all validation types in Kuzzle.

You can find an example of a type creation in the Kuzzle source code.


Dsl

Since Kuzzle 1.0.0

The DSL constructor provided in the plugin context can be used to access Koncorde.
It can be used to manage filters and test data to get a list of matching filters.

Each plugin can instantiate its own DSL sandbox instance:

const dsl = new context.constructors.Dsl();

The DSL exposes the following methods:

exists

Since Kuzzle 1.0.0

Returns a boolean indicating if filters exist for an index-collection pair.

Arguments

Name Type Description
index string Data index name
collection string Data collection name

Returns

Returns true if at least one filter exists in the provided index-collection pair, returns false otherwise.

getFilterIds

Since Kuzzle 1.0.0

Retrieves filter IDs registered on an index-collection pair.

Arguments

Name Type Description
index string Data index name
collection string Data collection name

Returns

An array of filterId corresponding to filters registered on an index-collection pair.

normalize

Since Kuzzle 1.1.0

Returns a promise that resolves if the provided filters are properly formatted.
The resolved object is a normalized and optimized version of the supplied filters, along with the corresponding Room unique identifier.

This method does not modify the DSL storage. To register the filters, the store method must be called afterwards.
If you do not need the Room unique identifier prior to store the DSL filters, then consider using register instead.

Arguments

Name Type Description
index string Data index name
collection string Data collection name
filters object Filters in Koncorde format

Returns

A promise that resolves to an object containing the following attributes:

  • index: data index name
  • collection: data collection name
  • normalized: an object containing the optimized version of the supplied filters
  • id: the room unique identifier

register

Since Kuzzle 1.0.0

Registers a filter to the DSL. This method is equivalent to executing normalize + store.

Arguments

Name Type Description
index string Data index name
collection string Data collection name
filters object Filters in Koncorde format

Returns

A promise that resolves to an object containing the following attributes:

  • id: the filter unique identifier
  • diff: false if the filter already exists in the engine. Otherwise, contains an object with the canonical version of the provided filters

remove

Since Kuzzle 1.0.0

Removes all references to a given filter from the DSL

Arguments

Name Type Description
filterId string Filter unique ID. Obtained by using register

Returns

A promise resolved once the filter has been completely removed from the DSL

store

Since Kuzzle 1.1.0

Stores normalized filters (obtained with normalize) in the DSL storage.

Arguments

Name Type Description
normalized Object Normalized filters

Returns

An Object containing the following attributes:

  • id: the filter unique identifier
  • diff: false if the filter already existed in the engine. Otherwise, contains an object with the canonical version of the provided filters

test

Since Kuzzle 1.0.0

Test data against filters registered in the DSL, returning matching filter IDs, if any.

Arguments

Name Type Description
index string Data index name
collection string Data collection name
data object Data to test against filters
documentId string If applicable, document unique ID

Returns

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

validate

Since Kuzzle 1.0.0

Tests the provided filters without storing them in the system, to check whether they are properly formatted or not.

Arguments

Name Type Description
filters object Filters in Koncorde format

Returns

A resolved promise if the provided filters are valid, or a rejected one with the appropriate error object.


Repository

Since Kuzzle 1.0.0

The Repository constructor provided in the plugin context gives access to methods that allow the plugin to interact with its plugin storage. The plugin storage is a dedicated index in Elasticsearch where the plugin can create collections. To do so, the plugin should first bootstrap the index. Once done, the plugin can instantiate repositories to interact with the different collections it created.

Arguments

Name Type Description
collection string The collection linked to the repository
ObjectConstructor constructor function (optional) Will be used as constructor for the fetched documents instead of Object

Usage

Each plugin can instantiate its own repositories linked to its own storage sandbox:

function ObjectConstructor() {
  this.someProperty = 'someValue';
}

var someCollectionRepository = new context.constructors.Repository('someCollection', ObjectConstructor);

The Repository exposes the following methods:

create

Since Kuzzle 1.0.0

Creates a document in the plugin storage.

Arguments

Name Type Description
document Object The document you want to create. It must contain a unique _id string property. You don't need to worry about collisions with other plugins as your plugin storage is only accessible by your plugin
options Object Optional arguments

If a raw options object is provided, it may contain:

Name Type Description
refresh string Value can only be wait_for if provided. See Elasticsearch documentation for more information.

Returns

Returns a promise that resolves to an object respresentation of Elasticsearch request result.

Usage

someCollectionRepository.create({
  _id: '<a unique id>',
  someField: 'some content',
  anotherField: 'another content',
  ...
})
  .then(result => {
    console.log(result);
  });

/**
 * Outputs:
 * { _index: '%some-plugin',
 *   _type: 'someCollection',
 *   _id: '<a unique id>',
 *   _version: 1,
 *   result: 'created',
 *   _shards: { total: 2, successful: 1, failed: 0 },
 *   created: true,
 *   _source: { someField: 'some content', anotherField: 'another content' } }
 */

createOrReplace

Since Kuzzle 1.0.0

Creates or replaces a document in the plugin storage.

Arguments

Name Type Description
document object The document you want to create or replace. It must contain a unique _id string property. You don't need to worry about collisions with other plugins as your plugin storage is only accessible by your plugin
options Object Optional arguments

If a raw options object is provided, it may contain:

Name Type Description
refresh string Value can only be wait_for if provided. See Elasticsearch documentation for more information.

Returns

Returns a promise that resolves to an object representation of Elasticsearch request result (see create usage).

Usage

someCollectionRepository.createOrReplace({
  _id: '<a unique id>',
  someField: 'some content',
  anotherField: 'another content',
  ...
});

delete

Since Kuzzle 1.0.0

Deletes a document from the plugin storage.

Arguments

Name Type Description
document object The document _id of the document you want to delete.
options Object Optional arguments

If a raw options object is provided, it may contain:

Name Type Description
refresh string Value can only be wait_for if provided. See Elasticsearch documentation for more information.

Returns

Returns a promise that resolves to an array of objects which is a representation of the Elasticsearch request result.

Usage

someCollectionRepository.delete('someDocumentId')
  .then(result => {
    console.log(result);
  });

/**
 * Outputs:
 *  [ { found: true,
 *    _index: '%some-plugin',
 *    _type: 'someCollection',
 *    _id: '<a unique id>',
 *    _version: 3,
 *    result: 'deleted',
 *    _shards: { total: 2, successful: 1, failed: 0 } } ]
 */

get

Since Kuzzle 1.0.0

Retrieves a document from the plugin storage.

Arguments

Name Type Description
documentId string The document identifier of the document you want to retrieve.

Returns

Returns a promise that resolves to an Object or an ObjectConstructor if provided in the constructor.

Usage

someCollectionRepository.get('someDocumentId', 'someCollection');

mGet

Since Kuzzle 1.0.0

Retrieves multiple documents from the plugin storage.

Arguments

Name Type Description
documentIds array<string> An array of document identifier of the documents you want to retrieve.

Returns

Returns a promise that resolves to an array of Object or ObjectConstructor if provided in the constructor.

Usage

someCollectionRepository.mGet(['someDocumentId', 'anotherDocument']);

replace

Since Kuzzle 1.0.0

Replaces a document in the plugin storage.

Arguments

Name Type Description
document object The content of the document. It must contain a unique _id string property.
options Object Optional arguments

If a raw options object is provided, it may contain:

Name Type Description
refresh string Value can only be wait_for if provided. See Elasticsearch documentation for more information.

Returns

Returns a promise that resolves to an object respresentation of Elasticsearch request result (see create usage).

Usage

someCollectionRepository.replace({
  _id: '<a unique id>',
  someField: 'some content',
  anotherField: 'another content',
  ...
});

search

Since Kuzzle 1.0.0

Searches documents that match the provided query in the collection.

Arguments

Name Type Description
query object The query sent to Elastisearch.
from integer Provides the offset of the returned documents.
size integer Provides the count of the returned documents.

Returns

Returns a promise that resolves to an object of the form {total: number, hits: array<object>} where hits contains an array of Object or ObjectConstructor if provided in the constructor and total the count of documents that match the query.

Usage

someCollectionRepository.search({
  query: {
    match_all: {}
  }
}, 0, 10);

update

Since Kuzzle 1.0.0

Updates a document in the plugin storage. You can provide a partial document to add or update one or more fields.

Arguments

Name Type Description
document object The partial content of the document. It must contain a unique _id string property.
options Object Optional arguments

If a raw options object is provided, it may contain:

Name Type Description
refresh string Value can only be wait_for if provided. See Elasticsearch documentation for more information.

Returns

Returns a promise that resolves to an object which is a representation of the Elasticsearch request result.

Usage

someCollectionRepository.update({
  _id: '<a unique id>',
  anotherField: 'changed content'
});
/**
 * Outputs:
 * { _index: '%some-plugin',
 *   _type: 'someCollection',
 *   _id: '<a unique id>',
 *   _version: 2,
 *   result: 'updated',
 *   _shards: { total: 0, successful: 0, failed: 0 } }
 */

Request

Since Kuzzle 1.0.0

This constructor is used to transform an API call into a standard Kuzzle request. This object is updated along the request process to reflect the current state of the request, and is ultimately used to serialize a standard Kuzzle response.

Protocol headers in a request response

Network protocol specific headers can be added to the response. If the protocol can handle them, these headers will be used to configure the response sent to the client.
As Kuzzle supports the HTTP protocol natively, this object handles HTTP headers special cases. Other network protocols headers are stored in raw format, and protocol plugins need to handle their own specific headers manually.

For more information about this object, please refer to our detailed documentation.

Constructors

new Request(<request object>, <data>, [options])

Since Kuzzle 1.0.0

Name Type Description
request Request Request object used to derive a new request object instance
data object JSON object following the same standard than for non-HTTP API calls
See the RequestInput constructor for more information
options object Optional initialization parameters

This constructor creates a new Request object from the provided one, and then adds the supplied data to complete the new object.

This constructor is particularly useful when a plugin needs to execute an API request derived from a user request, as most of the relevant information will be copied over to the new object.

Properties that are automatically copied to the new object:

  • All resource properties: _id, collection, index
  • Additional arguments: request.input.args
  • JSON Web Token, if any

Example:

const derivedRequest = new context.constructors.Request(request, {
  controller: 'document',
  action: 'create',
  body: {
    document: 'content'
  }
});

new Request(<data>, [options])

Since Kuzzle 1.2.0

Name Type Description
data object JSON object following the same standard than for non-HTTP API calls
See the RequestInput constructor for more information
options object Optional initialization parameters

This constructor can be used to create a new Request object without the need to provide a source.

The provided data object must contain a lot more information than what's needed by the constructor method described above, so if a Request object is available to your method, you should probably use it to instantiate one of these objects.

Example:

const request = new context.constructors.Request({
  controller: 'document',
  action: 'create',
  index: 'index',
  collection: 'collection',
  _id: 'documentId',
  body: {
    document: 'content'
  }
});

The "options" parameter

If a raw options object is provided to one of the Request constructors (see above), then it may contain the following properties:

Name Type Description

Since Kuzzle 1.4.1

connection
object Passed to RequestContext constructor

Deprecated since Kuzzle 1.4.1

connectionId
string Passed to RequestContext constructor
error KuzzleError or Error Invokes setError at initialization

Deprecated since Kuzzle 1.4.1

protocol
string Passed to RequestContext constructor
requestId string Initializes the id property
result (varies) Invokes setResult at initialization
status integer HTTP error code
token object Passed to RequestContext constructor
user object Passed to RequestContext constructor

Attributes

Read-only

Name Type Description
timestamp integer Request creation timestamp

Writable

Name Type default Description
id string Auto-generated UUID Request unique identifier
status integer 102 HTTP status code

Any undefined attribute from the list above will be set to null.

Please refer to our API Documentation for a complete list of controller actions and their usage.

Getters

Name Type Description
context RequestContext RequestContext object
error KuzzleError null
input RequestInput RequestInput object
response RequestResponse Response view of the request, standardized as the expected Kuzzle API response
result (varies) null

response.getHeader

Since Kuzzle 1.0.0

Returns the value registered for the response header name

Arguments

Name Type Description
name string Header name

response.removeHeader

Since Kuzzle 1.0.0

Removes header name from the response headers.

setHeader

Since Kuzzle 1.0.0

Adds a header name with value value to the response headers.

Arguments

Name Type Description
name string Header name
value string Header value

For standard headers, if name already exists, then the provided value will be concatenated to the existing value, separated by a comma.

As Kuzzle implements HTTP natively, this behavior changes for some HTTP specific headers to comply with the norm. For instance, set-cookie values are amended in an array, and other headers like user-agent or host can store only 1 value.

serialize

Since Kuzzle 1.0.0

Serializes the Request object into a pair of POJOs that can be sent across the network, and then used to rebuild another equivalent Request object.

let foo = request.serialize();
let bar = new context.constructors.Request(foo.data, foo.options);

setError

Since Kuzzle 1.0.0

Adds an error to the request, and sets the request's status to the error one.

Arguments

Name Type Description
error KuzzleError or Error Error object to set

If a KuzzleError is provided, the request's status attribute is set to the error one.

Otherwise, the provided error is encapsulated into an InternalError object, and the request's status is set to 500.

setResult

Since Kuzzle 1.0.0

Sets the request result.

Arguments

Name Type Description
result (varies) Request's result
options object Optional parameters

The options argument may contain the following properties:

Name Type Description Default
status integer HTTP status code 200
headers object Protocol specific headers null
raw boolean Asks Kuzzle to send the provided result directly, instead of encapsulating it in a Kuzzle JSON response false