@mikrojs/native 0.0.7

package/runtime/kv/types.ts

@@ -0,0 +1,150 @@
+import type {Result} from '../result/types.js'
+import type {
+  ArraySchema,
+  BooleanSchema,
+  Infer,
+  NumberSchema,
+  ObjectSchema,
+  OptionalSchema,
+  SchemaError,
+  StringSchema,
+  TupleSchema,
+  UnknownSchema,
+} from '../schema/types.js'
+
+export interface RtcMemoryInfo {
+  used: number
+  total: number
+  entries: number
+}
+
+export interface NvsStorageInfo {
+  /** Number of entries in the kv namespace. */
+  entries: number
+  /** Used entries across all NVS namespaces. */
+  used: number
+  /** Total entries in the NVS partition. */
+  total: number
+  /** Free entries in the NVS partition. */
+  free: number
+}
+
+/** Values that can be stored (CBOR-serializable). */
+export type Storable =
+  | number
+  | string
+  | boolean
+  | undefined
+  | Uint8Array
+  | Storable[]
+  | {[key: string]: Storable}
+
+/** Values that can be stored (CBOR-serializable). */
+export type StorableSchema =
+  | NumberSchema
+  | StringSchema
+  | UnknownSchema
+  | BooleanSchema
+  | OptionalSchema
+  | ArraySchema<StorableSchema>
+  | TupleSchema<StorableSchema[]>
+  | ObjectSchema<{[key: string]: StorableSchema}>
+
+export type KVError =
+  | {name: 'StorageFull'; message: string}
+  | {name: 'EncodeFailed'; message: string}
+  | {name: 'WriteFailed'; message: string}
+  | {name: 'ValidationFailed'; message: string; path: string}
+
+export type KVOptions<S> =
+  | {
+      schema: S
+      initialValue: Infer<S>
+      /** Called when reading stored data fails (decode error, schema mismatch).
+       *  On decode failure, corrupt data is deleted. On schema mismatch, stored data is kept.
+       *  Return a fallback value, or undefined. Default: `() => undefined`. */
+      onReadError: (error: KVError | SchemaError) => Infer<S>
+    }
+  | {
+      schema: OptionalSchema
+      initialValue?: Infer<S>
+      /** Called when reading stored data fails (decode error, schema mismatch).
+       *  On decode failure, corrupt data is deleted. On schema mismatch, stored data is kept.
+       *  Return a fallback value, or undefined. Default: `() => undefined`. */
+      onReadError?: (error: KVError | SchemaError) => Infer<S>
+    }
+  | {
+      schema?: never
+      initialValue: unknown
+      /** Called when reading stored data fails (decode error, schema mismatch).
+       *  On decode failure, corrupt data is deleted. On schema mismatch, stored data is kept.
+       *  Return a fallback value, or undefined. Default: `() => undefined`. */
+      onReadError: (error: KVError) => unknown
+    }
+  | {
+      schema?: never
+      initialValue?: unknown
+      /** Called when reading stored data fails (decode error, schema mismatch).
+       *  On decode failure, corrupt data is deleted. On schema mismatch, stored data is kept.
+       *  Return a fallback value, or undefined. Default: `() => undefined`. */
+      onReadError?: (error: KVError) => unknown
+    }
+
+export interface KVValue<T> {
+  /** Read the value. Returns undefined if the key doesn't exist. */
+  get(): T
+  /** Write a value, or delete the key if undefined. Returns the written value on success. */
+  set(value: T): Result<T, KVError>
+  /** Read, transform, and write. Receives undefined if key is missing. Return undefined to delete. */
+  update(updater: (value: T) => T): Result<T, KVError>
+  /** Remove the key. Returns ok on success, err if the storage operation fails. */
+  delete(): Result<void, KVError>
+}
+
+export type InferOpts<
+  Schema extends StorableSchema,
+  Options extends KVOptions<Schema>,
+> = Options extends {
+  schema?: never
+  initialValue: infer I
+  onReadError: (error: KVError) => infer V
+}
+  ? I | V
+  : Options extends {schema: infer S}
+    ? Infer<S>
+    : unknown
+
+export interface RtcStorage {
+  createValue<Schema extends StorableSchema, Opts extends KVOptions<Schema>>(
+    key: string,
+    options?: Opts,
+  ): KVValue<InferOpts<Schema, Opts>>
+
+  /** Clear all RTC data. */
+  clear(): void
+  /** Get info about RTC memory usage. */
+  info(): RtcMemoryInfo
+}
+
+/**
+ * NVS-backed key-value storage. Survives power cycles.
+ * Keys are limited to 15 characters (NVS constraint).
+ * Flash-backed: avoid high-frequency writes.
+ */
+export interface NvsStorage {
+  createValue<Schema extends StorableSchema, Opts extends KVOptions<Schema>>(
+    key: string,
+    options?: Opts,
+  ): KVValue<InferOpts<Schema, Opts>>
+
+  /** Erase all NVS key-value data. */
+  clear(): void
+  /** Get info about NVS key-value usage. */
+  info(): NvsStorageInfo
+}
+
+/** RTC memory store. Survives deep sleep, lost on power off. */
+export declare const rtcStorage: RtcStorage
+
+/** NVS flash store. Survives power cycles. */
+export declare const nvsStorage: NvsStorage

package/runtime/neopixel/neopixel.ts

@@ -0,0 +1,38 @@
+import {NeoPixel as NativeNeoPixel} from 'native:neopixel'
+
+import type {Result} from '../result/types.js'
+import type {NeoPixelError, NeoPixelOptions} from './types.js'
+
+export class NeoPixel {
+  #native: InstanceType<typeof NativeNeoPixel>
+
+  constructor(pin: number, options: NeoPixelOptions) {
+    this.#native = new NativeNeoPixel(pin, options.count, options.rgbw ? 4 : 3)
+  }
+
+  setPixel(
+    index: number,
+    r: number,
+    g: number,
+    b: number,
+    w?: number,
+  ): Result<void, NeoPixelError> {
+    return this.#native.setPixel(index, r, g, b, w ?? 0)
+  }
+
+  fill(r: number, g: number, b: number, w?: number): Result<void, NeoPixelError> {
+    return this.#native.fill(r, g, b, w ?? 0)
+  }
+
+  show(): Result<void, NeoPixelError> {
+    return this.#native.show()
+  }
+
+  clear(): Result<void, NeoPixelError> {
+    return this.#native.clear()
+  }
+
+  end(): Result<void, NeoPixelError> {
+    return this.#native.end()
+  }
+}

package/runtime/neopixel/types.ts

@@ -0,0 +1,27 @@
+import type {Result} from '../result/types.js'
+
+export interface NeoPixelOptions {
+  /** Number of LEDs in the strip */
+  count: number
+  /** Set to true for RGBW strips (SK6812). Defaults to false (RGB/WS2812). */
+  rgbw?: boolean
+}
+
+export type NeoPixelError =
+  | {name: 'NotActive'}
+  | {name: 'IndexOutOfRange'}
+  | {name: 'ShowFailed'; message: string}
+
+export declare class NeoPixel {
+  constructor(pin: number, options: NeoPixelOptions)
+  /** Set a single pixel's color (0–255 per channel) */
+  setPixel(index: number, r: number, g: number, b: number, w?: number): Result<void, NeoPixelError>
+  /** Set all pixels to the same color */
+  fill(r: number, g: number, b: number, w?: number): Result<void, NeoPixelError>
+  /** Transmit the pixel buffer to the strip */
+  show(): Result<void, NeoPixelError>
+  /** Turn off all pixels and transmit */
+  clear(): Result<void, NeoPixelError>
+  /** Release the RMT channel */
+  end(): Result<void, NeoPixelError>
+}

package/runtime/pin/pin.ts

@@ -0,0 +1,51 @@
+import * as native from 'native:pin'
+
+import type {Result} from '../result/types.js'
+import type {AnalogReadOptions, Attenuation, PinError, PinMode} from './types.js'
+
+// Public mode lookup. Kept as a runtime value (rather than inlined) because
+// user code occasionally reads it to build a mode-picker UI on host-side
+// tooling; the native:pin layer uses the numeric constants directly.
+const PIN_MODE_INPUT = 0x01
+const PIN_MODE_OUTPUT = 0x03
+const PIN_MODE_INPUT_PULLUP = 0x05
+
+export const NativePinModes = {
+  INPUT: PIN_MODE_INPUT,
+  OUTPUT: PIN_MODE_OUTPUT,
+  INPUT_PULLUP: PIN_MODE_INPUT_PULLUP,
+} as const
+
+const NativeAttenuation: Record<Attenuation, number> = {
+  '0db': 0,
+  '2.5db': 1,
+  '6db': 2,
+  '11db': 3,
+} as const
+
+// Wrappers translate the string/enum JS-idiom args to the numeric codes the
+// native layer expects. Errors flow through unchanged: native:pin returns
+// {ok, error:{name,message}} directly (see mik_pin.cpp), so no remapping.
+
+export function pinMode(pin: number, mode: PinMode): Result<void, PinError> {
+  return native.pinMode(pin, NativePinModes[mode])
+}
+
+export function digitalWrite(pin: number, value: 0 | 1): Result<void, PinError> {
+  return native.digitalWrite(pin, value)
+}
+
+export function digitalRead(pin: number): 0 | 1 {
+  return native.digitalRead(pin) as 0 | 1
+}
+
+export function analogRead(pin: number, options?: AnalogReadOptions): Result<number, PinError> {
+  return native.analogRead(pin, NativeAttenuation[options?.attenuation ?? '11db'])
+}
+
+export function analogReadMillivolts(
+  pin: number,
+  options?: AnalogReadOptions,
+): Result<number, PinError> {
+  return native.analogReadMillivolts(pin, NativeAttenuation[options?.attenuation ?? '11db'])
+}

package/runtime/pin/types.ts

@@ -0,0 +1,49 @@
+import type {Result} from '../result/types.js'
+
+export type PinMode = 'INPUT' | 'OUTPUT' | 'INPUT_PULLUP'
+
+/**
+ * ADC attenuation setting, controls the measurable voltage range.
+ * - `'0db'` — 0–750 mV
+ * - `'2.5db'` — 0–1050 mV
+ * - `'6db'` — 0–1300 mV
+ * - `'11db'` — 0–2500 mV (default)
+ */
+export type Attenuation = '0db' | '2.5db' | '6db' | '11db'
+
+export interface AnalogReadOptions {
+  /** ADC attenuation. Defaults to `'11db'` (0–2500 mV range). */
+  attenuation?: Attenuation
+}
+
+export type PinError =
+  | {name: 'InvalidPin'; message: string}
+  | {name: 'SetModeFailed'; message: string}
+  | {name: 'WriteFailed'; message: string}
+  | {name: 'AdcInitFailed'; message: string}
+  | {name: 'AdcReadFailed'; message: string}
+  | {name: 'InvalidAdcPin'}
+
+export declare function pinMode(pin: number, mode: PinMode): Result<void, PinError>
+
+export declare function digitalWrite(pin: number, value: 0 | 1): Result<void, PinError>
+
+export declare function digitalRead(pin: number): 0 | 1
+
+/**
+ * Read the raw ADC value from a pin.
+ * @returns A Result containing a 12-bit integer (0–4095) proportional to the input voltage, or a PinError.
+ */
+export declare function analogRead(
+  pin: number,
+  options?: AnalogReadOptions,
+): Result<number, PinError>
+
+/**
+ * Read a calibrated voltage from a pin.
+ * @returns A Result containing the input voltage in millivolts, or a PinError.
+ */
+export declare function analogReadMillivolts(
+  pin: number,
+  options?: AnalogReadOptions,
+): Result<number, PinError>

package/runtime/pwm/pwm.ts

@@ -0,0 +1,32 @@
+import {ok} from 'mikrojs/result'
+import {Pwm as NativePwm} from 'native:pwm'
+
+import type {Result} from '../result/types.js'
+import type {PwmError, PwmOptions} from './types.js'
+
+export class Pwm {
+  #native: InstanceType<typeof NativePwm>
+
+  constructor(pin: number, options: PwmOptions) {
+    this.#native = new NativePwm(pin, options.freq, options.duty ?? 0)
+  }
+
+  duty(value?: number): Result<number, PwmError> {
+    return this.#native.duty(value)
+  }
+
+  freq(value?: number): Result<number, PwmError> {
+    return this.#native.freq(value)
+  }
+
+  async fade(targetDuty: number, durationMs: number): Promise<Result<void, PwmError>> {
+    const result = this.#native.fade(targetDuty, durationMs)
+    if (!result.ok) return result
+    await result.value
+    return ok(undefined)
+  }
+
+  end(): Result<void, PwmError> {
+    return this.#native.end()
+  }
+}

package/runtime/pwm/types.ts

@@ -0,0 +1,29 @@
+import type {Result} from '../result/types.js'
+
+export interface PwmOptions {
+  /** Frequency in Hz */
+  freq: number
+  /** Initial duty cycle, 0.0–1.0. Defaults to 0. */
+  duty?: number
+}
+
+export type PwmError =
+  | {name: 'NoChannel'; message: string}
+  | {name: 'NoTimer'; message: string}
+  | {name: 'ConfigFailed'; message: string}
+  | {name: 'NotActive'}
+  | {name: 'DutyFailed'; message: string}
+  | {name: 'FreqFailed'; message: string}
+  | {name: 'FadeFailed'; message: string}
+
+export declare class Pwm {
+  constructor(pin: number, options: PwmOptions)
+  /** Get or set duty cycle (0.0–1.0) */
+  duty(value?: number): Result<number, PwmError>
+  /** Get or set frequency in Hz */
+  freq(value?: number): Result<number, PwmError>
+  /** Hardware fade to target duty over duration. Returns promise with result. */
+  fade(targetDuty: number, durationMs: number): Promise<Result<void, PwmError>>
+  /** Stop PWM and release the channel */
+  end(): Result<void, PwmError>
+}

package/runtime/reader/reader.ts

@@ -0,0 +1,167 @@
+/**
+ * Byte-level protocol reader for mikrojs.
+ *
+ * Separate runtime module from `mikrojs/stream` so that apps which
+ * only need a buffered reader (a modem driver, a log framer, an HTTP
+ * body splitter) don't pay the load cost of the async-iterator
+ * transforms in `mikrojs/stream`. Both modules share the same
+ * single-consumer design philosophy; they're separated only for
+ * lazy-load efficiency.
+ */
+
+/**
+ * A buffered byte reader over an async iterator of byte chunks.
+ *
+ * Wraps any `AsyncIterable<Uint8Array>` (typically `uart.read()`,
+ * eventually also TCP sockets) and exposes three primitives that
+ * share the same underlying byte buffer:
+ *
+ *   - `readUntil(delimiter, {timeoutMs})` — pull chunks until the
+ *     buffer contains `delimiter`, return everything before it and
+ *     consume the delimiter. The AT-channel workhorse: passes
+ *     `CRLF` to read a line, or `'> '` to wait for a prompt.
+ *
+ *   - `readBytes(count, {timeoutMs})` — pull chunks until the buffer
+ *     has at least `count` bytes, return the first `count` and keep
+ *     the rest. Used for length-prefixed binary payloads (e.g.
+ *     HTTP response bodies after `+SHREAD`).
+ *
+ *   - `drain()` — discard any buffered bytes without touching the
+ *     underlying iterator. Useful before sending a new command when
+ *     stale bytes from a previous response might be left over.
+ *
+ * Both `readUntil` and `readBytes` throw `TimeoutError` (an Error
+ * with `name === 'TimeoutError'`) if the deadline expires before
+ * the request is satisfied, and `StreamClosed` (an Error with
+ * `name === 'StreamClosed'`) if the underlying iterator finishes
+ * before the request is satisfied. Callers may wrap those in their
+ * own Result type if they prefer structured error handling.
+ *
+ * Timeout semantics: when a pull races against a `setTimeout` and
+ * the timer wins, the pending `iter.next()` promise is kept so the
+ * NEXT pull resumes on the same chunk — bytes received during the
+ * timed-out window are not dropped. This matches the behavior of
+ * hand-written AT channels and is what you want for command retries.
+ *
+ * This reader is intentionally **single-consumer**. Interleaving
+ * concurrent `readUntil` / `readBytes` calls is not supported and
+ * not protected against — the caller is responsible for
+ * sequential ordering.
+ */
+export class BufferedReader {
+  readonly #source: AsyncIterator<Uint8Array>
+  #buffer: Uint8Array
+  #pending: Promise<IteratorResult<Uint8Array>> | null
+
+  constructor(source: AsyncIterable<Uint8Array>) {
+    this.#source = source[Symbol.asyncIterator]() as AsyncIterator<Uint8Array>
+    this.#buffer = new Uint8Array(0)
+    this.#pending = null
+  }
+
+  async readUntil(delimiter: Uint8Array, options: {timeoutMs: number}): Promise<Uint8Array> {
+    if (delimiter.length === 0) {
+      throw new RangeError('BufferedReader.readUntil: delimiter must be non-empty')
+    }
+    const deadline = Date.now() + options.timeoutMs
+    while (true) {
+      const idx = indexOfBytes(this.#buffer, delimiter)
+      if (idx !== -1) {
+        const out = this.#buffer.slice(0, idx)
+        this.#buffer = this.#buffer.slice(idx + delimiter.length)
+        return out
+      }
+      await this.#pull(deadline)
+    }
+  }
+
+  async readBytes(count: number, options: {timeoutMs: number}): Promise<Uint8Array> {
+    if (count < 0) {
+      throw new RangeError('BufferedReader.readBytes: count must be non-negative')
+    }
+    if (count === 0) return new Uint8Array(0)
+    const deadline = Date.now() + options.timeoutMs
+    while (this.#buffer.length < count) {
+      await this.#pull(deadline)
+    }
+    const out = this.#buffer.slice(0, count)
+    this.#buffer = this.#buffer.slice(count)
+    return out
+  }
+
+  /**
+   * Discard buffered bytes. Leaves `#pending` alone so any in-flight
+   * `iter.next()` from a previously timed-out pull still gets
+   * consumed on the next read — we only want to drop stale bytes
+   * that were already delivered, not bytes the source hasn't sent
+   * yet.
+   */
+  drain(): void {
+    this.#buffer = new Uint8Array(0)
+  }
+
+  async #pull(deadline: number): Promise<void> {
+    const remaining = deadline - Date.now()
+    if (remaining <= 0) {
+      const err = new Error(`BufferedReader: timeout waiting for bytes`)
+      err.name = 'TimeoutError'
+      throw err
+    }
+
+    if (this.#pending === null) {
+      this.#pending = this.#source.next()
+    }
+    const pending = this.#pending
+
+    let timerId: ReturnType<typeof setTimeout> | undefined
+    try {
+      const result = await Promise.race([
+        pending.then((v): {kind: 'value'; v: IteratorResult<Uint8Array>} => ({kind: 'value', v})),
+        new Promise<{kind: 'timeout'}>((resolve) => {
+          timerId = setTimeout(() => resolve({kind: 'timeout'}), remaining)
+        }),
+      ])
+      if (result.kind === 'timeout') {
+        // Leave #pending intact so the next pull resumes on this chunk.
+        const err = new Error(`BufferedReader: timeout after ${remaining}ms waiting for bytes`)
+        err.name = 'TimeoutError'
+        throw err
+      }
+      this.#pending = null
+      if (result.v.done) {
+        const err = new Error('BufferedReader: stream closed before read satisfied')
+        err.name = 'StreamClosed'
+        throw err
+      }
+      this.#buffer = concatBytes(this.#buffer, result.v.value)
+    } finally {
+      if (timerId !== undefined) clearTimeout(timerId)
+    }
+  }
+}
+
+/** Find the first index of `needle` in `haystack`, or -1 if not found. */
+function indexOfBytes(haystack: Uint8Array, needle: Uint8Array): number {
+  if (needle.length === 0) return 0
+  const limit = haystack.length - needle.length
+  for (let i = 0; i <= limit; i++) {
+    let ok = true
+    for (let j = 0; j < needle.length; j++) {
+      if (haystack[i + j] !== needle[j]) {
+        ok = false
+        break
+      }
+    }
+    if (ok) return i
+  }
+  return -1
+}
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  if (a.length === 0) return b
+  if (b.length === 0) return a
+  const out = new Uint8Array(a.length + b.length)
+  out.set(a, 0)
+  out.set(b, a.length)
+  return out
+}

package/runtime/reader/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Public types for `mikrojs/reader`.
+ *
+ * Runtime implementation lives in `./reader.ts` and is compiled to
+ * bytecode at firmware build time. This file is the declaration-only
+ * surface consumed by the `mikrojs/reader` re-export in
+ * `packages/mikrojs` and by user apps via their tsconfig.
+ */
+
+/**
+ * A buffered byte reader over an async iterator of `Uint8Array`
+ * chunks. Offers three operations that share the same underlying
+ * buffer:
+ *
+ *   - `readUntil(delimiter, {timeoutMs})` — return everything before
+ *     the first occurrence of `delimiter`, consume the delimiter.
+ *   - `readBytes(count, {timeoutMs})` — return exactly `count` bytes,
+ *     pulling more source chunks as needed.
+ *   - `drain()` — discard buffered bytes without affecting the
+ *     underlying iterator.
+ *
+ * Throws an Error with `name === 'TimeoutError'` if the deadline
+ * expires before the request is satisfied, or `name === 'StreamClosed'`
+ * if the underlying iterator finishes before the request is satisfied.
+ *
+ * Single-consumer only: concurrent `readUntil` / `readBytes` calls on
+ * the same instance are unsupported.
+ */
+export declare class BufferedReader {
+  constructor(source: AsyncIterable<Uint8Array>)
+  readUntil(delimiter: Uint8Array, options: {timeoutMs: number}): Promise<Uint8Array>
+  readBytes(count: number, options: {timeoutMs: number}): Promise<Uint8Array>
+  drain(): void
+}

package/runtime/result/native-result.node-shim.ts

@@ -0,0 +1,44 @@
+// Host-side shim for `native:result` used only in vitest (Node) where the
+// mikrojs C runtime isn't available. Keep in sync with mik_result.cpp.
+
+const proto = {
+  map(this: {ok: boolean; value?: unknown; error?: unknown}, fn: (v: unknown) => unknown) {
+    return this.ok ? ok(fn(this.value)) : this
+  },
+  mapErr(this: {ok: boolean; value?: unknown; error?: unknown}, fn: (e: unknown) => unknown) {
+    return this.ok ? this : err(fn(this.error))
+  },
+  andThen(this: {ok: boolean; value?: unknown; error?: unknown}, fn: (v: unknown) => unknown) {
+    return this.ok ? fn(this.value) : this
+  },
+  match(
+    this: {ok: boolean; value?: unknown; error?: unknown},
+    handlers: {ok: (v: unknown) => unknown; err: (e: unknown) => unknown},
+  ) {
+    return this.ok ? handlers.ok(this.value) : handlers.err(this.error)
+  },
+  orDefault(this: {ok: boolean; value?: unknown; error?: unknown}, defaultValue: unknown) {
+    return this.ok ? this.value : defaultValue
+  },
+  orPanic(this: {ok: boolean; value?: unknown; error?: unknown}, message: string) {
+    if (this.ok) return this.value
+    const panic = new Error(message)
+    panic.name = 'PanicError'
+    ;(panic as Error & {cause?: unknown}).cause = this.error
+    throw panic
+  },
+}
+
+export function ok(value?: unknown): unknown {
+  const r = Object.create(proto)
+  r.ok = true
+  if (arguments.length > 0) r.value = value
+  return r
+}
+
+export function err(error: unknown): unknown {
+  const r = Object.create(proto)
+  r.ok = false
+  r.error = error
+  return r
+}

package/runtime/result/result.ts

@@ -0,0 +1,26 @@
+export {err, ok} from 'native:result'
+
+export class PanicError extends Error {
+  constructor(message: string, options?: {cause?: unknown}) {
+    super(message, options)
+    this.name = 'PanicError'
+  }
+}
+
+export function defineError<D extends Record<string, (...args: any[]) => Record<string, unknown>>>(
+  _name: string,
+  variants: D,
+): {[K in keyof D & string]: (...args: Parameters<D[K]>) => {name: K} & ReturnType<D[K]>} {
+  const constructors: Record<string, (...args: unknown[]) => Record<string, unknown>> = {}
+  for (const key in variants) {
+    const factory = variants[key]!
+    constructors[key] = (...args: unknown[]) => {
+      const fields = (factory as (...a: unknown[]) => Record<string, unknown>)(...args)
+      fields.name = key
+      return fields
+    }
+  }
+  return constructors as unknown as {
+    [K in keyof D & string]: (...args: Parameters<D[K]>) => {name: K} & ReturnType<D[K]>
+  }
+}