@mikrojs/native 0.0.7

package/runtime/spi/spi.ts

@@ -0,0 +1,31 @@
+import * as native from 'native:spi'
+
+import type {Result} from '../result/types.js'
+import type {Spi as PlatformSpi, SpiError, SpiOptions} from './types.js'
+
+/**
+ * @public
+ */
+export class Spi implements PlatformSpi {
+  #native: native.Spi
+
+  constructor(hostNo: 1 | 2, options: SpiOptions) {
+    this.#native = new native.Spi(hostNo, options)
+  }
+
+  begin(): Result<void, SpiError> {
+    return this.#native.begin()
+  }
+
+  end(): Result<void, SpiError> {
+    return this.#native.end()
+  }
+
+  transfer(data: Uint8Array): Result<Uint8Array, SpiError> {
+    return this.#native.transfer(data)
+  }
+
+  write(data: Uint8Array): Result<void, SpiError> {
+    return this.#native.write(data)
+  }
+}

package/runtime/spi/types.ts

@@ -0,0 +1,42 @@
+import type {Result} from '../result/types.js'
+
+/**
+ * @public
+ */
+export interface SpiOptions {
+  clk: number
+  mosi: number
+  miso?: number
+  cs?: number
+  freq?: number
+  mode?: 0 | 1 | 2 | 3
+}
+
+export type SpiError =
+  | {name: 'BusInitFailed'; message: string}
+  | {name: 'AddDeviceFailed'; message: string}
+  | {name: 'NotStarted'}
+  | {name: 'MissingPins'}
+  | {name: 'TransferFailed'; message: string}
+  | {name: 'WriteFailed'; message: string}
+
+/**
+ * @public
+ */
+export declare const Spi: {
+  prototype: Spi
+  new (hostNo: 1 | 2, options: SpiOptions): Spi
+}
+
+/**
+ * @public
+ */
+export interface Spi {
+  begin(): Result<void, SpiError>
+
+  end(): Result<void, SpiError>
+
+  transfer(data: Uint8Array): Result<Uint8Array, SpiError>
+
+  write(data: Uint8Array): Result<void, SpiError>
+}

package/runtime/stdio/stdio.ts

@@ -0,0 +1,44 @@
+import * as native from 'native:stdio'
+
+import type {StdIn, StdOut} from './types.js'
+
+function createStdIn(nativeStdin: typeof native.stdin): StdIn {
+  const listeners: ((buffer: Uint8Array) => void)[] = []
+
+  function onData(chunk: Uint8Array) {
+    listeners.forEach((listener) => listener(chunk))
+  }
+
+  return {
+    addListener(_event: 'data', callback: (buffer: Uint8Array) => void) {
+      if (!listeners.includes(callback)) {
+        listeners.push(callback)
+        if (listeners.length === 1) {
+          nativeStdin.setHandler(onData)
+        }
+      }
+    },
+    removeListener(_event: 'data', callback: (buffer: Uint8Array) => void) {
+      const idx = listeners.indexOf(callback)
+      if (idx > -1) {
+        listeners.splice(idx, 1)
+        if (listeners.length === 0) {
+          nativeStdin.clearHandler()
+        }
+      }
+    },
+    read: nativeStdin.read,
+  }
+}
+
+function createStdOut(nativeStdout: typeof native.stdout): StdOut {
+  return {
+    write: nativeStdout.write,
+    flush: nativeStdout.flush,
+    isTTY: false,
+    getWindowSize: undefined,
+  }
+}
+
+export const stdin = createStdIn(native.stdin)
+export const stdout = createStdOut(native.stdout)

package/runtime/stdio/types.ts

@@ -0,0 +1,22 @@
+export interface StdIn {
+  addListener(event: 'data', callback: (chunk: Uint8Array) => any): void
+
+  removeListener(event: 'data', callback: (chunk: Uint8Array) => any): void
+
+  read(): Uint8Array | undefined
+
+  setRawMode?: (rawMode: boolean) => void
+}
+
+export interface StdOut {
+  isTTY: boolean
+
+  write(output: string | Uint8Array): boolean
+
+  getWindowSize?: () => [width: number, height: number]
+
+  flush(): void
+}
+
+export declare const stdin: StdIn
+export declare const stdout: StdOut

package/runtime/stream/stream.ts

@@ -0,0 +1,150 @@
+/**
+ * Minimal composable stream primitives for mikrojs.
+ *
+ * Streams are plain `AsyncIterable<T>` — no class hierarchy, no
+ * lockable readers, no BYOB, no queueing strategies. Transforms are
+ * async generator functions. Composition is function call.
+ *
+ * This is deliberately a subset of what Snell's "new-streams" proposal
+ * covers, adapted for the realities of QuickJS on a microcontroller:
+ * no fast-path promise optimizations, no sendfile-style native
+ * shortcuts, tight heap budget.
+ *
+ * V1 scope: enough to rewrite a modem AT channel as a one-file shim.
+ * Expand only when a second call site asks for it.
+ */
+
+/** Decode a stream of UTF-8 byte chunks into a stream of strings. */
+export async function* decodeUtf8(source: AsyncIterable<Uint8Array>): AsyncIterable<string> {
+  const decoder = new TextDecoder()
+  for await (const chunk of source) yield decoder.decode(chunk, {stream: true})
+  yield decoder.decode()
+}
+
+/**
+ * Split a stream of text into a stream of lines.
+ *
+ * The delimiter is a string (default `\n`). Partial lines that don't
+ * end with the delimiter in a given input chunk are held in an
+ * internal buffer and prepended to the next chunk's content — so
+ * splitting happens correctly regardless of how the underlying source
+ * chunks its data. If the source closes before emitting a final
+ * delimiter, any trailing buffered content is emitted as a final line
+ * (matching how Node's readline handles EOF).
+ *
+ * Empty lines (consecutive delimiters) are preserved. This matters
+ * for protocols that use a blank line as a separator, e.g. HTTP
+ * headers vs. body.
+ */
+export async function* splitLines(
+  source: AsyncIterable<string>,
+  delimiter: string = '\n',
+): AsyncIterable<string> {
+  // indexOf('') returns 0 unconditionally, which would make the inner
+  // loop spin forever yielding empty strings. Reject at entry instead
+  // of hanging the event loop on a user mistake.
+  if (delimiter.length === 0) {
+    throw new RangeError('splitLines: delimiter must be non-empty')
+  }
+  let buffer = ''
+  for await (const chunk of source) {
+    buffer += chunk
+    let idx = buffer.indexOf(delimiter)
+    while (idx !== -1) {
+      yield buffer.slice(0, idx)
+      buffer = buffer.slice(idx + delimiter.length)
+      idx = buffer.indexOf(delimiter)
+    }
+  }
+  if (buffer.length > 0) yield buffer
+}
+
+/**
+ * Consume a stream until an item matches `predicate`, then stop.
+ *
+ * Returns both the matching item and every item that came before it.
+ * The matching item is NOT included in `collected` — callers who need
+ * it have `matched` for that. This distinction matters for protocols
+ * like modem AT commands where the terminator (`OK`/`ERROR`) is
+ * semantically different from the response body lines in between.
+ *
+ * If the stream closes before any item matches, throws `StreamClosed`
+ * (a plain Error with a `.name`). Callers should wrap this in their
+ * own Result type if they want structured error handling.
+ */
+export async function collectUntil<T>(
+  source: AsyncIterable<T>,
+  predicate: (item: T) => boolean,
+): Promise<{matched: T; collected: T[]}> {
+  const collected: T[] = []
+  for await (const item of source) {
+    if (predicate(item)) {
+      return {matched: item, collected}
+    }
+    collected.push(item)
+  }
+  const err = new Error('Stream closed before predicate matched')
+  err.name = 'StreamClosed'
+  throw err
+}
+
+/**
+ * Wrap an async iterable with a total-duration timeout.
+ *
+ * The deadline starts when this function is called (not per-item).
+ * If the next item doesn't arrive before the deadline, the returned
+ * iterable throws a `TimeoutError`, and cleans up the upstream source
+ * by calling its `return()` method. Callers using `for await` will see
+ * the error propagate out of the loop.
+ *
+ * Implementation notes:
+ * - Promise.race with setTimeout would leak orphaned timers on the
+ *   fast path (source wins, setTimeout's callback still fires
+ *   eventually). We track the timer id and clearTimeout() in a finally
+ *   around the race so fast-path calls don't accumulate pending jobs.
+ * - The upstream iterator is explicitly .return()'d on exit (normal,
+ *   timeout, or consumer break) so underlying resources (UART claims,
+ *   socket handles, ring buffers) get released.
+ */
+export async function* withTimeout<T>(source: AsyncIterable<T>, ms: number): AsyncIterable<T> {
+  const deadline = Date.now() + ms
+  const iter = source[Symbol.asyncIterator]()
+  try {
+    while (true) {
+      const remaining = deadline - Date.now()
+      if (remaining <= 0) {
+        const err = new Error(`Stream did not complete within ${ms}ms`)
+        err.name = 'TimeoutError'
+        throw err
+      }
+
+      let timerId: ReturnType<typeof setTimeout> | undefined
+      let result: IteratorResult<T, unknown>
+      try {
+        result = await Promise.race([
+          iter.next(),
+          new Promise<IteratorResult<T, unknown>>((_, reject) => {
+            timerId = setTimeout(() => {
+              const err = new Error(`Stream did not complete within ${ms}ms`)
+              err.name = 'TimeoutError'
+              reject(err)
+            }, remaining)
+          }),
+        ])
+      } finally {
+        if (timerId !== undefined) clearTimeout(timerId)
+      }
+
+      if (result.done) return
+      yield result.value as T
+    }
+  } finally {
+    if (typeof iter.return === 'function') {
+      try {
+        await iter.return(undefined)
+      } catch {
+        /* swallow — upstream cleanup errors shouldn't mask ours */
+      }
+    }
+  }
+}

package/runtime/stream/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Public types for `mikrojs/stream`.
+ *
+ * The runtime implementation lives in `./stream.ts` and is compiled to
+ * bytecode at firmware build time. This file is the declaration-only
+ * surface consumed by the `mikrojs/stream` re-export in
+ * `packages/mikrojs` and by user apps via their tsconfig.
+ */
+
+/** Decode a stream of UTF-8 byte chunks into a stream of strings. */
+export declare function decodeUtf8(source: AsyncIterable<Uint8Array>): AsyncIterable<string>
+
+/**
+ * Split a stream of text into a stream of lines on the given delimiter
+ * (default `\n`). Partial lines spanning chunk boundaries are buffered
+ * and reassembled. Empty lines between consecutive delimiters are
+ * preserved. Throws `RangeError` if called with an empty delimiter.
+ */
+export declare function splitLines(
+  source: AsyncIterable<string>,
+  delimiter?: string,
+): AsyncIterable<string>
+
+/**
+ * Consume a stream until an item matches `predicate`, then stop.
+ *
+ * Returns `{matched, collected}` where `collected` is every item that
+ * came BEFORE the match (not including the matching item). Throws an
+ * Error with `name === 'StreamClosed'` if the stream ends before any
+ * item matches.
+ */
+export declare function collectUntil<T>(
+  source: AsyncIterable<T>,
+  predicate: (item: T) => boolean,
+): Promise<{matched: T; collected: T[]}>
+
+/**
+ * Wrap an async iterable with a total-duration deadline. Throws an
+ * Error with `name === 'TimeoutError'` if the next item doesn't
+ * arrive in time. Releases the upstream iterator via `return()` on
+ * timeout, error, or consumer break.
+ */
+export declare function withTimeout<T>(source: AsyncIterable<T>, ms: number): AsyncIterable<T>
+
+/* BufferedReader lives in the sibling `mikrojs/reader` module — see
+ * `runtime/reader/` — so apps that only need byte-level framing can
+ * avoid loading the async-generator transforms above. */

package/runtime/sys/sys.ts

@@ -0,0 +1,90 @@
+import {err, ok, PanicError, type Result} from 'mikrojs/result'
+import * as native from 'native:sys'
+
+export function uptime(): {boot: number; rtc: number} {
+  return native.uptime()
+}
+
+export function setSystemTime(millisSinceEpoch: number): void
+export function setSystemTime(date: Date): void
+export function setSystemTime(dateOrMillisSinceEpoch: Date | number): void
+export function setSystemTime(dateOrMillisSinceEpoch: Date | number): void {
+  return native.setTime(
+    dateOrMillisSinceEpoch instanceof Date
+      ? dateOrMillisSinceEpoch.getTime()
+      : dateOrMillisSinceEpoch,
+  )
+}
+
+export function memoryUsage() {
+  return native.memoryUsage()
+}
+
+export function jsMemoryUsage() {
+  return native.jsMemoryUsage()
+}
+
+export function gc() {
+  return native.gc()
+}
+
+export const version: string = native.version
+
+export const board = native.board
+
+export const firmware = native.firmware
+
+export const deviceId: string = native.deviceId
+
+export function restart(): never {
+  return native.restart() as never
+}
+
+export function exit(_exitCode?: number): never {
+  return native.restart() as never
+}
+
+export function panic(message: string): never {
+  throw new PanicError(message)
+}
+
+const buildDate = new Date(native.firmware.date)
+
+export class MonotonicTimestamp {
+  readonly uptimeMs: number
+
+  private constructor(uptimeMs: number) {
+    this.uptimeMs = uptimeMs
+  }
+
+  static now(): MonotonicTimestamp {
+    return new MonotonicTimestamp(uptime().rtc)
+  }
+
+  /** Rehydrate a previously-serialized timestamp. `uptimeMs` must be a
+   *  value that originated from `.uptimeMs` on a MonotonicTimestamp taken
+   *  within the current RTC reset cycle; values from prior reset cycles
+   *  will resolve to meaningless wall-clock times because the RTC counter
+   *  reset between then and now. Callers must guard cross-reset-cycle
+   *  misuse themselves (e.g. via a cold-boot session id). */
+  static fromRtcMs(uptimeMs: number): MonotonicTimestamp {
+    return new MonotonicTimestamp(uptimeMs)
+  }
+
+  /** Elapsed ms since another MonotonicTimestamp (NTP-independent) */
+  since(other: MonotonicTimestamp): number {
+    return this.uptimeMs - other.uptimeMs
+  }
+
+  /** Resolve to wall-clock epoch ms */
+  private resolveMs(): number {
+    const elapsed = uptime().rtc - this.uptimeMs
+    return Date.now() - elapsed
+  }
+
+  wallDate(): Result<Date, 'ClockNotSynced'> {
+    const date = new Date(this.resolveMs())
+    if (date < buildDate) return err('ClockNotSynced' as const)
+    return ok(date)
+  }
+}

package/runtime/sys/types.ts

@@ -0,0 +1,131 @@
+import type {Result} from '../result/types.js'
+
+export interface MemoryUsage {
+  heapUsed: number
+  heapTotal: number
+  /** Free system heap in bytes (0 on host) */
+  systemFree: number
+  /** All-time minimum free system heap in bytes (0 on host) */
+  systemMinFree: number
+  /** Total system heap in bytes (0 on host) */
+  systemTotal: number
+  /** Largest contiguous free block in bytes (0 on host). Allocations
+   *  larger than this fail even when `systemFree` is bigger — the gap
+   *  between `systemLargestFree` and `systemFree` measures heap
+   *  fragmentation. */
+  systemLargestFree: number
+}
+
+export interface Uptime {
+  /** Milliseconds since last boot (resets on deep sleep) */
+  readonly boot: number
+  /** Milliseconds from RTC clock (survives deep sleep) */
+  readonly rtc: number
+}
+
+export declare function uptime(): Uptime
+
+export declare function setSystemTime(timestamp: number): void
+export declare function setSystemTime(date: Date): void
+
+export declare function memoryUsage(): MemoryUsage
+
+/** Curated breakdown of the QuickJS engine heap — "where is memory
+ *  going?" Use this when `memoryUsage()` tells you the heap is full
+ *  and you want to know *what kind* of allocation dominates. Values
+ *  are in bytes unless the field name ends in `Count`. */
+export interface JsMemoryUsage {
+  /** Number of live JS strings */
+  strCount: number
+  /** Bytes held by live JS strings */
+  strSize: number
+  /** Number of live JS objects */
+  objCount: number
+  /** Bytes held by live JS object headers */
+  objSize: number
+  /** Number of object properties across all live objects */
+  propCount: number
+  /** Bytes held by property slots */
+  propSize: number
+  /** Number of distinct object shapes (hidden classes) */
+  shapeCount: number
+  /** Bytes held by shape descriptors */
+  shapeSize: number
+  /** Number of compiled JS functions in memory */
+  jsFuncCount: number
+  /** Bytes of compiled JS bytecode in memory (usually the biggest
+   *  contributor to QuickJS heap on an mikrojs app) */
+  jsFuncCodeSize: number
+  /** Number of live arrays (fast + slow) */
+  arrayCount: number
+  /** Total element slots across all fast arrays */
+  fastArrayElements: number
+  /** Bytes of backing storage for ArrayBuffer / TypedArray data */
+  binaryObjectSize: number
+}
+
+export declare function jsMemoryUsage(): JsMemoryUsage
+
+export declare function gc(): void
+
+/** Firmware version string (e.g. "0.1.0") */
+export declare const version: string
+
+export interface BoardInfo {
+  /** Board name from the firmware build (e.g. "xiao-esp32c6") or "generic" */
+  name: string
+  /** Chip target (e.g. "esp32c6") or "host" */
+  chip: string
+  /** Number of CPU cores */
+  cores: number
+  /** Silicon revision (major * 100 + minor on ESP32, 0 on host) */
+  revision: number
+  /** Supported features (e.g. ["wifi", "ble"]) */
+  features: string[]
+  /** Flash size in bytes (0 on host) */
+  flash: number
+  /** PSRAM size in bytes (0 if unavailable) */
+  psram: number
+}
+
+/** Board and hardware info */
+export declare const board: BoardInfo
+
+/** Unique device identifier encoded as Crockford's Base32 (10 lowercase
+ * characters, no special symbols). On ESP32, derived from the chip's
+ * base MAC address; the encoding is lossless so decoding the 10 chars
+ * yields the original 6 MAC bytes. On host/Node builds, derived from
+ * the hostname via FNV-1a hash (stable across restarts on the same
+ * machine). */
+export declare const deviceId: string
+
+/** Firmware build identifiers */
+export declare const firmware: {
+  /** ELF SHA256 hash on ESP32, "dev" on host */
+  readonly hash: string
+  /** Build date and time */
+  readonly date: string
+  /** ESP-IDF version, undefined on host */
+  readonly idfVersion: string | undefined
+}
+
+export declare function restart(): never
+
+export declare function exit(exitCode?: number): never
+
+/** Immediately crash with an error message. Use for unrecoverable situations. */
+export declare function panic(message: string): never
+
+export declare class MonotonicTimestamp {
+  readonly uptimeMs: number
+  private constructor(uptimeMs: number)
+  static now(): MonotonicTimestamp
+  /** Rehydrate a previously-serialized timestamp. The `uptimeMs` value
+   *  must come from the current RTC reset cycle; values from prior reset
+   *  cycles will resolve to meaningless wall-clock times. */
+  static fromRtcMs(uptimeMs: number): MonotonicTimestamp
+  /** Elapsed ms since another MonotonicTimestamp (NTP-independent) */
+  since(other: MonotonicTimestamp): number
+  /** Resolve to a Date. Returns err if the system clock is clearly not synced. */
+  wallDate(): Result<Date, 'ClockNotSynced'>
+}