@zudojs/serialization 1.1.1 → 1.2.1

package/README.md

@@ -70,13 +70,40 @@ const registry = new TransformerRegistry();
 registry.register({
   type: "Money",
   canSerialize: (v): v is Money => v instanceof Money,
-  serialize: (v) => ({ $type: "Money", $value: v.toString() }),
+  serialize: (v) => (v as Money).toString(), // wrapped as { $type: "Money", $value: "..." }
   deserialize: (v) => Money.parse((v as { $value: string }).$value),
 });
 
 const serializer = new JSONSerializer({ transformers: registry });
+// Money uses your transformer; Date, BigInt, Map, Set, Buffer and Error still
+// use the built-ins.
 ```
 
+Your registry is consulted first, so registering a tag the built-ins use (say
+`"Date"`) replaces that built-in. Transformers you add to the registry later are
+picked up.
+
+**The transformer contract.** On the wire a transformed value is always
+`{ "$type": <type>, "$value": ... }`.
+
+- `serialize` returns either just the value to store, which the serializer
+  wraps as `{ $type: type, $value: <returned> }`, or that full tagged object
+  itself (as the built-ins do). A plain object with its own string `$type` is
+  taken as the full tagged object; anything else is wrapped. Special values
+  nested inside what you return (a `Date`, a `BigInt`) are transformed too.
+- `deserialize` always receives the full tagged object, with nested values
+  already restored, whichever form `serialize` returned. Read `$value` from it.
+
+**Opting out of the built-ins.** Pass `builtins: false` (to `JSONSerializer`
+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. 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
 
 `deserialize` is the boundary that matters — the string arrives from a queue, an
@@ -126,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/index.d.ts

@@ -26,11 +26,13 @@
  */
 export type { SerializationFormat, SerializedValue, SerializeOptions, DeserializeOptions, SerializationMetadata, SerializedEnvelope, Serializer, TypeTransformer, } from "./serializerTypes/index.js";
 export { JSONSerializer, ESCAPED_OBJECT_TAG } from "./serializerJson/index.js";
+export type { JSONSerializerOptions } from "./serializerJson/index.js";
 export { TransformerRegistry } from "./serializerTransforms/index.js";
 export { DateTransformer } from "./serializerTransforms/index.js";
 export { BigIntTransformer } from "./serializerTransforms/index.js";
 export { MapTransformer } from "./serializerTransforms/index.js";
 export { SetTransformer } from "./serializerTransforms/index.js";
+export { createBuiltinTransformers } from "./serializerTransformPolicy/index.js";
 export { BufferTransformer } from "./serializerTransformsExt/index.js";
 export { ErrorTransformer } from "./serializerTransformsExt/index.js";
 export { toBase64, fromBase64, encodeUtf8, decodeUtf8, } from "./serializerTransformsExt/index.js";

package/dist/index.js

@@ -32,6 +32,7 @@ export { DateTransformer } from "./serializerTransforms/index.js";
 export { BigIntTransformer } from "./serializerTransforms/index.js";
 export { MapTransformer } from "./serializerTransforms/index.js";
 export { SetTransformer } from "./serializerTransforms/index.js";
+export { createBuiltinTransformers } from "./serializerTransformPolicy/index.js";
 // ─── Extended Transformers ────────────────────────────────────
 export { BufferTransformer } from "./serializerTransformsExt/index.js";
 export { ErrorTransformer } from "./serializerTransformsExt/index.js";

package/dist/serializerJson/index.d.ts

@@ -4,6 +4,6 @@
  * JSON serializer with fast path (native JSON) and advanced path
  * with type preservation via transformer registry.
  */
-export { JSONSerializer } from "./jsonSerializer.core.js";
+export { JSONSerializer, type JSONSerializerOptions, } from "./jsonSerializer.core.js";
 export { ESCAPED_OBJECT_TAG } from "./jsonSerializer.escape.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/serializerJson/index.js

@@ -4,6 +4,6 @@
  * JSON serializer with fast path (native JSON) and advanced path
  * with type preservation via transformer registry.
  */
-export { JSONSerializer } from "./jsonSerializer.core.js";
+export { JSONSerializer, } from "./jsonSerializer.core.js";
 export { ESCAPED_OBJECT_TAG } from "./jsonSerializer.escape.js";
 //# sourceMappingURL=index.js.map

package/dist/serializerJson/jsonSerializer.core.d.ts

@@ -7,6 +7,25 @@
  */
 import type { Serializer, SerializeOptions, DeserializeOptions } from "../serializerTypes/index.js";
 import { TransformerRegistry } from "../serializerTransforms/index.js";
+/** Options accepted by the {@link JSONSerializer} constructor. */
+export interface JSONSerializerOptions {
+    /**
+     * Your transformers. They are consulted first; the built-in transformers
+     * (`Date`, `BigInt`, `Map`, `Set`, `Uint8Array`/`Buffer`, `Error`) still
+     * handle every type your registry does not, unless `builtins` is `false`.
+     * Transformers registered on it later are picked up.
+     */
+    readonly transformers?: TransformerRegistry;
+    /**
+     * Include the built-in transformers behind `transformers` (default
+     * `true`). With `false` only your registry is used, and a value no
+     * transformer handles that JSON would write as `{}` (a `Map`, `Set`,
+     * `Error`, ...) throws `SerializeError` under `preserveTypes`.
+     */
+    readonly builtins?: boolean;
+    /** Default options merged into every call. */
+    readonly defaults?: SerializeOptions & DeserializeOptions;
+}
 /**
  * JSON serializer. With `preserveTypes`, plain objects that carry their own
  * string `$type` key are escaped as `{"$type":"Object","$value":{...}}` on
@@ -16,13 +35,10 @@ import { TransformerRegistry } from "../serializerTransforms/index.js";
 export declare class JSONSerializer implements Serializer<unknown, string> {
     readonly name = "json";
     readonly contentType = "application/json";
+    private readonly registry;
     private readonly transformers;
     private readonly defaults;
-    constructor(options?: {
-        readonly transformers?: TransformerRegistry;
-        /** Default options merged into every call. */
-        readonly defaults?: SerializeOptions & DeserializeOptions;
-    });
+    constructor(options?: JSONSerializerOptions);
     /**
      * Register a custom type transformer.
      *

package/dist/serializerJson/jsonSerializer.core.js

@@ -5,8 +5,8 @@
  * Advanced path (preserveTypes: true): recursive traversal with
  * transformer-based type preservation.
  */
-import { TransformerRegistry, DateTransformer, BigIntTransformer, MapTransformer, SetTransformer, } from "../serializerTransforms/index.js";
-import { BufferTransformer, ErrorTransformer, } from "../serializerTransformsExt/index.js";
+import { TransformerRegistry } from "../serializerTransforms/index.js";
+import { createBuiltinTransformers, layerTransformers, } from "../serializerTransformPolicy/index.js";
 import { SerializationLimits } from "@zudojs/constants";
 import { InvalidSerializedDataError, TransformerError } from "@zudojs/errors";
 import { assertNoCircularReference, assertDepthWithinLimit, } from "@zudojs/validation";
@@ -14,17 +14,6 @@ import { ESCAPED_OBJECT_TAG } from "./jsonSerializer.escape.js";
 import { assertByteSize } from "./jsonSerializer.keys.js";
 import { transformValue } from "./jsonSerializer.transform.js";
 import { restoreValue } from "./jsonSerializer.restore.js";
-/** Default transformer registry with all built-in transformers. */
-function createDefaultTransformers() {
-    const registry = new TransformerRegistry();
-    registry.register(DateTransformer);
-    registry.register(BigIntTransformer);
-    registry.register(MapTransformer);
-    registry.register(SetTransformer);
-    registry.register(BufferTransformer);
-    registry.register(ErrorTransformer);
-    return registry;
-}
 /**
  * JSON serializer. With `preserveTypes`, plain objects that carry their own
  * string `$type` key are escaped as `{"$type":"Object","$value":{...}}` on
@@ -34,10 +23,18 @@ function createDefaultTransformers() {
 export class JSONSerializer {
     name = "json";
     contentType = "application/json";
+    registry;
     transformers;
     defaults;
     constructor(options) {
-        this.transformers = options?.transformers ?? createDefaultTransformers();
+        const builtins = options?.builtins !== false;
+        const custom = options?.transformers;
+        this.registry =
+            custom ?? (builtins ? createBuiltinTransformers() : new TransformerRegistry());
+        this.transformers =
+            custom && builtins
+                ? layerTransformers(custom, createBuiltinTransformers())
+                : this.registry;
         this.defaults = options?.defaults ?? {};
     }
     /**
@@ -49,7 +46,7 @@ export class JSONSerializer {
         if (transformer.type === ESCAPED_OBJECT_TAG) {
             throw new TransformerError(transformer.type, `"${ESCAPED_OBJECT_TAG}" is reserved for escaped plain objects.`);
         }
-        this.transformers.register(transformer);
+        this.registry.register(transformer);
     }
     serialize(value, options) {
         const opts = { ...this.defaults, ...options };

package/dist/serializerJson/jsonSerializer.restore.d.ts

@@ -5,10 +5,10 @@
  * plain objects (see `jsonSerializer.escape.ts`).
  */
 import type { DeserializeOptions } from "../serializerTypes/index.js";
-import type { TransformerRegistry } from "../serializerTransforms/index.js";
+import type { TransformerLookup } from "../serializerTransformPolicy/index.js";
 /** What the walker needs besides the value. */
 export interface RestoreWalk {
-    readonly transformers: TransformerRegistry;
+    readonly transformers: TransformerLookup;
     readonly maxDepth: number;
     readonly options: DeserializeOptions;
 }

package/dist/serializerJson/jsonSerializer.transform.d.ts

@@ -5,10 +5,10 @@
  * and escapes plain objects that would otherwise read back as a tag.
  */
 import type { SerializeOptions } from "../serializerTypes/index.js";
-import type { TransformerRegistry } from "../serializerTransforms/index.js";
+import { type TransformerLookup } from "../serializerTransformPolicy/index.js";
 /** What the walker needs besides the value. */
 export interface TransformWalk {
-    readonly transformers: TransformerRegistry;
+    readonly transformers: TransformerLookup;
     readonly maxDepth: number;
     readonly options: SerializeOptions;
 }

package/dist/serializerJson/jsonSerializer.transform.js

@@ -6,6 +6,7 @@
  */
 import { SerializationDepthError } from "@zudojs/errors";
 import { isPlainObject } from "@zudojs/types";
+import { assertNotLossy, toTaggedOutput, } from "../serializerTransformPolicy/index.js";
 import { escapeObject, needsEscape } from "./jsonSerializer.escape.js";
 import { defineKey } from "./jsonSerializer.keys.js";
 /** Converts a value into its JSON-safe, tagged representation. */
@@ -15,7 +16,7 @@ export function transformValue(walk, value, depth) {
     if (typeof value === "bigint") {
         const transformer = walk.transformers.findForValue(value);
         return transformer
-            ? transformer.serialize(value, walk.options)
+            ? transformEntries(walk, toTaggedOutput(transformer, transformer.serialize(value, walk.options)), depth + 1)
             : value.toString();
     }
     if (typeof value !== "object")
@@ -35,17 +36,17 @@ export function transformValue(walk, value, depth) {
     }
     const transformer = walk.transformers.findForValue(value);
     if (transformer) {
-        const raw = transformer.serialize(value, walk.options);
         // The transformer's own tag object is not user data: its children are
-        // walked, but it is never escaped.
-        return isPlainObject(raw)
-            ? transformEntries(walk, raw, depth + 1)
-            : transformValue(walk, raw, depth + 1);
+        // walked, but it is never escaped. A bare return value is wrapped in
+        // `{ $type, $value }` for the transformer author.
+        const raw = transformer.serialize(value, walk.options);
+        return transformEntries(walk, toTaggedOutput(transformer, raw), depth + 1);
     }
     if (isPlainObject(value)) {
         const body = transformEntries(walk, value, depth);
         return needsEscape(value) ? escapeObject(body) : body;
     }
+    assertNotLossy(value);
     return value;
 }
 /** Transforms each own enumerable key of a plain object. */

package/dist/serializerRegistry/serializerRegistry.factory.d.ts

@@ -17,8 +17,13 @@ import { SerializerRegistry } from "./serializerRegistry.core.js";
  * default that each call can still override.
  */
 export interface CreateSerializerOptions extends SerializeOptions, DeserializeOptions {
-    /** Transformer registry to use instead of the built-in one. */
+    /**
+     * Your transformers, consulted before the built-in ones (which still
+     * handle every other type unless `builtins` is `false`).
+     */
     readonly transformers?: TransformerRegistry;
+    /** Include the built-in transformers (default `true`). */
+    readonly builtins?: boolean;
     /** Pretty-print by default. Overridable per call. */
     readonly pretty?: boolean;
     /** Preserve special JS types by default. Overridable per call. */

package/dist/serializerRegistry/serializerRegistry.factory.js

@@ -15,9 +15,13 @@ export function createSerializer(format, options) {
         case Format.JSON: {
             // Only `pretty` and `preserveTypes` used to be forwarded, so instance
             // limits such as `maxDepth`/`maxSize`/`strict` were silently dropped.
-            const { transformers, ...rest } = options ?? {};
+            const { transformers, builtins, ...rest } = options ?? {};
             const defaults = Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined));
-            return new JSONSerializer({ transformers, defaults });
+            return new JSONSerializer({
+                ...(transformers !== undefined ? { transformers } : {}),
+                ...(builtins !== undefined ? { builtins } : {}),
+                defaults,
+            });
         }
         default:
             throw new UnsupportedSerializationFormatError(format);

package/dist/serializerTransformPolicy/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/serialization — Transformer policy.
+ *
+ * How the serializer resolves transformers (a caller registry layered over
+ * the built-ins), normalises what a transformer's `serialize` returns, and
+ * refuses values it would otherwise silently write as `{}`.
+ */
+export { createBuiltinTransformers, layerTransformers, type TransformerLookup, } from "./transformerLookup.core.js";
+export { assertNotLossy, toTaggedOutput } from "./transformerOutput.helper.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/serializerTransformPolicy/index.js

@@ -0,0 +1,10 @@
+/**
+ * @zudojs/serialization — Transformer policy.
+ *
+ * How the serializer resolves transformers (a caller registry layered over
+ * the built-ins), normalises what a transformer's `serialize` returns, and
+ * refuses values it would otherwise silently write as `{}`.
+ */
+export { createBuiltinTransformers, layerTransformers, } from "./transformerLookup.core.js";
+export { assertNotLossy, toTaggedOutput } from "./transformerOutput.helper.js";
+//# sourceMappingURL=index.js.map

package/dist/serializerTransformPolicy/transformerLookup.core.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @zudojs/serialization — Transformer lookup.
+ *
+ * The serializer resolves transformers through a lookup rather than a single
+ * registry, so a caller-supplied registry can sit in front of the built-ins
+ * instead of replacing them.
+ */
+import type { TypeTransformer } from "../serializerTypes/index.js";
+import { TransformerRegistry } from "../serializerTransforms/index.js";
+/** The read side of a transformer registry, as the walkers use it. */
+export interface TransformerLookup {
+    /** Find a transformer that can serialize the given value. */
+    findForValue(value: unknown): TypeTransformer | undefined;
+    /** Returns true when a transformer is registered for the type tag. */
+    has(type: string): boolean;
+    /** Retrieve a transformer by type tag (throws when absent). */
+    get(type: string): TypeTransformer;
+}
+/**
+ * Creates a registry holding every built-in transformer: `Date`, `BigInt`,
+ * `Map`, `Set`, `Uint8Array`/`Buffer` and `Error`.
+ */
+export declare function createBuiltinTransformers(): TransformerRegistry;
+/**
+ * Layers `primary` over `fallback`: every lookup consults `primary` first,
+ * so a caller's transformer for a tag or a value wins over the built-in
+ * one. `primary` is read live, so transformers registered on it later are
+ * seen too.
+ */
+export declare function layerTransformers(primary: TransformerLookup, fallback: TransformerLookup): TransformerLookup;
+//# sourceMappingURL=transformerLookup.core.d.ts.map

package/dist/serializerTransformPolicy/transformerLookup.core.js

@@ -0,0 +1,37 @@
+/**
+ * @zudojs/serialization — Transformer lookup.
+ *
+ * The serializer resolves transformers through a lookup rather than a single
+ * registry, so a caller-supplied registry can sit in front of the built-ins
+ * instead of replacing them.
+ */
+import { BigIntTransformer, DateTransformer, MapTransformer, SetTransformer, TransformerRegistry, } from "../serializerTransforms/index.js";
+import { BufferTransformer, ErrorTransformer, } from "../serializerTransformsExt/index.js";
+/**
+ * Creates a registry holding every built-in transformer: `Date`, `BigInt`,
+ * `Map`, `Set`, `Uint8Array`/`Buffer` and `Error`.
+ */
+export function createBuiltinTransformers() {
+    const registry = new TransformerRegistry();
+    registry.register(DateTransformer);
+    registry.register(BigIntTransformer);
+    registry.register(MapTransformer);
+    registry.register(SetTransformer);
+    registry.register(BufferTransformer);
+    registry.register(ErrorTransformer);
+    return registry;
+}
+/**
+ * Layers `primary` over `fallback`: every lookup consults `primary` first,
+ * so a caller's transformer for a tag or a value wins over the built-in
+ * one. `primary` is read live, so transformers registered on it later are
+ * seen too.
+ */
+export function layerTransformers(primary, fallback) {
+    return {
+        findForValue: (value) => primary.findForValue(value) ?? fallback.findForValue(value),
+        has: (type) => primary.has(type) || fallback.has(type),
+        get: (type) => (primary.has(type) ? primary.get(type) : fallback.get(type)),
+    };
+}
+//# sourceMappingURL=transformerLookup.core.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * @zudojs/serialization — Transformer output and lossy-value checks.
+ */
+import type { TypeTransformer } from "../serializerTypes/index.js";
+/**
+ * Normalises what a transformer's `serialize` returned into the tagged
+ * `{ $type, $value }` form that is written to the wire.
+ *
+ * A transformer may return the full tagged object (the built-ins do; any
+ * plain object with its own string `$type` is taken as-is), or just the
+ * value to store, which is wrapped as `{ $type: transformer.type, $value }`.
+ * Before, a bare return was written untagged and could never be revived.
+ */
+export declare function toTaggedOutput(transformer: TypeTransformer, raw: unknown): Record<string, unknown>;
+/**
+ * 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 declare function assertNotLossy(value: object): void;
+//# sourceMappingURL=transformerOutput.helper.d.ts.map

package/dist/serializerTransformPolicy/transformerOutput.helper.js

@@ -0,0 +1,78 @@
+/**
+ * @zudojs/serialization — Transformer output and lossy-value checks.
+ */
+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.
+ *
+ * A transformer may return the full tagged object (the built-ins do; any
+ * plain object with its own string `$type` is taken as-is), or just the
+ * value to store, which is wrapped as `{ $type: transformer.type, $value }`.
+ * Before, a bare return was written untagged and could never be revived.
+ */
+export function toTaggedOutput(transformer, raw) {
+    if (isPlainObject(raw) &&
+        Object.hasOwn(raw, SerializationTags.TYPE) &&
+        typeof raw[SerializationTags.TYPE] === "string") {
+        return raw;
+    }
+    return {
+        [SerializationTags.TYPE]: transformer.type,
+        [SerializationTags.VALUE]: raw,
+    };
+}
+/** Built-in objects whose JSON form silently drops their contents. */
+const LOSSY_TYPES = [
+    ["Map", (value) => value instanceof Map],
+    ["Set", (value) => value instanceof Set],
+    ["WeakMap", (value) => value instanceof WeakMap],
+    ["WeakSet", (value) => value instanceof WeakSet],
+    ["WeakRef", (value) => value instanceof WeakRef],
+    ["Promise", (value) => value instanceof Promise],
+    ["RegExp", (value) => value instanceof RegExp],
+    ["Error", (value) => value instanceof Error],
+    ["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)) {
+            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" });
+        }
+    }
+}
+//# sourceMappingURL=transformerOutput.helper.js.map

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/dist/serializerTypes/serializer.type.d.ts

@@ -86,15 +86,34 @@ export interface Serializer<TValue = unknown, TSerialized = SerializedValue> {
     /** Deserialize a value from the target format. */
     deserialize<T = TValue>(value: TSerialized, options?: DeserializeOptions): T;
 }
-/** Transforms a specific JS type during serialization. */
+/**
+ * Transforms a specific JS type during serialization.
+ *
+ * On the wire a transformed value is always the tagged object
+ * `{ "$type": type, "$value": ... }`.
+ */
 export interface TypeTransformer<TValue = unknown> {
     /** Tag name used in tagged representations (e.g., "Date"). */
     readonly type: string;
     /** Returns true when this transformer handles the given value. */
     canSerialize(value: unknown): value is TValue;
-    /** Convert the value into a JSON-safe representation. */
+    /**
+     * Convert the value into a JSON-safe representation.
+     *
+     * Return either just the value to store (for example
+     * `v.toString()`), which the serializer wraps as
+     * `{ $type: type, $value: <returned> }`, or the full tagged object
+     * `{ $type: type, $value: ... }` yourself (as the built-ins do). A plain
+     * object with its own string `$type` is taken to be the full tagged
+     * object; anything else is wrapped. Nested special values inside the
+     * returned value are transformed too.
+     */
     serialize(value: TValue, options?: SerializeOptions): unknown;
-    /** Reconstruct the original value from the serialized form. */
+    /**
+     * Reconstruct the original value. Always receives the full tagged object
+     * `{ $type, $value }` (with nested values already restored), whichever
+     * form `serialize` returned, so read `$value` from it.
+     */
     deserialize(value: unknown, options?: DeserializeOptions): TValue;
 }
 //# sourceMappingURL=serializer.type.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/serialization",
-  "version": "1.1.1",
+  "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",
@@ -19,14 +19,14 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@zudojs/constants": "1.1.1",
-    "@zudojs/errors": "1.2.0",
-    "@zudojs/types": "1.1.1",
-    "@zudojs/validation": "1.0.3"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/types": "1.2.0",
+    "@zudojs/validation": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "license": "MIT",
   "author": {
@@ -46,7 +46,7 @@
     "node": ">=24.0.0"
   },
   "module": "./dist/index.js",
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-serialization",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },