@zudojs/serialization 1.0.0 → 1.1.0

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 });
@@ -81,13 +89,35 @@ RPC peer or a request body.
   is plain `JSON.parse`, where `__proto__` survives as an inert own property and
   never reaches the prototype — but do not spread or deep-merge such an object
   into another without screening its keys.
-- **Input is size-bounded** by `maxSize`, and depth-bounded by `maxDepth`.
-- **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.
+- **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.
+- **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/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) {
@@ -42,17 +58,24 @@ export class JSONSerializer {
         if (opts.preserveTypes === true) {
             assertNoCircularReference(value);
             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
+        // limit the caller asked for must still be enforced: `maxDepth` used to
+        // be read only when `preserveTypes` was on, so a per-call or per-instance
+        // limit was silently ignored on the path most callers use.
+        if (opts.maxDepth !== undefined) {
+            assertDepthWithinLimit(value, maxDepth);
+        }
         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) {
@@ -62,138 +85,28 @@ 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 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}`);
+            return restoreValue({ transformers: this.transformers, maxDepth, options: opts }, parsed, 0);
         }
-        if (Array.isArray(value)) {
-            return value.map((item) => this.restoreValue(item, depth + 1, maxDepth, options));
+        // Same contract on the fast path: an explicit `maxDepth` bounds input
+        // that arrives from the wire, whether or not types are being restored.
+        if (opts.maxDepth !== undefined) {
+            assertDepthWithinLimit(parsed, opts.maxDepth);
         }
-        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;
+        return parsed;
     }
-    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,70 @@
+/**
+ * @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 { SerializationTags } from "@zudojs/constants";
+import { isPlainObject } from "@zudojs/types";
+import { escapedBody } from "./jsonSerializer.escape.js";
+import { defineKey } from "./jsonSerializer.keys.js";
+/** 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") {
+        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: "${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/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.0",
+  "version": "1.1.0",
   "description": "Data translation layer with JSON serializer, type transformers, envelopes, and registry for Zudojs applications.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,16 +19,20 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@zudojs/constants": "1.0.0",
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/types": "1.0.0",
-    "@zudojs/validation": "1.0.0"
+    "@zudojs/constants": "1.1.0",
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/types": "1.1.0",
+    "@zudojs/validation": "1.0.2"
   },
   "devDependencies": {
     "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "keywords": [
     "zudojs",
     "serialization",