@rosepetal/node-red-contrib-async-function 1.0.2 → 1.1.0

package/README.md

@@ -20,7 +20,7 @@ Run heavy computations in Node-RED without slowing down your flows. This node wo
 
 ## How It Works
 
-Drop an **async function** node into your flow. Write your code just like you would in a regular function node. The difference? Your code runs in a separate worker thread by default (or a child process if configured), so heavy operations won't freeze Node-RED.
+Drop a **worker function** node into your flow. Write your code just like you would in a regular function node. The difference? Your code runs in a separate worker thread by default (or a child process if configured), so heavy operations won't freeze Node-RED.
 
 ## When to Use This
 
@@ -31,7 +31,7 @@ Drop an **async function** node into your flow. Write your code just like you wo
 
 **Skip It For:**
 - Simple math or quick transformations (the regular function node is faster).
-- When you need `context`, `flow`, or `global` storage (coming in v2.0).
+- Flows that require live context reads/writes during execution (context is snapshot-based).
 
 ## Node Options
 
@@ -62,11 +62,11 @@ return msg;
 ```
 
 ### Buffer Handling
-- **Buffers** – Any `Buffer` in `msg` is transferred through shared memory (`/dev/shm` on Linux, otherwise `os.tmpdir()`), with base64 fallback if needed.
+- **Buffers** – Worker Threads use zero-copy transfer when possible. Child Process mode and non-transferable buffers fall back to shared memory (`/dev/shm` on Linux, otherwise `os.tmpdir()`), with base64 fallback if needed.
 
 ## Typical Flow
 
-1. Add an **async function** node to your workspace.
+1. Add a **worker function** node to your workspace.
 2. Connect an Inject node (input) and a Debug node (output).
 3. Write a simple script:
    ```javascript
@@ -86,9 +86,11 @@ return msg;
 - `console` – Logging functions
 - `setTimeout`, `setInterval` – Timers
 
-**Not Available (Yet):**
-- `context`, `flow`, `global` – Coming in v2.0
-- `node` – Node instance methods
+**Notes:**
+- `context`, `flow`, `global` are snapshot-based: reads are from the snapshot, writes are applied after the function completes
+- Snapshot includes only literal keys found in `flow.get("key")` / `global.get("key")` / `context.get("key")`
+- Context store selection is not supported (default store only)
+- `node.warn/error/log` are collected and forwarded to the main thread
 - Non-serializable objects (functions, symbols, etc.)
 
 ## Code Examples
@@ -170,7 +172,7 @@ The node shows you what's happening in real time:
 - Best for operations taking more than 10ms to run.
 - Each node maintains a fixed pool of workers—no startup delay or dynamic scaling overhead.
 - Workers are dedicated per-node, ensuring predictable performance.
-- **Binary Fast Path**: Buffers use shared memory transfer (base64 fallback), keeping messages responsive even with large payloads.
+- **Binary Fast Path**: Worker threads use zero-copy transfer when possible; shared memory is the fallback.
 - Event loop never blocks, even when processing multi-MB binary data (images, files, etc.).
 
 ## Error Handling
@@ -192,7 +194,9 @@ npm install @rosepetal/node-red-contrib-async-function
 
 Restart Node-RED and find the node in the **function** category.
 
-## Migration from Earlier Versions
+## Migration
+
+### From minWorkers/maxWorkers
 
 If you're upgrading from a version that used `minWorkers` and `maxWorkers`:
 - Your existing flows will automatically migrate to use the new `numWorkers` parameter

package/nodes/lib/child-process-pool.js

@@ -17,6 +17,7 @@ const DEFAULT_CONFIG = {
     taskTimeout: 30000,         // Default task timeout: 30s
     maxQueueSize: 100,          // Max queued messages
     shmThreshold: 0,            // Always use shared memory for Buffers
+    transferMode: 'shared',     // shared | copy (transfer not supported for child processes)
     libs: [],                   // External modules to load in workers
     nodeRedUserDir: null,       // Node-RED user directory for module resolution
     workerScript: path.join(__dirname, 'child-process-script.js')
@@ -166,7 +167,8 @@ class ChildProcessPool {
                     type: 'init',
                     libs: this.config.libs || [],
                     nodeRedUserDir: this.config.nodeRedUserDir,
-                    shmThreshold: this.config.shmThreshold
+                    shmThreshold: this.config.shmThreshold,
+                    transferMode: this.config.transferMode
                 });
             } catch (err) {
                 clearTimeout(readyTimeout);
@@ -298,7 +300,9 @@ class ChildProcessPool {
         workerState.state = WorkerState.BUSY;
         workerState.taskId = taskId;
 
-        this.serializer.sanitizeMessage(msg, null, taskId).then(sanitizedMsg => {
+        this.serializer.sanitizeMessage(msg, null, taskId, {
+            transferMode: this.config.transferMode
+        }).then(sanitizedMsg => {
             this.timeoutManager.startTimeout(taskId, timeout, () => {
                 this.handleTimeout(workerState, taskId);
             });
@@ -329,7 +333,7 @@ class ChildProcessPool {
      * @param {object} message - Message from worker
      */
     handleWorkerMessage(workerState, message) {
-        const { type, taskId, result, error, performance } = message || {};
+        const { type, taskId, result, error, performance, contextUpdates, logs } = message || {};
 
         if (type === 'result') {
             this.timeoutManager.cancelTimeout(taskId);
@@ -339,8 +343,18 @@ class ChildProcessPool {
                 this.callbacks.delete(taskId);
                 this.recycleWorker(workerState);
 
-                this.serializer.restoreBuffers(result).then(restoredResult => {
-                    callback(null, { result: restoredResult, performance: performance || null });
+                const restoreResult = this.serializer.restoreBuffers(result);
+                const restoreContext = contextUpdates
+                    ? this.serializer.restoreBuffers(contextUpdates)
+                    : Promise.resolve(contextUpdates);
+
+                Promise.all([restoreResult, restoreContext]).then(([restoredResult, restoredContext]) => {
+                    callback(null, {
+                        result: restoredResult,
+                        performance: performance || null,
+                        contextUpdates: restoredContext || null,
+                        logs: Array.isArray(logs) ? logs : null
+                    });
                 }).catch(restoreErr => {
                     callback(restoreErr instanceof Error ? restoreErr : new Error(String(restoreErr)), null);
                 });
@@ -362,7 +376,20 @@ class ChildProcessPool {
                 if (error && error.name) {
                     err.name = error.name;
                 }
-                callback(err, null);
+
+                if (contextUpdates) {
+                    this.serializer.restoreBuffers(contextUpdates).then(restoredContext => {
+                        err.contextUpdates = restoredContext;
+                        err.logs = Array.isArray(logs) ? logs : null;
+                        callback(err, null);
+                    }).catch(() => {
+                        err.logs = Array.isArray(logs) ? logs : null;
+                        callback(err, null);
+                    });
+                } else {
+                    err.logs = Array.isArray(logs) ? logs : null;
+                    callback(err, null);
+                }
             }
 
             this.recycleWorker(workerState);

package/nodes/lib/child-process-script.js

@@ -16,6 +16,9 @@ const { AsyncMessageSerializer } = require('./message-serializer');
 // Track worker state
 let isTerminating = false;
 let isInitialized = false;
+let transferMode = 'shared';
+const MSG_WRAPPER_KEY = '__rosepetal_msg';
+const CONTEXT_WRAPPER_KEY = '__rosepetal_context';
 
 // AsyncLocalStorage for tracking task context across async boundaries
 const taskContext = new AsyncLocalStorage();
@@ -70,6 +73,120 @@ function configureBaseRequire(nodeRedUserDir) {
     global.require = baseRequire;
 }
 
+function createContextProxy(initialData, updates) {
+    const data = (initialData && typeof initialData === 'object') ? initialData : {};
+    const updateMap = updates || {};
+
+    const getValue = (key, fallback) => {
+        if (Object.prototype.hasOwnProperty.call(updateMap, key)) {
+            return updateMap[key];
+        }
+        if (Object.prototype.hasOwnProperty.call(data, key)) {
+            return data[key];
+        }
+        return fallback;
+    };
+
+    const setValue = (key, value) => {
+        data[key] = value;
+        updateMap[key] = value;
+    };
+
+    const api = {
+        get: (key, storeOrCb, cbMaybe) => {
+            let callback = null;
+            if (typeof storeOrCb === 'function') {
+                callback = storeOrCb;
+            } else if (typeof cbMaybe === 'function') {
+                callback = cbMaybe;
+            }
+
+            const value = Array.isArray(key)
+                ? key.map((entry) => getValue(entry, undefined))
+                : getValue(key, undefined);
+
+            if (typeof callback === 'function') {
+                callback(null, value);
+                return undefined;
+            }
+            return value;
+        },
+        set: (key, value, cbMaybe) => {
+            let callback = typeof cbMaybe === 'function' ? cbMaybe : null;
+            let entries = [];
+
+            if (Array.isArray(key)) {
+                if (Array.isArray(value)) {
+                    entries = key.map((entry, index) => [entry, value[index]]);
+                } else if (value && typeof value === 'object') {
+                    entries = key.map((entry) => [entry, value[entry]]);
+                }
+            } else if (key && typeof key === 'object' && value !== null) {
+                entries = Object.entries(key);
+                if (typeof value === 'function') {
+                    callback = value;
+                }
+            } else {
+                entries = [[key, value]];
+            }
+
+            entries.forEach(([entryKey, entryValue]) => {
+                if (entryKey !== undefined) {
+                    setValue(entryKey, entryValue);
+                }
+            });
+
+            if (typeof callback === 'function') {
+                callback(null);
+            }
+            return undefined;
+        }
+    };
+
+    return new Proxy(api, {
+        get(target, prop) {
+            if (typeof prop === 'symbol' || prop in target) {
+                return target[prop];
+            }
+            return getValue(prop, undefined);
+        },
+        set(target, prop, value) {
+            if (typeof prop === 'symbol' || prop in target) {
+                target[prop] = value;
+                return true;
+            }
+            setValue(prop, value);
+            return true;
+        }
+    });
+}
+
+function createNodeProxy(logs) {
+    const push = (level, args) => {
+        if (!Array.isArray(logs)) {
+            return;
+        }
+        if (!args || args.length === 0) {
+            logs.push({ level, message: '' });
+            return;
+        }
+        const message = args.length === 1 ? args[0] : args.map((arg) => arg);
+        logs.push({ level, message });
+    };
+
+    return {
+        warn: (...args) => {
+            push('warn', args);
+        },
+        error: (...args) => {
+            push('error', args);
+        },
+        log: (...args) => {
+            push('log', args);
+        }
+    };
+}
+
 function parseModuleSpec(spec) {
     const match = /((?:@[^/]+\/)?[^/@]+)(\/[^/@]+)?(?:@([\s\S]+))?/.exec(spec);
     if (!match) {
@@ -109,7 +226,7 @@ async function loadConfiguredModules(libs) {
             moduleVars.push(lib.var);
             moduleValues.push(loadedModules[lib.var]);
         } catch (err) {
-            console.error(`[async-function] Failed to load module ${lib.module}: ${err.message}`);
+            console.error(`[worker-function] Failed to load module ${lib.module}: ${err.message}`);
             failedModules.push({ module: lib.module, var: lib.var, error: err.message });
         }
     }
@@ -139,6 +256,9 @@ async function initializeWorker(initData) {
     configureBaseRequire(nodeRedUserDir);
 
     const threshold = initData && typeof initData.shmThreshold === 'number' ? initData.shmThreshold : undefined;
+    if (initData && typeof initData.transferMode === 'string') {
+        transferMode = initData.transferMode;
+    }
     shmManager = new SharedMemoryManager({
         threshold,
         trackAttachments: false,
@@ -188,30 +308,59 @@ process.on('message', async (data) => {
 
     if (type === 'execute') {
         taskContext.run({ taskId }, async () => {
+            const contextUpdates = { flow: {}, global: {}, context: {} };
+            const logs = [];
+
             try {
                 const restoreStart = process.hrtime.bigint();
-                const restoredMsg = await serializer.restoreBuffers(msg);
+                const restoredPayload = await serializer.restoreBuffers(msg);
                 const transferToWorkerMs = hrtimeDiffToMs(restoreStart);
 
+                let contextPayload = {};
+                let restoredMsg = restoredPayload;
+                if (restoredPayload && typeof restoredPayload === 'object' && Object.prototype.hasOwnProperty.call(restoredPayload, MSG_WRAPPER_KEY)) {
+                    contextPayload = restoredPayload[CONTEXT_WRAPPER_KEY] || {};
+                    restoredMsg = restoredPayload[MSG_WRAPPER_KEY];
+                }
+
+                const nodeProxy = createNodeProxy(logs);
+                const flowProxy = createContextProxy(contextPayload.flow, contextUpdates.flow);
+                const globalProxy = createContextProxy(contextPayload.global, contextUpdates.global);
+                const contextProxy = createContextProxy(contextPayload.context, contextUpdates.context);
+
                 const cacheKey = code + '|' + moduleVars.join(',');
                 let userFunction = getCachedFunction(cacheKey);
                 if (!userFunction) {
-                    userFunction = new AsyncFunction('msg', ...moduleVars, code);
+                    userFunction = new AsyncFunction('msg', 'node', 'flow', 'global', 'context', ...moduleVars, code);
                     setCachedFunction(cacheKey, userFunction);
                 }
 
                 const execStart = process.hrtime.bigint();
-                const rawResult = await userFunction(restoredMsg, ...moduleValues);
+                const rawResult = await userFunction(restoredMsg, nodeProxy, flowProxy, globalProxy, contextProxy, ...moduleValues);
                 const executionMs = hrtimeDiffToMs(execStart);
 
                 const encodeStart = process.hrtime.bigint();
-                const encodedResult = await serializer.sanitizeMessage(rawResult, null, taskId);
+                const bufferCache = new WeakMap();
+                const encodedResult = await serializer.sanitizeMessage(rawResult, null, taskId, {
+                    transferMode,
+                    bufferCache
+                });
+                const hasUpdates = (
+                    Object.keys(contextUpdates.flow).length > 0 ||
+                    Object.keys(contextUpdates.global).length > 0 ||
+                    Object.keys(contextUpdates.context).length > 0
+                );
+                const encodedContextUpdates = hasUpdates
+                    ? await serializer.sanitizeMessage(contextUpdates, null, taskId, { transferMode, bufferCache })
+                    : null;
                 const transferToMainMs = hrtimeDiffToMs(encodeStart);
 
                 sendMessage({
                     type: 'result',
                     taskId,
                     result: encodedResult,
+                    contextUpdates: encodedContextUpdates,
+                    logs: logs.length > 0 ? logs : null,
                     performance: {
                         transferToWorkerMs,
                         executionMs,
@@ -219,7 +368,32 @@ process.on('message', async (data) => {
                     }
                 });
             } catch (err) {
-                sendError(taskId, err);
+                let encodedContextUpdates = null;
+                const hasUpdates = (
+                    Object.keys(contextUpdates.flow).length > 0 ||
+                    Object.keys(contextUpdates.global).length > 0 ||
+                    Object.keys(contextUpdates.context).length > 0
+                );
+                if (hasUpdates) {
+                    try {
+                        encodedContextUpdates = await serializer.sanitizeMessage(contextUpdates, null, taskId, { transferMode });
+                    } catch (_encodeErr) {
+                        encodedContextUpdates = null;
+                    }
+                }
+
+                const error = err instanceof Error ? err : new Error(String(err));
+                sendMessage({
+                    type: 'error',
+                    taskId,
+                    error: {
+                        message: error.message,
+                        stack: error.stack || '',
+                        name: error.name || 'Error'
+                    },
+                    contextUpdates: encodedContextUpdates,
+                    logs: logs.length > 0 ? logs : null
+                });
             }
         });
     } else if (type === 'terminate') {

package/nodes/lib/message-serializer.js

@@ -10,6 +10,50 @@
 
 const SHARED_SENTINEL_KEY = '__rosepetal_shm_path__';
 const SHARED_BASE64_KEY = '__rosepetal_base64__';
+const TRANSFER_SENTINEL_KEY = '__rosepetal_transfer_ab__';
+
+function canTransferBuffer(value) {
+    if (!Buffer.isBuffer(value)) {
+        return false;
+    }
+
+    if (!value.buffer || !(value.buffer instanceof ArrayBuffer)) {
+        return false;
+    }
+
+    // Avoid detaching pooled/sliced buffers that share backing stores
+    if (value.byteOffset !== 0) {
+        return false;
+    }
+
+    if (value.byteLength !== value.buffer.byteLength) {
+        return false;
+    }
+
+    return true;
+}
+
+function createTransferDescriptor(value, transferList, transferSet) {
+    if (!transferList) {
+        return null;
+    }
+
+    if (!canTransferBuffer(value)) {
+        return null;
+    }
+
+    const arrayBuffer = value.buffer;
+    if (transferSet && !transferSet.has(arrayBuffer)) {
+        transferSet.add(arrayBuffer);
+        transferList.push(arrayBuffer);
+    }
+
+    return {
+        [TRANSFER_SENTINEL_KEY]: arrayBuffer,
+        byteOffset: value.byteOffset,
+        byteLength: value.byteLength
+    };
+}
 
 /**
  * Async Message Serializer Class
@@ -31,18 +75,29 @@ class AsyncMessageSerializer {
      * @param {object} msg - Message object to sanitize
      * @param {object} node - Node-RED node instance (for warnings)
      * @param {number|string} taskId - Task identifier for shared memory tracking
+     * @param {object} options - Optional serialization options
      * @returns {Promise<object>} Sanitized message object
      */
-    async sanitizeMessage(msg, node, taskId) {
+    async sanitizeMessage(msg, node, taskId, options = {}) {
         if (!msg || typeof msg !== 'object') {
             return msg;
         }
 
         const seen = new WeakMap();
         const bufferIndex = { value: 0 }; // Mutable counter for buffer indexing
+        const transferMode = typeof options.transferMode === 'string' ? options.transferMode : 'shared';
+        const transferList = Array.isArray(options.transferList) ? options.transferList : null;
+        const transferSet = options.transferSet || (transferList ? new Set() : null);
+        const bufferCache = options.bufferCache || new WeakMap();
+        const cloneOptions = {
+            transferMode,
+            transferList,
+            transferSet,
+            bufferCache
+        };
 
         try {
-            return await this.cloneValue(msg, seen, bufferIndex, taskId, 0);
+            return await this.cloneValue(msg, seen, bufferIndex, taskId, 0, cloneOptions);
         } catch (err) {
             if (node) {
                 node.warn(`Message cloning failed: ${err.message}, creating minimal message`);
@@ -58,11 +113,10 @@ class AsyncMessageSerializer {
      * @param {number} depth - Current recursion depth
      * @param {object} bufferIndex - Mutable buffer index counter
      * @param {number|string} taskId - Task identifier
-     * @param {object} node - Node-RED node instance
-     * @param {string} path - Current property path (for warnings)
+     * @param {object} options - Serialization options
      * @returns {Promise<*>} Cloned value
      */
-    async cloneValue(value, seen, bufferIndex, taskId, depth) {
+    async cloneValue(value, seen, bufferIndex, taskId, depth, options) {
         // Optional depth guard (disabled by default for speed)
         if (this.maxDepth > 0 && depth > this.maxDepth) {
             return null;
@@ -83,14 +137,74 @@ class AsyncMessageSerializer {
             return undefined;
         }
 
-        // Buffers + typed arrays: offload to shared memory when above threshold
+        // Buffers + typed arrays: transfer, inline copy, or shared memory
         if (Buffer.isBuffer(value)) {
-            return await this.shmManager.writeBuffer(value, taskId, bufferIndex.value++);
+            if (options && options.bufferCache && options.bufferCache.has(value)) {
+                return options.bufferCache.get(value);
+            }
+
+            if (options && options.transferMode === 'copy') {
+                if (options.bufferCache) {
+                    options.bufferCache.set(value, value);
+                }
+                return value;
+            }
+
+            if (options && options.transferMode === 'transfer' && options.transferList) {
+                const transferDescriptor = createTransferDescriptor(value, options.transferList, options.transferSet);
+                if (transferDescriptor) {
+                    if (options.bufferCache) {
+                        options.bufferCache.set(value, transferDescriptor);
+                    }
+                    return transferDescriptor;
+                }
+
+                if (options.bufferCache) {
+                    options.bufferCache.set(value, value);
+                }
+                return value;
+            }
+
+            const sharedDescriptor = await this.shmManager.writeBuffer(value, taskId, bufferIndex.value++);
+            if (options && options.bufferCache) {
+                options.bufferCache.set(value, sharedDescriptor);
+            }
+            return sharedDescriptor;
         }
 
         if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
             const asBuffer = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
-            return await this.shmManager.writeBuffer(asBuffer, taskId, bufferIndex.value++);
+            if (options && options.bufferCache && options.bufferCache.has(asBuffer)) {
+                return options.bufferCache.get(asBuffer);
+            }
+
+            if (options && options.transferMode === 'copy') {
+                if (options.bufferCache) {
+                    options.bufferCache.set(asBuffer, asBuffer);
+                }
+                return asBuffer;
+            }
+
+            if (options && options.transferMode === 'transfer' && options.transferList) {
+                const transferDescriptor = createTransferDescriptor(asBuffer, options.transferList, options.transferSet);
+                if (transferDescriptor) {
+                    if (options.bufferCache) {
+                        options.bufferCache.set(asBuffer, transferDescriptor);
+                    }
+                    return transferDescriptor;
+                }
+
+                if (options.bufferCache) {
+                    options.bufferCache.set(asBuffer, asBuffer);
+                }
+                return asBuffer;
+            }
+
+            const sharedDescriptor = await this.shmManager.writeBuffer(asBuffer, taskId, bufferIndex.value++);
+            if (options && options.bufferCache) {
+                options.bufferCache.set(asBuffer, sharedDescriptor);
+            }
+            return sharedDescriptor;
         }
 
         if (type === 'object') {
@@ -104,7 +218,7 @@ class AsyncMessageSerializer {
 
             if (Array.isArray(value)) {
                 for (let i = 0; i < value.length; i++) {
-                    const clonedItem = await this.cloneValue(value[i], seen, bufferIndex, taskId, depth + 1);
+                    const clonedItem = await this.cloneValue(value[i], seen, bufferIndex, taskId, depth + 1, options);
                     clone[i] = clonedItem === undefined ? null : clonedItem;
                 }
                 return clone;
@@ -113,7 +227,7 @@ class AsyncMessageSerializer {
             const keys = Object.keys(value);
             for (let i = 0; i < keys.length; i++) {
                 const key = keys[i];
-                const clonedVal = await this.cloneValue(value[key], seen, bufferIndex, taskId, depth + 1);
+                const clonedVal = await this.cloneValue(value[key], seen, bufferIndex, taskId, depth + 1, options);
                 if (clonedVal !== undefined) {
                     clone[key] = clonedVal;
                 }
@@ -132,10 +246,11 @@ class AsyncMessageSerializer {
      */
     async restoreBuffers(value) {
         const seen = new WeakMap();
-        return this.restoreValue(value, seen);
+        const descriptorCache = new WeakMap();
+        return this.restoreValue(value, seen, descriptorCache);
     }
 
-    async restoreValue(value, seen) {
+    async restoreValue(value, seen, descriptorCache) {
         // Handle null/undefined
         if (value === null || value === undefined) {
             return value;
@@ -162,7 +277,7 @@ class AsyncMessageSerializer {
             seen.set(value, result);
 
             for (let i = 0; i < value.length; i++) {
-                result[i] = await this.restoreValue(value[i], seen);
+                result[i] = await this.restoreValue(value[i], seen, descriptorCache);
             }
 
             return result;
@@ -170,10 +285,42 @@ class AsyncMessageSerializer {
 
         // Handle objects
         if (type === 'object') {
+            // Transfer-list descriptor
+            if (Object.prototype.hasOwnProperty.call(value, TRANSFER_SENTINEL_KEY)) {
+                if (descriptorCache && descriptorCache.has(value)) {
+                    return descriptorCache.get(value);
+                }
+
+                try {
+                    const arrayBuffer = value[TRANSFER_SENTINEL_KEY];
+                    if (!(arrayBuffer instanceof ArrayBuffer)) {
+                        return Buffer.alloc(0);
+                    }
+
+                    const byteOffset = Number(value.byteOffset) || 0;
+                    const byteLength = Number(value.byteLength) || arrayBuffer.byteLength;
+                    const buffer = Buffer.from(arrayBuffer, byteOffset, byteLength);
+                    if (descriptorCache) {
+                        descriptorCache.set(value, buffer);
+                    }
+                    return buffer;
+                } catch (_err) {
+                    return Buffer.alloc(0);
+                }
+            }
+
             // Shared memory descriptor
             if (Object.prototype.hasOwnProperty.call(value, SHARED_SENTINEL_KEY)) {
+                if (descriptorCache && descriptorCache.has(value)) {
+                    return descriptorCache.get(value);
+                }
+
                 try {
-                    return await this.shmManager.readBuffer(value, { deleteAfterRead: true });
+                    const buffer = await this.shmManager.readBuffer(value, { deleteAfterRead: true });
+                    if (descriptorCache) {
+                        descriptorCache.set(value, buffer);
+                    }
+                    return buffer;
                 } catch (_err) {
                     return Buffer.alloc(0);
                 }
@@ -181,8 +328,16 @@ class AsyncMessageSerializer {
 
             // Base64 fallback
             if (Object.prototype.hasOwnProperty.call(value, SHARED_BASE64_KEY)) {
+                if (descriptorCache && descriptorCache.has(value)) {
+                    return descriptorCache.get(value);
+                }
+
                 try {
-                    return Buffer.from(value[SHARED_BASE64_KEY] || '', 'base64');
+                    const buffer = Buffer.from(value[SHARED_BASE64_KEY] || '', 'base64');
+                    if (descriptorCache) {
+                        descriptorCache.set(value, buffer);
+                    }
+                    return buffer;
                 } catch (_err) {
                     return Buffer.alloc(0);
                 }
@@ -198,7 +353,7 @@ class AsyncMessageSerializer {
             const entries = Object.entries(value);
             for (let i = 0; i < entries.length; i++) {
                 const [key, val] = entries[i];
-                result[key] = await this.restoreValue(val, seen);
+                result[key] = await this.restoreValue(val, seen, descriptorCache);
             }
 
             return result;