@zudojs/serialization 1.2.0 → 1.2.1

package/README.md

@@ -98,8 +98,11 @@ picked up.
 or `createSerializer`) to use only your registry. A value that no transformer
 handles and that JSON would write as `{}` (a `Map`, `Set`, `WeakMap`, `Error`,
 `RegExp`, `ArrayBuffer`, ...) then throws `SerializeError` under
-`preserveTypes` instead of being silently emptied. To compose a registry by
-hand, start from `createBuiltinTransformers()`.
+`preserveTypes` instead of being silently emptied. A type no built-in covers
+(`RegExp`, `WeakMap`, `ArrayBuffer`, `DataView`, ...) throws the same way with
+the built-ins on. The message names the fix: register a transformer, or, when
+a built-in handles the type and you turned them off, keep them enabled. To
+compose a registry by hand, start from `createBuiltinTransformers()`.
 
 ## Untrusted input
 
@@ -150,8 +153,19 @@ serializer.serialize({ error }, { preserveTypes: true }); // name, message, code
 serializer.serialize({ error }, { preserveTypes: true, includeStack: true });
 ```
 
-On the way back, a wire-supplied stack is attached as a non-enumerable
-`originalStack` rather than overwriting the reconstructed error's own.
+On the way back:
+
+- A built-in subclass (`TypeError`, `RangeError`, `SyntaxError`,
+  `ReferenceError`, `EvalError`, `URIError`, `AggregateError`) is rebuilt with
+  its own constructor, so `instanceof TypeError` still holds. Any other name
+  is rebuilt as a plain `Error` with `name` set. An `AggregateError` comes back
+  with an empty `errors` array, because the inner errors are not serialized.
+- `.stack` is only the header line (`"TypeError: bad input"`) with no frames.
+  The reader's own frames would point at the deserializer, not at where the
+  error was thrown.
+- A wire-supplied stack (sent with `includeStack`) is attached as a
+  non-enumerable `originalStack`. It never overwrites `.stack`, because it is
+  text the sender controls.
 
 ## Envelopes
 

package/dist/serializerTransformPolicy/transformerOutput.helper.d.ts

@@ -18,6 +18,9 @@ export declare function toTaggedOutput(transformer: TypeTransformer, raw: unknow
  * contents. Only reachable when the built-in transformers are disabled or
  * a type has no transformer.
  *
+ * Suggests re-enabling the built-ins only when one of them handles the
+ * type; otherwise the fix is registering a transformer.
+ *
  * @throws {SerializeError} naming the type and how to fix it.
  */
 export declare function assertNotLossy(value: object): void;

package/dist/serializerTransformPolicy/transformerOutput.helper.js

@@ -4,6 +4,7 @@
 import { SerializationTags } from "@zudojs/constants";
 import { SerializeError } from "@zudojs/errors";
 import { isPlainObject } from "@zudojs/types";
+import { createBuiltinTransformers, } from "./transformerLookup.core.js";
 /**
  * Normalises what a transformer's `serialize` returned into the tagged
  * `{ $type, $value }` form that is written to the wire.
@@ -37,21 +38,40 @@ const LOSSY_TYPES = [
     ["ArrayBuffer", (value) => value instanceof ArrayBuffer],
     ["DataView", (value) => value instanceof DataView],
 ];
+let builtins;
+/**
+ * Whether a built-in transformer handles `value`. When one does and the
+ * value still reached {@link assertNotLossy}, the built-ins were disabled.
+ */
+function hasBuiltinTransformer(value) {
+    builtins ??= createBuiltinTransformers();
+    return builtins.findForValue(value) !== undefined;
+}
+/** `"a Map"`, `"an Error"`. */
+function withArticle(name) {
+    return `${/^[AEIOU]/.test(name) ? "an" : "a"} ${name}`;
+}
 /**
  * Throws when a value that no transformer handles would be written as `{}`
  * (a `Map`, `Set`, `Error`, `RegExp`, ...), instead of silently losing its
  * contents. Only reachable when the built-in transformers are disabled or
  * a type has no transformer.
  *
+ * Suggests re-enabling the built-ins only when one of them handles the
+ * type; otherwise the fix is registering a transformer.
+ *
  * @throws {SerializeError} naming the type and how to fix it.
  */
 export function assertNotLossy(value) {
     for (const [name, matches] of LOSSY_TYPES) {
         if (matches(value)) {
-            throw new SerializeError(`Cannot serialize a ${name} with preserveTypes: no transformer is ` +
-                `registered for it, and JSON would write it as {} and lose its ` +
-                `contents. Register a transformer for ${name}, or keep the ` +
-                `built-in transformers enabled (do not pass builtins: false).`, { format: "json" });
+            const fix = hasBuiltinTransformer(value)
+                ? `Register a transformer for ${name}, or keep the built-in ` +
+                    `transformers enabled (do not pass builtins: false).`
+                : `Register a transformer for ${name}.`;
+            throw new SerializeError(`Cannot serialize ${withArticle(name)} with preserveTypes: no ` +
+                `transformer is registered for it, and JSON would write it as {} ` +
+                `and lose its contents. ${fix}`, { format: "json" });
         }
     }
 }

package/dist/serializerTransformsExt/error.transformer.js

@@ -9,6 +9,33 @@
  */
 import { SerializationTags } from "@zudojs/constants";
 const ERROR_TYPE = "Error";
+/**
+ * Built-in Error subclasses rebuilt with their own constructor, so a
+ * deserialized `TypeError` is still `instanceof TypeError`. Any other name
+ * falls back to `Error` with `name` set.
+ */
+const BUILT_IN_ERRORS = Object.freeze({
+    TypeError: (message) => new TypeError(message),
+    RangeError: (message) => new RangeError(message),
+    SyntaxError: (message) => new SyntaxError(message),
+    ReferenceError: (message) => new ReferenceError(message),
+    EvalError: (message) => new EvalError(message),
+    URIError: (message) => new URIError(message),
+    AggregateError: (message) => new AggregateError([], message),
+});
+/** Creates the error for a serialized name, preferring a built-in subclass. */
+function createError(name, message) {
+    const build = typeof name === "string" && Object.hasOwn(BUILT_IN_ERRORS, name)
+        ? BUILT_IN_ERRORS[name]
+        : undefined;
+    if (build !== undefined)
+        return build(message);
+    const error = new Error(message);
+    if (typeof name === "string" && name !== "Error") {
+        error.name = name;
+    }
+    return error;
+}
 /** Transformer that handles Error round-trips. */
 export const ErrorTransformer = {
     type: ERROR_TYPE,
@@ -33,11 +60,10 @@ export const ErrorTransformer = {
     deserialize(value) {
         const data = value;
         const message = typeof data.message === "string" ? data.message : "";
-        const error = new Error(message);
-        const name = data.name;
-        if (typeof name === "string" && name !== "Error") {
-            error.name = name;
-        }
+        const error = createError(data.name, message);
+        // The reader's own frames point at this deserializer, not at where the
+        // error was thrown, so the rebuilt stack is the header line only.
+        error.stack = message === "" ? error.name : `${error.name}: ${message}`;
         // A stack from the wire is attacker-controlled text. Restoring it over the
         // real one would make the reconstructed error lie about where it came
         // from, so it is carried as a separate, clearly-named field instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/serialization",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Data translation layer with JSON serializer, type transformers, envelopes, and registry for Zudojs applications.",
   "type": "module",
   "main": "./dist/index.js",