@moddable/typings 9.5.0 → 10.0.0

package/embedded_network/http/server.d.ts

@@ -18,6 +18,9 @@
  *
  */
 
+// the manifest that supplies this module includes the manifests of these configurations
+/// <reference path="../../config/httpserver.d.ts" />
+
 declare module "embedded:network/http/server" {
     import type Listener from "embedded:io/socket/listener";
     import type TCP from "embedded:io/socket/tcp";
@@ -40,8 +43,12 @@ declare module "embedded:network/http/server" {
         onResponse?(this: HTTPConnection, response: HTTPResponse): void;
         onWritable?(this: HTTPConnection, count: number): void;
         onDone?(this: HTTPConnection): void;
-        onError?(this: HTTPConnection): void;
+        onError?(this: HTTPConnection, error: string): void;
+    }
+
+    export interface HTTPRouteTypes {
     }
+    export type HTTPRoute = HTTPConnectionHandlers | HTTPRouteTypes[keyof HTTPRouteTypes];
 
     export interface HTTPConnection extends Disposable {
         close(): void;
@@ -50,21 +57,35 @@ declare module "embedded:network/http/server" {
         respond(options: HTTPResponse): void;
         read(count?: number): ArrayBuffer | undefined;
         write(bytes?: ByteBuffer): number;
-        route: HTTPConnectionHandlers;
+        route: HTTPRoute;
         format: "buffer";
+        protocol?: string;
     }
 
-    export interface HTTPServerOptions {
+    export interface HTTPServerSocketProvider {
         io: typeof Listener;
+    }
+
+    export interface HTTPServerProvider {
+        io: typeof HTTPServer;
+        socket: HTTPServerSocketProvider;
+    }
+
+    export interface HTTPServerOptions extends Partial<HTTPServerProvider> {
+        socket: HTTPServerSocketProvider;
         port?: number;
-        onConnect(this: HTTPServer, connection: HTTPConnection): void;
+        keepAlive?: number;
+        onConnect?(this: HTTPServer, connection: HTTPConnection): void;
+        target?: any;
+        onRoute?(this: HTTPServer, request: HTTPRequest): HTTPRoute | undefined | null | false | void;
     }
 
-    class HTTPServer {
+    class HTTPServer implements Disposable {
+        target?: any;
         constructor(options: HTTPServerOptions);
         close(): void;
         readonly port: number;
+        [Symbol.dispose](): void;
     }
-    interface HTTPServer extends Disposable {}
     export default HTTPServer;
 }

package/embedded_network/interface/ethernet.d.ts

@@ -25,7 +25,7 @@ declare module "embedded:network/interface/ethernet" {
 
 	export interface EthernetConstructorOptions {
 		port?: PortSpecifier;
-		onChanged?: (property: EthernetChangedProperty) => void;
+		onChanged?: (this: Ethernet, property: EthernetChangedProperty) => void;
 	}
 
 	export interface EthernetStaticAddress {
@@ -39,7 +39,7 @@ declare module "embedded:network/interface/ethernet" {
 		static?: EthernetStaticAddress | false;
 	}
 
-	class Ethernet {
+	class Ethernet implements Disposable {
 		constructor(options: EthernetConstructorOptions);
 
 		close(): void;
@@ -50,8 +50,8 @@ declare module "embedded:network/interface/ethernet" {
 		readonly connection: number;
 		readonly address: string | undefined;
 		readonly MAC: string | undefined;
+		[Symbol.dispose](): void;
 	}
-	interface Ethernet extends Disposable {}
 
 	export default Ethernet;
 }

package/embedded_network/interface/wifi/accesspoint.d.ts

@@ -47,7 +47,7 @@ declare module "embedded:network/interface/wifi/accesspoint" {
 		portal?: string;
 	}
 
-	class WiFiAccessPoint {
+	class WiFiAccessPoint implements Disposable {
 		constructor(options: WiFiAccessPointConstructorOptions);
 
 		close(): void;
@@ -58,8 +58,8 @@ declare module "embedded:network/interface/wifi/accesspoint" {
 		readonly MAC: string | undefined;
 		readonly SSID: string | undefined;
 		readonly channel: number | undefined;
+		[Symbol.dispose](): void;
 	}
-	interface WiFiAccessPoint extends Disposable {}
 
 	export default WiFiAccessPoint;
 }

package/embedded_network/interface/wifi.d.ts

@@ -23,28 +23,34 @@ declare module "embedded:network/interface/wifi" {
 
 	export type WiFiChangedProperty = "connection" | "address";
 
+	export type WiFiSecurity = "none" | "wep" | "wpa_psk" | "wpa2_psk" | "wpa_wpa2_psk" | "wpa3_psk" | "wpa2_wpa3_psk" | "wpa2_enterprise" | "unknown" | (string & {});
+
 	export interface WiFiConstructorOptions {
 		port?: PortSpecifier;
-		onChanged?: (property: WiFiChangedProperty) => void;
+		onChanged?: (this: WiFi, property: WiFiChangedProperty) => void;
 	}
 
 	export interface WiFiScanResult {
 		SSID: string;
-		channel: number;
+		BSSID: string;
 		RSSI: number;
-		BSSID?: string;
+		channel: number;
+		security: WiFiSecurity;
 	}
 
 	export interface WiFiScanOptions {
-		onFound?: (result: WiFiScanResult) => void;
-		onComplete?: () => void;
+		onFound: (this: WiFi, result: WiFiScanResult) => void;
+		onComplete?: (this: WiFi) => void;
+		channel?: number;
+		frequency?: 2.4 | 5;
+		secure?: boolean;
 	}
 
-	export interface WiFiConnectOptions {
-		SSID: string;
+	export type WiFiConnectOptions = ({ SSID: string; BSSID?: string } | { SSID?: string; BSSID: string }) & {
 		password?: string;
-		secure?: boolean;
-	}
+		secure?: boolean;			// true to disallow connecting to an open access point
+		channel?: number;
+	};
 
 	export interface WiFiStaticAddress {
 		address: string;
@@ -52,27 +58,30 @@ declare module "embedded:network/interface/wifi" {
 		gateway: string;
 	}
 
+	// Moddable SDK extension
 	export interface WiFiConfigureOptions {
 		hostname?: string;
 		static?: WiFiStaticAddress | false;
 	}
 
-	class WiFi {
+	class WiFi implements Disposable {
 		constructor(options: WiFiConstructorOptions);
 
 		close(): void;
 		scan(options: WiFiScanOptions): void;
 		connect(options: WiFiConnectOptions): void;
 		disconnect(): void;
-		configure(options: WiFiConfigureOptions): void;
+		configure(options: WiFiConfigureOptions): void;		// Moddable SDK extension
 
 		readonly connection: number;
 		readonly address: string | undefined;
 		readonly MAC: string | undefined;
 		readonly SSID: string | undefined;
+		readonly BSSID: string | undefined;
 		readonly RSSI: number | undefined;
+		readonly channel: number | undefined;
+		[Symbol.dispose](): void;
 	}
-	interface WiFi extends Disposable {}
 
 	export default WiFi;
 }

package/embedded_network/mdns.d.ts

@@ -70,13 +70,13 @@ declare module "embedded:network/mdns" {
 		close(): void;
 	}
 
-	class DNSSD {
+	class DNSSD implements Disposable {
 		constructor(options: DNSSDOptions);
 		close(): void;
 		claim(options: ClaimOptions): ClaimInstance;
 		advertise(options: AdvertiseOptions): AdvertiseInstance;
 		discover(options: DiscoverOptions): DiscoverInstance;
+		[Symbol.dispose](): void;
 	}
-	interface DNSSD extends Disposable {}
 	export default DNSSD;
 }

package/embedded_network/mqtt/client.d.ts

@@ -1,4 +1,18 @@
+// the manifest that supplies this module includes the manifests of these configurations
+/// <reference path="../../config/mqttclient.d.ts" />
+
 declare module "embedded:network/mqtt/client" {
+  import type TCP from "embedded:io/socket/tcp";
+  import type TLS from "embedded:io/socket/tcp/tls";
+  import type { ClientSocket } from "embedded:io/socket/tcp/tls";
+  import type { DNSResolverProvider } from "embedded:network/dns/resolver/udp";
+
+  export interface MQTTClientProvider {
+    io: typeof MQTTClient,
+    dns: DNSResolverProvider,
+    socket: ClientSocket,
+  }
+
   interface onReadableOptions {
     more: boolean,
     topic?: string,
@@ -26,33 +40,58 @@ declare module "embedded:network/mqtt/client" {
     password?: string,
     id?: string,
     clean?: boolean,
-    will?: any,
+    will?: Will,
     keepAlive?: number, // milliseconds
-    onReadable?: (count: number, options: onReadableOptions) => void,
-    onWritable?: (count: number) => void,
-    onControl?: (opcode: number, message: onControlMessage) => void,
-    onClose?: () => void,
-    onError?: (error: any) => void,
-    dns: Record<string, any>,
-    socket: Record<string, any>,
+    onReadable?: (this: MQTTClient, count: number, options: onReadableOptions) => void,
+    onWritable?: (this: MQTTClient, count: number) => void,
+    onControl?: (this: MQTTClient, opcode: number, message: onControlMessage) => void,
+    onClose?: (this: MQTTClient) => void,
+    onError?: (this: MQTTClient, error: any) => void,
+    target?: any,
+    dns: DNSResolverProvider,
+    socket: ClientSocket,
   }
 
-  interface WriteOptions {
-    operation?: number,
+  interface PublishOptions {
+    operation?: typeof MQTTClient.PUBLISH,
     id?: number,
     topic: string,
     QoS?: number,
     retain?: boolean,
     duplicate?: boolean,
-    byteLength?: number,
-    items?: any[], // being lazy here
+    byteLength?: number, // total payload, when larger than this first fragment
+  }
+
+  interface SubscribeOptions {
+    operation: typeof MQTTClient.SUBSCRIBE,
+    id?: number,
+    items: { topic: string, QoS?: number }[],
   }
 
-  class MQTTClient {
+  interface UnsubscribeOptions {
+    operation: typeof MQTTClient.UNSUBSCRIBE,
+    id?: number,
+    items: { topic: string }[],
+  }
+
+  interface AcknowledgeOptions {
+    operation: typeof MQTTClient.PUBACK | typeof MQTTClient.PUBREC | typeof MQTTClient.PUBREL | typeof MQTTClient.PUBCOMP,
+    id: number,
+  }
+
+  interface SessionOptions {
+    operation: typeof MQTTClient.PINGREQ | typeof MQTTClient.DISCONNECT,
+  }
+
+  type WriteOptions = PublishOptions | SubscribeOptions | UnsubscribeOptions | AcknowledgeOptions | SessionOptions;
+
+  class MQTTClient implements Disposable {
+    target?: any
     constructor(options: Options)
-    read(count: number): ArrayBuffer
+    read(count?: number): ArrayBuffer
     read(buffer: ByteBuffer): number
-    write(data: ByteBuffer, options: WriteOptions): number
+    write(data: ByteBuffer): number // continues the publish in progress
+    write(data: ByteBuffer | null, options: WriteOptions): number
     close(): void
 
     static CONNECT: 1
@@ -69,7 +108,7 @@ declare module "embedded:network/mqtt/client" {
     static PINGREQ: 12
     static PINGRESP: 13
     static DISCONNECT: 14
+    [Symbol.dispose](): void
   }
-  interface MQTTClient extends Disposable {}
   export default MQTTClient;
 }

package/embedded_network/ntp/client.d.ts

@@ -18,10 +18,21 @@
  *
  */
 
+// the manifest that supplies this module includes the manifests of these configurations
+/// <reference path="../../config/ntp.d.ts" />
+
 declare module "embedded:network/ntp/client" {
 	import type UDP from "embedded:io/socket/udp";
 	import type Resolver from "embedded:network/dns/resolver/udp";
-	
+	import type { DNSResolverProvider } from "embedded:network/dns/resolver/udp";
+
+	export interface NTPClientProvider {
+		io: typeof NTP;
+		dns: DNSResolverProvider;
+		socket: { io: typeof UDP; [option: string]: unknown };
+		servers: string[];
+	}
+
 	export interface NTPOptions<T = any> {
 		servers: string[];
 		socket: { io: typeof UDP };
@@ -29,17 +40,14 @@ declare module "embedded:network/ntp/client" {
 		target?: T;
 	}
 	
-	export interface NTPCallback {
-		(error: null, time: number): void;
-		(error: Error): void;
-	}
+	export type NTPCallback<T = any> = (this: NTP<T>, error: Error | null, time: number) => void;
 	
-	class NTP<T = any> {
+	class NTP<T = any> implements Disposable {
 		target?: T;
 		constructor(options: NTPOptions<T>);
 		close(): void;
-		getTime(callback: NTPCallback): void;
+		getTime(callback: NTPCallback<T>): void;
+		[Symbol.dispose](): void;
 	}
-	interface NTP<T = any> extends Disposable {}
 	export default NTP;
 }

package/embedded_network/websocket/client.d.ts

@@ -21,56 +21,75 @@
 // websocketclient.d.ts
 
 declare module "embedded:network/websocket/client" {
-  interface WebSocketClientOptions {
-    onReadable?: (this: WebSocketClient, count: number, options: { more: boolean; binary: boolean }) => void;
-    onWritable?: (this: WebSocketClient, count: number) => void;
-    onControl?: (this: WebSocketClient, opcode: number, data: ArrayBuffer) => void;
-    onClose?: (this: WebSocketClient) => void;
-    onError?: (this: WebSocketClient) => void;
-    format?: "buffer" | "number";
+  import type TCP from "embedded:io/socket/tcp";
+  import type TLS from "embedded:io/socket/tcp/tls";
+  import type { ClientSocket } from "embedded:io/socket/tcp/tls";
+  import type { DNSResolverProvider } from "embedded:network/dns/resolver/udp";
+
+  export interface WebSocketClientProvider {
+    io: typeof WebSocketClient;
+    dns: DNSResolverProvider;
+    socket: ClientSocket;
+  }
+
+  export type Format = "buffer" | "number";
+
+  export interface WebSocketClientOptions<F extends Format = Format> {
+    onReadable?: (this: WebSocketClient<F>, count: number, options: { more: boolean; binary: boolean }) => void;
+    onWritable?: (this: WebSocketClient<F>, count: number) => void;
+    onControl?: (this: WebSocketClient<F>, opcode: number, data: ArrayBuffer) => void;
+    onClose?: (this: WebSocketClient<F>) => void;
+    onError?: (this: WebSocketClient<F>) => void;
+    format?: F;
     target?: any;
-    attach?: {
-      constructor: new (options: any) => any;
-    };
+    attach?: TCP;
     host?: string;
     path?: string;
     port?: number;
     protocol?: string;
     headers?: Map<string, string>;
-    dns?: {
-      io: new (options: any) => any;
-    };
-    socket?: {
-      io: new (options: any) => any;
-    };
+    dns?: DNSResolverProvider;
+    socket?: ClientSocket;
   }
 
-  interface WebSocketWriteOptions {
+  export interface WebSocketWriteOptions {
     opcode?: number;
     binary?: boolean;
     more?: boolean;
   }
 
-  class WebSocketClient {
-    constructor(options: WebSocketClientOptions);
-
+  /*
+    F is the format named in the options when the client is created. Naming it there
+    (format: "buffer") fixes the type read() with no argument returns:
+    a byte for "number", an ArrayBuffer for "buffer".
+    When the options name no format, read() is typed as returning either, because the
+    format can be changed later through the format property.
+  */
+  interface WebSocketClient<F extends Format = Format> extends Disposable {
     close(): void;
     write(data: ByteBuffer, options?: WebSocketWriteOptions): number;
-    read(): number | ArrayBuffer;
+    read(): F extends "number" ? number : ArrayBuffer;
     read(count: number): ArrayBuffer;
     read(buffer: ByteBuffer): number;
 
-    format: "buffer" | "number";
+    get format(): F;
+    set format(value: Format);
     protocol: string | undefined;
     target?: any;
 
-    static readonly text: 1;
-    static readonly binary: 2;
-    static readonly close: 8;
-    static readonly ping: 9;
-    static readonly pong: 10;
+    [Symbol.dispose](): void;
+  }
+  interface WebSocketClientConstructor {
+    new <F extends Format = Format>(options: WebSocketClientOptions<F>): WebSocketClient<F>;
+    readonly prototype: WebSocketClient;
+
+    readonly text: 1;
+    readonly binary: 2;
+    readonly close: 8;
+    readonly ping: 9;
+    readonly pong: 10;
   }
-  interface WebSocketClient extends Disposable {}
+  const WebSocketClient: WebSocketClientConstructor;
 
   export default WebSocketClient;
 }

package/embedded_provider/builtin.d.ts

@@ -1,5 +1,5 @@
 /*
-* Copyright (c) 2022 Shinya Ishikawa
+* Copyright (c) 2026 Moddable Tech, Inc.
 *
 *   This file is part of the Moddable SDK Tools.
 *
@@ -20,38 +20,44 @@
 
 
 declare module "embedded:provider/builtin" {
-  import Digital from "embedded:io/digital";
-  import DigitalBank from "embedded:io/digitalbank";
-  import Analog from "embedded:io/analog";
-  import PWM from "embedded:io/pwm";
-  import PulseCount from "embedded:io/pulsecount";
-  import I2C from "embedded:io/i2c";
-  import SMBus from "embedded:io/smbus";
-  import SPI from "embedded:io/spi";
-  import Serial from "embedded:io/serial";
-  import type { PinSpecifier } from "embedded:io/_common";
-  const device: {
-    io: {
-      Digital: typeof Digital;
-      DigitalBank: typeof DigitalBank;
-      Analog: typeof Analog;
-      PWM: typeof PWM;
-      PulseCount: typeof PulseCount;
-      I2C: typeof I2C;
-      SMBus: typeof SMBus;
-      SPI: typeof SPI;
-      Serial: typeof Serial;
-    };
-    Digital: { default: ConstructorParameters<typeof Digital>[0] };
-    DigitalBank: { default: ConstructorParameters<typeof DigitalBank>[0] };
-    Analog: { default: ConstructorParameters<typeof Analog>[0] };
-    PWM: { default: ConstructorParameters<typeof PWM>[0] };
-    PulseCount: { default: ConstructorParameters<typeof PulseCount>[0] };
-    I2C: { default: ConstructorParameters<typeof I2C>[0] };
-    SMBus: { default: ConstructorParameters<typeof SMBus>[0] };
-    SPI: { default: ConstructorParameters<typeof SPI>[0] };
-    Serial: { default: ConstructorParameters<typeof Serial>[0] };
-    pin: { [name: string]: PinSpecifier };
-  };
+  export interface Device {
+  }
+  export interface DeviceIO {
+  }
+  // the host typing of a target with a network attaches DeviceNetwork to Device; the network configurations
+  // in the build (config/dns, config/httpclient, ...) add their providers to it
+  export interface DeviceNetwork {
+  }
+
+  export interface DeviceAnalog {
+  }
+  export interface DeviceI2C {
+  }
+  export interface DeviceSPI {
+  }
+  export interface DeviceSerial {
+  }
+
+  type Speed<T, K extends keyof T> = T extends unknown ? Omit<T, K> & Partial<Pick<T, K>> : never;
+  export type AnalogBus = ConstructorParameters<typeof import("embedded:io/analog").default>[0] & { io: typeof import("embedded:io/analog").default };
+  export type I2CBus = Speed<Omit<ConstructorParameters<typeof import("embedded:io/i2c").default>[0], "address">, "hz"> & { io: typeof import("embedded:io/i2c").default };
+  export type SPIBus = Speed<ConstructorParameters<typeof import("embedded:io/spi").default>[0], "hz"> & { io: typeof import("embedded:io/spi").default };
+  export type SerialBus = Speed<ConstructorParameters<typeof import("embedded:io/serial").default>[0], "baud"> & { io: typeof import("embedded:io/serial").default };
+
+  // any function or class
+  type Callable = ((...args: never) => unknown) | (abstract new (...args: never) => unknown);
+  // values that are not remapped: functions, classes, arrays, and byte buffers
+  type Leaf = Callable | readonly unknown[] | ArrayBufferLike | ArrayBufferView;
+
+  // device after lockdown: frozen with every io resolved to a constructor
+  type Frozen<T> = T extends Leaf ? T : T extends object ? { readonly [K in keyof T]: Frozen<T[K]> } : T;
+
+  // device before lockdown (during preload)
+  type Provider = { io: Callable };
+  type IOName<C> = { [N in keyof DeviceIO]: DeviceIO[N] extends C ? N : never }[keyof DeviceIO];
+  type ProviderConfig<T> = T extends Leaf ? T : T extends object ? { -readonly [K in keyof T]: K extends "io" ? T[K] | IOName<T[K]> : ProviderConfig<T[K]> } : T;
+  export type DeviceConfig<T = Device> = T extends Leaf ? T : T extends Provider ? ProviderConfig<T> : T extends object ? { -readonly [K in keyof T]?: DeviceConfig<T[K]> } : T;
+
+  const device: Frozen<Device>;
   export default device;
 }

package/file.d.ts

@@ -22,6 +22,7 @@ declare module "file" {
   /**
    * The `File` class provides access to files.
    */
+  /** @deprecated Use the ECMA-419 files API, embedded:storage/files */
   export class File {
     constructor(path: string, write?: boolean);
     /**
@@ -50,16 +51,19 @@ declare module "file" {
   }
   type IteratorDirectoryEntry = {name: string, length: undefined};
   type IteratorFileEntry = {name: string, length: number};
+  /** @deprecated Use the ECMA-419 files API, embedded:storage/files */
   class Iterator {
     constructor(path: string);
     next(): IteratorDirectoryEntry | IteratorFileEntry | undefined;
   }
 
+  /** @deprecated Use the ECMA-419 files API, embedded:storage/files */
   class Directory {
     static create(path: string): void;
     static delete(path: string): void;
   }
 
+  /** @deprecated Use the ECMA-419 files API, embedded:storage/files */
   class System {
     static config(): {maxPathLength: number}
     static info(): {used: number, total: number};

package/flash.d.ts

@@ -19,6 +19,7 @@
 */
 
 declare module "flash" {
+  /** @deprecated Use the ECMA-419 flash API, embedded:storage/flash */
   class Flash {
     constructor(partition?: string);
     constructor(offset: number, byteLength: number);

package/global.d.ts

@@ -1,12 +1,9 @@
 declare module "global" {
 
-  import System_ from "embedded:io/system"
   import Device from "embedded:provider/builtin"
 
   export {}
   global {
-    // NOTE: `System` is non-standard and temporary to support the IO examples. Breaking changes are possible.
-    var System: typeof System_;
     var device: typeof Device;
   }
 }

package/host/default.d.ts

@@ -0,0 +1,31 @@
+/*
+* Copyright (c) 2026 Moddable Tech, Inc.
+*
+*   This file is part of the Moddable SDK Tools.
+*
+*   The Moddable SDK Tools is free software: you can redistribute it and/or modify
+*   it under the terms of the GNU General Public License as published by
+*   the Free Software Foundation, either version 3 of the License, or
+*   (at your option) any later version.
+*
+*   The Moddable SDK Tools is distributed in the hope that it will be useful,
+*   but WITHOUT ANY WARRANTY; without even the implied warranty of
+*   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+*   GNU General Public License for more details.
+*
+*   You should have received a copy of the GNU General Public License
+*   along with the Moddable SDK Tools.  If not, see <http://www.gnu.org/licenses/>.
+*
+*/
+
+// the host provider typing when no target is named: the generic host plus every standard IO class,
+// since without a manifest there is no way to know which are in the build
+/// <reference path="./generic.d.ts" />
+/// <reference path="../config/analog.d.ts" />
+/// <reference path="../config/digital.d.ts" />
+/// <reference path="../config/i2c.d.ts" />
+/// <reference path="../config/pulsecount.d.ts" />
+/// <reference path="../config/pwm.d.ts" />
+/// <reference path="../config/serial.d.ts" />
+/// <reference path="../config/socket.d.ts" />
+/// <reference path="../config/spi.d.ts" />