@gurezo/web-serial-rxjs 3.0.0 → 3.1.0

package/dist/index.mjs

@@ -17,28 +17,32 @@ var SerialErrorCode = {
   /**
    * Browser does not support the Web Serial API.
    *
-   * This error occurs when attempting to use serial port functionality in a browser
-   * that doesn't support the Web Serial API. Supported desktop browsers are Chrome,
-   * Edge, Opera, and Firefox 151+. Safari and mobile browsers are not supported.
+   * Emitted on `connect$` when `navigator.serial` is unavailable.
    *
    * **Suggested action**: Inform the user to use a supported browser.
+   *
+   * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/438 | Issue #438}
    */
   BROWSER_NOT_SUPPORTED: "BROWSER_NOT_SUPPORTED",
   /**
    * Serial port is not available.
    *
-   * This error occurs when a requested port cannot be accessed, such as when
-   * getting previously granted ports fails or when the port is already in use
-   * by another application.
+   * **Reserved — not emitted in v3.x.** The current implementation uses only
+   * `navigator.serial.requestPort`; there is no `getPorts` API path. Scheduled
+   * for removal in the next major version.
+   *
+   * **Suggested action**: Handle port acquisition failures with
+   * {@link SerialErrorCode.PORT_OPEN_FAILED} or
+   * {@link SerialErrorCode.OPERATION_CANCELLED} instead.
    *
-   * **Suggested action**: Check if the port is available or being used by another application.
+   * @deprecated Not emitted at runtime in v3.x. Will be removed in the next major version.
+   * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/438 | Issue #438}
    */
   PORT_NOT_AVAILABLE: "PORT_NOT_AVAILABLE",
   /**
    * Failed to open the serial port.
    *
-   * This error occurs when the port cannot be opened, typically due to incorrect
-   * connection parameters, hardware issues, or permission problems.
+   * Emitted on `connect$` when `port.open()` rejects.
    *
    * **Suggested action**: Verify connection parameters and check hardware connections.
    */
@@ -46,8 +50,8 @@ var SerialErrorCode = {
   /**
    * Serial port is already open.
    *
-   * This error occurs when attempting to open a port that is already connected.
-   * Only one connection can be active at a time per SerialClient instance.
+   * Emitted on `connect$` when the session is not in `'idle'` or `'error'`
+   * (non-fatal; session state is unchanged).
    *
    * **Suggested action**: Disconnect the current port before connecting a new one.
    */
@@ -55,10 +59,10 @@ var SerialErrorCode = {
   /**
    * Serial port is not open.
    *
-   * This error occurs when attempting to read from or write to a port that hasn't
-   * been opened yet. The port must be connected before performing I/O operations.
+   * Emitted when `send$` or `disconnect$` is called in an invalid session
+   * state (for example before `connect$` completes).
    *
-   * **Suggested action**: Call {@link SerialClient.connect} before reading or writing.
+   * **Suggested action**: Call {@link SerialSession.connect$} before sending data.
    */
   PORT_NOT_OPEN: "PORT_NOT_OPEN",
   /**
@@ -111,8 +115,12 @@ var SerialErrorCode = {
   /**
    * Operation timed out before completion.
    *
-   * This error occurs when an operation waits for a condition (for example, prompt
-   * detection) and the timeout period elapses first.
+   * **Reserved — not emitted in v3.x.** No timeout / prompt detection /
+   * transaction API exists yet. Scheduled for removal in the next major version
+   * unless a future API adopts this code.
+   *
+   * @deprecated Not emitted at runtime in v3.x. Will be removed in the next major version.
+   * @see {@link https://github.com/gurezo/web-serial-rxjs/issues/438 | Issue #438}
    */
   OPERATION_TIMEOUT: "OPERATION_TIMEOUT",
   /**
@@ -191,10 +199,11 @@ var SerialErrorCode = {
   /**
    * Unknown error occurred.
    *
-   * This error code is used for errors that don't fit into any other category.
-   * The original error details may be available in the error's message or originalError property.
+   * Emitted as a fallback when dispose or disconnect encounters an error that
+   * cannot be classified more specifically. The underlying failure is on
+   * {@link SerialError.context | context.cause}.
    *
-   * **Suggested action**: Check the error message and originalError for more details.
+   * **Suggested action**: Check the error message and `context.cause` for more details.
    */
   UNKNOWN: "UNKNOWN"
 };
@@ -305,6 +314,89 @@ function createNewlineTokenizer(mode) {
   };
 }
 
+// src/internal/strip-ansi-sequences.ts
+var ESC = "\x1B";
+var CSI_FINAL_BYTE = /[@-~]/;
+var BEL = "\x07";
+var OSC_STRING_TERMINATOR = "\x1B\\";
+function findOscTerminator(oscBody) {
+  let earliest = null;
+  const belIndex = oscBody.indexOf(BEL);
+  if (belIndex >= 0) {
+    earliest = { index: belIndex, length: 1 };
+  }
+  const stIndex = oscBody.indexOf(OSC_STRING_TERMINATOR);
+  if (stIndex >= 0) {
+    const candidate = { index: stIndex, length: OSC_STRING_TERMINATOR.length };
+    if (!earliest || stIndex < earliest.index) {
+      earliest = candidate;
+    }
+  }
+  return earliest;
+}
+function createAnsiStripper() {
+  let pending = "";
+  const feed = (chunk) => {
+    const input = pending + chunk;
+    pending = "";
+    let output = "";
+    let i = 0;
+    while (i < input.length) {
+      const escIndex = input.indexOf(ESC, i);
+      if (escIndex < 0) {
+        output += input.slice(i);
+        break;
+      }
+      output += input.slice(i, escIndex);
+      const next = escIndex + 1;
+      if (next >= input.length) {
+        pending = ESC;
+        break;
+      }
+      const code = input.charCodeAt(next);
+      if (code === 91) {
+        const csiStart = next + 1;
+        let j = csiStart;
+        while (j < input.length && !CSI_FINAL_BYTE.test(input.charAt(j))) {
+          j++;
+        }
+        if (j < input.length) {
+          i = j + 1;
+          continue;
+        }
+        pending = input.slice(escIndex);
+        break;
+      }
+      if (code === 93) {
+        const oscBody = input.slice(next);
+        const terminator = findOscTerminator(oscBody);
+        if (terminator) {
+          i = escIndex + 1 + terminator.index + terminator.length;
+          continue;
+        }
+        pending = input.slice(escIndex);
+        break;
+      }
+      if (next < input.length) {
+        i = next + 1;
+        continue;
+      }
+      pending = input.slice(escIndex);
+      break;
+    }
+    return output;
+  };
+  const flush = () => {
+    if (pending.length === 0) {
+      return "";
+    }
+    const remainder = pending;
+    pending = "";
+    return remainder;
+  };
+  return { feed, flush };
+}
+
 // src/terminal/create-terminal-buffer.ts
 function applyTerminalChunk(state, chunk) {
   const tokenizer = createNewlineTokenizer("terminal");
@@ -373,7 +465,8 @@ function trimTerminalState(state, limits) {
 }
 var DEFAULT_TERMINAL_BUFFER_OPTIONS = {
   maxLines: 1e4,
-  maxChars: 1048576
+  maxChars: 1048576,
+  stripAnsi: true
 };
 function resolveTerminalBufferLimits(options) {
   const maxLines = options?.maxLines ?? DEFAULT_TERMINAL_BUFFER_OPTIONS.maxLines;
@@ -389,9 +482,12 @@ var initialTerminalState = {
 };
 function createTerminalBuffer(receive$, options) {
   const limits = resolveTerminalBufferLimits(options);
+  const stripAnsi = options?.stripAnsi ?? DEFAULT_TERMINAL_BUFFER_OPTIONS.stripAnsi;
+  const ansiStripper = stripAnsi ? createAnsiStripper() : null;
   const text$ = receive$.pipe(
     scan((state, chunk) => {
-      const next = applyTerminalChunk(state, chunk);
+      const normalized = ansiStripper !== null ? ansiStripper.feed(chunk) : chunk;
+      const next = applyTerminalChunk(state, normalized);
       return trimTerminalState(next, limits);
     }, initialTerminalState),
     map(terminalDisplayText),
@@ -435,17 +531,18 @@ var SerialError = class _SerialError extends Error {
    *
    * @param code - The error code identifying the type of error
    * @param message - A human-readable error message
-   * @param originalError - The original error that caused this SerialError, if any
-   * @param context - Structured metadata for the error code. When omitted, cause-bearing
-   *   codes derive `{ cause }` from `originalError`.
+   * @param originalError - The original error that caused this SerialError, if any.
+   *   @deprecated Prefer passing `{ cause }` via {@link context}. When omitted,
+   *   cause-bearing codes derive `{ cause }` from this argument for backward
+   *   compatibility.
+   * @param context - Structured metadata for the error code. For cause-bearing
+   *   codes, pass `{ cause }` here. When omitted, cause-bearing codes derive
+   *   `{ cause }` from the legacy {@link originalError} argument.
    */
   constructor(code, message, originalError, context) {
     super(message);
     this.name = "SerialError";
     this.code = code;
-    if (originalError !== void 0) {
-      this.originalError = originalError;
-    }
     if (context !== void 0) {
       this.context = context;
     } else if (originalError !== void 0 && isCauseContextCode(code)) {
@@ -453,6 +550,14 @@ var SerialError = class _SerialError extends Error {
     } else {
       this.context = void 0;
     }
+    if (originalError !== void 0) {
+      this.originalError = originalError;
+    } else if (isCauseContextCode(code) && this.context !== void 0) {
+      const causeContext = this.context;
+      if (causeContext.cause instanceof Error) {
+        this.originalError = causeContext.cause;
+      }
+    }
     if (ErrorWithCaptureStackTrace.captureStackTrace) {
       ErrorWithCaptureStackTrace.captureStackTrace(this, _SerialError);
     }
@@ -688,14 +793,16 @@ function normalizeSerialError(error, options) {
     return new SerialError(
       SerialErrorCode.OPERATION_CANCELLED,
       "Port selection was cancelled by the user",
-      error
+      void 0,
+      { cause: error }
     );
   }
   const cause = error instanceof Error ? error : new Error(String(error));
   return new SerialError(
     options.fallbackCode,
     `${prefix}: ${cause.message}`,
-    cause
+    void 0,
+    { cause }
   );
 }
 
@@ -1303,18 +1410,36 @@ function validateSerialPortFilters(filters) {
   if (!filters || filters.length === 0) {
     return filters;
   }
-  for (const filter of filters) {
+  for (let filterIndex = 0; filterIndex < filters.length; filterIndex++) {
+    const filter = filters[filterIndex];
+    if (filter === void 0) {
+      continue;
+    }
     if (!filter.usbVendorId && !filter.usbProductId) {
       throw new SerialError(
         SerialErrorCode.INVALID_FILTER_OPTIONS,
-        "Filter must have at least usbVendorId or usbProductId"
+        "Filter must have at least usbVendorId or usbProductId",
+        void 0,
+        {
+          field: "filters",
+          value: filter,
+          constraint: "at-least-one-usb-id",
+          filterIndex
+        }
       );
     }
     if (filter.usbVendorId !== void 0) {
       if (!Number.isInteger(filter.usbVendorId) || filter.usbVendorId < 0 || filter.usbVendorId > 65535) {
         throw new SerialError(
           SerialErrorCode.INVALID_FILTER_OPTIONS,
-          `Invalid usbVendorId: ${filter.usbVendorId}. Must be an integer between 0 and 65535.`
+          `Invalid usbVendorId: ${filter.usbVendorId}. Must be an integer between 0 and 65535.`,
+          void 0,
+          {
+            field: "usbVendorId",
+            value: filter.usbVendorId,
+            constraint: "usb-id-0-65535",
+            filterIndex
+          }
         );
       }
     }
@@ -1322,7 +1447,14 @@ function validateSerialPortFilters(filters) {
       if (!Number.isInteger(filter.usbProductId) || filter.usbProductId < 0 || filter.usbProductId > 65535) {
         throw new SerialError(
           SerialErrorCode.INVALID_FILTER_OPTIONS,
-          `Invalid usbProductId: ${filter.usbProductId}. Must be an integer between 0 and 65535.`
+          `Invalid usbProductId: ${filter.usbProductId}. Must be an integer between 0 and 65535.`,
+          void 0,
+          {
+            field: "usbProductId",
+            value: filter.usbProductId,
+            constraint: "usb-id-0-65535",
+            filterIndex
+          }
         );
       }
     }
@@ -1347,13 +1479,25 @@ function resolveReceiveReplayOptions(options) {
   if (!Number.isSafeInteger(bufferSize) || bufferSize < 1 || bufferSize > MAX_RECEIVE_REPLAY_BUFFER_SIZE) {
     throw new SerialError(
       SerialErrorCode.INVALID_RECEIVE_REPLAY_OPTIONS,
-      `Invalid receiveReplay.bufferSize: ${bufferSize}. Must be a safe integer between 1 and ${MAX_RECEIVE_REPLAY_BUFFER_SIZE}.`
+      `Invalid receiveReplay.bufferSize: ${bufferSize}. Must be a safe integer between 1 and ${MAX_RECEIVE_REPLAY_BUFFER_SIZE}.`,
+      void 0,
+      {
+        field: "receiveReplay.bufferSize",
+        value: bufferSize,
+        constraint: "receive-replay-buffer-size-range"
+      }
     );
   }
   if (!Number.isSafeInteger(maxChars) || maxChars < 0 || maxChars > MAX_RECEIVE_REPLAY_MAX_CHARS) {
     throw new SerialError(
       SerialErrorCode.INVALID_RECEIVE_REPLAY_OPTIONS,
-      `Invalid receiveReplay.maxChars: ${maxChars}. Must be a safe integer between 0 and ${MAX_RECEIVE_REPLAY_MAX_CHARS}.`
+      `Invalid receiveReplay.maxChars: ${maxChars}. Must be a safe integer between 0 and ${MAX_RECEIVE_REPLAY_MAX_CHARS}.`,
+      void 0,
+      {
+        field: "receiveReplay.maxChars",
+        value: maxChars,
+        constraint: "receive-replay-max-chars-range"
+      }
     );
   }
   return {
@@ -1371,18 +1515,31 @@ function resolveTerminalBufferOptions(options) {
   if (!Number.isSafeInteger(maxLines) || maxLines < 0) {
     throw new SerialError(
       SerialErrorCode.INVALID_TERMINAL_BUFFER_OPTIONS,
-      `Invalid terminalBuffer.maxLines: ${maxLines}. Must be a safe integer >= 0.`
+      `Invalid terminalBuffer.maxLines: ${maxLines}. Must be a safe integer >= 0.`,
+      void 0,
+      {
+        field: "terminalBuffer.maxLines",
+        value: maxLines,
+        constraint: "non-negative-safe-integer"
+      }
     );
   }
   if (!Number.isSafeInteger(maxChars) || maxChars < 0) {
     throw new SerialError(
       SerialErrorCode.INVALID_TERMINAL_BUFFER_OPTIONS,
-      `Invalid terminalBuffer.maxChars: ${maxChars}. Must be a safe integer >= 0.`
+      `Invalid terminalBuffer.maxChars: ${maxChars}. Must be a safe integer >= 0.`,
+      void 0,
+      {
+        field: "terminalBuffer.maxChars",
+        value: maxChars,
+        constraint: "non-negative-safe-integer"
+      }
     );
   }
   return {
     maxLines: brandMaxLines(maxLines),
-    maxChars: brandMaxChars(maxChars)
+    maxChars: brandMaxChars(maxChars),
+    stripAnsi: merged.stripAnsi
   };
 }
 function resolveLineBufferOptions(options) {
@@ -1394,7 +1551,13 @@ function resolveLineBufferOptions(options) {
   if (!Number.isSafeInteger(maxChars) || maxChars < 0) {
     throw new SerialError(
       SerialErrorCode.INVALID_LINE_BUFFER_OPTIONS,
-      `Invalid lineBuffer.maxChars: ${maxChars}. Must be a safe integer >= 0.`
+      `Invalid lineBuffer.maxChars: ${maxChars}. Must be a safe integer >= 0.`,
+      void 0,
+      {
+        field: "lineBuffer.maxChars",
+        value: maxChars,
+        constraint: "non-negative-safe-integer"
+      }
     );
   }
   return {
@@ -1426,7 +1589,13 @@ function resolveConnectionOptions(options) {
   if (!Number.isSafeInteger(baudRate) || baudRate <= 0) {
     throw new SerialError(
       SerialErrorCode.INVALID_CONNECTION_OPTIONS,
-      `Invalid baudRate: ${baudRate}. Must be a safe integer > 0.`
+      `Invalid baudRate: ${baudRate}. Must be a safe integer > 0.`,
+      void 0,
+      {
+        field: "baudRate",
+        value: baudRate,
+        constraint: "positive-safe-integer"
+      }
     );
   }
   return {
@@ -1533,9 +1702,6 @@ function createSerialSession(options) {
     getPortInfo() {
       return portInfoSubject.getValue();
     },
-    getCurrentPort() {
-      return getRuntimePort(controller.runtime);
-    },
     errors$,
     receive$,
     terminalText$,
@@ -1543,6 +1709,11 @@ function createSerialSession(options) {
     lines$
   };
 }
+
+// src/session/is-connected-session-state.ts
+function isConnectedSessionState(state) {
+  return state.status === SerialSessionStatus.Connected;
+}
 export {
   DEFAULT_LINE_BUFFER_OPTIONS,
   DEFAULT_TERMINAL_BUFFER_OPTIONS,
@@ -1554,6 +1725,7 @@ export {
   assertNever,
   createSerialSession,
   createTerminalBuffer,
+  isConnectedSessionState,
   resolveSerialSessionOptions
 };
 //# sourceMappingURL=index.mjs.map