@mikrojs/native 0.6.1 → 0.7.0

package/include/mikrojs/mikrojs.h

@@ -23,15 +23,25 @@ typedef struct MIKRunOptions {
     bool use_psram_heap;
 } MIKRunOptions;
 
+/* File-log flush policies. Mirror of `LogFlush` in the host-side TS type. */
+typedef enum MIKLogFlush {
+    MIK_LOG_FLUSH_ERROR = 0, /* default: buffer, flush on warn/error or buffer full */
+    MIK_LOG_FLUSH_LINE = 1,
+} MIKLogFlush;
+
 typedef struct MIKConfig {
-    bool restart_on_uncaught_exception;
-    int restart_delay_ms;
+    int panic_restart_delay_ms;
     size_t stack_size;
     uint32_t mem_reserved;
     uint32_t fs_read_max; /* 0 = keep runtime default (65536) */
     char entry_point[128];
     char wifi_country[3];   /* Two-letter country code + NUL, e.g. "NO" */
     char wifi_hostname[64]; /* DHCP hostname; empty = use mikrojs-<device-id> default */
+    /* File-log config. log_dir empty disables file logging; otherwise the
+     * file lives at "<log_dir>/log.txt" (rotated as ".../log.txt.1"). */
+    char log_dir[64];
+    uint32_t log_max_size;
+    MIKLogFlush log_flush;
 } MIKConfig;
 
 void MIK_DefaultConfig(MIKConfig* config);
@@ -306,6 +316,20 @@ void mik__proto_send(MIKReplTransport* transport, uint8_t type, const void* data
 void mik__proto_send_ok(MIKReplTransport* transport);
 void mik__proto_send_err(MIKReplTransport* transport, const char* msg);
 
+/* Tap called by mik__repl_proto_send_output with the raw body bytes (no
+ * TLV framing) before they're sent on the wire. Single slot — owned by
+ * the file logger on the device side. msg_type is the MIK_MSG_* value so
+ * the tap can pick the appropriate log level. */
+typedef void (*MIKLogEmitFn)(uint8_t msg_type, const void* data, size_t len);
+void mik__set_log_emit_tap(MIKLogEmitFn fn);
+
+/* True while mik__proto_send is writing TLV bytes to the transport.
+ * Platform-side transports (mik__console_write on the ESP32) check this
+ * to skip any installed wire-byte taps that would otherwise capture the
+ * framing in addition to the body. Single-task code path, so plain bool
+ * is sufficient — there's no other writer of this flag. */
+extern bool mik__proto_send_in_progress;
+
 /* ── Session primitives ─────────────────────────────────────────────
  * A protocol session is scoped to a transport (one client connection).
  * Runtimes are attached/detached within the session; a supervisor can

package/include/mikrojs/private.h

@@ -56,6 +56,18 @@ struct MIKRuntime {
     bool is_worker;
     bool freeing;
     bool stop_requested;  /* Set by promise rejection tracker to stop the loop */
+    /* Set by MIK_EnableTestHelpers — the test supervisor wants stop_requested
+     * to bubble up cleanly so it can synthesize a failing-test event and move
+     * to the next file. Without this flag, MIK_Stop would arm a panic-restart
+     * deadline and reboot the whole device mid-manifest on the first async
+     * rejection. */
+    bool test_mode;
+    /* Deferred restart deadline (boot_us, 0 = no pending restart). Set by
+     * MIK_Stop when an uncaught exception happens with a protocol REPL
+     * attached: the serve loop keeps reading commands until the deadline so
+     * the host can still deploy/clean/--recover during the grace window,
+     * then platform->restart() fires from MIK_Loop. */
+    int64_t restart_at_us;
     const char* fs_base_path;
     const char* fs_root;  /* Sandbox root for mikrojs/fs operations (separate from module resolution) */
     size_t fs_limit;      /* Max bytes for fs_root (0 = unlimited) */
@@ -259,6 +271,9 @@ void mik__repl_set_paused(bool paused);
 #define MIK_MSG_ERR 0x81
 #define MIK_MSG_CHECKSUM_RESULT 0x82
 #define MIK_MSG_CONFIG_ENTRIES 0x83
+/* Chunk of file bytes streamed in response to MIK_CMD_FS_GET.
+ * Multiple frames precede a final MSG_OK signaling end-of-file. */
+#define MIK_MSG_FS_CHUNK 0x84
 
 /* CLI → Device command types */
 #define MIK_CMD_EVAL 0x10
@@ -284,6 +299,10 @@ void mik__repl_set_paused(bool paused);
 #define MIK_CMD_RESTART 0x28
 #define MIK_CMD_RUNTIME_PAUSE 0x29
 #define MIK_CMD_RUNTIME_RESUME 0x2A
+/* Pull a file off the device. Payload: u16le path_len | path.
+ * Device replies with zero-or-more MIK_MSG_FS_CHUNK frames followed by
+ * MIK_MSG_OK on EOF, or MIK_MSG_ERR if the path can't be opened. */
+#define MIK_CMD_FS_GET 0x2B
 
 #define MIK_CMD_CONFIG_LIST 0x40
 #define MIK_CMD_CONFIG_SET 0x41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikrojs/native",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Mikro.js C++ runtime library and Node.js native addon",
   "keywords": [
     "esp32",
@@ -78,7 +78,7 @@
     "cmake-js": "^8.0.0",
     "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4",
-    "@mikrojs/quickjs": "0.6.1"
+    "@mikrojs/quickjs": "0.7.0"
   },
   "devDependencies": {
     "@swc/core": "^1.15.30",

package/runtime/fs/fs.ts

@@ -1,4 +1,4 @@
-import {ok} from 'mikrojs/result'
+import {err, ok} from 'mikrojs/result'
 import * as native from 'native:fs'
 
 import type {Result} from '../result/types.js'
@@ -61,28 +61,26 @@ export const exists = native.exists
 export function readStream(
   path: string,
   options?: ReadStreamOptions,
-): Result<AsyncIterable<Uint8Array>, FSError> {
+): Result<AsyncIterable<Result<Uint8Array, FSError>>, 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> {
+  async function* iterate(): AsyncIterable<Result<Uint8Array, FSError>> {
     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.
+          // path from the native side. Path-aware variants are decorated
+          // here so consumers see the original readStream context.
           const e = r.error
-          if (e.name === 'BadFileDescriptor' || e.name === 'Unknown') throw e
-          throw {...e, path}
+          yield e.name === 'BadFileDescriptor' || e.name === 'Unknown' ? err(e) : err({...e, path})
+          return
         }
         if (r.value === undefined) break
-        yield r.value
+        yield ok(r.value)
       }
     } finally {
       fh.close()

package/runtime/fs/types.ts

@@ -79,8 +79,8 @@ export interface ReadStreamOptions {
 
 /**
  * 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()`.
+ * initial open can fail; once iterating, mid-stream read errors arrive
+ * as a final `err(...)` item and end the stream.
  *
  * Compose with `mikrojs/stream` helpers (`decodeUtf8`, `splitLines`) for
  * text/line streams. Closes the underlying handle on EOF, mid-stream
@@ -89,4 +89,4 @@ export interface ReadStreamOptions {
 export declare function readStream(
   path: string,
   options?: ReadStreamOptions,
-): Result<AsyncIterable<Uint8Array>, FSError>
+): Result<AsyncIterable<Result<Uint8Array, FSError>>, FSError>

package/runtime/http/helpers.ts

@@ -3,7 +3,9 @@
 // LTE modem over UART) implement the `Request` type directly and reuse
 // `prepareBody` + `makeResponse` for the boring parts.
 
-import type {Result} from 'mikrojs/result'
+import {err, ok} from 'mikrojs/result'
+
+import type {Result} from '../result/types.js'
 
 export interface RequestOptions {
   method?: string
@@ -25,21 +27,24 @@ export interface Response {
   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`.
+   * Response body as an async iterable of byte chunks. Iteration yields
+   * `Result<Uint8Array, RequestError>` so mid-stream failures (network
+   * drop, abort, timeout) compose with the rest of the Result-based API.
+   * Single-shot: after any of `body`, `text()`, `bytes()`, or `json()`
+   * has started draining, the next consumer call throws
+   * `BodyConsumedError`.
    */
-  body: AsyncIterable<Uint8Array>
+  body: AsyncIterable<Result<Uint8Array, RequestError>>
   /** 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>
+  text(): Promise<Result<string, RequestError>>
   /** Drain body and parse as JSON. Throws `BodyConsumedError` on second consumer call. */
-  json(): Promise<unknown>
+  json(): Promise<Result<unknown, RequestError>>
   /** Drain body to a single `Uint8Array`. Throws `BodyConsumedError` on second consumer call. */
-  bytes(): Promise<Uint8Array>
+  bytes(): Promise<Result<Uint8Array, RequestError>>
   /**
    * Cancel the request and release any native resources. Safe to call after
    * the body has been consumed (no-op). Safe to call multiple times.
@@ -63,16 +68,11 @@ export const RequestError = {
   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,
+  /** Body drained but JSON.parse rejected the payload. */
+  InvalidJson: (message: string) => ({name: 'InvalidJson', message}) 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 type RequestError = ReturnType<(typeof RequestError)[keyof typeof RequestError]>
 
 export class BodyConsumedError extends Error {
   readonly name = 'BodyConsumed'
@@ -99,9 +99,9 @@ export function prepareBody(opts: RequestOptions): {
 }
 
 /**
- * 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.
+ * Wrap a transport's raw response (Result-yielding 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
@@ -109,7 +109,7 @@ export function makeResponse(raw: {
   url: string
   redirected: boolean
   headers: [string, string][]
-  body: AsyncIterable<Uint8Array>
+  body: AsyncIterable<Result<Uint8Array, RequestError>>
 }): Response {
   let consumed = false
   const claim = () => {
@@ -117,7 +117,7 @@ export function makeResponse(raw: {
     consumed = true
   }
 
-  const body: AsyncIterable<Uint8Array> = {
+  const body: AsyncIterable<Result<Uint8Array, RequestError>> = {
     [Symbol.asyncIterator]() {
       claim()
       return raw.body[Symbol.asyncIterator]()
@@ -153,7 +153,13 @@ export function makeResponse(raw: {
     },
     json: async () => {
       claim()
-      return JSON.parse(await drainAsText(raw.body))
+      const text = await drainAsText(raw.body)
+      if (!text.ok) return text
+      try {
+        return ok(JSON.parse(text.value))
+      } catch (e) {
+        return err(RequestError.InvalidJson(e instanceof Error ? e.message : String(e)))
+      }
     },
     bytes: async () => {
       claim()
@@ -177,29 +183,35 @@ function normalizeHeaders(
   return out
 }
 
-async function drain(source: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+async function drain(
+  source: AsyncIterable<Result<Uint8Array, RequestError>>,
+): Promise<Result<Uint8Array, RequestError>> {
   const parts: Uint8Array[] = []
   let total = 0
-  for await (const chunk of source) {
-    parts.push(chunk)
-    total += chunk.length
+  for await (const r of source) {
+    if (!r.ok) return r
+    parts.push(r.value)
+    total += r.value.length
   }
-  if (parts.length === 1) return parts[0]!
+  if (parts.length === 1) return ok(parts[0]!)
   const out = new Uint8Array(total)
   let offset = 0
   for (const p of parts) {
     out.set(p, offset)
     offset += p.length
   }
-  return out
+  return ok(out)
 }
 
-async function drainAsText(source: AsyncIterable<Uint8Array>): Promise<string> {
+async function drainAsText(
+  source: AsyncIterable<Result<Uint8Array, RequestError>>,
+): Promise<Result<string, RequestError>> {
   const decoder = new TextDecoder()
   let out = ''
-  for await (const chunk of source) {
-    out += decoder.decode(chunk, {stream: true})
+  for await (const r of source) {
+    if (!r.ok) return r
+    out += decoder.decode(r.value, {stream: true})
   }
   out += decoder.decode()
-  return out
+  return ok(out)
 }

package/runtime/http/native.ts

@@ -92,10 +92,10 @@ export function createRequestFromNative(native: NativeHttpModule): Request {
     const {status, headers: responseHeaders} = headersResult.value
 
     let done = false
-    const rawBody: AsyncIterable<Uint8Array> = {
+    const rawBody: AsyncIterable<Result<Uint8Array, RequestError>> = {
       [Symbol.asyncIterator]() {
         return {
-          async next() {
+          async next(): Promise<IteratorResult<Result<Uint8Array, RequestError>>> {
             if (done) return {done: true, value: undefined}
             let msg
             try {
@@ -103,19 +103,28 @@ export function createRequestFromNative(native: NativeHttpModule): Request {
             } catch (e) {
               done = true
               cleanup()
-              throw e
+              const message = e instanceof Error ? e.message : String(e)
+              return {done: false, value: err(RequestError.Network(message))}
             }
             if (msg.kind === 'chunk') {
-              return {done: false, value: msg.data}
+              return {done: false, value: ok(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'))
+              return {
+                done: false,
+                value: err(
+                  RequestError.Aborted(msg.message || String(options.signal?.reason ?? 'aborted')),
+                ),
+              }
+            }
+            return {
+              done: false,
+              value: err(RequestError.Network(msg.message || 'HTTP request failed')),
             }
-            throw RequestError.Network(msg.message || 'HTTP request failed')
           },
           async return() {
             if (!done) {

package/runtime/internal.d.ts

@@ -318,8 +318,8 @@ declare module 'native:uart' {
 
     read(): Result<
       {
-        next(): Promise<IteratorResult<Uint8Array>>
-        return(): Promise<IteratorResult<Uint8Array>>
+        next(): Promise<IteratorResult<Result<Uint8Array, UartError>>>
+        return(): Promise<IteratorResult<Result<Uint8Array, UartError>>>
       },
       UartError
     >

package/runtime/kv/shared.ts

@@ -1,4 +1,4 @@
-import {defineError, err, ok} from 'mikrojs/result'
+import {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'
@@ -8,12 +8,14 @@ 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}),
-})
+export const KVError = {
+  StorageFull: (message: string) => ({name: 'StorageFull', message}) as const,
+  EncodeFailed: (message: string) => ({name: 'EncodeFailed', message}) as const,
+  WriteFailed: (message: string) => ({name: 'WriteFailed', message}) as const,
+  ValidationFailed: (message: string, path: string) =>
+    ({name: 'ValidationFailed', message, path}) as const,
+  Unknown: (code: number, message: string) => ({name: 'Unknown', code, message}) as const,
+}
 
 /* Error codes from errors.h (MIK_ERR_BASE + 0xD0..0xD4) */
 const KV_INVALID_KEY = 0x80d0
@@ -43,7 +45,7 @@ function mapKvError(e: NativeError) {
     case KV_WRITE:
       return KVError.WriteFailed(e.message)
     default:
-      throw new Error(`unexpected native kv error: code=0x${e.code.toString(16)}`)
+      return KVError.Unknown(e.code, e.message)
   }
 }
 

package/runtime/kv/types.ts

@@ -55,6 +55,7 @@ export type KVError =
   | {name: 'EncodeFailed'; message: string}
   | {name: 'WriteFailed'; message: string}
   | {name: 'ValidationFailed'; message: string; path: string}
+  | {name: 'Unknown'; code: number; message: string}
 
 export type KVOptions<S> =
   | {

package/runtime/reader/reader.ts

@@ -9,12 +9,19 @@
  * lazy-load efficiency.
  */
 
+import {err, ok} from 'mikrojs/result'
+
+import type {Result} from '../result/types.js'
+
+export type ReaderError = {name: 'Timeout'; ms: number} | {name: 'StreamClosed'}
+
 /**
- * A buffered byte reader over an async iterator of byte chunks.
+ * A buffered byte reader over a Result-yielding 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:
+ * Wraps any `AsyncIterable<Result<Uint8Array, E>>` (typically
+ * `uart.read()`, `fs.readStream`, an HTTP body) 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
@@ -30,12 +37,12 @@
  *     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.
+ * Both `readUntil` and `readBytes` return `Result<Uint8Array, E |
+ * ReaderError>`: `err({name: 'Timeout', ms})` if the deadline expires
+ * before the request is satisfied, `err({name: 'StreamClosed'})` if
+ * the underlying iterator finishes early, or whatever error variant
+ * the source yields. `RangeError` is still thrown for invalid
+ * arguments (programmer mistakes, not stream errors).
  *
  * Timeout semantics: when a pull races against a `setTimeout` and
  * the timer wins, the pending `iter.next()` promise is kept so the
@@ -48,18 +55,21 @@
  * not protected against — the caller is responsible for
  * sequential ordering.
  */
-export class BufferedReader {
-  readonly #source: AsyncIterator<Uint8Array>
+export class BufferedReader<E = never> {
+  readonly #source: AsyncIterator<Result<Uint8Array, E>>
   #buffer: Uint8Array
-  #pending: Promise<IteratorResult<Uint8Array>> | null
+  #pending: Promise<IteratorResult<Result<Uint8Array, E>>> | null
 
-  constructor(source: AsyncIterable<Uint8Array>) {
-    this.#source = source[Symbol.asyncIterator]() as AsyncIterator<Uint8Array>
+  constructor(source: AsyncIterable<Result<Uint8Array, E>>) {
+    this.#source = source[Symbol.asyncIterator]() as AsyncIterator<Result<Uint8Array, E>>
     this.#buffer = new Uint8Array(0)
     this.#pending = null
   }
 
-  async readUntil(delimiter: Uint8Array, options: {timeoutMs: number}): Promise<Uint8Array> {
+  async readUntil(
+    delimiter: Uint8Array,
+    options: {timeoutMs: number},
+  ): Promise<Result<Uint8Array, E | ReaderError>> {
     if (delimiter.length === 0) {
       throw new RangeError('BufferedReader.readUntil: delimiter must be non-empty')
     }
@@ -69,24 +79,29 @@ export class BufferedReader {
       if (idx !== -1) {
         const out = this.#buffer.slice(0, idx)
         this.#buffer = this.#buffer.slice(idx + delimiter.length)
-        return out
+        return ok(out)
       }
-      await this.#pull(deadline)
+      const pull = await this.#pull(deadline, options.timeoutMs)
+      if (!pull.ok) return pull
     }
   }
 
-  async readBytes(count: number, options: {timeoutMs: number}): Promise<Uint8Array> {
+  async readBytes(
+    count: number,
+    options: {timeoutMs: number},
+  ): Promise<Result<Uint8Array, E | ReaderError>> {
     if (count < 0) {
       throw new RangeError('BufferedReader.readBytes: count must be non-negative')
     }
-    if (count === 0) return new Uint8Array(0)
+    if (count === 0) return ok(new Uint8Array(0))
     const deadline = Date.now() + options.timeoutMs
     while (this.#buffer.length < count) {
-      await this.#pull(deadline)
+      const pull = await this.#pull(deadline, options.timeoutMs)
+      if (!pull.ok) return pull
     }
     const out = this.#buffer.slice(0, count)
     this.#buffer = this.#buffer.slice(count)
-    return out
+    return ok(out)
   }
 
   /**
@@ -100,13 +115,9 @@ export class BufferedReader {
     this.#buffer = new Uint8Array(0)
   }
 
-  async #pull(deadline: number): Promise<void> {
+  async #pull(deadline: number, timeoutMs: number): Promise<Result<void, E | ReaderError>> {
     const remaining = deadline - Date.now()
-    if (remaining <= 0) {
-      const err = new Error(`BufferedReader: timeout waiting for bytes`)
-      err.name = 'TimeoutError'
-      throw err
-    }
+    if (remaining <= 0) return err({name: 'Timeout' as const, ms: timeoutMs})
 
     if (this.#pending === null) {
       this.#pending = this.#source.next()
@@ -116,24 +127,24 @@ export class BufferedReader {
     let timerId: ReturnType<typeof setTimeout> | undefined
     try {
       const result = await Promise.race([
-        pending.then((v): {kind: 'value'; v: IteratorResult<Uint8Array>} => ({kind: 'value', v})),
+        pending.then((v): {kind: 'value'; v: IteratorResult<Result<Uint8Array, E>>} => ({
+          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
+        return err({name: 'Timeout' as const, ms: timeoutMs})
       }
       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)
+      if (result.v.done) return err({name: 'StreamClosed' as const})
+      const item = result.v.value
+      if (!item.ok) return item
+      this.#buffer = concatBytes(this.#buffer, item.value)
+      return ok()
     } finally {
       if (timerId !== undefined) clearTimeout(timerId)
     }

package/runtime/reader/types.ts

@@ -7,10 +7,14 @@
  * `packages/mikrojs` and by user apps via their tsconfig.
  */
 
+import type {Result} from 'mikrojs/result'
+
+export type ReaderError = {name: 'Timeout'; ms: number} | {name: 'StreamClosed'}
+
 /**
- * A buffered byte reader over an async iterator of `Uint8Array`
- * chunks. Offers three operations that share the same underlying
- * buffer:
+ * A buffered byte reader over a Result-yielding 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.
@@ -19,16 +23,23 @@
  *   - `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.
+ * Returns `err({name: 'Timeout', ms})` if the deadline expires,
+ * `err({name: 'StreamClosed'})` if the underlying iterator finishes
+ * early, or the source's own error variant when it yields one.
+ * `RangeError` is still thrown for invalid arguments.
  *
  * 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>
+export declare class BufferedReader<E = never> {
+  constructor(source: AsyncIterable<Result<Uint8Array, E>>)
+  readUntil(
+    delimiter: Uint8Array,
+    options: {timeoutMs: number},
+  ): Promise<Result<Uint8Array, E | ReaderError>>
+  readBytes(
+    count: number,
+    options: {timeoutMs: number},
+  ): Promise<Result<Uint8Array, E | ReaderError>>
   drain(): void
 }