@zudojs/serialization 1.2.3 → 1.3.0

package/dist/index.d.ts

@@ -37,7 +37,7 @@ export { BufferTransformer } from "./serializerTransformsExt/index.js";
 export { ErrorTransformer } from "./serializerTransformsExt/index.js";
 export { toBase64, fromBase64, encodeUtf8, decodeUtf8, } from "./serializerTransformsExt/index.js";
 export { createEnvelope, assertValidEnvelope, contentTypeForFormat, unwrapEnvelope, serializeToEnvelope, deserializeFromEnvelope, } from "./serializerEnvelope/index.js";
+export type { EnvelopeMetadataOptions } from "./serializerEnvelope/index.js";
 export { SerializerRegistry } from "./serializerRegistry/index.js";
 export { createSerializer, createDefaultRegistry, } from "./serializerRegistry/index.js";
 export type { CreateSerializerOptions } from "./serializerRegistry/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -42,4 +42,3 @@ export { createEnvelope, assertValidEnvelope, contentTypeForFormat, unwrapEnvelo
 // ─── Registry & Factory ───────────────────────────────────────
 export { SerializerRegistry } from "./serializerRegistry/index.js";
 export { createSerializer, createDefaultRegistry, } from "./serializerRegistry/index.js";
-//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * @zudojs/serialization — Envelope assertions.
+ *
+ * Shape and version checks for envelopes produced here and received from
+ * the wire.
+ */
+import type { SerializedEnvelope } from "../serializerTypes/index.js";
+/**
+ * Rejects a wire-format version this build cannot read back.
+ *
+ * `createEnvelope(data, "json", { version: 2 })` used to be accepted and
+ * then refused by `unwrapEnvelope` in the same process, because callers took
+ * `version` for their own schema version.
+ *
+ * @throws {SerializationError} for a non-integer, non-positive or too-new version.
+ */
+export declare function assertProducibleVersion(version: number): void;
+/**
+ * Validates that a value received from the wire is a well-formed envelope.
+ *
+ * @param envelope - The candidate envelope.
+ * @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;

package/dist/serializerEnvelope/envelope.assert.js

@@ -0,0 +1,69 @@
+/**
+ * @zudojs/serialization — Envelope assertions.
+ *
+ * Shape and version checks for envelopes produced here and received from
+ * the wire.
+ */
+import { SERIALIZATION_SCHEMA_VERSION } from "@zudojs/constants";
+import { InvalidSerializedDataError, SerializationError } from "@zudojs/errors";
+/**
+ * Rejects a wire-format version this build cannot read back.
+ *
+ * `createEnvelope(data, "json", { version: 2 })` used to be accepted and
+ * then refused by `unwrapEnvelope` in the same process, because callers took
+ * `version` for their own schema version.
+ *
+ * @throws {SerializationError} for a non-integer, non-positive or too-new version.
+ */
+export function assertProducibleVersion(version) {
+    if (!Number.isInteger(version) ||
+        version < 1 ||
+        version > SERIALIZATION_SCHEMA_VERSION) {
+        throw new SerializationError(`Envelope version must be an integer between 1 and ${SERIALIZATION_SCHEMA_VERSION} (the wire-format version); ` +
+            `got ${String(version)}. Put your message's own version in metadata.schemaVersion.`, { format: "envelope" });
+    }
+}
+/**
+ * Validates that a value received from the wire is a well-formed envelope.
+ *
+ * @param envelope - The candidate envelope.
+ * @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 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 InvalidSerializedDataError("Malformed envelope: missing metadata", { format: "envelope" });
+    }
+    const metadata = candidate.metadata;
+    if (typeof metadata.format !== "string" || metadata.format.length === 0) {
+        throw new InvalidSerializedDataError("Malformed envelope: metadata.format is missing", { format: "envelope" });
+    }
+    if (typeof candidate.data !== "string" &&
+        !(candidate.data instanceof Uint8Array)) {
+        throw new InvalidSerializedDataError("Malformed envelope: data must be a string or Uint8Array", { format: "envelope" });
+    }
+    if (metadata.type !== undefined && typeof metadata.type !== "string") {
+        throw new InvalidSerializedDataError("Malformed envelope: metadata.type must be a string", { format: "envelope" });
+    }
+    if (metadata.schemaVersion !== undefined &&
+        typeof metadata.schemaVersion !== "string" &&
+        typeof metadata.schemaVersion !== "number") {
+        throw new InvalidSerializedDataError("Malformed envelope: metadata.schemaVersion must be a string or number", { 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 InvalidSerializedDataError(`Malformed envelope: metadata.version must be an integer, got ${String(metadata.version)}`, { format: "envelope" });
+        }
+        if (metadata.version > SERIALIZATION_SCHEMA_VERSION) {
+            throw new InvalidSerializedDataError(`Unsupported envelope wire-format version ${metadata.version}: this build understands up to ${SERIALIZATION_SCHEMA_VERSION}`, { format: "envelope" });
+        }
+    }
+}

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

@@ -6,6 +6,23 @@
  * messaging, queues, RPC, and cross-service communication.
  */
 import type { SerializedEnvelope, SerializedValue, SerializeOptions, DeserializeOptions } from "../serializerTypes/index.js";
+export { assertValidEnvelope } from "./envelope.assert.js";
+/** Application-level metadata a producer may stamp on an envelope. */
+export interface EnvelopeMetadataOptions {
+    /**
+     * Wire-format version. Defaults to, and may not exceed,
+     * `SERIALIZATION_SCHEMA_VERSION`; pass a lower value only to produce an
+     * envelope for an older consumer. Not the version of your message shape:
+     * that is `schemaVersion`.
+     */
+    readonly version?: number;
+    readonly contentType?: string;
+    readonly encoding?: string;
+    /** Name of the payload (`"OrderPlaced"`), carried verbatim. */
+    readonly type?: string;
+    /** Version of the payload's shape, carried verbatim. */
+    readonly schemaVersion?: number | string;
+}
 /**
  * Create a serialization envelope wrapping data with metadata.
  *
@@ -13,12 +30,10 @@ import type { SerializedEnvelope, SerializedValue, SerializeOptions, Deserialize
  * @param format - The serialization format used (default: "json").
  * @param options - Additional metadata options.
  * @returns A SerializedEnvelope with metadata and data.
+ * @throws {SerializationError} when `options.version` is not a wire-format
+ *   version this build can read back.
  */
-export declare function createEnvelope(data: SerializedValue, format?: string, options?: {
-    readonly version?: number;
-    readonly contentType?: string;
-    readonly encoding?: string;
-}): SerializedEnvelope;
+export declare function createEnvelope(data: SerializedValue, format?: string, options?: EnvelopeMetadataOptions): SerializedEnvelope;
 /**
  * Maps a format identifier to its MIME content type.
  *
@@ -26,16 +41,6 @@ export declare function createEnvelope(data: SerializedValue, format?: string, o
  * a msgpack payload ends up labelled as JSON on the wire.
  */
 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 {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;
 /**
  * Extract the data from an envelope, validating metadata.
  *
@@ -56,12 +61,14 @@ export declare function unwrapEnvelope(envelope: SerializedEnvelope, expectedFor
  *   the helper could only ever call `serialize(value)`, so `preserveTypes`,
  *   `pretty` and the size/depth limits were unreachable through an envelope
  *   unless they happened to be baked into the serializer instance.
+ * @param metadata - Application metadata (`type`, `schemaVersion`) to stamp
+ *   on the envelope.
  * @returns A SerializedEnvelope containing the serialized data.
  */
 export declare function serializeToEnvelope<T>(value: T, serializer: {
     serialize: (v: T, options?: SerializeOptions) => string;
     contentType?: string;
-}, format?: string, options?: SerializeOptions): SerializedEnvelope;
+}, format?: string, options?: SerializeOptions, metadata?: Pick<EnvelopeMetadataOptions, "type" | "schemaVersion">): SerializedEnvelope;
 /**
  * Unwrap an envelope and deserialize the data.
  *
@@ -77,4 +84,3 @@ export declare function serializeToEnvelope<T>(value: T, serializer: {
 export declare function deserializeFromEnvelope<T>(envelope: SerializedEnvelope, deserializer: {
     deserialize: <U>(v: string, options?: DeserializeOptions) => U;
 }, expectedFormat?: string, options?: DeserializeOptions): T;
-//# sourceMappingURL=envelope.core.d.ts.map

package/dist/serializerEnvelope/envelope.core.js

@@ -8,6 +8,8 @@
 import { SerializationFormat, SerializationContentType, SERIALIZATION_SCHEMA_VERSION, } from "@zudojs/constants";
 import { InvalidSerializedDataError } from "@zudojs/errors";
 import { decodeUtf8 } from "../serializerTransformsExt/index.js";
+import { assertProducibleVersion, assertValidEnvelope, } from "./envelope.assert.js";
+export { assertValidEnvelope } from "./envelope.assert.js";
 /**
  * Create a serialization envelope wrapping data with metadata.
  *
@@ -15,14 +17,22 @@ import { decodeUtf8 } from "../serializerTransformsExt/index.js";
  * @param format - The serialization format used (default: "json").
  * @param options - Additional metadata options.
  * @returns A SerializedEnvelope with metadata and data.
+ * @throws {SerializationError} when `options.version` is not a wire-format
+ *   version this build can read back.
  */
 export function createEnvelope(data, format = SerializationFormat.JSON, options = {}) {
+    const version = options.version ?? SERIALIZATION_SCHEMA_VERSION;
+    assertProducibleVersion(version);
     return {
         metadata: {
             format,
-            version: options.version ?? SERIALIZATION_SCHEMA_VERSION,
+            version,
             contentType: options.contentType ?? contentTypeForFormat(format),
             encoding: options.encoding ?? "utf-8",
+            ...(options.type !== undefined ? { type: options.type } : {}),
+            ...(options.schemaVersion !== undefined
+                ? { schemaVersion: options.schemaVersion }
+                : {}),
         },
         data,
     };
@@ -48,42 +58,6 @@ export function contentTypeForFormat(format) {
             return "application/octet-stream";
     }
 }
-/**
- * Validates that a value received from the wire is a well-formed envelope.
- *
- * @param envelope - The candidate envelope.
- * @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 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 InvalidSerializedDataError("Malformed envelope: missing metadata", { format: "envelope" });
-    }
-    const metadata = candidate.metadata;
-    if (typeof metadata.format !== "string" || metadata.format.length === 0) {
-        throw new InvalidSerializedDataError("Malformed envelope: metadata.format is missing", { format: "envelope" });
-    }
-    if (typeof candidate.data !== "string" &&
-        !(candidate.data instanceof 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 InvalidSerializedDataError(`Malformed envelope: metadata.version must be an integer, got ${String(metadata.version)}`, { format: "envelope" });
-        }
-        if (metadata.version > SERIALIZATION_SCHEMA_VERSION) {
-            throw new InvalidSerializedDataError(`Unsupported envelope schema version ${metadata.version}: this build understands up to ${SERIALIZATION_SCHEMA_VERSION}`, { format: "envelope" });
-        }
-    }
-}
 /**
  * Extract the data from an envelope, validating metadata.
  *
@@ -110,11 +84,14 @@ export function unwrapEnvelope(envelope, expectedFormat) {
  *   the helper could only ever call `serialize(value)`, so `preserveTypes`,
  *   `pretty` and the size/depth limits were unreachable through an envelope
  *   unless they happened to be baked into the serializer instance.
+ * @param metadata - Application metadata (`type`, `schemaVersion`) to stamp
+ *   on the envelope.
  * @returns A SerializedEnvelope containing the serialized data.
  */
-export function serializeToEnvelope(value, serializer, format = SerializationFormat.JSON, options) {
+export function serializeToEnvelope(value, serializer, format = SerializationFormat.JSON, options, metadata = {}) {
     const data = serializer.serialize(value, options);
     return createEnvelope(data, format, {
+        ...metadata,
         contentType: serializer.contentType,
     });
 }
@@ -141,4 +118,3 @@ export function deserializeFromEnvelope(envelope, deserializer, expectedFormat,
     }
     return deserializer.deserialize(decodeUtf8(data), options);
 }
-//# sourceMappingURL=envelope.core.js.map

package/dist/serializerEnvelope/index.d.ts

@@ -4,4 +4,4 @@
  * Wraps serialized data with metadata for cross-service communication.
  */
 export { createEnvelope, assertValidEnvelope, contentTypeForFormat, unwrapEnvelope, serializeToEnvelope, deserializeFromEnvelope, } from "./envelope.core.js";
-//# sourceMappingURL=index.d.ts.map
+export type { EnvelopeMetadataOptions } from "./envelope.core.js";

package/dist/serializerEnvelope/index.js

@@ -4,4 +4,3 @@
  * Wraps serialized data with metadata for cross-service communication.
  */
 export { createEnvelope, assertValidEnvelope, contentTypeForFormat, unwrapEnvelope, serializeToEnvelope, deserializeFromEnvelope, } from "./envelope.core.js";
-//# sourceMappingURL=index.js.map

package/dist/serializerJson/index.d.ts

@@ -6,4 +6,3 @@
  */
 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

@@ -6,4 +6,3 @@
  */
 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

@@ -50,4 +50,3 @@ export declare class JSONSerializer implements Serializer<unknown, string> {
     /** Parses JSON, reporting malformed input as a typed error. */
     private parse;
 }
-//# sourceMappingURL=jsonSerializer.core.d.ts.map

package/dist/serializerJson/jsonSerializer.core.js

@@ -110,4 +110,3 @@ export class JSONSerializer {
         }
     }
 }
-//# sourceMappingURL=jsonSerializer.core.js.map

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

@@ -32,4 +32,3 @@ export declare function escapeObject(body: Record<string, unknown>): Record<stri
  * 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

@@ -47,4 +47,3 @@ export function escapedBody(value) {
     const body = value[SerializationTags.VALUE];
     return isPlainObject(body) ? body : null;
 }
-//# sourceMappingURL=jsonSerializer.escape.js.map

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

@@ -29,4 +29,3 @@ export declare function assertByteSize(json: string, maxSize: number, origin: "i
  * 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

@@ -52,4 +52,3 @@ export function defineKey(target, key, value, allowUnsafeKeys) {
         configurable: true,
     });
 }
-//# sourceMappingURL=jsonSerializer.keys.js.map

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

@@ -14,4 +14,3 @@ export interface RestoreWalk {
 }
 /** 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

@@ -87,4 +87,3 @@ function restoreEntries(walk, obj, depth, verbatimKey) {
     }
     return result;
 }
-//# sourceMappingURL=jsonSerializer.restore.js.map

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

@@ -14,4 +14,3 @@ export interface TransformWalk {
 }
 /** 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

@@ -57,4 +57,3 @@ function transformEntries(walk, value, depth) {
     }
     return result;
 }
-//# sourceMappingURL=jsonSerializer.transform.js.map

package/dist/serializerRegistry/index.d.ts

@@ -7,4 +7,3 @@
 export { SerializerRegistry } from "./serializerRegistry.core.js";
 export { createSerializer, createDefaultRegistry, } from "./serializerRegistry.factory.js";
 export type { CreateSerializerOptions } from "./serializerRegistry.factory.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/serializerRegistry/index.js

@@ -6,4 +6,3 @@
  */
 export { SerializerRegistry } from "./serializerRegistry.core.js";
 export { createSerializer, createDefaultRegistry, } from "./serializerRegistry.factory.js";
-//# sourceMappingURL=index.js.map

package/dist/serializerRegistry/serializerRegistry.core.d.ts

@@ -28,4 +28,3 @@ export declare class SerializerRegistry {
     /** Number of registered serializers. */
     get size(): number;
 }
-//# sourceMappingURL=serializerRegistry.core.d.ts.map

package/dist/serializerRegistry/serializerRegistry.core.js

@@ -45,4 +45,3 @@ export class SerializerRegistry {
         return this.serializers.size;
     }
 }
-//# sourceMappingURL=serializerRegistry.core.js.map

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

@@ -50,4 +50,3 @@ export declare function createSerializer(format: SerializationFormat, options?:
  * @returns A SerializerRegistry with "json" registered.
  */
 export declare function createDefaultRegistry(): SerializerRegistry;
-//# sourceMappingURL=serializerRegistry.factory.d.ts.map

package/dist/serializerRegistry/serializerRegistry.factory.js

@@ -37,4 +37,3 @@ export function createDefaultRegistry() {
     registry.register(createSerializer(Format.JSON));
     return registry;
 }
-//# sourceMappingURL=serializerRegistry.factory.js.map

package/dist/serializerTransformPolicy/index.d.ts

@@ -7,4 +7,3 @@
  */
 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

@@ -7,4 +7,3 @@
  */
 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

@@ -28,4 +28,3 @@ export declare function createBuiltinTransformers(): TransformerRegistry;
  * seen too.
  */
 export declare function layerTransformers(primary: TransformerLookup, fallback: TransformerLookup): TransformerLookup;
-//# sourceMappingURL=transformerLookup.core.d.ts.map

package/dist/serializerTransformPolicy/transformerLookup.core.js

@@ -34,4 +34,3 @@ export function layerTransformers(primary, fallback) {
         get: (type) => (primary.has(type) ? primary.get(type) : fallback.get(type)),
     };
 }
-//# sourceMappingURL=transformerLookup.core.js.map

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

@@ -24,4 +24,3 @@ export declare function toTaggedOutput(transformer: TypeTransformer, raw: unknow
  * @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

@@ -75,4 +75,3 @@ export function assertNotLossy(value) {
         }
     }
 }
-//# sourceMappingURL=transformerOutput.helper.js.map

package/dist/serializerTransforms/bigint.transformer.d.ts

@@ -7,4 +7,3 @@
 import type { TypeTransformer } from "../serializerTypes/index.js";
 /** Transformer that handles BigInt round-trips. */
 export declare const BigIntTransformer: TypeTransformer<bigint>;
-//# sourceMappingURL=bigint.transformer.d.ts.map

package/dist/serializerTransforms/bigint.transformer.js

@@ -46,4 +46,3 @@ export const BigIntTransformer = {
         return BigInt(raw);
     },
 };
-//# sourceMappingURL=bigint.transformer.js.map

package/dist/serializerTransforms/date.transformer.d.ts

@@ -7,4 +7,3 @@
 import type { TypeTransformer } from "../serializerTypes/index.js";
 /** Transformer that handles Date round-trips. */
 export declare const DateTransformer: TypeTransformer<Date>;
-//# sourceMappingURL=date.transformer.d.ts.map

package/dist/serializerTransforms/date.transformer.js

@@ -35,4 +35,3 @@ export const DateTransformer = {
         return date;
     },
 };
-//# sourceMappingURL=date.transformer.js.map

package/dist/serializerTransforms/index.d.ts

@@ -8,4 +8,3 @@ export { DateTransformer } from "./date.transformer.js";
 export { BigIntTransformer } from "./bigint.transformer.js";
 export { MapTransformer } from "./map.transformer.js";
 export { SetTransformer } from "./set.transformer.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/serializerTransforms/index.js

@@ -8,4 +8,3 @@ export { DateTransformer } from "./date.transformer.js";
 export { BigIntTransformer } from "./bigint.transformer.js";
 export { MapTransformer } from "./map.transformer.js";
 export { SetTransformer } from "./set.transformer.js";
-//# sourceMappingURL=index.js.map

package/dist/serializerTransforms/map.transformer.d.ts

@@ -7,4 +7,3 @@
 import type { TypeTransformer } from "../serializerTypes/index.js";
 /** Transformer that handles Map round-trips. */
 export declare const MapTransformer: TypeTransformer<Map<unknown, unknown>>;
-//# sourceMappingURL=map.transformer.d.ts.map

package/dist/serializerTransforms/map.transformer.js

@@ -32,4 +32,3 @@ export const MapTransformer = {
         return new Map(raw);
     },
 };
-//# sourceMappingURL=map.transformer.js.map

package/dist/serializerTransforms/set.transformer.d.ts

@@ -7,4 +7,3 @@
 import type { TypeTransformer } from "../serializerTypes/index.js";
 /** Transformer that handles Set round-trips. */
 export declare const SetTransformer: TypeTransformer<Set<unknown>>;
-//# sourceMappingURL=set.transformer.d.ts.map

package/dist/serializerTransforms/set.transformer.js

@@ -28,4 +28,3 @@ export const SetTransformer = {
         return new Set(raw);
     },
 };
-//# sourceMappingURL=set.transformer.js.map

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

@@ -34,4 +34,3 @@ export declare class TransformerRegistry {
     /** Number of registered transformers. */
     get size(): number;
 }
-//# sourceMappingURL=transformerRegistry.core.d.ts.map

package/dist/serializerTransforms/transformerRegistry.core.js

@@ -61,4 +61,3 @@ export class TransformerRegistry {
         return this.transformers.size;
     }
 }
-//# sourceMappingURL=transformerRegistry.core.js.map

package/dist/serializerTransformsExt/buffer.transformer.d.ts

@@ -7,4 +7,3 @@
 import type { TypeTransformer } from "../serializerTypes/index.js";
 /** Transformer that handles Uint8Array round-trips. */
 export declare const BufferTransformer: TypeTransformer<Uint8Array>;
-//# sourceMappingURL=buffer.transformer.d.ts.map

package/dist/serializerTransformsExt/buffer.transformer.js

@@ -30,4 +30,3 @@ export const BufferTransformer = {
         return fromBase64(raw);
     },
 };
-//# sourceMappingURL=buffer.transformer.js.map

package/dist/serializerTransformsExt/encoding.utils.d.ts

@@ -11,4 +11,3 @@ export declare function fromBase64(base64: string): Uint8Array;
 export declare function encodeUtf8(text: string): Uint8Array;
 /** Decode a Uint8Array to a string using UTF-8. */
 export declare function decodeUtf8(data: Uint8Array): string;
-//# sourceMappingURL=encoding.utils.d.ts.map

package/dist/serializerTransformsExt/encoding.utils.js

@@ -40,4 +40,3 @@ export function decodeUtf8(data) {
     }
     return Buffer.from(data).toString("utf-8");
 }
-//# sourceMappingURL=encoding.utils.js.map

package/dist/serializerTransformsExt/error.transformer.d.ts

@@ -10,4 +10,3 @@
 import type { TypeTransformer } from "../serializerTypes/index.js";
 /** Transformer that handles Error round-trips. */
 export declare const ErrorTransformer: TypeTransformer<Error>;
-//# sourceMappingURL=error.transformer.d.ts.map

package/dist/serializerTransformsExt/error.transformer.js

@@ -83,4 +83,3 @@ export const ErrorTransformer = {
         return error;
     },
 };
-//# sourceMappingURL=error.transformer.js.map

package/dist/serializerTransformsExt/index.d.ts

@@ -7,4 +7,3 @@
 export { BufferTransformer } from "./buffer.transformer.js";
 export { ErrorTransformer } from "./error.transformer.js";
 export { toBase64, fromBase64, encodeUtf8, decodeUtf8, } from "./encoding.utils.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/serializerTransformsExt/index.js

@@ -7,4 +7,3 @@
 export { BufferTransformer } from "./buffer.transformer.js";
 export { ErrorTransformer } from "./error.transformer.js";
 export { toBase64, fromBase64, encodeUtf8, decodeUtf8, } from "./encoding.utils.js";
-//# sourceMappingURL=index.js.map

package/dist/serializerTypes/index.d.ts

@@ -4,4 +4,3 @@
  * Core contracts for serializers, transformers, and serialization options.
  */
 export type { SerializationFormat, SerializedValue, SerializeOptions, DeserializeOptions, SerializationMetadata, SerializedEnvelope, Serializer, TypeTransformer, } from "./serializer.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/serializerTypes/index.js

@@ -4,4 +4,3 @@
  * Core contracts for serializers, transformers, and serialization options.
  */
 export {};
-//# sourceMappingURL=index.js.map

package/dist/serializerTypes/serializer.type.d.ts

@@ -63,12 +63,28 @@ export interface DeserializeOptions {
 export interface SerializationMetadata {
     /** The format used (e.g., "json"). */
     readonly format: string;
-    /** Schema version for forward/backward compatibility. */
+    /**
+     * Version of the envelope's wire format, i.e. `SERIALIZATION_SCHEMA_VERSION`
+     * (currently 1). It is owned by this package, not by the application: a
+     * consumer refuses an envelope whose version is newer than it understands.
+     * The version of *your* message shape belongs in {@link schemaVersion}.
+     */
     readonly version?: number;
     /** MIME content type (e.g., "application/json"). */
     readonly contentType?: string;
     /** Character encoding (e.g., "utf-8"). */
     readonly encoding?: string;
+    /**
+     * Application-level name of what the payload is (`"OrderPlaced"`), so a
+     * consumer can route an envelope without deserializing it first.
+     */
+    readonly type?: string;
+    /**
+     * Application-level version of the payload's shape (`2` or `"2026-01"`),
+     * for the consumer's own forward/backward compatibility handling. Carried
+     * verbatim; this package never interprets it.
+     */
+    readonly schemaVersion?: number | string;
 }
 /** An envelope wrapping serialized data with metadata. */
 export interface SerializedEnvelope {
@@ -116,4 +132,3 @@ export interface TypeTransformer<TValue = unknown> {
      */
     deserialize(value: unknown, options?: DeserializeOptions): TValue;
 }
-//# sourceMappingURL=serializer.type.d.ts.map

package/dist/serializerTypes/serializer.type.js

@@ -6,4 +6,3 @@
  * NOT available in @zudojs/types or @zudojs/constants.
  */
 export {};
-//# sourceMappingURL=serializer.type.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/serialization",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "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.4",
-    "@zudojs/errors": "1.3.2",
-    "@zudojs/types": "1.2.0",
-    "@zudojs/validation": "1.1.2"
+    "@zudojs/constants": "1.2.0",
+    "@zudojs/errors": "1.4.0",
+    "@zudojs/types": "1.3.0",
+    "@zudojs/validation": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",