@depup/webpack 5.106.0-depup.0 → 5.109.0-depup.0

package/lib/serialization/DateObjectSerializer.js

@@ -4,11 +4,12 @@
 
 "use strict";
 
-/** @typedef {import("./ObjectMiddleware").ObjectDeserializerContext} ObjectDeserializerContext */
-/** @typedef {import("./ObjectMiddleware").ObjectSerializerContext} ObjectSerializerContext */
+/** @typedef {import("./ObjectMiddleware").ObjectDeserializerContext<[number]>} ObjectDeserializerContext */
+/** @typedef {import("./ObjectMiddleware").ObjectSerializerContext<[number]>} ObjectSerializerContext */
 
 class DateObjectSerializer {
 	/**
+	 * Serializes this instance into the provided serializer context.
 	 * @param {Date} obj date
 	 * @param {ObjectSerializerContext} context context
 	 */
@@ -17,6 +18,7 @@ class DateObjectSerializer {
 	}
 
 	/**
+	 * Restores this instance from the provided deserializer context.
 	 * @param {ObjectDeserializerContext} context context
 	 * @returns {Date} date
 	 */

package/lib/serialization/ErrorObjectSerializer.js

@@ -4,13 +4,15 @@
 
 "use strict";
 
-/** @typedef {import("./ObjectMiddleware").ObjectDeserializerContext} ObjectDeserializerContext */
-/** @typedef {import("./ObjectMiddleware").ObjectSerializerContext} ObjectSerializerContext */
+/** @typedef {import("./types").ComplexSerializableType} ComplexSerializableType */
+/** @typedef {import("./ObjectMiddleware").ObjectDeserializerContext<ComplexSerializableType[]>} ObjectDeserializerContext */
+/** @typedef {import("./ObjectMiddleware").ObjectSerializerContext<ComplexSerializableType[]>} ObjectSerializerContext */
 
 /** @typedef {Error & { cause?: unknown }} ErrorWithCause */
 
 class ErrorObjectSerializer {
 	/**
+	 * Creates an instance of ErrorObjectSerializer.
 	 * @param {ErrorConstructor | EvalErrorConstructor | RangeErrorConstructor | ReferenceErrorConstructor | SyntaxErrorConstructor | TypeErrorConstructor} Type error type
 	 */
 	constructor(Type) {
@@ -18,6 +20,7 @@ class ErrorObjectSerializer {
 	}
 
 	/**
+	 * Serializes this instance into the provided serializer context.
 	 * @param {Error | EvalError | RangeError | ReferenceError | SyntaxError | TypeError} obj error
 	 * @param {ObjectSerializerContext} context context
 	 */
@@ -25,20 +28,21 @@ class ErrorObjectSerializer {
 		context.write(obj.message);
 		context.write(obj.stack);
 		context.write(
-			/** @type {ErrorWithCause} */
-			(obj).cause
+			/** @type {ComplexSerializableType} */
+			(/** @type {ErrorWithCause} */ (obj).cause)
 		);
 	}
 
 	/**
+	 * Restores this instance from the provided deserializer context.
 	 * @param {ObjectDeserializerContext} context context
 	 * @returns {Error | EvalError | RangeError | ReferenceError | SyntaxError | TypeError} error
 	 */
 	deserialize(context) {
 		const err = new this.Type();
 
-		err.message = context.read();
-		err.stack = context.read();
+		err.message = /** @type {string} */ (context.read());
+		err.stack = /** @type {string | undefined} */ (context.read());
 		/** @type {ErrorWithCause} */
 		(err).cause = context.read();
 

package/lib/serialization/FileMiddleware.js

@@ -13,7 +13,12 @@ const {
 	// eslint-disable-next-line n/no-unsupported-features/node-builtins
 	createBrotliDecompress,
 	createGunzip,
-	createGzip
+	createGzip,
+	// zstd is only available on Node.js >= 22.15; guarded at use sites
+	// eslint-disable-next-line n/no-unsupported-features/node-builtins
+	createZstdCompress,
+	// eslint-disable-next-line n/no-unsupported-features/node-builtins
+	createZstdDecompress
 } = require("zlib");
 const { DEFAULTS } = require("../config/defaults");
 const createHash = require("../util/createHash");
@@ -48,6 +53,7 @@ const WRITE_LIMIT_TOTAL = 0x7fff0000;
 const WRITE_LIMIT_CHUNK = 511 * 1024 * 1024;
 
 /**
+ * Returns hash.
  * @param {Buffer[]} buffers buffers
  * @param {HashFunction} hashFunction hash function to use
  * @returns {string} hash
@@ -85,6 +91,7 @@ const readUInt64LE = Buffer.prototype.readBigUInt64LE
 /** @typedef {Promise<void | void[]>} BackgroundJob */
 
 /**
+ * Defines the serialize result type used by this module.
  * @typedef {object} SerializeResult
  * @property {string | false} name
  * @property {number} size
@@ -93,10 +100,12 @@ const readUInt64LE = Buffer.prototype.readBigUInt64LE
 
 /** @typedef {{ name: string, size: number }} LazyOptions */
 /**
+ * Defines the lazy function type used by this module.
  * @typedef {import("./SerializerMiddleware").LazyFunction<BufferSerializableType[], Buffer, FileMiddleware, LazyOptions>} LazyFunction
  */
 
 /**
+ * Serializes this instance into the provided serializer context.
  * @param {FileMiddleware} middleware this
  * @param {(BufferSerializableType | LazyFunction)[]} data data to be serialized
  * @param {string | boolean} name file base name
@@ -243,6 +252,7 @@ const serialize = async (
 };
 
 /**
+ * Restores this instance from the provided deserializer context.
  * @param {FileMiddleware} middleware this
  * @param {string | false} name filename
  * @param {(name: string | false) => Promise<Buffer[]>} readFile read content of a file
@@ -263,6 +273,7 @@ const deserialize = async (middleware, name, readFile) => {
 		contentPosition = 0;
 	};
 	/**
+	 * Processes the provided n.
 	 * @param {number} n number of bytes to ensure
 	 */
 	const ensureData = (n) => {
@@ -294,6 +305,7 @@ const deserialize = async (middleware, name, readFile) => {
 		}
 	};
 	/**
+	 * Returns value value.
 	 * @returns {number} value value
 	 */
 	const readUInt32LE = () => {
@@ -303,6 +315,7 @@ const deserialize = async (middleware, name, readFile) => {
 		return value;
 	};
 	/**
+	 * Returns value value.
 	 * @returns {number} value value
 	 */
 	const readInt32LE = () => {
@@ -312,6 +325,7 @@ const deserialize = async (middleware, name, readFile) => {
 		return value;
 	};
 	/**
+	 * Returns buffer.
 	 * @param {number} l length
 	 * @returns {Buffer} buffer
 	 */
@@ -369,9 +383,13 @@ const deserialize = async (middleware, name, readFile) => {
 				);
 			result.push(lazy);
 		} else {
+			// A section may start exactly at a content-buffer boundary; advance
+			// first, then read from the fresh buffer (don't fall through to the
+			// `while` below, which would skip it).
 			if (contentPosition === contentItemLength) {
 				nextContent();
-			} else if (contentPosition !== 0) {
+			}
+			if (contentPosition !== 0) {
 				if (length <= contentItemLength - contentPosition) {
 					result.push(
 						Buffer.from(
@@ -429,10 +447,12 @@ const deserialize = async (middleware, name, readFile) => {
 /** @typedef {{ filename: string, extension?: string }} Context */
 
 /**
+ * Represents FileMiddleware.
  * @extends {SerializerMiddleware<DeserializedType, SerializedType, Context>}
  */
 class FileMiddleware extends SerializerMiddleware {
 	/**
+	 * Creates an instance of FileMiddleware.
 	 * @param {IntermediateFileSystem} fs filesystem
 	 * @param {HashFunction} hashFunction hash function to use
 	 */
@@ -445,6 +465,7 @@ class FileMiddleware extends SerializerMiddleware {
 	}
 
 	/**
+	 * Serializes this instance into the provided serializer context.
 	 * @param {DeserializedType} data data
 	 * @param {Context} context context object
 	 * @returns {SerializedType | Promise<SerializedType> | null} serialized data
@@ -460,6 +481,7 @@ class FileMiddleware extends SerializerMiddleware {
 				/** @type {Set<string>} */
 				const allWrittenFiles = new Set();
 				/**
+				 * Processes the provided name.
 				 * @param {string | false} name name
 				 * @param {Buffer[]} content content
 				 * @param {number} size size
@@ -471,12 +493,13 @@ class FileMiddleware extends SerializerMiddleware {
 						: filename;
 					await new Promise(
 						/**
+						 * Handles the callback logic for this hook.
 						 * @param {(value?: undefined) => void} resolve resolve
 						 * @param {(reason?: Error | null) => void} reject reject
 						 */
 						(resolve, reject) => {
 							let stream = this.fs.createWriteStream(`${file}_`);
-							/** @type {undefined | import("zlib").Gzip | import("zlib").BrotliCompress} */
+							/** @type {undefined | import("zlib").Gzip | import("zlib").BrotliCompress | import("zlib").ZstdCompress} */
 							let compression;
 							if (file.endsWith(".gz")) {
 								compression = createGzip({
@@ -493,6 +516,17 @@ class FileMiddleware extends SerializerMiddleware {
 										[zConstants.BROTLI_PARAM_SIZE_HINT]: size
 									}
 								});
+							} else if (file.endsWith(".zst")) {
+								// eslint-disable-next-line n/no-unsupported-features/node-builtins
+								const levelParam = zConstants.ZSTD_c_compressionLevel;
+								// default level 3; some runtimes (e.g. Deno) don't expose ZSTD_CLEVEL_DEFAULT
+								// eslint-disable-next-line n/no-unsupported-features/node-builtins
+								const defaultLevel = zConstants.ZSTD_CLEVEL_DEFAULT;
+								const level = defaultLevel === undefined ? 3 : defaultLevel;
+								compression = createZstdCompress({
+									chunkSize: COMPRESSION_CHUNK_SIZE,
+									params: { [levelParam]: level }
+								});
 							}
 							if (compression) {
 								pipeline(compression, stream, reject);
@@ -518,6 +552,7 @@ class FileMiddleware extends SerializerMiddleware {
 							const len = chunks.length;
 							let i = 0;
 							/**
+							 * Processes the provided err.
 							 * @param {(Error | null)=} err err
 							 */
 							const batchWrite = (err) => {
@@ -557,6 +592,7 @@ class FileMiddleware extends SerializerMiddleware {
 							// Rename the index file to disallow access during inconsistent file state
 							await new Promise(
 								/**
+								 * Handles the callback logic for this hook.
 								 * @param {(value?: undefined) => void} resolve resolve
 								 */
 								(resolve) => {
@@ -573,6 +609,7 @@ class FileMiddleware extends SerializerMiddleware {
 									(file) =>
 										new Promise(
 											/**
+											 * Handles the callback logic for this hook.
 											 * @param {(value?: undefined) => void} resolve resolve
 											 * @param {(reason?: Error | null) => void} reject reject
 											 * @returns {void}
@@ -590,6 +627,7 @@ class FileMiddleware extends SerializerMiddleware {
 							// As final step automatically update the index file to have a consistent pack again
 							await new Promise(
 								/**
+								 * Handles the callback logic for this hook.
 								 * @param {(value?: undefined) => void} resolve resolve
 								 * @returns {void}
 								 */
@@ -609,6 +647,7 @@ class FileMiddleware extends SerializerMiddleware {
 	}
 
 	/**
+	 * Restores this instance from the provided deserializer context.
 	 * @param {SerializedType} data data
 	 * @param {Context} context context object
 	 * @returns {DeserializedType | Promise<DeserializedType>} deserialized data
@@ -616,6 +655,7 @@ class FileMiddleware extends SerializerMiddleware {
 	deserialize(data, context) {
 		const { filename, extension = "" } = context;
 		/**
+		 * Returns result.
 		 * @param {string | boolean} name name
 		 * @returns {Promise<Buffer[]>} result
 		 */
@@ -646,6 +686,10 @@ class FileMiddleware extends SerializerMiddleware {
 						decompression = createBrotliDecompress({
 							chunkSize: DECOMPRESSION_CHUNK_SIZE
 						});
+					} else if (file.endsWith(".zst")) {
+						decompression = createZstdDecompress({
+							chunkSize: DECOMPRESSION_CHUNK_SIZE
+						});
 					}
 					if (decompression) {
 						/** @typedef {(value: Buffer[] | PromiseLike<Buffer[]>) => void} NewResolve */
@@ -663,6 +707,7 @@ class FileMiddleware extends SerializerMiddleware {
 								}),
 								new Promise(
 									/**
+									 * Handles the chunk size callback for this hook.
 									 * @param {(value?: undefined) => void} resolve resolve
 									 * @param {(reason?: Error) => void} reject reject
 									 */
@@ -764,3 +809,5 @@ class FileMiddleware extends SerializerMiddleware {
 }
 
 module.exports = FileMiddleware;
+// Exposed for testing the content-buffer boundary handling in `deserialize`.
+module.exports._deserialize = deserialize;

package/lib/serialization/MapObjectSerializer.js

@@ -4,14 +4,12 @@
 
 "use strict";
 
-/** @typedef {import("./ObjectMiddleware").ObjectDeserializerContext} ObjectDeserializerContext */
-/** @typedef {import("./ObjectMiddleware").ObjectSerializerContext} ObjectSerializerContext */
-
 class MapObjectSerializer {
 	/**
+	 * Serializes this instance into the provided serializer context.
 	 * @template K, V
 	 * @param {Map<K, V>} obj map
-	 * @param {ObjectSerializerContext} context context
+	 * @param {import("./ObjectMiddleware").ObjectSerializerContext<(number | K | V)[]>} context context
 	 */
 	serialize(obj, context) {
 		context.write(obj.size);
@@ -24,22 +22,22 @@ class MapObjectSerializer {
 	}
 
 	/**
+	 * Restores this instance from the provided deserializer context.
 	 * @template K, V
-	 * @param {ObjectDeserializerContext} context context
+	 * @param {import("./ObjectMiddleware").ObjectDeserializerContext<(number | K | V)[]>} context context
 	 * @returns {Map<K, V>} map
 	 */
 	deserialize(context) {
-		/** @type {number} */
-		const size = context.read();
+		const size = /** @type {number} */ (context.read());
 		/** @type {Map<K, V>} */
 		const map = new Map();
 		/** @type {K[]} */
 		const keys = [];
 		for (let i = 0; i < size; i++) {
-			keys.push(context.read());
+			keys.push(/** @type {K} */ (context.read()));
 		}
 		for (let i = 0; i < size; i++) {
-			map.set(keys[i], context.read());
+			map.set(keys[i], /** @type {V} */ (context.read()));
 		}
 		return map;
 	}

package/lib/serialization/NullPrototypeObjectSerializer.js

@@ -4,16 +4,14 @@
 
 "use strict";
 
-/** @typedef {import("./ObjectMiddleware").ObjectDeserializerContext} ObjectDeserializerContext */
-/** @typedef {import("./ObjectMiddleware").ObjectSerializerContext} ObjectSerializerContext */
-
 /** @typedef {string[]} Keys */
 
 class NullPrototypeObjectSerializer {
 	/**
+	 * Serializes this instance into the provided serializer context.
 	 * @template {object} T
 	 * @param {T} obj null object
-	 * @param {ObjectSerializerContext} context context
+	 * @param {import("./ObjectMiddleware").ObjectSerializerContext<(string | null | T[keyof T])[]>} context context
 	 */
 	serialize(obj, context) {
 		/** @type {Keys} */
@@ -28,8 +26,9 @@ class NullPrototypeObjectSerializer {
 	}
 
 	/**
+	 * Restores this instance from the provided deserializer context.
 	 * @template {object} T
-	 * @param {ObjectDeserializerContext} context context
+	 * @param {import("./ObjectMiddleware").ObjectDeserializerContext<(string | null | T[keyof T])[]>} context context
 	 * @returns {T} null object
 	 */
 	deserialize(context) {
@@ -37,14 +36,15 @@ class NullPrototypeObjectSerializer {
 		const obj = Object.create(null);
 		/** @type {Keys} */
 		const keys = [];
-		/** @type {Keys[number] | null} */
-		let key = context.read();
+		let key = /** @type {string | null} */ (context.read());
 		while (key !== null) {
 			keys.push(key);
-			key = context.read();
+			key = /** @type {string | null} */ (context.read());
 		}
 		for (const key of keys) {
-			obj[/** @type {keyof T} */ (key)] = context.read();
+			obj[/** @type {keyof T} */ (key)] = /** @type {T[keyof T]} */ (
+				context.read()
+			);
 		}
 		return obj;
 	}

package/lib/serialization/ObjectMiddleware.js

@@ -48,6 +48,7 @@ Technically any value can be used.
 */
 
 /**
+ * Defines the object serializer snapshot type used by this module.
  * @typedef {object} ObjectSerializerSnapshot
  * @property {number} length
  * @property {number} cycleStackSize
@@ -60,8 +61,23 @@ Technically any value can be used.
 /** @typedef {EXPECTED_OBJECT | string} ReferenceableItem */
 
 /**
+ * First tuple element; element type for an open array; `EXPECTED_ANY` once exhausted.
+ * @template {readonly EXPECTED_ANY[]} T
+ * @typedef {T extends readonly [infer H, ...EXPECTED_ANY[]] ? H : T extends readonly [] ? EXPECTED_ANY : T extends readonly (infer E)[] ? E : never} Head
+ */
+
+/**
+ * Tuple without its first element; unchanged when `T` is an open array.
+ * @template {readonly EXPECTED_ANY[]} T
+ * @typedef {T extends readonly [EXPECTED_ANY, ...infer R] ? R : T} Tail
+ */
+
+/**
+ * Defines the object serializer context type used by this module.
+ * `T` is the tuple of values written in order; each `write` consumes the head.
+ * @template {readonly EXPECTED_ANY[]} [T=readonly EXPECTED_ANY[]]
  * @typedef {object} ObjectSerializerContext
- * @property {(value: EXPECTED_ANY) => void} write
+ * @property {(value: Head<T>) => ObjectSerializerContext<Tail<T>>} write
  * @property {(value: ReferenceableItem) => void} setCircularReference
  * @property {() => ObjectSerializerSnapshot} snapshot
  * @property {(snapshot: ObjectSerializerSnapshot) => void} rollback
@@ -70,18 +86,25 @@ Technically any value can be used.
  */
 
 /**
+ * Defines the object deserializer context type used by this module.
+ * `T` is the tuple of values read in order: `read` returns the head, and `rest`
+ * re-types the same context to `Tail<T>` so successive reads stay positional.
+ * @template {readonly EXPECTED_ANY[]} [T=readonly EXPECTED_ANY[]]
  * @typedef {object} ObjectDeserializerContext
- * @property {() => EXPECTED_ANY} read
+ * @property {() => Head<T>} read
+ * @property {ObjectDeserializerContext<Tail<T>>} rest
  * @property {(value: ReferenceableItem) => void} setCircularReference
  */
 
 /**
+ * Defines the object serializer type used by this module.
  * @typedef {object} ObjectSerializer
- * @property {(value: EXPECTED_ANY, context: ObjectSerializerContext) => void} serialize
- * @property {(context: ObjectDeserializerContext) => EXPECTED_ANY} deserialize
+ * @property {(value: EXPECTED_ANY, context: ObjectSerializerContext<EXPECTED_ANY>) => void} serialize
+ * @property {(context: ObjectDeserializerContext<EXPECTED_ANY>) => EXPECTED_ANY} deserialize
  */
 
 /**
+ * Updates set size using the provided set.
  * @template T
  * @param {Set<T>} set set
  * @param {number} size count of items to keep
@@ -96,6 +119,7 @@ const setSetSize = (set, size) => {
 };
 
 /**
+ * Updates map size using the provided map.
  * @template K, X
  * @param {Map<K, X>} map map
  * @param {number} size count of items to keep
@@ -110,6 +134,7 @@ const setMapSize = (map, size) => {
 };
 
 /**
+ * Returns hash.
  * @param {Buffer} buffer buffer
  * @param {HashFunction} hashFunction hash function to use
  * @returns {string} hash
@@ -207,13 +232,15 @@ const loaders = new Map();
 /** @typedef {PrimitiveSerializableType[]} SerializedType */
 /** @typedef {{ logger: Logger }} Context */
 
-/** @typedef {(context: ObjectSerializerContext | ObjectDeserializerContext) => void} ExtendContext */
+/** @typedef {(context: ObjectSerializerContext<EXPECTED_ANY> | ObjectDeserializerContext<EXPECTED_ANY>) => void} ExtendContext */
 
 /**
+ * Represents ObjectMiddleware.
  * @extends {SerializerMiddleware<DeserializedType, SerializedType, Context>}
  */
 class ObjectMiddleware extends SerializerMiddleware {
 	/**
+	 * Creates an instance of ObjectMiddleware.
 	 * @param {ExtendContext} extendContext context extensions
 	 * @param {HashFunction} hashFunction hash function to use
 	 */
@@ -226,6 +253,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 	}
 
 	/**
+	 * Processes the provided reg exp.
 	 * @param {RegExp} regExp RegExp for which the request is tested
 	 * @param {(request: string) => boolean} loader loader to load the request, returns true when successful
 	 * @returns {void}
@@ -235,6 +263,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 	}
 
 	/**
+	 * Processes the provided constructor.
 	 * @param {Constructor} Constructor the constructor
 	 * @param {string} request the request which will be required when deserializing
 	 * @param {string | null} name the name to make multiple serializer unique when sharing a request
@@ -266,6 +295,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 	}
 
 	/**
+	 * Register not serializable.
 	 * @param {Constructor} Constructor the constructor
 	 * @returns {void}
 	 */
@@ -280,6 +310,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 	}
 
 	/**
+	 * Gets serializer for.
 	 * @param {EXPECTED_ANY} object for serialization
 	 * @returns {SerializerConfigWithSerializer} Serializer config
 	 */
@@ -311,6 +342,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 	}
 
 	/**
+	 * Gets deserializer for.
 	 * @param {string} request request
 	 * @param {string} name name
 	 * @returns {ObjectSerializer} serializer
@@ -327,6 +359,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 	}
 
 	/**
+	 * Get deserializer for without error.
 	 * @param {string} request request
 	 * @param {string} name name
 	 * @returns {ObjectSerializer | undefined} serializer
@@ -338,6 +371,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 	}
 
 	/**
+	 * Serializes this instance into the provided serializer context.
 	 * @param {DeserializedType} data data
 	 * @param {Context} context context object
 	 * @returns {SerializedType | Promise<SerializedType> | null} serialized data
@@ -349,6 +383,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 		/** @type {Map<ReferenceableItem, number>} */
 		let referenceable = new Map();
 		/**
+		 * Adds referenceable.
 		 * @param {ReferenceableItem} item referenceable item
 		 */
 		const addReferenceable = (item) => {
@@ -357,6 +392,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 		/** @type {Map<number, Buffer | [Buffer, Buffer] | Map<string, Buffer>>} */
 		let bufferDedupeMap = new Map();
 		/**
+		 * Returns deduped buffer.
 		 * @param {Buffer} buf buffer
 		 * @returns {Buffer} deduped buffer
 		 */
@@ -426,6 +462,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 		/** @type {Set<ComplexSerializableType>} */
 		const cycleStack = new Set();
 		/**
+		 * Returns stack.
 		 * @param {ComplexSerializableType} item item to stack
 		 * @returns {string} stack
 		 */
@@ -487,11 +524,11 @@ class ObjectMiddleware extends SerializerMiddleware {
 		};
 		/** @type {undefined | WeakSet<Error>} */
 		let hasDebugInfoAttached;
-		/** @type {ObjectSerializerContext} */
+		/** @type {ObjectSerializerContext<EXPECTED_ANY>} */
 		let ctx = {
 			write(value) {
 				try {
-					process(value);
+					process(/** @type {ComplexSerializableType} */ (value));
 				} catch (err) {
 					if (err !== NOT_SERIALIZABLE) {
 						if (hasDebugInfoAttached === undefined) {
@@ -499,12 +536,14 @@ class ObjectMiddleware extends SerializerMiddleware {
 						}
 						if (!hasDebugInfoAttached.has(/** @type {Error} */ (err))) {
 							/** @type {Error} */
-							(err).message += `\nwhile serializing ${stackToString(value)}`;
+							(err).message +=
+								`\nwhile serializing ${stackToString(/** @type {ComplexSerializableType} */ (value))}`;
 							hasDebugInfoAttached.add(/** @type {Error} */ (err));
 						}
 					}
 					throw err;
 				}
+				return ctx;
 			},
 			setCircularReference(ref) {
 				addReferenceable(ref);
@@ -531,6 +570,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 		};
 		this.extendContext(ctx);
 		/**
+		 * Processes the provided item.
 		 * @param {ComplexSerializableType} item item to serialize
 		 */
 		const process = (item) => {
@@ -605,8 +645,19 @@ class ObjectMiddleware extends SerializerMiddleware {
 					// check if we can emit a reference
 					const ref = referenceable.get(item);
 					if (ref !== undefined) {
-						result.push(ESCAPE, ref - currentPos);
-						return;
+						const offset = ref - currentPos;
+						if (
+							// One far ref → 5 bytes (`null` + offset), one near ref -> 2/3 bytes
+							offset >= -32768 ||
+							// long enough that the ref wins, keep it
+							item.length >= 4 ||
+							// multibyte → inline would be even bigger, keep it
+							Buffer.byteLength(item) !== item.length
+						) {
+							// A back-reference is `null` + the offset.
+							result.push(ESCAPE, offset);
+							return;
+						}
 					}
 					addReferenceable(item);
 				}
@@ -681,6 +732,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 	}
 
 	/**
+	 * Restores this instance from the provided deserializer context.
 	 * @param {SerializedType} data data
 	 * @param {Context} context context object
 	 * @returns {DeserializedType | Promise<DeserializedType>} deserialized data
@@ -703,6 +755,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 		/** @type {ReferenceableItem[]} */
 		let referenceable = [];
 		/**
+		 * Adds referenceable.
 		 * @param {ReferenceableItem} item referenceable item
 		 */
 		const addReferenceable = (item) => {
@@ -714,10 +767,14 @@ class ObjectMiddleware extends SerializerMiddleware {
 		let objectTypeLookup = [];
 		/** @type {ComplexSerializableType[]} */
 		let result = [];
-		/** @type {ObjectDeserializerContext} */
+		/** @type {ObjectDeserializerContext<EXPECTED_ANY>} */
 		let ctx = {
 			read() {
-				return decodeValue();
+				return /** @type {EXPECTED_ANY} */ (decodeValue());
+			},
+			// type-only cursor advance; same object, retyped to the tuple tail
+			get rest() {
+				return ctx;
 			},
 			setCircularReference(ref) {
 				addReferenceable(ref);
@@ -726,6 +783,7 @@ class ObjectMiddleware extends SerializerMiddleware {
 		};
 		this.extendContext(ctx);
 		/**
+		 * Decodes the provided value.
 		 * @returns {ComplexSerializableType} deserialize value
 		 */
 		const decodeValue = () => {
@@ -836,7 +894,9 @@ class ObjectMiddleware extends SerializerMiddleware {
 				}
 
 				return item;
-			} else if (Buffer.isBuffer(item)) {
+			} else if (typeof item === "object") {
+				// Only non-null objects reach here (ESCAPE/null handled above), and
+				// the stream's only object type is Buffer — avoids a Buffer.isBuffer call
 				addReferenceable(item);
 
 				return item;