@elastic.io/maester-client

Maester Client

The official Elastic.io object-storage client.

Usage

This library propose you two clients: ObjectStorage & ObjectStorageWrapper. Use ObjectStorageWrapper to operate with data like string, number, object, array Use ObjectStorage to operate attachments (also could be used for same purpose as ObjectStorageWrapper)

Note: All the code snippets written in Typescript

Environment variables

REQUEST_MAX_RETRY - specifies amount of tries to repeat failed request if server/connection error occurred.
Default value: 2. Min value: 0. Max value: 4. If entered value is out of limits - default value will be used.

REQUEST_TIMEOUT - specifies the number of milliseconds before the request times out. If the request takes longer than 'timeout', the request will be aborted.
Default value: 10000 (10s). Min value: 500 (0.5s). Max value: 20000 (20s). If entered value is out of limits - default value will be used.

Create client

import { ObjectStorage, ObjectStorageWrapper } from '@elastic.io/maester-client';

const objectStorageWrapper = new ObjectStorageWrapper(this);
const objectStorage = new ObjectStorage(creds);

ObjectStorageWrapper CRUD operations

Create object

The method has the following signature:

async createObject(data: object, queryHeaders?: Header[], metaHeaders?: Header[], ttl?: number)

where

• data - any data to create. Required
• queryHeaders - array of objects { key: string, value: string }, current maximum - 5 items. Where key (must be lowercase) - searchable field name (see below in Get objects by query parameters section), must be unique for whole array, if specified - value must be specified as well; value - searchable field value, if specified - key must be specified as well. Optional
• metaHeaders - array of objects { key: string, value: string }, where key (must be lowercase) - meta field name, must be unique for whole array, if specified - value must be specified as well; value - meta field value, if specified - key must be specified as well. Optional
• ttl - configurable object's time to live, seconds. Optional

const obj = await objectStorageWrapper.createObject(data);
const obj = await objectStorageWrapper.createObject(data, [], [], 100000);
const obj = await objectStorageWrapper.createObject(
  data,
  [{key: 'somequeriablefieldkey', value: 'somequeriablefieldvalue'}],
  [{key: 'somemetakey', value: 'somemetavalue'}],
  60000
);
const obj = await objectStorageWrapper.createObject(
  data,
  [{key: 'anotherqueriablefieldkey', value: 'anotherqueriablefieldvalue'}, {key: 'anotherqueriablefieldkey2', value: 'anotherqueriablefieldvalue2'}],
  [{key: 'somemetakey', value: 'somemetavalue'}],
  60000
);

Read operations

Get object by ID

Returns JSON object. The method has the following signature:

async lookupObjectById(id: string)

where

• id - Maester internal id of the object to lookup. E.g. '76380cae-aee3-457a-9029-d971f61e3731'. Required

const obj = await objectStorageWrapper.lookupObjectById(id);

Get objects by query parameters

The method has the following signature:

async lookupObjectsByQueryParameters(headers: Header[])

where

• headers - array of objects { key: string, value: string }, current maximum - 5 items. Where key (must be lowercase) - searchable field name, must be unique for whole array, if specified - value must be specified as well; value - searchable field value, if specified - key must be specified as well. Required

If you create an object with a queriable headers, internally it looks like this:

x-query-somequeriablefieldkey: somequeriablefieldvalue
x-query-anotherqueriablefieldkey: anotherqueriablefieldvalue

where 'x-query-' is a default prefix.

Using Maester REST API you can find this object by:

/objects?query[somequeriablefieldkey]=somequeriablefieldvalue&query[anotherqueriablefieldkey]=anotherqueriablefieldvalue

Using the library:

const objects = await objectStorageWrapper.lookupObjectsByQueryParameters([
  { key: 'somequeriablefieldkey', value: 'somequeriablefieldvalue' },
  { key: 'anotherqueriablefieldkey', value: 'anotherqueriablefieldvalue' }
]);

The method returns an array of items. It either is empty in case no objects found or contains objects

Update object

The method has the following signature:

async updateObject(id: string, data: object, queryHeaders?: Header[], metaHeaders?: Header[])

where

• id - Maester internal id of the object to update. E.g. '76380cae-aee3-457a-9029-d971f61e3731'. Required
• data - object to update. Required
• queryHeaders - array of objects { key: string, value: string }, current maximum - 5 items. Where key (must be lowercase) - searchable field name (see below in Get objects by query parameters section), must be unique for whole array, if specified - value must be specified as well; value - searchable field value, if specified - key must be specified as well. Note: queryHeaders could be added to an existing object and modified as well, but they can not be deleted. Optional
• metaHeaders - array of objects { key: string, value: string }, where key (must be lowercase) - meta field name, must be unique for whole array, if specified - value must be specified as well; value - meta field value, if specified - key must be specified as well. Note: metaHeaders could be added to an existing object and modified as well, but they can not be deleted. Optional

const obj = await objectStorageWrapper.updateObject(id, data);
const obj = await objectStorageWrapper.updateObject(
  id,
  data,
  [{ key: 'somequeriablefieldkey', value: 'somequeriablefieldvalue' }, { key: 'anotherqueriablefieldkey', value: 'anotherqueriablefieldvalue' }]
);
const obj = await objectStorageWrapper.updateObject(
  id,
  data,
  [{key: 'anotherqueriablefieldkey', value: 'anotherqueriablefieldvalue'}, {key: 'anotherqueriablefieldkey2', value: 'anotherqueriablefieldvalue2'}],
  [{key: 'somemetakey', value: 'somemetavalue'}]
);

Delete operations

Delete object by ID

The method has the following signature:

async deleteObjectById(id: string)

where

• id - Maester internal id of the object to delete. E.g. '76380cae-aee3-457a-9029-d971f61e3731'. Required

const obj = await objectStorageWrapper.deleteObjectById(id);

Delete objects by query parameters

The method has the following signature:

async deleteObjectsByQueryParameters(headers: Header[])

where

• headers - array of objects { key: string, value: string }, current maximum - 5 items. Where key (must be lowercase) - searchable field name, must be unique for whole array, if specified - value must be specified as well; value - searchable field value, if specified - key must be specified as well. Required

const obj = await objectStorageWrapper.deleteObjectsByQueryParameters([{key: 'somequeriablefieldkey', value: 'somequeriablefieldvalue'}]);

ObjectStorage CRUD operations

Create Object

The method has the following signature:

async add(dataOrFunc: uploadData | (() => Promise<Readable>), reqWithBodyOptions?: ReqWithBodyOptions)

where

• dataOrFunc - async function returning stream OR any data (except 'undefined').
• reqWithBodyOptions.

const obj = await objectStorage.add(data, { headers: {'x-query-somequeriablefieldkey': 'somequeriablefieldvalue'} });
const getAttachAsStream = async () => (await axios.get('https://img.jpg', { responseType: 'stream' })).data;
const obj = await objectStorage.add(getAttachAsStream, { retryOptions: { retriesCount: 5, requestTimeout: 60000 } });
);

Read operations

Get object by ID

The method has the following signature:

async getOne(objectId: string, reqOptions: ReqOptions = {})

where

• id - Maester internal id of the object to lookup. E.g. '76380cae-aee3-457a-9029-d971f61e3731'.
• reqOptions.

const { data, headers } = await objectStorage.getOne(id);
const { data: stream, headers } = await objectStorage.getOne(id, { responseType: 'stream'});

Get objects by query parameters

The method has the following signature:

async getAllByParams(params: object, reqOptions: ReqOptions = {})

where

• params - object of query params, current maximum - 5 items.
• reqOptions.

Examples:

const obj = await objectStorage.getAllByParams({ 'query[field]': 'value' });

The method returns an array of items. It either is empty in case no objects found or contains objects

Update Object

The method has the following signature:

async update(objectId: string, dataOrFunc: uploadData | (() => Promise<Readable>), reqWithBodyOptions?: ReqWithBodyOptions)

where

• objectId - id of the object to update.
• dataOrFunc - async function returning stream OR any data (except 'undefined').
• reqWithBodyOptions

const obj = await objectStorage.update(data, { headers: {'x-query-somequeriablefieldkey': 'somequeriablefieldvalue'} });
const getAttachAsStream = async () => (await axios.get('https://img.jpg', { responseType: 'stream' })).data;
const obj = await objectStorage.update(getAttachAsStream);
);

Delete operations

Delete object by ID

The method has the following signature:

async deleteOne(objectId: string, reqOptions: ReqOptions = {})

where

• id - Maester internal id of the object to delete. E.g. '76380cae-aee3-457a-9029-d971f61e3731'.
• reqOptions.

const obj = await objectStorage.deleteOne(id);
const obj = await objectStorage.deleteOne(id, { retryOptions: { retriesCount: 5, requestTimeout: 60000 } });

Delete objects by query parameters

The method has the following signature:

async deleteAllByParams(params: object, reqOptions: ReqOptions = {})

where

• params - object of query params, current maximum - 5 items.
• reqOptions.

const obj = await objectStorage.deleteAllByParams({ 'query[field]': 'value' });

Additional methods

Use method

The method has the following signature:

async use(forward: TransformMiddleware, reverse: TransformMiddleware)

where

• forward - transform middleware to use with Create and Update object operations (add, update methods).
• reverse - transform middleware to use with Get object operations (getOne, getAllByParams methods).

getHeaders method

The method has the following signature:

async getHeaders(objectId: string, reqOptions: ReqOptions = {})

where

• forward - transform middleware to use with Create and Update object operations (add, update methods).
• reverse - transform middleware to use with Get object operations (getOne, getAllByParams methods).

Handling errors

All errors thrown by library are instances of ObjectStorageClientError class. Check exported Errors property for a list of all errors classes and their properties.

Limitations

1. Both ObjectStorage and ObjectStorageWrapper could'n process undefined as values for upsert value. Also value undefined in array will be converted to null, e.g [1, 'str', undefined, null, { d: 2 }] will be saved as [1, 'str', null, null, { d: 2 }]
2. Once object was created with custom 'content-type', be aware 'content-type' could be changed automatically with next update request of this object. To avoid that provide custom 'content-type' again with next update request.
   E.g if you created objected like this const objectId = await objectStorage.add({ a: 2 }, { headers: { 'content-type': 'some-type' } }) - object will be stored with 'content-type': 'some-type'. But if you are going to update this object without passing same custom 'content-type' (await objectStorage.update(objectId, { a: 3 })) - object 'content-type' will be calculated automatically, and in this case will be set to 'application/json'.