@tsed/json-mapper 8.23.0 → 8.24.0

package/lib/esm/components/PrimitiveMapper.js

@@ -4,6 +4,9 @@ import { JsonMapper } from "../decorators/jsonMapper.js";
 function isNullish(data) {
     return [null, "null"].includes(data);
 }
+/**
+ * Error thrown when a primitive conversion cannot be performed safely.
+ */
 export class CastError extends Error {
     constructor(message) {
         super(`Cast error. ${message}`);

package/lib/esm/decorators/afterDeserialize.js

@@ -2,7 +2,7 @@ import { JsonEntityFn } from "@tsed/schema";
 /**
  * Call the function after JsonMapper.
  *
- * ## Example
+ * ### Example
  *
  * ```typescript
  * @AfterDeserialize((data: Model) => { // After deserialize get the instance class

package/lib/esm/decorators/beforeDeserialize.js

@@ -2,7 +2,7 @@ import { JsonEntityFn } from "@tsed/schema";
 /**
  * Call the function before JsonMapper.
  *
- * ## Example
+ * ### Example
  *
  * ```typescript
  * @BeforeDeserialize((data: Record<string, unknown>) => { // Before deserialize get the data

package/lib/esm/decorators/jsonMapper.js

@@ -1,8 +1,19 @@
 import { registerJsonTypeMapper } from "../domain/JsonMapperTypesContainer.js";
 /**
- * Register a new JsonMapper Type
- * @param types
- * @constructor
+ * Register a class as the mapper responsible for the given primitive/class tokens.
+ * The decorator instantiates the mapper and stores it inside the JSON mapper types container.
+ *
+ * ### Example
+ *
+ * ```ts
+ * @JsonMapper(MyCustomType)
+ * export class MyCustomTypeMapper implements JsonMapperMethods {
+ *   serialize() {/* ... *\/}
+ *   deserialize() {/* ... *\/}
+ * }
+ * ```
+ *
+ * @param types One or more constructors/symbols handled by the mapper.
  */
 export function JsonMapper(...types) {
     return (target) => {

package/lib/esm/decorators/onDeserialize.js

@@ -2,7 +2,7 @@ import { JsonEntityFn } from "@tsed/schema";
 /**
  * Call the function before property deserialization.
  *
- * ## Example
+ * ### Example
  *
  * ```typescript
  * class Model {

package/lib/esm/decorators/onSerialize.js

@@ -2,7 +2,7 @@ import { JsonEntityFn } from "@tsed/schema";
 /**
  * Call the function before property serialization.
  *
- * ## Example
+ * ### Example
  *
  * ```typescript
  * class Model {

package/lib/esm/domain/JsonDeserializer.js

@@ -26,6 +26,10 @@ function mapParamStoreOptions(store, options) {
         generics: store.parameter.schema().getGenericOf()
     };
 }
+/**
+ * Deserializes raw JSON data into class instances based on schema metadata,
+ * handling collections, discriminators, hooks, and registered type mappers.
+ */
 export class JsonDeserializer extends JsonMapperCompiler {
     constructor() {
         super();

package/lib/esm/domain/JsonMapperCompiler.js

@@ -1,4 +1,9 @@
 import { ancestorsOf, classOf, getRandomId, hasJsonMethod, isClass, isCollection, isDate, isMomentObject, isMongooseObject, isNil, isObject, isObjectID, isString, nameOf, objectKeys } from "@tsed/core";
+/**
+ * Base compiler that turns schema metadata into executable (de)serialization functions.
+ * Subclasses supply `map`, `alterValue`, and `createMapper` implementations to specialize
+ * the pipeline for serialization or deserialization.
+ */
 export class JsonMapperCompiler {
     constructor() {
         /**

package/lib/esm/domain/JsonMapperSettings.js

@@ -1,3 +1,6 @@
+/**
+ * Default runtime settings applied by the JSON mapper pipeline.
+ */
 export const JsonMapperSettings = {
     disableUnsecureConstructor: true,
     additionalProperties: false,

package/lib/esm/domain/JsonMapperTypesContainer.js

@@ -4,13 +4,13 @@
 // tslint:disable-next-line:variable-name
 const JsonMapperTypesContainer = new Map();
 /**
- * @ignore
+ * Register a mapper class for a specific primitive/complex type so it can be reused by the serializers.
  */
 export function registerJsonTypeMapper(type, token) {
     JsonMapperTypesContainer.set(type, new token());
 }
 /**
- * @ignore
+ * Retrieve the registry of custom JSON mapper instances keyed by the types they support.
  */
 export function getJsonMapperTypes() {
     return JsonMapperTypesContainer;

package/lib/esm/domain/JsonSerializer.js

@@ -19,6 +19,12 @@ function getBestType(type, obj) {
 function varKey(k) {
     return `__${k}`;
 }
+/**
+ * Serializes data structures according to the metadata captured by `@tsed/schema`.
+ *
+ * The serializer walks entity schemas, applies hooks, honors alias/group rules, and falls back to the
+ * registered type mappers (e.g., components in `src/components`).
+ */
 export class JsonSerializer extends JsonMapperCompiler {
     constructor() {
         super();

package/lib/esm/domain/Writer.js

@@ -1,3 +1,7 @@
+/**
+ * Tiny utility used by the mapper compilers to build executable arrow functions as strings.
+ * It provides helpers for scoping, branching, and composing mapper fragments before `eval`.
+ */
 export class Writer {
     static { this.object = {
         assign(...args) {

package/lib/esm/hooks/alterAfterDeserialize.js

@@ -1,3 +1,6 @@
+/**
+ * Trigger the `afterDeserialize` lifecycle in order to finalize instances after mapping.
+ */
 export function alterAfterDeserialize(data, schema, options) {
     return schema?.$hooks?.alter("afterDeserialize", data, [options]);
 }

package/lib/esm/hooks/alterBeforeDeserialize.js

@@ -1,3 +1,7 @@
+/**
+ * Trigger the `beforeDeserialize` hooks declared on the schema to massage raw payloads
+ * prior to property mapping.
+ */
 export function alterBeforeDeserialize(data, schema, options) {
     return schema?.$hooks?.alter("beforeDeserialize", data, [options]);
 }

package/lib/esm/hooks/alterOnDeserialize.js

@@ -1,3 +1,6 @@
+/**
+ * Execute the `onDeserialize` hooks registered on a schema before writing the value onto the target.
+ */
 export function alterOnDeserialize(schema, value, options) {
     return schema.$hooks.alter("onDeserialize", value, [options]);
 }

package/lib/esm/hooks/alterOnSerialize.js

@@ -1,3 +1,7 @@
+/**
+ * Execute the `onSerialize` hooks registered on a schema before emitting a value.
+ * Used internally by the serializer when a property exposes lifecycle hooks.
+ */
 export function alterOnSerialize(schema, value, options) {
     return schema.$hooks.alter("onSerialize", value, [options]);
 }

package/lib/esm/utils/deserialize.js

@@ -3,6 +3,17 @@ import "../components/PrimitiveMapper.js";
 import "../components/SymbolMapper.js";
 import { JsonDeserializer } from "../domain/JsonDeserializer.js";
 const deserializer = new JsonDeserializer();
+/**
+ * Deserialize arbitrary data into the provided model type using the shared `JsonDeserializer`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {deserialize} from "@tsed/json-mapper";
+ *
+ * const model = deserialize<UserModel>(payload, {type: UserModel, useAlias: true});
+ * ```
+ */
 export function deserialize(input, options) {
     return deserializer.map(input, options);
 }

package/lib/esm/utils/getObjectProperties.js

@@ -1,4 +1,7 @@
 import { isFunction } from "@tsed/core";
+/**
+ * Return enumerable entries of an object while skipping function values (methods/getters).
+ */
 export function getObjectProperties(obj) {
     return Object.entries(obj).filter(([, value]) => !isFunction(value));
 }

package/lib/esm/utils/serialize.js

@@ -3,6 +3,18 @@ import "../components/PrimitiveMapper.js";
 import "../components/SymbolMapper.js";
 import { JsonSerializer } from "../domain/JsonSerializer.js";
 const serializer = new JsonSerializer();
+/**
+ * Serialize any value using the shared `JsonSerializer` instance.
+ * Respects schema metadata, hooks, aliases, and registered custom mappers.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {serialize} from "@tsed/json-mapper";
+ *
+ * const payload = serialize(model, {type: UserModel, useAlias: true});
+ * ```
+ */
 export function serialize(input, options) {
     return serializer.map(input, options);
 }

package/lib/types/components/PrimitiveMapper.d.ts

@@ -1,4 +1,7 @@
 import { JsonMapperCtx, JsonMapperMethods } from "../interfaces/JsonMapperMethods.js";
+/**
+ * Error thrown when a primitive conversion cannot be performed safely.
+ */
 export declare class CastError extends Error {
     name: string;
     constructor(message: string);

package/lib/types/decorators/afterDeserialize.d.ts

@@ -5,7 +5,7 @@ export interface AfterDeserializeCallback {
 /**
  * Call the function after JsonMapper.
  *
- * ## Example
+ * ### Example
  *
  * ```typescript
  * @AfterDeserialize((data: Model) => { // After deserialize get the instance class

package/lib/types/decorators/beforeDeserialize.d.ts

@@ -5,7 +5,7 @@ export interface BeforeDeserializeCallback {
 /**
  * Call the function before JsonMapper.
  *
- * ## Example
+ * ### Example
  *
  * ```typescript
  * @BeforeDeserialize((data: Record<string, unknown>) => { // Before deserialize get the data

package/lib/types/decorators/jsonMapper.d.ts

@@ -1,7 +1,18 @@
 import { Type } from "@tsed/core";
 /**
- * Register a new JsonMapper Type
- * @param types
- * @constructor
+ * Register a class as the mapper responsible for the given primitive/class tokens.
+ * The decorator instantiates the mapper and stores it inside the JSON mapper types container.
+ *
+ * ### Example
+ *
+ * ```ts
+ * @JsonMapper(MyCustomType)
+ * export class MyCustomTypeMapper implements JsonMapperMethods {
+ *   serialize() {/* ... *\/}
+ *   deserialize() {/* ... *\/}
+ * }
+ * ```
+ *
+ * @param types One or more constructors/symbols handled by the mapper.
  */
 export declare function JsonMapper(...types: (any | Type)[]): ClassDecorator;

package/lib/types/decorators/onDeserialize.d.ts

@@ -5,7 +5,7 @@ export interface OnDeserializeCallback {
 /**
  * Call the function before property deserialization.
  *
- * ## Example
+ * ### Example
  *
  * ```typescript
  * class Model {

package/lib/types/decorators/onSerialize.d.ts

@@ -5,7 +5,7 @@ export interface OnSerializeCallback {
 /**
  * Call the function before property serialization.
  *
- * ## Example
+ * ### Example
  *
  * ```typescript
  * class Model {

package/lib/types/domain/JsonDeserializer.d.ts

@@ -1,6 +1,10 @@
 import { Type } from "@tsed/core";
 import { JsonDeserializerOptions } from "./JsonDeserializerOptions.js";
 import { CachedJsonMapper, JsonMapperCompiler } from "./JsonMapperCompiler.js";
+/**
+ * Deserializes raw JSON data into class instances based on schema metadata,
+ * handling collections, discriminators, hooks, and registered type mappers.
+ */
 export declare class JsonDeserializer extends JsonMapperCompiler<JsonDeserializerOptions> {
     /**
      * Cached classes by his id

package/lib/types/domain/JsonDeserializerOptions.d.ts

@@ -2,6 +2,10 @@ import { MetadataTypes, Type } from "@tsed/core";
 import { type GenericsMap, JsonEntityStore } from "@tsed/schema";
 import { JsonMapperMethods } from "../interfaces/JsonMapperMethods.js";
 import { JsonMapperGlobalOptions } from "./JsonMapperGlobalOptions.js";
+/**
+ * Options accepted by the `JsonDeserializer`. They describe the target type,
+ * collection strategy, additional mapper types, and hook configuration used while materializing data.
+ */
 export interface JsonDeserializerOptions<T = any, C = any> extends MetadataTypes<T, C>, JsonMapperGlobalOptions {
     /**
      * Types used to map complex types (Symbol, Array, Set, Map)

package/lib/types/domain/JsonMapperCompiler.d.ts

@@ -1,11 +1,26 @@
 import { Type } from "@tsed/core";
 import { JsonSchema } from "@tsed/schema";
+/**
+ * Signature exposed by compiled mappers. They accept an input value plus contextual options
+ * and return the serialized/deserialized result.
+ */
 export type JsonMapperCallback<Options> = (input: any, options?: Options) => any;
+/**
+ * Executable mapper plus its unique identifier stored in the compiler cache.
+ */
 export type CachedJsonMapper<Options> = {
     id: string;
     fn: JsonMapperCallback<Options>;
 };
+/**
+ * Cached mapper registry keyed by the groups fingerprint generated for a schema.
+ */
 export type CachedGroupsJsonMapper<Options> = Map<string, CachedJsonMapper<Options>>;
+/**
+ * Base compiler that turns schema metadata into executable (de)serialization functions.
+ * Subclasses supply `map`, `alterValue`, and `createMapper` implementations to specialize
+ * the pipeline for serialization or deserialization.
+ */
 export declare abstract class JsonMapperCompiler<Options extends Record<string, any> = any> {
     /**
      * Cached mappers metadata

package/lib/types/domain/JsonMapperGlobalOptions.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Shared configuration flags used by both serialization and deserialization flows.
+ */
 export interface JsonMapperGlobalOptions {
     /**
      * JsonMapper additional property policy. (see [JsonMapper](/docs/json-mapper.md))

package/lib/types/domain/JsonMapperSettings.d.ts

@@ -1,2 +1,5 @@
 import type { JsonMapperGlobalOptions } from "./JsonMapperGlobalOptions.js";
+/**
+ * Default runtime settings applied by the JSON mapper pipeline.
+ */
 export declare const JsonMapperSettings: JsonMapperGlobalOptions;

package/lib/types/domain/JsonMapperTypesContainer.d.ts

@@ -1,10 +1,10 @@
 import { Type } from "@tsed/core";
 import { JsonMapperMethods } from "../interfaces/JsonMapperMethods.js";
 /**
- * @ignore
+ * Register a mapper class for a specific primitive/complex type so it can be reused by the serializers.
  */
 export declare function registerJsonTypeMapper(type: Type<any> | Symbol | string, token: Type<JsonMapperMethods>): void;
 /**
- * @ignore
+ * Retrieve the registry of custom JSON mapper instances keyed by the types they support.
  */
 export declare function getJsonMapperTypes(): Map<Type<any> | Symbol | string, JsonMapperMethods>;

package/lib/types/domain/JsonSerializer.d.ts

@@ -1,6 +1,12 @@
 import { Type } from "@tsed/core";
 import { JsonMapperCompiler } from "./JsonMapperCompiler.js";
 import { JsonSerializerOptions } from "./JsonSerializerOptions.js";
+/**
+ * Serializes data structures according to the metadata captured by `@tsed/schema`.
+ *
+ * The serializer walks entity schemas, applies hooks, honors alias/group rules, and falls back to the
+ * registered type mappers (e.g., components in `src/components`).
+ */
 export declare class JsonSerializer extends JsonMapperCompiler<JsonSerializerOptions> {
     constructor();
     map(input: any, options?: JsonSerializerOptions): any;

package/lib/types/domain/JsonSerializerOptions.d.ts

@@ -1,6 +1,10 @@
 import { MetadataTypes, Type } from "@tsed/core";
 import { JsonMapperMethods } from "../interfaces/JsonMapperMethods.js";
 import { JsonMapperGlobalOptions } from "./JsonMapperGlobalOptions.js";
+/**
+ * Options accepted by the `JsonSerializer`. They describe the target type, alias strategy,
+ * additional type mappers, and group handling.
+ */
 export interface JsonSerializerOptions<T = any, C = any> extends MetadataTypes<T, C>, Pick<JsonMapperGlobalOptions, "strictGroups"> {
     /**
      * Types used to map complex types (Symbol, Number, String, etc...)

package/lib/types/domain/Writer.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Tiny utility used by the mapper compilers to build executable arrow functions as strings.
+ * It provides helpers for scoping, branching, and composing mapper fragments before `eval`.
+ */
 export declare class Writer {
     static object: {
         assign(...args: string[]): string;

package/lib/types/hooks/alterAfterDeserialize.d.ts

@@ -1,4 +1,7 @@
 import type { Hooks } from "@tsed/hooks";
+/**
+ * Trigger the `afterDeserialize` lifecycle in order to finalize instances after mapping.
+ */
 export declare function alterAfterDeserialize(data: any, schema: {
     $hooks: Hooks;
 }, options: any): any;

package/lib/types/hooks/alterBeforeDeserialize.d.ts

@@ -1,4 +1,8 @@
 import type { Hooks } from "@tsed/hooks";
+/**
+ * Trigger the `beforeDeserialize` hooks declared on the schema to massage raw payloads
+ * prior to property mapping.
+ */
 export declare function alterBeforeDeserialize(data: any, schema: {
     $hooks: Hooks;
 }, options: any): any;

package/lib/types/hooks/alterOnDeserialize.d.ts

@@ -1,2 +1,5 @@
 import { JsonHookContext, JsonSchema } from "@tsed/schema";
+/**
+ * Execute the `onDeserialize` hooks registered on a schema before writing the value onto the target.
+ */
 export declare function alterOnDeserialize(schema: JsonSchema, value: any, options: JsonHookContext): any;

package/lib/types/hooks/alterOnSerialize.d.ts

@@ -1,2 +1,6 @@
 import { JsonHookContext, JsonSchema } from "@tsed/schema";
+/**
+ * Execute the `onSerialize` hooks registered on a schema before emitting a value.
+ * Used internally by the serializer when a property exposes lifecycle hooks.
+ */
 export declare function alterOnSerialize(schema: JsonSchema, value: any, options: JsonHookContext): any;

package/lib/types/interfaces/JsonMapperMethods.d.ts

@@ -1,4 +1,7 @@
 import { Type } from "@tsed/core";
+/**
+ * Runtime context passed to mapper methods so they can inspect target types, collection wrappers, and format options.
+ */
 export interface JsonMapperCtx<T = any, C = any> {
     collectionType: Type<C> | undefined;
     type: Type<T> | T;
@@ -7,22 +10,22 @@ export interface JsonMapperCtx<T = any, C = any> {
         format?: string;
     };
 }
+/**
+ * Function used to delegate to the next mapper in the chain (e.g., nested serialization).
+ */
 export interface JsonMapperNext {
     (obj: any): any;
 }
+/**
+ * Contract implemented by every custom JSON mapper.
+ */
 export interface JsonMapperMethods {
     /**
-     *
-     * @param obj
-     * @param {JsonMapperNext} ctx
-     * @returns {any}
+     * Transform raw data into the target type or collection item.
      */
     deserialize<T = any, C = any>(obj: any, ctx: JsonMapperCtx<T, C>): any;
     /**
-     *
-     * @param obj
-     * @param ctx
-     * @returns {any}
+     * Transform a runtime value into its serialized representation.
      */
     serialize(obj: any, ctx: JsonMapperCtx<any>): any;
 }

package/lib/types/utils/deserialize.d.ts

@@ -2,4 +2,15 @@ import "../components/DateMapper.js";
 import "../components/PrimitiveMapper.js";
 import "../components/SymbolMapper.js";
 import { JsonDeserializerOptions } from "../domain/JsonDeserializerOptions.js";
+/**
+ * Deserialize arbitrary data into the provided model type using the shared `JsonDeserializer`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {deserialize} from "@tsed/json-mapper";
+ *
+ * const model = deserialize<UserModel>(payload, {type: UserModel, useAlias: true});
+ * ```
+ */
 export declare function deserialize<Model = any>(input: any, options?: JsonDeserializerOptions): Model;

package/lib/types/utils/getObjectProperties.d.ts

@@ -1 +1,4 @@
+/**
+ * Return enumerable entries of an object while skipping function values (methods/getters).
+ */
 export declare function getObjectProperties(obj: any): [string, any][];

package/lib/types/utils/serialize.d.ts

@@ -2,4 +2,16 @@ import "../components/DateMapper.js";
 import "../components/PrimitiveMapper.js";
 import "../components/SymbolMapper.js";
 import { JsonSerializerOptions } from "../domain/JsonSerializerOptions.js";
+/**
+ * Serialize any value using the shared `JsonSerializer` instance.
+ * Respects schema metadata, hooks, aliases, and registered custom mappers.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {serialize} from "@tsed/json-mapper";
+ *
+ * const payload = serialize(model, {type: UserModel, useAlias: true});
+ * ```
+ */
 export declare function serialize(input: any, options?: JsonSerializerOptions): any;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tsed/json-mapper",
   "description": "Json mapper module for Ts.ED Framework",
   "type": "module",
-  "version": "8.23.0",
+  "version": "8.24.0",
   "source": "./src/index.ts",
   "main": "./lib/esm/index.js",
   "module": "./lib/esm/index.js",
@@ -41,10 +41,10 @@
     "tslib": "2.7.0"
   },
   "devDependencies": {
-    "@tsed/barrels": "8.23.0",
-    "@tsed/core": "8.23.0",
-    "@tsed/schema": "8.23.0",
-    "@tsed/typescript": "8.23.0",
+    "@tsed/barrels": "8.24.0",
+    "@tsed/core": "8.24.0",
+    "@tsed/schema": "8.24.0",
+    "@tsed/typescript": "8.24.0",
     "eslint": "9.12.0",
     "typescript": "5.9.3",
     "vitest": "3.2.4"