Calling Callbacks

Moddable SDK 9.0.0

About

Binary Data

Overview

Convert String to ArrayBuffer

Convert ArrayBuffer to String

Convert ArrayBuffers to String

Handle Errors Converting ArrayBuffer to String

Immutable ArrayBuffers

Resize an ArrayBuffer

Combine ArrayBuffers

Convert Base64 to Binary Data

Convert Binary Data to Base64

Convert Binary Data to Hex

Convert Hex to Binary Data

Calculate CRC for Binary Data

Compress Binary Data – One Buffer

Compress Binary Data – Streaming

Decompress Binary Data – One Buffer

Decompress Binary Data – Streaming

DNS

Overview

Resolve Name

Resolve Multiple Names

DNS Service Discovery

Overview

Claim Local Name

Advertise Services

Discover Services

EventSource

Overview

Connect

Connect Securely

Close

Receive

Connection Information

Files

Overview

Create, Open, and Close File

Read File

Write File

Delete File

Get File Information

Create Directory

Enumerate Directory

Delete Directory

Open Directory

HTTP

Overview

Make Request using fetch()

Make Secure Request using fetch()

Send Request Headers using fetch()

Receive Response Headers using fetch()

Send Request Body using fetch()

Make Request using HTTP Client

Make Secure Request using HTTP Client

Send Request Headers using HTTP Client

Receive Response Headers using HTTP Client

Send Request Body using HTTP Client

Implementing ECMA-419 Modules

Overview

Constructor Sets `target`

Constructor IO

Constructor Clean-up on Failure

`close()` and `[Symbol.dispose]`

Calling Callbacks

Setting Options with `configure()`

Keep Instance Surface Clean

Key-Value Storage

Overview

Read and Write Values using Web Storage

Delete Keys using Web Storage

Enumerate Keys using Web Storage

Read and Write Values using Key-Value Pair

Change Data Formats using Key-Value Pair

Delete Keys using Key-Value Pair

Enumerate Keys using Key-Value Pair

Logging

Overview

Logging with Console

Logging with trace()

MQTT

Overview

Connect to MQTT Server using MQTT()

Connect Securely to MQTT Server using MQTT()

Close Connection using MQTT()

Publish Message using MQTT()

Subscribe to Topic using MQTT()

Receive Messages using MQTT()

Get Connection Information using MQTT()

Connect to MQTT Server using MQTT Client

Connect Securely to MQTT Server using MQTT Client

Close Connection using MQTT Client

Publish Message using MQTT Client

Subscribe to Topic using MQTT Client

Receive Messages using MQTT Client

Optimizing Embedded JavaScript

Overview

When to Optimize

Know Where to Optimize

Loop through an Array

Iterate Over a String

Build a String

Avoid Copying Buffers

Accessing Properties

Map versus Object

Append to an Array

Operate on Bits

Define Class Methods

Streams

Overview

Time

Overview

Get Unix Time

Get Time of Day

Get Date

Get Time Since System Start

Get Microseconds

Set System Date and Time

Get Time and Date from Real-Time Clock

Set Real-Time Clock Time

Get Time and Date from Network

Sleep

Time Callbacks

Overview

One-Time Callback

Repeating Callback

Repeating Callback with Initial Delay

Immediate Callback

Reschedule Callback

Cancel Callback

Suspend Callback

Transport Layer Security (TLS)

Overview

Include Public Certificates

Include Private Certificates

Diagnostics

DER and PEM Certificates

WebSocket

Overview

Connect to Server using WebSocket()

Connect Securely to Server using WebSocket()

Close Connection using WebSocket()

Send Message using WebSocket()

Receive Message using WebSocket()

Get Connection Information using WebSocket()

Connect to Server using WebSocket Client

Connect Securely to Server using WebSocket Client

Close Connection using WebSocket Client

Send Message using WebSocket Client

Receive Message using WebSocket Client

Control Messages using WebSocket Client

Connect to Server using WebSocketStream

Connect Securely to Server using WebSocketStream

Close Connection using WebSocketStream

Send Message using WebSocketStream

Receive Message using WebSocketStream

Wi-Fi

Overview

Scan for Access Points

Scan Continuously for Access Points

Connect

Reconnect Automatically

Disconnect

Get Connection Information

Use Static IP Address

Calling Callbacks

ECMA-419 uses callbacks extensively to deliver notifications. Callbacks are used instead of Events or Promises because they are typically more efficient. Often callbacks are passed to the constructor to be called later.

Callbacks may only be called when there is nothing else running. Specifically this means that methods defined by ECMA-419 may not directly call a callback. This eliminates common bugs that happen when a callback is invoked at an unexpected time and it ensures that there is consistent free stack space for the callback's execution.

A timer is a common way to defer execution of a callback to meet this requirement.

import Timer from "timer";

class ExampleTCP {
	#onWritable;
	#timer;

	constructor(options) {
		this.#onWritable = options.onWritable;
		if (this.#onWritable)
			this.#timer = Timer.set(() => this.#onWritable());
	}
	close() {
		Timer.clear(this.#timer);
		this.#timer = undefined;
	}
}

Callbacks must be invoked with this set to the calling instance (scripts can override this using function.prototype.bind() or arrow functions). The preceding examples calls onWritable with the correct this because the callback is called through a private field, this.#onWritable. If a callback is stored on another object, use function.prototype.call() to set this to the instance.

import Timer from "timer";

class ExampleTCP {
	#callbacks = {};
	#timer;

	constructor(options) {
		const {onWritable} = options;
		if (onWritable) {
			this.#callbacks.onWritable = onWritable;
			this.#timer = Timer.set(() => this.#callbacks.onWritable.call(this));
		}
	}
	close() {
		Timer.clear(this.#timer);
		this.#timer = undefined;
	}
}

Perhaps the most misunderstood callback is onError(). This callback is called when the instance detects a failure outside of a public method call. For example, when a TCP socket unexpectedly disconnects.

If an error occurs within a public API call, usually the right thing to do is throw an exception immediately. If it is appropriate to call onError(), the callback needs to be deferred as shown above using a Timer.

A common mistake is invoking onError() from the constructor. The constructor is a public API, it cannot invoke callbacks directly. Therefore, it should throw an exception.