@moddable/typings 9.5.0 → 10.0.0

package/embedded_io/serial.d.ts

@@ -19,44 +19,61 @@
 */
 
 declare module "embedded:io/serial" {
-  import { PinSpecifier, PortSpecifier } from "embedded:io/_common";
-  class Serial {
-    constructor(options: ({
+  import { PinSpecifier, PortSpecifier, IOOptions } from "embedded:io/_common";
+  export type Format = "number" | "buffer";
+
+  export type Options<F extends Format = Format> = IOOptions<"Serial", ({
       receive: PinSpecifier;
       transmit?: PinSpecifier;
     } | {
-      recevice?: PinSpecifier;
+      receive?: PinSpecifier;
       transmit: PinSpecifier;
     }) & {
-      baud: number;
-      flowControl?: "hardware" | "none";
       dataTerminalReady?: PinSpecifier;
       requestToSend?: PinSpecifier;
       clearToSend?: PinSpecifier;
       dataSetReady?: PinSpecifier;
       port: PortSpecifier;
-      onReadable?: (this: Serial, bytes: number) => void;
-      onWritable?: (this: Serial, bytes: number) => void;
-      format?: "number" | "buffer";
+    }, {
+      baud: number;
+      flowControl?: "hardware" | "none";
+      onReadable?: (this: Serial<F>, bytes: number) => void;
+      onWritable?: (this: Serial<F>, bytes: number) => void;
+      format?: F;
       target?: any;
-    });
+    }>;
+
+  /*
+    F is the format named in the options when the serial port 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 Serial<F extends Format = Format> extends Disposable {
+    target?: any;
     readonly resolution: number;
     close(): void;
-    read(): number | ArrayBuffer | undefined;
+    read(): (F extends "number" ? number : ArrayBuffer) | undefined;
     read(byteLength: number): ArrayBuffer | undefined;
     read(buffer: ByteBuffer): number | undefined;
     write(value: number | ByteBuffer): void;
     flush(): void;
     flush(input: number, output: number): void;
     set(options: {
-      dataTerminalReady?: PinSpecifier;
-      requestToSend?: PinSpecifier;
+      dataTerminalReady?: boolean;
+      requestToSend?: boolean;
       break?: boolean;
     }): void
-    get format(): "number" | "buffer"
-    set format(value: "number" | "buffer")
+    get format(): F
+    set format(value: Format)
+    [Symbol.dispose](): void;
+  }
+  interface SerialConstructor {
+    new <F extends Format = Format>(options: Options<F>): Serial<F>;
+    readonly prototype: Serial;
   }
-  interface Serial extends Disposable {}
+  const Serial: SerialConstructor;
 
   export default Serial;
 }

package/embedded_io/socket/listener.d.ts

@@ -20,7 +20,8 @@
 
 declare module "embedded:io/socket/listener" {
   import TCP from "embedded:io/socket/tcp"
-  class Listener {
+  class Listener implements Disposable {
+    target?: any;
     constructor(options: {
       port?: number;
       address?: string;
@@ -33,7 +34,7 @@ declare module "embedded:io/socket/listener" {
     get format(): "socket/tcp"
     set format(value: "socket/tcp")
     readonly port: number;
+    [Symbol.dispose](): void;
   }
-  interface Listener extends Disposable {}
   export default Listener;
 }

package/embedded_io/socket/tcp/tls.d.ts

@@ -22,33 +22,62 @@ declare module "embedded:io/socket/tcp/tls" {
     verify?: boolean
   }
 
+  export type Format = "number" | "buffer"
+
+  /*
+    The socket property of a network client provider, and of the options of a network client.
+    The client creates its socket with io, passing the other properties as options.
+    For a secure connection io is TLS, tls has the TLS options (the client supplies host),
+    and TCP is the socket TLS runs over.
+  */
+  export type ClientSocket = {
+    io: typeof TCP | typeof TLS
+    tls?: Partial<TLSOptions>
+    TCP?: { io: typeof TCP, [option: string]: unknown }
+    [option: string]: unknown
+  }
+
   /** Extends the TCP socket's options object. Listed explicitly so the callbacks
       can be typed with `this` as the TLS socket rather than the TCP socket. */
-  export type Options = {
+  export type Options<F extends Format = Format> = {
     address: string
     port: number
     noDelay?: boolean
-    format?: "number" | "buffer"
+    format?: F
     target?: any
-    onReadable?: (this: TLSSocket, bytes: number) => void
-    onWritable?: (this: TLSSocket, bytes: number) => void
-    onError?: (this: TLSSocket) => void
+    onReadable?: (this: TLS<F>, bytes: number) => void
+    onWritable?: (this: TLS<F>, bytes: number) => void
+    onError?: (this: TLS<F>) => void
 
     tls: TLSOptions
     /** The TCP socket this TLS socket runs over. A Moddable SDK extension. */
     TCP: { io: new (options: TCPOptions) => TCP } & Partial<TCPOptions>
   }
 
-  class TLSSocket {
-    constructor(options: Options)
+  /*
+    F is the format named in the options when the socket 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 TLS<F extends Format = Format> extends Disposable {
+    target?: any
     close(): void
-    read(): number | ArrayBuffer
+    readonly remoteAddress: string | undefined
+    readonly remotePort: number | undefined
+    read(): F extends "number" ? number : ArrayBuffer
     read(byteLength: number): ArrayBuffer
     read(buffer: ByteBuffer): number
     write(buffer: ByteBuffer, options?: { more?: boolean, byteLength?: number }): number
-    get format(): "number" | "buffer"
-    set format(value: "number" | "buffer")
+    get format(): F
+    set format(value: Format)
+    [Symbol.dispose](): void
+  }
+  interface TLSConstructor {
+    new <F extends Format = Format>(options: Options<F>): TLS<F>
+    readonly prototype: TLS
   }
-  interface TLSSocket extends Disposable {}
-  export default TLSSocket;
+  const TLS: TLSConstructor
+  export default TLS;
 }

package/embedded_io/socket/tcp.d.ts

@@ -19,32 +19,46 @@
 */
 
 declare module "embedded:io/socket/tcp" {
-  export type Options = (({
+  export type Format = "number" | "buffer";
+
+  export type Options<F extends Format = Format> = (({
     address: string;
     port: number;
   }) | {
     from: TCP;
   }) & {
     noDelay?: boolean;
-    onReadable?: (this: TCP, bytes: number) => void;
-    onWritable?: (this: TCP, bytes: number) => void;
-    onError?: (this: TCP) => void;
-    format?: "number" | "buffer";
+    onReadable?: (this: TCP<F>, bytes: number) => void;
+    onWritable?: (this: TCP<F>, bytes: number) => void;
+    onError?: (this: TCP<F>) => void;
+    format?: F;
     target?: any;
   };
-  
-  class TCP {
-    constructor(options: Options)
+
+  /*
+    F is the format named in the options when the socket 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 TCP<F extends Format = Format> extends Disposable {
+    target?: any;
     readonly remoteAddress: string | undefined;
     readonly remotePort: number | undefined;
-    read(): number | ArrayBuffer;
+    read(): F extends "number" ? number : ArrayBuffer;
     read(byteLength: number): ArrayBuffer;
     read(buffer: ByteBuffer): number;
     write(value: number | ByteBuffer): number;
     close(): void;
-    get format(): "number" | "buffer"
-    set format(value: "number" | "buffer")
+    get format(): F
+    set format(value: Format)
+    [Symbol.dispose](): void;
+  }
+  interface TCPConstructor {
+    new <F extends Format = Format>(options: Options<F>): TCP<F>;
+    readonly prototype: TCP;
   }
-  interface TCP extends Disposable {}
+  const TCP: TCPConstructor;
   export default TCP;
 }

package/embedded_io/socket/udp.d.ts

@@ -1,5 +1,5 @@
 /*
-* Copyright (c) 2022-2025 Shinya Ishikawa
+* Copyright (c) 2022-2026 Shinya Ishikawa
 *
 *   This file is part of the Moddable SDK Tools.
 *
@@ -19,28 +19,33 @@
 */
 
 declare module "embedded:io/socket/udp" {
-  class UDP {
+  export interface UDPPacket extends ArrayBuffer {
+    address: string;		// sender's IP address
+    port: number;			// sender's port
+  }
+
+  class UDP implements Disposable {
+    target?: any;
     constructor(options: {
       port?: number;
       address?: string;
+      timeToLive?: number;	// Moddable SDK extension
       onReadable?: (this: UDP, packets: number) => void;
-      onError?: () => void;
+      onWritable?: (this: UDP, count: number) => void;
+      onError?: (this: UDP) => void;
       format?: "buffer";
       target?: any;
-    } & ({} | {
-      multicast: string;
-      timeToLive: number;
-    }))
+    });
     write(buffer: ByteBuffer, address: string, port: number): void;
-    read(): ArrayBuffer & {
-      address: string;
-      port: number;
-    };
+    read(): UDPPacket | undefined;
+    read(buffer: ByteBuffer): number;
+    add(multicastAddress: string): void;
+    remove(multicastAddress: string): void;
     close(): void;
     get format(): "buffer"
     set format(value: "buffer")
+    [Symbol.dispose](): void;
   }
-  interface UDP extends Disposable {}
 
   export default UDP
 }

package/embedded_io/spi.d.ts

@@ -19,20 +19,22 @@
 */
 
 declare module "embedded:io/spi" {
-  import { PinSpecifier, PortSpecifier } from "embedded:io/_common";
-  class SPI {
-    constructor(options: {
+  import { PinSpecifier, PortSpecifier, IOOptions } from "embedded:io/_common";
+  class SPI implements Disposable {
+    target?: any;
+    constructor(options: IOOptions<"SPI", {
       out?: PinSpecifier;
       in?: PinSpecifier;
       clock: PinSpecifier;
       select?: PinSpecifier;
+      port?: PortSpecifier;
+    }, {
       active?: 1 | 0;
       hz: number;
       mode?: number;
-      port?: PortSpecifier;
       format?: "buffer";
       target?: any;
-    })
+    }>)
     read(byteLength: number): ArrayBuffer;
     read(buffer: ByteBuffer): void;
     write(buffer: ByteBuffer): void;
@@ -41,7 +43,7 @@ declare module "embedded:io/spi" {
     close(): void;
     get format(): "buffer";
     set format(value: "buffer");
+    [Symbol.dispose](): void;
   }
-  interface SPI extends Disposable {}
   export default SPI;
 }

package/embedded_network/dns/resolver/udp.d.ts

@@ -19,20 +19,27 @@
 */
 
 declare module "embedded:network/dns/resolver/udp" {
+  import type UDP from "embedded:io/socket/udp";
+
+  export interface DNSResolverProvider {
+    io: typeof Resolver
+    servers: string[]
+    socket: { io: typeof UDP, [option: string]: unknown }
+  }
 
   interface Options {
     host: string
-    onResolved: ((host:string, address:any) => null)
-    onError: ((host:string) => null)
+    onResolved?: (this: Resolver, host: string, address: string) => void
+    onError?: (this: Resolver, host: string) => void
   }
 
-  class Resolver {
-    constructor(options: Record<string, any>)
+  class Resolver implements Disposable {
+    target?: any
+    constructor(options: Omit<DNSResolverProvider, "io"> & { target?: any })
     close(): void
     resolve(options: Options): void
-
+    [Symbol.dispose](): void
   }
-  interface Resolver extends Disposable {}
 
   export default Resolver
 }

package/embedded_network/dns/server/udp.d.ts

@@ -0,0 +1,39 @@
+/*
+* 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/>.
+*
+*/
+
+declare module "embedded:network/dns/server/udp" {
+  import type UDP from "embedded:io/socket/udp";
+
+  export interface Options {
+    socket: { io: typeof UDP };
+    // returns the address for the name, or a falsy value when the name is not served
+    onResolve: (name: string) => string | undefined | null | false;
+    ttl?: number;		// seconds, defaults to 60
+    port?: number;		// defaults to 53
+  }
+
+  class Server implements Disposable {
+    constructor(options: Options);
+    close(): void;
+    [Symbol.dispose](): void;
+  }
+
+  export default Server;
+}

package/embedded_network/dnssd.d.ts

@@ -30,12 +30,13 @@ declare module "embedded:network/dnssd" {
 
     export interface DNSSDOptions {
         socket: DNSSDSocketOptions;
+        target?: any;
     }
 
     export interface ClaimOptions {
         host: string;
-        onReady?(): void;
-        onError?(): void;
+        onReady?(this: ClaimHandle): void;
+        onError?(this: ClaimHandle): void;
     }
 
     export interface ClaimHandle extends Disposable {
@@ -52,9 +53,9 @@ declare module "embedded:network/dnssd" {
 
     export interface DiscoverOptions {
         serviceType: string;
-        onFound?(service: ServiceObject): void;
-        onUpdate?(service: ServiceObject): void;
-        onLost?(service: ServiceObject): void;
+        onFound?(this: DiscoverHandle, service: ServiceObject): void;
+        onUpdate?(this: DiscoverHandle, service: ServiceObject): void;
+        onLost?(this: DiscoverHandle, service: ServiceObject): void;
     }
 
     export interface DiscoverHandle extends Disposable {
@@ -74,13 +75,14 @@ declare module "embedded:network/dnssd" {
         updateTXT(txt: Map<string, string | ByteBuffer>): void;
     }
 
-    class DNSSD {
+    class DNSSD implements Disposable {
+        target?: any;
         constructor(options: DNSSDOptions);
         close(): void;
         claim(options: ClaimOptions): ClaimHandle;
         discover(options: DiscoverOptions): DiscoverHandle;
         advertise(options: AdvertiseOptions): AdvertiseHandle;
+        [Symbol.dispose](): void;
     }
-    interface DNSSD extends Disposable {}
     export default DNSSD;
 }

package/embedded_network/http/client.d.ts

@@ -19,18 +19,31 @@
 */
 
 declare module "embedded:network/http/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 HTTPClientProvider {
+    io: typeof HTTPClient
+    dns: DNSResolverProvider
+    socket: ClientSocket
+    port?: number
+  }
+
   export interface ClientOptions {
-    socket?: any
+    socket: ClientSocket
     port?: number
     host: string
-    dns?: any
-    onError?: (err:any)=>void
+    dns: DNSResolverProvider
+    onError?: (this: HTTPClient, err:any)=>void
+    target?: any
   }
 
   export interface RequestOptions {
     method?: string
     path?: string
-    headers?: Map<string, string|string[]>
+    headers?: Map<string, string | string[] | number>
     headersMask?: Array<string>
     onHeaders?: (this: HTTPRequest, status:number, headers: Map<string, string>, statusText: string) => void
     onReadable?: (this: HTTPRequest, count: number) => void
@@ -40,17 +53,18 @@ declare module "embedded:network/http/client" {
 
   export interface HTTPRequest {
     read(byteLength?: number): ArrayBuffer|undefined;
-    read(buffer: ByteBuffer): void;
+    read(buffer: ByteBuffer): number | undefined;
     write(): number;
     write(value: ByteBuffer|undefined): number;
   }
 
-  class HTTPClient {
+  class HTTPClient implements Disposable {
+    target?: any
     constructor(options: ClientOptions)
     request(options: RequestOptions): HTTPRequest
     close(): void
+    [Symbol.dispose](): void
   }
-  interface HTTPClient extends Disposable {}
   export default HTTPClient;
 
 }

package/embedded_network/http/server/route/serversentevents.d.ts

@@ -0,0 +1,48 @@
+/*
+* 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/>.
+*
+*/
+
+// handlers that accept a Server-Sent Events request. Spread them into a route and add onConnection, which
+// is called once the event stream is open, with a connection whose write sends an event
+declare module "embedded:network/http/server/route/serversentevents" {
+    import type { HTTPConnection, HTTPConnectionHandlers } from "embedded:network/http/server";
+
+    export interface ServerSentEvent {
+        data?: string;
+        event?: string;
+        id?: string;
+    }
+
+    export interface ServerSentEventsConnection extends Omit<HTTPConnection, "write"> {
+        write(event?: ServerSentEvent): void;			// no event sends a keep-alive comment
+    }
+
+    export interface ServerSentEventsRoute extends HTTPConnectionHandlers {
+        onConnection?(this: ServerSentEventsConnection): void;
+    }
+
+    const route: HTTPConnectionHandlers;
+    export default route;
+}
+
+declare module "embedded:network/http/server" {
+    interface HTTPRouteTypes {
+        serversentevents: import("embedded:network/http/server/route/serversentevents").ServerSentEventsRoute;
+    }
+}

package/embedded_network/http/server/route/static.d.ts

@@ -0,0 +1,41 @@
+/*
+* 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/>.
+*
+*/
+
+// handlers that respond with fixed content. Spread them into a route and add the content:
+//	{ ...StaticRoute, data: "<html>…</html>", contentType: "text/html" }
+declare module "embedded:network/http/server/route/static" {
+    import type { HTTPConnectionHandlers } from "embedded:network/http/server";
+
+    export interface StaticRoute extends HTTPConnectionHandlers {
+        data: ByteBuffer | string;		// a string is sent with chunked transfer encoding
+        contentType?: string;			// defaults to "text/html"
+        headers?: Map<string, string | number>;
+        status?: number;
+    }
+
+    const route: HTTPConnectionHandlers;
+    export default route;
+}
+
+declare module "embedded:network/http/server" {
+    interface HTTPRouteTypes {
+        static: import("embedded:network/http/server/route/static").StaticRoute;
+    }
+}

package/embedded_network/http/server/route/webdav.d.ts

@@ -0,0 +1,42 @@
+/*
+* 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/>.
+*
+*/
+
+// a WebDAV (RFC 4918) server over a directory. It composes with other routes: onRoute returns handlers for
+// requests under prefix, and undefined for the rest
+declare module "embedded:network/http/server/route/webdav" {
+    import type { HTTPConnectionHandlers, HTTPRequest } from "embedded:network/http/server";
+    import type { Directory } from "embedded:storage/files";
+
+    export interface WebDAVOptions {
+        directory: Directory;		// the directory to serve
+        prefix?: string;			// request path under which the directory is served, such as "/dav"; defaults to ""
+        log?: boolean;				// trace requests; defaults to false
+        appleDouble?: boolean;		// accept macOS "._" metadata files; defaults to true
+    }
+
+    class WebDAV {
+        constructor(options: WebDAVOptions);
+        onRoute(request: HTTPRequest): HTTPConnectionHandlers | undefined;
+        readonly directory: Directory;
+        readonly prefix: string;
+    }
+
+    export default WebDAV;
+}

package/embedded_network/http/server/route/ws/handshake.d.ts

@@ -0,0 +1,28 @@
+/*
+* 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/>.
+*
+*/
+
+// handlers that complete a WebSocket handshake. Spread them into a route; in its onDone, detach the socket and
+// attach a WebSocket to it. To choose a subprotocol, set the connection's protocol before the response is sent
+declare module "embedded:network/http/server/route/ws/handshake" {
+    import type { HTTPConnectionHandlers } from "embedded:network/http/server";
+
+    const route: HTTPConnectionHandlers;
+    export default route;
+}