Skip to content

Latest commit

 

History

History
166 lines (114 loc) · 5.65 KB

README.md

File metadata and controls

166 lines (114 loc) · 5.65 KB
Raw

@moralisweb3/common-core

The @moralisweb3/common-core should be used in every application that uses Moralis. It is already included if you install the unbrella package moralis.

The core responsibilities of this package are

  • Hanlding communication between packages. This is done by registering and requesting modules.
  • Moralis Errors
  • Controllers like the LoggerController and RequestController that can be used in other packages
  • Defining reusable DataTypes, to ensure uniform data formatting accross all packages
  • Global types and classes that are used in other packages
  • Common utilites

Table of contents

Modules

Registering modules via registerModules()

Note: this is automatically handled when using the moralis umbrella package

When you import packages from moralis @moralisweb3/xxx, you need to let this core package know what modules you are using. This is required to enable cross-communication between different modules.

You can do this by using the registerModules() function. This should be done before calling any Moralis logic. Ideally this should be at the top of your code, just after the imports.

Example when using Moralis with the evm network, evm api and server

import { Core } from '@moralisweb3/common-core';
import { EvmApi } from '@moralisweb3/evm-api';

Core.registerModules([EvmApi]);

Start all modules with start()

You can start every package separately via a start() function. But easier is to call the start() function in the core package. This will start (initialise) all registered modules.

You can provide a configuration object (see Config). Some config options are required, depending on what packages you have registered (for example you will need a apiKey for any api package).

import * as Core from '@moralisweb3/common-core';

Core.start({
  apiKey: '<YOUR_API_KEY>',
});

As argument you can provide a partial config object, as described in Config.

Config

You can set the config when you call Core.start. Possible options and default values are can be found in configOptions

Controllers

LoggerController

The LoggerController is used in every package as replacement for console.log, console.warn and console.error. In the config you can specify the logLevel:

enum LogLevel {
  VERBOSE = 5,
  DEBUG = 4,
  INFO = 3,
  WARNING = 2,
  ERROR = 1,
  OFF = 0,
}

By specifying a loglevel, any logs up and until that number will be emitted. For example, by specifying LogLevel.INFO, all logs with the level LogLevel.INFO, LogLevel.WARNING and LogLevel.ERROR will be emitted.

Using the LoggerController in a package is as simple as:

const logger = new Logger('moduleName');
logger.warning('this is a warning');

RequestController

the RequestController is a generalized way to handle any external request.

get request

await RequestController.get(url, params, options, abortSignal);

params: an object with searchparams. For example:

const params = {
  name: 'batman',
};

options: an object with possible options (See RequestController for possible options)

abortSignal: a signal from an AbortController, to cancel the request.

post request

await RequestController.post(url, params, body, options, abortSignal);

Accepts the same options as get(), with the addition of body, which is an (JSON) object.

Errors

Errors within Moralis are an instance of MoralisError. These are extended into a few different classes:

  • CoreError
  • MoralisApiError

Which are used in there respective packages. Creating a new error must accept the following 2 params:

  • code: a valid ErrorCode
  • message: a descriptive message for the user

Additionally the following params can be provided for more information

  • details: an object with additional data
  • cause: in case the MoralisError is caused by another Error, you should provide this Error as a cause

Example:

throw new MoralisServerError({
  code: NetworkErrorCode.GENERIC_SERVER_ERROR,
  message: 'Make sure to read the docs',
  details: {
    name: 'Gandalf',
  },
});

Data Types

Moralis DataTypes are used everywhere to enforce consistency and utilities for devs. The core benefits of them are:

  • Create with different data formats
  • Internally the data is parsed into a single type format
  • A format() function is used to format the datatype to its requested format. This can globally be configured in the config, or overwritten by giving a param
  • Utility functions as:
    • Equality checks
    • Formatted data

If a datatype has a DataType.create() function, then it should be created via this function rather than using new DataType. For example EvmChain accepts an EvmChainish as input value. This can be a string, number or EvmChain. In case a EvmChain is provided, no new instance is created, but that instance is returned directly. This makes it possible to make generalized functions where we accept a number/string/existing EvmChain as argument