// To make this API module available simply require max-api
const maxAPI = require("max-api");

Members

static, constant MESSAGE_TYPES :String

Built-in message types used for generic event handling

Properties:

Name	Type	Description
ALL	String	Generic Type for *all* kinds of messages
BANG	String	Bang message type
DICT	String	Dictionary message type
NUMBER	String	Number message type
LIST	String	List message type

static, constant POST_LEVELS :String

Post/Log Levels

Properties:

Name	Type	Description
ERROR	String	error level messages
INFO	String	info level messages
WARN	String	warn level messages

Methods

static addHandler(msg, handler)

Set a handler/callback function for the given message

Parameters:

Name	Type	Description
msg	module:max-api.MessageIdentifier	The message identifier to set the handler for
handler	module:max-api.MessageHandler	The message handler to add

static addHandlers(handlers)

Bulk register a set of handlers provided in an object fashion

Parameters:

Name	Type	Description
handlers	Object	The handler objects

Example

const maxAPI = require("max-api");

const handlers = {
  [MESSAGE_TYPES.BANG]: () => {
    console.log("got a bang");
  },
  [MESSAGE_TYPES.NUMBER]: (num) => {
  },
  my_message: () => {
    console.log("got my_message");
  },
  my_message_with_args: (arg1, arg2) => {
    console.log("got my arged message: ${arg1}, ${arg2} ");
  }
  [MESSAGE_TYPES.ALL]: (handled, ...args) => {
    console.log("This will be called for ALL messages");
    console.log(`The following inlet event was ${!handled ? "not " : "" }handled`);
    console.log(args);
  }
};

maxAPI.addHandlers(handlers);

static getDict(id) → {Promise.<module:max-api.Dict, Error>}

Access the contents of a dictionary in Max

Parameters:

Name	Type	Description
id	module:max-api.DictIdentifier	The identifier of the dictionary

Returns:

Promise.<module:max-api.Dict, Error> - Return the dictionary if resolved or an Error if rejected

static outlet(…anything) → {Promise.<null, Error>}

Outlets the given value of the object's outlet in Max

Parameters:

Name	Type	Attributes	Description
anything	module:max-api.Anything	<repeatable>	The value to output

Returns:

Promise.<null, Error> - Returns null if resolved or an Error if rejected

static outletBang() → {Promise.<null, Error>}

Sends a bang out of the object's outlet

Returns:

Promise.<null, Error> - Returns null if resolved or an Error if rejected

static post(…anything, level) → {Promise.<null, Error>}

Print the given value to the Max console

Parameters:

Name	Type	Attributes	Default	Description
anything	module:max-api.Anything	<repeatable>		The value to post
level	module:max-api.POST_LEVELS		POST_LEVELS.INFO	The log level of the post

Returns:

Promise.<null, Error> - Returns null if resolved or an Error if rejected

static removeHandler(msg, handler)

Set a handler/callback function for the given message

Parameters:

Name	Type	Description
msg	module:max-api.MessageIdentifier	The message identifier to remove the handler for
handler	module:max-api.MessageHandler	The message handler to remove

static removeHandlers(msgopt)

Remove all inlet handlers for the given MessageIdentifier. If no identifer is provided this function call removes *all* inlet handlers for *all* messages

Parameters:

Name	Type	Attributes	Description
msg	module:max-api.MessageIdentifier	<optional>	The message identifier to remove the handler for

static setDict(id, content) → {Promise.<module:max-api.Dict, Error>}

Overrides the *entire* content of a dictionary in Max

Parameters:

Name	Type	Description
id	module:max-api.DictIdentifier	The identifier of the dictionary
content	module:max-api.Dict	The new content of the dictionary

Returns:

Promise.<module:max-api.Dict, Error> - Return the updated dictionary if resolved or an Error if rejected

static updateDict(id, path, value) → {Promise.<module:max-api.Dict, Error>}

Updates the content of a dictionary in Max at the given path with the given value

Parameters:

Name	Type	Description
id	module:max-api.DictIdentifier	The identifier of the dictionary
path	module:max-api.DictPath	The path of the value change within the dictionary
value	module:max-api.Anything	The value to set at this path

Returns:

Promise.<module:max-api.Dict, Error> - Return the updated dictionary if resolved or an Error if rejected

Type Definitions

Anything

Mirroring the "anything" type known in Max. Can be lists (represented as array), numbers, strings and dictionaries

Example

const list = ["this", "is", "a", "list", 1, 2, 3];
const str = "this is a string message";
const numi = 42;
const numf = 42.42;
const dict = { "my": "dict" };

Dict

Dicts in Max are very similiar to simple, JS Object structures. Therefore the type is simply an object representing the contents in a JSON like structure

Example

const dict = {
  "my": "content",
  "is": {
    "here", "!",
    "1": 2,
    "a": [0,1,2]
  }
};

DictIdentifier

Dictionaries are referenced by a unique String identifier . So use this type to interact with dicts defined in Max

Example

// in Max [dit mydict]

const dictId = "mydict";
try {
  const dict = await maxAPI.getDict(dictId);
  // dict contains the dict's contents
} catch (err) {
  // handle Error here
}

DictPath

A DictPath is a string describing the access path to a portion of content within a Dict.

Example

const dict = {
  a: 1,
  b: {
    c: 2
  },
  d: {
    e: {
      f: 3
    }
  },
  h: [0, 1, 2, 3]
};

const pathToA = "a"; // 1
const pathToC = "b.c"; // 2
const pathtoE = "d.e"; // { f: 3 }
const pathToF = "d.e.f"; // 3
const arrayAccess = "h[1]"; // 1

MessageHandler()

Message Handlers are function callbacks assigned to inlet messages from Max.

MessageIdentifier

A message identifier is the message symbol received from Max.