mcbe-ipc 3.2.1 → 3.3.1

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

@@ -27,7 +27,7 @@ npm install mcbe-ipc
 > [!NOTE]
 > Official documentation is still in progress.
 > 
-> For now, you can refer to the [DeepWiki page](https://deepwiki.com/OmniacDev/MCBE-IPC/).
+> 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.
 
 

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,20 +23,15 @@
  * SOFTWARE.
  */
 export declare namespace PROTO {
-    const t: unique symbol;
-    interface Phantom<T> {
-        readonly [t]?: T;
-    }
-    export interface Serializer<T> extends Phantom<T> {
+    interface Serializer<T> {
         serialize(value: T, stream: Buffer): Generator<void, void, void>;
     }
-    export interface Deserializer<T> extends Phantom<T> {
+    interface Deserializer<T> {
         deserialize(stream: Buffer): Generator<void, T, void>;
     }
-    export interface Serializable<T> extends Serializer<T>, Deserializer<T> {
+    interface Serializable<T> extends Serializer<T>, Deserializer<T> {
     }
-    export type Infer<S> = S extends Phantom<infer T> ? T : never;
-    export class Buffer {
+    class Buffer {
         private _buffer;
         private _data_view;
         private _length;
@@ -55,65 +50,68 @@ export declare namespace PROTO {
         static from_uint8array(array: Uint8Array): Buffer;
         to_uint8array(): Uint8Array;
     }
-    export namespace MIPS {
+    namespace MIPS {
         function serialize(stream: PROTO.Buffer): Generator<void, string, void>;
         function deserialize(str: string): Generator<void, PROTO.Buffer, void>;
     }
-    export const Void: PROTO.Serializable<void>;
-    export const Null: PROTO.Serializable<null>;
-    export const Undefined: PROTO.Serializable<undefined>;
-    export const Int8: PROTO.Serializable<number>;
-    export const Int16: PROTO.Serializable<number>;
-    export const Int32: PROTO.Serializable<number>;
-    export const UInt8: PROTO.Serializable<number>;
-    export const UInt16: PROTO.Serializable<number>;
-    export const UInt32: PROTO.Serializable<number>;
-    export const UVarInt32: PROTO.Serializable<number>;
-    export const VarInt32: PROTO.Serializable<number>;
-    export const Float32: PROTO.Serializable<number>;
-    export const Float64: PROTO.Serializable<number>;
-    export const String: PROTO.Serializable<string>;
-    export const Boolean: PROTO.Serializable<boolean>;
-    export const UInt8Array: PROTO.Serializable<Uint8Array>;
-    export const Date: PROTO.Serializable<Date>;
-    export function Object<T extends object>(s: {
+    const Void: PROTO.Serializable<void>;
+    const Null: PROTO.Serializable<null>;
+    const Undefined: PROTO.Serializable<undefined>;
+    const Int8: PROTO.Serializable<number>;
+    const Int16: PROTO.Serializable<number>;
+    const Int32: PROTO.Serializable<number>;
+    const UInt8: PROTO.Serializable<number>;
+    const UInt16: PROTO.Serializable<number>;
+    const UInt32: PROTO.Serializable<number>;
+    const UVarInt32: PROTO.Serializable<number>;
+    const VarInt32: PROTO.Serializable<number>;
+    const Float32: PROTO.Serializable<number>;
+    const Float64: PROTO.Serializable<number>;
+    const String: PROTO.Serializable<string>;
+    const Boolean: PROTO.Serializable<boolean>;
+    const UInt8Array: PROTO.Serializable<Uint8Array>;
+    const Date: PROTO.Serializable<Date>;
+    function Object<T extends object>(s: {
         [K in keyof T]: PROTO.Serializable<T[K]>;
     }): PROTO.Serializable<T>;
-    export function Array<T>(s: PROTO.Serializable<T>): PROTO.Serializable<T[]>;
-    export function Tuple<T extends any[]>(...s: {
+    function Array<T>(s: PROTO.Serializable<T>): PROTO.Serializable<T[]>;
+    function Tuple<T extends any[]>(...s: {
         [K in keyof T]: PROTO.Serializable<T[K]>;
     }): PROTO.Serializable<T>;
-    export function Optional<T>(s: PROTO.Serializable<T>): PROTO.Serializable<T | undefined>;
-    export function Map<K, V>(kS: PROTO.Serializable<K>, vS: PROTO.Serializable<V>): PROTO.Serializable<Map<K, V>>;
-    export function Set<V>(s: PROTO.Serializable<V>): PROTO.Serializable<Set<V>>;
-    export type Endpoint = string;
-    export type Header = {
+    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>>;
+}
+export declare namespace NET {
+    type Meta = {
         guid: string;
-        encoding: string;
-        index: number;
-        final: boolean;
+        signature: string;
     };
-    export const Endpoint: PROTO.Serializable<Endpoint>;
-    export const Header: PROTO.Serializable<Header>;
+    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 interface ListenOptions {
+        filter?: (meta: Meta) => boolean;
+    }
+    export function listen<D>(endpoint: string, deserializer: PROTO.Deserializer<D>, callback: (value: NoInfer<D>, meta: Meta) => Generator<void, void, void>, options?: ListenOptions): () => void;
     export {};
 }
-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.Serializer<any>>(endpoint: string, serializer: S, value: PROTO.Infer<S>): Generator<void, void, void>;
-    function listen<D extends PROTO.Deserializer<any>>(endpoint: string, deserializer: D, callback: (value: PROTO.Infer<D>) => Generator<void, void, void>): () => void;
-}
 export declare namespace IPC {
     /** Sends a message with `args` to `channel` */
-    function send<S extends PROTO.Serializer<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.Serializer<any>, D extends PROTO.Deserializer<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.Deserializer<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.Deserializer<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.Deserializer<any>, S extends PROTO.Serializer<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,15 +475,15 @@ 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++) {
+                for (const listener of [...listeners]) {
                     try {
-                        yield* listeners[i](header, event.message);
+                        yield* listener(header, event.message);
                     }
                     catch (e) {
                         errors.push(e);
@@ -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,61 @@ 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, deserializer, callback) {
+    function listen(endpoint, deserializer, callback, options) {
         const buffer = new Map();
-        const listener = function* (payload, serialized_packet) {
-            let fragment = buffer.get(payload.guid);
-            if (!fragment) {
-                fragment = { size: -1, serialized_packets: [], data_size: 0 };
-                buffer.set(payload.guid, fragment);
+        const listener = function* (header, fragment) {
+            let packet = buffer.get(header.meta.guid);
+            if (packet === undefined) {
+                if (options?.filter?.(header.meta) === false)
+                    return;
+                packet = { size: -1, fragments: [], received: 0 };
+                buffer.set(header.meta.guid, packet);
             }
-            if (payload.final) {
-                fragment.size = payload.index + 1;
+            if (header.final) {
+                packet.size = header.index + 1;
             }
-            fragment.serialized_packets[payload.index] = serialized_packet;
-            fragment.data_size += payload.index + 1;
-            if (fragment.size !== -1 && fragment.data_size === (fragment.size * (fragment.size + 1)) / 2) {
-                const stream = yield* deserialize(fragment.serialized_packets);
+            if (packet.fragments[header.index] === undefined) {
+                packet.fragments[header.index] = fragment;
+                packet.received++;
+            }
+            else {
+                throw new Error(`received duplicate fragment ${header.index} for packet ${header.meta.guid}`);
+            }
+            if (packet.size !== -1 && packet.size === packet.received) {
+                const stream = yield* deserialize(packet.fragments);
                 const value = yield* deserializer.deserialize(stream);
-                yield* callback(value);
-                buffer.delete(payload.guid);
+                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 +573,22 @@ export var IPC;
     IPC.send = send;
     /** Sends an `invoke` message through IPC, and expects a result asynchronously. */
     function invoke(channel, serializer, value, deserializer) {
+        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();
+            }, {
+                filter: meta => !meta.signature.includes(`+correlation`) || meta.guid === id
             });
-            system.runJob(NET.emit(`ipc:${channel}:invoke`, serializer, value));
+            system.runJob(NET.emit(`ipc:${channel}:invoke`, serializer, value, {
+                metaOverride: {
+                    guid: id,
+                    signature: `${NET.SIGNATURE}+correlation`
+                }
+            }));
         });
     }
     IPC.invoke = invoke;
@@ -584,9 +610,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.1",
+  "version": "3.3.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/OmniacDev/MCBE-IPC.git"