@mikrojs/native 0.0.7

package/runtime/uart/types.ts

@@ -0,0 +1,75 @@
+import type {Result} from '../result/types.js'
+
+/**
+ * @public
+ */
+export interface UartBaseOptions {
+  baudRate: number
+}
+
+/**
+ * @public
+ */
+export interface UartTxRxOptions extends UartBaseOptions {
+  tx: number
+  rx: number
+}
+
+/**
+ * @public
+ */
+export interface UartTxOnlyOptions extends UartBaseOptions {
+  tx: number
+  rx?: undefined
+}
+
+/**
+ * @public
+ */
+export interface UartRxOnlyOptions extends UartBaseOptions {
+  tx?: undefined
+  rx: number
+}
+
+export type UartError =
+  | {name: 'DriverInstallFailed'; message: string}
+  | {name: 'SetPinFailed'; message: string}
+  | {name: 'InvalidParam'; message: string}
+  | {name: 'WriteFailed'; message: string}
+  | {name: 'ReadFailed'; message: string}
+  | {name: 'NotStarted'}
+  | {name: 'AlreadyReading'}
+  | {name: 'NoRxPin'}
+  | {name: 'NoTxPin'}
+
+/**
+ * @public
+ */
+export interface UartTx {
+  write(data: Uint8Array): Result<void, UartError>
+}
+
+/**
+ * @public
+ */
+export interface UartRx {
+  read(): Result<AsyncIterable<Uint8Array>, UartError>
+}
+
+/**
+ * @public
+ */
+export interface UartBase {
+  begin(): Result<void, UartError>
+  end(): Result<void, UartError>
+}
+
+/**
+ * @public
+ */
+export declare const Uart: {
+  prototype: UartBase
+  new (port: number, options: UartTxRxOptions): UartBase & UartTx & UartRx
+  new (port: number, options: UartTxOnlyOptions): UartBase & UartTx
+  new (port: number, options: UartRxOnlyOptions): UartBase & UartRx
+}

package/runtime/uart/uart.ts

@@ -0,0 +1,51 @@
+import {ok} from 'mikrojs/result'
+import * as native from 'native:uart'
+
+import type {Result} from '../result/types.js'
+import type {
+  UartBase,
+  UartBaseOptions,
+  UartError,
+  UartRxOnlyOptions,
+  UartTxOnlyOptions,
+  UartTxRxOptions,
+} from './types.js'
+
+/**
+ * @public
+ */
+export class Uart implements UartBase {
+  #native: native.Uart
+
+  constructor(port: number, options: UartTxRxOptions)
+  constructor(port: number, options: UartTxOnlyOptions)
+  constructor(port: number, options: UartRxOnlyOptions)
+  constructor(port: number, options: UartBaseOptions & {tx?: number; rx?: number}) {
+    this.#native = new native.Uart(port, options)
+  }
+
+  begin(): Result<void, UartError> {
+    return this.#native.begin()
+  }
+
+  end(): Result<void, UartError> {
+    return this.#native.end()
+  }
+
+  write(data: Uint8Array): Result<void, UartError> {
+    return this.#native.write(data)
+  }
+
+  read(): Result<AsyncIterable<Uint8Array>, UartError> {
+    const result = this.#native.read()
+    if (!result.ok) return result
+    const nativeIter = result.value
+    // Wrap the native iterator object (which has next/return) into a proper AsyncIterable
+    const iterable: AsyncIterable<Uint8Array> = {
+      [Symbol.asyncIterator]() {
+        return nativeIter as AsyncIterator<Uint8Array>
+      },
+    }
+    return ok(iterable)
+  }
+}

package/runtime/wifi/types.ts

@@ -0,0 +1,156 @@
+import type {Result} from '../result/types.js'
+
+export type WifiStatus =
+  | 'STOPPED'
+  | 'IDLE'
+  | 'NO_SSID_AVAIL'
+  | 'SCAN_COMPLETED'
+  | 'CONNECTED'
+  | 'CONNECT_FAILED'
+  | 'CONNECTION_LOST'
+  | 'DISCONNECTED'
+
+export type AuthMode = 'open' | 'wpa2-psk' | 'wpa3-psk' | 'wpa2-wpa3-psk' | 'unknown'
+
+export type PowerSaveMode = 'none' | 'min' | 'max'
+
+// prettier-ignore
+// Based on esp_wifi_regulatory.c wifi_country_table
+// https://github.com/espressif/esp-idf/blob/484e56869c6f6b8f777cc76d73fc02390587a7c5/components/esp_wifi/regulatory/esp_wifi_regulatory.c#L213
+export type WifiCountryCode =
+  | "01" | "AD" | "AE" | "AF" | "AI" | "AL" | "AM" | "AN" | "AR" | "AS" | "AT"
+  | "AU" | "AW" | "AZ" | "BA" | "BB" | "BD" | "BE" | "BF" | "BG" | "BH" | "BL"
+  | "BM" | "BN" | "BO" | "BR" | "BS" | "BT" | "BY" | "BZ" | "CA" | "CF" | "CH"
+  | "CI" | "CL" | "CN" | "CO" | "CR" | "CU" | "CX" | "CY" | "CZ" | "DE" | "DK"
+  | "DM" | "DO" | "DZ" | "EC" | "EE" | "EG" | "ES" | "ET" | "EU" | "FI" | "FM"
+  | "FR" | "GB" | "GD" | "GE" | "GF" | "GH" | "GL" | "GP" | "GR" | "GT" | "GU"
+  | "GY" | "HK" | "HN" | "HR" | "HT" | "HU" | "ID" | "IE" | "IL" | "IN" | "IR"
+  | "IS" | "IT" | "JM" | "JO" | "JP" | "KE" | "KH" | "KN" | "KP" | "KR" | "KW"
+  | "KY" | "KZ" | "LB" | "LC" | "LI" | "LK" | "LS" | "LT" | "LU" | "LV" | "MA"
+  | "MC" | "MD" | "ME" | "MF" | "MH" | "MK" | "MN" | "MO" | "MP" | "MQ" | "MR"
+  | "MT" | "MU" | "MV" | "MW" | "MX" | "MY" | "NA" | "NG" | "NI" | "NL" | "NO"
+  | "NP" | "NZ" | "OM" | "PA" | "PE" | "PF" | "PG" | "PH" | "PK" | "PL" | "PM"
+  | "PR" | "PT" | "PW" | "PY" | "QA" | "RE" | "RO" | "RS" | "RU" | "RW" | "SA"
+  | "SE" | "SG" | "SI" | "SK" | "SN" | "SR" | "SV" | "SY" | "TC" | "TD" | "TG"
+  | "TH" | "TN" | "TR" | "TT" | "TW" | "TZ" | "UA" | "UG" | "US" | "UY" | "UZ"
+  | "VC" | "VE" | "VI" | "VN" | "VU" | "WF" | "WS" | "YE" | "YT" | "ZA" | "ZW"
+
+export interface ScanOptions {
+  ssid?: string
+  channel?: number
+  passive?: boolean
+}
+
+export interface ScanResult {
+  ssid: string
+  bssid: string
+  channel: number
+  rssi: number
+  authMode: AuthMode
+  hidden: boolean
+}
+
+export interface WifiConnectionInfo {
+  ip: string
+  netmask: string
+  gateway: string
+}
+
+export interface IpConfig {
+  ip: string
+  netmask: string
+  gateway: string
+  dns: string
+}
+
+export interface StaticIpConfig {
+  ip?: string
+  netmask?: string
+  gateway?: string
+  dns?: string
+  dhcp?: boolean
+}
+
+export type WifiDisconnectReason = 'no-ssid' | 'auth-failed' | 'connection-lost' | 'disconnected'
+
+export interface ApStationInfo {
+  mac: string
+  rssi: number
+}
+
+export interface ApStartOptions {
+  ssid: string
+  passphrase?: string
+  authMode?: AuthMode
+  channel?: number
+  hidden?: boolean
+  maxConnections?: number
+}
+
+export interface WifiEventMap {
+  connect: (info: WifiConnectionInfo) => void
+  disconnect: (reason: WifiDisconnectReason) => void
+  'rssi-low': (rssi: number) => void
+}
+
+export interface ApEventMap {
+  'station-connect': (info: ApStationInfo) => void
+  'station-disconnect': (info: ApStationInfo) => void
+}
+
+export type WifiError =
+  | {name: 'InitFailed'; message: string}
+  | {name: 'CountryNotSet'}
+  | {name: 'StartFailed'; message: string}
+  | {name: 'ConnectFailed'; message: string}
+  | {name: 'ConnectInProgress'}
+  | {name: 'DisconnectFailed'; message: string}
+  | {name: 'ScanFailed'; message: string}
+  | {name: 'ScanInProgress'}
+  | {name: 'NotInitialized'}
+  | {name: 'ConfigFailed'; message: string}
+  | {name: 'ApStartFailed'; message: string}
+  | {name: 'ApStopFailed'; message: string}
+  | {name: 'SetFailed'; message: string}
+  | {name: 'GetFailed'; message: string}
+
+export interface WifiAp {
+  start(options: ApStartOptions): Result<void, WifiError>
+  stop(): Result<void, WifiError>
+  readonly isActive: boolean
+  readonly ip: string | undefined
+  readonly stations: ApStationInfo[]
+  deauthStation(mac: string): Result<void, WifiError>
+  inactiveTimeout: number
+  on<K extends keyof ApEventMap>(event: K, listener: ApEventMap[K]): void
+  off<K extends keyof ApEventMap>(event: K, listener: ApEventMap[K]): void
+}
+
+export interface Wifi {
+  connect(ssid: string, passphrase: string): Promise<Result<WifiConnectionInfo, WifiError>>
+  disconnect(): Result<void, WifiError>
+  rssi(): Result<number, WifiError>
+  ip(): string | undefined
+  status(): WifiStatus
+  isConnected: boolean
+  scan(opts?: ScanOptions): Promise<Result<ScanResult[], WifiError>>
+
+  on<K extends keyof WifiEventMap>(event: K, listener: WifiEventMap[K]): void
+  off<K extends keyof WifiEventMap>(event: K, listener: WifiEventMap[K]): void
+
+  readonly mac: string
+  hostname: string | undefined
+  ipConfig(): Result<IpConfig | undefined, WifiError>
+  ipConfig(opts: StaticIpConfig): Result<void, WifiError>
+  ipConfig(opts?: StaticIpConfig): Result<IpConfig | undefined, WifiError> | Result<void, WifiError>
+
+  readonly ap: WifiAp
+
+  txPower: number
+  rssiThreshold: number
+
+  powerSave: PowerSaveMode
+  country: WifiCountryCode | undefined
+}
+
+export declare const wifi: Wifi

package/runtime/wifi/wifi.ts

@@ -0,0 +1,208 @@
+import {err, ok} from 'mikrojs/result'
+import {Wifi as NativeWifi} from 'native:wifi'
+
+import type {Result} from '../result/types.js'
+import type {
+  ApEventMap,
+  ApStartOptions,
+  ApStationInfo,
+  IpConfig,
+  PowerSaveMode,
+  ScanOptions,
+  ScanResult,
+  StaticIpConfig,
+  Wifi,
+  WifiAp,
+  WifiConnectionInfo,
+  WifiCountryCode,
+  WifiError,
+  WifiEventMap,
+  WifiStatus,
+} from './types.js'
+
+const WifiStatusCodes: Record<WifiStatus, number> = {
+  STOPPED: 254,
+  IDLE: 0,
+  NO_SSID_AVAIL: 1,
+  SCAN_COMPLETED: 2,
+  CONNECTED: 3,
+  CONNECT_FAILED: 4,
+  CONNECTION_LOST: 5,
+  DISCONNECTED: 6,
+}
+
+const StatusFromCode = new Map<number, WifiStatus>(
+  Object.entries(WifiStatusCodes).map(([k, v]) => [v, k as WifiStatus]),
+)
+
+const native = new NativeWifi()
+
+const ap: WifiAp = {
+  start(options: ApStartOptions): Result<void, WifiError> {
+    return native.apStart(options as Parameters<typeof native.apStart>[0])
+  },
+
+  stop(): Result<void, WifiError> {
+    return native.apStop()
+  },
+
+  get isActive(): boolean {
+    return native.apIsActive()
+  },
+
+  get ip(): string | undefined {
+    return native.apIp()
+  },
+
+  get stations(): ApStationInfo[] {
+    return native.apStations()
+  },
+
+  deauthStation(mac: string): Result<void, WifiError> {
+    return native.apDeauthStation(mac)
+  },
+
+  get inactiveTimeout(): number {
+    const result = native.apGetInactiveTimeout()
+    return result.ok ? result.value : 0
+  },
+
+  set inactiveTimeout(seconds: number) {
+    native.apSetInactiveTimeout(seconds)
+  },
+
+  on<K extends keyof ApEventMap>(event: K, listener: ApEventMap[K]) {
+    native.on(event, listener as (...args: unknown[]) => void)
+  },
+
+  off<K extends keyof ApEventMap>(event: K, listener: ApEventMap[K]) {
+    native.off(event, listener as (...args: unknown[]) => void)
+  },
+}
+
+const MAX_CONNECT_RETRIES = 5
+const RETRY_DELAY_MS = 2000
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
+
+const wifi: Wifi = {
+  async connect(ssid: string, passphrase: string): Promise<Result<WifiConnectionInfo, WifiError>> {
+    for (let attempt = 0; attempt <= MAX_CONNECT_RETRIES; attempt++) {
+      const startResult = native.connect(ssid, passphrase)
+      if (!startResult.ok) return startResult
+
+      const asyncResult = await startResult.value
+      if (asyncResult.ok) return ok(asyncResult.value as WifiConnectionInfo)
+
+      if (attempt === MAX_CONNECT_RETRIES) return asyncResult
+
+      // eslint-disable-next-line no-console
+      console.warn(`WiFi connect failed, retrying in ${RETRY_DELAY_MS}ms…`)
+      native.disconnect()
+      await sleep(RETRY_DELAY_MS)
+    }
+    return err({name: 'ConnectFailed' as const, message: 'max retries exceeded'})
+  },
+
+  disconnect(): Result<void, WifiError> {
+    return native.disconnect()
+  },
+
+  rssi(): Result<number, WifiError> {
+    return native.rssi()
+  },
+
+  ip(): string | undefined {
+    const ip = native.ip()
+    return ip === '0.0.0.0' ? undefined : ip
+  },
+
+  status(): WifiStatus {
+    const code = native.status()
+    return StatusFromCode.get(code) ?? 'DISCONNECTED'
+  },
+
+  get isConnected(): boolean {
+    return native.status() === WifiStatusCodes.CONNECTED
+  },
+
+  async scan(opts?: ScanOptions): Promise<Result<ScanResult[], WifiError>> {
+    const startResult = native.scan(opts)
+    if (!startResult.ok) return startResult
+
+    const asyncResult = await startResult.value
+    if (!asyncResult.ok) return asyncResult
+    return ok(asyncResult.value as ScanResult[])
+  },
+
+  on<K extends keyof WifiEventMap>(event: K, listener: WifiEventMap[K]) {
+    native.on(event, listener as (...args: unknown[]) => void)
+  },
+
+  off<K extends keyof WifiEventMap>(event: K, listener: WifiEventMap[K]) {
+    native.off(event, listener as (...args: unknown[]) => void)
+  },
+
+  get mac(): string {
+    const result = native.mac()
+    return result.ok ? result.value : ''
+  },
+
+  get hostname(): string | undefined {
+    return native.getHostname()
+  },
+
+  set hostname(value: string | undefined) {
+    if (value !== undefined) {
+      native.setHostname(value)
+    }
+  },
+
+  ipConfig: ((
+    opts?: StaticIpConfig,
+  ): Result<IpConfig | undefined, WifiError> | Result<void, WifiError> => {
+    if (opts === undefined) {
+      return native.getIpConfig()
+    }
+    return native.setIpConfig(opts)
+  }) as Wifi['ipConfig'],
+
+  ap,
+
+  get txPower(): number {
+    const result = native.getTxPower()
+    return result.ok ? result.value : 0
+  },
+
+  set txPower(dbm: number) {
+    native.setTxPower(dbm)
+  },
+
+  get rssiThreshold(): number {
+    return native.getRssiThreshold()
+  },
+
+  set rssiThreshold(value: number) {
+    native.setRssiThreshold(value)
+  },
+
+  get powerSave(): PowerSaveMode {
+    return native.getPowerSave() as PowerSaveMode
+  },
+
+  set powerSave(mode: PowerSaveMode) {
+    native.setPowerSave(mode)
+  },
+
+  get country(): WifiCountryCode | undefined {
+    return native.getCountry() as WifiCountryCode | undefined
+  },
+
+  set country(cc: WifiCountryCode | undefined) {
+    if (cc !== undefined) {
+      native.setCountry(cc)
+    }
+  },
+}
+
+export {wifi}

package/scripts/bundle-runtime.js

@@ -0,0 +1,149 @@
+import {existsSync, mkdirSync, writeFileSync} from 'node:fs'
+import {dirname, join} from 'node:path'
+
+/**
+ * Bundle runtime TypeScript modules to JavaScript using esbuild.
+ * Output goes to a directory where qjsc can compile them to bytecode.
+ *
+ * Usage: node bundle-runtime.js <outdir> <runtime_dir> <mod1> <mod2> ... [--minifier=NAME] [--minify-level=LEVEL]
+ */
+import {build} from 'esbuild'
+
+// Parse positional args and optional flags
+const positionalArgs = []
+let minifier = 'esbuild'
+let minifyLevel = 'default'
+for (const arg of process.argv.slice(2)) {
+  if (arg.startsWith('--minifier=')) {
+    minifier = arg.slice('--minifier='.length)
+  } else if (arg.startsWith('--minify-level=')) {
+    minifyLevel = arg.slice('--minify-level='.length)
+  } else {
+    positionalArgs.push(arg)
+  }
+}
+
+const outDir = positionalArgs[0]
+const runtimeDir = positionalArgs[1]
+const moduleNames = positionalArgs.slice(2)
+
+if (!outDir || !runtimeDir || moduleNames.length === 0) {
+  // eslint-disable-next-line no-console
+  console.error(
+    'Usage: node bundle-runtime.js <outdir> <runtime_dir> <mod1> <mod2> ... [--minifier=NAME] [--minify-level=LEVEL]',
+  )
+  process.exit(1)
+}
+
+// Dynamic import helper to avoid TypeScript module resolution at parse time
+function importOptional(name) {
+  return import(name)
+}
+
+async function minifyWithTerser(code) {
+  const terser = await importOptional('terser')
+  const options =
+    minifyLevel === 'max'
+      ? {
+          module: true,
+          ecma: 2020,
+          compress: {
+            ecma: 2020,
+            module: true,
+            passes: 3,
+            toplevel: true,
+            pure_getters: true,
+            unsafe_arrows: true,
+            unsafe_math: true,
+            unsafe_methods: true,
+          },
+          mangle: {module: true, toplevel: true},
+        }
+      : {module: true}
+  const result = await terser.minify(code, options)
+  if (result.code === undefined) throw new Error('terser produced no output')
+  return result.code
+}
+
+async function minifyWithSwc(code) {
+  const swc = await importOptional('@swc/core')
+  const options =
+    minifyLevel === 'max'
+      ? {
+          module: true,
+          compress: {
+            module: true,
+            passes: 3,
+            toplevel: true,
+            pure_getters: true,
+            unsafe_arrows: true,
+            unsafe_math: true,
+            unsafe_methods: true,
+          },
+          mangle: {toplevel: true},
+        }
+      : {module: true}
+  const result = await swc.minify(code, options)
+  return result.code
+}
+
+mkdirSync(outDir, {recursive: true})
+
+for (const name of moduleNames) {
+  // Resolve entry point: {name}/{name}.ts (core modules) or {name}.ts (board/driver)
+  const nested = join(runtimeDir, name, `${name}.ts`)
+  const flat = join(runtimeDir, `${name}.ts`)
+  const entry = existsSync(nested) ? nested : flat
+  const useEsbuildMinify = minifier === 'esbuild'
+  const result = await build({
+    bundle: true,
+    entryPoints: [entry],
+    write: false,
+    minify: useEsbuildMinify,
+    treeShaking: true,
+    target: 'es2024',
+    platform: 'neutral',
+    format: 'esm',
+    external: ['mikrojs', 'mikrojs/*', '@mikrojs/*', 'native:*'],
+  })
+
+  const output = result.outputFiles?.[0]
+  if (!output) {
+    // eslint-disable-next-line no-console
+    console.error(`Bundling ${name} did not produce a file`)
+    process.exit(1)
+  }
+
+  let source = new TextDecoder().decode(output.contents)
+
+  // Post-process with selected minifier if not esbuild
+  if (!useEsbuildMinify) {
+    if (minifier === 'terser') {
+      source = await minifyWithTerser(source)
+    } else if (minifier === 'swc') {
+      source = await minifyWithSwc(source)
+    }
+  }
+
+  // Extract external imports so CMake can pass them as -M flags to qjsc
+  const externals = []
+  for (const match of source.matchAll(
+    /(?:from|import)\s*["']((?:native:|mikrojs\/|@mikrojs\/)[^"']+)["']/g,
+  )) {
+    externals.push(match[1])
+  }
+
+  const outFile = join(outDir, `${name}.js`)
+  // Module names may contain slashes (e.g. 'kv/nvs') for nested subpath
+  // builtins like `mikrojs/kv/nvs`. Ensure the parent directory exists
+  // before writing — writeFileSync won't create it on its own.
+  mkdirSync(dirname(outFile), {recursive: true})
+  writeFileSync(outFile, source)
+
+  // Write externals list for CMake to read
+  const extFile = join(outDir, `${name}.externals`)
+  writeFileSync(extFile, externals.join('\n'))
+
+  // eslint-disable-next-line no-console
+  console.log(`Bundled ${name} (${Buffer.byteLength(source)} bytes, ${externals.length} externals)`)
+}