@standardserver/peer 0.0.1 → 0.0.3

package/dist/index.d.mts

@@ -202,22 +202,60 @@ declare class ClientPeer {
     close(options?: AsyncIdQueueCloseOptions): Promise<void>;
 }
 
+interface EncodePeerMessageOptions {
+    /**
+     * Optional string prepended to the encoded message.
+     * Used to distinguish messages when multiple protocols share the same peer.
+     */
+    prefix?: string;
+}
+/**
+ * Encodes a {@link PeerMessage} into a wire-safe representation.
+ *
+ * Encoding rules:
+ * - If no binary payload is present, the message is encoded as a JSON string.
+ * - If binary data exists, the output layout is:
+ *
+ *   [ UTF-8 (prefix + JSON) | delimiter byte | raw binary bytes ]
+ *
+ * The optional prefix is prepended to the JSON portion before encoding.
+ */
+declare function encodePeerMessage(message: PeerMessage, options?: EncodePeerMessageOptions): Promise<string | Uint8Array<ArrayBuffer>>;
+interface DecodePeerMessageOptions {
+    /**
+     * Optional prefix expected at the start of the encoded message.
+     * If present and the message does not start with this prefix,
+     * the decoder returns `matched: false`.
+     */
+    prefix?: string;
+}
 /**
- * Encodes a PeerMessage into a wire-safe representation.
+ * Result of a decode attempt.
  *
- * - If no binary data is present, the message is encoded as a JSON string.
- * - If binary data exists, the output is:
- *   [ UTF-8 JSON bytes | separator byte | raw binary bytes ]
+ * - `matched: false` indicates the input does not belong to this decoder
+ *   (typically due to a prefix mismatch).
+ * - `matched: true` indicates successful decoding of a {@link PeerMessage}.
  */
-declare function encodePeerMessage(message: PeerMessage): Promise<string | Uint8Array<ArrayBuffer>>;
+type DecodePeerMessageResult = {
+    matched: false;
+    message?: undefined;
+} | {
+    matched: true;
+    message: PeerMessage;
+};
 /**
- * Decodes a wire-encoded PeerMessage.
+ * Decodes a wire-encoded {@link PeerMessage}.
+ *
+ * Decoding rules:
+ * - String input is treated as a JSON-only message.
+ * - Binary input may contain:
+ *   - JSON only, or
+ *   - JSON followed by binary data separated by the delimiter byte.
  *
- * - String input is treated as pure JSON.
- * - Binary input may contain only JSON bytes, or JSON followed by binary data
- *   separated by the separator byte.
+ * If a prefix is provided, it must be present at the start of the payload
+ * or the decode attempt will return `matched: false`.
  */
-declare function decodePeerMessage(data: string | Uint8Array<ArrayBuffer>): PeerMessage;
+declare function decodePeerMessage(encoded: string | Uint8Array<ArrayBuffer>, options?: DecodePeerMessageOptions): DecodePeerMessageResult;
 
 /**
  * Creates an AsyncIterator from a queue of peer event-stream messages.
@@ -277,4 +315,4 @@ declare class ServerPeer {
 }
 
 export { ClientPeer, EventStreamTransmitter, HibernationEventIterator, ServerPeer, decodePeerMessage, encodePeerMessage, toEventIterator };
-export type { ClientPeerCloseOptions, HibernationEventIteratorCallback, PeerAbortMessage, PeerEventStreamMessage, PeerMessage, PeerOctetStreamMessage, PeerRequestMessage, PeerResponseMessage, PeerStreamCancelMessage, ServerPeerCloseOptions };
+export type { ClientPeerCloseOptions, DecodePeerMessageOptions, DecodePeerMessageResult, EncodePeerMessageOptions, HibernationEventIteratorCallback, PeerAbortMessage, PeerEventStreamMessage, PeerMessage, PeerOctetStreamMessage, PeerRequestMessage, PeerResponseMessage, PeerStreamCancelMessage, ServerPeerCloseOptions };

package/dist/index.d.ts

@@ -202,22 +202,60 @@ declare class ClientPeer {
     close(options?: AsyncIdQueueCloseOptions): Promise<void>;
 }
 
+interface EncodePeerMessageOptions {
+    /**
+     * Optional string prepended to the encoded message.
+     * Used to distinguish messages when multiple protocols share the same peer.
+     */
+    prefix?: string;
+}
+/**
+ * Encodes a {@link PeerMessage} into a wire-safe representation.
+ *
+ * Encoding rules:
+ * - If no binary payload is present, the message is encoded as a JSON string.
+ * - If binary data exists, the output layout is:
+ *
+ *   [ UTF-8 (prefix + JSON) | delimiter byte | raw binary bytes ]
+ *
+ * The optional prefix is prepended to the JSON portion before encoding.
+ */
+declare function encodePeerMessage(message: PeerMessage, options?: EncodePeerMessageOptions): Promise<string | Uint8Array<ArrayBuffer>>;
+interface DecodePeerMessageOptions {
+    /**
+     * Optional prefix expected at the start of the encoded message.
+     * If present and the message does not start with this prefix,
+     * the decoder returns `matched: false`.
+     */
+    prefix?: string;
+}
 /**
- * Encodes a PeerMessage into a wire-safe representation.
+ * Result of a decode attempt.
  *
- * - If no binary data is present, the message is encoded as a JSON string.
- * - If binary data exists, the output is:
- *   [ UTF-8 JSON bytes | separator byte | raw binary bytes ]
+ * - `matched: false` indicates the input does not belong to this decoder
+ *   (typically due to a prefix mismatch).
+ * - `matched: true` indicates successful decoding of a {@link PeerMessage}.
  */
-declare function encodePeerMessage(message: PeerMessage): Promise<string | Uint8Array<ArrayBuffer>>;
+type DecodePeerMessageResult = {
+    matched: false;
+    message?: undefined;
+} | {
+    matched: true;
+    message: PeerMessage;
+};
 /**
- * Decodes a wire-encoded PeerMessage.
+ * Decodes a wire-encoded {@link PeerMessage}.
+ *
+ * Decoding rules:
+ * - String input is treated as a JSON-only message.
+ * - Binary input may contain:
+ *   - JSON only, or
+ *   - JSON followed by binary data separated by the delimiter byte.
  *
- * - String input is treated as pure JSON.
- * - Binary input may contain only JSON bytes, or JSON followed by binary data
- *   separated by the separator byte.
+ * If a prefix is provided, it must be present at the start of the payload
+ * or the decode attempt will return `matched: false`.
  */
-declare function decodePeerMessage(data: string | Uint8Array<ArrayBuffer>): PeerMessage;
+declare function decodePeerMessage(encoded: string | Uint8Array<ArrayBuffer>, options?: DecodePeerMessageOptions): DecodePeerMessageResult;
 
 /**
  * Creates an AsyncIterator from a queue of peer event-stream messages.
@@ -277,4 +315,4 @@ declare class ServerPeer {
 }
 
 export { ClientPeer, EventStreamTransmitter, HibernationEventIterator, ServerPeer, decodePeerMessage, encodePeerMessage, toEventIterator };
-export type { ClientPeerCloseOptions, HibernationEventIteratorCallback, PeerAbortMessage, PeerEventStreamMessage, PeerMessage, PeerOctetStreamMessage, PeerRequestMessage, PeerResponseMessage, PeerStreamCancelMessage, ServerPeerCloseOptions };
+export type { ClientPeerCloseOptions, DecodePeerMessageOptions, DecodePeerMessageResult, EncodePeerMessageOptions, HibernationEventIteratorCallback, PeerAbortMessage, PeerEventStreamMessage, PeerMessage, PeerOctetStreamMessage, PeerRequestMessage, PeerResponseMessage, PeerStreamCancelMessage, ServerPeerCloseOptions };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { AsyncIteratorClass, isTypescriptObject, isAsyncIteratorObject, SequentialIdGenerator, AsyncIdQueue, AbortError, stringifyJSON } from '@standardserver/shared';
 import { generateContentDisposition, flattenStandardHeader, getFilenameFromContentDisposition } from '@standardserver/core';
-import { withEventIteratorEventMeta, EventIteratorErrorEvent, resolveEventIteratorEvent } from '@standardserver/core/event-stream';
+import { withEventIteratorEventMeta, EventIteratorErrorEvent, unwrapEventIteratorEvent } from '@standardserver/core/event-stream';
 
 function toEventIterator(pull, cleanup) {
   return new AsyncIteratorClass(async () => {
@@ -55,7 +55,7 @@ class EventStreamTransmitter {
         if (item.done) {
           this.isCompleted = true;
         }
-        const [data, meta] = resolveEventIteratorEvent(item.value);
+        const [data, meta] = unwrapEventIteratorEvent(item.value);
         json = { ...meta, event: item.done ? "close" : "message", data };
       } catch (err) {
         if (err instanceof EventIteratorErrorEvent) {
@@ -63,7 +63,7 @@ class EventStreamTransmitter {
             return;
           }
           this.isCompleted = true;
-          const [resolvedError, meta] = resolveEventIteratorEvent(err);
+          const [resolvedError, meta] = unwrapEventIteratorEvent(err);
           json = { ...meta, event: "error", data: resolvedError.data };
         } else {
           this.isCompleted = true;
@@ -403,36 +403,57 @@ class ClientPeer {
   }
 }
 
-const JSON_BINARY_SEPARATOR_BYTE = 255;
+const JSON_BINARY_DELIMITER = 255;
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
-async function encodePeerMessage(message) {
+async function encodePeerMessage(message, options = {}) {
+  const jsonPart = stringifyJSON({ ...message, binary: void 0 });
   if (message.binary === void 0) {
-    return stringifyJSON(message);
+    return options.prefix ? options.prefix + jsonPart : jsonPart;
   }
-  const jsonBytes = textEncoder.encode(stringifyJSON(message));
+  const textBytes = textEncoder.encode(
+    options.prefix ? options.prefix + jsonPart : jsonPart
+  );
   const binaryBytes = message.binary instanceof Blob ? new Uint8Array(await message.binary.arrayBuffer()) : message.binary;
   const output = new Uint8Array(
-    jsonBytes.length + 1 + binaryBytes.length
+    textBytes.length + 1 + binaryBytes.length
   );
-  output.set(jsonBytes, 0);
-  output[jsonBytes.length] = JSON_BINARY_SEPARATOR_BYTE;
-  output.set(binaryBytes, jsonBytes.length + 1);
+  output.set(textBytes, 0);
+  output[textBytes.length] = JSON_BINARY_DELIMITER;
+  output.set(binaryBytes, textBytes.length + 1);
   return output;
 }
-function decodePeerMessage(data) {
-  if (typeof data === "string") {
-    return JSON.parse(data);
+function decodePeerMessage(encoded, options = {}) {
+  if (typeof encoded === "string") {
+    if (options.prefix) {
+      if (!encoded.startsWith(options.prefix)) {
+        return { matched: false };
+      }
+      encoded = encoded.slice(options.prefix.length);
+    }
+    return { matched: true, message: JSON.parse(encoded) };
   }
-  const separatorIndex = data.indexOf(JSON_BINARY_SEPARATOR_BYTE);
+  if (options.prefix) {
+    const prefixBytes = textEncoder.encode(options.prefix);
+    for (let i = 0; i < prefixBytes.length; i++) {
+      if (encoded[i] !== prefixBytes[i]) {
+        return { matched: false };
+      }
+    }
+    encoded = encoded.subarray(prefixBytes.length);
+  }
+  const separatorIndex = encoded.indexOf(JSON_BINARY_DELIMITER);
   if (separatorIndex === -1) {
-    return JSON.parse(textDecoder.decode(data));
+    return { matched: true, message: JSON.parse(textDecoder.decode(encoded)) };
   }
-  const jsonBytes = data.subarray(0, separatorIndex);
-  const binaryBytes = data.subarray(separatorIndex + 1);
+  const jsonBytes = encoded.subarray(0, separatorIndex);
+  const binaryBytes = encoded.subarray(separatorIndex + 1);
   return {
-    ...JSON.parse(textDecoder.decode(jsonBytes)),
-    binary: binaryBytes
+    matched: true,
+    message: {
+      ...JSON.parse(textDecoder.decode(jsonBytes)),
+      binary: binaryBytes
+    }
   };
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@standardserver/peer",
   "type": "module",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "license": "MIT",
   "homepage": "https://standardserver.dev",
   "repository": {
@@ -20,8 +20,8 @@
     "dist"
   ],
   "dependencies": {
-    "@standardserver/core": "0.0.1",
-    "@standardserver/shared": "0.0.1"
+    "@standardserver/core": "0.0.3",
+    "@standardserver/shared": "0.0.3"
   },
   "scripts": {
     "build": "unbuild",