@nowtilus/nemo-lib

NEMO Library

Quick Start

install

  npm i -S @nowtilus/nemo-lib

usage

const { storageAdapter, nemoResources } = require("@nowtilus/nemo-lib");

// Working with Nemo Resources
const nemo = await nemoResources.getConnectedNemoClient({
  origin: NEMO_ORIGIN,
  apiKey: NEMO_API_KEY
});
await nemoResources.message.create(messageObject);

// Using the storage adapter
const storage = storageAdapter.Storage.create({
  type: "azure",
  account: "[your-account-name]",
  key: process.env.KEY
});
storage.list(); // lists all files in the blob storage

Use-Cases

• Every NEMO service provides an API to create, read, update and delete resources. To simplify the interaction between services the nemo-lib can be used in a unified manner.
• From time to time there are services that need to implement the same functionality. To reduce code duplication the nemo-lib is a good place to store those functions.

NEMO Service Resources

The following resources are provided via nemo-lib

// messages
nemo.messages.create(message);

// titles
nemo.titles.getTotalCount();
nemo.titles.get(uuid); // returns the title with the given uuid
nemo.titles.get(filter); // returns a list of titles filtered by the given filter object - e.g.: {studio: 'Universal'}
nemo.titles.create(title); // creates the given title object
nemo.titles.update(title); // updates the given title object
nemo.titles.upsert(title); // creates or updates the given title if it exists
nemo.titles.delete(uuid); // deletes the title with the given uuid

// medias
nemo.medias.getTotalCount();
nemo.medias.get(uuid); // returns the media with the given uuid
nemo.medias.get(filter); // returns a list of medias filtered by the given filter object
nemo.medias.create(media); // creates the given media object
nemo.medias.update(media); // updates the given media object
nemo.medias.upsert(media); // creates or updates the given media if it exists
nemo.medias.delete(uuid); // deletes the media with the given uuid

// storages
nemo.storages.getTotalCount();
nemo.storages.get(uuid); // returns the storage with the given uuid
nemo.storages.get(filter); // returns a list of storages filtered by the given filter object
nemo.storages.create(storage); // creates the given storage object
nemo.storages.update(storage); // updates the given storage object
nemo.storages.upsert(storage); // creates or updates the given storage if it exists
nemo.storages.delete(uuid); // deletes the storage with the given uuid

// jobs
nemo.jobs.getTotalCount();
nemo.jobs.get(uuid); // returns the job with the given uuid
nemo.jobs.get(filter); // returns a list of jobs filtered by the given filter object
nemo.jobs.create(job); // creates the given job object
nemo.jobs.update(job); // updates the given job object
nemo.jobs.upsert(job); // creates or updates the given job if it exists
nemo.jobs.delete(uuid); // deletes the job with the given uuid

// contracts
nemo.contracts.get(filter); // returns a list of contracts filtered by the given filter object
nemo.contracts.create(contract); // creates the given contract object
nemo.contracts.update(contract); // updates the given contract object

// promotions
nemo.promotions.get(filter); // returns a list of promotions filtered by the given filter object
nemo.promotions.create(promotion); // creates the given promotion object

// licenses
nemo.licenses.get(uuid); // returns the licenses for a title with the uuid

Connect to NEMO

There are multiple authentication scenarios:

• Connect without authentication (is only relevant if you are requesting resources in the back end from another back end component that is in the same network)
• Connect with API-Key (this especially makes sense if you are requesting the API from another service from a different network)
• Connect with username and password (is appropriate if you are developing a frontend and want human users to be logged in)

Connect without authentication (with getConnectedNemoClient helper)

const { getConnectedNemoClient } = require("@nowtilus/nemo-lib").nemoResources;
const nemo = await getConnectedNemoClient({
  origin: NEMO_ORIGIN,
  password: NEMO_PASSWORD,
  user: NEMO_USER
});

Connect with API-Key (with instantiating NemoFactory manually)

const NemoFactory = require("@nowtilus/nemo-lib").nemoResources;
const nemoClient = new NemoFactory({
  origin: NEMO_ORIGIN,
  apiKey: NEMO_API_KEY
});
nemo = await nemoClient.connect();

Fire and forget

As fire and forget implementation you can simply call the message. Any error or non 2xx response ocuring while making the request wiill be logged to the console.

nemo.messages.create(message);

Waiting for the feedback

The methods are promise based and will throw any error or non-2xx respnse.

nemo.messages
  .create(message)
  .then(result => console.log(`The created message: ${JSON.stringify(result)}`))
  .catch(e => console.error(`An Error ocured: ${JSON.stringify(e)}`));

or async await style

(async () => {
  try {
    const result = await nemo.messages.create(message);
    console.log(`The created message: ${JSON.stringify(result)}`);
  } catch (e) {
    console.error(`An Error ocured: ${JSON.stringify(e)}`);
  }
})();

Options

To control the behaviour of the request in more detail you can specify options. Those are as unified as possible. E.g. for every resource.read method you'll find a "limit" and "offset" option.

NEMO Storage Adapter Module

The storage adapter provides a unified streaming api to move files easily between different storages. E.g. Download a file from a url and pipe it to an internal Azure or AWS storage.

Features:

• Internal complexity of using different storages is completely abstracted away
• No need to have enough disc space thanks to streaming
• The library can be used to build CLI tools that support unix pipes (e.g. my-cli | grep "search-text" | sort - r)

Supported Storages

Available:

• File System (local hdd or any mounted storage)
• Azure Blob Storage
• HTTP (read only)

Planned:

• AWS S3

Storages/ StorageAdapter have the following methods

Storage Class

.list()

list(target) → {Promise}

Lists all files in a provided directory. The directory is always relative to the defined root directory. For Azure this is the storage-account root. For the local file system it's the pwd but can be defined at instantiation.

usage:

const target = "lib";
list(target).then(
  libDir => console.log(libDir) // lists the contents for the lib directory
);

Parameters:

Name	Type	Description
target	string	path to folder

Returns:

• resolved with list of files and directories or rejects with error
• Type: Promise

.getDetails(target)

getDetails(target) → {Promise}

Retrieve the details of a file

Parameters:

Name	Type	Description
target	string	path to file

Returns:

• resolvs with fileInfo (detailed information about the file) or rejects with error
• Type: Promise

.delete()

delete(target) → {Promise}

Remove file or directory

Parameters:

Name	Type	Description
target	string	path to target file or directory

Returns:

• resolves with deletion result or rejects with error
• Type: Promise

StorageAdapter Class

.copy()

(static) copy(readStream, writeStream) → {Promise}

Pipe a read stream to a write stream and resolves when finished copying

Parameters:

Name	Type	Description
readStream	Readable	stream to read from
writeStream	Writable	stream to write to

Returns:

• resolves with success message or rejects with error
• Type: Promise

.move()

(static) move(readStream, writeStream) → {Promise}

Pipe a read stream to a write stream and deletes surce file on finish

Parameters:

Name	Type	Description
readStream	Readable	stream to read from
writeStream	Writable	stream to write to

Returns:

• resolves with success message or rejects with error
• Type: Promise

Examples

Actions on one storage

Note:

All read processes have the following success response (not all fields are provided by every storage - fields that are not available are set to null)

{
  name: 'maxresdefault.jpg',
  size: '75477',
  modifiedAt: 'Mon, 18 Dec 2017 12:18:44 GMT', // js date object
  createdAt: 'Mon, 18 Dec 2017 12:18:44 GMT' // js date object
}

All streaming and write processes will resolve with an success message or reject with an error

List files of a storage

const localStorage = require("nemo-lib").Storage.create({
  type: "local",
  root: "."
});

localStorage
  .list("examples")
  .then(result => {
    console.log(result.map(r => r.name)); // --> [ 'http-to-azure.js', 'local-adapter.js' ]
  })
  .catch(e => console.error(e));

Get file details

const httpStorage = require("nemo-lib").Storage.create("http");

httpStorage
  .getDetails(
    "https://www.elastic.co/assets/blt3541c4519daa9d09/maxresdefault.jpg"
  )
  .then(result => {
    console.log(result);
    /*
      {
        name: 'maxresdefault.jpg',
        size: '75477',
        modifiedAt: 'Mon, 18 Dec 2017 12:18:44 GMT',
        createdAt: 'Mon, 18 Dec 2017 12:18:44 GMT'
      }
    */
  })
  .catch(e => console.error(e));

Delete a blob on an Azure storage

const azureStorage = require("nemo-lib").Storage.create({
  type: "azure",
  account: "nowtilusingeststaging",
  key: process.env.KEY
});

azureStorage
  .delete("quality-assurance/nowtilus.png")
  .then(result => {
    console.log(result); // --> 'Deleted quality-assurance/nowtilus.png'
  })
  .catch(e => console.error(e));

More examples for single storage actions

• Local storage: ./examples/storage-adapter/local-storage.js
• Azure storage: ./examples/storage-adapter/azure-storage.js

Actions between storages

Stream from http to azure storage

const Adapter = require("nemo-lib").StorageAdapter;
const Storage = require("nemo-lib").Storage;

// instantiate an adapter for http
const httpStorage = Storage.create("http");

// instantiate an adapter for azure-blob
const azureStorage = Storage.create({
  type: "azure",
  account: "myteststorage",
  key: process.env.KEY
});

// define the https source
const source =
  "https://static.wixstatic.com/media/ef8b8b_910bcc934fa740c4a020b57b54686b35~mv2.png/v1/fill/w_231,h_33,al_c,q_90/nowtilus-sRGB-XL.webp";
const readStream = httpStorage.createReadStream(source);

// create a write stream to the target
const writeStream = azureStorage.createWriteStream(
  "quality-assurance/nowtilus.png"
);

// copy source to target
Adapter.copy(readStream, writeStream)
  .then(r => console.log(`Stream finished: ${JSON.stringify(r)}`))
  .catch(e => console.log(e));

More examples for stream actions

• Copy from HTTP Url to Azure Blob Storage: ./examples/storage-adapter/http-to-azure.js

Contribution Guidance

• Crucial to success
• Always (close to) 100% test coverage
• Stable