@zudojs/serialization 1.0.1 → 1.1.1

package/README.md

@@ -2,6 +2,12 @@
 
 JSON serialization with optional type preservation, a transformer registry, and an envelope for cross-service payloads.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-serialization](https://zudojs.oyinlola.site/docs/packages-serialization) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-serialization.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -22,8 +28,10 @@ const value = serializer.deserialize<{ id: string; createdAt: Date }>(json);
 value.createdAt instanceof Date; // true
 ```
 
-The methods are `serialize` / `deserialize`, and every option can be overridden
-per call:
+Every serialize/deserialize option — `pretty`, `preserveTypes`, `maxSize`,
+`maxDepth`, `strict`, `allowUnsafeKeys`, `includeStack` — can be passed to
+`createSerializer` as an instance default. The methods are `serialize` /
+`deserialize`, and every option can be overridden per call:
 
 ```typescript
 serializer.serialize(value, { pretty: true, maxSize: 1_000_000 });
@@ -84,12 +92,32 @@ RPC peer or a request body.
 - **Input is size-bounded** by `maxSize`, and depth-bounded by `maxDepth`. On
   the `preserveTypes` path the depth limit defaults to 128; on the fast path it
   is enforced whenever you set it, per call or as an instance default.
-- **An unrecognised `$type` tag is treated as ordinary data**, so a peer cannot
-  stop the consumer with `{"$type":"anything"}` and your own records may carry a
-  `$type` field. Pass `strict: true` to make an unknown tag an error instead.
+- **Your own data may carry a `$type` key.** With `preserveTypes`, a plain
+  object that has its own string `$type` is written escaped as
+  `{"$type":"Object","$value":{...}}` (`ESCAPED_OBJECT_TAG`) and read back as
+  the plain object it was, so user data can never be revived as a `Map`,
+  `Error`, `BigInt` or `Buffer`. `"Object"` is reserved and cannot be
+  registered as a transformer. Payloads written before this escaping existed
+  are still read as before: an unescaped tag is revived, since it cannot be
+  told apart from one the serializer wrote.
+- **An unrecognised or malformed tag is treated as ordinary data**, so a peer
+  cannot stop the consumer with `{"$type":"anything"}` or
+  `{"$type":"Date","$value":"nope"}`, and a bad record stays readable. Pass
+  `strict: true` to make either an error instead.
+- **BigInt tags are capped at 4096 decimal digits**
+  (`SerializationLimits.MAX_BIGINT_DIGITS` from `@zudojs/constants`, shared
+  with `@zudojs/schema`'s `coerce.bigint()`), checked before `BigInt()` runs;
+  serializing a larger BigInt throws.
 
 ## Errors
 
+Failures throw `@zudojs/errors` serialization classes: `SerializationPayloadTooLargeError`,
+`SerializationDepthError`, `InvalidSerializedDataError` (malformed JSON, unknown
+or malformed tags under `strict`), `TransformerError` and `SerializeError` (for
+example an invalid `Date`). All extend `SerializationError`.
+
+### Serialized errors
+
 Stack traces are **not** serialized unless you ask, because a serialized error
 routinely ends up in a queue message or a log sink:
 

package/dist/index.d.ts

@@ -25,7 +25,7 @@
  * ```
  */
 export type { SerializationFormat, SerializedValue, SerializeOptions, DeserializeOptions, SerializationMetadata, SerializedEnvelope, Serializer, TypeTransformer, } from "./serializerTypes/index.js";
-export { JSONSerializer } from "./serializerJson/index.js";
+export { JSONSerializer, ESCAPED_OBJECT_TAG } from "./serializerJson/index.js";
 export { TransformerRegistry } from "./serializerTransforms/index.js";
 export { DateTransformer } from "./serializerTransforms/index.js";
 export { BigIntTransformer } from "./serializerTransforms/index.js";

package/dist/index.js

@@ -25,7 +25,7 @@
  * ```
  */
 // ─── JSON Serializer ──────────────────────────────────────────
-export { JSONSerializer } from "./serializerJson/index.js";
+export { JSONSerializer, ESCAPED_OBJECT_TAG } from "./serializerJson/index.js";
 // ─── Transformer Registry ─────────────────────────────────────
 export { TransformerRegistry } from "./serializerTransforms/index.js";
 export { DateTransformer } from "./serializerTransforms/index.js";

package/dist/serializerEnvelope/envelope.core.d.ts

@@ -30,7 +30,10 @@ export declare function contentTypeForFormat(format: string): string;
  * Validates that a value received from the wire is a well-formed envelope.
  *
  * @param envelope - The candidate envelope.
- * @throws {Error} when the shape or schema version is unusable.
+ * @throws {InvalidSerializedDataError} when the shape or schema version is
+ *   unusable. Envelope payloads arrive from a queue or an RPC peer, so a
+ *   rejection has to be distinguishable from an internal bug: a bare `Error`
+ *   left callers unable to tell hostile input from a defect of their own.
  */
 export declare function assertValidEnvelope(envelope: unknown): asserts envelope is SerializedEnvelope;
 /**
@@ -39,7 +42,8 @@ export declare function assertValidEnvelope(envelope: unknown): asserts envelope
  * @param envelope - The envelope to unwrap.
  * @param expectedFormat - Optional format to validate against.
  * @returns The raw serialized data.
- * @throws {Error} when the envelope format doesn't match expectations.
+ * @throws {InvalidSerializedDataError} when the envelope is malformed or its
+ *   format doesn't match expectations.
  */
 export declare function unwrapEnvelope(envelope: SerializedEnvelope, expectedFormat?: string): SerializedValue;
 /**

package/dist/serializerEnvelope/envelope.core.js

@@ -6,6 +6,7 @@
  * messaging, queues, RPC, and cross-service communication.
  */
 import { SerializationFormat, SerializationContentType, SERIALIZATION_SCHEMA_VERSION, } from "@zudojs/constants";
+import { InvalidSerializedDataError } from "@zudojs/errors";
 import { decodeUtf8 } from "../serializerTransformsExt/index.js";
 /**
  * Create a serialization envelope wrapping data with metadata.
@@ -51,32 +52,35 @@ export function contentTypeForFormat(format) {
  * Validates that a value received from the wire is a well-formed envelope.
  *
  * @param envelope - The candidate envelope.
- * @throws {Error} when the shape or schema version is unusable.
+ * @throws {InvalidSerializedDataError} when the shape or schema version is
+ *   unusable. Envelope payloads arrive from a queue or an RPC peer, so a
+ *   rejection has to be distinguishable from an internal bug: a bare `Error`
+ *   left callers unable to tell hostile input from a defect of their own.
  */
 export function assertValidEnvelope(envelope) {
     if (typeof envelope !== "object" || envelope === null) {
-        throw new Error(`Malformed envelope: expected an object, got ${envelope === null ? "null" : typeof envelope}`);
+        throw new InvalidSerializedDataError(`Malformed envelope: expected an object, got ${envelope === null ? "null" : typeof envelope}`, { format: "envelope" });
     }
     const candidate = envelope;
     if (typeof candidate.metadata !== "object" || candidate.metadata === null) {
-        throw new Error("Malformed envelope: missing metadata");
+        throw new InvalidSerializedDataError("Malformed envelope: missing metadata", { format: "envelope" });
     }
     const metadata = candidate.metadata;
     if (typeof metadata.format !== "string" || metadata.format.length === 0) {
-        throw new Error("Malformed envelope: metadata.format is missing");
+        throw new InvalidSerializedDataError("Malformed envelope: metadata.format is missing", { format: "envelope" });
     }
     if (typeof candidate.data !== "string" &&
         !(candidate.data instanceof Uint8Array)) {
-        throw new Error("Malformed envelope: data must be a string or Uint8Array");
+        throw new InvalidSerializedDataError("Malformed envelope: data must be a string or Uint8Array", { format: "envelope" });
     }
     // The version exists so a future producer can be detected rather than
     // silently misread. Older versions stay readable; newer ones do not.
     if (metadata.version !== undefined) {
         if (!Number.isInteger(metadata.version)) {
-            throw new Error(`Malformed envelope: metadata.version must be an integer, got ${String(metadata.version)}`);
+            throw new InvalidSerializedDataError(`Malformed envelope: metadata.version must be an integer, got ${String(metadata.version)}`, { format: "envelope" });
         }
         if (metadata.version > SERIALIZATION_SCHEMA_VERSION) {
-            throw new Error(`Unsupported envelope schema version ${metadata.version}: this build understands up to ${SERIALIZATION_SCHEMA_VERSION}`);
+            throw new InvalidSerializedDataError(`Unsupported envelope schema version ${metadata.version}: this build understands up to ${SERIALIZATION_SCHEMA_VERSION}`, { format: "envelope" });
         }
     }
 }
@@ -86,12 +90,13 @@ export function assertValidEnvelope(envelope) {
  * @param envelope - The envelope to unwrap.
  * @param expectedFormat - Optional format to validate against.
  * @returns The raw serialized data.
- * @throws {Error} when the envelope format doesn't match expectations.
+ * @throws {InvalidSerializedDataError} when the envelope is malformed or its
+ *   format doesn't match expectations.
  */
 export function unwrapEnvelope(envelope, expectedFormat) {
     assertValidEnvelope(envelope);
     if (expectedFormat && envelope.metadata.format !== expectedFormat) {
-        throw new Error(`Envelope format mismatch: expected "${expectedFormat}", got "${envelope.metadata.format}"`);
+        throw new InvalidSerializedDataError(`Envelope format mismatch: expected "${expectedFormat}", got "${envelope.metadata.format}"`, { format: expectedFormat });
     }
     return envelope.data;
 }
@@ -132,7 +137,7 @@ export function deserializeFromEnvelope(envelope, deserializer, expectedFormat,
     }
     const encoding = (envelope.metadata.encoding ?? "utf-8").toLowerCase();
     if (encoding !== "utf-8" && encoding !== "utf8") {
-        throw new Error(`Unsupported envelope encoding "${envelope.metadata.encoding}": only UTF-8 is supported`);
+        throw new InvalidSerializedDataError(`Unsupported envelope encoding "${envelope.metadata.encoding}": only UTF-8 is supported`, { format: envelope.metadata.format });
     }
     return deserializer.deserialize(decodeUtf8(data), options);
 }

package/dist/serializerJson/index.d.ts

@@ -5,4 +5,5 @@
  * with type preservation via transformer registry.
  */
 export { JSONSerializer } from "./jsonSerializer.core.js";
+export { ESCAPED_OBJECT_TAG } from "./jsonSerializer.escape.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/serializerJson/index.js

@@ -5,4 +5,5 @@
  * with type preservation via transformer registry.
  */
 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,12 @@
  */
 import type { Serializer, SerializeOptions, DeserializeOptions } from "../serializerTypes/index.js";
 import { TransformerRegistry } from "../serializerTransforms/index.js";
+/**
+ * JSON serializer. With `preserveTypes`, plain objects that carry their own
+ * string `$type` key are escaped as `{"$type":"Object","$value":{...}}` on
+ * write and unwrapped on read, so user data can never be revived as a
+ * different runtime type.
+ */
 export declare class JSONSerializer implements Serializer<unknown, string> {
     readonly name = "json";
     readonly contentType = "application/json";
@@ -17,14 +23,15 @@ export declare class JSONSerializer implements Serializer<unknown, string> {
         /** Default options merged into every call. */
         readonly defaults?: SerializeOptions & DeserializeOptions;
     });
-    /** Register a custom type transformer. */
+    /**
+     * Register a custom type transformer.
+     *
+     * @throws {TransformerError} for the reserved escape tag `"Object"`.
+     */
     registerTransformer(transformer: import("../serializerTypes/index.js").TypeTransformer): void;
     serialize(value: unknown, options?: SerializeOptions): string;
     deserialize<T = unknown>(value: string, options?: DeserializeOptions): T;
-    private transformValue;
-    private restoreValue;
-    private assertValidJson;
-    private assertOutputSize;
-    private assertInputSize;
+    /** Parses JSON, reporting malformed input as a typed error. */
+    private parse;
 }
 //# sourceMappingURL=jsonSerializer.core.d.ts.map

package/dist/serializerJson/jsonSerializer.core.js

@@ -5,12 +5,15 @@
  * Advanced path (preserveTypes: true): recursive traversal with
  * transformer-based type preservation.
  */
-import { TransformerRegistry } from "../serializerTransforms/index.js";
-import { DateTransformer, BigIntTransformer, MapTransformer, SetTransformer, } from "../serializerTransforms/index.js";
+import { TransformerRegistry, DateTransformer, BigIntTransformer, MapTransformer, SetTransformer, } from "../serializerTransforms/index.js";
 import { BufferTransformer, ErrorTransformer, } from "../serializerTransformsExt/index.js";
-import { SerializationLimits, SerializationTags, SCHEMA_FORBIDDEN_KEYS, } from "@zudojs/constants";
-import { isPlainObject } from "@zudojs/types";
+import { SerializationLimits } from "@zudojs/constants";
+import { InvalidSerializedDataError, TransformerError } from "@zudojs/errors";
 import { assertNoCircularReference, assertDepthWithinLimit, } from "@zudojs/validation";
+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();
@@ -22,6 +25,12 @@ function createDefaultTransformers() {
     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
+ * write and unwrapped on read, so user data can never be revived as a
+ * different runtime type.
+ */
 export class JSONSerializer {
     name = "json";
     contentType = "application/json";
@@ -31,8 +40,15 @@ export class JSONSerializer {
         this.transformers = options?.transformers ?? createDefaultTransformers();
         this.defaults = options?.defaults ?? {};
     }
-    /** Register a custom type transformer. */
+    /**
+     * Register a custom type transformer.
+     *
+     * @throws {TransformerError} for the reserved escape tag `"Object"`.
+     */
     registerTransformer(transformer) {
+        if (transformer.type === ESCAPED_OBJECT_TAG) {
+            throw new TransformerError(transformer.type, `"${ESCAPED_OBJECT_TAG}" is reserved for escaped plain objects.`);
+        }
         this.transformers.register(transformer);
     }
     serialize(value, options) {
@@ -40,13 +56,17 @@ export class JSONSerializer {
         const maxDepth = opts.maxDepth ?? SerializationLimits.MAX_DEPTH;
         const maxSize = opts.maxSize ?? SerializationLimits.MAX_SIZE;
         if (opts.preserveTypes === true) {
-            assertNoCircularReference(value);
+            // The cycle check runs first and must therefore honour the caller's
+            // depth limit: with its own 512-level ceiling it halted on a deep but
+            // perfectly acyclic payload and reported a cycle that did not exist,
+            // disagreeing with the fast path below for the same input.
+            assertNoCircularReference(value, "root", maxDepth);
             assertDepthWithinLimit(value, maxDepth);
-            const transformed = this.transformValue(value, 0, maxDepth, opts);
+            const transformed = transformValue({ transformers: this.transformers, maxDepth, options: opts }, value, 0);
             const json = opts.pretty
                 ? JSON.stringify(transformed, null, opts.indent ?? 2)
                 : JSON.stringify(transformed);
-            this.assertOutputSize(json, maxSize);
+            assertByteSize(json, maxSize);
             return json;
         }
         // The fast path stays a bare `JSON.stringify` by default, but a depth
@@ -59,7 +79,7 @@ export class JSONSerializer {
         const json = opts.pretty
             ? JSON.stringify(value, null, opts.indent ?? 2)
             : JSON.stringify(value);
-        this.assertOutputSize(json, maxSize);
+        assertByteSize(json, maxSize);
         return json;
     }
     deserialize(value, options) {
@@ -69,14 +89,12 @@ export class JSONSerializer {
         // the string handed to `deserialize` arrives from a queue, an RPC peer, or
         // a request body.
         const maxSize = opts.maxSize ?? SerializationLimits.MAX_SIZE;
-        this.assertInputSize(value, maxSize);
-        if (opts.strict === true)
-            this.assertValidJson(value);
-        const parsed = JSON.parse(value);
+        assertByteSize(value, maxSize);
+        const parsed = this.parse(value);
         if (opts.preserveTypes === true) {
             const maxDepth = opts.maxDepth ?? SerializationLimits.MAX_DEPTH;
             assertDepthWithinLimit(parsed, maxDepth);
-            return this.restoreValue(parsed, 0, maxDepth, opts);
+            return restoreValue({ transformers: this.transformers, maxDepth, options: opts }, parsed, 0);
         }
         // Same contract on the fast path: an explicit `maxDepth` bounds input
         // that arrives from the wire, whether or not types are being restored.
@@ -85,127 +103,14 @@ export class JSONSerializer {
         }
         return parsed;
     }
-    transformValue(value, depth, maxDepth, options) {
-        if (value === null || value === undefined)
-            return value;
-        if (typeof value === "bigint") {
-            const transformer = this.transformers.findForValue(value);
-            return transformer
-                ? transformer.serialize(value, options)
-                : value.toString();
-        }
-        if (typeof value !== "object")
-            return value;
-        if (depth >= maxDepth) {
-            // Depth is pre-checked by assertDepthWithinLimit, so this is a belt-and
-            // braces guard. Returning the raw value would silently emit an untagged
-            // Map or Date, which cannot round-trip — fail loudly instead.
-            throw new Error(`Serialization exceeded maximum depth of ${maxDepth}`);
-        }
-        if (Array.isArray(value)) {
-            return value.map((item) => this.transformValue(item, depth + 1, maxDepth, options));
-        }
-        const transformer = this.transformers.findForValue(value);
-        if (transformer) {
-            const raw = transformer.serialize(value, options);
-            return this.transformValue(raw, depth + 1, maxDepth, options);
-        }
-        if (isPlainObject(value)) {
-            const result = {};
-            for (const key of Object.keys(value)) {
-                defineKey(result, key, this.transformValue(value[key], depth + 1, maxDepth, options), options.allowUnsafeKeys === true);
-            }
-            return result;
-        }
-        return value;
-    }
-    restoreValue(value, depth, maxDepth, options) {
-        if (value === null || value === undefined)
-            return value;
-        if (typeof value !== "object")
-            return value;
-        if (depth >= maxDepth) {
-            throw new Error(`Deserialization exceeded maximum depth of ${maxDepth}`);
-        }
-        if (Array.isArray(value)) {
-            return value.map((item) => this.restoreValue(item, depth + 1, maxDepth, options));
-        }
-        const obj = value;
-        const typeTag = obj[SerializationTags.TYPE];
-        if (typeof typeTag === "string" && this.transformers.has(typeTag)) {
-            // Restore the children first. A transformer receives a plain structure
-            // and has no way to recurse back into this serializer, so handing it the
-            // still-tagged payload is what used to leave a Map full of raw
-            // `{$type, $value}` objects.
-            const restoredShell = {};
-            for (const key of Object.keys(obj)) {
-                defineKey(restoredShell, key, key === SerializationTags.TYPE
-                    ? obj[key]
-                    : this.restoreValue(obj[key], depth + 1, maxDepth, options), options.allowUnsafeKeys === true);
-            }
-            return this.transformers.get(typeTag).deserialize(restoredShell, options);
-        }
-        // An unknown tag is ordinary data. Throwing here let any peer crash the
-        // consumer with `{"$type":"anything"}`, and made legitimate payloads that
-        // happen to carry a `$type` field unparseable.
-        if (typeof typeTag === "string" && options.strict === true) {
-            throw new Error(`Unknown serialization type tag: "${typeTag}". ` +
-                "Register a transformer for it, or deserialize without strict mode.");
-        }
-        if (isPlainObject(value)) {
-            const result = {};
-            for (const key of Object.keys(value)) {
-                defineKey(result, key, this.restoreValue(value[key], depth + 1, maxDepth, options), options.allowUnsafeKeys === true);
-            }
-            return result;
-        }
-        return value;
-    }
-    assertValidJson(value) {
+    /** Parses JSON, reporting malformed input as a typed error. */
+    parse(value) {
         try {
-            JSON.parse(value);
+            return JSON.parse(value);
         }
         catch (err) {
-            throw new Error(`Invalid JSON: ${err.message}`);
-        }
-    }
-    assertOutputSize(json, maxSize) {
-        const size = byteLength(json);
-        if (size > maxSize) {
-            throw new Error(`Serialized payload too large: ${size} bytes (max: ${maxSize})`);
-        }
-    }
-    assertInputSize(json, maxSize) {
-        const size = byteLength(json);
-        if (size > maxSize) {
-            throw new Error(`Serialized payload too large: ${size} bytes (max: ${maxSize})`);
+            throw new InvalidSerializedDataError(`Invalid JSON: ${err.message}`, { format: "json", cause: err });
         }
     }
 }
-/** Byte length of a string, in whichever runtime we are on. */
-function byteLength(value) {
-    return typeof Buffer !== "undefined"
-        ? Buffer.byteLength(value, "utf-8")
-        : new TextEncoder().encode(value).byteLength;
-}
-/**
- * Assigns a key onto a freshly built object without invoking a setter.
- *
- * Plain assignment of `__proto__` does not create an own property — it calls
- * the inherited setter and replaces the object's prototype, so an attacker's
- * keys resolve on the result while `Object.keys` shows nothing. `defineProperty`
- * always creates a real own property, and forbidden keys are dropped outright
- * unless the caller has explicitly opted in with `allowUnsafeKeys`.
- */
-function defineKey(target, key, value, allowUnsafeKeys) {
-    if (!allowUnsafeKeys && SCHEMA_FORBIDDEN_KEYS.has(key)) {
-        return;
-    }
-    Object.defineProperty(target, key, {
-        value,
-        writable: true,
-        enumerable: true,
-        configurable: true,
-    });
-}
 //# sourceMappingURL=jsonSerializer.core.js.map

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

@@ -0,0 +1,35 @@
+/**
+ * @zudojs/serialization — Escaping of user objects that look like type tags.
+ *
+ * With `preserveTypes`, a tagged object `{ "$type": "Map", "$value": [...] }`
+ * is revived into a real `Map` on read. A *user* object carrying its own
+ * string `$type` key used to be written out verbatim, so any caller who
+ * controlled part of a payload could choose the runtime type the reader got
+ * back (an `Error`, a `Buffer`, a `BigInt`), or plant a malformed tag that
+ * made the record unreadable.
+ *
+ * Such objects are now written wrapped in a reserved tag:
+ *
+ * ```json
+ * { "$type": "Object", "$value": { "$type": "Map", "note": "user data" } }
+ * ```
+ *
+ * and unwrapped on read into the plain object they were, with their own
+ * `$type` key left uninterpreted.
+ */
+/**
+ * Reserved type tag that marks an escaped plain object. No transformer may
+ * register under this name.
+ */
+export declare const ESCAPED_OBJECT_TAG = "Object";
+/** True when a plain object would be mistaken for a type tag on read. */
+export declare function needsEscape(value: Record<string, unknown>): boolean;
+/** Wraps an already-transformed object body in the reserved escape tag. */
+export declare function escapeObject(body: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Returns the escaped body when `value` is a well-formed escape wrapper,
+ * `undefined` when it is not an escape wrapper at all, and `null` when it
+ * claims to be one but its `$value` is not a plain object.
+ */
+export declare function escapedBody(value: Record<string, unknown>): Record<string, unknown> | null | undefined;
+//# sourceMappingURL=jsonSerializer.escape.d.ts.map

package/dist/serializerJson/jsonSerializer.escape.js

@@ -0,0 +1,50 @@
+/**
+ * @zudojs/serialization — Escaping of user objects that look like type tags.
+ *
+ * With `preserveTypes`, a tagged object `{ "$type": "Map", "$value": [...] }`
+ * is revived into a real `Map` on read. A *user* object carrying its own
+ * string `$type` key used to be written out verbatim, so any caller who
+ * controlled part of a payload could choose the runtime type the reader got
+ * back (an `Error`, a `Buffer`, a `BigInt`), or plant a malformed tag that
+ * made the record unreadable.
+ *
+ * Such objects are now written wrapped in a reserved tag:
+ *
+ * ```json
+ * { "$type": "Object", "$value": { "$type": "Map", "note": "user data" } }
+ * ```
+ *
+ * and unwrapped on read into the plain object they were, with their own
+ * `$type` key left uninterpreted.
+ */
+import { SerializationTags } from "@zudojs/constants";
+import { isPlainObject } from "@zudojs/types";
+/**
+ * Reserved type tag that marks an escaped plain object. No transformer may
+ * register under this name.
+ */
+export const ESCAPED_OBJECT_TAG = "Object";
+/** True when a plain object would be mistaken for a type tag on read. */
+export function needsEscape(value) {
+    return (Object.hasOwn(value, SerializationTags.TYPE) &&
+        typeof value[SerializationTags.TYPE] === "string");
+}
+/** Wraps an already-transformed object body in the reserved escape tag. */
+export function escapeObject(body) {
+    return {
+        [SerializationTags.TYPE]: ESCAPED_OBJECT_TAG,
+        [SerializationTags.VALUE]: body,
+    };
+}
+/**
+ * Returns the escaped body when `value` is a well-formed escape wrapper,
+ * `undefined` when it is not an escape wrapper at all, and `null` when it
+ * claims to be one but its `$value` is not a plain object.
+ */
+export function escapedBody(value) {
+    if (value[SerializationTags.TYPE] !== ESCAPED_OBJECT_TAG)
+        return undefined;
+    const body = value[SerializationTags.VALUE];
+    return isPlainObject(body) ? body : null;
+}
+//# sourceMappingURL=jsonSerializer.escape.js.map

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

@@ -0,0 +1,21 @@
+/**
+ * @zudojs/serialization — Low-level helpers shared by the JSON walkers.
+ */
+/** Byte length of a string, in whichever runtime we are on. */
+export declare function byteLength(value: string): number;
+/**
+ * Throws `SerializationPayloadTooLargeError` when a JSON string is larger
+ * than `maxSize` bytes.
+ */
+export declare function assertByteSize(json: string, maxSize: number): void;
+/**
+ * Assigns a key onto a freshly built object without invoking a setter.
+ *
+ * Plain assignment of `__proto__` does not create an own property — it calls
+ * the inherited setter and replaces the object's prototype, so an attacker's
+ * keys resolve on the result while `Object.keys` shows nothing. `defineProperty`
+ * always creates a real own property, and forbidden keys are dropped outright
+ * unless the caller has explicitly opted in with `allowUnsafeKeys`.
+ */
+export declare function defineKey(target: Record<string, unknown>, key: string, value: unknown, allowUnsafeKeys: boolean): void;
+//# sourceMappingURL=jsonSerializer.keys.d.ts.map

package/dist/serializerJson/jsonSerializer.keys.js

@@ -0,0 +1,41 @@
+/**
+ * @zudojs/serialization — Low-level helpers shared by the JSON walkers.
+ */
+import { SCHEMA_FORBIDDEN_KEYS } from "@zudojs/constants";
+import { SerializationPayloadTooLargeError } from "@zudojs/errors";
+/** Byte length of a string, in whichever runtime we are on. */
+export function byteLength(value) {
+    return typeof Buffer !== "undefined"
+        ? Buffer.byteLength(value, "utf-8")
+        : new TextEncoder().encode(value).byteLength;
+}
+/**
+ * Throws `SerializationPayloadTooLargeError` when a JSON string is larger
+ * than `maxSize` bytes.
+ */
+export function assertByteSize(json, maxSize) {
+    const size = byteLength(json);
+    if (size > maxSize)
+        throw new SerializationPayloadTooLargeError(size, maxSize);
+}
+/**
+ * Assigns a key onto a freshly built object without invoking a setter.
+ *
+ * Plain assignment of `__proto__` does not create an own property — it calls
+ * the inherited setter and replaces the object's prototype, so an attacker's
+ * keys resolve on the result while `Object.keys` shows nothing. `defineProperty`
+ * always creates a real own property, and forbidden keys are dropped outright
+ * unless the caller has explicitly opted in with `allowUnsafeKeys`.
+ */
+export function defineKey(target, key, value, allowUnsafeKeys) {
+    if (!allowUnsafeKeys && SCHEMA_FORBIDDEN_KEYS.has(key)) {
+        return;
+    }
+    Object.defineProperty(target, key, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+    });
+}
+//# sourceMappingURL=jsonSerializer.keys.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * @zudojs/serialization — Deserialize-side walker (`preserveTypes: true`).
+ *
+ * Revives tagged values through their transformers and unwraps escaped
+ * plain objects (see `jsonSerializer.escape.ts`).
+ */
+import type { DeserializeOptions } from "../serializerTypes/index.js";
+import type { TransformerRegistry } from "../serializerTransforms/index.js";
+/** What the walker needs besides the value. */
+export interface RestoreWalk {
+    readonly transformers: TransformerRegistry;
+    readonly maxDepth: number;
+    readonly options: DeserializeOptions;
+}
+/** Rebuilds runtime values from their tagged JSON representation. */
+export declare function restoreValue(walk: RestoreWalk, value: unknown, depth: number): unknown;
+//# sourceMappingURL=jsonSerializer.restore.d.ts.map

package/dist/serializerJson/jsonSerializer.restore.js

@@ -0,0 +1,86 @@
+/**
+ * @zudojs/serialization — Deserialize-side walker (`preserveTypes: true`).
+ *
+ * Revives tagged values through their transformers and unwraps escaped
+ * plain objects (see `jsonSerializer.escape.ts`).
+ */
+import { InvalidSerializedDataError, SerializationDepthError, TransformerError, isSerializationError, } from "@zudojs/errors";
+import { SerializationLimits, SerializationTags } from "@zudojs/constants";
+import { isPlainObject } from "@zudojs/types";
+import { escapedBody } from "./jsonSerializer.escape.js";
+import { defineKey } from "./jsonSerializer.keys.js";
+/** Longest prefix of a rejected tag quoted back in an error message. */
+const TAG_EXCERPT_LENGTH = 64;
+/** Clips a wire-supplied tag so it cannot flood an error message or a log line. */
+function describeTag(tag) {
+    return tag.length <= TAG_EXCERPT_LENGTH
+        ? tag
+        : `${tag.slice(0, TAG_EXCERPT_LENGTH)}…`;
+}
+/** Rebuilds runtime values from their tagged JSON representation. */
+export function restoreValue(walk, value, depth) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (depth >= walk.maxDepth) {
+        throw new SerializationDepthError(depth + 1, walk.maxDepth);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => restoreValue(walk, item, depth + 1));
+    }
+    const obj = value;
+    const strict = walk.options.strict === true;
+    const body = escapedBody(obj);
+    if (body)
+        return restoreEntries(walk, body, depth);
+    if (body === null && strict) {
+        throw new InvalidSerializedDataError('Escaped object tag "Object" must carry a plain-object $value.', { format: "json" });
+    }
+    const tag = obj[SerializationTags.TYPE];
+    if (body === undefined && typeof tag === "string") {
+        // The tag arrives from the wire, so bound it before it is looked up or
+        // quoted into a message: `SerializationLimits.MAX_TYPE_TAG_LENGTH` was
+        // exported and tested but never enforced, which let a 100 000-character
+        // tag be interpolated verbatim into an error and from there into a log.
+        if (tag.length > SerializationLimits.MAX_TYPE_TAG_LENGTH) {
+            throw new InvalidSerializedDataError(`Serialization type tag exceeds ${SerializationLimits.MAX_TYPE_TAG_LENGTH} characters ` +
+                `(got ${tag.length}): "${describeTag(tag)}".`, { format: "json" });
+        }
+        if (walk.transformers.has(tag))
+            return revive(walk, tag, obj, depth);
+        // An unknown tag is ordinary data unless the caller asked for strictness.
+        if (strict) {
+            throw new InvalidSerializedDataError(`Unknown serialization type tag: "${describeTag(tag)}". ` +
+                "Register a transformer for it, or deserialize without strict mode.", { format: "json" });
+        }
+    }
+    return isPlainObject(obj) ? restoreEntries(walk, obj, depth) : obj;
+}
+/**
+ * Hands a tag to its transformer after restoring the tag's children.
+ *
+ * A tag the transformer rejects (say an unparseable Date) used to make the
+ * whole record permanently unreadable. Outside strict mode it now reads back
+ * as the plain object it is; strict mode throws a typed `TransformerError`.
+ */
+function revive(walk, tag, obj, depth) {
+    const shell = restoreEntries(walk, obj, depth, SerializationTags.TYPE);
+    try {
+        return walk.transformers.get(tag).deserialize(shell, walk.options);
+    }
+    catch (error) {
+        if (walk.options.strict !== true)
+            return shell;
+        if (isSerializationError(error))
+            throw error;
+        throw new TransformerError(tag, error.message, { cause: error });
+    }
+}
+/** Restores each own key of a plain object into a fresh object. */
+function restoreEntries(walk, obj, depth, verbatimKey) {
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        defineKey(result, key, key === verbatimKey ? obj[key] : restoreValue(walk, obj[key], depth + 1), walk.options.allowUnsafeKeys === true);
+    }
+    return result;
+}
+//# sourceMappingURL=jsonSerializer.restore.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * @zudojs/serialization — Serialize-side walker (`preserveTypes: true`).
+ *
+ * Replaces values that have a registered transformer with their tagged form,
+ * 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";
+/** What the walker needs besides the value. */
+export interface TransformWalk {
+    readonly transformers: TransformerRegistry;
+    readonly maxDepth: number;
+    readonly options: SerializeOptions;
+}
+/** Converts a value into its JSON-safe, tagged representation. */
+export declare function transformValue(walk: TransformWalk, value: unknown, depth: number): unknown;
+//# sourceMappingURL=jsonSerializer.transform.d.ts.map

package/dist/serializerJson/jsonSerializer.transform.js

@@ -0,0 +1,59 @@
+/**
+ * @zudojs/serialization — Serialize-side walker (`preserveTypes: true`).
+ *
+ * Replaces values that have a registered transformer with their tagged form,
+ * and escapes plain objects that would otherwise read back as a tag.
+ */
+import { SerializationDepthError } from "@zudojs/errors";
+import { isPlainObject } from "@zudojs/types";
+import { escapeObject, needsEscape } from "./jsonSerializer.escape.js";
+import { defineKey } from "./jsonSerializer.keys.js";
+/** Converts a value into its JSON-safe, tagged representation. */
+export function transformValue(walk, value, depth) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "bigint") {
+        const transformer = walk.transformers.findForValue(value);
+        return transformer
+            ? transformer.serialize(value, walk.options)
+            : value.toString();
+    }
+    if (typeof value !== "object")
+        return value;
+    if (depth >= walk.maxDepth) {
+        // Depth is pre-checked by assertDepthWithinLimit, so this is a belt-and
+        // braces guard. Returning the raw value would silently emit an untagged
+        // Map or Date, which cannot round-trip — fail loudly instead.
+        throw new SerializationDepthError(depth + 1, walk.maxDepth);
+    }
+    if (Array.isArray(value)) {
+        const out = [];
+        for (let i = 0; i < value.length; i++) {
+            out.push(transformValue(walk, value[i], depth + 1));
+        }
+        return out;
+    }
+    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);
+    }
+    if (isPlainObject(value)) {
+        const body = transformEntries(walk, value, depth);
+        return needsEscape(value) ? escapeObject(body) : body;
+    }
+    return value;
+}
+/** Transforms each own enumerable key of a plain object. */
+function transformEntries(walk, value, depth) {
+    const result = {};
+    for (const key of Object.keys(value)) {
+        defineKey(result, key, transformValue(walk, value[key], depth + 1), walk.options.allowUnsafeKeys === true);
+    }
+    return result;
+}
+//# sourceMappingURL=jsonSerializer.transform.js.map

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

@@ -5,12 +5,18 @@
  * Provides a clean public API for creating serializers without
  * exposing concrete class constructors.
  */
-import type { Serializer, SerializationFormat } from "../serializerTypes/index.js";
+import type { Serializer, SerializationFormat, SerializeOptions, DeserializeOptions } from "../serializerTypes/index.js";
 import { SerializationFormat as Format } from "@zudojs/constants";
 import { TransformerRegistry } from "../serializerTransforms/index.js";
 import { SerializerRegistry } from "./serializerRegistry.core.js";
-/** Options accepted when creating a serializer. */
-export interface CreateSerializerOptions {
+/**
+ * Options accepted when creating a serializer.
+ *
+ * Every serialize/deserialize option (`pretty`, `preserveTypes`, `maxDepth`,
+ * `maxSize`, `strict`, `allowUnsafeKeys`, ...) is accepted as a per-instance
+ * default that each call can still override.
+ */
+export interface CreateSerializerOptions extends SerializeOptions, DeserializeOptions {
     /** Transformer registry to use instead of the built-in one. */
     readonly transformers?: TransformerRegistry;
     /** Pretty-print by default. Overridable per call. */

package/dist/serializerRegistry/serializerRegistry.factory.js

@@ -12,19 +12,13 @@ import { TransformerRegistry } from "../serializerTransforms/index.js";
 import { SerializerRegistry } from "./serializerRegistry.core.js";
 export function createSerializer(format, options) {
     switch (format) {
-        case Format.JSON:
-            // `pretty` and `preserveTypes` used to be accepted and thrown away.
-            // They are now carried as per-instance defaults that each call can
-            // still override.
-            return new JSONSerializer({
-                transformers: options?.transformers,
-                defaults: {
-                    ...(options?.pretty !== undefined ? { pretty: options.pretty } : {}),
-                    ...(options?.preserveTypes !== undefined
-                        ? { preserveTypes: options.preserveTypes }
-                        : {}),
-                },
-            });
+        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 defaults = Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined));
+            return new JSONSerializer({ transformers, defaults });
+        }
         default:
             throw new UnsupportedSerializationFormatError(format);
     }

package/dist/serializerTransforms/bigint.transformer.js

@@ -4,8 +4,18 @@
  * Preserves BigInt values across serialization boundaries
  * using string representation.
  */
-import { SerializationTags } from "@zudojs/constants";
+import { SerializationLimits, SerializationTags } from "@zudojs/constants";
+import { InvalidSerializedDataError, SerializeError } from "@zudojs/errors";
 const BIGINT_TYPE = "BigInt";
+/**
+ * Most decimal digits a BigInt may carry across the wire. `BigInt(raw)` is
+ * super-linear in the digit count, so one 10 MB `{"$type":"BigInt"}` payload
+ * used to stall a consumer for seconds. Shared with `@zudojs/schema`'s
+ * coercion cap through `SerializationLimits.MAX_BIGINT_DIGITS`.
+ */
+const MAX_BIGINT_DIGITS = SerializationLimits.MAX_BIGINT_DIGITS;
+/** Plain decimal integer, bounded, as `bigint.toString()` writes it. */
+const BIGINT_PATTERN = new RegExp(`^-?\\d{1,${MAX_BIGINT_DIGITS}}$`);
 /** Transformer that handles BigInt round-trips. */
 export const BigIntTransformer = {
     type: BIGINT_TYPE,
@@ -13,23 +23,27 @@ export const BigIntTransformer = {
         return typeof value === "bigint";
     },
     serialize(value) {
+        const text = value.toString();
+        if (!BIGINT_PATTERN.test(text)) {
+            throw new SerializeError(`BigInt exceeds ${MAX_BIGINT_DIGITS} digits and could not be read back.`);
+        }
         return {
             [SerializationTags.TYPE]: BIGINT_TYPE,
-            [SerializationTags.VALUE]: value.toString(),
+            [SerializationTags.VALUE]: text,
         };
     },
     deserialize(value) {
         const data = value;
         const raw = data[SerializationTags.VALUE];
         if (typeof raw !== "string") {
-            throw new Error(`Invalid BigInt serialized value: expected string, got ${typeof raw}`);
-        }
-        try {
-            return BigInt(raw);
+            throw new InvalidSerializedDataError(`Invalid BigInt serialized value: expected string, got ${typeof raw}`);
         }
-        catch {
-            throw new Error(`Cannot parse BigInt from: "${raw}"`);
+        // Checked before `BigInt()` runs, so an oversized value costs a regex
+        // scan bounded by the digit limit rather than a multi-second parse.
+        if (!BIGINT_PATTERN.test(raw)) {
+            throw new InvalidSerializedDataError(`Invalid BigInt serialized value: expected at most ${MAX_BIGINT_DIGITS} decimal digits`);
         }
+        return BigInt(raw);
     },
 };
 //# sourceMappingURL=bigint.transformer.js.map

package/dist/serializerTransforms/date.transformer.js

@@ -5,6 +5,7 @@
  * using ISO-8601 string representation.
  */
 import { SerializationTags } from "@zudojs/constants";
+import { InvalidSerializedDataError, SerializeError } from "@zudojs/errors";
 const DATE_TYPE = "Date";
 /** Transformer that handles Date round-trips. */
 export const DateTransformer = {
@@ -13,6 +14,9 @@ export const DateTransformer = {
         return value instanceof Date;
     },
     serialize(value) {
+        if (Number.isNaN(value.getTime())) {
+            throw new SerializeError("Cannot serialize an invalid Date.");
+        }
         return {
             [SerializationTags.TYPE]: DATE_TYPE,
             [SerializationTags.VALUE]: value.toISOString(),
@@ -22,11 +26,11 @@ export const DateTransformer = {
         const data = value;
         const raw = data[SerializationTags.VALUE];
         if (typeof raw !== "string") {
-            throw new Error(`Invalid Date serialized value: expected string, got ${typeof raw}`);
+            throw new InvalidSerializedDataError(`Invalid Date serialized value: expected string, got ${typeof raw}`);
         }
         const date = new Date(raw);
         if (Number.isNaN(date.getTime())) {
-            throw new Error(`Invalid Date value: "${raw}"`);
+            throw new InvalidSerializedDataError(`Invalid Date value: "${raw}"`);
         }
         return date;
     },

package/dist/serializerTransforms/map.transformer.js

@@ -5,6 +5,7 @@
  * using an array-of-entries representation.
  */
 import { SerializationTags } from "@zudojs/constants";
+import { InvalidSerializedDataError } from "@zudojs/errors";
 const MAP_TYPE = "Map";
 /** Transformer that handles Map round-trips. */
 export const MapTransformer = {
@@ -26,7 +27,7 @@ export const MapTransformer = {
         const data = value;
         const raw = data[SerializationTags.VALUE];
         if (!Array.isArray(raw)) {
-            throw new Error(`Invalid Map serialized value: expected array, got ${typeof raw}`);
+            throw new InvalidSerializedDataError(`Invalid Map serialized value: expected array, got ${typeof raw}`);
         }
         return new Map(raw);
     },

package/dist/serializerTransforms/set.transformer.js

@@ -5,6 +5,7 @@
  * using an array representation.
  */
 import { SerializationTags } from "@zudojs/constants";
+import { InvalidSerializedDataError } from "@zudojs/errors";
 const SET_TYPE = "Set";
 /** Transformer that handles Set round-trips. */
 export const SetTransformer = {
@@ -22,7 +23,7 @@ export const SetTransformer = {
         const data = value;
         const raw = data[SerializationTags.VALUE];
         if (!Array.isArray(raw)) {
-            throw new Error(`Invalid Set serialized value: expected array, got ${typeof raw}`);
+            throw new InvalidSerializedDataError(`Invalid Set serialized value: expected array, got ${typeof raw}`);
         }
         return new Set(raw);
     },

package/dist/serializerTransforms/transformerRegistry.core.d.ts

@@ -13,7 +13,11 @@ import type { TypeTransformer } from "../serializerTypes/index.js";
  */
 export declare class TransformerRegistry {
     private readonly transformers;
-    /** Register a transformer. Throws if the registry is full. */
+    /**
+     * Register a transformer.
+     *
+     * @throws {TransformerError} when the registry is already full.
+     */
     register(transformer: TypeTransformer): void;
     /** Unregister a transformer by type tag. */
     unregister(type: string): boolean;

package/dist/serializerTransforms/transformerRegistry.core.js

@@ -4,7 +4,7 @@
  * Manages type transformers that handle custom JS types during
  * serialization and deserialization. Keyed by type tag string.
  */
-import { TransformerNotFoundError } from "@zudojs/errors";
+import { TransformerError, TransformerNotFoundError } from "@zudojs/errors";
 import { SerializationLimits } from "@zudojs/constants";
 /**
  * Registry of type transformers keyed by their type tag.
@@ -14,10 +14,14 @@ import { SerializationLimits } from "@zudojs/constants";
  */
 export class TransformerRegistry {
     transformers = new Map();
-    /** Register a transformer. Throws if the registry is full. */
+    /**
+     * Register a transformer.
+     *
+     * @throws {TransformerError} when the registry is already full.
+     */
     register(transformer) {
         if (this.transformers.size >= SerializationLimits.MAX_TRANSFORMERS) {
-            throw new Error(`Maximum transformer limit (${SerializationLimits.MAX_TRANSFORMERS}) reached.`);
+            throw new TransformerError(transformer.type, `Maximum transformer limit (${SerializationLimits.MAX_TRANSFORMERS}) reached.`);
         }
         this.transformers.set(transformer.type, transformer);
     }

package/dist/serializerTransformsExt/buffer.transformer.js

@@ -5,6 +5,7 @@
  * using base64 encoding.
  */
 import { SerializationTags } from "@zudojs/constants";
+import { InvalidSerializedDataError } from "@zudojs/errors";
 import { toBase64, fromBase64 } from "./encoding.utils.js";
 const BUFFER_TYPE = "Buffer";
 /** Transformer that handles Uint8Array round-trips. */
@@ -24,7 +25,7 @@ export const BufferTransformer = {
         const data = value;
         const raw = data[SerializationTags.VALUE];
         if (typeof raw !== "string") {
-            throw new Error(`Invalid Buffer serialized value: expected string, got ${typeof raw}`);
+            throw new InvalidSerializedDataError(`Invalid Buffer serialized value: expected string, got ${typeof raw}`);
         }
         return fromBase64(raw);
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/serialization",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Data translation layer with JSON serializer, type transformers, envelopes, and registry for Zudojs applications.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,10 +19,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@zudojs/constants": "1.0.1",
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/types": "1.0.0",
-    "@zudojs/validation": "1.0.1"
+    "@zudojs/constants": "1.1.1",
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/types": "1.1.1",
+    "@zudojs/validation": "1.0.3"
   },
   "devDependencies": {
     "typescript": "7.0.2",