mcbe-ipc 3.2.0 → 3.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 OmniacDev
+Copyright (c) 2026 OmniacDev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -23,4 +23,13 @@ npm install mcbe-ipc
 
 
 
+
+> [!NOTE]
+> Official documentation is still in progress.
+> 
+> For now, you can [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/OmniacDev/MCBE-IPC).
+> Please note that while it is generally accurate, some of the more advanced sections may contain small inaccuracies.
+
+
+
 [^1]: Inter-Pack Communication

package/dist/ipc.d.ts

@@ -2,7 +2,7 @@
  * @license
  * MIT License
  *
- * Copyright (c) 2025 OmniacDev
+ * Copyright (c) 2026 OmniacDev
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -23,11 +23,14 @@
  * SOFTWARE.
  */
 export declare namespace PROTO {
-    interface Serializable<T> {
+    interface Serializer<T> {
         serialize(value: T, stream: Buffer): Generator<void, void, void>;
+    }
+    interface Deserializer<T> {
         deserialize(stream: Buffer): Generator<void, T, void>;
     }
-    type Infer<S> = S extends PROTO.Serializable<infer T> ? T : never;
+    interface Serializable<T> extends Serializer<T>, Deserializer<T> {
+    }
     class Buffer {
         private _buffer;
         private _data_view;
@@ -78,33 +81,34 @@ export declare namespace PROTO {
     function Optional<T>(s: PROTO.Serializable<T>): PROTO.Serializable<T | undefined>;
     function Map<K, V>(kS: PROTO.Serializable<K>, vS: PROTO.Serializable<V>): PROTO.Serializable<Map<K, V>>;
     function Set<V>(s: PROTO.Serializable<V>): PROTO.Serializable<Set<V>>;
-    type Endpoint = string;
-    type Header = {
-        guid: string;
-        encoding: string;
-        index: number;
-        final: boolean;
-    };
-    const Endpoint: PROTO.Serializable<Endpoint>;
-    const Header: PROTO.Serializable<Header>;
 }
 export declare namespace NET {
-    let FRAG_MAX: number;
-    function serialize(buffer: PROTO.Buffer, max_size?: number): Generator<void, string[], void>;
-    function deserialize(strings: string[]): Generator<void, PROTO.Buffer, void>;
-    function emit<S extends PROTO.Serializable<any>>(endpoint: string, serializer: S, value: PROTO.Infer<S>): Generator<void, void, void>;
-    function listen<S extends PROTO.Serializable<any>>(endpoint: string, serializer: S, callback: (value: PROTO.Infer<S>) => Generator<void, void, void>): () => void;
+    type Meta = {
+        guid: string;
+        signature: string;
+    };
+    const Meta: PROTO.Serializable<Meta>;
+    export const SIGNATURE: string;
+    export let FRAG_MAX: number;
+    export function serialize(buffer: PROTO.Buffer, max_size?: number): Generator<void, string[], void>;
+    export function deserialize(strings: string[]): Generator<void, PROTO.Buffer, void>;
+    export interface EmitOptions {
+        metaOverride?: Partial<Meta>;
+    }
+    export function emit<S>(endpoint: string, serializer: PROTO.Serializer<S>, value: NoInfer<S>, options?: EmitOptions): Generator<void, void, void>;
+    export function listen<D>(endpoint: string, deserializer: PROTO.Deserializer<D>, callback: (value: NoInfer<D>, meta: Meta) => Generator<void, void, void>): () => void;
+    export {};
 }
 export declare namespace IPC {
     /** Sends a message with `args` to `channel` */
-    function send<S extends PROTO.Serializable<any>>(channel: string, serializer: S, value: PROTO.Infer<S>): void;
+    function send<S>(channel: string, serializer: PROTO.Serializer<S>, value: NoInfer<S>): void;
     /** Sends an `invoke` message through IPC, and expects a result asynchronously. */
-    function invoke<S extends PROTO.Serializable<any>, D extends PROTO.Serializable<any>>(channel: string, serializer: S, value: PROTO.Infer<S>, deserializer: D): Promise<PROTO.Infer<D>>;
+    function invoke<S, D>(channel: string, serializer: PROTO.Serializer<S>, value: NoInfer<S>, deserializer: PROTO.Deserializer<D>): Promise<NoInfer<D>>;
     /** Listens to `channel`. When a new message arrives, `listener` will be called with `listener(args)`. */
-    function on<D extends PROTO.Serializable<any>>(channel: string, deserializer: D, listener: (value: PROTO.Infer<D>) => void): () => void;
+    function on<D>(channel: string, deserializer: PROTO.Deserializer<D>, listener: (value: NoInfer<D>) => void): () => void;
     /** Listens to `channel` once. When a new message arrives, `listener` will be called with `listener(args)`, and then removed. */
-    function once<D extends PROTO.Serializable<any>>(channel: string, deserializer: D, listener: (value: PROTO.Infer<D>) => void): () => void;
+    function once<D>(channel: string, deserializer: PROTO.Deserializer<D>, listener: (value: NoInfer<D>) => void): () => void;
     /** Adds a handler for an `invoke` IPC. This handler will be called whenever `invoke(channel, ...args)` is called */
-    function handle<D extends PROTO.Serializable<any>, S extends PROTO.Serializable<any>>(channel: string, deserializer: D, serializer: S, listener: (value: PROTO.Infer<D>) => PROTO.Infer<S>): () => void;
+    function handle<D, S>(channel: string, deserializer: PROTO.Deserializer<D>, serializer: PROTO.Serializer<S>, listener: (value: NoInfer<D>) => NoInfer<S>): () => void;
 }
 export default IPC;

package/dist/ipc.js

@@ -2,7 +2,7 @@
  * @license
  * MIT License
  *
- * Copyright (c) 2025 OmniacDev
+ * Copyright (c) 2026 OmniacDev
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -23,6 +23,14 @@
  * SOFTWARE.
  */
 import { ScriptEventSource, system } from '@minecraft/server';
+var UTIL;
+(function (UTIL) {
+    function generate_id() {
+        const r = (Math.random() * 0x100000000) >>> 0;
+        return r.toString(16).padStart(8, '0').toUpperCase();
+    }
+    UTIL.generate_id = generate_id;
+})(UTIL || (UTIL = {}));
 export var PROTO;
 (function (PROTO) {
     class Buffer {
@@ -394,19 +402,22 @@ export var PROTO;
         };
     }
     PROTO.Set = Set;
-    PROTO.Endpoint = PROTO.String;
-    PROTO.Header = PROTO.Object({
+})(PROTO || (PROTO = {}));
+export var NET;
+(function (NET) {
+    const Endpoint = PROTO.String;
+    const Meta = PROTO.Object({
         guid: PROTO.String,
-        encoding: PROTO.String,
+        signature: PROTO.String
+    });
+    const Header = PROTO.Object({
+        meta: Meta,
         index: PROTO.UVarInt32,
         final: PROTO.Boolean
     });
-})(PROTO || (PROTO = {}));
-export var NET;
-(function (NET) {
+    const LISTENERS = new Map();
+    NET.SIGNATURE = 'mcbe-ipc:v3';
     NET.FRAG_MAX = 2048;
-    const ENCODING = 'mcbe-ipc:v3';
-    const ENDPOINTS = new Map();
     function* serialize(buffer, max_size = Infinity) {
         const uint8array = buffer.to_uint8array();
         const result = [];
@@ -464,11 +475,11 @@ export var NET;
                 return;
             const [serialized_endpoint, serialized_header] = event.id.split(':');
             const endpoint_stream = yield* PROTO.MIPS.deserialize(serialized_endpoint);
-            const endpoint = yield* PROTO.Endpoint.deserialize(endpoint_stream);
-            const listeners = ENDPOINTS.get(endpoint);
+            const endpoint = yield* Endpoint.deserialize(endpoint_stream);
+            const listeners = LISTENERS.get(endpoint);
             if (listeners !== undefined) {
                 const header_stream = yield* PROTO.MIPS.deserialize(serialized_header);
-                const header = yield* PROTO.Header.deserialize(header_stream);
+                const header = yield* Header.deserialize(header_stream);
                 const errors = [];
                 for (let i = 0; i < listeners.length; i++) {
                     try {
@@ -483,11 +494,11 @@ export var NET;
             }
         })());
     });
-    function create_listener(endpoint, listener) {
-        let listeners = ENDPOINTS.get(endpoint);
-        if (!listeners) {
+    function register(endpoint, listener) {
+        let listeners = LISTENERS.get(endpoint);
+        if (listeners === undefined) {
             listeners = new Array();
-            ENDPOINTS.set(endpoint, listeners);
+            LISTENERS.set(endpoint, listeners);
         }
         listeners.push(listener);
         return () => {
@@ -495,56 +506,54 @@ export var NET;
             if (idx !== -1)
                 listeners.splice(idx, 1);
             if (listeners.length === 0) {
-                ENDPOINTS.delete(endpoint);
+                LISTENERS.delete(endpoint);
             }
         };
     }
-    function generate_id() {
-        const r = (Math.random() * 0x100000000) >>> 0;
-        return ((r & 0xff).toString(16).padStart(2, '0') +
-            ((r >> 8) & 0xff).toString(16).padStart(2, '0') +
-            ((r >> 16) & 0xff).toString(16).padStart(2, '0') +
-            ((r >> 24) & 0xff).toString(16).padStart(2, '0')).toUpperCase();
-    }
-    function* emit(endpoint, serializer, value) {
-        const guid = generate_id();
+    function* emit(endpoint, serializer, value, options) {
+        const guid = options?.metaOverride?.guid ?? UTIL.generate_id();
+        const signature = options?.metaOverride?.signature ?? NET.SIGNATURE;
         const endpoint_stream = new PROTO.Buffer();
-        yield* PROTO.Endpoint.serialize(endpoint, endpoint_stream);
+        yield* Endpoint.serialize(endpoint, endpoint_stream);
         const serialized_endpoint = yield* PROTO.MIPS.serialize(endpoint_stream);
         const packet_stream = new PROTO.Buffer();
         yield* serializer.serialize(value, packet_stream);
         const serialized_packets = yield* serialize(packet_stream, NET.FRAG_MAX);
         for (let i = 0; i < serialized_packets.length; i++) {
             const serialized_packet = serialized_packets[i];
-            const header = { guid, encoding: ENCODING, index: i, final: i === serialized_packets.length - 1 };
+            const header = {
+                meta: { guid, signature },
+                index: i,
+                final: i === serialized_packets.length - 1
+            };
             const header_stream = new PROTO.Buffer();
-            yield* PROTO.Header.serialize(header, header_stream);
+            yield* Header.serialize(header, header_stream);
             const serialized_header = yield* PROTO.MIPS.serialize(header_stream);
             system.sendScriptEvent(`${serialized_endpoint}:${serialized_header}`, serialized_packet);
         }
     }
     NET.emit = emit;
-    function listen(endpoint, serializer, callback) {
+    function listen(endpoint, deserializer, callback) {
         const buffer = new Map();
-        const listener = function* (payload, serialized_packet) {
-            let fragment = buffer.get(payload.guid);
+        const listener = function* (header, serialized_packet) {
+            let fragment = buffer.get(header.meta.guid);
             if (!fragment) {
                 fragment = { size: -1, serialized_packets: [], data_size: 0 };
-                buffer.set(payload.guid, fragment);
+                buffer.set(header.meta.guid, fragment);
             }
-            if (payload.final) {
-                fragment.size = payload.index + 1;
+            if (header.final) {
+                fragment.size = header.index + 1;
             }
-            fragment.serialized_packets[payload.index] = serialized_packet;
-            fragment.data_size += payload.index + 1;
+            fragment.serialized_packets[header.index] = serialized_packet;
+            fragment.data_size += header.index + 1;
             if (fragment.size !== -1 && fragment.data_size === (fragment.size * (fragment.size + 1)) / 2) {
                 const stream = yield* deserialize(fragment.serialized_packets);
-                const value = yield* serializer.deserialize(stream);
-                yield* callback(value);
-                buffer.delete(payload.guid);
+                const value = yield* deserializer.deserialize(stream);
+                yield* callback(value, header.meta);
+                buffer.delete(header.meta.guid);
             }
         };
-        return create_listener(endpoint, listener);
+        return register(endpoint, listener);
     }
     NET.listen = listen;
 })(NET || (NET = {}));
@@ -557,12 +566,20 @@ export var IPC;
     IPC.send = send;
     /** Sends an `invoke` message through IPC, and expects a result asynchronously. */
     function invoke(channel, serializer, value, deserializer) {
-        system.runJob(NET.emit(`ipc:${channel}:invoke`, serializer, value));
+        const id = UTIL.generate_id();
         return new Promise(resolve => {
-            const terminate = NET.listen(`ipc:${channel}:handle`, deserializer, function* (value) {
+            const terminate = NET.listen(`ipc:${channel}:handle`, deserializer, function* (value, meta) {
+                if (meta.signature.includes(`+correlation`) && meta.guid !== id)
+                    return;
                 resolve(value);
                 terminate();
             });
+            system.runJob(NET.emit(`ipc:${channel}:invoke`, serializer, value, {
+                metaOverride: {
+                    guid: id,
+                    signature: `${NET.SIGNATURE}+correlation`
+                }
+            }));
         });
     }
     IPC.invoke = invoke;
@@ -584,9 +601,16 @@ export var IPC;
     IPC.once = once;
     /** Adds a handler for an `invoke` IPC. This handler will be called whenever `invoke(channel, ...args)` is called */
     function handle(channel, deserializer, serializer, listener) {
-        return NET.listen(`ipc:${channel}:invoke`, deserializer, function* (value) {
+        return NET.listen(`ipc:${channel}:invoke`, deserializer, function* (value, meta) {
             const result = listener(value);
-            yield* NET.emit(`ipc:${channel}:handle`, serializer, result);
+            yield* NET.emit(`ipc:${channel}:handle`, serializer, result, {
+                metaOverride: meta.signature.includes(`+correlation`)
+                    ? {
+                        guid: meta.guid,
+                        signature: `${NET.SIGNATURE}+correlation`
+                    }
+                    : undefined
+            });
         });
     }
     IPC.handle = handle;

package/package.json

@@ -3,7 +3,7 @@
   "author": "OmniacDev",
   "description": "IPC system for MCBE Script API projects",
   "license": "MIT",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/OmniacDev/MCBE-IPC.git"
@@ -20,12 +20,15 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "vitest",
+    "bench": "vitest bench",
     "format": "prettier --write src",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "prettier": "^3.3.3",
-    "typescript": "^5.5.4"
+    "typescript": "^5.5.4",
+    "vitest": "^4.0.16"
   },
   "dependencies": {
     "@minecraft/server": "^1.18.0"