Type Annotations

Backendless uses JSDoc-based annotations in the deployed JavaScript code to extract information about method names, their types and the method return types. This information is used for several purposes. For instance, Backendless Console uses the type information to build service invocation user interface with a form for the input parameters. Additionally, the type information is used for the native client SDK generation.

Consider the following example which declares three parameters and a return type:

/**
   * @param {string} arg1
   * @param {boolean} arg2
   * @param {number} arg3
   * @return {Array.<CustomType>}
   */ 
  foo( arg1, arg2, arg3 ) {
    return [];
  }

The @param annotations declare the argument types and names. The @return annotation declares the return type.

The general syntax for the @param annotation is:

@param {type} argument-name

where:

Argument	Description
type	a predefined or a custom type. Can be string, boolean, number, Array, Object or a custom object type. Must be surrounded by the curly brackets.
argument-name	name of the argument which will be displayed in Backendless console and used in the generated native SDKs

The @return annotation syntax is:

@return {Promise<type> | <type>}

where:

Argument	Description
type	a predefined or a custom type. Can be string, boolean, number, void, Array, Object or a custom type.

In either case (whether service method returns Promise or specific data) Backendless will use the concrete type for the code generation purposes.

Arrays

For the array types, the syntax supports type definition for the array elements using the following format:

Array<type>

where type can be recursively defined using the same types applicable for the @param annotation. For example, the following code includes a  type definition for a parameter which can be an array of strings:

/**
   * @param {Array<string>} arg1
   */ 
  foo( arg1 ) {
   ...
  }

Custom Object Types

Backendless supports two ways for declaring custom object types - the first one is with JS class definition and the second is by using the @typedefannotation. The JS class definition approach requires that a JS class is declared and registered with Backendless. Consider the example below which declares and registers a custom type:

class Order {
  constructor(items) {
    super();

    /**
     * @type {Array.<string>}
     */
    this.items = items;

    /**
     * @type {number}
     */
    this.orderPrice = 0;
  }
}

Backendless.ServerCode.addType(Order);

Notice that the properties of the Order class, are also declared using the @type annotations - this helps Backendless to understand and create a complete "schema" for the data type. Additionally, the type must be registered with Backendless using the following call:

Backendless.ServerCode.addType(Order);

where the argument of the addType method is a reference to the custom type class.

The second approach for declaring a custom type is by using an annotation. With this approach, a data type class definition is not required. The example below declares a data type which can be used in other @param, @return and @type annotations without the actual class present in the application:

/**
   * @typedef {Object} ShoppingItem
   * @property {string} objectId
   * @property {string} product
   * @property {number} price
   * @property {number} quantity
   */

The @typedef annotation has the following syntax:

@typedef {base type} TypeName  
@property {type} property-name1  
@property {type} property-nameN

where:

Argument	Description
base type	the parent type for the declared type. If base type is another custom type then the TypeName type inherits all the properties from base type.
TypeName	name assigned to the custom data type
type	a type for the property identified by property-name1..N

Once a type is defined with @typedef, it can be used in all {type} definitions, for example:

/**
   * @typedef {Object} Order
   * @property {String} orderNumber
   * @property {Number} customerName
   */

  /**
   * @param {Order} order
   * @returns {void}
   */
  processOrder(order) {
   ...
  }

Method Visibility

By default all methods for a class registered as a service become API service operations. This may not be desirable for every method. To exclude a method from the list of the API operations use the following annotation:

/**
   * @private
   */
  thisMethodIsPrivate() {
   ...  
  }