@onion-party/spacepackets 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ryangibbs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+![spacepackets](logo.png)
+
+# spacepackets
+
+[![CI](https://github.com/ryangibbs/spacepackets/actions/workflows/ci.yml/badge.svg)](https://github.com/ryangibbs/spacepackets/actions/workflows/ci.yml)
+
+A TypeScript library for encoding and decoding CCSDS Space Packets — the standard packet format used in spacecraft telemetry and telecommand systems ([CCSDS 133.0-B-2](https://public.ccsds.org/Pubs/133x0b2e1.pdf)).
+
+## Install
+
+```sh
+npm install @onion-party/spacepackets
+# or
+pnpm add @onion-party/spacepackets
+```
+
+## Quick start
+
+### Decode a telemetry packet
+
+```ts
+import { decode, PacketType } from "@onion-party/spacepackets";
+
+const bytes = new Uint8Array([/* raw packet bytes from socket or file */]);
+const packet = decode(bytes);
+
+console.log(packet.header.apid);          // Application Process ID
+console.log(packet.header.sequenceCount); // For gap detection
+console.log(packet.header.packetType);    // PacketType.Telemetry or PacketType.Telecommand
+console.log(packet.dataField);            // Uint8Array — secondary header + user data
+```
+
+### Encode a telecommand
+
+```ts
+import { encode, PacketType, SequenceFlags } from "@onion-party/spacepackets";
+
+const packet = {
+  header: {
+    packetVersionNumber: 0,
+    packetType: PacketType.Telecommand,
+    secondaryHeaderFlag: false,
+    apid: 100,
+    sequenceFlags: SequenceFlags.Standalone,
+    sequenceCount: 0,
+    dataLength: 2, // dataField.byteLength - 1
+  },
+  dataField: new Uint8Array([0x01, 0x02, 0x03]),
+};
+
+const bytes = encode(packet); // Uint8Array ready for transmission
+```
+
+### Assemble packets from a byte stream
+
+Packets often arrive in chunks — split across frame boundaries or delivered over a socket. `PacketAssembler` buffers incoming bytes and emits complete packets.
+
+```ts
+import { PacketAssembler } from "@onion-party/spacepackets";
+
+const assembler = new PacketAssembler();
+
+// Feed raw bytes as they arrive (e.g. from a UDP socket)
+socket.on("data", (chunk: Buffer) => {
+  const packets = assembler.onChunk(chunk);
+  for (const packet of packets) {
+    console.log("received packet", packet.header.apid);
+  }
+});
+```
+
+### Full pipeline (Node.js streams)
+
+All three stream classes compose via `.pipe()` for a fully declarative receive pipeline:
+
+```ts
+import {
+  PacketAssemblerStream,
+  GapDetectorStream,
+  SegmentationReassemblerStream,
+  type ReassembledAdu,
+} from "@onion-party/spacepackets";
+
+socket
+  .pipe(new PacketAssemblerStream({ maxBufferBytes: 1_000_000 }))
+  .pipe(new GapDetectorStream({
+    onGap: (gap) => console.warn(`APID ${gap.apid}: ${gap.missing} packet(s) missing`),
+  }))
+  .pipe(new SegmentationReassemblerStream({
+    onError: (err) => console.warn(`APID ${err.apid}: ${err.kind}`),
+  }))
+  .on("data", (adu: ReassembledAdu) => {
+    console.log(`APID ${adu.apid}: ${adu.data.byteLength} bytes`);
+  });
+```
+
+### Detect gaps in the packet stream
+
+`GapDetector` tracks the sequence count per APID and fires a callback whenever packets are missing.
+
+```ts
+import { GapDetector, PacketAssembler } from "@onion-party/spacepackets";
+
+const assembler = new PacketAssembler();
+const detector = new GapDetector({
+  onGap: (gap) => {
+    console.warn(`APID ${gap.apid}: expected ${gap.expected}, got ${gap.received} — ${gap.missing} packet(s) missing`);
+  },
+});
+
+socket.on("data", (chunk: Buffer) => {
+  const packets = assembler.onChunk(chunk);
+  for (const packet of packets) {
+    detector.onPacket(packet.header);
+  }
+});
+```
+
+### Reassemble segmented ADUs
+
+Large application data units (ADUs) are sometimes split across multiple packets using `First`/`Continuation`/`Last` sequence flags. `SegmentationReassembler` buffers segments per APID and emits the fully concatenated data when the final segment arrives.
+
+```ts
+import { PacketAssembler, SegmentationReassembler } from "@onion-party/spacepackets";
+
+const assembler = new PacketAssembler();
+const reassembler = new SegmentationReassembler({
+  onAdu: (adu) => {
+    console.log(`APID ${adu.apid}: reassembled ${adu.data.byteLength} bytes`);
+  },
+  onError: (err) => {
+    if (err.kind === 'ORPHANED_SEGMENT') {
+      console.warn(`APID ${err.apid}: segment arrived with no matching First packet`);
+    } else {
+      console.warn(`APID ${err.apid}: new First arrived while ADU was in-progress — abandoned`);
+    }
+  },
+});
+
+socket.on("data", (chunk: Buffer) => {
+  const packets = assembler.onChunk(chunk);
+  for (const packet of packets) {
+    reassembler.onPacket(packet);
+  }
+});
+```
+
+### Error handling
+
+All errors thrown by this library are instances of `SpacePacketError`. Use the `code` field to branch programmatically without parsing message strings.
+
+```ts
+import { decode, SpacePacketError } from "@onion-party/spacepackets";
+
+try {
+  const packet = decode(bytes);
+} catch (err) {
+  if (err instanceof SpacePacketError) {
+    switch (err.code) {
+      case "BUFFER_TOO_SHORT":
+        // Not enough bytes yet — wait for more data
+        break;
+      case "INVALID_VERSION":
+        // Packet version number is non-zero — malformed or unsupported
+        break;
+    }
+  }
+}
+```
+
+## API
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `encode(packet)` | Serialize a `SpacePacket` to a `Uint8Array` |
+| `decode(bytes)` | Parse a `Uint8Array` into a `SpacePacket` |
+| `decodeHeader(bytes)` | Parse only the 6-byte primary header — useful in streaming contexts to learn the full packet length before the payload has arrived |
+| `getPacketLength(header)` | Returns the total byte length of a packet given its header (`6 + header.dataLength + 1`) |
+| `isIdlePacket(header)` | Returns `true` if the packet's APID is `0x7FF` (the reserved idle/fill APID); idle packets carry no mission data and should be discarded |
+
+### Classes
+
+| Class | Description |
+|---|---|
+| `PacketAssembler` | Stateful buffer that accepts raw byte chunks via `onChunk(chunk)` and returns complete `SpacePacket[]`. Handles packets split across chunk boundaries. |
+| `GapDetector` | Tracks sequence counts per APID and calls `onGap` whenever packets are missing. Handles 14-bit wrap-around and ignores idle packets. |
+| `SegmentationReassembler` | Reassembles segmented ADUs from `First`/`Continuation`/`Last` packet sequences. Calls `onAdu` when complete, `onError` on out-of-order or orphaned segments. |
+| `PacketAssemblerStream` | Node.js `Transform` stream wrapping `PacketAssembler`. Accepts raw byte chunks on the writable side, emits decoded `SpacePacket` objects on the readable side. Emits `INCOMPLETE_PACKET` if the stream ends mid-packet. |
+| `GapDetectorStream` | Passthrough `Transform` stream wrapping `GapDetector`. Accepts and re-emits `SpacePacket` objects; calls `onGap` as a side effect for any detected sequence gaps. |
+| `SegmentationReassemblerStream` | `Transform` stream wrapping `SegmentationReassembler`. Accepts `SpacePacket` objects, emits `ReassembledAdu` objects when a complete ADU is assembled. |
+| `SpacePacketError` | Thrown by `encode`/`decode` on malformed input, or emitted by `PacketAssemblerStream`. Has a `code` field: `BUFFER_TOO_SHORT`, `INVALID_VERSION`, `APID_OUT_OF_RANGE`, `DATA_FIELD_EMPTY`, `DATA_LENGTH_MISMATCH`, `SEQUENCE_COUNT_OUT_OF_RANGE`, `PACKET_TOO_LARGE`, `BUFFER_OVERFLOW`, `INCOMPLETE_PACKET`. |
+
+## Specification
+
+This library implements [CCSDS 133.0-B-2 — Space Packet Protocol](https://public.ccsds.org/Pubs/133x0b2e1.pdf), published by the [Consultative Committee for Space Data Systems (CCSDS)](https://public.ccsds.org).
+
+## License
+
+MIT

package/dist/decode.d.ts

@@ -0,0 +1,28 @@
+import { type PrimaryHeader, type SpacePacket } from './types.js';
+/**
+ * Parses only the 6-byte primary header from the start of `bytes`.
+ *
+ * Useful in streaming contexts: read the header first to learn `header.dataLength`,
+ * then wait for the remaining `header.dataLength + 1` bytes before calling `decode`.
+ *
+ * Throws {@link SpacePacketError} if:
+ * - `bytes.byteLength < 6` (`BUFFER_TOO_SHORT`)
+ * - The packet version number field is not `0` (`INVALID_VERSION`)
+ */
+export declare function decodeHeader(bytes: Uint8Array): PrimaryHeader;
+/**
+ * Parses a complete space packet from `bytes`.
+ *
+ * Decodes the primary header, then slices out the data field.
+ * If `bytes` contains more data than one packet (e.g. a stream of concatenated packets),
+ * only the first packet is decoded — use `header.dataLength` to advance your read cursor.
+ *
+ * The returned `dataField` is an independent copy (`.slice()`), not a view into `bytes`,
+ * so mutating the input buffer after decoding is safe.
+ *
+ * Throws {@link SpacePacketError} if:
+ * - `bytes.byteLength < 6` (`BUFFER_TOO_SHORT`)
+ * - The packet version number field is not `0` (`INVALID_VERSION`)
+ * - `bytes.byteLength < 6 + header.dataLength + 1` (`BUFFER_TOO_SHORT`)
+ */
+export declare function decode(bytes: Uint8Array): SpacePacket;

package/dist/decode.js

@@ -0,0 +1,63 @@
+import assert from 'assert';
+import { HEADER_BYTE_LENGTH } from './types.js';
+import { SpacePacketError } from './errors.js';
+import { getPacketLength } from './util.js';
+/**
+ * Parses only the 6-byte primary header from the start of `bytes`.
+ *
+ * Useful in streaming contexts: read the header first to learn `header.dataLength`,
+ * then wait for the remaining `header.dataLength + 1` bytes before calling `decode`.
+ *
+ * Throws {@link SpacePacketError} if:
+ * - `bytes.byteLength < 6` (`BUFFER_TOO_SHORT`)
+ * - The packet version number field is not `0` (`INVALID_VERSION`)
+ */
+export function decodeHeader(bytes) {
+    assert(bytes.byteLength >= HEADER_BYTE_LENGTH, SpacePacketError.bufferTooShort());
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const byte1 = view.getUint8(0);
+    const packetVersionNumber = (byte1 >> 5) & 0x7;
+    assert(packetVersionNumber === 0, SpacePacketError.invalidVersion());
+    const packetType = (byte1 >> 4) & 0x1;
+    const secondaryHeaderFlag = ((byte1 >> 3) & 0x1) === 1;
+    const apid = ((byte1 & 0x7) << 8) | view.getUint8(1);
+    const byte2 = view.getUint8(2);
+    const sequenceFlags = (byte2 >> 6) & 0x3;
+    const byte3 = view.getUint8(3);
+    const sequenceCount = ((byte2 & 0x3f) << 8) | byte3;
+    const dataLength = view.getUint16(4); // bytes 4-5 as big-endian uint16
+    return {
+        packetVersionNumber: packetVersionNumber,
+        packetType,
+        secondaryHeaderFlag,
+        apid,
+        sequenceFlags,
+        sequenceCount,
+        dataLength,
+    };
+}
+/**
+ * Parses a complete space packet from `bytes`.
+ *
+ * Decodes the primary header, then slices out the data field.
+ * If `bytes` contains more data than one packet (e.g. a stream of concatenated packets),
+ * only the first packet is decoded — use `header.dataLength` to advance your read cursor.
+ *
+ * The returned `dataField` is an independent copy (`.slice()`), not a view into `bytes`,
+ * so mutating the input buffer after decoding is safe.
+ *
+ * Throws {@link SpacePacketError} if:
+ * - `bytes.byteLength < 6` (`BUFFER_TOO_SHORT`)
+ * - The packet version number field is not `0` (`INVALID_VERSION`)
+ * - `bytes.byteLength < 6 + header.dataLength + 1` (`BUFFER_TOO_SHORT`)
+ */
+export function decode(bytes) {
+    const header = decodeHeader(bytes);
+    const totalLength = getPacketLength(header);
+    assert(bytes.byteLength >= totalLength, SpacePacketError.bufferTooShort());
+    const dataField = bytes.slice(HEADER_BYTE_LENGTH, totalLength);
+    return {
+        header,
+        dataField,
+    };
+}

package/dist/encode.d.ts

@@ -0,0 +1,16 @@
+import { type SpacePacket } from './types.js';
+/**
+ * Serializes a space packet to a byte array suitable for transmission.
+ *
+ * The returned buffer is: 6 header bytes + `packet.dataField`.
+ *
+ * Throws {@link SpacePacketError} if:
+ * - `header.packetVersionNumber` is not `0` (`INVALID_VERSION`)
+ * - `header.apid` is outside 0–2047 (`APID_OUT_OF_RANGE`)
+ * - `header.sequenceCount` is outside 0–16383 (`SEQUENCE_COUNT_OUT_OF_RANGE`)
+ * - `dataField` is empty (`DATA_FIELD_EMPTY`)
+ * - `dataField.byteLength` exceeds `MAX_DATA_FIELD_LENGTH` (65536) (`PACKET_TOO_LARGE`)
+ * - `header.dataLength` does not equal `dataField.byteLength - 1` (`DATA_LENGTH_MISMATCH`)
+ */
+export declare function encode(packet: SpacePacket): Uint8Array;
+export declare function encodeHeader(header: SpacePacket['header']): Uint8Array;

package/dist/encode.js

@@ -0,0 +1,57 @@
+import { SpacePacketError } from './errors.js';
+import { MAX_DATA_FIELD_LENGTH } from './types.js';
+/**
+ * Serializes a space packet to a byte array suitable for transmission.
+ *
+ * The returned buffer is: 6 header bytes + `packet.dataField`.
+ *
+ * Throws {@link SpacePacketError} if:
+ * - `header.packetVersionNumber` is not `0` (`INVALID_VERSION`)
+ * - `header.apid` is outside 0–2047 (`APID_OUT_OF_RANGE`)
+ * - `header.sequenceCount` is outside 0–16383 (`SEQUENCE_COUNT_OUT_OF_RANGE`)
+ * - `dataField` is empty (`DATA_FIELD_EMPTY`)
+ * - `dataField.byteLength` exceeds `MAX_DATA_FIELD_LENGTH` (65536) (`PACKET_TOO_LARGE`)
+ * - `header.dataLength` does not equal `dataField.byteLength - 1` (`DATA_LENGTH_MISMATCH`)
+ */
+export function encode(packet) {
+    const { header, dataField } = packet;
+    const headerBytes = encodeHeader(header);
+    if (dataField.byteLength === 0) {
+        throw SpacePacketError.dataFieldEmpty();
+    }
+    if (dataField.byteLength > MAX_DATA_FIELD_LENGTH) {
+        throw SpacePacketError.packetTooLarge();
+    }
+    if (packet.header.dataLength !== dataField.byteLength - 1) {
+        throw SpacePacketError.dataLengthMismatch();
+    }
+    const bytes = new Uint8Array(headerBytes.byteLength + dataField.byteLength);
+    bytes.set(headerBytes, 0);
+    bytes.set(dataField, headerBytes.byteLength);
+    return bytes;
+}
+export function encodeHeader(header) {
+    if (header.packetVersionNumber !== 0) {
+        throw SpacePacketError.invalidVersion();
+    }
+    if (header.apid < 0 || header.apid > 2047) {
+        throw SpacePacketError.apidOutOfRange();
+    }
+    if (header.sequenceCount < 0 || header.sequenceCount > 16383) {
+        throw SpacePacketError.sequenceCountOutOfRange();
+    }
+    const bytes = new Uint8Array(6);
+    const view = new DataView(bytes.buffer);
+    let byte1 = (header.packetVersionNumber & 0x7) << 5;
+    byte1 |= (header.packetType & 0x1) << 4;
+    byte1 |= (header.secondaryHeaderFlag ? 1 : 0) << 3;
+    byte1 |= (header.apid >> 8) & 0x7;
+    view.setUint8(0, byte1);
+    view.setUint8(1, header.apid & 0xff);
+    let byte2 = (header.sequenceFlags & 0x3) << 6;
+    byte2 |= (header.sequenceCount >> 8) & 0x3f;
+    view.setUint8(2, byte2);
+    view.setUint8(3, header.sequenceCount & 0xff);
+    view.setUint16(4, header.dataLength); // big-endian by default
+    return bytes;
+}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Thrown by encode/decode when a packet is malformed or a buffer is invalid.
+ * Use the `code` field to branch programmatically without parsing message strings.
+ */
+export declare class SpacePacketError extends Error {
+    readonly code: 'BUFFER_TOO_SHORT' | 'INVALID_VERSION' | 'APID_OUT_OF_RANGE' | 'DATA_FIELD_EMPTY' | 'DATA_LENGTH_MISMATCH' | 'SEQUENCE_COUNT_OUT_OF_RANGE' | 'PACKET_TOO_LARGE' | 'BUFFER_OVERFLOW' | 'INCOMPLETE_PACKET';
+    constructor(message: string, code: 'BUFFER_TOO_SHORT' | 'INVALID_VERSION' | 'APID_OUT_OF_RANGE' | 'DATA_FIELD_EMPTY' | 'DATA_LENGTH_MISMATCH' | 'SEQUENCE_COUNT_OUT_OF_RANGE' | 'PACKET_TOO_LARGE' | 'BUFFER_OVERFLOW' | 'INCOMPLETE_PACKET');
+    static bufferTooShort(): SpacePacketError;
+    static invalidVersion(): SpacePacketError;
+    static apidOutOfRange(): SpacePacketError;
+    static dataFieldEmpty(): SpacePacketError;
+    static dataLengthMismatch(): SpacePacketError;
+    static sequenceCountOutOfRange(): SpacePacketError;
+    static packetTooLarge(): SpacePacketError;
+    static bufferOverflow(): SpacePacketError;
+    static incompletePacket(): SpacePacketError;
+}

package/dist/errors.js

@@ -0,0 +1,39 @@
+/**
+ * Thrown by encode/decode when a packet is malformed or a buffer is invalid.
+ * Use the `code` field to branch programmatically without parsing message strings.
+ */
+export class SpacePacketError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'SpacePacketError';
+    }
+    static bufferTooShort() {
+        return new SpacePacketError('Buffer too short', 'BUFFER_TOO_SHORT');
+    }
+    static invalidVersion() {
+        return new SpacePacketError('Invalid packet version number', 'INVALID_VERSION');
+    }
+    static apidOutOfRange() {
+        return new SpacePacketError('APID out of range (0-2047)', 'APID_OUT_OF_RANGE');
+    }
+    static dataFieldEmpty() {
+        return new SpacePacketError('Data field is empty', 'DATA_FIELD_EMPTY');
+    }
+    static dataLengthMismatch() {
+        return new SpacePacketError('Data length mismatch', 'DATA_LENGTH_MISMATCH');
+    }
+    static sequenceCountOutOfRange() {
+        return new SpacePacketError('Sequence count out of range (0-16383)', 'SEQUENCE_COUNT_OUT_OF_RANGE');
+    }
+    static packetTooLarge() {
+        return new SpacePacketError('Packet too large: data field exceeds 65536 bytes (CCSDS maximum)', 'PACKET_TOO_LARGE');
+    }
+    static bufferOverflow() {
+        return new SpacePacketError('Buffer overflow: accumulated bytes exceed maxBufferBytes limit', 'BUFFER_OVERFLOW');
+    }
+    static incompletePacket() {
+        return new SpacePacketError('Incomplete packet', 'INCOMPLETE_PACKET');
+    }
+}

package/dist/gapDetector.d.ts

@@ -0,0 +1,20 @@
+import { type GapDetectorOptions, type PrimaryHeader } from './types.js';
+export declare class GapDetector {
+    private readonly onGap;
+    /** Tracks the last received sequence count per APID. */
+    private readonly lastSeen;
+    constructor(options: GapDetectorOptions);
+    /**
+     * Inspects a packet header for sequence count gaps.
+     * Call this for every packet received, in order.
+     *
+     * - Idle packets (APID `0x7FF`) are silently ignored.
+     * - The first packet seen for an APID establishes the baseline; no gap is reported.
+     * - For subsequent packets, if `sequenceCount` is not `(lastSeen + 1) % SEQUENCE_COUNT_RANGE`,
+     *   `onGap` is called with the details.
+     * - `missing` is the number of dropped packets:
+     *   `(received - expected + SEQUENCE_COUNT_RANGE) % SEQUENCE_COUNT_RANGE`
+     */
+    onPacket(header: PrimaryHeader): void;
+    reset(): void;
+}

package/dist/gapDetector.js

@@ -0,0 +1,44 @@
+import { IDLE_APID, SEQUENCE_COUNT_RANGE, } from './types.js';
+export class GapDetector {
+    onGap;
+    /** Tracks the last received sequence count per APID. */
+    lastSeen = new Map();
+    constructor(options) {
+        this.onGap = options.onGap;
+    }
+    /**
+     * Inspects a packet header for sequence count gaps.
+     * Call this for every packet received, in order.
+     *
+     * - Idle packets (APID `0x7FF`) are silently ignored.
+     * - The first packet seen for an APID establishes the baseline; no gap is reported.
+     * - For subsequent packets, if `sequenceCount` is not `(lastSeen + 1) % SEQUENCE_COUNT_RANGE`,
+     *   `onGap` is called with the details.
+     * - `missing` is the number of dropped packets:
+     *   `(received - expected + SEQUENCE_COUNT_RANGE) % SEQUENCE_COUNT_RANGE`
+     */
+    onPacket(header) {
+        if (header.apid === IDLE_APID) {
+            return;
+        }
+        const last = this.lastSeen.get(header.apid);
+        if (last === undefined) {
+            this.lastSeen.set(header.apid, header.sequenceCount);
+            return;
+        }
+        const expected = (last + 1) % SEQUENCE_COUNT_RANGE;
+        if (header.sequenceCount !== expected) {
+            const gap = {
+                apid: header.apid,
+                expected,
+                received: header.sequenceCount,
+                missing: (header.sequenceCount - expected + SEQUENCE_COUNT_RANGE) % SEQUENCE_COUNT_RANGE,
+            };
+            this.onGap(gap);
+        }
+        this.lastSeen.set(header.apid, header.sequenceCount);
+    }
+    reset() {
+        this.lastSeen.clear();
+    }
+}

package/dist/gapDetectorStream.d.ts

@@ -0,0 +1,22 @@
+import { Transform, type TransformCallback } from 'node:stream';
+import type { GapDetectorStreamOptions, SpacePacket } from './types.js';
+/**
+ * A passthrough Node.js `Transform` stream that wraps {@link GapDetector}.
+ *
+ * - **Writable side**: accepts decoded {@link SpacePacket} objects.
+ * - **Readable side**: emits the same {@link SpacePacket} objects unchanged.
+ * - **Side effect**: calls `onGap` for any detected sequence count gaps.
+ *
+ * @example
+ * ```ts
+ * socket
+ *   .pipe(new PacketAssemblerStream())
+ *   .pipe(new GapDetectorStream({ onGap: (gap) => console.warn(gap) }))
+ *   .on('data', (packet: SpacePacket) => process(packet));
+ * ```
+ */
+export declare class GapDetectorStream extends Transform {
+    private readonly detector;
+    constructor(options: GapDetectorStreamOptions);
+    _transform(packet: SpacePacket, _encoding: BufferEncoding, callback: TransformCallback): void;
+}

package/dist/gapDetectorStream.js

@@ -0,0 +1,33 @@
+import { Transform } from 'node:stream';
+import { GapDetector } from './gapDetector.js';
+/**
+ * A passthrough Node.js `Transform` stream that wraps {@link GapDetector}.
+ *
+ * - **Writable side**: accepts decoded {@link SpacePacket} objects.
+ * - **Readable side**: emits the same {@link SpacePacket} objects unchanged.
+ * - **Side effect**: calls `onGap` for any detected sequence count gaps.
+ *
+ * @example
+ * ```ts
+ * socket
+ *   .pipe(new PacketAssemblerStream())
+ *   .pipe(new GapDetectorStream({ onGap: (gap) => console.warn(gap) }))
+ *   .on('data', (packet: SpacePacket) => process(packet));
+ * ```
+ */
+export class GapDetectorStream extends Transform {
+    detector;
+    constructor(options) {
+        super({
+            readableObjectMode: true,
+            writableObjectMode: true,
+            readableHighWaterMark: options.readableHighWaterMark,
+        });
+        this.detector = new GapDetector(options);
+    }
+    _transform(packet, _encoding, callback) {
+        this.detector.onPacket(packet.header);
+        this.push(packet);
+        callback();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type { PrimaryHeader, SpacePacket, PacketAssemblerOptions, PacketAssemblerStreamOptions, SequenceGap, GapDetectorOptions, GapDetectorStreamOptions, ReassembledAdu, SegmentationError, SegmentationReassemblerOptions, SegmentationReassemblerStreamOptions, } from './types.js';
+export { HEADER_BYTE_LENGTH, IDLE_APID, MAX_DATA_FIELD_LENGTH, SEQUENCE_COUNT_RANGE, PacketType, SequenceFlags, } from './types.js';
+export { getPacketLength, isIdlePacket } from './util.js';
+export { encode } from './encode.js';
+export { decode, decodeHeader } from './decode.js';
+export { SpacePacketError } from './errors.js';
+export { PacketAssembler } from './packetAssembler.js';
+export { GapDetector } from './gapDetector.js';
+export { SegmentationReassembler } from './segmentationReassembler.js';
+export { PacketAssemblerStream } from './packetAssemblerStream.js';
+export { GapDetectorStream } from './gapDetectorStream.js';
+export { SegmentationReassemblerStream } from './segmentationReassemblerStream.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+export { HEADER_BYTE_LENGTH, IDLE_APID, MAX_DATA_FIELD_LENGTH, SEQUENCE_COUNT_RANGE, PacketType, SequenceFlags, } from './types.js';
+export { getPacketLength, isIdlePacket } from './util.js';
+export { encode } from './encode.js';
+export { decode, decodeHeader } from './decode.js';
+export { SpacePacketError } from './errors.js';
+export { PacketAssembler } from './packetAssembler.js';
+export { GapDetector } from './gapDetector.js';
+export { SegmentationReassembler } from './segmentationReassembler.js';
+export { PacketAssemblerStream } from './packetAssemblerStream.js';
+export { GapDetectorStream } from './gapDetectorStream.js';
+export { SegmentationReassemblerStream } from './segmentationReassemblerStream.js';

package/dist/packetAssembler.d.ts

@@ -0,0 +1,26 @@
+import { type PacketAssemblerOptions, type SpacePacket } from './types.js';
+export declare class PacketAssembler {
+    private buffer;
+    /** Byte offset into `buffer` where the next unread packet starts. */
+    private readOffset;
+    private readonly maxBufferBytes;
+    get bufferedByteLength(): number;
+    constructor(options?: PacketAssemblerOptions);
+    /**
+     * Appends a new chunk to the internal buffer.
+     * `Uint8Array` is fixed-length, so this allocates a new buffer and copies both into it.
+     */
+    private append;
+    /**
+     * Discards consumed bytes from the front of the buffer and resets `readOffset` to 0.
+     * Call once after the decode loop ends — one compaction per `onChunk` call,
+     * regardless of how many packets were decoded.
+     */
+    private compact;
+    /**
+     * Feed a new chunk of bytes into the assembler.
+     * Returns all complete packets that could be decoded from the accumulated buffer.
+     */
+    onChunk(chunk: Uint8Array): SpacePacket[];
+    reset(): void;
+}

package/dist/packetAssembler.js

@@ -0,0 +1,73 @@
+import { HEADER_BYTE_LENGTH } from './types.js';
+import { decodeHeader } from './decode.js';
+import { getPacketLength } from './util.js';
+import { SpacePacketError } from './errors.js';
+export class PacketAssembler {
+    buffer = new Uint8Array(0);
+    /** Byte offset into `buffer` where the next unread packet starts. */
+    readOffset = 0;
+    maxBufferBytes;
+    get bufferedByteLength() {
+        return this.buffer.byteLength - this.readOffset;
+    }
+    constructor(options) {
+        this.maxBufferBytes = options?.maxBufferBytes;
+    }
+    /**
+     * Appends a new chunk to the internal buffer.
+     * `Uint8Array` is fixed-length, so this allocates a new buffer and copies both into it.
+     */
+    append(chunk) {
+        if (this.maxBufferBytes !== undefined &&
+            this.buffer.byteLength - this.readOffset + chunk.byteLength > this.maxBufferBytes) {
+            throw SpacePacketError.bufferOverflow();
+        }
+        const newBuffer = new Uint8Array(this.buffer.byteLength + chunk.byteLength);
+        newBuffer.set(this.buffer, 0);
+        newBuffer.set(chunk, this.buffer.byteLength);
+        this.buffer = newBuffer;
+    }
+    /**
+     * Discards consumed bytes from the front of the buffer and resets `readOffset` to 0.
+     * Call once after the decode loop ends — one compaction per `onChunk` call,
+     * regardless of how many packets were decoded.
+     */
+    compact() {
+        if (this.readOffset === 0)
+            return;
+        if (this.readOffset === this.buffer.byteLength) {
+            this.buffer = new Uint8Array(0);
+        }
+        else {
+            this.buffer = this.buffer.slice(this.readOffset);
+        }
+        this.readOffset = 0;
+    }
+    /**
+     * Feed a new chunk of bytes into the assembler.
+     * Returns all complete packets that could be decoded from the accumulated buffer.
+     */
+    onChunk(chunk) {
+        this.append(chunk);
+        const packets = [];
+        while (true) {
+            if (this.buffer.byteLength - this.readOffset < HEADER_BYTE_LENGTH) {
+                break;
+            }
+            const header = decodeHeader(this.buffer.subarray(this.readOffset));
+            const totalLength = getPacketLength(header);
+            if (this.buffer.byteLength - this.readOffset < totalLength) {
+                break;
+            }
+            const dataField = this.buffer.slice(this.readOffset + HEADER_BYTE_LENGTH, this.readOffset + totalLength);
+            packets.push({ header, dataField });
+            this.readOffset += totalLength;
+        }
+        this.compact();
+        return packets;
+    }
+    reset() {
+        this.buffer = new Uint8Array(0);
+        this.readOffset = 0;
+    }
+}

package/dist/packetAssemblerStream.d.ts

@@ -0,0 +1,29 @@
+import { Transform, type TransformCallback } from 'node:stream';
+import type { PacketAssemblerStreamOptions } from './types.js';
+/**
+ * A Node.js `Transform` stream that wraps {@link PacketAssembler}.
+ *
+ * - **Writable side**: accepts raw `Buffer` / `Uint8Array` chunks (binary mode).
+ * - **Readable side**: emits decoded {@link SpacePacket} objects (object mode).
+ *
+ * @example
+ * ```ts
+ * import { createConnection } from 'node:net';
+ * import { PacketAssemblerStream } from 'spacepackets';
+ *
+ * const socket = createConnection({ host: 'ground-station', port: 4321 });
+ * const stream = new PacketAssemblerStream({ maxBufferBytes: 1_000_000 });
+ *
+ * socket.pipe(stream);
+ *
+ * stream.on('data', (packet: SpacePacket) => {
+ *   console.log('APID', packet.header.apid);
+ * });
+ * ```
+ */
+export declare class PacketAssemblerStream extends Transform {
+    private readonly assembler;
+    constructor(options?: PacketAssemblerStreamOptions);
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+}

package/dist/packetAssemblerStream.js

@@ -0,0 +1,48 @@
+import { Transform } from 'node:stream';
+import { PacketAssembler } from './packetAssembler.js';
+import { SpacePacketError } from './errors.js';
+/**
+ * A Node.js `Transform` stream that wraps {@link PacketAssembler}.
+ *
+ * - **Writable side**: accepts raw `Buffer` / `Uint8Array` chunks (binary mode).
+ * - **Readable side**: emits decoded {@link SpacePacket} objects (object mode).
+ *
+ * @example
+ * ```ts
+ * import { createConnection } from 'node:net';
+ * import { PacketAssemblerStream } from 'spacepackets';
+ *
+ * const socket = createConnection({ host: 'ground-station', port: 4321 });
+ * const stream = new PacketAssemblerStream({ maxBufferBytes: 1_000_000 });
+ *
+ * socket.pipe(stream);
+ *
+ * stream.on('data', (packet: SpacePacket) => {
+ *   console.log('APID', packet.header.apid);
+ * });
+ * ```
+ */
+export class PacketAssemblerStream extends Transform {
+    assembler;
+    constructor(options) {
+        super({
+            readableObjectMode: true,
+            readableHighWaterMark: options?.readableHighWaterMark,
+            writableObjectMode: false,
+        });
+        this.assembler = new PacketAssembler(options);
+    }
+    _transform(chunk, _encoding, callback) {
+        this.assembler.onChunk(chunk).forEach((packet) => this.push(packet));
+        callback();
+    }
+    _flush(callback) {
+        if (this.assembler.bufferedByteLength > 0) {
+            const error = SpacePacketError.incompletePacket();
+            callback(error);
+        }
+        else {
+            callback();
+        }
+    }
+}

package/dist/segmentationReassembler.d.ts

@@ -0,0 +1,22 @@
+import { type SegmentationReassemblerOptions, type SpacePacket } from './types.js';
+export declare class SegmentationReassembler {
+    private readonly onAdu;
+    private readonly onError;
+    /** Accumulated segments per APID. Present only while an ADU is in-progress. */
+    private readonly segments;
+    constructor(options: SegmentationReassemblerOptions);
+    /**
+     * Process a single space packet.
+     *
+     * - `Standalone`: call `onAdu` immediately with the packet's data field.
+     * - `First`: begin accumulating segments for this APID. If an in-progress ADU already
+     *   exists for this APID, call `onError` with `UNEXPECTED_FIRST` and abandon it.
+     * - `Continuation`: append to the in-progress ADU for this APID. If none exists,
+     *   call `onError` with `ORPHANED_SEGMENT`.
+     * - `Last`: append and call `onAdu` with the fully concatenated data. If no in-progress
+     *   ADU exists, call `onError` with `ORPHANED_SEGMENT`.
+     */
+    onPacket(packet: SpacePacket): void;
+    /** Clears all in-progress ADUs. Subsequent `Continuation`/`Last` packets will be orphaned. */
+    reset(): void;
+}

package/dist/segmentationReassembler.js

@@ -0,0 +1,63 @@
+import { SequenceFlags, } from './types.js';
+import { concatUint8Arrays } from './util.js';
+export class SegmentationReassembler {
+    onAdu;
+    onError;
+    /** Accumulated segments per APID. Present only while an ADU is in-progress. */
+    segments = new Map();
+    constructor(options) {
+        this.onAdu = options.onAdu;
+        this.onError = options.onError;
+    }
+    /**
+     * Process a single space packet.
+     *
+     * - `Standalone`: call `onAdu` immediately with the packet's data field.
+     * - `First`: begin accumulating segments for this APID. If an in-progress ADU already
+     *   exists for this APID, call `onError` with `UNEXPECTED_FIRST` and abandon it.
+     * - `Continuation`: append to the in-progress ADU for this APID. If none exists,
+     *   call `onError` with `ORPHANED_SEGMENT`.
+     * - `Last`: append and call `onAdu` with the fully concatenated data. If no in-progress
+     *   ADU exists, call `onError` with `ORPHANED_SEGMENT`.
+     */
+    onPacket(packet) {
+        const { apid, sequenceFlags } = packet.header;
+        switch (sequenceFlags) {
+            case SequenceFlags.Standalone:
+                this.onAdu({ apid, data: packet.dataField });
+                break;
+            case SequenceFlags.First: {
+                if (this.segments.has(apid)) {
+                    this.onError?.({ kind: 'UNEXPECTED_FIRST', apid });
+                    this.segments.delete(apid);
+                }
+                this.segments.set(apid, [packet.dataField]);
+                break;
+            }
+            case SequenceFlags.Continuation: {
+                const parts = this.segments.get(apid);
+                if (!parts) {
+                    this.onError?.({ kind: 'ORPHANED_SEGMENT', apid, sequenceFlags });
+                    break;
+                }
+                parts.push(packet.dataField);
+                break;
+            }
+            case SequenceFlags.Last: {
+                const parts = this.segments.get(apid);
+                if (!parts) {
+                    this.onError?.({ kind: 'ORPHANED_SEGMENT', apid, sequenceFlags });
+                    break;
+                }
+                parts.push(packet.dataField);
+                this.segments.delete(apid);
+                this.onAdu({ apid, data: concatUint8Arrays(parts) });
+                break;
+            }
+        }
+    }
+    /** Clears all in-progress ADUs. Subsequent `Continuation`/`Last` packets will be orphaned. */
+    reset() {
+        this.segments.clear();
+    }
+}

package/dist/segmentationReassemblerStream.d.ts

@@ -0,0 +1,25 @@
+import { Transform, type TransformCallback } from 'node:stream';
+import type { SegmentationReassemblerStreamOptions, SpacePacket } from './types.js';
+/**
+ * A Node.js `Transform` stream that wraps {@link SegmentationReassembler}.
+ *
+ * - **Writable side**: accepts decoded {@link SpacePacket} objects.
+ * - **Readable side**: emits {@link ReassembledAdu} objects — one per complete `First`→`Last` sequence
+ *   or `Standalone` packet.
+ *
+ * `onError` is optional — orphaned or unexpected segments are silently ignored if not provided.
+ * In-progress ADUs that are incomplete when the stream ends are silently abandoned.
+ *
+ * @example
+ * ```ts
+ * socket
+ *   .pipe(new PacketAssemblerStream())
+ *   .pipe(new SegmentationReassemblerStream({ onError: (err) => console.warn(err) }))
+ *   .on('data', (adu: ReassembledAdu) => process(adu));
+ * ```
+ */
+export declare class SegmentationReassemblerStream extends Transform {
+    private readonly reassembler;
+    constructor(options?: SegmentationReassemblerStreamOptions);
+    _transform(packet: SpacePacket, _encoding: BufferEncoding, callback: TransformCallback): void;
+}

package/dist/segmentationReassemblerStream.js

@@ -0,0 +1,38 @@
+import { Transform } from 'node:stream';
+import { SegmentationReassembler } from './segmentationReassembler.js';
+/**
+ * A Node.js `Transform` stream that wraps {@link SegmentationReassembler}.
+ *
+ * - **Writable side**: accepts decoded {@link SpacePacket} objects.
+ * - **Readable side**: emits {@link ReassembledAdu} objects — one per complete `First`→`Last` sequence
+ *   or `Standalone` packet.
+ *
+ * `onError` is optional — orphaned or unexpected segments are silently ignored if not provided.
+ * In-progress ADUs that are incomplete when the stream ends are silently abandoned.
+ *
+ * @example
+ * ```ts
+ * socket
+ *   .pipe(new PacketAssemblerStream())
+ *   .pipe(new SegmentationReassemblerStream({ onError: (err) => console.warn(err) }))
+ *   .on('data', (adu: ReassembledAdu) => process(adu));
+ * ```
+ */
+export class SegmentationReassemblerStream extends Transform {
+    reassembler;
+    constructor(options) {
+        super({
+            readableObjectMode: true,
+            writableObjectMode: true,
+            readableHighWaterMark: options?.readableHighWaterMark,
+        });
+        this.reassembler = new SegmentationReassembler({
+            onAdu: (adu) => this.push(adu),
+            ...(options?.onError !== undefined ? { onError: options.onError } : {}),
+        });
+    }
+    _transform(packet, _encoding, callback) {
+        this.reassembler.onPacket(packet);
+        callback();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Constants and types for CCSDS space packets.
+/
+
+/*
+ * The main types are `PrimaryHeader` (the fixed 6-byte header present in every packet)
+ * and `SpacePacket` (the full decoded packet, including header and data field).
+ */
+export declare const HEADER_BYTE_LENGTH = 6;
+/**
+ * The maximum number of bytes in a packet data field (CCSDS 133.0-B-2 §4.1.3.5.3).
+ * Total maximum packet size is `HEADER_BYTE_LENGTH + MAX_DATA_FIELD_LENGTH` = 65542 bytes.
+ */
+export declare const MAX_DATA_FIELD_LENGTH = 65536;
+/**
+ * The number of distinct sequence count values (2¹⁴ = 16384, for values 0–16383).
+ * After reaching 16383, the sequence count wraps back to 0.
+ * Use this as the modulus when computing expected counts or gap sizes.
+ */
+export declare const SEQUENCE_COUNT_RANGE = 16384;
+/**
+ * The reserved APID for idle (fill) packets. Packets with this APID carry no
+ * mission data and should be discarded by ground station routing logic.
+ */
+export declare const IDLE_APID = 2047;
+/** Whether the packet carries telemetry (spacecraft → ground) or a telecommand (ground → spacecraft). */
+export declare enum PacketType {
+    /**
+     * Spacecraft → ground. The most common type of packet, used for sending measurements, status reports, and other data from the spacecraft to the ground.
+     */
+    Telemetry = 0,
+    /**
+     * Ground → spacecraft. Used for sending commands and instructions from the ground to the spacecraft.
+     */
+    Telecommand = 1
+}
+/**
+ * Indicates whether this packet is a standalone unit or a segment of a larger application unit.
+ * - `Standalone` — a complete, self-contained packet (most common for telemetry)
+ * - `First` / `Continuation` / `Last` — segments of a larger unit that must be reassembled
+ */
+export declare enum SequenceFlags {
+    Continuation = 0,
+    First = 1,
+    Last = 2,
+    Standalone = 3
+}
+/**
+ * The mandatory 6-byte CCSDS primary header present in every space packet.
+ *
+ * Bit layout (big-endian):
+ * ```
+ * Byte 0: [PVN(3)] [Type(1)] [SecondaryHeaderFlag(1)] [APID_hi(3)]
+ * Byte 1: [APID_lo(8)]
+ * Byte 2: [SequenceFlags(2)] [SequenceCount_hi(6)]
+ * Byte 3: [SequenceCount_lo(8)]
+ * Bytes 4–5: [DataLength(16)]
+ * ```
+ */
+export interface PrimaryHeader {
+    /**
+     * Packet version number. Must be `0` for valid CCSDS packets; if you see a different value, the packet is malformed or uses an unsupported version of the standard. (The CCSDS standard reserves non-zero values for future versions, but as of this writing only version 0 exists.)
+     */
+    readonly packetVersionNumber: 0;
+    readonly packetType: PacketType;
+    /**
+     * Indicates whether a secondary header is present. The format of the secondary header is mission-specific and not parsed by this library; callers who need it can slice `dataField` themselves.
+     */
+    readonly secondaryHeaderFlag: boolean;
+    /**
+     * Application Process ID. A mission-specific identifier for the source or destination of the packet, used for routing and demultiplexing. Valid values are 0–2047 (11 bits); if you see a larger value, the packet is malformed.
+     */
+    readonly apid: number;
+    /**
+     * Indicates whether this packet is a complete standalone unit or a segment of a larger application data unit.
+     * Most telemetry packets are `SequenceFlags.Standalone`. Use `First`/`Continuation`/`Last` for segmented transfers.
+     */
+    readonly sequenceFlags: SequenceFlags;
+    /**
+     * Sequence count, used for identifying segments of larger application units that span multiple packets. For standalone packets, `sequenceFlags` is `SequenceFlags.Standalone` and `sequenceCount` is typically 0, but these fields can be set to other values for mission-specific purposes if desired. Valid `sequenceCount` values are 0–16383 (14 bits); if you see a larger value, the packet is malformed.
+     */
+    readonly sequenceCount: number;
+    /**
+     * Data length, defined as the number of bytes in the data field minus one. This is a quirk of the CCSDS standard; if you see a value that doesn't match `dataField.byteLength - 1`, the packet is malformed.
+     */
+    readonly dataLength: number;
+}
+/**
+ * A decoded CCSDS space packet.
+ *
+ * `dataField` is the complete data field — secondary header (if present) plus user data —
+ * as a single opaque byte array. The secondary header format is mission-specific and not
+ * parsed by this library; callers who need it can slice `dataField` themselves.
+ *
+ * The relationship between `header.dataLength` and `dataField` is always:
+ * `dataField.byteLength === header.dataLength + 1`
+ */
+/**
+ * Constructor options for {@link PacketAssembler}.
+ */
+export interface PacketAssemblerOptions {
+    /**
+     * Maximum number of bytes the internal buffer may hold at any one time.
+     * If a chunk would cause the buffer to exceed this limit, `onChunk` should throw
+     * a `SpacePacketError` with code `BUFFER_OVERFLOW`.
+     * Defaults to no limit.
+     */
+    maxBufferBytes?: number;
+}
+/**
+ * Constructor options for {@link PacketAssemblerStream}.
+ * Extends {@link PacketAssemblerOptions} with any Node.js `Transform` stream options.
+ */
+export interface PacketAssemblerStreamOptions extends PacketAssemblerOptions {
+    /**
+     * High-water mark for the readable side of the stream (number of objects).
+     * Defaults to `16`.
+     */
+    readableHighWaterMark?: number;
+}
+/**
+ * Describes a detected gap in the sequence count for a given APID.
+ */
+export interface SequenceGap {
+    /** The APID where the gap was detected. */
+    readonly apid: number;
+    /** The sequence count that was expected but not received. */
+    readonly expected: number;
+    /** The sequence count that was actually received. */
+    readonly received: number;
+    /** The number of missing packets. Accounts for wrap-around at 16383 → 0. */
+    readonly missing: number;
+}
+/**
+ * Constructor options for {@link GapDetector}.
+ */
+export interface GapDetectorOptions {
+    /** Called once for each gap detected, with details about the missing range. */
+    onGap: (gap: SequenceGap) => void;
+}
+/**
+ * Constructor options for {@link GapDetectorStream}.
+ * Extends {@link GapDetectorOptions} with any Node.js `Transform` stream options.
+ */
+export interface GapDetectorStreamOptions extends GapDetectorOptions {
+    /**
+     * High-water mark for the readable side of the stream (number of objects).
+     * Defaults to `16`.
+     */
+    readableHighWaterMark?: number;
+}
+/**
+ * A fully reassembled application data unit (ADU) produced by {@link SegmentationReassembler}.
+ * Contains the concatenated data fields from a `First` → `Continuation`* → `Last` sequence,
+ * or the data field of a single `Standalone` packet.
+ */
+export interface ReassembledAdu {
+    readonly apid: number;
+    readonly data: Uint8Array;
+}
+/**
+ * Emitted by {@link SegmentationReassembler} when a segment arrives out of order or
+ * without a matching counterpart.
+ *
+ * - `ORPHANED_SEGMENT` — a `Continuation` or `Last` arrived with no active `First` for this APID.
+ * - `UNEXPECTED_FIRST` — a `First` arrived while an in-progress ADU already exists for this APID;
+ *   the previous ADU is abandoned.
+ */
+export type SegmentationError = {
+    readonly kind: 'ORPHANED_SEGMENT';
+    readonly apid: number;
+    readonly sequenceFlags: SequenceFlags.Continuation | SequenceFlags.Last;
+} | {
+    readonly kind: 'UNEXPECTED_FIRST';
+    readonly apid: number;
+};
+/**
+ * Constructor options for {@link SegmentationReassembler}.
+ */
+export interface SegmentationReassemblerOptions {
+    /** Called when a complete ADU has been reassembled. */
+    onAdu: (adu: ReassembledAdu) => void;
+    /** Called when a segment arrives that cannot be reassembled. Optional — errors are silently ignored if not provided. */
+    onError?: (error: SegmentationError) => void;
+}
+/**
+ * Constructor options for {@link SegmentationReassemblerStream}.
+ * `onAdu` is omitted — the stream emits reassembled ADUs via `push()` internally.
+ */
+export interface SegmentationReassemblerStreamOptions extends Omit<SegmentationReassemblerOptions, 'onAdu'> {
+    /**
+     * High-water mark for the readable side of the stream (number of objects).
+     * Defaults to `16`.
+     */
+    readableHighWaterMark?: number;
+}
+export interface SpacePacket {
+    readonly header: PrimaryHeader;
+    readonly dataField: Uint8Array;
+}

package/dist/types.js

@@ -0,0 +1,49 @@
+/**
+ * Constants and types for CCSDS space packets.
+/
+
+/*
+ * The main types are `PrimaryHeader` (the fixed 6-byte header present in every packet)
+ * and `SpacePacket` (the full decoded packet, including header and data field).
+ */
+export const HEADER_BYTE_LENGTH = 6;
+/**
+ * The maximum number of bytes in a packet data field (CCSDS 133.0-B-2 §4.1.3.5.3).
+ * Total maximum packet size is `HEADER_BYTE_LENGTH + MAX_DATA_FIELD_LENGTH` = 65542 bytes.
+ */
+export const MAX_DATA_FIELD_LENGTH = 65536;
+/**
+ * The number of distinct sequence count values (2¹⁴ = 16384, for values 0–16383).
+ * After reaching 16383, the sequence count wraps back to 0.
+ * Use this as the modulus when computing expected counts or gap sizes.
+ */
+export const SEQUENCE_COUNT_RANGE = 16384;
+/**
+ * The reserved APID for idle (fill) packets. Packets with this APID carry no
+ * mission data and should be discarded by ground station routing logic.
+ */
+export const IDLE_APID = 0x7ff;
+/** Whether the packet carries telemetry (spacecraft → ground) or a telecommand (ground → spacecraft). */
+export var PacketType;
+(function (PacketType) {
+    /**
+     * Spacecraft → ground. The most common type of packet, used for sending measurements, status reports, and other data from the spacecraft to the ground.
+     */
+    PacketType[PacketType["Telemetry"] = 0] = "Telemetry";
+    /**
+     * Ground → spacecraft. Used for sending commands and instructions from the ground to the spacecraft.
+     */
+    PacketType[PacketType["Telecommand"] = 1] = "Telecommand";
+})(PacketType || (PacketType = {}));
+/**
+ * Indicates whether this packet is a standalone unit or a segment of a larger application unit.
+ * - `Standalone` — a complete, self-contained packet (most common for telemetry)
+ * - `First` / `Continuation` / `Last` — segments of a larger unit that must be reassembled
+ */
+export var SequenceFlags;
+(function (SequenceFlags) {
+    SequenceFlags[SequenceFlags["Continuation"] = 0] = "Continuation";
+    SequenceFlags[SequenceFlags["First"] = 1] = "First";
+    SequenceFlags[SequenceFlags["Last"] = 2] = "Last";
+    SequenceFlags[SequenceFlags["Standalone"] = 3] = "Standalone";
+})(SequenceFlags || (SequenceFlags = {}));

package/dist/util.d.ts

@@ -0,0 +1,9 @@
+import { type PrimaryHeader } from './types.js';
+export declare function getPacketLength(header: PrimaryHeader): number;
+/**
+ * Returns `true` if the packet's APID is the reserved idle/fill APID (`0x7FF`).
+ * Idle packets carry no mission data and should be discarded before routing.
+ */
+export declare function isIdlePacket(header: PrimaryHeader): boolean;
+/** Concatenates an array of `Uint8Array` chunks into a single contiguous buffer. */
+export declare function concatUint8Arrays(parts: Uint8Array[]): Uint8Array;

package/dist/util.js

@@ -0,0 +1,22 @@
+import { HEADER_BYTE_LENGTH, IDLE_APID } from './types.js';
+export function getPacketLength(header) {
+    return HEADER_BYTE_LENGTH + header.dataLength + 1;
+}
+/**
+ * Returns `true` if the packet's APID is the reserved idle/fill APID (`0x7FF`).
+ * Idle packets carry no mission data and should be discarded before routing.
+ */
+export function isIdlePacket(header) {
+    return header.apid === IDLE_APID;
+}
+/** Concatenates an array of `Uint8Array` chunks into a single contiguous buffer. */
+export function concatUint8Arrays(parts) {
+    const totalLength = parts.reduce((sum, p) => sum + p.byteLength, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.byteLength;
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@onion-party/spacepackets",
+  "version": "1.0.0",
+  "description": "Encode and decode CCSDS Space Packets for ground station and spacecraft software.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "logo.png"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc --project tsconfig.build.json",
+    "dev": "tsc --project tsconfig.build.json --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --config oxlint.json src/",
+    "format": "oxfmt src/",
+    "format:check": "oxfmt --check src/",
+    "coverage": "vitest run --coverage",
+    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test:run",
+    "prepublishOnly": "pnpm run check && pnpm run build",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "ccsds",
+    "space-packet",
+    "telemetry",
+    "telecommand",
+    "ground-station",
+    "space"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "author": "ryangibbs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryangibbs/spacepackets.git"
+  },
+  "homepage": "https://github.com/ryangibbs/spacepackets#readme",
+  "bugs": {
+    "url": "https://github.com/ryangibbs/spacepackets/issues"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "oxfmt": "^0.44.0",
+    "oxlint": "^1.59.0",
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  },
+  "lint-staged": {
+    "src/**/*.ts": [
+      "oxlint --config oxlint.json",
+      "oxfmt"
+    ]
+  },
+  "packageManager": "pnpm@10.33.0"
+}