GUIDES Implementing ECMA-419 Modules Setting Options with `configure()`
About
Binary Data
DNS
DNS Service Discovery
EventSource
Files
HTTP
Implementing ECMA-419 Modules
Key-Value Storage
Logging
MQTT
Optimizing Embedded JavaScript
Streams
Time
Time Callbacks
Transport Layer Security (TLS)
WebSocket
Wi-Fi
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
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

Setting Options with configure()

ECMA-419 uses configure() extensively to change the settings of an instance. The committee chose the general-purpose configure() over dozens of special-purpose, limited-use APIs. This keeps the API small and understandable. It provides a simple way to extend the API for features specific to a single hardware component. It can also be more efficient as setting several properties at once often allows combining what would otherwise be several hardware transactions. In addition, configure() reflects a common hardware programming paradigm, the omnipresent ioctl.

globalThis.screen.configure({
	flip: "h",
	brightness: 1.0,
	rotation: 90
});

Note that configure() is only to configure the instance's behavior, not how the instance communicates with the hardware. For example, it should not be used to change the baud rate used to communicate with a GPS sensor, but could be used to change the target accuracy of the GPS location.

ECMA-419 defines the hardware connection to be fixed at the time of construction. To modify communication properties, close the instance and reopen a new one.

By definition, configure() only changes the properties present at the root of the options object. The absence of a property means "don't change" not "reset to default." A typical implementation uses in to check for the existence of known properties. Unknown properties are silently ignored.

class DisplayExample {
	flags = 0;
	constructor() { /* placeholder */ }
	configure(options) {
		let flags = this.flags;
		if ("flip" in options) {
			const value = ["", "h", "v", "hv"].indexOf(options.flip);
			if (value < 0)
				throw new Error(`invalid flip: ${options.flip}`);
			flags = (flags & ~0x03) | value;
		}
		if ("rotation" in options) {
			flags &= (~0x03 << 2);
			flags |= (Math.idiv(options.rotation, 90) & 0x03) << 2;
		}
		if (flags !== this.flags) {
			/* set modified flags on hardware */
		}
	}
}

When a new instance is created, it can be useful to reset all hardware options to a known state. This is particularly important after a soft reset, where the hardware component is not powered down. Some hardware components have a reset command or pin for reset. For others, you may need to modify some settings directly. A convenient way to do this can be to call configure() from the constructor.

class DisplayExample {
	flags = 0;
	constructor() {
		/* initialize hardware connection */
		this.configure({
			flip: "",
			brightness: 0.5,
			rotation: 0
		});
	}
	configure(options) {
			/* as in the above example */
	}
}