@mikrojs/native 0.0.7

package/runtime/fs/fs.ts

@@ -0,0 +1,93 @@
+import {ok} from 'mikrojs/result'
+import * as native from 'native:fs'
+
+import type {Result} from '../result/types.js'
+import type {
+  DirEntry,
+  FSError,
+  MkdirOptions,
+  ReadStreamOptions,
+  StatResult,
+  WriteFileOptions,
+} from './types.js'
+
+// native:fs emits typed FSError variants directly (see mik__fs_err_result in
+// src/fs.cpp), including the `path` field for path-level operations. These
+// wrappers are thin pass-throughs that only exist to expose a typed public
+// API surface for mikrojs/fs.
+
+export function readFile(path: string): Result<Uint8Array, FSError>
+export function readFile(path: string, encoding: 'utf-8'): Result<string, FSError>
+export function readFile(path: string, encoding?: 'utf-8'): Result<Uint8Array | string, FSError> {
+  return encoding ? native.readFile(path, encoding) : native.readFile(path)
+}
+
+export function writeFile(
+  path: string,
+  contents: string | Uint8Array,
+  options?: WriteFileOptions,
+): Result<void, FSError> {
+  return typeof contents === 'string'
+    ? native.writeFile(path, contents, options)
+    : native.writeFile(path, contents, options)
+}
+
+export function stat(path: string): Result<StatResult, FSError> {
+  return native.stat(path)
+}
+
+export function readDir(path: string): Result<DirEntry[], FSError> {
+  return native.readDir(path)
+}
+
+export function unlink(path: string): Result<void, FSError> {
+  return native.unlink(path)
+}
+
+export function rename(from: string, to: string): Result<void, FSError> {
+  return native.rename(from, to)
+}
+
+export function mkdir(path: string, options?: MkdirOptions): Result<void, FSError> {
+  return native.mkdir(path, options)
+}
+
+export function rmdir(path: string): Result<void, FSError> {
+  return native.rmdir(path)
+}
+
+export const exists = native.exists
+
+export function readStream(
+  path: string,
+  options?: ReadStreamOptions,
+): Result<AsyncIterable<Uint8Array>, FSError> {
+  const openResult = native.open(path)
+  if (!openResult.ok) return openResult
+  const fh = openResult.value
+  const chunkSize = options?.chunkSize ?? 512
+
+  async function* iterate(): AsyncIterable<Uint8Array> {
+    try {
+      while (true) {
+        const r = fh.read(chunkSize)
+        if (!r.ok) {
+          // Handle-level errors (BadFileDescriptor, Unknown) don't carry a
+          // path from the native side. All other variants include `path`
+          // when emitted by path-level ops — but fh.read doesn't have the
+          // path, so we decorate here to preserve the original readStream
+          // context.
+          const e = r.error
+          if (e.name === 'BadFileDescriptor' || e.name === 'Unknown') throw e
+          throw {...e, path}
+        }
+        if (r.value === undefined) break
+        yield r.value
+      }
+    } finally {
+      fh.close()
+    }
+  }
+
+  return ok(iterate())
+}

package/runtime/fs/types.ts

@@ -0,0 +1,92 @@
+import type {Result} from '../result/types.js'
+
+/**
+ * Curated FSError variants. Each carries only the context that's
+ * meaningful for that error:
+ *   - `path` for most entries
+ *   - `limit` for TooLarge (the readFile cap; currently always absent
+ *     because native doesn't report the configured fs_read_max back)
+ *   - `code`/`errno`/`message` for Unknown, carrying the raw native
+ *     error through for debugging when a POSIX errno falls outside
+ *     the curated set
+ *
+ * Discriminate on `.name`.
+ */
+export type FSError =
+  | {name: 'NotFound'; path: string}
+  | {name: 'AlreadyExists'; path: string}
+  | {name: 'AccessDenied'; path: string}
+  | {name: 'NoSpace'; path: string}
+  | {name: 'TooLarge'; path: string; limit?: number}
+  | {name: 'IsDirectory'; path: string}
+  | {name: 'NotDirectory'; path: string}
+  | {name: 'BadFileDescriptor'}
+  | {name: 'Unknown'; code: number; errno: number | undefined; message: string}
+
+export interface WriteFileOptions {
+  /** If false, fail with NotFound when the file doesn't exist. Default true. */
+  create?: boolean
+  /** If true, append instead of truncating. Default false. */
+  append?: boolean
+}
+
+export declare function writeFile(
+  path: string,
+  contents: string | Uint8Array,
+  options?: WriteFileOptions,
+): Result<void, FSError>
+
+export declare function readFile(path: string): Result<Uint8Array, FSError>
+export declare function readFile(path: string, encoding: 'utf-8'): Result<string, FSError>
+
+export interface StatResult {
+  size: number
+  isDirectory: boolean
+  isFile: boolean
+  /** Modification time in ms since epoch. Absent if the platform doesn't
+   * track it (e.g. LittleFS without CONFIG_LITTLEFS_USE_MTIME). */
+  mtime?: number
+}
+
+export declare function stat(path: string): Result<StatResult, FSError>
+
+export interface DirEntry {
+  name: string
+  isFile: boolean
+  isDirectory: boolean
+}
+
+export declare function readDir(path: string): Result<DirEntry[], FSError>
+export declare function unlink(path: string): Result<void, FSError>
+export declare function rename(from: string, to: string): Result<void, FSError>
+
+export interface MkdirOptions {
+  /** Create intermediate directories as needed (like `mkdir -p`). Default false. */
+  recursive?: boolean
+}
+
+export declare function mkdir(path: string, options?: MkdirOptions): Result<void, FSError>
+export declare function rmdir(path: string): Result<void, FSError>
+
+/** Returns true when the path exists and is reachable, false otherwise.
+ * Never fails — resolution errors collapse to false. */
+export declare function exists(path: string): boolean
+
+export interface ReadStreamOptions {
+  /** Bytes to read per chunk. Default 512. */
+  chunkSize?: number
+}
+
+/**
+ * Open a file as a stream of byte chunks. Returns a Result because the
+ * initial open can fail; once iterating, mid-stream read errors propagate
+ * via rejected promises from `next()`.
+ *
+ * Compose with `mikrojs/stream` helpers (`decodeUtf8`, `splitLines`) for
+ * text/line streams. Closes the underlying handle on EOF, mid-stream
+ * error, or early consumer break.
+ */
+export declare function readStream(
+  path: string,
+  options?: ReadStreamOptions,
+): Result<AsyncIterable<Uint8Array>, FSError>

package/runtime/globals.d.ts

@@ -0,0 +1,87 @@
+// Global APIs available in the QuickJS runtime environment
+
+declare function setTimeout(callback: (...args: any[]) => void, ms?: number): number
+declare function clearTimeout(id: number): void
+
+declare function setInterval(callback: (...args: any[]) => void, ms?: number): number
+declare function clearInterval(id: number): void
+
+declare const console: {
+  log(...args: unknown[]): void
+  warn(...args: unknown[]): void
+  error(...args: unknown[]): void
+  info(...args: unknown[]): void
+  debug(...args: unknown[]): void
+}
+
+declare function btoa(data: string): string
+declare function atob(data: string): string
+
+declare class TextEncoder {
+  encode(input?: string): Uint8Array
+}
+
+declare class TextDecoder {
+  constructor(label?: 'utf-8' | 'utf8')
+  decode(input?: ArrayBufferView | ArrayBuffer, options?: {stream?: boolean}): string
+}
+
+declare class AbortError extends Error {
+  constructor(message?: string)
+  readonly name: 'AbortError'
+}
+
+declare class TimeoutError extends Error {
+  constructor(message?: string)
+  readonly name: 'TimeoutError'
+}
+
+declare class AbortSignal {
+  readonly aborted: boolean
+  readonly reason: unknown
+  throwIfAborted(): void
+  onabort: (() => void) | null
+  addEventListener(type: 'abort', fn: () => void): void
+  removeEventListener(type: 'abort', fn: () => void): void
+  static abort(reason?: unknown): AbortSignal
+  static timeout(ms: number): AbortSignal
+  static any(signals: AbortSignal[]): AbortSignal
+}
+
+declare class AbortController {
+  readonly signal: AbortSignal
+  abort(reason?: unknown): void
+}
+
+declare interface ImportMeta {
+  readonly url: string
+  readonly main: boolean
+  readonly dirname: string
+  readonly basename: string
+  readonly path: string
+  readonly env: Readonly<Record<string, string | undefined>>
+  /**
+   * Evict a module from the runtime's module cache, recursively freeing
+   * any transitive dependency whose only importer was the unloaded module.
+   * Builtin modules (native:*, mikrojs/*, @mikrojs/*) are anchored
+   * and cannot be unloaded.
+   *
+   * Intended for use with dynamic imports: a static `import` at the top of
+   * the module creates a binding that pins the imported module's exports,
+   * so unloading it while the binding is live reclaims nothing. Prefer
+   * `const x = await import(spec)` + local scope + `import.meta.unload(spec)`.
+   *
+   * **Incompatible with `bundle: true`.** When the build bundles modules
+   * into chunks, source-level specifiers like `./phases/display.js` no
+   * longer correspond to loaded module names (they become chunk names like
+   * `display-GYVGL5MB.js`) — the unload call silently resolves to 0 and
+   * frees nothing. Projects that rely on dynamic-import-then-unload for
+   * memory reclaim need `bundle: false` so specifier strings survive to
+   * runtime unchanged.
+   *
+   * Resolves to the number of modules actually freed (root + transitive
+   * orphans), after a GC pass has run so a subsequent `memoryUsage()`
+   * snapshot reflects the reclaim.
+   */
+  unload(specifier: string): Promise<number>
+}

package/runtime/http/helpers.ts

@@ -0,0 +1,222 @@
+// Transport-agnostic HTTP request/response primitives. No dependency on
+// `native:http`. Apps driving HTTP through a non-lwIP transport (e.g. an
+// LTE modem over UART) implement the `Request` type directly and reuse
+// `prepareBody` + `makeResponse` for the boring parts.
+
+import type {Result} from 'mikrojs/result'
+
+export interface RequestOptions {
+  method?: string
+  /** Headers as pairs or a record. Keys used as-is (no implicit case change). */
+  headers?: [string, string][] | Record<string, string>
+  /** Shortcut: stringify as JSON and set `content-type: application/json`. */
+  json?: unknown
+  /** Raw body. Mutually exclusive with `json`. */
+  body?: Uint8Array | string
+  /** Total wallclock deadline; transport enforces. */
+  timeoutMs?: number
+  /** Transport owns listener install + cleanup. Maps abort to RequestError.Aborted. */
+  signal?: AbortSignal
+}
+
+export interface Response {
+  status: number
+  statusText: string
+  url: string
+  redirected: boolean
+  headers: [string, string][]
+  ok: boolean
+  /**
+   * Response body as an async iterable of chunks. Single-shot: after any of
+   * `body`, `text()`, `bytes()`, or `json()` has started draining, calling
+   * another consumer throws `BodyConsumedError`.
+   */
+  body: AsyncIterable<Uint8Array>
+  /** First matching header value, case-insensitive, or undefined if absent. */
+  get(name: string): string | undefined
+  /** All matching header values in order, case-insensitive. Empty array if absent. */
+  getAll(name: string): string[]
+  /** Drain body as a UTF-8 string. Throws `BodyConsumedError` on second consumer call. */
+  text(): Promise<string>
+  /** Drain body and parse as JSON. Throws `BodyConsumedError` on second consumer call. */
+  json(): Promise<unknown>
+  /** Drain body to a single `Uint8Array`. Throws `BodyConsumedError` on second consumer call. */
+  bytes(): Promise<Uint8Array>
+  /**
+   * Cancel the request and release any native resources. Safe to call after
+   * the body has been consumed (no-op). Safe to call multiple times.
+   */
+  close(): Promise<void>
+}
+
+export type Request = (
+  url: string,
+  options?: RequestOptions,
+) => Promise<Result<Response, RequestError>>
+
+export const RequestError = {
+  Hardware: (message: string) => ({name: 'Hardware', message}) as const,
+  Network: (message: string) => ({name: 'Network', message}) as const,
+  Timeout: (message: string) => ({name: 'Timeout', message}) as const,
+  /** Request body exceeded the transport's per-request cap. */
+  BodyTooLarge: (size: number, cap: number) => ({name: 'BodyTooLarge', size, cap}) as const,
+  /** Transport returned bytes that could not be parsed as an HTTP response. */
+  InvalidResponse: (message: string) => ({name: 'InvalidResponse', message}) as const,
+  Aborted: (message: string) => ({name: 'Aborted', message}) as const,
+  /** Transport is at its concurrent-request cap. Retry after in-flight requests settle. */
+  TooManyPending: () => ({name: 'TooManyPending'}) as const,
+}
+
+export type RequestError =
+  | ReturnType<typeof RequestError.Hardware>
+  | ReturnType<typeof RequestError.Network>
+  | ReturnType<typeof RequestError.Timeout>
+  | ReturnType<typeof RequestError.BodyTooLarge>
+  | ReturnType<typeof RequestError.InvalidResponse>
+  | ReturnType<typeof RequestError.Aborted>
+  | ReturnType<typeof RequestError.TooManyPending>
+
+export class BodyConsumedError extends Error {
+  readonly name = 'BodyConsumed'
+  constructor() {
+    super('response body already consumed')
+  }
+}
+
+const textEncoder = new TextEncoder()
+
+/**
+ * Normalize `RequestOptions` into the byte-oriented shape a transport actually
+ * sends: final body bytes (or null) and header pairs. Applies the `json`
+ * shortcut (encodes + sets content-type unless already present) and
+ * UTF-8-encodes string bodies.
+ */
+export function prepareBody(opts: RequestOptions): {
+  body: Uint8Array | null
+  headers: [string, string][]
+} {
+  const headers = normalizeHeaders(opts.headers)
+  if (opts.json !== undefined) {
+    if (!hasHeader(headers, 'content-type')) {
+      headers.push(['content-type', 'application/json'])
+    }
+    return {body: textEncoder.encode(JSON.stringify(opts.json)), headers}
+  }
+  if (opts.body === undefined) return {body: null, headers}
+  if (typeof opts.body === 'string') return {body: textEncoder.encode(opts.body), headers}
+  return {body: opts.body, headers}
+}
+
+/**
+ * Wrap a transport's raw response (async-iterable body) into the public
+ * `Response` shape with `text()`/`json()`/`bytes()`/`get()`/`getAll()`/`close()`
+ * and a single-shot body claim.
+ */
+export function makeResponse(raw: {
+  status: number
+  statusText: string
+  url: string
+  redirected: boolean
+  headers: [string, string][]
+  body: AsyncIterable<Uint8Array>
+}): Response {
+  let consumed = false
+  const claim = () => {
+    if (consumed) throw new BodyConsumedError()
+    consumed = true
+  }
+
+  const body: AsyncIterable<Uint8Array> = {
+    [Symbol.asyncIterator]() {
+      claim()
+      return raw.body[Symbol.asyncIterator]()
+    },
+  }
+
+  return {
+    status: raw.status,
+    statusText: raw.statusText,
+    url: raw.url,
+    redirected: raw.redirected,
+    headers: raw.headers,
+    ok: raw.status >= 200 && raw.status < 300,
+    body,
+    get: (name) => {
+      const lower = name.toLowerCase()
+      for (const [k, v] of raw.headers) {
+        if (k.toLowerCase() === lower) return v
+      }
+      return undefined
+    },
+    getAll: (name) => {
+      const lower = name.toLowerCase()
+      const out: string[] = []
+      for (const [k, v] of raw.headers) {
+        if (k.toLowerCase() === lower) out.push(v)
+      }
+      return out
+    },
+    text: async () => {
+      claim()
+      return await drainAsText(raw.body)
+    },
+    json: async () => {
+      claim()
+      return JSON.parse(await drainAsText(raw.body))
+    },
+    bytes: async () => {
+      claim()
+      return await drain(raw.body)
+    },
+    close: async () => {
+      consumed = true
+      const it = raw.body[Symbol.asyncIterator]()
+      if (it.return) await it.return()
+    },
+  }
+}
+
+function normalizeHeaders(
+  input: [string, string][] | Record<string, string> | undefined,
+): [string, string][] {
+  if (!input) return []
+  if (Array.isArray(input)) return input.map(([k, v]) => [k, v])
+  const out: [string, string][] = []
+  for (const key of Object.keys(input)) out.push([key, input[key]!])
+  return out
+}
+
+function hasHeader(headers: [string, string][], name: string): boolean {
+  const lower = name.toLowerCase()
+  for (const [k] of headers) {
+    if (k.toLowerCase() === lower) return true
+  }
+  return false
+}
+
+async function drain(source: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+  const parts: Uint8Array[] = []
+  let total = 0
+  for await (const chunk of source) {
+    parts.push(chunk)
+    total += chunk.length
+  }
+  if (parts.length === 1) return parts[0]!
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const p of parts) {
+    out.set(p, offset)
+    offset += p.length
+  }
+  return out
+}
+
+async function drainAsText(source: AsyncIterable<Uint8Array>): Promise<string> {
+  const decoder = new TextDecoder()
+  let out = ''
+  for await (const chunk of source) {
+    out += decoder.decode(chunk, {stream: true})
+  }
+  out += decoder.decode()
+  return out
+}

package/runtime/http/native.ts

@@ -0,0 +1,151 @@
+// Internal: native:http-backed request implementation. Bundled into
+// http/request.js; not exposed as its own subpath. Exists as a seam so host
+// tests can inject a fake native module.
+
+import {
+  makeResponse,
+  prepareBody,
+  type Request,
+  RequestError,
+  type RequestOptions,
+} from 'mikrojs/http/helpers'
+import {err, ok} from 'mikrojs/result'
+
+import type {ErrResult, Result} from '../result/types.js'
+
+type HttpRequestStart =
+  | {
+      ok: true
+      id: number
+      headers: Promise<Result<{status: number; headers: [string, string][]}, RequestError>>
+    }
+  | ErrResult<RequestError>
+
+export interface NativeHttpModule {
+  request: (
+    url: string,
+    options?: {method?: string; body?: Uint8Array; headers?: [string, string][]},
+  ) => HttpRequestStart
+  nextMessage: (
+    id: number,
+  ) => Promise<
+    | {kind: 'chunk'; data: Uint8Array}
+    | {kind: 'end'}
+    | {kind: 'error'; cancelled: boolean; message: string}
+  >
+  cancel: (id: number) => void
+  pendingCount: () => number
+}
+
+/**
+ * Build a `Request` function driven by a `native:http`-shaped module. Owns
+ * AbortSignal listener lifecycle and total-wallclock timeout enforcement.
+ *
+ * Callers are responsible for releasing the native pending slot by either
+ * draining the response body or calling `response.close()`. Leaks are
+ * observable via `pendingCount()`.
+ */
+export function createRequestFromNative(native: NativeHttpModule): Request {
+  return async (url: string, options: RequestOptions = {}) => {
+    if (options.signal?.aborted) {
+      return err(RequestError.Aborted(String(options.signal.reason ?? 'aborted')))
+    }
+
+    const {body, headers} = prepareBody(options)
+    const method = (options.method ?? 'GET').toUpperCase()
+
+    const start = native.request(url, {
+      method,
+      body: body ?? undefined,
+      headers,
+    })
+    if (!start.ok) return start
+
+    const id = start.id
+
+    let cleaned = false
+    let timeoutId: ReturnType<typeof setTimeout> | undefined
+    let abortHandler: (() => void) | undefined
+    const cleanup = () => {
+      if (cleaned) return
+      cleaned = true
+      if (abortHandler && options.signal) {
+        options.signal.removeEventListener('abort', abortHandler)
+      }
+      if (timeoutId !== undefined) clearTimeout(timeoutId)
+    }
+
+    if (options.timeoutMs !== undefined) {
+      timeoutId = setTimeout(() => native.cancel(id), options.timeoutMs)
+    }
+    if (options.signal) {
+      abortHandler = () => native.cancel(id)
+      options.signal.addEventListener('abort', abortHandler)
+    }
+
+    const headersResult = await start.headers
+    if (!headersResult.ok) {
+      cleanup()
+      return headersResult
+    }
+
+    const {status, headers: responseHeaders} = headersResult.value
+
+    let done = false
+    const rawBody: AsyncIterable<Uint8Array> = {
+      [Symbol.asyncIterator]() {
+        return {
+          async next() {
+            if (done) return {done: true, value: undefined}
+            let msg
+            try {
+              msg = await native.nextMessage(id)
+            } catch (e) {
+              done = true
+              cleanup()
+              throw e
+            }
+            if (msg.kind === 'chunk') {
+              return {done: false, value: msg.data}
+            }
+            done = true
+            cleanup()
+            if (msg.kind === 'end') return {done: true, value: undefined}
+            /* error */
+            if (msg.cancelled) {
+              throw RequestError.Aborted(msg.message || String(options.signal?.reason ?? 'aborted'))
+            }
+            throw RequestError.Network(msg.message || 'HTTP request failed')
+          },
+          async return() {
+            if (!done) {
+              done = true
+              cleanup()
+              native.cancel(id)
+              try {
+                for (;;) {
+                  const msg = await native.nextMessage(id)
+                  if (msg.kind !== 'chunk') break
+                }
+              } catch {
+                /* ignore */
+              }
+            }
+            return {done: true, value: undefined}
+          },
+        }
+      },
+    }
+
+    return ok(
+      makeResponse({
+        status,
+        statusText: '',
+        url,
+        redirected: false,
+        headers: responseHeaders,
+        body: rawBody,
+      }),
+    )
+  }
+}

package/runtime/http/request.ts

@@ -0,0 +1,25 @@
+import * as native from 'native:http'
+
+import {createRequestFromNative} from './native.js'
+
+/**
+ * Default HTTP request for the mikrojs runtime. Uses the ESP32 `native:http`
+ * transport, which streams response bodies chunk-by-chunk with reader-driven
+ * backpressure, integrates with `AbortSignal`, and enforces total-wallclock
+ * timeouts.
+ *
+ * For `RequestError`, `BodyConsumedError`, `prepareBody`, `makeResponse`, or
+ * any of the shared types, import from `mikrojs/http/helpers`. That subpath
+ * has no dependency on `native:http`, so importing it from custom transports
+ * (e.g. an LTE modem) doesn't retain the WiFi-backed HTTP stack.
+ */
+export const request = createRequestFromNative(native)
+
+/**
+ * Number of in-flight requests whose terminal message has not yet been
+ * consumed. Primarily useful in tests and diagnostic code to verify that
+ * cancel + drain correctly releases request slots.
+ */
+export function pendingCount(): number {
+  return native.pendingCount()
+}