@zudojs/serialization 1.1.0 → 1.1.1

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/jsonSerializer.core.js

@@ -56,7 +56,11 @@ 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 = transformValue({ transformers: this.transformers, maxDepth, options: opts }, value, 0);
             const json = opts.pretty

package/dist/serializerJson/jsonSerializer.restore.js

@@ -5,10 +5,18 @@
  * plain objects (see `jsonSerializer.escape.ts`).
  */
 import { InvalidSerializedDataError, SerializationDepthError, TransformerError, isSerializationError, } from "@zudojs/errors";
-import { SerializationTags } from "@zudojs/constants";
+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")
@@ -29,11 +37,19 @@ export function restoreValue(walk, value, depth) {
     }
     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: "${tag}". ` +
+            throw new InvalidSerializedDataError(`Unknown serialization type tag: "${describeTag(tag)}". ` +
                 "Register a transformer for it, or deserialize without strict mode.", { format: "json" });
         }
     }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/serialization",
-  "version": "1.1.0",
+  "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.1.0",
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/types": "1.1.0",
-    "@zudojs/validation": "1.0.2"
+    "@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",