@pamoja/serial 0.1.15 → 0.1.16

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Ergonomic facade over the generated serial-framing binding.
+ *
+ * A serial line is a stream of bytes with no packet boundaries, so something has
+ * to mark where one message ends and the next begins. SLIP and COBS are the two
+ * ways to do that, and each is offered both as a one-shot call over a complete
+ * frame and as a streaming decoder for the arbitrary chunks a port delivers.
+ *
+ * The streaming decoders are what a real read loop uses. A corrupt frame does not
+ * throw, because the frames around it are still good; it is dropped and counted
+ * on {@link SlipDecoder.discarded}.
+ *
+ * @packageDocumentation
+ */
+/** One of the two byte-stuffing framings this module offers. */
+export interface Framing {
+    /**
+     * Frames a payload for the wire.
+     *
+     * @param payload - The bytes to send.
+     * @returns The frame, delimiter included.
+     */
+    encode(payload: Uint8Array): Buffer;
+    /**
+     * Reads the payload back out of a complete frame.
+     *
+     * @param frame - The frame as it arrived.
+     * @returns The payload.
+     * @throws If the frame is corrupt.
+     */
+    decode(frame: Uint8Array): Buffer;
+    /**
+     * Returns the largest frame a payload of this length can produce.
+     *
+     * @param payloadLen - The payload length in bytes.
+     * @returns The worst-case frame length.
+     */
+    maxEncodedLen(payloadLen: number): number;
+}
+/** The SLIP byte that ends a frame (RFC 1055). */
+export declare const SLIP_END_BYTE: number;
+/** The SLIP byte that escapes a reserved value inside a frame (RFC 1055). */
+export declare const SLIP_ESC_BYTE: number;
+/** The byte that follows an escape to stand for a literal end byte. */
+export declare const SLIP_ESC_END_BYTE: number;
+/** The byte that follows an escape to stand for a literal escape byte. */
+export declare const SLIP_ESC_ESC_BYTE: number;
+/** The byte that delimits a COBS frame, which never appears inside one. */
+export declare const COBS_DELIMITER_BYTE: number;
+/** SLIP (RFC 1055): an `END` byte ends a packet, and an escape pair carries it in the data. */
+export declare const slip: Framing;
+/** COBS: removes the zero byte from the payload so one zero delimits packets unambiguously. */
+export declare const cobs: Framing;
+/**
+ * Reassembles whole SLIP frames from the chunks a serial port delivers.
+ *
+ * @example
+ * ```ts
+ * const decoder = new SlipDecoder()
+ * port.on('data', (chunk) => {
+ *   for (const frame of decoder.feed(chunk)) handle(frame)
+ * })
+ * ```
+ */
+export declare class SlipDecoder {
+    #private;
+    /** Creates an empty decoder, ready for the first chunk. */
+    constructor();
+    /**
+     * Feeds a chunk of the stream.
+     *
+     * @param chunk - The bytes just read from the port.
+     * @returns Every frame this chunk completed, in order, which is often none.
+     */
+    feed(chunk: Uint8Array): Buffer[];
+    /** How many corrupt frames this decoder has discarded. */
+    get discarded(): number;
+    /** Discards any partly assembled frame. */
+    reset(): void;
+}
+/**
+ * Reassembles whole COBS frames from the chunks a serial port delivers.
+ *
+ * The counterpart to {@link SlipDecoder}, for links where the framing overhead
+ * has to stay small and predictable.
+ */
+export declare class CobsDecoder {
+    #private;
+    /** Creates an empty decoder, ready for the first chunk. */
+    constructor();
+    /**
+     * Feeds a chunk of the stream.
+     *
+     * @param chunk - The bytes just read from the port.
+     * @returns Every frame this chunk completed, in order.
+     */
+    feed(chunk: Uint8Array): Buffer[];
+    /** How many corrupt frames this decoder has discarded. */
+    get discarded(): number;
+    /** Discards any partly assembled frame. */
+    reset(): void;
+}

package/dist/index.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Ergonomic facade over the generated serial-framing binding.
+ *
+ * A serial line is a stream of bytes with no packet boundaries, so something has
+ * to mark where one message ends and the next begins. SLIP and COBS are the two
+ * ways to do that, and each is offered both as a one-shot call over a complete
+ * frame and as a streaming decoder for the arbitrary chunks a port delivers.
+ *
+ * The streaming decoders are what a real read loop uses. A corrupt frame does not
+ * throw, because the frames around it are still good; it is dropped and counted
+ * on {@link SlipDecoder.discarded}.
+ *
+ * @packageDocumentation
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _SlipDecoder_native, _CobsDecoder_native;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CobsDecoder = exports.SlipDecoder = exports.cobs = exports.slip = exports.COBS_DELIMITER_BYTE = exports.SLIP_ESC_ESC_BYTE = exports.SLIP_ESC_END_BYTE = exports.SLIP_ESC_BYTE = exports.SLIP_END_BYTE = void 0;
+const native_1 = require("@pamoja/native");
+/** The SLIP byte that ends a frame (RFC 1055). */
+exports.SLIP_END_BYTE = native_1.SLIP_END;
+/** The SLIP byte that escapes a reserved value inside a frame (RFC 1055). */
+exports.SLIP_ESC_BYTE = native_1.SLIP_ESC;
+/** The byte that follows an escape to stand for a literal end byte. */
+exports.SLIP_ESC_END_BYTE = native_1.SLIP_ESC_END;
+/** The byte that follows an escape to stand for a literal escape byte. */
+exports.SLIP_ESC_ESC_BYTE = native_1.SLIP_ESC_ESC;
+/** The byte that delimits a COBS frame, which never appears inside one. */
+exports.COBS_DELIMITER_BYTE = native_1.COBS_DELIMITER;
+/** SLIP (RFC 1055): an `END` byte ends a packet, and an escape pair carries it in the data. */
+exports.slip = {
+    encode: (payload) => (0, native_1.slipEncode)(Buffer.from(payload)),
+    decode: (frame) => (0, native_1.slipDecode)(Buffer.from(frame)),
+    maxEncodedLen: (payloadLen) => (0, native_1.slipMaxEncodedLen)(payloadLen),
+};
+/** COBS: removes the zero byte from the payload so one zero delimits packets unambiguously. */
+exports.cobs = {
+    encode: (payload) => (0, native_1.cobsEncode)(Buffer.from(payload)),
+    decode: (frame) => (0, native_1.cobsDecode)(Buffer.from(frame)),
+    maxEncodedLen: (payloadLen) => (0, native_1.cobsMaxEncodedLen)(payloadLen),
+};
+/**
+ * Reassembles whole SLIP frames from the chunks a serial port delivers.
+ *
+ * @example
+ * ```ts
+ * const decoder = new SlipDecoder()
+ * port.on('data', (chunk) => {
+ *   for (const frame of decoder.feed(chunk)) handle(frame)
+ * })
+ * ```
+ */
+class SlipDecoder {
+    /** Creates an empty decoder, ready for the first chunk. */
+    constructor() {
+        _SlipDecoder_native.set(this, void 0);
+        __classPrivateFieldSet(this, _SlipDecoder_native, new native_1.SlipDecoder(), "f");
+    }
+    /**
+     * Feeds a chunk of the stream.
+     *
+     * @param chunk - The bytes just read from the port.
+     * @returns Every frame this chunk completed, in order, which is often none.
+     */
+    feed(chunk) {
+        return __classPrivateFieldGet(this, _SlipDecoder_native, "f").feed(Buffer.from(chunk));
+    }
+    /** How many corrupt frames this decoder has discarded. */
+    get discarded() {
+        return __classPrivateFieldGet(this, _SlipDecoder_native, "f").discarded;
+    }
+    /** Discards any partly assembled frame. */
+    reset() {
+        __classPrivateFieldGet(this, _SlipDecoder_native, "f").reset();
+    }
+}
+exports.SlipDecoder = SlipDecoder;
+_SlipDecoder_native = new WeakMap();
+/**
+ * Reassembles whole COBS frames from the chunks a serial port delivers.
+ *
+ * The counterpart to {@link SlipDecoder}, for links where the framing overhead
+ * has to stay small and predictable.
+ */
+class CobsDecoder {
+    /** Creates an empty decoder, ready for the first chunk. */
+    constructor() {
+        _CobsDecoder_native.set(this, void 0);
+        __classPrivateFieldSet(this, _CobsDecoder_native, new native_1.CobsDecoder(), "f");
+    }
+    /**
+     * Feeds a chunk of the stream.
+     *
+     * @param chunk - The bytes just read from the port.
+     * @returns Every frame this chunk completed, in order.
+     */
+    feed(chunk) {
+        return __classPrivateFieldGet(this, _CobsDecoder_native, "f").feed(Buffer.from(chunk));
+    }
+    /** How many corrupt frames this decoder has discarded. */
+    get discarded() {
+        return __classPrivateFieldGet(this, _CobsDecoder_native, "f").discarded;
+    }
+    /** Discards any partly assembled frame. */
+    reset() {
+        __classPrivateFieldGet(this, _CobsDecoder_native, "f").reset();
+    }
+}
+exports.CobsDecoder = CobsDecoder;
+_CobsDecoder_native = new WeakMap();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pamoja/serial",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "SLIP and COBS byte stuffing with streaming decoders, so a UART byte stream carries discrete packets.",
   "license": "MIT",
   "publishConfig": {
@@ -34,6 +34,6 @@
     "node": ">= 16"
   },
   "dependencies": {
-    "@pamoja/native": "0.1.15"
+    "@pamoja/native": "0.1.16"
   }
 }