@mikrojs/native 0.0.7

package/runtime/i2c/i2c.ts

@@ -0,0 +1,35 @@
+import * as native from 'native:i2c'
+
+import type {Result} from '../result/types.js'
+import type {I2c as PlatformI2c, I2cError, I2cOptions} from './types.js'
+
+/**
+ * @public
+ */
+export class I2c implements PlatformI2c {
+  #native: native.I2c
+
+  constructor(busNo: 0 | 1, options?: I2cOptions) {
+    this.#native = new native.I2c(busNo, options)
+  }
+
+  begin(): Result<void, I2cError> {
+    return this.#native.begin()
+  }
+
+  end(): Result<void, I2cError> {
+    return this.#native.end()
+  }
+
+  scan(): Result<Uint8Array, I2cError> {
+    return this.#native.scan()
+  }
+
+  write(address: number, data: Uint8Array, stop?: boolean): Result<void, I2cError> {
+    return this.#native.write(address, data, stop)
+  }
+
+  read(address: number, bytes: number): Result<Uint8Array, I2cError> {
+    return this.#native.read(address, bytes)
+  }
+}

package/runtime/i2c/types.ts

@@ -0,0 +1,55 @@
+import type {Result} from '../result/types.js'
+
+/**
+ * @public
+ */
+export interface I2cBaseOptions {
+  freq?: number
+  timeout?: number
+}
+
+/**
+ * @public
+ */
+export interface I2cOptionsWithPins extends I2cBaseOptions {
+  sda: number
+  scl: number
+}
+
+/**
+ * @public
+ */
+export type I2cOptions = I2cBaseOptions | I2cOptionsWithPins
+
+export type I2cError =
+  | {name: 'BusInitFailed'; message: string}
+  | {name: 'BusDeinitFailed'; message: string}
+  | {name: 'NotStarted'}
+  | {name: 'MissingPins'}
+  | {name: 'AddDeviceFailed'; message: string}
+  | {name: 'WriteFailed'; message: string}
+  | {name: 'WriteTooLarge'}
+  | {name: 'ReadFailed'; message: string}
+
+/**
+ * @public
+ */
+export declare const I2c: {
+  prototype: I2c
+  new (busNo: 0 | 1, options?: I2cOptions): I2c
+}
+
+/**
+ * @public
+ */
+export interface I2c {
+  begin(): Result<void, I2cError>
+
+  end(): Result<void, I2cError>
+
+  read(address: number, bytes: number): Result<Uint8Array, I2cError>
+
+  write(address: number, data: Uint8Array, stop?: boolean): Result<void, I2cError>
+
+  scan(): Result<Uint8Array, I2cError>
+}

package/runtime/inspect/types.ts

@@ -0,0 +1,10 @@
+export interface InspectOptions {
+  showHidden?: boolean
+  depth?: number
+  truncate?: number
+  colors?: boolean
+}
+
+export type InspectFn = (value: unknown, options?: InspectOptions) => string
+
+export declare const inspect: InspectFn

package/runtime/internal.d.ts

@@ -0,0 +1,456 @@
+// Native C modules provided by the firmware, not importable by user scripts
+
+type NR<T> = {ok: true; value: T} | {ok: false; error: {code: number; message: string}}
+
+// Internal shared runtime modules. Registered as builtins so sibling bundles
+// can reference them at runtime to dedupe shared code, but not exposed via
+// the public `mikrojs/*` subpath exports so user apps can't accidentally
+// import them. Keep these in sync with the MODULES list in the firmware +
+// @mikrojs/native CMakeLists.
+declare module 'mikrojs/kv/shared' {
+  export {KVError, makeCreateValue, type NativeKvFns} from './kv/shared.js'
+}
+
+declare module 'native:cbor' {
+  import type {CborError} from '@mikrojs/native/runtime/cbor/types'
+  import type {Result} from 'mikrojs/result'
+  export function encode(value: unknown): Result<Uint8Array, CborError>
+  export function decode(data: Uint8Array): Result<unknown, CborError>
+}
+
+declare module 'native:result' {
+  import type {ErrResult, OkResult} from './result/types.js'
+  export function ok(): OkResult<void>
+  export function ok<T>(value: T): OkResult<T>
+  export function err<E>(error: E): ErrResult<E>
+}
+
+declare module 'native:sys' {
+  import type {JsMemoryUsage} from './sys/types.js'
+  export function evalScript(code: string): Promise<{value: unknown}>
+  export function memoryUsage(): {
+    heapUsed: number
+    heapTotal: number
+    systemFree: number
+    systemMinFree: number
+    systemTotal: number
+    systemLargestFree: number
+  }
+  export function jsMemoryUsage(): JsMemoryUsage
+  export function gc(): void
+  export function activeTimers(): number
+  export function setTime(millisSinceEpoch: number): void
+  export function uptime(): {boot: number; rtc: number}
+  export function restart(): never
+  export const version: string
+  export const board: {
+    name: string
+    chip: string
+    cores: number
+    revision: number
+    features: string[]
+    flash: number
+    psram: number
+  }
+  export const firmware: {hash: string; date: string; idfVersion: string | undefined}
+  export const deviceId: string
+}
+
+declare module 'native:fs' {
+  import type {DirEntry, FSError, MkdirOptions, StatResult, WriteFileOptions} from './fs/types.js'
+  import type {Result} from './result/types.js'
+
+  export interface FileHandle {
+    /** Reads up to `size` bytes. Value is `undefined` at EOF. */
+    read(size: number): Result<Uint8Array | undefined, FSError>
+    write(data: Uint8Array | string): Result<number, FSError>
+    seek(offset: number, whence?: 'start' | 'current' | 'end'): Result<number, FSError>
+    close(): Result<void, FSError>
+    stat(): Result<StatResult, FSError>
+    readonly path: string
+  }
+
+  export type OpenMode = 'r' | 'w' | 'a' | 'r+' | 'w+' | 'a+'
+
+  export function open(path: string, mode?: OpenMode): Result<FileHandle, FSError>
+  export function readFile(path: string): Result<Uint8Array, FSError>
+  export function readFile(path: string, encoding: 'utf-8'): Result<string, FSError>
+  export function writeFile(
+    path: string,
+    contents: string,
+    options?: WriteFileOptions,
+  ): Result<void, FSError>
+  export function writeFile(
+    path: string,
+    contents: Uint8Array,
+    options?: WriteFileOptions,
+  ): Result<void, FSError>
+  export function stat(path: string): Result<StatResult, FSError>
+  export function readDir(path: string): Result<DirEntry[], FSError>
+  export function unlink(path: string): Result<void, FSError>
+  export function rename(from: string, to: string): Result<void, FSError>
+  export function mkdir(path: string, options?: MkdirOptions): Result<void, FSError>
+  export function rmdir(path: string): Result<void, FSError>
+  export function exists(path: string): boolean
+}
+
+declare module 'native:stdio' {
+  export const stdout: {
+    write(output: Uint8Array | string): boolean
+    flush(): void
+  }
+
+  export const stdin: {
+    read(): undefined | Uint8Array
+    setHandler(handler: (data: Uint8Array) => void): void
+    clearHandler(): void
+  }
+}
+
+declare module 'native:pin' {
+  import type {PinError} from '@mikrojs/native/runtime/pin/types'
+  import type {Result} from 'mikrojs/result'
+  export type PinMode = 0x01 | 0x03 | 0x05
+  export function pinMode(pin: number, value: PinMode): Result<void, PinError>
+  export function digitalWrite(pin: number, value: 0 | 1): Result<void, PinError>
+  export function digitalRead(pin: number): number
+  // attenuation: 0=0dB, 1=2.5dB, 2=6dB, 3=11dB
+  export function analogRead(pin: number, attenuation: number): Result<number, PinError>
+  export function analogReadMillivolts(pin: number, attenuation: number): Result<number, PinError>
+}
+
+declare module 'native:sleep' {
+  import type {SleepError} from '@mikrojs/native/runtime/sleep/types'
+  import type {Result} from 'mikrojs/result'
+
+  export function deepSleep(ms: number): never
+  export function lightSleep(ms: number): Result<void, SleepError>
+  export function getWakeupCause(): string
+  export function enableTimerWakeup(us: number): Result<void, SleepError>
+  export function enableGpioWakeup(pin: number, level: number): Result<void, SleepError>
+  export function enableExt0Wakeup(pin: number, level: number): Result<void, SleepError>
+  export function enableExt1Wakeup(pinMask: number, mode: number): Result<void, SleepError>
+  export function disableWakeupSource(source?: string): Result<void, SleepError>
+}
+
+declare module 'native:http' {
+  import type {RequestError} from 'mikrojs/http/helpers'
+  import type {Result} from 'mikrojs/result'
+
+  import type {ErrResult} from './result/types.js'
+  type HeadersMsg = {status: number; headers: [string, string][]}
+  export type HttpMessage =
+    | {kind: 'chunk'; data: Uint8Array}
+    | {kind: 'end'}
+    | {kind: 'error'; cancelled: boolean; message: string}
+  export type HttpRequestStart =
+    | {ok: true; id: number; headers: Promise<Result<HeadersMsg, RequestError>>}
+    | ErrResult<RequestError>
+  export function request(
+    url: string,
+    options?: {method?: string; body?: Uint8Array; headers?: [string, string][]},
+  ): HttpRequestStart
+  export function nextMessage(id: number): Promise<HttpMessage>
+  export function cancel(id: number): void
+  export function pendingCount(): number
+}
+declare module 'native:i2c' {
+  import type {I2cError} from '@mikrojs/native/runtime/i2c/types'
+  import type {Result} from 'mikrojs/result'
+
+  export interface I2cBaseOptions {
+    freq?: number
+    timeout?: number
+  }
+
+  export interface I2cOptionsWithPins extends I2cBaseOptions {
+    sda: number
+    scl: number
+  }
+
+  export type I2cOptions = I2cBaseOptions | I2cOptionsWithPins
+  export declare const I2c: {
+    prototype: I2c
+    new (busNo: 0 | 1, options?: I2cOptions): I2c
+  }
+
+  export interface I2c {
+    begin(): Result<void, I2cError>
+
+    end(): Result<void, I2cError>
+
+    read(address: number, bytes: number): Result<Uint8Array, I2cError>
+
+    write(address: number, data: Uint8Array, stop?: boolean): Result<void, I2cError>
+
+    scan(): Result<Uint8Array, I2cError>
+  }
+}
+declare module 'native:spi' {
+  import type {SpiError} from '@mikrojs/native/runtime/spi/types'
+  import type {Result} from 'mikrojs/result'
+
+  export interface SpiOptions {
+    clk: number
+    mosi: number
+    miso?: number
+    cs?: number
+    freq?: number
+    mode?: 0 | 1 | 2 | 3
+  }
+
+  export declare const Spi: {
+    prototype: Spi
+    new (hostNo: 1 | 2, options: SpiOptions): Spi
+  }
+
+  export interface Spi {
+    begin(): Result<void, SpiError>
+
+    end(): Result<void, SpiError>
+
+    transfer(data: Uint8Array): Result<Uint8Array, SpiError>
+
+    write(data: Uint8Array): Result<void, SpiError>
+  }
+}
+
+declare module 'native:sntp' {
+  import type {SntpError} from '@mikrojs/native/runtime/sntp/types'
+  import type {Result} from 'mikrojs/result'
+  /**
+   * Native errors: the outer Result covers init/config failures (InitFailed);
+   * the inner Result on resolve covers post-start errors (Cancelled).
+   * `Timeout` is owned by the JS-side Promise racer in mikrojs/sntp, not
+   * emitted by native.
+   */
+  export function sync(
+    servers: string[],
+    timezone: string,
+    background: boolean,
+  ): Result<Promise<Result<{time: number}, SntpError>>, SntpError>
+  export function stop(): void
+  export function setTimezone(tz: string): void
+}
+
+declare module 'native:rtc' {
+  type NRV = {ok: true} | {ok: false; error: {code: number; message: string}}
+  export function set(key: string, value: unknown): NRV
+  export function get(key: string): unknown
+  export function remove(key: string): boolean
+  export function clear(): void
+  export function info(): {used: number; total: number; entries: number}
+}
+
+declare module 'native:nvs_kv' {
+  type NRV = {ok: true} | {ok: false; error: {code: number; message: string}}
+  export function set(key: string, value: unknown): NRV
+  export function get(key: string): unknown
+  export function remove(key: string): boolean
+  export function clear(): void
+  export function info(): {entries: number; used: number; total: number; free: number}
+}
+
+declare module 'native:pwm' {
+  import type {PwmError} from '@mikrojs/native/runtime/pwm/types'
+  import type {Result} from 'mikrojs/result'
+
+  export declare const Pwm: {
+    prototype: Pwm
+    new (pin: number, freq: number, duty: number): Pwm
+  }
+
+  export interface Pwm {
+    duty(value?: number): Result<number, PwmError>
+    freq(value?: number): Result<number, PwmError>
+    fade(target: number, durationMs: number): Result<Promise<void>, PwmError>
+    end(): Result<void, PwmError>
+  }
+}
+
+declare module 'native:neopixel' {
+  import type {NeoPixelError} from '@mikrojs/native/runtime/neopixel/types'
+  import type {Result} from 'mikrojs/result'
+
+  export declare const NeoPixel: {
+    prototype: NeoPixel
+    new (pin: number, numLeds: number, bytesPerLed: number): NeoPixel
+  }
+
+  export interface NeoPixel {
+    setPixel(index: number, r: number, g: number, b: number, w: number): Result<void, NeoPixelError>
+    fill(r: number, g: number, b: number, w: number): Result<void, NeoPixelError>
+    show(): Result<void, NeoPixelError>
+    clear(): Result<void, NeoPixelError>
+    end(): Result<void, NeoPixelError>
+  }
+}
+
+declare module 'native:uart' {
+  import type {UartError} from '@mikrojs/native/runtime/uart/types'
+  import type {Result} from 'mikrojs/result'
+
+  export interface UartOptions {
+    tx?: number
+    rx?: number
+    baudRate: number
+  }
+
+  export declare const Uart: {
+    prototype: Uart
+    new (port: number, options: UartOptions): Uart
+  }
+
+  export interface Uart {
+    begin(): Result<void, UartError>
+
+    end(): Result<void, UartError>
+
+    write(data: Uint8Array): Result<void, UartError>
+
+    read(): Result<
+      {
+        next(): Promise<IteratorResult<Uint8Array>>
+        return(): Promise<IteratorResult<Uint8Array>>
+      },
+      UartError
+    >
+  }
+}
+
+declare module 'native:ble' {
+  import type {BleError} from '@mikrojs/native/runtime/ble/types'
+  import type {Result} from 'mikrojs/result'
+
+  type R<T> = Result<T, BleError>
+
+  export interface CharacteristicNative {
+    uuid: string
+    properties: number // bitmask
+    value?: Uint8Array
+    onWrite?: (value: Uint8Array) => void
+    writeMode?: string
+    security?: string
+  }
+
+  export interface ServiceNative {
+    uuid: string
+    characteristics: CharacteristicNative[]
+  }
+
+  export interface AdvertiseOptionsNative {
+    name?: string
+    connectable?: boolean
+    services?: ServiceNative[]
+    interval?: {min: number; max: number}
+    includeTxPower?: boolean
+    manufacturerData?: Uint8Array
+  }
+
+  export interface Ble {
+    getName(): string
+    setName(name: string): R<void>
+    getAddress(): R<string>
+
+    getTxPower(): R<number>
+    setTxPower(dbm: number): R<void>
+
+    advertise(options: AdvertiseOptionsNative): R<void>
+    stopAdvertising(): R<void>
+    stop(): R<void>
+
+    setValue(serviceUuid: string, characteristicUuid: string, value: Uint8Array): R<void>
+    notify(serviceUuid: string, characteristicUuid: string, value: Uint8Array): R<void>
+
+    on(event: string, listener: (...args: unknown[]) => void): void
+    off(event: string, listener: (...args: unknown[]) => void): void
+  }
+
+  export declare const Ble: {
+    prototype: Ble
+    new (): Ble
+  }
+}
+
+declare module 'native:wifi' {
+  import type {WifiError} from '@mikrojs/native/runtime/wifi/types'
+  import type {Result} from 'mikrojs/result'
+
+  type R<T> = Result<T, WifiError>
+
+  export interface Wifi {
+    connect(
+      ssid: string,
+      passphrase: string,
+    ): R<Promise<R<{ip: string; netmask: string; gateway: string}>>>
+    disconnect(): R<void>
+    rssi(): R<number>
+    ip(): string
+    status(): number
+    scan(opts?: {ssid?: string; channel?: number; passive?: boolean}): R<
+      Promise<
+        R<
+          {
+            ssid: string
+            bssid: string
+            channel: number
+            rssi: number
+            authMode: string
+            hidden: boolean
+          }[]
+        >
+      >
+    >
+    on(event: string, listener: (...args: unknown[]) => void): void
+    off(event: string, listener: (...args: unknown[]) => void): void
+
+    // Network config
+    mac(): R<string>
+    getHostname(): string | undefined
+    setHostname(hostname: string): R<void>
+    getIpConfig(): R<{ip: string; netmask: string; gateway: string; dns: string} | undefined>
+    setIpConfig(opts: {
+      ip?: string
+      netmask?: string
+      gateway?: string
+      dns?: string
+      dhcp?: boolean
+    }): R<void>
+
+    // AP mode
+    apStart(opts: {
+      ssid: string
+      passphrase?: string
+      authMode?: string
+      channel?: number
+      hidden?: boolean
+      maxConnections?: number
+    }): R<void>
+    apStop(): R<void>
+    apIsActive(): boolean
+    apIp(): string | undefined
+    apStations(): {mac: string; rssi: number}[]
+
+    // TX power & RSSI threshold
+    getTxPower(): R<number>
+    setTxPower(dbm: number): R<void>
+    getRssiThreshold(): number
+    setRssiThreshold(threshold: number): R<void>
+
+    // AP extras
+    apDeauthStation(mac: string): R<void>
+    apGetInactiveTimeout(): R<number>
+    apSetInactiveTimeout(seconds: number): R<void>
+
+    // Power management & misc
+    getPowerSave(): string
+    setPowerSave(mode: string): R<void>
+    getCountry(): string | undefined
+    setCountry(cc: string): R<void>
+  }
+
+  export declare const Wifi: {
+    prototype: Wifi
+    new (): Wifi
+  }
+}

package/runtime/kv/nvs.ts

@@ -0,0 +1,17 @@
+import {KVError, makeCreateValue} from 'mikrojs/kv/shared'
+import {clear, get, info, remove, set} from 'native:nvs_kv'
+
+import type {NvsStorage} from './types.js'
+
+// Loaded in isolation: this file avoids `native:rtc`, so apps importing
+// `mikrojs/kv/nvs` directly don't pay for the RTC backend. `KVError` and
+// `makeCreateValue` come from the shared bytecode module at runtime so
+// they aren't duplicated across nvs.js and rtc.js.
+
+export {KVError}
+
+export const nvsStorage = {
+  createValue: makeCreateValue({get, set, remove, clear, info}),
+  clear,
+  info,
+} as NvsStorage

package/runtime/kv/rtc.ts

@@ -0,0 +1,17 @@
+import {KVError, makeCreateValue} from 'mikrojs/kv/shared'
+import {clear, get, info, remove, set} from 'native:rtc'
+
+import type {RtcStorage} from './types.js'
+
+// Loaded in isolation: this file avoids `native:nvs_kv`, so apps importing
+// `mikrojs/kv/rtc` directly don't pay for the NVS backend. `KVError` and
+// `makeCreateValue` come from the shared bytecode module at runtime so
+// they aren't duplicated across nvs.js and rtc.js.
+
+export {KVError}
+
+export const rtcStorage = {
+  createValue: makeCreateValue({get, set, remove, clear, info}),
+  clear,
+  info,
+} as RtcStorage

package/runtime/kv/shared.ts

@@ -0,0 +1,107 @@
+import {defineError, err, ok} from 'mikrojs/result'
+// Typed loosely to avoid deep type instantiation from Infer<S> in parse's generics.
+// Type safety is provided by the storage interface overloads in types.ts.
+import {parse as _parse} from 'mikrojs/schema'
+
+import type {NativeError} from '../result/types.js'
+
+type ParseResult = {ok: true; value: unknown} | {ok: false; error: {message: string; path: string}}
+const parse = _parse as unknown as (schema: unknown, value: unknown) => ParseResult
+
+export const KVError = defineError('KVError', {
+  StorageFull: (message: string) => ({message}),
+  EncodeFailed: (message: string) => ({message}),
+  WriteFailed: (message: string) => ({message}),
+  ValidationFailed: (message: string, path: string) => ({message, path}),
+})
+
+/* Error codes from errors.h (MIK_ERR_BASE + 0xD0..0xD4) */
+const KV_INVALID_KEY = 0x80d0
+const KV_ENCODE = 0x80d1
+const KV_TOO_LARGE = 0x80d2
+const KV_STORAGE_FULL = 0x80d3
+const KV_WRITE = 0x80d4
+
+type NativeResult = {ok: true} | {ok: false; error: NativeError}
+
+export type NativeKvFns = {
+  get: (key: string) => unknown
+  set: (key: string, value: unknown) => NativeResult
+  remove: (key: string) => boolean
+  clear: () => void
+  info: () => unknown
+}
+
+function mapKvError(e: NativeError) {
+  switch (e.code) {
+    case KV_STORAGE_FULL:
+    case KV_TOO_LARGE:
+      return KVError.StorageFull(e.message)
+    case KV_ENCODE:
+    case KV_INVALID_KEY:
+      return KVError.EncodeFailed(e.message)
+    case KV_WRITE:
+      return KVError.WriteFailed(e.message)
+    default:
+      throw new Error(`unexpected native kv error: code=0x${e.code.toString(16)}`)
+  }
+}
+
+export function makeCreateValue(native: NativeKvFns) {
+  return function createValue(key: string, options?: any): any {
+    const schema = options?.schema
+    const initialValue = options?.initialValue
+    const hasInitialValue = options !== undefined && 'initialValue' in options
+    const onReadError = options?.onReadError ?? (() => undefined)
+
+    function doGet(): unknown {
+      try {
+        const v = native.get(key)
+        if (v === undefined) return hasInitialValue ? initialValue : undefined
+        if (schema) {
+          const result = parse(schema, v)
+          if (!result.ok) {
+            // Schema mismatch: data decoded fine, don't delete it
+            return onReadError(result.error)
+          }
+          return result.value
+        }
+        return v
+      } catch (e) {
+        // Decode failure: corrupt data, delete it
+        native.remove(key)
+        const fallback = onReadError(e)
+        if (fallback !== undefined) native.set(key, fallback)
+        return fallback
+      }
+    }
+
+    function doSet(value: unknown) {
+      if (value === undefined) {
+        native.remove(key)
+        return ok(undefined)
+      }
+      if (schema) {
+        const result = parse(schema, value)
+        if (!result.ok) {
+          return err(KVError.ValidationFailed(result.error.message, result.error.path))
+        }
+      }
+      const result = native.set(key, value)
+      if (!result.ok) return err(mapKvError(result.error))
+      return ok(value)
+    }
+
+    return {
+      get: doGet,
+      set: doSet,
+      update(updater: (value: any) => any) {
+        return doSet(updater(doGet()))
+      },
+      delete() {
+        const removed = native.remove(key)
+        return removed ? ok() : err(KVError.WriteFailed(`failed to delete key "${key}"`))
+      },
+    }
+  }
+}