@moddable/typings 9.0.1 → 10.0.0

package/embedded/display.d.ts

@@ -30,6 +30,7 @@ declare module "embedded:display" {
 		brightness?: number; // 0-1 range
 		rotation?: 0 | 90 | 180 | 270;
 		format?: typeof Bitmap.RGB565LE | typeof Bitmap.RGB24 | typeof Bitmap.Gray256;
+		flip?: "" | "h" | "v" | "hv";
 	}
 
 	export interface DisplayConfiguration {
@@ -43,9 +44,10 @@ declare module "embedded:display" {
 		y: number;
 		width: number;
 		height: number;
+		continue?: boolean;		// true to continue updating the same frame buffer
 	}
 
-	class Display {
+	class Display implements Disposable {
 		constructor(options: DisplayConstructorOptions);
 		close(): void;
 
@@ -58,12 +60,15 @@ declare module "embedded:display" {
 		send(buffer: ByteBuffer, offset: number, length: number): void;
 		end(): void;
 
-		adapInvalid(rectangle: Rectangle): void;
+		adaptInvalid(rectangle: Rectangle): void;
 
 		get width(): number;
 		get height(): number;
+
+		corner?: number;		// circular & roundrect displays
+
+		[Symbol.dispose](): void;
 	}
-	interface Display extends Disposable {}
 
 	export default Display;
 }

package/embedded/storage/files.d.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024-2025  Moddable Tech, Inc.
+ * Copyright (c) 2024-2026  Moddable Tech, Inc.
  *
  *   This file is part of the Moddable SDK Runtime.
  * 
@@ -27,7 +27,7 @@ declare module "embedded:storage/files" {
 		isSymbolicLink(): boolean;
 	}
 
-	export class File {
+	export class File implements Disposable {
 		// Use Directory.openFile() to create File instances
 		close(): void;
 
@@ -38,8 +38,8 @@ declare module "embedded:storage/files" {
 		status(): Status;
 		setSize(length: number): void;
 		flush(): void;
+		[Symbol.dispose](): void;
 	}
-	export interface File extends Disposable {}
 
 	export interface DirectoryOpenFileOptions {
 		path: string;
@@ -54,7 +54,7 @@ declare module "embedded:storage/files" {
 		resolveTarget?: boolean;
 	}
 
-	export class Directory {
+	export class Directory implements Disposable {
 		// use device.files to access file system root
 		close(): void;
 
@@ -70,8 +70,11 @@ declare module "embedded:storage/files" {
 		createLink?(path: string, target: string): void;
 		readLink?(path: string): string;
 
-		scan(path?: string): IterableIterator<string>;
-		[Symbol.iterator](): IterableIterator<string>;
+		scan(path?: string): IteratorObject<string, undefined, unknown>;
+		[Symbol.iterator](): IteratorObject<string, undefined, unknown>;
+		[Symbol.dispose](): void;
 	}
-	export interface Directory extends Disposable {}
+
+	const root: Directory;
+	export default root;
 }

package/embedded/storage/flash.d.ts

@@ -32,7 +32,7 @@ declare module "embedded:storage/flash" {
 		eraseValue: number;
 	}
 
-	export class Flash {
+	export class Flash implements Disposable {
 		// Use the default export's open() method to create Flash instances
 		close(): void;
 
@@ -45,8 +45,8 @@ declare module "embedded:storage/flash" {
 		status(): FlashStatus;
 
 		format: "buffer";
+		[Symbol.dispose](): void;
 	}
-	export interface Flash extends Disposable {}
 
 	const FlashStorage: {
 		open(options: FlashOpenOptions): Flash;

package/embedded/storage/key-value.d.ts

@@ -27,24 +27,45 @@ declare module "embedded:storage/key-value" {
 
 	export type StorageFormat = "buffer" | "string" | "uint8" | "int8" | "uint16" | "int16" | "uint32" | "int32" | "uint64" | "int64";
 
-	export class Storage {
+	// the type read() returns for each format
+	export interface StorageFormats {
+		buffer: ArrayBuffer;
+		string: string;
+		uint8: number;
+		int8: number;
+		uint16: number;
+		int16: number;
+		uint32: number;
+		int32: number;
+		uint64: bigint;
+		int64: bigint;
+	}
+
+	/*
+		F is the format named in the options passed to open(). Naming it there
+		(format: "string") fixes the type read() returns.
+		When the options name no format, read() is typed as returning any of the types,
+		because the format can be changed later through the format property.
+	*/
+	export class Storage<F extends StorageFormat = StorageFormat> implements Disposable {
 		// Use the default export's open() method to create Storage instances
 		close(): void;
 
 		delete(key: string): void;
 
-		read(key: string): ArrayBuffer | string | number | bigint | undefined;
+		read(key: string): StorageFormats[F] | undefined;
 		read(key: string, buffer: ByteBuffer): number | undefined;
 		write(key: string, value: ByteBuffer | string | number | bigint): void;
 
-		[Symbol.iterator](): IterableIterator<string>;
+		[Symbol.iterator](): Iterator<string>;
 
-		format: StorageFormat;
+		get format(): F;
+		set format(value: StorageFormat);
+		[Symbol.dispose](): void;
 	}
-	export interface Storage extends Disposable {}
 
 	const KeyValueStorage: {
-		open(options: StorageOpenOptions): Storage;
+		open<F extends StorageFormat = StorageFormat>(options: StorageOpenOptions & { format?: F }): Storage<F>;
 	};
 
 	export default KeyValueStorage;

package/embedded/system.d.ts

@@ -0,0 +1,49 @@
+/*
+* 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/>.
+*
+*/
+
+/// <reference path="../config/system.d.ts" />
+
+declare module "embedded:system" {
+	interface RestartOptions {
+		type?: "soft" | "hard";
+	}
+
+	/**
+	 * Every method is optional: a host provides only those appropriate to it, so test for a method before calling it.
+	 */
+	interface System {
+		restart?(options?: RestartOptions): never;
+		shutdown?(): never;
+		exit?(reason?: unknown): never;
+		/**
+		 * @param duration milliseconds
+		 */
+		sleep?(duration: number): void;
+		/**
+		 * nRF52 extension. Without a duration, enters System OFF sleep; with a duration, enters System ON sleep
+		 * with RAM powered off, waking after `duration` milliseconds. Either way, wake-up reboots.
+		 * Returns without sleeping in debug builds.
+		 */
+		deepSleep?(duration?: number): void;
+	}
+
+	const System: Readonly<System>;
+	export default System;
+}

package/embedded_io/_common.d.ts

@@ -20,7 +20,46 @@
 
 
 declare module "embedded:io/_common" {
-  // This should be extended for future specification
-  export type PinSpecifier = number
-  export type PortSpecifier = number
+  /**
+   * Pin and port specifiers are host-dependent values (ECMA-419 9.1 and 9.2).
+   * A host declares its own by merging `pin` and/or `port` into this interface, for example:
+   *
+   *     declare module "embedded:io/_common" {
+   *       interface HostSpecifiers {
+   *         pin: {port: string; pin: number};
+   *         port: string;
+   *       }
+   *     }
+   *
+   * A host that declares nothing uses numbers.
+   */
+  export interface HostSpecifiers {}
+
+  export type PinSpecifier = HostSpecifiers extends {pin: infer T} ? T : number
+  export type PortSpecifier = HostSpecifiers extends {port: infer T} ? T : number
+
+  /**
+   * The constructor options that select the hardware of an IO class are host-dependent too.
+   * ECMA-419 defines them as pins. A host that selects hardware another way, such as by name
+   * from a devicetree, declares the options of a class by merging a property with the name
+   * of the class into this interface, for example:
+   *
+   *     declare module "embedded:io/_common" {
+   *       interface HostOptions {
+   *         PWM: {port: PortSpecifier; channel?: number};
+   *       }
+   *     }
+   *
+   * These replace the hardware options ECMA-419 defines for the class: its other options are unchanged.
+   */
+  export interface HostOptions {}
+
+  /**
+   * The constructor options of IO class `Name`: the host's hardware options if it declares any,
+   * otherwise `Hardware` (those of ECMA-419), together with `Rest`.
+   */
+  export type IOOptions<Name extends string, Hardware, Rest> =
+    Flatten<(HostOptions extends Record<Name, infer T> ? T : Hardware) & Rest>
+
+  type Flatten<T> = {[K in keyof T]: T[K]}
 }

package/embedded_io/analog.d.ts

@@ -20,22 +20,22 @@
 
 
 declare module "embedded:io/analog" {
-  import { PinSpecifier } from "embedded:io/_common";
-  class Analog {
-    constructor(options: {
+  import { PinSpecifier, IOOptions } from "embedded:io/_common";
+  class Analog implements Disposable {
+    constructor(options: IOOptions<"Analog", {
       pin: PinSpecifier;
+    }, {
       resolution?: number;
-      onReadable?: (this: Analog) => void;
       format?: "number";
-    });
+      target?: any;
+    }>);
     readonly resolution: number;
-    onReadable?: () => void;
     read(): number;
     close(): void;
     get format(): "number"
     set format(value: "number")
     target?: any;
+    [Symbol.dispose](): void;
   }
-  interface Analog extends Disposable {}
   export default Analog;
 }

package/embedded_io/audio/in.d.ts

@@ -29,7 +29,8 @@ declare module "embedded:io/audio/in" {
     target?: any;
   }
 
-  class AudioIn {
+  class AudioIn implements Disposable {
+    target?: any;
     constructor(options: AudioInOptions & {
       onReadable?: (this: AudioIn, byteLength: number, sampleCount?: number) => void;
     });
@@ -44,8 +45,8 @@ declare module "embedded:io/audio/in" {
     readonly audioType: AudioType;
     get format(): "buffer"
     set format(value: "buffer")
+    [Symbol.dispose](): void;
   }
-  interface AudioIn extends Disposable {}
 
   export { AudioIn as default };
 }

package/embedded_io/audio/out.d.ts

@@ -1,5 +1,5 @@
 /*
-* Copyright (c) 2025 Satoshi Tanaka
+* Copyright (c) 2025-2026 Satoshi Tanaka
 *
 *   This file is part of the Moddable SDK Tools.
 *
@@ -29,8 +29,9 @@ declare module "embedded:io/audio/out" {
     target?: any;
   }
 
-  class AudioOut {
-    constructor(options?: AudioOutOptions & {
+  class AudioOut implements Disposable {
+    target?: any;
+    constructor(options: AudioOutOptions & {
       onWritable?: (this: AudioOut, byteLength: number, sampleCount?: number) => void;
     });
     write(buffer: ByteBuffer): void;
@@ -45,8 +46,15 @@ declare module "embedded:io/audio/out" {
     get format(): "buffer"
     set format(value: "buffer")
     volume: number;
+    [Symbol.dispose](): void;
+  }
+
+  namespace AudioOut {
+    class Async extends AudioOut {
+      constructor(options: AudioOutOptions);
+      write(buffer: ByteBuffer, callback?: (this: Async, error: Error | null) => void): void;
+    }
   }
-  interface AudioOut extends Disposable {}
 
   export { AudioOut as default };
 }

package/embedded_io/ble/central.d.ts

@@ -17,13 +17,13 @@ declare module "embedded:io/bluetoothle/central" {
         onReadable?: (this: GAPClient, count: number) => void;
     }
 
-    class GAPClient {
+    class GAPClient implements Disposable {
         constructor(options: GAPClientOptions);
         target: any;
         close(): void;
         read(): Advertisement;
+        [Symbol.dispose](): void;
     }
-    interface GAPClient extends Disposable {}
 
     interface GATTClientNotifiedValue extends ArrayBuffer {
         handle: number
@@ -58,7 +58,7 @@ declare module "embedded:io/bluetoothle/central" {
         get uuid(): string;
     }
 
-    class GATTClient {
+    class GATTClient implements Disposable {
         constructor(options: GATTClientOptions);
         target: any;
 
@@ -100,8 +100,9 @@ declare module "embedded:io/bluetoothle/central" {
             write: 8;
             writeWithOutResponse: 4;
         };
+        [Symbol.dispose](): void;
     }
-    interface GATTClient extends Disposable {}
 
     export { GATTClient, GAPClient };
+    export type { Advertisement, GAPClientOptions, GATTClientNotifiedValue, GATTClientWriteOptions, GATTClientOptions, GATTClientService, GATTClientCharacteristic, GATTClientDescriptor };
 }

package/embedded_io/ble/peripheral.d.ts

@@ -15,10 +15,10 @@ declare module "embedded:io/bluetoothle/peripheral" {
 
     interface GATTServerConnection extends Disposable {
         close(): void;
-        notify(characteristic: GATTServerCharacteristic, value: ArrayBuffer, callback?: (error?: Error) => void): void;
+        notify(characteristic: GATTServerCharacteristic, value: ByteBuffer, callback?: (error?: Error) => void): void;
         replyToPasskey(action: "input" | "compareNumber" | "outOfBand", value: number | boolean | ArrayBuffer): void;
         disconnect(): void;
-        readonly maxinumWrite: number;
+        readonly maximumWrite: number;
         readonly remoteAddress: string | undefined;
     }
 
@@ -36,7 +36,7 @@ declare module "embedded:io/bluetoothle/peripheral" {
         onRead?(this: GATTServerCharacteristic, connection: GATTServerConnection): ByteBuffer;
         onWrite?(this: GATTServerCharacteristic, value: ArrayBuffer, connection: GATTServerConnection): void;
         onSubscribe?(this: GATTServerCharacteristic, connection: GATTServerConnection): void;
-        onUnsubscribe?(cthis: GATTServerCharacteristic, onnection: GATTServerConnection): void;
+        onUnsubscribe?(this: GATTServerCharacteristic, connection: GATTServerConnection): void;
     }
 
     interface GATTServerDescriptor {
@@ -55,7 +55,7 @@ declare module "embedded:io/bluetoothle/peripheral" {
         [ADType: number]: ByteBuffer;
     }
 
-    class GATTServer {
+    class GATTServer implements Disposable {
         constructor(options: GATTServerOptions);
 
         close(): void;
@@ -87,8 +87,9 @@ declare module "embedded:io/bluetoothle/peripheral" {
             dualModeController: 8;
             dualModeHost: 16;
         }
+        [Symbol.dispose](): void;
     }
-    interface GATTServer extends Disposable {}
 
     export { GATTServer };
+    export type { GATTServerOptions, GATTServerConnection, GATTServerService, GATTServerCharacteristic, GATTServerDescriptor, GATTServerAdvertisingRecords };
 }

package/embedded_io/crypt/digest.d.ts

@@ -31,7 +31,7 @@ declare module "embedded:io/crypt/digest" {
   }
   type DigestOptions = DigestOptionsBase | DigestOptionsGHASH;
 
-  class Digest {
+  class Digest implements Disposable {
     constructor(options: DigestOptions);
     write(data: ByteBuffer): void;
     read(): ArrayBuffer;
@@ -40,8 +40,8 @@ declare module "embedded:io/crypt/digest" {
     close(): void;
     readonly blockSize: number;
     readonly outputSize: number;
+    [Symbol.dispose](): void;
   }
-  interface Digest extends Disposable {}
 
   export default Digest;
 }

package/embedded_io/digital.d.ts

@@ -32,7 +32,8 @@ declare module "embedded:io/digital" {
     | typeof Digital.OutputOpenDrain
     | typeof Digital.ActiveLow
 
-  class Digital {
+  class Digital implements Disposable {
+    target?: any;
     static readonly Input: number
     static readonly InputPullUp: number
     static readonly InputPullDown: number
@@ -57,14 +58,14 @@ declare module "embedded:io/digital" {
       edge?: Edge;
     }));
 
-    write(value: 0 | 1): void;
+    write(value: number): void;
     read(): 0 | 1;
     close(): void;
 
     get format(): "number"
     set format(value: "number")
+    [Symbol.dispose](): void;
   }
-  interface Digital extends Disposable {}
 
   export default Digital;
 }

package/embedded_io/digitalbank.d.ts

@@ -19,6 +19,8 @@
 */
 
 declare module "embedded:io/digitalbank" {
+  import { IOOptions } from "embedded:io/_common";
+
   type Mode = 
     | typeof DigitalBank.Input
     | typeof DigitalBank.InputPullUp
@@ -28,7 +30,8 @@ declare module "embedded:io/digitalbank" {
     | typeof DigitalBank.OutputOpenDrain
     | typeof DigitalBank.ActiveLow
 
-  class DigitalBank {
+  class DigitalBank implements Disposable {
+    target?: any;
     static readonly Input: number
     static readonly InputPullUp: number
     static readonly InputPullDown: number
@@ -37,10 +40,11 @@ declare module "embedded:io/digitalbank" {
     static readonly OutputOpenDrain: number
     static readonly ActiveLow: number
 
-    constructor(dictionary: {
+    constructor(dictionary: IOOptions<"DigitalBank", {
+      bank?: number | string;
+    }, {
       pins: number;
       mode: Mode;
-      bank?: number | string;
       activeLow?: boolean;
       initialValue?: number;
       rises?: number;
@@ -48,7 +52,7 @@ declare module "embedded:io/digitalbank" {
       onReadable?: (this: DigitalBank, trigger: number) => void;
       format?: "number";
       target?: any;
-    })
+    }>)
 
     close(): void;
     read(): number;
@@ -56,8 +60,8 @@ declare module "embedded:io/digitalbank" {
 
     get format(): "number"
     set format(value: "number")
+    [Symbol.dispose](): void;
   }
-  interface DigitalBank extends Disposable {}
 
   export default DigitalBank;
 }

package/embedded_io/i2c.d.ts

@@ -20,17 +20,20 @@
 
 
 declare module "embedded:io/i2c" {
-  import { PinSpecifier, PortSpecifier } from "embedded:io/_common";
-  class I2C {
-    constructor(options: {
+  import { PinSpecifier, PortSpecifier, IOOptions } from "embedded:io/_common";
+  class I2C implements Disposable {
+    target?: any;
+    constructor(options: IOOptions<"I2C", {
       data: PinSpecifier;
       clock: PinSpecifier;
+      port?: PortSpecifier;
+    }, {
       hz: number;
       address: number;
-      port?: PortSpecifier;
+      timeout?: number;	// milliseconds (Moddable SDK extension)
       format?: "buffer";
       target?: any;
-    });
+    }>);
     readonly resolution: number;
     
     write(value: ByteBuffer, stop?: boolean): void;
@@ -41,8 +44,8 @@ declare module "embedded:io/i2c" {
     close(): void;
     get format(): "buffer"
     set format(value: "buffer")
+    [Symbol.dispose](): void;
   }
-  interface I2C extends Disposable {}
 
   export default I2C;
 }

package/embedded_io/image/in/camera.d.ts

@@ -0,0 +1,82 @@
+/*
+* 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:io/image/in/camera" {
+  // pixel format constants are those of commodetto/Bitmap; "jpeg" selects compressed frames
+  export type ImageType = number | "jpeg";
+
+  export interface CameraFrame extends HostBuffer, Disposable {
+    readonly camera: Camera;
+    close(): void;
+  }
+
+  export interface CameraConfiguration {
+    brightness?: number;
+    contrast?: number;
+    saturation?: number;
+    sharpness?: number;
+    denoise?: number;
+    whiteBalance?: number;
+  }
+
+  export type Format = "buffer" | "buffer/disposable";
+
+  export interface Options<F extends Format = Format> {
+    width?: number;
+    height?: number;
+    imageType?: ImageType;
+    format?: F;
+    onReadable?: (this: Camera<F>, count: number) => void;
+    target?: any;
+  }
+
+  /*
+    F is the format named in the options when the camera is created. Naming it there
+    (format: "buffer") fixes the type read() with no argument returns:
+    a CameraFrame for "buffer/disposable", 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 Camera<F extends Format = Format> extends Disposable {
+    target?: any;
+    close(): void;
+    // format "buffer/disposable" returns the frame without copying; close it to release it to the camera
+    read(): (F extends "buffer/disposable" ? CameraFrame : ArrayBuffer) | undefined;
+    read(buffer: ByteBuffer): number | undefined;
+    start(): void;
+    stop(): void;
+    configure(options: CameraConfiguration): void;
+    get format(): F;
+    set format(value: Format);
+    readonly imageType: ImageType;
+    readonly width: number;
+    readonly height: number;
+    readonly identification: { model: string };
+    readonly configuration: CameraConfiguration;
+    [Symbol.dispose](): void;
+  }
+  interface CameraConstructor {
+    new <F extends Format = Format>(options: Options<F>): Camera<F>;
+    readonly prototype: Camera;
+  }
+  const Camera: CameraConstructor;
+
+  export default Camera;
+}

package/embedded_io/pulsecount.d.ts

@@ -19,23 +19,25 @@
 */
 
 declare module "embedded:io/pulsecount" {
-  import { PinSpecifier } from "embedded:io/_common";
-  class PulseCount {
-    constructor (options: {
+  import { PinSpecifier, IOOptions } from "embedded:io/_common";
+  class PulseCount implements Disposable {
+    target?: any;
+    constructor (options: IOOptions<"PulseCount", {
       signal: PinSpecifier;
       control: PinSpecifier;
+    }, {
       onReadable?: (this: PulseCount) => void;
       onError?: (this: PulseCount) => void;
       format?: "number";
       target?: any;
-    });
+    }>);
     read(): number;
     write(count: number): void;
     close(): void;
     get format(): "number";
     set format(value: "number");
+    [Symbol.dispose](): void;
   }
-  interface PulseCount extends Disposable {}
 
   export default PulseCount;
 }