json2typescript/lib/cjs/src/json2typescript/json-convert.d.ts

Provides TypeScript methods to map a JSON object to a JavaScript object on runtime

import { PropertyConvertingMode } from "./json-convert-enums";
/**
 * Offers a simple API for mapping JSON objects to TypeScript/JavaScript classes and vice versa.
 *
 * @see https://www.npmjs.com/package/json2typescript full documentation on NPM
 */
export declare class JsonConvert {
    /**
     * Determines how the JsonConvert class instance should operate.
     *
     * You may assign three different values:
     * - OperationMode.DISABLE: json2typescript will be disabled, no type checking or mapping is done
     * - OperationMode.ENABLE: json2typescript is enabled, but only errors are logged
     * - OperationMode.LOGGING: json2typescript is enabled and detailed information is logged
     */
    private _operationMode;
    /*
    * Determines how the JsonConvert class instance should operate.
    *
    * You may assign three different values:
    * - OperationMode.DISABLE: json2typescript will be disabled, no type checking or mapping is done
    * - OperationMode.ENABLE: json2typescript is enabled, but only errors are logged
    * - OperationMode.LOGGING: json2typescript is enabled and detailed information is logged
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    
    
    * Determines how the JsonConvert class instance should operate.
    *
    * You may assign three different values:
    * - OperationMode.DISABLE: json2typescript will be disabled, no type checking or mapping is done
    * - OperationMode.ENABLE: json2typescript is enabled, but only errors are logged
    * - OperationMode.LOGGING: json2typescript is enabled and detailed information is logged
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    */
    operationMode: number;
    /**
     * Determines which types are allowed to be null.
     * This setting may be overridden by property settings (see PropertyConvertingMode).
     *
     * You may assign three different values:
     * - ValueCheckingMode.ALLOW_NULL: all given values are allowed to be null
     * - ValueCheckingMode.ALLOW_OBJECT_NULL: objects are allowed to be null, primitive types are not allowed to be null
     * - ValueCheckingMode.DISALLOW_NULL: no null values are tolerated
     */
    private _valueCheckingMode;
    /*
    * Determines which types are allowed to be null.
    * This setting may be overridden by property settings (see PropertyConvertingMode).
    *
    * You may assign three different values:
    * - ValueCheckingMode.ALLOW_NULL: all given values are allowed to be null
    * - ValueCheckingMode.ALLOW_OBJECT_NULL: objects are allowed to be null, primitive types are not allowed to be null
    * - ValueCheckingMode.DISALLOW_NULL: no null values are tolerated
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    
    
    * Determines which types are allowed to be null.
    * This setting may be overridden by property settings (see PropertyConvertingMode).
    *
    * You may assign three different values:
    * - ValueCheckingMode.ALLOW_NULL: all given values are allowed to be null
    * - ValueCheckingMode.ALLOW_OBJECT_NULL: objects are allowed to be null, primitive types are not allowed to be null
    * - ValueCheckingMode.DISALLOW_NULL: no null values are tolerated
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    */
    valueCheckingMode: number;
    /**
     * Determines whether a missing or undefined property value should be considered as null or not.
     *
     * If true, a missing JSON value will be added and set as null before deserialization.
     * For serialization, undefined values will be set to null before serialization.
     *
     * The ValueCheckingMode and PropertyConvertingMode determine whether an error will be thrown during
     * serialization or deserialization.
     */
    private _mapUndefinedToNull;
    /*
    * Determines whether a missing or undefined property value should be considered as null or not.
    *
    * If true, a missing JSON value will be added and set as null before deserialization.
    * For serialization, undefined values will be set to null before serialization.
    *
    * ValueCheckingMode and PropertyConvertingMode determine whether an error will be thrown during
    * serialization or deserialization.
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    
    
    * Determines whether a missing or undefined property value should be considered as null or not.
    *
    * If true, a missing JSON value will be added and set as null before deserialization.
    * For serialization, undefined values will be set to null before serialization.
    *
    * The ValueCheckingMode and PropertyConvertingMode determine whether an error will be thrown during
    * serialization or deserialization.
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    */
    mapUndefinedToNull: boolean;
    /**
     * Determines whether primitive types should be checked.
     * If true, it will be allowed to assign primitive to other primitive types.
     */
    private _ignorePrimitiveChecks;
    /*
    * Determines whether primitive types should be checked.
    * If true, it will be allowed to assign primitive to other primitive types.
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    
    
    * Determines whether primitive types should be checked.
    * If true, it will be allowed to assign primitive to other primitive types.
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    */
    ignorePrimitiveChecks: boolean;
    /**
     * Determines the rule of how JSON properties shall be matched with class properties during deserialization.
     *
     * You may assign the following values:
     * - PropertyMatchingRule.CASE_STRICT: JSON properties need to match exactly the names in the decorators
     * - PropertyMatchingRule.CASE_INSENSITIVE: JSON properties need to match names in the decorators, but names they
     * are not case sensitive
     */
    private _propertyMatchingRule;
    /*
    * Determines the rule of how JSON properties shall be matched with class properties during deserialization.
    *
    * You may assign the following values:
    * - PropertyMatchingRule.CASE_STRICT: JSON properties need to match exactly the names in the decorators
    * - PropertyMatchingRule.CASE_INSENSITIVE: JSON properties need to match names in the decorators, but names they
    * are not case sensitive
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    
    
    * Determines the rule of how JSON properties shall be matched with class properties during deserialization.
    *
    * You may assign the following values:
    * - PropertyMatchingRule.CASE_STRICT: JSON properties need to match exactly the names in the decorators
    * - PropertyMatchingRule.CASE_INSENSITIVE: JSON properties need to match names in the decorators, but names they
    * are not case sensitive
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    */
    propertyMatchingRule: number;
    /**
     * Determines how nullable property types should be serialized and deserialized.
     * Nullable types are either missing (in JSON), undefined (in TypeScript) or null (both).
     *
     * If the propertyConvertingMode has a non-undefined value, it overrides the individual settings of every property.
     *
     * The values should be used as follows:
     * Determines how nullable property types should be serialized and deserialized.
     * Nullable types are either missing (in JSON), undefined (in TypeScript) or null (both).
     *
     * If the propertyConvertingMode has a non-undefined value, it overrides the individual settings of every property.
     *
     * The values should be used as follows:
     * - MAP_NULLABLE: the mapper is applied, type is checked
     * - IGNORE_NULLABLE: the mapper is not applied if the property is missing, undefined or null; the property is
     * not added to the result
     * - PASS_NULLABLE: the mapper is not applied if the property is missing, undefined or null; the property is
     * added with its value to the result
     */
    private _propertyConvertingMode;
    /*
    * Determines how nullable property types should be serialized and deserialized.
    * Nullable types are either missing (in JSON), undefined (in TypeScript) or null (both).
    *
    * If the propertyConvertingMode has a non-undefined value, it overrides the individual settings of every property.
    *
    * The values should be used as follows:
    * - MAP_NULLABLE: the mapper is applied, type is checked
    * - IGNORE_NULLABLE: the mapper is not applied if the property is missing, undefined or null; the property is
    * not added to the result
    * - PASS_NULLABLE: the mapper is not applied if the property is missing, undefined or null; the property is
    * added with its value to the result
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    
    
    * Determines how nullable property types should be serialized and deserialized.
    * Nullable types are either missing (in JSON), undefined (in TypeScript) or null (both).
    *
    * If the propertyConvertingMode has a non-undefined value, it overrides the individual settings of every property.
    *
    * The values should be used as follows:
    * - MAP_NULLABLE: the mapper is applied, type is checked
    * - IGNORE_NULLABLE: the mapper is not applied if the property is missing, undefined or null; the property is
    * not added to the result
    * - PASS_NULLABLE: the mapper is not applied if the property is missing, undefined or null; the property is
    * added with its value to the result
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    */
    propertyConvertingMode: PropertyConvertingMode | undefined;
    /*
    * @deprecated
    
    
    * @deprecated
    */
    ignoreRequiredCheck: boolean;
    /**
     * Determines if discriminators should be used.
     * If this option is set to true, all registered classes will be serialized with an additional discriminator
     * property (default: "$type"), which has the key of the class (given in the @JsonObject decorator) as value.
     * When deserializing an object containing the discriminator property, json2typescript will attempt to
     * automatically instantiate the correct type (by comparing the value of the discriminator property with the
     * registered classes).
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    private _useDiscriminator;
    /*
    * Determines if discriminators should be used.
    * If this option is set to true, all registered classes will be serialized with an additional discriminator
    * property (default: "$type"), which has the key of the class (given in the @JsonObject decorator) as value.
    * When deserializing an object containing the discriminator property, json2typescript will attempt to
    * automatically instantiate the correct type (by comparing the value of the discriminator property with the
    * registered classes).
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    
    
    * Determines if discriminators should be used.
    * If this option is set to true, all registered classes will be serialized with an additional discriminator
    * property (default: "$type"), which has the key of the class (given in the @JsonObject decorator) as value.
    * When deserializing an object containing the discriminator property, json2typescript will attempt to
    * automatically instantiate the correct type (by comparing the value of the discriminator property with the
    * registered classes).
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    */
    useDiscriminator: boolean;
    /**
     * Defines the name of the discriminator property.
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    private _discriminatorPropertyName;
    /*
    * Defines the name of the discriminator property.
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    
    
    * Defines the name of the discriminator property.
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    */
    discriminatorPropertyName: string;
    /**
     * Determines all classes which should use the lazy-loading or discriminator feature.
     * Only classes provided here can be used with lazy-loading or the discriminator property.
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    private _classes;
    /*
    * Determines all classes which should use the lazy-loading or discriminator feature.
    * Only classes provided here can be used with lazy-loading or the discriminator property.
    *
    * @see https://www.npmjs.com/package/json2typescript full documentation
    */
    private readonly classes: any;
    /**
     * Constructor.
     *
     * To learn more about the params, check the documentation of the equally named class properties.
     *
     * @param operationMode optional param (default: OperationMode.ENABLE)
     * @param valueCheckingMode optional param (default: ValueCheckingMode.ALLOW_OBJECT_NULL)
     * @param ignorePrimitiveChecks optional param (default: false)
     * @param propertyMatchingRule optional param (default: PropertyMatchingRule.CASE_STRICT)
     */
    constructor(operationMode?: number, valueCheckingMode?: number, ignorePrimitiveChecks?: boolean, propertyMatchingRule?: number);
    /**
     * Registers a list of classes to be used in the discriminator feature.
     * After registering these classes, they may be used for the discriminator feature.
     *
     * @param classReferences the class references
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    registerClasses(...classReferences: {
        new (): any;
    }[]): void;
    /**
     * Unregisters a list of classes from the discriminator feature.
     * After unregistering these classes, they cannot be used anymore for the discriminator feature.
     *
     * @param classReferences the class references
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    unregisterClasses(...classReferences: {
        new (): any;
    }[]): void;
    /**
     * Unregisters all classes from discriminator feature.
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    unregisterAllClasses(): void;
    /**
     * Tries to serialize a TypeScript array of objects to JSON using the mappings defined on
     * the specified class reference.
     *
     * If a class reference is provided, it will be used as the source of property mapping for
     * serialization, even if the object or one of its elements is an instance of a different
     * class with its own mappings.
     *
     * Also, only the properties from the class reference will be serialized – any additional
     * properties on the object(s) will be silently ignored.
     *
     * @param data object or array of objects
     * @param classReference the class reference which provides the property mappings to use
     *
     * @returns the JSON array
     *
     * @throws an Error in case of failure
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    serialize<T extends object, U extends object = {}>(data: T[], classReference?: {
        new (): U;
    }): any[];
    /**
     * Tries to serialize a TypeScript object to JSON using the mappings defined on the specified
     * class reference.
     *
     * If a class reference is provided, it will be used as the source of property mapping for
     * serialization, even if the object or one of its elements is an instance of a different
     * class with its own mappings.
     *
     * Also, only the properties from the class reference will be serialized – any additional
     * properties on the object(s) will be silently ignored.
     *
     * @param data object or array of objects
     * @param classReference the class reference which provides the property mappings to use
     *
     * @returns the JSON object
     *
     * @throws an Error in case of failure
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    serialize<T extends object, U extends object = {}>(data: T, classReference?: {
        new (): U;
    }): any;
    /**
     * Tries to serialize a TypeScript array of objects to JSON using the mappings defined on
     * the specified class reference.
     *
     * If a class reference is provided, it will be used as the source of property mapping for
     * serialization, even if the object or one of its elements is an instance of a different
     * class with its own mappings.
     *
     * Also, only the properties from the class reference will be serialized – any additional
     * properties on the object(s) will be silently ignored.
     *
     * This method is similar to `serialize`, but it will not throw an error if a property is missing
     * (or undefined). The resulting JSON object will not include the missing property.
     *
     * @param data object or array of objects
     * @param classReference the class reference which provides the property mappings to use
     *
     * @returns the JSON array
     *
     * @throws an Error in case of failure
     *
     * @see serialize
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    partialSerialize<T extends object, U extends object = {}>(data: T[], classReference?: {
        new (): U;
    }): any[];
    /**
     * Tries to serialize a TypeScript object to JSON using the mappings defined on the specified
     * class reference.
     *
     * If a class reference is provided, it will be used as the source of property mapping for
     * serialization, even if the object or one of its elements is an instance of a different
     * class with its own mappings.
     *
     * Also, only the properties from the class reference will be serialized – any additional
     * properties on the object(s) will be silently ignored.
     *
     * This method is similar to `serialize`, but it will not throw an error if a property is missing
     * (or undefined). The resulting JSON object will not include the missing property.
     *
     * @param data object or array of objects
     * @param classReference the class reference which provides the property mappings to use
     *
     * @returns the JSON object
     *
     * @throws an Error in case of failure
     *
     * @see serialize
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    partialSerialize<T extends object, U extends object = {}>(data: T, classReference?: {
        new (): U;
    }): any;
    /**
     * Tries to deserialize a given JSON array to an array of TypeScript instances.
     *
     * @param json the JSON array of objects
     * @param classReference the class reference
     *
     * @returns the deserialized data (array of TypeScript instances)
     *
     * @throws an Error in case of failure
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    deserialize<T extends object>(json: object[], classReference?: {
        new (): T;
    } | null): T[];
    /**
     * Tries to deserialize a given JSON object to a TypeScript instance.
     *
     * @param json the JSON object
     * @param classReference the class reference
     *
     * @returns the deserialized data (TypeScript instance)
     *
     * @throws an Error in case of failure
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    deserialize<T extends object>(json: object, classReference?: {
        new (): T;
    } | null): T;
    /**
     * Tries to deserialize a given JSON array to an array of TypeScript instances.
     *
     * This method is similar to `deserialize`, but it will not throw an error if a JSON object is missing properties.
     *
     * @param json the JSON array of objects
     * @param classReference the class reference
     *
     * @returns the deserialized data (array of TypeScript instances)
     *
     * @throws an Error in case of failure
     *
     * @see deserialize
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    partialDeserialize<T extends object>(json: object[], classReference?: {
        new (): T;
    } | null): T[];
    /**
     * Tries to deserialize a given JSON object to a TypeScript instance.
     *
     * This method is similar to `deserialize`, but it will not throw an error if a JSON object is missing properties.
     *
     * @param json the JSON object
     * @param classReference the class reference
     *
     * @returns the deserialized data (TypeScript instance)
     *
     * @throws an Error in case of failure
     *
     * @see deserialize
     * @see https://www.npmjs.com/package/json2typescript full documentation
     */
    partialDeserialize<T extends object>(json: object, classReference?: {
        new (): T;
    } | null): T;
    /**
     * Tries to serialize a TypeScript object to a JSON object using either the mappings on the
     * provided class reference, if present, or on the provided object. Note that if a class
     * reference is provided, it will be used as the source of property mapping for serialization,
     * even if the object is itself an instance of a different class with its own mappings.
     * Also, ONLY the properties from the class reference will be serialized - any additional
     * properties on the object will be silently ignored.
     *
     * @param data object containing the values to be mapped to a JSON object, must be an
     *             instance of a class with JSON mappings if no class reference is provided
     * @param classReference optional class reference which provides the property mappings to use
     * @param partial optional param (default: false) to indicate if missing properties should be ignored
     *
     * @returns the JSON object
     *
     * @throws an Error in case of failure
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     *
     * @deprecated will be made private, use the generic `serialize`
     */
    serializeObject<T extends object, U extends object = {}>(data: T, classReference?: {
        new (): U;
    }, partial?: boolean): any;
    /**
     * Tries to serialize a TypeScript array to a JSON array using either the mappings on the
     * provided class reference, if present, or on the provided object. Note that if a class
     * reference is provided, ALL objects in the array will be serialized using the mappings
     * from that class reference, even if they're actually instances of a different class.
     * Also, ONLY the properties from the class reference will be serialized - any additional
     * properties on the objects will be silently ignored.
     *
     * @param dataArray array of objects containing the values to be mapped to a JSON object, which
     *                  must be instances of classes with JSON mappings if no class reference is provided
     * @param classReference optional class reference which provides the property mappings to use
     * @param partial optional param (default: false) to indicate if missing properties should be ignored
     *
     * @returns the JSON array
     *
     * @throws an Error in case of failure
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     *
     * @deprecated will be made private, use the generic `serialize`
     */
    serializeArray<T extends object, U extends object = {}>(dataArray: T[], classReference?: {
        new (): U;
    }, partial?: boolean): any[];
    /**
     * Tries to deserialize a JSON object to a TypeScript object.
     *
     * @param jsonObject the JSON object
     * @param classReference the class reference
     * @param partial optional param (default: false) to indicate if missing properties should be ignored
     *
     * @returns the deserialized TypeScript instance
     *
     * @throws an Error in case of failure
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     *
     * @deprecated will be made private, use the generic `deserialize`
     */
    deserializeObject<T extends object>(jsonObject: object, classReference?: {
        new (): T;
    } | null, partial?: boolean): T;
    /**
     * Tries to deserialize a JSON array to a TypeScript array.
     *
     * @param jsonArray the JSON array
     * @param classReference the object class
     * @param partial optional param (default: false) to indicate if missing properties should be ignored
     *
     * @returns the deserialized array of TypeScript instances
     *
     * @throws an Error in case of failure
     *
     * @see https://www.npmjs.com/package/json2typescript full documentation
     *
     * @deprecated will be made private, use the generic `deserialize`
     */
    deserializeArray<T extends object>(jsonArray: object[], classReference?: {
        new (): T;
    } | null, partial?: boolean): T[];
    /**
     * Returns the correct class reference for the provided JSON object.
     * If the provided class reference is null, the class reference is retrieved from the class map using the discriminator property.
     *
     * @param jsonObject the JSON object
     * @param classReference the class reference
     * @throws throws an Error in case of failure
     */
    private getRealClassReference;
    /**
     * Tries to find the JSON mapping for a given class property from the given instance used for mapping,
     * and finally assign the value from the given dataObject
     *
     * @param dataObject the object containing the value to be assigned
     * @param instance the instance of the class used for mapping
     * @param classPropertyName the property name
     * @param json the JSON object
     * @param partial optional param (default: false) to indicate if missing properties should be ignored
     *
     * @throws throws an Error in case of failure
     */
    private serializeObject_loopProperty;
    /**
     * Tries to find the JSON mapping for a given class property and finally assign the value.
     *
     * @param instance the instance of the class
     * @param classPropertyName the property name
     * @param json the JSON object
     * @param partial optional param (default: false) to indicate if missing properties should be ignored
     *
     * @throws throws an Error in case of failure
     */
    private deserializeObject_loopProperty;
    /**
     * Gets the mapping options of a given class property.
     *
     * @param instance any class instance
     * @param {string} propertyName any property name
     *
     * @returns {MappingOptions|null}
     */
    private getClassPropertyMappingOptions;
    /**
     * Compares the type of a given value with an internal expected json type.
     * Either returns the resulting value or throws an exception.
     *
     * @param expectedType the expected type for the property
     * @param value the property value to verify
     * @param convertingMode the converting mode for this property
     * @param serialize optional param (default: false), if given, we are in serialization mode
     *
     * @returns returns the resulted mapped property
     *
     * @throws an error in case of failure
     */
    private convertProperty;
    /**
     * Gets the value of an object for a given value.
     * If the object does not have the specific key, an Error is thrown.
     *
     * @param data
     * @param key
     *
     * @returns returns the value
     *
     * @throws an Error in case of the key was not found in the object
     */
    private getObjectValue;
    /**
     * Returns a string representation of the expected json type.
     *
     * @param expectedJsonType the expected type given from the decorator
     *
     * @returns {string} the string representation
     */
    private getExpectedType;
    /**
     * Returns a string representation of the JSON value type.
     *
     * @param jsonValue the JSON value
     *
     * @returns {string} the string representation
     */
    private getJsonType;
    /**
     * Returns a string representation of the true TypeScript type.
     *
     * @param trueValue the true value
     *
     * @returns {string} the string representation
     */
    private getTrueType;
}