@zudojs/serialization 1.1.0 → 1.2.0

package/README.md

@@ -70,13 +70,37 @@ const registry = new TransformerRegistry();
 registry.register({
   type: "Money",
   canSerialize: (v): v is Money => v instanceof Money,
-  serialize: (v) => ({ $type: "Money", $value: v.toString() }),
+  serialize: (v) => (v as Money).toString(), // wrapped as { $type: "Money", $value: "..." }
   deserialize: (v) => Money.parse((v as { $value: string }).$value),
 });
 
 const serializer = new JSONSerializer({ transformers: registry });
+// Money uses your transformer; Date, BigInt, Map, Set, Buffer and Error still
+// use the built-ins.
 ```
 
+Your registry is consulted first, so registering a tag the built-ins use (say
+`"Date"`) replaces that built-in. Transformers you add to the registry later are
+picked up.
+
+**The transformer contract.** On the wire a transformed value is always
+`{ "$type": <type>, "$value": ... }`.
+
+- `serialize` returns either just the value to store, which the serializer
+  wraps as `{ $type: type, $value: <returned> }`, or that full tagged object
+  itself (as the built-ins do). A plain object with its own string `$type` is
+  taken as the full tagged object; anything else is wrapped. Special values
+  nested inside what you return (a `Date`, a `BigInt`) are transformed too.
+- `deserialize` always receives the full tagged object, with nested values
+  already restored, whichever form `serialize` returned. Read `$value` from it.
+
+**Opting out of the built-ins.** Pass `builtins: false` (to `JSONSerializer`
+or `createSerializer`) to use only your registry. A value that no transformer
+handles and that JSON would write as `{}` (a `Map`, `Set`, `WeakMap`, `Error`,
+`RegExp`, `ArrayBuffer`, ...) then throws `SerializeError` under
+`preserveTypes` instead of being silently emptied. To compose a registry by
+hand, start from `createBuiltinTransformers()`.
+
 ## Untrusted input
 
 `deserialize` is the boundary that matters — the string arrives from a queue, an

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/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

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

package/dist/serializerJson/index.js

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

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

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

package/dist/serializerJson/jsonSerializer.core.js

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

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

package/dist/serializerJson/jsonSerializer.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/serializerJson/jsonSerializer.transform.d.ts

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

package/dist/serializerJson/jsonSerializer.transform.js

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

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

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

package/dist/serializerRegistry/serializerRegistry.factory.js

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

package/dist/serializerTransformPolicy/index.d.ts

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

package/dist/serializerTransformPolicy/index.js

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

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

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

package/dist/serializerTransformPolicy/transformerLookup.core.js

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

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

@@ -0,0 +1,24 @@
+/**
+ * @zudojs/serialization — Transformer output and lossy-value checks.
+ */
+import type { TypeTransformer } from "../serializerTypes/index.js";
+/**
+ * Normalises what a transformer's `serialize` returned into the tagged
+ * `{ $type, $value }` form that is written to the wire.
+ *
+ * A transformer may return the full tagged object (the built-ins do; any
+ * plain object with its own string `$type` is taken as-is), or just the
+ * value to store, which is wrapped as `{ $type: transformer.type, $value }`.
+ * Before, a bare return was written untagged and could never be revived.
+ */
+export declare function toTaggedOutput(transformer: TypeTransformer, raw: unknown): Record<string, unknown>;
+/**
+ * Throws when a value that no transformer handles would be written as `{}`
+ * (a `Map`, `Set`, `Error`, `RegExp`, ...), instead of silently losing its
+ * contents. Only reachable when the built-in transformers are disabled or
+ * a type has no transformer.
+ *
+ * @throws {SerializeError} naming the type and how to fix it.
+ */
+export declare function assertNotLossy(value: object): void;
+//# sourceMappingURL=transformerOutput.helper.d.ts.map

package/dist/serializerTransformPolicy/transformerOutput.helper.js

@@ -0,0 +1,58 @@
+/**
+ * @zudojs/serialization — Transformer output and lossy-value checks.
+ */
+import { SerializationTags } from "@zudojs/constants";
+import { SerializeError } from "@zudojs/errors";
+import { isPlainObject } from "@zudojs/types";
+/**
+ * Normalises what a transformer's `serialize` returned into the tagged
+ * `{ $type, $value }` form that is written to the wire.
+ *
+ * A transformer may return the full tagged object (the built-ins do; any
+ * plain object with its own string `$type` is taken as-is), or just the
+ * value to store, which is wrapped as `{ $type: transformer.type, $value }`.
+ * Before, a bare return was written untagged and could never be revived.
+ */
+export function toTaggedOutput(transformer, raw) {
+    if (isPlainObject(raw) &&
+        Object.hasOwn(raw, SerializationTags.TYPE) &&
+        typeof raw[SerializationTags.TYPE] === "string") {
+        return raw;
+    }
+    return {
+        [SerializationTags.TYPE]: transformer.type,
+        [SerializationTags.VALUE]: raw,
+    };
+}
+/** Built-in objects whose JSON form silently drops their contents. */
+const LOSSY_TYPES = [
+    ["Map", (value) => value instanceof Map],
+    ["Set", (value) => value instanceof Set],
+    ["WeakMap", (value) => value instanceof WeakMap],
+    ["WeakSet", (value) => value instanceof WeakSet],
+    ["WeakRef", (value) => value instanceof WeakRef],
+    ["Promise", (value) => value instanceof Promise],
+    ["RegExp", (value) => value instanceof RegExp],
+    ["Error", (value) => value instanceof Error],
+    ["ArrayBuffer", (value) => value instanceof ArrayBuffer],
+    ["DataView", (value) => value instanceof DataView],
+];
+/**
+ * Throws when a value that no transformer handles would be written as `{}`
+ * (a `Map`, `Set`, `Error`, `RegExp`, ...), instead of silently losing its
+ * contents. Only reachable when the built-in transformers are disabled or
+ * a type has no transformer.
+ *
+ * @throws {SerializeError} naming the type and how to fix it.
+ */
+export function assertNotLossy(value) {
+    for (const [name, matches] of LOSSY_TYPES) {
+        if (matches(value)) {
+            throw new SerializeError(`Cannot serialize a ${name} with preserveTypes: no transformer is ` +
+                `registered for it, and JSON would write it as {} and lose its ` +
+                `contents. Register a transformer for ${name}, or keep the ` +
+                `built-in transformers enabled (do not pass builtins: false).`, { format: "json" });
+        }
+    }
+}
+//# sourceMappingURL=transformerOutput.helper.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/serialization",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Data translation layer with JSON serializer, type transformers, envelopes, and registry for Zudojs applications.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,14 +19,14 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@zudojs/constants": "1.1.0",
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/types": "1.1.0",
-    "@zudojs/validation": "1.0.2"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/types": "1.2.0",
+    "@zudojs/validation": "1.1.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "license": "MIT",
   "author": {
@@ -46,7 +46,7 @@
     "node": ">=24.0.0"
   },
   "module": "./dist/index.js",
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-serialization",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },